Copyright and License information Home

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

### wxStyledTextCtrl - Caret Operations

- EnsureCaretVisible
- GetCaretForeground
- GetCaretLineBack
- GetCaretLineVisible
- GetCaretPeriod
- GetCaretWidth
- SetCaretForeground
- SetCaretLineBack
- SetCaretLineVisible
- SetCaretPeriod
- SetCaretWidth
- SetXCaretPolicy
- SetYCaretPolicy

Summary:

The caret is the insertion point when no selection exists. Normally this is a blinking vertical line. You can set the foreground color with SetCaretForeground, its width with SetCaretWidth, and its period with SetCaretPeriod. You can highlight the entire line that the caret's on with SetCaretLineBack.

You use the SetXCaretPolicy and SetYCaretPolicy methods to control how the caret behaves (called the policy). These methods use parameters caretPolicy and caretSlop to control how the caret is kept visible; pixelwise when moving horizontally and linewise when moving vertically. This control method is summarized below: this info is from the Scintilla sources but wxPython-ized.

SetXCaretPolicy and SetYCaretPolicy each have an argument called caretPolicy, which has an OR of the following values, for example wxSTC_CARET_SLOP | wxSTC_CARET_EVEN.

Bit | Meaning
wxSTC_CARET_CENTER | same as wxSTC_CARET_STRICT
wxSTC_CARET_EVEN | If even is not set, instead of having symmetrical UZs, the left and bottom UZs are extended up to right and top UZs respectively. This way, we favour the displaying of useful information: the begining of lines, where most code reside, and the lines after the caret, eg. the body of a function.
wxSTC_CARET_JUMPS | If jumps is set, the display is moved more energetically so the caret can move in the same direction longer before the policy is applied again. '3UZ' notation is used to indicate three time the size of the UZ as a distance to the margin.
wxSTC_CARET_SLOP | slop value will be used if 1.
wxSTC_CARET_STRICT | If strict is set, the policy is enforced... strictly. The caret is centered on the display if slop is not set, and cannot go in the UZ if slop is set.

SetXCaretPolicy and SetYCaretPolicy each have an second argument called caretSlop. As mentioned above, this is a number of pixels near the vertical margins for the X caret slop and a number of lines near the horizontal margins for the Y caret slop. The slop value defines an area where the caret shouldn't be, called the unwanted zone (UZ).

The idea is to keep the caret away from the vertical and horizontal edges so that the caret is in a sensible location: ideally, you'd like the location where the caret is present to be always visible so that the text that the caret is on can be completely seen (X policy), and that the current line is seen with some of the lines following it which are often dependent on that line (Y policy).

When an STC is created, the caret X policy is set to wxSTC_CARET_SLOP | wxSTC_CARET_EVEN and the X slop value is set to 50 pixels. The caret Y policy is set to wxSTC_CARET_EVEN and the caret Y slop is set to 0 lines.

slop | strict | jumps | even | Caret can go to the margin | On reaching limit (going out of visibility or going into the UZ) display is...
--- | --- | --- | --- | --- | ---
0 | 0 | 0 | 0 | Yes | moved to put caret on top/on right
0 | 0 | 0 | 1 | Yes | moved by one position
0 | 0 | 1 | 0 | Yes | moved to put caret on top/on right
0 | 0 | 1 | 1 | Yes | centred on the caret
0 | 1 | - | 0 | Caret is always on top/on right of display | -
0 | 1 | - | 1 | No, caret is always centred | -
>0 | 0 | 0 | 0 | Yes | moved to put caret out of the asymmetrical UZ
>0 | 0 | 0 | 1 | Yes | moved to put caret out of the UZ
>0 | 0 | 1 | 0 | Yes | moved to put caret at 3UZ of the top or right margin
>0 | 0 | 1 | 1 | Yes | moved to put caret at 3UZ of the margin
>0 | 1 | - | 0 | Caret is always at UZ of top/right margin | -
>0 | 1 | 0 | 1 | No, kept out of UZ | moved by one position
>0 | 1 | 1 | 0 | No, kept out of UZ | moved to put caret at 3UZ of the margin

EnsureCaretVisible()

Ensure that the caret is visible. Note that this calls the SCI_SCROLLCARET function in Scintilla. Returns None.

top

GetCaretForeground()

Returns a wxColour that's the color of the caret.

top

GetCaretLineBack()

Returns a wxColour that's the background color to be used when highlighting the line containing the caret. See SetCaretLineVisible.

top

GetCaretLineVisible()

Returns the state of the caret line visible mode. See SetCaretLineVisible.

top

GetCaretPeriod()

Returns the blink rate of the caret. See SetCaretPeriod.

top

GetCaretWidth()

Returns an integer object that's the caret width in pixels. See SetCaretWidth.

top

SetCaretForeground(fore)

Sets the foreground color of the caret. The parameter fore is a wxColour object, a #RRGGBB string, or a color spec like "white". Returns None.

top

SetCaretLineBack(back)

Sets the background color to be used when highlighting the line containing the caret. See SetCaretLineVisible for more information. The parameter back is a wxColour object, a #RRGGBB string, or a color spec like "white". Returns None.

top

SetCaretLineVisible(show)

This method is useful if you want to highlight the line with the caret. This is often desired when editing or when using an STC as a debugger window. The parameter show is 1 to enable this mode or 0 to reset it. This method returns None.

First set the background color of the line with SetCaretLineBack. Then use SetCaretLineVisible(1) to enable the highlighting or SetCaretLineVisible(0) to reset it.

Note that this form of background coloring has highest priority when a line has markers that would otherwise change the background color.

top

SetCaretPeriod(periodMilliseconds)

This method is used to set the caret blink rate. The parameter periodMilliseconds is an integer and the rate is measured in milliseconds. Setting the period to 0 stops the caret blinking. The default value is 500 milliseconds. Returns None.

top

SetCaretWidth(pixelWidth)

Used to set the width of the caret. The integer parameter pixelWidth must be 1, 2, or 3 pixels. If pixelWidth is less than 1 then the width is set to 1. If pixelWidth is greater than 3 then the width is set to 3. Returns None.

Note: at the time of this writing (12/2002) the underlying Scintilla code was changed to allow pixelWidth to be set to zero: this allows hiding the cursor. When wxPython is updated to use that version of Scintilla you'll be able to use this feature.

top

SetXCaretPolicy(caretPolicy,caretSlop)

Set the way the caret is kept visible when going sideways. The caretPolicy, or mode of operation is an OR of wxSTC_CARET_CENTER, wxSTC_CARET_EVEN, wxSTC_CARET_JUMPS, wxSTC_CARET_SLOP, wxSTC_CARET_STRICT. The caretSlop (exclusion zone) is given in pixels.

top

SetYCaretPolicy(caretPolicy,caretSlop)

Set the way the line the caret is on is kept visible. The caretPolicy, or mode of operation is an OR of wxSTC_CARET_CENTER, wxSTC_CARET_EVEN, wxSTC_CARET_JUMPS, wxSTC_CARET_SLOP, wxSTC_CARET_STRICT. The caretSlop (exclusion zone) is given in lines.

top