Inter-Widget Communication

All widgets use the href parameter to specify a function call or a group of function calls. One type of function call is Inter-Widget Communication (IWC). IWC's allow one Amulet widget to invoke the methods of another Amulet widget. (See Appendix B for a comprehensive listing of all available function calls. See Appendix C for a detailed listing of which IWC methods apply to which widget or object, as well as a more in-depth description of what the IWC method actually does.)

IWC borrows some of its syntax from Java Script, a scripting language used within HTML. All IWC function calls start with "Amulet:document.". The Amulet: signifies that what follows is an Amulet specific command. The document. represents the Document Object Model. Every HTML page has an object called document, which is one large object that contains every object (widget, text, images etc...) that is on that HTML page. To put it simply, document. signifies that we're dealing with the current HTML page.

IWC also borrows concepts from Java, an Object-Oriented Programming(OOP) language. Each widget can be thought of as an object. As in OOP, each object has its own set of data and a set of well-defined interfaces to that data. As in Java, IWC refers to these interfaces as methods. Methods are just functions that are specific to a particular object. Each object has its own set of methods. The same nomenclature as Java is used, where a method is called by using the object's name followed by the dot operator, followed by the method.

The href nomenclature for IWC's is Amulet:document.widgetName.method()

Control Widgets/Objects, using IWC, can send data to other widgets/objects or invoke other widgets'/objects' methods. View Widgets, using IWC, can request data from Control Widgets.

In addition to widgets, there are other objects that have methods that can be invoked using IWC. Images and animated images, referred to as View Objects, have methods that Control Widgets/Objects can call.

To use IWC, the widget/object to be called must have a name. (See Widgets.htm on how to specify a name for an Amulet widget.) To perform IWC methods on Control/View Objects, except META REFRESH, append the NAME attribute within the HTML tag:

NAME="user-defined name"

For example, to create a radio button to change the playback speed of an animated .GIF, do the following:

1. First, give an IWC name to the animated image: <IMG SRC="../Images/RunAnim.gif" WIDTH="200" HEIGHT="165" NAME="Runner" >
2. Next, use the following radio button href: Amulet:document.Runner.slowSpeed().
3. When the radio button is selected, the animated image will start playing back at a slower speed.

An example using the above animated .gif and radio button can be found in \Projects\Examples\RunningMan\CompileMe.htm.

To perform IWC methods on a META REFRESH, append:

;NAME=user-defined name to the CONTENT= attribute.

For example: (<META HTTP-EQUIV="REFRESH" CONTENT="12;URL=home.html;NAME=MetaOne">) Notice the semi-colon. For the META REFRESH only, all attributes must be separated by semi-colons.

There are essentially 3 different kinds of methods. 1) methods that do not require parameters; 2) methods that require parameters; 3) methods that return a value.

Methods that do not require arguments (parameters):

See example below, where a function button widget, when pressed, causes a line plot widget(Plot1) to remove itself from the LCD:

<APPLET CODE="FunctionButton.class" WIDTH="56" HEIGHT="25" NAME="Button1">
<PARAM NAME="href" VALUE="Amulet:document.Plot1.disappear()">
<PARAM NAME="fontSize" VALUE="3">
<PARAM NAME="fontStyle" VALUE="plain">
<PARAM NAME="label" VALUE="action">
<PARAM NAME="onButtonPress" VALUE="depress">
</APPLET>

The href line invokes the disappear() method on Plot1. That is, it calls disappear() relative to the Plot1 object. Thus, the call to Plot1.disappear() causes the widget named Plot1 to remove itself from the LCD. An example using the above function button can be found in \Projects\Examples\setMethod()\CompileMe.htm.

The method disappear() does not require any arguments (parameters that are passed to the method that the method uses as its input). Other methods do require arguments, though.

Methods that require arguments (parameters):

Some methods require a parameter to be passed to it. When dealing with methods, a parameter that is passed to it is referred to as the argument of the method. The argument passed to any method is the intrinsic value of the calling widget/object. Only Control Widgets/Objects have an intrinsic value. See example below, where a list widget sends its intrinsic value to an image sequence widget (Tour) to use as its input when a list entry is selected:

<APPLET CODE="List.class" WIDTH="46" HEIGHT="60" NAME="Country">
<PARAM NAME="href" VALUE="Amulet:document.Tour.setValue()">
<PARAM NAME="fontSize" VALUE="2">
<PARAM NAME="fontStyle" VALUE="plain">
<PARAM NAME="options" VALUE="America,Australia,China,France,San Francisco,Japan">
<PARAM NAME="initialCondition" VALUE="America">
</APPLET>

The href line invokes the setValue() method on Tour. If the list entry France is selected, then the call to Tour.setValue() causes the widget named Tour to receive 0x03. When dealing with View Widgets, their values are what they use as their input. So, Tour will use 0x03 as its input value. An example using the above list can be found in \Projects\Examples\List\CompileMe.htm.

Methods that return a value:

Only View Widgets can invoke methods that return a value. Only Control Widgets have an intrinsic value to return. Therefore the method value() is only a valid method for Control Widgets. And only View Widgets are allowed to invoke the value() method. See example below, where an image sequence widget requests a list widget's(Country) intrinsic value to use as the input to the image sequence widget:

<PARAM NAME="ImageSeq.class" WIDTH="145" HEIGHT="98" NAME="Tour">
<PARAM NAME="href" VALUE="Amulet:document.Country.value()">
<PARAM NAME="min" VALUE="0">
<PARAM NAME="max" VALUE="5">
<PARAM NAME="sequence" VALUE="../Images/america.gif;../Images/australia.gif;../Images/china.gif;../Images/france.gif;../Images/goldenbridge.gif;../Images/japan.gif">
<PARAM NAME="updateRate" VALUE=".04">
</APPLET>

The href line invokes the value() method on Country. So, every 40ms, Country's value() method will return the intrinsic value of Country to Tour. Country's intrinsic value is then used as the input for Tour. An example using the above image sequence can be found in \Projects\Examples\List\CompileMe.htm.

Table 1. IWC method descriptions.

Table 2. IWC method descriptions unqique to Animated Image Objects.

Table 3. Matrix of supported IWC methods for Widgets and Objects.

1. Regarding x: For Control Widgets that have intrinsic values, such as lists and sliders, leave the argument field empty, since the intrinsic value of the selection will be sent out. Anchors, META REFRESH tags, area maps and Function/Custom Buttons should use x. The range for x is 0-255 (0x00-0xff) for a BYTE, 0-65535 (0x00-0xffff) for a WORD and 250-character strings in double quotes for STRINGs.

2. Regarding m: When setMethod(), setOnVarMethod(), setOnVarUARTMethod or setUARTMethod() is the IWC method, the argument should be the name of the method you want to set. See setMethod() example.

3. Regarding f: For Control Widgets that have intrinsic values, such as lists and sliders, leave the argument field empty, since the intrinsic value of the selection will be sent out. Anchors, META REFRESH tags, area maps and Function/Custom Buttons should use f. Like the regular updateRate, use a floating point number to specify the update rate in seconds. Range for f is 0-655.35

4. forceHit() for checkBox widget: When imparting a forceHit on a single checkBox, that checkBox will toggle. You can also forceHit an entire checkBox group which will perform the href function(s), but will not toggle any checkboxes. To forceHit a checkbox group, use the groupName as the widgetName (rather than an individual checkBox name).

4a. forceUpdate() for checkBox widget: You can only impart a forceUpdate on an entire checkBox group (even if the checkBox is a lone box), which will perform the initHref function. To forceUpdate a checkbox group, use the groupName as the widgetName (rather than an individual checkBox name).

5. forceHit() for radioButton widget: You can only impart a forceHit to an individual radio button, not a radio button group.

6. setValue() for anchor/Area Map: setValue() cannot be invoked if the ONVAR attribute is present.

7. setValue() for META REFRESH: setValue() cannot be invoked if the ONVAR attribute is present.

8. setMethod() and setUpdateRate(): When using the setMethod() or setUpdateRate() methods, multiple functions are not allowed within a single href. However, you can invoke a forceHit() on another object that will launch setMethod() or setUpdateRate(), which then allows you to use multiple functions since there is no such limitation on the forceHit() method.

 9. setMethod() for checkBox widget: To change the method for a checkbox group, or an ungrouped checkbox, use the groupName as the widgetName (rather than an individual checkBox name). You cannot change the method for an individual checkBox within a group.

 10. regarding x in setX() and setY(): When setX() or setY() is the IWC method, the argument needs to be a word value with the range being the viewable area of the given LCD.

Table 4. Matrix of supported IWC methods for Animated Image Object

See some IWC examples in Amulet/Projects/Examples/setMethod()/ and Amulet/Projects/Examples/setValue()/ Read the comments in ReadMe.htm and compile and load CompileMe.htm into the Amulet controller.