An editor pane is an editor that has all of the functionality described in the LispWorks Guide To The Editor .
A string or
nil
.
t, nil
or
:read-only
.
A list specifying the modes of the editor buffer.
The name of the editor buffer.
A function designator, or
nil
.
A function designator, or
nil
.
A function designator, or
nil
.
A flag determining whether the editor pane has an Echo Area.
An integer specifying the fill length, or
nil
.
An
editor:face
object, or a symbol naming a face, or
nil
.
An integer specifying the fill length, or
nil
.
Changes the editor face that is used by editor-pane-default-composition-callback to display the composition string. The default value is
:default
.
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
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
.
capi:simple-pane-enabled
has the same effect when applied to an
editor-pane
.
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.
A non-empty string value of
text
specifies the initial text displayed. Otherwise an existing editor buffer is displayed. 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
LispWorks Editor User Guide
for a description of major and minor modes in the LispWorks edtor.
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 ...)
(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 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:
Normal wrapping. Display as many characters as possible in the
editor-pane
line.
Do not wrap. Text lines that are too long are truncated.
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
.
The input behaviour 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 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 LispWorks IDE 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 GTK+ and Motif. To alter the choice of emulation, see interface-keys-style or the
deliver
keyord
:editor-style
, described in the
LispWorks Delivery User Guide
.
:drawing-mode
controls anti-aliasing of the text displayed in an
editor-pane
on Microsoft Windows and GTK+.
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.
: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
.
:use-native-input-method
or call set-default-use-native-input-method.
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 later, variable-width fonts can also be used on Microsoft Windows, GTK+ and Motif. Specify the font via the
:font
initarg (see simple-pane).
The
:wrap-style
initarg supersedes
editor:set-window-split-on-space
, which is deprecated.
(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))
This example makes an
editor-pane
with no input behavior:
(capi:contain
(make-instance 'capi:editor-pane :input-model nil))
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)))
(setf (capi:output-pane-input-model ep)
(list* '((:button-1 :press) foo)
(capi:output-pane-input-model ep)))
(capi:contain ep)))
Also see the examples in the directory
examples/capi/editor/
.
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
output-pane
set-default-use-native-input-method
CAPI Reference Manual - 15 Dec 2011