| blob | 7affed586ed83ff8ed407e812c44e1581939fcc6 |
5 <head>
9 <title>
10 Scintilla and SciTE
11 </title>
12 </head>
15 <tr>
16 <td>
18 </td>
19 <td>
21 Scintilla</font></a>
22 </td>
23 </tr>
24 </table>
25 <h2>
26 Scintilla Documentation
27 </h2>
28 <p>
30 </p>
31 <p>
33 </p>
34 <p>
36 </p>
37 <p>
38 <a href="http://www.scintilla.org/dmapp.zip">A simple sample using Scintilla from C++ on Windows</a>.
39 </p>
40 <p>
41 <a href="http://www.scintilla.org/SciTry.vb">A simple sample using Scintilla from Visual Basic</a>.
42 </p>
43 <p>
45 A detailed description of how to write a lexer, including a discussion of folding</a>.
46 </p>
47 <p>
49 are worth following if you want to contribute code to Scintilla but are not
50 compulsory.
51 </p>
52 <p>
53 For now, the best way to work out how to develop using Scintilla is to see how SciTE uses
54 it. SciTE exercises most of Scintilla's facilities.
55 </p>
56 <p>
57 The Windows version of Scintilla is a Windows Control. As such, its primary programming
58 interface is through Windows messages. Early versions of Scintilla emulated much of the
59 API defined by the standard Windows Edit and Richedit controls but those APIs are now
60 deprecated in favour of Scintilla's own, more consistent API.
61 In addition to messages performing the actions of a normal Edit control, Scintilla
62 allows control of syntax styling, markers, auto-completion and call tips.
63 </p>
64 The GTK+ version also uses messages in a similar way to the Windows version. This is different
65 to normal GTK+ practice but made it easier to implement rapidly.
66 <p>
67 The messages are (with wParam and lParam use)
68 </p>
69 <h3>
70 Text retrieval and modification.
71 </h3>
72 <pre>
73 SCI_GETTEXT(int length, char *text)
75 SCI_GETLINE(int line, char *text)
77 SCI_SETREADONLY(bool readOnly)
78 SCI_GETREADONLY
80 SCI_ADDTEXT(int length, char *s)
81 SCI_ADDSTYLEDTEXT(int length, cell *s)
82 SCI_INSERTTEXT(int pos, char *text)
83 SCI_CLEARALL
84 SCI_CLEARDOCUMENTSTYLE
85 SCI_GETCHARAT(int position)
86 SCI_GETSTYLEAT(int position)
88 SCI_SETSTYLEBITS(int bits)
89 SCI_GETSTYLEBITS
90 </pre>
91 <p>
92 Each character in a Scintilla document is followed by an associated byte of styling
93 information. The combination of a character byte and a style byte is called a cell. Style
95 indicators. This allows 32 fundamental styles which is enough for most languages and three
96 independent indicators so that, for example, syntax errors, deprecated names and bad
97 indentation could all be displayed at once. Indicators may be displayed as simple underlines,
98 squiggly underlines, a line of small 'T' shapes, a line of diagonal hatching or as strike-out.
99 Additional indicators such as blurred could be defined in the future.
100 The number of bits used for styles can be altered
101 with SCI_SETSTYLEBITS up to a maximum of 7 bits.
102 The remaining bits can be used for indicators.
103 </p>
104 <p>
105 Positions within the Scintilla document refer to a character or the gap before that
106 character. The caret exists between character positions and can be located from before the
107 first character to after the last character. There are places where the caret can not go
108 where two character bytes make up one character. This occurs when a DBCS character from a
109 language like Japanese is included in the document or when line ends are marked with the CP/M
110 standard of a carriage return followed by a line feed. The INVALID_POSITION constant (-1)
111 represents an invalid position within the document.
112 </p>
113 <p>
114 All lines of text in Scintilla are the same height, and this height is calculated from the
115 largest font in any current style. This restriction is for performance as if lines differed
116 in height then calculations involving positioning of text would require that text to be
117 styled first.
118 </p>
119 <p>
120 When wanting to completely restyle the document, for example after choosing a lexer,
121 the SCI_CLEARDOCUMENTSTYLE can be used to clear all styling information and
122 reset the folding state.
123 </p>
124 <pre>
125 SCI_SETTARGETSTART(int pos)
126 SCI_GETTARGETSTART
127 SCI_SETTARGETEND(int pos)
128 SCI_GETTARGETEND
129 SCI_REPLACETARGET(int length, char *text)
130 SCI_REPLACETARGETRE(int length, char *text)
131 SCI_SETSEARCHFLAGS(int flags)
132 SCI_GETSEARCHFLAGS
133 SCI_SEARCHINTARGET(int length, string text)
134 </pre>
135 <p>
136 Using SCI_REPLACESEL, modifications cause scrolling and other visible changes
137 which may take some time and cause unwanted display updates. If performing many
138 changes, such as a replace all command, the target can be used instead.
139 First set the range to be replaced. Then call SCI_REPLACETARGET or
140 SCI_REPLACETARGETRE which returns the length taken by the replacement string.
141 The difference between SCI_REPLACETARGET and SCI_REPLACETARGETRE
142 is that SCI_REPLACETARGETRE looks for \d patterns in the replacement text
144 most recent regular expression search.
145 </p>
146 <p>
147 Searching can be performed within the target range with SCI_SEARCHINTARGET
148 which uses a counted string to allow searching for null characters.
149 Returns length of range or -1 for failure in which case target is not moved.
150 The flags used by SCI_SEARCHINTARGET such as SCFIND_MATCHCASE,
151 SCFIND_WHOLEWORD, SCFIND_WORDSTART, and SCFIND_REGEXP can
152 be set with SCI_SETSEARCHFLAGS. The SCI_SEARCHINTARGET call
153 may be simpler for some clients to use than SCI_FINDTEXT as that requires
154 using a pointer to a structure.
155 </p>
156 <pre>
157 SCI_SETOVERTYPE
158 SCI_GETOVERTYPE
159 </pre>
160 <p>
161 SCI_GETOVERTYPE returns TRUE if overtyping is active otherwise
162 FALSE will be returned. Use SCI_GETOVERTYPE to set the overtype node.
163 </p>
164 <h3>
165 Standard commands
166 </h3>
167 <pre>
168 SCI_CUT
169 SCI_COPY
170 SCI_PASTE
171 SCI_CLEAR
172 SCI_CANPASTE
173 </pre>
174 <h3>
175 Error handling
176 </h3>
177 <pre>
178 SCI_SETSTATUS
179 SCI_GETSTATUS
180 </pre>
181 <p>
182 If an error occurs, Scintilla may set an internal error number
183 which can be retrieved with SCI_GETSTATUS.
184 Not currently used but will be in the future.
185 To clear the error status call SCI_SETSTATUS(0).
186 </p>
187 <h3>
188 Undo and Redo
189 </h3>
190 <pre>
191 SCI_UNDO
192 SCI_CANUNDO
193 SCI_EMPTYUNDOBUFFER
194 SCI_REDO
195 SCI_CANREDO
196 SCI_SETUNDOCOLLECTION(bool collectUndo)
197 SCI_GETUNDOCOLLECTION
198 SCI_BEGINUNDOACTION
199 SCI_ENDUNDOACTION
200 </pre>
201 <p>
202 Scintilla has multiple level undo and redo. It will continue to collect undoable actions
203 until memory runs out. Sequences of typing or deleting are compressed into single actions to
204 make it easier to undo and redo at a sensible level of detail. Sequences of actions can be
205 combined into actions that are undone as a unit. These sequences occur between
206 SCI_BEGINUNDOACTION and SCI_ENDUNDOACTION messages. These sequences can be nested and only
207 the top level sequences are undone as units.
208 </p>
209 <h3>
210 Selection and information
211 </h3>
212 <pre>
213 SCI_GETTEXTLENGTH
214 SCI_GETFIRSTVISIBLELINE
215 SCI_GETLINECOUNT
216 SCI_GETMODIFY
217 SCI_SETSEL(int start, int end)
219 SCI_LINEFROMPOSITION(int position)
220 SCI_POSITIONFROMLINE(int line)
221 SCI_GETLINEENDPOSITION(int line)
222 SCI_LINELENGTH(int line)
223 SCI_POSITIONFROMPOINT(int x, int y)
224 SCI_POSITIONFROMPOINTCLOSE(int x, int y)
227 SCI_HIDESELECTION(bool hide)
228 SCI_GETLENGTH
229 SCI_SETCURRENTPOS(int position)
230 SCI_GETCURRENTPOS
231 SCI_SETANCHOR(int position)
232 SCI_GETANCHOR
233 SCI_SETSELECTIONSTART(int position)
234 SCI_GETSELECTIONSTART
235 SCI_SETSELECTIONEND(int position)
236 SCI_GETSELECTIONEND
237 SCI_SELECTALL
238 SCI_GOTOLINE(int line)
239 SCI_GOTOPOS(int position)
240 SCI_GETCURLINE(int textlen, char *text)
241 SCI_LINESONSCREEN
242 SCI_SELECTIONISRECTANGLE
243 SCI_MOVECARETINSIDEVIEW
244 SCI_WORDENDPOSITION(int position, bool onlyWordCharacters)
245 SCI_WORDSTARTPOSITION(int position, bool onlyWordCharacters)
246 </pre>
247 <p>
248 Scintilla maintains a selection which stretches between two points, the anchor and the
249 current position.
250 </p>
251 <p>
252 It is not possible to change the modified status as whether the document is modified is
253 determined by whether the undo position is at the save point.
254 </p>
255 <p>
256 SCI_GETCURLINE retrieves the text of the line containing the caret and returns the position
257 within the line of the caret.
258 </p>
259 <p>
260 SCI_POSITIONFROMPOINT finds the closest character position to a point and
261 SCI_POSITIONFROMPOINTCLOSE is similar but returns -1 if the point is
262 outside the window or not close to any characters.
263 </p>
264 <p>
265 SCI_WORDENDPOSITION and SCI_WORDSTARTPOSITION can be used to find
266 the start and end of words using the same definition of words as used internally
267 within Scintilla.
268 </p>
269 <h3>
270 Scrolling and automatic scrolling
271 </h3>
272 <pre>
273 SCI_LINESCROLL(int column, int line)
274 SCI_SCROLLCARET
275 SCI_SETCARETPOLICY(int policy, int slop)
276 SCI_SETVISIBLEPOLICY(int policy, int slop)
277 SCI_SETHSCROLLBAR(bool visible)
278 SCI_GETHSCROLLBAR
279 SCI_GETXOFFSET
280 SCI_SETXOFFSET(int xoffset)
281 </pre>
282 <p>
283 SCI_SETCARETPOLICY can be set to a combination of the flags CARET_SLOP
284 and CARET_STRICT to change the automatic vertical positioning of the view
285 when ensuring a position is visible. If CARET_SLOP is on then the slop value
286 determines the number of line at top and bottom of the view where the caret should not
287 go. If CARET_SLOP is off then the caret is centred within the view. When
288 CARET_STRICT is set then caret policy is rechecked even if the caret is completely
289 visible. If CARET_XEVEN is set then both the left and right margins are treated
290 equally whereas if it is not set then displaying text to the left is preferred.
291 CARET_XJUMPS causes the display to move in jumps and then stay still
292 rather than in a series of smaller movements.
293 SCI_SETVISIBLEPOLICY is a similar function that
294 determines how the vertical positioning is determined when
295 SCI_ENSUREVISIBLEENFORCEPOLICY is
296 called. It takes VISIBLE_SLOP and VISIBLE_STRICT flags
297 for the policy parameter.
298 </p>
299 <p>
300 The xoffset is the horizontal scroll position in pixels.
301 </p>
302 <h3>
303 Searching
304 </h3>
305 <pre>
306 SCI_FINDTEXT(int flags, TextToFind *ttf)
307 </pre>
308 <p>
309 Scintilla can find where a string is present in the document.
310 There are several option flags including a simple regular expression search.
311 SCFIND_MATCHCASE indicates that a match only occurs with a
312 string that matches the case of the search string.
313 SCFIND_WHOLEWORD indicates that a match only occurs if the characters
314 before and after are not word characters. SCFIND_WORDSTART
315 indicates that a match only occurs if the character before is not a word character.
316 </p>
317 <p>
318 SCFIND_REGEXP indicates that the search string should be interpreted as a regular
319 expression. Special characters interpreted are '.' for any character, '\(' and '\)' to tag
320 parts of the match, '\1' .. '\9' to refer to tagged parts, '\<' to match the start of a word,
321 '\>' to match the end of a word,
322 '\' as a quote character, '[' and ']'
323 to indicate a set of characters, ^ within a set to complement the set, ^ outside a set
324 to match the start of line, $ to match the end of line, * to match 0 or more times,
325 + to match 1 or more times
326 </p>
327 <p>
328 See also SCI_SEARCHINTARGET.
329 </p>
330 <pre>
331 SCI_SEARCHANCHOR
332 SCI_SEARCHNEXT(int flags, char *text)
333 SCI_SEARCHPREV(int flags, char *text)
334 </pre>
335 <p>
336 Relocatable search support. This allows
337 multiple incremental interactive searches to be macro recorded
338 while still setting the selection to found text so the find/select
339 operation is self-contained.
340 </p>
341 <h3>
342 Visible white space
343 </h3>
344 <pre>
345 SCI_GETVIEWWS
346 SCI_SETVIEWWS(SCWS_INVISIBLE or SCWS_VISIBLEAFTERINDENT or
347 SCWS_VISIBLEALWAYS)
348 </pre>
349 <p>
350 White space can be made visible which may useful for languages in which whitespace is
351 significant, such as Python. Space characters appear as small centred dots and tab characters
352 as light arrows pointing to the right. With the SCWS_VISIBLEAFTERINDENT option,
353 white space used for indentation is invisible but after the first visible character, it is visible.
354 </p>
355 <h3>
356 Cursor
357 </h3>
358 <pre>
359 SCI_SETCURSOR
360 SCI_GETCURSOR
361 </pre>
362 <p>
363 The cursor is normally chosen in a context sensitive way so will be different over
364 the margin than when over the text. When performing a slow action, a wait cursor
365 can be shown by calling SCI_SETCURSOR(SC_CURSORWAIT) and restored
366 with SCI_SETCURSOR(SC_CURSORNORMAL).
367 </p>
368 <h3>
369 Mouse Capture
370 </h3>
371 <pre>
372 SCI_SETMOUSEDOWNCAPTURES(bool captures)
373 SCI_GETMOUSEDOWNCAPTURES
374 </pre>
375 <p>
376 When the mouse is pressed inside Scintilla, it is captured so future mouse movement
377 events are sent to Scintilla. This behaviour may be turned off with
378 SCI_SETMOUSEDOWNCAPTURES(false).
379 </p>
380 <h3>
381 Line endings
382 </h3>
383 <pre>
384 SCI_GETEOLMODE
385 SCI_SETEOLMODE(SC_EOL_CRLF or SC_EOL_CR or SC_EOL_LF)
386 SCI_GETVIEWEOL
387 SCI_SETVIEWEOL(bool visible)
388 SCI_CONVERTEOLS(SC_EOL_CRLF or SC_EOL_CR or SC_EOL_LF)
389 </pre>
390 <p>
391 Scintilla can interpret any of the three major line end conventions, Macintosh (\r), Unix
392 (\n) and CP/M / DOS / Windows (\r\n). When the user presses the Enter key, one of these line
393 end strings is inserted into the buffer. The default is \r\n, but this can be changed with
394 the SCI_SETEOLMODE message taking a an argument of SC_EOL_CRLF, SC_EOL_CR, or SC_EOL_LF. The
395 SCI_GETEOLMODE message retrieves the current state.
396 </p>
397 <p>
398 The characters that make up line ends can be made visible with the view EOL option. This
399 looks similar to (CR), (LF), or (CR)(LF).
400 </p>
401 <p>
402 All of the line ends in the document may be changed by calling SCI_CONVERTEOLS with the
403 desired line ending.
404 </p>
405 <h3>
406 Styling
407 </h3>
408 <pre>
409 SCI_GETENDSTYLED
410 SCI_STARTSTYLING(int position, int mask)
411 SCI_SETSTYLING(int length, int style)
412 SCI_SETSTYLINGEX(int length, stylesequence *s)
413 SCI_SETLINESTATE(int line, int value)
414 SCI_GETLINESTATE(int line)
415 SCI_GETMAXLINESTATE
416 </pre>
417 <p>
418 Scintilla keeps a record of the last character that is likely to be styled correctly. This
419 is moved forwards when characters after it are styled and moved backwards if changes are made
420 to the text of the document before it. Before drawing text, this position is checked to see
421 if any styling is needed and a notification message sent to the container if so. The
422 container can send SCI_GETENDSTYLED to work out where it needs to start styling.
423 Scintilla will always ask to style whole lines.
424 </p>
425 <p>
426 To perform the actual styling, SCI_STARTSTYLING is sent with the position to start at and a
427 mask indicating which bits of the style bytes can be set. The mask allows styling to occur
428 over several passes, with, for example, basic styling done on an initial pass to ensure that
429 the text of the code is seen quickly and correctly, and then a second slower pass, detecting
430 syntax errors and using indicators to show where these are. After SCI_STARTSTYLING, multiple
431 SCI_SETSTYLING messages are sent for each lexical entity to be styled.
432 </p>
433 <p>
434 As well as the 8 bits of lexical state stored for each character there is also an integer stored
435 for each line. This can be used for longer lived parse states such as what the current scripting
436 language is in an ASP page.
437 </p>
438 <p>
439 The last line that has any line state can be found with SCI_GETMAXLINESTATE.
440 </p>
441 <h3>
442 Style Definition
443 </h3>
444 <pre>
445 SCI_STYLECLEARALL
446 SCI_STYLERESETDEFAULT
447 SCI_STYLESETFORE(int stylenumber, int colour)
448 SCI_STYLESETBACK(int stylenumber, int colour)
449 SCI_STYLESETBOLD(int stylenumber, bool bold)
450 SCI_STYLESETITALIC(int stylenumber, bool italic)
451 SCI_STYLESETSIZE(int stylenumber, int sizeinpoints)
452 SCI_STYLESETFONT(int stylenumber, char *fontname)
453 SCI_STYLESETEOLFILLED(int stylenumber, bool eolfilled)
454 SCI_STYLESETUNDERLINE(int stylenumber, bool underline)
455 SCI_STYLESETCHARACTERSET(int stylenumber, int charset)
456 SCI_STYLESETVISIBLE(int stylenumber, bool visible)
457 SCI_STYLESETCASE(int stylenumber, SC_CASE_MIXED or SC_CASE_UPPER or SC_CASE_LOWER)
458 SCI_STYLESETCHANGEABLE(int stylenumber, bool changeable)
459 </pre>
460 <p>
461 While the style setting messages mentioned above, change the style
462 numbers associated with text, these messages define how those style
463 numbers are interpreted visually. The STYLE_DEFAULT style defines
464 the attributes that all styles will receive when SCI_STYLECLEARALL
465 is called. SCI_STYLERESETDEFAULT resets STYLE_DEFAULT to its state
466 when Scintilla was initialised.
467 </p>
468 <p>
469 The EOLFILLED style uses the background colour at the end of the line
470 to colour from the last character of the line to the right side of the window.
471 This is useful when a document contains embedded sections in another
472 language such as HTML pages with embedded JavaScript. By setting both
473 the EOLFILLED style and a consistent background colour to all JavaScript
474 styles then JavaScript sections will be easily distinguished from HTML.
475 </p>
476 <p>
477 SCI_STYLESETCHARACTERSET can set a style to use a different
478 character set than the default.
479 For example, SCI_STYLESETCHARACTERSET(SCE_C_STRING,
480 SC_CHARSET_RUSSIAN) would ensure that strings in Russian would
481 display correctly.
482 This feature currently only works fully on Windows.
483 </p>
484 <p>
485 The character sets supported on Windows are:
486 SC_CHARSET_ANSI, SC_CHARSET_ARABIC, SC_CHARSET_BALTIC,
487 SC_CHARSET_CHINESEBIG5, SC_CHARSET_DEFAULT,
488 SC_CHARSET_EASTEUROPE, SC_CHARSET_GB2312, SC_CHARSET_GREEK,
489 SC_CHARSET_HANGUL, SC_CHARSET_HEBREW, SC_CHARSET_JOHAB,
490 SC_CHARSET_MAC, SC_CHARSET_OEM, SC_CHARSET_SHIFTJIS,
491 SC_CHARSET_SYMBOL, SC_CHARSET_THAI, SC_CHARSET_TURKISH, and
492 SC_CHARSET_VIETNAMESE.
493 </p>
494 <p>
495 The character sets supported on GTK+ are SC_CHARSET_ANSI,
496 SC_CHARSET_EASTEUROPE, SC_CHARSET_GB2312,
497 SC_CHARSET_HANGUL, and SC_CHARSET_SHIFTJIS.
498 </p>
499 <p>
500 As well as the 32 fundamental lexer styles, there are also some
501 predefined numbered styles starting at 32, STYLE_DEFAULT,
502 STYLE_LINENUMBER, STYLE_BRACELIGHT, STYLE_BRACEBAD,
503 STYLE_CONTROLCHAR, and STYLE_INDENTGUIDE.
504 These can be defined with the SCI_STYLESET* messages.
505 To make it easier for client code to discover the range of styles
506 that are predefined, STYLE_LASTPREDEFINED is set to the style
507 number of the last predefined style.
508 </p>
509 <p>
510 SCI_STYLESETCASE can force text to be displayed in upper case
511 (SC_CASE_UPPER) or lower case (SC_CASE_LOWER).
512 </p>
513 <p>
514 SCI_STYLESETCHANGEABLE is an experimental and incompletely
515 implemented style attribute.
516 The default setting is changeable but when turned off it makes text
517 read-only.
518 Currently only stops caret from being within not-changeable text
519 and does not yet stop deleting a range that contains not-changeable
520 text.
521 </p>
522 <h3>
523 Caret and Selection styles
524 </h3>
525 <pre>
526 SCI_SETSELFORE(bool useSelectionForeColour, int colour)
527 SCI_SETSELBACK(bool useSelectionBackColour, int colour)
528 SCI_SETCARETFORE(int colour)
529 SCI_GETCARETFORE
530 SCI_SETCARETLINEVISIBLE(bool show)
531 SCI_GETCARETLINEVISIBLE
532 SCI_SETCARETLINEBACK(int colour)
533 SCI_GETCARETLINEBACK
534 SCI_SETCARETPERIOD(int milliseconds)
535 SCI_GETCARETPERIOD
536 SCI_SETCARETWIDTH(int pixels)
537 SCI_GETCARETWIDTH
538 SCI_SETCONTROLCHARSYMBOL(int symbol)
539 SCI_GETCONTROLCHARSYMBOL
540 </pre>
541 <p>
542 The selection is shown by changing the foreground and / or
543 background colours.
544 If one of these is not set then that attribute is not changed for
545 the selection. The default is to show the selection by changing the
546 background to light grey and leaving the foreground the same as
547 when it was not selected.
548 </p>
549 <p>
550 The colour of the caret can be set with SCI_SETCARETFORE.
551 The background colour of the line containing the caret can be
552 changed to override the styles on that line with
553 SCI_GETCARETLINEVISIBLE and the colour used set with
554 SCI_SETCARETLINEBACK.
555 The caret line background colour is overridden by any background
556 colour used to display markers.
557 The rate at which the caret blinks can be set with
558 SCI_SETCARETPERIOD which determines the time in milliseconds that
559 the caret is visible or invisible before changing state.
560 Setting the period to 0 stops the caret blinking.
561 The width of the caret can be set with SCI_SETCARETWIDTH to a value
563 </p>
564 <p>
565 SCI_SETCONTROLCHARSYMBOL specifies a character to use to indicate
566 control characters rather than having them displayed as mnemonics.
567 </p>
568 <h3>
569 Margins
570 </h3>
571 <pre>
572 SCI_SETMARGINLEFT(int width)
573 SCI_GETMARGINLEFT
574 SCI_SETMARGINRIGHT(int width)
575 SCI_GETMARGINRIGHT
576 </pre>
577 <p>
578 Gets or sets the width of the blank margin on both sides of the
579 text. This defaults to one pixel on each side.
580 </p>
581 <pre>
582 SCI_SETMARGINTYPEN(int margin, SC_MARGIN_SYMBOL | SC_MARGIN_NUMBER)
583 SCI_GETMARGINTYPEN(int margin)
584 SCI_SETMARGINWIDTHN(int margin, int pixelwidth)
585 SCI_GETMARGINWIDTHN(int margin)
586 SCI_SETMARGINMASKN(int margin, int mask)
587 SCI_GETMARGINMASKN(int margin)
588 SCI_SETMARGINSENSITIVEN(int margin, bool sensitive)
589 SCI_GETMARGINSENSITIVEN(int margin)
590 </pre>
591 <p>
592 There may be up to three margins to the left of the text display.
593 Each margin may contain marker symbols and some may be set to
594 display line numbers (with SCI_SETMARGINTYPEN). The markers
595 displayed in each margin are set withSCI_SETMARGINMASKN. Any
596 markers not associated with a visible margin will be displayed as
597 changes in background colour in the text.
598 A width in pixels can be set for each margin. Margins with a zero
599 width are ignored completely. Each margin may be made sensitive to
600 mouse clicks. A click in a sensitive margin will result in a
601 SCN_MARGINCLICK notification being sent to the container. Margins
602 that are not sensitive act as selection margins which make it
603 easy to select ranges of lines.
604 </p>
605 <h3>
606 Other settings
607 </h3>
608 <pre>
609 SCI_SETUSEPALETTE(bool allowPaletteUse)
610 SCI_GETUSEPALETTE
611 </pre>
612 <p>
614 the graphics environment mediates between the colour needs of
615 applications through the use of palettes. On GTK+, Scintilla always
616 uses a palette. On Windows, there are some problems with visual
617 flashing when switching between applications with palettes and it
618 is also necessary for the application containing the Scintilla
619 control to forward some messages to Scintilla for its palette code
620 to work.
621 </p>
622 <p>
623 Because of these issues, the application must tell Scintilla to use
624 a palette. If Scintilla is not using a palette, then it will only
625 be able to display in those colours already available, which are
626 often the 20 Windows system colours.
627 </p>
628 <p>
629 To see an example of how to enable palette support in Scintilla,
630 search the text of SciTE for WM_PALETTECHANGED, WM_QUERYNEWPALETTE
631 and SCI_SETUSEPALETTE.
632 </p>
633 <pre>
634 SCI_SETBUFFEREDDRAW(bool isbuffered)
635 SCI_GETBUFFEREDDRAW
636 </pre>
637 <p>
638 Turns on or off buffered drawing. Buffered drawing draws each line
639 into a bitmap rather than directly to the screen and then copies
640 the bitmap to the screen. This avoids flickering although it does
641 take longer. The default is for drawing to be buffered.
642 </p>
643 <pre>
644 SCI_SETTABWIDTH(int widthinchars)
645 SCI_GETTABWIDTH
646 SCI_SETINDENT(int widthinchars)
647 SCI_GETINDENT
648 SCI_SETUSETABS(bool usetabs)
649 SCI_GETUSETABS
650 SCI_SETTABINDENTS(bool tabIndents)
651 SCI_GETTABINDENTS
652 SCI_SETBACKSPACEUNINDENTS(bool bsUnIndents)
653 SCI_GETBACKSPACEUNINDENTS
654 </pre>
655 <p>
656 SCI_SETTABWIDTH sets the size of a tab as a multiple of the size
657 of a space character in the style of the first style definition.
658 SCI_SETINDENT sets the size of indentation in terms of characters.
659 SCI_SETUSETABS determines whether indentation should be created out
660 of a mixture of tabs and space or be based purely on spaces.
661 </p>
662 <p>
663 Inside indentation whitespace the tab and backspace keys can be
664 made to indent and unindent rather than insert a tab character or
665 delete a character with the SCI_SETTABINDENTS and
666 SCI_GETBACKSPACEUNINDENTS functions.
667 </p>
668 <pre>
669 SCI_SETLINEINDENTATION(int line, int indentation)
670 SCI_GETLINEINDENTATION(int line)
671 SCI_GETLINEINDENTPOSITION(int line)
672 SCI_GETCOLUMN(int position)
673 </pre>
674 <p>
675 The amount of indentation on a line can be discovered and set with
676 SCI_GETLINEINDENTATION and SCI_SETLINEINDENTATION. The indentation
677 is measured in character columns which correspond to the width of
678 space characters.
679 SCI_GETLINEINDENTPOSITION returns the position at the end of
680 indentation of a line.
681 SCI_GETCOLUMN returns the column number of a position within the
682 document taking the width of tabs into account.
683 </p>
684 <pre>
685 SCI_SETCODEPAGE(int codepage)
686 SCI_GETCODEPAGE
687 </pre>
688 <p>
689 Scintilla has some very simple Japanese DBCS (and probably Chinese
690 and Korean) support. Use this message with argument set to the
691 code page number to set Scintilla to use code page information to
692 ensure double byte characters are treated as one character rather
693 than two. This also stops the caret from moving between the two
694 bytes in a double byte character. Call with argument set to zero
695 to disable DBCS support.
696 </p>
697 <p>
698 On Windows, code page SC_CP_UTF8 (65001) sets Scintilla into
699 Unicode mode with the document treated as a sequence of characters
701 drawn by the OS and can thus display Hebrew, Arabic, Cyrillic, and
702 Han characters. Languages which can use two characters stacked
703 vertically in one horizontal space such as Thai will mostly work
704 but there are som eissues where the characters are drawn
705 separately leading to visual glitches. Bidirectional text is not
706 supported.
707 </p>
708 <pre>
710 </pre>
711 <p>
712 Scintilla has several functions that operate on words which are
713 defined to be contiguous sequences of characters from a particular
714 set of characters. This message defines which characters are
715 members of that set. If chars is null then the default set,
716 alphanumeric and '_', is used.
717 </p>
718 <pre>
719 SCI_GRABFOCUS
720 SCI_SETFOCUS(bool focus)
721 SCI_GETFOCUS
722 </pre>
723 <p>
724 On GTK+, focus handling is more complicated than on Windows,
725 so Scintilla can be told with this message to grab the focus.
726 </p>
727 <p>
728 The internal focus flag can be set with SCI_SETFOCUS.
729 This is used by clients which have complex focus requirements such
730 as having their own window which gets the real focus but with the
731 need to indicate that Scintilla has the logical focus.
732 </p>
733 <h3>
734 Brace highlighting
735 </h3>
736 <pre>
737 SCI_BRACEHIGHLIGHT(int pos1, int pos2)
738 SCI_BRACEBADLIGHT(int pos1)
739 SCI_BRACEMATCH(int position, int maxReStyle)
740 </pre>
741 <p>
742 Up to two characters can be highlighted in a 'brace highlighting
743 style' which is defined as style number 34. If there is no matching
744 brace then the 'brace badlighting style', style number 35, can be
745 used to show the brace that is unmatched. Using a position of
746 INVALID_POSITION removes the highlight.
747 </p>
748 <p>
749 The SCI_BRACEMATCH message finds a corresponding matching brace
750 given the position of one brace. The brace characters handled are
752 A match only occurs if the style of the matching brace is the same
753 as the starting brace or the matching brace is beyond the end of
754 styling. Nested braces are handled correctly. The maxReStyle
755 parameter must currently be 0.
756 </p>
757 <h3>
758 Indentation Guides
759 </h3>
760 <pre>
761 SCI_SETINDENTATIONGUIDES(bool view)
762 SCI_GETINDENTATIONGUIDES
763 SCI_SETHIGHLIGHTGUIDE(int column)
764 SCI_GETHIGHLIGHTGUIDE
765 </pre>
766 <p>
767 Indentation guides are dotted vertical lines that appear within
768 indentation whitespace every indent size columns. They make it
769 easy to see which constructs line up especially when they extend
770 over multiple pages. Style 37 is used to specify the foreground and
771 background colour of the indentation guides.
772 </p>
773 <p>
774 When brace highlighting occurs, the indentation guide corresponding
775 to the braces may be highlighted with the brace highlighting style,
776 34.
777 </p>
778 <h3>
779 Markers
780 </h3>
781 <pre>
782 SCI_MARKERDEFINE(int markernumber, int markersymbols)
783 SCI_MARKERSETFORE(int markernumber, int colour)
784 SCI_MARKERSETBACK(int markernumber, int colour)
785 SCI_MARKERADD(int line, int markernumber)
786 SCI_MARKERDELETE(int line, int markernumber)
787 SCI_MARKERDELETEALL(int markernumber)
788 SCI_MARKERGET(int line)
789 SCI_MARKERNEXT(int lineStart, int markermask)
790 SCI_MARKERPREVIOUS(int lineStart, int markermask)
791 SCI_MARKERLINEFROMHANDLE(int handle)
792 SCI_MARKERDELETEHANDLE(int handle)
793 </pre>
794 <p>
795 Markers appear in the selection margin to the left of the text.
796 They are small geometric symbols often used in debuggers to
797 indicate breakpoints and the current line. If the selection margin
798 is set to zero width then the background colour of the whole line
799 is changed instead. There may be up to 32 marker symbols defined
800 and each line has a set of these markers associated with it. The
801 markers are drawn in the order of their numbers. Markers try to
802 move with their text by tracking where the start of their line
803 moves. When a line is deleted, its markers are combined, by an or
804 operation, with the markers of the previous line. The
805 SCI_MARKERDELETEALL removes markers of the given number from all
806 lines, and treats a parameter of -1 as meaning delete all markers
807 from all lines.<br />
808 SCI_MARKERADD returns a marker handle number which may be used to
809 find out where a marker has moved to with the
810 SCI_MARKERLINEFROMHANDLE message. SCI_MARKERDELETEHANDLE can be
811 used to delete a marker based upon its handle.
812 </p>
813 <p>
814 SCI_MARKERGET retrieves the set of markers associated with a line.
815 SCI_MARKERNEXT and SCI_MARKERPREVIOUS can be used to efficiently
816 search for lines that contain markers. They return the next /
817 previous line with a set of markers that includes some of the bits
818 set in the markermask parameter.<br />
820 each marker of the desired / retrieved set.
821 </p>
822 <p>
823 The marker symbols currently available are SC_MARK_CIRCLE,
824 SC_MARK_ROUNDRECT, SC_MARK_ARROW, SC_MARK_SMALLRECT,
825 SC_MARK_SHORTARROW, SC_MARK_EMPTY, SC_MARK_ARROWDOWN,
826 SC_MARK_MINUS, SC_MARK_PLUS.
827 The SC_MARK_BACKGROUND marker changes the background colour
828 of the line only.
829 The SC_MARK_EMPTY symbol is invisible,
830 allowing client code to track the movement of lines.
831 Characters can be used as markers by adding
832 the ASCII value of the character to SC_MARK_CHARACTER.
833 </p>
834 <p>
835 There are also marker symbols available for the folding margin in a
836 flattened tree style:
837 SC_MARK_BOXMINUS,
838 SC_MARK_BOXMINUSCONNECTED,
839 SC_MARK_BOXPLUS,
840 SC_MARK_BOXPLUSCONNECTED,
841 SC_MARK_CIRCLEMINUS,
842 SC_MARK_CIRCLEMINUSCONNECTED,
843 SC_MARK_CIRCLEPLUS,
844 SC_MARK_CIRCLEPLUSCONNECTED,
845 SC_MARK_LCORNER,
846 SC_MARK_LCORNERCURVE,
847 SC_MARK_TCORNER,
848 SC_MARK_TCORNERCURVE, and
849 SC_MARK_VLINE.
850 </p>
851 <p>
852 The marker numbers SC_MARKNUM_FOLDER and SC_MARKNUM_FOLDEROPEN are
853 used for showing that a fold is present and open or closed. Any
854 symbols may be assigned for this purpose although the
855 (SC_MARK_PLUS, SC_MARK_MINUS) pair or the (SC_MARK_ARROW,
856 SC_MARK_ARROWDOWN) pair are good choices.
857 As well as these two, more assignments are needed for the
858 flattened tree style:
859 SC_MARKNUM_FOLDEREND,
860 SC_MARKNUM_FOLDERMIDTAIL,
861 SC_MARKNUM_FOLDEROPENMID,
862 SC_MARKNUM_FOLDERSUB, and
863 SC_MARKNUM_FOLDERTAIL.
864 The bits used for folding is specified by SC_MASK_FOLDERS which is
865 commonly used as an argument to SCI_SETMARGINMASKN when defining a
866 margin to be used for folding.
867 </p>
868 <h3>
869 Indicators
870 </h3>
871 <pre>
872 SCI_INDICSETSTYLE(int indicatornumber, int indicatorstyle)
873 SCI_INDICGETSTYLE(int indicatornumber)
874 SCI_INDICSETFORE(int indicatornumber, int colour)
875 SCI_INDICGETFORE(int indicatornumber)
876 </pre>
877 <p>
878 These messages allow setting the visual appearance of the three
880 </p>
881 <p>
882 The indicator styles currently available are INDIC_PLAIN,
883 INDIC_SQUIGGLE, INDIC_TT, INDIC_DIAGONAL, and INDIC_STRIKE.
884 </p>
885 <p>
886 The indicators are set using SCI_STARTSTYLING with a INDICS_MASK
887 mask and SCI_SETSTYLING with the values INDIC0_MASK, INDIC1_MASK
888 and INDIC2_MASK.
889 </p>
890 <h3>
891 Autocompletion
892 </h3>
893 <pre>
894 SCI_AUTOCSHOW(int lenEntered,char *list)
895 SCI_AUTOCCANCEL
896 SCI_AUTOCACTIVE
897 SCI_AUTOCPOSSTART
898 SCI_AUTOCCOMPLETE
900 SCI_AUTOCSETSEPARATOR(char separator)
901 SCI_AUTOCGETSEPARATOR
903 SCI_AUTOCSETCANCELATSTART(bool cancel)
904 SCI_AUTOCGETCANCELATSTART
906 SCI_AUTOCSETCHOOSESINGLE(bool chooseSingle)
907 SCI_AUTOCGETCHOOSESINGLE
908 SCI_AUTOCSETIGNORECASE(bool ignoreCase)
909 SCI_AUTOCGETIGNORECASE
910 SCI_AUTOCSETAUTOHIDE(bool autoHide)
911 SCI_AUTOCGETAUTOHIDE
912 SCI_AUTOCSETDROPRESTOFWORD(bool dropRestOfWord)
913 SCI_AUTOCGETDROPRESTOFWORD
914 </pre>
915 <p>
916 Auto completion displays a list box based upon the users typing
917 showing likely identifiers.
918 The user chooses the currently selected item by pressing the tab character
919 or another character that is a member of the fillup character set defined
920 with SCI_AUTOCSETFILLUPS.
921 </p>
922 <p>
923 The SCI_AUTOCSHOW message causes this list to be displayed, with
924 its argument being a list of words separated by separator
925 characters. The initial separator character is a space but this can
926 be set or got with SCI_AUTOCSETSEPARATOR and
927 SCI_AUTOCGETSEPARATOR.
928 SCI_AUTOCPOSSTART returns the value of the current position when
929 SCI_AUTOCSHOW started display of the list.
930 An entry can be selected SCI_AUTOCSELECT.
931 The list of words should be in sorted order.
932 </p>
933 <p>
934 The current selection can be triggered with the SCI_AUTOCCOMPLETE
935 message. This has the same effect as the tab key. When in
936 autocompletion mode, the list should disappear when the user
937 types a character that can not be part of the autocompletion,
938 such as '.', '(' or '[' when typing an identifier. A set of
939 characters which will cancel autocompletion can be specified
940 with the SCI_AUTOCSTOPS.
941 </p>
942 <p>
943 If set to ignore case mode with SCI_AUTOCSETIGNORECASE,
944 then strings are matched after being converted to upper case.
945 One result of this is that the list should be sorted with the punctuation
946 characters '[', '\', ']', '^', '_', and '`' sorted after letters.
947 </p>
948 <p>
949 The default behaviour is for the list to be cancelled if the caret
950 moves before the location it was at when the list was displayed.
951 By calling SCI_AUTOCSETCANCELATSTART with a false argument, the
952 list is not cancelled until the caret moves before the first
953 character of the word being completed.
954 </p>
955 <p>
956 The list will also be cancelled if there are no viable matches.
957 To avoid this behaviour call SCI_AUTOCSETAUTOHIDE with a false
958 argument.
959 </p>
960 <p>
961 When an item is selected, any word characters following the caret are first
962 erased if SCI_AUTOCSETDROPRESTOFWORD is used to set this mode.
963 </p>
964 <h3>
965 User lists
966 </h3>
967 <pre>
968 SCI_USERLISTSHOW(int listType,char *list)
969 </pre>
970 <p>
971 User lists are similar to auto completion but do not insert text
972 when an item is selected, instead notifying the container with a
973 SCN_USERLISTSELECTION.
974 The listType parameter is returned to the container and can be used
975 to differentiate between different types of list such as between a
976 list of buffers and a list of keywords.
977 </p>
978 <h3>
979 Calltips
980 </h3>
981 <pre>
982 SCI_CALLTIPSHOW(int posStart, char *definition)
983 SCI_CALLTIPCANCEL
984 SCI_CALLTIPACTIVE
985 SCI_CALLTIPPOSSTART
986 SCI_CALLTIPSETHLT(int highlightstart, int highlightend)
987 SCI_CALLTIPSETBACK(int colour)
988 </pre>
989 <p>
990 Call tips are small windows displaying the arguments to a function
991 and are displayed after the user has typed the name of the
992 function. As the user types values for each argument, the
993 name of the argument currently being entered is highlighted.
994 </p>
995 <p>
996 SCI_CALLTIPSHOW starts the process by displaying the calltip
997 window, with the definition argument containing the text to
998 display. SCI_CALLTIPPOSSTART returns the value of the current
999 position when SCI_CALLTIPSHOW started display of the list.
1000 SCI_CALLTIPSETHLT sets the region of the calltip text displayed in
1001 a highlighted style. The background colour of calltips can
1002 be set with SCI_CALLTIPSETBACK with the default being white.
1003 </p>
1004 <h3>
1005 Keyboard Commands
1006 </h3>
1007 <pre>
1008 SCI_LINEDOWN
1009 SCI_LINEDOWNEXTEND
1010 SCI_LINEUP
1011 SCI_LINEUPEXTEND
1012 SCI_CHARLEFT
1013 SCI_CHARLEFTEXTEND
1014 SCI_CHARRIGHT
1015 SCI_CHARRIGHTEXTEND
1016 SCI_WORDLEFT
1017 SCI_WORDLEFTEXTEND
1018 SCI_WORDRIGHT
1019 SCI_WORDRIGHTEXTEND
1020 SCI_HOME
1021 SCI_HOMEEXTEND
1022 SCI_LINEEND
1023 SCI_LINEENDEXTEND
1024 SCI_DOCUMENTSTART
1025 SCI_DOCUMENTSTARTEXTEND
1026 SCI_DOCUMENTEND
1027 SCI_DOCUMENTENDEXTEND
1028 SCI_PAGEUP
1029 SCI_PAGEUPEXTEND
1030 SCI_PAGEDOWN
1031 SCI_PAGEDOWNEXTEND
1032 SCI_EDITTOGGLEOVERTYPE
1033 SCI_CANCEL
1034 SCI_DELETEBACK
1035 SCI_DELETEBACKNOTLINE
1036 SCI_TAB
1037 SCI_BACKTAB
1038 SCI_NEWLINE
1039 SCI_FORMFEED
1040 SCI_VCHOME
1041 SCI_VCHOMEEXTEND
1042 SCI_DELWORDLEFT
1043 SCI_DELWORDRIGHT
1044 SCI_DELLINELEFT
1045 SCI_DELLINERIGHT
1046 SCI_LINESCROLLDOWN
1047 SCI_LINESCROLLUP
1048 SCI_LINECUT
1049 SCI_LINEDELETE
1050 SCI_LINETRANSPOSE
1051 SCI_LOWERCASE
1052 SCI_UPPERCASE
1053 SCI_WORDPARTLEFT
1054 SCI_WORDPARTLEFTEXTEND
1055 SCI_WORDPARTRIGHT
1056 SCI_WORDPARTRIGHTEXTEND
1057 </pre>
1058 <p>
1059 To allow the container application to perform any of the actions
1060 available to the user with keyboard, all the keyboard actions are
1061 messages. They do not take any parameters.
1062 </p>
1063 <p>
1064 These commands are also used when redefining the key bindings with
1065 the SCI_ASSIGNCMDKEY message.
1066 </p>
1067 <p>
1068 The SCI_WORDPART* commands are used to move between word segments
1069 marked by capitalisation (aCamelCaseIdentifier) or underscores
1070 (an_under_bar_ident).
1071 </p>
1072 <h3>
1073 Key Bindings
1074 </h3>
1075 <pre>
1076 SCI_ASSIGNCMDKEY((short key,short modifiers), int message)
1077 SCI_CLEARCMDKEY((short key,short modifiers))
1078 SCI_CLEARALLCMDKEYS
1079 SCI_NULL
1080 </pre>
1081 <p>
1082 There is a default binding of keys to commands in Scintilla which
1083 can be overridden with these messages.
1084 To fit the parameters into a message, the first argument contains
1085 the key code in the low word and the key modifiers (possibly shift
1086 and control) in the high word. The key code is a visible or control
1087 character or a key from the SCK_* enumeration,
1088 which contains SCK_ADD, SCK_BACK, SCK_DELETE, SCK_DIVIDE,
1089 SCK_DOWN, SCK_END, SCK_ESCAPE, SCK_HOME, SCK_INSERT,
1090 SCK_LEFT, SCK_NEXT, SCK_PRIOR, SCK_RETURN, SCK_RIGHT,
1091 SCK_SUBTRACT, SCK_TAB, and SCK_UP.
1092 The modifiers are a combination of zero or more of
1093 SCMOD_ALT, SCMOD_CTRL, and SCMOD_SHIFT.
1094 SCI_NULL does nothing and is the value assigned to keys that
1095 perform no action.
1096 </p>
1097 <h3>
1098 Popup edit menu
1099 </h3>
1100 <pre>
1101 SCI_USEPOPUP
1102 </pre>
1103 <p>
1104 Clicking the wrong button on the mouse pops up a short default
1105 editing menu.
1106 This may be turned off with SCI_USEPOPUP(0).
1107 </p>
1108 <h3>
1109 Macro Recording
1110 </h3>
1111 <pre>
1112 SCI_STARTRECORD
1113 SCI_STOPRECORD
1114 </pre>
1115 <p>
1116 Starts and stops macro recording mode.
1117 </p>
1118 <h3>
1119 Printing
1120 </h3>
1121 <pre>
1122 SCI_FORMATRANGE
1123 SCI_SETPRINTMAGNIFICATION(int magnification)
1124 SCI_GETPRINTMAGNIFICATION
1125 SCI_SETPRINTCOLOURMODE(int mode)
1126 SCI_GETPRINTCOLOURMODE
1127 </pre>
1128 <p>
1129 On Windows SCI_FORMATRANGE can be used to draw the text onto a
1130 display context which can include a printer display context.
1131 </p>
1132 <p>
1133 To print at a different size than drawing on screen use
1134 SCI_SETPRINTMAGNIFICATION with a value which is the number of
1136 </p>
1137 <p>
1138 If a black background is used on the screen then it is best to
1139 invert the light value of all colours with
1140 SCI_SETPRINTCOLOURMODE(SC_PRINT_INVERTLIGHT) when printing to give
1141 a white background.
1142 If intermediate tones are used on screen then black on white print
1143 can be chosen with SCI_SETPRINTCOLOURMODE(SC_PRINT_BLACKONWHITE).
1144 Other options are the default, SC_PRINT_NORMAL, and
1145 SC_PRINT_COLOURONWHITE and SC_PRINT_COLOURONWHITEDEFAULTBG.
1146 </p>
1147 <h3>
1148 Direct Access
1149 </h3>
1150 <pre>
1151 SCI_GETDIRECTFUNCTION
1152 SCI_GETDIRECTPOINTER
1153 </pre>
1154 <p>
1155 On Windows, the message passing scheme used to communicate between
1156 the container and Scintilla is mediated by the operating system
1157 SendMessage function which can lead to bad performance when
1158 calling intensively.
1159 To avoid this overhead a pointer to a message handling function
1160 inside Scintilla can be retrieved with SCI_GETDIRECTFUNCTION.
1161 The first argument to use when calling the returned function is the
1162 value retrieved from SCI_GETDIRECTPOINTER. After that go the
1163 message number, wParam, and lParam.
1164 </p>
1165 <p>
1166 While faster, this direct calling will cause problems if performed
1167 from a different thread to the native thread of the Scintilla
1168 window in which case SendMessage should be used to synchronize with
1169 the window's thread.
1170 </p>
1171 <p>
1172 This feature also works on GTK+ but has no significant impact on
1173 speed.
1174 </p>
1175 <h3>
1176 Multiple Views
1177 </h3>
1178 <pre>
1179 SCI_GETDOCPOINTER
1181 SCI_CREATEDOCUMENT
1184 </pre>
1185 <p>
1186 This is to allow simple split views of documents and so
1187 applications may maintain multiple buffer which may be
1188 individually selected into the editor. Each Scintilla has a pointer
1189 to a used document.
1190 Initially the used document is a default one created when the
1191 Scintilla was created.
1192 The SCI_GETDOCPOINTER call returns a pointer to the used document.
1193 SCI_SETDOCPOINTER sets the used document.
1194 SCI_SETDOCPOINTER(0) switches to a new empty document.
1195 Before closing down Scintilla make sure all document pointers
1196 retrieved are released to avoid memory leaks.
1197 </p>
1198 <p>
1199 A new document may be created by SCI_CREATEDOCUMENT which returns a
1200 pointer to the document. This document is not selected into the
1201 editor and starts with a reference count of 1. A document may be
1202 released with SCI_RELEASEDOCUMENT and have its reference count
1203 incremented with SCI_ADDREFDOCUMENT.
1204 </p>
1205 <h3>
1206 Folding
1207 </h3>
1208 <pre>
1209 SCI_VISIBLEFROMDOCLINE(int docLine)
1210 SCI_DOCLINEFROMVISIBLE(int displayLine)
1211 SCI_SETFOLDLEVEL(int line, int level)
1212 SCI_SETFOLDFLAGS(int flags)
1213 SCI_GETFOLDLEVEL(int line)
1214 SCI_GETLASTCHILD(int line)
1215 SCI_GETFOLDPARENT(int line)
1216 SCI_SHOWLINES(int lineStart, int lineEnd)
1217 SCI_HIDELINES(int lineStart, int lineEnd)
1218 SCI_GETLINEVISIBLE(int line)
1219 SCI_SETFOLDEXPANDED(int line)
1220 SCI_GETFOLDEXPANDED(int line)
1221 SCI_TOGGLEFOLD(int line)
1222 SCI_ENSUREVISIBLE(int line)
1223 SCI_ENSUREVISIBLEENFORCEPOLICY(int line)
1224 </pre>
1225 <p>
1226 The fundamental operation in folding is making lines invisible or
1227 visible.
1228 Line visibility is a property of the view rather than the document
1229 so each view may be displaying a different set of lines.
1230 SCI_SHOWLINES and SCI_HIDELINES show or hide a range of lines.
1231 SCI_GETLINEVISIBLE determines whether a line is visible.
1232 When some lines are hidden, then a particular line in the document
1233 may be displayed at a different position to its document position.
1234 SCI_VISIBLEFROMDOCLINE and SCI_DOCLINEFROMVISIBLE map from
1235 document line to display line and back.
1236 </p>
1237 <p>
1238 Generally the fold points of a document are based on the
1239 hierarchical structure of the contents of the document.
1240 In Python, the hierarchy is determined by indentation and in C++
1241 by brace characters. This hierarchy can be represented within a
1242 Scintilla document object by attaching a numeric level to each
1243 line.
1244 The initial level of a file is SC_FOLDLEVELBASE to allow unsigned
1245 arithmetic on levels. The SC_FOLDLEVELNUMBERMASK constant can be
1246 used to mask out the other bits to reveal the fold level number.
1247 There are also two bit flags associated with each line.
1248 SC_FOLDLEVELWHITEFLAG indicates that the line is blank and allows
1249 it to be treated slightly different then its level may indicate.
1250 For example, blank lines should generally not be fold points.
1251 SC_FOLDLEVELHEADERFLAG indicates that the line is a header or fold
1252 point.
1253 </p>
1254 <p>
1255 The hierarchy can be navigated just through SCI_GETFOLDLEVEL, but
1256 it is often useful to find the parent of a line (SCI_GETFOLDPARENT)
1257 or the line that is the last child of a line (SCI_GETLASTCHILD).
1258 </p>
1259 <p>
1260 Each fold point may be either expanded, displaying all its child
1261 lines, or contracted, hiding all the child lines. This is per view
1262 state and can be manipulated with SCI_SETFOLDEXPANDED and
1263 SCI_GETFOLDEXPANDED. Using SCI_SETFOLDEXPANDED does not show or
1264 hide any lines but only changes a state flag and the margin markers
1265 that show the contraction state. SCI_TOGGLEFOLD performs the
1266 expansion or contraction of a fold point in the manner normally
1267 expected.
1268 </p>
1269 <p>
1270 A hidden line may be hidden because more than one of its parent
1271 lines is contracted. SCI_ENSUREVISIBLE travels up the fold
1272 hierarchy, expanding any contracted folds until it reaches the top
1273 level. The line will then be visible.
1274 </p>
1275 <p>
1276 The fold flags is a set of bit flags set with the SCI_SETFOLDFLAGS
1277 message to determine where folding lines are drawn. 2 is draw above
1279 expanded and 16 is draw below if not expanded.
1280 64 is display hexadecimal fold levels in line margin to aid debugging folding.
1281 This feature needs to be redesigned to be sensible.
1282 </p>
1283 <h3>
1284 Line Wrapping
1285 </h3>
1286 <pre>
1287 SCI_SETWRAPMODE(SC_WRAP_NONE or SC_WRAP_WORD)
1288 SCI_GETWRAPMODE
1289 </pre>
1290 <p>
1291 When the wrap mode is set to SC_WRAP_WORD lines wider than the
1292 window width are continued on the following lines. Lines are
1293 broken after space or tab characters or between runs of different
1294 styles. If this is not possible because a word in one style is
1295 wider than the window then the break occurs before after the last
1296 character that completely fits on the line.
1297 The horizontal scroll bar does not appear when wrap mode is on.
1298 </p>
1299 <pre>
1300 SCI_SETLAYOUTCACHE(SC_CACHE_NONE or SC_CACHE_CARET or SC_CACHE_PAGE or SC_CACHE_DOCUMENT)
1301 SCI_GETLAYOUTCACHE
1302 </pre>
1303 <p>
1304 Much of the time used by Scintilla is spent on laying out and drawing text.
1305 The same text layout calculations may be performed many times
1306 even when the data used in these calculations does not change.
1307 To avoid these unnecessary calculations in some circumstances, the line
1308 layout cache can store the results of the calculations.
1309 The cache in invalidated whenever the underlying data, such as the contents
1310 or styling of the document changes.
1311 Caching the layout of the whole document has the most effect, making dynamic
1313 required by the document contents.
1314 </p>
1315 <p>
1316 SC_CACHE_NONE performs no caching and is the default.
1317 SC_CACHE_CARET caches the layout information for the line containing the
1318 caret.
1319 SC_CACHE_PAGE caches the layout of the visible lines and the caret
1320 line.
1321 SC_CACHE_DOCUMENT caches the layout of the entire document.
1322 </p>
1323 <h3>
1324 Zooming
1325 </h3>
1326 <pre>
1327 SCI_ZOOMIN
1328 SCI_ZOOMOUT
1329 SCI_SETZOOM
1330 SCI_GETZOOM
1331 </pre>
1332 <p>
1333 The text can be made larger and smaller by using SCI_ZOOMIN and
1334 SCI_ZOOMOUT.
1335 The zoom level can be retrieved by SCI_GETZOOM and set by
1336 SCI_SETZOOM.
1338 styles point size. The calculated point size never goes below 2.
1339 </p>
1340 <h3>
1341 Long Lines
1342 </h3>
1343 <pre>
1344 SCI_GETEDGECOLUMN
1345 SCI_SETEDGECOLUMN(int column)
1346 SCI_GETEDGEMODE
1347 SCI_SETEDGEMODE(int mode)
1348 SCI_GETEDGECOLOUR
1349 SCI_SETEDGECOLOUR(int colour)
1350 </pre>
1351 <p>
1352 This mechanism marks lines that are longer than a specified length
1353 in one of two ways. A vertical line can be displayed at the
1354 specified column number (EDGE_LINE) or characters after that
1355 column can be displayed with a specified background colour
1356 (EDGE_BACKGROUND). The vertical line works well for monospaced
1357 fonts but not for proportional fonts which should use
1358 EDGE_BACKGROUND. The default is to not have any form of long line
1359 marking (EDGE_NONE).
1360 </p>
1361 <h3>
1362 Lexer
1363 </h3>
1364 <pre>
1365 SCI_SETLEXER(int lexer)
1367 SCI_GETLEXER
1368 SCI_COLOURISE(int start, int end)
1369 SCI_SETPROPERTY(char *key, char *value)
1370 SCI_SETKEYWORDS(int keywordset, char *keywordlist)
1371 </pre>
1372 <p>
1373 If the SciLexer version of Scintilla is used, then lexing support
1374 for some programming languages is included. A particular lexer may
1375 be chosen from the SCLEX* enumeration and it is invoked
1376 automatically to style the document as required. Lexers can also
1377 be chosen by string name rather than by integer ID.
1378 If the lexer is set to SCLEX_CONTAINER then the container is
1379 notified to perform styling as is the case with the standard
1380 Scintilla.DLL version. Styling may be requested for a range of the
1381 document by using SCI_COLOURISE.
1382 </p>
1383 <p>
1384 Settings can be communicated to the lexers using SCI_SETPROPERTY.
1385 Currently the "fold" property is defined for most of the lexers to
1386 set the fold structure if set to "1". SCLEX_PYTHON understands
1387 "tab.timmy.whinge.level" as a setting that determines how to
1388 indicate bad indentation. Many languages style a set of keywords
1389 distinctly from other words. Some languages, such as HTML may
1390 contain embedded languages, VBScript and Javascript are common for
1391 HTML. SCI_SETKEYWORDS specifies the keywords separated by spaces.
1393 for VBScript.
1394 </p>
1395 <h3>
1396 Notifications
1397 </h3>
1398 <p>
1399 Notifications are sent (fired) from the Scintilla control to its
1400 container when an event has occurred that may interest the
1401 container. Notifications are sent using the WM_NOTIFY message on
1402 Windows and the "notify" signal on GTK+ with a structure containing
1403 information about the event.
1404 </p>
1405 <pre>
1406 SCN_STYLENEEDED(int endstyleneeded)
1407 </pre>
1408 <p>
1409 Before displaying a page or printing, this message is sent to the
1410 container. It is a good opportunity for the container to ensure
1411 that syntax styling information for the visible text.
1412 </p>
1413 <pre>
1414 SCN_UPDATEUI
1415 SCN_CHECKBRACE
1416 </pre>
1417 <p>
1418 Either the text or styling of the document has changed or the
1419 selection range has changed. Now would be a good time to update
1420 any container UI elements that depend on document or view state.
1421 Was previously called SCN_CHECKBRACE because a common use is to
1422 check whether the caret is next to a brace and set highlights on
1423 this brace and its corresponding matching brace.
1424 </p>
1425 <pre>
1426 SCN_CHARADDED(int charadded)
1427 </pre>
1428 <p>
1429 Fired when the user types an ordinary text character (as opposed
1430 to a command character) which is entered into the text.
1431 Can be used by the container to decide to display a call tip or
1432 auto completion list.
1433 </p>
1434 <pre>
1435 SCN_POSCHANGED(int newPos)
1436 </pre>
1437 <p>
1438 Fired when the user moves the cursor to a different position in the text.
1439 Can be used by the container to cancel some time consuming thread.
1440 </p>
1441 <pre>
1442 SCN_SAVEPOINTREACHED
1443 SCN_SAVEPOINTLEFT
1444 SCI_SETSAVEPOINT
1445 </pre>
1446 <p>
1447 Sent to the container when the savepoint is entered or left,
1448 allowing the container to display a dirty indicator and change its
1449 menus.
1450 </p>
1451 <p>
1452 The container tells Scintilla where the save point is by sending
1453 the SCI_SETSAVEPOINT message. This is usually done when the file
1454 is saved or loaded. As Scintilla performs undo and redo
1455 operations, it will notify the container that it has entered or
1456 left the save point, allowing the container to know if the file
1457 should be considered dirty or not.
1458 </p>
1459 <pre>
1460 SCN_MODIFYATTEMPTRO
1461 </pre>
1462 <p>
1463 When in read-only mode, this notification is sent to the container
1464 should the user try to edit the document. This can be used to
1465 check the document out of a version control system.
1466 </p>
1467 <pre>
1468 SCN_DOUBLECLICK
1469 </pre>
1470 <p>
1471 Mouse button was double clicked in editor.
1472 </p>
1473 <pre>
1474 SCN_KEY
1475 </pre>
1476 <p>
1477 Reports all keys pressed. Used on GTK+ because of some problems
1478 with keyboard focus. Not sent by Windows version.
1479 </p>
1480 <pre>
1481 SCEN_SETFOCUS
1482 SCEN_KILLFOCUS
1483 </pre>
1484 <p>
1485 SCEN_SETFOCUS is fired when Scintilla receives focus and
1486 SCEN_KILLFOCUS when it loses focus.
1487 These notifications are sent using the WM_COMMAND message on
1488 Windows and the "Command" signal on GTK+ as this is the behaviour
1489 of the standard edit control.
1490 </p>
1491 <pre>
1492 SCN_MODIFIED
1493 SCEN_CHANGE
1494 SCI_SETMODEVENTMASK(int eventmask)
1495 SCI_GETMODEVENTMASK
1496 </pre>
1497 <p>
1498 SCN_MODIFIED is fired when the document has been changed including
1499 changes to both the text and styling. The notification structure
1500 contains information about what changed, how the change occurred
1501 and whether this changed the number of lines in the document. No
1502 modifications may be performed while in a SCN_MODIFIED event.
1503 </p>
1504 <p>
1505 SCEN_CHANGE is fired when the text of the document has been changed
1506 for any reason. This notification is sent using the WM_COMMAND
1507 message on Windows and the "Command" signal on GTK+ as this is the
1508 behaviour of the standard edit control.
1509 </p>
1510 <p>
1511 Both these notifications can be masked by the SCI_SETMODEVENTMASK
1512 function which sets which notification types are sent to the
1513 container. For example, a container may decide to see only
1514 notifications about changes to text and not styling changes by
1515 calling SCI_SETMODEVENTMASK(SC_MOD_INSERTTEXT|SC_MOD_DELETETEXT).
1516 </p>
1517 <p>
1518 The possible notification types are
1519 SC_MOD_INSERTTEXT,
1520 SC_MOD_DELETETEXT,
1521 SC_MOD_CHANGESTYLE,
1522 SC_MOD_CHANGEFOLD,
1523 SC_PERFORMED_USER,
1524 SC_PERFORMED_UNDO,
1525 SC_PERFORMED_REDO,
1526 SC_LASTSTEPINUNDOREDO,
1527 SC_MOD_CHANGEMARKER,
1528 SC_MOD_BEFOREINSERT,
1529 SC_MOD_BEFOREDELETE, and
1530 SC_MODEVENTMASKALL.
1531 </p>
1532 <pre>
1533 SCN_MACRORECORD
1534 </pre>
1535 <p>
1536 Tells the container that an operation is being performed so that
1537 the container may choose to record the fact if it is in a macro
1538 recording mode.
1539 </p>
1540 <pre>
1541 SCN_MARGINCLICK
1542 </pre>
1543 <p>
1544 Tells the container that the mouse was clicked inside a margin
1545 marked sensitive. Can be used to perform folding or to place
1546 breakpoints.
1547 </p>
1548 <pre>
1549 SCN_NEEDSHOWN
1550 </pre>
1551 <p>
1552 Scintilla has determined that a range of lines that is currently
1553 invisible should be made visible.
1554 An example of where this may be needed is if the end of line of a
1555 contracted fold point is deleted. This message is sent to the
1556 container in case it wants to make the line visible in some
1557 unusual way such as making the whole document visible.
1558 Most containers will just ensure each line in the range is
1559 visible by calling SCI_ENSUREVISIBLE.
1560 </p>
1561 <pre>
1562 SCN_PAINTED
1563 </pre>
1564 <p>
1565 Painting has just been done. Useful when you want to update some
1566 other widgets based on a change in Scintilla, but want to have the
1567 paint occur first to appear more responsive.
1568 </p>
1569 <pre>
1570 SCN_USERLISTSELECTION
1571 </pre>
1572 <p>
1573 User has selected an item in a user list.
1574 The list type is available in wParam and the text chosen in text.
1575 </p>
1576 <pre>
1577 SCN_URIDROPPED
1578 </pre>
1579 <p>
1580 Only on the GTK+ version. Indicates that the user has dragged a URI
1581 such as a file name or web address onto Scintilla.
1582 The container could interpret this as a request to open the file.
1583 </p>
1584 <pre>
1585 SCN_DWELLSTART
1586 SCN_DWELLEND
1587 SCI_SETMOUSEDWELLTIME
1588 SCI_GETMOUSEDWELLTIME
1589 SC_TIME_FOREVER
1590 </pre>
1591 <p>
1592 SCN_DWELLSTART is generated when the user hold the
1593 mouse still in one spot for the dwell period.
1594 SCN_DWELLEND is generated after a SCN_DWELLSTART
1595 and the mouse is moved or other activity such as key press
1596 indicates the dwell is over.
1597 </p>
1598 <p>
1599 The time the mouse must sit still, in milliseconds, to generate a
1600 SCI_DWELLSTART.
1601 If set to SC_TIME_FOREVER, the default, no dwell events will be
1602 generated.
1603 </p>
1604 <h3>
1605 Edit messages currently supported by Scintilla which will be
1606 removed in the future.
1607 </h3>
1608 <pre>
1609 WM_GETTEXT(int length, char *text)
1611 EM_GETLINE(int line, char *text)
1613 EM_SETREADONLY
1615 WM_CUT
1616 WM_COPY
1617 WM_PASTE
1618 WM_CLEAR
1619 WM_UNDO
1620 EM_CANUNDO
1621 EM_EMPTYUNDOBUFFER
1622 WM_GETTEXTLENGTH
1623 EM_GETFIRSTVISIBLELINE
1624 EM_GETLINECOUNT
1625 EM_GETMODIFY
1626 EM_SETMODIFY(bool ismodified)
1627 EM_GETRECT(RECT *rect)
1628 EM_GETSEL(int *start, int *end)
1630 EM_SETSEL(int start, int end)
1633 EM_LINEFROMCHAR(int position)
1634 EM_EXLINEFROMCHAR(int position)
1635 EM_LINEINDEX(int line)
1636 EM_LINELENGTH(int position)
1637 EM_SCROLL(int line)
1638 EM_LINESCROLL(int column, int line)
1639 EM_SCROLLCARET()
1640 EM_CANPASTE
1642 EM_POSFROMCHAR(int position, POINT *location)
1643 EM_SELECTIONTYPE
1644 EM_HIDESELECTION(bool hide)
1645 EM_FINDTEXT(int flags, FINDTEXTEX *ft)
1646 EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
1647 EM_GETMARGINS
1648 EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
1649 EM_FORMATRANGE
1650 </pre>
1651 <h3>
1652 Edit messages never supported by Scintilla
1653 </h3>
1654 <pre>
1655 EM_GETWORDBREAKPROC EM_GETWORDBREAKPROCEX
1656 EM_SETWORDBREAKPROC EM_SETWORDBREAKPROCEX
1657 EM_GETWORDWRAPMODE EM_SETWORDWRAPMODE
1658 EM_LIMITTEXT EM_EXLIMITTEXT
1659 EM_SETRECT EM_SETRECTNP
1660 EM_FMTLINES
1661 EM_GETHANDLE EM_SETHANDLE
1662 EM_GETPASSWORDCHAR EM_SETPASSWORDCHAR
1663 EM_SETTABSTOPS
1664 EM_FINDWORDBREAK
1665 EM_GETCHARFORMAT EM_SETCHARFORMAT
1666 EM_GETOLEINTERFACE EM_SETOLEINTERFACE
1667 EM_SETOLECALLBACK
1668 EM_GETPARAFORMAT EM_SETPARAFORMAT
1669 EM_PASTESPECIAL
1670 EM_REQUESTRESIZE
1671 EM_GETBKGNDCOLOR EM_SETBKGNDCOLOR
1672 EM_STREAMIN EM_STREAMOUT
1673 EM_GETIMECOLOR EM_SETIMECOLOR
1674 EM_GETIMEOPTIONS EM_SETIMEOPTIONS
1675 EM_GETOPTIONS EM_SETOPTIONS
1676 EM_GETPUNCTUATION EM_SETPUNCTUATION
1677 EM_GETTHUMB
1678 EM_GETEVENTMASK
1679 EM_SETEVENTMASK
1680 EM_DISPLAYBAND
1681 EM_SETTARGETDEVICE
1682 </pre>
1683 <p>
1684 Scintilla tries to be a superset of the standard windows Edit and
1685 Richedit controls wherever that makes sense. As it is not
1686 intended for use in a word processor, some edit messages can
1687 not be sensibly handled. Unsupported messages have no effect.
1688 </p>
1689 <h3>
1690 Building Scintilla
1691 </h3>
1692 <p>
1693 To build Scintilla or SciTE, see the README file present in both
1694 the scintilla and scite directories. For Windows, GCC 2.95.3,
1695 Borland C++ or Microsoft Visual C++ can be used for building.
1697 supported.
1698 </p>
1699 <h3>
1700 Static linking
1701 </h3>
1702 <p>
1703 On Windows, Scintilla is normally used as a dynamic library as a .DLL file.
1704 If you want to link Scintilla directly into your application .EXE or .DLL file,
1705 then the STATIC_BUILD preprocessor symbol should be defined and
1706 Scintilla_RegisterClasses called. STATIC_BUILD prevents compiling the
1707 DllMain function which will conflict with any DllMain defined in your code.
1708 Scintilla_RegisterClasses takes the HINSTANCE of your application and
1709 ensures that the "Scintilla" window class is registered. To make sure that
1710 the right pointing arrow cursor used in the margin is displayed by Scintilla
1711 add the scintilla/win32/Margin.cur file to your application's resources with
1712 the ID IDC_MARGIN which is defined in scintilla/win32/platfromRes.h as 400.
1713 </p>
1714 <h3>
1715 Ensuring lexers are linked into Scintilla
1716 </h3>
1717 <p>
1718 Depending on the compiler and linker used, the lexers may be stripped
1719 out. This is most often caused when building a static library. To ensure
1720 the lexers are linked in, the Scintilla_ForceLexers() function may be
1721 called. This function is not normally compiled and to ensure it is compiled
1722 the preprocessor symbol LINK_LEXERS should be defined.
1723 </p>
1724 </body>
1725 </html>