| blob | 4eda3ca0391daaf922756f26c66fa9d828875c67 |
6 <head>
15 <!--
16 /*<![CDATA[*/
17 CODE { font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
18 A:visited { color: blue; }
19 A:hover { text-decoration: underline ! important; }
20 A.message { text-decoration: none; font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
21 A.toc { text-decoration: none; }
22 A.jump { text-decoration: none; }
23 .S0 {
24 color: #808080;
25 }
26 .S2 {
27 font-family: 'Comic Sans MS';
28 color: #007F00;
29 font-size: 9pt;
30 }
31 .S3 {
32 font-family: 'Comic Sans MS';
33 color: #3F703F;
34 font-size: 9pt;
35 }
36 .S4 {
37 color: #007F7F;
38 }
39 .S5 {
40 font-weight: bold;
41 color: #00007F;
42 }
43 .S9 {
44 color: #7F7F00;
45 }
46 .S10 {
47 font-weight: bold;
48 color: #000000;
49 }
50 .S17 {
51 font-family: 'Comic Sans MS';
52 color: #3060A0;
53 font-size: 9pt;
54 }
55 DIV.highlighted {
56 background: #F7FCF7;
57 border: 1px solid #C0D7C0;
58 margin: 0.3em 3em;
59 padding: 0.3em 0.6em;
60 font-family: 'Verdana';
61 color: #000000;
62 font-size: 10pt;
63 }
64 /*]]>*/
65 -->
66 </style>
67 </head>
72 <tr>
77 </tr>
78 </table>
101 worth following if you want to contribute code to Scintilla but is not compulsory.</p>
105 <p>The Windows version of Scintilla is a Windows Control. As such, its primary programming
106 interface is through Windows messages. Early versions of Scintilla emulated much of the API
107 defined by the standard Windows Edit and RichEdit controls but those APIs are now deprecated in
108 favour of Scintilla's own, more consistent API. In addition to messages performing the actions
109 of a normal Edit control, Scintilla allows control of syntax styling, folding, markers, autocompletion
110 and call tips.</p>
112 <p>The GTK+ version also uses messages in a similar way to the Windows version. This is
113 different to normal GTK+ practice but made it easier to implement rapidly.</p>
115 <p>Scintilla does not properly support right-to-left languages like Arabic and Hebrew.
116 While text in these languages may appear correct, it is not possible to interact with this text
117 as is normal with other editing components.</p>
119 <p>This documentation describes the individual messages and notifications used by Scintilla. It
120 does not describe how to link them together to form a useful editor. For now, the best way to
121 work out how to develop using Scintilla is to see how SciTE uses it. SciTE exercises most of
122 Scintilla's facilities.</p>
124 <p>In the descriptions that follow, the messages are described as function calls with zero, one
127 are large enough to hold pointers, and the return value is also an integer large enough to contain a
128 pointer.
129 Although the commands only use the
130 arguments described, because all messages have two arguments whether Scintilla uses them or
131 not, it is strongly recommended that any unused arguments are set to 0. This allows future
132 enhancement of messages without the risk of breaking existing code. Common argument types
133 are:</p>
137 <tr>
142 </tr>
144 <tr>
148 </tr>
150 <tr>
153 <td>Arguments point at text that is being passed to Scintilla but not modified. The text
154 may be zero terminated or another argument may specify the character count, the
155 description will make this clear.</td>
156 </tr>
158 <tr>
161 <td>Arguments point at text buffers that Scintilla will fill with text. In some cases,
162 another argument will tell Scintilla the buffer size. In others, you must make sure that
163 the buffer is big enough to hold the requested text. If a NULL pointer (0) is passed
164 then, for SCI_* calls, the length that should be allocated is returned.</td>
165 </tr>
167 <tr>
170 <td>Colours are set using the RGB format (Red, Green, Blue). The intensity of each colour
173 colour is white. If you set all intensities to 0, the colour is black. When you set a
174 colour, you are making a request. What you will get depends on the capabilities of the
175 system and the current screen mode.</td>
176 </tr>
178 <tr>
181 <td>Translucency is set using an alpha value.
182 Alpha ranges from 0 (SC_ALPHA_TRANSPARENT) which is completely transparent to
184 is opaque and uses code that is not alpha-aware and may be faster. Not all platforms support
185 translucency and only some Scintilla features implement translucency.
186 The default alpha value for most features is SC_ALPHA_NOALPHA.</td>
187 </tr>
189 <tr>
193 enhancements.</td>
194 </tr>
195 </tbody>
196 </table>
201 <tbody>
202 <tr>
204 modification</a></td>
209 </tr>
211 <tr>
217 </tr>
219 <tr>
222 <td>o <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection and Virtual Space</a></td>
225 scrolling</a></td>
226 </tr>
228 <tr>
234 </tr>
236 <tr>
242 </tr>
244 <tr>
245 <td>o <a class="toc" href="#CaretAndSelectionStyles">Caret, selection, and hotspot styles</a></td>
250 </tr>
252 <tr>
258 Guides</a></td>
259 </tr>
261 <tr>
267 </tr>
269 <tr>
275 </tr>
277 <tr>
283 </tr>
285 <tr>
291 </tr>
293 <tr>
299 </tr>
301 <tr>
307 </tr>
309 <tr>
315 </tr>
317 <tr>
323 supported by Scintilla</a></td>
325 </tr>
327 <tr>
329 </tr>
330 </tbody>
331 </table>
340 <p>Each byte in a Scintilla document is followed by an associated byte of styling
341 information. The combination of a character byte and a style byte is called a cell. Style bytes
342 are interpreted an index into an array of styles.
343 Style bytes may be split into an index and a set of indicator bits
344 but this use is discouraged and indicators should now use
346 and related calls.
349 languages, and three independent indicators so that, for example, syntax errors, deprecated
350 names and bad indentation could all be displayed at once. The number of bits used for styles
353 The remaining bits can be used for indicators.</p>
355 <p>In this document, 'character' normally refers to a byte even when multi-byte characters are used.
356 Lengths measure the numbers of bytes, not the amount of characters in those bytes.</p>
358 <p>Positions within the Scintilla document refer to a character or the gap before that
361 The caret exists between character positions and can be located from before the first character (0)
364 <p>There are places where the caret can not go where two character bytes make up one character.
365 This occurs when a DBCS character from a language like Japanese is included in the document or
366 when line ends are marked with the CP/M standard of a carriage return followed by a line feed.
368 document.</p>
370 <p>All lines of text in Scintilla are the same height, and this height is calculated from the
371 largest font in any current style. This restriction is for performance; if lines differed in
372 height then calculations involving positioning of text would require the text to be styled
373 first.</p>
379 *text)</a><br />
383 *tr)</a><br />
395 *tr)</a><br />
399 <a class="message" href="#SCI_ENCODEDFROMUTF8">SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)</a><br />
401 </code>
409 entire document is returned.
411 the text as unmodified.</p>
420 This replaces all the text in the document with the zero terminated text string you pass
421 in.</p>
424 This message tells Scintilla that the current state of the document is unmodified. This is
425 usually done when the file is saved or loaded, hence the name "save point". As Scintilla
426 performs undo and redo operations, it notifies the container that it has entered or left the
431 should be considered dirty or not.</p>
437 This fills the buffer defined by text with the contents of the nominated line (lines start at
441 number of characters copied to the buffer. The returned text includes any end of line
442 characters. If you ask for a line number outside the range of lines in the document, 0
443 characters are copied. If the text argument is 0 then the length that should be allocated
444 to store the entire line is returned.</p>
455 current position are the same, the text is inserted at the caret position. The caret is
456 positioned after the inserted text and the caret is scrolled into view.</p>
460 These messages set and get the read-only flag for the document. If you mark a document as read
470 longer than the number of characters you wish to read. The return value is the length of the
481 This collects styled text into a buffer using two bytes for each cell, with the character at
482 the lower address of each pair and the style byte at the upper address. Characters between the
484 <code>struct Sci_TextRange</code> in <code>Scintilla.h</code>). Two 0 bytes are added to the end of
497 Allocate a document buffer large enough to store a given number of bytes.
498 The document will not be made smaller than its current contents.</p>
502 at the current position. This will include any 0's in the string that you might have expected
503 to stop the insert operation. The current position is set at the end of the inserted text,
504 but it is not scrolled into view.</p>
511 of the document. This will include any 0's in the string that you might have expected to stop
512 the operation. The current selection is not changed and the new text is not scrolled into
513 view.</p>
517 the current position if <code>pos</code> is -1. If the current position is after the insertion point
518 then it is moved along with its surrounding text but no scrolling is performed.</p>
521 Unless the document is read-only, this deletes all the text.</p>
524 Deletes a range of text in the document.</p>
527 When wanting to completely restyle the document, for example after choosing a lexer, the
529 folding state.</p>
533 negative or past the end of the document.</p>
537 negative or past the end of the document.</p>
541 This pair of routines sets and reads back the number of bits in each cell to use for styling,
542 to a maximum of 8 style bits. The remaining bits can be used as indicators. The standard
544 The number of styling bits needed by the current lexer can be found with
547 <p><b id="Sci_TextRange">Sci_TextRange</b> and <b id="Sci_CharacterRange">Sci_CharacterRange</b><br />
550 work.</p>
551 <pre>
552 struct Sci_CharacterRange {
553 long cpMin;
554 long cpMax;
555 };
557 struct Sci_TextRange {
558 struct Sci_CharacterRange chrg;
559 char *lpstrText;
560 };
561 </pre>
566 This method retrieves the value of the target encoded as UTF-8 which is the default
567 encoding of GTK+ so is useful for retrieving text for use in other parts of the user interface,
568 such as find and replace dialogs. The length of the encoded text in bytes is returned.
569 </p>
574 encoding which is useful for taking the results of a find dialog, for example, and receiving
575 a string of bytes that can be searched for in the document. Since the text can contain nul bytes,
577 length that will be converted. If set to -1, the length is determined by finding a nul byte.
578 The length of the converted string is returned.
579 </p>
583 <p>
584 There are methods to search for text and for regular expressions. The regular expression support
585 is limited and should only be used for simple cases and initial development. A different regular expression
587 or can be called from the container using direct access to the buffer contents through
589 </p>
591 *ttf)</a><br />
594 *text)</a><br />
596 *text)</a><br />
598 target</a><br />
599 </code>
602 Several of the search routines use flag options, which include a simple regular expression
603 search. Combine the flag options by adding them:</p>
606 <tbody>
607 <tr>
611 </tr>
613 <tr>
617 </tr>
619 <tr>
623 </tr>
625 <tr>
629 </tr>
630 <tr>
633 <td>Treat regular expression in a more POSIX compatible manner
634 by interpreting bare ( and ) for tagged sections rather than \( and \).</td>
635 </tr>
636 </tbody>
637 </table>
639 <p>You can
640 search backwards to find the previous occurrence of a search string by setting the end of the
641 search range before the start.</p>
646 <tbody>
647 <tr>
651 </tr>
653 <tr>
657 </tr>
659 <tr>
663 </tr>
665 <tr>
673 </tr>
675 <tr>
679 </tr>
681 <tr>
685 </tr>
687 <tr>
690 <td>This allows you to use a character x that would otherwise have a special meaning. For
691 example, \[ would be interpreted as [ and not as the start of a character set.</td>
692 </tr>
694 <tr>
697 <td>This indicates a set of characters, for example, [abc] means any of the characters a,
698 b or c. You can also use ranges, for example [a-z] for any lower case character.</td>
699 </tr>
701 <tr>
704 <td>The complement of the characters in the set. For example, [^A-Za-z] means any
705 character except an alphabetic character.</td>
706 </tr>
708 <tr>
712 </tr>
714 <tr>
718 </tr>
720 <tr>
725 </tr>
727 <tr>
732 </tr>
733 </tbody>
734 </table>
736 <p>Regular expressions will only match ranges within a single line, never matching over multiple lines.</p>
740 This message searches for text in the document. It does not use or move the current selection.
742 search type, which includes regular expression searches.</p>
746 to search. You can search backwards by
748 Set the <code>lpstrText</code> member of <code>Sci_TextToFind</code> to point at a zero terminated
749 text string holding the search pattern. If your language makes the use of <code>Sci_TextToFind</code>
754 <code>Sci_TextToFind</code> are filled in with the start and end positions of the found text.</p>
760 This structure is defined to have exactly the same shape as the Win32 structure
762 <pre>
763 struct Sci_TextToFind {
764 struct <a class="jump" href="#Sci_CharacterRange">Sci_CharacterRange</a> chrg; // range to search
765 char *lpstrText; // the search pattern (zero terminated)
766 struct Sci_CharacterRange chrgText; // returned as position of matching text
767 };
768 </pre>
773 These messages provide relocatable search support. This allows multiple incremental
774 interactive searches to be macro recorded while still setting the selection to found text so
781 selection, that is, the end of the selection that is nearer to the start of the document. You
786 occurrence of the zero terminated search string pointed at by text. The search is modified by
790 of the matching text. The selection is updated to show the matched text, but is not scrolled
791 into view.</p>
799 modifications cause scrolling and other visible changes, which may take some time and cause
800 unwanted display updates. If performing many changes, such as a replace all command, the target
801 can be used instead. First, set the target, ie. the range to be replaced. Then call
805 which uses a counted string to allow searching for null characters. It returns the
806 position of the start of the matching text range or -1 for failure, in which case the target is not moved. The flags used by
812 structure.</p>
821 *text)</a><br />
823 *text)</a><br />
825 *text)</a><br />
827 </code>
833 These functions set and return the start and end of the target. When searching in non-regular
834 expression mode, you can set start greater than end to find the last matching text in the
835 target rather than the first matching text. The target is also set by a successful
839 Set the target start and end to the start and end positions of the selection.</p>
845 expression search.</p>
848 This searches for the first occurrence of a text string in the target defined by
852 text and the return value is the position of the start of the matching text. If the search
858 After replacement, the target range refers to the replacement text.
859 The return value
860 is the length of the replacement string.<br />
861 Note that the recommended way to delete text in the document is to set the target to the text to be removed,
862 and to perform a replace target with an empty string.</p>
867 characters to use. The replacement string is formed from the text string with any sequences of
869 expression search. <code>\0</code> is replaced with all the matched text from the most recent search.
870 After replacement, the target range refers to the replacement text.
871 The return value is the length of the replacement string.</p>
874 Discover what text was matched by tagged expressions in a regular expression search.
875 This is useful if the application wants to interpret the replacement string itself.</p>
883 When overtype is enabled, each typed character replaces the character to the right of the text
884 caret. When overtype is disabled, characters are inserted at the caret.
887 mode.</p>
898 const char *text)</a><br />
900 <a class="message" href="#SCI_SETPASTECONVERTENDINGS">SCI_SETPASTECONVERTENDINGS(bool convert)</a><br />
902 </code>
910 These commands perform the standard tasks of cutting and copying data to the clipboard,
911 pasting from the clipboard into the document, and clearing the document.
915 selection ranges implying that a copy or cut to the clipboard should work.</p>
918 unless the document is read-only.</p>
920 <p>On X, the clipboard is asynchronous and may require several messages between
921 the destination and source applications. Data from SCI_PASTE will not arrive in the
922 document immediately.</p>
925 selection is empty then the current line is copied. On Windows, an extra "MSDEVLineSelect" marker
927 the whole line before the current line.</p>
933 text to the system clipboard.</p>
937 If this property is set then when text is pasted any line ends are converted to match the document's
938 end of line mode as set with
940 Currently only changeable on Windows. On GTK+ pasted text is always converted.</p>
946 If an error occurs, Scintilla may set an internal error number that can be retrieved with
949 The currently defined statuses are:
950 </p>
954 <tr>
958 </tr>
960 <tr>
964 </tr>
966 <tr>
970 </tr>
972 </tbody>
973 </table>
977 <p>Scintilla has multiple level undo and redo. It will continue to collect undoable actions
978 until memory runs out. Scintilla saves actions that change the document. Scintilla does not
979 save caret and selection movements, view scrolling and the like. Sequences of typing or
980 deleting are compressed into single transactions to make it easier to undo and redo at a sensible
981 level of detail. Sequences of actions can be combined into transactions that are undone as a unit.
983 <code>SCI_ENDUNDOACTION</code> messages. These transactions can be nested and only the top-level
984 sequences are undone as units.</p>
991 collectUndo)</a><br />
996 </code>
1004 <p><code>SCI_CANUNDO</code> returns 0 if there is nothing to undo, and 1 if there is. You would
1005 typically use the result of this message to enable/disable the Edit menu Undo command.</p>
1012 actions to redo. You could typically use the result of this message to enable/disable the Edit
1013 menu Redo command.</p>
1016 This command tells Scintilla to forget any saved undo or redo history. It also sets the save
1017 point to the start of the undo buffer, so the document will appear to be unmodified. This does
1020 container.</p>
1026 You can control whether Scintilla collects undo information with
1029 <code>SCI_EMPTYUNDOBUFFER</code> to avoid the undo buffer being unsynchronized with the data in
1030 the buffer.</p>
1032 <p>You might wish to turn off saving undo information if you use the Scintilla to store text
1033 generated by a program (a Log view) or in a display window where text is often deleted and
1034 regenerated.</p>
1038 Send these two messages to Scintilla to mark the beginning and end of a set of operations that
1039 you want to undo all as one operation but that you have to generate as several operations.
1040 Alternatively, you can use these to mark a set of operations that you do not want to have
1041 combined with the preceding or following operations if they are undone.</p>
1044 The container can add its own actions into the undo stack by calling
1046 notification will be sent to the container with the
1051 <p>For example, if the container wanted to allow undo and redo of a 'toggle bookmark' command then
1053 Then when it receives a notification to undo or redo it toggles a bookmark on the line given by
1054 the token field. If there are different types of commands or parameters that need to be stored into the undo
1055 stack then the container should maintain a stack of its own for the document and use the current
1062 coalesced along with any insertion and deletion actions into a single compound action, otherwise 0.
1063 Coalescing treats coalescible container actions as transparent so will still only group together insertions that
1064 look like typing or deletions that look like multiple uses of the Backspace or Delete keys.
1065 </p>
1068 <p>Scintilla maintains a selection that stretches between two points, the anchor and the
1069 current position. If the anchor and the current position are the same, there is no selected
1070 text. Positions in the document range from 0 (before the first character), to the document size
1071 (after the last character). If you use messages, there is nothing to stop you setting a
1072 position that is in the middle of a CRLF pair, or in the middle of a 2 byte character. However,
1073 keyboard commands will not move the caret into such positions.</p>
1077 <a class="message" href="#SCI_SETFIRSTVISIBLELINE">SCI_SETFIRSTVISIBLELINE(int lineDisplay)</a><br />
1102 y)</a><br />
1103 <a class="message" href="#SCI_CHARPOSITIONFROMPOINT">SCI_CHARPOSITIONFROMPOINT(int x, int y)</a><br />
1104 <a class="message" href="#SCI_CHARPOSITIONFROMPOINTCLOSE">SCI_CHARPOSITIONFROMPOINTCLOSE(int x, int
1105 y)</a><br />
1107 position)</a><br />
1109 position)</a><br />
1116 <a class="message" href="#SCI_GETLINESELSTARTPOSITION">SCI_GETLINESELSTARTPOSITION(int line)</a><br />
1117 <a class="message" href="#SCI_GETLINESELENDPOSITION">SCI_GETLINESELENDPOSITION(int line)</a><br />
1120 onlyWordCharacters)</a><br />
1122 onlyWordCharacters)</a><br />
1125 <a class="message" href="#SCI_COUNTCHARACTERS">SCI_COUNTCHARACTERS(int startPos, int endPos)</a><br />
1126 <a class="message" href="#SCI_TEXTWIDTH">SCI_TEXTWIDTH(int styleNumber, const char *text)</a><br />
1131 </code>
1135 Both these messages return the length of the document in bytes.</p>
1138 This returns the number of lines in the document. An empty document contains 1 line. A
1143 These messages retrieve and set the line number of the first visible line in the Scintilla view. The first line
1147 This returns the number of complete lines visible on the screen. With a constant line height,
1148 this is the vertical space available divided by the line separation. Unless you arrange to size
1149 your window to an integral number of lines, there may be a partial line visible at the bottom
1150 of the view.</p>
1153 This returns non-zero if the document is modified and 0 if it is unmodified. The modified
1154 status of a document is determined by the undo position relative to the save point. The save
1156 usually when you have saved data to a file.</p>
1158 <p>If you need to be notified when the document becomes modified, Scintilla notifies the
1167 remove any selection (i.e. set the anchor to the same position as <code>currentPos</code>). The
1168 caret is scrolled into view after this operation.</p>
1172 the caret visible, if necessary. It is equivalent to
1174 position.</p>
1178 and scrolls the view (if needed) to make it visible. The anchor position is set the same as the
1180 the line set is the first or last.</p>
1183 This sets the current position and creates a selection between the anchor and the current
1184 position. The caret is not scrolled into view.</p>
1189 This returns the current position.</p>
1192 This sets the anchor position and creates a selection between the anchor position and the
1193 current position. The caret is not scrolled into view.</p>
1198 This returns the current anchor position.</p>
1202 These set the selection based on the assumption that the anchor position is less than the
1203 current position. They do not make the caret visible. The table shows the positions of the
1204 anchor and the current position after using these messages.</p>
1208 <tr>
1209 <th>
1210 </th>
1215 </tr>
1216 </thead>
1219 <tr>
1225 </tr>
1227 <tr>
1233 </tr>
1234 </tbody>
1235 </table>
1241 These return the start and end of the selection without regard to which end is the current
1242 position and which is the anchor. <code>SCI_GETSELECTIONSTART</code> returns the smaller of the
1243 current position or the anchor position. <code>SCI_GETSELECTIONEND</code> returns the larger of
1244 the two values.</p>
1247 This removes any selection and sets the caret at <code>pos</code>. The caret is not scrolled into view.</p>
1250 This selects all the text in the document. The current position is not scrolled into view.</p>
1258 This returns the document position that corresponds with the start of the line. If
1262 last line), the return value is the end of the document.</p>
1265 This returns the position at the end of the line, before any line end characters. If <code>line</code>
1266 is the last line in the document (which does not have any end of line characters), the result is the size of the
1272 is negative or beyond the last line in the document, the result is 0. If you want the length of
1274 href="#SCI_GETLINEENDPOSITION"><code>SCI_GETLINEENDPOSITION(line)</code></a> - <a class="message"
1279 buffer. The buffer size should be determined by calling with a NULL pointer for the <code>text</code> argument
1281 This allows for rectangular and discontiguous selections as well as simple selections.
1282 See <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection</a> for information on
1283 how multiple and rectangular selections and virtual space are copied.</p>
1290 </code></p>
1293 This retrieves the text of the line containing the caret and returns the position within the
1295 the text you wish to retrieve and a terminating 0 character.
1298 If the text argument is 0 then the length that should be allocated
1299 to store the entire current line is returned.</p>
1312 The two functions set and get the selection mode, which can be
1317 When set in these modes, regular caret moves will extend or reduce the selection,
1319 The get function returns the current mode even if the selection was made by mouse
1320 or with regular extended moves.
1321 <code>SC_SEL_THIN</code> is the mode after a rectangular selection has been typed into and ensures
1322 that no characters are selected.</p>
1326 Retrieve the position of the start and end of the selection at the given line with
1327 INVALID_POSITION returned if no selection on this line.</p>
1330 If the caret is off the top or bottom of the view, it is moved to the nearest line that is
1331 visible to its current position. Any selection is lost.</p>
1334 onlyWordCharacters)</b><br />
1336 onlyWordCharacters)</b><br />
1337 These messages return the start and end of words using the same definition of words as used
1338 internally within Scintilla. You can set your own list of characters that count as words with
1340 sets the start or the search, which is forwards when searching for the end and backwards when
1341 searching for the start.</p>
1345 <code>false</code> (0), the first character in the search direction sets the type of the search
1346 as word or non-word and the search stops at the first non-matching character. Searches are also
1347 terminated by the start or end of the document.</p>
1355 <tr>
1365 </tr>
1366 </thead>
1369 <tr>
1379 </tr>
1381 <tr>
1391 </tr>
1393 <tr>
1403 </tr>
1405 <tr>
1415 </tr>
1416 </tbody>
1417 </table>
1421 These messages return the position before and after another position
1422 in the document taking into account the current code page. The minimum
1423 position returned is 0 and the maximum is the last position in the document.
1424 If called with a position within a multi byte character will return the position
1425 of the start/end of that character.</p>
1428 Returns the number of whole characters between two positions..</p>
1432 be used, for example, to decide how wide to make the line number margin in order to display a
1433 given number of numerals.</p>
1436 This returns the height in pixels of a particular line. Currently all lines are the same
1437 height.</p>
1441 taking the width of tabs into account. This returns the column number of the last tab on the
1443 <code>pos</code>. If there are no tab characters on the line, the return value is the number of
1444 characters up to the position on the line. In both cases, double byte characters count as a
1445 single character. This is probably only useful with monospaced fonts.</p>
1449 taking the width of tabs into account. It treats a multi-byte character as a single column.
1456 window or not close to any characters.</p>
1461 <code>SCI_CHARPOSITIONFROMPOINTCLOSE</code> is similar but returns -1 if the point is outside the
1462 window or not close to any characters. This is similar to the previous methods but finds characters rather than
1463 inter-character positions.</p>
1468 in the document.</p>
1474 is drawn as normal text.</p>
1477 Scintilla remembers the x value of the last position horizontally moved to explicitly by the
1478 user and this value is then used when moving vertically such as by using the up and down keys.
1479 This message sets the current x position of the caret as the remembered value.</p>
1482 Move the selected lines up one line, shifting the line above after the selection.
1483 The selection will be automatically extended to the beginning of the selection's first line and the end of the seletion's last line.
1484 If nothing was selected, the line the cursor is currently at will be selected.</p>
1487 Move the selected lines down one line, shifting the line below before the selection.
1488 The selection will be automatically extended to the beginning of the selection's first line and the end of the seletion's last line.
1489 If nothing was selected, the line the cursor is currently at will be selected.</p>
1493 <code>
1494 <a class="message" href="#SCI_SETMULTIPLESELECTION">SCI_SETMULTIPLESELECTION(bool multipleSelection)</a><br />
1496 <a class="message" href="#SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</a><br />
1497 <a class="message" href="#SCI_GETADDITIONALSELECTIONTYPING">SCI_GETADDITIONALSELECTIONTYPING</a><br />
1500 <a class="message" href="#SCI_SETVIRTUALSPACEOPTIONS">SCI_SETVIRTUALSPACEOPTIONS(int virtualSpaceOptions)</a><br />
1502 <a class="message" href="#SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</a><br />
1503 <a class="message" href="#SCI_GETRECTANGULARSELECTIONMODIFIER">SCI_GETRECTANGULARSELECTIONMODIFIER</a><br />
1504 <br />
1513 <br />
1515 <a class="message" href="#SCI_SETSELECTIONNCARET">SCI_SETSELECTIONNCARET(int selection, int pos)</a><br />
1516 <a class="message" href="#SCI_GETSELECTIONNCARET">SCI_GETSELECTIONNCARET(int selection)</a><br />
1517 <a class="message" href="#SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</a><br />
1518 <a class="message" href="#SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</a><br />
1519 <a class="message" href="#SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</a><br />
1520 <a class="message" href="#SCI_GETSELECTIONNANCHOR">SCI_GETSELECTIONNANCHOR(int selection)</a><br />
1521 <a class="message" href="#SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</a><br />
1522 <a class="message" href="#SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</a><br />
1523 <a class="message" href="#SCI_SETSELECTIONNSTART">SCI_SETSELECTIONNSTART(int selection, int pos)</a><br />
1524 <a class="message" href="#SCI_GETSELECTIONNSTART">SCI_GETSELECTIONNSTART(int selection)</a><br />
1525 <a class="message" href="#SCI_SETSELECTIONNEND">SCI_SETSELECTIONNEND(int selection, int pos)</a><br />
1527 <br />
1529 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARET">SCI_SETRECTANGULARSELECTIONCARET(int pos)</a><br />
1530 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARET">SCI_GETRECTANGULARSELECTIONCARET</a><br />
1531 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</a><br />
1532 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</a><br />
1533 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</a><br />
1534 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHOR">SCI_GETRECTANGULARSELECTIONANCHOR</a><br />
1535 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</a><br />
1536 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</a><br />
1537 <br />
1539 <a class="message" href="#SCI_SETADDITIONALSELALPHA">SCI_SETADDITIONALSELALPHA(int alpha)</a><br />
1541 <a class="message" href="#SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int colour)</a><br />
1542 <a class="message" href="#SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int colour)</a><br />
1543 <a class="message" href="#SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int colour)</a><br />
1545 <a class="message" href="#SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</a><br />
1547 <a class="message" href="#SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</a><br />
1548 <a class="message" href="#SCI_GETADDITIONALCARETSVISIBLE">SCI_GETADDITIONALCARETSVISIBLE</a><br />
1549 <br />
1553 </code>
1555 <p>
1556 There may be multiple selections active at one time.
1557 More selections are made by holding down the Ctrl key while dragging with the mouse.
1558 The most recent selection is the main selection and determines which part of the document is shown automatically.
1559 Any selection apart from the main selection is called an additional selection.
1560 The calls in the previous section operate on the main selection.
1561 There is always at least one selection.
1562 </p>
1564 <p>
1565 Rectangular selections are handled as multiple selections although the original rectangular range is remembered so that
1566 subsequent operations may be handled differently for rectangular selections. For example, pasting a rectangular selection
1567 places each piece in a vertical column.
1568 </p>
1570 <p>
1571 Virtual space is space beyond the end of each line. The caret may be moved into virtual space but no real space will be
1572 added to the document until there is some text typed or some other text insertion command is used.
1573 </p>
1575 <p>When discontiguous selections are copied to the clipboard, each selection is added to the clipboard text
1576 in order with no delimiting characters.
1577 For rectangular selections the document's line end is added after each line's text. Rectangular selections
1578 are always copied from top line to bottom, not in the in order of selection.Virtual space is not copied.</p>
1580 <p>
1583 Enable or disable multiple selection. When multiple selection is disabled, it is not possible to select
1584 multiple ranges by holding down the Ctrl key while dragging with the mouse.</p>
1586 <p>
1587 <b id="SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</b><br />
1589 Whether typing, backspace, or delete works with multiple selections simultaneously.</p>
1591 <p>
1594 When pasting into multiple selections, the pasted text can go into just the main selection with <code>SC_MULTIPASTE_ONCE</code>=0
1595 or into each selection with <code>SC_MULTIPASTE_EACH</code>=1. <code>SC_MULTIPASTE_ONCE</code> is the default.</p>
1597 <p>
1600 Virtual space can be enabled or disabled for rectangular selections or in other circumstances or in both.
1605 <p>
1606 <b id="SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</b><br />
1608 On GTK+, the key used to indicate that a rectangular selection should be created when combined with a mouse drag can be set.
1609 The three possible values are <code>SCMOD_CTRL</code>=2 (default), <code>SCMOD_ALT</code>=4 or <code>SCMOD_SUPER</code>=8.
1610 Since <code>SCMOD_ALT</code> is often already used by a window manager, the window manager may need configuring to allow this choice.
1611 <code>SCMOD_SUPER</code> is often a system dependent modifier key such as the Left Windows key on a Windows keyboard or the
1612 Command key on a Mac.</p>
1614 <p>
1616 Return the number of selections currently active.</p>
1618 <p>
1622 <p>
1626 <p>
1628 Set a single selection from <code>anchor</code> to <code>caret</code> as the only selection.</p>
1630 <p>
1632 Add a new selection from <code>anchor</code> to <code>caret</code> as the main selection retaining all other
1633 selections as additional selections.
1634 Since there is always at least one selection, to set a list of selections, the first selection should be
1635 added with <code>SCI_SETSELECTION</code> and later selections added with <code>SCI_ADDSELECTION</code></p>
1637 <p>
1640 One of the selections is the main selection which is used to determine what range of text is automatically visible.
1641 The main selection may be displayed in different colours or with a differently styled caret.
1642 Only an already existing selection can be made main.</p>
1644 <p>
1647 <b id="SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</b><br />
1648 <b id="SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</b><br />
1649 <b id="SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</b><br />
1651 <b id="SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</b><br />
1652 <b id="SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</b><br />
1653 Set or query the position and amount of virtual space for the caret and anchor of each already existing selection.</p>
1655 <p>
1660 Set or query the start and end position of each already existing selection.
1661 Mostly of use to query each range for its text.</p>
1663 <p>
1666 <b id="SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</b><br />
1667 <b id="SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</b><br />
1668 <b id="SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</b><br />
1670 <b id="SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</b><br />
1671 <b id="SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</b><br />
1672 Set or query the position and amount of virtual space for the caret and anchor of the rectangular selection.
1673 After setting the rectangular selection, this is broken down into multiple selections, one for each line.</p>
1675 <p>
1678 <b id="SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1679 <b id="SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int <a class="jump" href="#colour">colour</a>)</b><br />
1680 Modify the appearence of additional selections so that they can be differentiated from the main selection which has its appearence set with
1686 <p>
1687 <b id="SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1689 <b id="SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</b><br />
1691 Modify the appearence of additional carets so that they can be differentiated from the main caret which has its appearence set with
1697 <p>
1698 <b id="SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</b><br />
1702 <p>
1705 These commands may be assigned to keys to make it possible to manipulate multiple selections.
1706 <code>SCI_SWAPMAINANCHORCARET</code> moves the caret to the opposite end of the main selection.
1708 </p>
1714 caretSlop)</a><br />
1716 caretSlop)</a><br />
1718 caretSlop)</a><br />
1727 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING">SCI_SETSCROLLWIDTHTRACKING(bool tracking)</a><br />
1730 endAtLastLine)</a><br />
1732 </code>
1735 This will attempt to scroll the display by the number of columns and lines that you specify.
1736 Positive line values increase the line number at the top of the screen (i.e. they move the text
1737 upwards as far as the user is concerned), Negative line values do the reverse.</p>
1739 <p>The column measure is the width of a space in the default style. Positive values increase
1740 the column at the left edge of the view (i.e. they move the text leftwards as far as the user
1741 is concerned). Negative values do the reverse.</p>
1746 If the current position (this is the caret if there is no selection) is not visible, the view
1747 is scrolled to make it visible according to the current caret policy.</p>
1757 <tr>
1761 unwanted zone (UZ) where the caret is... unwanted. This zone is defined as a number of
1762 pixels near the vertical margins, and as a number of lines near the horizontal margins.
1763 By keeping the caret away from the edges, it is seen within its context. This makes it
1764 likely that the identifier that the caret is on can be completely seen, and that the
1765 current line is seen with some of the lines following it, which are often dependent on
1766 that line.</td>
1767 </tr>
1769 <tr>
1775 </tr>
1777 <tr>
1780 <td>If set, the display is moved more energetically so the caret can move in the same
1781 direction longer before the policy is applied again. '3UZ' notation is used to indicate
1782 three time the size of the UZ as a distance to the margin.</td>
1783 </tr>
1785 <tr>
1788 <td>If not set, instead of having symmetrical UZs, the left and bottom UZs are extended
1789 up to right and top UZs respectively. This way, we favour the displaying of useful
1790 information: the beginning of lines, where most code reside, and the lines after the
1791 caret, for example, the body of a function.</td>
1792 </tr>
1793 </tbody>
1794 </table>
1798 <tr>
1810 or going into the UZ) display is...</th>
1811 </tr>
1812 </thead>
1815 <tr>
1827 </tr>
1829 <tr>
1841 </tr>
1843 <tr>
1855 </tr>
1857 <tr>
1869 </tr>
1871 <tr>
1883 </tr>
1885 <tr>
1897 </tr>
1899 <tr>
1911 </tr>
1913 <tr>
1925 </tr>
1927 <tr>
1939 </tr>
1941 <tr>
1953 </tr>
1955 <tr>
1967 </tr>
1969 <tr>
1981 </tr>
1983 <tr>
1995 </tr>
1996 </tbody>
1997 </table>
2002 called. It takes <code>VISIBLE_SLOP</code> and <code>VISIBLE_STRICT</code> flags for the policy
2009 The horizontal scroll bar is only displayed if it is needed for the assumed width.
2010 If you never wish to see it, call
2013 when needed.</p>
2018 By default, the vertical scroll bar is always displayed when required. You can choose to hide
2025 view. A value of 0 is the normal position with the first text column visible at the left of the
2026 view.</p>
2032 For performance, Scintilla does not measure the display width of the document to determine
2033 the properties of the horizontal scroll bar. Instead, an assumed width is used.
2034 These messages set and get the document width in pixels assumed by Scintilla.
2035 The default value is 2000.
2036 To ensure the width of the currently visible lines can be scrolled use
2037 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING"><code>SCI_SETSCROLLWIDTHTRACKING</code></a></p>
2041 If scroll width tracking is enabled then the scroll width is adjusted to ensure that all of the lines currently
2042 displayed can be completely scrolled. This mode never adjusts the scroll width to be narrower.</p>
2048 scrolling one page below the last line.</p>
2054 useWhitespaceForeColour, int colour)</a><br />
2056 useWhitespaceBackColour, int colour)</a><br />
2058 size)</a><br />
2064 </code>
2068 White space can be made visible which may be useful for languages in which white space is
2069 significant, such as Python. Space characters appear as small centred dots and tab characters
2070 as light arrows pointing to the right. There are also ways to control the display of <a
2076 <tr>
2081 <td>The normal display mode with white space displayed as an empty background
2082 colour.</td>
2083 </tr>
2085 <tr>
2091 </tr>
2093 <tr>
2098 <td>White space used for indentation is displayed normally but after the first visible
2099 character, it is shown as dots and arrows.</td>
2100 </tr>
2101 </tbody>
2102 </table>
2110 By default, the colour of visible white space is determined by the lexer in use. The
2111 foreground and/or background colour of all visible white space can be set globally, overriding
2119 </p>
2121 <p>
2126 Text is drawn with the base of each character on a 'baseline'. The height of a line is found from the maximum
2127 that any style extends above the baseline (its 'ascent'), added to the maximum that any style extends below the
2128 baseline (its 'descent').
2131 This may done to make the text easier to read or to accomodate underlines or highlights.
2132 </p>
2138 The cursor is normally chosen in a context sensitive way, so it will be different over the
2139 margin than when over the text. When performing a slow action, you may wish to change to a wait
2141 argument can be:</p>
2145 <tr>
2151 </tr>
2153 <tr>
2158 <td>The wait cursor is displayed when the mouse is over or owned by the Scintilla
2159 window.</td>
2160 </tr>
2161 </tbody>
2162 </table>
2173 When the mouse is pressed inside Scintilla, it is captured so future mouse movement events are
2174 sent to Scintilla. This behavior may be turned off with
2179 <p>Scintilla can interpret any of the three major line end conventions, Macintosh (\r), Unix
2180 (\n) and CP/M / DOS / Windows (\r\n). When the user presses the Enter key, one of these line
2181 end strings is inserted into the buffer. The default is \r\n in Windows and \n in Unix, but
2190 </code>
2195 presses the Enter key. You can set <code>eolMode</code> to one of <code>SC_EOL_CRLF</code> (0),
2197 message retrieves the current state.</p>
2200 This message changes all the end of line characters in the document to match
2210 returns the current state.</p>
2214 <p>The styling messages allow you to assign styles to text. The standard Scintilla settings
2219 href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a>. If your styling needs can be met by
2220 one of the standard lexers, or if you can write your own, then a lexer is probably the easiest
2221 way to style your document. If you choose to use the container to do the styling you can use
2226 alternative, you might use idle time to style the document. Even if you use a lexer, you might
2227 use the styling commands to mark errors detected by a compiler. The following commands can be
2228 used.</p>
2233 *styles)</a><br />
2237 </code>
2240 Scintilla keeps a record of the last character that is likely to be styled correctly. This is
2241 moved forwards when characters after it are styled and moved backwards if changes are made to
2242 the text of the document before it. Before drawing text, this position is checked to see if any
2246 start styling. Scintilla will always ask to style whole lines.</p>
2251 to occur over several passes, with, for example, basic styling done on an initial pass to
2252 ensure that the text of the code is seen quickly and correctly, and then a second slower pass,
2253 detecting syntax errors and using indicators to show where these are. For example, with the
2254 standard settings of 5 style bits and 3 indicator bits, you would use a <code>mask</code> value
2257 lexical entity to style.</p>
2264 mask);</code><br />
2265 </p>
2272 not contain any bits not set in mask.</p>
2276 As well as the 8 bits of lexical state stored for each character there is also an integer
2277 stored for each line. This can be used for longer lived parse states such as what the current
2280 Changing the value produces a <a class="message" href="#SC_MOD_CHANGELINESTATE">SC_MOD_CHANGELINESTATE</a> notification.
2281 </p>
2284 This returns the last line that has any line state.</p>
2288 <p>While the style setting messages mentioned above change the style numbers associated with
2289 text, these messages define how those style numbers are interpreted visually. There are 256
2291 class="message" href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> to change the number
2294 defined.</p>
2298 <tr>
2303 <td>This style defines the attributes that all styles receive when the
2305 </tr>
2307 <tr>
2312 <td>This style sets the attributes of the text used to display line numbers in a line
2313 number margin. The background colour set for this style also sets the background colour
2314 for all margins that do not have any folding mask bits set. That is, any margin for which
2317 </tr>
2319 <tr>
2328 </tr>
2330 <tr>
2335 <td>This style sets the display attributes used when marking an unmatched brace with the
2337 message.</td>
2338 </tr>
2340 <tr>
2345 <td>This style sets the font used when drawing control characters.
2346 Only the font, size, bold, italics, and character set attributes are used and not
2347 the colour attributes. See
2350 </tr>
2352 <tr>
2357 <td>This style sets the foreground and background colours used when drawing the
2358 indentation guides.</td>
2359 </tr>
2361 <tr>
2368 causes call tips to use this style instead. Only the font face name, font size,
2369 foreground and background colours and character set attributes are used.</td>
2370 </tr>
2372 <tr>
2377 <td>To make it easier for client code to discover the range of styles that are
2378 predefined, this is set to the style number of the last predefined style. This is
2380 for one future predefined style.</td>
2381 </tr>
2383 <tr>
2388 <td>This is not a style but is the number of the maximum style that can be set. Styles
2392 </tr>
2393 </tbody>
2394 </table>
2396 <p>For each style you can set the font name, size and use of bold, italic and underline,
2397 foreground and background colour and the character set. You can also choose to hide text with a
2398 given style, display all characters as upper or lower case and fill from the last character on
2399 a line to the end of the line (for embedded languages). There is also an experimental attribute
2400 to make text read-only.</p>
2402 <p>It is entirely up to you how you use styles. If you want to use syntax colouring you might
2408 *fontName)</a><br />
2409 <a class="message" href="#SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName)</a><br />
2411 sizeInPoints)</a><br />
2413 <a class="message" href="#SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int
2414 sizeInHundredthPoints)</a><br />
2415 <a class="message" href="#SCI_STYLEGETSIZEFRACTIONAL">SCI_STYLEGETSIZEFRACTIONAL(int styleNumber)</a><br />
2417 bold)</a><br />
2420 weight)</a><br />
2423 italic)</a><br />
2426 underline)</a><br />
2427 <a class="message" href="#SCI_STYLEGETUNDERLINE">SCI_STYLEGETUNDERLINE(int styleNumber)</a><br />
2429 colour)</a><br />
2432 colour)</a><br />
2435 eolFilled)</a><br />
2436 <a class="message" href="#SCI_STYLEGETEOLFILLED">SCI_STYLEGETEOLFILLED(int styleNumber)</a><br />
2438 int charSet)</a><br />
2439 <a class="message" href="#SCI_STYLEGETCHARACTERSET">SCI_STYLEGETCHARACTERSET(int styleNumber)</a><br />
2441 caseMode)</a><br />
2444 visible)</a><br />
2447 changeable)</a><br />
2448 <a class="message" href="#SCI_STYLEGETCHANGEABLE">SCI_STYLEGETCHANGEABLE(int styleNumber)</a><br />
2450 hotspot)</a><br />
2452 </code>
2456 initialised.</p>
2460 are setting up Scintilla for syntax colouring, it is likely that the lexical styles you set
2461 will be very similar. One way to set the styles is to:<br />
2470 <b id="SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int sizeInHundredthPoints)</b><br />
2480 attributes that are used to match the fonts you request to those available. The
2482 only the first 32 characters of the name are used and the name is not case sensitive. For
2483 internal caching, Scintilla tracks fonts by name and does care about the casing of font names,
2484 so please be consistent. On GTK+, Pango is used to display text.</p>
2486 or to a fractional point size in hundredths of a point with <code>SCI_STYLESETSIZEFRACTIONAL</code>
2488 For example, a text size of 9.4 points is set with <code>SCI_STYLESETSIZEFRACTIONAL(<style>, 940)</code>.
2489 </p>
2491 or <code>SCI_STYLESETWEIGHT</code>. The weight is a number between 1 and 999 with 1 being very light
2492 and 999 very heavy. While any value can be used, fonts often only support between 2 and 4 weights with three weights
2493 being common enough to have symbolic names:
2497 The <code>SCI_STYLESETBOLD</code> message takes a boolean argument with 0 choosing <code>SC_WEIGHT_NORMAL</code>
2499 </p>
2502 underline)</b><br />
2504 You can set a style to be underlined. The underline is drawn in the foreground colour. All
2505 characters with a style that includes the underline attribute are underlined, even if they are
2506 white space.</p>
2514 Text is drawn in the foreground colour. The space in each character cell that is not occupied
2515 by the character is drawn in the background colour.</p>
2518 eolFilled)</b><br />
2520 If the last character in the line has a style with this attribute set, the remainder of the
2521 line up to the right edge of the window is filled with the background colour set for the last
2522 character. This is useful when a document contains embedded sections in another language such
2524 and a consistent background colour (different from the background colour set for the HTML
2525 styles) to all JavaScript styles then JavaScript sections will be easily distinguished from
2526 HTML.</p>
2529 charSet)</b><br />
2531 You can set a style to use a different character set than the default. The places where such
2532 characters sets are likely to be useful are comments and literal strings. For example,
2534 strings in Russian would display correctly in C and C++ (<code>SCE_C_STRING</code> is the style
2535 number used by the C and C++ lexer to display literal strings; it has the value 6). This
2536 feature works differently on Windows and GTK+.</p>
2545 <code>SC_CHARSET_SHIFTJIS</code>, <code>SC_CHARSET_SYMBOL</code>, <code>SC_CHARSET_THAI</code>,
2557 The value of caseMode determines how text is displayed. You can set upper case
2560 displayed.</p>
2564 Text is normally visible. However, you can completely hide it by giving it a style with the
2566 hypertext keywords in HTML or XML.</p>
2569 changeable)</b><br />
2571 This is an experimental and incompletely implemented style attribute. The default setting is
2573 read-only. Currently it only stops the caret from being within not-changeable text and does not
2574 yet stop deleting a range that contains not-changeable text.</p>
2577 hotspot)</b><br />
2579 This style is used to mark ranges of text that can detect mouse clicks.
2580 The cursor changes to a hand over hotspots, and the foreground, and background colours
2581 may change and an underline appear to indicate that these areas are sensitive to clicking.
2582 This may be used to allow hyperlinks to other documents.</p>
2586 <p>The selection is shown by changing the foreground and/or background colours. If one of these
2587 is not set then that attribute is not changed for the selection. The default is to show the
2588 selection by changing the background to light gray and leaving the foreground the same as when
2589 it was not selected. When there is no selection, the current insertion point is marked by the
2590 text caret. This is a vertical line that is normally blinking on and off to attract the users
2591 attention.</p>
2592 <code><a class="message" href="#SCI_SETSELFORE">SCI_SETSELFORE(bool useSelectionForeColour, int colour)</a><br />
2593 <a class="message" href="#SCI_SETSELBACK">SCI_SETSELBACK(bool useSelectionBackColour, int colour)</a><br />
2600 <a class="message" href="#SCI_SETCARETLINEVISIBLE">SCI_SETCARETLINEVISIBLE(bool show)</a><br />
2604 <a class="message" href="#SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int alpha)</a><br />
2612 <a class="message" href="#SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useSetting, int colour)</a><br />
2614 <a class="message" href="#SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useSetting, int colour)</a><br />
2616 <a class="message" href="#SCI_SETHOTSPOTACTIVEUNDERLINE">SCI_SETHOTSPOTACTIVEUNDERLINE(bool underline)</a><br />
2617 <a class="message" href="#SCI_GETHOTSPOTACTIVEUNDERLINE">SCI_GETHOTSPOTACTIVEUNDERLINE</a><br />
2618 <a class="message" href="#SCI_SETHOTSPOTSINGLELINE">SCI_SETHOTSPOTSINGLELINE(bool singleLine)</a><br />
2620 <a class="message" href="#SCI_SETCONTROLCHARSYMBOL">SCI_SETCONTROLCHARSYMBOL(int symbol)</a><br />
2622 <a class="message" href="#SCI_SETCARETSTICKY">SCI_SETCARETSTICKY(int useCaretStickyBehaviour)</a><br />
2625 </code>
2631 You can choose to override the default selection colouring with these two messages. The colour
2634 argument has no effect.</p>
2635 <p><b id="SCI_SETSELALPHA">SCI_SETSELALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2637 The selection can be drawn translucently in the selection background colour by
2638 setting an alpha value.</p>
2642 The selection can be drawn up to the right hand border by setting this property.</p>
2655 <b id="SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2657 You can choose to make the background colour of the line containing the caret different with
2658 these messages. To do this, set the desired background colour with
2662 background colouring has highest priority when a line has markers that would otherwise change
2663 the background colour.
2664 The caret line may also be drawn translucently which allows other background colours to show
2665 through. This is done by setting the alpha (translucency) value by calling
2666 SCI_SETCARETLINEBACKALPHA. When the alpha is not SC_ALPHA_NOALPHA,
2667 the caret line is drawn after all other features so will affect the colour of all other features.
2668 </p>
2673 determines the time in milliseconds that the caret is visible or invisible before changing
2674 state. Setting the period to 0 stops the caret blinking. The default value is 500 milliseconds.
2684 <p>The block character draws most combining and multibyte character sequences successfully,
2685 though some fonts like Thai Fonts (and possibly others) can sometimes appear strange when
2686 the cursor is positioned at these characters, which may result in only drawing a part of the
2687 cursor character sequence. This is most notable on Windows platforms.</p>
2694 1.50), similar to setting the caret style to CARETSTYLE_INVISIBLE (though not interchangable).
2695 This setting only affects the width of the cursor when the cursor style is set to line caret
2696 mode, it does not affect the width for a block caret.</p>
2698 <p><b id="SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useHotSpotForeColour, int <a class="jump"
2701 <b id="SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useHotSpotBackColour, int <a class="jump"
2708 While the cursor hovers over text in a style with the hotspot attribute set,
2709 the default colouring can be modified and an underline drawn with these settings.
2710 Single line mode stops a hotspot from wrapping onto next line.</p>
2714 By default, Scintilla displays control characters (characters with codes less than 32) in a
2718 early days of signaling, though some are still used (LF = Line Feed, BS = Back Space, CR =
2719 Carriage Return, for example).</p>
2721 <p>You can choose to replace these mnemonics by a nominated symbol with an ASCII code in the
2723 as mnemonics. The symbol you set is rendered in the font of the style set for the character.
2730 These messages set, get or toggle the caretSticky setting which controls when the last position
2731 of the caret on the line is saved.</p>
2734 (and all caret position changes) will remember the
2735 caret's new horizontal position when moving to different lines. This is the default.</p>
2737 <p>When set to <code>SC_CARETSTICKY_ON</code> (1), the sticky flag is on, and the only thing which will cause the editor to remember the
2738 horizontal caret position is moving the caret with mouse or keyboard (left/right arrow keys, home/end keys, etc). </p>
2740 <p>When set to <code>SC_CARETSTICKY_WHITESPACE</code> (2), the caret acts like mode 0 (sticky off) except under one
2741 special case; when space or tab characters are inserted. (Including pasting <b>only space/tabs</b> -- undo, redo,
2742 etc. do not exhibit this behavior..).</p>
2744 <p><code>SCI_TOGGLECARETSTICKY</code> switches from <code>SC_CARETSTICKY_ON</code> and <code>SC_CARETSTICKY_WHITESPACE</code>
2745 to <code>SC_CARETSTICKY_OFF</code> and from <code>SC_CARETSTICKY_OFF</code> to <code>SC_CARETSTICKY_ON</code>.</p>
2749 <p>There may be up to five margins to the left of the text display, plus a gap either side of
2750 the text. Each margin can be set to display only symbols, line numbers, or text with <a
2752 Textual margins may also display symbols.
2753 The markers
2755 href="#SCI_SETMARGINMASKN"><code>SCI_SETMARGINMASKN</code></a>. Any markers not associated with
2756 a visible margin will be displayed as changes in background colour in the text. A width in
2757 pixels can be set for each margin. Margins with a zero width are ignored completely. You can
2760 selects a line of text.</p>
2764 is hidden. Margin 1 is set to display non-folding symbols and is given a width of 16 pixels, so
2765 it is visible. Margin 2 is set to display the folding symbols, but is given a width of 0, so it
2766 is hidden. Of course, you can set the margins to be whatever you wish.</p>
2769 <p><img src="styledmargin.png" alt="Styled text margins used to show revision and blame information" /></p>
2772 type)</a><br />
2775 pixelWidth)</a><br />
2778 mask)</a><br />
2781 sensitive)</a><br />
2783 margin)</a><br />
2785 cursor)</a><br />
2787 margin)</a><br />
2789 pixels)</a><br />
2792 pixels)</a><br />
2794 <a class="message" href="#SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</a><br />
2795 <a class="message" href="#SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</a><br />
2798 <a class="message" href="#SCI_MARGINSETSTYLE">SCI_MARGINSETSTYLE(int line, int style)</a><br />
2800 <a class="message" href="#SCI_MARGINSETSTYLES">SCI_MARGINSETSTYLES(int line, char *styles)</a><br />
2801 <a class="message" href="#SCI_MARGINGETSTYLES">SCI_MARGINGETSTYLES(int line, char *styles)</a><br />
2803 <a class="message" href="#SCI_MARGINSETSTYLEOFFSET">SCI_MARGINSETSTYLEOFFSET(int style)</a><br />
2805 <a class="message" href="#SCI_SETMARGINOPTIONS">SCI_SETMARGINOPTIONS(int marginOptions)</a><br />
2807 </code>
2811 These two routines set and get the type of a margin. The margin argument should be 0, 1, 2, 3 or 4.
2816 By convention, margin 0 is used for line numbers and the next two are used for symbols. You can
2818 symbol margins that set their background colour to match the STYLE_DEFAULT background and
2819 foreground colours.</p>
2823 These routines set and get the width of a margin in pixels. A margin with zero width is
2825 is a reasonable guess if you are not sure what would be appropriate. Line number margins widths
2826 should take into account the number of lines in the document and the line number style. You
2829 suitable width.</p>
2834 displayed in a margin that is enabled for symbols. There is a useful constant,
2836 symbols used to denote folding. You can assign a wide range of symbols and colours to each of
2837 the 32 logical symbols, see <a href="#Markers">Markers</a> for more information. If <code>(mask
2843 does not appear in the mask of any margin with a non-zero width, the marker changes the
2844 background colour of the line. For example, suppose you decide to use logical marker 10 to mark
2845 lines with a syntax error and you want to show such lines by changing the background colour.
2847 sure that no symbol margin includes 0x400 in its mask, any line with the marker gets the
2848 background colour changed.</p>
2851 which is the default set by Scintilla.
2854 decimal. Of course, you may need to display all 32 symbols in a margin, in which case use
2858 sensitive)</b><br />
2860 Each of the five margins can be set sensitive or insensitive to mouse clicks. A click in a
2864 selection margins which make it easy to select ranges of lines. By default, all margins are
2865 insensitive.</p>
2868 cursor)</b><br />
2870 A reversed arrow cursor is normally shown over all margins. This may be changed to a normal arrow with
2872 reversed arrow with
2879 These messages set and get the width of the blank margin on both sides of the text in pixels.
2880 The default is to one pixel on each side.</p>
2882 <p><b id="SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</b><br />
2883 <b id="SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</b><br />
2884 These messages allow changing the colour of the fold margin and fold margin highlight.
2885 On Windows the fold margin colour defaults to ::GetSysColor(COLOR_3DFACE) and the fold margin highlight
2886 colour to ::GetSysColor(COLOR_3DHIGHLIGHT).</p>
2888 <p>
2896 Text margins are created with the type SC_MARGIN_TEXT or SC_MARGIN_RTEXT.
2898 The whole of the text margin on a line may be displayed in a particular style with
2902 Setting a text margin will cause a
2904 notification to be sent.
2905 </p>
2906 <p>
2907 Only some style attributes are active in text margins: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
2908 </p>
2909 <p>
2912 Margin styles may be completely separated from standard text styles by setting a style offset. For example,
2914 256 upto 511 so they do not overlap styles set by lexers. Each style number set with <code>SCI_MARGINSETSTYLE</code>
2916 </p>
2917 <p>
2920 Define margin options by enabling appropriate bit flags. At the moment, only one flag is available
2921 <code>SC_MARGINOPTION_SUBLINESELECT</code>=1, which controls how wrapped lines are selected when clicking
2922 on margin in front of them. If <code>SC_MARGINOPTION_SUBLINESELECT</code> is set only sub line of wrapped
2923 line is selected, otherwise whole wrapped line is selected. Margin options are set to
2925 </p>
2929 <p>Annotations are read-only lines of text underneath each line of editable text.
2930 An annotation may consist of multiple lines separated by '\n'.
2931 Annotations can be used to display an assembler version of code for debugging or to show diagnostic messages inline or to
2932 line up different versions of text in a merge tool.</p>
2936 <code>
2937 <a class="message" href="#SCI_ANNOTATIONSETTEXT">SCI_ANNOTATIONSETTEXT(int line, char *text)</a><br />
2938 <a class="message" href="#SCI_ANNOTATIONGETTEXT">SCI_ANNOTATIONGETTEXT(int line, char *text)</a><br />
2939 <a class="message" href="#SCI_ANNOTATIONSETSTYLE">SCI_ANNOTATIONSETSTYLE(int line, int style)</a><br />
2941 <a class="message" href="#SCI_ANNOTATIONSETSTYLES">SCI_ANNOTATIONSETSTYLES(int line, char *styles)</a><br />
2942 <a class="message" href="#SCI_ANNOTATIONGETSTYLES">SCI_ANNOTATIONGETSTYLES(int line, char *styles)</a><br />
2945 <a class="message" href="#SCI_ANNOTATIONSETVISIBLE">SCI_ANNOTATIONSETVISIBLE(int visible)</a><br />
2947 <a class="message" href="#SCI_ANNOTATIONSETSTYLEOFFSET">SCI_ANNOTATIONSETSTYLEOFFSET(int style)</a><br />
2949 </code>
2951 <p>
2962 The whole of the text ANNOTATION on a line may be displayed in a particular style with
2964 <code>SCI_ANNOTATIONSETSTYLES</code> which uses an array of bytes with each byte setting the style
2965 of the corresponding text byte similar to <code>SCI_SETSTYLINGEX</code>. The text must be set first as it
2966 specifies how long the annotation is so how many bytes of styling to read.
2967 Setting an annotation will cause a
2969 notification to be sent.
2970 </p>
2971 <p>
2972 The number of lines annotating a line can be retrieved with <code>SCI_ANNOTATIONGETLINES</code>.
2974 which is equivalent to clearing each line (setting to 0) and then deleting other memory used for this feature.
2975 </p>
2976 <p>
2977 Only some style attributes are active in annotations: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
2978 </p>
2979 <p>
2982 Annotations can be made visible in a view and there is a choice of display style when visible.
2984 argument can be one of:</p>
2988 <tr>
2994 </tr>
2996 <tr>
3002 </tr>
3004 <tr>
3010 </tr>
3011 </tbody>
3012 </table>
3014 <p>
3017 Annotation styles may be completely separated from standard text styles by setting a style offset. For example,
3018 <code>SCI_ANNOTATIONSETSTYLEOFFSET(512)</code> would allow the annotation styles to be numbered from
3019 512 upto 767 so they do not overlap styles set by lexers (or margins if margins offset is 256).
3022 </p>
3026 allowPaletteUse)</a><br />
3040 <a class="message" href="#SCI_SETWORDCHARS">SCI_SETWORDCHARS(<unused>, const char *characters)</a><br />
3041 <a class="message" href="#SCI_GETWORDCHARS">SCI_GETWORDCHARS(<unused>, char *characters)</a><br />
3042 <a class="message" href="#SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</a><br />
3043 <a class="message" href="#SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</a><br />
3044 <a class="message" href="#SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</a><br />
3045 <a class="message" href="#SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</a><br />
3050 </code>
3054 the handle to the Scintilla window you created as your editor.</p>
3056 <p>While we are on the subject of forwarding messages in Windows, the top level window should
3058 collect changes to mouse settings, but could be used for other user interface items in the
3059 future).</p>
3063 These messages turn buffered drawing on or off and report the buffered drawing state. Buffered
3064 drawing draws each line into a bitmap rather than directly to the screen and then copies the
3065 bitmap to the screen. This avoids flickering although it does take longer. The default is for
3066 drawing to be buffered.</p>
3070 Two phase drawing is a better but slower way of drawing text.
3071 In single phase drawing each run of characters in one style is drawn along with its background.
3072 If a character overhangs the end of a run, such as in "<i>V</i>_" where the
3075 cuts it off. Two phase drawing
3076 fixes this by drawing all the backgrounds first and then drawing the text in
3077 transparent mode. Two phase drawing may flicker more than single phase
3078 unless buffered drawing is on. The default is for drawing to be two phase.</p>
3082 The technology property allows choosing between different drawing APIs and options.
3085 can be chosen to use the Direct2D and DirectWrite APIs for higher quality antialiased drawing.
3086 Since Direct2D buffers drawing, Scintilla's buffering can be turned off with
3091 Manage font quality (antialiasing method). Currently, the following values are available on Windows:
3096 <p>In case it is necessary to squeeze more options into this property, only a limited number of bits defined
3101 Scintilla has some support for Japanese, Chinese and Korean DBCS. Use this message with
3102 <code>codePage</code> set to the code page number to set Scintilla to use code page information
3103 to ensure double byte characters are treated as one character rather than two. This also stops
3104 the caret from moving between the two bytes in a double byte character.
3105 Do not use this message to choose between different single byte character sets: it doesn't do that.
3106 Call with
3110 <p>Code page <code>SC_CP_UTF8</code> (65001) sets Scintilla into Unicode mode with the document
3111 treated as a sequence of characters expressed in UTF-8. The text is converted to the platform's
3112 normal Unicode encoding before being drawn by the OS and thus can display Hebrew, Arabic,
3113 Cyrillic, and Han characters. Languages which can use two characters stacked vertically in one
3114 horizontal space, such as Thai, will mostly work but there are some issues where the characters
3115 are drawn separately leading to visual glitches. Bi-directional text is not supported. </p>
3119 although these may require installation of language specific support.</p>
3123 On Windows, character keys are normally handled differently depending on whether Scintilla is a wide
3124 or narrow character window with character messages treated as Unicode when wide and as 8 bit otherwise.
3125 Set this property to always treat as Unicode. This option is needed for Delphi.</p>
3128 Scintilla has several functions that operate on words, which are defined to be contiguous
3129 sequences of characters from a particular set of characters. This message defines which
3130 characters are members of that set. The character sets are set to default values before processing this
3131 function.
3132 For example, if you don't allow '_' in your set of characters
3133 use:<br />
3134 <code>SCI_SETWORDCHARS(0, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")</code>;</p>
3137 This fills the characters parameter with all the characters included in words.
3138 The characters parameter must be large enough to hold all of the characters.
3139 If the characters parameter is 0 then the length that should be allocated
3140 to store the entire set is returned.</p>
3142 <p><b id="SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</b><br />
3143 <b id="SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</b><br />
3144 Similar to <code>SCI_SETWORDCHARS</code>, this message allows the user to define which chars Scintilla considers
3145 as whitespace. Setting the whitespace chars allows the user to fine-tune Scintilla's behaviour doing
3146 such things as moving the cursor to the start or end of a word; for example, by defining punctuation chars
3147 as whitespace, they will be skipped over when the user presses ctrl+left or ctrl+right.
3149 reset the whitespace characters to the default set.
3152 <p><b id="SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</b><br />
3153 <b id="SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</b><br />
3155 allows the user to define which chars Scintilla considers as punctuation.
3159 Use the default sets of word and whitespace characters. This sets whitespace to space, tab and other
3160 characters with codes less than 0x20, with word characters set to alphanumeric and '_'.
3161 </p>
3167 Scintilla can be told to grab the focus with this message. This is needed more on GTK+ where
3168 focus handling is more complicated than on Windows.</p>
3171 that have complex focus requirements such as having their own window that gets the real focus
3172 but with the need to indicate that Scintilla has the logical focus.</p>
3176 pos2)</a><br />
3178 <a class="message" href="#SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</a><br />
3179 <a class="message" href="#SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</a><br />
3181 maxReStyle)</a><br />
3182 </code>
3185 Up to two characters can be highlighted in a 'brace highlighting style', which is defined as
3186 style number <a class="message" href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34).
3187 If you have enabled indent guides, you may also wish to highlight the indent that corresponds
3196 highlight.</p>
3198 <p><b id="#SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</b><br />
3199 Use specified indicator to highlight matching braces instead of changing their style.</p>
3201 <p><b id="#SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</b><br />
3202 Use specified indicator to highlight non matching brace instead of changing its style.</p>
3208 from a closing brace. If the character at position is not a brace character, or a matching
3209 brace cannot be found, the return value is -1. Otherwise, the return value is the position of
3210 the matching brace.</p>
3212 <p>A match only occurs if the style of the matching brace is the same as the starting brace or
3213 the matching brace is beyond the end of styling. Nested braces are handled correctly. The
3215 the length of brace searches.</p>
3219 <p>Indentation (the white space at the start of a line) is often used by programmers to clarify
3220 program structure and in some languages, for example Python, it may be part of the language
3221 syntax. Tabs are normally used in editors to insert a tab character or to pad text with spaces
3222 up to the next tab.</p>
3224 <p>Scintilla can be set to treat tab and backspace in the white space at the start of a line in
3225 a special way: inserting a tab indents the line to the next indent position rather than just
3226 inserting a tab at the current character position and backspace unindents the line rather than
3227 deleting a character. Scintilla can also display indentation guides (vertical lines) to help
3228 you to generate code.</p>
3238 bsUnIndents)</a><br />
3241 indentation)</a><br />
3244 line)</a><br />
3245 <a class="message" href="#SCI_SETINDENTATIONGUIDES">SCI_SETINDENTATIONGUIDES(int indentView)</a><br />
3249 </code>
3260 of tabs and spaces or be based purely on spaces. Set <code>useTabs</code> to <code>false</code>
3261 (0) to create all tabs and indents out of spaces. The default is <code>true</code>. You can use
3263 position taking the width of a tab into account.</p>
3268 0, the indent size is the same as the tab size. There are no limits on indent sizes, but values
3269 less than 0 or large values may have undesirable effects.
3270 </p>
3276 </p>
3278 <p>Inside indentation white space, the tab and backspace keys can be made to indent and
3279 unindent rather than insert a tab character or delete a character with the
3284 The amount of indentation on a line can be discovered and set with
3285 <code>SCI_GETLINEINDENTATION</code> and <code>SCI_SETLINEINDENTATION</code>. The indentation is
3286 measured in character columns, which correspond to the width of space characters.</p>
3289 This returns the position at the end of indentation of a line.</p>
3293 Indentation guides are dotted vertical lines that appear within indentation white space every
3294 indent size columns. They make it easy to see which constructs line up especially when they
3297 foreground and background colour of the indentation guides.</p>
3300 SC_IV_NONE turns the feature off but the other 3 states determine how far the guides appear on
3301 empty lines. </p>
3303 <tbody>
3304 <tr>
3307 </tr>
3309 <tr>
3312 </tr>
3314 <tr>
3316 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3317 next non-empty line.
3318 If the previous non-empty line was a fold header then indentation guides are shown for
3319 one more level of indent than that line. This setting is good for Python.</td>
3320 </tr>
3322 <tr>
3324 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3325 next non-empty line or previous non-empty line whichever is the greater.
3326 This setting is good for most languages.</td>
3327 </tr>
3329 </tbody>
3330 </table>
3334 When brace highlighting occurs, the indentation guide corresponding to the braces may be
3336 href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34). Set <code>column</code> to 0 to
3337 cancel this highlight.</p>
3341 <p>There are 32 markers, numbered 0 to <code>MARKER_MAX</code> (31), and you can assign any combination of them to each
3343 margin</a> to the left of the text. If the selection margin is set to zero width, the
3349 or the current point of execution, break points, or whatever you need marking. If you do not
3352 <p>Each marker number has a symbol associated with it. You can also set the foreground and
3353 background colour for each marker number, so you can use the same symbol more than once with
3354 different colouring for different uses. Scintilla has a set of symbols you can assign
3358 <p>The markers are drawn in the order of their numbers, so higher numbered markers appear on
3359 top of lower numbered ones. Markers try to move with their text by tracking where the start of
3361 operation, with the markers of the previous line.</p>
3363 markerSymbols)</a><br />
3365 const char *xpm)</a><br />
3368 <a class="message" href="#SCI_RGBAIMAGESETSCALE">SCI_RGBAIMAGESETSCALE(int scalePercent)</a><br />
3369 <a class="message" href="#SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber,
3370 const char *pixels)</a><br />
3372 </a><br />
3374 colour)</a><br />
3376 colour)</a><br />
3377 <a class="message" href="#SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int
3378 colour)</a><br />
3379 <a class="message" href="#SCI_MARKERENABLEHIGHLIGHT">SCI_MARKERENABLEHIGHLIGHT(int enabled)</a><br />
3381 alpha)</a><br />
3383 <a class="message" href="#SCI_MARKERADDSET">SCI_MARKERADDSET(int line, int markerMask)</a><br />
3385 markerNumber)</a><br />
3389 markerMask)</a><br />
3391 markerMask)</a><br />
3393 handle)</a><br />
3395 </code>
3399 an ASCII character. The general-purpose marker symbols currently available are:<br />
3408 The <code>SC_MARK_FULLRECT</code> symbol mirrors this, changing only the margin background colour.
3411 of lines. You would also use it if you changed the folding style and wanted one or more of the
3415 plugins may allocate that marker number.
3416 </p>
3418 <p>There are also marker symbols designed for use in the folding margin in a flattened tree
3419 style.<br />
3426 Characters can be used as markers by adding the ASCII value of the character to
3431 <p>The marker numbers <code>SC_MARKNUM_FOLDER</code> and <code>SC_MARKNUM_FOLDEROPEN</code> are
3432 used for showing that a fold is present and open or closed. Any symbols may be assigned for
3435 these two, more assignments are needed for the flattened tree style:
3444 Macintosh), plus/minus shows folded lines as '+' and opened folds as '-', Circle tree, Box
3445 tree.</p>
3449 <tr>
3459 </tr>
3460 </thead>
3463 <tr>
3473 </tr>
3475 <tr>
3485 </tr>
3487 <tr>
3497 </tr>
3499 <tr>
3509 </tr>
3511 <tr>
3521 </tr>
3523 <tr>
3533 </tr>
3535 <tr>
3545 </tr>
3546 </tbody>
3547 </table>
3550 *xpm)</b><br />
3551 Markers can be set to pixmaps with this message. The
3555 <p>
3559 <b id="SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber, const char *pixels)</b><br />
3560 Markers can be set to translucent pixmaps with this message. The
3564 <p>A scale factor in percent may be set with <code>SCI_RGBAIMAGESETSCALE</code>. This is useful on OS X with
3565 a retina display where each display unit is 2 pixels: use a factor of 200 so that each image pixel is dsplayed using a screen pixel.
3566 The default scale, 100, will stretch each image pixel to cover 4 screen pixels on a retina display.</p>
3578 These two messages set the foreground and background colour of a marker number.<br />
3579 <b id="SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int <a class="jump"
3581 This message sets the highlight background colour of a marker number when its folding block is selected. The default colour is #FF0000.</p>
3583 This message allows to enable/disable the highlight folding block when it is selected. (i.e. block that contains the caret)</p>
3586 When markers are drawn in the content area, either because there is no margin for them or
3587 they are of <code>SC_MARK_BACKGROUND</code> or <code>SC_MARK_UNDERLINE</code> types, they may be drawn translucently by
3588 setting an alpha value.</p>
3592 this fails (illegal line number, out of memory) or it returns a marker handle number that
3597 based on its handle. The message does not check the value of markerNumber, nor does it
3598 check if the line already contains the marker.</p>
3601 This message can add one or more markers to a line with a single call, specified in the same "one-bit-per-marker" 32-bit integer format returned by
3603 (and used by the mask-based marker search functions
3606 As with
3608 to see if any of the markers are already present on the targeted line.</p>
3611 This searches the given line number for the given marker number and deletes it if it is
3612 present. If you added the same marker more than once to the line, this will delete one copy
3613 each time it is used. If you pass in a marker number of -1, all markers are deleted from the
3614 line.</p>
3617 This removes markers of the given number from all lines. If markerNumber is -1, it deletes all
3618 markers from all lines.</p>
3626 These messages search efficiently for lines that include a given set of markers. The search
3629 (<code>SCI_MARKERPREVIOUS</code>). The <code>markerMask</code> argument should have one bit set
3630 for each marker you wish to find. Set bit 0 to find marker 0, bit 1 for marker 1 and so on. The
3631 message returns the line number of the first line that contains one of the markers in
3637 the document for the marker with this handle and returns the line number that contains it or -1
3638 if it is not found.</p>
3643 the document for the marker with this handle and deletes the marker if it is found.</p>
3647 <p>Indicators are used to display additional information over the top of styling.
3648 They can be used to show, for example, syntax errors, deprecated names and bad indentation
3649 by drawing underlines under text or boxes around text. Originally, Scintilla stored indicator information in
3650 the style bytes but this has proved limiting, so now up to 32 separately stored indicators may be used.
3651 While style byte indicators currently still work, they will soon be removed so all the bits in each style
3652 byte can be used for lexical states.</p>
3654 <p>Indicators may be displayed as simple underlines, squiggly underlines, a
3655 line of small 'T' shapes, a line of diagonal hatching, a strike-out or a rectangle around the text.</p>
3658 indicators. They all use an <code>indicatorNumber</code> argument in the range 0 to INDIC_MAX(31)
3659 to set the indicator to style. To prevent interference the set of indicators is divided up into a range for use
3664 indicatorStyle)</a><br />
3667 colour)</a><br />
3669 <a class="message" href="#SCI_INDICSETALPHA">SCI_INDICSETALPHA(int indicatorNumber, int alpha)</a><br />
3671 <a class="message" href="#SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</a><br />
3672 <a class="message" href="#SCI_INDICGETOUTLINEALPHA">SCI_INDICGETOUTLINEALPHA(int indicatorNumber)</a><br />
3673 <a class="message" href="#SCI_INDICSETUNDER">SCI_INDICSETUNDER(int indicatorNumber, bool under)</a><br />
3675 </code>
3678 indicatorStyle)</b><br />
3680 These two messages set and get the style for a particular indicator. The indicator styles
3681 currently available are:</p>
3684 <tbody>
3685 <tr>
3691 </tr>
3692 </tbody>
3695 <tr>
3701 </tr>
3703 <tr>
3709 </tr>
3711 <tr>
3717 </tr>
3719 <tr>
3725 </tr>
3727 <tr>
3733 </tr>
3735 <tr>
3741 </tr>
3743 <tr>
3749 </tr>
3751 <tr>
3756 <td>A rectangle with rounded corners around the text using translucent drawing with the
3757 interior usually more transparent than the border. You can use
3760 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
3761 </tr>
3763 <tr>
3768 <td>A rectangle around the text using translucent drawing with the
3769 interior usually more transparent than the border. You can use
3772 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
3773 </tr>
3775 <tr>
3781 </tr>
3783 <tr>
3789 </tr>
3791 <tr>
3797 so will fit under small fonts.</td>
3798 </tr>
3800 <tr>
3805 <td>A dotted rectangle around the text using translucent drawing.
3806 Translucency alternates between the alpha and outline alpha settings with the top-left pixel using the alpha setting.
3809 control the alpha transparency values. The default values are 30 for alpha and 50 for outline alpha.
3810 To avoid excessive memory allocation the maximum width of a dotted box is 4000 pixels.
3811 Not available for OS X Carbon.</td>
3812 </tr>
3814 <tr>
3820 as a series of line segments for performance.
3823 </tr>
3825 </tbody>
3826 </table>
3833 <p><b id="SCI_INDICSETFORE">SCI_INDICSETFORE(int indicatorNumber, int <a class="jump" href="#colour">colour</a>)</b><br />
3835 These two messages set and get the colour used to draw an indicator. The default indicator
3836 colours are equivalent to:<br />
3843 These two messages set and get the alpha transparency used for drawing the
3844 fill colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
3846 </p>
3848 <p><b id="SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</b><br />
3850 These two messages set and get the alpha transparency used for drawing the
3851 outline colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
3853 </p>
3857 These two messages set and get whether an indicator is drawn under text or over(default).
3858 Drawing under text works only for modern indicators when <a class="message" href="#SCI_SETTWOPHASEDRAW">two phase drawing</a>
3859 is enabled.</p>
3863 <p>Modern indicators are stored in a format similar to run length encoding which is efficient in both
3864 speed and storage for sparse information.</p>
3865 <p>An indicator may store different values for each range but currently all values are drawn the same.
3866 In the future, it may be possible to draw different values in different styles.</p>
3867 <p>
3870 These two messages set and get the indicator that will be affected by calls to
3871 <a class="message" href="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE(int position, int fillLength)</a> and
3872 <a class="message" href="#SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</a>.
3873 </p>
3875 <p>
3878 These two messages set and get the value that will be set by calls to
3880 </p>
3882 <p>
3884 <b id="SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</b><br />
3885 These two messages fill or clear a range for the current indicator.
3887 the current value.
3888 </p>
3890 <p>
3892 Retrieve a bitmap value representing which indicators are non-zero at a position.
3893 </p>
3895 <p>
3897 Retrieve the value of a particular indicator at a position.
3898 </p>
3900 <p>
3903 Find the start or end of a range with one value from a position within the range.
3904 Can be used to iterate through the document to discover all the indicator positions.
3905 </p>
3909 <p>On OS X search matches are highlighted with an animated gold rounded rectangle.
3910 The indicator shows, then briefly grows 25% and shrinks to the original size to draw the user's attention.
3911 While this feature is currently only implemented on OS X, it may be implemented on other platforms
3912 in the future.</p>
3916 These two messages show and animate the find indicator. The indicator remains visible with
3919 <code>SCI_FINDINDICATORSHOW</code> behaves similarly to the OS X TextEdit and Safari applications
3920 and is best suited to editing documentation where the search target is often a word.
3922 where the match will often be located next to operators which would otherwise be hidden under the indicator's
3923 padding.
3924 </p>
3927 This message hides the find indicator.
3928 </p>
3933 indicators so that, for example, syntax errors, deprecated names and bad indentation could all
3934 be displayed at once.</p>
3937 href="#SCI_STARTSTYLING"><code>SCI_STARTSTYLING</code></a> with a <code>INDICS_MASK</code> mask
3941 <p>If you are using indicators in a buffer that has a lexer active
3943 you must save lexing state information before setting any indicators and restore it afterwards.
3945 to retrieve the current "styled to" position and
3947 to reset the styling position and mask (<code>0x1f </code> in the default layout of 5 style bits and 3 indicator bits)
3948 when you are done.</p>
3951 href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> from 0 to 8 bits. The remaining bits
3954 styling information and 3 indicators. If you use a different arrangement, you must define your
3955 own constants.</p>
3960 <p>Autocompletion displays a list box showing likely identifiers based upon the user's typing.
3961 The user chooses the currently selected item by pressing the tab character or another character
3963 Autocompletion is triggered by your application. For example, in C if you detect that the user
3965 list of members, you could offer them in an autocompletion list. Alternatively, you could
3966 monitor the user's typing and offer a list of likely items once their typing has narrowed down
3967 the choice to a reasonable list. As yet another alternative, you could define a key code to
3968 activate the list.</p>
3970 <p>When the user makes a selection from the list the container is sent a <code><a class="message"
3972 href="#Notifications">notification message</a>. On return from the notification Scintilla will insert
3973 the selected text unless the autocompletion list has been cancelled, for example by the container sending
3976 <p>To make use of autocompletion you must monitor each character added to the document. See
3979 *list)</a><br />
3985 *chars)</a><br />
3987 separator)</a><br />
3990 *select)</a><br />
3993 char *text)</a><br />
3995 cancel)</a><br />
3998 *chars)</a><br />
4000 chooseSingle)</a><br />
4003 ignoreCase)</a><br />
4005 <a class="message" href="#SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</a><br>
4006 <a class="message" href="#SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR</a><br>
4010 dropRestOfWord)</a><br />
4012 <a class="message" href="#SCI_REGISTERIMAGE">SCI_REGISTERIMAGE(int type, const char *xpmData)</a><br />
4013 <a class="message" href="#SCI_REGISTERRGBAIMAGE">SCI_REGISTERRGBAIMAGE(int type, const char *pixels)</a><br />
4015 <a class="message" href="#SCI_AUTOCSETTYPESEPARATOR">SCI_AUTOCSETTYPESEPARATOR(char separatorCharacter)</a><br />
4019 <a class="message" href="#SCI_AUTOCSETMAXWIDTH">SCI_AUTOCSETMAXWIDTH(int characterCount)</a><br />
4021 </code>
4026 separator characters. The initial separator character is a space but this can be set or got
4031 <p>The list of words should be in sorted order. If set to ignore case mode with <a class="message" href="#SCI_AUTOCSETIGNORECASE"><code>SCI_AUTOCSETIGNORECASE</code></a>, then
4032 strings are matched after being converted to upper case. One result of this is that the list
4033 should be sorted with the punctuation characters '[', '\', ']', '^', '_', and '`' sorted after
4034 letters.</p>
4037 This message cancels any displayed autocompletion list. When in autocompletion mode, the list
4038 should disappear when the user types a character that can not be part of the autocompletion,
4039 such as '.', '(' or '[' when typing an identifier. A set of characters that will cancel
4044 This message returns non-zero if there is an active autocompletion list and zero if there is
4045 not.</p>
4049 of the list.</p>
4052 This message triggers autocompletion. This has the same effect as the tab key.</p>
4056 automatically cancel the autocompletion list. When you start the editor, this list is
4057 empty.</p>
4061 These two messages set and get the separator character used to separate words in the
4066 This message selects an item in the autocompletion list. It searches the list of words for the
4067 first that matches <code>select</code>. By default, comparisons are case sensitive, but you can
4072 item is found, it is selected. If the item is not found, the autocompletion list closes if
4077 <p><b id="SCI_AUTOCGETCURRENTTEXT">SCI_AUTOCGETCURRENTTEXT(<unused>, char *text)</b><br />
4078 This message retrieves the current selected text in the autocompletion list. Normally the
4080 is used instead.</p>
4082 <p>The value is copied to the <code>text</code> buffer, returning the length (not including the
4090 The default behavior is for the list to be cancelled if the caret moves to the location it
4091 was at when the list was displayed. By calling this message with a <code>false</code> argument,
4092 the list is not cancelled until the caret moves at least one character before the word being
4093 completed.</p>
4095 <p><b id="SCI_AUTOCSETFILLUPS">SCI_AUTOCSETFILLUPS(<unused>, const char *chars)</b><br />
4096 If a fillup character is typed with an autocompletion list active, the currently selected item
4097 in the list is added into the document, then the fillup character is added. Common fillup
4098 characters are '(', '[' and '.' but others are possible depending on the language. By default,
4099 no fillup characters are set.</p>
4104 automatically added and no list is displayed. The default is to display the list even if there
4105 is only a single item.</p>
4109 By default, matching of characters to list members is case sensitive. These messages let you
4110 set and get case sensitivity.</p>
4112 <p><b id="SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</b><br>
4114 When autocompletion is set to ignore case (<code>SCI_AUTOCSETIGNORECASE</code>), by default it will
4115 nonetheless select the first list member that matches in a case sensitive way to entered characters.
4116 This corresponds to a behaviour property of <code>SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE</code> (0).
4117 If you want autocompletion to ignore case at all, choose <code>SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE</code> (1).</p>
4121 By default, the list is cancelled if there are no viable matches (the user has typed
4122 characters that no longer match a list entry). If you want to keep displaying the original
4126 <p><b id="SCI_AUTOCSETDROPRESTOFWORD">SCI_AUTOCSETDROPRESTOFWORD(bool dropRestOfWord)</b><br />
4128 When an item is selected, any word characters following the caret are first erased if
4131 <p>
4138 Autocompletion list items may display an image as well as text. Each image is first registered with an integer
4139 type. Then this integer is included in the text of the list separated by a '?' from the text. For example,
4141 The images are in either the <a class="jump" href="#XPM">XPM format</a> (<code>SCI_REGISTERIMAGE</code>) or
4144 the <a class="message" href="#SCI_RGBAIMAGESETWIDTH"><code>SCI_RGBAIMAGESETWIDTH</code></a> and
4145 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.
4146 The set of registered images can be cleared with <code>SCI_CLEARREGISTEREDIMAGES</code> and the '?' separator changed
4148 </p>
4150 <p>
4154 Get or set the maximum number of rows that will be visible in an autocompletion list. If there are more rows in the list, then a vertical
4155 scrollbar is shown. The default is 5.
4156 </p>
4158 <p>
4162 Get or set the maximum width of an autocompletion list expressed as the number of characters in the longest item that will be totally visible.
4163 If zero (the default) then the list's width is calculated to fit the item with the most characters. Any items that cannot be fully displayed within
4164 the available width are indicated by the presence of ellipsis.
4165 </p>
4169 <p>User lists use the same internal mechanisms as autocompletion lists, and all the calls
4170 listed for autocompletion work on them; you cannot display a user list at the same time as an
4171 autocompletion list is active. They differ in the following respects:</p>
4175 effect.<br />
4181 <p>BEWARE: if you have set fillup characters or stop characters, these will still be active
4182 with the user list, and may result in items being selected or the user list cancelled due to
4183 the user typing into the editor.</p>
4188 structure. It must be greater than 0 as this is how Scintilla tells the difference between an
4189 autocompletion list and a user list. If you have different types of list, for example a list of
4191 a selection. </p>
4195 <p>Call tips are small windows displaying the arguments to a function and are displayed after
4196 the user has typed the name of the function. They normally display characters using the font
4197 facename, size and character set defined by
4200 facename, size, foreground and background colours and character set with
4202 This also enables support for Tab characters.
4204 There is some interaction between call tips and autocompletion lists in that showing a
4205 call tip cancels any active autocompletion list, and vice versa.</p>
4207 <p>Call tips can highlight part of the text within them. You could use this to highlight the
4208 current argument to a function by counting the number of commas (or whatever separator your
4210 example of call tip use.</p>
4212 <p>The mouse may be clicked on call tips and this causes a
4214 notification to be sent to the container. Small up and down arrows may be displayed within
4216 for showing that there are overloaded variants of one function name and that the user can
4217 click on the arrows to cycle through the overloads.</p>
4219 <p>Alternatively, call tips can be displayed when you leave the mouse pointer for a while over
4224 the value of a variable, or during editing to give information about the word under the
4225 pointer.</p>
4227 *definition)</a><br />
4232 highlightEnd)</a><br />
4238 </code>
4241 This message starts the process by displaying the call tip window. If a call tip is already
4242 active, this has no effect.<br />
4244 tip text is aligned to start 1 line below this character unless you have included up and/or
4245 down arrows in the call tip text in which case the tip is aligned to the right-hand edge of
4246 the rightmost arrow. The assumption is that you will start the text with something like
4249 '\n' (Line Feed, ASCII code 10) characters. Do not include '\r' (Carriage Return, ASCII
4251 supported if you set a tabsize with
4255 This message cancels any displayed call tip. Scintilla will also cancel call tips for you if
4256 you use any keyboard commands that are not compatible with editing the argument list of a
4257 function.</p>
4264 started to display the tip.</p>
4267 This sets the region of the call tips text to display in a highlighted style.
4270 <code>hlEnd</code> must be greater than <code>hlStart</code>; <code>hlEnd-hlStart</code> is the
4271 number of characters to highlight. Highlights can extend over line ends if this is
4272 required.</p>
4274 <p>Unhighlighted text is drawn in a mid gray. Selected text is drawn in a dark blue. The
4275 background is white. These can be changed with
4279 </p>
4282 The background colour of call tips can be set with this message; the default colour is white.
4283 It is not a good idea to set a dark colour as the background as the default colour for normal
4284 calltip text is mid gray and the defaultcolour for highlighted text is dark blue. This also
4288 The colour of call tip text can be set with this message; the default colour is mid gray.
4292 The colour of highlighted call tip text can be set with this message; the default colour
4293 is dark blue.</p>
4298 less than 1, Tab characters are not treated specially. Once this call has been used, the
4299 call tip foreground and background colours are also taken from the style.</p>
4308 <p>To allow the container application to perform any of the actions available to the user with
4309 keyboard, all the keyboard actions are messages. They do not take any parameters. These
4314 <tbody>
4315 <tr>
4323 </tr>
4325 <tr>
4333 </tr>
4335 <tr>
4343 </tr>
4345 <tr>
4351 </tr>
4353 <tr>
4359 </tr>
4361 <tr>
4369 </tr>
4371 <tr>
4379 </tr>
4381 <tr>
4389 </tr>
4391 <tr>
4397 </tr>
4399 <tr>
4407 </tr>
4409 <tr>
4415 </tr>
4417 <tr>
4425 </tr>
4427 <tr>
4433 </tr>
4435 <tr>
4443 </tr>
4445 <tr>
4453 </tr>
4455 <tr>
4461 </tr>
4463 <tr>
4469 </tr>
4472 <tr>
4476 </tr>
4478 <tr>
4482 </tr>
4484 <tr>
4488 </tr>
4490 <tr>
4496 </tr>
4498 <tr>
4504 </tr>
4506 <tr>
4514 </tr>
4516 <tr>
4524 </tr>
4526 <tr>
4534 </tr>
4536 <tr>
4541 </tr>
4543 <tr>
4547 </tr>
4549 <tr>
4553 </tr>
4554 </tbody>
4555 </table>
4560 (and convert regular selection to rectangular one, if any).</p>
4563 capitalisation (aCamelCaseIdentifier) or underscores (an_under_bar_ident).</p>
4567 (ie. just after the indentation) unless it is already there; in this case, it acts as SCI_HOME*.</p>
4570 allow movement to the start or end of display lines as opposed to the normal
4575 They go first to the start / end of the display line, like <code>SCI_[HOME|LINEEND]DISPLAY*</code>,
4576 but if the cursor is already at the point, it goes on to the start or end of the document line,
4578 </p>
4581 or end without changing the selection. These commands match OS X platform conventions for the behaviour of the
4584 </p>
4588 <p>There is a default binding of keys to commands that is defined in the Scintilla source in
4592 command that has no arguments can be mapped). You can change the mapping to suit your own
4593 requirements.</p>
4595 sciCommand)</a><br />
4599 </code>
4602 A key definition contains the key code in the low 16-bits and the key modifiers in the high
4604 <br />
4608 enumeration, which contains:<br />
4611 <code>SCK_INSERT</code>, <code>SCK_LEFT</code>, <code>SCK_MENU</code>, <code>SCK_NEXT</code> (Page Down),
4621 If you are building a table, you might
4626 This assigns the given key definition to a Scintilla command identified by
4627 <code>sciCommand</code>. <code>sciCommand</code> can be any <code>SCI_*</code> command that has
4628 no arguments.</p>
4633 to it.</p>
4636 This command removes all keyboard command mapping by setting an empty mapping table.</p>
4640 action. SCI_NULL ensures that keys do not propagate to the parent window as that may
4641 cause focus to move. If you want the standard platform behaviour use the constant 0 instead.</p>
4646 Clicking the wrong button on the mouse pops up a short default editing menu. This may be
4649 Scintilla window will have the opportunity to handle the message.</p>
4653 <p>Start and stop macro recording mode. In macro recording mode, actions are reported to the
4656 record these actions for future replay.</p>
4660 These two messages turn macro recording on and off.</p>
4665 which can include a printer display surface. Printed output shows text styling as on the
4666 screen, but it hides all margins except a line number margin. All special marker effects are
4667 removed and the selection and caret are hidden.</p>
4669 <p>Different platforms use different display surface ID types to print on. On Windows, these are
4674 *pfr)</a><br />
4676 magnification)</a><br />
4682 </code>
4685 This call renders a range of text into a device context. If you use
4686 this for printing, you will probably want to arrange a page header and footer; Scintilla does
4688 example. Each use of this message renders a range of text into a rectangular area and returns
4689 the position in the document of the next character to print.</p>
4692 (for example, if you use this with MFC you will need to paginate in
4694 <pre>
4695 struct Sci_Rectangle { int left; int top; int right; int bottom; };
4697 struct Sci_RangeToFormat {
4698 Sci_SurfaceID hdc; // The Surface ID we print to
4699 Sci_SurfaceID hdcTarget; // The Surface ID we use for measuring (may be same as hdc)
4700 Sci_Rectangle rc; // Rectangle in which to print
4701 Sci_Rectangle rcPage; // Physically printable page size
4702 Sci_CharacterRange chrg; // Range of characters to print
4703 };
4704 </pre>
4706 <p>On Windows, <code>hdc</code> and <code>hdcTarget</code> should both be set to the device context handle
4707 of the output device (usually a printer). If you print to a metafile these will not be the same
4708 as Windows metafiles (unlike extended metafiles) do not implement the full API for returning
4713 rectangle defined by rcPage).<br />
4715 position of characters to output. All of each line within this character range is drawn.</p>
4717 <p>On Cocoa, the surface IDs for printing (<code>bDraw=1</code>) should be the graphics port of the current context
4718 (<code>(CGContextRef) [[NSGraphicsContext currentContext] graphicsPort]</code>) when the view's drawRect method is called.
4720 to a bitmap context (created with <code>CGBitmapContextCreate</code>) to avoid runtime warnings.</p>
4722 <p>On GTK+, the surface IDs to use can be found from the printing context with
4726 position of characters to output. All of each line within this character range is drawn.</p>
4728 <p>When printing, the most tedious part is always working out what the margins should be to
4729 allow for the non-printable area of the paper and printing a header and footer. If you look at
4730 the printing code in SciTE, you will find that most of it is taken up with this. The loop that
4731 causes Scintilla to render text is quite simple if you strip out all the margin, non-printable
4732 area, header and footer code.</p>
4743 These two messages set and get the method used to render coloured text on a printer that is
4744 probably using white paper. It is especially important to consider the treatment of colour if
4745 you use a dark or black screen background. Printing white on black uses up toner and ink very
4746 many times faster than the other way around. You can set the mode to one of:</p>
4749 <tbody>
4750 <tr>
4756 </tr>
4757 </tbody>
4760 <tr>
4766 </tr>
4768 <tr>
4773 <td>If you use a dark screen background this saves ink by inverting the light value of
4774 all colours and printing on a white background.</td>
4775 </tr>
4777 <tr>
4783 </tr>
4785 <tr>
4791 </tr>
4793 <tr>
4798 <td>Everything prints in its own colour on a white background except that line numbers
4799 use their own background colour.</td>
4800 </tr>
4801 </tbody>
4802 </table>
4811 generates one line of output and the line is truncated if it is too long to fit
4812 into the print area.<br />
4814 white space or style changes although if a word is longer than a line, it will be wrapped before
4817 between words.</p>
4823 <a class="message" href="#SCI_GETRANGEPOINTER">SCI_GETRANGEPOINTER(int position, int rangeLength)</a><br />
4825 </code>
4827 <p>On Windows, the message-passing scheme used to communicate between the container and
4828 Scintilla is mediated by the operating system <code>SendMessage</code> function and can lead to
4829 bad performance when calling intensively. To avoid this overhead, Scintilla provides messages
4830 that allow you to call the Scintilla message function directly. The code to do this in C/C++ is
4831 of the form:</p>
4832 <pre>
4833 #include "Scintilla.h"
4837 // now a wrapper to call Scintilla directly
4838 sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
4839 return pSciMsg(pSciWndData, iMessage, wParam, lParam);
4840 }
4841 </pre>
4845 the Scintilla window.</p>
4847 <p>While faster, this direct calling will cause problems if performed from a different thread
4848 to the native thread of the Scintilla window in which case <code>SendMessage(hSciWnd, SCI_*,
4857 pointer.</p>
4860 This message returns the address of the function to call to handle Scintilla messages without
4861 the overhead of passing through the Windows messaging system. You need only call this once,
4862 regardless of the number of Scintilla windows you create.</p>
4865 This returns a pointer to data that identifies which Scintilla window is in use. You must call
4866 this once for each Scintilla window you create. When you call the direct function, you must
4867 pass in the direct pointer associated with the target window.</p>
4872 Grant temporary direct read-only access to the memory used by Scintilla to store
4873 the document.</p>
4875 text of the document is stored consecutively
4876 and ensure there is a NUL character after the text, then returns a pointer to the first character.
4877 Applications may then pass this to a function that accepts a character pointer such as a regular
4878 expression search or a parser. The pointer should <em>not</em> be written to as that may desynchronize
4879 the internal state of Scintilla.</p>
4880 <p>Since any action in Scintilla may change its internal state
4881 this pointer becomes invalid after any call or by allowing user interface activity. The application
4882 should reacquire the pointer after making any call to Scintilla or performing any user-interface calls such
4883 as modifying a progress indicator.</p>
4884 <p>This call takes similar time to inserting a character at the end of the document and this may
4885 include moving the document contents. Specifically, all the characters after the document gap
4886 are moved to before the gap. This compacted state should persist over calls and user interface
4887 actions that do not change the document contents so reacquiring the pointer afterwards is very
4888 quick. If this call is used to implement a global replace operation, then each replacement will
4890 each replacement then the operation will become O(n^2) rather than O(n). Instead, all
4891 matches should be found and remembered, then all the replacements performed.</p>
4894 range requested. The gap is not moved unless it is within the requested range so this call
4896 This can be used by application code that is able to act on blocks of text or ranges of lines.</p>
4900 with a range that contains the gap and consequent costs of moving the gap.</p>
4904 <p>A Scintilla window and the document that it displays are separate entities. When you create
4905 a new window, you also create a new, empty document. Each document has a reference count that
4906 is initially set to 1. The document also has a list of the Scintilla windows that are linked to
4907 it so when any window changes the document, all other windows in which it appears are notified
4908 to cause them to update. The system is arranged in this way so that you can work with many
4909 documents in a single Scintilla window and so you can display a single document in multiple
4910 windows (for use with splitter windows).</p>
4912 <p>Although these messages use <code>document *pDoc</code>, to ensure compatibility with future
4914 is, you can use and store the pointer as described in this section but you should not
4915 dereference it.</p>
4918 *pDoc)</a><br />
4921 *pDoc)</a><br />
4923 *pDoc)</a><br />
4924 </code>
4927 This returns a pointer to the document currently in use by the window. It has no other
4928 effect.</p>
4931 This message does the following:<br />
4937 window.<br />
4941 This message creates a new, empty document and returns a pointer to it. This document is not
4942 selected into the editor and starts with a reference count of 1. This means that you have
4943 ownership of it and must either reduce its reference count by 1 after using
4946 application to avoid memory leaks.</p>
4949 This increases the reference count of a document by 1. If you want to replace the current
4950 document in the Scintilla window and take ownership of the current document, for example if you
4951 are editing many documents in one window, do the following:<br />
4961 must point at a document that still exists. If you call this on a document with a reference
4962 count of 1 that is still attached to a Scintilla window, bad things will happen. To keep the
4968 <p>To ensure a responsive user interface, applications may decide to load and save documents using a separate thread
4969 from the user interface.</p>
4973 <p>An application can load all of a file into a buffer it allocates on a background thread and then add the data in that buffer
4974 into a Scintilla document on the user interface thread. That technique uses extra memory to store a complete copy of the
4975 file and also means that the time that Scintilla takes to perform initial line end discovery blocks the user interface.</p>
4977 <p>To avoid these issues, a loader object may be created and used to load the file. The loader object supports the ILoader interface.</p>
4980 Create an object that supports the <code>ILoader</code> interface which can be used to load data and then
4981 be turned into a Scintilla document object for attachment to a view object.
4982 The <code>bytes</code> argument determines the initial memory allocation for the document as it is more efficient
4983 to allocate once rather than rely on the buffer growing as data is added.
4989 <span class="S5">class</span><span class="S0"> </span>ILoader<span class="S0"> </span><span class="S10">{</span><br />
4991 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>Release<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
4992 <span class="S0"> </span><span class="S2">// Returns a status code from SC_STATUS_*</span><br />
4993 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>AddData<span class="S10">(</span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>data<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>length<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
4994 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span><span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>ConvertToDocument<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
4996 </div>
4998 <p>The application should call the <code>AddData</code> method with each block of data read from the file.
4999 <code>AddData</code> will return SC_STATUS_OK unless a failure, such as memory exhaustion occurs.
5000 If a failure occurs in <code>AddData</code> or in a file reading call then loading can be abandoned and the loader released with
5002 When the whole file has been read, the <code>ConvertToDocument</code> method should be called to produce a Scintilla
5003 document pointer which can be used in the same way as a document pointer returned from
5009 <p>An application that wants to save in the background should lock the document with <code>SCI_SETREADONLY(1)</code>
5010 to prevent modifications and retrieve a pointer to the unified document contents with
5012 The buffer of a locked document will not move so the pointer is valid until the application calls <code>SCI_SETREADONLY(0)</code>.</p>
5014 <p>If the user tries to performs a modification while the document is locked then a <code><a class="message"
5015 href="#SCN_MODIFYATTEMPTRO">SCN_MODIFYATTEMPTRO</a></code> notification is sent to the application.
5016 The application may then decide to ignore the modification or to terminate the background saving thread and reenable
5017 modification before returning from the notification.</p>
5021 <p>The fundamental operation in folding is making lines invisible or visible. Line visibility
5022 is a property of the view rather than the document so each view may be displaying a different
5023 set of lines. From the point of view of the user, lines are hidden and displayed using fold
5024 points. Generally, the fold points of a document are based on the hierarchical structure of the
5025 document contents. In Python, the hierarchy is determined by indentation and in C++ by brace
5026 characters. This hierarchy can be represented within a Scintilla document object by attaching a
5027 numeric "fold level" to each line. The fold level is most easily set by a lexer, but you can
5028 also set it with messages.</p>
5030 <p>It is up to your code to set the connection between user actions and folding and unfolding.
5031 The best way to see how this is done is to search the SciTE source code for the messages used
5032 in this section of the documentation and see how they are used. You will also need to use
5033 markers and a folding margin to complete your folding implementation.
5037 docLine)</a><br />
5039 displayLine)</a><br />
5050 expanded)</a><br />
5052 <a class="message" href="#SCI_CONTRACTEDFOLDNEXT">SCI_CONTRACTEDFOLDNEXT(int lineStart)</a><br />
5056 line)</a><br />
5057 </code>
5060 When some lines are folded, then a particular line in the document may be displayed at a
5061 different position to its document position. If no lines are folded, this message returns
5062 <code>docLine</code>. Otherwise, this returns the display line (counting the very first visible
5063 line as 0). The display line of an invisible line is the same as the previous visible line. The
5064 display line number of the first line in the document is 0. If there is folding and
5066 Lines can occupy more than one display line if they wrap.</p>
5069 When some lines are hidden, then a particular line in the document may be displayed at a
5070 different position to its document position. This message returns the document line number that
5071 corresponds to a display line (counting the display line of the first line in the document as
5074 is the number of lines in the document.</p>
5080 The first two messages mark a range of lines as visible or invisible and then redraw the
5081 display.
5083 visible and 0 if it is not visible.
5085 if some lines are hidden.
5086 These messages have no effect on fold levels or fold
5087 flags. The first line can not be hidden.</p>
5091 These two messages set and get a 32-bit value that contains the fold level of a line and some
5092 flags associated with folding. The fold level is a number in the range 0 to
5095 two addition flag bits. <code>SC_FOLDLEVELWHITEFLAG</code> indicates that the line is blank and
5096 allows it to be treated slightly different then its level may indicate. For example, blank
5097 lines should generally not be fold points and will be considered part of the preceding section even though
5098 they may have a lesser fold level.
5100 the line is a header (fold point).</p>
5103 of a line. Likewise, use <code>SCI_GETFOLDLEVEL(line) & SC_FOLDLEVEL*FLAG</code> to get the
5104 state of the flags. To set the fold level you must or in the associated flags. For instance, to
5109 to handle user folding requests. If you do change the fold levels, the folding margin will
5110 update to match your changes.
5113 In addition to showing markers in the folding margin, you can indicate folds to the user by
5114 drawing lines in the text area. The lines are drawn in the foreground colour set for <a
5117 </p>
5120 <tbody>
5121 <tr>
5125 </tr>
5126 </tbody>
5129 <tr>
5133 </tr>
5135 <tr>
5140 </tr>
5142 <tr>
5147 </tr>
5149 <tr>
5154 </tr>
5156 <tr>
5161 </tr>
5163 <tr>
5168 folding. The appearance of this feature may change in the future.</td>
5169 </tr>
5170 </tbody>
5171 </table>
5181 state.</p>
5190 Each fold point may be either expanded, displaying all its child lines, or contracted, hiding
5191 all the child lines. This message toggles the folding state of the given line as long as it has
5193 all the lines that depend on the line. The display updates after this message.</p>
5197 These messages set and get the expanded state of a single line. The set message has no effect
5198 on the visible state of the line or any lines that depend on it. It does change the markers in
5199 the folding margin. If you ask for the expansion state of a line that is outside the document,
5202 <p>If you just want to toggle the fold state of one line and handle all the lines that are
5209 Search efficiently for lines that are contracted fold headers.
5210 This is useful when saving the user's folding when switching documents or saving folding with a file.
5211 The search starts at line number <code>lineStart</code> and continues forwards to the end of the file.
5212 <code>lineStart</code> is returned if it is a contracted fold header otherwise the next contracted
5217 A line may be hidden because more than one of its parent lines is contracted. Both these
5218 message travels up the fold hierarchy, expanding any contracted folds until they reach the top
5227 <a class="message" href="#SCI_SETWRAPVISUALFLAGS">SCI_SETWRAPVISUALFLAGS(int wrapVisualFlags)</a><br />
5229 <a class="message" href="#SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</a><br />
5230 <a class="message" href="#SCI_GETWRAPVISUALFLAGSLOCATION">SCI_GETWRAPVISUALFLAGSLOCATION</a><br />
5231 <a class="message" href="#SCI_SETWRAPINDENTMODE">SCI_SETWRAPINDENTMODE(int indentMode)</a><br />
5242 </code>
5244 <p>By default, Scintilla does not wrap lines of text. If you enable line wrapping, lines wider
5245 than the window width are continued on the following lines. Lines are broken after space or tab
5246 characters or between runs of different styles. If this is not possible because a word in one
5247 style is wider than the window then the break occurs after the last character that completely
5248 fits on the line. The horizontal scroll bar does not appear when wrap mode is on.</p>
5250 <p>For wrapped lines Scintilla can draw visual flags (little arrows) at end of a a subline of a
5251 wrapped line and at begin of the next subline. These can be enabled individually, but if Scintilla
5252 draws the visual flag at the beginning of the next subline this subline will be indented by one char.
5253 Independent from drawing a visual flag at the begin the subline can have an indention.</p>
5255 <p>Much of the time used by Scintilla is spent on laying out and drawing text. The same text
5256 layout calculations may be performed many times even when the data used in these calculations
5257 does not change. To avoid these unnecessary calculations in some circumstances, the line layout
5258 cache can store the results of the calculations. The cache is invalidated whenever the
5259 underlying data, such as the contents or styling of the document changes. Caching the layout of
5260 the whole document has the most effect, making dynamic line wrap as much as 20 times faster but
5262 line.</p>
5264 <p>Wrapping is not performed immediately there is a change but is delayed until the display
5265 is redrawn. This delay improves peformance by allowing a set of changes to be performed
5266 and then wrapped and displayed once. Because of this, some operations may not occur as
5267 expected. If a file is read and the scroll position moved to a particular line in the text,
5268 such as occurs when a container tries to restore a previous editing session, then
5269 the scroll position will have been determined before wrapping so an unexpected range
5270 of text will be displayed. To scroll to the position correctly, delay the scroll until the
5271 wrapping has been performed by waiting for an initial
5281 between words.</p>
5286 You can enable the drawing of visual flags to indicate a line is wrapped. Bits set in
5287 wrapVisualFlags determine which visual flags are drawn.
5288 </p>
5290 <tbody>
5291 <tr>
5295 </tr>
5296 </tbody>
5299 <tr>
5303 </tr>
5305 <tr>
5309 </tr>
5311 <tr>
5316 </td>
5317 </tr>
5319 <tr>
5323 </tr>
5324 </tbody>
5325 </table>
5327 <p><b id="SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</b><br />
5329 You can set whether the visual flags to indicate a line is wrapped are drawn near the border or near the text.
5330 Bits set in wrapVisualFlagsLocation set the location to near the text for the corresponding visual flag.
5331 </p>
5334 <tbody>
5335 <tr>
5339 </tr>
5340 </tbody>
5343 <tr>
5347 </tr>
5349 <tr>
5353 </tr>
5355 <tr>
5359 </tr>
5360 </tbody>
5361 </table>
5365 Wrapped sublines can be indented to the position of their first subline or one more indent level.
5367 The modes are:
5368 </p>
5371 <tbody>
5372 <tr>
5376 </tr>
5377 </tbody>
5380 <tr>
5383 <td>Wrapped sublines aligned to left of window plus amount set by
5385 </tr>
5387 <tr>
5391 </tr>
5393 <tr>
5396 <td>Wrapped sublines are aligned to first subline indent plus one more level of indentation</td>
5397 </tr>
5398 </tbody>
5399 </table>
5404 wrapped lines in terms of the average character width in
5406 There are no limits on indent sizes, but values less than 0 or large values may have
5407 undesirable effects.<br />
5408 The indention of sublines is independent of visual flags, but if
5410 </p>
5417 <tbody>
5418 <tr>
5424 </tr>
5425 </tbody>
5428 <tr>
5434 </tr>
5436 <tr>
5442 </tr>
5444 <tr>
5450 </tr>
5452 <tr>
5458 </tr>
5459 </tbody>
5460 </table>
5464 The position cache stores position information for short runs of text
5465 so that their layout can be determined more quickly if the run recurs.
5469 Split a range of lines indicated by the target into lines that are at most pixelWidth wide.
5470 Splitting occurs on word boundaries wherever possible in a similar manner to line wrapping.
5472 </p>
5475 Join a range of lines indicated by the target into one line by
5476 removing line end characters.
5477 Where this would lead to no space between words, an extra space is inserted.
5478 </p>
5481 Document lines can occupy more than one display line if they wrap and this
5482 returns the number of display lines needed to wrap a document line.</p>
5487 larger or smaller in steps of one point. The displayed point size never goes below 2, whatever
5493 </code>
5503 These messages let you set and get the zoom factor directly. There is no limit set on the
5504 factors you can set, so limiting yourself to -10 to +20 to match the incremental zoom functions
5505 is a good idea.</p>
5509 <p>You can choose to mark lines that exceed a given length by drawing a vertical line or by
5510 colouring the background of characters that exceed the set length.</p>
5517 </code>
5521 These two messages set and get the mode used to display long lines. You can set one of the
5522 values in the table:</p>
5525 <tbody>
5526 <tr>
5532 </tr>
5533 </tbody>
5536 <tr>
5542 </tr>
5544 <tr>
5550 This works well for monospaced fonts. The line is drawn at a position based on the width
5553 your styles use proportional fonts or if your style have varied font sizes or you use a
5554 mixture of bold, italic and normal text.</td>
5555 </tr>
5557 <tr>
5562 <td>The background colour of characters after the column limit is changed to the colour
5564 </tr>
5565 </tbody>
5566 </table>
5570 These messages set and get the column number at which to display the long line marker. When
5571 drawing lines, the column sets a position in units of the width of a space character in
5572 <code>STYLE_DEFAULT</code>. When setting the background colour, the column is a character count
5573 (allowing for tabs) into the line.</p>
5578 These messages set and get the colour of the marker used to show that a line has exceeded the
5584 called the SciLexer version of Scintilla), lexing support for a wide range of programming
5585 languages is included and the messages in this section are supported. If you want to set
5586 styling and fold points for an unsupported language you can either do this in the container or
5587 better still, write your own lexer following the pattern of one of the existing ones.</p>
5589 <p>Scintilla also supports external lexers. These are DLLs (on Windows) or .so modules (on GTK+/Linux) that export three
5594 <a class="message" href="#SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char
5595 *name)</a><br />
5597 *name)</a><br />
5598 <a class="message" href="#SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char
5599 *path)</a><br />
5601 <a class="message" href="#SCI_CHANGELEXERSTATE">SCI_CHANGELEXERSTATE(int start, int end)</a><br />
5602 <a class="message" href="#SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(<unused>, char *names)</a><br />
5604 <a class="message" href="#SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</a><br />
5605 <a class="message" href="#SCI_SETPROPERTY">SCI_SETPROPERTY(const char *key, const char *value)</a><br />
5606 <a class="message" href="#SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value)</a><br />
5607 <a class="message" href="#SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</a><br />
5608 <a class="message" href="#SCI_GETPROPERTYINT">SCI_GETPROPERTYINT(const char *key, int default)</a><br />
5609 <a class="message" href="#SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</a><br />
5611 *keyWordList)</a><br />
5613 <br />
5614 </code>
5620 <code>SCLEX_NULL</code> to select no lexing action and <code>SCLEX_CONTAINER</code> which sends
5621 the <code><a class="message" href="#SCN_STYLENEEDED">SCN_STYLENEEDED</a></code> notification to
5622 the container whenever a range of text needs to be styled. You cannot use the
5624 assigns unused lexer numbers to.</p>
5626 <p><b id="SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char *name)</b><br />
5628 <code>SCI_SETLEXERLANGUAGE</code> lets you select a lexer by name, and is the only method if you are using an
5629 external lexer or if you have written a lexer module for a language of your own and do not wish
5632 or "Python". To locate the name for the built-in lexers, open the relevant
5638 see if the lexer number changed.</p>
5642 <p><b id="SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char *path)</b><br />
5643 Load a lexer implemented in a shared library. This is a .so file on GTK+/Linux or a .DLL file on Windows.
5644 </p>
5647 This requests the current lexer or the container (if the lexer is set to
5652 message causes a redraw.</p>
5655 Indicate that the internal state of a lexer has changed over a range and therefore
5656 there may be a need to redraw.</p>
5660 <b id="SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</b><br />
5661 Information may be retrieved about the properties that can be set for the current lexer.
5662 This information is only available for newer lexers.
5663 <code>SCI_PROPERTYNAMES</code> returns a string with all of the valid properties separated by "\n".
5664 If the lexer does not support this call then an empty string is returned.
5665 Properties may be boolean (<code>SC_TYPE_BOOLEAN</code>), integer (<code>SC_TYPE_INTEGER</code>),
5670 You can communicate settings to lexers with keyword:value string pairs. There is no limit to
5673 there is already a value string associated with the keyword, it is replaced. If you pass a zero
5676 significant.</p>
5680 <code>"$(fold)0"</code>, but when this is accessed, the <code>$(fold)</code> is replaced by the
5683 <p>Currently the "fold" property is defined for most of the lexers to set the fold structure if
5685 setting that determines how to indicate bad indentation. Most keywords have values that are
5687 properties are used.</p>
5689 <p>There is a convention for naming properties used by lexers so that the set of properties can be found by scripts.
5690 Property names should start with "lexer.<lexer>." or "fold.<lexer>." when they apply to one
5693 <p>Applications may discover the set of properties used by searching the source code of lexers for lines that contain
5694 <code>GetProperty</code> and a double quoted string and extract the value of the double quoted string as the property name.
5696 Documentation for the property may be located above the call as a multi-line comment starting with
5700 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
5701 buffer and return the length (not including the terminating 0). If not found, copy an empty string
5707 <p>If the value argument is 0 then the length that should be allocated to store the value is returned;
5710 <p><b id="SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</b><br />
5711 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
5712 buffer and return the length (not including the terminating 0). If not found, copy an empty string
5718 <p>If the value argument is 0 then the length that should be allocated to store the value (including any indicated keyword replacement)
5722 Lookup a keyword:value pair using the specified key; if found, interpret the value as an integer and return it.
5723 If not found (or the value is an empty string) then return the supplied default. If the keyword:value pair is found but is not
5731 at revision 1.50. <code>keyWordSet</code> can be 0 to 8 (actually 0 to <code>KEYWORDSET_MAX</code>)
5734 It is expected that the keywords will be composed of standard ASCII printing characters,
5736 (except common sense).</p>
5738 <p>How these keywords are used is entirely up to the lexer. Some languages, such as HTML may
5739 contain embedded languages, VBScript and JavaScript are common for HTML. For HTML, key word set
5741 is for SGML and DTD keywords. Review the lexer code to see examples of keyword list. A fully
5743 list of strings that describe the uses of the keyword lists.</p>
5746 indentation and set 2 for keywords that cause unindentation. Yet again, you might have a simple
5747 lexer that colours keywords and you could change languages by changing the keywords in set 0.
5748 There is nothing to stop you building your own keyword lists into the lexer, but this means
5749 that the lexer must be rebuilt if more keywords are added.</p>
5751 <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</b><br />
5752 A description of all of the keyword sets separated by "\n" is returned by <code>SCI_DESCRIBEKEYWORDSETS</code>.</p>
5755 Retrieve the number of bits the current lexer needs for styling. This should normally be the argument
5757 </p>
5761 <p>Lexers are programmed as objects that implement the ILexer interface and that interact
5762 with the document they are lexing through the IDocument interface.
5763 Previously lexers were defined by providing lexing and folding functions but creating an object
5764 to handle the interaction of a lexer with a document allows the lexer to store state information that
5765 can be used during lexing. For example a C++ lexer may store a set of preprocessor definitions
5766 or variable declarations and style these depending on their role.</p>
5768 <p>A set of helper classes allows older lexers defined by functions to be used in Scintilla.</p>
5772 <span class="S5">class</span><span class="S0"> </span>ILexer<span class="S0"> </span><span class="S10">{</span><br />
5782 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5783 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5788 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5790 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>PropertyType<span class="S10">(</span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>name<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5792 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DescribeProperty<span class="S10">(</span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>name<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5799 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>val<span class="S10">)</span>
5802 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5803 <span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>
5804 <span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DescribeWordListSets<span class="S10">()</span>
5812 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>wl<span class="S10">)</span>
5830 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>startPos<span class="S10">,</span>
5845 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5847 </div>
5849 <p>
5850 The return values from PropertySet and WordListSet are used to indicate whether the change requires
5851 performing lexing or folding over any of the document. It is the position at which to restart lexing and folding or -1
5852 if the change does not require any extra work on the document.
5853 A simple approach is to return 0 if there is any possibility that a change requires lexing the document again while an
5854 optimisation could be to remember where a setting first affects the document and return that position.
5855 </p>
5860 application and a lexer. An example would be where an application
5861 maintains a single large data structure containing symbolic information
5862 about system headers (like Windows.h) and provides this to the lexer
5863 where it can be applied to each document. This avoids the costs of
5864 constructing the system header information for each document. This is
5868 Previously, lexers were called with a range that started one line before the range that
5869 needs to be folded as this allowed fixing up the last line from the previous folding.
5870 The new approach allows the lexer to decide whether to backtrack or to handle this
5871 more efficiently.</p>
5913 <span class="S0"> </span>LineFromPosition<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>position<span class="S10">)</span>
5914 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
5916 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5918 <span class="S0"> </span>LineStart<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
5919 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
5921 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5923 <span class="S0"> </span>GetLevel<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
5925 <span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span>
5927 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5945 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>state<span class="S10">)</span>
5952 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>mask<span class="S10">)</span>
5955 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
5959 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>style<span class="S10">)</span>
5960 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span>
5970 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span>
5972 <span class="S0"> </span>DecorationSetCurrentIndicator<span class="S10">(</span><span class="S5">int</span>
5978 <span class="S0"> </span>DecorationFillRange<span class="S10">(</span><span class="S5">int</span>
5980 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>value<span class="S10">,</span>
5981 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>fillLength<span class="S10">)</span>
5989 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>end<span class="S10">)</span>
5998 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
6002 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6005 </div>
6007 <p>Scintilla tries to minimize the consequences of modifying text to
6008 only relex and redraw the line of the change where possible. Lexer
6009 objects contain their own private extra state which can affect later
6010 lines. For example, if the C++ lexer is greying out inactive code
6014 the document that it should relex and display more.</p>
6017 exceptions. Exceptions should not be thrown over build boundaries as the
6018 two sides may be built with different compilers or incompatible
6019 exception options.</p>
6024 implemented and thus which methods may be called.</p>
6028 <p>Notifications are sent (fired) from the Scintilla control to its container when an event has
6029 occurred that may interest the container. Notifications are sent using the
6033 struct NotifyHeader { // This matches the Win32 NMHDR structure
6034 void *hwndFrom; // environment specific window handle/pointer
6035 uptr_t idFrom; // CtrlID of the window issuing the notification
6036 unsigned int code; // The SCN_* notification code
6037 };
6039 struct SCNotification {
6040 struct Sci_NotifyHeader nmhdr;
6041 int position;
6042 /* SCN_STYLENEEDED, SCN_DOUBLECLICK, SCN_MODIFIED, SCN_MARGINCLICK, */
6043 /* SCN_NEEDSHOWN, SCN_DWELLSTART, SCN_DWELLEND, SCN_CALLTIPCLICK, */
6044 /* SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, SCN_HOTSPOTRELEASECLICK, */
6045 /* SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6046 /* SCN_USERLISTSELECTION, SCN_AUTOCSELECTION */
6048 int ch; /* SCN_CHARADDED, SCN_KEY */
6049 int modifiers;
6050 /* SCN_KEY, SCN_DOUBLECLICK, SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, */
6051 /* SCN_HOTSPOTRELEASECLICK, SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6053 int modificationType; /* SCN_MODIFIED */
6054 const char *text;
6055 /* SCN_MODIFIED, SCN_USERLISTSELECTION, SCN_AUTOCSELECTION, SCN_URIDROPPED */
6057 int length; /* SCN_MODIFIED */
6058 int linesAdded; /* SCN_MODIFIED */
6059 int message; /* SCN_MACRORECORD */
6060 uptr_t wParam; /* SCN_MACRORECORD */
6061 sptr_t lParam; /* SCN_MACRORECORD */
6062 int line; /* SCN_MODIFIED */
6063 int foldLevelNow; /* SCN_MODIFIED */
6064 int foldLevelPrev; /* SCN_MODIFIED */
6065 int margin; /* SCN_MARGINCLICK */
6066 int listType; /* SCN_USERLISTSELECTION */
6067 int x; /* SCN_DWELLSTART, SCN_DWELLEND */
6068 int y; /* SCN_DWELLSTART, SCN_DWELLEND */
6069 int token; /* SCN_MODIFIED with SC_MOD_CONTAINER */
6070 int annotationLinesAdded; /* SCN_MODIFIED with SC_MOD_CHANGEANNOTATION */
6071 int updated; /* SCN_UPDATEUI */
6072 };
6073 </pre>
6075 <p>The notification messages that your container can choose to handle and the messages
6076 associated with them are:</p>
6104 </code>
6107 <code><a class="message" href="#SCI_SETMODEVENTMASK">SCI_SETMODEVENTMASK(int eventMask)</a><br />
6109 <a class="message" href="#SCI_SETMOUSEDWELLTIME">SCI_SETMOUSEDWELLTIME(int milliseconds)</a><br />
6113 </code>
6115 <p>The following additional notifications are sent using the <code>WM_COMMAND</code> message on
6116 Windows and the "Command" signal on GTK+. This emulates the Windows Edit control. Only the lower
6121 </code>
6125 These two messages set and get the identifier of the Scintilla instance which is included in notifications as the
6127 When an application creates multiple Scintilla widgets, this allows the source of each notification to be found.
6130 The value should be small, preferrably less than 16 bits,
6132 </p>
6137 lexer, you will receive this notification when Scintilla is about to display or print text that
6138 requires styling. You are required to style the text from the line that contains the position
6139 returned by <a class="message" href="#SCI_GETENDSTYLED"><code>SCI_GETENDSTYLED</code></a> up to
6140 the position passed in <code>SCNotification.position</code>. Symbolically, you need code of the
6141 form:</p>
6142 <pre>
6148 MyStyleRoutine(startPos, SCNotification.position);
6149 </pre>
6152 This is sent when the user types an ordinary text character (as opposed to a command
6153 character) that is entered into the text. The container can use this to decide to display a <a
6156 This notification is sent before the character has been styled so processing that depends on
6157 styling should instead be performed in the SCN_UPDATEUI notification.</p>
6161 Sent to the container when the save point is entered or left, allowing the container to
6167 When in read-only mode, this notification is sent to the container if the user tries to change
6168 the text. This can be used to check the document out of a version control system. You can set
6173 Reports all keys pressed but not consumed by Scintilla. Used on GTK+ because of
6174 some problems with keyboard focus and is not sent by the Windows version. <code>SCNotification.ch</code> holds the key code and
6180 The mouse button was double clicked in editor. The <code>position</code> field is set to the text position of the
6186 Either the text or styling of the document has changed or the selection range or scroll position has changed.
6187 Now would be a good time to update any container UI elements that depend on document or view state.
6188 The <code>updated</code> field is set to the bit set of things changed since the previous notification.</p>
6190 <tbody>
6191 <tr>
6198 </tr>
6199 </tbody>
6202 <tr>
6209 </tr>
6211 <tr>
6218 </tr>
6220 <tr>
6227 </tr>
6229 <tr>
6236 </tr>
6237 </tbody>
6238 </table>
6241 This notification is sent when the text or styling of the document changes or is about to
6242 change. You can set a mask for the notifications that are sent to the container with <a
6244 notification structure contains information about what changed, how the change occurred and
6245 whether this changed the number of lines in the document. No modifications may be performed
6247 are:</p>
6250 <tbody>
6251 <tr>
6255 </tr>
6256 </tbody>
6259 <tr>
6263 table.</td>
6264 </tr>
6266 <tr>
6270 </tr>
6272 <tr>
6277 </tr>
6279 <tr>
6284 </tr>
6286 <tr>
6290 information this holds a pointer to the text that is handed to the Undo system, otherwise
6291 it is zero. For user performed SC_MOD_BEFOREDELETE the text field is 0 and
6292 for user performed SC_MOD_BEFOREINSERT the text field points to an array of cells,
6293 not bytes and the length is the number of cells.</td>
6294 </tr>
6296 <tr>
6301 </tr>
6303 <tr>
6307 unused.</td>
6308 </tr>
6310 <tr>
6314 unused.</td>
6315 </tr>
6316 </tbody>
6317 </table>
6322 Undo or Redo of a previous action.</p>
6325 <tbody>
6326 <tr>
6334 </tr>
6335 </tbody>
6338 <tr>
6346 </tr>
6348 <tr>
6356 </tr>
6358 <tr>
6366 </tr>
6368 <tr>
6376 </tr>
6378 <tr>
6386 </tr>
6388 <tr>
6396 </tr>
6398 <tr>
6406 </tr>
6408 <tr>
6416 </tr>
6418 <tr>
6426 </tr>
6428 <tr>
6436 </tr>
6438 <tr>
6446 </tr>
6448 <tr>
6456 </tr>
6458 <tr>
6466 </tr>
6468 <tr>
6473 <td>A line state has changed because <a class="message" href="#SCI_SETLINESTATE">SCI_SETLINESTATE</a>
6474 was called.</td>
6477 </tr>
6479 <tr>
6487 </tr>
6489 <tr>
6497 </tr>
6499 <tr>
6507 </tr>
6509 <tr>
6517 </tr>
6519 <tr>
6524 <td>This is set on a SC_PERFORMED_USER action when it is the
6525 first or only step in an undo transaction. This can be used to integrate the Scintilla
6526 undo stack with an undo stack in the container application by adding a Scintilla
6527 action to the container's stack for the currently opened container transaction or
6528 to open a new container transaction if there is no open container transaction.
6529 </td>
6532 </tr>
6534 <tr>
6539 <td>This is set on for actions that the container stored into the undo stack with
6541 </td>
6544 </tr>
6546 <tr>
6555 </tr>
6556 </tbody>
6557 </table>
6562 "Command" signal on GTK+ as this is the behavior of the standard Edit control
6571 These messages set and get an event mask that determines which document change events are
6575 only notifications about changes to text and not styling changes by calling
6581 <code>SC_MOD_CHANGEFOLD</code>, <code>SC_PERFORMED_USER</code>, <code>SC_PERFORMED_UNDO</code>,
6592 behavior of the standard Edit control. Unfortunately, these codes do not match the Windows Edit
6594 now too late to change the Scintilla codes as clients depend on the current values.</p>
6599 disable macro recording. When enabled, each time a recordable change occurs, the
6604 notification are:</p>
6607 <tbody>
6608 <tr>
6612 </tr>
6613 </tbody>
6616 <tr>
6620 </tr>
6622 <tr>
6626 </tr>
6628 <tr>
6632 </tr>
6633 </tbody>
6634 </table>
6641 used:</p>
6644 <tbody>
6645 <tr>
6649 </tr>
6650 </tbody>
6653 <tr>
6658 at the time of the margin click.</td>
6659 </tr>
6661 <tr>
6665 to the margin click.</td>
6666 </tr>
6668 <tr>
6672 </tr>
6673 </tbody>
6674 </table>
6677 Scintilla has determined that a range of lines that is currently invisible should be made
6678 visible. An example of where this may be needed is if the end of line of a contracted fold
6679 point is deleted. This message is sent to the container in case it wants to make the line
6680 visible in some unusual way such as making the whole document visible. Most containers will
6684 that should be made visible. The container code will be similar to the following code
6685 skeleton:</p>
6686 <pre>
6687 firstLine = SCI_LINEFROMPOSITION(scn.position)
6688 lastLine = SCI_LINEFROMPOSITION(scn.position+scn.length-1)
6689 for line = lineStart to lineEnd do SCI_ENSUREVISIBLE(line) next
6690 </pre>
6693 Painting has just been done. Useful when you want to update some other widgets based on a
6694 change in Scintilla, but want to have the paint occur first to appear more responsive. There is
6702 <tbody>
6703 <tr>
6707 </tr>
6708 </tbody>
6711 <tr>
6716 initiated the list.</td>
6717 </tr>
6719 <tr>
6723 </tr>
6725 <tr>
6729 </tr>
6730 </tbody>
6731 </table>
6732 <br />
6736 Only on the GTK+ version. Indicates that the user has dragged a URI such as a file name or Web
6737 address onto Scintilla. The container could interpret this as a request to open the file. The
6746 key press indicates the dwell is over. Both notifications set the same fields in
6750 <tbody>
6751 <tr>
6755 </tr>
6756 </tbody>
6759 <tr>
6763 mouse pointer was lingering.</td>
6764 </tr>
6766 <tr>
6772 </tr>
6773 </tbody>
6774 </table>
6775 <br />
6779 These two messages set and get the time the mouse must sit still, in milliseconds, to generate
6784 This notification is generated when the user zooms the display using the keyboard or the
6786 notification can be used to recalculate positions, such as the width of the line number margin
6787 to maintain sizes in terms of characters rather than pixels. <code>SCNotification</code> has no
6788 additional information.</p>
6790 <p>
6794 These notifications are generated when the user clicks or double clicks on
6795 text that is in a style with the hotspot attribute set.
6796 This notification can be used to link to variable definitions or web pages.
6802 <p>
6805 These notifications are generated when the user clicks or releases the mouse on
6806 text that has an indicator.
6812 This notification is generated when the user clicks on a calltip.
6813 This notification can be used to display the next function prototype when a
6814 function name is overloaded with different arguments.
6819 The user has selected an item in an <a class="jump" href="#Autocompletion">autocompletion list</a>. The
6820 notification is sent before the selection is inserted. Automatic insertion can be cancelled by sending a
6825 <tbody>
6826 <tr>
6830 </tr>
6831 </tbody>
6834 <tr>
6838 </tr>
6839 <tr>
6843 </tr>
6844 </tbody>
6845 </table>
6849 There is no other information in SCNotification.</p>
6852 The user deleted a character while autocompletion list was active.
6853 There is no other information in SCNotification.</p>
6857 <p>Two formats are supported for images used in margin markers and autocompletion lists, RGBA and XPM.</p>
6862 value for each pixel. It is simpler than
6865 <p>The data is a sequence of 4 byte pixel values starting with the pixels for the top line, with the
6866 leftmost pixel first, then continuing with the pixels for subsequent lines. There is no gap between
6867 lines for alignment reasons.</p>
6869 <p>Each pixel consists of, in order, a red byte, a green byte, a blue byte and an alpha byte.
6870 The colour bytes are not premultiplied by the alpha value. That is, a fully red pixel that is
6873 <p>Since the RGBA pixel data does not include any size information the
6874 width and height must previously been set with the
6876 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.</p>
6878 <p>GUI platforms often include functions for reading image file formats like PNG into memory
6879 in the RGBA form or a similar form.
6880 If there is no suitable platform support, the <a href="http://lodev.org/lodepng/">LodePNG and picoPNG</a> libraries are small libraries
6881 for loading and decoding PNG files available under a BSD-style license.</p>
6883 <p>RGBA format is supported on Windows, GTK+ and OS X Cocoa.
6884 It is not supported on OS X Carbon.</p>
6888 <p>The XPM format is
6890 Scintilla is only able to handle XPM pixmaps that use one character per pixel with no named colours.
6892 <p>There are two forms of data structure used for XPM images, the first "lines form" format is well suited
6893 to embedding an image inside C source code and the "text form" is suited to reading from a file.
6894 In the lines form, an array of strings is used with the first string indicating the dimensions and number of colours
6895 used. This is followed by a string for each colour and that section is followed by the image with one string per line.
6896 The text form contains the same data as one null terminated block formatted as C source code starting
6898 <p>Either format may be used with Scintilla APIs with the bytes at the location pointed to examined
6899 to determine which format: if the bytes start with "/* XPM */" then it is treated as text form,
6900 otherwise it is treated as lines form.</p>
6905 <p>On GTK+, the following functions create a Scintilla widget, communicate with it and allow
6906 resources to be released after all Scintilla widgets have been destroyed.</p>
6908 <a class="message" href="#scintilla_set_id">void scintilla_set_id(ScintillaObject *sci, uptr_t id)</a><br />
6909 <a class="message" href="#scintilla_send_message">sptr_t scintilla_send_message(ScintillaObject *sci,unsigned int iMessage, uptr_t wParam, sptr_t lParam)</a><br />
6910 <a class="message" href="#scintilla_release_resources">void scintilla_release_resources()</a><br />
6911 </code>
6914 Create a new Scintilla widget. The returned pointer can be added to a container and displayed in the same way as other
6915 widgets.</p>
6918 Set the control ID which will be used in the idFrom field of the NotifyHeader structure of all
6919 notifications for this instance.
6922 <p><b id="scintilla_send_message">sptr_t scintilla_send_message(ScintillaObject *sci,unsigned int iMessage, uptr_t wParam, sptr_t lParam)</b><br />
6923 The main entry point allows sending any of the messages described in this document.</p>
6926 Call this to free any remaining resources after all the Scintilla widgets have been destroyed.</p>
6930 <p>The following messages are currently supported to emulate existing Windows controls, but
6931 they will be removed in future versions of Scintilla. If you use these messages you should
6932 replace them with the Scintilla equivalent.</p>
6933 <pre>
6934 WM_GETTEXT(int length, char *text)
6936 EM_GETLINE(int line, char *text)
6938 EM_SETREADONLY
6940 WM_CUT
6941 WM_COPY
6942 WM_PASTE
6943 WM_CLEAR
6944 WM_UNDO
6945 EM_CANUNDO
6946 EM_EMPTYUNDOBUFFER
6947 WM_GETTEXTLENGTH
6948 EM_GETFIRSTVISIBLELINE
6949 EM_GETLINECOUNT
6950 EM_GETMODIFY
6951 EM_SETMODIFY(bool isModified)
6952 EM_GETRECT(RECT *rect)
6953 EM_GETSEL(int *start, int *end)
6955 EM_SETSEL(int start, int end)
6958 EM_LINEFROMCHAR(int position)
6959 EM_EXLINEFROMCHAR(int position)
6960 EM_LINEINDEX(int line)
6961 EM_LINELENGTH(int position)
6962 EM_SCROLL(int line)
6963 EM_LINESCROLL(int column, int line)
6964 EM_SCROLLCARET()
6965 EM_CANPASTE
6967 EM_POSFROMCHAR(int position, POINT *location)
6968 EM_SELECTIONTYPE
6969 EM_HIDESELECTION(bool hide)
6970 EM_FINDTEXT(int flags, FINDTEXTEX *ft)
6971 EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
6972 EM_GETMARGINS
6973 EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
6974 EM_FORMATRANGE
6975 </pre>
6977 <p>The following are features that are only included if you define
6979 compatibility you should change them as indicated.</p>
6982 This was used to set a DBCS (Double Byte Character Set) mode on GTK+.
6983 An explicit DBCS code page should be used when calling <a class="message" href="#SCI_SETCODEPAGE">SCI_SETCODEPAGE</a></p>
6987 Scintilla no longer supports palette mode. The last version to support palettes was 2.29.
6988 Any calls to these methods should be removed.</p>
6991 <pre>
6992 EM_GETWORDBREAKPROC EM_GETWORDBREAKPROCEX
6993 EM_SETWORDBREAKPROC EM_SETWORDBREAKPROCEX
6994 EM_GETWORDWRAPMODE EM_SETWORDWRAPMODE
6995 EM_LIMITTEXT EM_EXLIMITTEXT
6996 EM_SETRECT EM_SETRECTNP
6997 EM_FMTLINES
6998 EM_GETHANDLE EM_SETHANDLE
6999 EM_GETPASSWORDCHAR EM_SETPASSWORDCHAR
7000 EM_SETTABSTOPS
7001 EM_FINDWORDBREAK
7002 EM_GETCHARFORMAT EM_SETCHARFORMAT
7003 EM_GETOLEINTERFACE EM_SETOLEINTERFACE
7004 EM_SETOLECALLBACK
7005 EM_GETPARAFORMAT EM_SETPARAFORMAT
7006 EM_PASTESPECIAL
7007 EM_REQUESTRESIZE
7008 EM_GETBKGNDCOLOR EM_SETBKGNDCOLOR
7009 EM_STREAMIN EM_STREAMOUT
7010 EM_GETIMECOLOR EM_SETIMECOLOR
7011 EM_GETIMEOPTIONS EM_SETIMEOPTIONS
7012 EM_GETOPTIONS EM_SETOPTIONS
7013 EM_GETPUNCTUATION EM_SETPUNCTUATION
7014 EM_GETTHUMB
7015 EM_GETEVENTMASK
7016 EM_SETEVENTMASK
7017 EM_DISPLAYBAND
7018 EM_SETTARGETDEVICE
7019 </pre>
7021 <p>Scintilla tries to be a superset of the standard windows Edit and RichEdit controls wherever
7022 that makes sense. As it is not intended for use in a word processor, some edit messages can not
7023 be sensibly handled. Unsupported messages have no effect.</p>
7027 <p>To build Scintilla or SciTE, see the README file present in both the Scintilla and SciTE
7028 directories. For Windows, GCC 3.2, Borland C++ or Microsoft Visual Studio .NET can be used
7029 for building. There is a make file for building Scintilla but not SciTE with Visual C++ 6 at
7031 supported. The version of GTK+ installed should be detected automatically.
7033 on the command line.</p>
7037 <p>On Windows, Scintilla is normally used as a dynamic library as a .DLL file. If you want to
7038 link Scintilla directly into your application .EXE or .DLL file, then the
7040 <code>Scintilla_RegisterClasses</code> called. <code>STATIC_BUILD</code> prevents compiling the
7041 <code>DllMain</code> function which will conflict with any <code>DllMain</code> defined in your
7047 <p>Depending on the compiler and linker used, the lexers may be stripped out. This is most
7048 often caused when building a static library. To ensure the lexers are linked in, the
7053 <p>To change the set of lexers in Scintilla, add and remove lexer source files
7058 following the patterns of other lexers. The important thing is to include
7064 <p id="AlternativeRegEx">A simple interface provides support for switching the Regular Expressions engine at
7068 to create an instance of your class. You must disable the built-in implementation by defining
7071 </body>
7072 </html>