8.2 Classes Menu and MenuItem - SWT: The Standard Widget Toolkit
|
< Day Day Up > |
|
8.2 Classes Menu and MenuItem8.2.1 Example
8.2.2 Menu and MenuItem Hierarchies
8.2.3 Menu Styles
8.2.4 Menu Events
8.2.5 MenuItem Styles
8.2.6 MenuItem Events
Menus are very common user interface elements used to display a list of choices. Menus are represented in SWT by the classes Menu and MenuItem.[9] Menus are not controls.[10]
There are three kinds of menus: Menu bars, also called main menus, are created using the SWT.BAR style and appear as part of the shell trimming[11] below the shell title. Drop-down menus,[12] sometimes called submenus or cascade menus, are created with the SWT.DROP_DOWN style. They are displayed when the user selects a menu item from the menu bar or an item from another menu that contains a drop-down indicator. Pop-up or context menus, created using the SWT.POP_UP style, are displayed when the user requests a menu in a control using the mouse or the keyboard.
One way to think about the relationship between the different kinds of menus is to consider that menu bars and pop-up menus are always the root of a containment hierarchy, composed of drop-down menus. This containment hierarchy is displayed whenever the user clicks on a menu item in the menu bar or requests a context menu. The MenuItem class is analogous to the Button and ToolItem classes, supporting similar creation styles and listeners. Like instances of the other "item" classes, menu items are automatically added when created and are positioned similarly in the children list of the parent, using the location constructor parameter. Menu items are removed from a menu when they are disposed. Like ToolItem and Button, instances of the MenuItem class support text and images. They also support separators and cascade items. A cascade item is a menu item that allows a drop-down menu to appear. Cascade items display the drop-down indicator. 8.2.7 Menu Items That Behave Like ButtonsThe MenuItem class supports styles and listeners similar to the ToolItem and Button classes. For example, check and radio menu items are provided using the styles SWT.CHECK and SWT.RADIO. Text and images, mnemonics, and enabling and disabling are supported using Button and ToolItem API naming conventions. Like buttons and tool items, menu items do not wrap their text or support more than one line of text. One interesting difference between MenuItem and the other "buttonlike" classes is that MenuItem supports accelerators and accelerator text.
8.2.8 Menu Items That Behave Like SeparatorsMenu items with the style SWT.SEPARATOR are used to reserve space between items in a menu. Sometimes the space is simply left blank between the items or an "etched line" is drawn. Even on the same operating system, the menu separator look can change between releases.[13]
8.2.9 Menu Items That Show Other MenusMenu items with the style SWT.CASCADE are used to connect menus together. When the user selects the menu item, a drop-down menu cascades into view. Drop-down menus are connected to the menu bar, pop-up menus, or other drop-down menus using setMenu().
8.2.10 Menu Items with AcceleratorsAccelerators are keyboard shortcuts that allow the user to invoke menu items using the keyboard instead of the mouse. The section Accelerators in the chapter The Keyboard describes accelerators in detail, so they will not be discussed here. 8.2.11 Main MenusTo create a main menu, you need to create a menu with the style SWT.BAR. You can create many different menu bars, but only one can be displayed at a time. The setMenuBar() method in class Shell is used to show the menu bar (see Setting the Menu Bar in the Class Shell). The following example program creates a shell and a menu bar with the classic "File" and "Edit" menus:
public static void main(String[] args) {
Display display = new Display();
Shell shell = new Shell(display);
Menu menuBar = new Menu(shell, SWT.BAR);
shell.setMenuBar(menuBar);
MenuItem fileItem = new MenuItem(menuBar, SWT.CASCADE);
fileItem.setText("File");
MenuItem editItem = new MenuItem(menuBar, SWT.CASCADE);
editItem.setText("Edit");
Menu fileMenu = new Menu(shell, SWT.DROP_DOWN);
fileItem.setMenu(fileMenu);
String [] fileStrings = {"New", "Close", "Exit"};
for (int i=0; i<fileStrings.length; i++) {
MenuItem item = new MenuItem(fileMenu, SWT.PUSH);
item.setText(fileStrings [i]);
}
Menu editMenu = new Menu(shell, SWT.DROP_DOWN);
String [] editStrings = {"Cut", "Copy", "Paste"};
editItem.setMenu(editMenu);
for (int i=0; i<editStrings.length; i++) {
MenuItem item = new MenuItem(editMenu, SWT.PUSH);
item.setText(editStrings [i]);
}
shell.pack();
shell.open();
while (!shell.isDisposed()) {
if (!display.readAndDispatch()) display.sleep();
}
display.dispose();
}
Although this example program is a good vehicle to show how menus and menu items are created and wired together, application programs that use menus generally do not create their menu items from an array of strings. This is because menu items, like tool items and buttons, need more properties than just text in order to be really useful in a program. 8.2.12 Pop-Up MenusTo create a pop-up menu, you create a menu with the style SWT.POP_UP. Pop-up menus can be displayed automatically by the control (using the method Control.setMenu()) when the user requests a menu or they can be displayed programmatically using the setVisible() method.
To show a menu at a particular location, setLocation() is used.
Note that if you are showing a pop-up menu using setVisible() and setLocation(), you need to show it at the right time and the right place. The mouse movements and keyboard sequence used to request a pop-up menu are platform-specific. If you guess wrong, your pop-up menus will frustrate the user. The easiest way to avoid this problem is to let SWT pop the menu up for you using Control.setMenu() or to implement the control event SWT.MenuDetect (see Detecting a Context Menu Request). The following example creates a pop-up menu and assigns it to a list control.
public static void main(String[] args) {
Display display = new Display();
Shell shell = new Shell(display);
List list = new List(shell, SWT.BORDER | SWT.V_SCROLL);
list.setItems(new String [] {"A", "B", "C", "D"});
list.setSize(200, 200);
Menu menu = new Menu(shell, SWT.POP_UP);
for (int i=0; i<8; i++) {
MenuItem item = new MenuItem(menu, SWT.PUSH);
item.setText("Item " + i);
}
list.setMenu(menu);
shell.pack();
shell.open();
while (!shell.isDisposed()) {
if (!display.readAndDispatch()) display.sleep();
}
display.dispose();
}
8.2.13 Index-Based Operations for MenusMenus provide a number of index and location operations that allow application programs to query items and indices from a menu.
8.2.14 Menu EventsSWT.Show (MenuEvent)Table 8.1 shows the show event for Menu.
The SWT.Show event (typed event MenuEvent) is sent whenever a pull-down or pop-up menu is shown. The happens when the user requests the menu or the application program makes the menu visible using setVisible(). Show events contain meaningful values in only the display, widget, and type fields. The SWT.Show event for Menu is one of the most useful events in SWT. It is often used to run the application code that enables or disables menu items. Because it occurs just before a menu is shown, modifications to the menu, including adding and removing menu items, are not visible to the user. The real benefit of SWT.Show is that it allows you to keep the code that maintains menu item state in one place. Without this event, the code would need to be distributed throughout your application in order to keep the menu up to date as state changes within your program. This kind of distributed code is error-prone. Note that you cannot use this approach for pull-down menus whose items contain accelerators. When the user types an accelerator, the menu is not shown, so SWT.Show will not be sent.The main disadvantage of using SWT.Show to update your menus is that the state of every menu item needs to be calculated, even if it has not changed since the last time the menu was shown. This is true because the menu item state is not maintained elsewhere in your program. If the application code that computes this state is slow, the user will be forced to wait for the menu to appear. Slow menus make the entire application appear to be slow. The following example program uses SWT.Show to enable and disable menu items that correspond to the selected items in a list. If an item is selected, it is enabled.
public static void main(String[] args) {
Display display = new Display();
Shell shell = new Shell(display);
final List list =
new List(shell, SWT.BORDER | SWT.MULTI);
for (int i=0; i<8; i++) list.add("Item " + i);
list.setSize(200, 200);
final Menu menu = new Menu(shell, SWT.POP_UP);
for (int i = 0; i < list.getItemCount(); i++) {
MenuItem item = new MenuItem(menu, SWT.PUSH);
item.setText(list.getItem(i));
}
list.setMenu(menu);
menu.addListener(SWT.Show, new Listener() {
public void handleEvent(Event event) {
MenuItem[] items = menu.getItems();
for (int i = 0; i < items.length; i++) {
MenuItem item = items[i];
item.setEnabled(list.isSelected(i));
}
}
});
shell.pack();
shell.open();
while (!shell.isDisposed()) {
if (!display.readAndDispatch()) display.sleep();
}
display.dispose();
}
SWT.Hide (MenuEvent)Table 8.2 shows the hide event for Menu.
The SWT.Hide event (typed event MenuEvent) is sent whenever the menu is hidden. The can happen when the user selects a menu item or dismisses the menu, or when the application program makes a menu invisible using setVisible(false). Hide events contain meaningful values in only the display, widget, and type fields. SWT.Help (HelpEvent)Table 8.3 shows the help event for Menu.
The SWT.Help event (typed event HelpEvent) is sent whenever the user asks for help in a widget. Typically, the <F1> key is used for help but some platforms, such as the Macintosh, have a dedicated Help key. If no help is found for the menu, the request is forwarded to the shell. Help events contain meaningful values in only the display, widget, and type fields. 8.2.15 MenuItem EventsSWT.Selection (SelectionEvent)The SWT.Selection event (typed event SelectionEvent) is sent whenever the user selects a menu item with the mouse or the keyboard. The event fields relevant during a selection event for a menu item are as follows.
The following code fragment prints "Menu item selected" when an item is selected.
item.addListener(SWT.Selection, new Listener() {
public void handleEvent(Event event) {
System.out.println("Menu item selected");
}
});
SWT.Arm (ArmEvent)Table 8.4 shows the arm event for Menu.
The SWT.Arm event (typed event ArmEvent) is sent whenever the user causes the menu item to draw highlighted but does not select the item. This can happen using either the mouse or the keyboard. Arm events contain meaningful values in only the display, widget, and type fields. Using SWT.Arm to Update a Status LineThe SWT.Arm event is often used to show a short help message in the status line of a window while the user browses through menu items without selecting them. Used in this capacity, it provides functionality that is analogous to tool tips. By itself, the SWT.Arm event is not particularly useful. It allows you to set the status line text when the item is armed but there is no obvious MenuItem event that can be used to clear the text when the user closes the last menu. Fortunately, the Menu event SWT.Hide can be used to do this. However, from inside the SWT.Hide event, it is not possible to tell the difference between a menu that is hidden because the user is dragging the mouse across the menu bar and the user closing the last menu on the menu bar. In the former case, the SWT.Hide from the menu happens before the SWT.Arm for the menu item. The solution is to use the Menu event SWT.Show to set the status line text, as well. The following example program uses SWT.Arm to implement a simple menu status line.
public static void main(String[] args) {
Display display = new Display();
Shell shell = new Shell(display);
FormLayout layout = new FormLayout();
shell.setLayout(layout);
final Label label = new Label(shell, SWT.BORDER);
Listener armListener = new Listener() {
public void handleEvent(Event event) {
MenuItem item = (MenuItem) event.widget;
label.setText(item.getText());
}
};
Listener showListener = new Listener() {
public void handleEvent(Event event) {
Menu menu = (Menu) event.widget;
MenuItem item = menu.getParentItem();
if (item != null) {
label.setText(item.getText());
}
}
};
Listener hideListener = new Listener() {
public void handleEvent(Event event) {
label.setText("");
}
};
FormData labelData = new FormData();
labelData.left = new FormAttachment(0);
labelData.right = new FormAttachment(100);
labelData.bottom = new FormAttachment(100);
label.setLayoutData(labelData);
Menu menuBar = new Menu(shell, SWT.BAR);
shell.setMenuBar(menuBar);
MenuItem fileItem = new MenuItem(menuBar, SWT.CASCADE);
fileItem.setText("File");
fileItem.addListener(SWT.Arm, armListener);
MenuItem editItem = new MenuItem(menuBar, SWT.CASCADE);
editItem.setText("Edit");
editItem.addListener(SWT.Arm, armListener);
Menu fileMenu = new Menu(shell, SWT.DROP_DOWN);
fileMenu.addListener(SWT.Hide, hideListener);
fileMenu.addListener(SWT.Show, showListener);
fileItem.setMenu(fileMenu);
String[] fileStrings = { "New", "Close", "Exit" };
for (int i = 0; i < fileStrings.length; i++) {
MenuItem item = new MenuItem(fileMenu, SWT.PUSH);
item.setText(fileStrings[i]);
item.addListener(SWT.Arm, armListener);
}
Menu editMenu = new Menu(shell, SWT.DROP_DOWN);
editMenu.addListener(SWT.Hide, hideListener);
editMenu.addListener(SWT.Show, showListener);
String[] editStrings = { "Cut", "Copy", "Paste" };
editItem.setMenu(editMenu);
for (int i = 0; i < editStrings.length; i++) {
MenuItem item = new MenuItem(editMenu, SWT.PUSH);
item.setText(editStrings[i]);
item.addListener(SWT.Arm, armListener);
}
shell.open();
while (!shell.isDisposed()) {
if (!display.readAndDispatch()) display.sleep();
}
display.dispose();
}
The result of running this code with the "Copy" menu item selected is shown in Figure 8.4. Figure 8.4.
SWT.Help (HelpEvent)Table 8.5 shows the help event for MenuItem.
The SWT.Help event (typed event HelpEvent) is sent whenever the user asks for help in a widget. Typically, the <F1> key is used for help but some platforms, such as the Macintosh, have a dedicated Help key. If no help is found in the menu item, the request is forwarded to the menu. Help events contain meaningful values in only the display, widget, and type fields. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
< Day Day Up > |
|