A
List
is the interface to Java's AWT List Component.
Yoix programs normally interact with a
List
using event handlers and by reading or writing the following fields:
| background |
The
Color
that is used to paint the background of the list.
Reading returns a snapshot of the current color.
Writing immediately changes the background to the new color.
Storing
NULL
in
background
is special and means use the background of the nearest component
that contains the list and was assigned a background color other than
NULL;
if no component qualifies the list uses white.
| | cursor |
An
Object
that should be an
int,
Image,
or
String
that selects the cursor shown when the pointer is over the list.
A
cursor
that is an
int
should be one of the cursors defined in the
yoix.awt.Cursor
dictionary.
A
cursor
that is an
Image
can describe the cursor using its
size
and
hotspot
fields and often draws it using its
paint
function.
A
cursor
that is a
String
should be the name of a cursor that is already defined in
yoix.awt.Cursor
or the name a local a file or URL that contains a GIF or JPEG image
that will be used as the cursor.
Reading returns the current cursor.
Writing immediately changes the list's cursor to the new value.
Storing
STANDARD_CURSOR
(the default) or
NULL
in
cursor
is special and means use the cursor assigned to the nearest component
that contains the list and was assigned a cursor other than
STANDARD_CURSOR;
if no component qualifies the list uses
DEFAULT_CURSOR.
| | enabled |
An
int
that is
1
when the list can respond to user input, and
0
otherwise.
Reading returns the current state.
Writing immediately sets the list's state to the new value.
| | focusowner |
A read-only
int
that is non-zero when the list has the focus.
| | font |
The
Font,
or font name if it is a
String,
used to paint the text strings displayed by the list.
Reading returns a snapshot of the current font.
Writing immediately repaints the text strings displayed by the list
in the new font.
| | foreground |
The
Color
that is used to paint text strings displayed by the list.
Reading returns a snapshot of the current color.
Writing immediately repaints the text strings displayed by the list
in the new color.
Storing
NULL
in
foreground
is special and means use the foreground of the nearest component
that contains the list and was assigned a foreground color other than
NULL;
if no component qualifies the list uses
VM.screen.foreground.
| | index |
An
int
that can be used to adjust the view of the list.
Writing tries to reposition the list so the specified item is visible.
Reading usually provides the last number stored in
index,
which unfortunately is not particularly useful because the value
may have no relationship to the items that are currently visible.
| | items |
An
Array
of strings, organized in pairs, that determines what is loaded
in the list (i.e., what users see) and what is returned by
the list when reading the
selected
field.
Strings at even indices in
items
are loaded in the list;
strings at odd indices are return values.
A
NULL
at an odd index means the return value is the string at the
corresponding even index
(i.e., the one that was loaded in the list).
Setting this field to
NULL
clears the list completely.
Reading this value will always return an
Array
of at least size 0.
This field affects the values of the
labels
and
mappings
fields (and vice versa).
| | labels |
An
Array
of strings that determines what is loaded
in the list and what is returned by
the list when reading the
selected
field.
All the strings are loaded into the list and the same values are returned
in the
selected
field.
The result is equivalent to using the
items
field with alternating
NULL
values.
Setting this field to
NULL
clears the list completely.
Reading this value will always return an
Array
of at least size 0.
This field affects the values of the
items
and
mappings
fields.
| | location |
A
Point
that determines the location of the list
in a coordinate system that has its origin at the upper left corner
of the container closest to the list (in the component hierarchy)
that actually contains it, positive x to the right, positive y down,
and a resolution of 72 dots per inch.
Reading returns a snapshot of the current location.
Writing is allowed, but layout managers usually get the final say, so setting
location
should be viewed as a request that may not be honored.
| | mappings |
An
Array
of strings that determines what is returned by
the list when reading the
selected
field.
This field must be set after the
labels
or
items
field is set and the length of the
Array
must match the length of the
Array
returned by the
labels
field.
The strings are assigned to be the return values for corresponding element,
positionally, in the labels
Array.
This field can be used to replace existing mappings, even those set by the
items
field.
Setting this field to
NULL
is equivalent to using the
items
field with alternating
NULL
values or the
labels
field alone.
Reading this value will always return an
Array
of at least size 0.
| | multiplemode |
An
int
that is
1
when more than one item can be selected, and
0
otherwise.
Reading returns the current mode.
Writing immediately sets a new mode, which may also mean deselecting
all but one of the currently selected items.
| | popup |
A
PopupMenu
that is associated with the list.
Reading returns the current popup menu.
Writing immediately shows the popup menu at the point in the list's coordinate
system specified by the popup menu's
location
field, assuming of course that the list is showing on the screen.
Storing
TRUE
in the popup menu's
visible
field, which was added in release 1.2.0, is an easy way to show the
popup menu that currently belongs to the list.
| | requestfocus |
An
int
that can be used to request or transfer the keyboard focus.
Storing a non-zero value in
requestfocus
tries to get the focus.
Storing
0
tries to transfer the focus.
Reading
requestfocus
does not currently return any useful information.
| | root |
An
Object
that is automatically updated by the interpreter's layout machinery
so it is always the top-level object that contains the list.
For example, put a list in a panel and
root
will be set to that panel;
add the panel to a frame and the list's
root
field will be set to that frame.
A list's event handlers can use
root
when they need to interact with the other components in the container.
| | rows |
An
int
that specifies the number of rows in a new list.
Layout managers usually get the final say, so setting
rows
should be viewed as a request that will not always be honored.
Changing
rows
after a list has been created has no effect and eventually may
trigger an
invalidaccess
error.
| | scroll |
An
int
that tries to control where scrollbars are added to a new list.
The value should be
NONE,
HORIZONTAL,
VERTICAL,
or
BOTH,
which are all defined in
yoix.awt;
the default value is
BOTH.
Changing
scroll
after a list has been created is not allowed and will result in an
invalidaccess
error.
Unfortunately an AWT List Component can not really control scrollbars,
so our implementation is advisory only.
It works by estimating the height and width of the text displayed by
the list, and when
scroll
is something other than
BOTH
the estimate is used to try to control the dimensions of the list
so the requested scrollbar display policy is followed.
| | selected |
A
String,
int,
or
Array
of strings and integers that refer to the items currently selected
by the list.
Reading always returns an array of strings that correspond to
the currently selected items:
the array is empty, but not
NULL,
when no items are selected.
Storing an integer in
selected
picks the item at that index.
Storing a string in
selected
picks the item that has that string as its return value,
or if there is no match, the item that has that string as its actual value.
Storing an array of strings or integers in
selected
is how you set several items in a
multiplemode
list.
The selected items in a list are cleared when
NULL
is assigned to
selected.
| | showing |
A read-only
int
that is non-zero when the list is showing on the screen.
| | size |
A
Dimension
that determines the size of the list
in units of 72 dots per inch.
Reading returns a snapshot of the current size.
Writing is allowed, but layout managers usually get the final say, so setting
size
should be viewed as a request that may not be honored.
| | tag |
A
String
used to identify the list that is either supplied when
the list is declared, or automatically generated otherwise.
Add a list to a container, like a
Frame
or
Panel,
and the interpreter's layout machinery updates the
root
field so it points at the top-level container and then adds the list, as
tag,
to the
root.components
dictionary.
| | visible |
An
int
that is
1
when the list is visible, and
0
otherwise.
Reading returns the current visibility.
Writing immediately sets the list's visibility to the new state.
|
Several permanent fields have not been documented and should not be
used in Yoix applications.
Event handlers are functions that must be added to a list when it is
declared.
The handlers that work with lists are listed below;
the names should be familiar if you have done some Java programming.
The
actionPerformed
event handler is only for menus.
| |
| Event Handlers: |
actionPerformed,
componentHidden,
componentMoved,
componentResized,
componentShown,
dragDropEnd,
dragEnter,
dragExit,
dragGestureRecognized,
dragMouseMoved,
dragOver,
drop,
dropActionChanged,
focusGained,
focusLost,
invocationRun,
itemStateChanged,
keyPressed,
keyReleased,
keyTyped,
mouseClicked,
mouseDragged,
mouseEntered,
mouseExited,
mouseMoved,
mousePressed,
mouseReleased,
mouseWheelMoved
| | |
| Example: |
The program,
import yoix.*.*;
Frame f = {
FlowLayout layoutmanager = {
int hgap = 10;
int vgap = 72;
};
Array layout = {
new List {
Array items = {
"one", "1",
"two", NULL,
"three", "3",
"four", NULL,
"five", "5"
};
int rows = 2;
int multiplemode = 1;
itemStateChanged(e) {
printf("selected=%O\n", selected);
}
},
new List {
Array items = {" ", NULL, "Continue", NULL, "Quit", NULL};
int selected = 1;
itemStateChanged(e) {
printf("selected=%O\n", selected);
if (strcmp(selected[0], "Quit") == 0)
exit(0);
}
},
};
};
f.visible = TRUE;
adds two lists to a frame,
prints the selected value when either one is changed,
and quits when the last item in the right list is
selected.
| | |
| See Also: |
Button,
Canvas,
Checkbox,
Choice,
Dialog,
FileDialog,
Frame,
Label,
Panel,
postEvent,
ScrollPane,
Scrollbar,
TableColumn,
TableManager,
TextArea,
TextCanvas,
TextField,
TextTerm,
Window
|
|
