The text in the pane.
The position of the caret in the text (from 0).
The maximum number of characters allowed.
A boolean controlling whether the pane is enabled.
A function called to complete the text.
The type of arguments to callback .
A function called when the user presses
Return
.
The type of arguments to callback .
A function called when a change is made.
A function called to validate a change. Note: Implemented for Motif/Lesstif only, not MS Windows or Mac OS X.
text-input-pane-text
text-input-pane-max-characters
text-input-pane-completion-function
text-input-pane-callback
text-input-pane-confirm-change-function
text-input-pane-change-callback
text-input-pane-enabled
text-input-pane-buttons-enabled
The class
text-input-pane
provides a great deal of flexibility in its handling of the text being entered. It starts with the initial text and caret-position specified by the arguments
text
and
caret-position
respectively. It limits the number of characters entered with the
max-characters
argument (which defaults to
nil
, meaning there is no maximum). The pane is enabled or disabled according to the value of the
enabled
slot.
A
completion-function
can be specified which will get called when the completion gesture is made by the user (or pressing the
Tab
key) or when text-input-pane-complete-text is called. The
completion-function
is called with the pane and the text to complete and should return either
nil
, the completed text or a list of candidate completions. In the latter case, the CAPI will prompt the user for the completion they wish, and this will become the new text.
When the text or caret-position is changed, the callback change-callback is called with the text , the pane itself, the interface and the caret-position . The arguments that are passed to the change-callback can be altered by specifying the change-callback-type (see the callbacks class for details of possible values).
Note: the change-callback is potentially called more than once for each user gesture.
With the Motif/Lesstif implementation it is possible to check changes that the user makes to the
text-input-pane
by providing a
confirm-change-function
which gets passed the new text, the pane itself, its interface and the new caret position, and which should return non-
nil
if it is OK to make the change. If
nil
is returned, then the pane will be unaltered and a beep will be signalled to indicate that the new values were invalid.
buttons specifies toolbar buttons which appear to the right of the pane and facilitate user actions on it. This feature appears in the Common LispWorks IDE, for example the Class box of the Class Browser.
The allowed keys and values of the plist buttons are:
A boolean, default value
t
. If true, a button which calls
callback
appears.
A boolean, default value
nil
. If true, a button which calls
cancel-function
appears.
A boolean.If true, a button which calls
completion-function
appears.The default value is
t
if
completion-function
is non-
nil
, and
nil
otherwise.
A function that expects the pane as its single argument. The default is a function which sets text to the empty string.
The value is either
:horizontal
or
:vertical
.
orientation
controls the orientation of the toolbar. This is useful for multi-line-text-input-pane. The default value is
:horizontal
.
The value is
:top
,
:center
,
:centre
or
:bottom
.
adjust
controls how the buttons are adjusted vertically relative to the text input pane. This is useful for multi-line-text-input-pane. The default value is
:center
.
The value
nil
for
buttons
means there are no buttons - this is the default. When
buttons
is true the buttons appear or not according to their specified values or their default values.
The
text-input-pane-buttons-enabled
reader returns a list containing the keywords
:ok
,
:cancel
and
:completion
, one for each corresponding button (as specified by
buttons
) that is currently enabled.
The
(setf text-input-pane-buttons-enabled)
writer takes a list of keywords as described for the reader and sets the enabled state of the buttons, enabling each button if it appears in the list and disabling it otherwise. The value
t
can also be passed: this enables all the buttons.
For more than one line of input, use multi-line-text-input-pane.
The
confirm-change-function
was called
before-change-callback
in LispWorks 3.1. Both the old initarg
before-change-callback and the old accessor text-input-pane-before-change-callback are still supported, but may not be in future releases.
(capi:contain (make-instance 'capi:text-input-pane
:text "Hello world"))
(setq tip (capi:contain
(make-instance
'capi:text-input-pane
:enabled nil)))
(capi:apply-in-pane-process
tip #'(setf capi:text-input-pane-enabled) t tip)
(capi:apply-in-pane-process
tip #'(setf capi:text-input-pane-enabled) nil tip)
(capi:apply-in-pane-process
tip #'(setf capi:text-input-pane-text) "New text" tip)
(capi:contain (make-instance
'capi:text-input-pane
:text "Hello world"
:callback #'(lambda (text interface)
(capi:display-message
"Interface ~S's text: ~S"
interface text))))
There is a further example in the file
examples/capi/elements/text-input-pane.lisp
display-pane
editor-pane
multi-line-text-input-pane
text-input-choice
text-input-pane-complete-text
text-input-range
title-pane