WildView - WVPanelTrigger Module

odule WVPanelTrigger

The trigger module (WVPanelTrigger) allows you create a panel that can send a single message or multiple messages to another panel (or to the WildView applet) when a mouse event (e.g, a mouse button click) occurs in the WVPanelTrigger panel's area.

The WVPanelTrigger 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 five sections:

Overview provides an overview of the module's operation
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.

verview

Most panels created with a WildView module can be controlled by sending the panel a TRIGGER from another panel (see each module's documentation for information regarding what types of TRIGGERs the module can recognize).

In version 1.0 of WildView, the WVPanelTrigger module allowed you to create panels that could send a single TRIGGER to another panel when a particular mouse event occurred in the WVPanelTrigger panel's region (as defined by the x, y, w, and h attributes). The TRIGGER to be sent was defined by information entered in the WVPanelTrigger panel tag (note that the WVPanelTrigger module still supports this method of specifying a TRIGGER).

An example of placing the TRIGGER information in the WVPanelTrigger panel tag is:

<PANEL name=showImage1 module="WVPanelTrigger" x=83 y=3 w=50 h=36 panel=images event=mouseEnter displayX=75 displayY=0 displayW=75 displayH=36>

Version 1.1 of WildView added the capability of sending any number of TRIGGERs from a WVPanelTrigger panel to another WildView panel or panels. TRIGGERs can now be specified by placing <TRIGGER> tags after the WVPanelTrigger panel tag (see the Tags section below for more information).

An example of placing the TRIGGER information after the WVPanelTrigger panel tag is:

<PANEL name=showImage1 module="WVPanelTrigger" x=83 y=3 w=50 h=36> <TRIGGER panel=images event=mouseEnter displayX=75 displayY=0 displayW=75 displayH=36> <TRIGGER panel=frame1 event=buttonDown color1=aa0000 color2=ff0000>

If you are creating a panel that sends only a single TRIGGER, then you can easily specify the TRIGGER by using the event, panel, panelSet, stop, loadMessage, and user attributes within the WVPanelTrigger panel tag.

If you are creating a panel that will send multiple TRIGGERs, then see the Tags section to learn how to specify the TRIGGERs by using TRIGGER tags.

odule Attributes

Each possible attribute that can be specified for a panel tag that uses the WVPanelTrigger 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="WVPanelTrigger" name=ActionTrigger x=10 y=10 w=50 h=25 enable=true event=mouseEnter panel=ArticleFrame panelSet="FancyLayout.TXT" stop=true loadMessage="Loading Fancy Layout" ... User Attributes ... >

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 file 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.

ttribute Descriptions

Each attribute of the WVPanelTrigger 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 WVPanelTrigger module, this attribute must be set as:

module="WVPanelTrigger"

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 determines where the left edge of the panel will be located in the WildView display area.

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 will be located with its left edge positioned in the middle of the WildView display.

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

y

The y attribute determines where the top edge of the panel will be located in the WildView display area.

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 will be located with its top edge positioned in the middle of the WildView display.

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

w

The w attribute determines the width of the panel in the WildView display area.

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 at 20 + 160 = 180), then the panel will be centered horizontally in the WildView display (there is a margin of 20 to the left of the left panel edge and a margin of 200 - 180 = 20 to the right of the right panel edge).

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

h

The h attribute determines the height of the panel in the WildView display area.

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 at 10 + 80 = 90), then the panel will be centered vertically in the WildView display (there is a margin of 10 above the top panel edge and a margin of 100 - 90 = 10 below the bottom panel edge).

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

enable

The enable attribute determines if the panel will examine mouse events that occur within the area defined by the x, y, w, and h attributes.

The following two values are valid for this attribute:

true - the panel will examine mouse events and will send all triggers with matching event types.
false - the panel will not respond to any mouse event

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

event (see Overview)

The event attribute defines the type of mouse event that will cause the WVPanelTrigger to send a trigger (i.e., perform an action). The mouse event must occur within the panel area defined by the x, y, w, and h attributes.

The valid attribute values are:

mouseEnter - the mouse moves into the panel's area
mouseExit - the mouse moves out of the panel's area
buttonDown - the mouse button is pressed in the panel's area
buttonUp - the mouse button is released after it has been pressed in the panel's area

If the trigger should be fired for more than one event type, then the event types may be combined.

For instance, if the trigger should be fired at a panel when the mouse button is released and also when the mouse moves out of the panel area, then both events can be specified as:

event=buttonDown+mouseExit

or as

event="buttonDown mouseExit"

Only one trigger per WVPanelTrigger panel can be sent when a defined event occurs, unless trigger tags are used.

If a value for the event attribute is not specified and if there are no trigger tags, then no <TRIGGER> will be fired by the panel.

panel (see Overview)

The panel attribute specifies the name of a panel to which the user attributes will be sent when the event defined by the event attribute occurs.

For instance, if the user attributes should be sent to a panel with the name of "PhotoPanel," then the attribute specification would look like:

panel=PhotoPanel

If the panelSet attribute is specified, then the panel attribute should not be specified.

If both the panel attribute and the panelSet attribute is specified, then the panel attribute will always be ignored.

If a value for the panel attribute is not specified, then any user attributes in the WVPanelTrigger panel tag will not be sent to a panel.

panelSet (see Overview)

The panelSet attribute specifies the name or number of a panel set file (i.e., a "layout" file) to be loaded and activated when the event defined by the event attribute occurs. The new panel set will replace the currently loaded panel set.

In order to load the specified panel set file when the defined event occurs, the WVPanelTrigger module will send a message to the WildView applet and pass to the applet the panelSet attribute value.

If a number is specified for the panelSet attribute, then the number should correspond to one of the panelSet parameters entered with <APPLET> tag.

An example of a panelSet attribute specification using a number is:

panelSet=2

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

If a file name is specified for the panelSet attribute, then the file name should always be enclosed within quotation marks to ensure that the WildView applet will be able to locate the file on the server. Here is an example of a panelSet attribute specification using a file name:

panelSet="FirstFile.TXT"

If a panel set file name is specified without a path, then the WildView applet will look for the panel set file using the URL of the Java code (i.e., the applet will search for the panel set file in the directory that contains the WildView Java class files).

If a path to panel set file is specified, then the path root is based on the URL of the Java code. For instance, if the WildView Java classes are in a directory called "Java", and if a panel set file called "FirstFile.TXT" is in a directory called "PanelSets" which is in the "Java" directory (i.e., "Java/PanelSets/FirstFile.TXT"), then the attribute assignment would be:

panelSet="PanelSets/FirstFile.TXT"

If the panelSet attribute is specified, then the panel attribute should not be specified.

If both the panelSet attribute and the panel attribute is specified, then the panel attribute will always be ignored.

See also the related stop and loadMessage attributes below.

If a value for this attribute is not specified, then no panel set file will be loaded when the specified event occurs.

stop (see Overview)

The stop attribute determines if the currently loaded panel set should be stopped when an event causes a new panelSet to be loaded.

This attribute is used only if the panelSet attribute is also specified. If the panelSet attribute is not specified, then the stop attribute is ignored.

The valid attribute values are:

true - the currently loaded panel set will be stopped while the new panel set is loaded. This means that animation in the WildView display will cease until the new panel set has been loaded.
false - the currently loaded panel set will continue to run while the new panel set loads as a background task.

See also the related loadMessage attribute below.

If a value for the stop attribute is not specified, then the attribute's value will default to false.

loadMessage (see Overview)

The loadMessage attribute specifies text that will be displayed on a single line in the center of the applet display area while the panel set specified by the panelSet attribute is loaded.

This attribute is used only if the panelSet attribute is also specified. If the panelSet attribute is not specified, then the loadMessage attribute is ignored.

See also the related stop attribute above.

User Attributes (see Overview)

When a panel name is specified for the panel attribute, then when a mouse event occurs that matches the event type specified by the event attribute, any attribute that is not recognized by the WVPanelTrigger module will be sent in a <TRIGGER> to the panel named by the panel attribute.

As an example, suppose the following WVPanelTrigger panel is defined in a panel set:

<PANEL name=ChgClr module="WVPanelTrigger" x=0 y=0 w=200 h=100 event=mouseDown panel=TextFrame color1=ff0000>

When the mouse is clicked (i.e., the mouse button is pressed down) in the panel area, the WVPanelTrigger will create and send a trigger that looks like:

<TRIGGER panel=TextFrame color1=ff0000>

In this case since the target panel is (probably) a WVPanelFrame panel, the mouse click will have the effect of changing the color of the frame.

There is no limit to the number of attributes that may be specified in a WVPanelTrigger panel definition.

Note that if the panel attribute is not specified, or if both the panel and panelSet attributes are specified, then all of the unrecognized attributes will be ignored and the trigger will not be sent.

If no unrecognized attributes are specified in the <PANEL> tag, then the trigger will be sent.

ags (see Overview)

Any number of <TRIGGER> tags may follow the WVPanelTrigger panel tag. The format of the <TRIGGER> tag is defined below. Click on any of the tag attributes to jump to a description of the attribute.

<TRIGGER event=mouseEnter panel=ArticleFrame panelSet="FancyLayout.TXT" stop=true loadMessage="Loading Fancy Layout..." ... User Attributes ... >

event

The event attribute defines the type of mouse event that will cause the trigger to be sent. The mouse event must occur within the panel area defined by the x, y, w, and h attributes.

The valid attribute values are:

mouseEnter - the mouse moves into the panel's area

mouseExit - the mouse moves out of the panel's area

buttonDown - the mouse button is pressed in the panel's area

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

For instance, if the trigger should be fired at a panel when the mouse button is released and also when the mouse moves out of the panel area, then both events can be specified as:

event=buttonDown+mouseExit

or as

event="buttonDown mouseExit"

If a value for the event attribute is not specified, then the <TRIGGER> definition will be ignored by the panel.

panel

The panel attribute specifies the name of a panel (or panels) to which the user attributes will be sent when the event defined by the event attribute occurs.

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

panel=panel1

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

panel=panel1,panel2,panel3

Note that without quotation marks, you cannot put spaces in the panel attribute value. If you surround the attribute value with quotation marks, however, you can place spaces in the panel attribute value: in fact, you can use spaces instead of commas to separate the panel names to which the user attributes 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"

If the panelSet attribute is specified, then the panel attribute should not be specified.

If both the panel attribute and the panelSet attribute is specified, then the panel attribute will always be ignored.

If a value for the panel attribute is not specified, then any user attributes in the TRIGGER tag will not be sent to a panel.

panelSet

The panelSet attribute specifies the name or number of a panel set file (i.e., a "layout" file) to be loaded and activated when the event defined by the event attribute occurs. The new panel set will replace the currently loaded panel set.

In order to load the specified panel set file when the defined event occurs, the WVPanelTrigger module will send a message to the WildView applet and pass to the applet the panelSet attribute value.

If a number is specified for the panelSet attribute, then the number should correspond to one of the panelSet parameters entered with <APPLET> tag.

An example of a panelSet attribute specification using a number is:

panelSet=2

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

If a file name is specified for the panelSet attribute, then the file name should always be enclosed within quotation marks to ensure that the WildView applet will be able to locate the file on the server. Here is an example of a panelSet attribute specification using a file name:

panelSet="FirstFile.TXT"

If a panel set file name is specified without a path, then the WildView applet will look for the panel set file using the URL of the Java code (i.e., the applet will search for the panel set file in the directory that contains the WildView Java class files).

If a path to panel set file is specified, then the path root is based on the URL of the Java code. For instance, if the WildView Java classes are in a directory called "Java", and if a panel set file called "FirstFile.TXT" is in a directory called "PanelSets" which is in the "Java" directory (i.e., "Java/PanelSets/FirstFile.TXT"), then the attribute assignment would be:

panelSet="PanelSets/FirstFile.TXT"

If the panelSet attribute is specified, then the panel attribute should not be specified.

If both the panelSet attribute and the panel attribute is specified, then the panel attribute will always be ignored.

See also the related stop and loadMessage attributes below.

If a value for this attribute is not specified, then no panel set file will be loaded when the specified event occurs.

stop

The stop attribute determines if the currently loaded panel set should be stopped when an event causes a new panelSet to be loaded.

This attribute is used only if the panelSet attribute is also specified. If the panelSet attribute is not specified, then the stop attribute is ignored.

The valid attribute values are:

true - the currently loaded panel set will be stopped while the new panel set is loaded. This means that animation in the WildView display will cease until the new panel set has been loaded.

false - the currently loaded panel set will continue to run while the new panel set loads as a background task.
See also the related loadMessage attribute below.

If a value for the stop attribute is not specified, then the attribute's value will default to false.

loadMessage

The loadMessage attribute specifies text that will be displayed on a single line in the center of the applet display area while the panel set specified by the panelSet attribute is loaded.

This attribute is used only if the panelSet attribute is also specified. If the panelSet attribute is not specified, then the loadMessage attribute is ignored.

See also the related stop attribute above.

User Attributes

When a panel name is specified for the panel attribute, then when a mouse event occurs that matches the event type specified by the event attribute, any attribute that is other than the attributes recognized by the <TRIGGER> will be sent to the panel named by the panel attribute.

As an example, suppose the following trigger is defined:

<TRIGGER event=mouseDown panel=TextFrame color1=ff0000>

When the mouse is clicked (i.e., the mouse button is pressed down) in the panel area, WildView will create and send a trigger that looks like:

<TRIGGER panel=TextFrame color1=ff0000>

In this case since the target panel is (probably) a WVPanelFrame panel, the mouse click will have the effect of changing the color of the frame.

There is no limit to the number of attributes that may be specified in the <TRIGGER> definition.

Note that if the panel attribute is not specified, or if both the panel and panelSet attributes are specified, then all of the unrecognized attributes will be ignored and the trigger will not be sent.

If no unrecognized attributes are specified in the <TRIGGER> tag, then the trigger will be sent.

eceiving Triggers

At present there is only one <TRIGGER> function that is supported by a panel based on the WVPanelTrigger module.

You can enable or disable a WVPanelTrigger panel by sending the panel a <TRIGGER> with an enable attribute.