001/* ComponentOrientation.java -- describes a component's orientation
002   Copyright (C) 2000, 2001, 2002 Free Software Foundation
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt;
040
041import java.io.Serializable;
042import java.util.Locale;
043import java.util.MissingResourceException;
044import 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 */
074public 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