1 CAPI Reference Entries

text-input-pane

Summary

The classtext-input-pane is a pane for entering a single line of text.

Superclasses

titled-pane

Subclasses

password-pane

Slots

text

The text in the pane.

caret-position

The position of the caret in the text (from 0).

max-characters

The maximum number of characters allowed.

enabled

Is the text-input-pane enabled?

completion-function

A function called when the user completes the input by pressing tab.

callback-type

The type of arguments to the callback.

callback

A function called when the user presses Return.

change-callback-type

The type of arguments to the callback.

change-callback

A function called when a change is made.

confirm-change-function

A function called to validate a change.

Accessors

text-input-pane-text
text-input-pane-caret-position
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

Description

The classtext-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:text and:caret-position respectively, and limits the number of characters entered with the:max-characters keyword (which defaults tonil, meaning there is no maximum). The pane can be enabled and disabled with the accessortext-input-pane-enabled.

Acompletion-function can be specified which will get called when the completion gesture is made by the user (or pressing the Tab key). The function is called with the pane and the text to complete and should return eithernil, the completed text or a list of possible completions. In the latter case, the CAPI will prompt the user for the selection they wish and this will become the new text.

When the text or caret-position is changed, the callbackchange-callback is called with the text, the pane itself, the interface and the caret position. The arguments that are passed to the callback can be specified with thechange-callback-type.

It is possible to check changes that the user makes to the text input pane by providing aconfirm-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 okay to make the change. Ifnil is returned, then the pane will be unaltered (and a beep will be signalled indicating that the new values were invalid.

Compatibility Note

Theconfirm-change-function was calledbefore-change-callback in LispWorks 3.1. Both the old initarg and the old accessor are still supported, but may not be in future releases.

Examples

(capi:contain (make-instance 'capi:text-input-pane
                             :text "Hello world"))

(setq text-input-pane (capi:contain
                       (make-instance 
                        'capi:text-input-pane
                        :enabled nil)))

(setf (capi:text-input-pane-enabled text-input-pane) t)
(setf (capi:text-input-pane-enabled text-input-pane)
      nil)
(setf (capi:text-input-pane-text text-input-pane)
      "New text")

(capi:contain (make-instance 'capi:text-input-pane
                             :max-characters 10))

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

Example File

capi/elements/text-input-pane.lisp

See Also

editor-pane
title-pane
display-pane

Generated with Harlequin WebMaker