KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > internal > menus > SOrder


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  * An ordering for a location. This is the sort order with respect to other menu
18  * elements.
19  * </p>
20  * <p>
21  * Additional position constants may be added in the future.
22  * </p>
23  * <p>
24  * Clients may instantiate this class, but must not extend.
25  * </p>
26  * <p>
27  * <strong>PROVISIONAL</strong>. This class or interface has been added as
28  * part of a work in progress. There is a guarantee neither that this API will
29  * work nor that it will remain the same. Please do not use this API without
30  * consulting with the Platform/UI team.
31  * </p>
32  * <p>
33  * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
34  * </p>
35  *
36  * @since 3.2
37  */
38 public final class SOrder {
39
40     /**
41      * The constant to use if there is no position. This is useful for some
42      * algorithms involved collections of ordering constraints.
43      */
44     static final int NO_POSITION = -1;
45
46     /**
47      * The constant to use if the position for the location is the start of the
48      * current <code>IMenuCollection</code>.
49      */
50     public static final int POSITION_START = 0;
51
52     /**
53      * The constant to use if the position for the location is the end of the
54      * current <code>IMenuCollection</code>.
55      */
56     public static final int POSITION_END = 1;
57
58     /**
59      * The constant to use if the position for the location is to be before a
60      * menu element with a particular identifier.
61      */
62     public static final int POSITION_BEFORE = 2;
63
64     /**
65      * The constant to use if the position for the location is to be after a
66      * menu element with a particular identifier.
67      */
68     public static final int POSITION_AFTER = 3;
69
70     /**
71      * The position the menu element should be given relative to other menu
72      * elements. This should be one of the position constants given by this
73      * class.
74      */
75     private final int position;
76
77     /**
78      * The identifier of the menu element to which the position is relative.
79      * This value is <code>null</code> iff the position is not a relative
80      * position.
81      */
82     private final String JavaDoc relativeTo;
83
84     /**
85      * Constructs a new instance of <code>SOrder</code>. This ordering
86      * constraint can be either indicate the start or end. For relative
87      * positioning, use {@link SOrder#SOrder(int, String)}.
88      *
89      * @param position
90      * The position in which the menu element should appear with
91      * respect to other menu elements. This value should be one of
92      * the position constants defined in this class.
93      *
94      * @see SOrder#POSITION_END
95      * @see SOrder#POSITION_START
96      */
97     public SOrder(final int position) {
98         this(position, null);
99     }
100
101     /**
102      * Constructs a new instance of <code>SOrder</code>.
103      *
104      * @param position
105      * The position in which the menu element should appear with
106      * respect to other menu elements. This value should be one of
107      * the position constants defined in this class.
108      * @param relativeTo
109      * The identifier of the menu element to which the position is
110      * relative. This value is required if the position is
111      * <code>POSITION_AFTER</code> or <code>POSITION_BEFORE</code>.
112      * Otherwise, this value should be <code>null</code>.
113      *
114      * @see SOrder#POSITION_AFTER
115      * @see SOrder#POSITION_BEFORE
116      * @see SOrder#POSITION_END
117      * @see SOrder#POSITION_START
118      */
119     public SOrder(final int position, final String JavaDoc relativeTo) {
120         if ((position < POSITION_START) || (position > POSITION_AFTER)) {
121             throw new IllegalArgumentException JavaDoc(
122                     "A location needs a valid position. Got: " + position); //$NON-NLS-1$
123 }
124
125         if ((position == POSITION_AFTER) || (position == POSITION_BEFORE)) {
126             if (relativeTo == null) {
127                 throw new NullPointerException JavaDoc(
128                         "A location positioned before or after needs an identifier of the menu element to which the position is relative"); //$NON-NLS-1$
129 }
130         } else if (relativeTo != null) {
131             throw new IllegalArgumentException JavaDoc(
132                     "A relative identifier was provided for a non-relative position"); //$NON-NLS-1$
133 }
134
135         this.position = position;
136         this.relativeTo = relativeTo;
137     }
138
139     /**
140      * Returns the position for this location. The position will be one of the
141      * the position constants defined in this class. Additional position
142      * constants may be added in the future.
143      *
144      * @return The position.
145      */
146     public final int getPosition() {
147         return position;
148     }
149
150     /**
151      * Returns the identifier of the menu element to which this location is
152      * relative. There will only be such an identifier if the position is a
153      * relative positioning.
154      *
155      * @return The relative identifier. If the position is not relative, then
156      * <code>null</code>.
157      * @see SOrder#POSITION_AFTER
158      * @see SOrder#POSITION_BEFORE
159      */
160     public final String JavaDoc getRelativeTo() {
161         return relativeTo;
162     }
163
164     public final String JavaDoc toString() {
165         final StringBuffer JavaDoc buffer = new StringBuffer JavaDoc();
166         buffer.append("SOrder("); //$NON-NLS-1$
167 switch (position) {
168         case POSITION_AFTER:
169             buffer.append("after"); //$NON-NLS-1$
170 break;
171         case POSITION_BEFORE:
172             buffer.append("before"); //$NON-NLS-1$
173 break;
174         case POSITION_END:
175             buffer.append("end"); //$NON-NLS-1$
176 break;
177         case POSITION_START:
178             buffer.append("start"); //$NON-NLS-1$
179 break;
180         default:
181             buffer.append("unknown"); //$NON-NLS-1$
182 }
183         buffer.append(',');
184         buffer.append(relativeTo);
185         buffer.append(')');
186         return buffer.toString();
187     }
188
189     /* (non-Javadoc)
190      * @see java.lang.Object#equals(java.lang.Object)
191      */
192     public boolean equals(Object JavaDoc obj) {
193         if (this == obj) {
194             return true;
195         }
196         if (obj instanceof SOrder) {
197             SOrder order = (SOrder) obj;
198             return position == order.position
199                     && Util.equals(relativeTo, order.relativeTo);
200         }
201         return false;
202     }
203
204     /* (non-Javadoc)
205      * @see java.lang.Object#hashCode()
206      */
207     public int hashCode() {
208         return position + Util.hashCode(relativeTo);
209     }
210 }
211
Popular Tags