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)

Method Summary
CATDialog getChild(String iName)
boolean getVisibility()
void setVisibility(boolean iVisibility)
boolean getAsyncRefreshable()
void setAsyncRefreshable(boolean iRefreshable)
void requestAsyncRefresh()
boolean isDisplayed()
boolean show()
boolean displayChild(CATDialog iChild)
boolean isChildDisplayed(CATDialog iChild)
Enumeration getChildren()
boolean hasChildren()
String[] getNotifications()
Object[][] getProperties()
Object getProperty(String iName)
void setProperty(String iName, String iValue)
CATNotification getCreateNotification()
CATNotification getDestroyNotification()
Object getExtension(String iExtension)
String getExtensionClass(String iClass, String iExtension)
String getName()
CATNotification getNewChildNotification()
String getNLS(String iMessage, String iDefault)
CATDialog getParent()
CATNotification getRemoveChildNotification()
CATNotification getDocumentChangedNotification()
CATDialog instanciate(String iFile, String iName)
CATDialog instanciate(String iFile)
CATDialog instanciate(String iFile, String iName, Object iController)
CATDialog instanciate(CATDialog iParent, CATXMLNode iNode, Object iController, String iMessageCatalog)
void requestDestruction()
String getPath()
CATDialog search(String iPath)
CATSession getSession()
void errorBox(CATError iError)
String toString()


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

getChild

    CATDialog getChild(String iName)

Returns the child component with the given name.

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

getVisibility

    boolean getVisibility()

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

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

setVisibility

    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.

getAsyncRefreshable

    boolean getAsyncRefreshable()

Determines whether this component may be refreshed asynchronously.

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

setAsyncRefreshable

    void setAsyncRefreshable(boolean iRefreshable)

Sets whether this component may be refreshed asynchronously.

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

requestAsyncRefresh

    void requestAsyncRefresh()

This method triggers the asynchronous refresh mechanism on this component.


isDisplayed

    boolean isDisplayed()

Determines whether this component is displayed on screen or not.

This method checks that:

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

show

    boolean show()

Tries to have this component displayed on screen.

This method proceeds as follows:

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

displayChild

    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.
Returns:
the status of the attempt (true = succeeded / false = failed).

isChildDisplayed

    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.
Returns:
true if the specified child component is displayed by this component; false otherwise.

getChildren

    Enumeration getChildren()

Returns the list of children components.

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

hasChildren

    boolean hasChildren()

Returns the list of children components.

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

getNotifications

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

Returns:
A String array of notification names.

getProperties

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

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

getProperty

    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.
Returns:
The evaluated property value.

setProperty

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

getCreateNotification

    CATNotification getCreateNotification()

The component creation notification.

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

Returns:
The component creation notification.

getDestroyNotification

    CATNotification getDestroyNotification()

The component destruction notification.

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

Returns:
The component destruction notification.

getExtension

    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).
Returns:
The component renderer object.

getExtensionClass

    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).
Returns:
The associated component renderer class name.

getName

    String getName()

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

Returns:
This component name.

getNewChildNotification

    CATNotification getNewChildNotification()

The component new child notification.

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

Returns:
The component new child notification.

getNLS

    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).
Returns:
The NLS message associated to the given entry, retreived from the right message catalog.

getParent

    CATDialog getParent()

Returns the parent component of this component.

Returns:
The parent component of this component.

getRemoveChildNotification

    CATNotification getRemoveChildNotification()

The component remove child notification.

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

Returns:
The component remove child notification.

getDocumentChangedNotification

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

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

instanciate

    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.
Returns:
The new instantiated component.

instanciate

    CATDialog instanciate(String iFile)

This helper method calls instanciate(iFile, iFile)

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

instanciate

    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.
Returns:
The new instantiated component.

instanciate

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

Instanciate a component hierarchy from an XML document


requestDestruction

    void requestDestruction()

Destroys this component.

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


getPath

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

Returns:
This component absolute path.

search

    CATDialog search(String iPath)

Searches a component child from its path.

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

getSession

    CATSession getSession()

Returns the user session.

Returns:
The user session.

errorBox

    void errorBox(CATError iError)

Causes an error box to show up.

Parameters:
iError
the error to dislpay

toString

    String toString()

Returns a string representation of the component object.

Returns:
A string representation of this component.


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