The Yoix^® Scripting Language

Individual menuitems are constructed by walking through the Menu array looking at the next two, three, or four elements for the information needed to build the menuitem. The first element in the description of a new menuitem must be a string and usually is the text that appears on the menubar or in the menu that contains the menuitem. The exception is the string "-", which has special meaning when it is followed by NULL, and in that case it means add a separator (i.e., a thin horizontal line) to the menu. For example,

JFrame frame = {
    JMenuBar menubar = {
        Menu items = {
            "File", new Menu {
                "Open", NULL,
                "Close", "file_close",
                "-", NULL,
                "Quit", "file_quit",
            },
        };
    };
};

frame.visible = TRUE;

The second element in the description of a menuitem is more complicated because it can be a String, Menu, Array, Dictionary, or NULL. A String is assigned to the command field of the ActionEvent or the item field of the ItemEvent that is generated when the menuitem is selected. In our example file_close or file_quit would be passed along in the command field of the ActionEvent generated when Close or Quit is selected. A NULL value that is not associated with the special separator string "-" means the menuitem is disabled, which is what happens to Open in our example. A Menu or Array describes another menu, which is a pulldown menu if we are building the items in a JMenuBar or MenuBar, otherwise it will be a submenu of the menu that we are currently working on. Notice that this is how we created the pulldown menu associated with File in our example. A Dictionary exposes additional fields, like menu accelerators, and lets you collect everything, including things we have not discussed yet, in the second argument. We will provide more details and an example.

If the next element in the array is an integer then three elements describe a checkbox menuitem that has its initial state set to the value of that integer. For example,

JFrame frame = {
    JMenuBar menubar = {
        Menu items = {
            "File", new Menu {
                "Open", NULL,
                "Close", "file_close",
                "-", NULL,
                "Quit", "file_quit",
            },

            "Style", new Menu {
                "Enabled", "style_enabled", TRUE,
                "-", NULL,
                "Bars", "style_bars", "qwert", TRUE,
                "Points", "style_points", "qwert", FALSE,
            },
        };
    };
};

frame.visible = TRUE;

If neither the third or fourth element is an integer, then we are at the end of the Menu array or the next element must be a string that starts the description of a new menuitem. Either way the preceding two elements would completely described the last menuitem.

The following fields are supported by AWT and Swing menus when a Dictionary is supplied as the second argument in the definition of a menuitem:

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.
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.
enabled	An int that is 1 when the menuitem can respond to user input, and 0 when it can not.
group	A String that is the name of the group that contains this checkbox menuitem. Group names are arbitrary and only apply to the items in a particular menubar or popup menu. Defining group or state automatically creates a checkbox menuitem.
state	An int that is 1 when the checkbox menuitem is selected and 0 otherwise. Defining group or state automatically creates a checkbox menuitem.

If AWT and Swing compatibility is not an issue and you are only interested in building a Swing menu then many of the fields defined by JMenuItem fields can be initialized in the dictionary, however the behavior documented by JMenuItem may not always apply.

Selection of a regular menuitem generates an actionPerformed event, while selection of a checkbox menuitem generates an itemStateChanged event. The events are passed back to the event handler, either actionPerformed or itemStateChanged, that is defined in the component that actually owns the menu.

Example:	Here is an example import yoix.*.*; JFrame frame = { JMenuBar menubar = { Menu items = { "File", new Menu { "Open", new Dictionary { String command = "file_open"; String accelerator = "ctrl O"; int enabled = FALSE; }, "Close", new Dictionary { String command = "file_close"; String accelerator = "ESCAPE"; }, "-", NULL, "Quit", new Dictionary { String command = "file_quit"; String accelerator = "ctrl Q"; Color foreground = Color.red; // Swing only }, }, "Style", new Menu { "Enabled", new Dictionary { String command = "style_enabled"; int state = TRUE; }, "-", NULL, "Bars", new Dictionary { String command = "style_bars"; String group = "qwert"; int state = TRUE; }, "Points", new Dictionary { String command = "style_points"; String group = "qwert"; int state = FALSE; }, }, }; }; actionPerformed(Event e) { fprintf(stderr, "actionPerformed: e=%O\n", e); } itemStateChanged(Event e) { fprintf(stderr, "itemStateChanged: e=%O\n", e); } }; frame.visible = TRUE; that uses dictionaries, adds a few accelerators, and includes simple actionPerformed and itemStateChanged event handlers.
See Also:	JMenu, JMenuBar, JPopupMenu, MenuBar, PopupMenu