net.xoetrope.xui
Class XPage

java.lang.Object
  java.awt.Component
      java.awt.Container
          net.xoetrope.xui.XPage

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, XExceptionHandler, PageSupport

Direct Known Subclasses:

NavigationHelper, XDialog, XDialog, XToolbar

public class XPage
extends java.awt.Container
implements XExceptionHandler, PageSupport

A basic unit for building applications. XPage integrates with page and event management facilities provided by XUI. The page also provides a number of methods to help control the page lifecycle and many methods to manage the state of the user interface. Most application functionality within an application will be implemented in derivates of the page class, however this is not strictly necessary and the page can act as little more than a container for the user interface components.

Pages can be displayed using the XPageDisplay interface implemented by XApplet and invoked by the XPage manager. Pages can be constructed directly or via the XuiBuilder. The page lifecycle also interaccts with the data bindings, triggering data updates and saving.

The page implements the PageSupport interface which abstracts many of the methods used by the XUI framework to interact with its notion of a page. Through the PageSupport interface the framework can interact with pages that are implement with Widget sets such as Swing and SWT which have different hierarchies and diffent means of instantiation.

The XPage class is little more than a shell and many of its methods are implemented by the XPageHelper class, the page delegates to an instance of the page helper. The page also defines a set of constants for common components, but the page and moreover the framework is not limited to just these components.

Copyright (c) Xoetrope Ltd., 2002-2006

License: see license.txt

$Revision: 2.33 $

See Also:

Serialized Form

Nested Class Summary

static interface

XPage.IXDialog A bare interface used to distinguish dialogs from normal pages and checked by the PageManager when loading pages

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

static int	ACTIVATED The page has been activated
protected WidgetAdapter	adapter The component adapter for the current widget set.
static java.lang.String	ANNOTATEDIMAGE Deprecated. merged with imagemap
protected static boolean	antiAlias The antialias member controls use of antialiasing.
static int	BORDER_LAYOUT ID for a border layout
static int	BOX_LAYOUT This type of layout simulates the Swing layout by using a GridLayout such that the layoutStyle attribute indicates vertical or horizontal layout.
static java.lang.String	BUTTON Tag for a push button
static int	CARD_LAYOUT ID for a card layout
static java.lang.String	CHECK Tag for a checkbox
static int	COLUMN_LAYOUT ColumnLayout ID
static java.lang.String	COMBO Tag for a combo box or drop down list
protected XStyleFactory	componentFactory Deprecated. use getComponentFactory() instead.
static int	CREATED The page has been created
static int	DEACTIVATED The page has been deactivated
static int	DISCARDED The page has been discarded
static int	DISPLAYED The page has been activated and displayed
static java.lang.String	EDIT A single text editing field
static int	FLOW_LAYOUT ID for a flow layout
static int	GRID_LAYOUT ID for a grid layout
static int	GRIDBAG_LAYOUT ID for a grid bag layout
static java.lang.String	GROUP Tag for a radio button group
static int	GUIDE_LAYOUT GuideLayout ID
static java.lang.String	HOTSPOTIMAGE Tag for a hotspot image
static java.lang.String	IMAGE Tag for an image component
static java.lang.String	IMAGEMAP Tag for an image map
static java.lang.String	LABEL Tag for a label component
static int	LAYER_LAYOUT LayerLayout ID
static java.lang.String	LIST Tag for a list box
static int	LOADED The page has been loaded
static java.lang.String	MENU Tag for a menu
static java.lang.String	MENUBAR Tag for a menubar
static java.lang.String	MENUITEM Tag for a menu item
static java.lang.String	METACONTENT Tag for Tagged text
static int	NULL_LAYOUT ID for an NULL layout
protected XPageHelper	pageHelper The helper class that implements many functions on behalf of the page, particularly the widget specific operations and those operations specified by the PageSupport interface.
protected XPageManager	pageMgr The page manager for the current project, the page manager controls the update and display of pages.
static java.lang.String	PANEL Tag for a panel
static java.lang.String	PASSWORD Tag for a password edit field
protected XProject	project The owner project.
static java.lang.String	RADIO Tag for a radio button
protected XModel	rootModel The root model of the current project.
static int	SCALE_LAYOUT ScaleLayout ID
static java.lang.String	SCROLLABLEMETACONTENT Tag for a Scrollable tagged text
static java.lang.String	SCROLLPANE Tag for a scroll pane
static java.lang.String	SPLITPANE Tag for a splitter
static int	SPRING_LAYOUT SpringLayout ID
static java.lang.String	TABLE Tag for a table component
static java.lang.String	TABPANEL Tag for a tabbed panel
static java.lang.String	TEXTAREA Tag for a multiline text field
static java.lang.String	UNKNOWN Tag for an unknown component type (not one of the built-in types)
static int	UNKNOWN_PAGE_STATE The page state is unknown
static java.lang.String	WMF Tag for a vector image
static java.lang.String	XUI_AWT_PACKAGE The package name for the built-in AWT component
static java.lang.String	XUI_HTML_PACKAGE The package name for the built-in HTML components
static java.lang.String	XUI_SWING_PACKAGE The package name for the built-in Swing component
static java.lang.String	XUI_SWT_PACKAGE The package name for the built-in SWT components

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

XPage()
Constructs an empty page, setting up the references to projects, data models and so on plus setting up a component factory to help instantiate the page's children.

Method Summary

int	accumulateMessages(boolean start, int level) Informs the handler when a page validation is starting or stopping.
void	addBinding(XDataBinding b) Add a binding of a component to the data model.
void	addHandler(java.lang.Object comp, long eventType, java.lang.String methodName) Adds an event handler.
void	addHandler(java.lang.Object srcObj, java.lang.String methodName, java.lang.String adderMethod, java.lang.String listenerInterface, long eventMask, java.lang.Object listener) Adds a handler for action events
void	addListener(java.lang.Object comp, java.lang.String listenerName, java.lang.String argType, java.lang.Object listener) Adds a listener for an event type.
void	addNotify() Repaint the component once it has been created
XValidator	addValidation(java.lang.Object comp, java.lang.String validationName) Adds a validation to this page.
XValidator	addValidation(java.lang.Object comp, java.lang.String validationName, java.lang.String method) Adds a validation to this page.
XValidator	addValidation(java.lang.Object comp, java.lang.String validationName, java.lang.String method, int mask, XmlElement pageEle) Adds a validation to this page.
int	checkValidations() Check all validations for this page.
void	clearValidations() Reset/removes all validations
java.lang.Object	evaluateAttribute(java.lang.String attribValue) Evaluates an attribute value.
java.lang.String	evaluatePath(java.lang.String path) Evaluates a path (potentially) containing a method call
java.lang.Object	findComponent(java.lang.Object container, java.lang.String name) Find a named component in the container.
java.lang.Object	findComponent(java.lang.String name) Find a named component in the container.
java.lang.Object	getAttribute(java.lang.String attribName) Gets the value of an attribute of this page
java.lang.Object	getAttribute(java.lang.String attribName, java.lang.String compName) Gets the value of an attribute of the named component.
java.lang.Object	getAttributes() Gets the table of attributes used by this page.
XDataBinding	getBinding(java.lang.Object targetComp) Find the data binding associated with a component
XDataBinding	getBinding(java.lang.String targetPath) Find the data binding associated with a data source path
java.util.Vector	getBindings() Get the data bindings
XComponentFactory	getComponentFactory() Get the component factory instance being used by this page.
java.lang.String	getComponentName(java.lang.Object comp) Get a name for a component.
java.util.EventObject	getCurrentEvent() Get the current event.
XDataBindingContext	getDataBindingContext() Get the XDataBindingContext object bound to this page
java.lang.Object	getEventAttribute(java.lang.Object c, java.lang.String attribName) Gets an attribute value
XuiEventHandler	getEventHandler() Get the current event handler.
java.lang.String	getExtension() Get the file extension of this page.
java.awt.Graphics	getGraphics() Customizes the graphics context by adding anti-aliasing rendering hints if the start-up parameter AntiAlias=true
java.lang.Object	getOwner() Get the parent
java.lang.String	getPageName() Get the name of this page.
java.awt.Dimension	getPageSize() Get the size of the page
XProject	getProject() Get the current project, the project that owns this page
int	getStatus() Get the page status, indicating whther the page has been created, activated and so on
XValidationHandler	getValidationHandler() Gets the validation handler
boolean	handleEventHandlerException(XProject project, java.lang.Object container, java.lang.Throwable error) Handle an exception during the invocation of a page's event handler.
boolean	handleException(java.lang.Object comp, java.lang.Exception ex, java.lang.Object validator) A method called when a validation exeption has been trapped.
boolean	isFocusChangeSuppressed() Check the focus change status.
void	layout() Deprecated. As of JDK version 1.1, replaced by doLayout().
void	pageActivated() A method called once the page has been created and initialized but just prior to display.
void	pageCreated() A method called once the page has been created but not yet initialized.
void	pageDeactivated() Called whenver the page is about to loose scope and be hidden.
void	paint(java.awt.Graphics g) Paint the background of this component with the background color
void	paintSuper(java.lang.Object g) Get the super class to paint the background
void	removeBinding(XDataBinding b) Remove a binding of a component to the data model.
void	saveBoundComponentValues() Save the component values to the model
void	setAttribute(java.lang.String attribName, java.lang.String compName, java.lang.Object attribValue) Set a named attributes.
void	setClearPage(boolean value) Modify the clearPage flag.
void	setComponentFactory(XStyleFactory factory) Set the component factory instance being used by this page when constructing new pages.
void	setEventHandler(XuiEventHandler eh) Set the current event handler
void	setExceptionHandler(XExceptionHandler eh) Set the validation exception handler called when a validation exception is trapped.
void	setExtension(java.lang.String ext) Get the file extension of this page
void	setLayout(java.lang.Object obj) Set the layout manager
void	setPageName(java.lang.String name) Get the name of this page
void	setStatus(int newStatus) Set the page status
void	setValidationFactory(XValidationFactory vf) Sets the factory used to create XValidator objects
void	showComponents(java.lang.Object container, boolean visible, int recursionLevel) Show or hide the components.
void	showHandCursor(java.lang.Object comp) Show the hand/pointer cursor for this component.
void	showMessage(java.lang.Object parent, java.lang.String title, java.lang.String msg) Shows a modal message box.
void	showMessage(java.lang.String title, java.lang.String msg) Shows a modal message box.
PageSupport	showPage(java.lang.String className) Load and show a page.
PageSupport	showPage(java.lang.String className, java.lang.String target) Load and show a page and show it in a named target area.
PageSupport	showPrevious() Show the previously displayed page.
java.lang.String	stripAttributeValues(java.lang.String path) Remove the attribute paths from a path e.g. remove @value=ignore
java.lang.String	translate(java.lang.String key) Translate a string by looking it up in the current resource bundle.
void	update(java.awt.Graphics g) Overrides the update method so as to allow the suppression of the default clearing of the background.
void	updateBinding(XDataBinding binding) Update the bound model node for the binding.
void	updateBindings() Iterate all of the bindings in the page to reflect the model state.
void	updateBoundComponentValues() Update the UI components with values from the model
static void	updateChildLayouts(java.awt.Container parent) Update any children or children of children that have a layout.
int	validationHandler() Invoke the validators for the last event.
boolean	wasMouseClicked() A utility method used to determine if the last event corrseponds to a mouse click.
boolean	wasMouseDoubleClicked() A utility method used to determine if the last event corrseponds to a mouse double click.
boolean	wasMouseRightClicked() A utility method used to determine if the last event corrseponds to a mouse right click.

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.xoetrope.xui.PageSupport

doLayout, getName, setBackground, setLocation, setName, setSize, setVisible, validate

Field Detail

XUI_AWT_PACKAGE

public static final java.lang.String XUI_AWT_PACKAGE

The package name for the built-in AWT component

See Also:

Constant Field Values

XUI_SWING_PACKAGE

public static final java.lang.String XUI_SWING_PACKAGE

The package name for the built-in Swing component

See Also:

Constant Field Values

XUI_SWT_PACKAGE

public static final java.lang.String XUI_SWT_PACKAGE

The package name for the built-in SWT components

See Also:

Constant Field Values

XUI_HTML_PACKAGE

public static final java.lang.String XUI_HTML_PACKAGE

The package name for the built-in HTML components

See Also:

Constant Field Values

UNKNOWN

public static final java.lang.String UNKNOWN

Tag for an unknown component type (not one of the built-in types)

See Also:

Constant Field Values

PANEL

public static final java.lang.String PANEL

Tag for a panel

See Also:

Constant Field Values

LABEL

public static final java.lang.String LABEL

Tag for a label component

See Also:

Constant Field Values

RADIO

public static final java.lang.String RADIO

Tag for a radio button

See Also:

Constant Field Values

CHECK

public static final java.lang.String CHECK

Tag for a checkbox

See Also:

Constant Field Values

COMBO

public static final java.lang.String COMBO

Tag for a combo box or drop down list

See Also:

Constant Field Values

LIST

public static final java.lang.String LIST

Tag for a list box

See Also:

Constant Field Values

IMAGE

public static final java.lang.String IMAGE

Tag for an image component

See Also:

Constant Field Values

EDIT

public static final java.lang.String EDIT

A single text editing field

See Also:

Constant Field Values

BUTTON

public static final java.lang.String BUTTON

Tag for a push button

See Also:

Constant Field Values

METACONTENT

public static final java.lang.String METACONTENT

Tag for Tagged text

See Also:

Constant Field Values

GROUP

public static final java.lang.String GROUP

Tag for a radio button group

See Also:

Constant Field Values

SCROLLPANE

public static final java.lang.String SCROLLPANE

Tag for a scroll pane

See Also:

Constant Field Values

SCROLLABLEMETACONTENT

public static final java.lang.String SCROLLABLEMETACONTENT

Tag for a Scrollable tagged text

See Also:

Constant Field Values

HOTSPOTIMAGE

public static final java.lang.String HOTSPOTIMAGE

Tag for a hotspot image

See Also:

Constant Field Values

TABLE

public static final java.lang.String TABLE

Tag for a table component

See Also:

Constant Field Values

WMF

public static final java.lang.String WMF

Tag for a vector image

See Also:

Constant Field Values

ANNOTATEDIMAGE

public static final java.lang.String ANNOTATEDIMAGE

Deprecated. merged with imagemap

Tag for an annotated image component

See Also:

Constant Field Values

MENUBAR

public static final java.lang.String MENUBAR

Tag for a menubar

See Also:

Constant Field Values

MENU

public static final java.lang.String MENU

Tag for a menu

See Also:

Constant Field Values

MENUITEM

public static final java.lang.String MENUITEM

Tag for a menu item

See Also:

Constant Field Values

TEXTAREA

public static final java.lang.String TEXTAREA

Tag for a multiline text field

See Also:

Constant Field Values

PASSWORD

public static final java.lang.String PASSWORD

Tag for a password edit field

See Also:

Constant Field Values

IMAGEMAP

public static final java.lang.String IMAGEMAP

Tag for an image map

See Also:

Constant Field Values

TABPANEL

public static final java.lang.String TABPANEL

Tag for a tabbed panel

See Also:

Constant Field Values

SPLITPANE

public static final java.lang.String SPLITPANE

Tag for a splitter

See Also:

Constant Field Values

NULL_LAYOUT

public static final int NULL_LAYOUT

ID for an NULL layout

See Also:

Constant Field Values

BORDER_LAYOUT

public static final int BORDER_LAYOUT

ID for a border layout

See Also:

Constant Field Values

FLOW_LAYOUT

public static final int FLOW_LAYOUT

ID for a flow layout

See Also:

Constant Field Values

CARD_LAYOUT

public static final int CARD_LAYOUT

ID for a card layout

See Also:

Constant Field Values

GRID_LAYOUT

public static final int GRID_LAYOUT

ID for a grid layout

See Also:

Constant Field Values

GRIDBAG_LAYOUT

public static final int GRIDBAG_LAYOUT

ID for a grid bag layout

See Also:

Constant Field Values

BOX_LAYOUT

public static final int BOX_LAYOUT

This type of layout simulates the Swing layout by using a GridLayout such that the layoutStyle attribute indicates vertical or horizontal layout. A layoutStyle of '0' indicates a vertical layout and any other value indicates a horizontal layout.

See Also:

Constant Field Values

SPRING_LAYOUT

public static final int SPRING_LAYOUT

SpringLayout ID

See Also:

Constant Field Values

SCALE_LAYOUT

public static final int SCALE_LAYOUT

ScaleLayout ID

See Also:

Constant Field Values

GUIDE_LAYOUT

public static final int GUIDE_LAYOUT

GuideLayout ID

See Also:

Constant Field Values

LAYER_LAYOUT

public static final int LAYER_LAYOUT

LayerLayout ID

See Also:

Constant Field Values

COLUMN_LAYOUT

public static final int COLUMN_LAYOUT

ColumnLayout ID

See Also:

Constant Field Values

UNKNOWN_PAGE_STATE

public static final int UNKNOWN_PAGE_STATE

The page state is unknown

See Also:

Constant Field Values

LOADED

public static final int LOADED

The page has been loaded

See Also:

Constant Field Values

CREATED

public static final int CREATED

The page has been created

See Also:

Constant Field Values

ACTIVATED

public static final int ACTIVATED

The page has been activated

See Also:

Constant Field Values

DISPLAYED

public static final int DISPLAYED

The page has been activated and displayed

See Also:

Constant Field Values

DEACTIVATED

public static final int DEACTIVATED

The page has been deactivated

See Also:

Constant Field Values

DISCARDED

public static final int DISCARDED

The page has been discarded

See Also:

Constant Field Values

project

protected XProject project

The owner project. Each page belongs to a single project and normally there is just one instance of a page per project. The project provides many resources and acts as a central, coordinating point for referencing such resources.

pageMgr

protected XPageManager pageMgr

The page manager for the current project, the page manager controls the update and display of pages. References to the instantiated pages are held by the page manager even if the pages are not currently visible.

rootModel

protected XModel rootModel

The root model of the current project. The data model acts as a hierachical collection of objects that can be referenced via an XPath like syntax. The data bindings generally reference objects in this data model. The rootModel is the root node in the model with all other nodes being children of this node. Normally the rootModel is a singleton (within a project).

adapter

protected WidgetAdapter adapter

The component adapter for the current widget set. The page as an abstract entity does not deal directly with components of one widget set or another, instead it interacts with the widgets via a widget adapter that provides a common set of interfaces needed to manage the page. The adapter does not however try to provide a full interface the widgets, rather it provides just those interface methods needed by the page.

pageHelper

protected XPageHelper pageHelper

The helper class that implements many functions on behalf of the page, particularly the widget specific operations and those operations specified by the PageSupport interface.

componentFactory

protected XStyleFactory componentFactory

Deprecated. use getComponentFactory() instead.

The component factory used by this page. The factory instantiates components and sets the basic style of those components.

antiAlias

protected static boolean antiAlias

The antialias member controls use of antialiasing. By default it is turned off so page graphics are not automatically antialiased

Constructor Detail

XPage

public XPage()

Constructs an empty page, setting up the references to projects, data models and so on plus setting up a component factory to help instantiate the page's children.

Method Detail

getPageName

public java.lang.String getPageName()

Get the name of this page. The page name is used internally by the page manager to reference the page.

Returns:

the page name

setPageName

public void setPageName(java.lang.String name)

Get the name of this page

Parameters:

name - the page name

getProject

public XProject getProject()

Get the current project, the project that owns this page

Specified by:

getProject in interface PageSupport

Returns:

the owner project

getExtension

public java.lang.String getExtension()

Get the file extension of this page. The page file extension is used internally by the page manager to reference the page.

Specified by:

getExtension in interface PageSupport

Returns:

the page file extension

setExtension

public void setExtension(java.lang.String ext)

Get the file extension of this page

Specified by:

setExtension in interface PageSupport

Parameters:

ext - the page file extension

update

public void update(java.awt.Graphics g)

Overrides the update method so as to allow the suppression of the default clearing of the background. If the background is not to be cleared then the clearPage flag can be set to false using the setClearPage method.

Overrides:

update in class java.awt.Container

Parameters:

g - the graphics context

paintSuper

public void paintSuper(java.lang.Object g)

Get the super class to paint the background

Parameters:

g - the graphics context

paint

public void paint(java.awt.Graphics g)

Paint the background of this component with the background color

Overrides:

paint in class java.awt.Container

Parameters:

g - the graphics context

addNotify

public void addNotify()

Repaint the component once it has been created

Overrides:

addNotify in class java.awt.Container

setLayout

public void setLayout(java.lang.Object obj)

Set the layout manager

Specified by:

setLayout in interface PageSupport

Parameters:

obj - the layout manager

getOwner

public java.lang.Object getOwner()

Get the parent

Specified by:

getOwner in interface PageSupport

Returns:

the owner/parent of the page

getPageSize

public java.awt.Dimension getPageSize()

Get the size of the page

Specified by:

getPageSize in interface PageSupport

Returns:

the page dimensions

setClearPage

public void setClearPage(boolean value)

Modify the clearPage flag. This flag determines if the default behaviour is used to update the page whereby the background is first erased and then the content painted or alternatively if the erase is suppressed.

Specified by:

setClearPage in interface PageSupport

Parameters:

value - true to clear

getGraphics

public java.awt.Graphics getGraphics()

Customizes the graphics context by adding anti-aliasing rendering hints if the start-up parameter AntiAlias=true

Overrides:

getGraphics in class java.awt.Component

showComponents

public void showComponents(java.lang.Object container,
                           boolean visible,
                           int recursionLevel)

Show or hide the components. In the AWT the heavyweight peers are created visible and paint themselves once created and therefore cause problems for page transitions.

Specified by:

showComponents in interface PageSupport

Parameters:

recursionLevel - the number of layers of recursion (occurs with nested panels)

container - the container whose components are being modified

visible - the visibility flag, true to make the components visible

findComponent

public java.lang.Object findComponent(java.lang.String name)

Find a named component in the container. Any child containers of the container will be searched recursively till the named component is found. The first component with a matching name will be returned. The name is specified by the name attribute if the component is declared via XML. Component names should follow normal Java conventions.

Specified by:

findComponent in interface PageSupport

Parameters:

name - the name to locate

Returns:

the component or null if nothing is found

findComponent

public java.lang.Object findComponent(java.lang.Object container,
                                      java.lang.String name)

Find a named component in the container. Any child containers of the container will be searched recursively till the named component is found. The first component with a matching name will be returned.

Specified by:

findComponent in interface PageSupport

Parameters:

container - the page or container to search

name - the name to locate

Returns:

the component or null if nothing is found

layout

public void layout()

Deprecated. As of JDK version 1.1, replaced by doLayout().

Overrides:

layout in class java.awt.Container

updateChildLayouts

public static void updateChildLayouts(java.awt.Container parent)

Update any children or children of children that have a layout. XUI often uses null layouts and in some cases the children do not get laid out if a null layout is in use. This method therefore iterates the children, requesting them to update their layouts. The method is called recursively.

Parameters:

parent - the container to be laid out

setExceptionHandler

public void setExceptionHandler(XExceptionHandler eh)

Set the validation exception handler called when a validation exception is trapped. The exception handler can be customized to determine how exceptions and other errors are notified to the user.

Specified by:

setExceptionHandler in interface PageSupport

Parameters:

eh - the new event handler

handleException

public boolean handleException(java.lang.Object comp,
                               java.lang.Exception ex,
                               java.lang.Object validator)

A method called when a validation exeption has been trapped. Override this method if you want to customize a particluar error message. Alternatively a custom exception handler can be installed.

Specified by:

handleException in interface XExceptionHandler

Specified by:

handleException in interface PageSupport

Parameters:

comp - Component being validated

ex - The exception caused

validator - The validator being used to validate.

Returns:

true to continue with error validation or false to suppress further validation.

handleEventHandlerException

public boolean handleEventHandlerException(XProject project,
                                           java.lang.Object container,
                                           java.lang.Throwable error)

Handle an exception during the invocation of a page's event handler. The page normally implements this interface and has the first chance at handling the error. Thereafter if false is returned a central (optional) exception handler owned by the project is invoked.

Specified by:

handleEventHandlerException in interface XExceptionHandler

Specified by:

handleEventHandlerException in interface PageSupport

Parameters:

project - the current project

container - the page

error - the exception or error that was thrown

Returns:

true to continue processing, false to stop processing

clearValidations

public void clearValidations()

Reset/removes all validations

Specified by:

clearValidations in interface PageSupport

checkValidations

public int checkValidations()

Check all validations for this page. Typically this method should be invoked prior to a page transition or a critical transaction. The method causes all the validations rules on the page to be checked.

Specified by:

checkValidations in interface PageSupport

Returns:

the maximum error level raised by the validators

accumulateMessages

public int accumulateMessages(boolean start,
                              int level)

Informs the handler when a page validation is starting or stopping. Typically when it starts the page will begin to accumulate message which are to be displayed. When the parameter is false the page will usually display the accumulated messages. In some cases a validation rule may occur multiple times or there may be several validations on a single input field such that a user input may lead to several validation errors and therefore in such circumstances you may want to accumulate all the errors and display a single message to the user rather than bombarding the user with popup error message dialogs (which the user may just ignore). The accumulated messages may also be displayed in a console or some less intrusive way.

Specified by:

accumulateMessages in interface XExceptionHandler

Specified by:

accumulateMessages in interface PageSupport

Parameters:

start - boolean to indicate whether the accumulation is started or stopped.

level - int which indicates the most serious level of error encountered

Returns:

the new level which might be set to zero if a confirm dialog is displayed

addValidation

public XValidator addValidation(java.lang.Object comp,
                                java.lang.String validationName,
                                java.lang.String method,
                                int mask,
                                XmlElement pageEle)

Adds a validation to this page.

Specified by:

addValidation in interface PageSupport

Parameters:

comp - the component being validated

validationName - the name of the validation in the validation file

method - the method used to get the component's value if any

mask - the event mask used to filter the events that trigger the validation

pageEle - the XML element which is declared in the page

Returns:

the new and initialized XValidator

addValidation

public XValidator addValidation(java.lang.Object comp,
                                java.lang.String validationName,
                                java.lang.String method)

Adds a validation to this page. It is assumed that the validation will be invoked in response to FocusEvent.FOCUS_LOST events

Specified by:

addValidation in interface PageSupport

Parameters:

comp - the component being validated

validationName - the name of the validation in the validation file

method - the method used to get the component's value if any

Returns:

the new and initialized XValidator

addValidation

public XValidator addValidation(java.lang.Object comp,
                                java.lang.String validationName)

Adds a validation to this page. It is assumed that the validation will be invoked in response to FocusEvent.FOCUS_LOST events

Specified by:

addValidation in interface PageSupport

Parameters:

comp - the component being validated

validationName - the name of the validation in the validation file

Returns:

the new and initialized XValidator

setValidationFactory

public void setValidationFactory(XValidationFactory vf)

Sets the factory used to create XValidator objects

Specified by:

setValidationFactory in interface PageSupport

Parameters:

vf - The validation factory

getValidationHandler

public XValidationHandler getValidationHandler()

Gets the validation handler

Specified by:

getValidationHandler in interface PageSupport

Returns:

the validation handler

validationHandler

public int validationHandler()

Invoke the validators for the last event. Multiple validations are checked in the order in which they were added.

Specified by:

validationHandler in interface PageSupport

Returns:

the maximum level returned by the validators

getEventHandler

public XuiEventHandler getEventHandler()

Get the current event handler. The event handler provides a set of methods and interfaces used to respond to common events. The default event handler ultimately uses reflection to invoke a specific response method, but you can install a custom event handler using the setEventHandler method.

Specified by:

getEventHandler in interface PageSupport

Returns:

the event handler

setEventHandler

public void setEventHandler(XuiEventHandler eh)

Set the current event handler

Specified by:

setEventHandler in interface PageSupport

Parameters:

eh - The event handler

getCurrentEvent

public java.util.EventObject getCurrentEvent()

Get the current event. This method will return the last event, which may be required to distinguish the subtypes of a specific listener interface. XUI also provides some utility methods like wasMouseClicked which checks if the mouseListener interface's mouseClicked method was invoked. XUI does not paramterize its response methods to promote simplicity and because in most cases an application only processes a fraction of the methods provided by the listener interfaces - the trade-off however is that sometimes it is necessary to query details of the event. If it is a common requirement for your application to do such process consider building an extra helper

Specified by:

getCurrentEvent in interface PageSupport

Returns:

the AWTEvent that was last triggered

addListener

public void addListener(java.lang.Object comp,
                        java.lang.String listenerName,
                        java.lang.String argType,
                        java.lang.Object listener)

Adds a listener for an event type. This method should not normally be called by an application

Specified by:

addListener in interface PageSupport

Parameters:

comp - the component that fires events

listenerName - the name of the listener interface

argType - the listener arguments

listener - the listener implementation

addHandler

public void addHandler(java.lang.Object comp,
                       long eventType,
                       java.lang.String methodName)
                throws java.lang.Exception

Adds an event handler. A specific handler such as the addActionHandler should be used instead of calling this method

Specified by:

addHandler in interface PageSupport

Parameters:

comp - the component that fires the event

eventType - the event ID/mask

methodName - the method to be invoked in response to the object

Throws:

java.lang.Exception - The handler could not be found or added

isFocusChangeSuppressed

public boolean isFocusChangeSuppressed()

Check the focus change status. Sometimes the focus change events are suppressed within the XUI framework as validation errors may cause popup error messages (dialogs) to pop up, the popups then cause a change in focus, which in turn may cause other validation errors. Typically the focus change caused by these error dialogs is not what was intended when the validation rule was declared and therefore to suppress these unwanted errors the focus change can be suppressed. The error may also be self generating, making it impossible to correct the input if the validation rule fires when the error dialog is dismissed - again, suppressing the focus event rectifies the problem.

Specified by:

isFocusChangeSuppressed in interface PageSupport

Returns:

true if the focus change events are being suppressed.

addHandler

public void addHandler(java.lang.Object srcObj,
                       java.lang.String methodName,
                       java.lang.String adderMethod,
                       java.lang.String listenerInterface,
                       long eventMask,
                       java.lang.Object listener)

Adds a handler for action events

Specified by:

addHandler in interface PageSupport

Parameters:

srcObj - the menu item that fires the events

methodName - the method to be invoked in response to the action event

adderMethod - the adder method name e.g. addActionListener

listenerInterface - the listener interface e.g. java.awt.event.ActionListener

eventMask - the event mask e.g. AWTEvent.ACTION_EVENT_MASK

listener - the listener implementation, usually the page's this pointer

See Also:

ActionListener, ActionEvent

wasMouseClicked

public boolean wasMouseClicked()

A utility method used to determine if the last event corrseponds to a mouse click. The notion of a click is extended by assuming the a mouse press and release within a single component constitutes a click even if not at the same coordinate. A MouseEvent.MOUSE_CLICKED is only triggered when the press and release are at the same location and this is often inadequate for end-user interaction.

Specified by:

wasMouseClicked in interface PageSupport

Returns:

true if the mouse was clicked

wasMouseDoubleClicked

public boolean wasMouseDoubleClicked()

A utility method used to determine if the last event corrseponds to a mouse double click. The notion of a click is extended by assuming the a mouse press and release within a single component constitutes a click even if not at the same coordinate. A MouseEvent.MOUSE_CLICKED is only triggered when the press and release are at the same location and this is often inadequate for end-user interaction.

Specified by:

wasMouseDoubleClicked in interface PageSupport

Returns:

true if the mouse was double clicked

wasMouseRightClicked

public boolean wasMouseRightClicked()

A utility method used to determine if the last event corrseponds to a mouse right click. The notion of a click is extended by assuming the a mouse press and release within a single component constitutes a click even if not at the same coordinate. A MouseEvent.MOUSE_CLICKED is only triggered when the press and release are at the same location and this is often inadequate for end-user interaction.

Specified by:

wasMouseRightClicked in interface PageSupport

Returns:

true if the mouse was right clicked

showHandCursor

public void showHandCursor(java.lang.Object comp)

Show the hand/pointer cursor for this component. When the mouse is moved over the component the hand cursor will be displayed

Specified by:

showHandCursor in interface PageSupport

Parameters:

comp - the component

getBindings

public java.util.Vector getBindings()

Get the data bindings

Specified by:

getBindings in interface PageSupport

Returns:

the bindings collection

addBinding

public void addBinding(XDataBinding b)

Add a binding of a component to the data model. If the page has already been activated this method will update the binding automatically.

Specified by:

addBinding in interface PageSupport

Parameters:

b - the binding

removeBinding

public void removeBinding(XDataBinding b)

Remove a binding of a component to the data model.

Specified by:

removeBinding in interface PageSupport

Parameters:

b - the binding

updateBindings

public void updateBindings()

Iterate all of the bindings in the page to reflect the model state. The method is normally invoked upon a page transition.

Specified by:

updateBindings in interface PageSupport

updateBinding

public void updateBinding(XDataBinding binding)

Update the bound model node for the binding. First the output path is reevaluated and then updated by setting the output node. Then the source path is reevaluated and set. Evaluation of the paths allows derived classes to dynamically modify the bindings. Some bindings may save the selection or state information to the output node and subsequently use it to restore the component state. This method does not alter the data held by the bound model nodes. To actually save the data use saveBoundComponentValues and to update the UI use updateBoundComponentValues.

Specified by:

updateBinding in interface PageSupport

Parameters:

binding - the binding to update

updateBoundComponentValues

public void updateBoundComponentValues()

Update the UI components with values from the model

Specified by:

updateBoundComponentValues in interface PageSupport

saveBoundComponentValues

public void saveBoundComponentValues()

Save the component values to the model

Specified by:

saveBoundComponentValues in interface PageSupport

getDataBindingContext

public XDataBindingContext getDataBindingContext()

Get the XDataBindingContext object bound to this page

Returns:

XDataBindingContext object

getBinding

public XDataBinding getBinding(java.lang.Object targetComp)

Find the data binding associated with a component

Specified by:

getBinding in interface PageSupport

Parameters:

targetComp - the component whose binding is required

Returns:

the binding or null if no binding is found

getBinding

public XDataBinding getBinding(java.lang.String targetPath)

Find the data binding associated with a data source path

Specified by:

getBinding in interface PageSupport

Parameters:

targetPath - the path to the bound model

Returns:

the binding or null if no binding is found

getStatus

public int getStatus()

Get the page status, indicating whther the page has been created, activated and so on

Specified by:

getStatus in interface PageSupport

Returns:

the current status

setStatus

public void setStatus(int newStatus)

Set the page status

Specified by:

setStatus in interface PageSupport

Parameters:

newStatus - the new page status

pageActivated

public void pageActivated()

A method called once the page has been created and initialized but just prior to display. Override this method if you need to add custom behavior when the page is activated or displayed.

Specified by:

pageActivated in interface PageSupport

pageCreated

public void pageCreated()

A method called once the page has been created but not yet initialized. Override this method if you need to implement custom creation when the page is created. The method is only called when the page is instantiated and not when the page is redisplayed. The pageActivated method is invoked whenever a page is displayed.

Specified by:

pageCreated in interface PageSupport

pageDeactivated

public void pageDeactivated()

Called whenver the page is about to loose scope and be hidden.

Specified by:

pageDeactivated in interface PageSupport

setAttribute

public void setAttribute(java.lang.String attribName,
                         java.lang.String compName,
                         java.lang.Object attribValue)

Set a named attributes. The attributes are stored in a hashtable owned by the page. Derived classes may access the hashtable directly but the preferred method of access is the getAttribute method. Attributes are used by the XuiBuilder class for component attributes other than those it handles directly. The attributes can be thought of as component properties or extra data and need not be used directly by the component.

Attributes are stored using a key in the form attribName_compName or just the attribName if compName is null.

Specified by:

setAttribute in interface PageSupport

Parameters:

attribName - the attribute name

compName - the component name or null if it is a page attribute

attribValue - the attribute value

See Also:

getAttribute(java.lang.String)

getAttribute

public java.lang.Object getAttribute(java.lang.String attribName)

Gets the value of an attribute of this page

Specified by:

getAttribute in interface PageSupport

Parameters:

attribName - the name of the attribute

Returns:

the value

getAttribute

public java.lang.Object getAttribute(java.lang.String attribName,
                                     java.lang.String compName)

Gets the value of an attribute of the named component.

Specified by:

getAttribute in interface PageSupport

Parameters:

attribName - the name of the attribute

compName - the component name

Returns:

the value

getAttributes

public java.lang.Object getAttributes()

Gets the table of attributes used by this page. The method is not intended for general use and should be used with great care.

Returns:

the table of attributes

getComponentName

public java.lang.String getComponentName(java.lang.Object comp)

Get a name for a component. If the component doesn't have one use the component hashcode

Specified by:

getComponentName in interface PageSupport

Parameters:

comp - the component

Returns:

the name

getEventAttribute

public java.lang.Object getEventAttribute(java.lang.Object c,
                                          java.lang.String attribName)

Gets an attribute value

Specified by:

getEventAttribute in interface PageSupport

Parameters:

c - the component whose attribute is being requested

attribName - the name of the attribute

Returns:

the value

evaluateAttribute

public java.lang.Object evaluateAttribute(java.lang.String attribValue)

Evaluates an attribute value. An attribute may be a value or a method call. If brackets are part of the value it is assumed that a method call is intended. The method call is indicated by the '$' symbol e.g. ${myMethod()}

Specified by:

evaluateAttribute in interface PageSupport

Parameters:

attribValue - the raw attribute value

Returns:

the evaluated attribute

evaluatePath

public java.lang.String evaluatePath(java.lang.String path)

Evaluates a path (potentially) containing a method call

Specified by:

evaluatePath in interface PageSupport

Parameters:

path - the raw path

Returns:

the evaluated path

stripAttributeValues

public java.lang.String stripAttributeValues(java.lang.String path)

Remove the attribute paths from a path e.g. remove @value=ignore

Specified by:

stripAttributeValues in interface PageSupport

Parameters:

path - the path to strip

Returns:

the stripped path

getComponentFactory

public XComponentFactory getComponentFactory()

Get the component factory instance being used by this page. Normally the page instantiates an instance of the XStyleFactory but this can be changed at any time and this method returns the current instance.

Specified by:

getComponentFactory in interface PageSupport

Returns:

the component factory

setComponentFactory

public void setComponentFactory(XStyleFactory factory)

Set the component factory instance being used by this page when constructing new pages. Normally there is no need to change the component factory. If you need to instantiate a component not included by default the component registration mechanism should be used.

Specified by:

setComponentFactory in interface PageSupport

Parameters:

factory - the component factory

translate

public java.lang.String translate(java.lang.String key)

Translate a string by looking it up in the current resource bundle. The translator is a project resource and the resource bundle is also defined on an application level.

Specified by:

translate in interface PageSupport

Parameters:

key - the resource bundle key

Returns:

the translated text

showMessage

public void showMessage(java.lang.String title,
                        java.lang.String msg)

Shows a modal message box. The dialog is displayed in such a way that it does not trigger a focus change event.

Specified by:

showMessage in interface PageSupport

Parameters:

title - the message dialog title

msg - the text of the message

showMessage

public void showMessage(java.lang.Object parent,
                        java.lang.String title,
                        java.lang.String msg)

Shows a modal message box. The dialog is displayed in such a way that it does not trigger a focus change event.

Specified by:

showMessage in interface PageSupport

Parameters:

parent - the message dialog parent

title - the message dialog title

msg - the text of the message

showPage

public PageSupport showPage(java.lang.String className)

Load and show a page.

Parameters:

className - The name, without package info, of the page to be displayed

Returns:

the page being displayed

showPage

public PageSupport showPage(java.lang.String className,
                            java.lang.String target)

Load and show a page and show it in a named target area. The target areas are the named 'frames' of the frames file. The default 'content' area is used by default if the named area cannot be found.

Parameters:

className - The name, without package info, of the page to be displayed

target - the area to update

Returns:

the page being displayed

showPrevious

public PageSupport showPrevious()

Show the previously displayed page. Although the method works with framesets the page history applies only to the main content area.

Returns:

The previous XPage