wxStyledTextCtrl - Events  

Copyright and License information  Home

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

wxStyledTextCtrl - Events

Event Masking

• GetModEventMask
• SetModEventMask

Summary:

These are the events used by the STC to send notifications to your application about events within itself. You set up the issuing ofthese events by adding the appropriateEVT_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 (althoughthis 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 wxStyledTextEvent 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 sourcecode 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 UsePopUp(0) 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 theSetModEventMask(mask) command. The mask parameter is an ORing of (uaually at least two) of the maskvalues 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 SetModEventMask command.

The event mask is set to enable ALL sources (SC_MODEVENTMASKALL) when the STC is initialized. See event mask constants.

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.

top

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()

top

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. top

EVT_STC_DOUBLECLICK(win, id, func)

This event is sent when a double-click occurs. No special information is provided.

top

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.

top

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.

top

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.

top

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.

top

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.

top

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.

top

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 SetModEventMask command.

The event mask is set to enable ALL sources (SC_MODEVENTMASKALL) when the STC is initialized. See event mask constants.

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.

top

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.

top

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.

top

EVT_STC_POSCHANGED(win, id, func)

This event occurs when the position within the document is changed. The attribute position is set.

top

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.

top

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.

top

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 EVT_STC_DO_DROP). The attributes dragText, dragAllowMove, and position are set. You may modify the dragAllowMove parameter (see SetDragAllowMove and GetDragAllowMove, and dragText.

top

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.

top

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.

top

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. 

top

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.

top

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.

top