A
JMenuItem
is the interface to the Java Swing JMenuItem, JCheckBoxMenuItem and
JRadioButtonMenuItem Components.
Yoix programs normally interact with a
JMenuItem
using event handlers and by reading or writing the following fields:
| accelerator |
An
int
or
String
that describes the keys that can be used to invoke the event handler
for the menuitem.
An
accelerator
that is an
int
represents a Unicode character, while an
accelerator
that is a
String
is interpreted as collection of space separated tokens that describe
the modifiers and key that must be pressed, released or typed to
trigger the call to the menuitem's event handler.
The rules that must be followed when
accelerator
is a string are strict and are imposed by the Java class
java.awt.AWTKeyStroke
that is used to parse the string.
Modifiers, if there are any, come first and must be a space separated
combination of the case-sensitive words
ctrl,
control,
shift,
meta,
alt,
and
altGraph.
An upper-case token that follows the modifiers must be the name of the key,
as it appears in the
KeyCode
dictionary that can be found in
yoix.awt
or
yoix.swing,
but without the leading
VK_
prefix that can be pressed, along with the modifiers, to trigger the event
handler call.
The case-sensitive words
pressed
or
released
can appear between the modifiers and upper-case keycode to specify exactly
when the event handler is called.
Alternatively the modifiers can be followed by the word
typed,
a space, and a single character if you want the event handler to be called
when that character is typed.
| | alignment |
An
int
that controls the horizontal positioning of the text in the menuitem.
The value should be
LEFT,
CENTER,
RIGHT,
LEADING,
or
TRAILING,
which are all defined in
yoix.swing.
Reading returns the current alignment.
Writing immediately repaints the text using the new alignment.
The default value is
LEFT.
Adjusting the menuitem's text alignment is not recommended.
| | armed |
An
int
that is 1 when the menuitem is armed (i.e., partially committed to being
pressed) and 0 otherwise.
Reading returns the current armed status.
Writing immediately changes the armed status.
Mostly this field is of use inside the
stateChanged
event handler.
| | 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 menuitem.
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 menuitem and was assigned a background color other than
NULL;
if no component qualifies the menuitem uses
VM.screen.background.
| | border |
An
Object
that should be a
Border,
Insets,
Number,
or
String
that describes the border that is drawn around this menuitem.
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 menuitem.
A
border
that is a
String
is a quick way to surround this menuitem with a border that uses the
String
as its title.
Reading returns a snapshot of the current border.
Writing immediately sets the menuitem's border to the new value.
| | click([Number time]) |
A
Builtin
that causes the menuitem to behave as if it has just been interactively clicked.
The optional
time
argument, when supplied, is the number of seconds the menuitem will remain depressed.
| | command |
A
String
that is assigned to the
command
field in the
ActionEvent
or in the
item
field of the
ItemEvent
that is generated when the menuitem is selected.
The value stored in the menuitem's
text
field is used when
command
is set to
NULL.
| | cursor |
An
Object
that should be an
int,
Image,
or
String
that selects the cursor shown when the pointer is over the menuitem.
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 menuitem'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 menuitem and was assigned a cursor other than
STANDARD_CURSOR;
if no component qualifies the menuitem uses
DEFAULT_CURSOR.
| | doublebuffered |
An
int
that is
1
when the menuitem uses double-buffering to draw itself,
0
when it does not, and starts with a default value that is
selected by Java for the menuitem.
Reading returns the current double-buffering behavior.
Writing immediately sets the menuitem'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 menuitem 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.
| | enabled |
An
int
that is
1
when the menuitem can respond to user input, and
0
when it can not.
The top-level application window that contains the menuitem always gets the
final say, so disabling that window always disables the menuitem.
Reading returns the current state.
Writing immediately sets the menuitem's state to the new value.
| | font |
The
Font,
or font name if it is a
String,
used to paint the characters stored in the
text
field.
Reading returns a snapshot of the current font.
Writing immediately repaints the text in the new font.
| | foreground |
The
Color
that is used to paint the characters stored in the
text
field.
Reading returns a snapshot of the current color.
Writing immediately repaints the text in the new color.
Storing
NULL
in
foreground
is special and means use the foreground of the nearest component
that contains the menuitem and was assigned a foreground color other than
NULL;
if no component qualifies the menuitem uses
VM.screen.foreground.
| | group |
The
ButtonGroup,
if any, containing this menuitem.
Reading returns the currently associated group, writing assigns the currently
associated group.
Button groups are used to
enforce a multiple-exclusion scope on the set of menuitems (or buttons)
in the group.
Usually a menuitem (or button) of type
RADIO_BUTTON
is used in conjunction with a
ButtonGroup.
| | icon |
A read-write
Image
to be used as the
defaulticon
for this menuitem.
This field is a convenience field and is equivalent to the
defaulticon
element in the
icons
dictionary discussed below.
| | icons |
A read-write
Dictionary
of
Image
fields that specify the icons to be used in the seven potential
states of the menuitem.
The seven fields are
defaulticon,
disabledicon,
disabledselectedicon,
pressedicon,
rollovericon,
rolloverselectedicon
and
selectedicon.
If
pressedicon
or
disabledicon
are not explicitly specified, the value of
defaulticon
is applied to them.
| | location |
A
Point
that determines the location of the menuitem
in a coordinate system that has its origin at the upper left corner
of the container closest to the menuitem (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.
| | mnemonic |
An
int
that sets the keyboard mnemonic for the menuitem.
The integer value represents, in a case-insensitive manner, a single key on
the keyboard.
It is recommended that elements in the
yoix.swing.KeyCode
dictionary be used for assigning mnemonic values.
Refer to the Java
AbstractButton
documentation for more information about
mnemonic usage.
| | preferredsize |
A
Dimension
that is used by layout managers when they need to know the menuitem's
preferred size in units of 72 dots per inch.
A
NULL
value means the menuitem has no preference.
A non-positive height or width is allowed and simply means the menuitem
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.
| | pressed |
An
int
that is 1 when the menuitem is pressed and 0 otherwise.
Reading returns the current pressed status.
Writing immediately changes the pressed status.
Mostly this field is of use inside the
stateChanged
event handler.
| | rolloverenabled |
An
int
that is
1
when a
rollover
(i.e., the mouse entering or exiting the menuitem)
will be registered, or
0
(the default)
when it will not.
Note that this field does not affect changing the rollover state by
assigning a value to the
rollover
field.
Reading returns the current state.
Writing immediately sets the menuitem's state to the new value.
| | rollover |
An
int
that is 1 when the mouse is over the menuitem and 0 otherwise.
Reading returns the current rollover status.
Writing immediately changes the rollover status.
Mostly this field is of use inside the
stateChanged
event handler.
| | root |
An
Object
that is automatically updated by the interpreter so it always references
the top-level component that currently owns the menuitem.
For example, add a menuitem to a menu and the
root
field in the menuitem will be set to that menu;
add the menu to a menubar and root in the menu and in the original
menuitem will be set to that menubar.
| | selected |
A synonym for
state,
which is preferred.
This field is retained for backward compatibility.
| | state |
An
int
that is 1 when the menuitem is selected and 0 otherwise.
For a standard menuitem, as opposed to checkbox or radiobutton,
this field has no real meaning and setting it in that
case has no meaningful effect.
| | showing |
A read-only
int
that is non-zero when the menuitem is showing on the screen.
| | size |
A
Dimension
that determines the size of the menuitem
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 menuitem that is either supplied when
the menuitem is declared, or automatically generated otherwise.
| | text |
A
String
of characters that is aligned, as indicated by the
alignment
field, in the menuitem.
Reading returns the current text.
Writing immediately paints the new text.
| | textposition |
An
int
that controls the horizontal positioning of the text in the menuitem relative to its icon.
The value should be
LEFT,
CENTER,
RIGHT,
LEADING,
or
TRAILING,
which are all defined in
yoix.swing.
Reading returns the current alignment.
Writing immediately repaints the text using the new alignment.
The default value is
TRAILING.
| | 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 menuitem.
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 menuitem 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 menuitem.
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.
| | type |
An
int
variable that can only be set at creation time to specify the type of menuitem.
The types,
which are all defined in
yoix.swing,
are
STANDARD_BUTTON,
CHECKBOX_BUTTON
RADIO_BUTTON,
and
TOGGLE_BUTTON.
The default is
STANDARD_BUTTON.
| | visible |
An
int
that is
1
when the menuitem is visible, and
0
otherwise.
Reading returns the current visibility.
Writing immediately sets the menuitem's visibility to the new state.
|
Several permanent fields have not been documented and should not be
used in Yoix applications.
In addition, even though the
layer,
opaque,
nextfocus,
requestfocus,
and
requestfocusenabled
fields are defined, in most situations they have no effect and as a result
they have not been documented.
Event handlers are functions that must be added to a menuitem when it is
declared.
The handlers that work with menuitems are listed below;
the names should be familiar if you have done some Java programming.
| |
| 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.*.*;
JMenuBar menubar = {
Array items = {
new JMenu {
String text = "File";
Array items = {
new JMenuItem {
String text = "Open";
String command = "open";
String accelerator = "ctrl O";
int mnemonic = KeyCode.VK_O;
},
new JMenuItem {
String text = "Close";
String command = "close";
String accelerator = "ESCAPE";
int mnemonic = KeyCode.VK_C;
},
NULL,
new JMenuItem {
String text = "Exit";
String command = "exit";
String accelerator = "control shift Q";
int mnemonic = KeyCode.VK_X;
actionPerformed(ActionEvent e) {
exit(0);
}
},
};
},
new JMenu {
String text = "Edit";
Array items = {
new JMenuItem {
String text = "Save";
String command = "save";
String accelerator = "control S";
int type = CHECKBOX_BUTTON;
},
new JMenuItem {
String text = "Save As...";
String command = "save_as";
String accelerator = "ctrl V";
},
};
},
};
};
JFrame f = {
JMenuBar menubar = menubar;
GridLayout layoutmanager = {
int rows = 1;
};
Array layout = {
new JButton {
String text = "Toggle MenuBar";
actionPerformed(e) {
if (root.menubar == NULL)
root.menubar = global.menubar;
else root.menubar = NULL;
}
},
new JButton {
String text = "Show MenuBar";
actionPerformed(e) {
root.menubar = global.menubar;
}
},
new JButton {
String text = "Hide MenuBar";
actionPerformed(e) {
root.menubar = NULL;
}
},
};
actionPerformed(e) {
printf("actionPerformed Received: %O\n", e);
}
itemStateChanged(e) {
printf("itemStateChanged Received: %O\n", e);
}
};
f.visible = TRUE;
is very similar to the example program in the
JMenuBar
documentation, except that it sets
items
using an array of
JMenuItem
objects rather than the
Menu
description that was used in the
JMenuBar
example.
Note that both
actionPerformed
event handlers receive the exit request.
| | |
| See Also: |
appendText,
BevelBorder,
Border,
ButtonGroup,
EmptyBorder,
EtchedBorder,
invokeLater,
JButton,
JCanvas,
JCheckBox,
JCheckBoxMenuItem,
JChoice,
JColorChooser,
JComboBox,
JDesktopPane,
JDialog,
JFileChooser,
JFileDialog,
JFrame,
JInternalFrame,
JLabel,
JLayeredPane,
JList,
JMenu,
JMenuBar,
JPanel,
JPasswordField,
JPopupMenu,
JProgressBar,
JRadioButton,
JRadioButtonMenuItem,
JScrollBar,
JScrollPane,
JSeparator,
JSlider,
JSplitPane,
JTabbedPane,
JTable,
JTextArea,
JTextCanvas,
JTextField,
JTextPane,
JTextTerm,
JToggleButton,
JToolBar,
JTree,
JWindow,
LineBorder,
MatteBorder,
Menu,
postEvent,
SoftBevelBorder,
TransferHandler
|
|