About this task
In most case, when an user selects a widget or changes
the value of a widget, some operation needs to be executed. XML UI
Engine provides the action injection for this purpose.
Users
need to implement the IAction interface provided by XML UI to execute
the operation on demand.
The actions provided by XML UI Engine
are listed below. See the IAction.java interface for more details.
- public boolean keyPressed(IXUIWidget source, char character, int
keyCode, int stateMask);
- Description: invoke when a key is pressed on the system keyboard.
- Parameters
- source: it specifies the source widget which invoke this action
- character: the character represented by the key that was typed.
This is the final character that results after all modifiers have
been applied. For example, when the user types Ctrl+A, the character
value is 0x01. It is important that applications do not attempt to
modify the character value based on a stateMask (such as SWT.CTRL)
or the resulting character will not be correct.
- keyCode: the key code of the key that was typed, as defined by
the key code constants in class SWT. When the character field of the
event is ambiguous, this field contains the unicode value of the original
character. For example, typing Ctrl+M or Return both result in the
character '\r' but the keyCode field will also contain '\r' when Return
was typed.
- stateMask: the state of the keyboard modifier keys at the time
the event was generated, as defined by the key code constants in class
SWT.
- Returns: boolean value which depending on the event, a flag indicating
whether the operation should be allowed. Setting this field to false
will cancel the operation.
- public boolean keyReleased(IXUIWidget source, char character,
int keyCode, int stateMask);
- Description:Invoke when a key is released on the system keyboard.
- Parameters:
- source source widget which invoke this action character the character
represented by the key that was typed. This is the final character
that results after all modifiers have been applied. For example, when
the user types Ctrl+A, the character value is 0x01. It is important
that applications do not attempt to modify the character value based
on a stateMask (such as SWT.CTRL) or the resulting character will
not be correct. keyCode the key code of the key that was typed, as
defined by the key code constants in class SWT. When the character
field of the event is ambiguous, this field contains the unicode value
of the original character. For example, typing Ctrl+M or Return both
result in the character '\r' but the keyCode field will also contain
'\r' when Return was typed. stateMask the state of the keyboard modifier
keys at the time the event was generated, as defined by the key code
constants in class SWT.
- Return:boolean value which depending on the event, a flag indicating
whether the operation should be allowed. Setting this field to false
will cancel the operation.
- public void mouseDoubleClick(IXUIWidget source, int type, int
stateMask);
- Description: invoke when a button is pressed twice within the
(operating system specified) double click period.
- Parameters:
- source: it specifies the source widget that invoke this action
- type: it specifies the button that was pressed or released. Such
as 1 for the first button, 2 for the second button, and 3 for the
third button, etc.
- stateMask: the state of the keyboard modifier keys at the time
the event was generated
- public boolean widgetSelected(IXUIWidget source, IXUIWidget item);
- Description: invoke when the selection occurs. For example, selection
occurs in a List when the user selects an item or items with the keyboard
or mouse. On some platforms, the event occurs when a mouse button
or key is pressed. On others, it happens when the mouse or key is
released. The exact key or mouse gesture that causes this event is
platform specific. The widgets that we currently support are: Button,
Table, ComboBox, RadioButton, CheckBox, List.
- Parameters:
- source: it specifies the source widget that invoke this action
- item: it specifies the selected item.
- Return: it depends on the event. For example a flag indicates
whether the operation should be allowed. Setting this field to false
will cancel the operation.
- public void focusLost(IXUIWidget source);
- Description: invoke when a control gets focus.
- Parameters:
- source: it specifies the source widget that invoke this action
- public void focusGained(IXUIWidget source);
- Description: invoke when a control loses focus.
- Parameters:
- source: it specifies the source widget that invoke this action.
- public void mouseDown(IXUIWidget source, int type, int stateMask);
- Description: invoke when a mouse button is pressed.
- Parameters:
- source: it specifies the source widget that invoke this action.
- type the button that was pressed or released; 1 for the first
button, 2 for the second button, and 3 for the third button, etc.
- stateMask the state of the keyboard modifier keys at the time
the event was generated
- Return:
- public void mouseUp(IXUIWidget source, int type, int stateMask);
- Description: Invoke when a mouse button is released.
- Parameters:
- source source widget which invoke this action
- type the button that was pressed or released; 1 for the first
button, 2 for the second button, and 3 for the third button, etc.
- stateMask the state of the keyboard modifier keys at the time
the event was generated
- Return:
- public void widgetDisposed(IXUIWidget source);
- Description:Invoke when the widget is disposed.
- Parameters:
- source: it specifies the source widget that invoke this action.
- public void modifyText(IXUIWidget source);
- Description: Invoke when the text is modified. Current® support widgets: Text widgets and
ComboBox
- Parameters:
- source: it specifies the source widget that invoke this action.
- public boolean verifyText(IXUIWidget source, int start, int end,
String text);
- Description:Invoke when the text is about to be modified. A verify
action occurs after the user has done something to modify the text
(typically typed a key), but before the text is modified. The return
value indicates whether or not to modify the text. Current support widgets: Text widgets and
ComboBox
- Parameters:
- source
- start the start point of text being modified.
- end the end point of text being modified.
- text the new text that will be inserted.
- Return: boolean value which depending on the event, a flag indicating
whether the operation should be allowed. Setting this field to false
will cancel the operation.
Injection the action in configuration file
The definition
of action in XML UI configuration file is based on the injection of
Element factory. The injection name is “actions”. Note that more than
one action could be assigned to a widget, they will be processed one
by one. So the action should be defined in a list.
<Text bounds="182,77,280,22">
<list Injection="initializers">
<com.ibm.btt.xmluiengine.test.initializers.TextInitializer />
</list>
<com.ibm.btt.rcp.xui.format.NumericFormat Injection="format" />
<list Injection="actions">
<com.ibm.btt.rcp.xui.action.TestAction />
</list>
</Text>
The XLM UI Engine will trigger the Actions for
the widget marked with v..