Eloquence JDLG Plugin API Reference

Version 1.2

com.eloquence.api
Interface Jdlg

public interface Jdlg

Plugin access to JDLG functionality.

Plugin classes use this interface to invoke JDLG methods.

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

int	apiMajorVersion() Returns the JDLG Plugin API major version.
int	apiMinorVersion() Returns the JDLG Plugin API minor version.
boolean	consumeRightMouseButtonEvent(java.awt.event.MouseEvent event) Consume a right mouse button event.
void	defaultKeyboardHandler(boolean enable) Enables or disables the default keyboard handler.
java.awt.Dimension	getGridDimension() Obtains the size of the Dialog raster unit.
java.awt.event.KeyListener	getKeyboardListener() Obtains the default keyboard listener.
boolean	ignoreEvent(java.awt.AWTEvent event) Returns whether the specified event should be ignored.
boolean	inToolBar() Returns whether the plugin object is located in a JDLG ToolBar.
void	obtainFocus() Makes the plugin object obtain the focus.
boolean	processRightMouseButtonEvent(java.awt.event.MouseEvent event) Process a right mouse button event.
boolean	requiresApiVersion(int major, int minor) Checks for a specific JDLG Plugin API version.
void	triggerRule() Triggers the object's default rule.
void	triggerRule(int rule) Reserved to trigger an arbitrary rule value.

Method Detail

triggerRule

void triggerRule()

Triggers the object's default rule.

If the plugin object's default rule value is nonzero, it is triggered and control is passed to the Eloquence program.

Since:

API version 1.0

triggerRule

void triggerRule(int rule)

Reserved to trigger an arbitrary rule value.

Note:

• Currently, this method has no effect.

Parameters:

rule - rule value to trigger

Since:

API version 1.0

obtainFocus

void obtainFocus()

Makes the plugin object obtain the focus.

Since:

API version 1.0

ignoreEvent

boolean ignoreEvent(java.awt.AWTEvent event)

Returns whether the specified event should be ignored.

The interaction between JDLG and Eloquence programs assumes that JDLG can temporarily ignore specific input events, i.e., keyboard and mouse events. A plugin implementation should support this by overloading the processEvent() method of any java.awt.Component potentially receiving input events, as shown in the example below:

   public void processEvent(java.awt.AWTEvent event) {
     if (!jdlg.ignoreEvent(event))
       super.processEvent(event);
   }
 

Parameters:

event - the event to check

Returns:

true if the specified event should be ignored, false if the specified event should be processed

Since:

API version 1.0

defaultKeyboardHandler

void defaultKeyboardHandler(boolean enable)

Enables or disables the default keyboard handler.

If a plugin class does not implement the java.awt.event.KeyListener interface, JDLG adds itself as key listener on the peer object and this way provides the standard tab-focus and function keys handling. If this is not desired, this method allows to disable the default keyboard handler, i.e., remove the JDLG key listener from the peer object.

Parameters:

enable - enable (true) or disable (false) the default keyboard handler

Since:

API version 1.0

getKeyboardListener

java.awt.event.KeyListener getKeyboardListener()

Obtains the default keyboard listener.

This allows a plugin class to invoke the keyPressed() / keyReleased() / keyTyped() methods of the default java.awt.event.KeyListener from its own implementation of these key listener methods. The default key listener provides the standard tab-focus and function keys handling.

For example:

   public void keyPressed(java.awt.event.KeyEvent event) {
     if (event.getKeyCode() == java.awt.event.KeyEvent.VK_LEFT) {
       ... handle VK_LEFT key ...
       return;
     }
     ...
     // key event not handled:
     // invoke default key listener (handles tab-focus and function keys)
     jdlg.getKeyboardListener().keyPressed(event);
   }
 

Returns:

the default java.awt.event.KeyListener

Since:

API version 1.0

processRightMouseButtonEvent

boolean processRightMouseButtonEvent(java.awt.event.MouseEvent event)

Process a right mouse button event.

This allows a plugin class to implement the standard mouse handling by invoking this method in a java.awt.event.MouseListener event handler.

This method checks whether the event is not already consumed and refers to the context menu mouse button configured for the plugin object. If this is the case and the plugin object is sensitive, the standard mouse action is performed: If configured, the plugin object's context menu is opened, else the Dialog's rmbr rule is triggered if set. After the standard mouse action was performed, the event is consumed and true is returned.

For example, a plugin might implement a mousePressed() event handler like below:

   public void mousePressed(java.awt.event.MouseEvent event) {
     if (jdlg.requiresApiVersion(1, 2))
     {
        // API version >= 1.2:
        // Handle right mouse button pressed event,
        // eg. open the context menu.
        if (jdlg.processRightMouseButtonEvent(event))
           return;
     }
     .. handle mousePressed event ...
   }
 

Returns:

true if right mouse button event was processed, false if not

Since:

API version 1.2

consumeRightMouseButtonEvent

boolean consumeRightMouseButtonEvent(java.awt.event.MouseEvent event)

Consume a right mouse button event.

This allows a plugin class to implement the standard mouse handling by invoking this method in a java.awt.event.MouseListener event handler.

This method checks whether the event is not already consumed and refers to the context menu mouse button configured for the plugin object. If this is the case, the event is consumed and true is returned.

For example, a plugin might implement a mouseReleased() event handler like below:

   public void mouseReleased(java.awt.event.MouseEvent event) {
     if (jdlg.requiresApiVersion(1, 2))
     {
        // API version >= 1.2:
        // Consume right mouse button released event.
        if (jdlg.processRightMouseButtonEvent(event))
           return;
     }
     .. handle mouseReleased event ...
   }
 

Returns:

true if right mouse button event was consumed, false if not

Since:

API version 1.2

getGridDimension

java.awt.Dimension getGridDimension()

Obtains the size of the Dialog raster unit.

Returns:

size of the Dialog raster unit.

Since:

API version 1.0

inToolBar

boolean inToolBar()

Returns whether the plugin object is located in a JDLG ToolBar.

A plugin object class might implement special behavior if an object is located in a JDLG ToolBar.

For example, if a plugin object behaves like a button, it should not be focusable if located in a ToolBar. This could be implemented as shown in the example below:

   public boolean isFocusable() {
     return !jdlg.inToolBar();
   }
 

Returns:

true if plugin object is located in a tool bar, false if not

Since:

API version 1.1

apiMajorVersion

int apiMajorVersion()

Returns the JDLG Plugin API major version.

Returns:

major version

Since:

API version 1.0

apiMinorVersion

int apiMinorVersion()

Returns the JDLG Plugin API minor version.

Returns:

minor version

Since:

API version 1.0

requiresApiVersion

boolean requiresApiVersion(int major,
                           int minor)

Checks for a specific JDLG Plugin API version.

This allows a plugin class to check if the JDLG Plugin API version is sufficient for its implementation, or to handle different API versions.

For example:

   if (!jdlg.requiresApiVersion(1, 1)) {
     // less than API version 1.1: cannot handle
     return false;
   }
 

Parameters:

major - API major version to check

minor - API minor version to check

Returns:

true if API has at least the specified version, false if not

Since:

API version 1.1