mwt
Class Window

java.lang.Object
  extended by mwt.Component
      extended by mwt.Window

public class Window
extends Component

In MWT the Window class is like a Frame/Form/Shell in other UI frameworks.
Normally, an application that uses MWT should instance at least one window.

A window has the following functionallity:

Handling Input

A window should be notified whenever a key is pressed or released using setKeyState(int, int, boolean) method.
Normally you will invoke this method from your canvas implementation:

        class MyCanvas extends Canvas {
                Window win;
                protected void keyPressed(int keyCode)  { win.setKeyState(keyCode,Window.KEYSTATE_PRESSED,true); }
                protected void keyReleased(int keyCode) { win.setKeyState(keyCode,Window.KEYSTATE_RELEASED,true); }
                ...
        }
 

Some devices don't support the Canvas.keyRepeated(int) event. MWT can "simulate" this event calling repeatKeys(boolean) from your application's main loop.

You may get a key state at anytime using getKeyState(int).

Focus Actions

Usually in UI frameworks the keyboard's TAB and ARROWS keys are used to move the focus, the ENTER key is used to trigger actions. Similarly, "focus actions" are used to handle such things.

A focus action can be either FOCUSACTION_FIRE, FOCUSACTION_NEXT, FOCUSACTION_PREV or FOCUSACTION_NONE.

The MWT Window has a default implementation which uses Canvas.KEY_NUM2, Canvas.KEY_NUM8, Canvas.KEY_NUM6 and Canvas.KEY_NUM4 to move the focus and Canvas.KEY_NUM5 to trigger actions.
You can define your own implementation overriding getFocusAction(long) method.


Handling Focus

A window can focus one or none components simultaneously.
To set the focus directely use setFocus(Component), but if you like to move it use setFocusNext() and setFocusPrevious().
Note that when a window is created and components are added into it focus is still null. You must set the focus "manually".

Components don't have a "focusIndex" (or "tabIndex" in other UI frameworks) propery, focus is moved according to the component hierarchy.

Remember that a component can gain focus only if Component.acceptsFocus() is true.


Painting

The paint(Graphics) paints all childs components into the graphics in hierarchy order; there is not a "z-index" property.

A window paints all components during each paint call, there is not a dirty rectangle implementation.


Dialogs

MWT allows you create dialogs, setting another window in front.
You don't need to notify input events to the new dialog window, its owner window dispatch these events automatically to the dialog.

Unlike other UI frameworks, the method dialogOpen(Window) returns immediately, without waiting the dialog to close. However, is possible to simulate this trick by calling your application main loop.

  Window main = ...;
  boolean result;
  Window dialog = ...; // sets the result before closing
  
  void save() {
    main.dialogOpen(dialog);
    while(main.getDialog() == dialog)
      mainLoop();
    if(result) ...
    else ... 
  }
 
Remember, everytime you use a dialogOpen(Window), a dialogClose() should be called somewhere.

Keys, KeyCodes and Key's States

A key code is a value that maps a device's key, like Canvas's KEY_NUMs.

MWT uses two more concepts; key's states and keys.
A key state is a value that represents the state of a key at anytime. That is, if it is released, pressed or repeated.
KEYSTATE_PRESSED or 1 is for key pressed states.
KEYSTATE_RELEASED or 0 is for key released states.
Other values are for key repeated states.
A key is a long value where the integer part is the key code, and the key >> 32 value is its key state.


Field Summary
static int FOCUSACTION_FIRE
          Constant returned by getFocusAction(long) to "fire" events.
static int FOCUSACTION_NEXT
          Constant returned by getFocusAction(long) to request focus next.
static int FOCUSACTION_NONE
          Constant returned by getFocusAction(long) when there's not action.
static int FOCUSACTION_PREV
          Constant returned by getFocusAction(long) to request focus previous.
static int KEYSTATE_PRESSED
          Constant which represents the state of a key when is pressed.
static int KEYSTATE_RELEASED
          Constant which represents the state of a key when is released.
static int STYLE_DEFAULT
          Constant value to get/set a skin/font.
static int STYLE_DISABLED
          Constant value to get/set a skin/font.
 
Fields inherited from class mwt.Component
ALIGN_BOTTOM_CENTER, ALIGN_BOTTOM_LEFT, ALIGN_BOTTOM_RIGHT, ALIGN_MIDDLE_CENTER, ALIGN_MIDDLE_LEFT, ALIGN_MIDDLE_RIGHT, ALIGN_TOP_CENTER, ALIGN_TOP_LEFT, ALIGN_TOP_RIGHT
 
Constructor Summary
Window(int x, int y, int width, int height)
          Creates a new window with the given position and size.
 
Method Summary
 void dialogClose()
          Closes the current dialog.
 void dialogOpen(Window dialog)
          Opens the given window as a dialog.
protected  void dispatchKey(long key)
          This method is called whenever a key event is not consumed by the focused component.
static Skin getDefaultSkin(int style)
          Gets the default skin for the given style.
 Window getDialog()
          Gets this window's current dialog.
 Component getFocus()
          Gets the current focused component.
 int getFocusAction(long key)
          Gets the focus action for the given key.
 int getKeyState(int keyCode)
          Gets the current key state for the given keycode.
 Skin getSkin(int style)
          Gets this window skin for the given style.
 void paint(javax.microedition.lcdui.Graphics g)
          Paints the window and all its childs components into the given graphics object.
protected  void paint(javax.microedition.lcdui.Graphics g, Window window)
          Paints this component.
 void repeatKeys(boolean processKeyEvents)
          Increments the state for all the keys that are not released.
static void setDefaultSkin(int style, Skin skin)
          Sets the default skin for the given style.
 void setFocus(Component c)
          Sets the focus to the given component.
 void setFocusFirst()
          Sets the focus to the first component that accepts focus.
 void setFocusNext()
          Focus the next component that accepts focus.
 void setFocusPrevious()
          Focus the previous component that accepts focus.
 void setKeyState(int keyCode, int keyState, boolean processKeyEvents)
          Sets the key state for the given key code.
 void setSkin(int style, Skin skin)
          Sets this window skin for the given style.
 
Methods inherited from class mwt.Component
acceptsFocus, add, add, focusGained, focusLost, getChild, getChild, getChild, getChildCount, getComponent, getComponentCount, getComponentIndex, getHeight, getId, getParent, getWidth, getX, getY, isContainer, isDoubleBuffered, isEnabled, isFocusable, isHierarchyEnabled, isHierarchyVisible, isVisible, keyEvent, paintChilds, remove, removeChild, setDoubleBuffered, setEnabled, setFocusable, setHeight, setId, setVisible, setWidth, setX, setY
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FOCUSACTION_NONE

public static final int FOCUSACTION_NONE
Constant returned by getFocusAction(long) when there's not action.

See Also:
Constant Field Values

FOCUSACTION_FIRE

public static final int FOCUSACTION_FIRE
Constant returned by getFocusAction(long) to "fire" events.

See Also:
Constant Field Values

FOCUSACTION_NEXT

public static final int FOCUSACTION_NEXT
Constant returned by getFocusAction(long) to request focus next.

See Also:
Constant Field Values

FOCUSACTION_PREV

public static final int FOCUSACTION_PREV
Constant returned by getFocusAction(long) to request focus previous.

See Also:
Constant Field Values

STYLE_DEFAULT

public static final int STYLE_DEFAULT
Constant value to get/set a skin/font.

See Also:
Constant Field Values

STYLE_DISABLED

public static final int STYLE_DISABLED
Constant value to get/set a skin/font.

See Also:
Constant Field Values

KEYSTATE_PRESSED

public static final int KEYSTATE_PRESSED
Constant which represents the state of a key when is pressed. See also Keys.

See Also:
Constant Field Values

KEYSTATE_RELEASED

public static final int KEYSTATE_RELEASED
Constant which represents the state of a key when is released. See also Keys.

See Also:
Constant Field Values
Constructor Detail

Window

public Window(int x,
              int y,
              int width,
              int height)
Creates a new window with the given position and size.

Method Detail

getDefaultSkin

public static final Skin getDefaultSkin(int style)
Gets the default skin for the given style.


setDefaultSkin

public static final void setDefaultSkin(int style,
                                        Skin skin)
Sets the default skin for the given style.


getSkin

public Skin getSkin(int style)
Gets this window skin for the given style.


setSkin

public void setSkin(int style,
                    Skin skin)
Sets this window skin for the given style.


getKeyState

public final int getKeyState(int keyCode)
Gets the current key state for the given keycode.

Parameters:
keyCode - the key code
Returns:
the current key state for the given keycode
See Also:
Keys

getFocusAction

public int getFocusAction(long key)
Gets the focus action for the given key.
The default implementation is:
 protected int getFocusAction(long key) {
        switch((int) key) {
                case Canvas.KEY_NUM4:
                case Canvas.KEY_NUM2: return FOCUSACTION_PREV;
                case Canvas.KEY_NUM6:
                case Canvas.KEY_NUM8: return FOCUSACTION_NEXT;
                case Canvas.KEY_NUM5: return FOCUSACTION_FIRE;
                default: return FOCUSACTION_NONE;
        }
 }
 
Note that you can ask for other key states using getKeyState(int). This allow you, for example, poll if another key is pressed.
 if((int)key && getKeyState(Canvas.KEY_NUM0)) ...
 

Parameters:
key - the key
Returns:
the focus action
See Also:
Keys

setKeyState

public final void setKeyState(int keyCode,
                              int keyState,
                              boolean processKeyEvents)
                       throws java.lang.IllegalArgumentException
Sets the key state for the given key code.
This method triggers component's key events if processKeyEvents is true.

Parameters:
keyCode - The key code
keyState - The new key state for the given key code. Either KEYSTATE_PRESSED or KEYSTATE_RELEASED
processKeyEvents - True if component's key events should be triggered
Throws:
java.lang.IllegalArgumentException
See Also:
Keys

repeatKeys

public final void repeatKeys(boolean processKeyEvents)
Increments the state for all the keys that are not released.
This method triggers component's key events if processKeyEvents is true.

Parameters:
processKeyEvents - True if component's key events should be triggered

dispatchKey

protected void dispatchKey(long key)
This method is called whenever a key event is not consumed by the focused component.
The default implementation moves the focus.


paint

public final void paint(javax.microedition.lcdui.Graphics g)
Paints the window and all its childs components into the given graphics object.

Parameters:
g - The graphics object

paint

protected void paint(javax.microedition.lcdui.Graphics g,
                     Window window)
Description copied from class: Component
Paints this component.

The default implementation calls Component.paintChilds(Graphics, Window).
An implementation should call Component.paintChilds(Graphics, Window) once (if the component is a container).

The graphics object was previously transformed to the current x and y, and the clip was setted according to this component width and height.

Overrides:
paint in class Component
Parameters:
g - the graphics to draw the component into
window - the window caller

dialogOpen

public final void dialogOpen(Window dialog)
Opens the given window as a dialog.

Parameters:
dialog -
See Also:
Dialogs

getDialog

public Window getDialog()
Gets this window's current dialog.

See Also:
Dialogs

dialogClose

public final void dialogClose()
Closes the current dialog.

See Also:
Dialogs

getFocus

public final Component getFocus()
Gets the current focused component.


setFocusFirst

public final void setFocusFirst()
Sets the focus to the first component that accepts focus.

See Also:
Component.acceptsFocus()

setFocusNext

public final void setFocusNext()
Focus the next component that accepts focus.

See Also:
Component.acceptsFocus()

setFocusPrevious

public final void setFocusPrevious()
Focus the previous component that accepts focus.

See Also:
Component.acceptsFocus()

setFocus

public final void setFocus(Component c)
Sets the focus to the given component.
If the given component doesn't accept focus, this does nothing.
Null is a valid parameter.



Copyright © 2007 MWT-Team. All Rights Reserved.