001    /* ComponentOrientation.java -- describes a component's orientation
002       Copyright (C) 2000, 2001, 2002 Free Software Foundation
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt;
040    
041    import java.io.Serializable;
042    import java.util.Locale;
043    import java.util.MissingResourceException;
044    import java.util.ResourceBundle;
045    
046    /**
047     * This class is used to differentiate different orientations for text layout.
048     * It controls whether text flows left-to-right or right-to-left, and whether
049     * lines are horizontal or vertical, as in this table:<br>
050     * <pre>
051     * LT      RT      TL      TR
052     * A B C   C B A   A D G   G D A
053     * D E F   F E D   B E H   H E B
054     * G H I   I H G   C F I   I F C
055     * </pre>
056     * <b>LT</b> languages are most common (left-to-right lines, top-to-bottom).
057     * This includes Western European languages, and optionally includes Japanese,
058     * Chinese, and Korean. <b>RT</b> languages (right-to-left lines,
059     * top-to-bottom) are mainly middle eastern, such as Hebrew and Arabic.
060     * <b>TR</b> languages flow top-to-bottom in a line, right-to-left, and are
061     * the basis of Japanese, Chinese, and Korean. Finally, <b>TL</b> languages
062     * flow top-to-bottom in a line, left-to-right, as in Mongolian.
063     *
064     * <p>This is a pretty poor excuse for a type-safe enum, since it is not
065     * guaranteed that orientation objects are unique (thanks to serialization),
066     * yet there is no equals() method. You would be wise to compare the output
067     * of isHorizontal() and isLeftToRight() rather than comparing objects with
068     * ==, especially since more constants may be added in the future.
069     *
070     * @author Bryce McKinlay (bryce@albatross.co.nz)
071     * @since 1.0
072     * @status updated to 1.4
073     */
074    public final class ComponentOrientation implements Serializable
075    {
076      /**
077       * Compatible with JDK 1.0+.
078       */
079      private static final long serialVersionUID = -4113291392143563828L;
080    
081      /** Constant for unknown orientation. */
082      private static final int UNKNOWN_ID = 1;
083    
084      /** Constant for horizontal line orientation. */
085      private static final int HORIZONTAL_ID = 2;
086    
087      /** Constant for left-to-right orientation. */
088      private static final int LEFT_TO_RIGHT_ID = 4;
089    
090      /**
091       * Items run left to right, and lines flow top to bottom. Examples: English,
092       * French.
093       */
094      public static final ComponentOrientation LEFT_TO_RIGHT
095        = new ComponentOrientation(HORIZONTAL_ID | LEFT_TO_RIGHT_ID);
096    
097      /**
098       * Items run right to left, and lines flow top to bottom. Examples: Arabic,
099       * Hebrew.
100       */
101      public static final ComponentOrientation RIGHT_TO_LEFT
102        = new ComponentOrientation(HORIZONTAL_ID);
103    
104      /**
105       * The orientation is unknown for the locale. For backwards compatibility,
106       * this behaves like LEFT_TO_RIGHT in the instance methods.
107       */
108      public static final ComponentOrientation UNKNOWN
109        = new ComponentOrientation(UNKNOWN_ID | HORIZONTAL_ID | LEFT_TO_RIGHT_ID);
110    
111      /**
112       * The orientation of this object; bitwise-or of unknown (1), horizontal (2),
113       * and left-to-right (4).
114       *
115       * @serial the orientation
116       */
117      private final int orientation;
118    
119      /**
120       * Construct a given orientation.
121       *
122       * @param orientation the orientation
123       */
124      private ComponentOrientation(int orientation)
125      {
126        this.orientation = orientation;
127      }
128    
129      /**
130       * Returns true if the lines are horizontal, in which case lines flow
131       * top-to-bottom. For example, English, Hebrew. Counterexamples: Japanese,
132       * Chinese, Korean, Mongolian.
133       *
134       * @return true if this orientation has horizontal lines
135       */
136      public boolean isHorizontal()
137      {
138        return (orientation & HORIZONTAL_ID) != 0;
139      }
140    
141      /**
142       * If isHorizontal() returns true, then this determines whether items in
143       * the line flow left-to-right. If isHorizontal() returns false, items in
144       * a line flow top-to-bottom, and this determines if lines flow
145       * left-to-right.
146       *
147       * @return true if this orientation flows left-to-right
148       */
149      public boolean isLeftToRight()
150      {
151        return (orientation & LEFT_TO_RIGHT_ID) != 0;
152      }
153    
154      /**
155       * Gets an orientation appropriate for the locale.
156       *
157       * @param locale the locale
158       * @return the orientation for that locale
159       * @throws NullPointerException if locale is null
160       */
161      public static ComponentOrientation getOrientation(Locale locale)
162      {
163        // Based on iterating over all languages defined in JDK 1.4, this behavior
164        // matches Sun's. However, it makes me wonder if any non-horizontal
165        // orientations even exist, as it sure contradicts their documentation.
166        String language = locale.getLanguage();
167        if ("ar".equals(language) || "fa".equals(language) || "iw".equals(language)
168            || "ur".equals(language))
169          return RIGHT_TO_LEFT;
170        return LEFT_TO_RIGHT;
171      }
172    
173      /**
174       * Gets an orientation from a resource bundle. This tries the following:
175       *
176       * <ul>
177       * <li>Use the key "Orientation" to find an instance of ComponentOrientation
178       * in the bundle.</li>
179       * <li>Get the locale of the resource bundle, and get the orientation of
180       * that locale.</li>
181       * <li>Give up and get the orientation of the default locale.</li>
182       * </ul>
183       *
184       * @param bdl the bundle to use
185       * @return the orientation
186       * @throws NullPointerException if bdl is null
187       * @deprecated use {@link #getOrientation(Locale)} instead
188       */
189      public static ComponentOrientation getOrientation(ResourceBundle bdl)
190      {
191        ComponentOrientation r;
192        try
193          {
194            r = (ComponentOrientation) bdl.getObject("Orientation");
195            if (r != null)
196              return r;
197          }
198        catch (MissingResourceException ignored)
199          {
200          }
201        catch (ClassCastException ignored)
202          {
203          }
204        try
205          {
206            r = getOrientation(bdl.getLocale());
207            if (r != null)
208              return r;
209          }
210        catch (Exception ignored)
211          {
212          }
213        return getOrientation(Locale.getDefault());
214      }
215    } // class ComponentOrientation