Events supported in XML documents
Posted: Sun May 19, 2019 7:14 pmUPDATED: December 30, 2020
The following events can be programmed into your XML configuration files:
(I will be progressively adding to this post. Please check back frequently.)
The following events can be programmed into your XML configuration files:
(I will be progressively adding to this post. Please check back frequently.)
- Event name: click
Example 1:<myObjectName>
<pgStyleObject>
{ theStyle : "cursor",
propVals : "pointer" }
</pgStyleObject>
<function name="myClick" event="click" params="evt,undef,target,mX,mY,isShift,isCntrl" useTB="true">
<![CDATA[
/* CLIFTON: When this object is clicked, the following function will execute.
the [useTB] property indicates this is a ToolBook object and the XML
engine should use ToolBook's event listener to setup the event.
The function changes the field fontSize, height, width, color, background,
border, padding and box shadow styles.
It also changes the text of the field.
***/
var css = [ "fontSize, height, width, color, background, border, padding, borderRadius, boxShadow",
"16pt, auto, auto, white, rgb(0,72,186), 2px solid #FFDD00, 14px, 14px, 2px 2px 6px 2px #274A65" ];
tbfunction_pgTBObjSet( this.name, "text", "You CLICKED me baby!");
tbfunction_pgStyleObject( this.name, css[0], css[1]);
]]>
</function>
</myObjectName>
Example 2: (Does NOT use the internal ToolBook event system but accomplishes the exact same thing. Sometimes, this provides more versatility. It is the REQUIRED method for any object (level 1 or 0) which is created using a <make> tag.)<myObjectName>
<pgStyleObject>
{ theStyle : "cursor",
propVals : "pointer" }
</pgStyleObject>
<function name="myClick" event="click" params="e">
<![CDATA[
/* CLIFTON: When this object is clicked, the following function will execute.
the [e] parameter is the DOM event object from which many properties
can be retrieved/discovered.
The function changes the field fontSize, height, width, color, background,
border, padding and box shadow styles.
It also changes the text of the field.
***/
var css = [ "fontSize, height, width, color, background, border, padding, borderRadius, boxShadow",
"16pt, auto, auto, white, rgb(0,72,186), 1px solid #FFDD00, 14px, 14px, 2px 2px 2px 6px #274A65" ];
tbfunction_pgTBObjSet( this.name, "text", "You CLICKED me baby!");
tbfunction_pgStyleObject( this.name, css[0], css[1]);
]]>
</function>
</myObjectName>
Results:- Before:
- Before clicking on field in browser.
- Image 3.png (1.46 KiB) Viewed 6573 times
- AFTER clicking on field in browser.
- Image 4.png (7.06 KiB) Viewed 6573 times
AFTER: - Event name: load
(NOT supported within <make> tags because the object has not loaded until the entire tag has been processed by the XML engine. However, you can still use the load event if you also include it in a <makeTagId> section that follows the <make id="makeTagId">...</make> section. See example 2.)
Example 1:<myObjectName>
<!--Next style prevents user from clicking this object and shows
other styles that can be set in XML files.-->
<pgStyleObject>
{ theStyle : "pointerEvents",
propVals : "none" }
</pgStyleObject>
<function name="myLoad" event="load" params="e" useTB="true">
<![CDATA[
/* CLIFTON: When this object loads, the following function executes.
The [useTB] = "true" property is NOT needed unless <myObjectName>
is a ToolBook page object or a group. In those cases, [useTB] = "true"
IS required. Generally, the property can be removed.
The function creates an audio playlist array which is used to play
background music.
Playlist indice format: "file,volume"
NOTE: When each clip is started it is popped into my3Done[ ] array.
When all clips have been played, mp3Done[ ] array is copied back to
mp3List[ ] array and playback continues. Each iteration randomizes
the clips left in mp3List[ ]array.
(See also user event function for this object where the audio is started and
manipulated.)
***/
this.mp3List = [ "Acoustic-Bass-Romantic-Funk, 8",
"Cheerful-Background, 12",
"Childhood, 10",
"Corporate-Background, 8",
"Corporate-Inspiration, 9",
"Corporate-Music, 10",
"Documentary, 12",
"Dreamy-Advert, 16",
"Fairy-Lullaby, 14",
"Happy-Sunny-Mood, 11",
"Happy-Walk, 18",
"Joyful-Background, 8",
"Pop-Rock-Beautiful, 15",
"Pop-Rock-Commercial, 12",
"Upbeat-Background-Music, 8" ];
this.mp3Done = [];
]]>
</function>
</myObjectName>
Example 2: (Using load events with <make> object tags.)<make id="myElement" type="div" level="1" dims="100,100,100,100" class="" refObj="myField" autoAlign="" replace="">
<style>
{ "border" : "2px solid blue",
"background" : "rgb(15, 192, 252)",
"borderRadius" : "12px",
"visibility" : "hidden" }
</style>
</make>
<!--Now we reference the <make> element which has finished loading and run an onload function.-->
<myElement>
<function name="myLoad" event="load" params="e">
<![CDATA[
/* CLIFTON: Align this object to an object called "myField" on the ToolBook page.
Using slight delay in next calls to make sure the ToolBook object has fully loaded.
***/
tbfunction_snapObjectToCenter(this.name, "myField", "left, top to bottom", false, "0,0", 250);
tbfunction_pgTBObjSet(this.name, "visible", true, 250);
]]>
</function>
</myElement>
UPDATE: As of PowerPac v15.049.2, it is possible to specify a delay="#" when defining the "load" function. This also permits embedding the "load" function directly inside the <make>...</make> tag. The default delay inside a <make>...</make> tag for a "load" function is 50 milliseconds.
- Event name: user
Example 1:<myObjectName>
<function name="myUser" event="user" params="evt,value" useTB="true">
<![CDATA[
/* CLIFTON: Audio control script. A user event is initially sent when the user logs in.
Random audio files play with each user event when a previous file has finished.
***/
var user = tbfunction_pgExecuteRemote('ContentArea', 'tbfunction_pgTBObjSet', ['Backdrop', 'manageUser'], false),
path = '../audio/', ext = '.mp3', defVol = 7, tmp, chk = tbfunction_pgTBObjGet(this.name, 'checked');
user.options = user.options.split('~');
if (/initialize/i.test(value)) {
// CLIFTON: Check user profile if audio is ON and begin playback.
tbfunction_pgTBObjSet(this.name, 'visible', true);
//Check the audio button if user has disabled audio in their options
tbfunction_pgTBObjSet(this.name, 'checked', user.options[4] == 1);
if (user.options[4] == 0) {
//Starts playback
tbfunction_pgTBObjSet(this.name, 'user', 'audio,end', 10);
}
} else if (/audio,end/i.test(value)) {
//Start new random audio sequence
if (this.mp3List.length == 0) {
//Reset the playlist array and start randomization over again
this.mp3List = this.mp3Done.slice(0);
this.mp3Done.length = 0;
}
tbfunction_pgSort_Shuffle(this.mp3List, false, true, 1, false, 'array'); //Manipulates mp3List[ ] directly!
tmp = this.mp3List.shift();
this.mp3Done.push( tmp );
tmp = tmp.split(',');
tmp[1] = tmp[1] || defVol; //Allow custom volume per file or use defVol
tbfunction_pgSoundLoader(path + tmp[0] + ext, this.name, 0, 'play', false, tmp[1]);
}
]]>
</function>
<myObjectName>
Example 2: (Similar to above but NOT using [useTB] = "true". This method IS REQUIRED for any object created with the <make> tag.)<myObjectName>
<function name="myUser" event="user" params="e">
<![CDATA[
/* CLIFTON: Audio control script. A user event is initially sent when the user logs in.
Random audio files play with each user event when a previous file has finished.
NOTE: to access the [value] property of the user event in this case we use
use [e.data] OR [e.value]. The choice is yours.
***/
var user = tbfunction_pgExecuteRemote('ContentArea', 'tbfunction_pgTBObjSet', ['Backdrop', 'manageUser'], false),
path = '../audio/', ext = '.mp3', defVol = 7, tmp, chk = tbfunction_pgTBObjGet(this.name, 'checked');
user.options = user.options.split('~');
if (/initialize/i.test(e.data)) {
// CLIFTON: Check user profile if audio is ON and begin playback.
tbfunction_pgTBObjSet(this.name, 'visible', true);
//Check the audio button if user has disabled audio in their options
tbfunction_pgTBObjSet(this.name, 'checked', user.options[4] == 1);
if (user.options[4] == 0) {
//Starts playback
tbfunction_pgTBObjSet(this.name, 'user', 'audio,end', 10);
}
} else if (/audio,end/i.test(e.data)) {
//Start new random audio sequence
if (this.mp3List.length == 0) {
//Reset the playlist array and start randomization over again
this.mp3List = this.mp3Done.slice(0);
this.mp3Done.length = 0;
}
tbfunction_pgSort_Shuffle(this.mp3List, false, true, 1, false, 'array'); //Manipulates mp3List[ ] directly!
tmp = this.mp3List.shift();
this.mp3Done.push( tmp );
tmp = tmp.split(',');
tmp[1] = tmp[1] || defVol; //Allow custom volume per file or use defVol
tbfunction_pgSoundLoader(path + tmp[0] + ext, this.name, 0, 'play', false, tmp[1]);
}
]]>
</function>
<myObjectName>
- Event names: mouseover, mouseout, mousedown, mouseup, mouseenter
These functions are supported on any objects, including objects created by <make> tags.
You can group these events in the same function, like this:
Example 1: (using native browser events for any object)<myObject>
<function name="myMouse" event="mouseout,mouseover" params="e">
<![CDATA[
/* CLIFTON: Change the border color on mouseover and restore it on mouseout.
Params: (a few of the properties available)
e = window.event object
e.type = string as mouseout | mouseover
e.screenX = integer
e.screenY = integer
e.pageX or e.clientX or e.x = integer for mouse X position relative to window or iframe
e.pageY or e.clientY or e.y = integer for mouse Y position
e.offsetX or e.offsetY = integer as mouse X/Y position relative to e.target
e.ctrlKey = boolean true/false if control key is pressed
e.shiftKey = boolean true/false if shift key is pressed
e.target = DOM object that fired the event or the object that the mouse is over
e.buttons = integer indicating whether a mouse button is depressed when event fires
0 - none; 1 - left button; 2 - right button;
3 - both left and right buttons; 4 - middle button
***/
if (e.type == "mouseout") {
//Restore the object's border style
tbfunction_pgStyleObject(this.name, "border", "1px solid black");
} else if (e.type == "mouseover") {
tbfunction_pgStyleObject(this.name, "border", "1px solid red");
}
]]>
</function>
</myObject>
Example 2: (using internal ToolBook events for ToolBook objects only)<myObject>
<function name="myMouse" event="mouseout,mouseover" params="evt,undef,target,mX,mY,isShift,isCntrl" useTB="true">
<![CDATA[
/* CLIFTON: Change the border color on mouseover and restore it on mouseout.
Params:
evt = string as mouseout | mouseover
undef = always null or undefined
target = object as the ToolBook object that fired the event
Example: target.name = string as name of the ToolBook object
mX = integer as the mouse X position when the event fires
mY = integer as the mouse Y position when the event fires
isShift = boolean true/false indicating if shift key is down when event fires.
isCntrl = boolean true/false indicating if control key is down when event fires.
***/
if (evt == "mouseout") {
//Restore the border
tbfunction_pgStyleObject(this.name, "border", "1px solid black");
} else if (evt == "mouseover") {
tbfunction_pgStyleObject(this.name, "border", "1px solid red");
}
]]>
</function>
</myObject>
Grouped events may include "mouseover,mouseout,mouseenter" and "mousedown,mouseup".
NOTE: "mouseenter" is not supported as an internal ToolBook event.
- Event name: mousemove
The mousemove event is NOT supported by the internal ToolBook event system. Therefore, to
set this up in XML, you will need to use the normal browser event system. It is best to
only add a mousemove event in response to some other mouse event (e.g.: mousedown); and
then remove the mousemove event when the trigger event has finished.
Example 1:<myObject>
<function name="mousey" event="mousedown,mouseup" params="e">
<![CDATA[
/* CLIFTON: Set up a mousemove event to allow moving this object as long as
the left mouse button is down. Releasing the mouse button
generates a mouseup event and turns off the mousemove event
notification.
***/
if (!this.myMove) {
//Define mousemove function; only defined ONCE
this.myMove = function(e) {
if (!e) return;
this.style.left = (e.pageX - this.offset[0]) + "px";
this.style.top = (e.pageY - this.offset[1]) + "px";
};
}
if (e.type == "mousedown") {
this.offset = [e.offsetX, e.offsetY]; //Saves relative mouse position for "myObject"
this.style.cursor = "pointer";
pgAddEvent(this, "mousemove", this.myMove);
} else if (e.type == "mouseup") {
pgRemoveEvent(this, "mousemove", this.myMove);
this.style.cursor = '';
delete this.offset;
}
]]>
</function>
</myObject>
- Event names: focus, blur
- Event names: keydown, keyup, keypress
- Event name: unload
- Event name: change
- Event name: answer
- Event name: score
- Event name: reset
- custom functions