SLocation


1   /*******************************************************************************
2    * Copyright (c) 2005, 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  package org.eclipse.ui.internal.menus;
12  
13  import org.eclipse.jface.util.Util;
14  
15  /**
16   * <p>
17   * A location for a menu element. A location carries with it information about
18   * the group in which is should appear. The location can also specify a style of
19   * image to associate with the menu element and a mnemonic.
20   * </p>
21   * <p>
22   * Clients may instantiate this class, but must not extend.
23   * </p>
24   * <p>
25   * <strong>PROVISIONAL</strong>. This class or interface has been added as
26   * part of a work in progress. There is a guarantee neither that this API will
27   * work nor that it will remain the same. Please do not use this API without
28   * consulting with the Platform/UI team.
29   * </p>
30   * <p>
31   * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
32   * </p>
33   * 
34   * @since 3.2
35   */
36  public final class SLocation {
37  
38      /**
39       * The constant to use if there is no mnemonic for this location.
40       */
41      public static final char MNEMONIC_NONE = 0;
42  
43      /**
44       * The style of image to use in this location. This value may be
45       * <code>null</code> if the default image style should be used.
46       */
47      private final String   imageStyle;
48  
49      /**
50       * The mnemonic to use in this location. This value may be <code>null</code>.
51       */
52      private final char mnemonic;
53  
54      /**
55       * The ordering constraint for this menu element with respect to other menu
56       * elements. This value may be <code>null</code>.
57       */
58      private final SOrder ordering;
59  
60      /**
61       * The location element specifying the path for this location. This
62       * indicates which menu or tool bar this location indicates.
63       */
64      private final LocationElement path;
65  
66      /**
67       * Constructs a new instance of <code>SLocation</code> -- indicating that
68       * the item should appear at the top-level of the menu bar, with no mnemonic
69       * or ordering constraints.
70       */
71      public SLocation() {
72          this(new SBar());
73      }
74  
75      /**
76       * Constructs a new instance of <code>SLocation</code>.
77       * 
78       * @param path
79       *            The location element specifying the path for this location;
80       *            must not be null.
81       */
82      public SLocation(final LocationElement path) {
83          this(path, MNEMONIC_NONE);
84      }
85  
86      /**
87       * Constructs a new instance of <code>SLocation</code> that is the child
88       * of the given location with the given id appended to the path. The new
89       * location will have no ordering, mnemonic or image style. It will only
90       * have a path.
91       * 
92       * @param parent
93       *            The parent location to which the id should be appended; must
94       *            not be <code>null</code>.
95       * @param id
96       *            The identifier to append to the location; must not be
97       *            <code>null</code>.
98       */
99      public SLocation(final SLocation parent, final String   id) {
100         this(parent, id, MNEMONIC_NONE);
101     }
102     
103     /**
104      * Constructs a new instance of <code>SLocation</code> that is the child
105      * of the given location with the given id appended to the path. The new
106      * location will have no ordering, mnemonic or image style. It will only
107      * have a path.
108      * 
109      * @param parent
110      *            The parent location to which the id should be appended; must
111      *            not be <code>null</code>.
112      * @param id
113      *            The identifier to append to the location; must not be
114      *            <code>null</code>.
115      * @param mnemonic
116      *            The mnemonic to set
117      */
118     public SLocation(final SLocation parent, final String   id, final char mnemonic) {
119 
120         if (parent == null) {
121             throw new NullPointerException  ("The parent cannot be null"); //$NON-NLS-1$
122         }
123 
124         if (id == null) {
125             throw new NullPointerException  ("The id cannot be null"); //$NON-NLS-1$
126         }
127 
128         final LocationElement parentPath = parent.getPath();
129         final LocationElement childPath = parentPath.createChild(id);
130 
131         this.imageStyle = null;
132         this.mnemonic = mnemonic;
133         this.ordering = null;
134         this.path = childPath;
135     }
136 
137     /**
138      * Constructs a new instance of <code>SLocation</code>.
139      * 
140      * @param path
141      *            The location element specifying the path for this location;
142      *            must not be null.
143      * @param mnemonic
144      *            The mnemonic to use in this particular location. The mnemonic
145      *            should be translated. If there is no mnemonic, then send
146      *            <code>MNEMONIC_NONE</code>.
147      */
148     public SLocation(final LocationElement path, final char mnemonic) {
149         this(path, null, mnemonic);
150     }
151 
152     /**
153      * Constructs a new instance of <code>SLocation</code>.
154      * 
155      * @param path
156      *            The location element specifying the path for this location;
157      *            must not be null.
158      * @param ordering
159      *            The ordering constraints for this menu element with respect to
160      *            other menu elements. This value may be <code>null</code>.
161      */
162     public SLocation(final LocationElement path, final SOrder ordering) {
163         this(path, ordering, MNEMONIC_NONE);
164     }
165 
166     /**
167      * Constructs a new instance of <code>SLocation</code>.
168      * 
169      * @param path
170      *            The location element specifying the path for this location;
171      *            must not be null.
172      * @param ordering
173      *            The ordering constraint for this menu element with respect to
174      *            other menu elements. This value may be <code>null</code>.
175      * @param mnemonic
176      *            The mnemonic to use in this particular location. The mnemonic
177      *            should be translated. If there is no mnemonic, then send
178      *            <code>MNEMONIC_NONE</code>.
179      */
180     public SLocation(final LocationElement path, final SOrder ordering,
181             final char mnemonic) {
182         this(path, ordering, mnemonic, null);
183 
184     }
185 
186     /**
187      * Constructs a new instance of <code>SLocation</code>.
188      * 
189      * @param path
190      *            The location element specifying the path for this location;
191      *            must not be null.
192      * @param ordering
193      *            The ordering constraint for this menu element with respect to
194      *            other menu elements. This value may be <code>null</code>.
195      * @param mnemonic
196      *            The mnemonic to use in this particular location. The mnemonic
197      *            should be translated. If there is no mnemonic, then send
198      *            <code>MNEMONIC_NONE</code>.
199      * @param imageStyle
200      *            The style of image to use in this location. If this value is
201      *            <code>null</code>, then the default image style is used.
202      */
203     public SLocation(final LocationElement path, final SOrder ordering,
204             final char mnemonic, String   imageStyle) {
205         if ((imageStyle != null) && (imageStyle.length() == 0)) {
206             imageStyle = null;
207         }
208 
209         if (path == null) {
210             throw new NullPointerException  (
211                     "The path for a location must not be null"); //$NON-NLS-1$
212         }
213 
214         this.mnemonic = mnemonic;
215         this.imageStyle = imageStyle;
216         this.ordering = ordering;
217         this.path = path;
218     }
219 
220     /**
221      * Returns the image style for this location.
222      * 
223      * @return The image style. If the default image style, then
224      *         <code>null</code>.
225      */
226     public final String   getImageStyle() {
227         return imageStyle;
228     }
229 
230     /**
231      * Returns the mnemonic for this location. The mnemonic should be
232      * translated.
233      * 
234      * @return The mnemonic. If no mnemonic, then <code>MNEMONIC_NONE</code>.
235      */
236     public final char getMnemonic() {
237         return mnemonic;
238     }
239 
240     /**
241      * Returns the ordering for this location.
242      * 
243      * @return The ordering. If no ordering, then <code>null</code>.
244      */
245     public final SOrder getOrdering() {
246         return ordering;
247     }
248 
249     /**
250      * Returns the path for this location element.
251      * 
252      * @return The path; never <code>null</code>.
253      */
254     public final LocationElement getPath() {
255         return path;
256     }
257 
258     public final String   toString() {
259         final StringBuffer   buffer = new StringBuffer  ();
260         buffer.append("SLocation("); //$NON-NLS-1$
261         buffer.append(path);
262         buffer.append(',');
263         if (mnemonic != MNEMONIC_NONE) {
264             buffer.append(mnemonic);
265             buffer.append(',');
266         }
267         buffer.append(imageStyle);
268         buffer.append(',');
269         buffer.append(ordering);
270         buffer.append(')');
271         return buffer.toString();
272     }
273 
274     /* (non-Javadoc)
275      * @see java.lang.Object#equals(java.lang.Object)
276      */
277     public boolean equals(Object   obj) {
278         if (this == obj) {
279             return true;
280         }
281         if (obj instanceof SLocation) {
282             SLocation loc = (SLocation) obj;
283             return path.equals(loc.path) && mnemonic == loc.mnemonic
284                     && Util.equals(ordering, loc.ordering)
285                     && Util.equals(imageStyle, loc.imageStyle);
286         }
287         return false;
288     }
289 
290     /* (non-Javadoc)
291      * @see java.lang.Object#hashCode()
292      */
293     public int hashCode() {
294         return path.hashCode() + Util.hashCode(imageStyle)
295                 + Util.hashCode(ordering);
296     }
297 }
298
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags