|
1 /* |
|
2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: This class is a placeholder of utility methods. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 package com.nokia.mid.ui; |
|
21 |
|
22 import javax.microedition.lcdui.Graphics; |
|
23 import javax.microedition.lcdui.Image; |
|
24 import javax.microedition.lcdui.Font; |
|
25 |
|
26 /** |
|
27 * This class is a placeholder of utility methods. It contains |
|
28 * methods for converting standard lcdui classes to Nokia UI classes |
|
29 * and vice versa, and method for creating Image out of ARGB pixel |
|
30 * array, creating empty transparent or specific |
|
31 * background colored images, creating mutable image from encoded |
|
32 * image byte array. |
|
33 * |
|
34 * @see javax.microedition.lcdui.Graphics |
|
35 * @see com.nokia.mid.ui.DirectGraphics |
|
36 * @see javax.microedition.lcdui.Canvas |
|
37 * @see com.nokia.mid.ui.DirectCanvas |
|
38 * @version 0.11 |
|
39 * @since 1.0 |
|
40 */ |
|
41 public class DirectUtils |
|
42 { |
|
43 |
|
44 private DirectUtils() |
|
45 { |
|
46 } |
|
47 |
|
48 /** |
|
49 * Converts standard javax.microedition.lcdui.Graphics to DirectGraphics. The |
|
50 * returned Graphics context is the same, e.g. calling draw operations |
|
51 * via original Graphics reference affect the DirectGraphics context |
|
52 * and vice versa. Note that eventhough the graphics context is the same |
|
53 * the returned object reference may or may not be the same as passed. |
|
54 * This means that purely casting Graphics (g) passed in paint of lcdui |
|
55 * Canvas to DirectGraphics may not work ok. The safe way is to always |
|
56 * do the conversion with this method. |
|
57 * |
|
58 * @return the DirectGraphics object based on Graphics |
|
59 * @param g Graphics object for which DirectGraphics should be returned |
|
60 * @since 1.0 |
|
61 */ |
|
62 |
|
63 public static DirectGraphics getDirectGraphics(Graphics aG) |
|
64 { |
|
65 return com.nokia.mid.ui.DirectGraphicsInvoker.getDirectGraphics(aG); |
|
66 } |
|
67 |
|
68 /** |
|
69 * Creates a mutable image which is decoded from the data stored |
|
70 * in the specified byte array at the specified offset and length. |
|
71 * The data must be in a self-identifying image file format |
|
72 * supported by the implementation, such as PNG. |
|
73 * <p> |
|
74 * Note that the semantics of this method are exactly the same |
|
75 * as |
|
76 * {@link javax.microedition.lcdui.Image#createImage(byte[],int,int)} |
|
77 * except that the returned image is mutable. |
|
78 * |
|
79 * @param imageData the array of image data in a supported image format |
|
80 * @param imageOffset the offset of the start of the data in the array |
|
81 * @param imageLength the length of the data in the array |
|
82 * @return the created mutable image |
|
83 * @throws ArrayIndexOutOfBoundsException if imageOffset and |
|
84 * imageLength specify an invalid range |
|
85 * @throws NullPointerException if imageData is null |
|
86 * @throws IllegalArgumentException if imageData is incorrectly |
|
87 * formatted or otherwise cannot be decoded |
|
88 * @see javax.microedition.lcdui.Image#createImage(byte[],int,int) |
|
89 * @since 1.0 |
|
90 */ |
|
91 public static Image createImage(byte[] aImageData, int aImageOffset, |
|
92 int aImageLength) |
|
93 { |
|
94 Image source = Image.createImage(aImageData, aImageOffset, aImageLength); |
|
95 Image copy = Image.createImage(source.getWidth(), source.getHeight()); |
|
96 DirectGraphics dg = getDirectGraphics(copy.getGraphics()); |
|
97 DirectGraphicsInvoker.setColorValues(dg, 0x00FFFFFF, copy); |
|
98 dg.drawImage(source, 0, 0, 0, 0); |
|
99 return copy; |
|
100 } |
|
101 |
|
102 /** |
|
103 * <p> |
|
104 * The method will return a newly created mutable Image with specified |
|
105 * dimension with all pixels of an image of defined ARGB color. The color |
|
106 * can contain alpha channel transparency information. |
|
107 * </p> |
|
108 * |
|
109 * @param width the width of the new image, in pixels |
|
110 * @param height the height of the new image, in pixels |
|
111 * @return the created image |
|
112 * @throws IllegalArgumentException if either width or height is |
|
113 * zero or less |
|
114 * @since 1.0 |
|
115 */ |
|
116 public static Image createImage(int aWidth, int aHeight, int aColor) |
|
117 { |
|
118 Image result = Image.createImage(aWidth, aHeight); |
|
119 DirectGraphics dg = getDirectGraphics(result.getGraphics()); |
|
120 DirectGraphicsInvoker.setColorValues(dg, aColor, result); |
|
121 return result; |
|
122 } |
|
123 |
|
124 /** |
|
125 * <p> |
|
126 * The method returns new instance of {@link javax.microedition.lcdui.Font} |
|
127 * with custom font height. System provides a font that matches |
|
128 * the requested attributes as closely as possible. |
|
129 * </p> |
|
130 * <p> |
|
131 * Font created in this way can be used only for Graphics instance |
|
132 * (Canvas, CustomItem, Image). This font is not supported |
|
133 * for high-level UI components (ChoiceGroup, StringItem and List). |
|
134 * If font with custom height is set to some high-level component, it's |
|
135 * replaced by default font. |
|
136 * </p> |
|
137 * <p> |
|
138 * Actual font height could be affected by system limitations, there may be |
|
139 * a maximum height defined by the system. |
|
140 * </p> |
|
141 * |
|
142 * @param face one of FACE_SYSTEM, FACE_MONOSPACE, or FACE_PROPORTIONAL |
|
143 * @param style STYLE_PLAIN, or a combination of STYLE_BOLD, STYLE_ITALIC, |
|
144 * and STYLE_UNDERLINED |
|
145 * @param height font height in pixels |
|
146 * @return new instance of Font |
|
147 * @throws IllegalArgumentException if height is negative, if face or style |
|
148 * are not legal values |
|
149 * @since 1.2 |
|
150 */ |
|
151 public static Font getFont(int face, int style, int height) |
|
152 { |
|
153 return com.nokia.mid.ui.FreeSizeFontInvoker.getFont(face, style, height); |
|
154 } |
|
155 } |