IupScintilla (since 3.8)

Creates a multiline source code text editor that uses the Scintilla library.

Scintilla is a free library that provides text-editing functions, with an emphasis on advanced features for source code editing. It comes with complete source code and a license that permits use in any free project or commercial product, and it is available on http://www.scintilla.org/.

IupScintilla library includes the Scintilla code, so no external references are needed.

For compilers that don't have C++ 11 support (g++ < 4.8 and Visual C++ < 14) we use Scintilla version 3.6.6, for compilers that have we use Scintilla version 3.11.2. We are still not using Scintilla 4.x because it uses C++14 features, and requires Microsoft Visual C++ 2017 and g++ 7.

The global attribute SCINTILLA_VERSION contains the Scintilla version in use. (since 3.29)

Supported in Windows and in the systems the GTK driver is supported.

Initialization and Usage

The IupScintillaOpen function must be called after a IupOpen, so that the control can be used. The "iup_scintilla.h" file must also be included in the source code. The program must be linked to the controls library (iup_scintilla). When statically linking there are additional libraries: "imm32.lib" and "msimg32" in Windows; and "atk-1.0" in Linux.

To make the control available in Lua use require"iuplua_scintilla" or manually call the initialization function in C, iupscintillalua_open, after calling iuplua_open.  When manually calling the function the iuplua_scintilla.h file must also be included in the source code and the program must be linked to the Lua control library (iuplua_scintilla).

Creation

Ihandle* IupScintilla(void); [in C]
iup.scintilla{} -> (ih: ihandle) [in Lua]
scintilla() [in LED]

This function returns the identifier of the created editing component, or NULL if an error occurs.

Auxiliary Functions

sptr_t IupScintillaSendMessage(Ihandle* ih, unsigned int iMessage, uptr_t wParam, sptr_t lParam); [in C]
Not available in Lua.

Sends a message to the Scintilla control in any platform. (since 3.11)

IupText auxiliary functions IupTextConvertLinColToPos and IupTextConvertPosToLinCol can also be used. But here lin and col starts at 0, pos starts at 0.

Attributes

General

BORDER (creation only): Shows a border around the text. Default: "YES".

CANFOCUS (creation only) (non inheritable): enables the focus traversal of the control. In Windows the control will still get the focus when clicked. Default: YES.

PROPAGATEFOCUS(non inheritable): enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO. (since 3.23)

CLIPBOARD (non inheritable): clear, cut, copy or paste the selection to or from the clipboard. Values: "CLEAR", "CUT", "COPY", "PASTE". Returns Yes or No, if data can be pasted from the clipboard.

CURSOR (non inheritable): defines the cursor type. Can be: "NORMAL" or "WAIT" (displays a wait cursor when the mouse is over or owned by the control).

DROPFILESTARGET [Windows and GTK Only] (non inheritable): Enable or disable the drop of files. Default: NO, but if DROPFILES_CB is defined when the element is mapped then it will be automatically enabled.

KEYSUNICODE [Windows Only] (non inheritable): allow processing of Unicode typed characters. Default: NO. (since 3.9)

OVERWRITE (non inheritable): turns the overwrite mode ON or OFF. When enabled, each typed character replaces the character to the right of the text caret. When disabled, characters are inserted at the caret.

MOUSEDWELLTIME (non inheritable): time the mouse must sit still, in milliseconds, to generate a DWELL_CB callback. If set to NULL, the default, no dwell events are generated. (since 3.23)

READONLY (non inheritable): Allows the user only to read the contents, without changing it. Restricts the insertion using keyboard input and attributes. Navigation keys are still available. Possible values: "YES" and "NO". Default: NO.

SAVEPOINT (non inheritable, write-only): sets the current state of the document to saved (given value is ignored). The SAVEPOINT_CB callback is called with status=0 if the document is modified, and called with status=1 if the save point is reached with Undo/Redo. After setting the SAVEPOINT, when editing is done the SAVEPOINT_CB callback is called with status=0. When undo is performed back to the point were the saved state was set the callback is called again with status=1. (since 3.23)

MODIFIED (non inheritable, read-only): returns if the text has been modified since the last SAVEPOINT. Can return Yes or No. (since 3.23)

SIZE (non inheritable): Since the contents can be changed by the user, the Natural Size is not affected by the text contents. Use VISIBLECOLUMNS and VISIBLELINES to control the Natural Size.

USEPOPUP (non inheritable): allows to disable the default editing menu shown when the user clicks with the right button. Default: Yes.

VISIBLECOLUMNS: Defines the number of visible columns for the Natural Size, this means that will act also as minimum number of visible columns. It uses a wider character size then the one used for the SIZE attribute so strings will fit better without the need of extra columns. As for SIZE you can set to NULL after map to use it as an initial value. Default: 50.

VISIBLELINES: Defines the number of visible lines for the Natural Size, this means that will act also as minimum number of visible lines. As for SIZE you can set to NULL after map to use it as an initial value. Default: 10.

VISIBLELINESCOUNT (non inheritable, read-only): returns the number of actual visible lines.

WORDWRAP (non inheritable): If enabled will force a word wrap of lines that are greater than the with of the control, and the horizontal scrollbar will be removed. Can be "WORD", "CHAR" or "NONE". Default: NONE.

WORDWRAPVISUALFLAGS (non inheritable): enable the drawing of visual flags to indicate a line is wrapped. Can be: MARGIN (at the line number margin), START (start of wrapped line), END (end of wrapped line) or NONE. Default: NONE.

Text Retrieval and Modification

ADD (non inheritable, write-only): Inserts a text at the current position. If VALUELEN is defined, the it is used instead of strlen. (since 3.27)

APPEND (non inheritable, write-only): Inserts a text at the end of the text. If APPENDNEWLINE=YES, an end of line character will be automatically inserted before the appended text (APPENDNEWLINE default is YES). If VALUELEN is defined, the it is used instead of strlen (since 3.27).

CHARid (non inheritable, read-only): returns the character at a given position, considering the "id" as the position.

CLEARALL (non inheritable, write-only): deletes all the text (unless the document is read-only).

COUNT (non inheritable, read-only): returns the number of characters in the text.

DELETERANGE (non inheritable, write-only): Deletes a range of text in the document. It uses a string format "pos,len" in order to indicate the start position and text length to delete.

INSERTid (non inheritable, write-only): Inserts a text string at position "id" or at the current position if pos is -1 or omitted. If the current position is after the insertion point then it is moved along with its surrounding text but no scrolling is performed. Notice that the selected text is not used to position the inserted text.

LINEid (non inheritable, read-only): returns the text of the line, considering the "id" as the line number. It includes the end of line character if the line has one. Number lines starts at 0.

LINECOUNT (non inheritable, read-only): returns the number of lines in the text.

LINEVALUE (non inheritable, read-only): returns the text of the line where the caret is. It does not include the end of line character.

PREPEND (non inheritable, write-only): Inserts a text at the begin of the text. If APPENDNEWLINE=YES, an end of line character will be automatically inserted after the prepended text if the text is not empty (APPENDNEWLINE default is YES).

VALUE (non inheritable): Text entered by the user. The end of line character indicates a new line. After the element is mapped and if there is no text will return the empty string "". This replaces all the text in the document with the zero terminated text string you pass in.

Annotation 

ANNOTATIONTEXTid  (non inheritable): defines and returns an annotation displayed underneath a specific line, considering the "id" as the line number. An annotation may consist of multiple lines separated by '\n'.

ANNOTATIONSTYLEid  (non inheritable): sets and gets a particular style to the annotation, considering the "id" as the line number.

ANNOTATIONSTYLEOFFSET (non inheritable): sets and gets a style offset, in order to separate standard text styles from annotation styles.

ANNOTATIONVISIBLE (non inheritable): enable or disable annotations. Can be "HIDDEN" (not displayed), "STANDARD" (displayed) or "BOXED" (displayed and surrounded by a box). Default HIDDEN.

ANNOTATIONCLEARALL (non inheritable, write-only): deletes all annotations.

Auto-Completion (since 3.10)

AUTOCSHOWid (non inheritable, write only): causes a list of words to be displayed. The words are separated by a space. "id" defines the number of characters of the word already entered by user.

AUTOCCANCEL (non inheritable, write only): cancels any displayed auto-completion list. When in auto-completion mode, the list should disappear when the user types a character that can not be part of the auto-completion.

AUTOCACTIVE (non inheritable, read only): returns YES if there is an active auto-completion list and NO if there is not.

AUTOCPOSSTART (non inheritable, read only): returns the current position when the list of words started to be shown.

AUTOCCOMPLETE (non inheritable, write only): triggers auto-completion. This has the same effect as the tab key.

AUTOCSELECT (non inheritable, write only): selects an item in the auto-completion list. It searches in the list of words for the first that matches of value (comparisons are case sensitive). If the item is not found, no item is selected.

AUTOCSELECTEDINDEX (non inheritable, read only): retrieves the current selection index, set by AUTOCSELECT attribute.

AUTOCDROPRESTOFWORD (non inheritable): when an item is selected, any word characters following the caret are first erased if this attribute is set YES. The default is NO.

AUTOCMAXHEIGHT (non inheritable): sets and gets the maximum number of rows that will be visible in an auto-completion list. If there are more rows in the list, then a vertical scrollbar is shown. The default is 5.

AUTOCMAXWIDTH (non inheritable): the maximum width of an auto-completion list expressed as the number of characters in the longest item that will be totally visible. The default is 0 (in this case, the list width is calculated to fit the item with the most characters).

Brace Highlighting

BRACEHIGHLIGHT (non inheritable, write only): highlights the brace, defined by its initial and final positions (format: "pos1:pos2"). Up to two characters can be highlighted in a 'brace highlighting style', which is defined as style number (See Style Definition, id = 34).

BRACEBADLIGHT (non inheritable, write only): highlights the non matching brace, based on a position. If there is no matching brace then the brace badlighting style (See Style Definition, id = 35) can be used to show the brace that is unmatched. Set -1 as position removes the highlight.

BRACEMATCHid (non inheritable, read only): finds a corresponding matching brace given id, the position of one brace. The brace characters handled are '(', ')', '[', ']', '{', '}', '<', and '>'. If the character at position is not a brace character, or a matching brace cannot be found, the return value is -1.

Caret and Selection

CARET (non inheritable): Position of the insertion point. The first position, lin or col, is "0". It uses a string format "lin,col" in order to indicate the caret position, where lin and col must be integer numbers.

When lin is greater than the number of lines, the caret is placed at the last line. When col is greater than the number of characters in the given line, the caret is placed after the last character of the line.

If the caret is not visible the text is scrolled to make it visible.

CARETPOS (non inheritable): Position of the insertion point using a zero based character unique index "pos". Useful for indexing the VALUE string. This removes any selection, sets the caret at pos and scrolls the view to make the caret visible, if necessary.

CARETTOVIEW (non inheritable, write only): Moves the caret to the nearest visible line. Any selection is lost.

CARETCOLOR (non inheritable): color of the caret. Values in RGB format ("r g b"). (since 3.17)

CARETSTYLE (non inheritable): style of the caret. Can be LINE, BLOCK or INVISIBLE. Default: LINE. (since 3.17)

CARETWIDTH (non inheritable): with of the caret line. Can be 0, 1, 2 or 3 pixels. Default: 1. Works only when CARETSTYLE=LINE. A size of 0 will make the caret invisible also. (since 3.17)

CARETLINEVISIBLE (non inheritable): Enable or disable caret line background color. Can be Yes or No. Default: No. (since 3.21)

CARETLINEBACKCOLOR (non inheritable): Color of caret line background. Values in RGB format ("r g b"). (since 3.21)

CARETLINEBACKALPHA (non inheritable): Set translucency used for line containing the caret. Translucency ranges from 0 for completely transparent to 255 for opaque with 256 being opaque and not using translucent drawing code which may be slower. (since 3.21)

CARETXPOLICY/CARETYPOLICY (non inheritable): These set the caret policy. The value can be a combination of "SLOP", "STRICT", "JUMPS" and "EVEN" using "|" as separator. When SLOP is used the attribute CARETSLOP defines an unwanted zone for the caret. This zone is defined as a number of pixels near the vertical margins, and as a number of lines near the horizontal margins. (since 3.26)

FIRSTVISIBLELINE (non inheritable): the line number of the first visible line. (since 3.18)

SELECTEDTEXT (non inheritable): Selection text. Returns NULL if there is no selection. When changed replaces the current selection. Similar to INSERT, but does nothing if there is no selection.

SELECTION (non inheritable): Selection interval. Returns NULL if there is no selection. The first position, lin or col, is "0". The accepted format is represented by the string "lin1,col1:lin2,col2", where lin1, col1, lin2 and col2 are integer numbers corresponding to the selection's interval. col2 correspond to the character after the last selected character. The values ALL and NONE are also accepted.

SELECTIONFGCOLOR (non inheritable): foreground color of the selection. Values in RGB format ("r g b"). Default is system dependent. (since 3.23)

SELECTIONBGCOLOR (non inheritable): background color of the selection. Values in RGB format ("r g b"). Default is system dependent. (since 3.23)

SELECTIONALPHA (non inheritable): The selection can be drawn translucently in the selection background color by setting an alpha value. Translucency ranges from 0 for completely transparent to 255 for opaque with 256 being opaque and not using translucent drawing. (since 3.23)

SELECTIONPOS (non inheritable): Same as SELECTION but using a zero based character index "pos1:pos2". Useful for indexing the VALUE string. The values ALL and NONE are also accepted.

WORDPOSid (non inheritable, read-only): returns the start and end of a word in the text around the given position (in id). It uses the format "start:end". Returns NULL if no words were found. (since 3.23)

WORDRANGE (non inheritable): interval for ISWORD. (since 3.23)

ISWORD (non inheritable, read-only): check if the interval defined by WORDRANGE is a word. (since 3.23)

Folding

FOLDFLAGS (non inheritable, write-only): determines how folding lines are drawn. Can be: "LINEBEFORE_EXPANDED", "LINEBEFORE_CONTRACTED", "LINEAFTER_EXPANDED" or "LINEAFTER_CONTRACTED " (default).

FOLDLINEid (non inheritable, write-only): operates over a single line. Can be CONTRACT, EXPAND, or TOGGLE. (since 3.23)

FOLDCHILDRENid (non inheritable, write-only): operates over a single line and all its children. Can be CONTRACT, EXPAND, or TOGGLE. (since 3.23)

FOLDALL (non inheritable, write-only): operates over all levels. Can be CONTRACT, EXPAND, or TOGGLE. (since 3.23)

FOLDEXPANDEDid (non inheritable): the expanded state of a single line. It has no effect on the visible state of the line or any lines that depend on it. It does change the markers in the folding margin. If you just want to toggle the fold state of one line and handle all the lines that are dependent on it, it is much easier to use TOGGLEFOLD. It can be used to process many folds without updating the display until you had finished, but you have to manually hide or show lines, and force a COLORISE. (since 3.23)

FOLDLEVELid (non inheritable): the fold level number of a line (given in id). If you use a Lexer, it is not recommend to set the fold level (this is far better handled by the Lexer). By contrast, the fold level is useful to decide how to handle user folding requests. Fold level starts at 0.

FOLDLEVELWHITEid (non inheritable): the fold level white flag state of a line (indicates that the line is blank). Can be: "Yes" or "No". (since 3.23)

FOLDLEVELHEADERid (non inheritable): the fold level header flag state of a line (indicates that the line is a header/fold point). Can be: "Yes" or "No". (since 3.23)

FOLDPARENTid (non inheritable, read-only): returns the line number of the first line before the given line (in id) that is marked as a fold point with FOLDLEVELHEADER=Yes and has a fold level less than the given line. If no line is found, or if the header flags and fold levels are inconsistent, the return value is -1. (since 3.23)

FOLDTOGGLE (non inheritable, write-only): Determines if the fold point (line number) may be either expanded, displaying all its child lines, or contracted, hiding all the child lines.

ENSUREVISIBLEid (non inheritable, write-only): ensure that the given line (in id) is visible by expanding folded parents. Value is can be NULL or "ENFORCEPOLICY" to apply vertical caret policy. (since 3.23)

SHOWLINES (non inheritable, write-only): make the given lines interval visible. Value is in the format "start:end", start default is 0, end default is -1 (last line). (since 3.23)

HIDELINES (non inheritable, write-only): make the given lines interval hidden. Value is in the format "start:end", start default is 0, end default is -1 (last line). (since 3.23) 

Indicators

Indicators are used to display additional information over the top of styling. 

INDICATORCURRENT (non inheritable): sets the indicator number that will affect INDICATORCLEARRANGE and INDICATORFILLRANGE. (since 3.23)

INDICATORVALUE (non inheritable): sets the indicator value that will affect INDICATORFILLRANGE. (since 3.23)

INDICATORCLEARRANGE (non inheritable, write-only): clears the current indicator in the range given in the format "start:length" ("%d:%d" in C). (since 3.23)

INDICATORFILLRANGE (non inheritable, write-only): fills the current indicator with the current value in the range given in the format "start:length" ("%d:%d" in C). (since 3.23)

INDICATORSTYLEid (non inheritable): the style used to draw the given indicator (in id). Can be: PLAIN, SQUIGGLE, TT, DIAGONAL, STRIKE, HIDDEN, BOX, ROUNDBOX, STRAIGHTBOX, FULLBOX, DASH, DOTS, SQUIGGLELOW, DOTBOX, SQUIGGLEPIXMAP, COMPOSITIONTHICK, COMPOSITIONTHIN, TEXTFORE. Default for indicator 0 is SQUIGGLE, default for indicator 1 is TT, default for indicator 2 is PLAIN. (since 3.23)

INDICATORFGCOLORid (non inheritable): the color used to draw the given indicator (in id). Value in RGB format ("r g b"). Default for indicator 0 is "0 127 0", default for indicator 1 is "255 0 0", default for indicator 2 is "0 0 255". (since 3.23)

INDICATOROUTLINEALPHAid (non inheritable): sets and retrieves the alpha transparency used to draw the outline color of the given indicator (in id). The alpha value can range from 0 (completely transparent) to 255 (no transparency). (since 3.23)

INDICATORALPHAid (non inheritable): sets and retrieves the alpha transparency used to draw the fill color of the given indicator (in id). The alpha value can range from 0 (completely transparent) to 255 (no transparency). (since 3.23)

Lexer

COLORISE (non inheritable, write-only): requests the lexer to style the document in an character interval given in value (format "start:end", start default is 0, end default is -1 (last pos)). (since 3.23)

KEYWORDid (non inheritable, write-only): keyword list used by the current Lexer. Until 9 lists of keywords can set up using id from 0 to 8. The value is a list of keywords separated by spaces, tabs, "\n" or "\r" or any combination of these.

KEYWORDSETS (non inheritable, read only): returns a description of all of the keyword sets separated by "\n".

LEXERLANGUAGE (non inheritable): associate the Lexer language name. It is case sensitive. Default: not defined. Set to NULL to clear the association. Can be: any name supported by Scintilla. For instance: asm, bash, freebasic, cmake, COBOL, cpp (C++), css, d, diff, eiffel, fortran, hypertext (HTML), xml, lisp, lua (Lua), makefile, matlab, mysql, nsis, pascal, perl, python, ruby, smalltalk, sql, tcl, tex, vb (Visual Basic), and many others.

LOADLEXERLIBRARY (non inheritable, write-only): Load a Lexer implemented in a dynamic library given the library file name. This is a .so file on GTK+/Linux or a .DLL file on Windows. (since 3.11)

PROPERTY (non inheritable): sets and gets Lexer properties using "name=value" string pairs, where name is case sensitive and value is the associated string. There is no limit to the number of keyword pairs you can set, other than available memory. To retrieve a property first set the PROPERTYNAME attribute, the PROPERTY attribute will return its value.

PROPERTYNAMES (non inheritable, read only): returns a list of property names separated by "\n". If the Lexer does not support this information then an empty string is returned. 

Line Endings

EOL (non inheritable): Returns the current end of line character(s). Can be "\r", "\r\n" or "\n". (since 3.24)

EOLMODE (non inheritable): End of line mode. Can be CR ("\r"), CRLF ("\r\n") or LF ("\n"). Default: LF. (since 3.24)

EOLVISIBLE (non inheritable): End of line visibility. Default: No. (since 3.22)

FIXEOL (non inheritable, write only): Fix the line ends to use only the given mde. Can be CR ("\r"), CRLF ("\r\n") or LF ("\n"). (since 3.22, options other than LF since 3.24)

Margins

The margins id are numbered 0 to 4. By default, Scintilla margin 0 is set to display line numbers, margin 1 is set to display non-folding symbols, and margin 2 is set to display folding symbols. However, you can set the margins to be whatever you wish using MARGINTYPEid. All margins are hidden by default, i.e. margin with is set to 0.

MARGINMASKFOLDERSid (non inheritable): defines if a margin is folding or non-folding. Can be: Yes or No.

MARGINSENSITIVEid (non inheritable): determines if a margin is sensitive or not. Margins that are not sensitive act as selection margins which make it easy to select ranges of lines. By default, all margins are insensitive. Can be: YES or NO.

MARGINTYPEid (non inheritable): set and get the type of a margin. Each margin can be set to display only symbols, line numbers, or text. You can use the predefined values "SYMBOL", "NUMBER", "TEXT", "RTEXT" (right justify text), "BACKGROUND" or "FOREGROUND" (the latter two used for symbol margins that set their background or foreground using the style default colors).

MARGINWIDTHid (non inheritable): width of a margin in pixels (Default value: 0). A margin with width=0 is invisible.

MARGINMASKid (non inheritable): defines which markers can be used for symbols in the given margin (id). The value is a 32 bit number with the selected markers. A single margin can display several types of markers. See Markers. (since 3.22)

MARGINLEFT (non inheritable): size of the blank margin on the left side. Default: 1.

MARGINRIGHT (non inheritable): size of the blank margin on the right side. Default: 1.

MARGINTEXTid (non inheritable): controls the text of each line of a text margin. id is the line number.

MARGINTEXTSTYLEid (non inheritable): controls the style of the text of each line of a text margin. id is the line number.

MARGINTEXTCLEARALL (non inheritable, write-only): clear all text and styles of a text margin.

MARGINCURSORid (non inheritable): set and get the arrow cursor normally shown over margins. Can be: "REVERSEARROW" (default) or "ARROW".

FOLDMARGINCOLOR (non inheritable, write-only): changes the color of the fold margin. Values in RGB format ("r g b"). If set to NULL reset to internal default values. (since 3.22)

FOLDMARGINHICOLOR (non inheritable, write-only): changes the color of the fold margin highlight. Values in RGB format ("r g b"). If set to NULL reset to internal default values. (since 3.22)

Markers

Markers are numbers from 0 to 31. They can be combined in a 32 bit mask with one or more markers.

MARKERSYMBOLid (non inheritable): associates a marker number in the range 0 to 31 (id) with one of the marker symbols or an ASCII character.

Marker symbols: 0="CIRCLE", 1="ROUNDRECT", 2="ARROW", 3="SMALLRECT", 4="SHORTARROW", 5="EMPTY", 6="ARROWDOWN", 7="MINUS", 8="PLUS", 9="VLINE", 10="LCORNER", 11="TCORNER", 12="BOXPLUS", 13="BOXPLUSCONNECTED", 14="BOXMINUS", 15="BOXMINUSCONNECTED", 16="LCORNERCURVE", 17="TCORNERCURVE", 18="CIRCLEPLUS", 19="CIRCLEPLUSCONNECTED", 20="CIRCLEMINUS", 21="CIRCLEMINUSCONNECTED", 22="BACKGROUND" (line background color), 23="DOTDOTDOT", 24="ARROWS", 25=(unused), 26="FULLRECT" (margin background color), 27="LEFTRECT",  28=(unused), 29="UNDERLINE" (underline across the line), 30="RGBAIMAGE", 31="BOOKMARK"  and "CHARACTER+c" (where c is an ASCii character code). The numbers are used only in marker masks.

MARKERDEFINE (non inheritable, write-only): Defines a marker using its number and its symbol in the format: "number=symbol".

Marker numbers: can be a number in the range 0 to 31, or the pre-defined names: "FOLDEREND", "FOLDEROPENMID", "FOLDERMIDTAIL", "FOLDERSUB", "FOLDER" and "FOLDEROPEN".
Marker symbols: the same values used in MARKERSYMBOL.

MARKERFGCOLORid (non inheritable, write only): defines the foreground color of a marker number (id). Values in RGB format ("r g b").

MARKERBGCOLORid (non inheritable, write only): defines the background color of a marker number (id). Values in RGB format ("r g b").

MARKERBGCOLORSELid (non inheritable, write only): defines the highlight background color of a marker number (id) when its folding block is selected. Values in RGB format ("r g b").

MARKERALPHAid (non inheritable, write only): defines the alpha value of a marker number (id). Markers may be drawn translucently when there are no margins.

MARKERRGBAIMAGEid (non inheritable, write only): defines the image name to be used on a marker number. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. It must be an image created with the IupImageRGBA constructor, it can not be a image loaded from stock or resources.

MARKERRGBAIMAGESCALE (non inheritable, write only): defines the image scale factor, in percent (1-100).

MARKERHIGHLIGHT (non inheritable): enable or disable the the highlight folding block when it is selected. (i.e. block that contains the caret). Can be Yes or No. Default: No.

MARKERADDid (non inheritable, write-only): adds marker number to a line (id). Internally, sets the marker handle number (LASTMARKERADDHANDLE attribute) that identifies the added marker (or -1 for invalid line and out of memory), which may be useful to find where a marker is after moving or combining lines.

MARKERGETid (non inheritable, read-only): returns a marker mask with the markers that are present on the line (id).

MARKERDELETEid (non inheritable, write-only): deletes marker number given a line number (id). If marker number is -1, all markers are deleted from the line.

MARKERDELETEALL (non inheritable, write-only): removes the marker from all lines given its number (0-31). If marker number is -1, it deletes all markers from all lines.

MARKERNEXTid (non inheritable, write-only): searches for a given marker mask, starting at line number (id) and continuing forwards to the end of the file. Internally, sets the the line number of the first line that contains the markers in the mask (LASTMARKERFOUND attribute) or -1, if no marker is found.

MARKERPREVIOUSid (non inheritable, write-only): searches for a given marker mask, starting at line number (id) and continuing backwards to the start of the file. Internally, sets the the line number of the first line that contains the markers (LASTMARKERFOUND attribute) or -1, if no marker is found.

MARKERLINEFROMHANDLEid (non inheritable, read-only): searches for a marker given its handle (id) created in MARKERADDid (use the LASTMARKERADDHANDLE attribute to obtain its value) and returns the line number of the first line that contains the marker or -1, if no marker is found.

MARKERDELETEHANDLE (non inheritable, write-only): searches for a marker given its handle and deletes the marker if it is found.

LASTMARKERADDHANDLE (non inheritable, read-only): returns the last marker handle created by the MARKERADDid attribute.

LASTMARKERFOUND (non inheritable, read-only): returns the last line number that contains a marker found by the MARKERNEXTid, MARKERPREVIOUSid or MARKERLINEFROMHANDLE attributes.

Printing (since 2.23)

PRINT: Prints the text. Use the following attributes to configure the printed document. Value is the job title. By default will print all text.

PRINTDIALOG: shows the system dialog before printing. Can be YES or NO. Default: YES. If there is a selection the user can print only the selected text.

PRINTMARGINLEFT: left margin.

PRINTMARGINTOP: top margin.

PRINTMARGINRIGHT: right margin.

PRINTMARGINBOTTOM: bottom margin.

PRINTMARGINUNITS: units used in print margin attributes. Can be: INCH, CM or PIXELS. Default: INCH.

PRINTWORDWRAP: controls how long lines that don't fit in the page are processed. Can be: NONE (lines are truncated) or WORD (lines are break between words). Default: WORD. Notice that CHAR wrap mode is not supported when printing.

PRINTCOLOR: controls how colors are printed. Can be: NORMAL (print using the current screen colors), INVERTLIGHT (inverts the light value of all colors and printing on a white background), BLACKONWHITE (print all text as black on a white background), COLORONWHITE (prints all text in its own color on a white background), and COLORONWHITEDEFAULTBG (everything prints in its own color on a white background except that line numbers use their own background color). Default: NORMAL.

PRINTMAGNIFICATION: lets you to print at a different size than the screen font. It is the number of points to add to the size of each screen font. A value of -3 or -4 gives reasonably small print.

Scrolling

SCROLLBAR (creation only): Associates an automatic horizontal and/or vertical scrollbar. Can be: "VERTICAL", "HORIZONTAL", "YES" (both) or "NO" (none). Default: "YES". For all systems, when SCROLLBAR is NO, the natural size will always include its size even if the native system hides the scrollbar.

SCROLLBY (non inheritable, write only): Scroll the text by the given offsets in the format "lin,col". Positive lin values increase the line number at the top of the screen (i.e. they move the text upwards). Positive col values increase the column at the left edge of the view (i.e. they move the text leftwards). (since 3.17)

SCROLLTOCARET (non inheritable, write only): Scroll the text to make the caret position visible.

SCROLLWIDTH (non inheritable): controls the document width in pixels. Default: 2000.

SCROLLWIDTHTRACKING (non inheritable): scroll width is adjusted to ensure that all of the lines currently displayed can be completely scrolled. This mode never adjusts the scroll width to be narrower. (since 3.30)

Search and Replace (since 3.10)

SEARCHINTARGET (non inheritable, write only): This searches for the first occurrence of a text string in the target defined by TARGETSTART and TARGETEND. If the search succeeds, the target is set to the found text.

SEARCHFLAGS (non inheritable): sets and gets the search flags used in SEARCHINTARGET attribute. Possible values: MATCHCASE, WHOLEWORD, WORDSTART, REGEXP and POSIX. The flag options are combined using "|" as separators. Use NULL to reset all flags.

TARGETSTART (non inheritable): sets and gets the start of target. When searching in non-regular expression mode, you can set TARGETSTART greater than TARGETEND to find the last matching text in the target rather than the first matching text. The first position of text is 0. If set to NULL, 0 will be used (since 3.23).

TARGETEND (non inheritable): sets and gets the end of target. If set to -1 or NULL, target end will be the last position of text (since 3.23).

TARGETFROMSELECTION (non inheritable, write only): set the target start and end from current position of the selection.

 TARGETWHOLEDOCUMENT (non inheritable, write only): Set the target start to the start of the document and target end to the end of the document. (since 3.23)

REPLACETARGET (non inheritable, write only): replaces the target text. After replacement, the target range refers to the replacement text.

Style Definition (See Style Definition)

BGCOLOR: Background color of the text. Default: the global attribute TXTBGCOLOR. If changed it will affect the background color of all styles (since 3.23).

FGCOLOR: Text color. Default: the global attribute TXTFGCOLOR. If changed it will affect the foreground color of all styles (since 3.23).

FONT: the text font. Default: the global attribute DEFAULTFONT. If changed it will affect all the font attributes of all styles (since 3.23).

STYLEBGCOLORid (non inheritable): background color for a style (See Style Definition). Values in RGB format ("r g b").

STYLEBOLDid (non inheritable): the boldness of a font (See Style Definition).

STYLECASEid (non inheritable): determines how text is displayed (See Style Definition). Values: LOWERCASE, UPPERCASE or MIXED (default).

STYLECHARSETid (non inheritable): sets and gets a style to use a different character set than the default (See Style Definition). Can be ANSI (default), EASTEUROPE, RUSSIAN, GB2312, HANGUL or SHIFTJIS.

STYLECLEARALL (non inheritable): sets all styles to have the same attributes as default global style (id = 32) (See Style Definition).

STYLEEOLFILLEDid (non inheritable): If the last character in the line has a style with this attribute set, the remainder of the line up to the right edge of the window is filled with the background color set for the last character (See Style Definition). Can be YES (italic) or NO.

STYLEFGCOLORid (non inheritable): foreground color for a style (See Style Definition). Values in RGB format ("r g b").

STYLEFONTid (non inheritable): sets and gets the font name (See Style Definition). Scintilla caches fonts by their names, but the cache is case sensitive.

STYLEFONTSIZEid (non inheritable): sets and gets the font size (See Style Definition), using a integer number of points.

STYLEFONTSIZEFRACid (non inheritable): sets and gets the font size (See Style Definition), using a fractional point size in hundredths of a point. For example, a text size of 9.4 points is set with value = 940.

STYLEHOTSPOTid (non inheritable): used to mark ranges of text that can detect mouse clicks (See Style Definition). The cursor changes to a hand over hotspots, and the foreground, and background colors may change and an underline appear to indicate that these areas are sensitive to clicking. This may be used to allow hyperlinks to other documents.

STYLEITALICid (non inheritable): the italic style of a font (See Style Definition). Can be YES (italic) or NO.

STYLERESET (non inheritable, write-only): Resets to the initial Scintilla style default (See Style Definition).

STYLEUNDERLINEid (non inheritable): determines if the underline is drawn, using a foreground color (See Style Definition). Can be YES (underline) or NO.

STYLEVISIBLEid (non inheritable): determines if the text is visible (YES) or hidden (NO) (See Style Definition).

STYLEWEIGHTid (non inheritable): the weight of a font (See Style Definition). Predefined values: NORMAL, SEMIBOLD and BOLD. The weight can also be a number between 1 and 999 with 1 being very light and 999 very heavy.

Styling

CLEARDOCUMENTSTYLE (non inheritable, write-only): clear all styling information and reset the folding state.

STARTSTYLING (non inheritable, write only): prepares for styling by setting the styling position.

STYLINGid (non inheritable, write only): sets the style of given length characters starting at the styling position and then increases the styling position by length. id is the style.

Tabs and Indentation Guides

TABSIZE (non inheritable): Controls the number of characters for a tab stop. Default: 8.

INDENTATIONGUIDES (non inheritable): dotted vertical lines that appear within indentation white space every indent size columns. Can be: NONE, REAL, LOOKFORWARD, LOOKBOTH. Default: NONE.

HIGHLIGHTGUIDE (non inheritable): Highlights the indentation guide of a given column. When brace highlighting occurs, the indentation guide corresponding to the braces may be highlighted with the brace highlighting style (See Style Definition, id = 34). Set column to 0 to cancel this highlight.

USETABS (non inheritable): Use tabs also for indentation or only spaces. Can be Yes or No. Default: Yes.

Undo and Redo

REDO (non inheritable): redo the last operation if set to Yes, redo all operations if set to ALL, clears the undo information otherwise. Returns Yes or No if redo can be performed.

UNDO (non inheritable): undo the last operation if set to Yes, undo all operations if set to ALL, clears the undo information otherwise. Returns Yes or No if undo can be performed.

UNDOCOLLECT (non inheritable): enable or disable the undo collect of information. Can be Yes or No. Default: Yes.

UNDOACTION (non inheritable, write only): allows to create a block of undo operations. Can be BEGIN (start a bock) or END (end a block). (since 3.21)

White Space

EXTRAASCENT (non inheritable): sets and gets the space to be added to the maximum ascent, in order to allow for more space between lines. Default: 0.

EXTRADESCENT (non inheritable): sets and gets the space to be added to the maximum descent, in order to allow for more space between lines. Default: 0.

WHITESPACEVIEW (non inheritable): sets and gets the white space display mode. The white spaces can be: "INVISIBLE" (shown as an empty background color), "VISIBLEALWAYS" (drawn as dots and arrows) or "VISIBLEAFTERINDENT" (white space used for indentation is displayed normally but after the first visible character, it is shown as dots and arrows). Default: INVISIBLE.

WHITESPACESIZE (non inheritable): sets and gets the size of the dots used for mark space characters. Default: 3.

WHITESPACEFGCOLOR (non inheritable, write only): defines the foreground color of visible white space. Values in RGB format ("r g b"). By default the color will be defined by the Lexer, but defining this attribute will overriding the Lexer definition. Set to NULL to reset the definition and use the Lexer again.

WHITESPACEBGCOLOR (non inheritable, write only): defines the background color of visible white space. Values in RGB format ("r g b"). By default the color will be defined by the Lexer, but defining this attribute will overriding the Lexer definition. Set to NULL to reset the definition and use the Lexer again. 

Zooming

ZOOMIN (non inheritable, write only): increases the zoom factor by one point if the current zoom factor is less than 20 points.

ZOOMOUT (non inheritable, write only): decreases the zoom factor by one point if the current zoom factor is greater than -10 points.

ZOOM (non inheritable): sets and gets the zoom factor directly. Limits: -10 points to zoom out and 20 points to zoom in. 

ACTIVE, EXPAND, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, RASTERSIZE, ZORDER, VISIBLE: also accepted.

Drag & Drop attributes are supported. See Notes bellow.

Callbacks

ACTION: Action generated when the text is edited, but before its value is actually changed. Can be generated when using the keyboard, undo/redo system or from the clipboard.

int function(Ihandle *ih, int insert, int pos, int length, char* text ); [in C]
ih:action(insert, pos, length: number, text: string) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
insert: =1 when text is inserted, =0 when text is deleted.
pos: 0 based character position when change started.
length: size of the change.
text: the inserted text value. It is NULL when insert=0.

AUTOCSELECTION_CB: Action generated when the user has selected an item in an auto-completion list. It is sent before the selection is inserted. Automatic insertion can be cancelled by setting the AUTOCCANCEL attribute before returning from the callback. (since 3.10.1)

int function(Ihandle *ih, int pos, char* text ); [in C]
ih:autocselection_cb(pos: number, text: string) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
pos: 0 based character start position of the word being completed.
text: the text of the selection.

AUTOCCANCELLED_CB: Called after the user has cancelled an auto-completion list. (since 3.10.1)

int function(Ihandle *ih); [in C]
ih:autoccancelled_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

AUTOCCHARDELETED_CB: Called after the user deleted a character while auto-completion list was active. (since 3.10.1)

int function(Ihandle *ih); [in C]
ih:autocchardeleted_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

BUTTON_CB: Action generated when any mouse button is pressed or released. Use IupConvertXYToPos to convert (x,y) coordinates in character positioning.

CARET_CB: Action generated when the caret/cursor position is changed.

int function(Ihandle *ih, int lin, int col, int pos); [in C]
ih:caret_cb(lin, col, pos: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
lin, col: line and column number (start at 0).
pos: 0 based character position.

INSERTCHECK_CB: Action generated before some text is inserted. Inside the callback the attribute CHANGEINSERT can be set to change the inserted text. (since 3.27)

int function(Ihandle *ih, int pos, int length, char* text ); [in C]
ih:insertcheck_cb(pos, length: number, text: string) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
pos: 0 based character position when change started.
length: size of the change.
text: the inserted text value. It is NULL when insert=0.

DROPFILES_CB: Action generated when one or more files are dropped in the element.

DWELL_CB: Action generated when the user keeps the mouse in one position for the dwell period defined in MOUSEDWELLTIME. (since 3.23)

int function(Ihandle *ih, int state, int pos, int x, int y); [in C]
ih:dwell_cb(state, pos, x, y: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
state: 1 if mouse sit still more than the dwell period, 0 if mouse moved or key pressed after state=1 was called.
pos: the nearest position in the document to the position where the mouse pointer was lingering. Can be -1 if not near any character.
x, y: Where the pointer lingered. 

HOTSPOTCLICK_CB: Action generated when the user clicks or double clicks on text that is in a style with the hotspot attribute set.

int function(Ihandle *ih, int pos, int lin, int col, char* status); [in C]
ih:hotspotclick_cb(pos, lin, col: number, status: string) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
pos: the character position in the document that corresponds to the hotspot click.
lin: line in the document that corresponds to the hotspot click.
col: column in the document that corresponds to the hotspot click.
status: status of mouse buttons and certain keyboard keys at the moment the event was generated. The same macros used for BUTTON_CB can be used for this status.

LINESCHANGED_CB: Called after the number of lines was interactively changed by the user. (since 3.23)

int function(Ihandle *ih, int lin, int num); [in C]
ih:lineschanged_cb(lin, num: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
lin: line where the change started
num: number of lines than changed. A negative value indicates that lines were removed.

MARGINCLICK_CB: Action generated when the mouse button is clicked inside a margin that is marked as sensitive.

int function(Ihandle *ih, int margin, int lin, char* status); [in C]
ih:marginclick_cb(margin, lin: number, status: string) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
margin: the margin number that was clicked.
lin: line in the document that corresponds to the margin click.
status: status of mouse buttons and certain keyboard keys at the moment the event was generated. The same macros used for BUTTON_CB can be used for this status.

MOTION_CB: Action generated when the mouse is moved. Use IupConvertXYToPos to convert (x,y) coordinates in character positioning.

SAVEPOINT_CB: Notifies the application that a save point was reached (1) or left (0). Can be used to control whether to display a saved or modified document. To set the save point use the SAVEPOINT attribute.

int function(Ihandle *ih, int status); [in C]
ih:savepoint_cb(status: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
status: can be 1 (reached) or 0 (left).

UPDATECONTENT_CB: Called when contents, styling or markers have been changed. (since 3.23)

int function(Ihandle *ih); [in C]
ih:updatecontent_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

UPDATESELECTION_CB: Called when selection has been changed . (since 3.23)

int function(Ihandle *ih); [in C]
ih:updateselection_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

UPDATEHSCROLL_CB: Called when the document was scrolled horizontally. (since 3.23)

int function(Ihandle *ih); [in C]
ih:updatehscroll_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

UPDATEVSCROLL_CB: Called when the document was scrolled vertically. (since 3.23)

int function(Ihandle *ih); [in C]
ih:updatevscroll_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

VALUECHANGED_CB: Called after the value was interactively changed by the user.

int function(Ihandle *ih); [in C]
ih:valuechanged_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

ZOOM_CB: Notifies the application when the user zooms the display using the keyboard or the ZOOM attribute. Can be used to recalculate positions, such as the width of the line number margin to maintain sizes in terms of characters rather than pixels.

int function(Ihandle *ih, int zoomInPoints); [in C]
ih:zoom_cb(zoomInPoints: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
zoomInPoints: the current zoom factor.

MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

Drag & Drop callbacks are supported (*). See Notes bellow.

Style Definition

Scintilla can automatically format the text using the Lexer or the application can manually format the text. In both cases only 256 different styles are available. Styles are numbered from 0 to 255, invalid IDs are simply ignored. When the id is not specified for an attributes the style 0 is assumed.

Each Lexer will use the available styles with its own rules, but several Lexers share many ids. Notice that language keywords and styles definitions are not pre-defined internally, the application must define them.

Here are some known styles for C++ and Lua:

Notes

Enter key will add a new line, and the Tab key will insert a Tab.

Internal Drag&Drop support is enabled by default, although the Drag & Drop attributes and callbacks are supported they may not work as expected.

IupScintilla uses attributes and callbacks very similar to the IupText control, except for text formatting. But notice that in IupScintilla position always starts at 0.

Although the IupScintilla documentation should be sufficient for most uses, some advanced features will be better understood if the Scintilla Documentation is consulted. Also some Scintilla features are not available in IupScintilla, so by consulting that documentation you will be able to check which one and if necessary you can request the implementation in IupScintilla.

Our version of Scintilla also supports a LED lexer. (since 3.28)

Navigation, Selection and Clipboard Keys

Here is a list of the common keys for all drivers. Other keys are available depending on the driver.

Examples

Browse for Example Files

 IupSetAttribute(ih, "LEXERLANGUAGE", "cpp");

IupSetAttribute(ih, "KEYWORDS0", "void struct union enum char short int long double float signed unsigned const static extern auto register volatile bool class private protected public friend inline template virtual asm explicit typename mutable"
                                  "if else switch case default break goto return for while do continue typedef sizeof NULL new delete throw try catch namespace operator this const_cast static_cast dynamic_cast reinterpret_cast true false using"
                                  "typeid and and_eq bitand bitor compl not not_eq or or_eq xor xor_eq");

//IupSetAttribute(ih, "STYLEFONT32", "Courier New");
IupSetAttribute(ih, "STYLEFONT32", "Consolas");
IupSetAttribute(ih, "STYLEFONTSIZE32", "11");
IupSetAttribute(ih, "STYLECLEARALL", "Yes");  /* sets all styles to have the same attributes as 32 */

IupSetAttribute(ih, "STYLEFGCOLOR1", "0 128 0");    // 1-C comment 
IupSetAttribute(ih, "STYLEFGCOLOR2", "0 128 0");    // 2-C++ comment line 
IupSetAttribute(ih, "STYLEFGCOLOR4", "128 0 0");    // 4-Number 
IupSetAttribute(ih, "STYLEFGCOLOR5", "0 0 255");    // 5-Keyword 
IupSetAttribute(ih, "STYLEFGCOLOR6", "160 20 20");  // 6-String 
IupSetAttribute(ih, "STYLEFGCOLOR7", "128 0 0");    // 7-Character 
IupSetAttribute(ih, "STYLEFGCOLOR9", "0 0 255");    // 9-Preprocessor block 
IupSetAttribute(ih, "STYLEFGCOLOR10", "255 0 255"); // 10-Operator 
IupSetAttribute(ih, "STYLEBOLD10", "YES");

IupSetAttribute(ih, "STYLEHOTSPOT6", "YES");
  
IupSetAttribute(ih, "MARGINWIDTH0", "50");

IupSetAttribute(ih, "PROPERTY", "fold=1");
IupSetAttribute(ih, "PROPERTY", "fold.compact=0");
IupSetAttribute(ih, "PROPERTY", "fold.comment=1");
IupSetAttribute(ih, "PROPERTY", "fold.preprocessor=1");

IupSetAttribute(ih, "MARGINWIDTH1", "20");
IupSetAttribute(ih, "MARGINTYPE1",  "SYMBOL");
IupSetAttribute(ih, "MARGINMASKFOLDERS1",  "Yes");

IupSetAttribute(ih, "MARKERDEFINE", "FOLDER=PLUS");
IupSetAttribute(ih, "MARKERDEFINE", "FOLDEROPEN=MINUS");
IupSetAttribute(ih, "MARKERDEFINE", "FOLDEREND=EMPTY");
IupSetAttribute(ih, "MARKERDEFINE", "FOLDERMIDTAIL=EMPTY");
IupSetAttribute(ih, "MARKERDEFINE", "FOLDEROPENMID=EMPTY");
IupSetAttribute(ih, "MARKERDEFINE", "FOLDERSUB=EMPTY");
IupSetAttribute(ih, "MARKERDEFINE", "FOLDERTAIL=EMPTY");

IupSetAttribute(ih, "FOLDFLAGS", "LINEAFTER_CONTRACTED");

IupSetAttribute(ih, "MARGINSENSITIVE1", "YES");

See Also

IupText, Scintilla