Alpha Anywhere Tutorial Definition

Description

The .a5tut extension is used for defining an interactive tutorial.

 Fields

Name
Property and Description
action

Track action to follow

name

Name of action

where

Fully Qualified identifier of action location in the UX.

message

HTML content to display associated with the control or subitem of a control identified by the 'where' property.

edge

Edge of control specified by the 'where' property to display the message (left, right, top, bottom).

exactMatch

For this step to complete, the value of the control specified by the 'where' property must match this value.

Can be an object rather than a string if the control specified for 'where' does not match the control for the action.

skipMatch

If the value of the control specified by the 'where' property matches this value, this step is skipped.

Can be an object rather than a string if the control specified for 'where' does not match the control for the action.

validateEval

This contains an optional xbasic expression, which can contain a <dlgtitle> placeholder, which gets replaced with the string of the xdialog specified by the actions 'where' property.

The expression should return a logical .t. if the action is valid (at which point, the action script will advance to the next action).

skipEval

This contains an optional xbasic expression, which can contain a <dlgtitle> placeholder, which gets replaced with the string of the xdialog specified by the actions 'where' property.

The expression should return a logical .t. if the action should be skipped.

step

Identifies this as the last action in a 'step'.

continue

Add the 'next' step to the 'page' this step is one.

 Actions

Action
Property and Description
menuSelect

Action is a menu selection , can be top menu or context menu or submenu.

controlChange

Action is result of user editing the value of a control.

controlSelect

Action is result of user selecting the value of a control.

controlClick

Action is the result of the user clicking on a control.

controlDoubleClick

Action is the result of the user double clicking on a control.

controlRightClick

Action is the result of the user right clicking on a control.

controlAny

Action is *any* action on a control (this is generally used in conjuction with an 'exactMatch' where a control value might be set via selection or editing).

viewActivate

Action is the result of the user selecting a diffent view, generally by clicking on the title section.

include

Action is placeholder for actions in another file (where property contains relative path).

 ExactMatch, SkipMatch Object

Property
Description
where

Specifies the control to follow the value of.

value

Specifies the match 'value'.

 Example with SkipMatch

In this example, when the tutorial script is run from the web control panel, a message will point to the 'Web Components' entry of in the Web Control Panel Selector if the 'Web Components' page is not the active page. Then a message will show up above the 'new' button.

{
    "actions": [
        {
            "action": "controlChange",
            "name": "Web Components",
            "where": "/WebControlPanel/list/Category/Web Components",
            "message": "Change Web Components control.",
            "skipMatch": "Web Components",
            "step": 1
        },
        {
            "action": "buttonClick",
            "name": "New",
            "where": "/WebControlPanel/button/New",
            "message": "Click New button.",
            "edge": "top",
            "step": 2
        },
    ]
}

 Example of tracking changes to List Content

Below is a standalone tutorial code example of a dialog that has a button that adds elements to a list, and advances to the *next* step only when the list has 7 entries.

Note that exactMatch is an object instead of a string, because the action is the button click, but the value to Test is the content of the list.

Also note that the list content is denoted by the control path (/Test/list/item) with the #List suffix.

Also note that the sample xdialog uses the {where=} keyword to specify the well known name.

dim json as c = <<%json%
{
    "actions": [
        {
            "action": "buttonClick",
            "name": "Add",
            "where": "/Test/button/Add",
            "message": "Click Add button.",
            "step": 2,
            "continue" : true , 
            "exactMatch" : {
             	"where" : "/Test/list/item#List",
             	"value" :  "One\nTwo\nThree\nFour\nFive\nSix\nSeven"
            }
        },
        {
            "action": "buttonClick",
            "name": "Close",
            "where": "/Test/button/Close",
            "message": "Click Close button.",
            "step": 3
        }
    ]
}
%json%
dim uxa as WindowManager::UxAutomation
uxa.RunTutorial(json,.f.)

dim item as c
dim items as c = <<%str%
One
Two
%str%

ui_dlg_box("test",<<%dlg% {where=/Test}
[.80,20item^#items];
<Add!add><Close!close>;
%dlg%,<<%code%
if a_dlg_button = "add" then
	a_dlg_button = ""
	 items = alltrim(items) + crlf() + str(line_count(items)+1,200,0,"XF")
end if
%code%)

 Example of using Xbasic expressions to Validate and Skip

If the validation or skip rules provided are not enough, there are two rules that call into xbasic that allow for arbitrarily complex validation.

The following script demonstrates a Validation rule and a Skip rule that are bound to two logical variables maintained by the example xdialog.

dim json as c = <<%json%
{
    "actions": [
        {
            "action": "buttonClick",
            "name": "Add",
            "where": "/Test/button/Add",
            "message": "Click Add button.",
            "step": 2,
            "continue" : true , 
            "validateEval" : "ui_dlg_eval(<dlgtitle>,\"valid\")"
        },
        {
            "action": "buttonClick",
            "name": "Optional",
            "where": "/Test/button/Optional",
            "message": "Click Optional button.",
            "step": 3, 
            "skipEval" : "ui_dlg_eval(<dlgtitle>,\".not. require_optional\")"
        },
        {
            "action": "buttonClick",
            "name": "Close",
            "where": "/Test/button/Close",
            "message": "Click Close button.",
            "step": 4
        }
    ]
}
%json%
dim uxa as WindowManager::UxAutomation
uxa.RunTutorial(json,.f.)

dim item as c
dim valid as l = .f.
dim require_optional as l = .f.
dim items as c = <<%str%
One
Two
%str%

ui_dlg_box("test",<<%dlg% {where=/Test}
[.80,20item^#items];
(valid!state_change) Its valid;
(require_optional!state_change) Require Optional Step;
<Add!add><Optional!optional><Close!close>;
%dlg%,<<%code%
if a_dlg_button = "add" then
	a_dlg_button = ""
	 items = alltrim(items) + crlf() + str(line_count(items)+1,200,0,"XF")
else if a_dlg_button = "optional" then
	a_dlg_button = ""
	ui_msg_box("optional step","clicking on this button is optional")
else if a_dlg_button = "state_change" then
	a_dlg_button = ""
end if
%code%)