NextPrevUpTopContentsIndex

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

:text

The text in the editor pane.

:enabled

If t the editor pane will accept input from the mouse and keyboard.

:buffer-modes

A list specifying the modes of the editor buffer.

:buffer-name

The name of the editor buffer.

:change-callback

A function designator, or nil .

:before-input-callback

A function designator, or nil .

:after-input-callback

A function designator, or nil .

:echo-area

A flag determining whether the editor pane has an Echo Area.

:fixed-fill

An integer specifying the fill length, or nil .

:line-wrap-marker

A character , or nil .

:line-wrap-face

An editor:face object, or a symbol naming a face, or nil .

:wrap-style

An integer specifying the fill length, or nil .

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

Description

The accessor editor-pane-text is provided to read and write the text in the editor buffer. The accessor editor-pane-enabled is used to enable and disable the editor (when it is disabled, it ignores all input from the mouse and keyboard).

The editor-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, pass a buffer-name that does not match any existing buffer. If buffer-name is not passed, then the editor-pane uses some existing 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 LispWorks Editor User Guide for a description of major and minor modes in the LispWorks edtor.

Note: 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. The value change-callback can be set either by:

(make-instance 'capi:editor-pane :change-callback ...)

or

(setf capi:editor-pane-change-callback)

The current value can be queried by the accessor editor-pane-change-callback .

The change-callback function must have signature:

change-callback pane point old-length new-length

pane is the editor-pane itself.

point is an editor:point object where the modification to the underlying buffer starts. point is a temporary point, and is not valid outside the scope of the change callback. For more information about editor:point objects, see "Points" in the LispWorks Editor User Guide .

old-length is the length of the affected text following point , prior to the modification.

new-length is the length of the affected text following point , after the modification has occurred.

Typical calls to the change-callback occur on insertion of text (when old-length is 0) and on deletion of text (when new-length is 0). There can be other combinations, for example, after executing the Uppercase Region editor command, change-callback be called with both old-length and new-length being the length of the region. The same is true for changing editor text properties.

The change-callback is always executed in the process of pane (as if by apply-in-pane-process).

The change-callback is permitted to modify the buffer of pane , and other editor buffers. The callback is disabled inside the dynamic scope of the call, so there are no recursive calls to the change-callback of pane . However, changes done by the callback may trigger change-callback calls on other editor-pane s, whether in the same process or in another process.

There is an example illustrating the use of change-callback in the file examples/capi/editor/change-callback.lisp .

You can use the initargs :before-input-callback and :after-input-callback to add input callbacks which are called when call-editor is called. Note that the default input-model also generates calls to call-editor, so unless you override the default input-model the input callbacks are called for all keyboard and mouse gestures (other than gestures that are processed by a non-focus completer window).

In both cases (before and after) the argument is a function that takes two arguments: the editor pane itself and the input gesture (the second argument to call-editor).

call-editor may redirect gestures to another pane. For example, gestures to an editor-pane are redirected to the echo area while it is used. In this case the before callback is called more than once for the same gesture. The after callback is called only once for each gesture, on the pane that actually processed the gesture.

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 IDE via the Editor tool's Preferences... dialog ( Styles tab, 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:

t

Normal wrapping. Display as many characters as possible in the editor-pane line.

nil

Do not wrap. Text lines that are too long are truncated.

:split-on-space

Wrapping, but attempts to split lines on spaces. When the text reaches the end of a line, the code looks backwards for space, and wraps before it.

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

Note: editor panes support GNU Emacs keys on all platforms. Addtionally on Microsoft Windows they support Windows editor keys, on Motif they support KDE/Gnome keys, and on Cocoa they support Mac OS X editor keys. Exactly one style of emulation is active at any one time for each editor pane. By default, editor panes in the Common LispWorks development environment use Emacs emulation on all platforms. By default, editor panes in delivered applications use Windows emulation on Microsoft Windows, Mac OS X editor emulation on Cocoa, and Emacs emulation on Motif. To alter the choice of emulation, see interface-keys-style or the deliver keyord :editor-style , described in the LispWorks Delivery User Guide .

Compatibility Note

In LispWorks 4.4 and previous versions, editor-pane supports only fixed-width fonts. In LispWorks 5.0 and later, variable-width fonts can also be used on Microsoft Windows and Motif. Specify the font via the :font initarg (see simple-pane).

Compatibility Note

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

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

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

Also see the examples in the directory examples/capi/editor/ .

See also

call-editor
*default-editor-pane-line-wrap-marker*
editor-pane-blink-rate
*editor-cursor-active-style*
*editor-cursor-color*
*editor-cursor-drag-style*
*editor-cursor-inactive-style*
interface-keys-style
modify-editor-pane-buffer


LispWorks CAPI Reference Manual - 17 Mar 2008

NextPrevUpTopContentsIndex