Copyright and License information Home

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

### wxStyledTextCtrl - Text operations

AddStyledText AddText ClearAll ClearDocumentStyle GetCharAt GetCurLine GetLine GetOvertype | GetReadOnly GetSearchFlags GetStyleAt GetStyleBits GetStyledText GetTargetEnd GetTargetStart | GetText GetTextRange InsertText ReplaceSelection ReplaceTarget ReplaceTargetRE SearchInTarget | SetOvertype SetReadOnly SetSavePoint SetSearchFlags SetStyleBits SetTargetEnd SetTargetStart SetText

Summary:

The methods in this section are used to perform basic text operations on the contents of the active Document. These include adding plain and styled text as well as some search and replace operations.

Backgrounder:

Character Cells

The STC Document stores characters as two-byte Cells. Each Cell comprises one byte for the character itself (Character byte)followed by a byte for styling and indicators (Style byte). The Style byte defaults to 5 bits for the style index and three bit-flags for indicators (numbered 0,1,2, see Indicators). This is illustrated in the figure below.

Also see SetStyleBits. This can be used to change the division between style bits and the number of indicator bit-flags.

The Caret and Position Encoding

The Caret is the visible marker where text insertion or overtyping happens. Its appearance is a blinking vertical line in Insert mode, or a blinking underscore in Overtype mode. The Overtype/Insert mode is controlled by the SetOverType method. The caret position can be set anywhere between the beginning and end of the Document; except between double-byte characters or between the CR and LF of a MSDOS-style line ending. The wxSTC_INVALID_POSITION constant (-1) represents an invalid position. Other Caret details are discussed in Caret Control.

Some methods require a position specification or return a position. This value refers to a character location or to the position just before that character.

Targets and Search/Replace Functionality

The STC has two different ways to perform text replacement. One can use ReplaceSelection; where the selection is replaced with the text passed to ReplaceSel. This can cause visible artifacts such as scrolling. If performing several replacements or global replacements, alternate functionality is provided that uses the concept of a target, or range of positions to operate within.

One sets the range with SetTargetStart and SetTargetEnd. The range can be retrieved with GetTargetStart and GetTargetEnd.

Then ReplaceTarget or ReplaceTargetRE can be used to perform the replacement.

You can use SearchInTarget to find a subrange within the range set with SetTargetStart and SetTargetEnd. This may be useful to narrow the range prior to a replacement using ReplaceTarget or ReplaceTargetRE.

SearchInTarget's action is modified by setting one or more search flags using SetSearchFlags.

Also see the Searching page for an alternative approach.

AddStyledText(data)

Add a buffer of styled text (data) at the current position. Each character occupies two bytes, one for the character itself and one for styling information. Clears the current selection, if any. Returns None.

top

AddText(text)

Add text at the current position. The text value must be a string object. Clears the current selection, if any. Returns None.

top

ClearAll()

Clears all text in the document. Sets the current position to zero. Returns None.

top

ClearDocumentStyle()

Clears all styling information in the document and reset the folding state. If you are using a syntax coloring capable lexer, you should use this method prior to changing lexers.

top

GetCharAt(position)

Returns the character (without styling information) at character position position. Position is an integer. Returns an integer. Also see GetStyleAt.

top

GetCurLine()

Returns a tuple `(text,pos)`, where text is a string object containing the text of the line containing the caret and pos is an integer with the position of the caret within the line. Note that pos is the position within the line, not from the start of the Document. Also, there are no passed-in parameters, unlike the version of this method shown in the Scintilla documentation.

top

GetLine(line)

Returns a string object with the contents of the line number line. The line argument must be an integer. The Python interface to STC queries the STC for the size of the line so that the buffer created for the STC to place the line's contents will always be large enough; avoiding the issue of buffer overruns.

top

GetOvertype()

Returns an integer whose value is 1 if overtype mode is active or 0 if it is not. Also see SetOvertype.

top

GetReadOnly()

Returns an integer whose value is 1 if the active Document is read-only or 0 if it is not. Also see SetReadOnly.

top

GetSearchFlags()

Returns an integer with the search flag bit settings. These are used with the SearchInTarget method. See SetSearchFlags for a description of the flags.

top

GetStyleAt(position)

Returns the styling information (only) at character position position. Position is an integer. Returns an integer. Also see GetCharAt.

top

GetStyleBits()

This method allows you to see how many bits in the style byte are being used for styling information. The return value is an integer in the range of 0..7. Ordinarily you don't need to use this functionality. Also see SetStyleBits

top

GetStyledText(startpos,endpos)

Returns a string object that contains the cellbuffers between startpos and endpos. This means that the characters and styling information are both returned.

top

GetTargetEnd()

Returns the position (an integer) within the active Document where the target range ends. See Targets for more information.

top

GetTargetStart()

Returns the position (an integer) within the active Document where the target range begins. See Targets for more information.

top

GetText()

Returns a text object that contains all the text in the Document. Does not contain any styling information.

top

GetTextRange(startpos,endpos)

Returns a text object that contains all the text in the Document that lies between startpos and endpos. Does not contain any styling information.

top

InsertText(pos,text)

Inserts the contents of string object text into the active Document at position pos. Returns None.

top

ReplaceSelection(text)

Replace the contents of the selection with the contents of the string object text. Returns None.

top

ReplaceTarget(text)

Replace the text in the range set by SetTargetStart and SetTargetEnd with the contents of the text object text. Returns an integer containing the length taken by the replacement string.

top

ReplaceTargetRE(text)

Replace the text in the range set by SetTargetStart and SetTargetEnd with the contents of the text object text. Unlike ReplaceTarget, above, it looks for \d patterns in text, where d is a digit from 1 to 9. When these are found, tagged matches from the most recent regular expression search (see SearchInTarget() are substituted for the \d patterns.

Returns an integer containing the length taken by the replacement string.

top

SearchInTarget(text)

Searches witin the range set by SetTargetStart and SetTargetEnd. If the text isn't found then -1 is returned. Otherwise the position within the document (NOT within the RANGE) where the search-text was found is returned. A side effect is that the STC's internal target-start and target-end positions are altered to the new range delimited by the start and end of the locations where the search-text was found.

The text can be affected by search-flags set by SetSearchFlags. These are:

- wxSTC_FIND_WHOLEWORD: a match occurs only if the characters before and after the match are not word characters
- wxSTC_FIND_MATCHCASE: a match occurs only if the case of the search string and the candidate string match.
- wxSTC_FIND_WORDSTART: a match occurs if the character before is not a word character.
- wxSTC_FIND_REGEXP: a simple regular-expression search: see Regular Expression Searches for more info.

top

SetOvertype(overtype)

Set the overtype flag to the value of the integer argument overtype. This value should be 1 to set overtyping mode or 0 to set insert mode. Returns None. Also see GetOvertype

top

SetReadOnly(readonly)

Set the read-only state of the active Document based on the value of the integer argument readonly. Returns None. Also see GetReadOnly

top

SetSavePoint()

SetSavePoint sets the Document state to unmodified. This is usually done when the file is saved or loaded, hence the name "save point".

As undo and redo operations are performed, EVT_STC_SAVEPOINTLEFT and EVT_STC_SAVEPOINTREACHED are emitted by the STC as appropriate, allowing the containing window to know if the file should be considered dirty or not. top

SetSearchFlags(flags)

Set the value of the target-range search flags to the value of the integer argument flags. Returns None. See SearchInTarget for more information about the flags.

top

SetStyleBits(bits)

Sets the number of bits in the styling byte that are used for styling indices to the value of the integer argument bits. Returns None. See the backgrounder on Character Cells and GetStyleBits for more information.

top

SetTargetEnd(pos)

Sets the position within the active Document where the target range ends to the value of the integer argument pos. Returns None. See Targets for more information.

top

SetTargetStart(pos)

Sets the position within the active Document where the target range begins to the value of the integer argument pos. Returns None. See Targets for more information.

top

SetText(t)

Delete all the text in the active Document, clear the selection, then insert the string from the string object argument t into the Document. Returns None.

top