editor-pane Class

Summary

An editor pane is an editor that has all of the functionality described in the LispWorks Guide To The Editor.

Package

capi

Superclasses

output-pane

Subclasses

interactive-pane
collector-pane

Initargs

Accessors

editor-pane-text
editor-pane-change-callback
editor-pane-enabled
editor-pane-fixed-fill
editor-pane-line-wrap-marker
editor-pane-line-wrap-face
editor-pane-wrap-style
editor-pane-composition-face

Description

The class editor-pane is an editor that has all of the functionality described in the LispWorks Guide To The Editor.

enabled controls how user input affects the editor-pane. If enabled is nil, all input from the mouse and keyboard is ignored. When enabled is t, all input is processed according to the input-model. When enabled is :read-only, input to the pane by keyboard or mouse gestures cannot change the text. More accurately, input via the default input-model of editor-pane cannot change the text. The Cut and Paste menu entries are also disabled. When a user tries to change the text, the operation quietly aborts. Programmatic modifications of the text are still allowed (see Notes below for more detail).

The enabled state can be set by the accessor editor-pane-enabled. simple-pane-enabled has the same effect when applied to an editor-pane.

The pane stores text in buffers which are uniquely named, and so to create an editor-pane using an existing buffer you should pass the buffer-name. To create an editor-pane with a new buffer, use either flag or a non-empty text string or a buffer-name that does not match any existing buffer.

buffer-name can also be an editor buffer naming itself.

buffer-name can also be the keyword :temp. In this case the editor-pane will be created with a temporary buffer that will go away when the editor-pane is Garbage Collected (it is created by editor:make-buffer with :temporary t).

A non-empty string value of text specifies the initial text displayed and forces the creation of a new buffer. The accessor editor-pane-text is provided to read and write the text in the editor buffer.

buffer-modes allows you to specify the initial major mode and minor modes of the editor-pane's buffer. It should be a list of the form (major-mode-name . minor-mode-names). See the Editor User Guide for a description of major and minor modes in the LispWorks editor. buffer-modes is used only when the CAPI creates the buffer, and not when it reuses a buffer.

If echo-area is non-nil. then an Echo Area is added. echo-area defaults to nil.

If fixed-fill is non-nil, the editor pane tries to form lines of length close to, but no more than, fixed-fill. It does this by forcing line breaks at spaces between words. fixed-fill defaults to nil.

The cursor in an editor-pane blinks on and off by the mechanism described in editor-pane-blink-rate.

change-callback, if non-nil, should be a function which is called whenever the editor buffer under the editor-pane changes. For the details see 3.5.3.1 Editor pane callbacks.

before-input-callback and after-input-callback, if non-nil, should be functions which are called when call-editor is called. For the details see 3.5.3.1 Editor pane callbacks.

line-wrap-marker specifies the marker to display at the end of a line that is wrapped to the next line, or truncated if wrap-style is nil. The value must be a character, or nil (which is interpreted as #\Space). The default value is the value of *default-editor-pane-line-wrap-marker*. The value can be read by editor-pane-line-wrap-marker.

line-wrap-face specifies a face to use when displaying the line-wrap-marker. The argument can be nil, an editor:face object (the result of a call to editor:make-face), or a symbol naming a face (that is, the first argument to editor:make-face).

The default value of line-wrap-face is an internal symbol naming a face. The value can be accessed by editor-pane-line-wrap-face. The default face can be modified in the LispWorks IDE via Tools > Preferences... > Environment > Styles > Colors and Attributes, style name Line Wrap Marker.

wrap-style defines the wrapping of text lines that cannot be displayed in one line of the editor-pane. The argument can be one of:

The default value of wrap-style is t and the value can accessed by editor-pane-wrap-style.

The input behavior of an editor-pane is determined by its input-model (inherited from output-pane). By default, an editor-pane has an input-model that implements the functionality of the Editor tool in the LispWorks IDE, and always does it via call-editor. You can replace this behavior by supplying :input-model when you call make-instance or by (setf capi:output-pane-input-model), though this has an effect only if called before the pane is displayed. It is possible to achieve a minor modification to the default input behavior by prepending the modification (see the example below). Note that functions performing editor operations must do this via call-editor.

Editor panes support GNU Emacs keys on all platforms. Additionally on Microsoft Windows they support Windows editor keys, on GTK+ and Motif they support KDE/Gnome keys, and on Cocoa they support macOS editor keys. Exactly one style of emulation is active at any one time for each editor pane. By default, editor panes in the LispWorks IDE use Emacs emulation on all platforms. By default, editor panes in delivered applications use Windows emulation on Microsoft Windows, macOS editor emulation on Cocoa, and Emacs emulation on GTK+ and Motif. To alter the choice of emulation, see interface-keys-style or the deliver keyword :editor-style, described in the Delivery User Guide.

Notes

1. The output-pane initarg :drawing-mode controls anti-aliasing of the text displayed in an editor-pane on Microsoft Windows and GTK+.
2. For an editor-pane with enabled :read-only, Editor commands (predefined, and user-defined by editor:defcommand) may or may not be able to change the text, depending on how they are called. When executed by a key sequence they cannot change the text directly. However Editor commands can also be called via editor:process-character or call-editor, and then are programmatic input and so can change the text.
3. The effect of enabled :read-only is on the editor-pane. It does not affect the underlying Editor buffer, which can still be modified from other panes. The buffer that is displayed can be changed, and this does not affect the enabled state of the editor-pane.
4. Except when actually editing a file, it is normally best to use a temporary buffer when using an editor-pane, supplying :buffer-name :temp (or :buffer-name tb, where tb is created by editor:make-buffer with :temporary t). This prevents auto-saving and sharing buffers unintentionally.
5. To control whether the native input method is used to interpret keyboard input, you can supply the output-pane initarg :use-native-input-method or call set-default-use-native-input-method.
6. The default value of composition-callback (see output-pane) is editor-pane-default-composition-callback.

Compatibility note

In LispWorks 4.4 and previous versions editor-pane supports only fixed-width fonts.

On Cocoa, editor-pane supports only fixed-width fonts in LispWorks 6.1 and earlier versions.

In LispWorks 6.1 and later versions, variable-width fonts can be used on Microsoft Windows, GTK+ and Motif. In LispWorks 7.0 and later, variable-width fonts can also be used on Cocoa. Specify the font via the :font initarg (see simple-pane).

The initarg :wrap-style supersedes editor:set-window-split-on-space, which is deprecated.

Examples

(capi:contain (make-instance 'capi:editor-pane
                             :text "Hello world"
                             :buffer-name :temp))
 
(setq ed (capi:contain
          (make-instance 'capi:editor-pane
                         :text "Hello world"
                         :enabled nil
                         :buffer-name :temp)))

Note that you cannot type into the editor pane.

(capi:apply-in-pane-process 
  ed #'(setf capi:editor-pane-enabled) t ed)

Now you can enter text into the editor pane interactively.

You can also change the text programmatically:

(capi:apply-in-pane-process
  ed #'(setf capi:editor-pane-text) "New text" ed)

In this example the callback modifies the buffer in the correct editor context so you that see the editor update immediately:

(capi:define-interface updating-editor ()
  ()
  (:panes
   (numbers capi:list-panel
            :items '(1 2 3)
            :selection-callback 'update-editor
            :callback-type :interface
            :visible-min-height '(:character 3))
   (editor capi:editor-pane
           :text 
           "Select numbers in the list above."
           :visible-min-width
           (list :character 35)
           :buffer-name :temp)))
 
(defun update-editor (interface)
  (with-slots (numbers editor) interface
    (editor:process-character 
     (list #'(setf capi:editor-pane-text)
           (format nil "~R" 
                   (capi:choice-selected-item numbers))
           editor)
     (capi:editor-window editor))))
 
(capi:display (make-instance 'updating-editor))

This example illustrates the use of buffer-modes to specify a major mode:

(defclass my-lisp-editor (capi:editor-pane) ()
  (:default-initargs
   :buffer-modes '("Lisp")
   :echo-area t
   :text
   ";; Lisp mode functionality such as command bindings and
;; parenthesis balancing work in this window.
 
(list 1 2 3)
"
   :visible-min-width '(:character 60)
   :name "My Lisp Editor Pane"))
 
(capi:define-interface my-lisp-editor-interface ()
  ()
  (:panes
   (ed
    my-lisp-editor
    ))
  (:default-initargs
   :title "My Lisp Editor Interface"))
 
;; Ensure Emacs-like bindings regardless of platform
(defmethod capi:interface-keys-style 
           ((self my-lisp-editor-interface))
  :emacs)
 
(capi:display 
 (make-instance 'my-lisp-editor-interface))

This example makes an editor-pane with no input behavior:

(capi:contain
 (make-instance 'capi:editor-pane
                :input-model nil
                :buffer-name :temp))

This example makes an editor-pane with the default input behavior, except that pressing the mouse button displays a message rather than setting the point. It then displays the pane:

(progn
  (defun foo (self x y)
    (capi:display-message "Button-1 Press at ~a/~a"
                          x y))
  (let ((ep (make-instance 'capi:editor-pane
                           :buffer-name :temp)))
    (setf (capi:output-pane-input-model ep)
          (list* '((:button-1 :press) foo)
                 (capi:output-pane-input-model ep)))
    (capi:contain ep)))

Also see these examples:

(example-edit-file "capi/editor/")

See also

call-editor
*default-editor-pane-line-wrap-marker*
editor-pane-blink-rate
*editor-cursor-active-style*
*editor-cursor-inactive-style*
*editor-cursor-color*
*editor-cursor-drag-style*
*editor-cursor-inactive-style*
interface-keys-style
modify-editor-pane-buffer
output-pane
set-default-use-native-input-method
3.5 Displaying and entering text
10.6 In-place completion