net.xoetrope.xui
Interface PageSupport

All Superinterfaces:
XExceptionHandler
All Known Implementing Classes:
NavigationHelper, XDialog, XDialog, XMessageBox, XMessageBox, XPage, XSwtPage

public interface PageSupport
extends XExceptionHandler

    

Some common page methods

Copyright (c) Xoetrope Ltd., 2002-2005

License: see license.txt

$Revision: 1.9 $


Method Summary
 int accumulateMessages(boolean start, int level)
          Informs the handler when a page validation is starting or stopping.
 void addActionHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for action events
 void addBinding(XDataBinding b)
          Add a binding of a component to the data model.
 void addFocusHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for focus events
 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 addItemHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for item events
 void addKeyHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for key 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 addMenuHandler(java.lang.Object menuItem, java.lang.String methodName)
          Adds a handler for action events
 void addMouseHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for mouse events
 void addMouseMotionHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for mouse motion events
 void addTextHandler(java.lang.Object comp, java.lang.String methodName)
          Adds a handler for text events
 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
 void doLayout()
          Layout the page
 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 an attribute value
 java.lang.Object getAttribute(java.lang.String attribName, java.lang.String compName)
          Gets an attribute value
 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 for the page
 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
 java.lang.Object getEventAttribute(java.lang.Object c, java.lang.String attribName)
          Gets an attribute value belonging to a component
 XuiEventHandler getEventHandler()
          Get the current event handler
 java.lang.String getName()
          Get the name of the page
 java.lang.Object getOwner()
          Get the parent
 java.awt.Dimension getPageSize()
          Get the size
 int getStatus()
          Get the page status
 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 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 when the page is about to loose scope and be hidden.
 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 setBackground(java.awt.Color c)
          Set the background color
 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 setLayout(java.lang.Object obj)
          Set the layout manager
 void setLocation(int x, int y)
          Set the page location
 void setName(java.lang.String name)
          Set the name of the component
 void setSize(int width, int height)
          Set the page size
 void setStatus(int newStatus)
          Set the page status
 void setValidationFactory(java.lang.String vf)
          Sets the factory used to create XValidator objects.
 void setValidationFactory(XValidationFactory vf)
          Sets the factory used to create XValidator objects
 void setVisible(boolean state)
          Set the visible state of the component
 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
 java.lang.String stripAttributeValues(java.lang.String path)
          Remove the attribute paths from a path e.g.
 java.lang.String translate(java.lang.String key)
          Get the translatation refernced by the key
 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 with values from the model
 void validate()
          Validates this container and all of its subcomponents.
 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.
 

Method Detail

setBackground

void setBackground(java.awt.Color c)
Set the background color

Parameters:
c - The color

setLayout

void setLayout(java.lang.Object obj)
Set the layout manager

Parameters:
obj - the layout manager instance

doLayout

void doLayout()
Layout the page


getName

java.lang.String getName()
Get the name of the page

Returns:
the name

setVisible

void setVisible(boolean state)
Set the visible state of the component

Parameters:
state - true to make the component visible

setClearPage

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 - the new flag value, true to clear

showComponents

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 - a counter of the recursion level
container - the container
visible - true to show the components

findComponent

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

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

setName

void setName(java.lang.String name)
Set the name of the component

Parameters:
name - the new name for the page

setExceptionHandler

void setExceptionHandler(XExceptionHandler eh)
Set the validation exception handler called when a validation exception is trapped

Parameters:
eh - the new event handler

handleException

boolean handleException(java.lang.Object comp,
                        java.lang.Exception ex,
                        java.lang.Object validator)
A method called when a validation exeption has been trapped.

Specified by:
handleException in interface XExceptionHandler
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

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

void clearValidations()
Reset/removes all validations


checkValidations

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

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

Specified by:
accumulateMessages in interface XExceptionHandler
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

XValidator addValidation(java.lang.Object comp,
                         java.lang.String validationName,
                         java.lang.String method,
                         int mask,
                         XmlElement pageEle)
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
pageEle - the XML element which is declared in the page
Returns:
the new and initialized XValidator

addValidation

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

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

void setValidationFactory(XValidationFactory vf)
Sets the factory used to create XValidator objects

Parameters:
vf - The validation factory

setValidationFactory

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

XValidationHandler getValidationHandler()
Gets the validation handler

Returns:
the validation handler

validationHandler

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

Returns:
the maximum level returned by the validators

getEventHandler

XuiEventHandler getEventHandler()
Get the current event handler

Returns:
the event handler

setEventHandler

void setEventHandler(XuiEventHandler eh)
Set the current event handler

Parameters:
eh - The event handler

getCurrentEvent

java.util.EventObject getCurrentEvent()
Get the current event

Returns:
the AWTEvent that was last triggered

addListener

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

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

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 - couldn't find or add the event handler

addHandler

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

isFocusChangeSuppressed

boolean isFocusChangeSuppressed()
Check the focus change status

Returns:
true if the focus change events are being suppressed.

addMenuHandler

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

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

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

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

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

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

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

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

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

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

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

void showHandCursor(java.lang.Object comp)
Show the hand/pointer cursor for this component

Parameters:
comp - the component

getBindings

java.util.Vector getBindings()
Get the data bindings for the page

Returns:
the bindings

addBinding

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

void removeBinding(XDataBinding b)
Remove a binding of a component to the data model.

Parameters:
b - the binding

updateBindings

void updateBindings()
Iterate all of the bindings in the page to reflect the model state.


updateBinding

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 data binding to update

updateBoundComponentValues

void updateBoundComponentValues()
Update the UI with values from the model


saveBoundComponentValues

void saveBoundComponentValues()
Save the component values to the model


getBinding

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

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

int getStatus()
Get the page status

Returns:
the current status

setStatus

void setStatus(int newStatus)
Set the page status

Parameters:
newStatus - the new page status

pageActivated

void pageActivated()
A method called once the page has been created and initialized but just prior to display


pageCreated

void pageCreated()
A method called once the page has been created but not yet initialized.


pageDeactivated

void pageDeactivated()
Called when the page is about to loose scope and be hidden.


setAttribute

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

java.lang.Object getAttribute(java.lang.String attribName)
Gets an attribute value

Parameters:
attribName - the name of the attribute
Returns:
the value

getAttribute

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

getComponentName

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

java.lang.Object getEventAttribute(java.lang.Object c,
                                   java.lang.String attribName)
Gets an attribute value belonging to a component

Parameters:
c - the component/container
attribName - the name of the attribute
Returns:
the value

evaluateAttribute

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

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

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

XComponentFactory getComponentFactory()
Get the component factory instance being used by this page.

Returns:
the component factory

setComponentFactory

void setComponentFactory(XStyleFactory factory)
Set the component factory instance being used by this page when constructing new pages.

Parameters:
factory - the component factory used for component creation

translate

java.lang.String translate(java.lang.String key)
Get the translatation refernced by the key

Parameters:
key - the language string lookup key
Returns:
The translated text

showMessage

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

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

validate

void validate()
Validates this container and all of its subcomponents.


getOwner

java.lang.Object getOwner()
Get the parent

Returns:
The owner container

getPageSize

java.awt.Dimension getPageSize()
Get the size

Returns:
The page's dimensions

setSize

void setSize(int width,
             int height)
Set the page size

Parameters:
width - the new page width
height - the new page height

setLocation

void setLocation(int x,
                 int y)
Set the page location

Parameters:
x - the new page's left edge coordinate
y - the new page's top coordinate