waba.ui
Class Window

java.lang.Object
  |
  +--waba.ui.Control
        |
        +--waba.ui.Container
              |
              +--waba.ui.Window
Direct Known Subclasses:
Calculator, Calendar, Calendar, ChoicesDialog, InputDialog, Keyboard, MainWindow, MenuBar, MessageBox, MultiEditMenu, PopList, PopupMenu

public class Window
extends Container

Window is a "floating" top-level window. This class IS functional like a modal window.

Attention! Is not a good practice use this class as a Container, adding it to other Window. Use this class only as a popup window, or strange things can happen!

Important: the popupModal method is not blocking, but the popupBlockingModal is blocking. In other words, after you call popupModal, the process continues immediately to the next line. You'll need to catch the WINDOW_CLOSED event to do things after the user had really closed the window. If you want to block until the Window is dismissed, just use popupBlockingModal Very important! popupBlockingModal can't be used on the program startup, ie, in the constructor, onStart or other application initialization methods. The main event loop must have been initialized in order to use it. Otherwise, the whole application will just halt!

The following example creates an popup window class:

  class TestWindow extends Window
  {
     Button btnHi;
     public TestWindow()
     {
        super("Test",RECT_BORDER); // with caption and borders
        setRect(CENTER,CENTER,Settings.screenWidth/2,Settings.screenHeight/4);
        add(btnHi=new Button("Hi!"),CENTER,CENTER);
     }
     public void onEvent(Event event)
     {
        if (event.type == ControlEvent.PRESSED && event.target == btnHi)
           unpop(); // a WINDOW_CLOSED event will be posted to this PARENT window by the Window class.
     }
  }
To use it (non-blocking):
  public class Main extends MainWindow
  {
     TestWindow tw;
     public void onStart()
     {
        tw = new TestWindow();
        tw.dontSaveBehind(true); // dont save behind (theres still nothing to be saved) and call repaint when window is closed - only needed when opening windows in onStart
        popupModal(tw);
        // this line is executed immediately
     }
     public void onEvent(Event event)
     {
        if (event.target == tw && event.type == ControlEvent.WINDOW_CLOSED)
        {
           // any stuff
        }
     }
  }
To use it (blocking):
  public class Main extends MainWindow
  {
     Button btn;
     public void onEvent(Event e)
     {
        if (e.target == btn)
        {
           TestWindow tw = new TestWindow();
           popupBlockingModal(tw);
           // this line is only executed after the window is closed.
        }
     }
  }
PopupBlockingModal may be use in InputDialog/MessageBox classes, while PopupModal is used in MenuBar and other classes.

Important note: you can't use popupBlockingModal with a delay to unpop it. In this case, the correct would be to use popupModal:

 popupModal(mb = new MessageBox(...));
 Vm.sleep(5000);
 mb.unpop;
 
If you use popupBlockingModal in this specific case, the Vm may hang.


Field Summary
protected  boolean beepIfOut
           
protected  byte borderStyle
           
protected  boolean canDrag
           
 boolean eraseBackgroundNow
           
protected  boolean flicker
          If true, the background is erased on each paint.
static int HIDE_STATE
          used to hide the showing state
protected  boolean highResPrepared
          Must set to true if your Window is prepared for 320x320 resolutions.
protected  Image imgCovered
           
protected  Container lastSwappedContainer
          Used in swap
protected  Container mainSwapContainer
          Used in swap
protected  Control menubar
           
protected  boolean needsPaint
           
static byte NO_BORDER
           
static byte RECT_BORDER
           
static byte ROUND_BORDER
           
static byte TAB_BORDER
           
static byte TAB_ONLY_BORDER
           
protected  String title
           
protected  Font titleFont
           
protected static Window topMost
           
static int VK_BOTTOM
          used to place the keyboard on bottom of screen
static int VK_HIDE
          used to hide the virtual keyboard
static int VK_TOP
          used to place the keyboard on top of screen
static Vector zStack
          Dont mess with this, unless you want to crash the VM!
 
Fields inherited from class waba.ui.Container
BORDER_LOWERED, BORDER_NONE, BORDER_RAISED, BORDER_SIMPLE, children, lastH, lastW, lastX, lastY, parentWindow, tail
 
Fields inherited from class waba.ui.Control
AFTER, appId, asContainer, asWindow, backColor, backDis, BEFORE, BOTTOM, CENTER, enabled, FILL, FIT, fm, fmH, focusLess, font, foreColor, foreDis, height, LEFT, parent, PREFERRED, RANGE, RIGHT, SAME, TOP, visible, width, x, x2, y, y2
 
Constructor Summary
Window()
          Constructs a window.
Window(String title, byte borderStyle)
          Constructs a window with the given title and border borderStyle.
 
Method Summary
 void _doPaint()
          paints the top-level window. called by MainWindow
 void _doPaint(int x, int y, int width, int height)
          Called by the VM to repaint an area.
 void _postEvent(int type, int key, int x, int y, int modifiers, int timeStamp)
          Called by the VM to post key and pen events.
protected  void damageRect(int x, int y, int width, int height)
          Adds a damage rectangle to the current list of areas that need repainting.
static void destroyZStack()
          this method is for internal use only. calling it directly will cause the VM to crash.
 void dontSaveBehind(boolean repaintOnClose)
          Sets the saveBehindWhenPopup flag to false.
 Rect getClientRect()
          returns the client rect, ie, the rect minus the border and title area, in relative coords
 Control getFocus()
          Returns the focus control for this window.
 Image getOffScreen()
          Returns the image that is used for the offscreen (double buffering). if there is no double buffer or an out of memory problem occurs, returns null.
 int getPreferredHeight()
          Returns the size of the title if any plus the size of the border.
 int getPreferredWidth()
          Returns the size of the title if any plus the size of the border.
static Window getTopMost()
          returns the topmost window
 boolean isTopMost()
          returns true if this window is the top-level window
 boolean isVisible()
          true if this is the topmost window
protected  void loadBehind(boolean release)
          This method loads the saved area behind of the current window.
 void makeUnmovable()
          Makes this window static, i.e., the user will not be able to move it around the screen by dragging the title area.
protected  boolean onClickedOutside(int x, int y)
          called when the user clicks outside the bounds of this window. must return true if the event was handled, false otherwise.
protected  void onPopup()
          Placeholder called imediatly before the popup began. the default implementation does nothing.
protected  void onUnpop()
          Placeholder called imediatly before the unpop began. the default implementation does nothing.
protected  void paintTitle(String title, Graphics gg)
          paints the title immediatly.
 void popupBlockingModal(Window newWin)
          Popup a modal window, blocking the program execution, and make it child of this one.
protected  void popupMenuBar()
          Open the menu bar that is associated with this window
 void popupModal(Window newWin)
          Popup a modal window, and make it child of this one.
protected  void postPopup()
          Placeholder called after the popup is done and after the repaint of this window. the default implementation does nothing.
protected  void postUnpop()
          Placeholder called after the unpop is done and after the repaint of the other window. the default implementation does nothing.
static void pumpEvents()
          Let the VM handle all the events in the event queue.
protected  void saveBehind()
          This method tries to save the area behind the window before it is popped up.
 void setBorderStyle(byte borderStyle)
          sets the border borderStyle. use the constants XXXX_BORDER. sets the flag border accordingly to the borderStyle.
 void setDoubleBuffer(boolean doubleBuf)
          Sets true if we have to use an double buffer to paint the screen.
 void setFocus(Control c)
          Sets focus to the given control.
 void setMenuBar(Control menubar)
          sets the menu bar for this window
 void setStatePosition(int x, int y)
          used to set the position where the status chars will be displayed. the chars are 8x11 pixels. this method must be called so the status can be displayed. these positions must be relative to this window, because they are converted to absolute coordinates. use setStatePosition(Window.HIDE_STATE,Window.HIDE_STATE) to remove the display of the state.
 void setTitle(String title)
          sets the title and call repaint. if you want an imediate repaint, call paintTitle.
 void setTitleFont(Font titleFont)
          sets the title font
 void swap(Container newContainer)
          Used to swap containers from the
Window.
 void unpop()
          Hides this window.
 void validate()
          Calls _doPaint if the window needs painting.
 
Methods inherited from class waba.ui.Container
add, add, add, broadcastEvent, findChild, getChildren, onColorsChanged, onPaint, onStart, paintChildren, remove, setEnabled
 
Methods inherited from class waba.ui.Control
addTimer, contains, createGraphics, getAbsoluteRect, getBackColor, getFont, getFontMetrics, getForeColor, getNext, getParent, getParentWindow, getPos, getRect, getSize, isDisplayed, isEnabled, onBoundsChanged, onEvent, onFontChanged, onWindowPaintFinished, postEvent, removeTimer, repaint, repaintNow, requestFocus, setBackColor, setBackForeColors, setFocusLess, setFont, setForeColor, setRect, setRect, setRect, setVisible
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, toString, wait, wait
 

Field Detail

needsPaint

protected boolean needsPaint

title

protected String title

beepIfOut

protected boolean beepIfOut

flicker

protected boolean flicker
If true, the background is erased on each paint. If false, you must take care of erasing the background

topMost

protected static Window topMost

titleFont

protected Font titleFont

borderStyle

protected byte borderStyle

menubar

protected Control menubar

canDrag

protected boolean canDrag

eraseBackgroundNow

public boolean eraseBackgroundNow

imgCovered

protected Image imgCovered

highResPrepared

protected boolean highResPrepared
Must set to true if your Window is prepared for 320x320 resolutions. If false (default), the Window is doubled size (and centered) to make controls fit

mainSwapContainer

protected Container mainSwapContainer
Used in swap

lastSwappedContainer

protected Container lastSwappedContainer
Used in swap

NO_BORDER

public static final byte NO_BORDER

RECT_BORDER

public static final byte RECT_BORDER

ROUND_BORDER

public static final byte ROUND_BORDER

TAB_BORDER

public static final byte TAB_BORDER

TAB_ONLY_BORDER

public static final byte TAB_ONLY_BORDER

HIDE_STATE

public static final int HIDE_STATE
used to hide the showing state

VK_HIDE

public static final int VK_HIDE
used to hide the virtual keyboard

VK_TOP

public static final int VK_TOP
used to place the keyboard on top of screen

VK_BOTTOM

public static final int VK_BOTTOM
used to place the keyboard on bottom of screen

zStack

public static Vector zStack
Dont mess with this, unless you want to crash the VM!
Constructor Detail

Window

public Window()
Constructs a window.

Window

public Window(String title,
              byte borderStyle)
Constructs a window with the given title and border borderStyle.
Method Detail

setTitleFont

public void setTitleFont(Font titleFont)
sets the title font

setTitle

public void setTitle(String title)
sets the title and call repaint. if you want an imediate repaint, call paintTitle.

setBorderStyle

public void setBorderStyle(byte borderStyle)
sets the border borderStyle. use the constants XXXX_BORDER. sets the flag border accordingly to the borderStyle.
Overrides:
setBorderStyle in class Container

setDoubleBuffer

public void setDoubleBuffer(boolean doubleBuf)
Sets true if we have to use an double buffer to paint the screen.

getOffScreen

public Image getOffScreen()
Returns the image that is used for the offscreen (double buffering). if there is no double buffer or an out of memory problem occurs, returns null. Initializes the buffer if necessary.

makeUnmovable

public void makeUnmovable()
Makes this window static, i.e., the user will not be able to move it around the screen by dragging the title area. It just set the canDrag member to false.

setFocus

public void setFocus(Control c)
Sets focus to the given control. When a user types a key, the control with focus get the key event. At any given time, only one control in a window can have focus. Calling this method will cause a FOCUS_OUT control event to be posted to the window's current focus control (if one exists) and will cause a FOCUS_IN control event to be posted to the new focus control.

getFocus

public Control getFocus()
Returns the focus control for this window.
See Also:
setFocus(waba.ui.Control)

damageRect

protected void damageRect(int x,
                          int y,
                          int width,
                          int height)
Adds a damage rectangle to the current list of areas that need repainting.

onClickedOutside

protected boolean onClickedOutside(int x,
                                   int y)
called when the user clicks outside the bounds of this window. must return true if the event was handled, false otherwise. If false is returned and beepIfOut is true, then a beep is played and nothing more happens.
Since:
SuperWaba 1.2

validate

public void validate()
Calls _doPaint if the window needs painting.
Since:
SuperWaba 4.0

_postEvent

public void _postEvent(int type,
                       int key,
                       int x,
                       int y,
                       int modifiers,
                       int timeStamp)
Called by the VM to post key and pen events.

getClientRect

public Rect getClientRect()
returns the client rect, ie, the rect minus the border and title area, in relative coords
Overrides:
getClientRect in class Container

paintTitle

protected void paintTitle(String title,
                          Graphics gg)
paints the title immediatly.

_doPaint

public void _doPaint(int x,
                     int y,
                     int width,
                     int height)
Called by the VM to repaint an area. If doubleBuf is true, paints the whole screen in a buffer and draws it on screen.

popupModal

public final void popupModal(Window newWin)
Popup a modal window, and make it child of this one. All events in the behind window are deactivated

popupBlockingModal

public final void popupBlockingModal(Window newWin)
Popup a modal window, blocking the program execution, and make it child of this one. All events in the behind window are deactivated. Important! You can't use this method in the application's constructor or in the onStart method!

unpop

public final void unpop()
Hides this window. Calling unpop when only the MainWindow is active does nothing.

pumpEvents

public static void pumpEvents()
Let the VM handle all the events in the event queue. This method is used to implement a blocking Window. Here is an example:
 while(someCondition)
 {
    Event.pumpEvents();
 }
 

_doPaint

public void _doPaint()
paints the top-level window. called by MainWindow

isTopMost

public boolean isTopMost()
returns true if this window is the top-level window

getTopMost

public static Window getTopMost()
returns the topmost window

onPopup

protected void onPopup()
Placeholder called imediatly before the popup began. the default implementation does nothing.

postPopup

protected void postPopup()
Placeholder called after the popup is done and after the repaint of this window. the default implementation does nothing.

onUnpop

protected void onUnpop()
Placeholder called imediatly before the unpop began. the default implementation does nothing.

postUnpop

protected void postUnpop()
Placeholder called after the unpop is done and after the repaint of the other window. the default implementation does nothing.

isVisible

public boolean isVisible()
true if this is the topmost window
Overrides:
isVisible in class Control

setStatePosition

public void setStatePosition(int x,
                             int y)
used to set the position where the status chars will be displayed. the chars are 8x11 pixels. this method must be called so the status can be displayed. these positions must be relative to this window, because they are converted to absolute coordinates. use setStatePosition(Window.HIDE_STATE,Window.HIDE_STATE) to remove the display of the state. Note: in SuperWaba 2.0, this only works on PalmOS >= 3.5.

setMenuBar

public void setMenuBar(Control menubar)
sets the menu bar for this window

popupMenuBar

protected void popupMenuBar()
Open the menu bar that is associated with this window

dontSaveBehind

public void dontSaveBehind(boolean repaintOnClose)
Sets the saveBehindWhenPopup flag to false. If repaintOnClose is true, the window calls repaint on the parent window when it closes. This method is important if you popup a window on the onStart method before the MainWindow is drawed.

saveBehind

protected void saveBehind()
This method tries to save the area behind the window before it is popped up. It is used in the popupModal method so the area can be restored when the window is unpopped. If an out of memory error occurs, the window will be repainted instead of saved.
Since:
SuperWaba2.0beta4

loadBehind

protected void loadBehind(boolean release)
This method loads the saved area behind of the current window. It is automaticaly used in the unpop method.
Parameters:
release - if true, the memory used is released
Since:
SuperWaba2.0beta4

destroyZStack

public static void destroyZStack()
this method is for internal use only. calling it directly will cause the VM to crash.

swap

public void swap(Container newContainer)
Used to swap containers from the
Window. To restore the first container, pass null as parameter. See samples/ui/ContainerSwitch.

getPreferredWidth

public int getPreferredWidth()
Returns the size of the title if any plus the size of the border. Note that the value returned here does not handle the controls inside the window.
Overrides:
getPreferredWidth in class Control

getPreferredHeight

public int getPreferredHeight()
Returns the size of the title if any plus the size of the border. Note that the value returned here does not handle the controls inside the window.
Overrides:
getPreferredHeight in class Control