uic.model
Class ActionFactory

java.lang.Object
  uic.model.ActionFactory

public class ActionFactory
extends Object

ActionFactory builds actions and keeps them referenced so you can easily enable/disable them. Creating the menu and toolbar parts of a new Gui exitst from two steps; first you have to register all the actions your application supports, and next you have to provide an rc file that contains the structure of the GUI.

Registering actions can be done with addAction or addSpecialAction.

        // in constructor of class extending JFrame
        actionFactory = new ActionFactory();
        actionFactory.addSpecialAction("file_new", this, "fileNewSlot");
        actionFactory.addAction("context_new",     // the name this action can be found under
            this, "insertContextSlot",             // the method called when action is selected
            "New Context...",                      // the text to show on menu entries
            "toolbarButtonGraphics.general.New");  // an icon from the jlfgr-1_0.jar

The next step is to build the user interface:

        getContentPane().setLayout(new BorderLayout());
        actionFactory.build(this, getClass().getClassLoader().getResourceAsStream("myapp.rc"));

getContentPane().add(myContentPanel, BorderLayout.CENTER);

And thats it.
If you keep a reference to the actionFactory you will be able to call methods like enableAction like this:

        actionFactory.enableAction("file_new", false); 

You will typically have one actionFactory instance per main window (the window with the menus)

A short example of the formatting of the .rc file (the myapp.rc above) is like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <actionfactory name="myapp" version="1">
      <MenuBar>
       <Menu name="edit"><text>&amp;Edit</text>
        <Action name="edit_undo"/>
        <Action name="edit_redo"/>
        <Separator/>
        <Action name="delete_page"/>
       </Menu>
      </MenuBar>
      <ToolBar name="edit_toolbar" position="top"><text>Edit</text>
        <Action name="edit_undo"/>
      </ToolBar>
      <Menu name="action_popup">
        <Action name="tools_createtext"/>
        <Action name="tools_createpix"/>
        <Action name="tools_table"/>
        <Action name="tools_kspreadtable"/>
        <Action name="tools_formula"/>
        <Action name="tools_part"/>
      </Menu>
      </actionfactory> 

The tag Menu specifies one menu (or a submenu when it has another menu as parent) which can contain Action tags.
The ToolBar tag contains actions which will be placed on a toolbar by that name.
When a Menu is nested below the MenuBar tag it will appear in the menubar of the JFrame, The Menu tags at root level will be popups as supported by getPopupMenu(java.lang.String)

Actions that are not yet known at writing of the .rc need to be added to the menu without relying on individual action names. It is possible to add a placeholder for any number of actions in the rc file which can then be requested and filled programattically using any UICAction instance you have.

The placeholder should be named in the rc file and takes the format of an <ActionList name="myname"> element. The element can appear anywhere where an action can also appear. From your code you can add actions to the menus and toolbars by filling the actionlist you can request from the ActionFactory:

      UICActionList entriesList = af.getActionList("myList");
      entriesList.add(anAction);

Note that it is no problem to have a ActionList name appear multiple times in your rc file, which makes all actions added to it appear in each of the menus and toolbars you use that name in.

Since:

1.2

Field Summary

protected IconFactory	iconFactory
static int	POLICY_DIRECT
static int	POLICY_DIRECT_MULTITHREADED
static int	POLICY_ONLY_LAST
static int	POLICY_QUEUED

Constructor Summary

ActionFactory()
Empty constructor to create an un-translated ActionFactory.

ActionFactory(TranslationInterface appTranslator)
Create a new ActionFactory where texts from the config file are translated.

Method Summary

void	addAction(String name, Object targetObject, String targetMethod, String title)
void	addAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName)
void	addAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke)
void	addAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke, String toolTipText)
UICAction	addAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke, String toolTipText, String whatIsThis) Register action with factory.
void	addAction(UICAction action)
boolean	addIconJar(String path)
boolean	addIconRepository(String path)
UICAction	addSpecialAction(String name, Object targetObject, String targetMethod) register actions that are predifined.
void	build(JFrame parent, InputStream is)
void	build(JFrame parent, InputStream is, StatusBar statusBar)
void	build(JFrame parent, StatusBar statusBar)
void	build(JFrame parent, URL url)
void	build(JFrame parent, URL url, StatusBar statusBar)
void	build(MainWindow parent, InputStream is) Deprecated. use MainWindow.createGui(uic.TranslationInterface, java.lang.String) instead
void	build(MainWindow parent, URL url) Deprecated. use MainWindow.createGui(uic.TranslationInterface, java.lang.String) instead
void	buildMenu(JMenuBar parent, Element menuRoot)
void	buildMenu(JMenuBar parent, Element menuRoot, StatusBar statusBar)
void	buildMenu(JMenuBar parent, InputStream is)
void	buildMenu(JMenuBar parent, URL url)
void	buildToolbars(JFrame parent, Element documentRoot)
void	buildToolbars(JFrame parent, InputStream is)
void	buildToolbars(JFrame parent, URL url)
JToolBar	createToolBar(Element toolbar)
JToolBar	createToolBar(String toolbarName)
void	enableAction(String actionName, boolean on) set the action to be enabled/disabled.
void	enableGroup(String groupName, boolean on) Enable action groups.
UICAction	getAction(String name) Return the action registered using the argument name.
UICActionList	getActionList(String name) Return the actionList list of actions that are grouped by argument name.
IconFactory	getIconFactory()
JPopupMenu	getPopupMenu(String name)
protected JMenu	getSettingsMenu(JMenuBar parent)
void	init(InputStream is)
void	setAllowToolBarHiding(boolean allow) Set true to allow the user the option to hide toolbars Set false to not present hiding options to the user Toolbar hiding must also be set on the WindowRepresenter.
void	setExecutionPolicy(String actionName, int policy)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

iconFactory

protected IconFactory iconFactory

POLICY_QUEUED

public static final int POLICY_QUEUED

See Also:

Constant Field Values

POLICY_DIRECT

public static final int POLICY_DIRECT

See Also:

Constant Field Values

POLICY_DIRECT_MULTITHREADED

public static final int POLICY_DIRECT_MULTITHREADED

See Also:

Constant Field Values

POLICY_ONLY_LAST

public static final int POLICY_ONLY_LAST

See Also:

Constant Field Values

Constructor Detail

ActionFactory

public ActionFactory()

Empty constructor to create an un-translated ActionFactory.

Since:

2.0

ActionFactory

public ActionFactory(TranslationInterface appTranslator)

Create a new ActionFactory where texts from the config file are translated.

Parameters:

appTranslator - the translator used to translate the strings which are passed in the rc file as 'text' nodes. These are, for instance, the names of the menus, like "File" and "Edit".

Method Detail

addAction

public UICAction addAction(String name,
                           Object targetObject,
                           String targetMethod,
                           String title,
                           String iconBaseName,
                           String keyStroke,
                           String toolTipText,
                           String whatIsThis)

Register action with factory.

Parameters:

name - The identifying name of the action, must be unique.

targetObject - The object that contains the method we want to connect to.

targetMethod - the name of the method we want to connect to.

title - the name used on buttons or in a menu entry.

iconBaseName - the basename the new widgets can use to fetch the correct icon, or null if none

keyStroke - the keyStroke in the format accepted by javax.swing.KeyStroke.getKeyStroke(String)

toolTipText - the text for tooltips, or null for none

whatIsThis - the text for the statusBar.

See Also:

KeyStroke.getKeyStroke(String)

addAction

public void addAction(String name,
                      Object targetObject,
                      String targetMethod,
                      String title)

addAction

public void addAction(String name,
                      Object targetObject,
                      String targetMethod,
                      String title,
                      String iconBaseName)

addAction

public void addAction(String name,
                      Object targetObject,
                      String targetMethod,
                      String title,
                      String iconBaseName,
                      String keyStroke)

addAction

public void addAction(String name,
                      Object targetObject,
                      String targetMethod,
                      String title,
                      String iconBaseName,
                      String keyStroke,
                      String toolTipText)

addAction

public void addAction(UICAction action)

addSpecialAction

public UICAction addSpecialAction(String name,
                                  Object targetObject,
                                  String targetMethod)

register actions that are predifined. These actions can be registred without providing texts or icons since UICompiler provides them already. Using these your application will have the most used commands instantly translated into a number of languages. Full list of names provided:

code	Description
file_new	New Document
file_open	Open Document
file_save	Save Document
file_saveas	Save As...
file_close	Close
file_quit	Quit (default on Mac and Linux)
file_exit	Exit (default on Windows)

Parameters:

name - action name from the limited set (file_open/file_save etc.)

targetObject - The object that contains the method we want to connect to.

targetMethod - the name of the method we want to connect to.

Throws:

NullPointerException - when name is null.

IllegalArgumentException - if the name is not a known special action.

getAction

public UICAction getAction(String name)

Return the action registered using the argument name.

Parameters:

name - the name the action is registered under (file_new for example)

Returns:

the action, or null if action not registered.

Since:

2.0

getActionList

public UICActionList getActionList(String name)

Return the actionList list of actions that are grouped by argument name. In the rc file menus and toolbars are groups for several actions. The actionList groups these actions.

Parameters:

name - the name the actionList is registered under (file_menu for example)

Returns:

the actionList.

Since:

2.0

build

public void build(MainWindow parent,
                  URL url)

Deprecated. use MainWindow.createGui(uic.TranslationInterface, java.lang.String) instead

uses the input file to read actions and menu structure, and build that.

build

public void build(JFrame parent,
                  URL url)

build

public void build(JFrame parent,
                  URL url,
                  StatusBar statusBar)

build

public void build(MainWindow parent,
                  InputStream is)

Deprecated. use MainWindow.createGui(uic.TranslationInterface, java.lang.String) instead

uses the input file to read actions and menu structure, and build that.

build

public void build(JFrame parent,
                  InputStream is)

build

public void build(JFrame parent,
                  InputStream is,
                  StatusBar statusBar)

build

public void build(JFrame parent,
                  StatusBar statusBar)

init

public void init(InputStream is)
          throws IOException,
                 JDOMException

Throws:

IOException

JDOMException

buildMenu

public void buildMenu(JMenuBar parent,
                      URL url)
               throws IOException,
                      JDOMException

Throws:

IOException

JDOMException

buildMenu

public void buildMenu(JMenuBar parent,
                      InputStream is)
               throws JDOMException,
                      IOException

Throws:

JDOMException

IOException

buildMenu

public void buildMenu(JMenuBar parent,
                      Element menuRoot)

buildMenu

public void buildMenu(JMenuBar parent,
                      Element menuRoot,
                      StatusBar statusBar)

buildToolbars

public void buildToolbars(JFrame parent,
                          URL url)
                   throws IOException,
                          JDOMException

Throws:

IOException

JDOMException

buildToolbars

public void buildToolbars(JFrame parent,
                          InputStream is)
                   throws JDOMException,
                          IOException

Throws:

JDOMException

IOException

buildToolbars

public void buildToolbars(JFrame parent,
                          Element documentRoot)

createToolBar

public JToolBar createToolBar(String toolbarName)

Parameters:

toolbarName - the name of the popup as registred in the resource file with the 'name' attribute.

Throws:

IllegalStateException - if this is called on an ActionFactory which did not have one of the build() flavors called before.

createToolBar

public JToolBar createToolBar(Element toolbar)

getSettingsMenu

protected JMenu getSettingsMenu(JMenuBar parent)

getPopupMenu

public JPopupMenu getPopupMenu(String name)

Parameters:

name - the name of the popup as registred in the resource file with the 'name' attribute.

Returns:

A popup menu as registred in the rc file. You will get an empty popup menu if nothing was registred.

Throws:

IllegalStateException - if this is called on an ActionFactory which did not have one of the build() flavors called before.

setExecutionPolicy

public void setExecutionPolicy(String actionName,
                               int policy)

enableAction

public void enableAction(String actionName,
                         boolean on)

set the action to be enabled/disabled.

Parameters:

actionName - the key of the action to enable/disable

on - set to enabled when true;

enableGroup

public void enableGroup(String groupName,
                        boolean on)

Enable action groups.

Parameters:

groupName - the name of the group to enable can be found in the &l;Menu> and <ToolBar> tags which can contain a "name" attribute.

addIconJar

public boolean addIconJar(String path)

addIconRepository

public boolean addIconRepository(String path)

getIconFactory

public IconFactory getIconFactory()

setAllowToolBarHiding

public void setAllowToolBarHiding(boolean allow)

Set true to allow the user the option to hide toolbars Set false to not present hiding options to the user Toolbar hiding must also be set on the WindowRepresenter.