Xbasic Action Scripting

Description

An Alpha Anywhere User Guide to the Desktop.

Name
Description
Action Commenting

In the Action Scripting Editor you may add, delete, and edit comments attached to your action scripts. When you select an action, it is highlighted with light purple.

Script Modes - Action Scripting

This page looks at the Standard, Local, and Spawn modes that are used to run a script.

Script Recorder

The Script Recorder records your actions as you use Alpha Anywhere and it writes the Xbasic code that corresponds to your actions. Not every action that you perform interactively with Alpha Anywhere is recorded, but most actions are recorded. It is an excellent way to learn Xbasic.

Activate an Object

The Activate an Object action gives focus to an object in an open window. This is a useful action for guiding the user, as well as for repetitive data entry. Performing an activate action multiple times on a form allows you to step a user through a process, giving focus to subsequent required fields so that the user does not need to tab or click to get to necessary fields.

Activate Window

The Activate Window action sets focus to a window. You can must have the window open to select it.

Add Text to Memo Field

The Add Text to Memo Field action adds text at any location in a memo field. You can also insert new lines before or after the inserted text.

Add Text to RTF Memo Field

The Add Text to RTF Memo Field action adds text at any location in an RTF memo field. You may specify the font, style, size, and color. You can also insert new lines before or after the inserted text.

Allow Edits

The Allow Edits action allows the user to enter and edit records in the current or another specified form. This action is needed to edit records if a previous action disallowed edits, or if a form's data entry style is set to modal. If the data entry style is set to modal, then edits will be disallowed again after the record is saved.

Archive a Layout

The Archive a Layout action allows you to print, preview, email, or save a layout in a variety of formats.

Attaching Scripts to Events

With the exception of Global Scripts, which can be run directly by the user, Xbasic scripts cannot be run directly. Rather, they are run automatically in response to various events (such as Pressing a button, saving a record, deleting a record etc. ) that occur when you are using Alpha Anywhere. Xbasic scripts are "attached" to events, and are run when the event occurs. For example, a script might be attached to the OnActivate event for a control on a form. When that control gets focus, the script is automatically run. To attach a script to an object event:

Branch Command

The Branch Command Action can be used to change the execution of your script based on an expression or the value of a control. Note that this action references an open form or browse.

Cancel Changes

The Cancel Changes action removes all edits made to the current record. Use this action as an "escape" method to prevent accidental changes to a record.

Cancel Event

The Cancel Event action cancels a form event if a condition is not met.

Close Window

The Close Window action closes a window. You can must have the window open to select it.

Compiling Scripts and Functions

Alpha Anywhere lets you compile your scripts and functions into a Compiled Script Library. The Compiled Script Library is a file with an .AEX extension.

Control Panel

An Alpha Anywhere User Guide to the Desktop.

Creating and Programming a Hotspot with Action Scripting

The following procedure assumes that the developer has opened the form in the Form Editor . Follow these instructions to use Action Scripting to create and format a hotspot similar to hotspot4 .

Creating Custom Action Scripts

While the Pre-Defined buttons are useful, they will not satisfy all your customization needs. You will need more elaborate, multi-step scripts that are executed when a user clicks a button on a form. This example creates a button that saves the current record, puts the form into Enter mode for entering a new record, sets the Bill_Country field default value to "United States," and then gives focus to the Firstname field, where the user can continue entering data for the new record.

Database

An Alpha Anywhere User Guide to the Desktop.

Dim Variables

The Dim Variables action identifies variables dimensioned outside the current action script. For example, this action would be useful in the case where you are defining a filter for a record list control on an Xdialog and your filter references a variable that was previously defined.

Disable Object(s)

The Disable Object(s) action renders objects unable to receive focus. A user cannot switch focus to a disabled object. This action, when used with the Enable Object(s) action, is useful when either user interaction is required for accessing objects, or user interaction indicates that specific objects are unimportant/important for the task at hand. In either case, use the Disable Object action to restrict objects from receiving focus, and use Enable Object to allow focus.

Disable Window

The Disable Window action makes a window unable to receive focus. You can must have the window open to select it.

Display 'Manage Script Favorites' Dialog

The Display 'Manage Script Favorites' Dialog action displays the Manage Script Favorites dialog box that allows you to edit your list of favorite scripts. Each form or browse layout has its own list of favorite scripts.

Display a Message Box

The Display a Message Box action automates the process of creating message boxes. Message boxes are a great way to communicate with users, allowing them to accomplish tasks using a simple, specialized interface for the task at hand.

Display a Pick-List of Scripts

The Display a Pick-List of Scripts action displays a pick-list dialog box, pop-up list, or toolbar of pre-written scripts. The pick-list can have a variety of options, depending on the style of pick-list you choose.

Display Script Favorites Pick-list

The Display Script Favorites Pick-list action displays script favorites in the Select Script to Run dialog box, toolbar, or pop-up menu.

Enable Object(s)

The Enable Object(s) action allows previously disabled objects to receive focus. This action, when used with the Disable Object(s) action, is useful when either user interaction is required for accessing objects, or user interaction indicates that specific objects are unimportant/important for the task at hand. In either case, use the Disable Object action to restrict objects from receiving focus, and use Enable Object to allow focus.

Enable Window

The Enable Window action makes a window able to receive focus. You can must have the window open to select it.

End Script

The End Script action ends the current script. You do not need to enter this at the end of every script. It is used to terminate a script as the result of a branch or condition.

Exit Alpha Anywhere

The Exit Alpha Anywhere action closes all open tables and stops the Alpha Anywhere application.

Exporting and Importing Scripts and Functions

You can share scripts or transfer them to other databases by exporting and importing them.

Field

An Alpha Anywhere User Guide to the Desktop.

Find by Key - Action Scripting

The Find by Key action searches for records matching a specified key value using the Find by Key dialog. This action gives you the option to specify the key to search for in advance, or prompt the user at run-time.

Find by Key Dialog (Custom)

The Find by Key Dialog (Custom) action displays the Find by Key dialog. It allows you to customize the settings of the dialog or leave them up to the user.

Find by Key Dialog (Standard)

The Find by Key Dialog (Standard) action displays the Find by Key dialog.

Finding and Replacing in Scripts and Functions

The Edit > Find , Edit > Find and Replace , and Edit > Goto features let you search an entire script or just selected text. You can search forward or backward, for whole words, and with case sensitivity.

Forms

An Alpha Anywhere User Guide to the Desktop.

Get 'Text' Property of Object(s)

The Get 'Text' Property of Object(s) action retrieves the 'Text' property of one or more object(s) on a form or browse.

Get 'Value' Property of Object(s)

The Get 'Value' Property of Object(s) action retrieves the 'Value' property of one or more object(s) on a form or browse.

Get Field Values (into Variables)

The Get Field Values (into Variables) action retrieves the "Value" properties of object(s) on a form or browse into variables.

Get Properties of Object(s)

The Get Properties of Object(s) action retrieves specified properties of one or more object(s) on a form or browse.

Goto Label

The Goto Label Action causes your script to start executing at a label created with the Insert Label Action.

Hide Object(s)

The Hide Object(s) action hides objects on a window. When the action is performed, the selected objects are removed from sight. This action is contextually useful in order to remove unnecessary objects (as dictated through user interaction) from sight. You can see this action in use throughout Alpha Anywhere, including the Script Genie, as Alpha will often hide entry fields depending on the choices you made previously.

Hide Window

The Hide Window action hides a window. Choose to hide the current window, or another Form or Browse window. The window remains hidden until a Show Window action runs.

Home Page

The Home Page action assists you in building a startup form that can be used�as�a main menu for your application.

How to Use Branches in Your Scripts

A Branch Action allows your script to execute different actions depending on the outcome of a test. To perform the test, Alpha Anywhere evaluates an expression (the "branch expression"), or checks the value in a control on the form. For example, if the value of the branch expression is "Boston", you might want your script to print a report for your Boston customers, while if the value of the branch expression is "New York", you might want your script to print a report for your New York customers.

Inline Xbasic

The Inline Xbasic action inserts Xbasic into a script. This should only be used if you know how to use Xbasic. The window that pops up is a Code Editor window with standard features such�as�bubble help, code completion, and syntax checking.

Insert Label

The Insert Label Action inserts a label in the list of actions. You can later use the Goto Label Action to jump to it. When used with conditions, this Action can be used to create a loop. This action should not be used for simple conditions. Action Scripting's built-in condition handling is much simpler and easier to use.

Introduction to Action Scripting (Desktop)

Action Scripting is a visual way for creating scripts in Alpha Anywhere desktop applications. In this guide, you'll learn about Action Scripting and how to use it in your desktop apps.

Locate Text

The Locate Text action finds text in a form or browse using the Locate Text dialog. You can look for text in a specific field or all fields in that window. This is most often used to find the correct record to edit or display

Locate Text Dialog

The Locate Text Dialog action displays the Locate Text dialog that allows the reader to search for text.

Maximize Main Alpha Anywhere Window

The Maximize Main Alpha Anywhere Window action maximizes the top-level Alpha Anywhere window so that it fills the entire screen.

Maximize Window

The Maximize Window action maximizes a window so that it covers the entire screen. Choose to maximize the current window, or another Form or Browse window.

Minimize Main Alpha Anywhere Window

The Minimize Main Alpha Anywhere Window action minimizes the top-level Alpha Anywhere window so that it does not appear on the screen.

Minimize Window

The Minimize Window action minimizes a window so that it does not appear on the screen. Choose to minimize the current window, or another Form or Browse window.

Multi-Select Dialog Alternatives

If you want to present a user with a list of options that allows multiple selections, the following alternatives are easy to implement. Both alternatives are variations of a single design and both assume that you can subsequently use a character list of the selected options.

Navigator

The Navigator action displays a small, modeless, pop-up window which allows users to quickly give focus to a particular field on a form. The Navigator is helpful on larger forms with many fields.

Open a Non-Alpha Anywhere File

The Open a Non-Alpha Anywhere File action opens a file with its Windows associated application. For example, specifying a .XLS file causes Microsoft Excel to run and specifying a .DOC file causes Microsoft Word to run.

Play a Sound

The Play a Sound action plays a specified .WAV sound file.

Position Window

The Position Window action sets the location of a window.

Preview a Layout

The Preview a Layout action allows you to print, preview, email, save, or fax a layout in a variety of formats.

Print a Layout

The Print a Layout action allows you to print, preview, email, or save a layout in a variety of formats.

Query by Expression - Action Scripting

The Query by Expression action displays the Query by Expression dialog, which allows the user to enter a character filter expression that selects records and a character order expression that sequences the selected records. This provides users with an extremely easy and flexible method of creating ad-hoc expression-based queries at run-time.

Query by Genie

The Query by Genie action displays the Query Genie, allowing the user to enter criteria to search the records in a table. The user specifies the filter and order at run-time.

Quick Dialog

The Quick Dialog action displays a selection dialog box in any of three styles, using radio buttons, a tree control, or a list box.

Quick Dialog Example

How to create a quick dialog.

Quick Export to Excel - Action Scripting

The Quick Export to Excel action exports the current selection of records to Excel and opens Excel with the records loaded into a new worksheet. All data in the current Form or Browse window is exported, and the column order in Excel corresponds to the field order on the form or browse layout. If you want more control over which fields are exported and in which order, try using an Export Operation instead.

Quick Filter

The Quick Filter action filters records in a window based on the value in the control that currently has focus, or on another explicitly specified control. If you choose to specify the control, Alpha Anywhere will always perform the filter on that value, regardless of which field might actually have focus.

Quick Sort

The Quick Sort action sorts the records in a window, based on the control that currently has focus, or on another explicitly specified control. For instance, if you specify this sort operation to sort on the lastname field, the action will always sort on the lastname field, regardless of focus. You may also specify that the operation should sort based on the field with focus. This leaves the operation more open-ended, allowing the quick sort action to run on whichever field the user gives focus to.

Desktop Records Guides

An Alpha Anywhere User Guide to the Desktop.

Refresh Display

The Refresh Display action refreshes all the data displayed in the current or another specified window. If the window is displaying a query result, the query is updated. The action cannot be performed if the form or browse is in Change or Enter mode.

Refresh Objects

The Refresh Object(s) action refreshes the displayed contents of one or more objects.

Restore Main Alpha Anywhere Window

The Restore Main Alpha Anywhere Window action restores the Alpha Anywhere window to its previous size.

Restore Window

The Restore Window action restores the a window to its previous size. Choose to restore the current window, or another Form or Browse window.

Run a Script

The Run a Script action runs an Xbasic script.

Run Another Program

The Run Another Program action executes another program outside of Alpha Anywhere. You can specify the program to run now or prompt the user at run-time.

Run Custom Query

The Run Custom Query action queries records based on custom filter and order expressions. This query can include parameters prompted for at run-time. If you choose to prompt for parameters at run-time, you can customize the prompts, title, and buttons on the parameters dialog.

Run One-Step Backup

The Run One-Step Backup action runs a previously saved One-Step backup operation, created with the Backup Database dialog.

Run Saved Query

The Run Saved Query action sorts records in a window based on search and sort criteria in a previously saved query operation.

Running a Script

When you run a script you can choose one of three ways in which the script is run:

Save a Layout to a File

The Save Layout to a File action allows you to print, preview, email, or save a layout in a variety of formats.

Save Record

The Save Record action allows the user to save any changes to the current record in a specified window.

Script Modes

This page describes the Standard, Local, and Spawn modes used to run a script.

Select Action From the Control Panel

The Select Action From the Control Panel action allows an object to run one of the actions listed in the Control Panel 's menu.

Select Action From the Form Menu

The Select Action From the Form Menu action allows an object to run one of the actions listed in the form's menu.

Select Index Dialog

The Select Index Dialog action displays the Primary Index or Query dialog, from which the user may select the primary index or query list for the current form or browse. The primary index controls which records are viewed, and in what order.

Send a Layout via E-mail

The Send a Layout via Email action allows you to print, preview, email, or save a layout in a variety of formats.

Send Keys

The Send Keys action specifies keystrokes to send to Alpha Anywhere or another application. Immediately before the Send Keys action to set focus? to the window and/or object to which you want to send keystrokes.

Set 'Text' Property of Object(s)

The Set 'Text' Property of Object(s) action sets the text that is displayed by one or more objects.

Set 'Value' Property of Object(s)

The Set 'Value' Property of Object(s) action sets the 'Value' property of one or more object(s) on a form or browse.

Set Border Style of Object(s)

The Set Border Style of Object(s) action sets the border attributes of one or more objects.

Set Fill Style of Object(s)

The Set Fill Style of Object(s) action sets the fill properties of one or more objects.

Set Font Property of Object(s)

The Set 'Font' Property of Object(s) action sets font attributes (face, point size, etc.) of one or more field, text or button objects.

Set Modeless Data Entry Style

The Set Modeless Data Entry Style action changes data entry style of a specified Form/Browse to Modeless.

Set Properties of Objects

The Set Properties of Object(s) action sets specified properties of one or more field, text or button objects.

Set Record Number Order

The Set Record Number Order action sets the primary index for a form or browse to record number order. The primary index controls which records are viewed, and in what order.

Set the Values of One or More Variables

The Set the Values of One or More Variables action creates one or more variables. It also sets the value of multiple new or existing variables.

Set Variable(s) to Form/Browse Window Info

The Set Variable(s) to Form/Browse Window Info action retrieves various kinds of information about a window.

Set Variable(s) to Object 'Text' Property

The Set Variable(s) to Object 'Text' Property action retrieves text properties of one or more object(s) on a form or browse.

Set Variable(s) to Object Properties

The Set Variable(s) to Object Properties action retrieves the values of properties of object(s) on a form or browse.

Set Z-Order of Window

The Set Z-Order of Window action moves a window to the top or bottom of the stack of visible windows or underneath a specified window. Choose to show the current window, or another Form or Browse window.

Show Object(s)

The Show Object(s) action reveals objects previously hidden in a window. This action is contextually useful in order to reveal pertinent objects (as dictated through user interaction). You can see this action in use throughout Alpha Anywhere, including the Script Genie, as Alpha will often reveal entry fields depending on the choices you made previously.

Show Window

The Show Window action shows a previously hidden window. Choose to show the current window, or another Form or Browse window.

Storing Scripts in a Library

By default, Alpha Anywhere stores all Global Scripts, Global Functions, Custom Menus, and Custom Toolbars in the current database's Library. The Library files have the same name as the database (i.e. the .adb file) with the .alb, .alm and . alx file extensions.

Swap Form in Window

The Swap Form in Window action opens a different form for the current record in a new window. You can specify the target form in advance or prompt the user at run-time. A swap action differs from an open action in that the target form must be from the same table or set. The target form displays the focused record and closes the source form.

Switch to Another (non-Alpha Anywhere) Window

The Switch to Another (non-Alpha Anywhere) Window action sets focus to another non-Alpha Anywhere window. If you want to send keystrokes to the target window after it gets focus, use the Send Keys action.

Desktop Tables

An Alpha Anywhere User Guide to the Desktop.

Toggle Form or Browse Mode

The Toggle Form or Browse Mode action switches between the form and browse views of a table or set.

Turn Hourglass Off

The Turn Hourglass Off action changes the cursor back to normal after you have turned it into an hourglass with the Turn Hourglass On action.

Turn Hourglass On

The Turn Hourglass On action changes the cursor into an hourglass. The user will not be able to do anything in Alpha Five until you reset their cursor with the Turn Hourglass Off action.

Un-Mark Record

The Un-Mark Record action allows the user to un-mark the current record.

Update Indexes

The Update Indexes action updates the indexes for specified tables.

Using Compiled Script Libraries

There are three different ways in which you might use .AEX files:

Wait Dialog - Close

The Wait Dialog - Close action closes a wait dialog started by a Wait Dialog - Open action.

Wait Dialog - Open

The Wait Dialog - Open action displays a wait dialog that is used to indicate the progress of a long running process.

Wait Dialog - Set Percentage

The Wait Dialog - Set Percentage action is used with a Wait Dialog - Open action of style "Percent" to indicate the progress of a process.

Wait for Idle

The Wait for Idle action pauses the script until the user interface has finished painting.

Xbasic Debugger Off

The Xbasic Debugger Off action disables debugging of Xbasic code. If necessary, consult the Alpha Anywhere User Guide for more information about the Debugger utility.

Xbasic Debugger On

The Xbasic Debugger On action enables debugging of Xbasic code. If necessary, consult Turning on the Debugger for more information about the Debugger utility.

Xbasic Enter Record

The Xbasic Enter Record action adds a record without opening a form or browse. The user never has to be aware that changes were made.

Xbasic Explorer

The Xbasic Explorer is an extremely useful tool when you are writing code in the Code Editor, or experimenting with code in the Interactive window. It is a complete reference of all of the commands, functions, methods, properties and constants in the Xbasic language. It also shows you all of the current objects that exist, all global variables that you have created, and all Global Functions that you have defined.

Xbasic Script Genie

The Xbasic Script Genie generates the Xbasic code associated with the library of Action Scripting actions. The result of the process is code that is ready to be copied and pasted into your script or function. To use the Xbasic Script Genie :