PyFrame Guide to wxPython
Copyright and License information Home
__ A B C D E F G H I L M P R S T U V W
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. Note that the Hypertext lexer uses 7 bits for styling. This affects wxSTC_LEX_HTML, wxSTC_LEX_XML, wxSTC_LEX_ASP, wxSTC_LEX_PHP.
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.
GetMaxLineState()
Returns the last line that has any line state. See SetLineState for more information.
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.
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.
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.
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.
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).
StyleResetDefault()
Returns the attributes for wxSTC_STYLE_DEFAULT to the STC defaults prior to any modifications that you might have made. Returns None.
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.
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.
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
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.
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
wxSTC_CHARSET_ARABIC
N
wxSTC_CHARSET_BALTIC
wxSTC_CHARSET_CHINESEBIG5
wxSTC_CHARSET_DEFAULT
wxSTC_CHARSET_EASTEUROPE
wxSTC_CHARSET_GB2312
wxSTC_CHARSET_GREEK
wxSTC_CHARSET_HANGUL
wxSTC_CHARSET_HEBREW
wxSTC_CHARSET_JOHAB
wxSTC_CHARSET_MAC
wxSTC_CHARSET_OEM
wxSTC_CHARSET_RUSSIAN
wxSTC_CHARSET_SHIFTJIS
wxSTC_CHARSET_SYMBOL
wxSTC_CHARSET_THAI
wxSTC_CHARSET_TURKISH
wxSTC_CHARSET_VIETNAMESE
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
To install Wx::Scintilla, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Wx::Scintilla
CPAN shell
perl -MCPAN -e shell install Wx::Scintilla
For more information on module installation, please visit the detailed CPAN module installation guide.