Package com.dassault_systemes.catjdialog

   
Class CATDialog

 
Class Hierarchy
java.lang.Object
  |
  +-com.dassault_systemes.catjdialog.CATCallbackSource
        |
        +-com.dassault_systemes.catjdialog.CATDialog
Class Location

Framework : CATJDialog

Module : CATJDialog

Class Description

public abstract class CATDialog

The base graphical component class.

Description:

Every JDialog graphical component extends this class. It factorizes general properties and notifications.

Introducing 'Properties' and 'Notifications':

Each JDialog graphical component exposes properties and notifications (see CATCallbackSource and CATNotification).

Properties are attributes that represent the component content/state.
A component exposing a property involves that it has:

Example: the checkbox component exposes a State property.
Then the CATCheckBox class exposes:
    public boolean getState()
    public void setState(boolean)

Notifications are (user) events that the component may fire, and that the application may register to.
A component exposing a notification involves that it has a method with the following signature:
    public <Notif_Type> get<Notif_Name>Notification()
    <Notif_Type> being CATNotification or a subclass.

Example: the button component exposes a ButtonActivated notification.
Then the CATButton class exposes:
    public CATNotification getButtonActivatedNotification()

Properties and notifications are clearly identified in the javadoc of each JDialog component.

Introducting XMLDlg file format:

Although JDialog allows to build applications in a pure programmatic and dynamic way, it also offers the possibility to describe the user interface in xml resource files.
Those are XMLDlg files.
Although using the CAA UI Builder hides the XMLDlg mysteries, here is a short explanation of how it works.

The XMLDlg format allows to:

Sample: let's study the following XMLDlg excerpt

 <?xml version="1.0"?>
   <Frame onCreate="onCreate" Controller="com.mypackage.MyController" DefaultButton="AddButton">
     <Table Name="List" Attribute="_list" SelectionMode="LINE_SELECTION_MODE" onToolbar="onCommand" onMenu="onCommand"/>
     <TextField Name="Field" Attribute="_field" Text="please enter text"/>
     <Button Name="AddButton" onButtonActivated="onAdd"/>
     [...]
 

Message Catalog files and implicit property mappings:

Each JDialog command (XMLDlg file) may come with its associated message catalog file(s).
Those are CATNls files.
This file format is comparable to the standard Java Properties file (a list of 'tag=value' entries), and supports NLS.

All component properties that are displayed to the end-user (such as a CATButton title, a CATLabel text, a tooltip, ...), support an implicit mapping to the message catalog file.
The entry is of the form:
<relative_component_path>.<Ppty_Mapping> = "the message value";

Message Catalog Implicit Mappings are clearly identified in the javadoc of each JDialog component.

Sample: here is an XMLDlg with its associated CATNls file

XMLDlg fileCATNls file
<?xml version="1.0"?>
<!-- XMLDlg file for MySearch command -->
<DialogBox onCreate="onCreate"
           Controller="com.mypackage.MySearch">
  <Frame Name="frame">
    <WebPartFrame Name="search">
      <Frame Name="f">
        <Label Name="CriteriaLabel"/>
        <TextField Name="Criteria"
                   Attribute="_criteria"/>
        <Button Name="Search"
                onButtonActivated="onSearch"/>
        [...]
      </Frame>
    </WebPartFrame>
    <WebPartFrame Name="results">
      <Table Name="Table" Attribute="_results"/>
    </WebPartFrame>
  [...]
  </Frame>
</DialogBox>
// --- English Message Catalog for MySearch command

// 'search' WebPartFrame title
frame.search.Title = "Search: ";

// 'CriteriaLabel' Label text
frame.search.f.CriteriaLabel.Title = "Criteria: ";

// 'Search' Button label
frame.search.f.Search.Title = "Search";

// 'Search' Button tooltip
frame.search.f.Search.Tooltip = "Click Here To Search";

// 'results' WebPartFrame title
frame.results.Title = "Results: ";

CATDialog Properties:

CATDialog Notifications:

See Also:
com.dassault_systemes.catjdialog.CATDocumentManager
Field Summary

Constructor Summary
CATDialog(CATDialog iParent, String iName)
This is the base constructor for any graphical component.

Method Summary
protected boolean displayChild(CATDialog iChild)
Tries to display the given child component.
protected void errorBox(CATError iError)
Causes an error box to show up.
public boolean getAsyncRefreshable()
Determines whether this component may be refreshed asynchronously.
public CATDialog getChild(String iName)
Returns the child component with the given name.
public Enumeration getChildren()
Returns the list of children components.
public CATNotification getCreateNotification()
The component creation notification.
public CATNotification getDestroyNotification()
The component destruction notification.
public CATNotification getDocumentChangedNotification()
The component document changed notification.
public final Object getExtension(String iExtension)
Returns the renderer object associated to this component class.
protected String getExtensionClass(String iClass, String iExtension)
Returns the name of an extension class.
public String getName()
Returns the component name (that was passed in the constructor).
public CATNotification getNewChildNotification()
The component new child notification.
public String getNLS(String iMessage, String iDefault)
Retreives a NLS message from the command message catalog.
public String[] getNotifications()
Returns the list of notification names exposed by this component.
public CATDialog getParent()
Returns the parent component of this component.
public String getPath()
Returns the component absolute path.
public Object[][] getProperties()
Returns the list of property names and types exposed by the given component.
public Object getProperty(String iName)
Returns a property value by name.
public CATNotification getRemoveChildNotification()
The component remove child notification.
public CATSession getSession()
Returns the user session.
public boolean getVisibility()
Returns whether this component is visibile or not.
public boolean hasChildren()
Returns the list of children components.
protected static CATDialog instanciate(CATDialog iParent, CATXMLNode iNode, Object iController, String iMessageCatalog)
Instanciate a component hierarchy from an XML document
public CATDialog instanciate(String iFile)
This helper method calls instanciate(iFile, iFile)
public CATDialog instanciate(String iFile, String iName)
Instanciates a component from an XMLDlg file.
The created component is then added as a child of this component.
public CATDialog instanciate(String iFile, String iName, Object iController)
Helper method for instanciate.
protected boolean isChildDisplayed(CATDialog iChild)
Determines whether the child component is displayed by this component.
public boolean isDisplayed()
Determines whether this component is displayed on screen or not.
public void requestAsyncRefresh()
This method triggers the asynchronous refresh mechanism on this component.
public void requestDestruction()
Destroys this component.
public CATDialog search(String iPath)
Searches a component child from its path.
public void setAsyncRefreshable(boolean iRefreshable)
Sets whether this component may be refreshed asynchronously.
public void setProperty(String iName, String iValue)
Sets a property value by name, from a string.
public void setVisibility(boolean iVisibility)
Changes this component visibility (true displays it, false hides it).
public boolean show()
Tries to have this component displayed on screen.
public String toString()
Returns a string representation of the component object.


Field Detail

Constructor Detail

CATDialog

    CATDialog(CATDialog iParent, String iName)

This is the base constructor for any graphical component.

Parameters:
iParent
The parent component.
iName
This component name. Here are some rules for this name:
  • It is set in the constructor, and cannot be changed afterwards.
  • The name must be unique for the parent (2 children with the same name are not allowed).
  • The name may not contain any ot the following characters: '.' (dot), ' ' (blank), '_' (underscore)

Method Detail

displayChild

    protected boolean displayChild(CATDialog iChild)

Tries to display the given child component.

This is involved in the show() method implementation.

Parameters:
iChild
The child component to display.
Return:
the status of the attempt (true = succeeded / false = failed).

errorBox

    protected void errorBox(CATError iError)

Causes an error box to show up.

Parameters:
iError
the error to dislpay

getAsyncRefreshable

    public boolean getAsyncRefreshable()

Determines whether this component may be refreshed asynchronously.

Return:
true if this component may be refreshed asynchronously; false otherwise.

getChild

    public CATDialog getChild(String iName)

Returns the child component with the given name.

Parameters:
iName
The name of the child component to retreive.
Return:
The child component with the specified name (null if not found).

getChildren

    public Enumeration getChildren()

Returns the list of children components.

Return:
An Enumeration of CATDialog objects, or null if this component has no child.

getCreateNotification

    public CATNotification getCreateNotification()

The component creation notification.

This notification is sent right after the component is instantiated and added to its parent.

Return:
The component creation notification.

getDestroyNotification

    public CATNotification getDestroyNotification()

The component destruction notification.

This notification is sent right before the component is removed from its parent and destroyed.

Return:
The component destruction notification.

getDocumentChangedNotification

    public CATNotification getDocumentChangedNotification()

The component document changed notification.

This notification is sent by the top command component every time the command document changes (including when activating of stacking the command).

Return:
The component document changed notification.
See Also:
CATDocumentManager

getExtension

    public final Object getExtension(String iExtension)

Returns the renderer object associated to this component class.

This method is called by the framework to retreive renderer classes.

Parameters:
iExtension
The renderer type (html, xml).
Return:
The component renderer object.

getExtensionClass

    protected String getExtensionClass(String iClass, String iExtension)

Returns the name of an extension class.

Overload this method for custom widgets that are not part of the com.dassault_systemes.catjdialog package.

Parameters:
iClass
The graphical component class.
iExtension
The renderer type (html, xml).
Return:
The associated component renderer class name.

getName

    public String getName()

Returns the component name (that was passed in the constructor).

Return:
This component name.

getNewChildNotification

    public CATNotification getNewChildNotification()

The component new child notification.

This notification is sent right after a new child is added to this component.

Return:
The component new child notification.

getNLS

    public String getNLS(String iMessage, String iDefault)

Retreives a NLS message from the command message catalog.

NLS messages are defined in CATNls resource files in the runtime view.
Navigate in component hierarchy to find a message catalog.

Parameters:
iMessage
The catalog entry name.
iDefault
The default message (if the entry is not found).
Return:
The NLS message associated to the given entry, retreived from the right message catalog.

getNotifications

    public String[] getNotifications()

Returns the list of notification names exposed by this component.

The list of notifications is retreived by introspecting methods with the following signature:
   CATNotification get<Notif_Name>Notification()

Return:
A String array of notification names.

getParent

    public CATDialog getParent()

Returns the parent component of this component.

Return:
The parent component of this component.

getPath

    public String getPath()

Returns the component absolute path.

This path is built up with component names from the top component to this one, separated with '/' characters.
Note: The path identifies uniquely the component in a user session (no other component may share the same path).

Return:
This component absolute path.

getProperties

    public Object[][] getProperties()

Returns the list of property names and types exposed by the given component.

The list of properties is retreived by introspecting methods with the following signature:
   <Ppty_Type> get<Ppty_Name>()
   void set<Ppty_Name>(<Ppty_Type>)

Return:
A two-columned array: column 0 contains the property names (String), column 1 contains property types (String).

getProperty

    public Object getProperty(String iName)

Returns a property value by name.

Returns the property value by invoking <Ppty_Type> get<Ppty_Name>()
This method might throw an Error if the given method is not found or not accessible.

Parameters:
iName
The property name.
Return:
The evaluated property value.

getRemoveChildNotification

    public CATNotification getRemoveChildNotification()

The component remove child notification.

This notification is sent right before new child is removed from this component.

Return:
The component remove child notification.

getSession

    public CATSession getSession()

Returns the user session.

Return:
The user session.

getVisibility

    public boolean getVisibility()

Returns whether this component is visibile or not. Default is visible.

Return:
true if this component is visible; false otherwise.

hasChildren

    public boolean hasChildren()

Returns the list of children components.

Return:
An Enumeration of CATDialog objects, or null if this component has no child.

instanciate

    protected static CATDialog instanciate(CATDialog iParent, CATXMLNode iNode, Object iController, String iMessageCatalog)

Instanciate a component hierarchy from an XML document


instanciate

    public CATDialog instanciate(String iFile)

This helper method calls instanciate(iFile, iFile)

Parameters:
iFile
The root XMLDlg file name, with no path and extension.
Return:
The new instantiated component.

instanciate

    public CATDialog instanciate(String iFile, String iName)

Instanciates a component from an XMLDlg file.
The created component is then added as a child of this component.

Parameters:
iFile
The root XMLDlg file name, with no path and extension.
iName
The name that will be given to the instantiated child component.
Return:
The new instantiated component.

instanciate

    public CATDialog instanciate(String iFile, String iName, Object iController)

Helper method for instanciate.

Parameters:
iFile
The root XMLDlg file name, with no path and extension.
iName
The name that will be given to the instantiated child component.
iController
The controller object to attach to the instantiated children components.
Return:
The new instantiated component.

isChildDisplayed

    protected boolean isChildDisplayed(CATDialog iChild)

Determines whether the child component is displayed by this component.

This is involved in the isDisplayed() method implementation.

Parameters:
iChild
The child component to check.
Return:
true if the specified child component is displayed by this component; false otherwise.

isDisplayed

    public boolean isDisplayed()

Determines whether this component is displayed on screen or not.

This method checks that:

Return:
true if this component is displayed on screen; false otherwise.

requestAsyncRefresh

    public void requestAsyncRefresh()

This method triggers the asynchronous refresh mechanism on this component.


requestDestruction

    public void requestDestruction()

Destroys this component.

The component is first removed from its parent and then destroyed.


search

    public CATDialog search(String iPath)

Searches a component child from its path.

Parameters:
iPath
A component path (that is component names separated with '/').
Return:
The component if found from its path, or null otherwise.

setAsyncRefreshable

    public void setAsyncRefreshable(boolean iRefreshable)

Sets whether this component may be refreshed asynchronously.

Parameters:
iRefreshable
true makes this component "asynchronously refreshable".

setProperty

    public void setProperty(String iName, String iValue)

Sets a property value by name, from a string.

Sets the property value by invoking void set<Ppty_Name>(<Ppty_Type>) and trying to cast the given string value to the expected type.
This method might throw an Error if the given method is not found or not accessible, or if the string value cannot be casted into the expected type.

Parameters:
iName
The property name to change.
iValue
The property value to set (will be casted to the appropriate type).

setVisibility

    public void setVisibility(boolean iVisibility)

Changes this component visibility (true displays it, false hides it).

An invisible component is never displayed to the end user. It doesn't occupy any space in the page layout.

Parameters:
iVisibility
true makes this component visible; false hides it.

show

    public boolean show()

Tries to have this component displayed on screen.

This method proceeds as follows:

Return:
the status of the attempt (true = succeeded / false = failed).

toString

    public String toString()

Returns a string representation of the component object.

Return:
A string representation of this component.


Copyright © 2000, Dassault Systèmes. All rights reserved