Markers

Defining a marker

There are 32 markers, numbered 0 to 31, and you can assign any combination of them to each line in the document. Markers appear in the selection margin to the left of the text. If the selection margin is set to zero width, the background colour of the whole line is changed instead. Marker numbers 25 to 31 are used by Scintilla in folding margins, and have symbolic names of the form SC_MARKNUM_*, for example SC_MARKNUM_FOLDEROPEN.

Marker numbers 0 to 24 have no pre-defined function; you can use them to mark syntax errors or the current point of execution, break points, or whatever you need marking. If you do not need folding, you can use all 32 for any purpose you wish.

Each marker number has a symbol associated with it. You can also set the foreground and background colour for each marker number, so you can use the same symbol more than once with different colouring for different uses. Scintilla has a set of symbols you can assign (SC_MARK_*) or you can use characters. By default, all 32 markers are set to SC_MARK_CIRCLE with a black foreground and a white background.

The markers are drawn in the order of their numbers, so higher numbered markers appear on top of lower numbered ones. Markers try to move with their text by tracking where the start of their line moves. When a line is deleted, its markers are combined, by an OR operation, with the markers of the previous line.

gtkscintilla.Scintilla.set_marker(markerNumber[, markerStyle=None | **props])

Like styles you can define markers, you can assign a markerNumber to a specified marker type, color, background etc.... The marker style can be specified or with an instance of gtkscintilla.MarkerStyle or with keyword arguments.

Parameters:

• markerNumber – See the start of the page. This is the number associated with the marker.
• type – This is the marker type, see below for further infos
• pixmap – The marker type specified by a pixmap string.
• color – The foreground color of the marker.
• alpha – The translucency of the marker (0-255).
• background – The background color of the marker.

gtkscintilla.Scintilla.get_marker(markerNumber)

This is completely different from gtkscintilla.Scintilla.marker_get() because this retrieves the specifications of the marker identified by markerNumber. :returns: An instance of gtkscintilla.MarkerStyle

class gtkscintilla.MarkerStyle(**props)

This represents the style specs of a marker. The props keyword arguments are the same of gtkscintilla.Scintilla.set_marker(). The props are its attributes.

The type parameter

The general-purpose marker symbols currently available are: SC_MARK_CIRCLE, SC_MARK_ROUNDRECT, SC_MARK_ARROW, SC_MARK_SMALLRECT, SC_MARK_SHORTARROW, SC_MARK_EMPTY, SC_MARK_ARROWDOWN, SC_MARK_MINUS, SC_MARK_PLUS, SC_MARK_ARROWS, SC_MARK_DOTDOTDOT, SC_MARK_EMPTY, SC_MARK_BACKGROUND, SC_MARK_LEFTRECT, SC_MARK_FULLRECT, and SC_MARK_UNDERLINE.

The SC_MARK_BACKGROUND marker changes the background colour of the line only. The SC_MARK_FULLRECT symbol mirrors this, changing only the margin background colour. SC_MARK_UNDERLINE draws an underline across the text. The SC_MARK_EMPTY symbol is invisible, allowing client code to track the movement of lines. You would also use it if you changed the folding style and wanted one or more of the SC_FOLDERNUM_* markers to have no associated symbol.

Applications may use the marker symbol SC_MARK_AVAILABLE to indicate that plugins may allocate that marker number.

There are also marker symbols designed for use in the folding margin in a flattened tree style. SC_MARK_BOXMINUS, SC_MARK_BOXMINUSCONNECTED, SC_MARK_BOXPLUS, SC_MARK_BOXPLUSCONNECTED, SC_MARK_CIRCLEMINUS, SC_MARK_CIRCLEMINUSCONNECTED, SC_MARK_CIRCLEPLUS, SC_MARK_CIRCLEPLUSCONNECTED, SC_MARK_LCORNER, SC_MARK_LCORNERCURVE, SC_MARK_TCORNER, SC_MARK_TCORNERCURVE, and SC_MARK_VLINE.

Characters can be used as markers by adding the ASCII value of the character to SC_MARK_CHARACTER (10000). For example, to use ‘A’ (ASCII code 65) as marker number 1 use:

>>> s.set_marker(1, type=SC_MARK_CHARACTER+65)

The marker numbers SC_MARKNUM_FOLDER and SC_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 (SC_MARK_PLUS, SC_MARK_MINUS) pair or the (SC_MARK_ARROW, SC_MARK_ARROWDOWN) pair are good choices. As well as these two, more assignments are needed for the flattened tree style: SC_MARKNUM_FOLDEREND, SC_MARKNUM_FOLDERMIDTAIL, SC_MARKNUM_FOLDEROPENMID, SC_MARKNUM_FOLDERSUB, and SC_MARKNUM_FOLDERTAIL. The bits used for folding are specified by SC_MASK_FOLDERS, which is commonly used as an argument to gtkscintilla.Scintilla.set_margin() when defining a margin to be used for folding (the mask parameter).

Adding and removing markers in the text

gtkscintilla.Scintilla.marker_add(line, markerNumber)

This message adds marker number markerNumber to a line. The message returns -1 if this fails (illegal line number, out of memory) or it returns a marker handle number that identifies the added marker. You can use this returned handle with marker_line_from_handle() to find where a marker is after moving or combining lines and with marker_delete_handle() to delete the marker based on its handle. The method does not check the value of markerNumber, nor does it check if the line already contains the marker.

gtkscintilla.Scintilla.marker_delete(line, markerNumber)

This searches the given line number for the given marker number and deletes it if it is present. If you added the same marker more than once to the line, this will delete one copy each time it is used. If you pass in a marker number of -1, all markers are deleted from the line.

gtkscintilla.Scintilla.marker_delete_all(markerNumber)

This removes markers of the given number from all lines. If markerNumber is -1, it deletes all markers from all lines.

gtkscintilla.Scintilla.marker_get(line)

This returns a list which markers were present on the line identified by number.

gtkscintilla.Scintilla.marker_next(lineStart, markerList)

gtkscintilla.Scintilla.marker_previous(lineStart, markerList)

These messages search efficiently for lines that include a given set of markers. The search starts at line number lineStart and continues forwards to the end of the file (marker_next()) or backwards to the start of the file (marker_previous()). The markerList argument should be a list of markers to find (referenced by marker numbers). The method returns the line number of the first line that contains one of the markers in markerList or -1 if no marker is found.

gtkscintilla.Scintilla.marker_line_from_handle(markerHandle)

The markerHandle argument is an identifier for a marker returned by marker_add(). This function searches the document for the marker with this handle and returns the line number that contains it or -1 if it is not found.

gtkscintilla.Scintilla.marker_delete_handle(markerHandle)

The markerHandle argument is an identifier for a marker returned by marker_add(). This function searches the document for the marker with this handle and deletes the marker if it is found.