Interface Script

public interface Script

This interface specifies the callbacks that system may call on widget script. All callbacks are optional.

It is imperative that all callbacks finish in timely manner as otherwise the normal application execution is severely crippled.

Method Summary

void	actionPerformed(Shell shell, Component source, int action) Called when specified action has occurred.
void	closeWidget() Called when last script-created maximized shell is popped.
Component	createElement(String viewName, String elementId, Style style, Object context) Callback to create user interface element for view.
Menu	getMenu(Shell shell, Component focused) Called when user has requested menu to be opened.
MenuItem	getSoftKey(Shell shell, Component focused, int key) Called when system wants to get a binding for soft key.
Object	handleMessage(String service, Object argument) This privileged operation is used when java code wishes to interact with integrated "core" widget.
boolean	keyAction(Component source, int op, int code) Called when key event has occurred.
void	messageReceived(String service, Object argument, ResponseCallback callback) Called when inter widget communication request has been received.
void	onFailure(Object state, String errorMessage) Called when server call has failed.
void	onSuccess(Object state, Value returnValue) Called when server call has finished successfully.
Shell	openWidget() Called when the user opens the widget from the dashboard.
Shell	openWidgetItem(Value context, String text, ByteArray icon) Called when the user has clicked on active standby item.
void	paint(Component c, Graphics g, Style style, int width, int height) Called when custom component should be painted.
void	parametersChanged() Called when widget parameters are changed either from server side or client side.
void	startWidget() Called when the widget instance is created and started.
void	stopWidget() Called when the widget execution is fully stopped.
void	timerEvent(Timer timer) Called then scheduled timer is executed.
void	updateReceived(String service, Value argument) Called when asynchronous notification has been received from server indicating that something has changed on the service associated with this widget.
void	updateWidget() Called when widget should update it's contents.

Method Detail

actionPerformed

void actionPerformed(Shell shell,
                     Component source,
                     int action)

Called when specified action has occurred. Action is one of

• Menu action
• Component "fire" action
• Implicit action (such as FOCUS_CHANGED)

Parameters:

shell - Source shell

source - Source component

action - Action code

See Also:

Component.setAction(int), Component.getAction(), Menu, MenuItem, OPEN_MENU, FOCUS_CHANGED, ITEM_CHANGED, OPEN_LINK, SHELL_OPENED, SHELL_CLOSED, VIEWPORT_CHANGED, FOCUSED, BLURRED, ActionCallback

getMenu

Menu getMenu(Shell shell,
             Component focused)

Called when user has requested menu to be opened.

Parameters:

shell - Source shell

focused - Source component

Returns:

Menu object, or null if no menu is available.

See Also:

OPEN_MENU, Menu, MenuItem, MenuCallback

getSoftKey

MenuItem getSoftKey(Shell shell,
                    Component focused,
                    int key)

Called when system wants to get a binding for soft key.

Parameters:

shell - Source shell

focused - Source component

key - Either SOFTKEY_OK, SOFTKEY_MIDDLE or SOFTKEY_BACK

See Also:

MenuItem, SoftKeyCallback

keyAction

boolean keyAction(Component source,
                  int op,
                  int code)

Called when key event has occurred.

Parameters:

source - Currently focused component

op - Operation that has occurred: KEY_PRESSED, KEY_RELEASED, KEY_REPEATED

code - unicode value of key (>=0) or special key code (<0) for other keys

Returns:

true if key event was consumed and should not be processed anywhere else

See Also:

KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_FIRE, KEY_ESC, KEY_ENTER, KEY_CR, KEY_DELETE, KEY_BACKSPACE, KEY_TAB, KEY_OK, KEY_BACK

createElement

Component createElement(String viewName,
                        String elementId,
                        Style style,
                        Object context)

Callback to create user interface element for view. This function gets called when script calls createView(String, Object) and referred view contains script actions.

Parameters:

viewName - Name of view being created, same as name in createView(String, Object)

elementId - Id of element

style - Style for element

context - Same as parameter context passed to createView(String, Object)

Returns:

Created element - returning null is not recommended.

startWidget

void startWidget()

Called when the widget instance is created and started. Here the widget should start it's (background) activity, such as timers

stopWidget

void stopWidget()

Called when the widget execution is fully stopped. Here the widget should stop it's (background) activity, such as timers.

updateWidget

void updateWidget()

Called when widget should update it's contents. Typically this might involve in calling the server and fetching some content.

This function is always invoked after client has connected to server and widgets has been loaded and verified to be up-to-date.

updateReceived

void updateReceived(String service,
                    Value argument)

Called when asynchronous notification has been received from server indicating that something has changed on the service associated with this widget.

If this function is not implemented, the updateWidget() will be called instead.

Parameters:

service - Name of service

argument - Notification argument

openWidget

Shell openWidget()

Called when the user opens the widget from the dashboard.

Returns:

Shell to show or null if there is no user interface. If the null is returned the widget can still open the user interface by itself.

openWidgetItem

Shell openWidgetItem(Value context,
                     String text,
                     ByteArray icon)

Called when the user has clicked on active standby item. With this callback the widget can adjust UI and, for instance, open the specified item directly. This callback is optional if it's not specified the openWidget() is used instead.

Parameters:

context - Widget specific context

text - Text shown on active standby screen

icon - Icon shown on active standby screen

Returns:

Shell to show or null if there is no user interface. If the null is returned the widget can still open the user interface by itself.

closeWidget

void closeWidget()

Called when last script-created maximized shell is popped. This is where script should do cleaning up, like stop timers or make them occur not so often anymore, set large pictures/binaries/arrays to null, or save modified user data to store.

timerEvent

void timerEvent(Timer timer)

Called then scheduled timer is executed.

Parameters:

timer - Scheduled timer object

See Also:

schedule(long), schedule(long,long), Timer, Timer.cancel(), TimerCallback

paint

void paint(Component c,
           Graphics g,
           Style style,
           int width,
           int height)

Called when custom component should be painted. Coordinate (0,0) points to top left corner of component's rectangle. Clipping is in effect so that drawing actions are contained into area reserved for this component.

Parameters:

c - Instance of custom component

g - Graphics context

style - Style to use

width - Width of the available area

height - Height of the available area

See Also:

PaintCallback, Callbacks

onSuccess

void onSuccess(Object state,
               Value returnValue)

Called when server call has finished successfully. Server calls are made with call(Object, String, String, Value) or call(Object, String, String, Value, SuccessCallback, FailureCallback)

Parameters:

state - State object given with call(Object, String, String, Value)

returnValue - the return value from server

See Also:

SuccessCallback, Callbacks

onFailure

void onFailure(Object state,
               String errorMessage)

Called when server call has failed. Server calls are made with call(Object, String, String, Value) or call(Object, String, String, Value, SuccessCallback, FailureCallback)

Parameters:

state - State object given with call(Object, String, String, Value)

errorMessage - error message of exception

See Also:

FailureCallback, Callbacks

messageReceived

void messageReceived(String service,
                     Object argument,
                     ResponseCallback callback)

Called when inter widget communication request has been received.

Parameters:

service - Name of service being called

argument - Argument for service

callback - Optional callback for sending response back, null callback indicates that caller do not wish to receive response.

handleMessage

Object handleMessage(String service,
                     Object argument)

This privileged operation is used when java code wishes to interact with integrated "core" widget. Not applicable to user defined widgets.

parametersChanged

void parametersChanged()

Called when widget parameters are changed either from server side or client side. Note. If this function is not declared, parameter change will close maximized mode (if widget was maximized), sync dashboard -> restart widget.