SwingEngine (SWIXML API v2.4 (#240))

java.lang.Object
- 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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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(InputStream 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(InputStream 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(InputStream 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(InputStream 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.

Class SwingEngine

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAC_OSX_OS_NAME

MAC_OSX_LOCALE_VARIANT

DEBUG_MODE

cl

Constructor Detail

SwingEngine

SwingEngine

SwingEngine

SwingEngine

Method Detail

render

render

render

render

render

insert

insert

insert

insert

setResourceBundleName

setDefaultLocale

setAppFrame

getAppFrame

getClient

getRootComponent

getAllComponentItertor

getIdComponentItertor

getIdMap

cleanup

forget

find

setLocale

setResourceBundle

getLocalizer

getTaglib

setClassLoader

getClassLoader

setActionListener

getDescendants

mapMembers

traverse

setMacOSXSuport

isMacOSXSupported

isMacOSX

test