AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs
JMenuItem typedict
 
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

 

Yoix is a registered trademark of AT&T Inc.