The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Wx-Scintilla-0.16
River stage one • 1 direct dependent • 1 total dependent
5 ++
/ share::doc::markers

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

wxStyledTextCtrl - Markers

  • MarkerAdd

  • MarkerDefine

  • MarkerDelete

  • MarkerDeleteAll

  • MarkerDeleteHandle

  • MarkerGet

  • MarkerLineFromHandle

  • MarkerNext

  • MarkerPrevious

  • MarkerSetBackground

  • MarkerSetForeground

Summary:

Markers and Margins: they're intimately connected. Markers are totally useless without a margin to put them in (duh). What's important is that each of the three left-side margins supports up to 32 symbol specifiers using a 32-bit bit-mapped vector called a mask. This mask is set for each margin using SetMarginMask. You then assign a marker for each bit using MarkerDefine. This method associates an ordinal number in the range 0..31 (corresponding with a bit position in the mask) to a symbol or alphanumeric character, or, in the future, with a pixmap.

For example, if you assign the wxSTC_MARK_ARROW symbol to bit position 0, then whenever you use MarkerAdd to add marker #0 to a particular line, an arrow will appear in any of the three margins that has bit 0 set in its mask. MarkerAdd() returns a handle to the marker that you can use to keep track of it.

You can 'turn on' any defined symbol for any line: as a matter of fact, you could turn on all 31 at once if you had defined all of them. However, symbols are drawn starting with symbol #0, so the highest numbered symbol will appear on top.

The markers for each line are maintained in a linked list of the marker handles. When a line is deleted, its handles are added to the list for the previous line: in effect, ORing the markers (although some may be duplicated, this op is not currently checked for dupes).

The STC moves markers along with their text lines by watching the movement of the beginning of each line.

So, each marker number has an associated symbol. When the STC is instantiated, all markers are set to symbol index 0, which is wxSTC_MARK_CIRCLE. You can use MarkerDefine to assign a different symbol to each marker number. You can use MarkerSetBackground and MarkerSetForeground to set the color scheme for each marker, so indeed you can use each marker more than once if you wish, with different colors.

What symbols are there to use? In future versions of the STC you'll be able to use pixmaps (XPM format). This is supported in Scintilla but not yet in wxPython. For now, you can use symbols or characters, see MarkerDefine.

Some marker numbers are reserved for use in folding margins (#25..#31), although you can certainly use them for your own purposes if you're not doing folding. There are some defined variables that you can use as constants when referring to the 'folding' marker numbers, you could use one of these as the first argument to MarkerDefine:

 wxSTC_MARKNUM_FOLDEREND = 25
 wxSTC_MARKNUM_FOLDEROPENMID = 26
 wxSTC_MARKNUM_FOLDERMIDTAIL = 27
 wxSTC_MARKNUM_FOLDERTAIL = 28
 wxSTC_MARKNUM_FOLDERSUB = 29
 wxSTC_MARKNUM_FOLDER = 30
 wxSTC_MARKNUM_FOLDEROPEN = 31

There are also a number of defined variables that you can use to refer to symbols; you could use one of these as the second argument to MarkerDefine.

 wxSTC_MARK_ARROW
 wxSTC_MARK_ARROWDOWN
 wxSTC_MARK_ARROWS
 wxSTC_MARK_BACKGROUND  (changes the background color of the line, no effect on margin)
 wxSTC_MARK_BOXMINUS
 wxSTC_MARK_BOXMINUSCONNECTED
 wxSTC_MARK_BOXPLUS
 wxSTC_MARK_BOXPLUSCONNECTED
 wxSTC_MARK_CHARACTER   (used to create a character-symbol, see below)
 wxSTC_MARK_CIRCLE
 wxSTC_MARK_CIRCLEMINUS
 wxSTC_MARK_CIRCLEMINUSCONNECTED = 
 wxSTC_MARK_CIRCLEPLUS
 wxSTC_MARK_CIRCLEPLUSCONNECTED
 wxSTC_MARK_DOTDOTDOT
 wxSTC_MARK_EMPTY      (invisible, see below)
 wxSTC_MARK_LCORNER
 wxSTC_MARK_LCORNERCURVE
 wxSTC_MARK_MINUS
 wxSTC_MARK_PLUS
 wxSTC_MARK_ROUNDRECT
 wxSTC_MARK_SHORTARROW
 wxSTC_MARK_SMALLRECT
 wxSTC_MARK_TCORNER
 wxSTC_MARK_TCORNERCURVE
 wxSTC_MARK_VLINE

From the Scintilla Documentation:

The wxSTC_MARK_EMPTY symbol is invisible, allowing client code to track the movement of lines. You would also use it if you chang the folding style dynamically and wanted one or more of the wxSTC_MARKNUM_ group of markers to have no associated symbol.

If you want to use a character as a symbol, add the ASCII value of the character to wxSTC_MARK_CHARACTER: e.g., MarkerDefine(1,wxSTC_MARK_CHARACTER+(ASCII code for char)).

The following markers are designed to be used to provide a flattened-tree style folding margin: wxSTC_MARK_BOXMINUS, wxSTC_MARK_BOXMINUSCONNECTED, wxSTC_MARK_BOXPLUS, wxSTC_MARK_BOXPLUSCONNECTED, wxSTC_MARK_CIRCLEMINUS, wxSTC_MARK_CIRCLEMINUSCONNECTED, wxSTC_MARK_CIRCLEPLUS, wxSTC_MARK_CIRCLEPLUSCONNECTED, wxSTC_MARK_LCORNER, wxSTC_MARK_LCORNERCURVE, wxSTC_MARK_TCORNER, wxSTC_MARK_TCORNERCURVE, and wxSTC_MARK_VLINE.

The marker numbers wxSTC_MARKNUM_FOLDER and wxSTC_MARKNUM_FOLDEROPEN are used for showing that a fold is present and open or closed. Any symbols may be assigned for this purpose although the (wxSTC_MARK_PLUS, wxSTC_MARK_MINUS) pair or the (wxSTC_MARK_ARROW, wxSTC_MARK_ARROWDOWN) pair are good choices. As well as these two, more assignments are needed for the flattened tree style: wxSTC_MARKNUM_FOLDEREND, wxSTC_MARKNUM_FOLDERMIDTAIL, wxSTC_MARKNUM_FOLDEROPENMID, wxSTC_MARKNUM_FOLDERSUB, and wxSTC_MARKNUM_FOLDERTAIL. The bits used for folding is specified by wxSTC_MASK_FOLDERS which is commonly used as an argument to SetMarginMask when defining a margin to be used for folding.

This table shows which wxSTC_MARK_* symbols should be assigned to which wxSTC_MARKNUM_* marker numbers to obtain four folding styles: Arrow (mimics Macintosh), plus/minus shows folded lines as '+' and opened folds as '-', Circle tree, Box tree.

wxSTC_MARKNUM_*

Arrow

Plus/minus

Circle tree

Box tree

FOLDEROPEN

ARROWDOWN

MINUS

CIRCLEMINUS

BOXMINUS

FOLDER

ARROW

PLUS

CIRCLEPLUS

BOXPLUS

FOLDERSUB

EMPTY

EMPTY

VLINE

VLINE

FOLDERTAIL

EMPTY

EMPTY

LCORNERCURVE

LCORNER

FOLDEREND

EMPTY

EMPTY

CIRCLEPLUSCONNECTED

BOXPLUSCONNECTED

FOLDEROPENMID

EMPTY

EMPTY

CIRCLEMINUSCONNECTED

BOXMINUSCONNECTED

FOLDERMIDTAIL

EMPTY

EMPTY

TCORNERCURVE

TCORNER

----

MarkerAdd(line,markerNumber)

Add the marker specified by markerNumber (0..31) to the line specified by line. Both line and markerNumber are integers. Returns an integer object: a handle that can be used to specify this marker when you need to find it or delete it. If line is out of range, or if there's not enough memory to add a new marker-handle list for the specified line, then MarkerAdd returns -1.

top

----

MarkerDefine(markerNumber,markerSymbol,foreground,background)

This wxPython version of MarkerDefine adds some functionality that the 'normal' Scintilla version doesn't have; namely, the ability to set the foreground and background colors. And as these args are keywords, you can only set the background if you want.

MarkerDefine is used to map marker numbers to marker symbols. The markerNumber argument is an integer in the range 0..31. As mentioned above, a numbers from 25..31 are ordinarily reserved for the folding symbols. The markerSymbol is an integer as well, and you can use one of the predefined symbol names provided or use an alphanumeric character by using wxSTC_MARK_CHARACTER+(ASCII code for char) as the value for markerSymbol.

The foreground and background are optional arguments, and you can use a wxColour object, a #RRGGBB string, or a color spec like "white".

MarkerDefine returns None.

top

----

MarkerDelete(line,markerNumber)

This method can be used to delete markers on a particular line (integer) by using the marker number, markerNumber (an integer) i.e., the symbol index, 0..31. You may also choose to delete a marker by its handle using MarkerDeleteHandle: the handle is the value returned by MarkerAdd().

What's the difference? Well, MarkerDelete scans the marker-handle list for the marker whose marker number matches that passed in by the markerNumber parameter. But, due to line deletion or other combining there can easily be more than one marker with the same marker number in the list. So, using MarkerDelete you may need to then use MarkerGet to make sure that all markers with the same marker number are deleted from a particular line. Depending on your app, it may be more efficient to keep track of marker handles and use MarkerDeleteHandle.

If markerNumber is -1, all markers are deleted from the line. MarkerDelete returns None.

top

----

MarkerDeleteAll(markerNumber)

Delete all markers that match markerNumber (integer, range 0..31) from all lines. If markerNumber is -1, then all markers are deleted from all lines. Returns None.

top

----

MarkerDeleteHandle(handle)

Searchs the entire Document for the marker which has a handle matching the integer parameter handle, then delete that marker. The parameter handle is a value returned from markerAdd. Returns None.

top

----

MarkerGet(line)

Returns a 32-bit integer object that has a bit set for each marker in the line specified by the integer parameter line. For example, if bit 1 was set then that line would have the marker symbol associated with bit 1.

top

----

MarkerLineFromHandle(handle)

Returns the line where the handle specified by the integer parameter handle was found, or -1 if it isn't found.

top

----

MarkerNext(lineStart,markerMask )

Starting at (and including) the line specified by the integer parameter lineStart, search towards the end-of-file for the first line that includes one of the markers specified by the integer parameter markerMask. markerMask is a bit-vector that has a bit set for each marker number that you want to search for. For example, if you use a markerMask of 0x80000000, then the first line that had marker #31 set would be returned. Returns -1 if the search is unsuccessful.

top

----

MarkerPrevious(lineStart,markerMask)

Starting (and including) at the line specified by the integer parameter lineStart, search towards the beginning-of-file for the first line that includes one of the markers specified by the integer parameter markerMask. markerMask is a bit-vector that has a bit set for each marker number that you want to search for. For example, if you use a markerMask of 0x80000000, then the first line that had marker #31 set would be returned. Returns -1 if the search is unsuccessful.

top

----

MarkerSetBackground(markerNumber,fore)

Set the foreground color fore for marker number markerNumber (integer, range 0..31). The parameter fore can be a wxColour object, a #RRGGBB string, or a color spec like "white". Returns None.

top

----

MarkerSetForeground(markerNumber,back)

Set the background color back for marker number markerNumber (integer, range 0..31). The parameter back can be a wxColour object, a #RRGGBB string, or a color spec like "white". Returns None.

top

----