org.swixml

Class SwingEngine


public class SwingEngine
extends java.lang.Object

The SwingEngine class is the rendering engine able to convert an XML descriptor into a java.swing UI.

Version:
$Revision: 1.4 $
Author:
Wolf Paulus

Field Summary

static boolean
DEBUG_MODE
Debug / Release Mode
static String
MAC_OSX_LOCALE_VARIANT
Mac OSX locale variant to localize strings like quit etc.
static String
MAC_OSX_OS_NAME
Mac OSX identifier in System.getProperty(os.name)
protected ClassLoader
cl
Localizer, setup by parameters found in the xml descriptor.

Constructor Summary

SwingEngine()
Default ctor for a SwingEngine.
SwingEngine(ClassLoader cl, String resource)
Deprecated.
SwingEngine(Object client)
Constructor to be used if the SwingEngine is not extend but used through object composition.
SwingEngine(String resource)
Constructs a new SwingEngine, rendering the provided XML into a javax.swing UI

Method Summary

int
cleanup()
Removes all un-displayable compontents from the id map and deletes the components collection (for recreation at the next request).
Component
find(String id)
Returns the UI component with the given name or null.
void
forget(String id)
Removes the id from the internal from the id map, to make the given id available for re-use.
Iterator
getAllComponentItertor()
Returns an Iterator for all parsed GUI components.
static Frame
getAppFrame()
ClassLoader
getClassLoader()
Object
getClient()
Returns the object which instantiated this SwingEngine.
Iterator
getDescendants(Component c)
Walks the whole tree to add all components into the components collection.
Iterator
getIdComponentItertor()
Returns an Iterator for id-ed parsed GUI components.
Map
getIdMap()
Returns the id map, containing all id-ed parsed GUI components.
Localizer
getLocalizer()
Container
getRootComponent()
Returns the root component of the generated Swing UI.
TagLibrary
getTaglib()
void
insert(Document jdoc, Container container)
Inserts swing objects rendered from an XML document into the given container.
void
insert(Reader reader, Container container)
Inserts swing objects rendered from an XML reader into the given container.
void
insert(String resource, Container container)
Inserts swing objects rendered from an XML reader into the given container.
void
insert(URL url, Container container)
Inserts swing object rendered from an XML document into the given container.
static boolean
isMacOSX()
Indicates if currently running on Mac OS X
static boolean
isMacOSXSupported()
Indicates state of Mac OS X support (default is true = ON).
protected void
mapMembers(Object obj)
Introspects the given object's class and initializes its non-transient fields with objects that have been instanced during parsing.
Container
render(Document jdoc)
Gets the parsing of the XML file started.
Container
render(File xml_file)
Gets the parsing of the XML file started.
Container
render(Reader xml_reader)
Gets the parsing of the XML file started.
Container
render(String resource)
Gets the parsing of the XML file started.
Container
render(URL url)
Gets the parsing of the XML started.
boolean
setActionListener(Component c, ActionListener al)
Recursively Sets an ActionListener

  Backtracking algorithm: if al was set for a child component, its not being set for its parent
 
.
static void
setAppFrame(Frame frame)
Sets the SwingEngine's global application frame variable, to be used as a parent for all child dialogs.
void
setClassLoader(ClassLoader cl)
Sets a classloader to be used for all getResourse..() and loadClass() calls.
static void
setDefaultLocale(Locale locale)
Sets the SwingEngine's global locale, to be used by all SwingEngine instances.
void
setLocale(Locale l)
Sets the locale to be used during parsing / String conversion
static void
setMacOSXSuport(boolean osx)
Enables or disables support of Mac OS X GUIs
void
setResourceBundle(String bundlename)
Sets the ResourceBundle to be used during parsing / String conversion
static void
setResourceBundleName(String bundlename)
Sets the SwingEngine's global resource bundle name, to be used by all SwingEngine instances.
void
test()
Displays the GUI during a RAD session.
protected static void
traverse(Component c, Collection collection)
Walks the whole tree to add all components into the components collection.

Field Details

DEBUG_MODE

public static final boolean DEBUG_MODE
Debug / Release Mode
Field Value:
false

MAC_OSX_LOCALE_VARIANT

public static final String MAC_OSX_LOCALE_VARIANT
Mac OSX locale variant to localize strings like quit etc.

MAC_OSX_OS_NAME

public static final String MAC_OSX_OS_NAME
Mac OSX identifier in System.getProperty(os.name)

cl

protected ClassLoader cl
Localizer, setup by parameters found in the xml descriptor.

Constructor Details

SwingEngine

public SwingEngine()
Default ctor for a SwingEngine.

SwingEngine

public SwingEngine(ClassLoader cl,
                   String resource)

Deprecated.

Constructs a new SwingEngine, rendering the provided XML into a javax.swing UI
Parameters:
resource - String

SwingEngine

public SwingEngine(Object client)
Constructor to be used if the SwingEngine is not extend but used through object composition.
Parameters:
client - Object owner of this instance

SwingEngine

public SwingEngine(String resource)
Constructs a new SwingEngine, rendering the provided XML into a javax.swing UI
Parameters:
resource - String

Method Details

cleanup

public int cleanup()
Removes all un-displayable compontents from the id map and deletes the components collection (for recreation at the next request).

  A component is made undisplayable either when it is removed from a displayable containment hierarchy or when its
 containment hierarchy is made undisplayable. A containment hierarchy is made undisplayable when its ancestor
 window
 is disposed.
 
Returns:
int number of removed componentes.

find

public Component find(String id)
Returns the UI component with the given name or null.
Parameters:
id - String assigned name
Returns:
Component- the GUI component with the given name or null if not found.

forget

public void forget(String id)
Removes the id from the internal from the id map, to make the given id available for re-use.
Parameters:
id - String assigned name

getAllComponentItertor

public Iterator getAllComponentItertor()
Returns an Iterator for all parsed GUI components.
Returns:
Iterator GUI components itearator

getAppFrame

public static Frame getAppFrame()
Returns:
Frame a parent for all dialogs.

getClassLoader

public ClassLoader getClassLoader()
Returns:
ClassLoader- the Classloader used for all getResourse..() and loadClass() calls.

getClient

public Object getClient()
Returns the object which instantiated this SwingEngine.
Returns:
Objecy SwingEngine client object

Note:
This is the object used through introspection the actions and fileds are set.

getDescendants

public Iterator getDescendants(Component c)
Walks the whole tree to add all components into the components collection.
Parameters:
c - Component recursive start component.

Note:There is another collection available that only tracks those object that were provided with an idattribute, which hold an unique id


getIdComponentItertor

public Iterator getIdComponentItertor()
Returns an Iterator for id-ed parsed GUI components.
Returns:
Iterator GUI components itearator

getIdMap

public Map getIdMap()
Returns the id map, containing all id-ed parsed GUI components.
Returns:
Map GUI components map

getLocalizer

public Localizer getLocalizer()
Returns:
Localizer- the Localizer, which is used for localization.

getRootComponent

public Container getRootComponent()
Returns the root component of the generated Swing UI.
Returns:
Component- the root component of the javax.swing ui

getTaglib

public TagLibrary getTaglib()
Returns:
TagLibrary- the Taglibray to insert custom tags.

Note:ConverterLibrary and TagLibray need to be set up before rendering is called.

insert

public void insert(Document jdoc,
                   Container container)
            throws Exception
Inserts swing objects rendered from an XML document into the given container.

  Differently to the parse methods, insert does NOT consider the root node of the XML document.
 
  NOTE:
insert() does NOT clear() the idmap before rendering. Therefore, if this SwingEngine's parser was used before, the idmap still contains (key/value) pairs (id, JComponent obj. references).
If insert() is NOT used to insert in a previously (with this very SwingEngine) rendered UI, it is highly recommended to clear the idmap:
mySwingEngine.getIdMap().clear()
Parameters:
jdoc - Document xml-doc path info

insert

public void insert(Reader reader,
                   Container container)
            throws Exception
Inserts swing objects rendered from an XML reader into the given container.

  Differently to the render methods, insert does NOT consider the root node of the XML document.
 
  NOTE:
insert() does NOT clear() the idmap before rendering. Therefore, if this SwingEngine's parser was used before, the idmap still contains (key/value) pairs (id, JComponent obj. references).
If insert() is NOT used to insert in a previously (with this very SwingEngine) rendered UI, it is highly recommended to clear the idmap:
mySwingEngine.getIdMap().clear()
Parameters:
reader - Reader xml-file path info
container - Container target, the swing obj, are added to.

insert

public void insert(String resource,
                   Container container)
            throws Exception
Inserts swing objects rendered from an XML reader into the given container.

  Differently to the render methods, insert does NOT consider the root node of the XML document.
 
  NOTE:
insert() does NOT clear() the idmap before rendering. Therefore, if this SwingEngine's parser was used before, the idmap still contains (key/value) pairs (id, JComponent obj. references).
If insert() is NOT used to insert in a previously (with this very SwingEngine) rendered UI, it is highly recommended to clear the idmap:
mySwingEngine.getIdMap().clear()
Parameters:
resource - String xml-file path info
container - Container target, the swing obj, are added to.

insert

public void insert(URL url,
                   Container container)
            throws Exception
Inserts swing object rendered from an XML document into the given container.

  Differently to the render methods, insert does NOT consider the root node of the XML document.
 
  NOTE:
insert() does NOT clear() the idmap before rendering. Therefore, if this SwingEngine's parser was used before, the idmap still contains (key/value) pairs (id, JComponent obj. references).
If insert() is NOT used to insert in a previously (with this very SwingEngine) rendered UI, it is highly recommended to clear the idmap:
mySwingEngine.getIdMap().clear()
Parameters:
url - URL url pointing to an XML descriptor *
container - Container target, the swing obj, are added to.

isMacOSX

public static boolean isMacOSX()
Indicates if currently running on Mac OS X
Returns:
boolean- indicating if currently running on a MAC

isMacOSXSupported

public static boolean isMacOSXSupported()
Indicates state of Mac OS X support (default is true = ON).
Returns:
boolean- indicating MacOS support is enabled

mapMembers

protected void mapMembers(Object obj)
Introspects the given object's class and initializes its non-transient fields with objects that have been instanced during parsing. Mappping happens based on type and field name: the fields name has to be equal to the tag id, psecified in the XML descriptor. The fields class has to be assignable (equals or super class..) from the class that was used to instance the tag.
Parameters:
obj - Object target object to be mapped with instanced tags

render

public Container render(Document jdoc)
            throws Exception
Gets the parsing of the XML file started.
Parameters:
jdoc - Document xml gui descritptor
Returns:
Object- instanced swing object tree root

render

public Container render(File xml_file)
            throws Exception
Gets the parsing of the XML file started.
Parameters:
xml_file - File xml-file
Returns:
Object- instanced swing object tree root

render

public Container render(Reader xml_reader)
            throws Exception
Gets the parsing of the XML file started.
Parameters:
xml_reader - Reader xml-file path info
Returns:
Object- instanced swing object tree root

render

public Container render(String resource)
            throws Exception
Gets the parsing of the XML file started.
Parameters:
resource - String xml-file path info
Returns:
Object- instanced swing object tree root

render

public Container render(URL url)
            throws Exception
Gets the parsing of the XML started.
Parameters:
url - URL url pointing to an XML descriptor
Returns:
Object- instanced swing object tree root

setActionListener

public boolean setActionListener(Component c,
                                 ActionListener al)
Recursively Sets an ActionListener

  Backtracking algorithm: if al was set for a child component, its not being set for its parent
 
.
Parameters:
c - Component start component
al - ActionListener

setAppFrame

public static void setAppFrame(Frame frame)
Sets the SwingEngine's global application frame variable, to be used as a parent for all child dialogs.
Parameters:
frame - Object the parent for all future dialogs.

setClassLoader

public void setClassLoader(ClassLoader cl)
Sets a classloader to be used for all getResourse..() and loadClass() calls. If no class loader is set, the SwingEngine's loader is used.
Parameters:
cl - ClassLoader
See Also:
ClassLoader.loadClass, ClassLoader.getResource

setDefaultLocale

public static void setDefaultLocale(Locale locale)
Sets the SwingEngine's global locale, to be used by all SwingEngine instances. This locale can be overwritten however for a single instance, if a locale attribute is places in the root tag of an XML descriptor.
Parameters:
locale - Locale

setLocale

public void setLocale(Locale l)
Sets the locale to be used during parsing / String conversion
Parameters:
l - Locale

setMacOSXSuport

public static void setMacOSXSuport(boolean osx)
Enables or disables support of Mac OS X GUIs
Parameters:
osx - boolean

setResourceBundle

public void setResourceBundle(String bundlename)
Sets the ResourceBundle to be used during parsing / String conversion
Parameters:
bundlename - String

setResourceBundleName

public static void setResourceBundleName(String bundlename)
Sets the SwingEngine's global resource bundle name, to be used by all SwingEngine instances. This name can be overwritten however for a single instance, if a bundle attribute is places in the root tag of an XML descriptor.
Parameters:
bundlename - String the resource bundle name.

test

public void test()
Displays the GUI during a RAD session. If the root component is neither a JFrame nor a JDialog, the a JFrame is instantiated and the root is added into the new frames contentpane.

traverse

protected static void traverse(Component c,
                               Collection collection)
Walks the whole tree to add all components into the components collection.
Parameters:
c - Component recursive start component.

Note:There is another collection available that only tracks those object that were provided with an idattribute, which hold an unique id


Copyright B) 2002 - 2005 - Wolf Paulus - CarlsbadCubes.com . All rights reserved.