ModernJava
http://www.modernminds.com
M odule WVPanelTimer

The timer module (WVPanelTimer) allows you to send a pre-defined sequence of triggers to other panels beginning either when the WVPanelTimer panel is initialized, or beginning when a specified activation event occurs. The trigger sequence can be played continuously, or a specified number of times.

The WVPanelTimer module can also be used to load a sequence of URLs to create a "slide show" effect.

An example of the use of the WVPanelTimer module is its use in combination with the WVPanelImage module to create simple animations at frame rates of up to 10 frames/second (see the example below).

The WVPanelTimer module is always added to a WildView display by using a <PANEL> tag in a WildView layout file.

This module's documentation is divided into four sections:
  • Module Attributes lists all of the attributes for the module
  • Attribute Descriptions provides details about each attribute
  • Tags describes the tags that are supported by the module
  • Receiving Triggers details what types of <TRIGGERS> are recognized by the module.
  • Example is a section showing the use of the WVPanelTimer module for simple animation.
M odule Attributes

Each possible attribute that can be specified for a panel tag that uses the WVPanelTimer module is listed below along with a link to the attribute's description.

Be aware that attribute values are shown for illustrative purposes only: refer to each attribute's description for information regarding attribute requirements.

<PANEL
   module="WVPanelTimer"
   name=animate
   x=0
   y=0
   w=150
   h=50
   initWait=image2
   loop=3
   enable=true
   activate=mouseEnter
   deactivate=mouseExit
>

Note that attribute names and attribute values are always converted to lowercase internally (this does not apply to the tag type name -- "PANEL" -- which must always be in uppercase characters).

If you wish to preserve the case of an attribute value (e.g., you are specifying a module name that has upper and lower case characters), then you should surround the attribute value with quotation marks. Also, if there is a space character in an attribute value, then you should use quotation marks around the entire attribute value.

A ttribute Descriptions

Each attribute of the WVPanelTimer panel tag is defined below. The attribute's use is described and the valid attribute values are listed.
module

The module attribute identifies the Java component that will be associated with the panel.

In order to use the WVPanelTimer module, this attribute must be set as:

module="WVPanelTimer"

Note that the module name is within quotation marks in order to preserve the case of the characters.

Be sure that the spelling and the capitalization of the module name match exactly, or WildView will not be able to locate the module.
name

The name attribute allows you to assign a name to the panel.

Panel names are primarily used in conjunction with triggers in order to identify what panel a trigger is being sent to, or in some cases, what panel the trigger was received from.

Panel names are also used by WildView when logging error conditions in order to identify the panel that encountered the error.

The name attribute is optional, but if it is not specified then you will not be able to send triggers to this panel from other panels.
x

The x attribute is useful only if the activate or deactivate panel attribute has been specified.

The x attribute determines the left edge of the area within the WildView display area in which the panel will respond to activate and deactivate events.

For instance, if the WildView display area has a total width of 200, and if a value of 100 is specified for the panel's x attribute, then the panel area will be located with its left edge positioned in the middle of the WildView display.

The WVPanelTimer module will only respond to activate and deactivate events that occur within the rectangle defined by the x, y, w, and h attributes.

Panel Area
y

The y attribute is useful only if the activate or deactivate panel attribute has been specified.

The y attribute determines the top edge of the area within the WildView display area in which the panel will respond to activate and deactivate events.

For instance, if the WildView display area has a total height of 100, and if a value of 50 is specified for the panel's y attribute, then the panel area will be located with its top edge positioned in the middle of the WildView display.

The WVPanelTimer module will only respond to activate and deactivate events that occur within the rectangle defined by the x, y, w, and h attributes.

Panel Area
w

The w attribute is useful only if the activate or deactivate panel attribute has been specified.

The w attribute determines the width of the area within the WildView display area in which the panel will respond to activate and deactivate events.

For instance, if the WildView display area has a total width of 200, and if the panel's x attribute has a value of 20, and the panel's w attribute has a value of 160 (positioning the right edge of the panel area at 20 + 160 = 180), then the panel area will be centered horizontally in the WildView display (there is a margin of 20 to the left of the panel area's left edge and a margin of 200 - 180 = 20 to the right of the panel area's right edge).

The WVPanelTimer module will only respond to activate and deactivate events that occur within the rectangle defined by the x, y, w, and h attributes.

Panel Area
h

The h attribute is useful only if the activate or deactivate panel attribute has been specified.

The h attribute determines the height of the area within the WildView display area in which the panel will respond to activate and deactivate events.

For instance, if the WildView display area has a total height of 100, and if the panel's y attribute has a value of 10, and the panel's h attribute has a value of 80 (positioning the bottom edge of the panel area at 10 + 80 = 90), then the panel area will be centered vertically in the WildView display (there is a margin of 10 above the panel area's top edge and a margin of 100 - 90 = 10 below the panel area's bottom edge).

The WVPanelTimer module will only respond to activate and deactivate events that occur within the rectangle defined by the x, y, w, and h attributes.

Panel Area
initWait

The initWait attribute can be used to assign an id that the WVPanelTimer panel will wait for before it begins to process the tags that follow the WVPanelTimer panel tag. In other words, the panel will wait until it receives a <TRIGGER> with the specified id before it will commence operation.

An example of using this attribute would be in a situation where a WVPanelTimer panel is being used to animate an image. When WildView initializes the WVPanelTimer panel, there is no guarantee that the image that is to be animated has been completely loaded. However, since a WVPanelImage panel can send a trigger to another panel when its image has been completely loaded, we can use the WVPanelTimer initWait attribute to cause the WVPanelTimer panel to wait until it receives the trigger from the WVPanelImage panel before it begins processing tags and animating the image.
loop

The loop attribute controls how many times the tags that follow the WVPanelTimer panel tag will be processed. For instance, if the WVPanelTimer panel is being used to animate a image, and if the loop attribute is set to 2, then the animation sequence will be performed twice.

If the loop attribute is omitted, then the WVPanelTimer panel will loop through the tags that follow the WVPanelTimer panel tag continuously.

Note that if the loop attribute is specified and if an activate event is defined, then the WVPanelTimer panel will loop the number of times specified by the loop attribute each time that the WVPanelTimer panel is activated.
enable

The enable attribute determines if the WVPanelTimer panel is initially operational.

The following two values are valid for this attribute:
  • true - the WVPanelTimer panel is operational

  • false - the WVPanelTimer panel is not operational
The enable state can be changed by sending a <TRIGGER> to the WVPanelTimer panel from another panel (see Receiving Triggers below).

If a value for the enable attribute is not specified, then the value will default to "true".
activate

The activate attribute can be used to define an event that will cause the WVPanelTimer panel to become active and to begin processing the tags that follow the WVPanelTimer panel tag.

The valid activate attribute values are:
  • start - activate the WVPanelTimer panel when the panel set is started (this is the default if the activate attribute is not specified -- it is provided here as an option for use in combination with the other values listed below)

  • mouseEnter - activate the WVPanelTimer panel when the mouse moves into the panel's area

  • mouseExit - activate the WVPanelTimer panel when the mouse moves out of the panel's area

  • buttonDown - activate the WVPanelTimer panel when the mouse button is pressed in the panel's area

  • buttonUp - activate the WVPanelTimer panel when the mouse button is released after it has been pressed in the panel's area
If the panel should be activated for more than one event type, then the event types may be combined.

For instance, if the panel should be activated when the mouse button is pressed and also when the mouse moves into the panel area, then both events can be specified as:

activate=buttonDown+mouseEnter

An example of when defining an activate event would be useful is if you would like a button image in a WildView display to animate when the mouse is moved into the button image area and the animation to stop when the mouse is moved out of the button image area. In this situation, you would define a "mouseEnter" activate event, and a "mouseExit" deactivate event.
deactivate

The deactivate attribute can be used to define an event that will cause the WVPanelTimer panel to become inactive and to stop processing the tags that follow the WVPanelTimer panel tag.

The valid deactivate attribute values are:
  • mouseEnter - deactivate the WVPanelTimer panel when the mouse moves into the panel's area

  • mouseExit - deactivate the WVPanelTimer panel when the mouse moves out of the panel's area

  • buttonDown - deactivate the WVPanelTimer panel when the mouse button is pressed in the panel's area

  • buttonUp - deactivate the WVPanelTimer panel when the mouse button is released after it has been pressed in the panel's area
If the panel should be deactivated when more than one event type occurs, then the event types may be combined.

For instance, if the panel should be deactivated when the mouse button is released or when the mouse moves out of the panel area, then both events can be specified as:

deactivate=buttonDown+mouseEnter

An example of when defining an deactivate event would be useful is if you would like a button image in a WildView display to animate when the mouse is moved into the button image area and the animation to stop when the mouse is moved out of the button image area. In this situation, you would define a "mouseEnter" activate event, and a "mouseExit" deactivate event.
T ags

The tags that follow the WVPanelTimer panel tag are what make the WVPanelTimer panel actually do something. Without these tags, the WVPanelTimer panel would just sit around and spin its wheels (or whatever computers have that are equivalent to wheels).

When the WVPanelTimer panel is active (see the enable, activate, and deactivate attributes), the WVPanelTimer panel will sequentially process the tags that it finds after the WVPanelTimer panel tag up to, of course, the next <PANEL> tag.

The WVPanelTimer module recognizes the following tags:
  • <TRIGGER> - send a trigger to a panel
  • <WAIT> - stop reading and processing the tags
  • <LOAD> - load one or more URLs
  • <SET> - replace the current panel set with another panel set
<TRIGGER>

The <TRIGGER> tag allows you send a message to one or more panels. Each WildView module recognizes only certain messages, so please refer to the documentation for each module to determine what types of triggers the module can receive.

The format of the <TRIGGER> tag is:

<TRIGGER panel=panelName id=idName ... >

The <TRIGGER> tag attributes are:
  • panel

    This required attribute is the name of a panel (or panels) to which this trigger should be sent.

    The attribute value can be the name of a single panel to which the trigger should be sent, as for example:

    panel=panel1

    or, multiple panels can be sent a trigger by separating the panel names with commas, like:

    panel=panel1,panel2,panel3

    Note that without quotation marks, you cannot put spaces in the attribute value. If you surround the attribute value with quotation marks, however, you can place spaces in the attribute value: in fact, you can use spaces instead of commas to separate the panel names to which triggers should be sent.

    With quotation marks, you can use spaces after a comma:

    panel="panel1, panel2, panel3"

    Or you can use spaces instead of commas:

    panel="panel1 panel2 panel3"

  • id

    This optional attribute is commonly used, and so it is documented here.

    The attribute is most often specified when another panel has executed a <WAIT> tag and is waiting for a <TRIGGER> with a specific id.

    In this case, you can cause the <WAIT>ing panel to resume by sending it a <TRIGGER> with an id attribute that matches the id for which the panel is <WAIT>ing.

  • ...

    The ellipse indicates that there can be any number of additional attribute/value pairs that can be sent to the panel.

    The attributes in the <TRIGGER> that are recognized by the target panel depends upon the module that was used to create the panel.

    See the documentation for the appropriate module to determine what <TRIGGER> attributes can be sent to the particular target panel.
See the example below for an illustration of how triggers can be used to create a simple animation.
<WAIT>

The <WAIT> tag allows you insert a pause between <TRIGGER> tags.

When a <WAIT> tag is encountered, the WVPanelTimer panel stops processing tags until the panel receives a <TRIGGER>, or until an (optional) timeout expires.

The format of the <WAIT> tag is:

<WAIT id=idName timeout=seconds>

The <WAIT> tag attributes are:
  • id

    This optional attribute is the id that a <TRIGGER> must send in order for the panel to begin processing tags again. If the attribute is omitted, then any <TRIGGER> sent to this panel will cause the tag processing to resume.

  • timeout

    If a timeout attribute is specified, then the next tag will be processed if a <TRIGGER> is received (with the appropriate id, if specified), or when the number of 1/10 seconds specified for the timeout attribute have elapsed.

    IMPORTANT: the timeout value for the WVPanelTimer panel is in 1/10 second increments (i.e., timeout=1 means 100 milliseconds, not 1 second). This is different from other panels where the timeout value is in seconds.
See the example below for an illustration of how the <WAIT> tag can be used with triggers to create a simple animation.
<LOAD>

The <LOAD> tag is used to load one or more URLs.

The format of the <LOAD> tag is:

<LOAD url="url1 url2 url3 ..." target="target1 target 2 target3 ...">

The <LOAD> tag attributes are:
  • url

    The value of the url attribute can be any valid URL, or it can be a list of URLs separated by at least one space character. For instance,

    url=http://www.modernminds.com

    or

    url="../HTML/Home.html  http://www.microsoft.com  http://home.netscape.com"

    Note that if you specify more than one URL, then the list must be enclosed within quotation marks. Also, you should specify a target for each of the URLs. If you do not specify targets when multiple URLs are used, then the URLs will just load on top of each other, each URL replacing the URL that was previously loaded.

    If you specify a partial URL, as for example,

    url="Home.html"

    then the root of the URL will be based on the URL of the directory that contains the the Java code.

    For instance, if the WildView Java classes are in a directory called "Java", and if a HTML file called "Home.html" is in a directory called "HTML" which is in the "Java" directory (i.e., "Java/HTML/Home.html"), then the attribute would be:

    url="HTML/Home.html"

    Note that you can also use the "mailto" option to launch a user's mail client. For example:

    url=mailto:comments@modernminds.com

    Make sure that you do not use the target attribute if you are using "mailto."

    If a value for this attribute is not specified, then the tag will be ignored.

  • target

    For each URL specified in the url attribute, a target can be specified. If a target is not specified, then the URL will load over the current page and replace the applet.

    The value of the target attribute can be any valid target frame name or symbol (some browsers will open a new browser window if the target name does not exist).

    Some special symbolic values are (warning: these values might not work for every browser):

    • _blank - Always load the URL into a new, unnamed window

    • _self - Always load the URL over the current page

    • _parent - Always load this URL over the parent page (becomes self if there was no parent)

    • _top - Always load this link at the top level (becomes self if current page is at the top)

    If more than one URL is specified for the url attribute, then the corresponding targets must be listed within quotation marks in the same order as the URLs.

    For example:

    <LOAD url="http://www.modernminds.com
      http://www.microsoft.com
      http://home.netscape.com"
      target="MMFrame MSFrame NSFrame">

    This example will load http://www.modernminds.com in MMFrame,
    http://www.microsoft.com in MSFrame, and
    http://home.netscape.com in NSFrame.

    If you do not wish to specify a target for a URL in a list, then you may enter a dash (i.e., "-") for the target. For instance:

    <LOAD url="http://www.modernminds.com
      mailto:support@modernminds.com
      http://home.netscape.com"
      target="MMFrame - NSFrame">
<SET>

The <SET> tag can be used to load another panel set (i.e., a layout file) to replace the panel set currently being displayed.

The format of the <SET> tag is:

<SET panelSet="panelSetToLoad" stop=stopDisplay loadMessage="messageText">

The <SET> tag attributes are:
  • panelSet

    This required attribute is the panel set file name or the number of the panel set that should be loaded.

    If a file name is specified, then the file name must exactly match a file name assigned to one of the panelSet parameters entered with <APPLET> tag.

    An example of a <SET> tag using a file name is:

    <SET panelSet="SecondPanelSet.TXT">

    Remember, in order to preserve upper and lower case characters, you must surround the attribute value with quotation marks.

    If a panel set number is entered, then it should correspond to one of the panelSet parameters entered with <APPLET> tag.

    An example of a <SET> tag using a number is:

    <SET panelSet=2>

    The above example would load the panel set associated with the panelSet2 applet parameter.

  • stop

    If this optional attribute is set to "true", then all WildView animation will be stopped while the new panel set is loaded.

    If the attribute value is set to "false", then animation will continue while the next panel set is loaded.

    If the stop attribute is not specified, then its value will default to "false".

  • loadMessage

    If a text string is specified for this optional attribute, then the text will be displayed on a single line in the center of the applet display area while the next panel set is loaded.
R eceiving Triggers

A <TRIGGER> sent by a WildView panel to a WVPanelTimer panel can cause a WVPanelTimer panel that has been paused to resume, or it can ask the WVPanelTimer panel to pause and wait until it receives a specific waitID or until a timeout expires, or the <TRIGGER> can change the enable state of the WVPanelTimer panel.
Resume from a <WAIT>

If a WVPanelTimer panel encounters a <WAIT> tag, then the panel will stop and wait for a trigger, or for the time specified by the <WAIT> tag's timeout attribute to elapse.

If the <WAIT> tag specifies an id attribute, then the panel will wait until it receives a trigger that has a matching id.

For instance, suppose there is a WVPanelTimer panel named "animate" and some of the tags that follow the WVPanelTimer panel tag are:

...

<TRIGGER panel=image displayX=120 displayY=0 displayW=120 displayH=50>

<WAIT id=continue>

<TRIGGER panel=image2 displayX=0 displayY=0 displayW=120 displayH=50>

...

After the first <TRIGGER> shown is fired at the image panel, the WVPanelTimer panel will pause and will wait until another panel executes a trigger that might look something like this:

... and that's the end of this topic.<BR> <TRIGGER panel=animate id=continue>Here is our next topic ...


Once the WVPanelTimer panel (which is named "animate") receives this trigger, it sees that the id attribute of the <WAIT> tag matches the id attribute of the trigger received, and it continues processing the tags beginning with the <TRIGGER> tag for the image2 panel that follows the <WAIT> tag.

If the <WAIT> tag had omitted the id attribute, then processing would have resumed when any trigger was received, regardless of the trigger's id attribute.

Also, if the <WAIT> tag had used the timeout attribute, then the processing would have resumed even if a trigger had not been received provided that the number of 1/10th seconds specified by the timeout attribute had elapsed.
Pause and <WAIT> for ID

If a trigger is sent to a WVPanelTimer panel with a waitID attribute, then the panel will pause and stop processing the tags that follow the panel tag.

The panel will resume processing the tags when either it receives a trigger that has a matching id, or when a timeout expires.

The effect of sending a trigger with a waitID attribute to a WVPanelTimer panel is the same as embedding a <WAIT> tag in the tags following the WVPanelTimer panel tag.

To illustrate when this feature might be used, imagine that you have two WVPanelTrigger panels in a panel set that are used to simulate buttons. The panel set might look something like:

...

<PANEL name=pauseButton
  module="WVPanelTrigger"
  x=0 y=0 w=52 h=40
  event=buttonUp panel=timer
  waitID=continue>

<PANEL name=continueButton
  module="WVPanelTrigger"
  x=52 y=0 w=52 h=40
  event=buttonUp panel=timer
  id=continue>

<PANEL name=timer
  module="WVPanelTimer">

...

In this configuration, when the mouse button is pressed and released in the "pauseButton" panel, a trigger will be sent to the "timer" panel that looks like this:

<TRIGGER panel=timer waitID=continue>

This will cause the "timer" panel to pause and wait for a trigger with an id of "continue" before it will resume processing.

When the mouse button is pressed and released in the "continueButton" panel, a trigger will be sent to the "timer" panel that looks like this:

<TRIGGER panel=timer id=continue>

Since the id matches the id that the "timer" panel is waiting for, the "timer" panel will resume processing.

The waitID can be combined with the timeout attribute so long as the waitID attribute appears before the timeout attribute in the trigger.
Pause until Timeout

If a trigger is sent to a WVPanelTimer panel with a timeout attribute, then the panel will pause and stop processing the tags that follow the panel tag.

The panel will resume processing the tags when the number of 1/10th seconds specified by the timeout attribute value have elapsed, or when the panel receives a subsequent trigger (if a waitID is active, then in order for the panel to resume processing when a trigger is received, the trigger must have an id attribute that matches the id for which the panel is waiting).

The effect of sending a trigger with a timeout attribute to a WVPanelTimer panel is the same as embedding a <WAIT> tag in the tags following the WVPanelTimer panel tag.

Remember that the value of the timeout attribute is in 1/10th seconds (e.g. timeout=25 is equivalent to 2½ seconds), and not whole seconds as it is for other types of panels.

As an example of how this feature might be used, suppose that you would like to briefly stop an animation controlled by a WVPanelTrigger panel when the mouse enters a particular area of a WildView display. The panel set might look something like:

...

<PANEL name=restArea
  module="WVPanelTrigger"
  x=0 y=0 w=52 h=40
  event=mouseEnter panel=animation
  timeout=50>

<PANEL name=animation
  module="WVPanelTimer">

...

In this configuration, when the mouse button is moved within the "restArea" panel, a trigger will be sent to the "animation" panel that looks like this:

<TRIGGER panel=restArea timeOut=50>

This will cause the "animation" panel to pause and wait for five seconds, or until a subsequent trigger is sent to the panel, before the panel will resume processing.

The timeout can be combined with the waitID attribute so long as the waitID attribute appears before the timeout attribute in the trigger.
Change the Enable State

A WVPanelTimer panel can be enabled or disabled by sending a <TRIGGER> to the panel to change the panel's enable state.

To enable the WVPanelTimer panel, the <TRIGGER> tag sent to the WVPanelTimer panel should look like:

<TRIGGER panel=panelName enable=true>

To disable the WVPanelTimer panel, the <TRIGGER> tag sent to the WVPanelTimer panel should look like:

<TRIGGER panel=panelName enable=false>

An example of when triggering the panel's enable state might be useful is if you would like to start an animation when a particular passage in some scrolling text is reached and end the animation after the text passage has been completely displayed.

To accomplish this, you would create a WVPanelTimer panel to control the animation with a panel tag similar to:

<PANEL name=animate module="WVPanelTimer" enable=false>

Notice how the panel is initially disabled.

In the text defined for the scrolling text panel, you would pace two triggers: one trigger to enable the WVPanelTimer panel and thus start the animation, and one trigger to disable the WVPanelTimer panel and stop the animation. This would look something like:

...

<TRIGGER panel=timer enable=true>

The animation that you can now see simulates...
...as you have seen in the animation.
<TRIGGER panel=timer enable=false>

...

E xample

Using <WAIT> tags with a timeout attribute in combination with <TRIGGER> tags is a good way to create a simple animation (at speeds of up to 10 frames per second).

In order to create an animation, you will need a WVPanelTimer panel and a WVPanelImage panel in your panel set.

The example below shows an applet tag and a panel set to implement an animated button. In an actual WildView display you probably would include the button as part of a larger panel set, but to keep things simple, the animated button has been implemented as a stand-alone applet.

The functioning animated button applet is displayed below. To see the animation, move the mouse over the button (the black area on the left). When the button is clicked, the first page of the WildView documentation will be loaded over this page.

Go to Doc Home Page

The applet tag for the WildView animated button is shown below.

<APPLET CODEBASE="../Java"
  WIDTH="52" HEIGHT="40"
  CODE="WildViewApplet.class">
<PARAM NAME="panelSet1"
  VALUE="DocExamples/WVPanelTimer/WVPanelTimer.TXT">
</APPLET>

The following is the panel set layout file for the WildView animated button.

<PANEL name=DocHome module="WVPanelURL"
  x=0 y=0 w=52 h=40
  url="../WildView.html" target="_self">

<PANEL name=ArrowImage module="WVPanelImage"
       preLoad=false
  x=0 y=0 w=52 h=40
  image="DocExamples/WVPanelTimer/AnimArrow.GIF"
  loadTrigger=ArrowTimer
  displayX=208 displayY=40
  displayW=52 displayH=40>

<PANEL name=ArrowTimer module="WVPanelTimer"   initWait=ArrowImage x=0 y=0 w=52 h=40
  activate=mouseEnter deactivate=mouseExit>

<TRIGGER panel=ArrowImage
  displayX=0 displayY=0>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=52 displayY=0>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=104 displayY=0>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=156 displayY=0>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=208 displayY=0>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=0 displayY=40>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=52 displayY=40>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=104 displayY=40>
<WAIT timeout=2>
<TRIGGER panel=ArrowImage
  displayX=156 displayY=40>
<WAIT timeout=5>

<PANEL name=resetImage module="WVPanelTrigger"
  x=0 y=0 w=52 h=40
  event=mouseExit panel=ArrowImage
  displayX=208 displayY=40>

The frames for the animation ("AnimArrow.GIF") are shown below.

Copyright © 1997 by Modern Minds, Inc.