KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > nextapp > echo2 > app > Extent


1 /*
2  * This file is part of the Echo Web Application Framework (hereinafter "Echo").
3  * Copyright (C) 2002-2005 NextApp, Inc.
4  *
5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
6  *
7  * The contents of this file are subject to the Mozilla Public License Version
8  * 1.1 (the "License"); you may not use this file except in compliance with
9  * the License. You may obtain a copy of the License at
10  * http://www.mozilla.org/MPL/
11  *
12  * Software distributed under the License is distributed on an "AS IS" basis,
13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
14  * for the specific language governing rights and limitations under the
15  * License.
16  *
17  * Alternatively, the contents of this file may be used under the terms of
18  * either the GNU General Public License Version 2 or later (the "GPL"), or
19  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
20  * in which case the provisions of the GPL or the LGPL are applicable instead
21  * of those above. If you wish to allow use of your version of this file only
22  * under the terms of either the GPL or the LGPL, and not to allow others to
23  * use your version of this file under the terms of the MPL, indicate your
24  * decision by deleting the provisions above and replace them with the notice
25  * and other provisions required by the GPL or the LGPL. If you do not delete
26  * the provisions above, a recipient may use your version of this file under
27  * the terms of any one of the MPL, the GPL or the LGPL.
28  */

29
30 package nextapp.echo2.app;
31 import java.io.Serializable JavaDoc;
32
33 /**
34  * A representation of a linear distance with units. <code>Extent</code>
35  * objects are immutable once constructed.
36  * <p>
37  * <strong>WARNING:</strong> Many <code>Component</code>s will have
38  * <code>Extent</code>-based properties that allow only certain types of
39  * units. Make certain to verify the API specification of any
40  * <code>Component</code> to ensure that you are using <code>Extent</code>s
41  * correctly with it. The <code>Extent</code>-based <code>getXXX()</code>
42  * and <code>setXXX()</code> property methods of a <code>Component</code>
43  * will explain what types of <code>Extent</code>s are allowed.
44  */

45 public class Extent
46 implements Comparable JavaDoc, Serializable JavaDoc {
47     
48     /**
49      * Adds one <code>Extent</code> to another, returning the sum as a new
50      * <code>Extent</code>. Null is returned if the <code>Extent</code>s have
51      * incompatible units. If either provided <code>Extent</code> is null, the
52      * other is returned.
53      *
54      * @param a the first <code>Extent</code>
55      * @param b the second <code>Extent</code>
56      * @return the sum of the <code>Extent</code>s, if calculable
57      */

58     public static Extent add(Extent a, Extent b) {
59         if (a == null) {
60             return b;
61         }
62         if (b == null) {
63             return a;
64         }
65         if (a.getUnits() == b.getUnits()) {
66             return new Extent(a.getValue() + b.getValue(), a.getUnits());
67         }
68         if (a.isPrint() && b.isPrint()) {
69             if (a.isEnglish() && b.isEnglish()) {
70                 return new Extent(a.toPoint() + b.toPoint(), PT);
71             }
72             return new Extent(a.toMm() + b.toMm(), MM);
73         }
74         return null;
75     }
76     
77     /**
78      * Validates that the specified <code>Extent</code> is acceptable for use
79      * in a particular environment, by ensuring that its units are of a
80      * supported type.
81      *
82      * @param value the <code>Extent</code> to validate
83      * @param validUnits a bitmask containing one or more of the unit constants
84      * (multiple unit constants may be ORed together)
85      * @throws IllegalArgumentException if the <code>Extent</code> is invalid
86      */

87     public static void validate(Extent value, int validUnits) {
88         if (value != null && (value.getUnits() & validUnits) == 0) {
89             throw new IllegalArgumentException JavaDoc("Specified units are unsupported in this context.");
90         }
91     }
92
93     /**
94      * Pixel units.
95      */

96     public static final int PX = 1;
97     
98     /**
99      * Percentage units.
100      */

101     public static final int PERCENT = 2;
102         
103     /**
104      * Points (1pt = 1/72in).
105      */

106     public static final int PT = 4;
107     
108     /**
109      * Centimeter units.
110      */

111     public static final int CM = 8;
112     
113     /**
114      * Millimeter units.
115      */

116     public static final int MM = 16;
117     
118     /**
119      * Inch units.
120      */

121     public static final int IN = 32;
122     
123     /**
124      * Em units (height of font).
125      */

126     public static final int EM = 64;
127     
128     /**
129      * Ex units (height of character 'x' in font).
130      */

131     public static final int EX = 128;
132     
133     /**
134      * Picas (1pc = 12pt)
135      */

136     public static final int PC = 256;
137     
138     
139     private int value;
140     private int units;
141     
142     /**
143      * Creates a new <code>Extent</code> with pixel units.
144      *
145      * @param value the value of the extent in pixels
146      */

147     public Extent(int value) {
148         this.value = value;
149         this.units = Extent.PX;
150     }
151     
152     /**
153      * Creates a new <code>Extent</code>.
154      *
155      * @param value the value of the extent
156      * @param units the units of the value, one of the following constants:
157      * <ul>
158      * <li><code>PC</code>: Pixels</li>
159      * <li><code>PERCENT</code>: Percent (of size of containing
160      * component)</li>
161      * <li><code>PT</code>: Points</li>
162      * <li><code>CM</code>: Centimeters</li>
163      * <li><code>MM</code>: Millimeters</li>
164      * <li><code>IN</code>: Inches</li>
165      * <li><code>EM</code>: Ems (height of 'M' character)</li>
166      * <li><code>EX</code>: Exs (height of 'x' character)</li>
167      * <li><code>PC</code>: Picas</li>
168      * </ul>
169      */

170     public Extent(int value, int units) {
171         this.value = value;
172         this.units = units;
173     }
174     
175     /**
176      * @see java.lang.Comparable#compareTo(java.lang.Object)
177      */

178     public int compareTo(Object JavaDoc o) {
179         Extent that = (Extent) o;
180         if (this.units == that.units) {
181             return this.value - that.value;
182         }
183         if (this.isPrint() && that.isPrint()) {
184             return this.toPoint() - that.toPoint();
185         }
186         return this.units - that.units;
187     }
188     
189     /**
190      * @see java.lang.Object#equals(java.lang.Object)
191      */

192     public boolean equals(Object JavaDoc o) {
193         if (this == o) {
194             return true;
195         } else if (o == null) {
196             return false;
197         } else if (o instanceof Extent) {
198             Extent that = (Extent) o;
199             return this.value == that.value && this.units == that.units;
200         } else {
201             return false;
202         }
203     }
204
205     /**
206      * Returns the value of the <code>Extent</code>.
207      *
208      * @return The value of the <code>Extent</code>
209      */

210     public int getValue() {
211         return value;
212     }
213     
214     /**
215      * Returns the units of the <code>Extent</code>.
216      *
217      * @return The units of the <code>Extent</code>, one of the following
218      * constants:
219      * <ul>
220      * <li><code>PC</code>: Pixels</li>
221      * <li><code>PERCENT</code>: Percent (of size of containing
222      * component)</li>
223      * <li><code>PT</code>: Points</li>
224      * <li><code>CM</code>: Centimeters</li>
225      * <li><code>MM</code>: Millimeters</li>
226      * <li><code>IN</code>: Inches</li>
227      * <li><code>EM</code>: Ems (height of 'M' character)</li>
228      * <li><code>EX</code>: Exs (height of 'x' character)</li>
229      * <li><code>PC</code>: Picas</li>
230      * </ul>
231      */

232     public int getUnits() {
233         return units;
234     }
235     
236     /**
237      * Determines whether this <code>Extent</code> can be compared to another
238      * <code>Extent</code> to determine which is a greater length.
239      *
240      * @param that the <code>Extent</code> to test comparability to
241      * @return true if the <code>Extent</code>s can be compared
242      */

243     public boolean isComparableTo(Extent that) {
244         return this.units == that.units || (this.isPrint() && that.isPrint());
245     }
246     
247     /**
248      * Determines if the <code>Extent</code> has English units, i.e., the
249      * units are of type <code>IN</code> (inches), <code>PC</code> (picas), or
250      * <code>PT</code> (points).
251      *
252      * @return true if this <code>Extent</code> has English units
253      */

254     public boolean isEnglish() {
255         return units == IN || units == PC || units == PT;
256     }
257
258     /**
259      * Determines if the <code>Extent</code> has SI (Metric) units, i.e., the
260      * units are of type <code>MM</code> (millimeters) or <code>CM</code>
261      * (centimeters).
262      *
263      * @return true if this <code>Extent</code> has SI units
264      */

265     public boolean isSI() {
266         return units == MM || units == CM;
267     }
268     
269     /**
270      * Determines if the <code>Extent</code> has percentage-based units.
271      *
272      * @return true if the <code>Extent</code> has percentage-based units
273      */

274     public boolean isPercentage() {
275         return units == PERCENT;
276     }
277     
278     /**
279      * Determines if this <code>Extent</code> has 'print' based units, i.e.,
280      * the units are in real dimensions, such as SI or English values, rather
281      * than screen-based units such as pixels or percentages.
282      *
283      * @return true if this <code>Extent</code> has 'print' based units
284      */

285     public boolean isPrint() {
286         return units == IN || units == PC || units == PT || units == MM || units == CM;
287     }
288     
289     /**
290      * Returns the value of the extent in millimeters.
291      *
292      * @return the value of the extent in millimeters
293      * @throws IllegalStateException if the value cannot be returned in
294      * millimeters.
295      * Verify that <code>isPrint()</code> returns true to avoid
296      * potentially receiving this exception.
297      */

298     public int toMm() {
299         switch (units) {
300         case MM:
301             return value;
302         case CM:
303             return value * 10;
304         case IN:
305             return (int) (value * 25.4);
306         case PT:
307             return (int) ((value / 72) * 25.4);
308         case PC:
309             return (int) ((value / 6) * 25.4);
310         }
311         throw new IllegalStateException JavaDoc("Cannot convert to mm.");
312     }
313     
314     /**
315      * Returns the value of the extent in points.
316      *
317      * @return the value of the extent in points
318      * @throws IllegalStateException if the value cannot be returned in points
319      * (verify that <code>isPrint()</code> returns true to avoid
320      * potentially receiving this exception).
321      */

322     public int toPoint() {
323         switch (units) {
324         case PT:
325             return value;
326         case PC:
327             return value * 12;
328         case IN:
329             return value * 72;
330         case MM:
331             return (int) ((value / 25.4) * 72);
332         case CM:
333             return (int) ((value / 2.54) * 72);
334         }
335         throw new IllegalStateException JavaDoc("Cannot convert to pt.");
336     }
337     
338     /**
339      * Returns a string describing the state of the Extent.
340      * For debugging purposes only, do not rely on formatting.
341      *
342      * @see java.lang.Object#toString()
343      */

344     public String JavaDoc toString() {
345         StringBuffer JavaDoc out = new StringBuffer JavaDoc();
346         out.append(value);
347         switch (units) {
348         case Extent.CM:
349             out.append("cm");
350             break;
351         case Extent.EM:
352             out.append("em");
353             break;
354         case Extent.EX:
355             out.append("ex");
356             break;
357         case Extent.IN:
358             out.append("in");
359             break;
360         case Extent.MM:
361             out.append("mm");
362             break;
363         case Extent.PC:
364             out.append("pc");
365             break;
366         case Extent.PERCENT:
367             out.append("%");
368             break;
369         case Extent.PT:
370             out.append("pt");
371             break;
372         case Extent.PX:
373             out.append("px");
374             break;
375         }
376         return out.toString();
377     }
378 }
379
Popular Tags