| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to you under the Apache License, |
| Version 2.0 (the "License"); you may not use this file except in |
| compliance with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document id="menu-bars"> |
| <properties> |
| <title>Menu Bars</title> |
| </properties> |
| |
| <body> |
| <p> |
| Menu bars are generally used to provide convenient access to major application |
| features. They act as a repository for top-level hierarchical menus, keeping the menus |
| out of sight until they are needed. |
| </p> |
| |
| <p> |
| Like all other components, menu bars can actually be placed anywhere in an |
| application's user interface. However, they are most often located at the top of an |
| application's main window. Pivot provides framework-level support for simplifying the |
| task of defining a menu bar positioned in this way. The <tt>Frame</tt> class defines |
| a "menuBar" property that is handled specially by the application using the |
| <tt>configureMenuBar()</tt> and <tt>cleanupMenuBar()</tt> methods of the |
| <tt>MenuHandler</tt> interface. These methods are called by the framework as the focus |
| changes within a window, to allow the application to customize the contents of the menu |
| bar based on the currently focused component. |
| </p> |
| |
| <p> |
| Note that for a keystroke to be processed (for example assigned to a Menu Item), |
| a component must have the focus to receive the key event and propagate it up the component hierarchy. |
| So, make sure that the window's content contains a focusable component, like a TextInput or PushButton. |
| </p> |
| |
| <p> |
| The example application below shows a menu bar containing two common top-level menu |
| items: "File" and "Edit" (note that the applet is signed since it makes use of the |
| <tt>FileBrowserSheet</tt> component, which requires access to the local file system): |
| </p> |
| |
| <application class="org.apache.pivot.wtk.ScriptApplication" |
| width="640" height="480"> |
| <libraries signed="true"> |
| <library>core</library> |
| <library>wtk</library> |
| <library>wtk-terra</library> |
| <library>tutorials</library> |
| </libraries> |
| <startup-properties> |
| <src>/org/apache/pivot/tutorials/menus/menu_bars.bxml</src> |
| </startup-properties> |
| </application> |
| |
| <p> |
| Each sub-menu item is associated with an <tt>Action</tt> that is executed when the |
| item is selected. For example, the action attached to the "File > Open" menu item |
| simulates opening a document by showing a file browser sheet and adding a new tab to |
| the application's tab pane. Each component in the "document" has a menu handler |
| attached to it that configures the menu contents as appropriate for the current |
| selection. When a text input component has the focus, the "Paste" menu item is enabled. |
| If text is selected in the text input, the "Cut" and "Copy" menu items are also |
| enabled. |
| </p> |
| |
| <p> |
| The BXML source for this example is shown below. It creates the initial menu structure |
| as well as the tab pane that will host the simulated documents. It also defines a set |
| of "action mappings" in the root frame's "actionMappings" sequence. Action mappings |
| associate keystrokes with actions; when a keystroke matching an action in the sequence |
| is processed by the window, the action is invoked. Action mappings are often called |
| "keyboard shortcuts". |
| </p> |
| |
| <p> |
| Note that the actions in this example are associated with the "CMD" key. This is a |
| Pivot-specific, platform-independent modifier. It maps to the Control key (CTRL) |
| on Windows and Linux and the Command key (META) on Mac OS X: |
| </p> |
| |
| <source type="xml" location="org/apache/pivot/tutorials/menus/menu_bars.bxml"> |
| <![CDATA[ |
| <menus:MenuBars title="Menu Bars" maximized="true" |
| styles="{padding:{top:0, left:4, bottom:4, right:4}, showWindowControls:false}" |
| xmlns:bxml="http://pivot.apache.org/bxml" |
| xmlns:content="org.apache.pivot.wtk.content" |
| xmlns:menus="org.apache.pivot.tutorials.menus" |
| xmlns="org.apache.pivot.wtk"> |
| <bxml:define> |
| <FileBrowserSheet bxml:id="fileBrowserSheet"/> |
| </bxml:define> |
| |
| <actionMappings> |
| <Window.ActionMapping action="fileNew" keyStroke="CMD-N"/> |
| <Window.ActionMapping action="fileOpen" keyStroke="CMD-O"/> |
| </actionMappings> |
| |
| <menuBar> |
| <MenuBar> |
| <MenuBar.Item buttonData="File"> |
| <Menu> |
| <Menu.Section> |
| <Menu.Item action="fileNew"> |
| <buttonData> |
| <content:MenuItemData text="New" keyboardShortcut="CMD-N"/> |
| </buttonData> |
| </Menu.Item> |
| |
| <Menu.Item action="fileOpen"> |
| <buttonData> |
| <content:MenuItemData text="Open" keyboardShortcut="CMD-O"/> |
| </buttonData> |
| </Menu.Item> |
| </Menu.Section> |
| </Menu> |
| </MenuBar.Item> |
| |
| <MenuBar.Item buttonData="Edit"> |
| <Menu> |
| <Menu.Section> |
| <Menu.Item action="cut"> |
| <buttonData> |
| <content:MenuItemData text="Cut" keyboardShortcut="CMD-X"/> |
| </buttonData> |
| </Menu.Item> |
| <Menu.Item action="copy"> |
| <buttonData> |
| <content:MenuItemData text="Copy" keyboardShortcut="CMD-C"/> |
| </buttonData> |
| </Menu.Item> |
| <Menu.Item action="paste"> |
| <buttonData> |
| <content:MenuItemData text="Paste" keyboardShortcut="CMD-V"/> |
| </buttonData> |
| </Menu.Item> |
| </Menu.Section> |
| </Menu> |
| </MenuBar.Item> |
| </MenuBar> |
| </menuBar> |
| |
| <Border styles="{backgroundColor:null, padding:2}"> |
| <TabPane bxml:id="tabPane"/> |
| </Border> |
| </menus:MenuBars> |
| ]]> |
| </source> |
| |
| <p> |
| The Java source for the example is shown below. In the constructor, the application's |
| actions are created and added to the global action dictionary. Note that, since the |
| BXML file refers to the actions by ID, it is essential that the actions be available |
| before the BXML is read. |
| </p> |
| |
| <source type="java" location="org/apache/pivot/tutorials/menus/MenuBars.java"> |
| <![CDATA[ |
| package org.apache.pivot.tutorials.menus; |
| |
| import java.io.IOException; |
| import java.net.URL; |
| |
| import org.apache.pivot.beans.BXML; |
| import org.apache.pivot.beans.BXMLSerializer; |
| import org.apache.pivot.beans.Bindable; |
| import org.apache.pivot.collections.Map; |
| import org.apache.pivot.serialization.SerializationException; |
| import org.apache.pivot.util.Resources; |
| import org.apache.pivot.wtk.Action; |
| import org.apache.pivot.wtk.Border; |
| import org.apache.pivot.wtk.Component; |
| import org.apache.pivot.wtk.FileBrowserSheet; |
| import org.apache.pivot.wtk.Frame; |
| import org.apache.pivot.wtk.MenuBar; |
| import org.apache.pivot.wtk.MenuHandler; |
| import org.apache.pivot.wtk.TabPane; |
| import org.apache.pivot.wtk.TextInput; |
| import org.apache.pivot.wtk.TextInputSelectionListener; |
| import org.apache.pivot.wtk.TextInputContentListener; |
| |
| public class MenuBars extends Frame implements Bindable { |
| @BXML private FileBrowserSheet fileBrowserSheet; |
| @BXML private TabPane tabPane = null; |
| |
| private MenuHandler menuHandler = new MenuHandler.Adapter() { |
| TextInputContentListener textInputTextListener = new TextInputContentListener.Adapter() { |
| @Override |
| public void textChanged(TextInput textInput) { |
| updateActionState(textInput); |
| } |
| }; |
| |
| TextInputSelectionListener textInputSelectionListener = new TextInputSelectionListener() { |
| @Override |
| public void selectionChanged(TextInput textInput, int previousSelectionStart, |
| int previousSelectionLength) { |
| updateActionState(textInput); |
| } |
| }; |
| |
| @Override |
| public void configureMenuBar(Component component, MenuBar menuBar) { |
| if (component instanceof TextInput) { |
| TextInput textInput = (TextInput)component; |
| |
| updateActionState(textInput); |
| Action.getNamedActions().get("paste").setEnabled(true); |
| |
| textInput.getTextInputContentListeners().add(textInputTextListener); |
| textInput.getTextInputSelectionListeners().add(textInputSelectionListener); |
| } else { |
| Action.getNamedActions().get("cut").setEnabled(false); |
| Action.getNamedActions().get("copy").setEnabled(false); |
| Action.getNamedActions().get("paste").setEnabled(false); |
| } |
| } |
| |
| @Override |
| public void cleanupMenuBar(Component component, MenuBar menuBar) { |
| if (component instanceof TextInput) { |
| TextInput textInput = (TextInput)component; |
| textInput.getTextInputContentListeners().remove(textInputTextListener); |
| textInput.getTextInputSelectionListeners().remove(textInputSelectionListener); |
| } |
| } |
| |
| private void updateActionState(TextInput textInput) { |
| Action.getNamedActions().get("cut").setEnabled(textInput.getSelectionLength() > 0); |
| Action.getNamedActions().get("copy").setEnabled(textInput.getSelectionLength() > 0); |
| } |
| }; |
| |
| public MenuBars() { |
| Action.getNamedActions().put("fileNew", new Action() { |
| @Override |
| public void perform(Component source) { |
| BXMLSerializer bxmlSerializer = new BXMLSerializer(); |
| bxmlSerializer.getNamespace().put("menuHandler", menuHandler); |
| |
| Component tab; |
| try { |
| tab = new Border((Component)bxmlSerializer.readObject(MenuBars.class, "document.bxml")); |
| } catch (IOException exception) { |
| throw new RuntimeException(exception); |
| } catch (SerializationException exception) { |
| throw new RuntimeException(exception); |
| } |
| |
| tabPane.getTabs().add(tab); |
| TabPane.setTabData(tab, "Document " + tabPane.getTabs().getLength()); |
| tabPane.setSelectedIndex(tabPane.getTabs().getLength() - 1); |
| } |
| }); |
| |
| Action.getNamedActions().put("fileOpen", new Action() { |
| @Override |
| public void perform(Component source) { |
| fileBrowserSheet.open(MenuBars.this); |
| } |
| }); |
| |
| Action.getNamedActions().put("cut", new Action(false) { |
| @Override |
| public void perform(Component source) { |
| TextInput textInput = (TextInput)MenuBars.this.getFocusDescendant(); |
| textInput.cut(); |
| } |
| }); |
| |
| Action.getNamedActions().put("copy", new Action(false) { |
| @Override |
| public void perform(Component source) { |
| TextInput textInput = (TextInput)MenuBars.this.getFocusDescendant(); |
| textInput.copy(); |
| } |
| }); |
| |
| Action.getNamedActions().put("paste", new Action(false) { |
| @Override |
| public void perform(Component source) { |
| TextInput textInput = (TextInput)MenuBars.this.getFocusDescendant(); |
| textInput.paste(); |
| } |
| }); |
| } |
| |
| @Override |
| public void initialize(Map<String, Object> namespace, URL location, Resources resources) { |
| } |
| } |
| ]]> |
| </source> |
| |
| <p> |
| The class also defines an anonymous inner implementation of the <tt>MenuHandler</tt> |
| interface that is used to configure the menu bar based on the focused component. In |
| <tt>configureMenuBar()</tt>, the actions associated with the "cut", "copy", and "paste" |
| operations are enabled and disabled as appropriate. Listeners are also added to the |
| focused component (if it is a <tt>TextInput</tt>) to ensure that the action's state |
| accurately reflects the current selection. The listeners are removed in |
| <tt>cleanupMenuBar()</tt>, if necessary. |
| </p> |
| |
| <p> |
| Note that menu bar configuration via <tt>MenuHandler</tt> isn't limited to enabling or |
| disabling actions - new menu items can be dynamically created, menu item selection |
| state can be changed, etc. However, unlike context menus, the framework does not |
| automatically clean up any changes made to the menu bar. It is up to the application |
| to ensure that the menu bar remains in a consistent state using the |
| <tt>configureMenuBar()</tt> and <tt>cleanupMenuBar()</tt> methods. |
| </p> |
| </body> |
| </document> |
