| blob | 3f88d2d07901f97e33a6cad8feaf383caca590cf |
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 .provisional {
65 background: #FFB000;
66 }
67 /*]]>*/
68 -->
69 </style>
70 </head>
75 <tr>
80 </tr>
81 </table>
103 <a class="jump" href="https://bitbucket.org/StarFire/scintilla-doc/downloads/Scintilla-var'aq-Tutorial.pdf">
106 worth following if you want to contribute code to Scintilla but is not compulsory.</p>
110 <p>The Windows version of Scintilla is a Windows Control. As such, its primary programming
111 interface is through Windows messages. Early versions of Scintilla emulated much of the API
112 defined by the standard Windows Edit and RichEdit controls but those APIs are now deprecated in
113 favour of Scintilla's own, more consistent API. In addition to messages performing the actions
114 of a normal Edit control, Scintilla allows control of syntax styling, folding, markers, autocompletion
115 and call tips.</p>
117 <p>The GTK+ version also uses messages in a similar way to the Windows version. This is
118 different to normal GTK+ practice but made it easier to implement rapidly.</p>
120 <p>Scintilla also builds with Cocoa on OS X and with Qt, and follows the conventions of
121 those platforms.</p>
123 <p>Scintilla does not properly support right-to-left languages like Arabic and Hebrew.
124 While text in these languages may appear correct, it is not possible to interact with this text
125 as is normal with other editing components.</p>
127 <p>This documentation describes the individual messages and notifications used by Scintilla. It
128 does not describe how to link them together to form a useful editor. For now, the best way to
129 work out how to develop using Scintilla is to see how SciTE uses it. SciTE exercises most of
130 Scintilla's facilities.</p>
132 <p>In the descriptions that follow, the messages are described as function calls with zero, one
135 are large enough to hold pointers, and the return value is also an integer large enough to contain a
136 pointer.
137 Although the commands only use the
138 arguments described, because all messages have two arguments whether Scintilla uses them or
139 not, it is strongly recommended that any unused arguments are set to 0. This allows future
140 enhancement of messages without the risk of breaking existing code. Common argument types
141 are:</p>
145 <tr>
150 </tr>
152 <tr>
156 </tr>
158 <tr>
161 <td>Arguments point at text that is being passed to Scintilla but not modified. The text
162 may be zero terminated or another argument may specify the character count, the
163 description will make this clear.</td>
164 </tr>
166 <tr>
169 <td>Arguments point at text buffers that Scintilla will fill with text. In some cases,
170 another argument will tell Scintilla the buffer size. In others, you must make sure that
171 the buffer is big enough to hold the requested text. If a NULL pointer (0) is passed
172 then, for SCI_* calls, the length that should be allocated, not including any terminating
173 NUL, is returned. Some calls (marked "NUL-terminated") add a NUL character to the result but other calls do
174 not: to generically handle both types, allocate one more byte than indicated and set it to NUL.</td>
175 </tr>
177 <tr>
180 <td>Colours are set using the RGB format (Red, Green, Blue). The intensity of each colour
183 colour is white. If you set all intensities to 0, the colour is black. When you set a
184 colour, you are making a request. What you will get depends on the capabilities of the
185 system and the current screen mode.</td>
186 </tr>
188 <tr>
191 <td>Translucency is set using an alpha value.
192 Alpha ranges from 0 (SC_ALPHA_TRANSPARENT) which is completely transparent to
194 is opaque and uses code that is not alpha-aware and may be faster. Not all platforms support
195 translucency and only some Scintilla features implement translucency.
196 The default alpha value for most features is SC_ALPHA_NOALPHA.</td>
197 </tr>
199 <tr>
203 enhancements.</td>
204 </tr>
205 </tbody>
206 </table>
211 <tbody>
212 <tr>
214 modification</a></td>
220 </tr>
222 <tr>
229 </tr>
231 <tr>
234 <td>o <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection and Virtual Space</a></td>
237 scrolling</a></td>
239 </tr>
241 <tr>
248 </tr>
250 <tr>
257 </tr>
259 <tr>
260 <td>o <a class="toc" href="#CaretAndSelectionStyles">Caret, selection, and hotspot styles</a></td>
266 </tr>
268 <tr>
275 </tr>
277 <tr>
279 Guides</a></td>
285 </tr>
287 <tr>
294 </tr>
296 <tr>
303 </tr>
305 <tr>
312 </tr>
314 <tr>
321 </tr>
323 <tr>
330 </tr>
332 <tr>
339 </tr>
341 <tr>
346 <td>o <a class="toc" href="#ProvisionalMessages"><span class="provisional">Provisional messages</span></a></td>
348 </tr>
350 <tr>
354 supported by Scintilla</a></td>
358 </tr>
359 </tbody>
360 </table>
369 <p>Each byte in a Scintilla document is associated with a byte of styling
370 information. The combination of a character byte and a style byte is called a cell. Style bytes
371 are interpreted an index into an array of styles.</p>
373 <p>In this document, 'character' normally refers to a byte even when multi-byte characters are used.
374 Lengths measure the numbers of bytes, not the amount of characters in those bytes.</p>
376 <p>Positions within the Scintilla document refer to a character or the gap before that
379 The caret exists between character positions and can be located from before the first character (0)
382 <p>There are places where the caret can not go where two character bytes make up one character.
383 This occurs when a DBCS character from a language like Japanese is included in the document or
384 when line ends are marked with the CP/M standard of a carriage return followed by a line feed.
386 document.</p>
388 <p>All lines of text in Scintilla are the same height, and this height is calculated from the
389 largest font in any current style. This restriction is for performance; if lines differed in
390 height then calculations involving positioning of text would require the text to be styled
391 first.</p>
397 *text)</a><br />
401 *tr)</a><br />
407 <a class="message" href="#SCI_CHANGEINSERTION">SCI_CHANGEINSERTION(int length, const char *text)</a><br />
414 *tr)</a><br />
416 <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES(int numberStyles)</a><br />
418 <a class="message" href="#SCI_ENCODEDFROMUTF8">SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)</a><br />
420 </code>
428 entire document is returned.
430 the text as unmodified.</p>
439 This replaces all the text in the document with the zero terminated text string you pass
440 in.</p>
443 This message tells Scintilla that the current state of the document is unmodified. This is
444 usually done when the file is saved or loaded, hence the name "save point". As Scintilla
445 performs undo and redo operations, it notifies the container that it has entered or left the
450 should be considered dirty or not.</p>
456 This fills the buffer defined by text with the contents of the nominated line (lines start at
460 number of characters copied to the buffer. The returned text includes any end of line
461 characters. If you ask for a line number outside the range of lines in the document, 0
462 characters are copied. If the text argument is 0 then the length that should be allocated
463 to store the entire line is returned.</p>
474 current position are the same, the text is inserted at the caret position. The caret is
475 positioned after the inserted text and the caret is scrolled into view.</p>
479 These messages set and get the read-only flag for the document. If you mark a document as read
489 longer than the number of characters you wish to read. The return value is the length of the
500 This collects styled text into a buffer using two bytes for each cell, with the character at
501 the lower address of each pair and the style byte at the upper address. Characters between the
503 <code>struct Sci_TextRange</code> in <code>Scintilla.h</code>). Two 0 bytes are added to the end of
516 Allocate a document buffer large enough to store a given number of bytes.
517 The document will not be made smaller than its current contents.</p>
521 at the current position. This will include any 0's in the string that you might have expected
522 to stop the insert operation. The current position is set at the end of the inserted text,
523 but it is not scrolled into view.</p>
530 of the document. This will include any 0's in the string that you might have expected to stop
531 the operation. The current selection is not changed and the new text is not scrolled into
532 view.</p>
536 the current position if <code>pos</code> is -1. If the current position is after the insertion point
537 then it is moved along with its surrounding text but no scrolling is performed.</p>
540 This may only be called from a <a class="message" href="#SC_MOD_INSERTCHECK">SC_MOD_INSERTCHECK</a>
541 notification handler and will change the text being inserted to that provided.</p>
544 Unless the document is read-only, this deletes all the text.</p>
547 Deletes a range of text in the document.</p>
550 When wanting to completely restyle the document, for example after choosing a lexer, the
552 folding state.</p>
556 negative or past the end of the document.</p>
560 negative or past the end of the document.</p>
564 Extended styles are used for features like textual margins and annotations as well as internally by Scintilla.
566 These functions manage the use of extended styles to ensures that components cooperate in defining styles.
567 <code>SCI_RELEASEALLEXTENDEDSTYLES</code> releases any extended styles allocated by the container.
568 <code>SCI_ALLOCATEEXTENDEDSTYLES</code> allocates a range of style numbers after the byte style values and returns
569 the number of the first allocated style.
570 Ranges for margin and annotation styles should be allocated before calling
574 <p><b id="Sci_TextRange">Sci_TextRange</b> and <b id="Sci_CharacterRange">Sci_CharacterRange</b><br />
577 work.</p>
578 <pre>
579 struct Sci_CharacterRange {
580 long cpMin;
581 long cpMax;
582 };
584 struct Sci_TextRange {
585 struct Sci_CharacterRange chrg;
586 char *lpstrText;
587 };
588 </pre>
593 This method retrieves the value of the target encoded as UTF-8 which is the default
594 encoding of GTK+ so is useful for retrieving text for use in other parts of the user interface,
595 such as find and replace dialogs. The length of the encoded text in bytes is returned.
596 Cocoa uses UTF-16 which is easily converted from UTF-8 so this method can be used to perform the
597 more complex work of transcoding from the various encodings supported.
598 </p>
603 encoding which is useful for taking the results of a find dialog, for example, and receiving
604 a string of bytes that can be searched for in the document. Since the text can contain nul bytes,
606 length that will be converted. If set to -1, the length is determined by finding a nul byte.
607 The length of the converted string is returned.
608 </p>
612 <p>
613 There are methods to search for text and for regular expressions.
614 Most applications should use
616 as the basis for their search implementations.
618 </p>
619 <p>
620 The base regular expression support
621 is limited and should only be used for simple cases and initial development.
622 <span class="provisional">When using a C++11 compliant compiler and runtime, it may be possible to use the
623 runtime's implementation of <regex> by compiling Scintilla with <code>CXX11_REGEX</code> defined.</span>
624 A different regular expression
626 or can be called from the container using direct access to the buffer contents through
628 </p>
633 which uses a counted string to allow searching for null characters. It returns the
634 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
648 *text)</a><br />
650 char *text)</a><br />
652 *text)</a><br />
654 *text)</a><br />
656 </code>
663 These functions set and return the start and end of the target. When searching
664 you can set start greater than end to find the last matching text in the
665 target rather than the first matching text. The target is also set by a successful
669 Set the target start and end to the start and end positions of the selection.</p>
672 Set the target start to the start of the document and target end to the end of the document.</p>
678 expression search.</p>
681 This searches for the first occurrence of a text string in the target defined by
685 text and the return value is the position of the start of the matching text. If the search
689 Retrieve the value in the target.</p>
694 After replacement, the target range refers to the replacement text.
695 The return value
696 is the length of the replacement string.<br />
697 Note that the recommended way to delete text in the document is to set the target to the text to be removed,
698 and to perform a replace target with an empty string.</p>
703 characters to use. The replacement string is formed from the text string with any sequences of
705 expression search. <code>\0</code> is replaced with all the matched text from the most recent search.
706 After replacement, the target range refers to the replacement text.
707 The return value is the length of the replacement string.</p>
710 Discover what text was matched by tagged expressions in a regular expression search.
711 This is useful if the application wants to interpret the replacement string itself.</p>
716 Several of the search routines use flag options, which include a simple regular expression
717 search. Combine the flag options by adding them:</p>
720 <tbody>
721 <tr>
725 </tr>
727 <tr>
731 </tr>
733 <tr>
737 </tr>
739 <tr>
743 </tr>
744 <tr>
747 <td>Treat regular expression in a more POSIX compatible manner
748 by interpreting bare ( and ) for tagged sections rather than \( and \).</td>
749 </tr>
755 If the regular expression is invalid then -1 is returned and status is set to
757 The ECMAScript flag is set on the regex object and UTF-8 documents will exhibit Unicode-compliant
759 astral-plane character. There may be other differences between compilers.</td>
760 </tr>
761 </tbody>
762 </table>
767 <tbody>
768 <tr>
772 </tr>
774 <tr>
778 </tr>
780 <tr>
784 </tr>
786 <tr>
794 </tr>
796 <tr>
800 </tr>
802 <tr>
806 </tr>
808 <tr>
811 <td>This allows you to use a character x that would otherwise have a special meaning. For
812 example, \[ would be interpreted as [ and not as the start of a character set.</td>
813 </tr>
815 <tr>
818 <td>This indicates a set of characters, for example, [abc] means any of the characters a,
819 b or c. You can also use ranges, for example [a-z] for any lower case character.</td>
820 </tr>
822 <tr>
825 <td>The complement of the characters in the set. For example, [^A-Za-z] means any
826 character except an alphabetic character.</td>
827 </tr>
829 <tr>
833 </tr>
835 <tr>
839 </tr>
841 <tr>
846 </tr>
848 <tr>
853 </tr>
854 </tbody>
855 </table>
857 <p>Regular expressions will only match ranges within a single line, never matching over multiple lines.</p>
860 *ttf)</a><br />
863 *text)</a><br />
865 *text)</a><br />
866 </code>
870 This message searches for text in the document. It does not use or move the current selection.
872 search type, which includes regular expression searches.</p>
874 <p>You can
875 search backwards to find the previous occurrence of a search string by setting the end of the
876 search range before the start.</p>
880 to search. You can search backwards by
882 Set the <code>lpstrText</code> member of <code>Sci_TextToFind</code> to point at a zero terminated
883 text string holding the search pattern. If your language makes the use of <code>Sci_TextToFind</code>
888 <code>Sci_TextToFind</code> are filled in with the start and end positions of the found text.</p>
894 This structure is defined to have exactly the same shape as the Win32 structure
896 <pre>
897 struct Sci_TextToFind {
898 struct <a class="jump" href="#Sci_CharacterRange">Sci_CharacterRange</a> chrg; // range to search
899 const char *lpstrText; // the search pattern (zero terminated)
900 struct Sci_CharacterRange chrgText; // returned as position of matching text
901 };
902 </pre>
907 These messages provide relocatable search support. This allows multiple incremental
908 interactive searches to be macro recorded while still setting the selection to found text so
915 selection, that is, the end of the selection that is nearer to the start of the document. You
920 occurrence of the zero terminated search string pointed at by text. The search is modified by
924 of the matching text. The selection is updated to show the matched text, but is not scrolled
925 into view.</p>
934 When overtype is enabled, each typed character replaces the character to the right of the text
935 caret. When overtype is disabled, characters are inserted at the caret.
938 mode.</p>
949 const char *text)</a><br />
951 <a class="message" href="#SCI_SETPASTECONVERTENDINGS">SCI_SETPASTECONVERTENDINGS(bool convert)</a><br />
953 </code>
961 These commands perform the standard tasks of cutting and copying data to the clipboard,
962 pasting from the clipboard into the document, and clearing the document.
966 selection ranges implying that a copy or cut to the clipboard should work.</p>
969 unless the document is read-only.</p>
971 <p>On X, the clipboard is asynchronous and may require several messages between
972 the destination and source applications. Data from SCI_PASTE will not arrive in the
973 document immediately.</p>
976 selection is empty then the current line is copied. On Windows, an extra "MSDEVLineSelect" marker
978 the whole line before the current line.</p>
984 text to the system clipboard.</p>
988 If this property is set then when text is pasted any line ends are converted to match the document's
989 end of line mode as set with
991 Defaults to true.</p>
997 If an error occurs, Scintilla may set an internal error number that can be retrieved with
1001 and above are warnings.
1002 The currently defined statuses are:
1003 </p>
1007 <tr>
1011 </tr>
1013 <tr>
1017 </tr>
1023 </tr>
1025 <tr>
1029 </tr>
1031 </tbody>
1032 </table>
1036 <p>Scintilla has multiple level undo and redo. It will continue to collect undoable actions
1037 until memory runs out. Scintilla saves actions that change the document. Scintilla does not
1038 save caret and selection movements, view scrolling and the like. Sequences of typing or
1039 deleting are compressed into single transactions to make it easier to undo and redo at a sensible
1040 level of detail. Sequences of actions can be combined into transactions that are undone as a unit.
1042 <code>SCI_ENDUNDOACTION</code> messages. These transactions can be nested and only the top-level
1043 sequences are undone as units.</p>
1050 collectUndo)</a><br />
1055 </code>
1063 <p><code>SCI_CANUNDO</code> returns 0 if there is nothing to undo, and 1 if there is. You would
1064 typically use the result of this message to enable/disable the Edit menu Undo command.</p>
1071 actions to redo. You could typically use the result of this message to enable/disable the Edit
1072 menu Redo command.</p>
1075 This command tells Scintilla to forget any saved undo or redo history. It also sets the save
1076 point to the start of the undo buffer, so the document will appear to be unmodified. This does
1079 container.</p>
1085 You can control whether Scintilla collects undo information with
1088 <code>SCI_EMPTYUNDOBUFFER</code> to avoid the undo buffer being unsynchronized with the data in
1089 the buffer.</p>
1091 <p>You might wish to turn off saving undo information if you use the Scintilla to store text
1092 generated by a program (a Log view) or in a display window where text is often deleted and
1093 regenerated.</p>
1097 Send these two messages to Scintilla to mark the beginning and end of a set of operations that
1098 you want to undo all as one operation but that you have to generate as several operations.
1099 Alternatively, you can use these to mark a set of operations that you do not want to have
1100 combined with the preceding or following operations if they are undone.</p>
1103 The container can add its own actions into the undo stack by calling
1105 notification will be sent to the container with the
1110 <p>For example, if the container wanted to allow undo and redo of a 'toggle bookmark' command then
1112 Then when it receives a notification to undo or redo it toggles a bookmark on the line given by
1113 the token field. If there are different types of commands or parameters that need to be stored into the undo
1114 stack then the container should maintain a stack of its own for the document and use the current
1121 coalesced along with any insertion and deletion actions into a single compound action, otherwise 0.
1122 Coalescing treats coalescible container actions as transparent so will still only group together insertions that
1123 look like typing or deletions that look like multiple uses of the Backspace or Delete keys.
1124 </p>
1127 <p>Scintilla maintains a selection that stretches between two points, the anchor and the
1128 current position. If the anchor and the current position are the same, there is no selected
1129 text. Positions in the document range from 0 (before the first character), to the document size
1130 (after the last character). If you use messages, there is nothing to stop you setting a
1131 position that is in the middle of a CRLF pair, or in the middle of a 2 byte character. However,
1132 keyboard commands will not move the caret into such positions.</p>
1136 <a class="message" href="#SCI_SETFIRSTVISIBLELINE">SCI_SETFIRSTVISIBLELINE(int lineDisplay)</a><br />
1161 y)</a><br />
1162 <a class="message" href="#SCI_CHARPOSITIONFROMPOINT">SCI_CHARPOSITIONFROMPOINT(int x, int y)</a><br />
1163 <a class="message" href="#SCI_CHARPOSITIONFROMPOINTCLOSE">SCI_CHARPOSITIONFROMPOINTCLOSE(int x, int
1164 y)</a><br />
1166 position)</a><br />
1168 position)</a><br />
1175 <a class="message" href="#SCI_GETLINESELSTARTPOSITION">SCI_GETLINESELSTARTPOSITION(int line)</a><br />
1176 <a class="message" href="#SCI_GETLINESELENDPOSITION">SCI_GETLINESELENDPOSITION(int line)</a><br />
1179 onlyWordCharacters)</a><br />
1181 onlyWordCharacters)</a><br />
1185 <a class="message" href="#SCI_POSITIONRELATIVE">SCI_POSITIONRELATIVE(int position, int relative)</a><br />
1186 <a class="message" href="#SCI_COUNTCHARACTERS">SCI_COUNTCHARACTERS(int startPos, int endPos)</a><br />
1187 <a class="message" href="#SCI_TEXTWIDTH">SCI_TEXTWIDTH(int styleNumber, const char *text)</a><br />
1192 <a class="message" href="#SCI_SETMOUSESELECTIONRECTANGULARSWITCH">SCI_SETMOUSESELECTIONRECTANGULARSWITCH(bool
1193 mouseSelectionRectangularSwitch)</a><br />
1194 <a class="message" href="#SCI_GETMOUSESELECTIONRECTANGULARSWITCH">SCI_GETMOUSESELECTIONRECTANGULARSWITCH</a><br />
1195 </code>
1199 Both these messages return the length of the document in bytes.</p>
1202 This returns the number of lines in the document. An empty document contains 1 line. A
1207 These messages retrieve and set the line number of the first visible line in the Scintilla view. The first line
1211 This returns the number of complete lines visible on the screen. With a constant line height,
1212 this is the vertical space available divided by the line separation. Unless you arrange to size
1213 your window to an integral number of lines, there may be a partial line visible at the bottom
1214 of the view.</p>
1217 This returns non-zero if the document is modified and 0 if it is unmodified. The modified
1218 status of a document is determined by the undo position relative to the save point. The save
1220 usually when you have saved data to a file.</p>
1222 <p>If you need to be notified when the document becomes modified, Scintilla notifies the
1231 remove any selection (i.e. set the anchor to the same position as <code>currentPos</code>). The
1232 caret is scrolled into view after this operation.</p>
1236 the caret visible, if necessary. It is equivalent to
1238 position.</p>
1242 and scrolls the view (if needed) to make it visible. The anchor position is set the same as the
1244 the line set is the first or last.</p>
1247 This sets the current position and creates a selection between the anchor and the current
1248 position. The caret is not scrolled into view.</p>
1253 This returns the current position.</p>
1256 This sets the anchor position and creates a selection between the anchor position and the
1257 current position. The caret is not scrolled into view.</p>
1262 This returns the current anchor position.</p>
1266 These set the selection based on the assumption that the anchor position is less than the
1267 current position. They do not make the caret visible. The table shows the positions of the
1268 anchor and the current position after using these messages.</p>
1272 <tr>
1273 <th>
1274 </th>
1279 </tr>
1280 </thead>
1283 <tr>
1289 </tr>
1291 <tr>
1297 </tr>
1298 </tbody>
1299 </table>
1305 These return the start and end of the selection without regard to which end is the current
1306 position and which is the anchor. <code>SCI_GETSELECTIONSTART</code> returns the smaller of the
1307 current position or the anchor position. <code>SCI_GETSELECTIONEND</code> returns the larger of
1308 the two values.</p>
1311 This removes any selection and sets the caret at <code>pos</code>. The caret is not scrolled into view.</p>
1314 This selects all the text in the document. The current position is not scrolled into view.</p>
1322 This returns the document position that corresponds with the start of the line. If
1326 last line), the return value is the end of the document.</p>
1329 This returns the position at the end of the line, before any line end characters. If <code>line</code>
1330 is the last line in the document (which does not have any end of line characters) or greater,
1331 the result is the size of the document.
1336 is negative or beyond the last line in the document, the result is 0. If you want the length of
1338 href="#SCI_GETLINEENDPOSITION"><code>SCI_GETLINEENDPOSITION(line)</code></a> - <a class="message"
1343 buffer. The buffer size should be determined by calling with a NULL pointer for the <code>text</code> argument
1345 This allows for rectangular and discontiguous selections as well as simple selections.
1346 See <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection</a> for information on
1347 how multiple and rectangular selections and virtual space are copied.</p>
1354 </code></p>
1357 This retrieves the text of the line containing the caret and returns the position within the
1359 the text you wish to retrieve and a terminating 0 character.
1362 If the text argument is 0 then the length that should be allocated
1363 to store the entire current line is returned.</p>
1376 The two functions set and get the selection mode, which can be
1381 When set in these modes, regular caret moves will extend or reduce the selection,
1383 The get function returns the current mode even if the selection was made by mouse
1384 or with regular extended moves.
1385 <code>SC_SEL_THIN</code> is the mode after a rectangular selection has been typed into and ensures
1386 that no characters are selected.</p>
1390 Retrieve the position of the start and end of the selection at the given line with
1394 If the caret is off the top or bottom of the view, it is moved to the nearest line that is
1395 visible to its current position. Any selection is lost.</p>
1398 onlyWordCharacters)</b><br />
1400 onlyWordCharacters)</b><br />
1401 These messages return the start and end of words using the same definition of words as used
1402 internally within Scintilla. You can set your own list of characters that count as words with
1404 sets the start or the search, which is forwards when searching for the end and backwards when
1405 searching for the start.</p>
1408 Is the range start..end a word or set of words? This message checks that start is at a word start transition and that
1409 end is at a word end transition. It does not check whether there are any spaces inside the range.</p>
1415 <code>false</code> (0), the first character in the search direction sets the type of the search
1416 as word or non-word and the search stops at the first non-matching character. Searches are also
1417 terminated by the start or end of the document.</p>
1425 <tr>
1435 </tr>
1436 </thead>
1439 <tr>
1449 </tr>
1451 <tr>
1461 </tr>
1463 <tr>
1473 </tr>
1475 <tr>
1485 </tr>
1486 </tbody>
1487 </table>
1491 These messages return the position before and after another position
1492 in the document taking into account the current code page. The minimum
1493 position returned is 0 and the maximum is the last position in the document.
1494 If called with a position within a multi byte character will return the position
1495 of the start/end of that character.</p>
1498 Count a number of whole characters before or after the argument position and return that position.
1499 The minimum position returned is 0 and the maximum is the last position in the document.
1500 </p>
1503 Returns the number of whole characters between two positions..</p>
1507 be used, for example, to decide how wide to make the line number margin in order to display a
1508 given number of numerals.</p>
1511 This returns the height in pixels of a particular line. Currently all lines are the same
1512 height.</p>
1516 taking the width of tabs into account. This returns the column number of the last tab on the
1518 <code>pos</code>. If there are no tab characters on the line, the return value is the number of
1519 characters up to the position on the line. In both cases, double byte characters count as a
1520 single character. This is probably only useful with monospaced fonts.</p>
1524 taking the width of tabs into account. It treats a multi-byte character as a single column.
1531 window or not close to any characters.</p>
1536 <code>SCI_CHARPOSITIONFROMPOINTCLOSE</code> is similar but returns -1 if the point is outside the
1537 window or not close to any characters. This is similar to the previous methods but finds characters rather than
1538 inter-character positions.</p>
1543 in the document.</p>
1549 is drawn as normal text.</p>
1552 Scintilla remembers the x value of the last position horizontally moved to explicitly by the
1553 user and this value is then used when moving vertically such as by using the up and down keys.
1554 This message sets the current x position of the caret as the remembered value.</p>
1557 Move the selected lines up one line, shifting the line above after the selection.
1558 The selection will be automatically extended to the beginning of the selection's first line and the end of the selection's last line.
1559 If nothing was selected, the line the cursor is currently at will be selected.</p>
1562 Move the selected lines down one line, shifting the line below before the selection.
1563 The selection will be automatically extended to the beginning of the selection's first line and the end of the selection's last line.
1564 If nothing was selected, the line the cursor is currently at will be selected.</p>
1567 mouseSelectionRectangularSwitch)</b><br />
1568 <b id="SCI_GETMOUSESELECTIONRECTANGULARSWITCH">SCI_GETMOUSESELECTIONRECTANGULARSWITCH</b><br />
1569 Enable or disable the ability to switch to rectangular selection mode while making a selection with the mouse.
1570 When this option is turned on, mouse selections in stream mode can be switched to rectangular mode by pressing
1571 the corresponding modifier key. They then stick to rectangular mode even when the modifier key is released again.
1572 When this option is turned off, mouse selections will always stick to the mode the selection was started in. It
1573 is off by default.</p>
1577 <code>
1578 <a class="message" href="#SCI_SETMULTIPLESELECTION">SCI_SETMULTIPLESELECTION(bool multipleSelection)</a><br />
1580 <a class="message" href="#SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</a><br />
1581 <a class="message" href="#SCI_GETADDITIONALSELECTIONTYPING">SCI_GETADDITIONALSELECTIONTYPING</a><br />
1584 <a class="message" href="#SCI_SETVIRTUALSPACEOPTIONS">SCI_SETVIRTUALSPACEOPTIONS(int virtualSpaceOptions)</a><br />
1586 <a class="message" href="#SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</a><br />
1587 <a class="message" href="#SCI_GETRECTANGULARSELECTIONMODIFIER">SCI_GETRECTANGULARSELECTIONMODIFIER</a><br />
1588 <br />
1598 <br />
1600 <a class="message" href="#SCI_SETSELECTIONNCARET">SCI_SETSELECTIONNCARET(int selection, int pos)</a><br />
1601 <a class="message" href="#SCI_GETSELECTIONNCARET">SCI_GETSELECTIONNCARET(int selection)</a><br />
1602 <a class="message" href="#SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</a><br />
1603 <a class="message" href="#SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</a><br />
1604 <a class="message" href="#SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</a><br />
1605 <a class="message" href="#SCI_GETSELECTIONNANCHOR">SCI_GETSELECTIONNANCHOR(int selection)</a><br />
1606 <a class="message" href="#SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</a><br />
1607 <a class="message" href="#SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</a><br />
1608 <a class="message" href="#SCI_SETSELECTIONNSTART">SCI_SETSELECTIONNSTART(int selection, int pos)</a><br />
1609 <a class="message" href="#SCI_GETSELECTIONNSTART">SCI_GETSELECTIONNSTART(int selection)</a><br />
1610 <a class="message" href="#SCI_SETSELECTIONNEND">SCI_SETSELECTIONNEND(int selection, int pos)</a><br />
1612 <br />
1614 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARET">SCI_SETRECTANGULARSELECTIONCARET(int pos)</a><br />
1615 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARET">SCI_GETRECTANGULARSELECTIONCARET</a><br />
1616 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</a><br />
1617 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</a><br />
1618 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</a><br />
1619 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHOR">SCI_GETRECTANGULARSELECTIONANCHOR</a><br />
1620 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</a><br />
1621 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</a><br />
1622 <br />
1624 <a class="message" href="#SCI_SETADDITIONALSELALPHA">SCI_SETADDITIONALSELALPHA(int alpha)</a><br />
1626 <a class="message" href="#SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int colour)</a><br />
1627 <a class="message" href="#SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int colour)</a><br />
1628 <a class="message" href="#SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int colour)</a><br />
1630 <a class="message" href="#SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</a><br />
1632 <a class="message" href="#SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</a><br />
1633 <a class="message" href="#SCI_GETADDITIONALCARETSVISIBLE">SCI_GETADDITIONALCARETSVISIBLE</a><br />
1634 <br />
1640 </code>
1642 <p>
1643 There may be multiple selections active at one time.
1644 More selections are made by holding down the Ctrl key while dragging with the mouse.
1645 The most recent selection is the main selection and determines which part of the document is shown automatically.
1646 Any selection apart from the main selection is called an additional selection.
1647 The calls in the previous section operate on the main selection.
1648 There is always at least one selection.
1649 </p>
1651 <p>
1652 Rectangular selections are handled as multiple selections although the original rectangular range is remembered so that
1653 subsequent operations may be handled differently for rectangular selections. For example, pasting a rectangular selection
1654 places each piece in a vertical column.
1655 </p>
1657 <p>
1658 Virtual space is space beyond the end of each line. The caret may be moved into virtual space but no real space will be
1659 added to the document until there is some text typed or some other text insertion command is used.
1660 </p>
1662 <p>When discontiguous selections are copied to the clipboard, each selection is added to the clipboard text
1663 in order with no delimiting characters.
1664 For rectangular selections the document's line end is added after each line's text. Rectangular selections
1665 are always copied from top line to bottom, not in the in order of selection.Virtual space is not copied.</p>
1667 <p>
1670 Enable or disable multiple selection. When multiple selection is disabled, it is not possible to select
1671 multiple ranges by holding down the Ctrl key while dragging with the mouse.</p>
1673 <p>
1674 <b id="SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</b><br />
1676 Whether typing, backspace, or delete works with multiple selections simultaneously.</p>
1678 <p>
1681 When pasting into multiple selections, the pasted text can go into just the main selection with <code>SC_MULTIPASTE_ONCE</code>=0
1682 or into each selection with <code>SC_MULTIPASTE_EACH</code>=1. <code>SC_MULTIPASTE_ONCE</code> is the default.</p>
1684 <p>
1687 Virtual space can be enabled or disabled for rectangular selections or in other circumstances or in both.
1692 <p>
1693 <b id="SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</b><br />
1695 On GTK+, the key used to indicate that a rectangular selection should be created when combined with a mouse drag can be set.
1696 The three possible values are <code>SCMOD_CTRL</code>=2 (default), <code>SCMOD_ALT</code>=4 or <code>SCMOD_SUPER</code>=8.
1697 Since <code>SCMOD_ALT</code> is often already used by a window manager, the window manager may need configuring to allow this choice.
1698 <code>SCMOD_SUPER</code> is often a system dependent modifier key such as the Left Windows key on a Windows keyboard or the
1699 Command key on a Mac.</p>
1701 <p>
1703 Return the number of selections currently active. There is always at least one selection.</p>
1705 <p>
1709 <p>
1713 <p>
1715 Set a single selection from <code>anchor</code> to <code>caret</code> as the only selection.</p>
1717 <p>
1719 Add a new selection from <code>anchor</code> to <code>caret</code> as the main selection retaining all other
1720 selections as additional selections.
1721 Since there is always at least one selection, to set a list of selections, the first selection should be
1722 added with <code>SCI_SETSELECTION</code> and later selections added with <code>SCI_ADDSELECTION</code></p>
1724 <p>
1726 If there are multiple selections, remove the indicated selection.
1727 If this was the main selection then make the previous selection the main and if it was the first then the last selection becomes main.
1728 If there is only one selection, or there is no selection <code>selection</code>, then there is no effect.</p>
1730 <p>
1733 One of the selections is the main selection which is used to determine what range of text is automatically visible.
1734 The main selection may be displayed in different colours or with a differently styled caret.
1735 Only an already existing selection can be made main.</p>
1737 <p>
1740 <b id="SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</b><br />
1741 <b id="SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</b><br />
1742 <b id="SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</b><br />
1744 <b id="SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</b><br />
1745 <b id="SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</b><br />
1746 Set or query the position and amount of virtual space for the caret and anchor of each already existing selection.</p>
1748 <p>
1753 Set or query the start and end position of each already existing selection.
1754 Mostly of use to query each range for its text. The selection parameter is zero-based. </p>
1756 <p>
1759 <b id="SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</b><br />
1760 <b id="SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</b><br />
1761 <b id="SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</b><br />
1763 <b id="SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</b><br />
1764 <b id="SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</b><br />
1765 Set or query the position and amount of virtual space for the caret and anchor of the rectangular selection.
1766 After setting the rectangular selection, this is broken down into multiple selections, one for each line.</p>
1768 <p>
1771 <b id="SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1772 <b id="SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int <a class="jump" href="#colour">colour</a>)</b><br />
1773 Modify the appearance of additional selections so that they can be differentiated from the main selection which has its appearance set with
1782 called with useSelection*Colour value set to true. Subsequent calls to
1786 <p>
1787 <b id="SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1789 <b id="SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</b><br />
1791 Modify the appearance of additional carets so that they can be differentiated from the main caret which has its appearance set with
1797 <p>
1798 <b id="SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</b><br />
1802 <p>
1807 These commands may be assigned to keys to make it possible to manipulate multiple selections.
1808 <code>SCI_SWAPMAINANCHORCARET</code> moves the caret to the opposite end of the main selection.
1811 within the target to the set of selections as main. If the current selection is empty then select word around caret.
1813 are used so the application may choose case sensitivity and word search options.<br />
1816 </p>
1821 <a class="message" href="#SCI_SCROLLRANGE">SCI_SCROLLRANGE(int secondary, int primary)</a><br />
1823 caretSlop)</a><br />
1825 caretSlop)</a><br />
1827 caretSlop)</a><br />
1836 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING">SCI_SETSCROLLWIDTHTRACKING(bool tracking)</a><br />
1839 endAtLastLine)</a><br />
1841 </code>
1844 This will attempt to scroll the display by the number of columns and lines that you specify.
1845 Positive line values increase the line number at the top of the screen (i.e. they move the text
1846 upwards as far as the user is concerned), Negative line values do the reverse.</p>
1848 <p>The column measure is the width of a space in the default style. Positive values increase
1849 the column at the left edge of the view (i.e. they move the text leftwards as far as the user
1850 is concerned). Negative values do the reverse.</p>
1855 If the current position (this is the caret if there is no selection) is not visible, the view
1856 is scrolled to make it visible according to the current caret policy.</p>
1859 Scroll the argument positions and the range between them into view giving
1860 priority to the primary position then the secondary position.
1861 The behaviour is similar to <a class="message" href="#SCI_SCROLLCARET"><code>SCI_SCROLLCARET</code></a>
1862 with the primary position used instead of the caret. An effort is then made to ensure that the secondary
1863 position and range between are also visible.
1864 This may be used to make a search match visible.</p>
1874 <tr>
1878 unwanted zone (UZ) where the caret is... unwanted. This zone is defined as a number of
1879 pixels near the vertical margins, and as a number of lines near the horizontal margins.
1880 By keeping the caret away from the edges, it is seen within its context. This makes it
1881 likely that the identifier that the caret is on can be completely seen, and that the
1882 current line is seen with some of the lines following it, which are often dependent on
1883 that line.</td>
1884 </tr>
1886 <tr>
1892 </tr>
1894 <tr>
1897 <td>If set, the display is moved more energetically so the caret can move in the same
1898 direction longer before the policy is applied again. '3UZ' notation is used to indicate
1899 three time the size of the UZ as a distance to the margin.</td>
1900 </tr>
1902 <tr>
1905 <td>If not set, instead of having symmetrical UZs, the left and bottom UZs are extended
1906 up to right and top UZs respectively. This way, we favour the displaying of useful
1907 information: the beginning of lines, where most code reside, and the lines after the
1908 caret, for example, the body of a function.</td>
1909 </tr>
1910 </tbody>
1911 </table>
1915 <tr>
1927 or going into the UZ) display is...</th>
1928 </tr>
1929 </thead>
1932 <tr>
1944 </tr>
1946 <tr>
1958 </tr>
1960 <tr>
1972 </tr>
1974 <tr>
1986 </tr>
1988 <tr>
2000 </tr>
2002 <tr>
2014 </tr>
2016 <tr>
2028 </tr>
2030 <tr>
2042 </tr>
2044 <tr>
2056 </tr>
2058 <tr>
2070 </tr>
2072 <tr>
2084 </tr>
2086 <tr>
2098 </tr>
2100 <tr>
2112 </tr>
2113 </tbody>
2114 </table>
2119 called. It takes <code>VISIBLE_SLOP</code> and <code>VISIBLE_STRICT</code> flags for the policy
2126 The horizontal scroll bar is only displayed if it is needed for the assumed width.
2127 If you never wish to see it, call
2130 when needed.</p>
2135 By default, the vertical scroll bar is always displayed when required. You can choose to hide
2142 view. A value of 0 is the normal position with the first text column visible at the left of the
2143 view.</p>
2149 For performance, Scintilla does not measure the display width of the document to determine
2150 the properties of the horizontal scroll bar. Instead, an assumed width is used.
2151 These messages set and get the document width in pixels assumed by Scintilla.
2152 The default value is 2000.
2153 To ensure the width of the currently visible lines can be scrolled use
2154 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING"><code>SCI_SETSCROLLWIDTHTRACKING</code></a></p>
2158 If scroll width tracking is enabled then the scroll width is adjusted to ensure that all of the lines currently
2159 displayed can be completely scrolled. This mode never adjusts the scroll width to be narrower.</p>
2165 scrolling one page below the last line.</p>
2171 useWhitespaceForeColour, int colour)</a><br />
2173 useWhitespaceBackColour, int colour)</a><br />
2175 size)</a><br />
2181 </code>
2185 White space can be made visible which may be useful for languages in which white space is
2186 significant, such as Python. Space characters appear as small centred dots and tab characters
2187 as light arrows pointing to the right. There are also ways to control the display of <a
2193 <tr>
2198 <td>The normal display mode with white space displayed as an empty background
2199 colour.</td>
2200 </tr>
2202 <tr>
2208 </tr>
2210 <tr>
2215 <td>White space used for indentation is displayed normally but after the first visible
2216 character, it is shown as dots and arrows.</td>
2217 </tr>
2218 </tbody>
2219 </table>
2227 By default, the colour of visible white space is determined by the lexer in use. The
2228 foreground and/or background colour of all visible white space can be set globally, overriding
2236 </p>
2238 <p>
2243 Text is drawn with the base of each character on a 'baseline'. The height of a line is found from the maximum
2244 that any style extends above the baseline (its 'ascent'), added to the maximum that any style extends below the
2245 baseline (its 'descent').
2248 This may done to make the text easier to read or to accommodate underlines or highlights.
2249 </p>
2255 The cursor is normally chosen in a context sensitive way, so it will be different over the
2256 margin than when over the text. When performing a slow action, you may wish to change to a wait
2258 argument can be:</p>
2262 <tr>
2268 </tr>
2270 <tr>
2275 <td>The wait cursor is displayed when the mouse is over or owned by the Scintilla
2276 window.</td>
2277 </tr>
2278 </tbody>
2279 </table>
2290 When the mouse is pressed inside Scintilla, it is captured so future mouse movement events are
2291 sent to Scintilla. This behaviour may be turned off with
2296 <p>Scintilla can handle the major line end conventions and, depending on settings and
2297 the current lexer also support additional Unicode line ends.</p>
2299 <p>Scintilla can interpret any of the Macintosh (\r), Unix (\n) and Windows (\r\n)
2300 line ends.
2301 When the user presses the Enter key, one of these line
2302 end strings is inserted into the buffer. The default is \r\n in Windows and \n in Unix, but
2308 Next Line (<code>NEL=U+0085</code>), Line Separator (<code>LS=U+2028</code>), and Paragraph Separator (<code>PS=U+2029</code>)
2309 may optionally be interpreted when Unicode line ends is turned on and the current lexer also supports
2310 Unicode line ends.</p>
2319 <a class="message" href="#SCI_SETLINEENDTYPESALLOWED">SCI_SETLINEENDTYPESALLOWED(int lineEndBitSet)</a><br />
2326 presses the Enter key. You can set <code>eolMode</code> to one of <code>SC_EOL_CRLF</code> (0),
2328 message retrieves the current state.</p>
2331 This message changes all the end of line characters in the document to match
2341 returns the current state.</p>
2345 by the current lexer. This is a bit set although there is currently only a single choice
2346 with either <code>SC_LINE_END_TYPE_DEFAULT</code> (0) or <code>SC_LINE_END_TYPE_UNICODE</code> (1).
2347 These values are also used by the other messages concerned with Unicode line ends.</p>
2351 By default, only the ASCII line ends are interpreted. Unicode line ends may be requested with
2353 but this will be ineffective unless the lexer also allows you Unicode line ends.
2358 by Scintilla. It is <code>SCI_GETLINEENDTYPESSUPPORTED & SCI_GETLINEENDTYPESALLOWED</code>.</p>
2362 <p>The styling messages allow you to assign styles to text. If your styling needs can be met by
2363 one of the standard lexers, or if you can write your own, then a lexer is probably the easiest
2364 way to style your document. If you choose to use the container to do the styling you can use
2369 alternative, you might use idle time to style the document. Even if you use a lexer, you might
2370 use the styling commands to mark errors detected by a compiler. The following commands can be
2371 used.</p>
2373 <a class="message" href="#SCI_STARTSTYLING">SCI_STARTSTYLING(int position, int unused)</a><br />
2376 *styles)</a><br />
2380 </code>
2383 Scintilla keeps a record of the last character that is likely to be styled correctly. This is
2384 moved forwards when characters after it are styled and moved backwards if changes are made to
2385 the text of the document before it. Before drawing text, this position is checked to see if any
2389 start styling. Scintilla will always ask to style whole lines.</p>
2393 The unused argument was used in earlier versions but is now ignored.
2394 After
2402 </p>
2408 the next call.
2410 </p>
2414 As well as the 8 bits of lexical state stored for each character there is also an integer
2415 stored for each line. This can be used for longer lived parse states such as what the current
2418 Changing the value produces a <a class="message" href="#SC_MOD_CHANGELINESTATE">SC_MOD_CHANGELINESTATE</a> notification.
2419 </p>
2422 This returns the last line that has any line state.</p>
2426 <p>While the style setting messages mentioned above change the style numbers associated with
2427 text, these messages define how those style numbers are interpreted visually. There are 256
2429 There are also some
2431 defined.</p>
2435 <tr>
2440 <td>This style defines the attributes that all styles receive when the
2442 </tr>
2444 <tr>
2449 <td>This style sets the attributes of the text used to display line numbers in a line
2450 number margin. The background colour set for this style also sets the background colour
2451 for all margins that do not have any folding mask bits set. That is, any margin for which
2454 </tr>
2456 <tr>
2465 </tr>
2467 <tr>
2472 <td>This style sets the display attributes used when marking an unmatched brace with the
2474 message.</td>
2475 </tr>
2477 <tr>
2482 <td>This style sets the font used when drawing control characters.
2483 Only the font, size, bold, italics, and character set attributes are used and not
2484 the colour attributes. See
2487 </tr>
2489 <tr>
2494 <td>This style sets the foreground and background colours used when drawing the
2495 indentation guides.</td>
2496 </tr>
2498 <tr>
2505 causes call tips to use this style instead. Only the font face name, font size,
2506 foreground and background colours and character set attributes are used.</td>
2507 </tr>
2509 <tr>
2514 <td>To make it easier for client code to discover the range of styles that are
2515 predefined, this is set to the style number of the last predefined style. This is
2517 for one future predefined style.</td>
2518 </tr>
2520 <tr>
2525 <td>This is not a style but is the number of the maximum style that can be set. Styles
2527 </tr>
2528 </tbody>
2529 </table>
2531 <p>For each style you can set the font name, size and use of bold, italic and underline,
2532 foreground and background colour and the character set. You can also choose to hide text with a
2533 given style, display all characters as upper or lower case and fill from the last character on
2534 a line to the end of the line (for embedded languages). There is also an experimental attribute
2535 to make text read-only.</p>
2537 <p>It is entirely up to you how you use styles. If you want to use syntax colouring you might
2543 *fontName)</a><br />
2544 <a class="message" href="#SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName)</a><br />
2546 sizeInPoints)</a><br />
2548 <a class="message" href="#SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int
2549 sizeInHundredthPoints)</a><br />
2550 <a class="message" href="#SCI_STYLEGETSIZEFRACTIONAL">SCI_STYLEGETSIZEFRACTIONAL(int styleNumber)</a><br />
2552 bold)</a><br />
2555 weight)</a><br />
2558 italic)</a><br />
2561 underline)</a><br />
2562 <a class="message" href="#SCI_STYLEGETUNDERLINE">SCI_STYLEGETUNDERLINE(int styleNumber)</a><br />
2564 colour)</a><br />
2567 colour)</a><br />
2570 eolFilled)</a><br />
2571 <a class="message" href="#SCI_STYLEGETEOLFILLED">SCI_STYLEGETEOLFILLED(int styleNumber)</a><br />
2573 int charSet)</a><br />
2574 <a class="message" href="#SCI_STYLEGETCHARACTERSET">SCI_STYLEGETCHARACTERSET(int styleNumber)</a><br />
2576 caseMode)</a><br />
2579 visible)</a><br />
2582 changeable)</a><br />
2583 <a class="message" href="#SCI_STYLEGETCHANGEABLE">SCI_STYLEGETCHANGEABLE(int styleNumber)</a><br />
2585 hotspot)</a><br />
2587 </code>
2591 initialised.</p>
2595 are setting up Scintilla for syntax colouring, it is likely that the lexical styles you set
2596 will be very similar. One way to set the styles is to:<br />
2602 <b id="SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName NUL-terminated)</b><br />
2605 <b id="SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int sizeInHundredthPoints)</b><br />
2615 attributes that are used to match the fonts you request to those available.</p>
2616 <p>The
2618 only the first 32 characters of the name are used, the name is decoded as UTF-8, and the name is not case sensitive. For
2619 internal caching, Scintilla tracks fonts by name and does care about the casing of font names,
2620 so please be consistent.
2621 On GTK+, Pango is used to display text and the name is sent directly to Pango without transformation.
2622 On Qt, the name is decoded as UTF-8.
2623 On Cocoa, the name is decoded as MacRoman.</p>
2625 or to a fractional point size in hundredths of a point with <code>SCI_STYLESETSIZEFRACTIONAL</code>
2627 For example, a text size of 9.4 points is set with <code>SCI_STYLESETSIZEFRACTIONAL(<style>, 940)</code>.
2628 </p>
2630 or <code>SCI_STYLESETWEIGHT</code>. The weight is a number between 1 and 999 with 1 being very light
2631 and 999 very heavy. While any value can be used, fonts often only support between 2 and 4 weights with three weights
2632 being common enough to have symbolic names:
2636 The <code>SCI_STYLESETBOLD</code> message takes a boolean argument with 0 choosing <code>SC_WEIGHT_NORMAL</code>
2638 </p>
2641 underline)</b><br />
2643 You can set a style to be underlined. The underline is drawn in the foreground colour. All
2644 characters with a style that includes the underline attribute are underlined, even if they are
2645 white space.</p>
2653 Text is drawn in the foreground colour. The space in each character cell that is not occupied
2654 by the character is drawn in the background colour.</p>
2657 eolFilled)</b><br />
2659 If the last character in the line has a style with this attribute set, the remainder of the
2660 line up to the right edge of the window is filled with the background colour set for the last
2661 character. This is useful when a document contains embedded sections in another language such
2663 and a consistent background colour (different from the background colour set for the HTML
2664 styles) to all JavaScript styles then JavaScript sections will be easily distinguished from
2665 HTML.</p>
2668 charSet)</b><br />
2670 You can set a style to use a different character set than the default. The places where such
2671 characters sets are likely to be useful are comments and literal strings. For example,
2673 strings in Russian would display correctly in C and C++ (<code>SCE_C_STRING</code> is the style
2674 number used by the C and C++ lexer to display literal strings; it has the value 6). This
2675 feature works differently on Windows and GTK+.</p>
2684 <code>SC_CHARSET_SHIFTJIS</code>, <code>SC_CHARSET_SYMBOL</code>, <code>SC_CHARSET_THAI</code>,
2696 The value of caseMode determines how text is displayed. You can set upper case
2699 displayed.</p>
2703 Text is normally visible. However, you can completely hide it by giving it a style with the
2705 hypertext keywords in HTML or XML.</p>
2708 changeable)</b><br />
2710 This is an experimental and incompletely implemented style attribute. The default setting is
2712 read-only. Currently it only stops the caret from being within not-changeable text and does not
2713 yet stop deleting a range that contains not-changeable text.</p>
2716 hotspot)</b><br />
2718 This style is used to mark ranges of text that can detect mouse clicks.
2719 The cursor changes to a hand over hotspots, and the foreground, and background colours
2720 may change and an underline appear to indicate that these areas are sensitive to clicking.
2721 This may be used to allow hyperlinks to other documents.</p>
2725 <p>The selection is shown by changing the foreground and/or background colours. If one of these
2726 is not set then that attribute is not changed for the selection. The default is to show the
2727 selection by changing the background to light grey and leaving the foreground the same as when
2728 it was not selected. When there is no selection, the current insertion point is marked by the
2729 text caret. This is a vertical line that is normally blinking on and off to attract the users
2730 attention.</p>
2731 <code><a class="message" href="#SCI_SETSELFORE">SCI_SETSELFORE(bool useSelectionForeColour, int colour)</a><br />
2732 <a class="message" href="#SCI_SETSELBACK">SCI_SETSELBACK(bool useSelectionBackColour, int colour)</a><br />
2739 <a class="message" href="#SCI_SETCARETLINEVISIBLE">SCI_SETCARETLINEVISIBLE(bool show)</a><br />
2743 <a class="message" href="#SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int alpha)</a><br />
2745 <a class="message" href="#SCI_SETCARETLINEVISIBLEALWAYS">SCI_SETCARETLINEVISIBLEALWAYS(bool alwaysVisible)</a><br />
2746 <a class="message" href="#SCI_GETCARETLINEVISIBLEALWAYS">SCI_GETCARETLINEVISIBLEALWAYS</a><br />
2753 <a class="message" href="#SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useSetting, int colour)</a><br />
2755 <a class="message" href="#SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useSetting, int colour)</a><br />
2757 <a class="message" href="#SCI_SETHOTSPOTACTIVEUNDERLINE">SCI_SETHOTSPOTACTIVEUNDERLINE(bool underline)</a><br />
2758 <a class="message" href="#SCI_GETHOTSPOTACTIVEUNDERLINE">SCI_GETHOTSPOTACTIVEUNDERLINE</a><br />
2759 <a class="message" href="#SCI_SETHOTSPOTSINGLELINE">SCI_SETHOTSPOTSINGLELINE(bool singleLine)</a><br />
2761 <a class="message" href="#SCI_SETCARETSTICKY">SCI_SETCARETSTICKY(int useCaretStickyBehaviour)</a><br />
2764 </code>
2770 You can choose to override the default selection colouring with these two messages. The colour
2773 argument has no effect.</p>
2774 <p><b id="SCI_SETSELALPHA">SCI_SETSELALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2776 The selection can be drawn translucently in the selection background colour by
2777 setting an alpha value.</p>
2781 The selection can be drawn up to the right hand border by setting this property.</p>
2794 <b id="SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2796 You can choose to make the background colour of the line containing the caret different with
2797 these messages. To do this, set the desired background colour with
2801 background colouring has highest priority when a line has markers that would otherwise change
2802 the background colour.
2803 The caret line may also be drawn translucently which allows other background colours to show
2804 through. This is done by setting the alpha (translucency) value by calling
2805 SCI_SETCARETLINEBACKALPHA. When the alpha is not SC_ALPHA_NOALPHA,
2806 the caret line is drawn after all other features so will affect the colour of all other features.
2807 </p>
2809 <p><b id="SCI_SETCARETLINEVISIBLEALWAYS">SCI_SETCARETLINEVISIBLEALWAYS(bool alwaysVisible)</b><br />
2811 Choose to make the caret line always visible even when the window is not in focus.
2812 Default behaviour <code>SCI_SETCARETLINEVISIBLEALWAYS(false)</code> the caret line is only visible when the window is in focus.
2813 </p>
2818 determines the time in milliseconds that the caret is visible or invisible before changing
2819 state. Setting the period to 0 stops the caret blinking. The default value is 500 milliseconds.
2829 <p>The block character draws most combining and multibyte character sequences successfully,
2830 though some fonts like Thai Fonts (and possibly others) can sometimes appear strange when
2831 the cursor is positioned at these characters, which may result in only drawing a part of the
2832 cursor character sequence. This is most notable on Windows platforms.</p>
2839 1.50), similar to setting the caret style to CARETSTYLE_INVISIBLE (though not interchangeable).
2840 This setting only affects the width of the cursor when the cursor style is set to line caret
2841 mode, it does not affect the width for a block caret.</p>
2843 <p><b id="SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useHotSpotForeColour, int <a class="jump"
2846 <b id="SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useHotSpotBackColour, int <a class="jump"
2853 While the cursor hovers over text in a style with the hotspot attribute set,
2854 the default colouring can be modified and an underline drawn with these settings.
2855 Single line mode stops a hotspot from wrapping onto next line.</p>
2860 These messages set, get or toggle the caretSticky setting which controls when the last position
2861 of the caret on the line is saved.</p>
2864 (and all caret position changes) will remember the
2865 caret's new horizontal position when moving to different lines. This is the default.</p>
2867 <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
2868 horizontal caret position is moving the caret with mouse or keyboard (left/right arrow keys, home/end keys, etc). </p>
2870 <p>When set to <code>SC_CARETSTICKY_WHITESPACE</code> (2), the caret acts like mode 0 (sticky off) except under one
2871 special case; when space or tab characters are inserted. (Including pasting <b>only space/tabs</b> -- undo, redo,
2872 etc. do not exhibit this behaviour..).</p>
2874 <p><code>SCI_TOGGLECARETSTICKY</code> switches from <code>SC_CARETSTICKY_ON</code> and <code>SC_CARETSTICKY_WHITESPACE</code>
2875 to <code>SC_CARETSTICKY_OFF</code> and from <code>SC_CARETSTICKY_OFF</code> to <code>SC_CARETSTICKY_ON</code>.</p>
2879 <p>Some characters, such as control characters and invalid bytes, do not have a visual glyph or use a glyph that is hard to distinguish.</p>
2881 <p>Control characters (characters with codes less than 32, or between 128 and 159 in some encodings)
2882 are displayed by Scintilla using their mnemonics inverted in a rounded rectangle. These mnemonics come from the
2883 early days of signalling, though some are still used (LF = Line Feed, BS = Back Space, CR =
2884 Carriage Return, for example).</p>
2890 <p>For the high 'C1' values:
2896 <p>Invalid bytes are shown in a similar way with an 'x' followed by their value in hexadecimal, like "xFE".</p>
2898 <code>
2899 <a class="message" href="#SCI_SETREPRESENTATION">SCI_SETREPRESENTATION(const char *encodedCharacter, const char *representation)</a><br />
2900 <a class="message" href="#SCI_GETREPRESENTATION">SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation)</a><br />
2901 <a class="message" href="#SCI_CLEARREPRESENTATION">SCI_CLEARREPRESENTATION(const char *encodedCharacter)</a><br />
2902 <a class="message" href="#SCI_SETCONTROLCHARSYMBOL">SCI_SETCONTROLCHARSYMBOL(int symbol)</a><br />
2904 </code>
2906 <p><b id="SCI_SETREPRESENTATION">SCI_SETREPRESENTATION(const char *encodedCharacter, const char *representation)</b><br />
2907 <b id="SCI_GETREPRESENTATION">SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation NUL-terminated)</b><br />
2908 <b id="SCI_CLEARREPRESENTATION">SCI_CLEARREPRESENTATION(const char *encodedCharacter)</b><br />
2909 Any character, including those normally displayed as mnemonics may be represented by a
2910 string inverted in a rounded rectangle.</p>
2912 <p>For example, the Ohm sign Ω U+2126 looks very similar to the Greek Omega character Ω U+03C9 so,
2913 for the UTF-8 encoding, to distinguish the Ohm sign as "U+2126 Ω" this call could be made:
2916 <p>The encodedCharacter parameter is a NUL-terminated string of the bytes for one character in the
2917 current encoding. This can not be used to set a representation for multiple-character strings. </p>
2919 <p>The NUL (0) character is a special case since the encodedCharacter parameter is NUL terminated, the NUL
2920 character is specified as an empty string.</p>
2924 The mnemonics may be replaced by a nominated symbol with an ASCII code in the
2926 as mnemonics. The symbol you set is rendered in the font of the style set for the character.
2933 to the left of the text display, plus a gap either side of
2934 the text. Each margin can be set to display only symbols, line numbers, or text with <a
2936 Textual margins may also display symbols.
2937 The markers
2939 href="#SCI_SETMARGINMASKN"><code>SCI_SETMARGINMASKN</code></a>. Any markers not associated with
2940 a visible margin will be displayed as changes in background colour in the text. A width in
2941 pixels can be set for each margin. Margins with a zero width are ignored completely. You can
2944 selects a line of text.</p>
2948 is hidden. Margin 1 is set to display non-folding symbols and is given a width of 16 pixels, so
2949 it is visible. Margin 2 is set to display the folding symbols, but is given a width of 0, so it
2950 is hidden. Of course, you can set the margins to be whatever you wish.</p>
2953 <p><img src="styledmargin.png" alt="Styled text margins used to show revision and blame information" /></p>
2956 type)</a><br />
2959 pixelWidth)</a><br />
2962 mask)</a><br />
2965 sensitive)</a><br />
2967 margin)</a><br />
2969 cursor)</a><br />
2971 margin)</a><br />
2973 pixels)</a><br />
2976 pixels)</a><br />
2978 <a class="message" href="#SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</a><br />
2979 <a class="message" href="#SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</a><br />
2982 <a class="message" href="#SCI_MARGINSETSTYLE">SCI_MARGINSETSTYLE(int line, int style)</a><br />
2984 <a class="message" href="#SCI_MARGINSETSTYLES">SCI_MARGINSETSTYLES(int line, char *styles)</a><br />
2985 <a class="message" href="#SCI_MARGINGETSTYLES">SCI_MARGINGETSTYLES(int line, char *styles)</a><br />
2987 <a class="message" href="#SCI_MARGINSETSTYLEOFFSET">SCI_MARGINSETSTYLEOFFSET(int style)</a><br />
2989 <a class="message" href="#SCI_SETMARGINOPTIONS">SCI_SETMARGINOPTIONS(int marginOptions)</a><br />
2991 </code>
2995 These two routines set and get the type of a margin. The margin argument should be 0, 1, 2, 3 or 4.
3000 By convention, margin 0 is used for line numbers and the next two are used for symbols. You can
3002 symbol margins that set their background colour to match the STYLE_DEFAULT background and
3003 foreground colours.</p>
3007 These routines set and get the width of a margin in pixels. A margin with zero width is
3009 is a reasonable guess if you are not sure what would be appropriate. Line number margins widths
3010 should take into account the number of lines in the document and the line number style. You
3013 suitable width.</p>
3018 displayed in a margin that is enabled for symbols. There is a useful constant,
3020 symbols used to denote folding. You can assign a wide range of symbols and colours to each of
3021 the 32 logical symbols, see <a href="#Markers">Markers</a> for more information. If <code>(mask
3027 does not appear in the mask of any margin with a non-zero width, the marker changes the
3028 background colour of the line. For example, suppose you decide to use logical marker 10 to mark
3029 lines with a syntax error and you want to show such lines by changing the background colour.
3031 sure that no symbol margin includes 0x400 in its mask, any line with the marker gets the
3032 background colour changed.</p>
3035 which is the default set by Scintilla.
3038 decimal. Of course, you may need to display all 32 symbols in a margin, in which case use
3042 sensitive)</b><br />
3044 Each of the five margins can be set sensitive or insensitive to mouse clicks. A click in a
3048 selection margins which make it easy to select ranges of lines. By default, all margins are
3049 insensitive.</p>
3052 cursor)</b><br />
3054 A reversed arrow cursor is normally shown over all margins. This may be changed to a normal arrow with
3056 reversed arrow with
3063 These messages set and get the width of the blank margin on both sides of the text in pixels.
3064 The default is to one pixel on each side.</p>
3066 <p><b id="SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</b><br />
3067 <b id="SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</b><br />
3068 These messages allow changing the colour of the fold margin and fold margin highlight.
3069 On Windows the fold margin colour defaults to ::GetSysColor(COLOR_3DFACE) and the fold margin highlight
3070 colour to ::GetSysColor(COLOR_3DHIGHLIGHT).</p>
3072 <p>
3080 Text margins are created with the type SC_MARGIN_TEXT or SC_MARGIN_RTEXT.
3082 The whole of the text margin on a line may be displayed in a particular style with
3086 Setting a text margin will cause a
3088 notification to be sent.
3089 </p>
3090 <p>
3091 Only some style attributes are active in text margins: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
3092 </p>
3093 <p>
3096 Margin styles may be completely separated from standard text styles by setting a style offset. For example,
3098 256 up to 511 so they do not overlap styles set by lexers. Each style number set with <code>SCI_MARGINSETSTYLE</code>
3100 </p>
3101 <p>
3102 Always call <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES</a>
3103 before <code>SCI_MARGINSETSTYLEOFFSET</code> and use the result as the argument to <code>SCI_MARGINSETSTYLEOFFSET</code>.
3104 </p>
3105 <p>
3108 Define margin options by enabling appropriate bit flags. At the moment, only one flag is available
3109 <code>SC_MARGINOPTION_SUBLINESELECT</code>=1, which controls how wrapped lines are selected when clicking
3110 on margin in front of them. If <code>SC_MARGINOPTION_SUBLINESELECT</code> is set only sub line of wrapped
3111 line is selected, otherwise whole wrapped line is selected. Margin options are set to
3113 </p>
3117 <p>Annotations are read-only lines of text underneath each line of editable text.
3118 An annotation may consist of multiple lines separated by '\n'.
3119 Annotations can be used to display an assembler version of code for debugging or to show diagnostic messages inline or to
3120 line up different versions of text in a merge tool.</p>
3121 <p>Annotations count as display lines for the methods
3127 <code>
3128 <a class="message" href="#SCI_ANNOTATIONSETTEXT">SCI_ANNOTATIONSETTEXT(int line, char *text)</a><br />
3129 <a class="message" href="#SCI_ANNOTATIONGETTEXT">SCI_ANNOTATIONGETTEXT(int line, char *text)</a><br />
3130 <a class="message" href="#SCI_ANNOTATIONSETSTYLE">SCI_ANNOTATIONSETSTYLE(int line, int style)</a><br />
3132 <a class="message" href="#SCI_ANNOTATIONSETSTYLES">SCI_ANNOTATIONSETSTYLES(int line, char *styles)</a><br />
3133 <a class="message" href="#SCI_ANNOTATIONGETSTYLES">SCI_ANNOTATIONGETSTYLES(int line, char *styles)</a><br />
3136 <a class="message" href="#SCI_ANNOTATIONSETVISIBLE">SCI_ANNOTATIONSETVISIBLE(int visible)</a><br />
3138 <a class="message" href="#SCI_ANNOTATIONSETSTYLEOFFSET">SCI_ANNOTATIONSETSTYLEOFFSET(int style)</a><br />
3140 </code>
3142 <p>
3153 The whole of the text ANNOTATION on a line may be displayed in a particular style with
3155 <code>SCI_ANNOTATIONSETSTYLES</code> which uses an array of bytes with each byte setting the style
3156 of the corresponding text byte similar to <code>SCI_SETSTYLINGEX</code>. The text must be set first as it
3157 specifies how long the annotation is so how many bytes of styling to read.
3158 Setting an annotation will cause a
3160 notification to be sent.
3161 </p>
3162 <p>
3163 The number of lines annotating a line can be retrieved with <code>SCI_ANNOTATIONGETLINES</code>.
3165 which is equivalent to clearing each line (setting to 0) and then deleting other memory used for this feature.
3166 </p>
3167 <p>
3168 Only some style attributes are active in annotations: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
3169 </p>
3170 <p>
3173 Annotations can be made visible in a view and there is a choice of display style when visible.
3175 argument can be one of:</p>
3179 <tr>
3185 </tr>
3187 <tr>
3193 </tr>
3195 <tr>
3201 </tr>
3203 <tr>
3209 </tr>
3210 </tbody>
3211 </table>
3213 <p>
3216 Annotation styles may be completely separated from standard text styles by setting a style offset. For example,
3217 <code>SCI_ANNOTATIONSETSTYLEOFFSET(512)</code> would allow the annotation styles to be numbered from
3218 512 up to 767 so they do not overlap styles set by lexers (or margins if margins offset is 256).
3221 </p>
3222 <p>
3223 Always call <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES</a>
3224 before <code>SCI_ANNOTATIONSETSTYLEOFFSET</code> and use the result as the argument to <code>SCI_ANNOTATIONSETSTYLEOFFSET</code>.
3225 </p>
3228 <code>
3241 <a class="message" href="#SCI_SETIMEINTERACTION">SCI_SETIMEINTERACTION(int imeInteraction)</a><br />
3243 <a class="message" href="#SCI_SETWORDCHARS">SCI_SETWORDCHARS(<unused>, const char *characters)</a><br />
3244 <a class="message" href="#SCI_GETWORDCHARS">SCI_GETWORDCHARS(<unused>, char *characters)</a><br />
3245 <a class="message" href="#SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</a><br />
3246 <a class="message" href="#SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</a><br />
3247 <a class="message" href="#SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</a><br />
3248 <a class="message" href="#SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</a><br />
3253 </code>
3257 the handle to the Scintilla window you created as your editor.</p>
3259 <p>While we are on the subject of forwarding messages in Windows, the top level window should
3261 collect changes to mouse settings, but could be used for other user interface items in the
3262 future).</p>
3266 These messages turn buffered drawing on or off and report the buffered drawing state. Buffered
3267 drawing draws each line into a bitmap rather than directly to the screen and then copies the
3268 bitmap to the screen. This avoids flickering although it does take longer. The default is for
3269 drawing to be buffered.</p>
3273 There are several orders in which the text area may be drawn offering a trade-off between speed
3274 and allowing all pixels of text to be seen even when they overlap other elements.</p>
3276 run of characters in one style is drawn along with its background.
3277 If a character overhangs the end of a run, such as in "<i>V</i>_" where the
3280 cuts it off.</p>
3282 fixes this by drawing all the backgrounds of a line first and then drawing the text
3283 in transparent mode. Lines are drawn separately and no line will overlap another
3284 so any pixels that overlap into another line such as extreme ascenders and
3285 descenders on characters will be cut off.
3286 Two phase drawing may flicker more than single phase
3287 unless buffered drawing is on or the platform is naturally buffered.
3288 The default is for drawing to be two phase.</p>
3290 draws the whole area multiple times, once for each feature, building up the
3291 the appearance in layers or phases. The coloured backgrounds for all lines are
3292 drawn before any text and then all the text is drawn in transparent mode over this
3293 combined background without clipping text to the line boundaries. This allows
3294 extreme ascenders and descenders to overflow into the adjacent lines.
3296 if buffered drawing is turned on.
3297 Multiple phase drawing is slower than two phase drawing.
3299 or higher can ensure that multiple phase drawing is not significantly slower.</p>
3303 This property has been replaced with the preceding PHASESDRAW property which is more general,
3304 allowing multiple phase drawing as well as one and two phase drawing.</p>
3308 The technology property allows choosing between different drawing APIs and options.
3313 can be chosen to use the Direct2D and DirectWrite APIs for higher quality antialiased drawing.
3316 is retained after being presented which may prevent drawing failures on some cards and drivers.
3319 Since Direct2D buffers drawing, Scintilla's buffering can be turned off with
3323 are provisional, they may be changed or removed in a future release if a better solution is found.</span></p>
3327 Manage font quality (antialiasing method). Currently, the following values are available on Windows:
3332 <p>In case it is necessary to squeeze more options into this property, only a limited number of bits defined
3337 Scintilla has some support for Japanese, Chinese and Korean DBCS. Use this message with
3338 <code>codePage</code> set to the code page number to set Scintilla to use code page information
3339 to ensure double byte characters are treated as one character rather than two. This also stops
3340 the caret from moving between the two bytes in a double byte character.
3341 Do not use this message to choose between different single byte character sets: it doesn't do that.
3342 Call with
3346 <p>Code page <code>SC_CP_UTF8</code> (65001) sets Scintilla into Unicode mode with the document
3347 treated as a sequence of characters expressed in UTF-8. The text is converted to the platform's
3348 normal Unicode encoding before being drawn by the OS and thus can display Hebrew, Arabic,
3349 Cyrillic, and Han characters. Languages which can use two characters stacked vertically in one
3350 horizontal space, such as Thai, will mostly work but there are some issues where the characters
3351 are drawn separately leading to visual glitches. Bi-directional text is not supported. </p>
3355 although these may require installation of language specific support.</p>
3359 When entering text in Chinese, Japanese, or Korean an Input Method Editor (IME) may be displayed.
3360 The IME may be an extra window appearing above Scintilla or may be displayed by Scintilla itself
3361 as text. On some platforms there is a choice between the two techniques.
3363 behaviour to the IME in other applications.
3364 An inline IME <code>SC_IME_INLINE</code> (1) may work better with some Scintilla features such as
3365 rectangular and multiple selection.</p>
3366 <p>The windowed behaviour can be chosen with <code>SCI_SETIMEINTERACTION(SC_IME_WINDOWED)</code>
3368 Scintilla may ignore this call in some cases. For example, the inline behaviour might only be supported for some languages.</p>
3371 Scintilla has several functions that operate on words, which are defined to be contiguous
3372 sequences of characters from a particular set of characters. This message defines which
3373 characters are members of that set. The character sets are set to default values before processing this
3374 function.
3375 For example, if you don't allow '_' in your set of characters
3376 use:<br />
3377 <code>SCI_SETWORDCHARS(0, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")</code>;</p>
3380 This fills the characters parameter with all the characters included in words.
3381 The characters parameter must be large enough to hold all of the characters.
3382 If the characters parameter is 0 then the length that should be allocated
3383 to store the entire set is returned.</p>
3385 <p><b id="SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</b><br />
3386 <b id="SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</b><br />
3387 Similar to <code>SCI_SETWORDCHARS</code>, this message allows the user to define which chars Scintilla considers
3388 as whitespace. Setting the whitespace chars allows the user to fine-tune Scintilla's behaviour doing
3389 such things as moving the cursor to the start or end of a word; for example, by defining punctuation chars
3390 as whitespace, they will be skipped over when the user presses ctrl+left or ctrl+right.
3392 reset the whitespace characters to the default set.
3395 <p><b id="SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</b><br />
3396 <b id="SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</b><br />
3398 allows the user to define which chars Scintilla considers as punctuation.
3402 Use the default sets of word and whitespace characters. This sets whitespace to space, tab and other
3403 characters with codes less than 0x20, with word characters set to alphanumeric and '_'.
3404 </p>
3410 Scintilla can be told to grab the focus with this message. This is needed more on GTK+ where
3411 focus handling is more complicated than on Windows.</p>
3414 that have complex focus requirements such as having their own window that gets the real focus
3415 but with the need to indicate that Scintilla has the logical focus.</p>
3419 pos2)</a><br />
3421 <a class="message" href="#SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</a><br />
3422 <a class="message" href="#SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</a><br />
3424 maxReStyle)</a><br />
3425 </code>
3428 Up to two characters can be highlighted in a 'brace highlighting style', which is defined as
3429 style number <a class="message" href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34).
3430 If you have enabled indent guides, you may also wish to highlight the indent that corresponds
3439 highlight.</p>
3441 <p><b id="SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</b><br />
3442 Use specified indicator to highlight matching braces instead of changing their style.</p>
3444 <p><b id="SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</b><br />
3445 Use specified indicator to highlight non matching brace instead of changing its style.</p>
3451 from a closing brace. If the character at position is not a brace character, or a matching
3452 brace cannot be found, the return value is -1. Otherwise, the return value is the position of
3453 the matching brace.</p>
3455 <p>A match only occurs if the style of the matching brace is the same as the starting brace or
3456 the matching brace is beyond the end of styling. Nested braces are handled correctly. The
3458 the length of brace searches.</p>
3462 <p>Indentation (the white space at the start of a line) is often used by programmers to clarify
3463 program structure and in some languages, for example Python, it may be part of the language
3464 syntax. Tabs are normally used in editors to insert a tab character or to pad text with spaces
3465 up to the next tab.</p>
3467 <p>When Scintilla is laying out a section of text, text after a tab character will usually be
3468 displayed at the next multiple of TABWIDTH columns from the left. However, it is also possible
3469 to explicitly set tabstops in pixels for each line.</p>
3471 <p>Scintilla can be set to treat tab and backspace in the white space at the start of a line in
3472 a special way: inserting a tab indents the line to the next indent position rather than just
3473 inserting a tab at the current character position and backspace unindents the line rather than
3474 deleting a character. Scintilla can also display indentation guides (vertical lines) to help
3475 you to generate code.</p>
3488 bsUnIndents)</a><br />
3491 indentation)</a><br />
3494 line)</a><br />
3495 <a class="message" href="#SCI_SETINDENTATIONGUIDES">SCI_SETINDENTATIONGUIDES(int indentView)</a><br />
3499 </code>
3511 adds an explicit tabstop at the specified distance from the left (in pixels), and
3512 <code>SCI_GETNEXTTABSTOP</code> gets the next explicit tabstop position set after the given x position,
3513 or zero if there aren't any.
3514 Changing tab stops produces a <a class="message" href="#SC_MOD_CHANGETABSTOPS">SC_MOD_CHANGETABSTOPS</a> notification.
3515 </p>
3520 of tabs and spaces or be based purely on spaces. Set <code>useTabs</code> to <code>false</code>
3521 (0) to create all tabs and indents out of spaces. The default is <code>true</code>. You can use
3523 position taking the width of a tab into account.</p>
3528 0, the indent size is the same as the tab size. There are no limits on indent sizes, but values
3529 less than 0 or large values may have undesirable effects.
3530 </p>
3536 </p>
3538 <p>Inside indentation white space, the tab and backspace keys can be made to indent and
3539 unindent rather than insert a tab character or delete a character with the
3544 The amount of indentation on a line can be discovered and set with
3545 <code>SCI_GETLINEINDENTATION</code> and <code>SCI_SETLINEINDENTATION</code>. The indentation is
3546 measured in character columns, which correspond to the width of space characters.</p>
3549 This returns the position at the end of indentation of a line.</p>
3553 Indentation guides are dotted vertical lines that appear within indentation white space every
3554 indent size columns. They make it easy to see which constructs line up especially when they
3557 foreground and background colour of the indentation guides.</p>
3560 SC_IV_NONE turns the feature off but the other 3 states determine how far the guides appear on
3561 empty lines. </p>
3563 <tbody>
3564 <tr>
3567 </tr>
3569 <tr>
3572 </tr>
3574 <tr>
3576 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3577 next non-empty line.
3578 If the previous non-empty line was a fold header then indentation guides are shown for
3579 one more level of indent than that line. This setting is good for Python.</td>
3580 </tr>
3582 <tr>
3584 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3585 next non-empty line or previous non-empty line whichever is the greater.
3586 This setting is good for most languages.</td>
3587 </tr>
3589 </tbody>
3590 </table>
3594 When brace highlighting occurs, the indentation guide corresponding to the braces may be
3596 href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34). Set <code>column</code> to 0 to
3597 cancel this highlight.</p>
3601 <p>There are 32 markers, numbered 0 to <code>MARKER_MAX</code> (31), and you can assign any combination of them to each
3603 margin</a> to the left of the text. If the selection margin is set to zero width, the
3609 or the current point of execution, break points, or whatever you need marking. If you do not
3612 <p>Each marker number has a symbol associated with it. You can also set the foreground and
3613 background colour for each marker number, so you can use the same symbol more than once with
3614 different colouring for different uses. Scintilla has a set of symbols you can assign
3618 <p>The markers are drawn in the order of their numbers, so higher numbered markers appear on
3619 top of lower numbered ones. Markers try to move with their text by tracking where the start of
3621 operation, with the markers of the next line.</p>
3623 markerSymbols)</a><br />
3625 const char *xpm)</a><br />
3628 <a class="message" href="#SCI_RGBAIMAGESETSCALE">SCI_RGBAIMAGESETSCALE(int scalePercent)</a><br />
3629 <a class="message" href="#SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber,
3630 const char *pixels)</a><br />
3632 </a><br />
3634 colour)</a><br />
3636 colour)</a><br />
3637 <a class="message" href="#SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int
3638 colour)</a><br />
3639 <a class="message" href="#SCI_MARKERENABLEHIGHLIGHT">SCI_MARKERENABLEHIGHLIGHT(int enabled)</a><br />
3641 alpha)</a><br />
3643 <a class="message" href="#SCI_MARKERADDSET">SCI_MARKERADDSET(int line, int markerMask)</a><br />
3645 markerNumber)</a><br />
3649 markerMask)</a><br />
3651 markerMask)</a><br />
3653 handle)</a><br />
3655 </code>
3659 an ASCII character. The general-purpose marker symbols currently available are:<br />
3676 </p>
3679 The <code>SC_MARK_FULLRECT</code> symbol mirrors this, changing only the margin background colour.
3682 of lines. You would also use it if you changed the folding style and wanted one or more of the
3686 plugins may allocate that marker number.
3687 </p>
3689 <p>There are also marker symbols designed for use in the folding margin in a flattened tree
3690 style.<br />
3704 Characters can be used as markers by adding the ASCII value of the character to
3709 <p>The marker numbers <code>SC_MARKNUM_FOLDER</code> and <code>SC_MARKNUM_FOLDEROPEN</code> are
3710 used for showing that a fold is present and open or closed. Any symbols may be assigned for
3713 these two, more assignments are needed for the flattened tree style:
3722 Macintosh), plus/minus shows folded lines as '+' and opened folds as '-', Circle tree, Box
3723 tree.</p>
3727 <tr>
3737 </tr>
3738 </thead>
3741 <tr>
3751 </tr>
3753 <tr>
3763 </tr>
3765 <tr>
3775 </tr>
3777 <tr>
3787 </tr>
3789 <tr>
3799 </tr>
3801 <tr>
3811 </tr>
3813 <tr>
3823 </tr>
3824 </tbody>
3825 </table>
3829 *xpm)</b><br />
3830 Markers can be set to pixmaps with this message. The
3834 <p>
3838 <b id="SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber, const char *pixels)</b><br />
3839 Markers can be set to translucent pixmaps with this message. The
3843 <p>A scale factor in percent may be set with <code>SCI_RGBAIMAGESETSCALE</code>. This is useful on OS X with
3844 a retina display where each display unit is 2 pixels: use a factor of 200 so that each image pixel is displayed using a screen pixel.
3845 The default scale, 100, will stretch each image pixel to cover 4 screen pixels on a retina display.</p>
3857 These two messages set the foreground and background colour of a marker number.<br />
3858 <b id="SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int <a class="jump"
3860 This message sets the highlight background colour of a marker number when its folding block is selected. The default colour is #FF0000.</p>
3862 This message allows to enable/disable the highlight folding block when it is selected. (i.e. block that contains the caret)</p>
3865 When markers are drawn in the content area, either because there is no margin for them or
3866 they are of <code>SC_MARK_BACKGROUND</code> or <code>SC_MARK_UNDERLINE</code> types, they may be drawn translucently by
3867 setting an alpha value.</p>
3871 this fails (illegal line number, out of memory) or it returns a marker handle number that
3876 based on its handle. The message does not check the value of markerNumber, nor does it
3877 check if the line already contains the marker.</p>
3880 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
3882 (and used by the mask-based marker search functions
3885 As with
3887 to see if any of the markers are already present on the targeted line.</p>
3890 This searches the given line number for the given marker number and deletes it if it is
3891 present. If you added the same marker more than once to the line, this will delete one copy
3892 each time it is used. If you pass in a marker number of -1, all markers are deleted from the
3893 line.</p>
3896 This removes markers of the given number from all lines. If markerNumber is -1, it deletes all
3897 markers from all lines.</p>
3905 These messages search efficiently for lines that include a given set of markers. The search
3908 (<code>SCI_MARKERPREVIOUS</code>). The <code>markerMask</code> argument should have one bit set
3909 for each marker you wish to find. Set bit 0 to find marker 0, bit 1 for marker 1 and so on. The
3910 message returns the line number of the first line that contains one of the markers in
3916 the document for the marker with this handle and returns the line number that contains it or -1
3917 if it is not found.</p>
3922 the document for the marker with this handle and deletes the marker if it is found.</p>
3926 <p>Indicators are used to display additional information over the top of styling.
3927 They can be used to show, for example, syntax errors, deprecated names and bad indentation
3928 by drawing underlines under text or boxes around text.</p>
3930 <p>Indicators may have a different "hover" colour and style when the mouse is over them or the caret is moved into them.
3931 This may be used, for example, to indicate that a URL can be clicked.</p>
3933 <p>Indicators may be displayed as simple underlines, squiggly underlines, a
3934 line of small 'T' shapes, a line of diagonal hatching, a strike-out or a rectangle around the text.
3935 They may also be invisible when used to track pieces of content for the application as <code>INDIC_HIDDEN</code>.</p>
3938 indicators. They all use an <code>indicatorNumber</code> argument in the range 0 to INDIC_MAX(35)
3939 to set the indicator to style. To prevent interference the set of indicators is divided up into a range for use
3942 and a range for IME indicators (32=<code>INDIC_IME</code> .. 35=<code>INDIC_IME_MAX</code>).</p>
3944 <p>Indicators are stored in a format similar to run length encoding which is efficient in both
3945 speed and storage for sparse information.</p>
3946 <p>An indicator may store different values for each range but currently all values are drawn the same.
3947 In the future, it may be possible to draw different values in different styles.</p>
3949 <p>Originally, Scintilla used a different technique for indicators but this
3952 While both techniques were supported, the term "modern indicators" was used for the
3953 newer implementation.</p>
3956 indicatorStyle)</a><br />
3959 colour)</a><br />
3961 <a class="message" href="#SCI_INDICSETALPHA">SCI_INDICSETALPHA(int indicatorNumber, int alpha)</a><br />
3963 <a class="message" href="#SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</a><br />
3964 <a class="message" href="#SCI_INDICGETOUTLINEALPHA">SCI_INDICGETOUTLINEALPHA(int indicatorNumber)</a><br />
3965 <a class="message" href="#SCI_INDICSETUNDER">SCI_INDICSETUNDER(int indicatorNumber, bool under)</a><br />
3967 <a class="message" href="#SCI_INDICSETHOVERSTYLE">SCI_INDICSETHOVERSTYLE(int indicatorNumber, int
3968 indicatorStyle)</a><br />
3969 <a class="message" href="#SCI_INDICGETHOVERSTYLE">SCI_INDICGETHOVERSTYLE(int indicatorNumber)</a><br />
3970 <a class="message" href="#SCI_INDICSETHOVERFORE">SCI_INDICSETHOVERFORE(int indicatorNumber, int
3971 colour)</a><br />
3972 <a class="message" href="#SCI_INDICGETHOVERFORE">SCI_INDICGETHOVERFORE(int indicatorNumber)</a><br />
3973 <a class="message" href="#SCI_INDICSETFLAGS">SCI_INDICSETFLAGS(int indicatorNumber, int flags)</a><br />
3975 <br />
3977 <a class="message" href="#SCI_SETINDICATORCURRENT">SCI_SETINDICATORCURRENT(int indicator)</a><br />
3981 <a class="message" href="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE(int position, int fillLength)</a><br />
3982 <a class="message" href="#SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</a><br />
3984 <a class="message" href="#SCI_INDICATORVALUEAT">SCI_INDICATORVALUEAT(int indicator, int position)</a><br />
3985 <a class="message" href="#SCI_INDICATORSTART">SCI_INDICATORSTART(int indicator, int position)</a><br />
3986 <a class="message" href="#SCI_INDICATOREND">SCI_INDICATOREND(int indicator, int position)</a><br />
3988 <a class="message" href="#SCI_FINDINDICATORSHOW">SCI_FINDINDICATORSHOW(int start, int end)</a><br />
3989 <a class="message" href="#SCI_FINDINDICATORFLASH">SCI_FINDINDICATORFLASH(int start, int end)</a><br />
3991 </code>
3994 indicatorStyle)</b><br />
3996 These two messages set and get the style for a particular indicator. The indicator styles
3997 currently available are:<br />
4002 <tbody>
4003 <tr>
4009 </tr>
4010 </tbody>
4013 <tr>
4019 </tr>
4021 <tr>
4027 </tr>
4029 <tr>
4035 </tr>
4037 <tr>
4043 </tr>
4045 <tr>
4051 </tr>
4053 <tr>
4059 </tr>
4061 <tr>
4067 </tr>
4069 <tr>
4074 <td>A rectangle with rounded corners around the text using translucent drawing with the
4075 interior usually more transparent than the border. You can use
4078 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
4079 </tr>
4081 <tr>
4086 <td>A rectangle around the text using translucent drawing with the
4087 interior usually more transparent than the border. You can use
4090 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.
4091 This indicator does not colour the top pixel of the line so that indicators on contiguous lines are visually distinct
4092 and disconnected.</td>
4093 </tr>
4095 <tr>
4100 <td>A rectangle around the text using translucent drawing similar to <code>INDIC_STRAIGHTBOX</code>
4101 but covering the entire character area.</td>
4102 </tr>
4104 <tr>
4110 </tr>
4112 <tr>
4118 </tr>
4120 <tr>
4126 so will fit under small fonts.</td>
4127 </tr>
4129 <tr>
4134 <td>A dotted rectangle around the text using translucent drawing.
4135 Translucency alternates between the alpha and outline alpha settings with the top-left pixel using the alpha setting.
4138 control the alpha transparency values. The default values are 30 for alpha and 50 for outline alpha.
4140 </tr>
4142 <tr>
4148 as a series of line segments for performance.
4151 </tr>
4153 <tr>
4158 <td>A 2-pixel thick underline located at the bottom of the line to try to avoid touching the character base.
4159 Each side is inset 1 pixel so that different indicators in this style covering a range appear isolated.
4160 This is similar to an appearance used for the target in Asian language input composition.</td>
4161 </tr>
4163 <tr>
4169 Each side is inset 1 pixel so that different indicators in this style covering a range appear isolated.
4170 This is similar to an appearance used for non-target ranges in Asian language input composition.</td>
4171 </tr>
4173 <tr>
4179 </tr>
4181 </tbody>
4182 </table>
4189 <p><b id="SCI_INDICSETFORE">SCI_INDICSETFORE(int indicatorNumber, int <a class="jump" href="#colour">colour</a>)</b><br />
4191 These two messages set and get the colour used to draw an indicator. The default indicator
4192 colours are equivalent to:<br />
4199 These two messages set and get the alpha transparency used for drawing the
4200 fill colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
4202 </p>
4204 <p><b id="SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</b><br />
4206 These two messages set and get the alpha transparency used for drawing the
4207 outline colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
4209 </p>
4213 These two messages set and get whether an indicator is drawn under text or over(default).
4214 Drawing under text works only for indicators when <a class="message" href="#SCI_SETTWOPHASEDRAW">two phase drawing</a>
4215 is enabled.</p>
4218 indicatorStyle)</b><br />
4220 <b id="SCI_INDICSETHOVERFORE">SCI_INDICSETHOVERFORE(int indicatorNumber, int <a class="jump" href="#colour">colour</a>)</b><br />
4222 These messages set and get the colour and style used to draw indicators when the mouse is over them or the caret moved into them.
4223 The mouse cursor also changes when an indicator is drawn in hover style.
4224 The default is for the hover appearance to be the same as the normal appearance and calling
4227 also reset the hover attribute.</p>
4231 These messages set and get the flags associated with an indicator.
4232 There is currently one flag defined, <code>SC_INDICFLAG_VALUEFORE</code>: when this flag is set
4233 the colour used by the indicator is not from the indicator's fore setting but instead from the value of the indicator at
4234 that point in the file. This allows many colours to be displayed for a single indicator. The value is an <a class="jump"
4235 href="#colour">RGB integer colour</a> that has been ored with <code>SC_INDICVALUEBIT</code>(0x1000000)
4237 To find the colour from the value, and the value with <code>SC_INDICVALUEMASK</code>(0xFFFFFF).
4238 </p>
4240 <p>
4243 These two messages set and get the indicator that will be affected by calls to
4244 <a class="message" href="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE(int position, int fillLength)</a> and
4245 <a class="message" href="#SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</a>.
4246 </p>
4248 <p>
4251 These two messages set and get the value that will be set by calls to
4253 </p>
4255 <p>
4257 <b id="SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</b><br />
4258 These two messages fill or clear a range for the current indicator.
4260 the current value.
4261 </p>
4263 <p>
4265 Retrieve a bitmap value representing which indicators are non-zero at a position.
4266 Only the first 32 indicators are represented in the result so no IME indicators are included.
4267 </p>
4269 <p>
4271 Retrieve the value of a particular indicator at a position.
4272 </p>
4274 <p>
4277 Find the start or end of a range with one value from a position within the range.
4278 Can be used to iterate through the document to discover all the indicator positions.
4279 </p>
4283 <p>On OS X search matches are highlighted with an animated gold rounded rectangle.
4284 The indicator shows, then briefly grows 25% and shrinks to the original size to draw the user's attention.
4285 While this feature is currently only implemented on OS X, it may be implemented on other platforms
4286 in the future.</p>
4290 These two messages show and animate the find indicator. The indicator remains visible with
4293 <code>SCI_FINDINDICATORSHOW</code> behaves similarly to the OS X TextEdit and Safari applications
4294 and is best suited to editing documentation where the search target is often a word.
4296 where the match will often be located next to operators which would otherwise be hidden under the indicator's
4297 padding.
4298 </p>
4301 This message hides the find indicator.
4302 </p>
4304 <p>Earlier versions of Scintilla allowed <a href="#StyleByteIndicators">partitioning style bytes</a>
4305 between style numbers and indicators and provided APIs for setting and querying this.</p>
4310 <p>Autocompletion displays a list box showing likely identifiers based upon the user's typing.
4311 The user chooses the currently selected item by pressing the tab character or another character
4313 Autocompletion is triggered by your application. For example, in C if you detect that the user
4315 list of members, you could offer them in an autocompletion list. Alternatively, you could
4316 monitor the user's typing and offer a list of likely items once their typing has narrowed down
4317 the choice to a reasonable list. As yet another alternative, you could define a key code to
4318 activate the list.</p>
4320 <p>When the user makes a selection from the list the container is sent a <code><a class="message"
4322 href="#Notifications">notification message</a>. On return from the notification Scintilla will insert
4323 the selected text unless the autocompletion list has been cancelled, for example by the container sending
4326 <p>To make use of autocompletion you must monitor each character added to the document. See
4329 *list)</a><br />
4335 *chars)</a><br />
4337 separator)</a><br />
4340 *select)</a><br />
4343 char *text)</a><br />
4345 cancel)</a><br />
4348 *chars)</a><br />
4350 chooseSingle)</a><br />
4353 ignoreCase)</a><br />
4355 <a class="message" href="#SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</a><br />
4356 <a class="message" href="#SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR</a><br />
4364 dropRestOfWord)</a><br />
4366 <a class="message" href="#SCI_REGISTERIMAGE">SCI_REGISTERIMAGE(int type, const char *xpmData)</a><br />
4367 <a class="message" href="#SCI_REGISTERRGBAIMAGE">SCI_REGISTERRGBAIMAGE(int type, const char *pixels)</a><br />
4369 <a class="message" href="#SCI_AUTOCSETTYPESEPARATOR">SCI_AUTOCSETTYPESEPARATOR(char separatorCharacter)</a><br />
4373 <a class="message" href="#SCI_AUTOCSETMAXWIDTH">SCI_AUTOCSETMAXWIDTH(int characterCount)</a><br />
4375 </code>
4380 separator characters. The initial separator character is a space but this can be set or got
4385 <p>With default settings, the list of words should be in sorted order.
4386 If set to ignore case mode with <a class="message" href="#SCI_AUTOCSETIGNORECASE"><code>SCI_AUTOCSETIGNORECASE</code></a>, then
4387 strings are matched after being converted to upper case. One result of this is that the list
4388 should be sorted with the punctuation characters '[', '\', ']', '^', '_', and '`' sorted after
4389 letters.
4390 Alternative handling of list order may be specified with <a class="message" href="#SCI_AUTOCSETORDER">SCI_AUTOCSETORDER</a>
4391 </p>
4394 This message cancels any displayed autocompletion list. When in autocompletion mode, the list
4395 should disappear when the user types a character that can not be part of the autocompletion,
4396 such as '.', '(' or '[' when typing an identifier. A set of characters that will cancel
4401 This message returns non-zero if there is an active autocompletion list and zero if there is
4402 not.</p>
4406 of the list.</p>
4409 This message triggers autocompletion. This has the same effect as the tab key.</p>
4413 automatically cancel the autocompletion list. When you start the editor, this list is
4414 empty.</p>
4418 These two messages set and get the separator character used to separate words in the
4423 This message selects an item in the autocompletion list. It searches the list of words for the
4424 first that matches <code>select</code>. By default, comparisons are case sensitive, but you can
4429 item is found, it is selected. If the item is not found, the autocompletion list closes if
4434 <p><b id="SCI_AUTOCGETCURRENTTEXT">SCI_AUTOCGETCURRENTTEXT(<unused>, char *text NUL-terminated)</b><br />
4435 This message retrieves the current selected text in the autocompletion list. Normally the
4437 is used instead.</p>
4439 <p>The value is copied to the <code>text</code> buffer, returning the length (not including the
4447 The default behaviour is for the list to be cancelled if the caret moves to the location it
4448 was at when the list was displayed. By calling this message with a <code>false</code> argument,
4449 the list is not cancelled until the caret moves at least one character before the word being
4450 completed.</p>
4452 <p><b id="SCI_AUTOCSETFILLUPS">SCI_AUTOCSETFILLUPS(<unused>, const char *chars)</b><br />
4453 If a fillup character is typed with an autocompletion list active, the currently selected item
4454 in the list is added into the document, then the fillup character is added. Common fillup
4455 characters are '(', '[' and '.' but others are possible depending on the language. By default,
4456 no fillup characters are set.</p>
4461 automatically added and no list is displayed. The default is to display the list even if there
4462 is only a single item.</p>
4466 By default, matching of characters to list members is case sensitive. These messages let you
4467 set and get case sensitivity.</p>
4469 <p><b id="SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</b><br />
4471 When autocompletion is set to ignore case (<code>SCI_AUTOCSETIGNORECASE</code>), by default it will
4472 nonetheless select the first list member that matches in a case sensitive way to entered characters.
4473 This corresponds to a behaviour property of <code>SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE</code> (0).
4474 If you want autocompletion to ignore case at all, choose <code>SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE</code> (1).</p>
4478 When autocompleting with multiple selections present, the autocompleted text can go into just the main selection with
4479 <code>SC_MULTIAUTOC_ONCE</code> (0) or into each selection with <code>SC_MULTIAUTOC_EACH</code> (1).
4484 The default setting <code>SC_ORDER_PRESORTED</code> (0) requires that the list be provided in alphabetical sorted order.
4485 </p>
4486 <p>Sorting the list can be done by Scintilla instead of the application with <code>SC_ORDER_PERFORMSORT</code> (1).
4487 This will take additional time.
4488 </p>
4489 <p>Applications that wish to prioritize some values and show the list in order of priority instead
4491 This requires extra processing in <a class="message" href="#SCI_AUTOCSHOW">SCI_AUTOCSHOW</a> to create a sorted index.
4492 </p>
4493 <p>Setting the order should be done before calling <a class="message" href="#SCI_AUTOCSHOW">SCI_AUTOCSHOW</a>.
4494 </p>
4498 By default, the list is cancelled if there are no viable matches (the user has typed
4499 characters that no longer match a list entry). If you want to keep displaying the original
4503 <p><b id="SCI_AUTOCSETDROPRESTOFWORD">SCI_AUTOCSETDROPRESTOFWORD(bool dropRestOfWord)</b><br />
4505 When an item is selected, any word characters following the caret are first erased if
4508 <p>
4515 Autocompletion list items may display an image as well as text. Each image is first registered with an integer
4516 type. Then this integer is included in the text of the list separated by a '?' from the text. For example,
4518 The images are in either the <a class="jump" href="#XPM">XPM format</a> (<code>SCI_REGISTERIMAGE</code>) or
4521 the <a class="message" href="#SCI_RGBAIMAGESETWIDTH"><code>SCI_RGBAIMAGESETWIDTH</code></a> and
4522 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.
4523 The set of registered images can be cleared with <code>SCI_CLEARREGISTEREDIMAGES</code> and the '?' separator changed
4525 </p>
4527 <p>
4531 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
4532 scrollbar is shown. The default is 5.
4533 </p>
4535 <p>
4539 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.
4540 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
4541 the available width are indicated by the presence of ellipsis.
4542 </p>
4546 <p>User lists use the same internal mechanisms as autocompletion lists, and all the calls
4547 listed for autocompletion work on them; you cannot display a user list at the same time as an
4548 autocompletion list is active. They differ in the following respects:</p>
4552 effect.<br />
4558 <p>BEWARE: if you have set fillup characters or stop characters, these will still be active
4559 with the user list, and may result in items being selected or the user list cancelled due to
4560 the user typing into the editor.</p>
4565 structure. It must be greater than 0 as this is how Scintilla tells the difference between an
4566 autocompletion list and a user list. If you have different types of list, for example a list of
4568 a selection. </p>
4572 <p>Call tips are small windows displaying the arguments to a function and are displayed after
4573 the user has typed the name of the function. They normally display characters using the font
4574 facename, size and character set defined by
4577 facename, size, foreground and background colours and character set with
4579 This also enables support for Tab characters.
4581 There is some interaction between call tips and autocompletion lists in that showing a
4582 call tip cancels any active autocompletion list, and vice versa.</p>
4586 <p>Call tips can highlight part of the text within them. You could use this to highlight the
4587 current argument to a function by counting the number of commas (or whatever separator your
4589 example of call tip use.</p>
4591 <p>The mouse may be clicked on call tips and this causes a
4593 notification to be sent to the container. Small up and down arrows may be displayed within
4595 for showing that there are overloaded variants of one function name and that the user can
4596 click on the arrows to cycle through the overloads.</p>
4598 <p>Alternatively, call tips can be displayed when you leave the mouse pointer for a while over
4603 the value of a variable, or during editing to give information about the word under the
4604 pointer.</p>
4606 *definition)</a><br />
4610 <a class="message" href="#SCI_CALLTIPSETPOSSTART">SCI_CALLTIPSETPOSSTART(int posStart)</a><br />
4612 highlightEnd)</a><br />
4618 </code>
4621 This message starts the process by displaying the call tip window. If a call tip is already
4622 active, this has no effect.<br />
4624 tip text is aligned to start 1 line below this character unless you have included up and/or
4625 down arrows in the call tip text in which case the tip is aligned to the right-hand edge of
4626 the rightmost arrow. The assumption is that you will start the text with something like
4629 '\n' (Line Feed, ASCII code 10) characters. Do not include '\r' (Carriage Return, ASCII
4631 supported if you set a tabsize with
4633 The position of the caret is remembered here so that the call tip can be cancelled automatically if subsequent deletion
4634 moves the caret before this position.</p>
4637 This message cancels any displayed call tip. Scintilla will also cancel call tips for you if
4638 you use any keyboard commands that are not compatible with editing the argument list of a
4639 function.
4640 Call tips are cancelled if you delete back past the position where the caret was when the tip was triggered.</p>
4647 This message returns or sets the value of the current position when <code>SCI_CALLTIPSHOW</code>
4648 started to display the tip.</p>
4651 This sets the region of the call tips text to display in a highlighted style.
4654 <code>hlEnd</code> must be greater than <code>hlStart</code>; <code>hlEnd-hlStart</code> is the
4655 number of characters to highlight. Highlights can extend over line ends if this is
4656 required.</p>
4658 <p>Unhighlighted text is drawn in a mid grey. Selected text is drawn in a dark blue. The
4659 background is white. These can be changed with
4663 </p>
4666 The background colour of call tips can be set with this message; the default colour is white.
4667 It is not a good idea to set a dark colour as the background as the default colour for normal
4668 calltip text is mid grey and the default colour for highlighted text is dark blue. This also
4672 The colour of call tip text can be set with this message; the default colour is mid grey.
4676 The colour of highlighted call tip text can be set with this message; the default colour
4677 is dark blue.</p>
4682 less than 1, Tab characters are not treated specially. Once this call has been used, the
4683 call tip foreground and background colours are also taken from the style.</p>
4692 <p>To allow the container application to perform any of the actions available to the user with
4693 keyboard, all the keyboard actions are messages. They do not take any parameters. These
4698 <tbody>
4699 <tr>
4707 </tr>
4709 <tr>
4717 </tr>
4719 <tr>
4727 </tr>
4729 <tr>
4735 </tr>
4737 <tr>
4743 </tr>
4745 <tr>
4753 </tr>
4755 <tr>
4763 </tr>
4765 <tr>
4773 </tr>
4775 <tr>
4781 </tr>
4783 <tr>
4791 </tr>
4793 <tr>
4799 </tr>
4801 <tr>
4809 </tr>
4811 <tr>
4817 </tr>
4819 <tr>
4827 </tr>
4829 <tr>
4837 </tr>
4839 <tr>
4845 </tr>
4847 <tr>
4853 </tr>
4856 <tr>
4860 </tr>
4862 <tr>
4866 </tr>
4868 <tr>
4872 </tr>
4874 <tr>
4880 </tr>
4882 <tr>
4888 </tr>
4890 <tr>
4898 </tr>
4900 <tr>
4908 </tr>
4910 <tr>
4918 </tr>
4920 <tr>
4925 </tr>
4927 <tr>
4931 </tr>
4933 <tr>
4937 </tr>
4938 </tbody>
4939 </table>
4944 (and convert regular selection to rectangular one, if any).</p>
4947 capitalisation (aCamelCaseIdentifier) or underscores (an_under_bar_ident).</p>
4951 (ie. just after the indentation) unless it is already there; in this case, it acts as SCI_HOME*.</p>
4954 allow movement to the start or end of display lines as opposed to the normal
4959 They go first to the start / end of the display line, like <code>SCI_[HOME|LINEEND]DISPLAY*</code>,
4960 but if the cursor is already at the point, it goes on to the start or end of the document line,
4962 </p>
4965 or end without changing the selection. These commands match OS X platform conventions for the behaviour of the
4968 </p>
4972 <p>There is a default binding of keys to commands that is defined in the Scintilla source in
4976 command that has no arguments can be mapped). You can change the mapping to suit your own
4977 requirements.</p>
4979 sciCommand)</a><br />
4983 </code>
4986 A key definition contains the key code in the low 16-bits and the key modifiers in the high
4988 <br />
4992 enumeration, which contains:<br />
4995 <code>SCK_INSERT</code>, <code>SCK_LEFT</code>, <code>SCK_MENU</code>, <code>SCK_NEXT</code> (Page Down),
5005 If you are building a table, you might
5010 This assigns the given key definition to a Scintilla command identified by
5011 <code>sciCommand</code>. <code>sciCommand</code> can be any <code>SCI_*</code> command that has
5012 no arguments.</p>
5017 to it.</p>
5020 This command removes all keyboard command mapping by setting an empty mapping table.</p>
5024 action. SCI_NULL ensures that keys do not propagate to the parent window as that may
5025 cause focus to move. If you want the standard platform behaviour use the constant 0 instead.</p>
5030 Clicking the wrong button on the mouse pops up a short default editing menu. This may be
5033 Scintilla window will have the opportunity to handle the message.</p>
5037 <p>Start and stop macro recording mode. In macro recording mode, actions are reported to the
5040 record these actions for future replay.</p>
5044 These two messages turn macro recording on and off.</p>
5049 which can include a printer display surface. Printed output shows text styling as on the
5050 screen, but it hides all margins except a line number margin. All special marker effects are
5051 removed and the selection and caret are hidden.</p>
5053 <p>Different platforms use different display surface ID types to print on. On Windows, these are
5058 *pfr)</a><br />
5060 magnification)</a><br />
5066 </code>
5069 This call renders a range of text into a device context. If you use
5070 this for printing, you will probably want to arrange a page header and footer; Scintilla does
5072 example. Each use of this message renders a range of text into a rectangular area and returns
5073 the position in the document of the next character to print.</p>
5076 (for example, if you use this with MFC you will need to paginate in
5078 <pre>
5079 struct Sci_Rectangle { int left; int top; int right; int bottom; };
5081 struct Sci_RangeToFormat {
5082 Sci_SurfaceID hdc; // The Surface ID we print to
5083 Sci_SurfaceID hdcTarget; // The Surface ID we use for measuring (may be same as hdc)
5084 Sci_Rectangle rc; // Rectangle in which to print
5085 Sci_Rectangle rcPage; // Physically printable page size
5086 Sci_CharacterRange chrg; // Range of characters to print
5087 };
5088 </pre>
5090 <p>On Windows, <code>hdc</code> and <code>hdcTarget</code> should both be set to the device context handle
5091 of the output device (usually a printer). If you print to a metafile these will not be the same
5092 as Windows metafiles (unlike extended metafiles) do not implement the full API for returning
5097 rectangle defined by rcPage).<br />
5099 position of characters to output. All of each line within this character range is drawn.</p>
5101 <p>On Cocoa, the surface IDs for printing (<code>bDraw=1</code>) should be the graphics port of the current context
5102 (<code>(CGContextRef) [[NSGraphicsContext currentContext] graphicsPort]</code>) when the view's drawRect method is called.
5104 to a bitmap context (created with <code>CGBitmapContextCreate</code>) to avoid runtime warnings.</p>
5106 <p>On GTK+, the surface IDs to use can be found from the printing context with
5110 position of characters to output. All of each line within this character range is drawn.</p>
5112 <p>When printing, the most tedious part is always working out what the margins should be to
5113 allow for the non-printable area of the paper and printing a header and footer. If you look at
5114 the printing code in SciTE, you will find that most of it is taken up with this. The loop that
5115 causes Scintilla to render text is quite simple if you strip out all the margin, non-printable
5116 area, header and footer code.</p>
5127 These two messages set and get the method used to render coloured text on a printer that is
5128 probably using white paper. It is especially important to consider the treatment of colour if
5129 you use a dark or black screen background. Printing white on black uses up toner and ink very
5130 many times faster than the other way around. You can set the mode to one of:</p>
5133 <tbody>
5134 <tr>
5140 </tr>
5141 </tbody>
5144 <tr>
5150 </tr>
5152 <tr>
5157 <td>If you use a dark screen background this saves ink by inverting the light value of
5158 all colours and printing on a white background.</td>
5159 </tr>
5161 <tr>
5167 </tr>
5169 <tr>
5175 </tr>
5177 <tr>
5182 <td>Everything prints in its own colour on a white background except that line numbers
5183 use their own background colour.</td>
5184 </tr>
5185 </tbody>
5186 </table>
5195 generates one line of output and the line is truncated if it is too long to fit
5196 into the print area.<br />
5198 white space or style changes although if a word is longer than a line, it will be wrapped before
5201 between words.</p>
5207 <a class="message" href="#SCI_GETRANGEPOINTER">SCI_GETRANGEPOINTER(int position, int rangeLength)</a><br />
5209 </code>
5211 <p>On Windows, the message-passing scheme used to communicate between the container and
5212 Scintilla is mediated by the operating system <code>SendMessage</code> function and can lead to
5213 bad performance when calling intensively. To avoid this overhead, Scintilla provides messages
5214 that allow you to call the Scintilla message function directly. The code to do this in C/C++ is
5215 of the form:</p>
5216 <pre>
5217 #include "Scintilla.h"
5221 // now a wrapper to call Scintilla directly
5222 sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
5223 return pSciMsg(pSciWndData, iMessage, wParam, lParam);
5224 }
5225 </pre>
5229 the Scintilla window.</p>
5231 <p>While faster, this direct calling will cause problems if performed from a different thread
5232 to the native thread of the Scintilla window in which case <code>SendMessage(hSciWnd, SCI_*,
5241 pointer.</p>
5244 This message returns the address of the function to call to handle Scintilla messages without
5245 the overhead of passing through the Windows messaging system. You need only call this once,
5246 regardless of the number of Scintilla windows you create.</p>
5249 This returns a pointer to data that identifies which Scintilla window is in use. You must call
5250 this once for each Scintilla window you create. When you call the direct function, you must
5251 pass in the direct pointer associated with the target window.</p>
5256 Grant temporary direct read-only access to the memory used by Scintilla to store
5257 the document.</p>
5259 text of the document is stored consecutively
5260 and ensure there is a NUL character after the text, then returns a pointer to the first character.
5261 Applications may then pass this to a function that accepts a character pointer such as a regular
5262 expression search or a parser. The pointer should <em>not</em> be written to as that may desynchronize
5263 the internal state of Scintilla.</p>
5264 <p>Since any action in Scintilla may change its internal state
5265 this pointer becomes invalid after any call or by allowing user interface activity. The application
5266 should reacquire the pointer after making any call to Scintilla or performing any user-interface calls such
5267 as modifying a progress indicator.</p>
5268 <p>This call takes similar time to inserting a character at the end of the document and this may
5269 include moving the document contents. Specifically, all the characters after the document gap
5270 are moved to before the gap. This compacted state should persist over calls and user interface
5271 actions that do not change the document contents so reacquiring the pointer afterwards is very
5272 quick. If this call is used to implement a global replace operation, then each replacement will
5274 each replacement then the operation will become O(n^2) rather than O(n). Instead, all
5275 matches should be found and remembered, then all the replacements performed.</p>
5278 range requested. The gap is not moved unless it is within the requested range so this call
5280 This can be used by application code that is able to act on blocks of text or ranges of lines.</p>
5284 with a range that contains the gap and consequent costs of moving the gap.</p>
5288 <p>A Scintilla window and the document that it displays are separate entities. When you create
5289 a new window, you also create a new, empty document. Each document has a reference count that
5290 is initially set to 1. The document also has a list of the Scintilla windows that are linked to
5291 it so when any window changes the document, all other windows in which it appears are notified
5292 to cause them to update. The system is arranged in this way so that you can work with many
5293 documents in a single Scintilla window and so you can display a single document in multiple
5294 windows (for use with splitter windows).</p>
5296 <p>Although these messages use <code>document *pDoc</code>, to ensure compatibility with future
5298 is, you can use and store the pointer as described in this section but you should not
5299 dereference it.</p>
5302 *pDoc)</a><br />
5305 *pDoc)</a><br />
5307 *pDoc)</a><br />
5308 </code>
5311 This returns a pointer to the document currently in use by the window. It has no other
5312 effect.</p>
5315 This message does the following:<br />
5321 window.<br />
5325 This message creates a new, empty document and returns a pointer to it. This document is not
5326 selected into the editor and starts with a reference count of 1. This means that you have
5327 ownership of it and must either reduce its reference count by 1 after using
5330 application to avoid memory leaks.</p>
5333 This increases the reference count of a document by 1. If you want to replace the current
5334 document in the Scintilla window and take ownership of the current document, for example if you
5335 are editing many documents in one window, do the following:<br />
5345 must point at a document that still exists. If you call this on a document with a reference
5346 count of 1 that is still attached to a Scintilla window, bad things will happen. To keep the
5352 <p>To ensure a responsive user interface, applications may decide to load and save documents using a separate thread
5353 from the user interface.</p>
5357 <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
5358 into a Scintilla document on the user interface thread. That technique uses extra memory to store a complete copy of the
5359 file and also means that the time that Scintilla takes to perform initial line end discovery blocks the user interface.</p>
5361 <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>
5364 Create an object that supports the <code>ILoader</code> interface which can be used to load data and then
5365 be turned into a Scintilla document object for attachment to a view object.
5366 The <code>bytes</code> argument determines the initial memory allocation for the document as it is more efficient
5367 to allocate once rather than rely on the buffer growing as data is added.
5373 <span class="S5">class</span><span class="S0"> </span>ILoader<span class="S0"> </span><span class="S10">{</span><br />
5375 <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 />
5376 <span class="S0"> </span><span class="S2">// Returns a status code from SC_STATUS_*</span><br />
5377 <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 />
5378 <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 />
5380 </div>
5382 <p>The application should call the <code>AddData</code> method with each block of data read from the file.
5383 <code>AddData</code> will return SC_STATUS_OK unless a failure, such as memory exhaustion occurs.
5384 If a failure occurs in <code>AddData</code> or in a file reading call then loading can be abandoned and the loader released with
5386 When the whole file has been read, the <code>ConvertToDocument</code> method should be called to produce a Scintilla
5387 document pointer which can be used in the same way as a document pointer returned from
5393 <p>An application that wants to save in the background should lock the document with <code>SCI_SETREADONLY(1)</code>
5394 to prevent modifications and retrieve a pointer to the unified document contents with
5396 The buffer of a locked document will not move so the pointer is valid until the application calls <code>SCI_SETREADONLY(0)</code>.</p>
5398 <p>If the user tries to performs a modification while the document is locked then a <code><a class="message"
5399 href="#SCN_MODIFYATTEMPTRO">SCN_MODIFYATTEMPTRO</a></code> notification is sent to the application.
5400 The application may then decide to ignore the modification or to terminate the background saving thread and reenable
5401 modification before returning from the notification.</p>
5405 <p>The fundamental operation in folding is making lines invisible or visible. Line visibility
5406 is a property of the view rather than the document so each view may be displaying a different
5407 set of lines. From the point of view of the user, lines are hidden and displayed using fold
5408 points. Generally, the fold points of a document are based on the hierarchical structure of the
5409 document contents. In Python, the hierarchy is determined by indentation and in C++ by brace
5410 characters. This hierarchy can be represented within a Scintilla document object by attaching a
5411 numeric "fold level" to each line. The fold level is most easily set by a lexer, but you can
5412 also set it with messages.</p>
5414 <p>It is up to your code to set the connection between user actions and folding and unfolding.
5415 The best way to see how this is done is to search the SciTE source code for the messages used
5416 in this section of the documentation and see how they are used. You will also need to use
5417 markers and a folding margin to complete your folding implementation.
5421 docLine)</a><br />
5423 displayLine)</a><br />
5430 <a class="message" href="#SCI_SETAUTOMATICFOLD">SCI_SETAUTOMATICFOLD(int automaticFold)</a><br />
5436 expanded)</a><br />
5438 <a class="message" href="#SCI_CONTRACTEDFOLDNEXT">SCI_CONTRACTEDFOLDNEXT(int lineStart)</a><br />
5443 <a class="message" href="#SCI_EXPANDCHILDREN">SCI_EXPANDCHILDREN(int line, int level)</a><br />
5446 line)</a><br />
5447 </code>
5450 When some lines are hidden and/or annotations are displayed, then a particular line in the
5451 document may be displayed at a
5452 different position to its document position. If no lines are hidden and there are no annotations,
5453 this message returns
5454 <code>docLine</code>. Otherwise, this returns the display line (counting the very first visible
5455 line as 0). The display line of an invisible line is the same as the previous visible line. The
5456 display line number of the first line in the document is 0. If lines are hidden and
5458 Lines can occupy more than one display line if they wrap.</p>
5461 When some lines are hidden and/or annotations are displayed, then a particular line in the
5462 document may be displayed at a
5463 different position to its document position. This message returns the document line number that
5464 corresponds to a display line (counting the display line of the first line in the document as
5467 is the number of lines in the document.</p>
5473 The first two messages mark a range of lines as visible or invisible and then redraw the
5474 display.
5476 visible and 0 if it is not visible.
5478 if some lines are hidden.
5479 These messages have no effect on fold levels or fold
5480 flags. The first line can not be hidden.</p>
5484 These two messages set and get a 32-bit value that contains the fold level of a line and some
5485 flags associated with folding. The fold level is a number in the range 0 to
5488 two addition flag bits. <code>SC_FOLDLEVELWHITEFLAG</code> indicates that the line is blank and
5489 allows it to be treated slightly different then its level may indicate. For example, blank
5490 lines should generally not be fold points and will be considered part of the preceding section even though
5491 they may have a lesser fold level.
5493 the line is a header (fold point).</p>
5496 of a line. Likewise, use <code>SCI_GETFOLDLEVEL(line) & SC_FOLDLEVEL*FLAG</code> to get the
5497 state of the flags. To set the fold level you must or in the associated flags. For instance, to
5502 to handle user folding requests. If you do change the fold levels, the folding margin will
5503 update to match your changes.
5506 In addition to showing markers in the folding margin, you can indicate folds to the user by
5507 drawing lines in the text area. The lines are drawn in the foreground colour set for <a
5510 </p>
5513 <tbody>
5514 <tr>
5518 </tr>
5519 </tbody>
5522 <tr>
5526 </tr>
5528 <tr>
5533 </tr>
5535 <tr>
5540 </tr>
5542 <tr>
5547 </tr>
5549 <tr>
5554 </tr>
5556 <tr>
5561 folding. The appearance of this feature may change in the future.</td>
5562 </tr>
5564 <tr>
5568 <td align="left">display hexadecimal line state in line margin to aid debugging of lexing and folding.
5570 </tr>
5571 </tbody>
5572 </table>
5582 state.</p>
5591 Each fold point may be either expanded, displaying all its child lines, or contracted, hiding
5592 all the child lines. This message toggles the folding state of the given line as long as it has
5594 all the lines that depend on the line. The display updates after this message.</p>
5598 These messages set and get the expanded state of a single line. The set message has no effect
5599 on the visible state of the line or any lines that depend on it. It does change the markers in
5600 the folding margin. If you ask for the expansion state of a line that is outside the document,
5603 <p>If you just want to toggle the fold state of one line and handle all the lines that are
5612 These messages provide a higher-level approach to folding instead of setting expanded flags and showing
5613 or hiding individual lines.</p>
5616 <p>To affect the entire document call <code>SCI_FOLDALL</code>. With <code>SC_FOLDACTION_TOGGLE</code>
5617 the first fold header in the document is examined to decide whether to expand or contract.
5618 </p>
5620 <tbody>
5621 <tr>
5625 </tr>
5626 </tbody>
5629 <tr>
5633 </tr>
5635 <tr>
5639 </tr>
5641 <tr>
5645 </tr>
5647 </tbody>
5648 </table>
5651 This is used to respond to a change to a line causing its fold level or whether it is a header to change,
5652 perhaps when adding or removing a '{'.</p>
5653 <p>By the time the container has received the notification that the line has changed,
5654 the fold level has already been set, so the container has to use the previous level in this call
5655 so that any range hidden underneath this line can be shown.
5656 </p>
5660 Instead of implementing all the logic for handling folding in the container, Scintilla can provide behaviour
5661 that is adequate for many applications. The <code>automaticFold</code> argument is a bit set defining
5662 which of the 3 pieces of folding implementation should be enabled. Most applications should be able to use the
5664 flags unless they wish to implement quite different behaviour such as defining their own fold structure.
5666 like to add or change click behaviour such as showing method headers only when Shift+Alt is used in
5667 conjunction with a click.
5668 </p>
5670 <tbody>
5671 <tr>
5675 </tr>
5676 </tbody>
5679 <tr>
5684 </tr>
5686 <tr>
5691 </tr>
5693 <tr>
5698 container.</td>
5699 </tr>
5701 </tbody>
5702 </table>
5705 Search efficiently for lines that are contracted fold headers.
5706 This is useful when saving the user's folding when switching documents or saving folding with a file.
5707 The search starts at line number <code>lineStart</code> and continues forwards to the end of the file.
5708 <code>lineStart</code> is returned if it is a contracted fold header otherwise the next contracted
5713 A line may be hidden because more than one of its parent lines is contracted. Both these
5714 message travels up the fold hierarchy, expanding any contracted folds until they reach the top
5723 <a class="message" href="#SCI_SETWRAPVISUALFLAGS">SCI_SETWRAPVISUALFLAGS(int wrapVisualFlags)</a><br />
5725 <a class="message" href="#SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</a><br />
5726 <a class="message" href="#SCI_GETWRAPVISUALFLAGSLOCATION">SCI_GETWRAPVISUALFLAGSLOCATION</a><br />
5727 <a class="message" href="#SCI_SETWRAPINDENTMODE">SCI_SETWRAPINDENTMODE(int indentMode)</a><br />
5738 </code>
5740 <p>By default, Scintilla does not wrap lines of text. If you enable line wrapping, lines wider
5741 than the window width are continued on the following lines. Lines are broken after space or tab
5742 characters or between runs of different styles. If this is not possible because a word in one
5743 style is wider than the window then the break occurs after the last character that completely
5744 fits on the line. The horizontal scroll bar does not appear when wrap mode is on.</p>
5746 <p>For wrapped lines Scintilla can draw visual flags (little arrows) at end of a a subline of a
5747 wrapped line and at begin of the next subline. These can be enabled individually, but if Scintilla
5748 draws the visual flag at the beginning of the next subline this subline will be indented by one char.
5749 Independent from drawing a visual flag at the begin the subline can have an indention.</p>
5751 <p>Much of the time used by Scintilla is spent on laying out and drawing text. The same text
5752 layout calculations may be performed many times even when the data used in these calculations
5753 does not change. To avoid these unnecessary calculations in some circumstances, the line layout
5754 cache can store the results of the calculations. The cache is invalidated whenever the
5755 underlying data, such as the contents or styling of the document changes. Caching the layout of
5756 the whole document has the most effect, making dynamic line wrap as much as 20 times faster but
5758 line.</p>
5760 <p>Wrapping is not performed immediately there is a change but is delayed until the display
5761 is redrawn. This delay improves performance by allowing a set of changes to be performed
5762 and then wrapped and displayed once. Because of this, some operations may not occur as
5763 expected. If a file is read and the scroll position moved to a particular line in the text,
5764 such as occurs when a container tries to restore a previous editing session, then
5765 the scroll position will have been determined before wrapping so an unexpected range
5766 of text will be displayed. To scroll to the position correctly, delay the scroll until the
5767 wrapping has been performed by waiting for an initial
5777 there is no white space between words.
5778 </p>
5783 You can enable the drawing of visual flags to indicate a line is wrapped. Bits set in
5784 wrapVisualFlags determine which visual flags are drawn.
5785 </p>
5787 <tbody>
5788 <tr>
5792 </tr>
5793 </tbody>
5796 <tr>
5800 </tr>
5802 <tr>
5806 </tr>
5808 <tr>
5813 </td>
5814 </tr>
5816 <tr>
5820 </tr>
5821 </tbody>
5822 </table>
5824 <p><b id="SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</b><br />
5826 You can set whether the visual flags to indicate a line is wrapped are drawn near the border or near the text.
5827 Bits set in wrapVisualFlagsLocation set the location to near the text for the corresponding visual flag.
5828 </p>
5831 <tbody>
5832 <tr>
5836 </tr>
5837 </tbody>
5840 <tr>
5844 </tr>
5846 <tr>
5850 </tr>
5852 <tr>
5856 </tr>
5857 </tbody>
5858 </table>
5862 Wrapped sublines can be indented to the position of their first subline or one more indent level.
5864 The modes are:
5865 </p>
5868 <tbody>
5869 <tr>
5873 </tr>
5874 </tbody>
5877 <tr>
5880 <td>Wrapped sublines aligned to left of window plus amount set by
5882 </tr>
5884 <tr>
5888 </tr>
5890 <tr>
5893 <td>Wrapped sublines are aligned to first subline indent plus one more level of indentation</td>
5894 </tr>
5895 </tbody>
5896 </table>
5901 wrapped lines in terms of the average character width in
5903 There are no limits on indent sizes, but values less than 0 or large values may have
5904 undesirable effects.<br />
5905 The indention of sublines is independent of visual flags, but if
5907 </p>
5914 <tbody>
5915 <tr>
5921 </tr>
5922 </tbody>
5925 <tr>
5931 </tr>
5933 <tr>
5939 </tr>
5941 <tr>
5947 </tr>
5949 <tr>
5955 </tr>
5956 </tbody>
5957 </table>
5961 The position cache stores position information for short runs of text
5962 so that their layout can be determined more quickly if the run recurs.
5966 Split a range of lines indicated by the target into lines that are at most pixelWidth wide.
5967 Splitting occurs on word boundaries wherever possible in a similar manner to line wrapping.
5969 </p>
5972 Join a range of lines indicated by the target into one line by
5973 removing line end characters.
5974 Where this would lead to no space between words, an extra space is inserted.
5975 </p>
5978 Document lines can occupy more than one display line if they wrap and this
5979 returns the number of display lines needed to wrap a document line.</p>
5984 larger or smaller in steps of one point. The displayed point size never goes below 2, whatever
5990 </code>
6000 These messages let you set and get the zoom factor directly. There is no limit set on the
6001 factors you can set, so limiting yourself to -10 to +20 to match the incremental zoom functions
6002 is a good idea.</p>
6006 <p>You can choose to mark lines that exceed a given length by drawing a vertical line or by
6007 colouring the background of characters that exceed the set length.</p>
6014 </code>
6018 These two messages set and get the mode used to display long lines. You can set one of the
6019 values in the table:</p>
6022 <tbody>
6023 <tr>
6029 </tr>
6030 </tbody>
6033 <tr>
6039 </tr>
6041 <tr>
6047 This works well for monospaced fonts. The line is drawn at a position based on the width
6050 your styles use proportional fonts or if your style have varied font sizes or you use a
6051 mixture of bold, italic and normal text.</td>
6052 </tr>
6054 <tr>
6059 <td>The background colour of characters after the column limit is changed to the colour
6061 </tr>
6062 </tbody>
6063 </table>
6067 These messages set and get the column number at which to display the long line marker. When
6068 drawing lines, the column sets a position in units of the width of a space character in
6069 <code>STYLE_DEFAULT</code>. When setting the background colour, the column is a character count
6070 (allowing for tabs) into the line.</p>
6075 These messages set and get the colour of the marker used to show that a line has exceeded the
6081 called the SciLexer version of Scintilla), lexing support for a wide range of programming
6082 languages is included and the messages in this section are supported. If you want to set
6083 styling and fold points for an unsupported language you can either do this in the container or
6084 better still, write your own lexer following the pattern of one of the existing ones.</p>
6086 <p>Scintilla also supports external lexers. These are DLLs (on Windows) or .so modules (on GTK+/Linux) that export three
6091 <a class="message" href="#SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char
6092 *name)</a><br />
6094 *name)</a><br />
6095 <a class="message" href="#SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char
6096 *path)</a><br />
6098 <a class="message" href="#SCI_CHANGELEXERSTATE">SCI_CHANGELEXERSTATE(int start, int end)</a><br />
6099 <a class="message" href="#SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(<unused>, char *names)</a><br />
6101 <a class="message" href="#SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</a><br />
6102 <a class="message" href="#SCI_SETPROPERTY">SCI_SETPROPERTY(const char *key, const char *value)</a><br />
6103 <a class="message" href="#SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value)</a><br />
6104 <a class="message" href="#SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</a><br />
6105 <a class="message" href="#SCI_GETPROPERTYINT">SCI_GETPROPERTYINT(const char *key, int default)</a><br />
6106 <a class="message" href="#SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</a><br />
6108 *keyWordList)</a><br />
6110 <a class="message" href="#SCI_GETSUBSTYLEBASES">SCI_GETSUBSTYLEBASES(<unused>, char *styles)</a><br />
6111 <a class="message" href="#SCI_DISTANCETOSECONDARYSTYLES">SCI_DISTANCETOSECONDARYSTYLES</a><br />
6112 <a class="message" href="#SCI_ALLOCATESUBSTYLES">SCI_ALLOCATESUBSTYLES(int styleBase, int numberStyles)</a><br />
6114 <a class="message" href="#SCI_GETSUBSTYLESSTART">SCI_GETSUBSTYLESSTART(int styleBase)</a><br />
6115 <a class="message" href="#SCI_GETSUBSTYLESLENGTH">SCI_GETSUBSTYLESLENGTH(int styleBase)</a><br />
6116 <a class="message" href="#SCI_GETSTYLEFROMSUBSTYLE">SCI_GETSTYLEFROMSUBSTYLE(int subStyle)</a><br />
6117 <a class="message" href="#SCI_GETPRIMARYSTYLEFROMSTYLE">SCI_GETPRIMARYSTYLEFROMSTYLE(int style)</a><br />
6118 <a class="message" href="#SCI_SETIDENTIFIERS">SCI_SETIDENTIFIERS(int style, const char *identifiers)</a><br />
6124 <code>SCLEX_NULL</code> to select no lexing action and <code>SCLEX_CONTAINER</code> which sends
6125 the <code><a class="message" href="#SCN_STYLENEEDED">SCN_STYLENEEDED</a></code> notification to
6126 the container whenever a range of text needs to be styled. You cannot use the
6128 assigns unused lexer numbers to.</p>
6130 <p><b id="SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char *name)</b><br />
6131 <b id="SCI_GETLEXERLANGUAGE">SCI_GETLEXERLANGUAGE(<unused>, char *name NUL-terminated)</b><br />
6132 <code>SCI_SETLEXERLANGUAGE</code> lets you select a lexer by name, and is the only method if you are using an
6133 external lexer or if you have written a lexer module for a language of your own and do not wish
6136 or "Python". To locate the name for the built-in lexers, open the relevant
6142 see if the lexer number changed.</p>
6146 <p><b id="SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char *path)</b><br />
6147 Load a lexer implemented in a shared library. This is a .so file on GTK+/Linux or a .DLL file on Windows.
6148 </p>
6151 This requests the current lexer or the container (if the lexer is set to
6156 message causes a redraw.</p>
6159 Indicate that the internal state of a lexer has changed over a range and therefore
6160 there may be a need to redraw.</p>
6162 <p><b id="SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(<unused>, char *names NUL-terminated)</b><br />
6164 <b id="SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description NUL-terminated)</b><br />
6165 Information may be retrieved about the properties that can be set for the current lexer.
6166 This information is only available for newer lexers.
6167 <code>SCI_PROPERTYNAMES</code> returns a string with all of the valid properties separated by "\n".
6168 If the lexer does not support this call then an empty string is returned.
6169 Properties may be boolean (<code>SC_TYPE_BOOLEAN</code>), integer (<code>SC_TYPE_INTEGER</code>),
6174 You can communicate settings to lexers with keyword:value string pairs. There is no limit to
6177 there is already a value string associated with the keyword, it is replaced. If you pass a zero
6180 significant.</p>
6184 <code>"$(fold)0"</code>, but when this is accessed, the <code>$(fold)</code> is replaced by the
6187 <p>Currently the "fold" property is defined for most of the lexers to set the fold structure if
6189 setting that determines how to indicate bad indentation. Most keywords have values that are
6191 properties are used.</p>
6193 <p>There is a convention for naming properties used by lexers so that the set of properties can be found by scripts.
6194 Property names should start with "lexer.<lexer>." or "fold.<lexer>." when they apply to one
6197 <p>Applications may discover the set of properties used by searching the source code of lexers for lines that contain
6198 <code>GetProperty</code> and a double quoted string and extract the value of the double quoted string as the property name.
6200 Documentation for the property may be located above the call as a multi-line comment starting with
6203 <p><b id="SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value NUL-terminated)</b><br />
6204 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
6205 buffer and return the length (not including the terminating 0). If not found, copy an empty string
6211 <p>If the value argument is 0 then the length that should be allocated to store the value is returned;
6214 <p><b id="SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</b><br />
6215 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
6216 buffer and return the length (not including the terminating 0). If not found, copy an empty string
6222 <p>If the value argument is 0 then the length that should be allocated to store the value (including any indicated keyword replacement)
6226 Lookup a keyword:value pair using the specified key; if found, interpret the value as an integer and return it.
6227 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
6234 You can set up to 9 lists of keywords for use by the current lexer.
6238 It is expected that the keywords will be composed of standard ASCII printing characters,
6240 (except common sense).</p>
6242 <p>How these keywords are used is entirely up to the lexer. Some languages, such as HTML may
6243 contain embedded languages, VBScript and JavaScript are common for HTML. For HTML, key word set
6245 is for SGML and DTD keywords. Review the lexer code to see examples of keyword list. A fully
6247 list of strings that describe the uses of the keyword lists.</p>
6250 indentation and set 2 for keywords that cause unindentation. Yet again, you might have a simple
6251 lexer that colours keywords and you could change languages by changing the keywords in set 0.
6252 There is nothing to stop you building your own keyword lists into the lexer, but this means
6253 that the lexer must be rebuilt if more keywords are added.</p>
6255 <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions NUL-terminated)</b><br />
6256 A description of all of the keyword sets separated by "\n" is returned by <code>SCI_DESCRIBEKEYWORDSETS</code>.</p>
6259 <p>Lexers may support several different sublanguages and each sublanguage may want to style some number of
6260 sets of identifiers (or similar lexemes such as documentation keywords) uniquely. Preallocating a large number for each
6261 purpose would exhaust the number of allowed styles quickly.
6262 This is alleviated by substyles which allow the application to determine how many sets of identifiers to allocate for
6263 each purpose.
6264 Lexers have to explicitly support this feature by implementing the methods in <code>ILexerWithSubStyles</code>.</p>
6266 <p><b id="SCI_GETSUBSTYLEBASES">SCI_GETSUBSTYLEBASES(<unused>, char *styles NUL-terminated)</b><br />
6270 Returns the distance between a primary style and its corresponding secondary style.</p>
6272 <p><b id="SCI_ALLOCATESUBSTYLES">SCI_ALLOCATESUBSTYLES(int styleBase, int numberStyles)</b><br />
6273 Allocate some number of substyles for a particular base style returning the first substyle number allocated.
6274 Substyles are allocated contiguously.</p>
6277 Free all allocated substyles.</p>
6281 Return the start and length of the substyles allocated for a base style.</p>
6284 For a sub style, return the base style, else return the argument.</p>
6287 For a secondary style, return the primary style, else return the argument.</p>
6291 The prefix feature available with <code>SCI_SETKEYWORDS</code> is not implemented for <code>SCI_SETIDENTIFIERS</code>.</p>
6295 <p>Lexers are programmed as objects that implement the ILexer interface and that interact
6296 with the document they are lexing through the IDocument interface.
6297 Previously lexers were defined by providing lexing and folding functions but creating an object
6298 to handle the interaction of a lexer with a document allows the lexer to store state information that
6299 can be used during lexing. For example a C++ lexer may store a set of preprocessor definitions
6300 or variable declarations and style these depending on their role.</p>
6302 <p>A set of helper classes allows older lexers defined by functions to be used in Scintilla.</p>
6306 <span class="S5">class</span><span class="S0"> </span>ILexer<span class="S0"> </span><span class="S10">{</span><br />
6316 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6317 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6322 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6324 <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 />
6326 <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 />
6333 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>val<span class="S10">)</span>
6336 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6337 <span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>
6338 <span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DescribeWordListSets<span class="S10">()</span>
6346 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>wl<span class="S10">)</span>
6364 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>startPos<span class="S10">,</span>
6379 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6381 </div>
6383 <p>
6384 The return values from PropertySet and WordListSet are used to indicate whether the change requires
6385 performing lexing or folding over any of the document. It is the position at which to restart lexing and folding or -1
6386 if the change does not require any extra work on the document.
6387 A simple approach is to return 0 if there is any possibility that a change requires lexing the document again while an
6388 optimisation could be to remember where a setting first affects the document and return that position.
6389 </p>
6391 <p><code>Version</code> returns an enumerated value specifying which version of the interface is implemented:
6392 <code>lvOriginal</code> for <code>ILexer</code> and <code>lvSubStyles</code> for <code>ILexerWithSubStyles</code>.</p>
6397 application and a lexer. An example would be where an application
6398 maintains a single large data structure containing symbolic information
6399 about system headers (like Windows.h) and provides this to the lexer
6400 where it can be applied to each document. This avoids the costs of
6401 constructing the system header information for each document. This is
6405 Previously, lexers were called with a range that started one line before the range that
6406 needs to be folded as this allowed fixing up the last line from the previous folding.
6407 The new approach allows the lexer to decide whether to backtrack or to handle this
6408 more efficiently.</p>
6412 <p>
6413 To allow lexers to report which line ends they support, and to support substyles,
6415 </p>
6418 <span class="S5">class</span><span class="S0"> </span>ILexerWithSubStyles<span class="S0"> </span><span class="S10">:</span><span class="S0"> </span><span class="S5">public</span><span class="S0"> </span>ILexer<span class="S0"> </span><span class="S10">{</span><br />
6420 <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>LineEndTypesSupported<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 />
6421 <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>AllocateSubStyles<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>styleBase<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>numberStyles<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 />
6422 <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>SubStylesStart<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>styleBase<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 />
6423 <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>SubStylesLength<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>styleBase<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 />
6424 <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>StyleFromSubStyle<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>subStyle<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 />
6425 <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>PrimaryStyleFromStyle<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>style<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 />
6426 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>FreeSubStyles<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 />
6427 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>SetIdentifiers<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>style<span class="S10">,</span><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>identifiers<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 />
6428 <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>DistanceToSecondaryStyles<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 />
6429 <span class="S0"> </span><span class="S5">virtual</span><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>GetSubStyleBases<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 />
6431 </div>
6473 <span class="S0"> </span>LineFromPosition<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>position<span class="S10">)</span>
6474 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6476 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6478 <span class="S0"> </span>LineStart<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
6479 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6481 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6483 <span class="S0"> </span>GetLevel<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
6485 <span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span>
6487 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6505 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>state<span class="S10">)</span>
6512 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>mask<span class="S10">)</span>
6515 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
6519 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>style<span class="S10">)</span>
6520 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span>
6530 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span>
6532 <span class="S0"> </span>DecorationSetCurrentIndicator<span class="S10">(</span><span class="S5">int</span>
6538 <span class="S0"> </span>DecorationFillRange<span class="S10">(</span><span class="S5">int</span>
6540 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>value<span class="S10">,</span>
6541 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>fillLength<span class="S10">)</span>
6549 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>end<span class="S10">)</span>
6558 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
6562 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6565 </div>
6567 <p>Scintilla tries to minimize the consequences of modifying text to
6568 only relex and redraw the line of the change where possible. Lexer
6569 objects contain their own private extra state which can affect later
6570 lines. For example, if the C++ lexer is greying out inactive code
6574 the document that it should relex and display more.</p>
6576 <p>For <code>StartStyling</code> the mask argument has no effect. It was used in version 3.4.2 and earlier.</p>
6579 exceptions. Exceptions should not be thrown over build boundaries as the
6580 two sides may be built with different compilers or incompatible
6581 exception options.</p>
6585 <p>
6586 To allow lexers to determine the end position of a line and thus more easily support Unicode line ends
6589 returning <code>INVALID_POSITION</code> for movement beyond the start and end of the document.</p>
6593 not valid Unicode code points.
6595 bytes in the character.
6596 </p>
6599 <span class="S5">class</span><span class="S0"> </span>IDocumentWithLineEnd<span class="S0"> </span><span class="S10">:</span><span class="S0"> </span><span class="S5">public</span><span class="S0"> </span>IDocument<span class="S0"> </span><span class="S10">{</span><br />
6601 <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>LineEnd<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6602 <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>GetRelativePosition<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>positionStart<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>characterOffset<span class="S10">)</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6603 <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>GetCharacterAndWidth<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>position<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span><span class="S10">*</span>pWidth<span class="S10">)</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6605 </div>
6611 implemented and thus which methods may be called.</p>
6615 <p>Notifications are sent (fired) from the Scintilla control to its container when an event has
6616 occurred that may interest the container.</p>
6617 <p>Notifications are sent using the
6622 may be set to receive notifications or the <code>ScintillaView</code> class may be subclassed and the
6624 subclass to control whether default handling is performed.</p>
6625 <p>The container is
6628 struct NotifyHeader { // This matches the Win32 NMHDR structure
6629 void *hwndFrom; // environment specific window handle/pointer
6630 uptr_t idFrom; // CtrlID of the window issuing the notification
6631 unsigned int code; // The SCN_* notification code
6632 };
6634 struct SCNotification {
6635 struct Sci_NotifyHeader nmhdr;
6636 int position;
6637 /* SCN_STYLENEEDED, SCN_DOUBLECLICK, SCN_MODIFIED, SCN_MARGINCLICK, */
6638 /* SCN_NEEDSHOWN, SCN_DWELLSTART, SCN_DWELLEND, SCN_CALLTIPCLICK, */
6639 /* SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, SCN_HOTSPOTRELEASECLICK, */
6640 /* SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6641 /* SCN_USERLISTSELECTION, SCN_AUTOCSELECTION */
6643 int ch; /* SCN_CHARADDED, SCN_KEY */
6644 int modifiers;
6645 /* SCN_KEY, SCN_DOUBLECLICK, SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, */
6646 /* SCN_HOTSPOTRELEASECLICK, SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6648 int modificationType; /* SCN_MODIFIED */
6649 const char *text;
6650 /* SCN_MODIFIED, SCN_USERLISTSELECTION, SCN_AUTOCSELECTION, SCN_URIDROPPED */
6652 int length; /* SCN_MODIFIED */
6653 int linesAdded; /* SCN_MODIFIED */
6654 int message; /* SCN_MACRORECORD */
6655 uptr_t wParam; /* SCN_MACRORECORD */
6656 sptr_t lParam; /* SCN_MACRORECORD */
6657 int line; /* SCN_MODIFIED */
6658 int foldLevelNow; /* SCN_MODIFIED */
6659 int foldLevelPrev; /* SCN_MODIFIED */
6660 int margin; /* SCN_MARGINCLICK */
6661 int listType; /* SCN_USERLISTSELECTION */
6662 int x; /* SCN_DWELLSTART, SCN_DWELLEND */
6663 int y; /* SCN_DWELLSTART, SCN_DWELLEND */
6664 int token; /* SCN_MODIFIED with SC_MOD_CONTAINER */
6665 int annotationLinesAdded; /* SCN_MODIFIED with SC_MOD_CHANGEANNOTATION */
6666 int updated; /* SCN_UPDATEUI */
6667 };
6668 </pre>
6670 <p>The notification messages that your container can choose to handle and the messages
6671 associated with them are:</p>
6701 </code>
6704 <code><a class="message" href="#SCI_SETMODEVENTMASK">SCI_SETMODEVENTMASK(int eventMask)</a><br />
6706 <a class="message" href="#SCI_SETMOUSEDWELLTIME">SCI_SETMOUSEDWELLTIME(int milliseconds)</a><br />
6710 </code>
6712 <p>The following additional notifications are sent using a secondary "command" method and should
6713 be avoided in new code as the primary "notification" method provides all the same events with richer
6714 information.
6716 This emulates the Windows Edit control. Only the lower
6723 </code>
6727 These two messages set and get the identifier of the Scintilla instance which is included in notifications as the
6729 When an application creates multiple Scintilla widgets, this allows the source of each notification to be found.
6732 The value should be small, preferably less than 16 bits,
6734 </p>
6739 lexer, you will receive this notification when Scintilla is about to display or print text that
6740 requires styling. You are required to style the text from the line that contains the position
6741 returned by <a class="message" href="#SCI_GETENDSTYLED"><code>SCI_GETENDSTYLED</code></a> up to
6742 the position passed in <code>SCNotification.position</code>. Symbolically, you need code of the
6743 form:</p>
6744 <pre>
6750 MyStyleRoutine(startPos, SCNotification.position);
6751 </pre>
6754 This is sent when the user types an ordinary text character (as opposed to a command
6755 character) that is entered into the text. The container can use this to decide to display a <a
6758 This notification is sent before the character has been styled so processing that depends on
6759 styling should instead be performed in the SCN_UPDATEUI notification.</p>
6763 Sent to the container when the save point is entered or left, allowing the container to
6769 When in read-only mode, this notification is sent to the container if the user tries to change
6770 the text. This can be used to check the document out of a version control system. You can set
6775 Reports all keys pressed but not consumed by Scintilla. Used on GTK+ because of
6776 some problems with keyboard focus and is not sent by the Windows version. <code>SCNotification.ch</code> holds the key code and
6782 The mouse button was double clicked in editor. The <code>position</code> field is set to the text position of the
6788 Either the text or styling of the document has changed or the selection range or scroll position has changed.
6789 Now would be a good time to update any container UI elements that depend on document or view state.
6790 The <code>updated</code> field is set to the bit set of things changed since the previous notification.</p>
6792 <tbody>
6793 <tr>
6800 </tr>
6801 </tbody>
6804 <tr>
6811 </tr>
6813 <tr>
6820 </tr>
6822 <tr>
6829 </tr>
6831 <tr>
6838 </tr>
6839 </tbody>
6840 </table>
6843 This notification is sent when the text or styling of the document changes or is about to
6844 change. You can set a mask for the notifications that are sent to the container with <a
6846 notification structure contains information about what changed, how the change occurred and
6847 whether this changed the number of lines in the document. No modifications may be performed
6849 are:</p>
6852 <tbody>
6853 <tr>
6857 </tr>
6858 </tbody>
6861 <tr>
6865 table.</td>
6866 </tr>
6868 <tr>
6872 </tr>
6874 <tr>
6879 </tr>
6881 <tr>
6886 </tr>
6888 <tr>
6892 information this holds a pointer to the text that is handed to the Undo system, otherwise
6894 </tr>
6896 <tr>
6901 </tr>
6903 <tr>
6907 unused.</td>
6908 </tr>
6910 <tr>
6914 unused.</td>
6915 </tr>
6916 </tbody>
6917 </table>
6922 Undo or Redo of a previous action.</p>
6925 <tbody>
6926 <tr>
6934 </tr>
6935 </tbody>
6938 <tr>
6946 </tr>
6948 <tr>
6956 </tr>
6958 <tr>
6966 </tr>
6968 <tr>
6976 </tr>
6978 <tr>
6986 </tr>
6988 <tr>
6996 </tr>
6998 <tr>
7006 </tr>
7008 <tr>
7016 </tr>
7018 <tr>
7026 </tr>
7028 <tr>
7036 </tr>
7038 <tr>
7046 </tr>
7048 <tr>
7056 </tr>
7058 <tr>
7066 </tr>
7068 <tr>
7073 <td>A line state has changed because <a class="message" href="#SCI_SETLINESTATE">SCI_SETLINESTATE</a>
7074 was called.</td>
7077 </tr>
7079 <tr>
7084 <td>The explicit tab stops on a line have changed because <a class="message" href="#SCI_CLEARTABSTOPS">SCI_CLEARTABSTOPS</a> or
7088 </tr>
7090 <tr>
7098 </tr>
7100 <tr>
7108 </tr>
7110 <tr>
7118 </tr>
7120 <tr>
7125 <td>Text is about to be inserted. The handler may change the text being inserted by calling
7127 No other modifications may be made in this handler.</td>
7130 </tr>
7132 <tr>
7140 </tr>
7142 <tr>
7147 <td>This is set on a SC_PERFORMED_USER action when it is the
7148 first or only step in an undo transaction. This can be used to integrate the Scintilla
7149 undo stack with an undo stack in the container application by adding a Scintilla
7150 action to the container's stack for the currently opened container transaction or
7151 to open a new container transaction if there is no open container transaction.
7152 </td>
7155 </tr>
7157 <tr>
7162 <td>This is set on for actions that the container stored into the undo stack with
7164 </td>
7167 </tr>
7169 <tr>
7178 </tr>
7179 </tbody>
7180 </table>
7185 "command" signal on GTK+ as this is the behaviour of the standard Edit control
7194 These messages set and get an event mask that determines which document change events are
7198 only notifications about changes to text and not styling changes by calling
7204 <code>SC_MOD_CHANGEFOLD</code>, <code>SC_PERFORMED_USER</code>, <code>SC_PERFORMED_UNDO</code>,
7215 behaviour of the standard Edit control. Unfortunately, these codes do not match the Windows Edit
7217 now too late to change the Scintilla codes as clients depend on the current values.</p>
7222 disable macro recording. When enabled, each time a recordable change occurs, the
7227 notification are:</p>
7230 <tbody>
7231 <tr>
7235 </tr>
7236 </tbody>
7239 <tr>
7243 </tr>
7245 <tr>
7249 </tr>
7251 <tr>
7255 </tr>
7256 </tbody>
7257 </table>
7264 used:</p>
7267 <tbody>
7268 <tr>
7272 </tr>
7273 </tbody>
7276 <tr>
7281 at the time of the margin click.</td>
7282 </tr>
7284 <tr>
7288 to the margin click.</td>
7289 </tr>
7291 <tr>
7295 </tr>
7296 </tbody>
7297 </table>
7300 Scintilla has determined that a range of lines that is currently invisible should be made
7301 visible. An example of where this may be needed is if the end of line of a contracted fold
7302 point is deleted. This message is sent to the container in case it wants to make the line
7303 visible in some unusual way such as making the whole document visible. Most containers will
7307 that should be made visible. The container code will be similar to the following code
7308 skeleton:</p>
7309 <pre>
7310 firstLine = SCI_LINEFROMPOSITION(scn.position)
7311 lastLine = SCI_LINEFROMPOSITION(scn.position+scn.length-1)
7312 for line = lineStart to lineEnd do SCI_ENSUREVISIBLE(line) next
7313 </pre>
7316 Painting has just been done. Useful when you want to update some other widgets based on a
7317 change in Scintilla, but want to have the paint occur first to appear more responsive. There is
7325 <tbody>
7326 <tr>
7330 </tr>
7331 </tbody>
7334 <tr>
7339 initiated the list.</td>
7340 </tr>
7342 <tr>
7346 </tr>
7348 <tr>
7352 </tr>
7353 </tbody>
7354 </table>
7355 <br />
7359 Only on the GTK+ version. Indicates that the user has dragged a URI such as a file name or Web
7360 address onto Scintilla. The container could interpret this as a request to open the file. The
7369 key press indicates the dwell is over. Both notifications set the same fields in
7373 <tbody>
7374 <tr>
7378 </tr>
7379 </tbody>
7382 <tr>
7386 mouse pointer was lingering.</td>
7387 </tr>
7389 <tr>
7395 </tr>
7396 </tbody>
7397 </table>
7398 <br />
7402 These two messages set and get the time the mouse must sit still, in milliseconds, to generate
7407 This notification is generated when the user zooms the display using the keyboard or the
7409 notification can be used to recalculate positions, such as the width of the line number margin
7410 to maintain sizes in terms of characters rather than pixels. <code>SCNotification</code> has no
7411 additional information.</p>
7413 <p>
7417 These notifications are generated when the user clicks or double clicks on
7418 text that is in a style with the hotspot attribute set.
7419 This notification can be used to link to variable definitions or web pages.
7420 In the notification handler, you should avoid calling any function that modifies the current selection or caret position.
7426 <p>
7429 These notifications are generated when the user clicks or releases the mouse on
7430 text that has an indicator.
7436 This notification is generated when the user clicks on a calltip.
7437 This notification can be used to display the next function prototype when a
7438 function name is overloaded with different arguments.
7443 The user has selected an item in an <a class="jump" href="#Autocompletion">autocompletion list</a>. The
7444 notification is sent before the selection is inserted. Automatic insertion can be cancelled by sending a
7449 <tbody>
7450 <tr>
7454 </tr>
7455 </tbody>
7458 <tr>
7462 </tr>
7463 <tr>
7467 </tr>
7468 </tbody>
7469 </table>
7473 There is no other information in SCNotification.</p>
7476 The user deleted a character while autocompletion list was active.
7477 There is no other information in SCNotification.</p>
7486 <p>Two formats are supported for images used in margin markers and autocompletion lists, RGBA and XPM.</p>
7491 value for each pixel. It is simpler than
7494 <p>The data is a sequence of 4 byte pixel values starting with the pixels for the top line, with the
7495 leftmost pixel first, then continuing with the pixels for subsequent lines. There is no gap between
7496 lines for alignment reasons.</p>
7498 <p>Each pixel consists of, in order, a red byte, a green byte, a blue byte and an alpha byte.
7499 The colour bytes are not premultiplied by the alpha value. That is, a fully red pixel that is
7502 <p>Since the RGBA pixel data does not include any size information the
7503 width and height must previously been set with the
7505 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.</p>
7507 <p>GUI platforms often include functions for reading image file formats like PNG into memory
7508 in the RGBA form or a similar form.
7509 If there is no suitable platform support, the <a href="http://lodev.org/lodepng/">LodePNG and picoPNG</a> libraries are small libraries
7510 for loading and decoding PNG files available under a BSD-style license.</p>
7516 <p>The XPM format is
7518 Scintilla is only able to handle XPM pixmaps that use one character per pixel with no named colours.
7520 <p>There are two forms of data structure used for XPM images, the first "lines form" format is well suited
7521 to embedding an image inside C source code and the "text form" is suited to reading from a file.
7522 In the lines form, an array of strings is used with the first string indicating the dimensions and number of colours
7523 used. This is followed by a string for each colour and that section is followed by the image with one string per line.
7524 The text form contains the same data as one null terminated block formatted as C source code starting
7526 <p>Either format may be used with Scintilla APIs with the bytes at the location pointed to examined
7527 to determine which format: if the bytes start with "/* XPM */" then it is treated as text form,
7528 otherwise it is treated as lines form.</p>
7533 <p>On GTK+, the following functions create a Scintilla widget, communicate with it and allow
7534 resources to be released after all Scintilla widgets have been destroyed.</p>
7536 <a class="message" href="#scintilla_set_id">void scintilla_set_id(ScintillaObject *sci, uptr_t id)</a><br />
7537 <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 />
7538 <a class="message" href="#scintilla_release_resources">void scintilla_release_resources()</a><br />
7539 </code>
7542 Create a new Scintilla widget. The returned pointer can be added to a container and displayed in the same way as other
7543 widgets.</p>
7546 Set the control ID which will be used in the idFrom field of the NotifyHeader structure of all
7547 notifications for this instance.
7550 <p><b id="scintilla_send_message">sptr_t scintilla_send_message(ScintillaObject *sci,unsigned int iMessage, uptr_t wParam, sptr_t lParam)</b><br />
7551 The main entry point allows sending any of the messages described in this document.</p>
7554 Call this to free any remaining resources after all the Scintilla widgets have been destroyed.</p>
7558 <p>Complex new features may be added as 'provisional' to allow further changes to the API.
7559 Provisional features may even be removed if experience shows they are a mistake.</p>
7561 <p>Provisional features are displayed in this document with <span class="provisional">a distinctive background colour</span>.</p>
7563 <p>There are currently no provisional messages.
7570 <p>Some developers may want to only use features that are stable and have graduated from
7571 provisional status. To avoid using provisional messages compile with the symbol
7576 <p>The following messages are currently supported to emulate existing Windows controls, but
7577 they will be removed in future versions of Scintilla. If you use these messages you should
7578 replace them with the Scintilla equivalent.</p>
7579 <pre>
7580 WM_GETTEXT(int length, char *text)
7582 EM_GETLINE(int line, char *text)
7584 EM_SETREADONLY
7586 WM_CUT
7587 WM_COPY
7588 WM_PASTE
7589 WM_CLEAR
7590 WM_UNDO
7591 EM_CANUNDO
7592 EM_EMPTYUNDOBUFFER
7593 WM_GETTEXTLENGTH
7594 EM_GETFIRSTVISIBLELINE
7595 EM_GETLINECOUNT
7596 EM_GETMODIFY
7597 EM_SETMODIFY(bool isModified)
7598 EM_GETRECT(RECT *rect)
7599 EM_GETSEL(int *start, int *end)
7601 EM_SETSEL(int start, int end)
7604 EM_LINEFROMCHAR(int position)
7605 EM_EXLINEFROMCHAR(int position)
7606 EM_LINEINDEX(int line)
7607 EM_LINELENGTH(int position)
7608 EM_SCROLL(int line)
7609 EM_LINESCROLL(int column, int line)
7610 EM_SCROLLCARET()
7611 EM_CANPASTE
7613 EM_POSFROMCHAR(int position, POINT *location)
7614 EM_SELECTIONTYPE
7615 EM_HIDESELECTION(bool hide)
7616 EM_FINDTEXT(int flags, FINDTEXTEX *ft)
7617 EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
7618 EM_GETMARGINS
7619 EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
7620 EM_FORMATRANGE
7621 </pre>
7623 <p>The following are features that are only included if you define
7625 compatibility you should change them as indicated.</p>
7628 This was used to set a DBCS (Double Byte Character Set) mode on GTK+.
7629 An explicit DBCS code page should be used when calling <a class="message" href="#SCI_SETCODEPAGE">SCI_SETCODEPAGE</a></p>
7633 Scintilla no longer supports palette mode. The last version to support palettes was 2.29.
7634 Any calls to these methods should be removed.</p>
7638 On Windows, Scintilla no longer supports narrow character windows so input is always treated as Unicode.</p>
7640 <p>The following are features that should be removed from calling code but are still
7641 defined to avoid breaking callers.</p>
7643 <p id="StyleByteIndicators"><b id="SCI_SETSTYLEBITS">SCI_SETSTYLEBITS(int bits)</b> Deprecated<br />
7646 <code>INDIC0_MASK</code>, <code>INDIC1_MASK</code>, <code>INDIC2_MASK</code>, <code>INDICS_MASK</code> Deprecated<br />
7647 Scintilla no longer supports style byte indicators. The last version to support style byte indicators was 3.4.2.
7648 Any use of these symbols should be removed and replaced with <a href="#Indicators">standard indicators</a>.
7653 <pre>
7654 EM_GETWORDBREAKPROC EM_GETWORDBREAKPROCEX
7655 EM_SETWORDBREAKPROC EM_SETWORDBREAKPROCEX
7656 EM_GETWORDWRAPMODE EM_SETWORDWRAPMODE
7657 EM_LIMITTEXT EM_EXLIMITTEXT
7658 EM_SETRECT EM_SETRECTNP
7659 EM_FMTLINES
7660 EM_GETHANDLE EM_SETHANDLE
7661 EM_GETPASSWORDCHAR EM_SETPASSWORDCHAR
7662 EM_SETTABSTOPS
7663 EM_FINDWORDBREAK
7664 EM_GETCHARFORMAT EM_SETCHARFORMAT
7665 EM_GETOLEINTERFACE EM_SETOLEINTERFACE
7666 EM_SETOLECALLBACK
7667 EM_GETPARAFORMAT EM_SETPARAFORMAT
7668 EM_PASTESPECIAL
7669 EM_REQUESTRESIZE
7670 EM_GETBKGNDCOLOR EM_SETBKGNDCOLOR
7671 EM_STREAMIN EM_STREAMOUT
7672 EM_GETIMECOLOR EM_SETIMECOLOR
7673 EM_GETIMEOPTIONS EM_SETIMEOPTIONS
7674 EM_GETOPTIONS EM_SETOPTIONS
7675 EM_GETPUNCTUATION EM_SETPUNCTUATION
7676 EM_GETTHUMB
7677 EM_GETEVENTMASK
7678 EM_SETEVENTMASK
7679 EM_DISPLAYBAND
7680 EM_SETTARGETDEVICE
7681 </pre>
7683 <p>Scintilla tries to be a superset of the standard windows Edit and RichEdit controls wherever
7684 that makes sense. As it is not intended for use in a word processor, some edit messages can not
7685 be sensibly handled. Unsupported messages have no effect.</p>
7689 <p>Previous versions of Scintilla allowed indicators to be stored in bits of each style byte.
7691 All uses of style byte indicators should be replaced with <a href="#Indicators">standard indicators</a>.</p>
7695 <p>To build Scintilla or SciTE, see the README file present in both the Scintilla and SciTE
7698 supported. The version of GTK+ installed should be detected automatically.
7700 on the command line.</p>
7704 <p>On Windows, Scintilla is normally used as a dynamic library as a .DLL file. If you want to
7705 link Scintilla directly into your application .EXE or .DLL file, then the
7707 <code>Scintilla_RegisterClasses</code> called. <code>STATIC_BUILD</code> prevents compiling the
7708 <code>DllMain</code> function which will conflict with any <code>DllMain</code> defined in your
7714 <p>Depending on the compiler and linker used, the lexers may be stripped out. This is most
7715 often caused when building a static library. To ensure the lexers are linked in, the
7720 <p>To change the set of lexers in Scintilla, add and remove lexer source files
7722 <code>scripts/LexGen.py</code> script from the <code>scripts</code> directory to update the make files
7724 not have access to Python, you can hand edit <code>Catalogue.cxx</code> in a simple-minded way,
7725 following the patterns of other lexers. The important thing is to include
7731 <p id="AlternativeRegEx">A simple interface provides support for switching the Regular Expressions engine at
7735 to create an instance of your class. You must disable the built-in implementation by defining
7738 </body>
7739 </html>