1.168.2 Send methods

text_item ->_wants_keyboard_focus:

Test if the text_item is prepared to get the keyboard focus. Succeeds if:

1. TextItem is displayed
2. TextItem is active
3. TextItem is editable @see device->advance

text_item ->apply: [bool]

Executes dialog_item<-message iff it is a code object, always is @on or text_item<-modified is @on and text_item<-selection succeeds. The following arguments are forwarded:

@receiver	The text_item
@arg1	The text_item<-selection.

text_item ->catch_all: selector=name, argument=unchecked ...

Delegate to text_item<-value_text and update the visualisation if the method was accepted. This allows all text object manipulation methods such as string->append and string->insert to be applied directly on a text_item object. See also text->catch_all.

text_item ->clear:

Equivalent to text_item->selection” . This method is meaningless when type is not name or some other type that allows for” .

text_item ->complete: [event_id]

Attempt to complete the value typed so far. If this fails or there is no completion defined for this item. activate text->insert_self.

This method is the central method of the text_item's completion mechanism. This completion mechanism both deals selecting in hierarchical organised data (like the Unix file-system) and with simple lists of possible values. The second case is generally handled by text_item<->value_set. For selecting from hierarchical organised data the following methods need to be redefined:

• text_item<-split_completion Split the currently typed value in a directory part and a file part.
• text_item<-completions Return a set of possible files in the indicated directory using the result of text_item<-split_completion.
• text_item->indicate_directory Indicate the match of a directory.

  In this documentation we refer to files and directories, but in general this may refer to any organised data using any syntactical convention. The Prolog library file file_item.pl illustrated how the methods described above may be redefined to select a file from the Unix file-system.

  When text_item->complete is invoked, it attempts to complete the current entry. To do so, it locates the first choice-point and the set of objects that may be selected after this choice-point using chain<-complete_name. If the current point is a choice-point it will pop-up the browser object @completer with all possible completions. If the current point is a unique description of a completed value it will indicate such using the error sole_completion. Otherwise it will replace text_item<-displayed_value with the text leading to the first choice-point or completion.

  See also

  - text_item->indicate_directory
  - @completer
  - text_item-value_set

text_item ->complete_or_next: [event_id]

If text_item<-style is combobox, text_item->complete the value. Otherwise use text_item->next to advance to the next dialog item. See also device->advance.

text_item ->compute:

Updates the text_item<-value_text, the label and value positions and the text_item<-reference.

text_item ->default: any|function

Set the variable -default to the argument and then text_item->restore the text_item.

text_item ->displayed_value: char_array

Inherits description from: text_item<-displayed_value

text_item ->enter: [event_id]

The method text_item->enter is by default bound the the RETURN key. It's behaviour is rather complicated to get proper default action both if the dialog window in which the text_item resides has a‘dialog text_item<-default_button’and if this is not the case.

1. Send window->typed to the graphical<-window of the text_item. If the window has an accelerator for RET this will be activated. If this message returns successfully the text_item considers the RETURN handled.
2. Otherwise, text_item->apply the text_item. If this succeeds and text_item<-advance = clear, clear the text_item using text_item->selection ” . Otherwise proceed to the next text_item using text_item->next.

text_item ->event: event

Process an event:

• When graphical<->active equals @off: fail
• Left button: try to get the caret (see text_item->caret).
• Middle button: paste X-cut-buffer 0 Finally is the event is a keyboard event and @completer is working for this text_item event->post this event to @completer. Otherwise invoke text_item->typed.

text_item ->execute:

Execute the text_item. Invokes text_item->apply: @on. See also text_item->enter.

text_item ->decrement:

(virtual) Decrement the selection.

text_item ->increment:

(virtual) Increment the selection. Called when the user clicks the upper of the stepper buttons. See also text_item->style: stepper.

text_item ->indicate_directory: text=string

This method is invoked by text_item->complete if the expansion is unique. It provides a possibility to indicate that this string represents a directory. Class file_item from the PCE/Prolog library defines this method as:

indicate_directory(_FI, Dir:string) :->
        (   send(directory(Dir), exists)
        ->  send(Dir, ensure_suffix, /)
        ;   true
        ).

See also

text_item->complete

text_item ->initialise: name=[name], default=[any|function], message=[code]*

Create a text-entry-field from its label, initial value and message to execute after the value is edited by the user. The initial value will be processed as text_item->default’

text_item ->length: int

Length of entry field in characters.

text_item ->modified: bool

If the argument equals @off, text_item->modified runs text_item<-selection to reset the -selection and -print_name slots.

text_item ->next:

Advance to next item in same graphical<-device. This invokes device->advance using the receiver as argument. This method is normally bound to the TAB key.

See also text_item->complete_or_next.

text_item ->paste: which=[{primary,clipboard}]

Paste the value of the indicated X-cut buffer. See‘display text_item<-cute_buffer’. By default invoked from text_item->event on a middle button click.

text_item ->reset:

Equivalent to text_item->quit_completer.

text_item ->restore:

Computes the current text_item<-default value and sets the text_item->selection to this value.

text_item ->select_completion: value_set=chain, prefix=[char_array]*, search=[char_array]*, auto_hide=[0..]

Called by text_item->complete. It's function is to allow the user to select a value from the set of possible values. Prefix is the value entered so far,

By default this method pops-up the browser @completer. This may be redefined.

text_item ->selected_completion: item=char_array, apply=[bool]

Called from @completer, a global browser object used to to display completions on a text_item or alternatives from the drop-down browser of a text_item.

@completer calls this method with a single argument representing the selected text.

This method appends the argument value to the prefix resulting from text_item<-split_completion, sets the text_item<-value of the text_item and hides @completer.

text_item ->selection: any

Set the text_item<-selection. If the given value is not equal to the text_item<-selection, convert it to text_item<-type using type<-check. If the value is still not equal to the text_item<-selection, obtain a printable representation using object<-print_name with the value as argument. Finally assign text_item<-selection with the (converted) value and object<-print_name with the textual representation and update the display.

See also text_item<-selection and text_item->default.

text_item ->show_combo_box: bool

Called internally to show/unshow the combo-box browser. This browser is actuially @completer, as used by text_item->select_completion.

text_item ->status: {inactive,active,preview,execute,increment,decrement}

If active, show the caret (text->show_caret). Otherwise the caret is not visible.

text_item ->typed: event|event_id

Activates the key_binding object named text_item from @key_bindings. This key_binding object will map the typed keys onto functions (selectors) which will then be invoked on the text_item.

For example, if the user types an a to a text_item the following sequence of method is traversed:

1. text_item->event
2. text_item->typed
3. ’a’mapped by key_binding object to text_item->insert_self: @default, 97
4. text_item->insert_self is delegated to text_item<-value_text

text_item ->width: characters=int

Equivalent to text_item->length. New code should use text_item->length, to avoid the ambiguity with graphical->width.

Inherits description from: text_item-length, text_item->length