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 import net.sf.jguiraffe.gui.builder.components.ComponentBuilderData;
19
20 /**
21 * <p>
22 * Definition of an interface for controlling popup menus that can be associated
23 * with GUI components.
24 * </p>
25 * <p>
26 * With this interface a platform-independent way of associating popup menus
27 * with specific UI elements can be realized. The basic idea is that the
28 * <code>{@link ActionManager}</code> interface provides the
29 * <code>registerPopupMenuHandler()</code> method for associating an object
30 * implementing this interface with a UI element. This will cause a
31 * platform-specific event handler being registered at said element, which
32 * listens for gestures bringing up a context menu. When such a gesture is
33 * detected the <code>PopupMenuHandler</code> is invoked passing in a
34 * <code>{@link PopupMenuBuilder}</code> implementation. Using this builder
35 * object the handler can create an arbitrary complex menu. It is especially
36 * free to adapt this menu to the current status of the application (it is
37 * completely up to the handler, which actions it adds to the menu; it can even
38 * add different actions on each invocation). When it calls the builder's
39 * <code>{@link PopupMenuBuilder#create()}</code> method the menu will be
40 * displayed. (The handler can also decide not to invoke <code>create()</code>;
41 * in this case no menu will be displayed.)
42 * </p>
43 *
44 * @author Oliver Heger
45 * @version $Id: PopupMenuHandler.java 205 2012-01-29 18:29:57Z oheger $
46 */
47 public interface PopupMenuHandler
48 {
49 /**
50 * Asks this handler to create a popup menu using the specified
51 * <code>PopupMenuBuilder</code>. An implementation can use the methods
52 * offered by the builder to create a menu with arbitrary actions and sub
53 * menus. On calling the builder's <code>create()</code> method the menu
54 * will be displayed. The <code>ComponentBuilderData</code> object is a
55 * source of all available information: through the <code>BeanContext</code>
56 * accessible through this object many important objects can be obtained
57 * including the current form or the <code>ActionStore</code>. So all
58 * actions required by the <code>PopupMenuHandler</code> should be reachable
59 * through this object.
60 *
61 * @param builder the builder for creating the menu
62 * @param compData the current <code>ComponentBuilderData</code> object
63 * providing access to lots of context information
64 * @throws FormActionException if an error occurs when creating the menu
65 */
66 void constructPopup(PopupMenuBuilder builder, ComponentBuilderData compData)
67 throws FormActionException;
68 }