Copyright and License information Home

__ A B C D E F G H I L M P R S T U V W

### wxStyledTextCtrl - Styling & Style Definition

- GetEndStyled
- GetLineState
- GetMaxLineState
- SetLineState
- SetStyleBytes
- SetStyling
- StartStyling
- StyleClearAll
- StyleResetDefault
- StyleSetBackground
- StyleSetBold
- StyleSetCase
- StyleSetChangeable
- StyleSetCharacterSet
- StyleSetEOLFilled
- StyleSetFaceName
- StyleSetFont
- StyleSetFontAttr
- StyleSetForeground
- StyleSetItalic
- StyleSetSize
- StyleSetSpec
- StyleSetUnderline
- StyleSetVisible

Summary:

You may wish to style text programmatically or let a lexer do it for you. In either case you need to know about Styling and Style Definition. The discussion about cells talks about how there are two bytes for each character: one for the character and one for styling. The normal way to divide the style byte is to use 5 bits (b0..b4) for 32 possible styles (called styles 0 through 31) and three bits (5..7) to define indicators.

If you're using one of the standard lexers to style the Document, then you should probably leave the default 5-3 bit division as is. If you want to roll-your-own you can change this with SetStyleBits.

If you want to use a lexer, use SetLexer to choose one of the prebuilt lexers. If you want your app to handle styling, use wxSTC_LEX_CONTAINER as the argument to SetLexer. In this case, your app would be sent STYLE_NEEDED events when styling is needed; see EVT_STC_STYLENEEDED. Of course, whatever GUI object contains the STC would need to have a EVT_STC_STYLENEEDED(win, id, func) statment.

The Scintilla documentation points out that you can style text during an idle event, or that you may wish to style text to mark errors that were detected by a compiler.

With the standard 5-3 bit split of the styling byte you have 32 styles. There are some style numbers that are greater than 32 which are used for special purposes:

Style name | style# | purpose
wxSTC_STYLE_DEFAULT | 32 | This style defines the attributes that all styles receive when StyleClearAll is used.
wxSTC_STYLE_LINENUMBER | 33 | This style sets the attributes of the text used to display line numbers in a line number margin. The background colour set for this style also sets the background color for all margins that do not have any folding mask bits set. That is, any margin for which mask & wxSTC_MASK_FOLDERS is 0. See SetMarginMask for more about masks.
wxSTC_STYLE_BRACELIGHT | 34 | This style sets the attributes used when highlighting braces with BraceHighlight and when highlighting the corresponding indentation with SetHighlightGuide.
wxSTC_STYLE_BRACEBAD | 35 | This style sets the display attributes used when marking an unmatched brace with BraceBadLight.
wxSTC_STYLE_CONTROLCHAR | 36 | This style sets the display attributes used when drawing control characters. See also: SetControlCharSymbol.
wxSTC_STYLE_INDENTGUIDE | 37 | This style sets the foreground and background colors used when drawing the indentation guides.

You'll need to set the visual attributes of each style that you wish to use, including the predefined special styles shown in the above table. StyleSetBold, StyleSetItalic, StyleSetSize, StyleSetFaceName, and StyleSetCharacterSet are used to set the font, size, bold, italic, underline, character set, and foreground and background colors. You can even make text all upper- or lower-case or make it invisible. You can affect a number of attributes with one call by using StyleSetSpec (this is provided for wxWindows/wxPython and doesn't appear in the Scintilla documentation).

If you want to use one of the built-in lexers, see Variable Wrappers to discover the styles used by each lexer. As an example, the Python lexer uses these styles: wxSTC_P_CHARACTER, wxSTC_P_CLASSNAME, wxSTC_P_COMMENTBLOCK, wxSTC_P_COMMENTLINE, wxSTC_P_DEFAULT, wxSTC_P_DEFNAME, wxSTC_P_IDENTIFIER, wxSTC_P_NUMBER, wxSTC_P_OPERATOR, wxSTC_P_STRING, wxSTC_P_STRINGEOL, wxSTC_P_TRIPLE, wxSTC_P_TRIPLEDOUBLE, and wxSTC_P_WORD. Each is used to style a particular type of attribute in Python. If you look at the wxPython demo for the wxStyledTextCtrl, you'd see the following code which sets the styles for the 'special' styles as well as those used by the Python lexer. Note also that this code uses StyleSetSpec, a composite method that permits setting all of the attributes of a style in one operation:

    if wxPlatform == '__WXMSW__':
        faces = { 'times': 'Times New Roman',
                  'mono' : 'Courier New',
                  'helv' : 'Arial',
                  'other': 'Comic Sans MS',
                  'size' : 10,
                  'size2': 8,
                 }
    else:
        faces = { 'times': 'Times',
                  'mono' : 'Courier',
                  'helv' : 'Helvetica',
                  'other': 'new century schoolbook',
                  'size' : 12,
                  'size2': 10,
                 }

    # Global default styles for all languages
    self.StyleSetSpec(wxSTC_STYLE_DEFAULT,     "face:%(helv)s,size:%(size)d" % faces)
    self.StyleSetSpec(wxSTC_STYLE_LINENUMBER,  "back:#C0C0C0,face:%(helv)s,size:%(size2)d" % faces)
    self.StyleSetSpec(wxSTC_STYLE_CONTROLCHAR, "face:%(other)s" % faces)
    self.StyleSetSpec(wxSTC_STYLE_BRACELIGHT,  "fore:#FFFFFF,back:#0000FF,bold")
    self.StyleSetSpec(wxSTC_STYLE_BRACEBAD,    "fore:#000000,back:#FF0000,bold")

    # Python styles
    # White space
    self.StyleSetSpec(wxSTC_P_DEFAULT, "fore:#808080,face:%(helv)s,size:%(size)d" % faces)
    # Comment
    self.StyleSetSpec(wxSTC_P_COMMENTLINE, "fore:#007F00,face:%(other)s,size:%(size)d" % faces)
    # Number
    self.StyleSetSpec(wxSTC_P_NUMBER, "fore:#007F7F,size:%(size)d" % faces)
    # String
    self.StyleSetSpec(wxSTC_P_STRING, "fore:#7F007F,italic,face:%(times)s,size:%(size)d" % faces)
    # Single quoted string
    self.StyleSetSpec(wxSTC_P_CHARACTER, "fore:#7F007F,italic,face:%(times)s,size:%(size)d" % faces)
    # Keyword
    self.StyleSetSpec(wxSTC_P_WORD, "fore:#00007F,bold,size:%(size)d" % faces)
    # Triple quotes
    self.StyleSetSpec(wxSTC_P_TRIPLE, "fore:#7F0000,size:%(size)d" % faces)
    # Triple double quotes
    self.StyleSetSpec(wxSTC_P_TRIPLEDOUBLE, "fore:#7F0000,size:%(size)d" % faces)
    # Class name definition
    self.StyleSetSpec(wxSTC_P_CLASSNAME, "fore:#0000FF,bold,underline,size:%(size)d" % faces)
    # Function or method name definition
    self.StyleSetSpec(wxSTC_P_DEFNAME, "fore:#007F7F,bold,size:%(size)d" % faces)
    # Operators
    self.StyleSetSpec(wxSTC_P_OPERATOR, "bold,size:%(size)d" % faces)
    # Identifiers
    self.StyleSetSpec(wxSTC_P_IDENTIFIER, "fore:#808080,face:%(helv)s,size:%(size)d" % faces)
    # Comment-blocks
    self.StyleSetSpec(wxSTC_P_COMMENTBLOCK, "fore:#7F7F7F,size:%(size)d" % faces)
    # End of line where string is not closed
    self.StyleSetSpec(wxSTC_P_STRINGEOL, "fore:#000000,face:%(mono)s,back:#E0C0E0,eol,size:%(size)d" % faces)

GetEndStyled()

Scintilla keeps a record of the last character that is likely to be styled correctly. This is moved forwards when characters after it are styled and moved backwards if changes are made to the text of the document before it. Before drawing text, this position is checked to see if any styling is needed and a notification message sent to either the lexer or to the designated recipient of a EVT_STC_STYLENEEDED event; typically the GUI element (probably a panel or other window) that contains the STC. Upon receipt of this event, your app can use GetEndStyled to work out where it needs to start styling. The STC will always ask to style whole lines.

The return value is an integer.

top

GetLineState(line)

Returns an integer with the line state for the line specified by the integer parameter line. See SetLineState for more information.

top

GetMaxLineState

Returns the last line that has any line state. See SetLineState for more information.

top

SetLineState(line, state)

For the line specified by the integer parameter line the internally-stored state is set to state, also an integer. This so-called state is an arbitrary value used by some code, e.g., a parser, that needs to associate a state value with a line. Unless you're doing something like that, SetLineState has no real use for you. Returns None.

top

SetStyleBytes(length, styleBytes)

This method is used to set a number of style bytes specified by the integer parameter length to a set of values from the string styleBytes (ex. "/x01,/x02"). Also see SetStyling, which lets you style a number of characters to a single style.

The start point for styling must be set prior to using SetStyleBytes by using StartStyling. After SetStyleBytes the styling position is increased by the value of the length parameter. The bytes in styleBytes must not have bits that aren't specified in the mask argument to StartStyling.

Returns None.

top

SetStyling(length,style)

This method is used to set a number of style bytes specified by the integer parameter length to a single value specified by the integer parameter style. Also see SetStyleBytes, which lets you style a number of characters to a set of styles specified by an array of style numbers.

The start point for styling must be set prior to using SetStyling by using StartStyling. After SetStyling the styling position is increased by the value of the length parameter. The byte 'style' must not have bits that aren't specified in the mask argument to StartStyling.

top

StartStyling(pos,mask)

You use this method to set up for styling prior to executing one or more calls to SetStyleBytes or SetStyling. Returns None.

The integer parameter pos sets the position where you'd like to begin styling operations. The integer parameter mask indicates which bits of the style bytes to modify.

From the Scintilla documentation: The mask allows styling to occur over several passes, with, for example, basic styling done on an initial pass to ensure that the text of the code is seen quickly and correctly, and then a second slower pass, detecting syntax errors and using indicators to show where these are. For example, with the standard settings of 5 style bits and 3 indicator bits, you would use a mask value of 31 (0x1f) if you were setting text styles and did not want to change the indicators.

top

StyleClearAll()

StyleClearAll is used to set the attributes of each style to those set in the default style, wxSTC_STYLE_DEFAULT. Returns None.

The Scintilla documentation points out that a nifty way to use this method is to set the attributes of the default style then use StyleClearAll to set all the styles to these defaults. Then you can make changes to the other styles as needed, rather than programming all of them independently. However, Scintilla natively doesn't have the StyleSetSpec method, which allows multiple style attributes to be set in one call; this is in the wxWindows/wxPython implementation. Hence, StyleClearAll may not really be that useful for this purpose (but didn't want to leave this possible use out entirely).

top

StyleResetDefault()

Returns the attributes for wxSTC_STYLE_DEFAULT to the STC defaults prior to any modifications that you might have made. Returns None.

top

StyleSetBackground(style,back)

Set the background color for the style specified by the integer parameter style to the value specified by back. The value for back may be a wxColour object, a #RRGGBB string, or a color spec like "white". Returns None.

The background color is used to fill in the space not occupied by a character.

top

StyleSetBold(style, bold)

Turn on or off the BOLD mode for the style specifed by the integer parameter style. The integer parameter bold is 1 to turn bolding on or 0 to turn it off. Returns None.

top

StyleSetCase(style, caseForce)

Change the case of text while displayed. Doesn't affect what's in the buffer. The style number is specified by the integer parameter style and the caseForce parameter is also an integer. Its values are shown in the table below. The method returns None.

value | effect
wxSTC_CASE_MIXED | Mixed case
wxSTC_CASE_UPPER | Force all upper case
wxSTC_CASE_LOWER | Force all lower case

top

StyleSetChangeable(style, changeable)

This is an experimental and incompletely implemented style attribute. The default setting is changeable set true but when set false it makes text read-only. Currently it only stops the caret from being within not-changeable text and does not yet stop deleting a range that contains not-changeable text.

The values style and changeable are integers. The return value is None.

top

StyleSetCharacterSet(style, characterSet)

Sets the character set for the style specified by the integer parameter style to the character set specified by the integer parameter characterSet.

The character sets supported on Windows and GTK are shown in the table below:

char set | Win32 | GTK+
wxSTC_CHARSET_ANSI | Y | Y
wxSTC_CHARSET_ARABIC | Y | N
wxSTC_CHARSET_BALTIC | Y | N
wxSTC_CHARSET_CHINESEBIG5 | Y | N
wxSTC_CHARSET_DEFAULT | Y | N
wxSTC_CHARSET_EASTEUROPE | Y | Y
wxSTC_CHARSET_GB2312 | Y | Y
wxSTC_CHARSET_GREEK | Y | N
wxSTC_CHARSET_HANGUL | Y | Y
wxSTC_CHARSET_HEBREW | Y | Y
wxSTC_CHARSET_JOHAB | Y | N
wxSTC_CHARSET_MAC | Y | N
wxSTC_CHARSET_OEM | Y | N
wxSTC_CHARSET_RUSSIAN | Y | N
wxSTC_CHARSET_SHIFTJIS | Y | Y
wxSTC_CHARSET_SYMBOL | Y | N
wxSTC_CHARSET_THAI | Y | N
wxSTC_CHARSET_TURKISH | Y | N
wxSTC_CHARSET_VIETNAMESE | Y | N

From the Scintilla documentation: The places where such characters sets are likely to be useful are comments and literal strings. For example, StyleSetCharacterSet(wxSTC_C_STRING, wxSTC_CHARSET_RUSSIAN) would ensure that strings in Russian would display correctly in C and C++ (wxSTC_C_STRING is the style number used by the C and C++ lexer to display literal strings; it has the value 6). This feature currently only works fully on Windows.

top

StyleSetEOLFilled(style, filled)

Set the 'filled' attribute for the style specified by the integer parameter style. The value of filled (also an integer) is 1 to set the attribute or 0 to reset it. Returns None.

From the Scintilla documentation: 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. This is useful when a document contains embedded sections in another language such as HTML pages with embedded JavaScript. By using this feature with a consistent background colour (different from the background color set for the HTML styles) to all JavaScript styles then JavaScript sections will be easily distinguished from HTML.

top

StyleSetFaceName(style, facename)

This method is used to set the font face name for the style specified by the integer parameter style to the face name specified by the string parameter facename. Returns None.

To avoid confusion with the Scintilla documentation, be aware that this method is analagous to the Scintilla command STYLESETFONT. The facename parameter is not a wxFont, it's a font name: for example, if you had a wxFont, you'd use font.GetFaceName() to get the value to use for facename.

Because of this, it's probably better to use StyleSetFont or StyleSetSpec as they transparently deal with the use of wxFonts as would be common in the wxPython environment.

top

StyleSetFont(styleNum, font)

For the style specified by the integer parameter styleNum, set all the font parameters to those of the wxFont object parameter font. Returns None.

Internally (in C), this method extracts the facename, point size, bold, italic, and underline attributes of the font and sends them to the StyleSetFontAttr. Hence, it's a shortcut.

top

StyleSetFontAttr(styleNum, size, faceName, bold, italic, underline)

This method allows you to set various attributes for the style specified by the integer parameter styleNum. The parameters size, bold, italic, and underline are integers. Furthermore, bold, italic, and underline are 0/1 boolean flags. The facename parameter is a string object. Returns None. Also see StyleSetSpec.

top

StyleSetForeground(style, fore)

Set the foreground color for the style specified by the integer parameter style to the value specified by fore. The value for fore may be a wxColour object, a #RRGGBB string, or a color spec like "white". Returns None.

The foreground color is used to draw characters.

top

StyleSetItalic(style, italic)

Sets the italic attribute for the style number specified by the integer parameter style to the value of italic (also an integer, but boolean in intent). Returns None.

top

StyleSetSize(style, sizePoints)

Sets the size in points for the style specified by the integer parameter style to the value of the integer parameter sizePoints. Returns None.

top

StyleSetSpec(styleNum, spec)

A swiss-army knife method, it takes a string object spec and applies the information from the string as the attributes for the style specified by the integer parameter styleNum. Returns None.

The specification string has various tokens, some with options.

    bold                    turns on bold
    italic                  turns on italics
    fore:#RRGGBB            sets the foreground colour
    back:#RRGGBB            sets the background colour
    face:[facename]         sets the font face name to use
    size:[num]              sets the font size in points
    eol                     turns on eol filling
    underline               turns on underlining

Also see the example at the top of this page.

top

StyleSetUnderline(style, underline)

Sets the underline attribute for the style number specified by the integer parameter style to the value of underline (also an integer, but boolean in intent). Returns None.

top

StyleSetVisible(style, visible)

Sets the visibility attribute for the style number specified by the integer parameter style to the value of visible (also an integer, but boolean in intent). Returns None.

top