Eloquence JDLG Plugin API Reference

Version 1.2

com.eloquence.api
Interface Plugin

public interface Plugin

JDLG Plugin Interface.

Plugin classes must implement this interface and follow a defined naming scheme:

• The class name must start with an upper case letter (A-Z).
• The remaining part of the class name must consist only of lower case letters (a-z) or digits (0-9) or the underscore character (_).

JDLG detects the "plugin." DLG class name prefix to delegate object creation to the plugin loader, which in turn resolves the plugin class by appending the class name, adjusted to the naming scheme explained above, to the "com.eloquence." package prefix. As a consequence, plugin classes must be located in the com.eloquence.plugin package.

Example 1: DLG NEW "main.bigone","plugin.Snowball"

This loads the com.eloquence.plugin.Snowball plugin class and uses it to create the main.bigone DLG object.

DLG file equivalent:

   Dialog main {
     ...
     plugin.Snowball bigone {
       ...
 

Example 2: DLG NEW "main.label42","plugin.labels.fancy"

This loads the com.eloquence.plugin.labels.Fancy plugin class from the labels package located in com.eloquence.plugin and uses it to create the main.label42 DLG object.

DLG file equivalent:

   Dialog main {
     ...
     plugin.labels.fancy label42 {
       ...
 

A plugin implementation provides three kinds of object references:

• plugin object - an instance of the loaded plugin class, implementing the Plugin interface
• peer object - the java.awt.Component representing the plugin object on screen
• focus peer object - the java.awt.Component which receives the focus if the plugin object is focusable

A plugin class may either derive from java.awt.Component so that plugin and peer objects are identical, or contain the peer java.awt.Component so that plugin and peer objects are different. Furthermore, a plugin class might manage multiple focusable elements, accordingly adjusting the current focus peer.

The plugin class must implement the onCreate(Jdlg) and onGetFocusPeer() methods to return the peer object and the (current) focus peer object, respectively.

API version history:

• 1.2 (current): since JDLG 1.6.7
• 1.1: since JDLG 1.5.6
• 1.0: since JDLG 1.5.0

Method Summary

boolean	allowRMBR() This method is deprecated since API version 1.2 and is never invoked.
boolean	fireRuleOnLosingFocus() Returns whether the plugin object triggers a rule when focus is lost.
boolean	isFocusable() Returns whether the plugin object is focusable.
void	onClone(Plugin clone) Invoked when a plugin object is derived from a model.
java.awt.Component	onCreate(Jdlg jdlg) Invoked upon plugin object creation.
void	onDispose() Invoked upon plugin object disposal.
void	onEloq2Swing() Invoked when the Eloquence program executes DLG DO or DLG DRAW.
void	onFocusLost() Notifies the plugin object that it has lost the focus.
void	onFocusReceived() Notifies the plugin object that it has received the focus.
void	onFontModified(java.awt.Font font) Notifies the plugin object that its font has been modified.
UnifiedData	onGet(java.lang.String attribute, java.util.List index) Invoked when the Eloquence program executes DLG GET.
java.awt.Component	onGetFocusPeer() Invoked to request the current focus peer object.
boolean	onRuleOverride() Returns whether the plugin object supports the RuleOverride behavior.
boolean	onSet(java.lang.String attribute, java.util.List index, UnifiedData data) Invoked when the Eloquence program executes DLG SET.
void	onSwing2Eloq() Invoked before control is passed to the Eloquence program.
void	onTabFocus(boolean toNext) Notifies the plugin object that is has been tab-focused.

Method Detail

onCreate

java.awt.Component onCreate(Jdlg jdlg)

Invoked upon plugin object creation.

A typical implementation should first verify that the JDLG Plugin API version is sufficient for this plugin, and immediately return null if not.

It might then save a copy of the passed Jdlg interface object for later use and perform any necessary initialization on the plugin object.

Finally, it returns a reference to the peer java.awt.Component representing the plugin object on screen, which might be the plugin object itself or a java.awt.Component managed by the plugin object.

For example:

   public class Snowball implements Plugin {
     private Jdlg jdlg;
     ...
     public java.awt.Component onCreate(Jdlg jdlg) {
       // This plugin requires API version 1.0
       if (!jdlg.requiresApiVersion(1, 0))
         return null;
       // save the Jdlg reference
       this.jdlg = jdlg;
       // finalize plugin object initialization
       ...
       // return the plugin object's peer
       return peer;
     }
 

Parameters:

jdlg - reference to JDLG interface object

Returns:

plugin object peer java.awt.Component or null if plugin creation failed

Since:

API version 1.0

onClone

void onClone(Plugin clone)

Invoked when a plugin object is derived from a model.

The invoked plugin object is cloned to the clone object. This method is responsible for cloning all object properties and can presume that the passed clone object is an instance of the invoked object's class, so the clone object can be safely cast, as shown in the example below:

   public class Snowball implements Plugin {
     private float weight;
     private float diameter;
     ...
     public void onClone(Plugin clone) {
       // Cast the clone object to Snowball
       Snowball cloneObj = (Snowball)clone;
       // Clone the weight member value
       cloneObj.weight = weight;
       // Clone the diameter member value
       cloneObj.diameter = diameter;
       ...
     }
 

Alternatively, attributes may be cloned using onGet(String,java.util.List) and onSet(String,java.util.List,UnifiedData), for example:

     public void onClone(Plugin clone) {
       // Clone the "weight" attribute value
       clone.onSet("weight", null, onGet("weight", null));
       // Clone the "diameter" attribute value
       clone.onSet("diameter", null, onGet("diameter", null));
       ...
     }
 

Parameters:

clone - new plugin object cloned from the invoked object

Since:

API version 1.0

onDispose

void onDispose()

Invoked upon plugin object disposal.

Since:

API version 1.0

onEloq2Swing

void onEloq2Swing()

Invoked when the Eloquence program executes DLG DO or DLG DRAW.

This method notifies the plugin object to update its state before the Dialog is displayed or control is passed to the Dialog.

Eloquence programs typically execute a number of DLG SET statements before DLG DO or DLG DRAW is issued. Therefore, the DLG SET implementation should be as lightweight as possible, while expensive actions such as invoking plugin or peer object methods on the modified attribute values should be batched in the onEloq2Swing() implementation.

Since:

API version 1.0

onSwing2Eloq

void onSwing2Eloq()

Invoked before control is passed to the Eloquence program.

When the Eloquence program executes DLG DO it passes control to the Dialog and waits until a rule is triggered so that control is passed back.

This method is invoked after the rule was triggered but before control is passed back to the program. The plugin object might require to update its attribute values according to the current state of the peer object, so that the program can DLG GET the updated attribute values.

Since:

API version 1.0

onSet

boolean onSet(java.lang.String attribute,
              java.util.List index,
              UnifiedData data)

Invoked when the Eloquence program executes DLG SET.

The attribute name is passed in lower case. If an indexed attribute is specified, for example cell[15][4], the attribute name is passed without the index subscripts, for example cell, and the indices are passed in the index list. Indices may be integer and/or string values, for example key[name]. If no indices are specified, index is passed as null.

Example implementation:

     public void onSet(String attribute, java.util.List index, UnifiedData data) {
       int indexElements = index != null ? index.size() : 0;
       if (attribute.equals("weight")) {
         // "weight" attribute is not indexed
         if (indexElements != 0)
           return false;
         // convert to (float)weight
         try {
           weight = Float.valueOf(data.getStringData()).floatValue();
           return true;
         }
         catch (NumberFormatException) {
           return false;
         }
       }
       if (attribute.equals("cell")) {
         // "cell" attribute wants two integer indices
         if (indexElements != 2)
           return false;
         UnifiedData idx1 = (UnifiedData)index.get(0);
         UnifiedData idx2 = (UnifiedData)index.get(1);
         if (idx1.isStringData() || idx2.isStringData())
           return false;
         // ok: set the cell value
         return setCell(idx1.getIntData(), idx2.getIntData(), data.getStringData());
       }
       ...
       return false;
     }
 

Parameters:

attribute - attribute name (lower case without index subscripts)

index - list of UnifiedData indices or null if no index

data - UnifiedData attribute value

Returns:

true if attribute exists and value was successfully set, else false

Since:

API version 1.0

onGet

UnifiedData onGet(java.lang.String attribute,
                  java.util.List index)

Invoked when the Eloquence program executes DLG GET.

See onSet(String,java.util.List,UnifiedData) above for a detailed description.

Parameters:

attribute - attribute name (lower case without index subscripts)

index - list of UnifiedData indices or null if no index

Returns:

UnifiedData attribute value if attribute exists and value was successfully obtained, else null

Since:

API version 1.0

onFontModified

void onFontModified(java.awt.Font font)

Notifies the plugin object that its font has been modified.

The plugin object might for example use this notification to update its layout according to the font metrics.

Parameters:

font - new plugin object font

Since:

API version 1.0

isFocusable

boolean isFocusable()

Returns whether the plugin object is focusable.

Returns:

true if the plugin object is focusable, false if not

Since:

API version 1.0

onFocusReceived

void onFocusReceived()

Notifies the plugin object that it has received the focus.

Note:

• This method is not invoked if isFocusable() returns false.

Since:

API version 1.0

onFocusLost

void onFocusLost()

Notifies the plugin object that it has lost the focus.

Note:

• This method is not invoked if isFocusable() returns false.

Since:

API version 1.0

onGetFocusPeer

java.awt.Component onGetFocusPeer()

Invoked to request the current focus peer object.

JDLG invokes this method to request the java.awt.Component that should receive the focus, aka. the focus peer object. If a plugin object contains multiple focusable elements, this method specifies which one will receive the focus.

Note:

• If isFocusable() returns false, this method should return null.

Returns:

java.awt.Component representing the current focus peer, null if not applicable

Since:

API version 1.0

onTabFocus

void onTabFocus(boolean toNext)

Notifies the plugin object that is has been tab-focused.

If a plugin object contains multiple focusable elements, typically the tab order should be correctly maintained. If the user hits the RETURN or TAB key to forward-tab into the plugin object the first contained element should receive the focus. If the user hits SHIFT-TAB to backward-tab into the plugin object the last contained element should receive the focus. This method allows to implement this kind of behavior.

Note:

• This method is not invoked if isFocusable() returns false.

Parameters:

toNext - whether tab focus has been moved forward (true) or backward (false) into the plugin object

Since:

API version 1.0

fireRuleOnLosingFocus

boolean fireRuleOnLosingFocus()

Returns whether the plugin object triggers a rule when focus is lost.

JDLG EditText and ComboBox objects trigger its rule when losing the focus. If the plugin class implements a similar behavior, this method should return true. This information is used to handle the plugin object's RuleOverride behavior.

Notes:

• If this method returns true, this does not implicitly trigger a rule when focus is lost. Instead, the plugin class still needs to implement that, typically in the onFocusLost() method.
• If isFocusable() returns false, this method should return false.

Returns:

true if the plugin object triggers a rule when focus is lost, false if not

Since:

API version 1.1

onRuleOverride

boolean onRuleOverride()

Returns whether the plugin object supports the RuleOverride behavior.

Typically, if a plugin object behaves like a button, i.e., it triggers a rule when clicked, it should support the RuleOverride behavior, so this method should return true.

Notes:

• JDLG implements the ruleoverride attribute for any plugin class. The ruleoverride default value is false. If this method is invoked, the plugin class can conclude that the ruleoverride attribute value was set to nonzero (true).
• Should the plugin class require that the default value is true it must implement the ruleoverride attribute itself, then use this method to return the ruleoverride attribute value.

Returns:

true if the plugin object supports the RuleOverride behavior, false if not

Since:

API version 1.0

allowRMBR

boolean allowRMBR()

This method is deprecated since API version 1.2 and is never invoked.

Therefore its return value does not matter, but it must be implemented to satisfy the plugin interface definition.

Since:

API version 1.0