A text_item is a entry field for a short text. It is normally used in dialog windows for entering names or other short textual information. A text_item consists of a label, and an entry field. The label is fixed. The user may type in the entry field.
When the user hits RETURN, the text_item will forward the current
text_item<-selection
over the associated dialog_item<-message
with the following arguments:
@receiver The text_item @arg1 The current selection
Text_item's may used to edit/examine any PCE type that defines a
object<-print_name
and an object<-convert
which allows the item to convert a typed textual representation into an
object of the requested type. See text_item<-type.
If is possible to generate a set of possible completions for a
partially typed text, the text_item may be programmed to perform
automatic completion. See text_item->complete.
The mapping from key-strokes to edit actions is determined by the reusable key_binding object named text_item, a reference to which may be obtained using:
?- new(KB, key_binding(text_item)).
See also class label and class int_item.
Bugs:
It is not possible to detect the user typed something before the
RETURN or ESCAPE otherwise than creating a subclass and redefining the text_item->event
method.
->enter.
Values are:
Defaults: The initial value is next.
|function->restore’d.->alert
on the text_item.
Defaults: @on
->layout.
The item will be extended towards the item at its right or the
right-side of the dialog window.<-value_font’s ex
units (see font<-ex).
See also text_item->value_width.<-selection
converted to text. It is used to detect if the user has modified the
selection.
->selection
and text_item<-selection
if the text has been edited by the user.Defaults: @on
<-value_set
or do completion on the basis of their associated text_item<-type.
In both cases, visualisation by means of a combo box
provides useful feedback to the user as well as a commonly found user
interface style.
text_item<-style
combo_box is automatically selected after text_item->value_set
or
text_item->type
with a suitable type. It may be switched afterwards.
A text item showing as a combo-box both supports completion and opening the combo-box.
Style stepper shows a small up/down arrow at the right
of the text-entry-field. Pressing this field invokes text_item->increment
and
text_item->decrement,
holding the mouse-button down repeats this message. This style is used
by class int_item.
Applications may use it to implement -for example- an ordinal scale.
<->type
slot describes the value-type represented by the text_item. When a value
is displayed, it is translated into a string using
object<-print_name.
After editing, it is translated into a PCE
object of the specified type using type<-check.
Slot text_item<-type
is set by text_item->default,
where it is deduced from the initial value. When the value is an
integer, the type is int. Otherwise the type describes the
class the selection belongs to.
If the type can generate a value_set (see type<-value_set
and
text_item<->value_set,
the text_item->style
will automatically be changed to
combo_box.
EXAMPLE
?- new(P, picture),
send(P, display, new(B, box(100,100))),
send(new(D, dialog), below, P),
send(D, append,
text_item(size, B?size,
message(B, size, @arg1))),
send(P, open).
|function]*->complete
and text_item<-completions.
The interpretation of this slot is:
<-completions
fails (no completion).
<-completions
activates type<-value_set
on the associated
text_item<-type.
<-completions
answers with this chain.
<-completions
invokes the function and returns the result. During execution of the
function @arg1
is bound to the file return of text_item<-split_completions.
If this function is invoked to generate all values for opening a
combo-box, @arg1
is bound to the empty name (” ). The function is supposed to
return a chain of possible values whose textual description starts with @arg1.
Note that text_item->complete
will not consider elements of the chain whose object<-print_name
does not start with
text_item<-displayed_value.
Using @arg1 to
select candidates is only useful if this speeds up the selection
process.
->right_side
is often a comfortable for helping allignment. See also
text_item<-hor_stretch.
->advance
<-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.
<-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.->selection” .
This method is meaningless when type is not name or some
other type that allows for” .->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:
<-split_completion
Split the currently typed value in a directory part and a
file part.
<-completions
Return a set of possible files in the indicated
directory using the result of text_item<-split_completion.
->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.
<-style
is combobox, text_item->complete
the value. Otherwise use text_item->next
to advance to the next dialog item. See also
device->advance.<-value_text,
the label and value positions and the
text_item<-reference.|function->restore
the text_item.<-displayed_value->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.
->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.
->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.
<->active
equals @off:
fail
->caret).
->post
this event to @completer. Otherwise invoke text_item->typed.
->apply: @on.
See also
text_item->enter.stepper buttons. See also text_item->style:
stepper.->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
).
|function], message=[code]*->default’->modified
runs text_item<-selection
to reset the -selection and -print_name slots.<-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.
<-cute_buffer’. By default
invoked from text_item->event
on a middle button click.->quit_completer.<-default
value and sets the text_item->selection
to this value.->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.
@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.
<-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.
->select_completion.active, show the caret (text->show_caret).
Otherwise the caret is not visible.|event_idtext_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:
->event
->typed
->insert_self: @default,
97
->insert_self is delegated to text_item<-value_text
->length.
New code should use text_item->length,
to avoid the ambiguity with graphical->width.
Inherits description from: text_item-length, text_item->length
|tuple -> chain->complete.
The argument is the return-value of text_item<-split_completion.
If the argument is a char_array the text_item completes from a plain
list. It should return a chain of objects that match the indicated start
of their object<-print_name.
The chain may contain objects whose name does
->complete.
If the argument is a tuple the text_item is used for a hierarchical
structure. This method should return a chain of
files matching tuple<-second
in the directory tuple<-first.
The default implementation exploits text_item<-value_set.
<-string
of text_item<-value_text.->style:
@default to
see whether the item should appear as a normal entry-field or as a
combo-box.<-print_name.
<-selection
into a textual format. It attempts the following conversions:
<-print_name
type(char_array) text_item<-check
(calling char_array<-convert).
pretty printing format used by the debugger.
@see text_item-type
<-print_name.
May be redefined. See also -print_name.<-selection
from the entered value. Performs the following steps:
->enter_completer
<-modified
equals @on,
convert the text<-string
of the text_item<-value_text
(i.e. the displayed value) using
type<-check
to the requested type. If this succeed assign text_item<-selection
and object<-print_name.
If it fails generate a connot_convert_text error.
<-selection
slot value
|tuple<-displayed_value
(passed as argument) into a directory- and a file-part
to deal with hierarchically organised data. This method should return:
directory and file component if the
text_item is used to select from a hierarchical structure.
Note that the return-value of this message is passed to
text_item<-completions.