001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program 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 version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.lcdui;
028:
029: /**
030: * The <code>Font</code> class represents fonts and font
031: * metrics. <code>Fonts</code> cannot be
032: * created by applications. Instead, applications query for fonts
033: * based on
034: * font attributes and the system will attempt to provide a font that
035: * matches
036: * the requested attributes as closely as possible.
037: *
038: * <p> A <code>Font's</code> attributes are style, size, and face. Values for
039: * attributes must be specified in terms of symbolic constants. Values for
040: * the style attribute may be combined using the bit-wise
041: * <code>OR</code> operator,
042: * whereas values for the other attributes may not be combined. For example,
043: * the value </p>
044: *
045: * <p> <code>
046: * STYLE_BOLD | STYLE_ITALIC
047: * </code> </p>
048: *
049: * <p> may be used to specify a bold-italic font; however </p>
050: *
051: * <p> <code>
052: * SIZE_LARGE | SIZE_SMALL
053: * </code> </p>
054: *
055: * <p> is illegal. </p>
056: *
057: * <p> The values of these constants are arranged so that zero is valid for
058: * each attribute and can be used to specify a reasonable default font
059: * for the system. For clarity of programming, the following symbolic
060: * constants are provided and are defined to have values of zero: </p>
061: *
062: * <p> <ul>
063: * <li> <code> STYLE_PLAIN </code> </li>
064: * <li> <code> SIZE_MEDIUM </code> </li>
065: * <li> <code> FACE_SYSTEM </code> </li>
066: * </ul> </p>
067: *
068: * <p> Values for other attributes are arranged to have disjoint bit patterns
069: * in order to raise errors if they are inadvertently misused (for example,
070: * using <code>FACE_PROPORTIONAL</code> where a style is
071: * required). However, the values
072: * for the different attributes are not intended to be combined with each
073: * other. </p>
074: * @since MIDP 1.0
075: */
076:
077: public final class Font {
078:
079: /**
080: * The plain style constant. This may be combined with the
081: * other style constants for mixed styles.
082: *
083: * <P>Value <code>0</code> is assigned to <code>STYLE_PLAIN</code>.</P>
084: */
085: public static final int STYLE_PLAIN = 0;
086:
087: /**
088: * The bold style constant. This may be combined with the
089: * other style constants for mixed styles.
090: *
091: * <P>Value <code>1</code> is assigned to <code>STYLE_BOLD</code>.</P>
092: */
093: public static final int STYLE_BOLD = 1;
094:
095: /**
096: * The italicized style constant. This may be combined with
097: * the other style constants for mixed styles.
098: *
099: * <P>Value <code>2</code> is assigned to <code>STYLE_ITALIC</code>.</P>
100: */
101: public static final int STYLE_ITALIC = 2;
102:
103: /**
104: * The underlined style constant. This may be combined with
105: * the other style constants for mixed styles.
106: *
107: * <P>Value <code>4</code> is assigned to <code>STYLE_UNDERLINED</code>.</P>
108: */
109: public static final int STYLE_UNDERLINED = 4;
110:
111: /**
112: * The "small" system-dependent font size.
113: *
114: * <P>Value <code>8</code> is assigned to <code>STYLE_SMALL</code>.</P>
115: */
116: public static final int SIZE_SMALL = 8;
117:
118: /**
119: * The "medium" system-dependent font size.
120: *
121: * <P>Value <code>0</code> is assigned to <code>STYLE_MEDIUM</code>.</P>
122: */
123: public static final int SIZE_MEDIUM = 0;
124:
125: /**
126: * The "large" system-dependent font size.
127: *
128: * <P>Value <code>16</code> is assigned to <code>SIZE_LARGE</code>.</P>
129: */
130: public static final int SIZE_LARGE = 16;
131:
132: /**
133: * The "system" font face.
134: *
135: * <P>Value <code>0</code> is assigned to <code>FACE_SYSTEM</code>.</P>
136: */
137: public static final int FACE_SYSTEM = 0;
138:
139: /**
140: * The "monospace" font face.
141: *
142: * <P>Value <code>32</code> is assigned to <code>FACE_MONOSPACE</code>.</P>
143: */
144: public static final int FACE_MONOSPACE = 32;
145:
146: /**
147: * The "proportional" font face.
148: *
149: * <P>Value <code>64</code> is assigned to
150: * <code>FACE_PROPORTIONAL</code>.</P>
151: */
152: public static final int FACE_PROPORTIONAL = 64;
153:
154: /**
155: * Default font specifier used to draw Item and Screen contents.
156: *
157: * <code>FONT_STATIC_TEXT</code> has the value <code>0</code>.
158: *
159: * @see #getFont(int fontSpecifier)
160: */
161: public static final int FONT_STATIC_TEXT = 0;
162:
163: /**
164: * Font specifier used by the implementation to draw text input by
165: * a user.
166: *
167: * <code>FONT_INPUT_TEXT</code> has the value <code>1</code>.
168: *
169: * @see #getFont(int fontSpecifier)
170: */
171: public static final int FONT_INPUT_TEXT = 1;
172:
173: /**
174: * Gets the <code>Font</code> used by the high level user interface
175: * for the <code>fontSpecifier</code> passed in. It should be used
176: * by subclasses of
177: * <code>CustomItem</code> and <code>Canvas</code> to match user
178: * interface on the device.
179: *
180: * @param fontSpecifier one of <code>FONT_INPUT_TEXT</code>, or
181: * <code>FONT_STATIC_TEXT</code>
182: * @return font that corresponds to the passed in font specifier
183: * @throws IllegalArgumentException if <code>fontSpecifier</code> is not
184: * a valid fontSpecifier
185: */
186: public static Font getFont(int fontSpecifier) {
187:
188: Font font;
189:
190: switch (fontSpecifier) {
191: case FONT_STATIC_TEXT:
192: case FONT_INPUT_TEXT:
193: font = getDefaultFont();
194: break;
195: default:
196: throw new IllegalArgumentException();
197: }
198: return font;
199: }
200:
201: /**
202: * Construct a new Font object
203: *
204: * @param inp_face The face to use to construct the Font
205: * @param inp_style The style to use to construct the Font
206: * @param inp_size The point size to use to construct the Font
207: */
208: private Font(int inp_face, int inp_style, int inp_size) {
209: face = inp_face;
210: style = inp_style;
211: size = inp_size;
212:
213: init(inp_face, inp_style, inp_size);
214: }
215:
216: /**
217: * Gets the default font of the system.
218: * @return the default font
219: */
220: public static Font getDefaultFont() {
221: synchronized (Display.LCDUILock) {
222: if (DEFAULT_FONT == null)
223: DEFAULT_FONT = new Font(FACE_SYSTEM, STYLE_PLAIN,
224: SIZE_MEDIUM);
225: return DEFAULT_FONT;
226: }
227: }
228:
229: /**
230: * Obtains an object representing a font having the specified face, style,
231: * and size. If a matching font does not exist, the system will
232: * attempt to provide the closest match. This method <em>always</em>
233: * returns
234: * a valid font object, even if it is not a close match to the request.
235: *
236: * @param inp_face one of <code>FACE_SYSTEM</code>,
237: * <code>FACE_MONOSPACE</code>, or <code>FACE_PROPORTIONAL</code>
238: * @param inp_style <code>STYLE_PLAIN</code>, or a combination of
239: * <code>STYLE_BOLD</code>,
240: * <code>STYLE_ITALIC</code>, and <code>STYLE_UNDERLINED</code>
241: * @param inp_size one of <code>SIZE_SMALL</code>, <code>SIZE_MEDIUM</code>,
242: * or <code>SIZE_LARGE</code>
243: * @return instance the nearest font found
244: * @throws IllegalArgumentException if <code>face</code>,
245: * <code>style</code>, or <code>size</code> are not
246: * legal values
247: */
248: public static Font getFont(int inp_face, int inp_style, int inp_size) {
249: if ((inp_face != FACE_SYSTEM) && (inp_face != FACE_MONOSPACE)
250: && (inp_face != FACE_PROPORTIONAL)) {
251: throw new IllegalArgumentException("Unsupported face");
252: }
253:
254: if ((inp_style & ((STYLE_UNDERLINED << 1) - 1)) != inp_style) {
255: throw new IllegalArgumentException("Illegal style");
256: }
257:
258: if ((inp_size != SIZE_SMALL) && (inp_size != SIZE_MEDIUM)
259: && (inp_size != SIZE_LARGE)) {
260: throw new IllegalArgumentException("Unsupported size");
261: }
262:
263: synchronized (Display.LCDUILock) {
264: /* IMPL_NOTE: this makes garbage. But hashtables need Object keys. */
265: Integer key = new Integer(inp_face | inp_style | inp_size);
266: Font f = (Font) table.get(key);
267: if (f == null) {
268: f = new Font(inp_face, inp_style, inp_size);
269: table.put(key, f);
270: }
271:
272: return f;
273: }
274: }
275:
276: /**
277: * Gets the style of the font. The value is an <code>OR'ed</code>
278: * combination of
279: * <code>STYLE_BOLD</code>, <code>STYLE_ITALIC</code>, and
280: * <code>STYLE_UNDERLINED</code>; or the value is
281: * zero (<code>STYLE_PLAIN</code>).
282: * @return style of the current font
283: *
284: * @see #isPlain()
285: * @see #isBold()
286: * @see #isItalic()
287: */
288: public int getStyle() {
289: // SYNC NOTE: return of atomic value, no locking necessary
290: return style;
291: };
292:
293: /**
294: * Gets the size of the font.
295: *
296: * @return one of <code>SIZE_SMALL</code>, <code>SIZE_MEDIUM</code>,
297: * <code>SIZE_LARGE</code>
298: */
299: public int getSize() {
300: // SYNC NOTE: return of atomic value, no locking necessary
301: return size;
302: }
303:
304: /**
305: * Gets the face of the font.
306: *
307: * @return one of <code>FACE_SYSTEM</code>,
308: * <code>FACE_PROPORTIONAL</code>, <code>FACE_MONOSPACE</code>
309: */
310: public int getFace() {
311: // SYNC NOTE: return of atomic value, no locking necessary
312: return face;
313: }
314:
315: /**
316: * Returns <code>true</code> if the font is plain.
317: * @see #getStyle()
318: * @return <code>true</code> if font is plain
319: */
320: public boolean isPlain() {
321: // SYNC NOTE: return of atomic value, no locking necessary
322: return style == STYLE_PLAIN;
323: }
324:
325: /**
326: * Returns <code>true</code> if the font is bold.
327: * @see #getStyle()
328: * @return <code>true</code> if font is bold
329: */
330: public boolean isBold() {
331: // SYNC NOTE: return of atomic value, no locking necessary
332: return (style & STYLE_BOLD) == STYLE_BOLD;
333: }
334:
335: /**
336: * Returns <code>true</code> if the font is italic.
337: * @see #getStyle()
338: * @return <code>true</code> if font is italic
339: */
340: public boolean isItalic() {
341: // SYNC NOTE: return of atomic value, no locking necessary
342: return (style & STYLE_ITALIC) == STYLE_ITALIC;
343: }
344:
345: /**
346: * Returns <code>true</code> if the font is underlined.
347: * @see #getStyle()
348: * @return <code>true</code> if font is underlined
349: */
350: public boolean isUnderlined() {
351: // SYNC NOTE: return of atomic value, no locking necessary
352: return (style & STYLE_UNDERLINED) == STYLE_UNDERLINED;
353: }
354:
355: /**
356: * Gets the standard height of a line of text in this font. This value
357: * includes sufficient spacing to ensure that lines of text painted this
358: * distance from anchor point to anchor point are spaced as intended by the
359: * font designer and the device. This extra space (leading) occurs below
360: * the text.
361: * @return standard height of a line of text in this font (a
362: * non-negative value)
363: */
364: public int getHeight() {
365: // SYNC NOTE: return of atomic value, no locking necessary
366: return height;
367: }
368:
369: /**
370: * Gets the distance in pixels from the top of the text to the text's
371: * baseline.
372: * @return the distance in pixels from the top of the text to the text's
373: * baseline
374: */
375: public int getBaselinePosition() {
376: // SYNC NOTE: return of atomic value, no locking necessary
377: return baseline;
378: }
379:
380: /**
381: * Gets the advance width of the specified character in this Font.
382: * The advance width is the horizontal distance that would be occupied if
383: * <code>ch</code> were to be drawn using this <code>Font</code>,
384: * including inter-character spacing following
385: * <code>ch</code> necessary for proper positioning of subsequent text.
386: *
387: * @param ch the character to be measured
388: * @return the total advance width (a non-negative value)
389: */
390: public native int charWidth(char ch);
391:
392: /**
393: * Returns the advance width of the characters in <code>ch</code>,
394: * starting at the specified offset and for the specified number of
395: * characters (length).
396: * The advance width is the horizontal distance that would be occupied if
397: * the characters were to be drawn using this <code>Font</code>,
398: * including inter-character spacing following
399: * the characters necessary for proper positioning of subsequent text.
400: *
401: * <p>The <code>offset</code> and <code>length</code> parameters must
402: * specify a valid range of characters
403: * within the character array <code>ch</code>. The <code>offset</code>
404: * parameter must be within the
405: * range <code>[0..(ch.length)]</code>, inclusive.
406: * The <code>length</code> parameter must be a non-negative
407: * integer such that <code>(offset + length) <= ch.length</code>.</p>
408: *
409: * @param ch the array of characters
410: * @param offset the index of the first character to measure
411: * @param length the number of characters to measure
412: * @return the width of the character range
413: * @throws ArrayIndexOutOfBoundsException if <code>offset</code> and
414: * <code>length</code> specify an
415: * invalid range
416: * @throws NullPointerException if <code>ch</code> is <code>null</code>
417: */
418: public native int charsWidth(char[] ch, int offset, int length);
419:
420: /**
421: * Gets the total advance width for showing the specified
422: * <code>String</code>
423: * in this <code>Font</code>.
424: * The advance width is the horizontal distance that would be occupied if
425: * <code>str</code> were to be drawn using this <code>Font</code>,
426: * including inter-character spacing following
427: * <code>str</code> necessary for proper positioning of subsequent text.
428: *
429: * @param str the <code>String</code> to be measured
430: * @return the total advance width
431: * @throws NullPointerException if <code>str</code> is <code>null</code>
432: */
433: public native int stringWidth(java.lang.String str);
434:
435: /**
436: * Gets the total advance width for showing the specified substring in this
437: * <code>Font</code>.
438: * The advance width is the horizontal distance that would be occupied if
439: * the substring were to be drawn using this <code>Font</code>,
440: * including inter-character spacing following
441: * the substring necessary for proper positioning of subsequent text.
442: *
443: * <p>
444: * The <code>offset</code> and <code>len</code> parameters must
445: * specify a valid range of characters
446: * within <code>str</code>. The <code>offset</code> parameter must
447: * be within the
448: * range <code>[0..(str.length())]</code>, inclusive.
449: * The <code>len</code> parameter must be a non-negative
450: * integer such that <code>(offset + len) <= str.length()</code>.
451: * </p>
452: *
453: * @param str the <code>String</code> to be measured
454: * @param offset zero-based index of first character in the substring
455: * @param len length of the substring
456: * @return the total advance width
457: * @throws StringIndexOutOfBoundsException if <code>offset</code> and
458: * <code>length</code> specify an
459: * invalid range
460: * @throws NullPointerException if <code>str</code> is <code>null</code>
461: */
462: public native int substringWidth(String str, int offset, int len);
463:
464: // private implementation //
465:
466: /** The face of this Font */
467: private int face;
468: /** The style of this Font */
469: private int style;
470: /** The point size of this Font */
471: private int size;
472: /** The baseline of this Font */
473: private int baseline;
474: /** The height of this Font */
475: private int height;
476:
477: /**
478: * The "default" font, constructed from the 'system' face,
479: * plain style, and 'medium' size point.
480: */
481: private static Font DEFAULT_FONT;
482:
483: /**
484: * A hashtable used to maintain a store of created Fonts
485: * so they are not re-created in the future
486: */
487: private static java.util.Hashtable table = new java.util.Hashtable(
488: 4);
489:
490: /**
491: * Natively initialize this Font object's peer
492: *
493: * @param inp_face The face to initialize the native Font
494: * @param inp_style The style to initialize the native Font
495: * @param inp_size The point size to initialize the native Font
496: */
497: private native void init(int inp_face, int inp_style, int inp_size);
498: }
|