| blob | 619fb00b70f65bfd4cceadf0d9a0b8490126271b |
6 <head>
15 <!--
16 /*<![CDATA[*/
17 CODE { font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
18 A:visited { color: blue; }
19 A:hover { text-decoration: underline ! important; }
20 A.message { text-decoration: none; font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
21 A.toc { text-decoration: none; }
22 A.jump { text-decoration: none; }
23 .S0 {
24 color: #808080;
25 }
26 .S2 {
27 font-family: 'Comic Sans MS';
28 color: #007F00;
29 font-size: 9pt;
30 }
31 .S3 {
32 font-family: 'Comic Sans MS';
33 color: #3F703F;
34 font-size: 9pt;
35 }
36 .S4 {
37 color: #007F7F;
38 }
39 .S5 {
40 font-weight: bold;
41 color: #00007F;
42 }
43 .S9 {
44 color: #7F7F00;
45 }
46 .S10 {
47 font-weight: bold;
48 color: #000000;
49 }
50 .S17 {
51 font-family: 'Comic Sans MS';
52 color: #3060A0;
53 font-size: 9pt;
54 }
55 DIV.highlighted {
56 background: #F7FCF7;
57 border: 1px solid #C0D7C0;
58 margin: 0.3em 3em;
59 padding: 0.3em 0.6em;
60 font-family: 'Verdana';
61 color: #000000;
62 font-size: 10pt;
63 }
64 /*]]>*/
65 -->
66 </style>
67 </head>
72 <tr>
77 </tr>
78 </table>
101 worth following if you want to contribute code to Scintilla but is not compulsory.</p>
105 <p>The Windows version of Scintilla is a Windows Control. As such, its primary programming
106 interface is through Windows messages. Early versions of Scintilla emulated much of the API
107 defined by the standard Windows Edit and RichEdit controls but those APIs are now deprecated in
108 favour of Scintilla's own, more consistent API. In addition to messages performing the actions
109 of a normal Edit control, Scintilla allows control of syntax styling, folding, markers, autocompletion
110 and call tips.</p>
112 <p>The GTK+ version also uses messages in a similar way to the Windows version. This is
113 different to normal GTK+ practice but made it easier to implement rapidly.</p>
115 <p>Scintilla does not properly support right-to-left languages like Arabic and Hebrew.
116 While text in these languages may appear correct, it is not possible to interact with this text
117 as is normal with other editing components.</p>
119 <p>This documentation describes the individual messages and notifications used by Scintilla. It
120 does not describe how to link them together to form a useful editor. For now, the best way to
121 work out how to develop using Scintilla is to see how SciTE uses it. SciTE exercises most of
122 Scintilla's facilities.</p>
124 <p>In the descriptions that follow, the messages are described as function calls with zero, one
127 are large enough to hold pointers, and the return value is also an integer large enough to contain a
128 pointer.
129 Although the commands only use the
130 arguments described, because all messages have two arguments whether Scintilla uses them or
131 not, it is strongly recommended that any unused arguments are set to 0. This allows future
132 enhancement of messages without the risk of breaking existing code. Common argument types
133 are:</p>
137 <tr>
142 </tr>
144 <tr>
148 </tr>
150 <tr>
153 <td>Arguments point at text that is being passed to Scintilla but not modified. The text
154 may be zero terminated or another argument may specify the character count, the
155 description will make this clear.</td>
156 </tr>
158 <tr>
161 <td>Arguments point at text buffers that Scintilla will fill with text. In some cases,
162 another argument will tell Scintilla the buffer size. In others, you must make sure that
163 the buffer is big enough to hold the requested text. If a NULL pointer (0) is passed
164 then, for SCI_* calls, the length that should be allocated is returned.</td>
165 </tr>
167 <tr>
170 <td>Colours are set using the RGB format (Red, Green, Blue). The intensity of each colour
173 colour is white. If you set all intensities to 0, the colour is black. When you set a
174 colour, you are making a request. What you will get depends on the capabilities of the
175 system and the current screen mode.</td>
176 </tr>
178 <tr>
181 <td>Translucency is set using an alpha value.
182 Alpha ranges from 0 (SC_ALPHA_TRANSPARENT) which is completely transparent to
184 is opaque and uses code that is not alpha-aware and may be faster. Not all platforms support
185 translucency and only some Scintilla features implement translucency.
186 The default alpha value for most features is SC_ALPHA_NOALPHA.</td>
187 </tr>
189 <tr>
193 enhancements.</td>
194 </tr>
195 </tbody>
196 </table>
201 <tbody>
202 <tr>
204 modification</a></td>
209 </tr>
211 <tr>
217 </tr>
219 <tr>
222 <td>o <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection and Virtual Space</a></td>
225 scrolling</a></td>
226 </tr>
228 <tr>
234 </tr>
236 <tr>
242 </tr>
244 <tr>
245 <td>o <a class="toc" href="#CaretAndSelectionStyles">Caret, selection, and hotspot styles</a></td>
250 </tr>
252 <tr>
258 Guides</a></td>
259 </tr>
261 <tr>
267 </tr>
269 <tr>
275 </tr>
277 <tr>
283 </tr>
285 <tr>
291 </tr>
293 <tr>
299 </tr>
301 <tr>
307 </tr>
309 <tr>
315 </tr>
317 <tr>
323 supported by Scintilla</a></td>
325 </tr>
327 <tr>
329 </tr>
330 </tbody>
331 </table>
340 <p>Each byte in a Scintilla document is followed by an associated byte of styling
341 information. The combination of a character byte and a style byte is called a cell. Style bytes
342 are interpreted an index into an array of styles.
343 Style bytes may be split into an index and a set of indicator bits
344 but this use is discouraged and indicators should now use
346 and related calls.
349 languages, and three independent indicators so that, for example, syntax errors, deprecated
350 names and bad indentation could all be displayed at once. The number of bits used for styles
353 The remaining bits can be used for indicators.</p>
355 <p>In this document, 'character' normally refers to a byte even when multi-byte characters are used.
356 Lengths measure the numbers of bytes, not the amount of characters in those bytes.</p>
358 <p>Positions within the Scintilla document refer to a character or the gap before that
361 The caret exists between character positions and can be located from before the first character (0)
364 <p>There are places where the caret can not go where two character bytes make up one character.
365 This occurs when a DBCS character from a language like Japanese is included in the document or
366 when line ends are marked with the CP/M standard of a carriage return followed by a line feed.
368 document.</p>
370 <p>All lines of text in Scintilla are the same height, and this height is calculated from the
371 largest font in any current style. This restriction is for performance; if lines differed in
372 height then calculations involving positioning of text would require the text to be styled
373 first.</p>
379 *text)</a><br />
383 *tr)</a><br />
395 *tr)</a><br />
399 <a class="message" href="#SCI_ENCODEDFROMUTF8">SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)</a><br />
401 </code>
409 entire document is returned.
411 the text as unmodified.</p>
420 This replaces all the text in the document with the zero terminated text string you pass
421 in.</p>
424 This message tells Scintilla that the current state of the document is unmodified. This is
425 usually done when the file is saved or loaded, hence the name "save point". As Scintilla
426 performs undo and redo operations, it notifies the container that it has entered or left the
431 should be considered dirty or not.</p>
437 This fills the buffer defined by text with the contents of the nominated line (lines start at
441 number of characters copied to the buffer. The returned text includes any end of line
442 characters. If you ask for a line number outside the range of lines in the document, 0
443 characters are copied. If the text argument is 0 then the length that should be allocated
444 to store the entire line is returned.</p>
455 current position are the same, the text is inserted at the caret position. The caret is
456 positioned after the inserted text and the caret is scrolled into view.</p>
460 These messages set and get the read-only flag for the document. If you mark a document as read
470 longer than the number of characters you wish to read. The return value is the length of the
481 This collects styled text into a buffer using two bytes for each cell, with the character at
482 the lower address of each pair and the style byte at the upper address. Characters between the
484 <code>struct Sci_TextRange</code> in <code>Scintilla.h</code>). Two 0 bytes are added to the end of
497 Allocate a document buffer large enough to store a given number of bytes.
498 The document will not be made smaller than its current contents.</p>
502 at the current position. This will include any 0's in the string that you might have expected
503 to stop the insert operation. The current position is set at the end of the inserted text,
504 but it is not scrolled into view.</p>
511 of the document. This will include any 0's in the string that you might have expected to stop
512 the operation. The current selection is not changed and the new text is not scrolled into
513 view.</p>
517 the current position if <code>pos</code> is -1. If the current position is after the insertion point
518 then it is moved along with its surrounding text but no scrolling is performed.</p>
521 Unless the document is read-only, this deletes all the text.</p>
524 Deletes a range of text in the document.</p>
527 When wanting to completely restyle the document, for example after choosing a lexer, the
529 folding state.</p>
533 negative or past the end of the document.</p>
537 negative or past the end of the document.</p>
541 This pair of routines sets and reads back the number of bits in each cell to use for styling,
542 to a maximum of 8 style bits. The remaining bits can be used as indicators. The standard
544 The number of styling bits needed by the current lexer can be found with
547 <p><b id="Sci_TextRange">Sci_TextRange</b> and <b id="Sci_CharacterRange">Sci_CharacterRange</b><br />
550 work.</p>
551 <pre>
552 struct Sci_CharacterRange {
553 long cpMin;
554 long cpMax;
555 };
557 struct Sci_TextRange {
558 struct Sci_CharacterRange chrg;
559 char *lpstrText;
560 };
561 </pre>
566 This method retrieves the value of the target encoded as UTF-8 which is the default
567 encoding of GTK+ so is useful for retrieving text for use in other parts of the user interface,
568 such as find and replace dialogs. The length of the encoded text in bytes is returned.
569 </p>
574 encoding which is useful for taking the results of a find dialog, for example, and receiving
575 a string of bytes that can be searched for in the document. Since the text can contain nul bytes,
577 length that will be converted. If set to -1, the length is determined by finding a nul byte.
578 The length of the converted string is returned.
579 </p>
583 <p>
584 There are methods to search for text and for regular expressions. The regular expression support
585 is limited and should only be used for simple cases and initial development. A different regular expression
587 or can be called from the container using direct access to the buffer contents through
589 </p>
591 *ttf)</a><br />
594 *text)</a><br />
596 *text)</a><br />
598 target</a><br />
599 </code>
602 Several of the search routines use flag options, which include a simple regular expression
603 search. Combine the flag options by adding them:</p>
606 <tbody>
607 <tr>
611 </tr>
613 <tr>
617 </tr>
619 <tr>
623 </tr>
625 <tr>
629 </tr>
630 <tr>
633 <td>Treat regular expression in a more POSIX compatible manner
634 by interpreting bare ( and ) for tagged sections rather than \( and \).</td>
635 </tr>
636 </tbody>
637 </table>
639 <p>You can
640 search backwards to find the previous occurrence of a search string by setting the end of the
641 search range before the start.</p>
646 <tbody>
647 <tr>
651 </tr>
653 <tr>
657 </tr>
659 <tr>
663 </tr>
665 <tr>
673 </tr>
675 <tr>
679 </tr>
681 <tr>
685 </tr>
687 <tr>
690 <td>This allows you to use a character x that would otherwise have a special meaning. For
691 example, \[ would be interpreted as [ and not as the start of a character set.</td>
692 </tr>
694 <tr>
697 <td>This indicates a set of characters, for example, [abc] means any of the characters a,
698 b or c. You can also use ranges, for example [a-z] for any lower case character.</td>
699 </tr>
701 <tr>
704 <td>The complement of the characters in the set. For example, [^A-Za-z] means any
705 character except an alphabetic character.</td>
706 </tr>
708 <tr>
712 </tr>
714 <tr>
718 </tr>
720 <tr>
725 </tr>
727 <tr>
732 </tr>
733 </tbody>
734 </table>
736 <p>Regular expressions will only match ranges within a single line, never matching over multiple lines.</p>
740 This message searches for text in the document. It does not use or move the current selection.
742 search type, which includes regular expression searches.</p>
746 to search. You can search backwards by
748 Set the <code>lpstrText</code> member of <code>Sci_TextToFind</code> to point at a zero terminated
749 text string holding the search pattern. If your language makes the use of <code>Sci_TextToFind</code>
754 <code>Sci_TextToFind</code> are filled in with the start and end positions of the found text.</p>
760 This structure is defined to have exactly the same shape as the Win32 structure
762 <pre>
763 struct Sci_TextToFind {
764 struct <a class="jump" href="#Sci_CharacterRange">Sci_CharacterRange</a> chrg; // range to search
765 char *lpstrText; // the search pattern (zero terminated)
766 struct Sci_CharacterRange chrgText; // returned as position of matching text
767 };
768 </pre>
773 These messages provide relocatable search support. This allows multiple incremental
774 interactive searches to be macro recorded while still setting the selection to found text so
781 selection, that is, the end of the selection that is nearer to the start of the document. You
786 occurrence of the zero terminated search string pointed at by text. The search is modified by
790 of the matching text. The selection is updated to show the matched text, but is not scrolled
791 into view.</p>
799 modifications cause scrolling and other visible changes, which may take some time and cause
800 unwanted display updates. If performing many changes, such as a replace all command, the target
801 can be used instead. First, set the target, ie. the range to be replaced. Then call
805 which uses a counted string to allow searching for null characters. It returns the
806 position of the start of the matching text range or -1 for failure, in which case the target is not moved. The flags used by
812 structure.</p>
821 *text)</a><br />
823 *text)</a><br />
825 *text)</a><br />
827 </code>
833 These functions set and return the start and end of the target. When searching in non-regular
834 expression mode, you can set start greater than end to find the last matching text in the
835 target rather than the first matching text. The target is also set by a successful
839 Set the target start and end to the start and end positions of the selection.</p>
845 expression search.</p>
848 This searches for the first occurrence of a text string in the target defined by
852 text and the return value is the position of the start of the matching text. If the search
858 After replacement, the target range refers to the replacement text.
859 The return value
860 is the length of the replacement string.<br />
861 Note that the recommended way to delete text in the document is to set the target to the text to be removed,
862 and to perform a replace target with an empty string.</p>
867 characters to use. The replacement string is formed from the text string with any sequences of
869 expression search. <code>\0</code> is replaced with all the matched text from the most recent search.
870 After replacement, the target range refers to the replacement text.
871 The return value is the length of the replacement string.</p>
874 Discover what text was matched by tagged expressions in a regular expression search.
875 This is useful if the application wants to interpret the replacement string itself.</p>
883 When overtype is enabled, each typed character replaces the character to the right of the text
884 caret. When overtype is disabled, characters are inserted at the caret.
887 mode.</p>
898 const char *text)</a><br />
900 <a class="message" href="#SCI_SETPASTECONVERTENDINGS">SCI_SETPASTECONVERTENDINGS(bool convert)</a><br />
902 </code>
910 These commands perform the standard tasks of cutting and copying data to the clipboard,
911 pasting from the clipboard into the document, and clearing the document.
915 copy or cut to the clipboard.</p>
918 unless the document is read-only.</p>
920 <p>On X, the clipboard is asynchronous and may require several messages between
921 the destination and source applications. Data from SCI_PASTE will not arrive in the
922 document immediately.</p>
925 selection is empty then the current line is copied. On Windows, an extra "MSDEVLineSelect" marker
927 the whole line before the current line.</p>
933 text to the system clipboard.</p>
937 If this property is set then when text is pasted any line ends are converted to match the document's
938 end of line mode as set with
940 Currently only changeable on Windows. On GTK+ pasted text is always converted.</p>
946 If an error occurs, Scintilla may set an internal error number that can be retrieved with
949 The currently defined statuses are:
950 </p>
954 <tr>
958 </tr>
960 <tr>
964 </tr>
966 <tr>
970 </tr>
972 </tbody>
973 </table>
977 <p>Scintilla has multiple level undo and redo. It will continue to collect undoable actions
978 until memory runs out. Scintilla saves actions that change the document. Scintilla does not
979 save caret and selection movements, view scrolling and the like. Sequences of typing or
980 deleting are compressed into single transactions to make it easier to undo and redo at a sensible
981 level of detail. Sequences of actions can be combined into transactions that are undone as a unit.
983 <code>SCI_ENDUNDOACTION</code> messages. These transactions can be nested and only the top-level
984 sequences are undone as units.</p>
991 collectUndo)</a><br />
996 </code>
1004 <p><code>SCI_CANUNDO</code> returns 0 if there is nothing to undo, and 1 if there is. You would
1005 typically use the result of this message to enable/disable the Edit menu Undo command.</p>
1012 actions to redo. You could typically use the result of this message to enable/disable the Edit
1013 menu Redo command.</p>
1016 This command tells Scintilla to forget any saved undo or redo history. It also sets the save
1017 point to the start of the undo buffer, so the document will appear to be unmodified. This does
1020 container.</p>
1026 You can control whether Scintilla collects undo information with
1029 <code>SCI_EMPTYUNDOBUFFER</code> to avoid the undo buffer being unsynchronized with the data in
1030 the buffer.</p>
1032 <p>You might wish to turn off saving undo information if you use the Scintilla to store text
1033 generated by a program (a Log view) or in a display window where text is often deleted and
1034 regenerated.</p>
1038 Send these two messages to Scintilla to mark the beginning and end of a set of operations that
1039 you want to undo all as one operation but that you have to generate as several operations.
1040 Alternatively, you can use these to mark a set of operations that you do not want to have
1041 combined with the preceding or following operations if they are undone.</p>
1044 The container can add its own actions into the undo stack by calling
1046 notification will be sent to the container with the
1051 <p>For example, if the container wanted to allow undo and redo of a 'toggle bookmark' command then
1053 Then when it receives a notification to undo or redo it toggles a bookmark on the line given by
1054 the token field. If there are different types of commands or parameters that need to be stored into the undo
1055 stack then the container should maintain a stack of its own for the document and use the current
1062 coalesced along with any insertion and deletion actions into a single compound action, otherwise 0.
1063 Coalescing treats coalescible container actions as transparent so will still only group together insertions that
1064 look like typing or deletions that look like multiple uses of the Backspace or Delete keys.
1065 </p>
1068 <p>Scintilla maintains a selection that stretches between two points, the anchor and the
1069 current position. If the anchor and the current position are the same, there is no selected
1070 text. Positions in the document range from 0 (before the first character), to the document size
1071 (after the last character). If you use messages, there is nothing to stop you setting a
1072 position that is in the middle of a CRLF pair, or in the middle of a 2 byte character. However,
1073 keyboard commands will not move the caret into such positions.</p>
1077 <a class="message" href="#SCI_SETFIRSTVISIBLELINE">SCI_SETFIRSTVISIBLELINE(int lineDisplay)</a><br />
1102 y)</a><br />
1103 <a class="message" href="#SCI_CHARPOSITIONFROMPOINT">SCI_CHARPOSITIONFROMPOINT(int x, int y)</a><br />
1104 <a class="message" href="#SCI_CHARPOSITIONFROMPOINTCLOSE">SCI_CHARPOSITIONFROMPOINTCLOSE(int x, int
1105 y)</a><br />
1107 position)</a><br />
1109 position)</a><br />
1116 <a class="message" href="#SCI_GETLINESELSTARTPOSITION">SCI_GETLINESELSTARTPOSITION(int line)</a><br />
1117 <a class="message" href="#SCI_GETLINESELENDPOSITION">SCI_GETLINESELENDPOSITION(int line)</a><br />
1120 onlyWordCharacters)</a><br />
1122 onlyWordCharacters)</a><br />
1125 <a class="message" href="#SCI_COUNTCHARACTERS">SCI_COUNTCHARACTERS(int startPos, int endPos)</a><br />
1126 <a class="message" href="#SCI_TEXTWIDTH">SCI_TEXTWIDTH(int styleNumber, const char *text)</a><br />
1131 </code>
1135 Both these messages return the length of the document in bytes.</p>
1138 This returns the number of lines in the document. An empty document contains 1 line. A
1143 These messages retrieve and set the line number of the first visible line in the Scintilla view. The first line
1147 This returns the number of complete lines visible on the screen. With a constant line height,
1148 this is the vertical space available divided by the line separation. Unless you arrange to size
1149 your window to an integral number of lines, there may be a partial line visible at the bottom
1150 of the view.</p>
1153 This returns non-zero if the document is modified and 0 if it is unmodified. The modified
1154 status of a document is determined by the undo position relative to the save point. The save
1156 usually when you have saved data to a file.</p>
1158 <p>If you need to be notified when the document becomes modified, Scintilla notifies the
1167 remove any selection (i.e. set the anchor to the same position as <code>currentPos</code>). The
1168 caret is scrolled into view after this operation.</p>
1172 the caret visible, if necessary. It is equivalent to
1174 position.</p>
1178 and scrolls the view (if needed) to make it visible. The anchor position is set the same as the
1180 the line set is the first or last.</p>
1183 This sets the current position and creates a selection between the anchor and the current
1184 position. The caret is not scrolled into view.</p>
1189 This returns the current position.</p>
1192 This sets the anchor position and creates a selection between the anchor position and the
1193 current position. The caret is not scrolled into view.</p>
1198 This returns the current anchor position.</p>
1202 These set the selection based on the assumption that the anchor position is less than the
1203 current position. They do not make the caret visible. The table shows the positions of the
1204 anchor and the current position after using these messages.</p>
1208 <tr>
1209 <th>
1210 </th>
1215 </tr>
1216 </thead>
1219 <tr>
1225 </tr>
1227 <tr>
1233 </tr>
1234 </tbody>
1235 </table>
1241 These return the start and end of the selection without regard to which end is the current
1242 position and which is the anchor. <code>SCI_GETSELECTIONSTART</code> returns the smaller of the
1243 current position or the anchor position. <code>SCI_GETSELECTIONEND</code> returns the larger of
1244 the two values.</p>
1247 This removes any selection and sets the caret at <code>pos</code>. The caret is not scrolled into view.</p>
1250 This selects all the text in the document. The current position is not scrolled into view.</p>
1258 This returns the document position that corresponds with the start of the line. If
1262 last line), the return value is the end of the document.</p>
1265 This returns the position at the end of the line, before any line end characters. If <code>line</code>
1266 is the last line in the document (which does not have any end of line characters), the result is the size of the
1272 is negative or beyond the last line in the document, the result is 0. If you want the length of
1274 href="#SCI_GETLINEENDPOSITION"><code>SCI_GETLINEENDPOSITION(line)</code></a> - <a class="message"
1279 buffer. The buffer size should be determined by calling with a NULL pointer for the <code>text</code> argument
1281 This allows for rectangular and discontiguous selections as well as simple selections.
1282 See <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection</a> for information on
1283 how multiple and rectangular selections and virtual space are copied.</p>
1290 </code></p>
1293 This retrieves the text of the line containing the caret and returns the position within the
1295 the text you wish to retrieve and a terminating 0 character.
1298 If the text argument is 0 then the length that should be allocated
1299 to store the entire current line is returned.</p>
1312 The two functions set and get the selection mode, which can be
1317 When set in these modes, regular caret moves will extend or reduce the selection,
1319 The get function returns the current mode even if the selection was made by mouse
1320 or with regular extended moves.
1321 <code>SC_SEL_THIN</code> is the mode after a rectangular selection has been typed into and ensures
1322 that no characters are selected.</p>
1326 Retrieve the position of the start and end of the selection at the given line with
1327 INVALID_POSITION returned if no selection on this line.</p>
1330 If the caret is off the top or bottom of the view, it is moved to the nearest line that is
1331 visible to its current position. Any selection is lost.</p>
1334 onlyWordCharacters)</b><br />
1336 onlyWordCharacters)</b><br />
1337 These messages return the start and end of words using the same definition of words as used
1338 internally within Scintilla. You can set your own list of characters that count as words with
1340 sets the start or the search, which is forwards when searching for the end and backwards when
1341 searching for the start.</p>
1345 <code>false</code> (0), the first character in the search direction sets the type of the search
1346 as word or non-word and the search stops at the first non-matching character. Searches are also
1347 terminated by the start or end of the document.</p>
1355 <tr>
1365 </tr>
1366 </thead>
1369 <tr>
1379 </tr>
1381 <tr>
1391 </tr>
1393 <tr>
1403 </tr>
1405 <tr>
1415 </tr>
1416 </tbody>
1417 </table>
1421 These messages return the position before and after another position
1422 in the document taking into account the current code page. The minimum
1423 position returned is 0 and the maximum is the last position in the document.
1424 If called with a position within a multi byte character will return the position
1425 of the start/end of that character.</p>
1428 Returns the number of whole characters between two positions..</p>
1432 be used, for example, to decide how wide to make the line number margin in order to display a
1433 given number of numerals.</p>
1436 This returns the height in pixels of a particular line. Currently all lines are the same
1437 height.</p>
1441 taking the width of tabs into account. This returns the column number of the last tab on the
1443 <code>pos</code>. If there are no tab characters on the line, the return value is the number of
1444 characters up to the position on the line. In both cases, double byte characters count as a
1445 single character. This is probably only useful with monospaced fonts.</p>
1449 taking the width of tabs into account. It treats a multi-byte character as a single column.
1456 window or not close to any characters.</p>
1461 <code>SCI_CHARPOSITIONFROMPOINTCLOSE</code> is similar but returns -1 if the point is outside the
1462 window or not close to any characters. This is similar to the previous methods but finds characters rather than
1463 inter-character positions.</p>
1468 in the document.</p>
1474 is drawn as normal text.</p>
1477 Scintilla remembers the x value of the last position horizontally moved to explicitly by the
1478 user and this value is then used when moving vertically such as by using the up and down keys.
1479 This message sets the current x position of the caret as the remembered value.</p>
1482 Move the selected lines up one line, shifting the line above after the selection.
1483 The selection will be automatically extended to the beginning of the selection's first line and the end of the seletion's last line.
1484 If nothing was selected, the line the cursor is currently at will be selected.</p>
1487 Move the selected lines down one line, shifting the line below before the selection.
1488 The selection will be automatically extended to the beginning of the selection's first line and the end of the seletion's last line.
1489 If nothing was selected, the line the cursor is currently at will be selected.</p>
1493 <code>
1494 <a class="message" href="#SCI_SETMULTIPLESELECTION">SCI_SETMULTIPLESELECTION(bool multipleSelection)</a><br />
1496 <a class="message" href="#SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</a><br />
1497 <a class="message" href="#SCI_GETADDITIONALSELECTIONTYPING">SCI_GETADDITIONALSELECTIONTYPING</a><br />
1500 <a class="message" href="#SCI_SETVIRTUALSPACEOPTIONS">SCI_SETVIRTUALSPACEOPTIONS(int virtualSpaceOptions)</a><br />
1502 <a class="message" href="#SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</a><br />
1503 <a class="message" href="#SCI_GETRECTANGULARSELECTIONMODIFIER">SCI_GETRECTANGULARSELECTIONMODIFIER</a><br />
1504 <br />
1512 <br />
1514 <a class="message" href="#SCI_SETSELECTIONNCARET">SCI_SETSELECTIONNCARET(int selection, int pos)</a><br />
1515 <a class="message" href="#SCI_GETSELECTIONNCARET">SCI_GETSELECTIONNCARET(int selection)</a><br />
1516 <a class="message" href="#SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</a><br />
1517 <a class="message" href="#SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</a><br />
1518 <a class="message" href="#SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</a><br />
1519 <a class="message" href="#SCI_GETSELECTIONNANCHOR">SCI_GETSELECTIONNANCHOR(int selection)</a><br />
1520 <a class="message" href="#SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</a><br />
1521 <a class="message" href="#SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</a><br />
1522 <a class="message" href="#SCI_SETSELECTIONNSTART">SCI_SETSELECTIONNSTART(int selection, int pos)</a><br />
1523 <a class="message" href="#SCI_GETSELECTIONNSTART">SCI_GETSELECTIONNSTART(int selection)</a><br />
1524 <a class="message" href="#SCI_SETSELECTIONNEND">SCI_SETSELECTIONNEND(int selection, int pos)</a><br />
1526 <br />
1528 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARET">SCI_SETRECTANGULARSELECTIONCARET(int pos)</a><br />
1529 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARET">SCI_GETRECTANGULARSELECTIONCARET</a><br />
1530 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</a><br />
1531 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</a><br />
1532 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</a><br />
1533 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHOR">SCI_GETRECTANGULARSELECTIONANCHOR</a><br />
1534 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</a><br />
1535 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</a><br />
1536 <br />
1538 <a class="message" href="#SCI_SETADDITIONALSELALPHA">SCI_SETADDITIONALSELALPHA(int alpha)</a><br />
1540 <a class="message" href="#SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int colour)</a><br />
1541 <a class="message" href="#SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int colour)</a><br />
1542 <a class="message" href="#SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int colour)</a><br />
1544 <a class="message" href="#SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</a><br />
1546 <a class="message" href="#SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</a><br />
1547 <a class="message" href="#SCI_GETADDITIONALCARETSVISIBLE">SCI_GETADDITIONALCARETSVISIBLE</a><br />
1548 <br />
1552 </code>
1554 <p>
1555 There may be multiple selections active at one time.
1556 More selections are made by holding down the Ctrl key while dragging with the mouse.
1557 The most recent selection is the main selection and determines which part of the document is shown automatically.
1558 Any selection apart from the main selection is called an additional selection.
1559 The calls in the previous section operate on the main selection.
1560 There is always at least one selection.
1561 </p>
1563 <p>
1564 Rectangular selections are handled as multiple selections although the original rectangular range is remembered so that
1565 subsequent operations may be handled differently for rectangular selections. For example, pasting a rectangular selection
1566 places each piece in a vertical column.
1567 </p>
1569 <p>
1570 Virtual space is space beyond the end of each line. The caret may be moved into virtual space but no real space will be
1571 added to the document until there is some text typed or some other text insertion command is used.
1572 </p>
1574 <p>When discontiguous selections are copied to the clipboard, each selection is added to the clipboard text
1575 in order with no delimiting characters.
1576 For rectangular selections the document's line end is added after each line's text. Rectangular selections
1577 are always copied from top line to bottom, not in the in order of selection.Virtual space is not copied.</p>
1579 <p>
1582 Enable or disable multiple selection. When multiple selection is disabled, it is not possible to select
1583 multiple ranges by holding down the Ctrl key while dragging with the mouse.</p>
1585 <p>
1586 <b id="SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</b><br />
1588 Whether typing, backspace, or delete works with multiple selections simultaneously.</p>
1590 <p>
1593 When pasting into multiple selections, the pasted text can go into just the main selection with <code>SC_MULTIPASTE_ONCE</code>=0
1594 or into each selection with <code>SC_MULTIPASTE_EACH</code>=1. <code>SC_MULTIPASTE_ONCE</code> is the default.</p>
1596 <p>
1599 Virtual space can be enabled or disabled for rectangular selections or in other circumstances or in both.
1604 <p>
1605 <b id="SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</b><br />
1607 On GTK+, the key used to indicate that a rectangular selection should be created when combined with a mouse drag can be set.
1608 The three possible values are <code>SCMOD_CTRL</code>=2 (default), <code>SCMOD_ALT</code>=4 or <code>SCMOD_SUPER</code>=8.
1609 Since <code>SCMOD_ALT</code> is often already used by a window manager, the window manager may need configuring to allow this choice.
1610 <code>SCMOD_SUPER</code> is often a system dependent modifier key such as the Left Windows key on a Windows keyboard or the
1611 Command key on a Mac.</p>
1613 <p>
1615 Return the number of selections currently active.</p>
1617 <p>
1621 <p>
1623 Set a single selection from <code>anchor</code> to <code>caret</code> as the only selection.</p>
1625 <p>
1627 Add a new selection from <code>anchor</code> to <code>caret</code> as the main selection retaining all other
1628 selections as additional selections.
1629 Since there is always at least one selection, to set a list of selections, the first selection should be
1630 added with <code>SCI_SETSELECTION</code> and later selections added with <code>SCI_ADDSELECTION</code></p>
1632 <p>
1635 One of the selections is the main selection which is used to determine what range of text is automatically visible.
1636 The main selection may be displayed in different colours or with a differently styled caret.
1637 Only an already existing selection can be made main.</p>
1639 <p>
1642 <b id="SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</b><br />
1643 <b id="SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</b><br />
1644 <b id="SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</b><br />
1646 <b id="SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</b><br />
1647 <b id="SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</b><br />
1648 Set or query the position and amount of virtual space for the caret and anchor of each already existing selection.</p>
1650 <p>
1655 Set or query the start and end position of each already existing selection.
1656 Mostly of use to query each range for its text.</p>
1658 <p>
1661 <b id="SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</b><br />
1662 <b id="SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</b><br />
1663 <b id="SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</b><br />
1665 <b id="SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</b><br />
1666 <b id="SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</b><br />
1667 Set or query the position and amount of virtual space for the caret and anchor of the rectangular selection.
1668 After setting the rectangular selection, this is broken down into multiple selections, one for each line.</p>
1670 <p>
1673 <b id="SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1674 <b id="SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int <a class="jump" href="#colour">colour</a>)</b><br />
1675 Modify the appearence of additional selections so that they can be differentiated from the main selection which has its appearence set with
1681 <p>
1682 <b id="SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1684 <b id="SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</b><br />
1686 Modify the appearence of additional carets so that they can be differentiated from the main caret which has its appearence set with
1692 <p>
1693 <b id="SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</b><br />
1697 <p>
1700 These commands may be assigned to keys to make it possible to manipulate multiple selections.
1701 <code>SCI_SWAPMAINANCHORCARET</code> moves the caret to the opposite end of the main selection.
1703 </p>
1709 caretSlop)</a><br />
1711 caretSlop)</a><br />
1713 caretSlop)</a><br />
1722 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING">SCI_SETSCROLLWIDTHTRACKING(bool tracking)</a><br />
1725 endAtLastLine)</a><br />
1727 </code>
1730 This will attempt to scroll the display by the number of columns and lines that you specify.
1731 Positive line values increase the line number at the top of the screen (i.e. they move the text
1732 upwards as far as the user is concerned), Negative line values do the reverse.</p>
1734 <p>The column measure is the width of a space in the default style. Positive values increase
1735 the column at the left edge of the view (i.e. they move the text leftwards as far as the user
1736 is concerned). Negative values do the reverse.</p>
1741 If the current position (this is the caret if there is no selection) is not visible, the view
1742 is scrolled to make it visible according to the current caret policy.</p>
1752 <tr>
1756 unwanted zone (UZ) where the caret is... unwanted. This zone is defined as a number of
1757 pixels near the vertical margins, and as a number of lines near the horizontal margins.
1758 By keeping the caret away from the edges, it is seen within its context. This makes it
1759 likely that the identifier that the caret is on can be completely seen, and that the
1760 current line is seen with some of the lines following it, which are often dependent on
1761 that line.</td>
1762 </tr>
1764 <tr>
1770 </tr>
1772 <tr>
1775 <td>If set, the display is moved more energetically so the caret can move in the same
1776 direction longer before the policy is applied again. '3UZ' notation is used to indicate
1777 three time the size of the UZ as a distance to the margin.</td>
1778 </tr>
1780 <tr>
1783 <td>If not set, instead of having symmetrical UZs, the left and bottom UZs are extended
1784 up to right and top UZs respectively. This way, we favour the displaying of useful
1785 information: the beginning of lines, where most code reside, and the lines after the
1786 caret, for example, the body of a function.</td>
1787 </tr>
1788 </tbody>
1789 </table>
1793 <tr>
1805 or going into the UZ) display is...</th>
1806 </tr>
1807 </thead>
1810 <tr>
1822 </tr>
1824 <tr>
1836 </tr>
1838 <tr>
1850 </tr>
1852 <tr>
1864 </tr>
1866 <tr>
1878 </tr>
1880 <tr>
1892 </tr>
1894 <tr>
1906 </tr>
1908 <tr>
1920 </tr>
1922 <tr>
1934 </tr>
1936 <tr>
1948 </tr>
1950 <tr>
1962 </tr>
1964 <tr>
1976 </tr>
1978 <tr>
1990 </tr>
1991 </tbody>
1992 </table>
1997 called. It takes <code>VISIBLE_SLOP</code> and <code>VISIBLE_STRICT</code> flags for the policy
2004 The horizontal scroll bar is only displayed if it is needed for the assumed width.
2005 If you never wish to see it, call
2008 when needed.</p>
2013 By default, the vertical scroll bar is always displayed when required. You can choose to hide
2020 view. A value of 0 is the normal position with the first text column visible at the left of the
2021 view.</p>
2027 For performance, Scintilla does not measure the display width of the document to determine
2028 the properties of the horizontal scroll bar. Instead, an assumed width is used.
2029 These messages set and get the document width in pixels assumed by Scintilla.
2030 The default value is 2000.
2031 To ensure the width of the currently visible lines can be scrolled use
2032 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING"><code>SCI_SETSCROLLWIDTHTRACKING</code></a></p>
2036 If scroll width tracking is enabled then the scroll width is adjusted to ensure that all of the lines currently
2037 displayed can be completely scrolled. This mode never adjusts the scroll width to be narrower.</p>
2043 scrolling one page below the last line.</p>
2049 useWhitespaceForeColour, int colour)</a><br />
2051 useWhitespaceBackColour, int colour)</a><br />
2053 size)</a><br />
2059 </code>
2063 White space can be made visible which may be useful for languages in which white space is
2064 significant, such as Python. Space characters appear as small centred dots and tab characters
2065 as light arrows pointing to the right. There are also ways to control the display of <a
2071 <tr>
2076 <td>The normal display mode with white space displayed as an empty background
2077 colour.</td>
2078 </tr>
2080 <tr>
2086 </tr>
2088 <tr>
2093 <td>White space used for indentation is displayed normally but after the first visible
2094 character, it is shown as dots and arrows.</td>
2095 </tr>
2096 </tbody>
2097 </table>
2105 By default, the colour of visible white space is determined by the lexer in use. The
2106 foreground and/or background colour of all visible white space can be set globally, overriding
2114 </p>
2116 <p>
2121 Text is drawn with the base of each character on a 'baseline'. The height of a line is found from the maximum
2122 that any style extends above the baseline (its 'ascent'), added to the maximum that any style extends below the
2123 baseline (its 'descent').
2126 This may done to make the text easier to read or to accomodate underlines or highlights.
2127 </p>
2133 The cursor is normally chosen in a context sensitive way, so it will be different over the
2134 margin than when over the text. When performing a slow action, you may wish to change to a wait
2136 argument can be:</p>
2140 <tr>
2146 </tr>
2148 <tr>
2153 <td>The wait cursor is displayed when the mouse is over or owned by the Scintilla
2154 window.</td>
2155 </tr>
2156 </tbody>
2157 </table>
2168 When the mouse is pressed inside Scintilla, it is captured so future mouse movement events are
2169 sent to Scintilla. This behavior may be turned off with
2174 <p>Scintilla can interpret any of the three major line end conventions, Macintosh (\r), Unix
2175 (\n) and CP/M / DOS / Windows (\r\n). When the user presses the Enter key, one of these line
2176 end strings is inserted into the buffer. The default is \r\n in Windows and \n in Unix, but
2185 </code>
2190 presses the Enter key. You can set <code>eolMode</code> to one of <code>SC_EOL_CRLF</code> (0),
2192 message retrieves the current state.</p>
2195 This message changes all the end of line characters in the document to match
2205 returns the current state.</p>
2209 <p>The styling messages allow you to assign styles to text. The standard Scintilla settings
2214 href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a>. If your styling needs can be met by
2215 one of the standard lexers, or if you can write your own, then a lexer is probably the easiest
2216 way to style your document. If you choose to use the container to do the styling you can use
2221 alternative, you might use idle time to style the document. Even if you use a lexer, you might
2222 use the styling commands to mark errors detected by a compiler. The following commands can be
2223 used.</p>
2228 *styles)</a><br />
2232 </code>
2235 Scintilla keeps a record of the last character that is likely to be styled correctly. This is
2236 moved forwards when characters after it are styled and moved backwards if changes are made to
2237 the text of the document before it. Before drawing text, this position is checked to see if any
2241 start styling. Scintilla will always ask to style whole lines.</p>
2246 to occur over several passes, with, for example, basic styling done on an initial pass to
2247 ensure that the text of the code is seen quickly and correctly, and then a second slower pass,
2248 detecting syntax errors and using indicators to show where these are. For example, with the
2249 standard settings of 5 style bits and 3 indicator bits, you would use a <code>mask</code> value
2252 lexical entity to style.</p>
2259 mask);</code><br />
2260 </p>
2267 not contain any bits not set in mask.</p>
2271 As well as the 8 bits of lexical state stored for each character there is also an integer
2272 stored for each line. This can be used for longer lived parse states such as what the current
2275 Changing the value produces a <a class="message" href="#SC_MOD_CHANGELINESTATE">SC_MOD_CHANGELINESTATE</a> notification.
2276 </p>
2279 This returns the last line that has any line state.</p>
2283 <p>While the style setting messages mentioned above change the style numbers associated with
2284 text, these messages define how those style numbers are interpreted visually. There are 256
2286 class="message" href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> to change the number
2289 defined.</p>
2293 <tr>
2298 <td>This style defines the attributes that all styles receive when the
2300 </tr>
2302 <tr>
2307 <td>This style sets the attributes of the text used to display line numbers in a line
2308 number margin. The background colour set for this style also sets the background colour
2309 for all margins that do not have any folding mask bits set. That is, any margin for which
2312 </tr>
2314 <tr>
2323 </tr>
2325 <tr>
2330 <td>This style sets the display attributes used when marking an unmatched brace with the
2332 message.</td>
2333 </tr>
2335 <tr>
2340 <td>This style sets the font used when drawing control characters.
2341 Only the font, size, bold, italics, and character set attributes are used and not
2342 the colour attributes. See
2345 </tr>
2347 <tr>
2352 <td>This style sets the foreground and background colours used when drawing the
2353 indentation guides.</td>
2354 </tr>
2356 <tr>
2363 causes call tips to use this style instead. Only the font face name, font size,
2364 foreground and background colours and character set attributes are used.</td>
2365 </tr>
2367 <tr>
2372 <td>To make it easier for client code to discover the range of styles that are
2373 predefined, this is set to the style number of the last predefined style. This is
2375 for one future predefined style.</td>
2376 </tr>
2378 <tr>
2383 <td>This is not a style but is the number of the maximum style that can be set. Styles
2387 </tr>
2388 </tbody>
2389 </table>
2391 <p>For each style you can set the font name, size and use of bold, italic and underline,
2392 foreground and background colour and the character set. You can also choose to hide text with a
2393 given style, display all characters as upper or lower case and fill from the last character on
2394 a line to the end of the line (for embedded languages). There is also an experimental attribute
2395 to make text read-only.</p>
2397 <p>It is entirely up to you how you use styles. If you want to use syntax colouring you might
2403 *fontName)</a><br />
2404 <a class="message" href="#SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName)</a><br />
2406 sizeInPoints)</a><br />
2408 <a class="message" href="#SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int
2409 sizeInHundredthPoints)</a><br />
2410 <a class="message" href="#SCI_STYLEGETSIZEFRACTIONAL">SCI_STYLEGETSIZEFRACTIONAL(int styleNumber)</a><br />
2412 bold)</a><br />
2415 weight)</a><br />
2418 italic)</a><br />
2421 underline)</a><br />
2422 <a class="message" href="#SCI_STYLEGETUNDERLINE">SCI_STYLEGETUNDERLINE(int styleNumber)</a><br />
2424 colour)</a><br />
2427 colour)</a><br />
2430 eolFilled)</a><br />
2431 <a class="message" href="#SCI_STYLEGETEOLFILLED">SCI_STYLEGETEOLFILLED(int styleNumber)</a><br />
2433 int charSet)</a><br />
2434 <a class="message" href="#SCI_STYLEGETCHARACTERSET">SCI_STYLEGETCHARACTERSET(int styleNumber)</a><br />
2436 caseMode)</a><br />
2439 visible)</a><br />
2442 changeable)</a><br />
2443 <a class="message" href="#SCI_STYLEGETCHANGEABLE">SCI_STYLEGETCHANGEABLE(int styleNumber)</a><br />
2445 hotspot)</a><br />
2447 </code>
2451 initialised.</p>
2455 are setting up Scintilla for syntax colouring, it is likely that the lexical styles you set
2456 will be very similar. One way to set the styles is to:<br />
2465 <b id="SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int sizeInHundredthPoints)</b><br />
2475 attributes that are used to match the fonts you request to those available. The
2477 only the first 32 characters of the name are used and the name is not case sensitive. For
2478 internal caching, Scintilla tracks fonts by name and does care about the casing of font names,
2479 so please be consistent. On GTK+, Pango is used to display text.</p>
2481 or to a fractional point size in hundredths of a point with <code>SCI_STYLESETSIZEFRACTIONAL</code>
2483 For example, a text size of 9.4 points is set with <code>SCI_STYLESETSIZEFRACTIONAL(<style>, 940)</code>.
2484 </p>
2486 or <code>SCI_STYLESETWEIGHT</code>. The weight is a number between 1 and 999 with 1 being very light
2487 and 999 very heavy. While any value can be used, fonts often only support between 2 and 4 weights with three weights
2488 being common enough to have symbolic names:
2492 The <code>SCI_STYLESETBOLD</code> message takes a boolean argument with 0 choosing <code>SC_WEIGHT_NORMAL</code>
2494 </p>
2497 underline)</b><br />
2499 You can set a style to be underlined. The underline is drawn in the foreground colour. All
2500 characters with a style that includes the underline attribute are underlined, even if they are
2501 white space.</p>
2509 Text is drawn in the foreground colour. The space in each character cell that is not occupied
2510 by the character is drawn in the background colour.</p>
2513 eolFilled)</b><br />
2515 If the last character in the line has a style with this attribute set, the remainder of the
2516 line up to the right edge of the window is filled with the background colour set for the last
2517 character. This is useful when a document contains embedded sections in another language such
2519 and a consistent background colour (different from the background colour set for the HTML
2520 styles) to all JavaScript styles then JavaScript sections will be easily distinguished from
2521 HTML.</p>
2524 charSet)</b><br />
2526 You can set a style to use a different character set than the default. The places where such
2527 characters sets are likely to be useful are comments and literal strings. For example,
2529 strings in Russian would display correctly in C and C++ (<code>SCE_C_STRING</code> is the style
2530 number used by the C and C++ lexer to display literal strings; it has the value 6). This
2531 feature works differently on Windows and GTK+.</p>
2540 <code>SC_CHARSET_SHIFTJIS</code>, <code>SC_CHARSET_SYMBOL</code>, <code>SC_CHARSET_THAI</code>,
2552 The value of caseMode determines how text is displayed. You can set upper case
2555 displayed.</p>
2559 Text is normally visible. However, you can completely hide it by giving it a style with the
2561 hypertext keywords in HTML or XML.</p>
2564 changeable)</b><br />
2566 This is an experimental and incompletely implemented style attribute. The default setting is
2568 read-only. Currently it only stops the caret from being within not-changeable text and does not
2569 yet stop deleting a range that contains not-changeable text.</p>
2572 hotspot)</b><br />
2574 This style is used to mark ranges of text that can detect mouse clicks.
2575 The cursor changes to a hand over hotspots, and the foreground, and background colours
2576 may change and an underline appear to indicate that these areas are sensitive to clicking.
2577 This may be used to allow hyperlinks to other documents.</p>
2581 <p>The selection is shown by changing the foreground and/or background colours. If one of these
2582 is not set then that attribute is not changed for the selection. The default is to show the
2583 selection by changing the background to light gray and leaving the foreground the same as when
2584 it was not selected. When there is no selection, the current insertion point is marked by the
2585 text caret. This is a vertical line that is normally blinking on and off to attract the users
2586 attention.</p>
2587 <code><a class="message" href="#SCI_SETSELFORE">SCI_SETSELFORE(bool useSelectionForeColour, int colour)</a><br />
2588 <a class="message" href="#SCI_SETSELBACK">SCI_SETSELBACK(bool useSelectionBackColour, int colour)</a><br />
2595 <a class="message" href="#SCI_SETCARETLINEVISIBLE">SCI_SETCARETLINEVISIBLE(bool show)</a><br />
2599 <a class="message" href="#SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int alpha)</a><br />
2607 <a class="message" href="#SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useSetting, int colour)</a><br />
2609 <a class="message" href="#SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useSetting, int colour)</a><br />
2611 <a class="message" href="#SCI_SETHOTSPOTACTIVEUNDERLINE">SCI_SETHOTSPOTACTIVEUNDERLINE(bool underline)</a><br />
2612 <a class="message" href="#SCI_GETHOTSPOTACTIVEUNDERLINE">SCI_GETHOTSPOTACTIVEUNDERLINE</a><br />
2613 <a class="message" href="#SCI_SETHOTSPOTSINGLELINE">SCI_SETHOTSPOTSINGLELINE(bool singleLine)</a><br />
2615 <a class="message" href="#SCI_SETCONTROLCHARSYMBOL">SCI_SETCONTROLCHARSYMBOL(int symbol)</a><br />
2617 <a class="message" href="#SCI_SETCARETSTICKY">SCI_SETCARETSTICKY(int useCaretStickyBehaviour)</a><br />
2620 </code>
2626 You can choose to override the default selection colouring with these two messages. The colour
2629 argument has no effect.</p>
2630 <p><b id="SCI_SETSELALPHA">SCI_SETSELALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2632 The selection can be drawn translucently in the selection background colour by
2633 setting an alpha value.</p>
2637 The selection can be drawn up to the right hand border by setting this property.</p>
2650 <b id="SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2652 You can choose to make the background colour of the line containing the caret different with
2653 these messages. To do this, set the desired background colour with
2657 background colouring has highest priority when a line has markers that would otherwise change
2658 the background colour.
2659 The caret line may also be drawn translucently which allows other background colours to show
2660 through. This is done by setting the alpha (translucency) value by calling
2661 SCI_SETCARETLINEBACKALPHA. When the alpha is not SC_ALPHA_NOALPHA,
2662 the caret line is drawn after all other features so will affect the colour of all other features.
2663 </p>
2668 determines the time in milliseconds that the caret is visible or invisible before changing
2669 state. Setting the period to 0 stops the caret blinking. The default value is 500 milliseconds.
2679 <p>The block character draws most combining and multibyte character sequences successfully,
2680 though some fonts like Thai Fonts (and possibly others) can sometimes appear strange when
2681 the cursor is positioned at these characters, which may result in only drawing a part of the
2682 cursor character sequence. This is most notable on Windows platforms.</p>
2689 1.50), similar to setting the caret style to CARETSTYLE_INVISIBLE (though not interchangable).
2690 This setting only affects the width of the cursor when the cursor style is set to line caret
2691 mode, it does not affect the width for a block caret.</p>
2693 <p><b id="SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useHotSpotForeColour, int <a class="jump"
2696 <b id="SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useHotSpotBackColour, int <a class="jump"
2703 While the cursor hovers over text in a style with the hotspot attribute set,
2704 the default colouring can be modified and an underline drawn with these settings.
2705 Single line mode stops a hotspot from wrapping onto next line.</p>
2709 By default, Scintilla displays control characters (characters with codes less than 32) in a
2713 early days of signaling, though some are still used (LF = Line Feed, BS = Back Space, CR =
2714 Carriage Return, for example).</p>
2716 <p>You can choose to replace these mnemonics by a nominated symbol with an ASCII code in the
2718 as mnemonics. The symbol you set is rendered in the font of the style set for the character.
2725 These messages set, get or toggle the caretSticky setting which controls when the last position
2726 of the caret on the line is saved.</p>
2729 (and all caret position changes) will remember the
2730 caret's new horizontal position when moving to different lines. This is the default.</p>
2732 <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
2733 horizontal caret position is moving the caret with mouse or keyboard (left/right arrow keys, home/end keys, etc). </p>
2735 <p>When set to <code>SC_CARETSTICKY_WHITESPACE</code> (2), the caret acts like mode 0 (sticky off) except under one
2736 special case; when space or tab characters are inserted. (Including pasting <b>only space/tabs</b> -- undo, redo,
2737 etc. do not exhibit this behavior..).</p>
2739 <p><code>SCI_TOGGLECARETSTICKY</code> switches from <code>SC_CARETSTICKY_ON</code> and <code>SC_CARETSTICKY_WHITESPACE</code>
2740 to <code>SC_CARETSTICKY_OFF</code> and from <code>SC_CARETSTICKY_OFF</code> to <code>SC_CARETSTICKY_ON</code>.</p>
2744 <p>There may be up to five margins to the left of the text display, plus a gap either side of
2745 the text. Each margin can be set to display only symbols, line numbers, or text with <a
2747 Textual margins may also display symbols.
2748 The markers
2750 href="#SCI_SETMARGINMASKN"><code>SCI_SETMARGINMASKN</code></a>. Any markers not associated with
2751 a visible margin will be displayed as changes in background colour in the text. A width in
2752 pixels can be set for each margin. Margins with a zero width are ignored completely. You can
2755 selects a line of text.</p>
2759 is hidden. Margin 1 is set to display non-folding symbols and is given a width of 16 pixels, so
2760 it is visible. Margin 2 is set to display the folding symbols, but is given a width of 0, so it
2761 is hidden. Of course, you can set the margins to be whatever you wish.</p>
2764 <p><img src="styledmargin.png" alt="Styled text margins used to show revision and blame information" /></p>
2767 type)</a><br />
2770 pixelWidth)</a><br />
2773 mask)</a><br />
2776 sensitive)</a><br />
2778 margin)</a><br />
2780 cursor)</a><br />
2782 margin)</a><br />
2784 pixels)</a><br />
2787 pixels)</a><br />
2789 <a class="message" href="#SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</a><br />
2790 <a class="message" href="#SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</a><br />
2793 <a class="message" href="#SCI_MARGINSETSTYLE">SCI_MARGINSETSTYLE(int line, int style)</a><br />
2795 <a class="message" href="#SCI_MARGINSETSTYLES">SCI_MARGINSETSTYLES(int line, char *styles)</a><br />
2796 <a class="message" href="#SCI_MARGINGETSTYLES">SCI_MARGINGETSTYLES(int line, char *styles)</a><br />
2798 <a class="message" href="#SCI_MARGINSETSTYLEOFFSET">SCI_MARGINSETSTYLEOFFSET(int style)</a><br />
2800 <a class="message" href="#SCI_SETMARGINOPTIONS">SCI_SETMARGINOPTIONS(int marginOptions)</a><br />
2802 </code>
2806 These two routines set and get the type of a margin. The margin argument should be 0, 1, 2, 3 or 4.
2811 By convention, margin 0 is used for line numbers and the next two are used for symbols. You can
2813 symbol margins that set their background colour to match the STYLE_DEFAULT background and
2814 foreground colours.</p>
2818 These routines set and get the width of a margin in pixels. A margin with zero width is
2820 is a reasonable guess if you are not sure what would be appropriate. Line number margins widths
2821 should take into account the number of lines in the document and the line number style. You
2824 suitable width.</p>
2829 displayed in a margin that is enabled for symbols. There is a useful constant,
2831 symbols used to denote folding. You can assign a wide range of symbols and colours to each of
2832 the 32 logical symbols, see <a href="#Markers">Markers</a> for more information. If <code>(mask
2838 does not appear in the mask of any margin with a non-zero width, the marker changes the
2839 background colour of the line. For example, suppose you decide to use logical marker 10 to mark
2840 lines with a syntax error and you want to show such lines by changing the background colour.
2842 sure that no symbol margin includes 0x400 in its mask, any line with the marker gets the
2843 background colour changed.</p>
2846 which is the default set by Scintilla.
2849 decimal. Of course, you may need to display all 32 symbols in a margin, in which case use
2853 sensitive)</b><br />
2855 Each of the five margins can be set sensitive or insensitive to mouse clicks. A click in a
2859 selection margins which make it easy to select ranges of lines. By default, all margins are
2860 insensitive.</p>
2863 cursor)</b><br />
2865 A reversed arrow cursor is normally shown over all margins. This may be changed to a normal arrow with
2867 reversed arrow with
2874 These messages set and get the width of the blank margin on both sides of the text in pixels.
2875 The default is to one pixel on each side.</p>
2877 <p><b id="SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</b><br />
2878 <b id="SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</b><br />
2879 These messages allow changing the colour of the fold margin and fold margin highlight.
2880 On Windows the fold margin colour defaults to ::GetSysColor(COLOR_3DFACE) and the fold margin highlight
2881 colour to ::GetSysColor(COLOR_3DHIGHLIGHT).</p>
2883 <p>
2891 Text margins are created with the type SC_MARGIN_TEXT or SC_MARGIN_RTEXT.
2893 The whole of the text margin on a line may be displayed in a particular style with
2897 Setting a text margin will cause a
2899 notification to be sent.
2900 </p>
2901 <p>
2902 Only some style attributes are active in text margins: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
2903 </p>
2904 <p>
2907 Margin styles may be completely separated from standard text styles by setting a style offset. For example,
2909 256 upto 511 so they do not overlap styles set by lexers. Each style number set with <code>SCI_MARGINSETSTYLE</code>
2911 </p>
2912 <p>
2915 Define margin options by enabling appropriate bit flags. At the moment, only one flag is available
2916 <code>SC_MARGINOPTION_SUBLINESELECT</code>=1, which controls how wrapped lines are selected when clicking
2917 on margin in front of them. If <code>SC_MARGINOPTION_SUBLINESELECT</code> is set only sub line of wrapped
2918 line is selected, otherwise whole wrapped line is selected. Margin options are set to
2920 </p>
2924 <p>Annotations are read-only lines of text underneath each line of editable text.
2925 An annotation may consist of multiple lines separated by '\n'.
2926 Annotations can be used to display an assembler version of code for debugging or to show diagnostic messages inline or to
2927 line up different versions of text in a merge tool.</p>
2931 <code>
2932 <a class="message" href="#SCI_ANNOTATIONSETTEXT">SCI_ANNOTATIONSETTEXT(int line, char *text)</a><br />
2933 <a class="message" href="#SCI_ANNOTATIONGETTEXT">SCI_ANNOTATIONGETTEXT(int line, char *text)</a><br />
2934 <a class="message" href="#SCI_ANNOTATIONSETSTYLE">SCI_ANNOTATIONSETSTYLE(int line, int style)</a><br />
2936 <a class="message" href="#SCI_ANNOTATIONSETSTYLES">SCI_ANNOTATIONSETSTYLES(int line, char *styles)</a><br />
2937 <a class="message" href="#SCI_ANNOTATIONGETSTYLES">SCI_ANNOTATIONGETSTYLES(int line, char *styles)</a><br />
2940 <a class="message" href="#SCI_ANNOTATIONSETVISIBLE">SCI_ANNOTATIONSETVISIBLE(int visible)</a><br />
2942 <a class="message" href="#SCI_ANNOTATIONSETSTYLEOFFSET">SCI_ANNOTATIONSETSTYLEOFFSET(int style)</a><br />
2944 </code>
2946 <p>
2957 The whole of the text ANNOTATION on a line may be displayed in a particular style with
2959 <code>SCI_ANNOTATIONSETSTYLES</code> which uses an array of bytes with each byte setting the style
2960 of the corresponding text byte similar to <code>SCI_SETSTYLINGEX</code>. The text must be set first as it
2961 specifies how long the annotation is so how many bytes of styling to read.
2962 Setting an annotation will cause a
2964 notification to be sent.
2965 </p>
2966 <p>
2967 The number of lines annotating a line can be retrieved with <code>SCI_ANNOTATIONGETLINES</code>.
2969 which is equivalent to clearing each line (setting to 0) and then deleting other memory used for this feature.
2970 </p>
2971 <p>
2972 Only some style attributes are active in annotations: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
2973 </p>
2974 <p>
2977 Annotations can be made visible in a view and there is a choice of display style when visible.
2979 argument can be one of:</p>
2983 <tr>
2989 </tr>
2991 <tr>
2997 </tr>
2999 <tr>
3005 </tr>
3006 </tbody>
3007 </table>
3009 <p>
3012 Annotation styles may be completely separated from standard text styles by setting a style offset. For example,
3013 <code>SCI_ANNOTATIONSETSTYLEOFFSET(512)</code> would allow the annotation styles to be numbered from
3014 512 upto 767 so they do not overlap styles set by lexers (or margins if margins offset is 256).
3017 </p>
3021 allowPaletteUse)</a><br />
3035 <a class="message" href="#SCI_SETWORDCHARS">SCI_SETWORDCHARS(<unused>, const char *characters)</a><br />
3036 <a class="message" href="#SCI_GETWORDCHARS">SCI_GETWORDCHARS(<unused>, char *characters)</a><br />
3037 <a class="message" href="#SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</a><br />
3038 <a class="message" href="#SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</a><br />
3039 <a class="message" href="#SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</a><br />
3040 <a class="message" href="#SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</a><br />
3045 </code>
3049 the handle to the Scintilla window you created as your editor.</p>
3051 <p>While we are on the subject of forwarding messages in Windows, the top level window should
3053 collect changes to mouse settings, but could be used for other user interface items in the
3054 future).</p>
3058 These messages turn buffered drawing on or off and report the buffered drawing state. Buffered
3059 drawing draws each line into a bitmap rather than directly to the screen and then copies the
3060 bitmap to the screen. This avoids flickering although it does take longer. The default is for
3061 drawing to be buffered.</p>
3065 Two phase drawing is a better but slower way of drawing text.
3066 In single phase drawing each run of characters in one style is drawn along with its background.
3067 If a character overhangs the end of a run, such as in "<i>V</i>_" where the
3070 cuts it off. Two phase drawing
3071 fixes this by drawing all the backgrounds first and then drawing the text in
3072 transparent mode. Two phase drawing may flicker more than single phase
3073 unless buffered drawing is on. The default is for drawing to be two phase.</p>
3077 The technology property allows choosing between different drawing APIs and options.
3080 can be chosen to use the Direct2D and DirectWrite APIs for higher quality antialiased drawing.
3081 Since Direct2D buffers drawing, Scintilla's buffering can be turned off with
3086 Manage font quality (antialiasing method). Currently, the following values are available on Windows:
3091 <p>In case it is necessary to squeeze more options into this property, only a limited number of bits defined
3096 Scintilla has some support for Japanese, Chinese and Korean DBCS. Use this message with
3097 <code>codePage</code> set to the code page number to set Scintilla to use code page information
3098 to ensure double byte characters are treated as one character rather than two. This also stops
3099 the caret from moving between the two bytes in a double byte character.
3100 Do not use this message to choose between different single byte character sets: it doesn't do that.
3101 Call with
3105 <p>Code page <code>SC_CP_UTF8</code> (65001) sets Scintilla into Unicode mode with the document
3106 treated as a sequence of characters expressed in UTF-8. The text is converted to the platform's
3107 normal Unicode encoding before being drawn by the OS and thus can display Hebrew, Arabic,
3108 Cyrillic, and Han characters. Languages which can use two characters stacked vertically in one
3109 horizontal space, such as Thai, will mostly work but there are some issues where the characters
3110 are drawn separately leading to visual glitches. Bi-directional text is not supported. </p>
3114 although these may require installation of language specific support.</p>
3118 On Windows, character keys are normally handled differently depending on whether Scintilla is a wide
3119 or narrow character window with character messages treated as Unicode when wide and as 8 bit otherwise.
3120 Set this property to always treat as Unicode. This option is needed for Delphi.</p>
3123 Scintilla has several functions that operate on words, which are defined to be contiguous
3124 sequences of characters from a particular set of characters. This message defines which
3125 characters are members of that set. The character sets are set to default values before processing this
3126 function.
3127 For example, if you don't allow '_' in your set of characters
3128 use:<br />
3129 <code>SCI_SETWORDCHARS(0, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")</code>;</p>
3132 This fills the characters parameter with all the characters included in words.
3133 The characters parameter must be large enough to hold all of the characters.
3134 If the characters parameter is 0 then the length that should be allocated
3135 to store the entire set is returned.</p>
3137 <p><b id="SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</b><br />
3138 <b id="SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</b><br />
3139 Similar to <code>SCI_SETWORDCHARS</code>, this message allows the user to define which chars Scintilla considers
3140 as whitespace. Setting the whitespace chars allows the user to fine-tune Scintilla's behaviour doing
3141 such things as moving the cursor to the start or end of a word; for example, by defining punctuation chars
3142 as whitespace, they will be skipped over when the user presses ctrl+left or ctrl+right.
3144 reset the whitespace characters to the default set.
3147 <p><b id="SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</b><br />
3148 <b id="SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</b><br />
3150 allows the user to define which chars Scintilla considers as punctuation.
3154 Use the default sets of word and whitespace characters. This sets whitespace to space, tab and other
3155 characters with codes less than 0x20, with word characters set to alphanumeric and '_'.
3156 </p>
3162 Scintilla can be told to grab the focus with this message. This is needed more on GTK+ where
3163 focus handling is more complicated than on Windows.</p>
3166 that have complex focus requirements such as having their own window that gets the real focus
3167 but with the need to indicate that Scintilla has the logical focus.</p>
3171 pos2)</a><br />
3173 <a class="message" href="#SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</a><br />
3174 <a class="message" href="#SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</a><br />
3176 maxReStyle)</a><br />
3177 </code>
3180 Up to two characters can be highlighted in a 'brace highlighting style', which is defined as
3181 style number <a class="message" href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34).
3182 If you have enabled indent guides, you may also wish to highlight the indent that corresponds
3191 highlight.</p>
3193 <p><b id="#SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</b><br />
3194 Use specified indicator to highlight matching braces instead of changing their style.</p>
3196 <p><b id="#SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</b><br />
3197 Use specified indicator to highlight non matching brace instead of changing its style.</p>
3203 from a closing brace. If the character at position is not a brace character, or a matching
3204 brace cannot be found, the return value is -1. Otherwise, the return value is the position of
3205 the matching brace.</p>
3207 <p>A match only occurs if the style of the matching brace is the same as the starting brace or
3208 the matching brace is beyond the end of styling. Nested braces are handled correctly. The
3210 the length of brace searches.</p>
3214 <p>Indentation (the white space at the start of a line) is often used by programmers to clarify
3215 program structure and in some languages, for example Python, it may be part of the language
3216 syntax. Tabs are normally used in editors to insert a tab character or to pad text with spaces
3217 up to the next tab.</p>
3219 <p>Scintilla can be set to treat tab and backspace in the white space at the start of a line in
3220 a special way: inserting a tab indents the line to the next indent position rather than just
3221 inserting a tab at the current character position and backspace unindents the line rather than
3222 deleting a character. Scintilla can also display indentation guides (vertical lines) to help
3223 you to generate code.</p>
3233 bsUnIndents)</a><br />
3236 indentation)</a><br />
3239 line)</a><br />
3240 <a class="message" href="#SCI_SETINDENTATIONGUIDES">SCI_SETINDENTATIONGUIDES(int indentView)</a><br />
3244 </code>
3255 of tabs and spaces or be based purely on spaces. Set <code>useTabs</code> to <code>false</code>
3256 (0) to create all tabs and indents out of spaces. The default is <code>true</code>. You can use
3258 position taking the width of a tab into account.</p>
3263 0, the indent size is the same as the tab size. There are no limits on indent sizes, but values
3264 less than 0 or large values may have undesirable effects.
3265 </p>
3271 </p>
3273 <p>Inside indentation white space, the tab and backspace keys can be made to indent and
3274 unindent rather than insert a tab character or delete a character with the
3279 The amount of indentation on a line can be discovered and set with
3280 <code>SCI_GETLINEINDENTATION</code> and <code>SCI_SETLINEINDENTATION</code>. The indentation is
3281 measured in character columns, which correspond to the width of space characters.</p>
3284 This returns the position at the end of indentation of a line.</p>
3288 Indentation guides are dotted vertical lines that appear within indentation white space every
3289 indent size columns. They make it easy to see which constructs line up especially when they
3292 foreground and background colour of the indentation guides.</p>
3295 SC_IV_NONE turns the feature off but the other 3 states determine how far the guides appear on
3296 empty lines. </p>
3298 <tbody>
3299 <tr>
3302 </tr>
3304 <tr>
3307 </tr>
3309 <tr>
3311 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3312 next non-empty line.
3313 If the previous non-empty line was a fold header then indentation guides are shown for
3314 one more level of indent than that line. This setting is good for Python.</td>
3315 </tr>
3317 <tr>
3319 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3320 next non-empty line or previous non-empty line whichever is the greater.
3321 This setting is good for most languages.</td>
3322 </tr>
3324 </tbody>
3325 </table>
3329 When brace highlighting occurs, the indentation guide corresponding to the braces may be
3331 href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34). Set <code>column</code> to 0 to
3332 cancel this highlight.</p>
3336 <p>There are 32 markers, numbered 0 to <code>MARKER_MAX</code> (31), and you can assign any combination of them to each
3338 margin</a> to the left of the text. If the selection margin is set to zero width, the
3344 or the current point of execution, break points, or whatever you need marking. If you do not
3347 <p>Each marker number has a symbol associated with it. You can also set the foreground and
3348 background colour for each marker number, so you can use the same symbol more than once with
3349 different colouring for different uses. Scintilla has a set of symbols you can assign
3353 <p>The markers are drawn in the order of their numbers, so higher numbered markers appear on
3354 top of lower numbered ones. Markers try to move with their text by tracking where the start of
3356 operation, with the markers of the previous line.</p>
3358 markerSymbols)</a><br />
3360 const char *xpm)</a><br />
3363 <a class="message" href="#SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber,
3364 const char *pixels)</a><br />
3366 </a><br />
3368 colour)</a><br />
3370 colour)</a><br />
3371 <a class="message" href="#SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int
3372 colour)</a><br />
3373 <a class="message" href="#SCI_MARKERENABLEHIGHLIGHT">SCI_MARKERENABLEHIGHLIGHT(int enabled)</a><br />
3375 alpha)</a><br />
3377 <a class="message" href="#SCI_MARKERADDSET">SCI_MARKERADDSET(int line, int markerMask)</a><br />
3379 markerNumber)</a><br />
3383 markerMask)</a><br />
3385 markerMask)</a><br />
3387 handle)</a><br />
3389 </code>
3393 an ASCII character. The general-purpose marker symbols currently available are:<br />
3402 The <code>SC_MARK_FULLRECT</code> symbol mirrors this, changing only the margin background colour.
3405 of lines. You would also use it if you changed the folding style and wanted one or more of the
3409 plugins may allocate that marker number.
3410 </p>
3412 <p>There are also marker symbols designed for use in the folding margin in a flattened tree
3413 style.<br />
3420 Characters can be used as markers by adding the ASCII value of the character to
3425 <p>The marker numbers <code>SC_MARKNUM_FOLDER</code> and <code>SC_MARKNUM_FOLDEROPEN</code> are
3426 used for showing that a fold is present and open or closed. Any symbols may be assigned for
3429 these two, more assignments are needed for the flattened tree style:
3438 Macintosh), plus/minus shows folded lines as '+' and opened folds as '-', Circle tree, Box
3439 tree.</p>
3443 <tr>
3453 </tr>
3454 </thead>
3457 <tr>
3467 </tr>
3469 <tr>
3479 </tr>
3481 <tr>
3491 </tr>
3493 <tr>
3503 </tr>
3505 <tr>
3515 </tr>
3517 <tr>
3527 </tr>
3529 <tr>
3539 </tr>
3540 </tbody>
3541 </table>
3544 *xpm)</b><br />
3545 Markers can be set to pixmaps with this message. The
3549 <p>
3552 <b id="SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber, const char *pixels)</b><br />
3553 Markers can be set to translucent pixmaps with this message. The
3568 These two messages set the foreground and background colour of a marker number.<br />
3569 <b id="SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int <a class="jump"
3571 This message sets the highlight background colour of a marker number when its folding block is selected. The default colour is #FF0000.</p>
3573 This message allows to enable/disable the highlight folding block when it is selected. (i.e. block that contains the caret)</p>
3576 When markers are drawn in the content area, either because there is no margin for them or
3577 they are of <code>SC_MARK_BACKGROUND</code> or <code>SC_MARK_UNDERLINE</code> types, they may be drawn translucently by
3578 setting an alpha value.</p>
3582 this fails (illegal line number, out of memory) or it returns a marker handle number that
3587 based on its handle. The message does not check the value of markerNumber, nor does it
3588 check if the line already contains the marker.</p>
3591 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
3593 (and used by the mask-based marker search functions
3596 As with
3598 to see if any of the markers are already present on the targeted line.</p>
3601 This searches the given line number for the given marker number and deletes it if it is
3602 present. If you added the same marker more than once to the line, this will delete one copy
3603 each time it is used. If you pass in a marker number of -1, all markers are deleted from the
3604 line.</p>
3607 This removes markers of the given number from all lines. If markerNumber is -1, it deletes all
3608 markers from all lines.</p>
3616 These messages search efficiently for lines that include a given set of markers. The search
3619 (<code>SCI_MARKERPREVIOUS</code>). The <code>markerMask</code> argument should have one bit set
3620 for each marker you wish to find. Set bit 0 to find marker 0, bit 1 for marker 1 and so on. The
3621 message returns the line number of the first line that contains one of the markers in
3627 the document for the marker with this handle and returns the line number that contains it or -1
3628 if it is not found.</p>
3633 the document for the marker with this handle and deletes the marker if it is found.</p>
3637 <p>Indicators are used to display additional information over the top of styling.
3638 They can be used to show, for example, syntax errors, deprecated names and bad indentation
3639 by drawing underlines under text or boxes around text. Originally, Scintilla stored indicator information in
3640 the style bytes but this has proved limiting, so now up to 32 separately stored indicators may be used.
3641 While style byte indicators currently still work, they will soon be removed so all the bits in each style
3642 byte can be used for lexical states.</p>
3644 <p>Indicators may be displayed as simple underlines, squiggly underlines, a
3645 line of small 'T' shapes, a line of diagonal hatching, a strike-out or a rectangle around the text.</p>
3648 indicators. They all use an <code>indicatorNumber</code> argument in the range 0 to INDIC_MAX(31)
3649 to set the indicator to style. To prevent interference the set of indicators is divided up into a range for use
3654 indicatorStyle)</a><br />
3657 colour)</a><br />
3659 <a class="message" href="#SCI_INDICSETALPHA">SCI_INDICSETALPHA(int indicatorNumber, int alpha)</a><br />
3661 <a class="message" href="#SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</a><br />
3662 <a class="message" href="#SCI_INDICGETOUTLINEALPHA">SCI_INDICGETOUTLINEALPHA(int indicatorNumber)</a><br />
3663 <a class="message" href="#SCI_INDICSETUNDER">SCI_INDICSETUNDER(int indicatorNumber, bool under)</a><br />
3665 </code>
3668 indicatorStyle)</b><br />
3670 These two messages set and get the style for a particular indicator. The indicator styles
3671 currently available are:</p>
3674 <tbody>
3675 <tr>
3681 </tr>
3682 </tbody>
3685 <tr>
3691 </tr>
3693 <tr>
3699 </tr>
3701 <tr>
3707 </tr>
3709 <tr>
3715 </tr>
3717 <tr>
3723 </tr>
3725 <tr>
3731 </tr>
3733 <tr>
3739 </tr>
3741 <tr>
3746 <td>A rectangle with rounded corners around the text using translucent drawing with the
3747 interior usually more transparent than the border. You can use
3750 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
3751 </tr>
3753 <tr>
3758 <td>A rectangle around the text using translucent drawing with the
3759 interior usually more transparent than the border. You can use
3762 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
3763 </tr>
3765 <tr>
3771 </tr>
3773 <tr>
3779 </tr>
3781 <tr>
3787 so will fit under small fonts.</td>
3788 </tr>
3790 <tr>
3795 <td>A dotted rectangle around the text using translucent drawing.
3796 Translucency alternates between the alpha and outline alpha settings with the top-left pixel using the alpha setting.
3799 control the alpha transparency values. The default values are 30 for alpha and 50 for outline alpha.
3800 To avoid excessive memory allocation the maximum width of a dotted box is 4000 pixels.
3801 Not available for OS X Carbon.</td>
3802 </tr>
3804 </tbody>
3805 </table>
3812 <p><b id="SCI_INDICSETFORE">SCI_INDICSETFORE(int indicatorNumber, int <a class="jump" href="#colour">colour</a>)</b><br />
3814 These two messages set and get the colour used to draw an indicator. The default indicator
3815 colours are equivalent to:<br />
3822 These two messages set and get the alpha transparency used for drawing the
3823 fill colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
3825 </p>
3827 <p><b id="SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</b><br />
3829 These two messages set and get the alpha transparency used for drawing the
3830 outline colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
3832 </p>
3836 These two messages set and get whether an indicator is drawn under text or over(default).
3837 Drawing under text works only for modern indicators when <a class="message" href="#SCI_SETTWOPHASEDRAW">two phase drawing</a>
3838 is enabled.</p>
3842 <p>Modern indicators are stored in a format similar to run length encoding which is efficient in both
3843 speed and storage for sparse information.</p>
3844 <p>An indicator may store different values for each range but currently all values are drawn the same.
3845 In the future, it may be possible to draw different values in different styles.</p>
3846 <p>
3849 These two messages set and get the indicator that will be affected by calls to
3850 <a class="message" href="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE(int position, int fillLength)</a> and
3851 <a class="message" href="#SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</a>.
3852 </p>
3854 <p>
3857 These two messages set and get the value that will be set by calls to
3859 </p>
3861 <p>
3863 <b id="SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</b><br />
3864 These two messages fill or clear a range for the current indicator.
3866 the current value.
3867 </p>
3869 <p>
3871 Retrieve a bitmap value representing which indicators are non-zero at a position.
3872 </p>
3874 <p>
3876 Retrieve the value of a particular indicator at a position.
3877 </p>
3879 <p>
3882 Find the start or end of a range with one value from a position within the range.
3883 Can be used to iterate through the document to discover all the indicator positions.
3884 </p>
3888 <p>On OS X search matches are highlighted with an animated gold rounded rectangle.
3889 The indicator shows, then briefly grows 25% and shrinks to the original size to draw the user's attention.
3890 While this feature is currently only implemented on OS X, it may be implemented on other platforms
3891 in the future.</p>
3895 These two messages show and animate the find indicator. The indicator remains visible with
3898 <code>SCI_FINDINDICATORSHOW</code> behaves similarly to the OS X TextEdit and Safari applications
3899 and is best suited to editing documentation where the search target is often a word.
3901 where the match will often be located next to operators which would otherwise be hidden under the indicator's
3902 padding.
3903 </p>
3906 This message hides the find indicator.
3907 </p>
3912 indicators so that, for example, syntax errors, deprecated names and bad indentation could all
3913 be displayed at once.</p>
3916 href="#SCI_STARTSTYLING"><code>SCI_STARTSTYLING</code></a> with a <code>INDICS_MASK</code> mask
3920 <p>If you are using indicators in a buffer that has a lexer active
3922 you must save lexing state information before setting any indicators and restore it afterwards.
3924 to retrieve the current "styled to" position and
3926 to reset the styling position and mask (<code>0x1f </code> in the default layout of 5 style bits and 3 indicator bits)
3927 when you are done.</p>
3930 href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> from 0 to 8 bits. The remaining bits
3933 styling information and 3 indicators. If you use a different arrangement, you must define your
3934 own constants.</p>
3939 <p>Autocompletion displays a list box showing likely identifiers based upon the user's typing.
3940 The user chooses the currently selected item by pressing the tab character or another character
3942 Autocompletion is triggered by your application. For example, in C if you detect that the user
3944 list of members, you could offer them in an autocompletion list. Alternatively, you could
3945 monitor the user's typing and offer a list of likely items once their typing has narrowed down
3946 the choice to a reasonable list. As yet another alternative, you could define a key code to
3947 activate the list.</p>
3949 <p>When the user makes a selection from the list the container is sent a <code><a class="message"
3951 href="#Notifications">notification message</a>. On return from the notification Scintilla will insert
3952 the selected text unless the autocompletion list has been cancelled, for example by the container sending
3955 <p>To make use of autocompletion you must monitor each character added to the document. See
3958 *list)</a><br />
3964 *chars)</a><br />
3966 separator)</a><br />
3969 *select)</a><br />
3972 char *text)</a><br />
3974 cancel)</a><br />
3977 *chars)</a><br />
3979 chooseSingle)</a><br />
3982 ignoreCase)</a><br />
3984 <a class="message" href="#SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</a><br>
3985 <a class="message" href="#SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR</a><br>
3989 dropRestOfWord)</a><br />
3991 <a class="message" href="#SCI_REGISTERIMAGE">SCI_REGISTERIMAGE(int type, const char *xpmData)</a><br />
3992 <a class="message" href="#SCI_REGISTERRGBAIMAGE">SCI_REGISTERRGBAIMAGE(int type, const char *pixels)</a><br />
3994 <a class="message" href="#SCI_AUTOCSETTYPESEPARATOR">SCI_AUTOCSETTYPESEPARATOR(char separatorCharacter)</a><br />
3998 <a class="message" href="#SCI_AUTOCSETMAXWIDTH">SCI_AUTOCSETMAXWIDTH(int characterCount)</a><br />
4000 </code>
4005 separator characters. The initial separator character is a space but this can be set or got
4010 <p>The list of words should be in sorted order. If set to ignore case mode with <a class="message" href="#SCI_AUTOCSETIGNORECASE"><code>SCI_AUTOCSETIGNORECASE</code></a>, then
4011 strings are matched after being converted to upper case. One result of this is that the list
4012 should be sorted with the punctuation characters '[', '\', ']', '^', '_', and '`' sorted after
4013 letters.</p>
4016 This message cancels any displayed autocompletion list. When in autocompletion mode, the list
4017 should disappear when the user types a character that can not be part of the autocompletion,
4018 such as '.', '(' or '[' when typing an identifier. A set of characters that will cancel
4023 This message returns non-zero if there is an active autocompletion list and zero if there is
4024 not.</p>
4028 of the list.</p>
4031 This message triggers autocompletion. This has the same effect as the tab key.</p>
4035 automatically cancel the autocompletion list. When you start the editor, this list is
4036 empty.</p>
4040 These two messages set and get the separator character used to separate words in the
4045 This message selects an item in the autocompletion list. It searches the list of words for the
4046 first that matches <code>select</code>. By default, comparisons are case sensitive, but you can
4051 item is found, it is selected. If the item is not found, the autocompletion list closes if
4056 <p><b id="SCI_AUTOCGETCURRENTTEXT">SCI_AUTOCGETCURRENTTEXT(<unused>, char *text)</b><br />
4057 This message retrieves the current selected text in the autocompletion list. Normally the
4059 is used instead.</p>
4061 <p>The value is copied to the <code>text</code> buffer, returning the length (not including the
4069 The default behavior is for the list to be cancelled if the caret moves to the location it
4070 was at when the list was displayed. By calling this message with a <code>false</code> argument,
4071 the list is not cancelled until the caret moves at least one character before the word being
4072 completed.</p>
4074 <p><b id="SCI_AUTOCSETFILLUPS">SCI_AUTOCSETFILLUPS(<unused>, const char *chars)</b><br />
4075 If a fillup character is typed with an autocompletion list active, the currently selected item
4076 in the list is added into the document, then the fillup character is added. Common fillup
4077 characters are '(', '[' and '.' but others are possible depending on the language. By default,
4078 no fillup characters are set.</p>
4083 automatically added and no list is displayed. The default is to display the list even if there
4084 is only a single item.</p>
4088 By default, matching of characters to list members is case sensitive. These messages let you
4089 set and get case sensitivity.</p>
4091 <p><b id="SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</b><br>
4093 When autocompletion is set to ignore case (<code>SCI_AUTOCSETIGNORECASE</code>), by default it will
4094 nonetheless select the first list member that matches in a case sensitive way to entered characters.
4095 This corresponds to a behaviour property of <code>SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE</code> (0).
4096 If you want autocompletion to ignore case at all, choose <code>SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE</code> (1).</p>
4100 By default, the list is cancelled if there are no viable matches (the user has typed
4101 characters that no longer match a list entry). If you want to keep displaying the original
4105 <p><b id="SCI_AUTOCSETDROPRESTOFWORD">SCI_AUTOCSETDROPRESTOFWORD(bool dropRestOfWord)</b><br />
4107 When an item is selected, any word characters following the caret are first erased if
4110 <p>
4117 Autocompletion list items may display an image as well as text. Each image is first registered with an integer
4118 type. Then this integer is included in the text of the list separated by a '?' from the text. For example,
4120 The images are in either the <a class="jump" href="#XPM">XPM format</a> (<code>SCI_REGISTERIMAGE</code>) or
4123 the <a class="message" href="#SCI_RGBAIMAGESETWIDTH"><code>SCI_RGBAIMAGESETWIDTH</code></a> and
4124 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.
4125 The set of registered images can be cleared with <code>SCI_CLEARREGISTEREDIMAGES</code> and the '?' separator changed
4127 </p>
4129 <p>
4133 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
4134 scrollbar is shown. The default is 5.
4135 </p>
4137 <p>
4141 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.
4142 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
4143 the available width are indicated by the presence of ellipsis.
4144 </p>
4148 <p>User lists use the same internal mechanisms as autocompletion lists, and all the calls
4149 listed for autocompletion work on them; you cannot display a user list at the same time as an
4150 autocompletion list is active. They differ in the following respects:</p>
4154 effect.<br />
4160 <p>BEWARE: if you have set fillup characters or stop characters, these will still be active
4161 with the user list, and may result in items being selected or the user list cancelled due to
4162 the user typing into the editor.</p>
4167 structure. It must be greater than 0 as this is how Scintilla tells the difference between an
4168 autocompletion list and a user list. If you have different types of list, for example a list of
4170 a selection. </p>
4174 <p>Call tips are small windows displaying the arguments to a function and are displayed after
4175 the user has typed the name of the function. They normally display characters using the font
4176 facename, size and character set defined by
4179 facename, size, foreground and background colours and character set with
4181 This also enables support for Tab characters.
4183 There is some interaction between call tips and autocompletion lists in that showing a
4184 call tip cancels any active autocompletion list, and vice versa.</p>
4186 <p>Call tips can highlight part of the text within them. You could use this to highlight the
4187 current argument to a function by counting the number of commas (or whatever separator your
4189 example of call tip use.</p>
4191 <p>The mouse may be clicked on call tips and this causes a
4193 notification to be sent to the container. Small up and down arrows may be displayed within
4195 for showing that there are overloaded variants of one function name and that the user can
4196 click on the arrows to cycle through the overloads.</p>
4198 <p>Alternatively, call tips can be displayed when you leave the mouse pointer for a while over
4203 the value of a variable, or during editing to give information about the word under the
4204 pointer.</p>
4206 *definition)</a><br />
4211 highlightEnd)</a><br />
4217 </code>
4220 This message starts the process by displaying the call tip window. If a call tip is already
4221 active, this has no effect.<br />
4223 tip text is aligned to start 1 line below this character unless you have included up and/or
4224 down arrows in the call tip text in which case the tip is aligned to the right-hand edge of
4225 the rightmost arrow. The assumption is that you will start the text with something like
4228 '\n' (Line Feed, ASCII code 10) characters. Do not include '\r' (Carriage Return, ASCII
4230 supported if you set a tabsize with
4234 This message cancels any displayed call tip. Scintilla will also cancel call tips for you if
4235 you use any keyboard commands that are not compatible with editing the argument list of a
4236 function.</p>
4243 started to display the tip.</p>
4246 This sets the region of the call tips text to display in a highlighted style.
4249 <code>hlEnd</code> must be greater than <code>hlStart</code>; <code>hlEnd-hlStart</code> is the
4250 number of characters to highlight. Highlights can extend over line ends if this is
4251 required.</p>
4253 <p>Unhighlighted text is drawn in a mid gray. Selected text is drawn in a dark blue. The
4254 background is white. These can be changed with
4258 </p>
4261 The background colour of call tips can be set with this message; the default colour is white.
4262 It is not a good idea to set a dark colour as the background as the default colour for normal
4263 calltip text is mid gray and the defaultcolour for highlighted text is dark blue. This also
4267 The colour of call tip text can be set with this message; the default colour is mid gray.
4271 The colour of highlighted call tip text can be set with this message; the default colour
4272 is dark blue.</p>
4277 less than 1, Tab characters are not treated specially. Once this call has been used, the
4278 call tip foreground and background colours are also taken from the style.</p>
4287 <p>To allow the container application to perform any of the actions available to the user with
4288 keyboard, all the keyboard actions are messages. They do not take any parameters. These
4293 <tbody>
4294 <tr>
4302 </tr>
4304 <tr>
4312 </tr>
4314 <tr>
4322 </tr>
4324 <tr>
4330 </tr>
4332 <tr>
4338 </tr>
4340 <tr>
4348 </tr>
4350 <tr>
4358 </tr>
4360 <tr>
4368 </tr>
4370 <tr>
4376 </tr>
4378 <tr>
4386 </tr>
4388 <tr>
4394 </tr>
4396 <tr>
4400 </tr>
4402 <tr>
4408 </tr>
4410 <tr>
4418 </tr>
4420 <tr>
4428 </tr>
4430 <tr>
4436 </tr>
4438 <tr>
4444 </tr>
4447 <tr>
4451 </tr>
4453 <tr>
4457 </tr>
4459 <tr>
4463 </tr>
4465 <tr>
4471 </tr>
4473 <tr>
4479 </tr>
4481 <tr>
4489 </tr>
4491 <tr>
4499 </tr>
4501 <tr>
4509 </tr>
4511 <tr>
4516 </tr>
4518 <tr>
4522 </tr>
4524 <tr>
4528 </tr>
4529 </tbody>
4530 </table>
4535 (and convert regular selection to rectangular one, if any).</p>
4538 capitalisation (aCamelCaseIdentifier) or underscores (an_under_bar_ident).</p>
4542 (ie. just after the indentation) unless it is already there; in this case, it acts as SCI_HOME*.</p>
4545 allow movement to the start or end of display lines as opposed to the normal
4550 They go first to the start / end of the display line, like <code>SCI_[HOME|LINEEND]DISPLAY*</code>,
4551 but if the cursor is already at the point, it goes on to the start or end of the document line,
4553 </p>
4556 or end without changing the selection. These commands match OS X platform conventions for the behaviour of the
4559 </p>
4563 <p>There is a default binding of keys to commands that is defined in the Scintilla source in
4567 command that has no arguments can be mapped). You can change the mapping to suit your own
4568 requirements.</p>
4570 sciCommand)</a><br />
4574 </code>
4577 A key definition contains the key code in the low 16-bits and the key modifiers in the high
4579 <br />
4583 enumeration, which contains:<br />
4586 <code>SCK_INSERT</code>, <code>SCK_LEFT</code>, <code>SCK_MENU</code>, <code>SCK_NEXT</code> (Page Down),
4596 If you are building a table, you might
4601 This assigns the given key definition to a Scintilla command identified by
4602 <code>sciCommand</code>. <code>sciCommand</code> can be any <code>SCI_*</code> command that has
4603 no arguments.</p>
4608 to it.</p>
4611 This command removes all keyboard command mapping by setting an empty mapping table.</p>
4615 action. SCI_NULL ensures that keys do not propagate to the parent window as that may
4616 cause focus to move. If you want the standard platform behaviour use the constant 0 instead.</p>
4621 Clicking the wrong button on the mouse pops up a short default editing menu. This may be
4624 Scintilla window will have the opportunity to handle the message.</p>
4628 <p>Start and stop macro recording mode. In macro recording mode, actions are reported to the
4631 record these actions for future replay.</p>
4635 These two messages turn macro recording on and off.</p>
4640 which can include a printer display surface. Printed output shows text styling as on the
4641 screen, but it hides all margins except a line number margin. All special marker effects are
4642 removed and the selection and caret are hidden.</p>
4644 <p>Different platforms use different display surface ID types to print on. On Windows, these are
4649 *pfr)</a><br />
4651 magnification)</a><br />
4657 </code>
4660 This call renders a range of text into a device context. If you use
4661 this for printing, you will probably want to arrange a page header and footer; Scintilla does
4663 example. Each use of this message renders a range of text into a rectangular area and returns
4664 the position in the document of the next character to print.</p>
4667 (for example, if you use this with MFC you will need to paginate in
4669 <pre>
4670 struct Sci_Rectangle { int left; int top; int right; int bottom; };
4672 struct Sci_RangeToFormat {
4673 Sci_SurfaceID hdc; // The Surface ID we print to
4674 Sci_SurfaceID hdcTarget; // The Surface ID we use for measuring (may be same as hdc)
4675 Sci_Rectangle rc; // Rectangle in which to print
4676 Sci_Rectangle rcPage; // Physically printable page size
4677 Sci_CharacterRange chrg; // Range of characters to print
4678 };
4679 </pre>
4681 <p>On Windows, <code>hdc</code> and <code>hdcTarget</code> should both be set to the device context handle
4682 of the output device (usually a printer). If you print to a metafile these will not be the same
4683 as Windows metafiles (unlike extended metafiles) do not implement the full API for returning
4688 rectangle defined by rcPage).<br />
4690 position of characters to output. All of each line within this character range is drawn.</p>
4692 <p>On Cocoa, the surface IDs for printing (<code>bDraw=1</code>) should be the graphics port of the current context
4693 (<code>(CGContextRef) [[NSGraphicsContext currentContext] graphicsPort]</code>) when the view's drawRect method is called.
4695 to a bitmap context (created with <code>CGBitmapContextCreate</code>) to avoid runtime warnings.</p>
4697 <p>On GTK+, the surface IDs to use can be found from the printing context with
4701 position of characters to output. All of each line within this character range is drawn.</p>
4703 <p>When printing, the most tedious part is always working out what the margins should be to
4704 allow for the non-printable area of the paper and printing a header and footer. If you look at
4705 the printing code in SciTE, you will find that most of it is taken up with this. The loop that
4706 causes Scintilla to render text is quite simple if you strip out all the margin, non-printable
4707 area, header and footer code.</p>
4718 These two messages set and get the method used to render coloured text on a printer that is
4719 probably using white paper. It is especially important to consider the treatment of colour if
4720 you use a dark or black screen background. Printing white on black uses up toner and ink very
4721 many times faster than the other way around. You can set the mode to one of:</p>
4724 <tbody>
4725 <tr>
4731 </tr>
4732 </tbody>
4735 <tr>
4741 </tr>
4743 <tr>
4748 <td>If you use a dark screen background this saves ink by inverting the light value of
4749 all colours and printing on a white background.</td>
4750 </tr>
4752 <tr>
4758 </tr>
4760 <tr>
4766 </tr>
4768 <tr>
4773 <td>Everything prints in its own colour on a white background except that line numbers
4774 use their own background colour.</td>
4775 </tr>
4776 </tbody>
4777 </table>
4786 generates one line of output and the line is truncated if it is too long to fit
4787 into the print area.<br />
4789 white space or style changes although if a word is longer than a line, it will be wrapped before
4792 between words.</p>
4798 <a class="message" href="#SCI_GETRANGEPOINTER">SCI_GETRANGEPOINTER(int position, int rangeLength)</a><br />
4800 </code>
4802 <p>On Windows, the message-passing scheme used to communicate between the container and
4803 Scintilla is mediated by the operating system <code>SendMessage</code> function and can lead to
4804 bad performance when calling intensively. To avoid this overhead, Scintilla provides messages
4805 that allow you to call the Scintilla message function directly. The code to do this in C/C++ is
4806 of the form:</p>
4807 <pre>
4808 #include "Scintilla.h"
4812 // now a wrapper to call Scintilla directly
4813 sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
4814 return pSciMsg(pSciWndData, iMessage, wParam, lParam);
4815 }
4816 </pre>
4820 the Scintilla window.</p>
4822 <p>While faster, this direct calling will cause problems if performed from a different thread
4823 to the native thread of the Scintilla window in which case <code>SendMessage(hSciWnd, SCI_*,
4832 pointer.</p>
4835 This message returns the address of the function to call to handle Scintilla messages without
4836 the overhead of passing through the Windows messaging system. You need only call this once,
4837 regardless of the number of Scintilla windows you create.</p>
4840 This returns a pointer to data that identifies which Scintilla window is in use. You must call
4841 this once for each Scintilla window you create. When you call the direct function, you must
4842 pass in the direct pointer associated with the target window.</p>
4847 Grant temporary direct read-only access to the memory used by Scintilla to store
4848 the document.</p>
4850 text of the document is stored consecutively
4851 and ensure there is a NUL character after the text, then returns a pointer to the first character.
4852 Applications may then pass this to a function that accepts a character pointer such as a regular
4853 expression search or a parser. The pointer should <em>not</em> be written to as that may desynchronize
4854 the internal state of Scintilla.</p>
4855 <p>Since any action in Scintilla may change its internal state
4856 this pointer becomes invalid after any call or by allowing user interface activity. The application
4857 should reacquire the pointer after making any call to Scintilla or performing any user-interface calls such
4858 as modifying a progress indicator.</p>
4859 <p>This call takes similar time to inserting a character at the end of the document and this may
4860 include moving the document contents. Specifically, all the characters after the document gap
4861 are moved to before the gap. This compacted state should persist over calls and user interface
4862 actions that do not change the document contents so reacquiring the pointer afterwards is very
4863 quick. If this call is used to implement a global replace operation, then each replacement will
4865 each replacement then the operation will become O(n^2) rather than O(n). Instead, all
4866 matches should be found and remembered, then all the replacements performed.</p>
4869 range requested. The gap is not moved unless it is within the requested range so this call
4871 This can be used by application code that is able to act on blocks of text or ranges of lines.</p>
4875 with a range that contains the gap and consequent costs of moving the gap.</p>
4879 <p>A Scintilla window and the document that it displays are separate entities. When you create
4880 a new window, you also create a new, empty document. Each document has a reference count that
4881 is initially set to 1. The document also has a list of the Scintilla windows that are linked to
4882 it so when any window changes the document, all other windows in which it appears are notified
4883 to cause them to update. The system is arranged in this way so that you can work with many
4884 documents in a single Scintilla window and so you can display a single document in multiple
4885 windows (for use with splitter windows).</p>
4887 <p>Although these messages use <code>document *pDoc</code>, to ensure compatibility with future
4889 is, you can use and store the pointer as described in this section but you should not
4890 dereference it.</p>
4893 *pDoc)</a><br />
4896 *pDoc)</a><br />
4898 *pDoc)</a><br />
4899 </code>
4902 This returns a pointer to the document currently in use by the window. It has no other
4903 effect.</p>
4906 This message does the following:<br />
4912 window.<br />
4916 This message creates a new, empty document and returns a pointer to it. This document is not
4917 selected into the editor and starts with a reference count of 1. This means that you have
4918 ownership of it and must either reduce its reference count by 1 after using
4921 application to avoid memory leaks.</p>
4924 This increases the reference count of a document by 1. If you want to replace the current
4925 document in the Scintilla window and take ownership of the current document, for example if you
4926 are editing many documents in one window, do the following:<br />
4936 must point at a document that still exists. If you call this on a document with a reference
4937 count of 1 that is still attached to a Scintilla window, bad things will happen. To keep the
4943 <p>To ensure a responsive user interface, applications may decide to load and save documents using a separate thread
4944 from the user interface.</p>
4948 <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
4949 into a Scintilla document on the user interface thread. That technique uses extra memory to store a complete copy of the
4950 file and also means that the time that Scintilla takes to perform initial line end discovery blocks the user interface.</p>
4952 <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>
4955 Create an object that supports the <code>ILoader</code> interface which can be used to load data and then
4956 be turned into a Scintilla document object for attachment to a view object.
4957 The <code>bytes</code> argument determines the initial memory allocation for the document as it is more efficient
4958 to allocate once rather than rely on the buffer growing as data is added.
4964 <span class="S5">class</span><span class="S0"> </span>ILoader<span class="S0"> </span><span class="S10">{</span><br />
4966 <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 />
4967 <span class="S0"> </span><span class="S2">// Returns a status code from SC_STATUS_*</span><br />
4968 <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 />
4969 <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 />
4971 </div>
4973 <p>The application should call the <code>AddData</code> method with each block of data read from the file.
4974 <code>AddData</code> will return SC_STATUS_OK unless a failure, such as memory exhaustion occurs.
4975 If a failure occurs in <code>AddData</code> or in a file reading call then loading can be abandoned and the loader released with
4977 When the whole file has been read, the <code>ConvertToDocument</code> method should be called to produce a Scintilla
4978 document pointer which can be used in the same way as a document pointer returned from
4984 <p>An application that wants to save in the background should lock the document with <code>SCI_SETREADONLY(1)</code>
4985 to prevent modifications and retrieve a pointer to the unified document contents with
4987 The buffer of a locked document will not move so the pointer is valid until the application calls <code>SCI_SETREADONLY(0)</code>.</p>
4989 <p>If the user tries to performs a modification while the document is locked then a <code><a class="message"
4990 href="#SCN_MODIFYATTEMPTRO">SCN_MODIFYATTEMPTRO</a></code> notification is sent to the application.
4991 The application may then decide to ignore the modification or to terminate the background saving thread and reenable
4992 modification before returning from the notification.</p>
4996 <p>The fundamental operation in folding is making lines invisible or visible. Line visibility
4997 is a property of the view rather than the document so each view may be displaying a different
4998 set of lines. From the point of view of the user, lines are hidden and displayed using fold
4999 points. Generally, the fold points of a document are based on the hierarchical structure of the
5000 document contents. In Python, the hierarchy is determined by indentation and in C++ by brace
5001 characters. This hierarchy can be represented within a Scintilla document object by attaching a
5002 numeric "fold level" to each line. The fold level is most easily set by a lexer, but you can
5003 also set it with messages.</p>
5005 <p>It is up to your code to set the connection between user actions and folding and unfolding.
5006 The best way to see how this is done is to search the SciTE source code for the messages used
5007 in this section of the documentation and see how they are used. You will also need to use
5008 markers and a folding margin to complete your folding implementation.
5012 docLine)</a><br />
5014 displayLine)</a><br />
5025 expanded)</a><br />
5027 <a class="message" href="#SCI_CONTRACTEDFOLDNEXT">SCI_CONTRACTEDFOLDNEXT(int lineStart)</a><br />
5031 line)</a><br />
5032 </code>
5035 When some lines are folded, then a particular line in the document may be displayed at a
5036 different position to its document position. If no lines are folded, this message returns
5037 <code>docLine</code>. Otherwise, this returns the display line (counting the very first visible
5038 line as 0). The display line of an invisible line is the same as the previous visible line. The
5039 display line number of the first line in the document is 0. If there is folding and
5041 Lines can occupy more than one display line if they wrap.</p>
5044 When some lines are hidden, then a particular line in the document may be displayed at a
5045 different position to its document position. This message returns the document line number that
5046 corresponds to a display line (counting the display line of the first line in the document as
5049 is the number of lines in the document.</p>
5055 The first two messages mark a range of lines as visible or invisible and then redraw the
5056 display.
5058 visible and 0 if it is not visible.
5060 if some lines are hidden.
5061 These messages have no effect on fold levels or fold
5062 flags. The first line can not be hidden.</p>
5066 These two messages set and get a 32-bit value that contains the fold level of a line and some
5067 flags associated with folding. The fold level is a number in the range 0 to
5070 two addition flag bits. <code>SC_FOLDLEVELWHITEFLAG</code> indicates that the line is blank and
5071 allows it to be treated slightly different then its level may indicate. For example, blank
5072 lines should generally not be fold points and will be considered part of the preceding section even though
5073 they may have a lesser fold level.
5075 the line is a header (fold point).</p>
5078 of a line. Likewise, use <code>SCI_GETFOLDLEVEL(line) & SC_FOLDLEVEL*FLAG</code> to get the
5079 state of the flags. To set the fold level you must or in the associated flags. For instance, to
5084 to handle user folding requests. If you do change the fold levels, the folding margin will
5085 update to match your changes.
5088 In addition to showing markers in the folding margin, you can indicate folds to the user by
5089 drawing lines in the text area. The lines are drawn in the foreground colour set for <a
5092 </p>
5095 <tbody>
5096 <tr>
5100 </tr>
5101 </tbody>
5104 <tr>
5108 </tr>
5110 <tr>
5115 </tr>
5117 <tr>
5122 </tr>
5124 <tr>
5129 </tr>
5131 <tr>
5136 </tr>
5138 <tr>
5143 folding. The appearance of this feature may change in the future.</td>
5144 </tr>
5145 </tbody>
5146 </table>
5156 state.</p>
5165 Each fold point may be either expanded, displaying all its child lines, or contracted, hiding
5166 all the child lines. This message toggles the folding state of the given line as long as it has
5168 all the lines that depend on the line. The display updates after this message.</p>
5172 These messages set and get the expanded state of a single line. The set message has no effect
5173 on the visible state of the line or any lines that depend on it. It does change the markers in
5174 the folding margin. If you ask for the expansion state of a line that is outside the document,
5177 <p>If you just want to toggle the fold state of one line and handle all the lines that are
5184 Search efficiently for lines that are contracted fold headers.
5185 This is useful when saving the user's folding when switching documents or saving folding with a file.
5186 The search starts at line number <code>lineStart</code> and continues forwards to the end of the file.
5187 <code>lineStart</code> is returned if it is a contracted fold header otherwise the next contracted
5192 A line may be hidden because more than one of its parent lines is contracted. Both these
5193 message travels up the fold hierarchy, expanding any contracted folds until they reach the top
5202 <a class="message" href="#SCI_SETWRAPVISUALFLAGS">SCI_SETWRAPVISUALFLAGS(int wrapVisualFlags)</a><br />
5204 <a class="message" href="#SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</a><br />
5205 <a class="message" href="#SCI_GETWRAPVISUALFLAGSLOCATION">SCI_GETWRAPVISUALFLAGSLOCATION</a><br />
5206 <a class="message" href="#SCI_SETWRAPINDENTMODE">SCI_SETWRAPINDENTMODE(int indentMode)</a><br />
5217 </code>
5219 <p>By default, Scintilla does not wrap lines of text. If you enable line wrapping, lines wider
5220 than the window width are continued on the following lines. Lines are broken after space or tab
5221 characters or between runs of different styles. If this is not possible because a word in one
5222 style is wider than the window then the break occurs after the last character that completely
5223 fits on the line. The horizontal scroll bar does not appear when wrap mode is on.</p>
5225 <p>For wrapped lines Scintilla can draw visual flags (little arrows) at end of a a subline of a
5226 wrapped line and at begin of the next subline. These can be enabled individually, but if Scintilla
5227 draws the visual flag at the beginning of the next subline this subline will be indented by one char.
5228 Independent from drawing a visual flag at the begin the subline can have an indention.</p>
5230 <p>Much of the time used by Scintilla is spent on laying out and drawing text. The same text
5231 layout calculations may be performed many times even when the data used in these calculations
5232 does not change. To avoid these unnecessary calculations in some circumstances, the line layout
5233 cache can store the results of the calculations. The cache is invalidated whenever the
5234 underlying data, such as the contents or styling of the document changes. Caching the layout of
5235 the whole document has the most effect, making dynamic line wrap as much as 20 times faster but
5237 line.</p>
5239 <p>Wrapping is not performed immediately there is a change but is delayed until the display
5240 is redrawn. This delay improves peformance by allowing a set of changes to be performed
5241 and then wrapped and displayed once. Because of this, some operations may not occur as
5242 expected. If a file is read and the scroll position moved to a particular line in the text,
5243 such as occurs when a container tries to restore a previous editing session, then
5244 the scroll position will have been determined before wrapping so an unexpected range
5245 of text will be displayed. To scroll to the position correctly, delay the scroll until the
5246 wrapping has been performed by waiting for an initial
5256 between words.</p>
5261 You can enable the drawing of visual flags to indicate a line is wrapped. Bits set in
5262 wrapVisualFlags determine which visual flags are drawn.
5263 </p>
5265 <tbody>
5266 <tr>
5270 </tr>
5271 </tbody>
5274 <tr>
5278 </tr>
5280 <tr>
5284 </tr>
5286 <tr>
5291 </td>
5292 </tr>
5294 <tr>
5298 </tr>
5299 </tbody>
5300 </table>
5302 <p><b id="SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</b><br />
5304 You can set whether the visual flags to indicate a line is wrapped are drawn near the border or near the text.
5305 Bits set in wrapVisualFlagsLocation set the location to near the text for the corresponding visual flag.
5306 </p>
5309 <tbody>
5310 <tr>
5314 </tr>
5315 </tbody>
5318 <tr>
5322 </tr>
5324 <tr>
5328 </tr>
5330 <tr>
5334 </tr>
5335 </tbody>
5336 </table>
5340 Wrapped sublines can be indented to the position of their first subline or one more indent level.
5342 The modes are:
5343 </p>
5346 <tbody>
5347 <tr>
5351 </tr>
5352 </tbody>
5355 <tr>
5358 <td>Wrapped sublines aligned to left of window plus amount set by
5360 </tr>
5362 <tr>
5366 </tr>
5368 <tr>
5371 <td>Wrapped sublines are aligned to first subline indent plus one more level of indentation</td>
5372 </tr>
5373 </tbody>
5374 </table>
5379 wrapped lines in terms of the average character width in
5381 There are no limits on indent sizes, but values less than 0 or large values may have
5382 undesirable effects.<br />
5383 The indention of sublines is independent of visual flags, but if
5385 </p>
5392 <tbody>
5393 <tr>
5399 </tr>
5400 </tbody>
5403 <tr>
5409 </tr>
5411 <tr>
5417 </tr>
5419 <tr>
5425 </tr>
5427 <tr>
5433 </tr>
5434 </tbody>
5435 </table>
5439 The position cache stores position information for short runs of text
5440 so that their layout can be determined more quickly if the run recurs.
5444 Split a range of lines indicated by the target into lines that are at most pixelWidth wide.
5445 Splitting occurs on word boundaries wherever possible in a similar manner to line wrapping.
5447 </p>
5450 Join a range of lines indicated by the target into one line by
5451 removing line end characters.
5452 Where this would lead to no space between words, an extra space is inserted.
5453 </p>
5456 Document lines can occupy more than one display line if they wrap and this
5457 returns the number of display lines needed to wrap a document line.</p>
5462 larger or smaller in steps of one point. The displayed point size never goes below 2, whatever
5468 </code>
5478 These messages let you set and get the zoom factor directly. There is no limit set on the
5479 factors you can set, so limiting yourself to -10 to +20 to match the incremental zoom functions
5480 is a good idea.</p>
5484 <p>You can choose to mark lines that exceed a given length by drawing a vertical line or by
5485 colouring the background of characters that exceed the set length.</p>
5492 </code>
5496 These two messages set and get the mode used to display long lines. You can set one of the
5497 values in the table:</p>
5500 <tbody>
5501 <tr>
5507 </tr>
5508 </tbody>
5511 <tr>
5517 </tr>
5519 <tr>
5525 This works well for monospaced fonts. The line is drawn at a position based on the width
5528 your styles use proportional fonts or if your style have varied font sizes or you use a
5529 mixture of bold, italic and normal text.</td>
5530 </tr>
5532 <tr>
5537 <td>The background colour of characters after the column limit is changed to the colour
5539 </tr>
5540 </tbody>
5541 </table>
5545 These messages set and get the column number at which to display the long line marker. When
5546 drawing lines, the column sets a position in units of the width of a space character in
5547 <code>STYLE_DEFAULT</code>. When setting the background colour, the column is a character count
5548 (allowing for tabs) into the line.</p>
5553 These messages set and get the colour of the marker used to show that a line has exceeded the
5559 called the SciLexer version of Scintilla), lexing support for a wide range of programming
5560 languages is included and the messages in this section are supported. If you want to set
5561 styling and fold points for an unsupported language you can either do this in the container or
5562 better still, write your own lexer following the pattern of one of the existing ones.</p>
5564 <p>Scintilla also supports external lexers. These are DLLs (on Windows) or .so modules (on GTK+/Linux) that export three
5569 <a class="message" href="#SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char
5570 *name)</a><br />
5572 *name)</a><br />
5573 <a class="message" href="#SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char
5574 *path)</a><br />
5576 <a class="message" href="#SCI_CHANGELEXERSTATE">SCI_CHANGELEXERSTATE(int start, int end)</a><br />
5577 <a class="message" href="#SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(<unused>, char *names)</a><br />
5579 <a class="message" href="#SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</a><br />
5580 <a class="message" href="#SCI_SETPROPERTY">SCI_SETPROPERTY(const char *key, const char *value)</a><br />
5581 <a class="message" href="#SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value)</a><br />
5582 <a class="message" href="#SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</a><br />
5583 <a class="message" href="#SCI_GETPROPERTYINT">SCI_GETPROPERTYINT(const char *key, int default)</a><br />
5584 <a class="message" href="#SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</a><br />
5586 *keyWordList)</a><br />
5588 <br />
5589 </code>
5595 <code>SCLEX_NULL</code> to select no lexing action and <code>SCLEX_CONTAINER</code> which sends
5596 the <code><a class="message" href="#SCN_STYLENEEDED">SCN_STYLENEEDED</a></code> notification to
5597 the container whenever a range of text needs to be styled. You cannot use the
5599 assigns unused lexer numbers to.</p>
5601 <p><b id="SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char *name)</b><br />
5603 <code>SCI_SETLEXERLANGUAGE</code> lets you select a lexer by name, and is the only method if you are using an
5604 external lexer or if you have written a lexer module for a language of your own and do not wish
5607 or "Python". To locate the name for the built-in lexers, open the relevant
5613 see if the lexer number changed.</p>
5617 <p><b id="SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char *path)</b><br />
5618 Load a lexer implemented in a shared library. This is a .so file on GTK+/Linux or a .DLL file on Windows.
5619 </p>
5622 This requests the current lexer or the container (if the lexer is set to
5627 message causes a redraw.</p>
5630 Indicate that the internal state of a lexer has changed over a range and therefore
5631 there may be a need to redraw.</p>
5635 <b id="SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</b><br />
5636 Information may be retrieved about the properties that can be set for the current lexer.
5637 This information is only available for newer lexers.
5638 <code>SCI_PROPERTYNAMES</code> returns a string with all of the valid properties separated by "\n".
5639 If the lexer does not support this call then an empty string is returned.
5640 Properties may be boolean (<code>SC_TYPE_BOOLEAN</code>), integer (<code>SC_TYPE_INTEGER</code>),
5645 You can communicate settings to lexers with keyword:value string pairs. There is no limit to
5648 there is already a value string associated with the keyword, it is replaced. If you pass a zero
5651 significant.</p>
5655 <code>"$(fold)0"</code>, but when this is accessed, the <code>$(fold)</code> is replaced by the
5658 <p>Currently the "fold" property is defined for most of the lexers to set the fold structure if
5660 setting that determines how to indicate bad indentation. Most keywords have values that are
5662 properties are used.</p>
5664 <p>There is a convention for naming properties used by lexers so that the set of properties can be found by scripts.
5665 Property names should start with "lexer.<lexer>." or "fold.<lexer>." when they apply to one
5668 <p>Applications may discover the set of properties used by searching the source code of lexers for lines that contain
5669 <code>GetProperty</code> and a double quoted string and extract the value of the double quoted string as the property name.
5671 Documentation for the property may be located above the call as a multi-line comment starting with
5675 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
5676 buffer and return the length (not including the terminating 0). If not found, copy an empty string
5682 <p>If the value argument is 0 then the length that should be allocated to store the value is returned;
5685 <p><b id="SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</b><br />
5686 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
5687 buffer and return the length (not including the terminating 0). If not found, copy an empty string
5693 <p>If the value argument is 0 then the length that should be allocated to store the value (including any indicated keyword replacement)
5697 Lookup a keyword:value pair using the specified key; if found, interpret the value as an integer and return it.
5698 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
5706 at revision 1.50. <code>keyWordSet</code> can be 0 to 8 (actually 0 to <code>KEYWORDSET_MAX</code>)
5709 It is expected that the keywords will be composed of standard ASCII printing characters,
5711 (except common sense).</p>
5713 <p>How these keywords are used is entirely up to the lexer. Some languages, such as HTML may
5714 contain embedded languages, VBScript and JavaScript are common for HTML. For HTML, key word set
5716 is for SGML and DTD keywords. Review the lexer code to see examples of keyword list. A fully
5718 list of strings that describe the uses of the keyword lists.</p>
5721 indentation and set 2 for keywords that cause unindentation. Yet again, you might have a simple
5722 lexer that colours keywords and you could change languages by changing the keywords in set 0.
5723 There is nothing to stop you building your own keyword lists into the lexer, but this means
5724 that the lexer must be rebuilt if more keywords are added.</p>
5726 <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</b><br />
5727 A description of all of the keyword sets separated by "\n" is returned by <code>SCI_DESCRIBEKEYWORDSETS</code>.</p>
5730 Retrieve the number of bits the current lexer needs for styling. This should normally be the argument
5732 </p>
5736 <p>Lexers are programmed as objects that implement the ILexer interface and that interact
5737 with the document they are lexing through the IDocument interface.
5738 Previously lexers were defined by providing lexing and folding functions but creating an object
5739 to handle the interaction of a lexer with a document allows the lexer to store state information that
5740 can be used during lexing. For example a C++ lexer may store a set of preprocessor definitions
5741 or variable declarations and style these depending on their role.</p>
5743 <p>A set of helper classes allows older lexers defined by functions to be used in Scintilla.</p>
5747 <span class="S5">class</span><span class="S0"> </span>ILexer<span class="S0"> </span><span class="S10">{</span><br />
5757 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5758 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5763 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5765 <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 />
5767 <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 />
5774 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>val<span class="S10">)</span>
5777 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5778 <span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>
5779 <span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DescribeWordListSets<span class="S10">()</span>
5787 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>wl<span class="S10">)</span>
5805 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>startPos<span class="S10">,</span>
5820 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5822 </div>
5824 <p>
5825 The return values from PropertySet and WordListSet are used to indicate whether the change requires
5826 performing lexing or folding over any of the document. It is the position at which to restart lexing and folding or -1
5827 if the change does not require any extra work on the document.
5828 A simple approach is to return 0 if there is any possibility that a change requires lexing the document again while an
5829 optimisation could be to remember where a setting first affects the document and return that position.
5830 </p>
5835 application and a lexer. An example would be where an application
5836 maintains a single large data structure containing symbolic information
5837 about system headers (like Windows.h) and provides this to the lexer
5838 where it can be applied to each document. This avoids the costs of
5839 constructing the system header information for each document. This is
5843 Previously, lexers were called with a range that started one line before the range that
5844 needs to be folded as this allowed fixing up the last line from the previous folding.
5845 The new approach allows the lexer to decide whether to backtrack or to handle this
5846 more efficiently.</p>
5888 <span class="S0"> </span>LineFromPosition<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>position<span class="S10">)</span>
5889 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
5891 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5893 <span class="S0"> </span>LineStart<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
5894 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
5896 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5898 <span class="S0"> </span>GetLevel<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
5900 <span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span>
5902 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
5920 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>state<span class="S10">)</span>
5927 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>mask<span class="S10">)</span>
5930 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
5934 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>style<span class="S10">)</span>
5935 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span>
5945 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span>
5947 <span class="S0"> </span>DecorationSetCurrentIndicator<span class="S10">(</span><span class="S5">int</span>
5953 <span class="S0"> </span>DecorationFillRange<span class="S10">(</span><span class="S5">int</span>
5955 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>value<span class="S10">,</span>
5956 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>fillLength<span class="S10">)</span>
5964 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>end<span class="S10">)</span>
5973 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
5977 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
5980 </div>
5982 <p>Scintilla tries to minimize the consequences of modifying text to
5983 only relex and redraw the line of the change where possible. Lexer
5984 objects contain their own private extra state which can affect later
5985 lines. For example, if the C++ lexer is greying out inactive code
5989 the document that it should relex and display more.</p>
5992 exceptions. Exceptions should not be thrown over build boundaries as the
5993 two sides may be built with different compilers or incompatible
5994 exception options.</p>
5999 implemented and thus which methods may be called.</p>
6003 <p>Notifications are sent (fired) from the Scintilla control to its container when an event has
6004 occurred that may interest the container. Notifications are sent using the
6008 struct NotifyHeader { // This matches the Win32 NMHDR structure
6009 void *hwndFrom; // environment specific window handle/pointer
6010 uptr_t idFrom; // CtrlID of the window issuing the notification
6011 unsigned int code; // The SCN_* notification code
6012 };
6014 struct SCNotification {
6015 struct Sci_NotifyHeader nmhdr;
6016 int position;
6017 /* SCN_STYLENEEDED, SCN_DOUBLECLICK, SCN_MODIFIED, SCN_MARGINCLICK, */
6018 /* SCN_NEEDSHOWN, SCN_DWELLSTART, SCN_DWELLEND, SCN_CALLTIPCLICK, */
6019 /* SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, SCN_HOTSPOTRELEASECLICK, */
6020 /* SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6021 /* SCN_USERLISTSELECTION, SCN_AUTOCSELECTION */
6023 int ch; /* SCN_CHARADDED, SCN_KEY */
6024 int modifiers;
6025 /* SCN_KEY, SCN_DOUBLECLICK, SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, */
6026 /* SCN_HOTSPOTRELEASECLICK, SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6028 int modificationType; /* SCN_MODIFIED */
6029 const char *text;
6030 /* SCN_MODIFIED, SCN_USERLISTSELECTION, SCN_AUTOCSELECTION, SCN_URIDROPPED */
6032 int length; /* SCN_MODIFIED */
6033 int linesAdded; /* SCN_MODIFIED */
6034 int message; /* SCN_MACRORECORD */
6035 uptr_t wParam; /* SCN_MACRORECORD */
6036 sptr_t lParam; /* SCN_MACRORECORD */
6037 int line; /* SCN_MODIFIED */
6038 int foldLevelNow; /* SCN_MODIFIED */
6039 int foldLevelPrev; /* SCN_MODIFIED */
6040 int margin; /* SCN_MARGINCLICK */
6041 int listType; /* SCN_USERLISTSELECTION */
6042 int x; /* SCN_DWELLSTART, SCN_DWELLEND */
6043 int y; /* SCN_DWELLSTART, SCN_DWELLEND */
6044 int token; /* SCN_MODIFIED with SC_MOD_CONTAINER */
6045 int annotationLinesAdded; /* SCN_MODIFIED with SC_MOD_CHANGEANNOTATION */
6046 int updated; /* SCN_UPDATEUI */
6047 };
6048 </pre>
6050 <p>The notification messages that your container can choose to handle and the messages
6051 associated with them are:</p>
6079 </code>
6082 <code><a class="message" href="#SCI_SETMODEVENTMASK">SCI_SETMODEVENTMASK(int eventMask)</a><br />
6084 <a class="message" href="#SCI_SETMOUSEDWELLTIME">SCI_SETMOUSEDWELLTIME(int milliseconds)</a><br />
6088 </code>
6090 <p>The following additional notifications are sent using the <code>WM_COMMAND</code> message on
6091 Windows and the "Command" signal on GTK+. This emulates the Windows Edit control. Only the lower
6096 </code>
6100 These two messages set and get the identifier of the Scintilla instance which is included in notifications as the
6102 When an application creates multiple Scintilla widgets, this allows the source of each notification to be found.
6105 The value should be small, preferrably less than 16 bits,
6107 </p>
6112 lexer, you will receive this notification when Scintilla is about to display or print text that
6113 requires styling. You are required to style the text from the line that contains the position
6114 returned by <a class="message" href="#SCI_GETENDSTYLED"><code>SCI_GETENDSTYLED</code></a> up to
6115 the position passed in <code>SCNotification.position</code>. Symbolically, you need code of the
6116 form:</p>
6117 <pre>
6123 MyStyleRoutine(startPos, SCNotification.position);
6124 </pre>
6127 This is sent when the user types an ordinary text character (as opposed to a command
6128 character) that is entered into the text. The container can use this to decide to display a <a
6131 This notification is sent before the character has been styled so processing that depends on
6132 styling should instead be performed in the SCN_UPDATEUI notification.</p>
6136 Sent to the container when the save point is entered or left, allowing the container to
6142 When in read-only mode, this notification is sent to the container if the user tries to change
6143 the text. This can be used to check the document out of a version control system. You can set
6148 Reports all keys pressed but not consumed by Scintilla. Used on GTK+ because of
6149 some problems with keyboard focus and is not sent by the Windows version. <code>SCNotification.ch</code> holds the key code and
6155 The mouse button was double clicked in editor. The <code>position</code> field is set to the text position of the
6161 Either the text or styling of the document has changed or the selection range or scroll position has changed.
6162 Now would be a good time to update any container UI elements that depend on document or view state.
6163 The <code>updated</code> field is set to the bit set of things changed since the previous notification.</p>
6165 <tbody>
6166 <tr>
6173 </tr>
6174 </tbody>
6177 <tr>
6184 </tr>
6186 <tr>
6193 </tr>
6195 <tr>
6202 </tr>
6204 <tr>
6211 </tr>
6212 </tbody>
6213 </table>
6216 This notification is sent when the text or styling of the document changes or is about to
6217 change. You can set a mask for the notifications that are sent to the container with <a
6219 notification structure contains information about what changed, how the change occurred and
6220 whether this changed the number of lines in the document. No modifications may be performed
6222 are:</p>
6225 <tbody>
6226 <tr>
6230 </tr>
6231 </tbody>
6234 <tr>
6238 table.</td>
6239 </tr>
6241 <tr>
6245 </tr>
6247 <tr>
6252 </tr>
6254 <tr>
6259 </tr>
6261 <tr>
6265 information this holds a pointer to the text that is handed to the Undo system, otherwise
6266 it is zero. For user performed SC_MOD_BEFOREDELETE the text field is 0 and
6267 for user performed SC_MOD_BEFOREINSERT the text field points to an array of cells,
6268 not bytes and the length is the number of cells.</td>
6269 </tr>
6271 <tr>
6276 </tr>
6278 <tr>
6282 unused.</td>
6283 </tr>
6285 <tr>
6289 unused.</td>
6290 </tr>
6291 </tbody>
6292 </table>
6297 Undo or Redo of a previous action.</p>
6300 <tbody>
6301 <tr>
6309 </tr>
6310 </tbody>
6313 <tr>
6321 </tr>
6323 <tr>
6331 </tr>
6333 <tr>
6341 </tr>
6343 <tr>
6351 </tr>
6353 <tr>
6361 </tr>
6363 <tr>
6371 </tr>
6373 <tr>
6381 </tr>
6383 <tr>
6391 </tr>
6393 <tr>
6401 </tr>
6403 <tr>
6411 </tr>
6413 <tr>
6421 </tr>
6423 <tr>
6431 </tr>
6433 <tr>
6441 </tr>
6443 <tr>
6448 <td>A line state has changed because <a class="message" href="#SCI_SETLINESTATE">SCI_SETLINESTATE</a>
6449 was called.</td>
6452 </tr>
6454 <tr>
6462 </tr>
6464 <tr>
6472 </tr>
6474 <tr>
6482 </tr>
6484 <tr>
6492 </tr>
6494 <tr>
6499 <td>This is set on a SC_PERFORMED_USER action when it is the
6500 first or only step in an undo transaction. This can be used to integrate the Scintilla
6501 undo stack with an undo stack in the container application by adding a Scintilla
6502 action to the container's stack for the currently opened container transaction or
6503 to open a new container transaction if there is no open container transaction.
6504 </td>
6507 </tr>
6509 <tr>
6514 <td>This is set on for actions that the container stored into the undo stack with
6516 </td>
6519 </tr>
6521 <tr>
6530 </tr>
6531 </tbody>
6532 </table>
6537 "Command" signal on GTK+ as this is the behavior of the standard Edit control
6546 These messages set and get an event mask that determines which document change events are
6550 only notifications about changes to text and not styling changes by calling
6556 <code>SC_MOD_CHANGEFOLD</code>, <code>SC_PERFORMED_USER</code>, <code>SC_PERFORMED_UNDO</code>,
6567 behavior of the standard Edit control. Unfortunately, these codes do not match the Windows Edit
6569 now too late to change the Scintilla codes as clients depend on the current values.</p>
6574 disable macro recording. When enabled, each time a recordable change occurs, the
6579 notification are:</p>
6582 <tbody>
6583 <tr>
6587 </tr>
6588 </tbody>
6591 <tr>
6595 </tr>
6597 <tr>
6601 </tr>
6603 <tr>
6607 </tr>
6608 </tbody>
6609 </table>
6616 used:</p>
6619 <tbody>
6620 <tr>
6624 </tr>
6625 </tbody>
6628 <tr>
6633 at the time of the margin click.</td>
6634 </tr>
6636 <tr>
6640 to the margin click.</td>
6641 </tr>
6643 <tr>
6647 </tr>
6648 </tbody>
6649 </table>
6652 Scintilla has determined that a range of lines that is currently invisible should be made
6653 visible. An example of where this may be needed is if the end of line of a contracted fold
6654 point is deleted. This message is sent to the container in case it wants to make the line
6655 visible in some unusual way such as making the whole document visible. Most containers will
6659 that should be made visible. The container code will be similar to the following code
6660 skeleton:</p>
6661 <pre>
6662 firstLine = SCI_LINEFROMPOSITION(scn.position)
6663 lastLine = SCI_LINEFROMPOSITION(scn.position+scn.length-1)
6664 for line = lineStart to lineEnd do SCI_ENSUREVISIBLE(line) next
6665 </pre>
6668 Painting has just been done. Useful when you want to update some other widgets based on a
6669 change in Scintilla, but want to have the paint occur first to appear more responsive. There is
6677 <tbody>
6678 <tr>
6682 </tr>
6683 </tbody>
6686 <tr>
6691 initiated the list.</td>
6692 </tr>
6694 <tr>
6698 </tr>
6700 <tr>
6704 </tr>
6705 </tbody>
6706 </table>
6707 <br />
6711 Only on the GTK+ version. Indicates that the user has dragged a URI such as a file name or Web
6712 address onto Scintilla. The container could interpret this as a request to open the file. The
6721 key press indicates the dwell is over. Both notifications set the same fields in
6725 <tbody>
6726 <tr>
6730 </tr>
6731 </tbody>
6734 <tr>
6738 mouse pointer was lingering.</td>
6739 </tr>
6741 <tr>
6747 </tr>
6748 </tbody>
6749 </table>
6750 <br />
6754 These two messages set and get the time the mouse must sit still, in milliseconds, to generate
6759 This notification is generated when the user zooms the display using the keyboard or the
6761 notification can be used to recalculate positions, such as the width of the line number margin
6762 to maintain sizes in terms of characters rather than pixels. <code>SCNotification</code> has no
6763 additional information.</p>
6765 <p>
6769 These notifications are generated when the user clicks or double clicks on
6770 text that is in a style with the hotspot attribute set.
6771 This notification can be used to link to variable definitions or web pages.
6777 <p>
6780 These notifications are generated when the user clicks or releases the mouse on
6781 text that has an indicator.
6787 This notification is generated when the user clicks on a calltip.
6788 This notification can be used to display the next function prototype when a
6789 function name is overloaded with different arguments.
6794 The user has selected an item in an <a class="jump" href="#Autocompletion">autocompletion list</a>. The
6795 notification is sent before the selection is inserted. Automatic insertion can be cancelled by sending a
6800 <tbody>
6801 <tr>
6805 </tr>
6806 </tbody>
6809 <tr>
6813 </tr>
6814 <tr>
6818 </tr>
6819 </tbody>
6820 </table>
6824 There is no other information in SCNotification.</p>
6827 The user deleted a character while autocompletion list was active.
6828 There is no other information in SCNotification.</p>
6832 <p>Two formats are supported for images used in margin markers and autocompletion lists, RGBA and XPM.</p>
6837 value for each pixel. It is simpler than
6840 <p>The data is a sequence of 4 byte pixel values starting with the pixels for the top line, with the
6841 leftmost pixel first, then continuing with the pixels for subsequent lines. There is no gap between
6842 lines for alignment reasons.</p>
6844 <p>Each pixel consists of, in order, a red byte, a green byte, a blue byte and an alpha byte.
6845 The colour bytes are not premultiplied by the alpha value. That is, a fully red pixel that is
6848 <p>Since the RGBA pixel data does not include any size information the
6849 width and height must previously been set with the
6851 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.</p>
6853 <p>GUI platforms often include functions for reading image file formats like PNG into memory
6854 in the RGBA form or a similar form.
6855 If there is no suitable platform support, the <a href="http://lodev.org/lodepng/">LodePNG and picoPNG</a> libraries are small libraries
6856 for loading and decoding PNG files available under a BSD-style license.</p>
6858 <p>RGBA format is supported on Windows, GTK+ and OS X Cocoa.
6859 It is not supported on OS X Carbon.</p>
6863 <p>The XPM format is
6865 Scintilla is only able to handle XPM pixmaps that use one character per pixel with no named colours.
6867 <p>There are two forms of data structure used for XPM images, the first "lines form" format is well suited
6868 to embedding an image inside C source code and the "text form" is suited to reading from a file.
6869 In the lines form, an array of strings is used with the first string indicating the dimensions and number of colours
6870 used. This is followed by a string for each colour and that section is followed by the image with one string per line.
6871 The text form contains the same data as one null terminated block formatted as C source code starting
6873 <p>Either format may be used with Scintilla APIs with the bytes at the location pointed to examined
6874 to determine which format: if the bytes start with "/* XPM */" then it is treated as text form,
6875 otherwise it is treated as lines form.</p>
6880 <p>On GTK+, the following functions create a Scintilla widget, communicate with it and allow
6881 resources to be released after all Scintilla widgets have been destroyed.</p>
6883 <a class="message" href="#scintilla_set_id">void scintilla_set_id(ScintillaObject *sci, uptr_t id)</a><br />
6884 <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 />
6885 <a class="message" href="#scintilla_release_resources">void scintilla_release_resources()</a><br />
6886 </code>
6889 Create a new Scintilla widget. The returned pointer can be added to a container and displayed in the same way as other
6890 widgets.</p>
6893 Set the control ID which will be used in the idFrom field of the NotifyHeader structure of all
6894 notifications for this instance.
6897 <p><b id="scintilla_send_message">sptr_t scintilla_send_message(ScintillaObject *sci,unsigned int iMessage, uptr_t wParam, sptr_t lParam)</b><br />
6898 The main entry point allows sending any of the messages described in this document.</p>
6901 Call this to free any remaining resources after all the Scintilla widgets have been destroyed.</p>
6905 <p>The following messages are currently supported to emulate existing Windows controls, but
6906 they will be removed in future versions of Scintilla. If you use these messages you should
6907 replace them with the Scintilla equivalent.</p>
6908 <pre>
6909 WM_GETTEXT(int length, char *text)
6911 EM_GETLINE(int line, char *text)
6913 EM_SETREADONLY
6915 WM_CUT
6916 WM_COPY
6917 WM_PASTE
6918 WM_CLEAR
6919 WM_UNDO
6920 EM_CANUNDO
6921 EM_EMPTYUNDOBUFFER
6922 WM_GETTEXTLENGTH
6923 EM_GETFIRSTVISIBLELINE
6924 EM_GETLINECOUNT
6925 EM_GETMODIFY
6926 EM_SETMODIFY(bool isModified)
6927 EM_GETRECT(RECT *rect)
6928 EM_GETSEL(int *start, int *end)
6930 EM_SETSEL(int start, int end)
6933 EM_LINEFROMCHAR(int position)
6934 EM_EXLINEFROMCHAR(int position)
6935 EM_LINEINDEX(int line)
6936 EM_LINELENGTH(int position)
6937 EM_SCROLL(int line)
6938 EM_LINESCROLL(int column, int line)
6939 EM_SCROLLCARET()
6940 EM_CANPASTE
6942 EM_POSFROMCHAR(int position, POINT *location)
6943 EM_SELECTIONTYPE
6944 EM_HIDESELECTION(bool hide)
6945 EM_FINDTEXT(int flags, FINDTEXTEX *ft)
6946 EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
6947 EM_GETMARGINS
6948 EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
6949 EM_FORMATRANGE
6950 </pre>
6952 <p>The following are features that are only included if you define
6954 compatibility you should change them as indicated.</p>
6957 This was used to set a DBCS (Double Byte Character Set) mode on GTK+.
6958 An explicit DBCS code page should be used when calling <a class="message" href="#SCI_SETCODEPAGE">SCI_SETCODEPAGE</a></p>
6962 Scintilla no longer supports palette mode. The last version to support palettes was 2.29.
6963 Any calls to these methods should be removed.</p>
6966 <pre>
6967 EM_GETWORDBREAKPROC EM_GETWORDBREAKPROCEX
6968 EM_SETWORDBREAKPROC EM_SETWORDBREAKPROCEX
6969 EM_GETWORDWRAPMODE EM_SETWORDWRAPMODE
6970 EM_LIMITTEXT EM_EXLIMITTEXT
6971 EM_SETRECT EM_SETRECTNP
6972 EM_FMTLINES
6973 EM_GETHANDLE EM_SETHANDLE
6974 EM_GETPASSWORDCHAR EM_SETPASSWORDCHAR
6975 EM_SETTABSTOPS
6976 EM_FINDWORDBREAK
6977 EM_GETCHARFORMAT EM_SETCHARFORMAT
6978 EM_GETOLEINTERFACE EM_SETOLEINTERFACE
6979 EM_SETOLECALLBACK
6980 EM_GETPARAFORMAT EM_SETPARAFORMAT
6981 EM_PASTESPECIAL
6982 EM_REQUESTRESIZE
6983 EM_GETBKGNDCOLOR EM_SETBKGNDCOLOR
6984 EM_STREAMIN EM_STREAMOUT
6985 EM_GETIMECOLOR EM_SETIMECOLOR
6986 EM_GETIMEOPTIONS EM_SETIMEOPTIONS
6987 EM_GETOPTIONS EM_SETOPTIONS
6988 EM_GETPUNCTUATION EM_SETPUNCTUATION
6989 EM_GETTHUMB
6990 EM_GETEVENTMASK
6991 EM_SETEVENTMASK
6992 EM_DISPLAYBAND
6993 EM_SETTARGETDEVICE
6994 </pre>
6996 <p>Scintilla tries to be a superset of the standard windows Edit and RichEdit controls wherever
6997 that makes sense. As it is not intended for use in a word processor, some edit messages can not
6998 be sensibly handled. Unsupported messages have no effect.</p>
7002 <p>To build Scintilla or SciTE, see the README file present in both the Scintilla and SciTE
7003 directories. For Windows, GCC 3.2, Borland C++ or Microsoft Visual Studio .NET can be used
7004 for building. There is a make file for building Scintilla but not SciTE with Visual C++ 6 at
7006 supported. The version of GTK+ installed should be detected automatically.
7008 on the command line.</p>
7012 <p>On Windows, Scintilla is normally used as a dynamic library as a .DLL file. If you want to
7013 link Scintilla directly into your application .EXE or .DLL file, then the
7015 <code>Scintilla_RegisterClasses</code> called. <code>STATIC_BUILD</code> prevents compiling the
7016 <code>DllMain</code> function which will conflict with any <code>DllMain</code> defined in your
7022 <p>Depending on the compiler and linker used, the lexers may be stripped out. This is most
7023 often caused when building a static library. To ensure the lexers are linked in, the
7028 <p>To change the set of lexers in Scintilla, add and remove lexer source files
7033 following the patterns of other lexers. The important thing is to include
7039 <p id="AlternativeRegEx">A simple interface provides support for switching the Regular Expressions engine at
7043 to create an instance of your class. You must disable the built-in implementation by defining
7046 </body>
7047 </html>