wxStyledTextCtrl - Events
wxStyledTextCtrl - Events
Event Masking
| Events | ||
| | | |
Summary:
These are the events used by the STC to send notifications to your application about events within itself. You set up the issuing of these events by adding the appropriate EVT_STC_XXX in the subclass of wxStyledTextCtrl that you create or in a window that holds an attr that's an instance of an STC (although this latter approach can be more difficult to manage).
This section also shows how to set the event mask for EVT_STC_CHANGE and EVT_STC_MODIFIED.
Also see for a description of the event object passed to the target event for all of these event types. References to c++ source code can be found in the wxWindows source code under the contrib/src/stc subdirectory structure.
Finally, since the STC is a subclass of wxControl, which itself is a subclass of wxWindow, wxEvtHandler, and wxObject, other event handlers (EVT_***) are useful as well. For the STC, the following events are among those that are the most useful:
- EVT_KEY_DOWN : grab keystrokes before they get to the STC for calltips, autocompletion, and other processing. Be sure to use event.Skip() if you don't consume the keystroke and want it to go to the STC.
- EVT_CHAR : handy for autocompletion and calltips. Note that if you use EVT_KEY_DOWN and do not end it with event.Skip() then the EVT_CHAR won't occur. You usually want to end this in event.Skip(), but not always.
- EVT_RIGHT_DOWN : use to popup a menu. Be sure to use first!
Event Masking
SetModEventMask(mask)
GetModEventMask()
You can control what types of modifications will fire a EVT_STC_CHANGE and EVT_STC_MODIFIED event with the SetModEventMask(mask) command. The mask parameter is an ORing of (uaually at least two) of the mask values from the list below. Returns None.
GetModEventMask will return the mask value.
Mask Values
wxSTC_MOD_INSERTTEXTwxSTC_MOD_DELETETEXTwxSTC_MOD_CHANGESTYLEwxSTC_MOD_CHANGEFOLDwxSTC_PERFORMED_USER (performed by user)wxSTC_PERFORMED_UNDO (performed during undo)wxSTC_PERFORMED_REDO (performed during redo)wxSTC_LASTSTEPINUNDOREDOwxSTC_MOD_CHANGEMARKERwxSTC_MOD_BEFOREINSERTwxSTC_MOD_BEFOREDELETEwxSTC_MODEVENTMASKALL
Note: For the MOD and PERFORMED flag bits you need to set at least one bit from each group; for example:
wxSTC_MOD_DELETETEXT | wxSTC_PERFORMED_USER
Using wxSTC_MOD_DELETETEXT by itself would be incorrect.
Events
EVT_STC_CHANGE(win, id, func)
EVT_STC_CHANGE is sent to your application whenever a change is made to the text of the document, except for style changes, which are ignored.
You can control what types of modifications will fire a EVT_STC_CHANGE event with the command.
The event mask is set to enable ALL sources (SC_MODEVENTMASKALL) when the STC is initialized. See .
Important! No modifications may be performed while servicing this event!!
No special attributes are set by this event. You're only aware that a change occurred.
EVT_STC_CHARADDED(win, id, func)
This event occurs when a character is added. The wxStyledTextEvent.GetKey() method may be used to retrieve the character. Note that the value returned by GetKey may actually be a multi-byte characters See Editor.cxx, specifically Editor::AddCharUTF. Also, in the case of an EOL, the value returned by GetKey may be part of a two-character EOL like \r\n. In this case, multiple notifications are sent. See Editor.cxx: Editor::NewLine()
EVT_STC_DO_DROP(win, id, func)
This event is sent in response to a text drop as part of a drag-n-drop where the STC is the drop destination. The STC sets a drop target for itself when it's instantiated and the text drop is translated into a EVT_STC_DO DROP event that you can handle if you wish to change some characteristic of the drop. The attributes available are: x, y, position, dragText, and dragResult. You may change dragResult, position, and dragText.
EVT_STC_DOUBLECLICK(win, id, func)
This event is sent when a double-click occurs. No special information is provided.
EVT_STC_DRAG_OVER(win, id, func)
This event is called when the mouse is being dragged over the drop target. The attributes available are: x, y, position, and dragResult. You may change dragResult.
EVT_STC_DWELLEND(win, id, func)
The DWELLEND event is sent after a DWELLSTART and the mouse is moved or other activity such as a keypress indicates that the dwell is over.
EVT_STC_DWELLSTART(win, id, func)
The DWELLSTART event is sent when the mouse has not moved in the amount of time defined by wxStyledTextCtrl.SetMouseDwellTime(). This method is used to set the time (in milliseconds) that the mouse must not move in order to fire a DWELLSTART event. If set to SC_TIME_FOREVER (which is the default) then no dwell events are generated.
Note: SC_TIME_FOREVER is not defined in wxPython. Its value is: 10000000.
EVT_STC_KEY(win, id, func)
The Scintilla documentation says:
Reports all keys pressed. Used on GTK+ because of some problems with keyboard focus. Not sent by Windows version.
As far as this writer can tell, this means that this event, although technically available thru wxWindows, will not actually ever occur.
EVT_STC_MACRORECORD(win, id, func)
This event lets you know that some operation has occurred so that you can record it if you wish to provide a macro-recording facility. The attributes message, wParam and lParam are available. See Editor.cxx: Editor::NotifyMacroRecord to see which messages are passed thru to the event.
EVT_STC_MARGINCLICK(win, id, func)
This event is indicates that an active margin has been clicked. The available attributes are: modifiers (GetAlt, GetShift, GetCtrl), position (always at the start of the line that the mouse was on; i.e., the column will be 0), and margin (the margin number that was clicked). Note that if a margin is clicked by isn't active then no event will occur.
EVT_STC_MODIFIED(win, id, func)
EVT_STC_MODIFIED is sent to your application whenever a change is made to the text of the document, including style changes.
You can control what types of modifications will fire a EVT_STC_MODIFIED event with the command.
The event mask is set to enable ALL sources (SC_MODEVENTMASKALL) when the STC is initialized. See .
Important! No modifications may be performed while servicing this event!!
Attributes set by this event are: position, modificationType (which will be one of the modifications selected by SetModEventMask), text, length, linesAdded, line, foldLevelNow, and foldLevelPrev.
EVT_STC_NEEDSHOWN(win, id, func)
This event occurs when lines that are hidden should be made visible. An example of where this may be needed is if the end of line of a contracted fold point is deleted.
This message is sent to the container in case it wants to make the line visible in some unusual way such as making the whole document visible. Most containers will just ensure each line in the range is visible by calling SCI_ENSUREVISIBLE.
Attributes set by this event are length and position.
n.b. This is copied from the Scintilla documentation. Author unsure how to use it.
EVT_STC_PAINTED(win, id, func)
This event occurs at the end of Editor.cxx: Editor:Paint(), after all Painting is complete. The Scintilla dox say:
Useful when you want to update some other widgets based on a change in Scintilla, but want to have the paint occur first to appear more responsive.
No special attributes available, you only know that a paint operation has occurred.
EVT_STC_POSCHANGED(win, id, func)
This event occurs when the position within the document is changed. The attribute position is set.
EVT_STC_ROMODIFYATTEMPT(win, id, func)
This event is sent when there's an attempt to modify a read-only Document. There's no special information for this event.
EVT_STC_SAVEPOINTLEFT(win, id, func)
EVT_STC_SAVEPOINTREACHED(win, id, func)
From the Scintilla dox:
Sent to the container when the savepoint is entered or left, allowing the container to display a dirty indicator and change its menus. The container tells Scintilla where the save point is by sending the SCI_SETSAVEPOINT message. This is usually done when the file is saved or loaded. As Scintilla performs undo and redo operations, it will notify the container that it has entered or left the save point, allowing the container to know if the file should be considered dirty or not.
There's no special information for this event.
EVT_STC_START_DRAG(win, id, func)
This event is sent when a drag operation begins with the STC as the source of the drag (unlike ). The attributes dragText, dragAllowMove, and position are set. You may modify the dragAllowMove parameter (see and , and dragText.
EVT_STC_STYLENEEDED(win, id, func)
This event is sent when text is displayed or printed. The client can ensure that the styling information is appropriate for the visible text. Most useful for syntax styling information. The position attribute is set to the last character position where styling is needed.
EVT_STC_UPDATEUI(win, id, func)
This event occurs during Editor.cxx: Editor:Paint(), if a change has been made to the text, the styling, or the selection. Used to update any GUI elements that should change as a result. Useful for performing brace highlighting and other tasks that can be performed using background processing.
EVT_STC_URIDROPPED(win, id, func)
The Scintilla dox state:
Only on the GTK+ version. Indicates that the user has dragged a URI such as a file name or web address onto Scintilla. The container could interpret this as a request to open the file.
EVT_STC_USERLISTSELECTION(win, id, func)
Fired after an item in a user list is selected. Use wxStyledTextCtrl.GetListType and .GetText to retrieve the values of the listType and text attributes set by this event. Note: at the time of this writing (Nov 2002) GetListType will always return 0. This will probably be fixed by the time you read this, unless you are using an old version of wxPython.
EVT_STC_ZOOM(win, id, func)
This event occurs when the Zoom has been changed: usually by a human using the keyboard keys which are mapped to the ZOOMIN and ZOOMOUT functions, or by the mouse-wheeel. Can also be triggered by programmatic use of the SetZoom method.