1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.action;
17
18 /**
19 * <p>
20 * A <em>builder</em> interface for creating popup menus.
21 * </p>
22 * <p>
23 * Using the methods defined in this interface arbitrary complex popup menus can
24 * be created. A popup menu consists of an arbitrary number of
25 * <code>{@link FormAction}</code> objects plus optional separators and sub
26 * menus. The basic usage pattern is to invoke the several <code>add()</code>
27 * methods for defining the menu's content. Finally the <code>create()</code>
28 * method must be called, which will actually create the menu.
29 * </p>
30 * <p>
31 * This interface provides a platform-independent view on popup menus. There
32 * will be concrete implementations for the GUI libraries supported. These
33 * implementations take care of creating the correct, platform-specific menu
34 * objects.
35 * </p>
36 * <p>
37 * As is common practice for builder-like structures this interface supports
38 * method chaining, i.e. most methods return a reference to the builder itself,
39 * which can be used for immediately adding the next element. The following
40 * example fragment shows how a popup menu with some items and a sub menu can be
41 * constructed. It assumes that the references to the actions involved are
42 * defined somewhere else:
43 *
44 * <pre>
45 * PopupMenuBuilder builder = ... // obtain the builder
46 *
47 * Object popup = builder
48 * .addAction(actionOpen)
49 * .addAction(actionSave)
50 * .addAction(actionSaveAs)
51 * .addSeparator()
52 * .addSubMenu(builder.subMenuBuilder(tiMenuEdit)
53 * .addAction(actionCopy)
54 * .addAction(actionCut)
55 * .addAction(actionPaste)
56 * .create())
57 * .addSeparator()
58 * .addAction(actionExit)
59 * .create();
60 * </pre>
61 *
62 * </p>
63 *
64 * @author Oliver Heger
65 * @version $Id: $
66 */
67 public interface PopupMenuBuilder
68 {
69 /**
70 * Adds an action to the current menu. This will create a menu item that
71 * invokes this action when it is selected by the user. The properties of
72 * this item (like text, icon, etc.) are obtained from the action object.
73 *
74 * @param action the action to be added (must not be <b>null</b>)
75 * @return a reference to this builder
76 * @throws IllegalArgumentException if the action is <b>null</b>
77 */
78 PopupMenuBuilder addAction(FormAction action);
79
80 /**
81 * Adds a separator to the current menu. Separators can be used for grouping
82 * related menu items.
83 *
84 * @return a reference to this builder
85 */
86 PopupMenuBuilder addSeparator();
87
88 /**
89 * Adds a sub menu to the current menu. This allows for complex structures
90 * of hierarchical menus. The object passed to this method must be a menu
91 * that was created by a sub menu builder.
92 *
93 * @param subMenu the sub menu to add (must not be <b>null</b>)
94 * @return a reference to this builder
95 * @throws IllegalArgumentException if the sub menu is <b>null</b>
96 * @see #subMenuBuilder(ActionData)
97 */
98 PopupMenuBuilder addSubMenu(Object subMenu);
99
100 /**
101 * Returns a builder for creating a sub menu. The builder returned by this
102 * method can be used to define the sub menu (i.e. add actions, separators,
103 * and further sub menus as desired). Its <code>create()</code> method
104 * returns the menu created. The passed in <code>ActionData</code> object
105 * contains the definition of the menu as it will be displayed in the parent
106 * menu (i.e. its text, icon, etc.).
107 *
108 * @param menuDesc an <code>ActionData</code> object with the properties of
109 * the sub menu (must not be <b>null</b>)
110 * @return a builder for defining the new sub menu
111 * @throws IllegalArgumentException if the menu description is <b>null</b>
112 */
113 PopupMenuBuilder subMenuBuilder(ActionData menuDesc);
114
115 /**
116 * Creates the menu and returns a reference to it. If this is the top-level
117 * builder (i.e. not a builder for a sub menu), the popup menu will be
118 * displayed.
119 *
120 * @return the menu created by this builder
121 */
122 Object create();
123 }