SWIXML
1.5 (#149)

org.swixml
Class SwingEngine

java.lang.Object
  extended by org.swixml.SwingEngine

public class SwingEngine
extends Object

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

Version:
$Revision: 1.5 $
Author:
Wolf Paulus

Field Summary
protected  ClassLoader cl
          Localizer, setup by parameters found in the xml descriptor.
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)
 
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<String,Object> 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAC_OSX_OS_NAME

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

See Also:
Constant Field Values

MAC_OSX_LOCALE_VARIANT

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

See Also:
Constant Field Values

DEBUG_MODE

public static boolean DEBUG_MODE
Debug / Release Mode


cl

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

Constructor Detail

SwingEngine

public SwingEngine()
Default ctor for a SwingEngine.


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

SwingEngine

public SwingEngine(ClassLoader cl,
                   String resource)
Deprecated. 

Constructs a new SwingEngine, rendering the provided XML into a javax.swing UI

Parameters:
resource - String
Method Detail

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
Throws:
Exception

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
Throws:
Exception

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
Throws:
Exception

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
Throws:
Exception

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
Throws:
Exception

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.
Throws:
Exception

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.
Throws:
Exception

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.
Throws:
Exception

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
container - Container target, the swing obj, are added to
Throws:
Exception - Exception exception thrown by the parser

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.

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

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 - Window the parent for all future dialogs.

getAppFrame

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

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.


getRootComponent

public Container getRootComponent()
Returns the root component of the generated Swing UI.

Returns:
Component- the root component of the javax.swing ui

getAllComponentItertor

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

Returns:
Iterator GUI components itearator

getIdComponentItertor

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

Returns:
Iterator GUI components itearator

getIdMap

public Map<String,Object> getIdMap()
Returns the id map, containing all id-ed parsed GUI components.

Returns:
Map GUI components map

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.

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

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.

setLocale

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

Parameters:
l - Locale

setResourceBundle

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

Parameters:
bundlename - String

getLocalizer

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

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.
                                                                                                                                                                 

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(java.lang.String), ClassLoader.getResource(java.lang.String)

getClassLoader

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

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
Returns:
boolean true, if ActionListener was 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

Returns:
Iterator to walk all components, not just the id components.

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

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.
collection - Collection target collection.

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


setMacOSXSuport

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

Parameters:
osx - boolean

isMacOSXSupported

public static boolean isMacOSXSupported()
Indicates state of Mac OS X support (default is true = ON).

Returns:
boolean- indicating MacOS support is enabled

isMacOSX

public static boolean isMacOSX()
Indicates if currently running on Mac OS X

Returns:
boolean- indicating if currently running on a MAC

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.


SWIXML
1.5 (#149)

Copyright ? 2002 - 2007 - Wolf Paulus - wolfpaulus.com. All rights reserved.