SPartMenuLayout


1   /*******************************************************************************
2    * Copyright (c) 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   ******************************************************************************/
11  
12  package org.eclipse.ui.internal.menus;
13  
14  import java.util.Collection  ;
15  import java.util.HashMap  ;
16  import java.util.Iterator  ;
17  import java.util.Map  ;
18  
19  import org.eclipse.core.commands.common.NotDefinedException;
20  
21  /**
22   * <p>
23   * A menu layout that includes the bars and the context menus.
24   * </p>
25   * <p>
26   * Clients must not instantiate, and must not extend.
27   * </p>
28   * <p>
29   * <strong>PROVISIONAL</strong>. This class or interface has been added as
30   * part of a work in progress. There is a guarantee neither that this API will
31   * work nor that it will remain the same. Please do not use this API without
32   * consulting with the Platform/UI team.
33   * </p>
34   * <p>
35   * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
36   * </p>
37   * 
38   * @since 3.2
39   */
40  class SPartMenuLayout {
41  
42      /**
43       * <p>
44       * Each character in this string represents a path delimiter that is
45       * understood by this layout class when parsing paths. This can be passed
46       * directly to a string tokenizer for parsing, or the first character can be
47       * used for programmatically generating paths.
48       * </p>
49       * <p>
50       * The character "<code>/</code>" is guaranteed to be a path delimiter.
51       * </p>
52       */
53      public static final String   PATH_DELIMITERS = "/"; //$NON-NLS-1$
54  
55      /**
56       * Inserts a particular path into a map. The layout is represented by a
57       * nesting structure of maps.
58       * 
59       * @param element
60       *            The element to insert into the node; must not be
61       *            <code>null</code>.
62       * @param location
63       *            The location at which the element is to be inserted; may be
64       *            <code>null</code>.
65       * @param locationElement
66       *            The element containining the path at which element should be
67       *            inserted; must not be <code>null</code>.
68       * @param node
69       *            The top-level node representing the layout; must not be
70       *            <code>null</code>.
71       * @throws NotDefinedException
72       *             If the given menu element is not defined.
73       */
74      protected static final void insertElementIntoNode(
75              final MenuElement element, final SLocation location,
76              final LeafLocationElement locationElement, LayoutNode node)
77              throws NotDefinedException {
78          final ILocationElementTokenizer tokenizer = locationElement
79                  .getTokenizer();
80          while (tokenizer.hasMoreTokens()) {
81              final LocationElementToken token = tokenizer.nextToken();
82              node = node.getChildNode(token);
83          }
84  
85          node.createChildNode(element, location);
86      }
87  
88      /**
89       * The top-level bars for this menu layout, indexed by type ({@link String}).
90       * Each bar is represented by a top-level {@link LayoutNode} with no menu
91       * element. Never <code>null</code>.
92       */
93      private final Map   barsByType;
94  
95      /**
96       * The menu layout for the context menus, indexed by the context menu
97       * identifiers ({@link String}). Each menu is represented by a top-level
98       * {@link LayoutNode} with no menu element. Never <code>null</code>.
99       */
100     private final Map   popupsById;
101 
102     /**
103      * Constructs a new instance of <code>SMenuLayout</code>.
104      */
105     protected SPartMenuLayout() {
106         this.barsByType = new HashMap  ();
107         this.popupsById = new HashMap  ();
108     }
109 
110     /**
111      * Adds an entry into one of the top-level bars. A bar can be a menu bar, a
112      * tool bar, or a status line.
113      * 
114      * @param element
115      *            The element to insert into the node; must not be
116      *            <code>null</code>.
117      * @param location
118      *            The location at which the element is to be inserted; may be
119      *            <code>null</code>.
120      * @param bar
121      *            The location in a bar; must not be <code>null</code>.
122      * @throws NotDefinedException
123      *             If the given menu element is not defined.
124      */
125     protected final void addBar(final MenuElement element,
126             final SLocation location, final SBar bar)
127             throws NotDefinedException {
128         final String   type = bar.getType();
129         LayoutNode node = (LayoutNode) barsByType.get(type);
130         if (node == null) {
131             node = new LayoutNode();
132             barsByType.put(type, node);
133         }
134         insertElementIntoNode(element, location, bar, node);
135     }
136 
137     /**
138      * Adds an entry into a popup menu.
139      * 
140      * @param element
141      *            The element to insert into the popup; must not be
142      *            <code>null</code>.
143      * @param location
144      *            The location at which the element is to be inserted; may be
145      *            <code>null</code>.
146      * @param popup
147      *            The popup indicator; must not be <code>null</code>.
148      * @throws NotDefinedException
149      *             If the given menu element is not defined.
150      */
151     protected final void addPopup(final MenuElement element,
152             final SLocation location, final SPopup popup)
153             throws NotDefinedException {
154         final String   popupId = popup.getId();
155         LayoutNode node = (LayoutNode) popupsById.get(popupId);
156         if (node == null) {
157             node = new LayoutNode();
158             popupsById.put(popupId, node);
159         }
160         insertElementIntoNode(element, location, popup, node);
161     }
162 
163     /**
164      * <p>
165      * Returns the layout node representing the root of the bar of the given
166      * type.
167      * </p>
168      * 
169      * @param type
170      *            The type of the bar to retrieve; should not be
171      *            <code>null</code>.
172      * @return The layout node corresponding to the type; <code>null</code> if
173      *         there are no bars of that type, or if that bar is currently
174      *         empty.
175      * @see {@link #getMenuBar()}
176      */
177     public final ILayoutNode getBar(final String   type) {
178         return (ILayoutNode) barsByType.get(type);
179     }
180 
181     /**
182      * <p>
183      * Returns the layout node representing the root of the menu bar.
184      * </p>
185      * 
186      * @return The root menu bar layout node; may be <code>null</code> if
187      *         there are no items in the menu bar.
188      */
189     public final ILayoutNode getMenuBar() {
190         return (ILayoutNode) barsByType.get(SBar.TYPE_MENU);
191     }
192 
193     /**
194      * Returns the bars indexed by type. Generally, a bar will be a menu bar, a
195      * tool bar or a status line.
196      * 
197      * @return The map of bar nodes ({@link LayoutNode} indexed by type; never
198      *         <code>null</code>;
199      */
200     protected final Map   getBarsByType() {
201         return barsByType;
202     }
203 
204     /**
205      * Returns the popup menus indexed by identifiers.
206      * 
207      * @return The map of context menu nodes ({@link LayoutNode}) indexed by
208      *         context menu identifier.
209      */
210     protected final Map   getPopupsById() {
211         return popupsById;
212     }
213 
214     /**
215      * This is a debugging method for printing node information. The method is
216      * recursive.
217      * 
218      * @param node
219      *            The node which should be printed (along with its children) to
220      *            the buffer; must not be <code>null</code>
221      * @param buffer
222      *            The buffer to which to print; must not be <code>null</code>.
223      * @param indent
224      *            The identation level for the node; must be a whole number.
225      */
226     protected final void printNode(final LayoutNode node,
227             final StringBuffer   buffer, final int indent) {
228         for (int i = 0; i < indent; i++) {
229             buffer.append(' ');
230         }
231         buffer.append(node.getMenuElement());
232         buffer.append('\n');
233         final Collection   children = node.getChildrenSorted();
234         final Iterator   childItr = children.iterator();
235         while (childItr.hasNext()) {
236             final LayoutNode childNode = (LayoutNode) childItr.next();
237             printNode(childNode, buffer, indent + 2);
238         }
239     }
240 
241     /**
242      * Prints out some debugging information about the entire menu layout. This
243      * information is quite large.
244      */
245     public String   toString() {
246         final StringBuffer   buffer = new StringBuffer  ();
247         Iterator   entryItr;
248 
249         // Print out the bars.
250         buffer.append("   ___ top-level bars ___ \n"); //$NON-NLS-1$
251         entryItr = getBarsByType().entrySet().iterator();
252         while (entryItr.hasNext()) {
253             final Map.Entry   entry = (Map.Entry  ) entryItr.next();
254             final String   type = (String  ) entry.getKey();
255             buffer.append(' ');
256             buffer.append(' ');
257             buffer.append(type);
258             buffer.append('\n');
259             LayoutNode node = (LayoutNode) entry.getValue();
260             printNode(node, buffer, 4);
261         }
262 
263         // Print out the context menus.
264         buffer.append("   ___ context menus ___ \n"); //$NON-NLS-1$
265         entryItr = getPopupsById().entrySet().iterator();
266         while (entryItr.hasNext()) {
267             final Map.Entry   entry = (Map.Entry  ) entryItr.next();
268             final String   id = (String  ) entry.getKey();
269             buffer.append(' ');
270             buffer.append(' ');
271             buffer.append(id);
272             buffer.append('\n');
273             LayoutNode node = (LayoutNode) entry.getValue();
274             printNode(node, buffer, 4);
275         }
276 
277         return buffer.toString();
278     }
279 }
280
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags