Class

Summary

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

Superclasses

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

A completion-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 either nil , 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 callback change-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 the change-callback-type .

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 okay to make the change. If nil is returned, then the pane will be unaltered (and a beep will be signalled indicating that the new values were invalid.

Compatibility Note

The confirm-change-function was called before-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)

                       :process 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))))

See also

editor-pane
title-pane
display-pane
text-input-range
text-input-choice