A
JComboBox
is the interface to the Java Swing JComboBox Component.
Yoix programs normally interact with a
JComboBox
using event handlers and by reading or writing the following fields:
| autotrim |
An
int
that is
1
when white space is automatically trimmed from both ends of every string
read from or written to the
text
field, and
0
otherwise.
| | background |
The
Color
that is used to paint the background of the combobox.
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 the combobox uses its preferred color, which is white.
| | border |
An
Object
that should be a
Border,
Insets,
Number,
or
String
that describes the border that is drawn around this combobox.
A
NULL
value, which is the default, means no border.
A
border
that is an
Insets
or
Number
is an easy way to describe margins
(i.e., an
EmptyBorder),
in units of 72 dots per inch, that are left around the sides of this combobox.
A
border
that is a
String
is a quick way to surround this combobox with a border that uses the
String
as its title.
Reading returns a snapshot of the current border.
Writing immediately sets the combobox's border to the new value.
| | cursor |
An
Object
that should be an
int,
Image,
or
String
that selects the cursor shown when the pointer is over the combobox.
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 combobox'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 combobox and was assigned a cursor other than
STANDARD_CURSOR;
if no component qualifies the combobox uses
DEFAULT_CURSOR.
| | doublebuffered |
An
int
that is
1
when the combobox uses double-buffering to draw itself,
0
when it does not, and starts with a default value that is
selected by Java for the combobox.
Reading returns the current double-buffering behavior.
Writing immediately sets the combobox's double-buffering behavior to the new value.
Note that double-buffering may be required when transparent components are used.
| | dragenabled |
An
int
that should be set to
1
when this combobox wants to use the automatic drag handling that Swing provides
for some components, and
0
(the default)
when it does not.
Components that do not provide automatic drag handling always return
0
when their
dragenabled
field is read, so storing
1
in
dragenabled
should only be viewed as a request for a service that may not be available.
Swing components can always take complete control of their drag and drop
handling using their
transferhandler
field or special drag and drop event handlers.
| | edit |
An
int
that is
1
when the selected item displayed by the combobox can be edited
0
(the default)
when it can not.
Reading returns the current edit flag.
Writing immediately sets the combobox's edit state to the new value.
| | enabled |
An
Object
that is
1
when the combobox can respond to user input,
0
when it can not respond, and
NULL
(the default)
when the combobox inherits the value from the nearest lightweight container,
like a
JPanel,
that contains the combobox and has its
enabled
field set to something other than
NULL.
The top-level application window that contains the combobox always gets the
final say, so disabling that window always disables the combobox.
Reading returns the current state.
Writing immediately sets the combobox's state to the new value.
| | focusable |
An
int
that is non-zero (the default)
when the combobox can accept the keyboard focus and zero
when it can not.
Reading returns the combobox's current focusable state.
Writing immediately changes the combobox's focusable state to the new value,
which means the focus is automatically transferred if the new value is zero
and the combobox is the current focus owner.
| | focusowner |
A read-only
int
that is non-zero when the combobox has the focus.
| | font |
The
Font,
or font name if it is a
String,
used to paint the text strings displayed by the combobox.
Reading returns a snapshot of the current font.
Writing immediately repaints the text strings displayed by the combobox
in the new font.
| | foreground |
The
Color
that is used to paint text strings displayed by the combobox.
Reading returns a snapshot of the current color.
Writing immediately repaints the text strings displayed by the combobox
in the new color.
Storing
NULL
in
foreground
is special and means use the foreground of the nearest component
that contains the combobox and was assigned a foreground color other than
NULL;
if no component qualifies the combobox uses
VM.screen.foreground.
| | items |
An
Array
of strings, usually organized in pairs, that determines what is loaded
in the combobox (i.e., what users see) and what is returned by
the combobox when reading the
selected
field.
Strings at even indices in
items
are loaded in the combobox;
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 combobox).
The grouping has to be changed slightly if you want to display images in the combobox.
The change happens automatically when the first element in
items
is
NULL
or an
Image
(actually anything other than a
String)
and in that case the elements in the array are assumed to be organized in triples with the
Image
being the first element, the text string displayed by the combobox the second element,
and the value returned when
selected
is read the third element.
Setting this field to
NULL
clears the combobox 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 combobox and what is returned by
the combobox when reading the
selected
field.
All the strings are loaded into the combobox 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 combobox 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.
| | layer |
An
int,
often a small number between 0 and 99,
that identifies the depth of this combobox when it is added to a
JLayeredPane
or
JDesktopPane.
Components assigned to lower numbered layers are drawn before
the components in higher numbered layers.
Writing immediately changes the combobox's layer, which usually means the
JLayeredPane
or
JDesktopPane
that contains the combobox will be repainted.
| | location |
A
Point
that determines the location of the combobox
in a coordinate system that has its origin at the upper left corner
of the container closest to the combobox (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 combobox 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.
| | nextfocus |
An
Object
that identifies the component that receives the focus after this combobox
when the focus traverses from one component to the next
(usually by means of the keyboard
TAB
character).
When
nextfocus
is a
String
it is assumed to be the tag associated with the target component,
which must belong to the same top-level container (e.g., the same
JFrame)
as this combobox.
A
NULL
value means the component that gets the focus after this combobox will be
selected by Java's default focus traversal policy.
Reading returns the value last stored or
NULL
if the value was a
String
that did not reference a component.
Writing immediately changes the component that gets the focus after this combobox.
| | opaque |
An
Object
that is
1
when the combobox is opaque,
0
when it is transparent, and
NULL
(the default)
when the combobox inherits the value from the nearest component that
contains the combobox and has its
opaque
field set to something other than
NULL.
| | popup |
A
JPopupMenu
that is associated with the combobox.
Reading returns the current popup menu.
Writing immediately shows the popup menu at the point in the combobox's coordinate
system specified by the popup menu's
location
field, assuming of course that the combobox 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 combobox.
| | preferredsize |
A
Dimension
that is used by layout managers when they need to know the combobox's
preferred size in units of 72 dots per inch.
A
NULL
value means the combobox has no preference.
A non-positive height or width is allowed and simply means the combobox
has no preference for that dimension.
Reading returns the current preferred size.
Writing changes the preferred size and immediately notifies
root.layoutmanager,
which means the components contained in
root
may be repositioned and resized.
| | prototypevalue |
An
Object,
usually a
String,
that Swing can use to compute the maximum width and height the cells displayed
by the combobox.
A value of
NULL,
which is the default, means all items displayed by the combobox are measured
and used to calculate the appropriate cell width and height.
A value that's the empty string (i.e.,
"")
is special and means all text strings that can be displayed by the combobox
are measured once and the widest one is handed to Swing as the prototype.
Even though all strings are measured, it only happens once, so in practice
the empty string really does turn out to be a reasonable choice.
| | 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.
| | requestfocusenabled |
An
int
that is
1
(the default)
when actions, like mouse clicks or changes to the
requestfocus
field, can steal the keyboard focus and
0
when they can not.
Note that this field does not affect acceptance of the keyboard focus
during normal focus traversal.
Reading returns the current state.
Writing immediately sets the combobox's state to the new value.
| | root |
An
Object
that is automatically updated by the interpreter's layout machinery
so it is always the top-level object that contains the combobox.
For example, put a combobox in a panel and
root
will be set to that panel;
add the panel to a frame and the combobox's
root
field will be set to that frame.
A combobox'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 maximum number of rows that can be displayed
by the combobox before a scrollbar is added.
Reading returns the current limit.
Writing immediately changes limit to the new value if it is a positive
number, otherwise the request is ignored.
| | scroll |
An
int
that controls how scrollbars are added to a new combobox.
The value should normally be one of
NONE,
HORIZONTAL,
VERTICAL,
BOTH,
or
AS_NEEDED
(the default), which are all defined in
yoix.swing.
Fancier controls described in the
JScrollPane
reference page are allowed here, but in practice they are rarely needed.
In addition you can explicitly set
scroll
to zero to permanently disable scrolling in this combobox.
| | selected |
When reading, it is a
String
that is the
mapping
value of the currently selected item or
NULL
when no item is selected.
When writing, it can be either
String
or an
int.
Storing an integer in
selected
picks the item at that index or clears the selection if the index is
out of range.
Storing a string in
selected
picks the item that has that string as its return value.
If there is no match and
edit
has a zero value, namely the combobox is not editable, then
the item that has that string as its label
value, if any, becomes the selected item, otherwise
NULL
is assigned to selected and the combobox selection is cleared.
If the combobox is editable, namely
edit
has a non-zero value, and there is no existing entry that matches the
string value assigned to
selected,
then that value becomes the selected value and is displayed as such
though the array of items in the combobox is not augmented.
The selected items in a combobox are cleared when
NULL
is assigned to
selected.
| | selectedends |
An
Array
that contains entries that are used to set the starting
and ending positions of the currently displayed text for an editable combobox.
Writing
NULL
to
selectedends
clears the currently displayed text,
otherwise the first array element controls the start position,
while the second element controls the end position.
The starting position is either 0 or the integer value of the number at
selectedends[0].
The ending position is either the length of the
text
string, which puts it just to the right of the last character,
or the integer value of the number at
selectedends[1].
Requesting an ending value that is less than or equal to the starting
value also clears the currently displayed text.
Reading returns an
Array
of two integers that are the starting and ending positions of the
current selection.
When writing, the insertion caret is set to the end of the selected text.
| | selectedindex |
A read-only
int
that is the index of the currently selected item or
-1
when no item is selected.
| | selectedlabel |
A read-only
String
that is the
label
value of the currently selected item or
NULL
when no item is selected.
It returns the same value as
selected
when there is no
mapping
in effect.
| | showing |
A read-only
int
that is non-zero when the combobox is showing on the screen.
| | size |
A
Dimension
that determines the size of the combobox
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 combobox that is either supplied when
the combobox is declared, or automatically generated otherwise.
Add a combobox to a container, like a
JFrame
or
JPanel,
and the interpreter's layout machinery updates the
root
field so it points at the top-level container and then adds the combobox, as
tag,
to the
root.components
dictionary.
| | text |
A
String
of characters that is displayed in the textfield of an editable combobox.
If the combobox is not editable, this field does not affect the GUI.
Reading returns the current text.
Writing immediately paints the new text.
| | tooltiptext |
A
String
of characters that is displayed in a tightly sized pop-up window that
appears near the cursor whenever the cursor lingers over the combobox.
Setting this value to
NULL
(the default)
disables the tooltip mechanism.
Reading returns the current tooltip text.
Writing immediately sets the new tooltip text.
| | transferhandler |
An
Object
that should be a
TransferHandler
or
String
that determines how the combobox handles data transfer operations
like drag and drop.
A value that is a
String
but not
""
means the field named by the
String
should be used as the source and sink of the data that is transferred by
the combobox.
The result is the same as assigning the
String
to the
property
field in a
TransferHandler
and then assigning that
TransferHandler
to
transferhandler.
The empty
String
""
is special and refers to the
TransferHandler
that Swing uses for automatic drag handling, if there is one.
Swing components that provide automatic drag handling start out with a
transferhandler
field that is not
NULL,
but the automatic drag handling is not enabled until
1
is stored in
dragenabled.
Swing components that provide their own drag and drop event handlers
currently must store
NULL
in
transferhandler
before those event handlers will start working.
| | visible |
An
int
that is
1
when the combobox is visible, and
0
otherwise.
Reading returns the current visibility.
Writing immediately sets the combobox'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 combobox when it is
declared.
The handlers that work with comboboxes are listed below;
the names should be familiar if you have done some Java programming.
The
actionPerformed
event handler is only for menus.
We have not listed any
DragGestureEvent,
DragSourceEvent,
DropTargetEvent,
KeyEvent,
or
MouseEvent
handlers because the experiments that we ran were either unsuccessful
or inconsistent.
| |
| Event Handlers: |
actionPerformed,
componentHidden,
componentMoved,
componentResized,
componentShown,
focusGained,
focusLost,
invocationRun,
itemStateChanged,
textValueChanged
| | |
| Example: |
The program,
import yoix.*.*;
JFrame f = {
FlowLayout layoutmanager = {
int hgap = 10;
int vgap = 72;
};
Array layout = {
new JComboBox {
Array items = {"one", "1", "two", NULL, "three", "3"};
itemStateChanged(e) {
printf("selected=%O\n", selected);
}
},
new JComboBox {
Array items =
{" ", NULL, "Continue", NULL, "Quit", NULL};
int selected = 1;
itemStateChanged(e) {
printf("selected=%O\n", selected);
if (strcmp(selected, "Quit") == 0)
exit(0);
}
},
};
};
f.visible = TRUE;
adds two comboboxes to a frame,
prints the selected value when either one is changed,
and quits when the last item in the right combobox is
selected.
| | |
| See Also: |
BevelBorder,
Border,
EmptyBorder,
EtchedBorder,
invokeLater,
JButton,
JCanvas,
JCheckBox,
JCheckBoxMenuItem,
JChoice,
JColorChooser,
JDesktopPane,
JDialog,
JFileChooser,
JFileDialog,
JFrame,
JInternalFrame,
JLabel,
JLayeredPane,
JList,
JMenu,
JMenuBar,
JMenuItem,
JPanel,
JPasswordField,
JPopupMenu,
JProgressBar,
JRadioButton,
JRadioButtonMenuItem,
JScrollBar,
JScrollPane,
JSeparator,
JSlider,
JSplitPane,
JTabbedPane,
JTable,
JTextArea,
JTextCanvas,
JTextField,
JTextPane,
JTextTerm,
JToggleButton,
JToolBar,
JTree,
JWindow,
LineBorder,
MatteBorder,
postEvent,
SoftBevelBorder,
TransferHandler
|
|
