PyFrame Guide to  wxPython

Copyright and License information


wxStyledTextCtrl

*Revision: 1.02 : 30 Jan 2003

March 2011: This site has been moved to a new server, but is exactly the same as it was in January 2003. The URL will not change.

If you are using these pages - please send an email to jeff ___at___ sasmor.com just so I can know if anyone is using them. They'll be here anyway, just curious to know if the site is being used.

Alphabetic Index Subject Index Variable Wrappers
__  A  B  C  D  E  F  G  H  I  L  M  P  R  S  T  U  V  W 

Overview:

This control wraps the Scintilla editor component (written by Neil Hodgson) to work with wxPython. It's a complex control that requires a lot of study to use, but it's better than writing your own :-). Scintilla is a wonderful addition to the wxPython library.

Writing this documentation showed this author the depth of the Scintilla Editor (great work, Neil) and the adept way that it was blended into the wxWindows/wxPython environment by Robin Dunn. Credit is also due to Greg Smith. He revised much of the Scintilla Documentation; which made this task a lot easier (although it was about 6 solid weeks of work, believe it or not!).

This documentation is targeted specifically at wxPython users, and has been carefully (one hopes) checked for accuracy by poring thru the Scintilla code, and the wxWindows/wxPython layers. The arguments shown for Python method calls have the keywords expected by the Python adaptation layer, although generally you do not need to use them. Return types are shown; note that many methods return None even though one might expect them to return nothing at all. Folks interested more in WxWindows- or Scintilla-level programming may benefit reading these pages just to see some of the many details I uncovered during the writing process, but of course certain information will be incorrect - most notably with respect to calling parameters and return values as Python does not use pointers. Also, a number of method names in the wxPython version are different than the names shown in the Scintilla documentation; some of the methods available in wxPython (and wxWindows) versions of the STC are not available in the Scintilla DLL version.

In a number of cases, comments from the Scintilla source code are incorporated into this documentation for clarity; often these comments are massaged so that variable names, etc. match those used in the wxPython port. Some of the information in this document is from the Scintilla documentation, again, massaged to match what makes sense for wxPython. The abbreviation STC is used throughout rather than writing wxStyledTextCtrl a few hundred extra times.

If you find any errors or have any questions please contact jeff_at_sasmor.com. Please note that as this is a new document (1.0 was issued 01 January 2003, revisions noted in the heading for this page), there are likely to be some errors.

PLEASE do not send questions about use of the STC, please use the appropriate listserv for that!


Miscellany:

  1. You need to add the following line to your program in order to use the STC:
           from wxPython.stc import * 
  2. You should look at the Initialization page to see how to instantiate a STC
  3. General: For performance reasons, all lines of text are the same height; said height is set by the largest font in any current style.
  4. There are a few commands listed in the official Scintilla documentation that don't seem to exist:
    • AppendText
  5. Color/Colour specifications use the RGB format. Each of the Red, Green, and Blue values can range from 0 thru 255. When combined into one value, it's (blue<<16) | (green<<8) | red. Most places where a color must be specified can use one of three formats: a wxColour object, a #RRGGBB string, or a color spec like "white". See this for more information about color specs. Also, see this for a quick way to go from #RRGGBB to RGB.
  6. Very often we'll use the term 'constant' when we mean 'variable'. There are a large number of symbolic values useful when programming the wxWindows/wxPython port of Scintilla, these are shown in Variable Wrappers. An example would be wxSTC_MARGIN_SYMBOL. If you were using the wxWindows port of Scintilla (the wxPython port is based on this), these would actually be constants that would probably come from an include file. Since Python has neither constants nor include files, the SWIGged port of the STC uses variables. But it's less confusing to call them constants, as they are sort of 'proxies' for constants. Anyway, this variable-as-proxy-for-a-constant system is used throughout wxPython, but one likes to keep one's nomenclature in check.
  7. The mouse wheel will ordinarily scroll the text vertically, if CTRL is held down then the text size of all styles changes. Unsure if this is Win32 only.
  8. If <ALT> is pressed while selecting text, then the selection is forced to be rectangular. See SelectionIsRectangle for a way to detemine the type of selection programmatically.
  9. Line numbers begin at zero. When they're drawn in a margin they start at 1. Don't get confused!

Pointers in wxPython:

For those who aren't aware of it, the C/C++ pointers that are used extensively in wxWindows are translated to and from string objects:

hexaddress_pointertype
for example:
XXXXXXXX__wxStyledTextCtrl_p
is the return value from wxStyledTextCtrl.__init__().

This is due to the SWIG interface, and the details of it are both transparent and beyond the scope of this guide. The interested person is directed to look at WXPYTHON/WXSWIG/Runtime/libpy.c for details of the conversion.

The reason for mentioning this here at all, is that when a phrase like "returns a wxColour" is used, what's meant is that a pointer-string is returned that can be used to reference the wxColour.

Editorial -- Honestly, unless I've misunderstood this, it seems remarkably inefficient to convert back and forth to and from strings every time you create or reference/use one of these 'pointers.' Could it be endian issues? Wouldn't a data structure of some kind with the pointer maintained as a long int (need support for 64 bit addressing) be better? Well, I'm sure that there must be a good reason...


Subject Index

Auto-completion
Brace checking
Call Tips
Caret
Clipboard
Color Names
Events
Event Object
Folding
Helpful Hints
Indicators
Initialization
Key mapping and execution
Keyboard proxy commands
Layout
Lexing
Line Endings
Long Line Indicators
Macros
Margins
Markers
Multiple Views
Printing
Regular Expressions
Scrolling
Searching
Selection & Positioning
Styling & Style Definition
Tabs & Indentation Guides
Text setting and retrieval
Undo
Utility / Miscellaneous
Variable Wrappers
White Space
Zooming


Alphabetic Index

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


__

__init__

__repr__

Go to Top of Alphabetic Index


A

AddRefDocument

AddStyledText

AddText

Auto Completion
AutoCompActive
AutoCompCancel
AutoCompComplete
AutoCompGetAutoHide
AutoCompGetCancelAtStart
AutoCompGetChooseSingle
AutoCompGetDropRestOfWord
AutoCompGetIgnoreCase
AutoCompGetSeparator
AutoCompPosStart
AutoCompSelect
AutoCompSetAutoHide
AutoCompSetCancelAtStart
AutoCompSetChooseSingle
AutoCompSetDropRestOfWord
AutoCompSetFillUps
AutoCompSetIgnoreCase
AutoCompSetSeparator
AutoCompShow
AutoCompStops

Go to Top of Alphabetic Index


B

BeginUndoAction

BraceBadLight

BraceHighlight

Go to Top of Alphabetic Index


C
CallTips
CallTipActive
CallTipCancel
CallTipPosAtStart
CallTipSetBackground
CallTipSetHighlight
CallTipShow

CanPaste

CanRedo

CanUndo

Clear

ClearAll

ClearDocumentStyle

CmdKeyAssign

CmdKeyClear

CmdKeyClearAll

CmdKeyExecute

Colourise

ConvertEOLs

Copy

CreateDocument

Cut

Go to Top of Alphabetic Index


D

DelLineLeft

DelLineRight

DocLineFromVisible

Go to Top of Alphabetic Index


E

EmptyUndoBuffer

EndUndoAction

EnsureCaretVisible

EnsureVisible

EnsureVisibleEnforcePolicy

Go to Top of Alphabetic Index


B

FindText

FormatRange

Go to Top of Alphabetic Index


G
GetXX
GetAnchor
GetBackSpaceUnIndents
GetBufferedDraw
GetCaretForeground
GetCaretLineBack
GetCaretLineVisible
GetCaretPeriod
GetCaretWidth
GetCharAt
GetCodePage
GetColumn
GetControlCharSymbol
GetCurLine
GetCurrentLine
GetCurrentPos
GetCursor
GetDocPointer
GetEdgeColour
GetEdgeColumn
GetEdgeMode
GetEndAtLastLine
GetEndStyled
GetEOLMode
GetFirstVisibleLine
GetFoldExpanded
GetFoldLevel
GetFoldParent
GetHighlightGuide
GetIndent
GetIndentationGuides
GetLastChild
GetLastKeydownProcessed
GetLayoutCache
GetLength
GetLexer
GetLine
GetLineCount
GetLineEndPosition
GetLineIndentation
GetLineIndentPosition
GetLineState
GetLineVisible
GetMarginLeft
GetMarginMask
GetMarginRight
GetMarginSensitive
GetMarginType
GetMarginWidth
GetMaxLineState
GetModEventMask
GetModify
GetMouseDownCaptures
GetMouseDwellTime
GetOvertype
GetPrintColourMode
GetPrintMagnification
GetReadOnly
GetScrollWidth
GetSearchFlags
GetSelectedText GetSelection
GetSelectionEnd
GetSelectionStart
GetStatus
GetSTCFocus
GetStyleAt
GetStyleBits
GetStyledText
GetTabIndents
GetTabWidth
GetTargetEnd
GetTargetStart
GetText
GetTextLength
GetTextRange
GetUndoCollection
GetUseHorizontalScrollBar
GetUseTabs
GetViewEOL
GetViewWhiteSpace
GetWrapMode
GetXOffset
GetZoom

GotoLine

GotoPos

Go to Top of Alphabetic Index


H

HideLines

HideSelection

HomeDisplay

HomeDisplayExtend

Go to Top of Alphabetic Index


I

IndicatorGetForeground

IndicatorGetStyle

IndicatorSetForeground

IndicatorSetStyle

InsertText

Go to Top of Alphabetic Index


L

LineEndDisplay

LineEndDisplayExtend

LineFromPosition

LineLength

LineScroll

LinesOnScreen

Go to Top of Alphabetic Index


M

MarkerAdd

MarkerDefine

MarkerDelete

MarkerDeleteAll

MarkerDeleteHandle

MarkerGet

MarkerLineFromHandle

MarkerNext

MarkerPrevious

MarkerSetBackground

MarkerSetForeground

MoveCaretInsideView

Go to Top of Alphabetic Index


P

Paste

PointFromPosition

PositionFromLine

PositionFromPoint

PositionFromPointClose

Go to Top of Alphabetic Index


R

Redo

ReleaseDocument

ReplaceSelection

ReplaceTarget

ReplaceTargetRE

Go to Top of Alphabetic Index


S

ScrollToColumn

ScrollToLine

SearchAnchor

SearchInTarget

SearchNext

SearchPrev

SelectAll

SelectionIsRectangle

SendMsg

SetXX
SetAnchor
SetBackSpaceUnIndents
SetBufferedDraw
SetCaretForeground
SetCaretLineBack
SetCaretLineVisible
SetCaretPeriod
SetCaretWidth
SetCodePage
SetControlCharSymbol
SetCurrentPos
SetCursor
SetDocPointer
SetEdgeColour
SetEdgeColumn
SetEdgeMode
SetEndAtLastLine
SetEOLMode
SetFoldExpanded
SetFoldFlags
SetFoldLevel
SetHighlightGuide
SetHScrollBar
SetIndent
SetIndentationGuides
SetKeyWords
SetLastKeydownProcessed
SetLayoutCache
SetLexer
SetLexerLanguage
SetLineIndentation
SetLineState
SetMarginLeft
SetMarginMask
SetMarginRight
SetMargins
SetMarginSensitive
SetMarginType
SetMarginWidth
SetModEventMask
SetMouseDownCaptures
SetMouseDwellTime
SetOvertype
SetPrintColourMode
SetPrintMagnification
SetProperty
SetReadOnly
SetSavePoint
SetScrollWidth
SetSearchFlags
SetSelBackground
SetSelection
SetSelectionEnd
SetSelectionStart
SetSelForeground
SetStatus
SetSTCFocus
SetStyleBits
SetStyleBytes
SetStyling
SetTabIndents
SetTabWidth
SetTargetEnd
SetTargetStart
SetText
SetUndoCollection
SetUseHorizontalScrollBar
SetUseTabs
SetViewEOL
SetViewWhiteSpace
SetVisiblePolicy
SetVScrollBar
SetWhitespaceBackground
SetWhitespaceForeground
SetWordChars
SetWrapMode
SetXCaretPolicy
SetXOffset
SetYCaretPolicy
SetZoom

ShowLines

StartRecord

StartStyling

StopRecord

StyleXX
StyleClearAll
StyleResetDefault
StyleSetBackground
StyleSetBold
StyleSetCase
StyleSetChangeable
StyleSetCharacterSet
StyleSetEOLFilled
StyleSetFaceName
StyleSetFont
StyleSetFontAttr
StyleSetForeground
StyleSetItalic
StyleSetSize
StyleSetSpec
StyleSetUnderline
StyleSetVisible

Go to Top of Alphabetic Index


T

TextHeight

TextWidth

ToggleFold

Go to Top of Alphabetic Index


U

Undo

UsePopUp

UserListShow

Go to Top of Alphabetic Index


V

VisibleFromDocLine

Go to Top of Alphabetic Index


W

WordEndPosition

WordPartLeft

WordPartLeftExtend

WordPartRight

WordPartRightExtend

WordStartPosition

Go to Top of Alphabetic Index


 

License for this documention

This documentation is Copyright © 2003 Jeff Sasmor. jeff__at__sasmor.com

Except for inclusion in a physical, printed, or virtual book (such as an E-Book), permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby granted, provided that all copyright notices herein appear in all copies and that this copyright notice, this permission notice, and the following disclaimer appear in all copies. For re-use not permitted by this permission, please contact jeff__at__sasmor.com. why

JEFF SASMOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL JEFF SASMOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS DOCUMENTATION OR THE RELATED SOFTWARE.


License for Scintilla and SciTE

Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>

All Rights Reserved

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.

NEIL HODGSON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL NEIL HODGSON BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


Why?

Why this seemingly spurious restriction on copying and what does it mean? Basically, if you want to include the material provided here in a book or ebook you will need to speak to the author. If you want to include it in documentation accompanying wxPython or wxWindows, that's fine as long as you include the copyright notices provided by the author and by Neil Hodgson.

Anti-Spam Bots!