Notifications ============= Notifications are sent (fired) from the Scintilla control to its container when an event has occurred that may interest the container. style-needed ------------ .. function:: callback(widget, position) If you used :meth:`gtkscintilla.Scintilla.set_lexer` (SCLEX_CONTAINER) to make the container act as the lexer, you will receive this notification when Scintilla is about to display or print text that requires styling. You are required to style the text from the line that contains the position returned by :meth:`gtkscintilla.Scintilla.get_end_styled` up to the position passed to the callback. Symbolically, you need code of the form: >>> startPos = s.get_end_styled() >>> lineNumber = s.line_from_position(startPos) >>> startPos = s.position_from_line(lineNumber) >>> MyStyleRoutine(startPos, position); char-added ---------- .. function:: callback(widget, char) This is sent when the user types an ordinary text character (as opposed to a command character) that is entered into the text. The container can use this to decide to display a call tip or an auto completion list. This notification is sent before the character has been styled so processing that depends on styling should instead be performed in the *update-ui* notification. save-point-reached ------------------ save-point-left --------------- .. function:: callback(widget) Sent to the container when the save point is entered or left, allowing the container to display a "document dirty" indicator and change its menus. .. seealso:: :meth:`gtkscintilla.Scintilla.set_save_point` , :meth:`gtkscintilla.Scintilla.get_modify` modify-attempt-ro ----------------- .. function:: callback(widget) When in read-only mode, this notification is sent to the container if the user tries to change the text. This can be used to check the document out of a version control system. You can set the read-only state of a document with :meth:`gtkscintilla.Scintilla.set_readonly` . key --- .. function:: callback(widget, ch, modifiers) Reports all keys pressed but not consumed by Scintilla. Used on GTK+ because of some problems with keyboard focus. *ch* holds the key code and *modifiers* holds the modifiers. This notification is sent if the modifiers include SCMOD_ALT or SCMOD_CTRL and the key code is less than 256. double-click ------------ .. function:: callback(widget) The mouse button was double clicked in editor. The position field is set to the text position of the double click and the line field is set to the line of the double click. update-ui --------- .. function:: callback(widget) Either the text or styling of the document has changed or the selection range has changed. Now would be a good time to update any container UI elements that depend on document or view state. This was previously called *check-brace* because a common use is to check whether the caret is next to a brace and set highlights on this brace and its corresponding matching brace. modified -------- TODO macro-record ------------ .. function:: callback(widget, message, wParam, lParam) The :meth:`gtkscintilla.Scintilla.start_record` and :meth:`gtkscintilla.Scintilla.stop_record` method enable and disable macro recording. When enabled, each time a recordable change occurs, the *macrp-record* notification is sent to the container. It is up to the container to record the action. The parameter passed are a lower level representation of scintilla methods. :param message: The SCI_\* message that caused the notification. :param wParam: The value of wParam in the SCI_\* message. :param lParam: The value of lParam in the SCI_\* message. margin-click ------------ .. function:: callback(widget, modifiers, position, margin) This notification tells the container that the mouse was clicked inside a margin that was marked as sensitive (see :meth:`gtkscintilla.Scintilla.set_margin`). This can be used to perform folding or to place breakpoints. The following fields are used: :param modifiers: The appropriate combination of SCI_SHIFT, SCI_CTRL and SCI_ALT to indicate the keys that were held down at the time of the margin click. :param position: The position of the start of the line in the document that corresponds to the margin click. :param margin: The margin number that was clicked. need-shown ---------- .. function:: callback(widget, position, length) Scintilla has determined that a range of lines that is currently invisible 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 :meth:`gtkscintilla.Scintilla.ensure_visible` . The position and length fields of notification indicate the range of the document that should be made visible. The container code will be similar to the following code skeleton:: firstLine = s.line_from_position(position) lastLine = s.line_from_position(position+length-1) for line = lineStart to lineEnd do s.ensure_visible(line) next painted ------- .. function:: callback(widget) Painting has just been done. 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. user-list-selection ------------------- .. function:: callback(widget, wParam, text) The user has selected an item in a user list. :param wParam: This is set to the listType parameter from the S:meth:`gtkscintilla.Scintilla.user_list_show` method that initiated the list. :param text: The text of the selection. uri-dropped ----------- .. function:: callback(widget, text) 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. dwell-start ----------- dwell-end --------- .. function:: callback(widget, position) dwell-start is generated when the user keeps the mouse in one position for the dwell period, dwell-end is generated after a SCN_DWELLSTART and the mouse is moved or other activity such as key press indicates the dwell is over :param position: This is the nearest position in the document to the position where the mouse pointer was lingering. zoom ---- .. function:: callback(widget) This notification is generated when the user zooms the display using the keyboard or the :meth:`gtkscintilla.Scintilla.set_zoom` method is called. This notification can be used to recalculate positions, such as the width of the line number margin to maintain sizes in terms of characters rather than pixels. hotspot-click ------------- hotspot-doubleclick ------------------- .. function:: callback(widget, position, modifiers) These notifications are generated when the user clicks or double clicks on text that is in a style with the hotspot attribute set. This notification can be used to link to variable definitions or web pages. The *position* field is set the text position of the click or double click and the modifiers field set to the key modifiers held down in a similar manner to *key*. indicator-click --------------- indicator-release ----------------- .. function:: callback(widget, position, modifiers) These notifications are generated when the user clicks or releases the mouse on text that has an indicator. The position field is set the text position of the click or double click and the modifiers field set to the key modifiers held down in a similar manner to *key*. calltip-click ------------- .. function:: callback(widget, position, text) This notification is generated when the user clicks on a calltip. This notification can be used to display the next function prototype when a function name is overloaded with different arguments. The position field is set to 1 if the click is in an up arrow, 2 if in a down arrow, and 0 if elsewhere. auto-c-selection ---------------- .. function:: callback(widget, position, text) The user has selected an item in an autocompletion list. The notification is sent before the selection is inserted. Automatic insertion can be cancelled by sending :meth:`gtkscintilla.Scintilla.auto_c_cancel` before returning from the notification. :param position: The start position of the word being completed. :param text: The text of the selection. auto-c-cancelled ---------------- .. function:: callback(widget) The user has cancelled an autocompletion list. auto-c-char-deleted ------------------- .. function:: callback(widget) The user deleted a character while autocompletion list was active.