Copyright and License information

## wxStyledTextCtrl

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@sasmor.com. Please note that as this is a new document (issued 01 January 2003), 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.

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@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 the 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@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.