Copyright and License information Home

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

### Autocompletion and User lists

AutoCompActive AutoCompCancel AutoCompComplete AutoCompGetAutoHide AutoCompGetCancelAtStart AutoCompGetChooseSingle AutoCompGetDropRestOfWord | AutoCompGetIgnoreCase AutoCompGetSeparator AutoCompPosStart AutoCompSelect AutoCompSetAutoHide AutoCompSetCancelAtStart AutoCompSetChooseSingle | AutoCompSetDropRestOfWord AutoCompSetFillUps AutoCompSetIgnoreCase AutoCompSetSeparator AutoCompShow AutoCompStops UserListShow

Summary:

Autocompletion is a popular feature that pops-up a window listing possible completions for strings the user has typed. The initiating string may be a programming-language keyword or identifier, an HTML/XML tag, or a similar entity. The STC client must recognize these situations (by watching the characters that are entered into the Document) and initiate the autocompletion mode in the STC with AutoCompShow.

Once this is done the user can choose the currently-selected item in the list by pressing <TAB> or <ENTER>. If you want to use other characters in addition to <TAB> and <ENTER>, use AutoCompSetFillUps. You can programmatically trigger the completion, using the current selection, with AutoCompComplete.

While in the autocompletion mode the list will disappear when certain characters are typed. Typically these are chosen to be characters that logically can't be part of the result, e.g., punctuation or ( [ for identifiers. You can specify which characters to use with AutoCompStops. Note that the list of stop characters is initially empty, so you do need to set them.

Any cursor movement aside from backspace will also cancel the autocompletion. Note that the up/down arrow keys should normally move the current position within the popped-up list and NOT the position in the active document.

Pressing ESCAPE or simulating it with CmdKeyExecute(wxSTC_CMD_CANCEL) will cancel the autocompletion as well.

If set to ignore case mode with AutoCompSetIgnoreCase, then strings are matched after being converted to upper case. One result of this is that the list should be sorted with the punctuation characters '[', '\', ']', '^', '_', and '`' sorted after letters.

The default behaviour is for the list to be cancelled if the caret moves before the location it was at when the list was displayed. By calling AutoCompSetCancelAtStart with a false argument, the list is not cancelled until the caret moves before the first character of the word being completed.

The list will also be cancelled if there are no viable matches. To avoid this behaviour call AutoCompSetAutoHide with a false argument.

When an item is selected, any word characters following the caret are first erased if AutoCompSetDropRestOfWord is used to set this mode.

Notes:

There's a limit to the number of stop chars and fillupchars: there must be <= 255 chars for each. The STC will truncate a string input to AutoCompStops or AutoCompSetFillups at 255 characters.

Initial conditions:

- the choices separator is a space.
- chooseSingle mode is OFF (false)
- ignoreCase mode is OFF (false)
- cancelAtStartPos mode is ON (true),
- autoHide mode is ON (true),
- dropRestOfWord mode is OFF (false)
- stopChars is an empty string
- fillUpChars is an empty string

AutoCompActive()

Returns 1 if autocompletion mode is currently active.

top

AutoCompCancel()

Cancels autocompletion. Returns None.

top

AutoCompComplete()

Completes an autocompletion operation. Internally, this is caused by clicking <TAB>, <ENTER>, or one of the characters specified by AutoCompSetFillUps. AutoCompComplete allows you to complete the operation programmatically. Returns None.

top

AutoCompGetAutoHide()

Return the state of the autoHide mode. Also see: AutoCompSetAutoHide.

top

AutoCompGetCancelAtStart()

Returns the state of the cancelAtStartPos mode. Also see: AutoCompSetCancelAtStart

top

AutoCompGetChooseSingle()

Returns the state of the chooseSingle mode. Also see: AutoCompSetChooseSingle.

top

AutoCompGetDropRestOfWord()

Returns the state of the dropRestOfWord mode. Also see: AutoCompSetDropRestOfWord.

top

AutoCompGetIgnoreCase()

Returns the state of the ignoreCase mode. Also see: AutoCompSetIgnoreCase.

top

AutoCompGetSeparator()

Returns the separator character. Also see: AutoCompSetSeparator.

top

AutoCompPosStart()

Returns the position when autocompletion began.

top

AutoCompSelect(text)

Selects a string in the autocompletion listbox which matches the input sting object text. Returns None. Note: if autoHide mode is active and there's no match for text, then the autocomplete operation is cancelled.

top

AutoCompSetAutoHide(autoHide)

Sets the autoHide mode to 1 if the value of the input integer object autoHide is nonzero, otherwise it is set to 0. Returns None.

top

AutoCompSetCancelAtStart(cancel)

Sets the cancelAtStartPos mode to 1 if the value of the input integer object cancel is nonzero, otherwise it is set to 0. Returns None.

top

AutoCompSetChooseSingle(chooseSingle)

Sets the chooseSingle mode to 1 if the value of the input integer object chooseSingle is nonzero, otherwise it is set to 0. Returns None.

top

AutoCompSetDropRestOfWord(dropRestOfWord)

Sets the dropRestOfWord mode to 1 if the value of the input integer object dropRestOfWord is nonzero, otherwise it is set to 0. Returns None.

top

AutoCompSetFillUps(characterSet)

The first 255 characters of the string object characterSet are copied to fillUpChars. If a character from the set of characters in fillUpChars is pressed by the user, then the autocomplete operation is completed; just as if AutoCompComplete() was invoked programmatically. Returns None.

top

AutoCompSetIgnoreCase(ignoreCase)

Sets the ignoreCase mode to 1 if the value of the input integer object ignoreCase is nonzero, otherwise it is set to 0. Returns None.

top

AutoCompSetSeparator(separatorCharacter)

Sets the separator character that is used to separate strings in the itemList passed to AutoCompShow or UserListShow. If this method is not used then the default is the space character. Returns None.

top

AutoCompShow(lenEntered,itemList)

This method initiates an auto-complete sequence. The lenEntered argument is an integer that specifies how many characters prior to the current position are part of the word that is to be completed. The itemList argument is a string which comprises a list of words to use for choices. These words are separated by spaces (or other valid separator character that's set by AutoCompSetSeparator). You can retrieve the current separator with AutoCompGetSeparator . Note that the itemList must be in sorted order. Returns None.

Side effects:

- An open call-tip is cancelled (if there's one shown).
- If autocomplete's chooseSingle mode is TRUE and list does not have a separator (i.e., it's a single-choice list) then the contents of list are inserted at the current position. This will replace the entire on-screen string if AutoCompSetIgnoreCase is used to SET the ignore-case mode or will replace only the remainder of the on-screen string (after lenEntered) if the ignore-case mode is cleared (the default state).

top

AutoCompStops(characterSet)

The first 255 characters of the string object characterSet are copied to stopChars. If a character from the set of characters in stopChars is pressed by the user, then the autocomplete operation is cancelled; just as if AutoCompCancel() was invoked programmatically. Returns None.

top

UserListShow(listType,itemList)

User lists are similar to auto completion (see AutoCompShow, and see that for the meaning of itemList) but do not insert text when an item is selected, instead notifying the container with a EVT_STC_USERLISTSELECTION. The listType parameter is returned to the container and can be used to differentiate between different types of lists such as between a list of buffers and a list of keywords. The value of listType has no meaning to the STC (aside from the exception in the next paragraph); it is for the programmer's convenience. Returns None.

Notes:

1. listType must be > 0. If listType == 0, the STC will not send a EVT_STC_USERLISTSELECTION when the operation ends.
2. You can't have an autocompletion list open at the same time as a userlist.
3. The mode set by AutoCompSetChooseSingle is irrelevant.
4. Since the internal mechanism is the same one used by autocompletion, user-lists will react to fillup (AutoCompSetFillUps) and/or stop (AutoCompStops) characters.

top