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  ;
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  , Serializable   {
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  ("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   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   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  ("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  ("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   toString() {
345         StringBuffer   out = new StringBuffer  ();
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags