|
1 /* |
|
2 * Copyright (c) 2009 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: Public abstract class defining the |
|
15 * interface for MIDP Canvas Graphics Item. |
|
16 * |
|
17 */ |
|
18 |
|
19 package com.nokia.mid.ui; |
|
20 |
|
21 import java.util.Enumeration; |
|
22 import javax.microedition.lcdui.Canvas; |
|
23 import javax.microedition.lcdui.CustomItem; |
|
24 import javax.microedition.lcdui.Graphics; |
|
25 |
|
26 import com.nokia.mid.ui.CanvasItem; |
|
27 import com.nokia.mid.ui.CanvasGraphicsItemPainter; |
|
28 |
|
29 import com.nokia.mj.impl.rt.legacy.NativeError; |
|
30 import com.nokia.mj.impl.rt.legacy.ToolkitInvoker; |
|
31 import com.nokia.mj.impl.rt.support.Finalizer; |
|
32 |
|
33 /** |
|
34 * <P> |
|
35 * A <code>CanvasGraphicsItem</code> is a drawable component that is used with a |
|
36 * parent object; with <code>Canvas</code>. The <code>CanvasGraphicsItem</code> |
|
37 * may be added to and removed from <code>Canvas</code> through |
|
38 * <code>setParent</code> method. |
|
39 * </P> |
|
40 * |
|
41 * <P> |
|
42 * Parent for <code>CanvasGraphicsItem</code> must be set, through |
|
43 * <code>setParent</code> method, before other methods are called and change the |
|
44 * state or parameters of <code>CanvasGraphicsItem</code>. |
|
45 * </P> |
|
46 * |
|
47 * <P> |
|
48 * The implementation presents the <code>CanvasGraphicsItem</code> with the same |
|
49 * draw capabilities as <code>Canvas</code> has. See <a |
|
50 * href="Graphics.html">Graphics</a> for drawing options. |
|
51 * </P> |
|
52 * |
|
53 * <P> |
|
54 * <code>CanvasGraphicsItem</code> does not support DSA over its area. Playing |
|
55 * video or using camera over <code>CanvasGraphicsItem</code> area can lead to |
|
56 * artifacts on screen. |
|
57 * </P> |
|
58 * |
|
59 * <P> |
|
60 * <code>CanvasGraphicsItem</code> does not support touch input. Pointer events |
|
61 * are delivered to parent object from the area of the visible |
|
62 * <code>CanvasGraphicsItem</code>. |
|
63 * </P> |
|
64 * |
|
65 * <P> |
|
66 * Visibility of <code>CanvasGraphicsItem</code> is set through |
|
67 * <code>setVisible()</code>. The default visbility is set to false. Changing |
|
68 * parent does not affect the visibility status. |
|
69 * </P> |
|
70 * |
|
71 * <P> |
|
72 * The <code>CanvasGraphicsItem</code> cannot have focus. |
|
73 * </P> |
|
74 * |
|
75 * @since 1.4 |
|
76 */ |
|
77 public abstract class CanvasGraphicsItem |
|
78 extends CanvasItem |
|
79 { |
|
80 // Private data |
|
81 |
|
82 // Native handle |
|
83 int iHandle; |
|
84 |
|
85 // LCDUI Toolkit invoker object. |
|
86 ToolkitInvoker iToolkitInvoker; |
|
87 |
|
88 // LCDUI Toolkit object. |
|
89 Object iToolkit; |
|
90 |
|
91 //Object finalizer |
|
92 private Finalizer mFinalizer; |
|
93 |
|
94 private com.nokia.mid.ui.CanvasGraphicsItemPainter iItemPainter; |
|
95 |
|
96 /** |
|
97 * Creates a new <code>CanvasGraphicsItem</code> object with the given |
|
98 * initial size. |
|
99 * |
|
100 * @param width |
|
101 * width in pixels |
|
102 * @param height |
|
103 * height in pixels |
|
104 * |
|
105 * @throws IllegalArgumentException |
|
106 * if the width or height is less than one pixel |
|
107 */ |
|
108 public CanvasGraphicsItem(int width, int height) |
|
109 { |
|
110 // Validate width and height. |
|
111 if (!(width >= 1 && height >= 1)) |
|
112 { |
|
113 throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID); |
|
114 } |
|
115 |
|
116 // Toolkit invoker is needed for accessing javax.microedition.lcdui |
|
117 // package |
|
118 iToolkitInvoker = ToolkitInvoker.getToolkitInvoker(); |
|
119 iToolkit = iToolkitInvoker.getToolkit(); |
|
120 |
|
121 // Create painter |
|
122 iItemPainter = |
|
123 CanvasGraphicsItemPainterInvoker.createCanvasGraphicsItemPainter( |
|
124 this, iToolkit, width, height); |
|
125 |
|
126 int painterHandle = iItemPainter.getHandle(); |
|
127 |
|
128 int handle = 0; |
|
129 |
|
130 synchronized (iToolkit) |
|
131 { |
|
132 // Create native peer object for this Java object. |
|
133 handle = |
|
134 _createNativePeer(getToolkitHandle(), painterHandle, width, |
|
135 height); |
|
136 } |
|
137 |
|
138 // Check if construction failed and throw out of memory error. |
|
139 if (handle <= NativeError.KErrNone) |
|
140 { |
|
141 throw new OutOfMemoryError(); |
|
142 } |
|
143 |
|
144 // Operation was a success, store size. |
|
145 iWidth = width; |
|
146 iHeight = height; |
|
147 |
|
148 // Sets parent to null |
|
149 iParent = null; |
|
150 |
|
151 // Set visibility |
|
152 iVisible = false; |
|
153 |
|
154 // Construction was successful. Store handle and register for |
|
155 // finalization. |
|
156 iHandle = handle; |
|
157 |
|
158 mFinalizer = new Finalizer() |
|
159 { |
|
160 public void finalizeImpl() |
|
161 { |
|
162 registeredFinalize(); |
|
163 } |
|
164 }; |
|
165 } |
|
166 |
|
167 /** |
|
168 * Set the parent object of this <code>CanvasGraphicsItem</code>. |
|
169 * |
|
170 * Typically the parent object would be Canvas. Setting the parameter to |
|
171 * null removes the association to the parent. If |
|
172 * <code>setParent(null)</code> is called for a |
|
173 * <code>CanvasGraphicsItem</code> yet not having any parent or |
|
174 * <code>setParent(parent)</code> is called with the same parent, the call |
|
175 * is silently ignored. |
|
176 * |
|
177 * @param parent |
|
178 * the parent object |
|
179 * |
|
180 * @throws IllegalArgumentException |
|
181 * if <code>aParent</code> is not a valid object with which a |
|
182 * CanvasGraphicsItem can be associated, or if CanvasItem |
|
183 * is already set to another another parent |
|
184 */ |
|
185 public void setParent(java.lang.Object parent) |
|
186 { |
|
187 // Ignore argument check if parent is set to null. |
|
188 // Custom item support will be added in future, currently it's |
|
189 // unsupported. |
|
190 if (((parent != null) && !(parent instanceof Canvas)) || |
|
191 ((parent != null) && (iParent != null) && (iParent != parent))) |
|
192 { |
|
193 throw new IllegalArgumentException(ERROR_NOT_A_VALID_PARENT_OBJECT); |
|
194 } |
|
195 |
|
196 if (parent != iParent) |
|
197 { |
|
198 // Lock this object so that parent cannot be adjusted from other |
|
199 // threads. |
|
200 synchronized (iToolkit) |
|
201 { |
|
202 int parentHandle = 0; |
|
203 |
|
204 // Toolkit invoker can be used to get proper handles. |
|
205 if (parent instanceof Canvas) |
|
206 { |
|
207 // Note that canvas is shown inside a displayable so in this |
|
208 // case we use the handle to the displayble object. |
|
209 parentHandle = iToolkitInvoker.getDisplayableHandle(parent); |
|
210 } |
|
211 else if (parent instanceof CustomItem) |
|
212 { |
|
213 parentHandle = iToolkitInvoker.itemGetHandle(parent); |
|
214 } |
|
215 |
|
216 // parentHandle = 0 indicates removal of the parent. |
|
217 int error = |
|
218 _setParent(getToolkitHandle(), iHandle, parentHandle); |
|
219 |
|
220 // Check if an error occured when setting the parent object. |
|
221 NativeError.check(error); |
|
222 |
|
223 // Store new parent |
|
224 iParent = parent; |
|
225 } |
|
226 } |
|
227 } |
|
228 |
|
229 /** |
|
230 * Sets the size of this <code>CanvasGraphicsItem</code> in pixels. |
|
231 * |
|
232 * @param width |
|
233 * width in pixels |
|
234 * @param height |
|
235 * height in pixels |
|
236 * |
|
237 * @throws IllegalArgumentException |
|
238 * if the width or height is less than one pixel |
|
239 */ |
|
240 public void setSize(int width, int height) |
|
241 { |
|
242 // Validate width and row count |
|
243 if (width < 1 || height < 1) |
|
244 { |
|
245 throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID); |
|
246 } |
|
247 |
|
248 synchronized (iToolkit) |
|
249 { |
|
250 NativeError.check(_setSize(getToolkitHandle(), iHandle, width, |
|
251 height)); |
|
252 |
|
253 // Operation was a success, store size. |
|
254 iWidth = width; |
|
255 iHeight = height; |
|
256 } |
|
257 } |
|
258 |
|
259 /** |
|
260 * <P> |
|
261 * Sets the rendering position of this <code>CanvasGraphicsItem</code>. The |
|
262 * anchor point given is relative to the upper left corner of the target |
|
263 * <code>Canvas</code>. |
|
264 * </P> |
|
265 * |
|
266 * <P> |
|
267 * The <code>CanvasGraphicsItem</code> may be placed fully off or partially |
|
268 * of the visible area of the target <code>Canvas</code> by the |
|
269 * <code>setPosition</code> method; in this case the |
|
270 * <code>CanvasGraphicsItem</code> is just parly visible. |
|
271 * </P> |
|
272 * |
|
273 * @param x |
|
274 * the x coordinate of the anchor point, in pixels. |
|
275 * @param y |
|
276 * the y coordinate of the anchor point, in pixels. |
|
277 * |
|
278 * @throws IllegalStateException |
|
279 * if a valid parent object hasn't been set. |
|
280 * |
|
281 * @see #setParent(java.lang.Object aParent) |
|
282 */ |
|
283 public void setPosition(int x, int y) |
|
284 { |
|
285 synchronized (iToolkit) |
|
286 { |
|
287 checkParent(); |
|
288 |
|
289 NativeError.check(_setPosition(getToolkitHandle(), iHandle, x, y)); |
|
290 |
|
291 // Store current position. |
|
292 iPositionX = x; |
|
293 iPositionY = y; |
|
294 } |
|
295 } |
|
296 |
|
297 /** |
|
298 * <P> |
|
299 * Sets the visibility value of <code>CanvasGraphicsItem</code>. Initially |
|
300 * <code>CanvasGraphicsItem</code> is not visible so it must be explicitly |
|
301 * set to visible in order it to appear on UI. |
|
302 * </P> |
|
303 * |
|
304 * <P> |
|
305 * Setting visibility to true shows the graphics item with its content. If |
|
306 * the graphics item is already visible calling |
|
307 * <code>setVisible(true)</code> does nothing. |
|
308 * </P> |
|
309 * |
|
310 * <P> |
|
311 * Setting the visibility to false hides the graphics item and its content. |
|
312 * If the graphics item is already hidden calling |
|
313 * <code>setVisible(false)</code> does nothing. |
|
314 * </P> |
|
315 * |
|
316 * @param visible |
|
317 * visibility of the <code>CanvasGraphicsItem</code> |
|
318 * |
|
319 * @throws IllegalStateException |
|
320 * if a valid parent object has not been set. |
|
321 * |
|
322 * @see #setParent(java.lang.Object aParent) |
|
323 */ |
|
324 public void setVisible(boolean visible) |
|
325 { |
|
326 synchronized (iToolkit) |
|
327 { |
|
328 checkParent(); |
|
329 |
|
330 NativeError |
|
331 .check(_setVisible(getToolkitHandle(), iHandle, visible)); |
|
332 |
|
333 iVisible = visible; |
|
334 } |
|
335 } |
|
336 |
|
337 /** |
|
338 * <P> |
|
339 * Sets the Z-position (elevation) of the item. |
|
340 * <p> |
|
341 * The Z-position decides the stacking order of items on the same parent. An |
|
342 * item of higher Z-position will be drawn on top of an item with a lower |
|
343 * Z-position. |
|
344 * <p> |
|
345 * The Z-position is unique for each item, meaning that changing a |
|
346 * Z-position of an item may change the Z-position of the items that share |
|
347 * the same parent. The Z-position does not affect the item's size in any |
|
348 * way. |
|
349 * <p> |
|
350 * When items are added with {@link CanvasItem#setParent} they will get a |
|
351 * Z-position that is increased by 1 from the item that is the top most item |
|
352 * at that time. |
|
353 * </P> |
|
354 * |
|
355 * @param z |
|
356 * the Z-position of the item. |
|
357 * |
|
358 * @throws IllegalArgumentException |
|
359 * if <code>z</code> < 0 |
|
360 * @throws IllegalStateException |
|
361 * if a valid parent object has not been set. |
|
362 * |
|
363 * @see #getZPosition() |
|
364 * @see #setParent(java.lang.Object aParent) |
|
365 */ |
|
366 public void setZPosition(int z) |
|
367 { |
|
368 if (z < 0) |
|
369 { |
|
370 throw new IllegalArgumentException(); |
|
371 } |
|
372 |
|
373 synchronized (iToolkit) |
|
374 { |
|
375 checkParent(); |
|
376 |
|
377 NativeError.check(_setZPosition(getToolkitHandle(), iHandle, z)); |
|
378 } |
|
379 } |
|
380 |
|
381 /** |
|
382 * <P> |
|
383 * Returns the Z-position (elevation) of the item. |
|
384 * |
|
385 * @see #setZPosition(int) </P> |
|
386 * |
|
387 * @throws IllegalStateException |
|
388 * if a valid parent object has not been set. |
|
389 * |
|
390 * @see #setParent(java.lang.Object aParent) |
|
391 */ |
|
392 public int getZPosition() |
|
393 { |
|
394 int positionZ = -1; |
|
395 |
|
396 synchronized (iToolkit) |
|
397 { |
|
398 checkParent(); |
|
399 |
|
400 positionZ = _getZPosition(getToolkitHandle(), iHandle); |
|
401 } |
|
402 |
|
403 NativeError.check(positionZ); |
|
404 |
|
405 return positionZ; |
|
406 } |
|
407 |
|
408 /* |
|
409 * Hidden default constructor. |
|
410 */ |
|
411 CanvasGraphicsItem() |
|
412 { |
|
413 } |
|
414 |
|
415 /** |
|
416 * <P> |
|
417 * Renders the <code>CanvasGraphicsItem</code>. |
|
418 * <P> |
|
419 * The application implements this method to paint graphics on |
|
420 * <code>CanvasGraphicsItem</code>. |
|
421 * <P> |
|
422 * <code>CanvasGraphicsItem</code> paint works in the same way as |
|
423 * <code>Canvas</code> paint method. The only difference to |
|
424 * <code>Canvas</code> paint method is that application does not need to |
|
425 * paint all the pixels of the clip region as that the clip region needing |
|
426 * updating is cleared and fully transparent before paint is called. Content |
|
427 * rendered by application in previous paint method calls is not available |
|
428 * in the clip region. Coordinates used in <code>Graphics</code> methods are |
|
429 * relative to <code>CanvasGraphicsItem</code> itself. This means (0,0) |
|
430 * coordinate is top left pixel of <code>CanvasGraphicsItem</code> as |
|
431 * positioned in the containing parent (e.g. <code>Canvas</code>). |
|
432 * </P> |
|
433 * |
|
434 * @param graphics |
|
435 * the <code>Graphics</code> object to be used for rendering the |
|
436 * <code>Canvas</code> |
|
437 * |
|
438 */ |
|
439 protected abstract void paint(javax.microedition.lcdui.Graphics graphics); |
|
440 |
|
441 /** |
|
442 * Requests a repaint for the specified region of the |
|
443 * <code>CanvasGraphicsItem</code>. |
|
444 * <P> |
|
445 * Coordinates are relative to the <code>CanvasGraphicsItem</code> |
|
446 * coordinates. The method works in similar manner as <code>Canvas</code> |
|
447 * repaint method. |
|
448 * |
|
449 * @param x |
|
450 * the x coordinate of the rectangle to be repainted, in pixels |
|
451 * @param y |
|
452 * the y coordinate of the rectangle to be repainted, in pixels |
|
453 * @param width |
|
454 * the width of the rectangle to be repainted, in pixels |
|
455 * @param height |
|
456 * the height of the rectangle to be repainted, in pixels |
|
457 * |
|
458 */ |
|
459 public final void repaint(int x, int y, int width, int height) |
|
460 { |
|
461 iItemPainter.Repaint(x, y, width, height); |
|
462 } |
|
463 |
|
464 /** |
|
465 * Requests a repaint for the entire <code>CanvasGraphicsItem</code>. The |
|
466 * effect is identical to |
|
467 * <code>repaint(0, 0, getWidth(), getHeight());</code> |
|
468 * |
|
469 * @see #repaint(int x, int y, int width, int height) |
|
470 */ |
|
471 public final void repaint() |
|
472 { |
|
473 iItemPainter.Repaint(0, 0, getWidth(), getHeight()); |
|
474 } |
|
475 |
|
476 /* |
|
477 * Disposes the Landmark native peer object, if the handles are valid. |
|
478 * Invalid (negative) handles indicate that their creation failed in the |
|
479 * first place. |
|
480 */ |
|
481 final void registeredFinalize() |
|
482 { |
|
483 if (mFinalizer != null ) |
|
484 { |
|
485 synchronized (iToolkit) |
|
486 { |
|
487 if (iHandle != 0) |
|
488 { |
|
489 iToolkitInvoker.toolkitDisposeObject(iToolkit,iHandle); |
|
490 iHandle = 0; |
|
491 } |
|
492 } |
|
493 mFinalizer = null; |
|
494 } |
|
495 } |
|
496 |
|
497 void Repaint(Graphics aGraphics) |
|
498 { |
|
499 paint(aGraphics); |
|
500 } |
|
501 |
|
502 /* |
|
503 * Returns the native side handle to the LCDUI Toolkit. |
|
504 * |
|
505 * @return The native side handle to the LCDUI Toolkit. |
|
506 */ |
|
507 synchronized int getToolkitHandle() |
|
508 { |
|
509 return iToolkitInvoker.toolkitGetHandle(iToolkit); |
|
510 } |
|
511 |
|
512 // Native methods |
|
513 |
|
514 /* |
|
515 * Creates the native side peer object for this CanvasGraphicsItem. |
|
516 * |
|
517 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
518 * |
|
519 * @param aPainterHandle A handle of a CanvasGraphicsItemPainter native side |
|
520 * peer |
|
521 * |
|
522 * @param width The new width of this canvas graphics item. |
|
523 * |
|
524 * @param height The new hight of this canvas graphics item. |
|
525 * |
|
526 * @return A handle to the the native side peer object or a system-wide |
|
527 * error code. |
|
528 */ |
|
529 private native int _createNativePeer( |
|
530 int aToolkitHandle, |
|
531 int aPainterHandle, |
|
532 int width, |
|
533 int height); |
|
534 |
|
535 /* |
|
536 * Disposes the native side peer object. |
|
537 * |
|
538 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
539 * |
|
540 * @param aNativePeerHandle A handle to the native side peer object. |
|
541 */ |
|
542 private native void _dispose(int aToolkitHandle, int aNativePeerHandle); |
|
543 |
|
544 /* |
|
545 * Sets the size of this graphics item using the given width and height. |
|
546 * |
|
547 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
548 * |
|
549 * @param aNativePeerHandle A handle to the native side peer object. |
|
550 * |
|
551 * @param width The new width of this graphics item. |
|
552 * |
|
553 * @param height The new hight of this graphics item. |
|
554 * |
|
555 * @return NativeError.KErrNone if the operation was successful. Otherwise, |
|
556 * a system-wide error code is returned. |
|
557 */ |
|
558 private native int _setSize( |
|
559 int aToolkitHandle, |
|
560 int aNativePeerHandle, |
|
561 int width, |
|
562 int height); |
|
563 |
|
564 /* |
|
565 * Disposes the native side peer object. |
|
566 * |
|
567 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
568 * |
|
569 * @param aNativePeerHandle A handle to the native side peer object. |
|
570 * |
|
571 * @param aParentHandle A handle to the parent object. |
|
572 * |
|
573 * @return NativeError.KErrNone if the operation was successful. Otherwise, |
|
574 * a system-wide error code is returned. |
|
575 */ |
|
576 private native int _setParent( |
|
577 int aToolkitHandle, |
|
578 int aNativePeerHandle, |
|
579 int aParentHandle); |
|
580 |
|
581 /* |
|
582 * Sets the graphics item visible. |
|
583 * |
|
584 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
585 * |
|
586 * @param aNativePeerHandle A handle to the native side peer object. |
|
587 * |
|
588 * @param aVisible The visibility status of this graphics item. |
|
589 * |
|
590 * @return NativeError.KErrNone if the operation was successful. Otherwise, |
|
591 * a system-wide error code is returned. |
|
592 */ |
|
593 private native int _setVisible( |
|
594 int aToolkitHandle, |
|
595 int aNativePeerHandle, |
|
596 boolean aVisible); |
|
597 |
|
598 /* |
|
599 * Sets the graphics item's position. |
|
600 * |
|
601 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
602 * |
|
603 * @param aNativePeerHandle A handle to the native side peer object. |
|
604 * |
|
605 * @param x The x coordinate of the anchor point. |
|
606 * |
|
607 * @param y The y coordinate of the anchor point. |
|
608 * |
|
609 * @return NativeError.KErrNone if the operation was successful. Otherwise, |
|
610 * a system-wide error code is returned. |
|
611 */ |
|
612 private native int _setPosition( |
|
613 int aToolkitHandle, |
|
614 int aNativePeerHandle, |
|
615 int x, |
|
616 int y); |
|
617 |
|
618 /* |
|
619 * Sets the elevation of this graphics item. |
|
620 * |
|
621 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
622 * |
|
623 * @param aNativePeerHandle A handle to the native side peer object. |
|
624 * |
|
625 * @param aZ The new z-position. |
|
626 * |
|
627 * @return NativeError.KErrNone if the operation was successful. Otherwise, |
|
628 * a system-wide error code is returned. |
|
629 */ |
|
630 private native int _setZPosition( |
|
631 int aToolkitHandle, |
|
632 int aNativePeerHandle, |
|
633 int aZ); |
|
634 |
|
635 /* |
|
636 * Gets the elevation of this graphics item. |
|
637 * |
|
638 * @param aToolkitHandle A handle to the LCDUI toolkit. |
|
639 * |
|
640 * @param aNativePeerHandle A handle to the native side peer object. |
|
641 * |
|
642 * @return The elevation if the operation was successful. Otherwise, a |
|
643 * system-wide error code is returned. |
|
644 */ |
|
645 private native int _getZPosition(int aToolkitHandle, int aNativePeerHandle); |
|
646 } |