Control Objects and View Objects

Amulet µHTML™ pages can be created using standard HTML. However, there are user interface (UI) objects common to embedded systems that are not supported by standard HTML. These UI objects are referred to as Amulet widgets. There are also UI objects that are supported by HTML, but Amulet has extended their capabilities. These objects can be separated into two distinct categories, Control Objects (anchors, META refreshes, area maps), which can call the functions defined in Appendix B, and View Objects (images, animated images), which have methods that can be invoked via Inter-Widget Communications, but can't call functions on their own.

Control Objects

Anchors   <A>

Anchors create a touch sensitive hypertext link. Hitting anything that appears between the <A> and </A> tags will launch the function(s) defined in the HREF attribute. You can put text, images, or view widgets between the <A> and </A> tags. When the pen is down in the area of the anchor, the image within the area inverts. Anchors can also be set up to call a function(s) based upon a timer event, by using the ONTIME attribute. They can also call a function(s) when a timer-based function returns a specific value, by using the ONVAR and either the TRIGGER, TRIGGER.GT or TRIGGER.LT attributes. Anchors can be given an intrinsic value by using the VALUE attribute. Other objects/widgets can interact with anchors by using their internal name which is specified by the NAME attribute.

The following is an example of an anchor that creates a hypertext link to Page1.htm on the text "Page 1". To see this example work, the following example can be found in \Projects\Examples\Anchors\Text\CompileMe.htm.

The following is an example of an anchor around an image (pointer.gif) that links to Page1.htm either every 5 seconds if no user input ,or whenever the image is "hit." To see this example work, the following example can be found in \Projects\Examples\Anchors\Images\CompileMe.htm.

The following is an example of an anchor around the same image (pointer.gif) that links to Page1.htm when the value of external byte variable #1 equals 0x20, which is polled every 100ms. To see this example work, the following example can be found in \Projects\Examples\Anchors\Trigger\CompileMe.htm. In the example, the slider on the display is sending its intrinsic value to the anchor named test5. When the slider reaches the value 0x20, the anchor should be triggered and the Amulet will launch to Page1.htm.

In the example above, Page1.htm will be linked to if one of four different events occur. One being the external byte variable #1 returning a value of 0x20, thus activating the trigger. A second way is if another Control Widget/Object sends its value to the anchor and that value is 0x20, thus activating the trigger. A third way is if the image "pointer.gif" is physically "hit". The fourth way is if the anchor, internally named test5, has a forceHit() method applied to it by another Control Widget/Object. This is getting into Inter-Widget Communications, but just to show an example, here's how another anchor would do a force hit on our previous example test5. Hitting the text "Force hit on pointer" will cause the anchor, test5, to act as if it had been hit.

The following is an example similar to the above, but instead of using TRIGGER, it uses TRIGGER.GT. TRIGGER.GT acts the same as TRIGGER except the HREF will be triggered when the external byte variable #1 is greater than 0x10 .To see this example work, the following example can be found in \Projects\Examples\Anchors\Trigger.gt\CompileMe.htm.

The following is an example similar to the above, but instead of using TRIGGER.GT, it uses TRIGGER.LT. TRIGGER.LT acts the same as TRIGGER.GT except the HREF will be triggered when the external byte variable #1 is less than 0x10 .To see this example work, the following example can be found in \Projects\Examples\Anchors\Trigger.lt\CompileMe.htm.

Area Maps   <AREA>

Area maps create a touch sensitive hypertext link within the bounds of an image. Area maps use the same attributes, and act the same way, as anchors. When the pen is down in the area of the area map, the image within the area inverts. Upon a "hit" in an area map, the functions specified in the HREF attribute are launched. Area maps can also be set up to call a function(s) based upon a timer event, by using the ONTIME attribute. They can also call a function(s) when a timer-based function returns a specific value, by using the ONVAR and either the TRIGGER, TRIGGER.GT or TRIGGER.LT attributes. Area maps can be given an intrinsic value by using the VALUE attribute. Other objects/widgets can interact with area maps by using the area map's internal name which is specified by the NAME attribute.

For example, to make a rectangular region of the image popup.gif be an active link that returns you to the calling page when "hit", use the following.

To see this example work, compile any of the examples in the Projects/Examples/ directory and "hit" the image of the file folder. It will bring up a pop up screen that uses the above image map. The source is in Amulet/Projects/Examples/Images/PopUp.htm.

 META REFRESH   <META HTTP-EQUIV="REFRESH">

The most powerful, and potentially the most confusing, object in the Amulet system is the META Refresh object. It can be thought of as an invisible anchor that exists on a page, but isn't visible on the LCD.

There are four different ways to use the META Refresh control object:

1) Call a function(s) based upon a timer event.
2) Call a function(s) when a timer-based function returns a specific value.
3) Initialize InternalRAM variables with a value returned from a timer-based function.
4) Be a container object that makes no function calls, essentially becoming a variable which other objects/widgets can reference.

1) Call a function(s) based upon a timer event.

<META HTTP-EQUIV="REFRESH"
CONTENT="1st number, 2nd number;URL=function(s);VALUE=number;NAME=string"> -- This meta tag acts like an anchor that calls its function based upon a timer event instead of a user "hit". Notice the strange syntax with all of the semi-colon delimited fields enclosed within one set of quotes. Also, REFRESH must be all uppercase. CONTENT fields are described below:

1st number, 2nd number
The 1st number specifies the frequency that the URL function(s) is called (specified in seconds, with a single floating-point number). The range is 0.00 - 655.35. 0.00 means update never. The 2nd number specifies the delay time from when the page is loaded until the initial URL function(s) is called (specified in seconds, with a single floating-point number). The range is 0.01 - 655.35. If the 2nd number is not specified, then the delay time defaults to the 1st number (frequency) value. If the 2nd number is specified and the 1st number is 0.00, then the function(s) is called after the delay time specified by the second number and does not update again.

URL=function(s)
The allowable syntax for the "URL=function(s)"string are identical to that of the HREF attribute of the <A> tag or the HREF attribute for a user-input widget. See Appendix B for available functions.

VALUE=number
Specifies the intrinsic value of this meta refresh object. This parameter is optional because the intrinsic value can be specified directly within the URL function call as the argument to the method. See note regarding Control Object intrinsic values.

NAME=string
Specifies the internal name of this meta refresh object. Used for Inter-Widget Communication only.

Examples:

To send out an "invoke RPC #5" message every 500ms, use the following META REFRESH object:
 <META HTTP-EQUIV="REFRESH" CONTENT="0.5;URL=Amulet:UART.invokeRPC(5)">

An example using the above META tag can be found in \Projects\Examples\Meta\CompileMe.htm.

To send out an "invoke RPC #5" message once immediately upon loading the HTML page, but never again, use the following:
 <META HTTP-EQUIV="REFRESH" CONTENT="0,0.01;URL=Amulet:UART.invokeRPC(5)">
Note: The 0 of "0,0.01" means that the URL function will not have an update rate. The 0.01 of "0,0.01" means that the URL function will be called 10ms after loading the HTML page.

To launch to a page called parrot.html after 5 seconds, use the following:
<META HTTP-EQUIV="REFRESH" CONTENT="5;URL=parrot.html">

2) Call a function(s) when a timer based function returns a specific value

<META HTTP-EQUIV="REFRESH"
CONTENT="1st number, 2nd number;ONVAR=function;TRIGGER=number;TRIGGER.GT=number;TRIGGER.LT=number;TRIGGER.NEQ=number;URL=function(s);VALUE=number;NAME=string"> -- This meta tag acts like an anchor that calls its URL function(s) when the timer-based ONVAR function returns a specific value, instead of a user "hit". Notice the strange syntax with all of the semi-colon delimited fields enclosed within one set of quotes. The ONVAR attribute is like a View Widget's HREF parameter. The URL attribute is like a Control Widget's HREF parameter. CONTENT fields are described below:

1st number, 2nd number
The 1st number specifies the frequency that the ONVAR function is called (specified in seconds, with a single floating-point number). The range is 0.00 - 655.35. 0.00 means update never. The 2nd number specifies the delay time from when the page is loaded until the initial ONVAR function is called (specified in seconds, with a single floating-point number). The range is 0.01 - 655.35. If the 2nd number is not specified, then the delay time defaults to the 1st number (frequency) value. If the 2nd number is specified and the 1st number is 0.00, then the function(s) is called after the delay time specified by the second number and does not update again.

ONVAR=function
The value returned by this function call is used to trigger the function(s) in URL. The behavior and syntax of this META attribute is identical to that of the ONVAR attribute of the <A> tag or the HREF parameter for a View Widget. See Appendix B for available functions.

TRIGGER=number
This attribute specifies the byte value that triggers the URL function(s). When the value returned from the ONVAR function is equal to the TRIGGER value, the URL function(s) is called. The trigger value can be a byte, word, InternalRAM byte variable or InternalRAM word variable.

TRIGGER.GT=number
This attribute specifies the byte value that triggers the URL function(s). When the value returned from the ONVAR function is greater than the TRIGGER.GT value, the URL function(s) is called. The trigger value can be a byte, word, InternalRAM byte variable or InternalRAM word variable.

TRIGGER.LT=number
This attribute specifies the byte value that triggers the URL function(s). When the value returned from the ONVAR function is less than the TRIGGER.LT value, the URL function(s) is called. The trigger value can be a byte, word, InternalRAM byte variable or InternalRAM word variable.

TRIGGER.NEQ=number
This attribute specifies the byte value that triggers the URL function(s). When the value returned from the ONVAR function is not equal to the TRIGGER.NEQ value, the URL function(s) is called. The trigger value can be a byte, word, InternalRAM byte variable or InternalRAM word variable.

URL=function(s)
The allowable syntax for the "URL=function(s)"string are identical to that of the HREF attribute of the <A> tag or the HREF parameter for a Control Widget. See Appendix B for available functions.

VALUE=number
Specifies the intrinsic value of this meta refresh object. This parameter is optional because the intrinsic value can be specified directly within the URL function call as the argument to the method. See note regarding Control Object intrinsic values.

NAME=string
Specifies the internal name of this meta refresh object. Used for Inter-Widget Communication only.

3) Initialize Internal RAM variables with a value returned from a timer-based function.

META HTTP-EQUIV="REFRESH"
CONTENT="1st number, 2nd number;ONVAR=function;VALUE=InternalRAM.type(x) ;NAME=string"> -- This meta tag does not require a URL function since the META object only exists to initialize an Internal RAM variable value, either a BYTE, WORD or STRING.

The most obvious use for this type of META is for initializing an Internal RAM variable to an internal Amulet value. For example, to set Internal RAM word variable 0 to the current page number, you could use the following:

<META HTTP-EQUIV="Refresh" CONTENT="0,0.01;ONVAR=Amulet:internal.fileNumber.value();value=InternalRAM.word(0)">

Since the value=InternalRAM.word(0), instead of the META Refresh saving the value in its own memory space, it actually saves it directly to Internal RAM word variable #0.

Another case where this could be useful is if someone wanted to initialize an Internal RAM variable, but wanted to maintain the slave relationship with the Amulet. Therefore, you could have the META request a variable and store it directly into an Internal RAM variable without ever sending a master message.

<META HTTP-EQUIV="Refresh" CONTENT="0,0.01;ONVAR=Amulet:UART.byte(5).value();value=InternalRAM.byte(5)">

The above example will request the value of external byte variable #5 once 10ms after loading the page and save that value into InternalRAM byte variable #5.

4) Be a container object (byte, word or string variable)

META HTTP-EQUIV="REFRESH"
CONTENT="1st number, 2nd number;ONVAR=function;URL=Amulet:nop();VALUE=number ;NAME=string"> -- This meta tag does not need to call any functions. It exists to hold a variable value, either a BYTE, WORD or STRING. Other control objects/widgets can set the value of this "variable" by using Amulet:document.name.setValue(), and the value of the "variable" can be read by using Amulet:document.name.value(), where name is the internal name given in NAME=string. See note regarding Control Object intrinsic values.

With the addition of InternalRAM variables, using the META as a container object is not needed. InternalRAM uses less uHTML space as well as the additional benefit of existing outside of a specific page. META objects are only valid in the page that they are defined in and will be reinitialized every time the page is re-entered. InternalRAM can survive from page to page, will not be reinitialized every time the page is re-entered unless you specify it and InternalRAM can actually be saved back to the flash, so the variable can persist even after powering down.

Examples:

To send out an"invoke RPC #5" message when the value of a slider (Slider1) equals 0xFF, which is polled every 500ms, use the following META REFRESH object:
<META HTTP-EQUIV="REFRESH" CONTENT="0.5;ONVAR=Amulet:document.Slider1.value();TRIGGER=0xFF;URL=Amulet:UART.invokeRPC(5);NAME=MetaOne">

This META will continue to send the RPC every 500ms until the slider value no longer equals 0xFF. To have the META send it out only once, you could have the META URL include the following function after the invokeRPC function: Amulet:document.MetaOne.setUpdateRate(0)  
This will make the META turn itself off after the first invokeRPC is sent.

An example using the above META tag can be found in \Projects\Examples\Meta\TriggerInvoke.htm.

To send out a "set byte variable #2 to 0x78" message when the value of external byte variable #4 equals 0xFF, which is polled every 500ms, use the following META REFRESH object:
<META HTTP-EQUIV="REFRESH" CONTENT="0.5;ONVAR=Amulet:UART.byte(4).value();TRIGGER=0xFF;URL=Amulet:UART.byte(2).setValue(0x78)">

An example using the above META tag can be found in \Projects\Examples\Meta\SetVar.htm.

To send out a 'set string variable #5 to "My String"' message when the value of external byte variable #4 equals 0xF0, which is polled every 500ms, use the following META REFRESH object:
<META HTTP-EQUIV="REFRESH" CONTENT='0.5;ONVAR=Amulet:UART.byte(4).value();TRIGGER=0xF0;URL=Amulet:UART.string(5).setValue("My String")'>

To launch to "Page1.html"when the value of external byte variable #1 is greater than 0xC0, which is polled every 500ms, and to "Page2.htm" if the value is less than 0x40, use the following META REFRESH objects:
<META HTTP-EQUIV="REFRESH" CONTENT="0.5;ONVAR=Amulet:UART.byte(1).value();TRIGGER.GT=0xC0;URL=../setValue()/Page1.html"> <META HTTP-EQUIV="REFRESH" CONTENT="0.5;ONVAR=Amulet:UART.byte(1).value();TRIGGER.LT=0x40;URL=../setValue()/Page2.html">

An example using the above META tags can be found in \Projects\Examples\Meta\Trigger2Page.htm.

To use a list box, a function button and multiple META REFRESH objects to launch to another page see the setValue() example.

View Objects

Images & Animated Images   <IMG>

Both images and animated images use the <IMG> tag. Although they cannot represent data like View Widgets can, they do have internal methods that can be invoked by other Control Widgets/Objects. See the Inter-Widget Communications document for the list of available methods for each object/widget.

For example, to create 3 radio buttons that can be used to change the playback speed of an animated .gif named RunAnim.gif with the internal name of Runner, use the following listings:

 Amulet HTMLCompiler,
Copyright © 2000-2004 by
Amulet Technologies, LLC


Back to Welcome - Contact Amulet - Amulet Home