Frequently asked questions for self help.

Knowledge base article 95

How to use Programmable Forms

"Forms" are used in conjunction with macros so you can provide a custom user interface for your macro program. Here's how to create a simple form in Write:

Stage 1 - create the new form

1. Start Write and Select Tools/Forms Editor
2. Click on the "+" next to "Ability Write" and select "Global" (or you could select the current document).
3. Click on the "Add New" button.
4. Close the form manager dialog.

Stage 2 - edit the form

1. Right click over the form and select Properties.
2. Change the default name "Untitled" to "My Form" - click on "Title" enter "My Form" in the edit box and click Apply.
3. Close the Properties dialog.
4. Select the "AbilityButton" tool from the toolbox.
5. Drag the shape of the button on the form to create a new button.
6. Right-click over the new button and select "AbilityButton1" properties.
7. Set the caption to "Close" and OK the dialog.
8. Right-click over the button and select "ActiveScript"
9. From the Events drop-down, select "Click"
10. In the new function (the event handler for the button), enter the macro code to close a form:


11. Save the Form (use the Save button) and switch to the Write Window (leave the forms program running for now).

Stage 3 - write a macro to call the form

1. Select Tools/Macros and create a new macro, e.g. call it TestForms
2. Add the following code to display the Form:

Forms.ShowForm("My Form")

3. Run the macro to display the dialog (e.g. Right-click over macro code and select "Run").

Next steps 1 - Get data from a form

1. Go back to the forms editor and select View/Active Objects (or click on the "VB" button to toggle between script and design modes)
2. Select the "AbilityEditBox" tool from the toolbox and draw an edit box on the form.
3. Select View/Active Script and add the following line to the close button function so it looks like this:

Retval.Var("EditText") = AbilityEditBox2.Text

Note that "AbilityEditBox2" is the default ID for the edit box since it was the second control placed on the form - you can change this if you want to (right-click over edit box and select Properties).

4. Return to the Write macro and add an extra line so it looks like this:

Forms.ShowForm("My Form")
MsgBox ReturnVal.Var("EditText")

5. Run the macro, type something into the Edit box and select Close.

What's happening? The macro shows the form, the user interacts with the form and when the form is closed, a "special" variable called "EditText" is created to hold the value of the edit box. This is then referenced by the Write macro. You can make as many of these special variables as you want to pass data from a form to the main macro.

Next steps 2 - Investigate the other tools and events

All the other control types and events work in the same way as described as above. You can create complex and forms and put the bulk of the macro code in the actual form as well.