incubator.net.xoetrope.xui
Class XPageHelper

java.lang.Object
  incubator.net.xoetrope.xui.XPageHelper

public class XPageHelper

extends java.lang.Object

A class used by XPage to implement its functionality in a reusable way

Copyright (c) Xoetrope Ltd., 2002-2004

License: see license.txt

hand

public static final java.awt.Cursor hand

Hand Cursor Object instance

componentFactory

public XStyleFactory componentFactory

The XComponentFactory being used

dataBindings

public XDataBindingContext dataBindings

The context for data binding management

pathEvaluator

public XPathEvaluator pathEvaluator

An evaluator of paths, attribs etc...

hiddenComponents

public java.util.Vector hiddenComponents

Vector of components to be hidden or shown over page transitions

eventHandler

public XuiEventHandler eventHandler

The XuiEventHandler being used by the XPage

attribs

public java.util.Hashtable attribs

Hashtable of named component attributes

status

public int status

Indicates current state of the XPage in itÝs lifecycle

clearPage

public boolean clearPage

boolean to indicate how to handle repaints of the page

currentProject

public XProject currentProject

The currently active XProject instance

adapter

public WidgetAdapter adapter

For handling different component packages

page

public PageSupport page

The PageSupport being helped

evaluator

protected XPathEvaluator evaluator

The default evaluator for databinding paths

pageName

public java.lang.String pageName

The name of the page

XPageHelper

public XPageHelper(PageSupport thePage)

Creates a new instance of XPageHelper

Parameters:

thePage - The XPageHelper to be used

getPageName

public java.lang.String getPageName()

Get the name of this page

Returns:

the page name

setPageName

public void setPageName(java.lang.String name)

Get the name of this page

Parameters:

name - the page name

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.

Parameters:

value - boolean to apply to clearPage

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.

Parameters:

recursionLevel - The level to which the components should be shown

container - the container

visible - the

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.

Parameters:

name - the name to locate

Returns:

the component ornull 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.

Parameters:

container - the page or container to search

name - the name to locate

Returns:

the component or null if nothing is found

setExceptionHandler

public void setExceptionHandler(XExceptionHandler eh)

Set the validation exception handler called when a validation exception is trapped

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.

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.

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

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.

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

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 ele)

Adds a validation to this page.

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

ele - 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

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

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

Parameters:

vf - The XValidationFactory to be used

setValidationFactory

public void setValidationFactory(java.lang.String vf)

Sets the factory used to create XValidator objects. It is assumed that the file can be found on the classpath and that it can be read as UTF8 (by default)

Parameters:

vf - the filename

getValidationHandler

public XValidationHandler getValidationHandler()

Gets the validation handler

Returns:

the validation handler

validationHandler

public int validationHandler(XuiEventHandler eventHandler)

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

Parameters:

eventHandler - the current event handler that this handler will use to listen to for events that should trigger validations

Returns:

the maximum level returned by the validators

getEventHandler

public XuiEventHandler getEventHandler()

Get the current event handler

Returns:

the event handler

setEventHandler

public void setEventHandler(XuiEventHandler eh)

Set the current event handler

Parameters:

eh - The XuiEventHandler to be used

getCurrentEvent

public java.util.EventObject getCurrentEvent()

Get the current event

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

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.ClassNotFoundException,
                       java.lang.NoSuchMethodException

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

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.ClassNotFoundException - throw if the class cannot be found

java.lang.NoSuchMethodException - throw if the method cannot be found

isFocusChangeSuppressed

public boolean isFocusChangeSuppressed()

Check the focus change status

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

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

addMenuHandler

public void addMenuHandler(java.lang.Object menuItem,
                           java.lang.String methodName)

Adds a handler for action events

Parameters:

menuItem - the component that fires the event

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

See Also:

ActionListener, ActionEvent

addActionHandler

public void addActionHandler(java.lang.Object comp,
                             java.lang.String methodName)

Adds a handler for action events

Parameters:

comp - the component that fires the events

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

See Also:

ActionListener, ActionEvent

addFocusHandler

public void addFocusHandler(java.lang.Object comp,
                            java.lang.String methodName)

Adds a handler for focus events

Parameters:

comp - the component that fires the events

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

See Also:

FocusListener, FocusEvent

addTextHandler

public void addTextHandler(java.lang.Object comp,
                           java.lang.String methodName)

Adds a handler for text events

Parameters:

comp - the component that fires the events

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

See Also:

TextListener, TextEvent

addItemHandler

public void addItemHandler(java.lang.Object comp,
                           java.lang.String methodName)

Adds a handler for item events

Parameters:

comp - the component that fires the events

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

See Also:

ItemListener, ItemEvent

addKeyHandler

public void addKeyHandler(java.lang.Object comp,
                          java.lang.String methodName)

Adds a handler for key events

Parameters:

comp - the component that fires the events

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

See Also:

KeyListener, KeyEvent

addMouseHandler

public void addMouseHandler(java.lang.Object comp,
                            java.lang.String methodName)

Adds a handler for mouse events

Parameters:

comp - the component that fires the events

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

See Also:

MouseMotionListener, MouseEvent

addMouseMotionHandler

public void addMouseMotionHandler(java.lang.Object comp,
                                  java.lang.String methodName)

Adds a handler for mouse motion events

Parameters:

comp - the component that fires the events

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

See Also:

MouseMotionListener, MouseEvent

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.

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.

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.

Returns:

true if the mouse was right clicked

showHandCursor

public void showHandCursor(java.lang.Object comp)

Show the hand/pointer cursor for this component

Parameters:

comp - the component

getBindings

public java.util.Vector getBindings()

Retrieve the Vector of XDataBinding for the XPage

Returns:

Vector of XDataBinding

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.

Parameters:

b - the binding

removeBinding

public void removeBinding(XDataBinding b)

Remove a binding of a component to the data model.

Parameters:

b - the binding

updateBindings

public void updateBindings()

Iterate all of the bindings in the page to reflect the model state.

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.

Parameters:

binding - The databinding to be updated

updateBoundComponentValues

public void updateBoundComponentValues()

Update the UI with values from the model

saveBoundComponentValues

public void saveBoundComponentValues()

Save the component values to the model

getBinding

public XDataBinding getBinding(java.lang.Object targetComp)

Find the data binding associated with a component

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

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

Returns:

the current status

setStatus

public void setStatus(int newStatus)

Set the page status

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

pageCreated

public void pageCreated()

A method called once the page has been created but not yet initialized.

pageDeactivated

public void pageDeactivated()

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

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.

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 an attribute value

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 an attribute value

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

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

Parameters:

c - Not used

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()}

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

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

Parameters:

path - the path to strip

Returns:

the stripped path

getComponentFactory

public XComponentFactory getComponentFactory()

Get the component factory instance being used by this page.

Returns:

the component factory

setComponentFactory

public void setComponentFactory(XStyleFactory factory)

Set the component factory instance being used by this page when constructing new pages.

Parameters:

factory - The XComponentFactory to be used

translate

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

Used to translate strings found in the 'content' attribute of a component declaration and translate it using the localization resource bundles

Parameters:

key - The key into the ResourceBundle

Returns:

The translated key if found otherwise the passed string

showMessage

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

Shows a modal message box

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

Parameters:

parent - the message dialog parent

title - the message dialog title

msg - the text of the message