text-input-pane Class

Summary

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

Package

capi

Superclasses

titled-object
simple-pane

Subclasses

multi-line-text-input-pane
password-pane
text-input-choice

Initargs

Accessors

text-input-pane-text
text-input-pane-max-characters
text-input-pane-enabled
text-input-pane-callback
text-input-pane-confirm-change-function
text-input-pane-change-callback
text-input-pane-completion-function
text-input-pane-navigation-callback
text-input-pane-editing-callback
text-input-pane-buttons-enabled

Readers

text-input-pane-caret-position

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

If enabled is nil, the pane is disabled. If enabled is :read-only, then the pane shows the text and allows it to be selected without it being editable. In this case the visual appearance varies between window systems, but often the text can be copied and the caret position altered. If enabled is any other true value, then the pane is fully enabled. The default value of enabled is t.

You can programmatically get and set the selection and caret position by set-text-input-pane-selection, text-input-pane-selected-text, text-input-pane-selection and text-input-pane-caret-position. You can programmatically perform standard edit operations by using text-input-pane-paste, text-input-pane-copy, text-input-pane-cut and text-input-pane-delete. You can programmatically invoke the completion functions by text-input-pane-complete-text and text-input-pane-in-place-complete.

For more than one line of input, use multi-line-text-input-pane.

Description: Callbacks

callback, if non-nil, is called when the user presses Return, unless navigation-callback is non-nil, in which case navigation-callback is called instead. If the pane has "recent-items" (implemented only on Cocoa) then the timing of calls to callback is modified: see the discussion of recent-items below for the details.

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

With the Motif 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.

gesture-callbacks provides callbacks to perform for specific keyboard gestures. Each gesture must be an object that sys:coerce-to-gesture-spec can coerce to a sys:gesture-spec. Each callback can be a callable (symbol or function) which takes one argument, the pane. Alternatively each callback can be a list of the form (function arguments). Note that in this case, the pane itself is not automatically passed to the function amongst arguments.

When the user enters a gesture that matches gesture in any pair amongst gesture-callbacks, the callback is executed and the gesture is not processed any more.

text-change-callback is a change callback (see change-callback) that is called only when the text in the pane changes. In contrast, change-callback is also called when the caret moves. If both text-change-callback and change-callback are supplied, only text-change-callback is invoked.

Notes: Callbacks

1. change-callback is potentially called more than once for each user gesture.
2. The interaction of in-place completion is implemented using gesture-callbacks. Gestures which you define explicitly by gesture-callbacks override the gestures which are defined implicitly by the in-place completion mechanism.
3. For gestures that change the text, text-change-callback is probably better than gesture-callbacks.

Description: Completion

A completion-function can be specified which will get called when the completion gesture is made by the user (by pressing the Tab key) or when text-input-pane-complete-text is called. The function should have signature:

completion-function pane string => completions, start, end

where pane is the text-input-pane itself and string is the string to complete. When completion is invoked completion-function is called with pane and a string containing the text of pane to the left of the cursor.

The completion-function is called with the pane and the text to complete and should return either nil, the completed text as a string or a list completions 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. In addition, the completion-function can return two more values, start and end, which specify a range in the text that is to be replaced if the completion is successful.

When complete-do-action is non-nil, completion of the text in the pane automatically invokes callback (if callback is non-nil). The default value of complete-do-action is nil.

in-place-completion-function tells the pane to do in-place completion and specifies the function to use. The function should have signature:

in-place-completion-function pane string => completions, start, end

where pane is the text-input-pane itself and string is the string to complete. When in-place completion is invoked in-place-completion-function is called with pane and a string containing the text of pane to the left of the cursor.

completions needs to be a list of strings that are possible completions, a single string that is a unique completion, or the symbol :destroy. :destroy means that the in-place completion needs to stop and close the in-place window. In addition, the completion function can return two more values, start and end, which specify a range in the text that is to be replaced if the completion is successful. The function is called repeatedly whenever there is a change to the text that should be completed.

The default value of in-place-completion-function is nil.

file-completion, if non-nil, tells the pane to do file completion using an in-place window. The user invokes In-place completion or file completion by pressing the Up or Down key. See 10.6 In-place completion for more details of the user interaction.

If file-completion is a pathname designator, its location is used as the root path for the completion.

The default value of file-completion is nil.

in-place-filter takes effect only when either in-place-completion-function or file-completion is non-nil. If in-place-filter is t then the in-place window can have a filter. Note that the filter needs to requested by a user gesture. Control+Return is the default in-place filter gesture. The default value of in-place-filter is t.

directories-only takes effect only if file-completion is used. If directories-only is t then in-place completion shows only directories. The default value of directories-only is nil.

ignore-file-suffices takes effect only if file-completion is used. It tells in-place completion to ignore files whose file namestring (the result of cl:file-namestring) ends with any of the strings in the list ignore-file-suffices. If ignore-file-suffices is :default, then completion uses the default value, which is the value of editor:*ignorable-file-suffices* (see config/a-dot-lispworks.lisp).

Notes: Completion

1. If in-place-completion-function needs some dynamic information, it can put it in a property of the pane (using capi-object-property).
2. For dynamic control over whether there is an in-place completion or not, specify an in-place-completion-function that simply returns the keyword :destroy when there should be no completion.
3. The initarg :file-completion overrides :in-place-completion-function.
4. The in-place completion mechanism uses gesture-callbacks to implement the functionality.
5. :in-place-filter can be used to specify that the in-place window can have a filter.
6. The behavior of in-place completion is somewhat different from other completion.
7. The initargs :directories-only and :ignore-file-suffices can be used to change the behavior of the completion.

Description: Editing and navigation callbacks

navigation-callback, if non-nil, is a function that will be called when certain navigation gestures are used in the text-input-pane. The function is called with two arguments, the pane itself, and one of the following keywords:

When navigation-callback is non-nil, it is called instead of callback when Return is pressed. callback is still called via an OK button if there is one (see buttons below).

navigation-callback is implemented only on Microsoft Windows and Cocoa.

editing-callback, if non-nil, is a function of two arguments:

editing-callback pane type

pane is the text-input-pane and type is a keyword. editing-callback is called with type :start when the user starts editing and type :end when the user stops editing. In general, this occurs when the focus changes, but on Cocoa type :start is passed when the first change is made to the text.

Notes: Editing and navigation callbacks

Enter is the key usually found on the numeric keypad.

Description: Buttons

buttons specifies toolbar buttons which appear next to the pane and facilitate user actions on it. It also specifies the position of the buttons relative to the pane. This feature appears in the LispWorks IDE, for example the Class box of the Class Browser.

The allowed keys and values of the plist buttons are:

(apply function pane arguments)

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.

All of the button plists (for :ok, :cancel, :help and so on) can contain the following keys and values in addition to those mentioned above:

The reader text-input-pane-buttons-enabled returns a list containing keywords such as:ok, :cancel and :completion, one for each corresponding button (as specified by buttons) that is currently enabled.

The writer (setf text-input-pane-buttons-enabled) 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.

Description: Search field and recent items

If search-field is a string and recent-items-name is not supplied, then the value search-field is used as the name. See the discussion of recent-items below.

If any of search-field, recent-items or recent-items-name is supplied and is non-nil, the pane uses NSSearchField, and also has "recent items". An NSSearchField has a different appearance from text-input-pane, can display recent items menu, and its input behavior is a little different too.

If recent-items is non-nil, it must be a list of strings, or t. When it is a list of strings, it specifies the initial list of "recent items". When it is t, it simply specifies that the pane should handle recent items.

If recent-items-name is non-nil, it should be a string. The string specifies the autosave name of the pane. When a pane has an autosave name, Cocoa remembers the list of recent items for pane with the same autosave name and same application. The record persists between invocations of the application.

If recent-items-name is not supplied or is nil, and search-field is a string, it is used instead as the name.

The maximum number of recent items defaults to 50 and can be controlled by the initarg value maximum-recent-items. The value 0 can be used to switch off the "recent items" feature, including the menu.

The recent items list can be read and set by text-input-pane-recent-items, or modified by any of text-input-pane-replace-recent-items, text-input-pane-delete-recent-items, text-input-pane-append-recent-items, text-input-pane-prepend-recent-items and text-input-pane-set-recent-items.

The input behavior of text-input-pane with "recent items" is the same is that of other text-input-panes except for the timing of calls to callback. Note that this refers to the function that is passed with the initarg :callback, so change-callback is not affected.

By default, each time the user types a character it causes a scheduling of callback some short time later. If the user types another character before the callback, it is re-scheduled later. The result is that as long as the user types, there are no callbacks, but once the user stops a callback is generated.

The behavior of callback can be controlled by the initarg value recent-items-mode, which can be one of :explicit, :delayed or :immediate. :explicit gives the same behavior as a normal text-input-pane, :delayed is the default described above, and :immediate means doing a callback immediately after each character. In addition, when the user selects an item from the recent items menu or clicks its Cancel button, the callback is called. In the case of the Cancel button, the string would be empty.

Examples

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

This example uses a plist value for the buttons key :cancel to specify that the Cancel button is initially disabled:

(capi:contain 
 (make-instance 'capi:text-input-pane 
                :buttons 
                '(:ok t :cancel (:enabled nil))))

This example shows how to specify a Help button which displays a help message:

(defvar *help-message* "A long help message.")
 
(capi:contain
 (make-instance 'capi:text-input-pane
                :buttons 
                `(:help 
                  (:title "help window"
                   :message ,*help-message*))))

This example shows to specify a button which prompts for a directory:

(capi:contain 
 (make-instance 'capi:text-input-pane
                :buttons 
                '(:browse-file (:directory t 
                                :image :std-file-open)
                  :ok nil))
  :title "Enter a directory path")

This example illustrates the use of gesture-callbacks. Ctrl+e moves the cursor to the end of the input, Ctrl+a moves it to the start, and Ctrl+6 does something else:

(capi:contain
 (make-instance
  'capi:text-input-pane
  :gesture-callbacks
  (list 
   (cons
    "Ctrl-e"
    #'(lambda (tip)
        (setf (capi:text-input-pane-caret-position tip)
              (length (capi:text-input-pane-text tip)))))
   (cons
    "Ctrl-a"
    #'(lambda (tip)
        (setf (capi:text-input-pane-caret-position tip)
              0)))
   (cons 
    "Ctrl-6" 'do-something-else))))

There is a further example here:

(example-edit-file "capi/elements/text-input-pane")

See also

display-pane
editor-pane
multi-line-text-input-pane
set-text-input-pane-selection
text-input-choice
text-input-pane
text-input-pane-complete-text
text-input-pane-copy
text-input-pane-cut
text-input-pane-delete
text-input-pane-in-place-complete
text-input-pane-paste
text-input-pane-selected-text
text-input-pane-selection
title-pane
3.5.2 Text input panes
3.1.4.1 Controlling Mnemonics
3.5 Displaying and entering text
19.3.2 Matching resources for GTK+
9 Adding Toolbars
9.7.1 Toolbar items other than buttons with images
10.6 In-place completion