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
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
Yes
moved to put caret on top/on right
1
moved by one position
centred on the caret
-
Caret is always on top/on right of display
No, caret is always centred
>0
moved to put caret out of the asymmetrical UZ
moved to put caret out of the UZ
moved to put caret at 3UZ of the top or right margin
moved to put caret at 3UZ of the margin
Caret is always at UZ of top/right margin
No, kept out of UZ
----
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.
GetCaretLineBack()
Returns a wxColour that's the background color to be used when highlighting the line containing the caret. See SetCaretLineVisible.
GetCaretLineVisible()
Returns the state of the caret line visible mode. See SetCaretLineVisible.
GetCaretPeriod()
Returns the blink rate of the caret. See SetCaretPeriod.
GetCaretWidth()
Returns an integer object that's the caret width in pixels. See SetCaretWidth.
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.
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.
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.
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.
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.
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.
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.
To install Wx::Scintilla, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Wx::Scintilla
CPAN shell
perl -MCPAN -e shell install Wx::Scintilla
For more information on module installation, please visit the detailed CPAN module installation guide.