## textlist.api
#
# "A text list provides the user with a list of strings,
# and allows the user to select some items from the list.
# The user selects an item by clicking on it with the
# left mouse button. The user can unselect an item by
# clicking on it with the middle button. The widget
# reports user selections as events, which can be tied
# to application-specific actions. There are two types
# of list behavior, viz., lists allowing multiple
# selections and lists allowing at most one selection.
# In the single selection case, selecting a new item
# automatically causes a previously selected item to
# be unselected."
#
# "An item is essentially a triple of a string, a value
# and an initial state. The string specifies the text
# displayed in the list. The value is returned when
# the user selects the item. The initial state specifies
# whether the item is active, and whether or not the
# item is set."
#
# -- p29 Gansner+Reppy's 1993 eXene widget manual,
# http://mythryl.org/pub/exene/1993-widgets.ps
#
#
# "An item is essentially a triple of a string, a value
# and an initial state. The string specifies the text
# displayed in the list. The value is returned when
# the user selects the item. The initial state specifies
# whether the item is active, and whether or not the
# item is set."
#
# -- 309 Gansner+Reppy's 1993 eXene widget manual,
# http://mythryl.org/pub/exene/1993-widgets.ps
#
#
# Background and foreground colors default
# to black and white, respectively.
#
# At runtime the de/selected and in/active state of each
# Textlist_Item can be externally controlled via
#
# set_textlist_selections
# set_textlist_active_items
#
# The Textlist state may be queried via
#
# get_textlist_selections
# get_textlist_item_states
#
# textlist_change'_of
# yields the textlist_change' mailop on which to
# 'do_one_mailop' for state changes; it returns each
# change in selection status plus the associated
# value. As usual, if you do not read it, the
# testlist thread will block and the widget will
# freeze.
#
#
# NB From inspection of the code, it appears that (Dusty's?)
# intent was to default to mono-selection mode but
# allow it to be overridden using 'attribute_multiset' from
#
# src/lib/x-kit/widget/old/lib/widget-attribute-old.api#
# but that this never got implemented.
#
# Similarly, it appears that horizontal textlists and
# horizontal justification were to be supported via
#
# wa::attribute_is_vertical and horizontal
# wa::halign
#
# respectively, but that it again did not get implemented.
#
#
# For example code using textlist see:
# src/lib/x-kit/tut/arithmetic-game/arithmetic-game-app.pkg# Compiled by:
# src/lib/x-kit/widget/xkit-widget.sublibstipulate
include package threadkit; # threadkit is from src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg #
package wg = widget; # widget is from src/lib/x-kit/widget/old/basic/widget.pkg package wt = widget_types; # widget_types is from src/lib/x-kit/widget/old/basic/widget-types.pkgherein
# This api is implemented in:
#
# src/lib/x-kit/widget/old/leaf/textlist.pkg #
api Textlist {
exception BAD_INDEX;
Textlist(X);
List_Event(X)
= SET(X)
| UNSET(X)
;
Textlist_Item(X); # = (String, X, wg::Button_State)
make_textlist_item
:
( String, # String to display on this line of widget.
X, # Value to return when this line is selected by user.
wt::Button_State # Initial state (in/active, de/selected).
)
->
Textlist_Item(X);
make_textlist
: (wg::Root_Window, wg::View, List( wg::Arg ))
-> List( Textlist_Item(X) )
-> Textlist(X)
;
as_widget: Textlist(X) -> wg::Widget;
set_textlist_selections: Textlist(X) -> List( (Int, Bool) ) -> Void;
set_textlist_active_items: Textlist(X) -> List( (Int, Bool) ) -> Void;
get_textlist_selections: Textlist(X) -> List( Int );
get_textlist_item_states: Textlist(X) -> List( wt::Button_State );
textlist_change'_of: Textlist(X) -> Mailop( List_Event(X) );
insert: Textlist(X) -> (Int, List( (String, X) )) -> Void;
append: Textlist(X) -> (Int, List( (String, X) )) -> Void;
delete: Textlist(X) -> List( Int ) -> Void;
/*
my setOrigin: Textlist(X) -> wg::G.point -> Void
my setHorz: Textlist(X) -> Int -> Void
my setVert: Textlist(X) -> Int -> Void
my getGeometry: viewport -> { box: wg::G.box, childSz: wg::G.size }
my geomEvtOf: text_list(X) -> Mailop { box: wg::G.box, childSz: wg::G.size }
*/
};
end;