ewe.ui
Class Form

java.lang.Object
  ewe.ui.ControlBase
      ewe.ui.Control
          ewe.ui.Container
              ewe.ui.Canvas
                  ewe.ui.Panel
                      ewe.ui.CellPanel
                          ewe.ui.FormBase
                              ewe.ui.Form

All Implemented Interfaces:

CellConstants, ControlConstants, EventListener, HasProperties, ImageRefresher, IScroll, LayoutManager, ScrollClient, TimerProc, UIConstants

Direct Known Subclasses:

ControlPopupForm, Editor, MessageBox, PhoneVMLauncher, ProgressBarForm, RegistryView, SelectKeys, SimpleFileChooser

public class Form

extends FormBase

implements HasProperties

A Form is a CellPanel that is able to create a Frame/Window for itself for display on the screen. This is the easiest way to display controls within a Frame or Window - much easier than attempting to create Frames and Windows yourself. However you can still use a Form as an ordinary CellPanel if you wish - it will only create a Frame/Window for itself if you call one of the show()/exec()/execute() methods.

When displaying a Form within a new Window you can set flags for the properties of the new Window by adjusting windowFlagsToSet and windowFlagsToClear.

A Form can display an icon in the system taskbar by setting the taskbarIcon variable. By default, clicking on this icon will bring the application to the front.

Field Summary

boolean	acceptsDroppedFiles Set this true to accept files dropped from the file manager.
Control	apply
Control	back
protected Vector	buttons The buttons to be displayed at the bottom of the Form (if any) are stored here.
static int	BUTTONS_TO_SOFT_KEY_FIRST_BUTTON_SEPARATE
static int	BUTTONS_TO_SOFT_KEY_MENU_ALWAYS
static int	BUTTONS_TO_SOFT_KEY_USE_FIRST_SOFT_KEY
CellPanel	buttonsPanel This is the panel that will contain any of the special buttons you add.
int	buttonsPerRow Set this to be greater than zero to limit the number of buttons displayed at the bottom of the Form.
Control	cancel
Control	deflt
boolean	dismantleOnClose This tells the Form to dismantle itself when it closes.
boolean	exitButtonDefined This is set true when doButtons() is called to add close buttons to the form.
boolean	exitSystemOnClose
int	exitValue This is the value that was sent to close(int exitCode) or exit(int exitCode).
Control	firstFocus This explicitly sets the control which will first get focus when the Form is displayed.
protected FormFrame	formFrame The Frame the Form is currently displayed in.
static IImage	globalIcon
Handle	handle This is used to monitor the state of the Form.
boolean	hasTopBar
boolean	keepFrame This option tells the Form to keep a reference to the Frame it creates for itself to save time if it is closed and then re-shown.
boolean	moveable
Control	no
boolean	noBorder
Control	ok
protected PropertyList	pl The properties of the Form.
Control	reset
boolean	resizable
boolean	resizeOnSIP If this is true then the Frame containing the Form will resize itself to avoid the SIP when the SIP is turned on.
Window.TaskBarIconInfo	taskbarIcon Set this to be a valid Window.TaskBarIconInfo if you want to display an icon in the taskbar when this Form is displayed.
String	title The title of the form.
Control	titleCancel If this is set to a control then this control will appear to the right of the title bar.
CellPanel	titleControls Use this to add controls to the title bar of the form.
Control	titleOK If this is set to a control then this control will appear to the right of the title bar.
CellPanel	topControls Use this to add controls to the top of the form, below the title bar.
static String	untitledTitle This is the default title that will be assigned to a new Form.
int	windowFlagsToClear These are flags that you want to clear for any new Window being created to display this Form.
int	windowFlagsToSet These are flags that you want to set for any new Window being created to display this Form.
IImage	windowIcon
String	windowTitle If this is not null, then the window that the Form is displayed in will have its title set to this value regardless of whether it is the top level form or not.
Control	yes

Fields inherited from class ewe.ui.FormBase

BACKB, CANCELB, close, cross, defaultShowOptions, DEFCANCELB, DEFOKB, EXIT_IDBACK, EXIT_IDCANCEL, EXIT_IDNO, EXIT_IDOK, EXIT_IDYES, IDBACK, IDCANCEL, IDNO, IDOK, IDYES, MBB, MBNONE, MBOK, MBOKCANCEL, MBYESNO, MBYESNOCANCEL, NOB, OKB, stop, tick, tools, YESB

Fields inherited from class ewe.ui.CellPanel

autoSpan, equalHeights, equalWidths, layout, mySplitter, nextSplitter, quickRecalculate

Fields inherited from class ewe.ui.Panel

all, backgroundImage, calculated, childListeners, defaultAddToMeCellConstraints, defaultTags, grid, lastAdded, layoutManager, made, noInsets, stretchFirstColumn, stretchFirstRow, stretchLastColumn, stretchLastRow, titleGap

Fields inherited from class ewe.ui.Canvas

isFullScrollClient, origin, scrollPercent, virtualSize

Fields inherited from class ewe.ui.Container

closedFocus, cycleFocus, dontAutoScroll, dontFocusOnChildren

Fields inherited from class ewe.ui.Control

_debug, backGround, beforeRemoved, borderColor, borderStyle, borderWidth, children, columns, constraints, DoPaintMethod, dragging, dragResolution, dragTime, exitKeys, fieldTransfer, font, foreGround, haveNativePaint, height, holdDownPause, holdTick, hotKey, image, lastSelected, listeners, maxHeight, maxWidth, menuState, minHeight, minWidth, modifiers, MyClass, name, next, np, parent, penStatus, popupSound, popupSoundClip, preferredHeight, preferredWidth, prev, prompt, promptControl, rows, ss, standardBorder, standardEdge, startDragResolution, tags, tail, text, toolTip, width, x, y

Fields inherited from class ewe.ui.ControlBase

clipItems, clipObject, clipOwner, curPoint, currentPenEvent, debugControl, debugFlag, DidHoldDown, doubleBuffer, doubleClickTime, firstPress, globalDrawFlat, globalEditable, globalEnabled, globalPalmStyle, globalSmallControls, GotPenDown, PenIsOn, pressPoint, TAG_LAST_USER_DATA, TAG_USER_DATA, TAKE_FIRST_PRESS, unnamed, useNativeTextInput

Fields inherited from interface ewe.ui.CellConstants

BORDER, BOTTOM, CELLFLAG, CELLMASK, CENTER, CONTROLMASK, DONTCHANGE, DONTFILL, DONTSTRETCH, EAST, FILL, FIXEDSIZE, GROW, HCENTER, HCONTRACT, HEXPAND, HFILL, HGROW, HSHRINK, HSTRETCH, INITIALLY_CLOSED, INITIALLY_MINIMIZED, INITIALLY_PREFERRED_SIZE, INSETS, LEFT, MAXIMUMSIZE, MINIMUMSIZE, NORTH, NORTHEAST, NORTHWEST, PREFERREDSIZE, RECT, RIGHT, SHRINK, SOUTH, SOUTHEAST, SOUTHWEST, SPAN, STRETCH, TEXTSIZE, TOP, VCENTER, VCONTRACT, VEXPAND, VFILL, VGROW, VSHRINK, VSTRETCH, WEST

Fields inherited from interface ewe.ui.IScroll

Higher, Horizontal, Lower, OPTION_INDICATOR_ONLY, PageHigher, PageLower, ScrollHigher, ScrollLower, TrackTo, Vertical

Fields inherited from interface ewe.ui.UIConstants

BDR_DOTTED, BDR_INNER, BDR_NOBORDER, BDR_OUTER, BDR_OUTLINE, BDR_RAISEDINNER, BDR_RAISEDOUTER, BDR_SUNKENINNER, BDR_SUNKENOUTER, BF_BOTTOM, BF_BOTTOMLEFT, BF_BOTTOMRIGHT, BF_BUTTON, BF_DIAGONAL, BF_DIAGONAL_ENDBOTTOMLEFT, BF_DIAGONAL_ENDBOTTOMRIGHT, BF_DIAGONAL_ENDTOPLEFT, BF_DIAGONAL_ENDTOPRIGHT, BF_EXACT, BF_FLAT, BF_LEFT, BF_MIDDLE, BF_MONO, BF_PALM, BF_RECT, BF_RIGHT, BF_SOFT, BF_SQUARE, BF_TOP, BF_TOPLEFT, BF_TOPRIGHT, EDGE_BUMP, EDGE_ETCHED, EDGE_RAISED, EDGE_SUNKEN

Fields inherited from interface ewe.ui.ControlConstants

All, AlwaysEnabled, AlwaysRecalculateSizes, ByDeferredMouse, ByDeferredPen, ByFrameChange, ByKeyboard, ByMouse, ByPen, ByRequest, CalculatedSizes, Disabled, DisablePopupMenu, DisplayOnly, Down, DrawFlat, Flag, ForceResize, HasData, Invisible, KeepImage, KeepSIP, Left, MakeMenuAtLeastAsWide, Maximize, Minimize, MouseSensitive, NoFocus, NotAnEditor, NotEditable, PaintDataOnly, PaintOutsideOnly, PenTransparent, PreferredSizeOnly, Right, SendUpKeyEvents, SendUpPenEvents, ShowSIP, ShrinkToNothing, SmallControl, SpecialBackground, TakeControlEvents, TakesKeyFocus, Transparent, Up, WantDrag, WantHoldDown

Fields inherited from interface ewe.fx.ImageRefresher

KEEP_VISIBLE

Constructor Summary

Form()

Method Summary

boolean	_getSetField(String fieldName, Wrapper wrapper, boolean isGet) A special method used by ewe.reflect.FieldTransfer() to transfer data to and from controls and properties.
void	addButton(Control b) This is used to add custom buttons to the bottom of the bar.
Control[]	addTabbedPanel(boolean useExpandingTabs) A very useful method for creating a Form with a tabbed panel.
CellPanel[]	addToolbar() A very useful method for creating a Form with a toolbar or menubar.
Menu	buttonsToMenu(Vector buttons, Menu destination) Add a Vector of mButton objects to a Menu.
boolean	buttonsToSoftKeyBar(Container buttons, String menuName, int options) Add a container which contains mButton objects to the SoftKeyBar.
boolean	buttonsToSoftKeyBar(Vector buttons, String menuName, int options) Add a Vector of mButton objects to the SoftKeyBar.
static void	cancelWait() This cancels the display of the wait Cursor IF it was requested.
protected boolean	canExit(int exitCode) This is called by the exit() method to see if the form can be closed.
protected void	checkButtons() This is called before the Form is displayed to setup the buttons as requested by doButtons().
void	close(int exitCode) This closes the form unconditionally and sets the exitValue to be exitCode.
void	closeAll(int exitCode) If this Form is embedded within another Form, then this will close the topmost Form.
Handle	closeForTransfer() This closes the Form but does not set the handle to a stopped state, instead it returns the still running handle.
Handle	closeForTransfer(boolean dismantle, boolean showWait) This closes the Form but does not set the handle to a stopped state, instead it returns the still running handle.
static void	continueWait() This requests that a wait Cursor be shown IF it was shown before the last Form was displayed - otherwise it has no effect.
MenuItem	createMenuItem(mButton button) Return a MenuItem that will be used as a proxy for a specific buton.
MenuItem	createMenuItem(String label, String action, IImage icon)
MenuItem	createMenuItem(String label, String action, String iconName, Object maskOrColor)
Window	createWindow() This creates a new Window for the Form on request (when being shown).
void	defaultTitleTo(String newTitle) This will set the title of the Form if it has not already been set.
void	dismantle(Control stopAt)
void	doButtons(int which) This is used to add a row of buttons at the bottom of the form, using The value of "which" can be the logical OR of any of the pre-defined button values (e.g.
protected FormFrame	doShowExec(Frame parent, EventListener listener, boolean modal, int options) All show()/exec()/execute() methods eventually call this method.
FormFrame	exec() This displays the Form modally in a new Window.
Handle	exec(boolean dismantleOnClose) Display the Form modally in a new Window and return the Handle that can be used to monitor the Form's open state using waitUntilClosed().
Handle	exec(boolean dismantleOnClose, Frame parent, int options) Display the Form modally in a parent Frame and return the Handle that can be used to monitor the Form's open state using waitUntilClosed().
FormFrame	exec(Frame parent, EventListener listener) Deprecated.
FormFrame	exec(Frame parent, EventListener listener, int options) Deprecated.
FormFrame	exec(Frame parent, int options) This displays the Form modally within an already displayed parent Frame.
FormFrame	exec(Handle transferredHandle) This is used to exec a Form using the Handle from another Form (usually got from closeForTransfer()).
FormFrame	exec(Handle transferredHandle, Frame parent, int options) This is used to exec a Form using the Handle from another Form (usually got from closeForTransfer()).
FormFrame	exec(int options) Deprecated.
int	execute() This displays the Form modally in a new Window and waits for the Form to close.
int	execute(Frame parent, int options) This displays the Form modally within an already displayed parent Frame and then waits for the Form to close.
int	execute(int options) Deprecated.
boolean	exit(int exitCode) This will call the canExit() method and if it returns true, it will close the form.
void	filesDropped(String[] fileNames) This is called when files are dropped on the Form and acceptsDroppedFiles is true.
protected void	formClosing() This is called to indicate that the Form is about to close and it causes a FormEvent.CLOSED event to be posted.
protected void	formShown() This is called to indicate that the Form has been made and has been displayed on the screen.
static Vector	gatherButtons(Container buttons, Vector destination)
Control	getButton(String text) Used to create a new Button for the Form.
protected Control	getFirstFocus()
FormFrame	getFormFrame(int options) This is called when the Form is about to be displayed.
PropertyList	getProperties() Get the PropertyList object associated with this object.
SoftKeyBar	getSoftKeyBarFor(Control c) Get the SoftKeyBar for a particular Control or the default SoftKeyBar.
Form	getTopmostForm()
boolean	handleAction(ControlEvent ev) Handle a ControlEvent that is of type PRESSED and for which the "action" field is not null.
boolean	handleAction(String action) Handle an action type event.
boolean	hasExitButton() Tests if the Form has an exit button defined for it.
void	make(boolean reMake) This is used to "make" the control before being displayed.
Control	makeButtonForForm(String text, IImage icon, int hotkey)
Control	makeButtonForForm(String text, String iconName, Object maskOrColor, int hotkey)
Control	makeDefaultButton(int whichButton, boolean useText) Create and return the default OK or Cancel button.
Control	makeDefaultButton(int whichButton, String textToUse) Create and return the default OK or Cancel button.
protected FormFrame	makeFrame(int options) This is used to actually create the frame for the form.
MenuItem	makeMenuItemForForm(String label, String action, IImage icon)
MenuItem	makeMenuItemForForm(String label, String action, String iconName, Object maskOrColor)
SoftKeyBar	makeSoftKeys() Create a SoftKeyBar that applies to the entire Form and return it for you to set the keys in it.
SoftKeyBar	makeSoftKeys(Object left, String leftLabel, Object right, String rightLabel) Create a SoftKeyBar that applies to the entire Form and set the left and right key functions.
static void	mb(String text)
void	menuItemSelected(MenuItem selected)
boolean	modifyForSmartPhone() This modifies the setup for the Form to be one suitable to run full screen on a SmartPhone compatible IF the application actually is running on a SmartPhone device.
void	onControlEvent(ControlEvent ev) Make sure you call super.onControlEvent() if you override this method.
void	onDataChangeEvent(DataChangeEvent ev)
void	onEvent(Event ev)
void	onSoftKey(int whichKey, String action, MenuItem selected) The default onEvent for a Form will call this method if a SoftKeyEvent is sent to the Form.
boolean	placeCancelOnLeft()
void	removeSoftKeyBarFor(Control c) Remove the SoftKeyBar for a particular Control or the default SoftKeyBar.
Form	setOKCancel() Set OK and Cancel keys appropriate for the platform and return this Form.
void	setSoftKeyBarFor(Control c, SoftKeyBar bar) Set the SoftKeyBar for a particular Control or the default SoftKeyBar.
void	setSoftKeyBarForAll(Vector controls, SoftKeyBar bar) Set the SoftKeyBar for a particular set of Controls.
void	setTitle(String newTitle) Change the title of the Form on-screen.
void	setTopLevelTitle(String newTitle) Change the title of the top-level Form on-screen even if this Form is not a top-level form.
protected void	setupFrame(FormFrame f, int options) This is used to do a customized setup of the FormFrame created for the Form.
FormFrame	show() This displays the Form non-modally in a new Window.
FormFrame	show(Frame parent) Deprecated.
FormFrame	show(Frame parent, EventListener listener) Deprecated.
FormFrame	show(Frame parent, EventListener listener, int options) Deprecated.
FormFrame	show(Frame parent, int options) This displays the Form non-modally within an already displayed parent Frame.
FormFrame	show(int options) Deprecated.
void	shown()
static void	showWait() This displays a wait cursor until the next Form is shown.
static void	stopFormHandle(Handle h, int retCode) This can be used to stop the Handle of a Form to indicate that it should be considered closed.
boolean	toolsOnBottom() Returns true if tools are best added to the bottom of Forms on this platform.
int	waitUntilClosed() This waits indefinitely for the form to close and returns the exitValue.
static int	waitUntilClosed(Handle h) Use this to wait on the Handle of a Form, without keeping a reference to the Form.
static int	waitUntilClosed(Handle h, TimeOut t) Use this to wait on the Handle of a Form, without keeping a reference to the Form.
boolean	waitUntilClosed(TimeOut howLong) This waits and returns true if it closed before the timeout.
boolean	waitUntilPainted(int timeOut) Call this ONLY after a show() call.

Methods inherited from class ewe.ui.CellPanel

calculateSizes, makeLayoutGrid, relayout, relayoutMe, removeAll, reShow, resize, resizeTo

Methods inherited from class ewe.ui.Panel

add, addChildListener, addDirectly, addLast, addLast, addNext, addNext, addNext, doBackground, doBorder, endRow, getControlTag, getPreferredSize, getSubControls, isEmpty, layout, remove, removeChildListener, sendToChildListeners, setText

Methods inherited from class ewe.ui.Canvas

canGo, canScreenScroll, checkScrolls, doScroll, fixOrigin, getActual, getBuffer, getCurrent, getDisplayedSize, getMySize, getPercent, getScrollablePanel, getScrollClient, getVisible, getVisibleArea, needScrollBar, onScroll, onSetOrigin, reduceClip, scroll, scroll, scrollToVisible, setOrigin, updateScrollServer

Methods inherited from class ewe.ui.Container

_paintChildren, add, containerHasFocus, dismantle, doHotKey, findChild, focusFirst, focusFirst, focusOnContainer, focusOnData, getChildren, getChildrenBackwards, getNextKeyFocus, gotFocus, lostFocus, repaintDataNow, takeFocus, takePromptControl

Methods inherited from class ewe.ui.Control

acceptsData, activate, addListener, addTimer, amOnTopFrame, calculateTextSize, cancelCut, cancelHoldDown, canEdit, chainDataChange, change, checkClipboardOperations, checkExitKey, checkMenu, checkMenuKey, checkModifiers, checkPenTransparent, clearTag, clipboardToString, clipboardTransfer, closeMenu, contains, contains, createGraphics, dataAccepted, dataBeingRemoved, dataDraggedOff, dataDraggedOver, dataDraggedOver, dataDroppedOn, dataTransferCancelled, deactivate, defaultTo, doAction, doActionKey, doMenu, dontAcceptDrop, doPaint, doPaintChildren, doPaintChildren, doPaintChildren, doPaintData, doPaintData, doShowMenu, dragged, exitEntry, fillBackground, fromClipboard, fromField, fromField, getAllDescendants, getAllSubControls, getBackground, getClipboardMenu, getClipObject, getControlBuffer, getControlBuffer, getDataRect, getDataToCopy, getDataToDragAndDrop, getDim, getDisplayText, getDragAndDropContext, getFont, getFontMetrics, getFontMetrics, getForeground, getFrame, getFrameOrContainer, getGraphics, getImage, getLastSelected, getLocation, getMaximumSize, getMenu, getMinimumSize, getModifiers, getNext, getParent, getPasswordCharacter, getPosInFrame, getPosInParent, getPreferredSize, getPrompt, getPromptText, getRect, getRect, getServer, getSize, getSizes, getTag, getText, getToolTip, getWindow, hasModifier, hasPopupFormAttached, hasTag, inheritModifiers, isChildOf, isModal, isOnMe, isSomeonesHotKey, makeFrameTopMost, makeHot, menuIsActive, modify, modifyAll, modifyAll, notifyAction, notifyDataChange, notifyDataChange, notNative_doPaintChildren, oldButWorksDoPaintChildren, oldPaintChildren, oldPostEvent, onKeyEvent, onLabelPenEvent, onPaint, onPenEvent, paintBackground, paintChildren, penClicked, penDoubleClicked, penHeld, penPressed, penReleased, penRightReleased, popupBeep, popupMenuClosed, popupMenuEvent, popupMenuEvent, postEvent, recalculatePreferredSize, redisplay, refresh, removeListener, removeTimer, repaint, repaintNow, repaintNow, repaintNow, requestPaint, requestResizeTo, resetRect, restore, scrollAndRepaint, sendToListeners, set, setBorder, setCell, setClipObject, setControl, setCursor, setFixedSize, setFont, setHotKey, setHotKey, setLocation, setMaximumSize, setMenu, setMinimumSize, setPreferredSize, setPromptControl, setRect, setRect, setServer, setTag, setTags, setTextSize, setToolTip, show, standardOnKeyEvent, startDragAndDrop, startDragAndDrop, startDragging, stopDragging, takeData, takeFromClipboard, testDim, ticked, toClipboard, toField, toField, toString, toTextData, transferPenPress, transferPenPress, tryDragAndDrop, tryNext, tryStartMenu, updateData, willAcceptDrop, willShowFrame

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode

Methods inherited from interface ewe.ui.ScrollClient

getServer, setServer

Field Detail

globalIcon

public static IImage globalIcon

untitledTitle

public static String untitledTitle

This is the default title that will be assigned to a new Form.

exitSystemOnClose

public boolean exitSystemOnClose

dismantleOnClose

public boolean dismantleOnClose

This tells the Form to dismantle itself when it closes.

resizable

public boolean resizable

keepFrame

public boolean keepFrame

This option tells the Form to keep a reference to the Frame it creates for itself to save time if it is closed and then re-shown.

resizeOnSIP

public boolean resizeOnSIP

If this is true then the Frame containing the Form will resize itself to avoid the SIP when the SIP is turned on.

moveable

public boolean moveable

hasTopBar

public boolean hasTopBar

noBorder

public boolean noBorder

acceptsDroppedFiles

public boolean acceptsDroppedFiles

Set this true to accept files dropped from the file manager.

handle

public Handle handle

This is used to monitor the state of the Form. It is only valid when show()/execute() is called on the Form.

yes

public Control yes

no

public Control no

cancel

public Control cancel

ok

public Control ok

apply

public Control apply

reset

public Control reset

deflt

public Control deflt

back

public Control back

windowIcon

public IImage windowIcon

buttonsPerRow

public int buttonsPerRow

Set this to be greater than zero to limit the number of buttons displayed at the bottom of the Form.

titleOK

public Control titleOK

If this is set to a control then this control will appear to the right of the title bar. If it is activated it will cause the form to exit with the value IDOK.

titleCancel

public Control titleCancel

If this is set to a control then this control will appear to the right of the title bar. If it is activated it will cause the form to exit with the value IDCANCEL.

buttons

protected Vector buttons

The buttons to be displayed at the bottom of the Form (if any) are stored here.

topControls

public CellPanel topControls

Use this to add controls to the top of the form, below the title bar. It is initially null, but you can create a CellPanel, add controls to it and set topControls to point to it. This panel will stretch horizontally across the top of the form but it will not stretch vertically. You can use it to add a menu bar, for example, to your form.

titleControls

public CellPanel titleControls

Use this to add controls to the title bar of the form. It is initially null, but you can create a CellPanel, add controls to it and then set titleControls to point to it. These controls will appear to the right of the title, but to the left of any titleOK or titleCancel buttons.

buttonsPanel

public CellPanel buttonsPanel

This is the panel that will contain any of the special buttons you add.

firstFocus

public Control firstFocus

This explicitly sets the control which will first get focus when the Form is displayed.

exitValue

public int exitValue

This is the value that was sent to close(int exitCode) or exit(int exitCode).

title

public String title

The title of the form.

windowTitle

public String windowTitle

If this is not null, then the window that the Form is displayed in will have its title set to this value regardless of whether it is the top level form or not.

exitButtonDefined

public boolean exitButtonDefined

This is set true when doButtons() is called to add close buttons to the form. If it is false when the form is displayed, then the Form will automatically add an OK button to the title of the form.

windowFlagsToSet

public int windowFlagsToSet

These are flags that you want to set for any new Window being created to display this Form. It should consist of WindowConstants.FLAG_xxx values OR'ed together.

windowFlagsToClear

public int windowFlagsToClear

These are flags that you want to clear for any new Window being created to display this Form. It should consist of WindowConstants.FLAG_xxx values OR'ed together.

taskbarIcon

public Window.TaskBarIconInfo taskbarIcon

Set this to be a valid Window.TaskBarIconInfo if you want to display an icon in the taskbar when this Form is displayed. It will replace the application icon with this and then restore it when it closes. If there is no application icon, it will add a new icon.

BUTTONS_TO_SOFT_KEY_FIRST_BUTTON_SEPARATE

public static int BUTTONS_TO_SOFT_KEY_FIRST_BUTTON_SEPARATE

BUTTONS_TO_SOFT_KEY_MENU_ALWAYS

public static int BUTTONS_TO_SOFT_KEY_MENU_ALWAYS

BUTTONS_TO_SOFT_KEY_USE_FIRST_SOFT_KEY

public static int BUTTONS_TO_SOFT_KEY_USE_FIRST_SOFT_KEY

formFrame

protected FormFrame formFrame

The Frame the Form is currently displayed in.

pl

protected PropertyList pl

The properties of the Form.

Constructor Detail

Form

public Form()

Method Detail

canExit

protected boolean canExit(int exitCode)

This is called by the exit() method to see if the form can be closed. It should return true if it can be closed and false if it cannot.

exit

public boolean exit(int exitCode)

This will call the canExit() method and if it returns true, it will close the form.

hasExitButton

public boolean hasExitButton()

Tests if the Form has an exit button defined for it.

Returns:

true if the Form has an exit button defined for it.

makeMenuItemForForm

public MenuItem makeMenuItemForForm(String label,
                                    String action,
                                    String iconName,
                                    Object maskOrColor)

makeMenuItemForForm

public MenuItem makeMenuItemForForm(String label,
                                    String action,
                                    IImage icon)

makeButtonForForm

public Control makeButtonForForm(String text,
                                 IImage icon,
                                 int hotkey)

makeButtonForForm

public Control makeButtonForForm(String text,
                                 String iconName,
                                 Object maskOrColor,
                                 int hotkey)

makeDefaultButton

public Control makeDefaultButton(int whichButton,
                                 String textToUse)

Create and return the default OK or Cancel button.

Parameters:

whichButton - one of OKB, DEFOKB, CANCELB, or DEFCANCELB.

textToUse - the text to use with the button, or null to use the icon only.

Returns:

the button created. You should assign this button to either the "ok" or "cancel" field.

makeDefaultButton

public Control makeDefaultButton(int whichButton,
                                 boolean useText)

Create and return the default OK or Cancel button.

Parameters:

whichButton - one of OKB, DEFOKB, CANCELB, or DEFCANCELB.

useText - true to use the standard OK/Cancel lables, false to use the icon only.

Returns:

the button created. You should assign this button to either the "ok" or "cancel" field.

placeCancelOnLeft

public boolean placeCancelOnLeft()

doButtons

public void doButtons(int which)

This is used to add a row of buttons at the bottom of the form, using The value of "which" can be the logical OR of any of the pre-defined button values (e.g. YESB|NOB|OKB).

addButton

public void addButton(Control b)

This is used to add custom buttons to the bottom of the bar.

getButton

public Control getButton(String text)

Used to create a new Button for the Form. By default it simply creates an mButton().

gatherButtons

public static Vector gatherButtons(Container buttons,
                                   Vector destination)

buttonsToSoftKeyBar

public boolean buttonsToSoftKeyBar(Container buttons,
                                   String menuName,
                                   int options)

Add a container which contains mButton objects to the SoftKeyBar.

buttonsToMenu

public Menu buttonsToMenu(Vector buttons,
                          Menu destination)

Add a Vector of mButton objects to a Menu.

buttonsToSoftKeyBar

public boolean buttonsToSoftKeyBar(Vector buttons,
                                   String menuName,
                                   int options)

Add a Vector of mButton objects to the SoftKeyBar.

checkButtons

protected void checkButtons()

This is called before the Form is displayed to setup the buttons as requested by doButtons(). If no exit button has been defined for the Form, then titleOK is set to a new button.

make

public void make(boolean reMake)

Description copied from class: Control

This is used to "make" the control before being displayed. This is usually only overridden by containers.

Overrides:

make in class CellPanel

makeFrame

protected FormFrame makeFrame(int options)

This is used to actually create the frame for the form. The implementation of this is simply: {return new FormFrame(this,options);} but it can be overridden to return a different FormFrame.

setupFrame

protected void setupFrame(FormFrame f,
                          int options)

This is used to do a customized setup of the FormFrame created for the Form.

showWait

public static void showWait()

This displays a wait cursor until the next Form is shown.

continueWait

public static void continueWait()

This requests that a wait Cursor be shown IF it was shown before the last Form was displayed - otherwise it has no effect. continueWait() is called automatically when a MessageBox exits.

cancelWait

public static void cancelWait()

This cancels the display of the wait Cursor IF it was requested.

mb

public static void mb(String text)

doShowExec

protected FormFrame doShowExec(Frame parent,
                               EventListener listener,
                               boolean modal,
                               int options)

All show()/exec()/execute() methods eventually call this method. It is used to create and display the Frame/Window for the Form. It also creates the Handle for the Form and sets it to Handle.Running.

Parameters:

parent - The parent Frame (may be null).

listener - A listener for listening to Form events (may be null).

modal - true if the Form is to be displayed modally.

options - one of the Gui.XXX_FRAME options along with the Gui.NEW_WINDOW option.

Returns:

The FormFrame created and displayed.

setTitle

public void setTitle(String newTitle)

Change the title of the Form on-screen. This will only work if the Form was shown()/executed() so that it is considered the top-level Form.

Parameters:

newTitle - The new title.

setTopLevelTitle

public void setTopLevelTitle(String newTitle)

Change the title of the top-level Form on-screen even if this Form is not a top-level form.

Parameters:

newTitle - The new title.

waitUntilPainted

public boolean waitUntilPainted(int timeOut)

Call this ONLY after a show() call. It waits until the Form has been painted. If the form is being placed in a new Window this will occur when the Window manager sends a PAINT message to the Window. If the Form is within an already displayed Frame then this will return immediately.

formShown

protected void formShown()

This is called to indicate that the Form has been made and has been displayed on the screen.

formClosing

protected void formClosing()

This is called to indicate that the Form is about to close and it causes a FormEvent.CLOSED event to be posted. If you override it you should call super.formClosing(). There is no way of stopping the Form closing at this point.

Overrides:

formClosing in class Control

waitUntilClosed

public final int waitUntilClosed()
                          throws IllegalStateException

This waits indefinitely for the form to close and returns the exitValue.

Returns:

the exitValue of the Form.

Throws:

IllegalStateException - if the Form has no handle (i.e. has not been opened).

waitUntilClosed

public static final int waitUntilClosed(Handle h,
                                        TimeOut t)
                                 throws InterruptedException,
                                        TimedOutException

Use this to wait on the Handle of a Form, without keeping a reference to the Form. This allows the Handle to be transferred to another Form while letting this Form be destroyed/garbage collected.

Parameters:

h - The handle of the Form (from the "handle" variable).

t - A TimeOut to wait form.

Returns:

The final exited value of the Form as placed in the Handle.

Throws:

InterruptedException - If the Thread was interrupted.

TimedOutException - If the TimeOut expired.

waitUntilClosed

public static final int waitUntilClosed(Handle h)

Use this to wait on the Handle of a Form, without keeping a reference to the Form. This allows the Handle to be transferred to another Form while letting this Form be destroyed/garbage collected.

Parameters:

h - The handle of the Form (from the "handle" variable).

Returns:

The final exited value of the Form as placed in the Handle.

waitUntilClosed

public final boolean waitUntilClosed(TimeOut howLong)
                              throws IllegalStateException

This waits and returns true if it closed before the timeout.

Throws:

IllegalStateException - if the Form has no handle (i.e. has not been opened).

closeForTransfer

public Handle closeForTransfer(boolean dismantle,
                               boolean showWait)

This closes the Form but does not set the handle to a stopped state, instead it returns the still running handle. This allows the handle to be transferred to another Form using setHandle(), so that any Threads waiting for this Form to close will then wait for the other Form to close instead.

Transferring the handle to another Form is done using the exec(Handle) method or exec(Handle,Parent,int) method.

Parameters:

dismantle - dismantle this Form after closing.

showWait - call the showWait() method to display a wait cursor until the next Form is displayed.

Returns:

The running handle for this open Form.

closeForTransfer

public Handle closeForTransfer()

This closes the Form but does not set the handle to a stopped state, instead it returns the still running handle. This allows the handle to be transferred to another Form using setHandle(), so that any Threads waiting for this Form to close will then wait for the other Form to close instead.

Transferring the handle to another Form is done using the exec(Handle) method or exec(Handle,Parent,int) method.

This Form will be dismantled after closing and the wait cursor will be displayed until the new Form is displayed.

Returns:

The running handle for this open Form.

execute

public final int execute(Frame parent,
                         int options)

This displays the Form modally within an already displayed parent Frame and then waits for the Form to close.

Parameters:

parent - The parent Frame for the Form. A null parent will indicate that a new Window should be created.

options - this should be one of:
Gui.CENTER_FRAME - Size the Frame to the preferred size of its contents and then display it centered in the parent frame (this is the most common option).
Gui.FILL_FRAME - Fill the entire parent frame.
Gui.FILL_WIDTH - Fill the entire width of the parent frame.
Gui.FILL_HEIGHT - Fill the entire height of the parent frame.
If options is 0 then the Frame will not be sized, positioned or painted although it will be added as a child of the parent Frame. In this case you must size and position the returned FormFrame yourself and then call repaintNow().

Returns:

The return value of the Form as sent to exit() or close().

execute

public final int execute()

This displays the Form modally in a new Window and waits for the Form to close. If the platform does not support multiple windows it will be displayed centered within the main application window.

Returns:

The return value of the Form as sent to exit() or close().

exec

public final FormFrame exec()

This displays the Form modally in a new Window. If the platform does not support multiple windows it will be displayed centered within the main application window.

Returns:

The FormFrame that was created and displayed.

exec

public final FormFrame exec(Frame parent,
                            int options)

This displays the Form modally within an already displayed parent Frame.

Parameters:

parent - The parent Frame for the Form. A null parent will indicate that a new Window should be created.

options - this should be one of:
Gui.CENTER_FRAME - Size the Frame to the preferred size of its contents and then display it centered in the parent frame (this is the most common option).
Gui.FILL_FRAME - Fill the entire parent frame.
Gui.FILL_WIDTH - Fill the entire width of the parent frame.
Gui.FILL_HEIGHT - Fill the entire height of the parent frame.
If options is 0 then the Frame will not be sized, positioned or painted although it will be added as a child of the parent Frame. In this case you must size and position the returned FormFrame yourself and then call repaintNow().

Returns:

The FormFrame that was created and displayed.

show

public final FormFrame show()

This displays the Form non-modally in a new Window. If the platform does not support multiple windows it will be displayed centered within the main application window.

Returns:

The FormFrame that was created and displayed.

show

public final FormFrame show(Frame parent,
                            int options)

This displays the Form non-modally within an already displayed parent Frame.

Parameters:

parent - The parent Frame for the Form. A null parent will indicate that a new Window should be created.

options - this should be one of:
Gui.CENTER_FRAME - Size the Frame to the preferred size of its contents and then display it centered in the parent frame (this is the most common option).
Gui.FILL_FRAME - Fill the entire parent frame.
Gui.FILL_WIDTH - Fill the entire width of the parent frame.
Gui.FILL_HEIGHT - Fill the entire height of the parent frame.
If options is 0 then the Frame will not be sized, positioned or painted although it will be added as a child of the parent Frame. In this case you must size and position the returned FormFrame yourself and then call repaintNow().

Returns:

The FormFrame that was created and displayed.

exec

public final FormFrame exec(Frame parent,
                            EventListener listener)

Deprecated.

exec

public final FormFrame exec(Frame parent,
                            EventListener listener,
                            int options)

Deprecated.

show

public final FormFrame show(int options)

Deprecated.

exec

public FormFrame exec(int options)

Deprecated.

execute

public final int execute(int options)

Deprecated.

show

public final FormFrame show(Frame parent)

Deprecated.

show

public final FormFrame show(Frame parent,
                            EventListener listener)

Deprecated.

show

public final FormFrame show(Frame parent,
                            EventListener listener,
                            int options)

Deprecated.

getFormFrame

public FormFrame getFormFrame(int options)

This is called when the Form is about to be displayed. It creates and returns a FormFrame with the contents set to be the Form.

dismantle

public void dismantle(Control stopAt)

Overrides:

dismantle in class Container

exec

public FormFrame exec(Handle transferredHandle)

This is used to exec a Form using the Handle from another Form (usually got from closeForTransfer()).

Parameters:

transferredHandle - The Handle to use for this Form.

Returns:

The FormFrame created.

exec

public FormFrame exec(Handle transferredHandle,
                      Frame parent,
                      int options)

This is used to exec a Form using the Handle from another Form (usually got from closeForTransfer()).

Parameters:

transferredHandle - The Handle to use for this Form.

parent - The parent Frame to exec() this Form in.

options - this should be one of:
Gui.CENTER_FRAME - Size the Frame to the preferred size of its contents and then display it centered in the parent frame (this is the most common option).
Gui.FILL_FRAME - Fill the entire parent frame.
Gui.FILL_WIDTH - Fill the entire width of the parent frame.
Gui.FILL_HEIGHT - Fill the entire height of the parent frame.
If options is 0 then the Frame will not be sized, positioned or painted although it will be added as a child of the parent Frame. In this case you must size and position the returned FormFrame yourself and then call repaintNow().

Returns:

The FormFrame created.

exec

public Handle exec(boolean dismantleOnClose)

Display the Form modally in a new Window and return the Handle that can be used to monitor the Form's open state using waitUntilClosed().

Parameters:

dismantleOnClose - The state to set the dismantleOnClose flag.

Returns:

the Handle that can be used to monitor the Form's open state using waitUntilClosed().

exec

public Handle exec(boolean dismantleOnClose,
                   Frame parent,
                   int options)

Display the Form modally in a parent Frame and return the Handle that can be used to monitor the Form's open state using waitUntilClosed().

Parameters:

dismantleOnClose - The state to set the dismantleOnClose flag.

parent - The parent Frame. If this is null then the Form will be displayed in a new Window.

options - this should be one of:
Gui.CENTER_FRAME - Size the Frame to the preferred size of its contents and then display it centered in the parent frame (this is the most common option).
Gui.FILL_FRAME - Fill the entire parent frame.
Gui.FILL_WIDTH - Fill the entire width of the parent frame.
Gui.FILL_HEIGHT - Fill the entire height of the parent frame.
If options is 0 then the Frame will not be sized, positioned or painted although it will be added as a child of the parent Frame. In this case you must size and position the returned FormFrame yourself and then call repaintNow().

Returns:

the Handle that can be used to monitor the Form's open state using waitUntilClosed().

getTopmostForm

public Form getTopmostForm()

closeAll

public void closeAll(int exitCode)

If this Form is embedded within another Form, then this will close the topmost Form.

stopFormHandle

public static void stopFormHandle(Handle h,
                                  int retCode)

This can be used to stop the Handle of a Form to indicate that it should be considered closed.

Parameters:

h - The Handle of the open Form.

retCode - The exit code the Form should report.

close

public void close(int exitCode)

This closes the form unconditionally and sets the exitValue to be exitCode.

makeSoftKeys

public SoftKeyBar makeSoftKeys(Object left,
                               String leftLabel,
                               Object right,
                               String rightLabel)

Create a SoftKeyBar that applies to the entire Form and set the left and right key functions.

Returns:

the SoftKeyBar.

makeSoftKeys

public SoftKeyBar makeSoftKeys()

Create a SoftKeyBar that applies to the entire Form and return it for you to set the keys in it. If you want a SoftKey which changes for a particular control, use setSoftKeyBarFor().

setSoftKeyBarFor

public void setSoftKeyBarFor(Control c,
                             SoftKeyBar bar)

Set the SoftKeyBar for a particular Control or the default SoftKeyBar.

Parameters:

c - the particular Control or null to set the default SoftKeyBar.

bar - The SoftKeyBar to use.

setSoftKeyBarForAll

public void setSoftKeyBarForAll(Vector controls,
                                SoftKeyBar bar)

Set the SoftKeyBar for a particular set of Controls.

Parameters:

controls - a Vector holding a set of Controls.

bar - The SoftKeyBar to use for each of the Controls.

getSoftKeyBarFor

public SoftKeyBar getSoftKeyBarFor(Control c)

Get the SoftKeyBar for a particular Control or the default SoftKeyBar.

Parameters:

c - the particular Control or null to get the default SoftKeyBar.

removeSoftKeyBarFor

public void removeSoftKeyBarFor(Control c)

Remove the SoftKeyBar for a particular Control or the default SoftKeyBar.

Parameters:

c - the particular Control or null to remove the default SoftKeyBar.

onControlEvent

public void onControlEvent(ControlEvent ev)

Make sure you call super.onControlEvent() if you override this method.

Overrides:

onControlEvent in class Control

handleAction

public boolean handleAction(String action)

Handle an action type event. This method is called by the default handleAction(ControlEvent ev) method and also by the default menuItemSelected() method and onSoftKey() method. By default this method checks if the action is equal to any of the EXIT_XXX constants and if it is it will call exit() with the appropriate exit code.

Parameters:

action - the action value.

Returns:

true to tell the Form the event has been handled, false if not.

handleAction

public boolean handleAction(ControlEvent ev)

Handle a ControlEvent that is of type PRESSED and for which the "action" field is not null. This method is called by the default onControlEvent(). By default this method returns a call to handleAction(String action).

Parameters:

ev - The Control Event.

Returns:

true to tell the Form the event has been handled and not to pass the event to its parents, false to continue normal event dispatching.

menuItemSelected

public void menuItemSelected(MenuItem selected)

onSoftKey

public void onSoftKey(int whichKey,
                      String action,
                      MenuItem selected)

The default onEvent for a Form will call this method if a SoftKeyEvent is sent to the Form. By default it calls handleAction(String action).

Parameters:

whichKey - the SoftKey that was pressed, either 1 or 2.

action - the action associated with the key or menu item.

selected - if a MenuItem was selected, this will be the selected item.

onEvent

public void onEvent(Event ev)

Specified by:

onEvent in interface EventListener

Overrides:

onEvent in class CellPanel

onDataChangeEvent

public void onDataChangeEvent(DataChangeEvent ev)

filesDropped

public void filesDropped(String[] fileNames)

This is called when files are dropped on the Form and acceptsDroppedFiles is true.

Parameters:

fileNames - the list of fileNames dropped.

getProperties

public PropertyList getProperties()

Description copied from interface: HasProperties

Get the PropertyList object associated with this object.

Specified by:

getProperties in interface HasProperties

_getSetField

public boolean _getSetField(String fieldName,
                            Wrapper wrapper,
                            boolean isGet)

A special method used by ewe.reflect.FieldTransfer() to transfer data to and from controls and properties.

toolsOnBottom

public boolean toolsOnBottom()

Returns true if tools are best added to the bottom of Forms on this platform.

addToolbar

public CellPanel[] addToolbar()

A very useful method for creating a Form with a toolbar or menubar. It places it in the most appropriate place for the platform. If the platform supports a SIP button on the screen (e.g. PocketPC) then a SipButton placeholder will be put in the toolbar and the SIP button will always be visible once the Form is displayed.

Returns:

An array of CellPanels. The panel at index 0 will be the panel you should use for your toolbar. The panel at index 1 will be the panel for adding your main controls.

addTabbedPanel

public Control[] addTabbedPanel(boolean useExpandingTabs)

A very useful method for creating a Form with a tabbed panel. It places it in the most appropriate place for the platform.

Parameters:

useExpandingTabs - set this true if you wish for the created tabbed panel to be the autoexpanding type.

Returns:

An array of Controls. The Control at index 0 will be the tabbed panel you should use. If you specified an expanding tabbed panel, then the panel at index 1 will be the panel for adding your main controls - otherwise it will be null.

defaultTitleTo

public void defaultTitleTo(String newTitle)

This will set the title of the Form if it has not already been set.

createWindow

public Window createWindow()

This creates a new Window for the Form on request (when being shown). You can use this to setup the window icon.

Returns:

a new Window for the Form.

getFirstFocus

protected Control getFirstFocus()

Overrides:

getFirstFocus in class Container

shown

public void shown()

Overrides:

shown in class Control

modifyForSmartPhone

public boolean modifyForSmartPhone()

This modifies the setup for the Form to be one suitable to run full screen on a SmartPhone compatible IF the application actually is running on a SmartPhone device.

Setup the title and other Form options before calling this method.

Returns:

true if the application IS running on a SmartPhone device.

setOKCancel

public Form setOKCancel()

Set OK and Cancel keys appropriate for the platform and return this Form.

createMenuItem

public MenuItem createMenuItem(String label,
                               String action,
                               String iconName,
                               Object maskOrColor)

createMenuItem

public MenuItem createMenuItem(String label,
                               String action,
                               IImage icon)

createMenuItem

public MenuItem createMenuItem(mButton button)

Return a MenuItem that will be used as a proxy for a specific buton. When the menu item is selected the specified button will fire of an action event (ControlEvent.PRESSED)