Automatic Form Construction
If you were going to construct a nice form like this one object at a time, it would take quite a while. There are 28 objects in this form, it would be quite tedious to set each one up one by one by one.

Fortunately, you don’t have to set these objects up one by one. Panorama includes a form constructor tool that can make a complete form like this in a minute or two. Let’s take a look at how it works. To illustrate this, I’ll use a customer list database with 14 fields.

I’ll start with a new blank form (see Creating a New Form). To automatically create a form with a Text Editor Object for every field, I choose Fields and Variables from the Construct menu. This opens a dialog sheet that lists all of the fields in the database. If I wanted to omit some fields I could edit them out of the list, since I want all of the objects I simply press the Construct button. Panorama automatically creates 14 text editor objects, along with 14 text display objects with captions.

That’s it – the form is done! You can switch to data entry mode and start displaying and editing data immediately.

#### Customizing the Automatically Generated Form

You can, of course, manually modify the form objects after they have been generated. But you can also modify the template and regenerate the form. For example, it might be nice if the Notes field was more than one line high. I can make it 5 lines high by adding the tag `<lines:5>` after the field name. Pressing the Construct button regenerates the form objects with the taller Notes field.

As long as you don’t modify the generated objects individually, you can go back and make additional modifications to the template at any time.

In addition to text editor objects, the template can also be used to construct checkboxes, radio buttons, pop-up menus, and scrolling list. In this example the Undeliverable field is changed to a checkbox. (The on value for the checkbox is `YES`.)

#### Constructor Tag Help Menu

There are about two dozen tags that you can use to customize the generated form objects. There is complete documentation for all of these tags below, but if you just need a quick reminder while using the dialog, click the tag in the upper left. This displays a pop-up menu with all the available tags. When you select a tag from the menu, that tag is automatically typed into the template. In this example I use the tag menu to change the Children text editor into a pop-up menu.

#### Manually Modifying Generated Objects

Once they are generated, you can manually modify individual objects by dragging them, resizing them, or using the object properties panel to modify their appearance and operation. Once you do that, however, you probably want to avoid running the constructor dialog again – doing so will undo any manual changes you have made.

However, you can move all the generated objects to a new position in the form, as long as you do so to the entire set. You can even add other objects to the form. These additional objects will be ignored if you re-run the constructor – they won’t be touched. Watch this movie carefully as multiple steps are performed:

- The previously generated objects are selected as a set and moved down a bit in the form to make room at the top.
- A logo image is dragged onto the top of the form and the position adjusted.
- The Constructor dialog sheet is opened, and the temmplate is edited to remove the label from the Undeliverable checkbox.
- The automatically constructed objects are regenerated. Notice that the logo image is not touched, and the objects are generated in the new position.

#### Using Two Templates in a Single Form

You may want to generate objects using more than one template in a single form – however, you can’t do that. But all is not lost – simply create each template in a different form, and then copy the finished results into the same form. Each form has its own separate constructor template.

#### Tag Language Reference

The template parameter allows you to customize how form elements are generated. You can specify which fields (or variables) are included, the size, alignment, etc. Each item can have tags that customize the generated object, and there are tags for overall options as well. The remainder of this page describes the details of the available tags

#### Fields & Variables

To specify which fields (or variables) should be included in the generated form, simply include a carriage return delimited list of the fields and/or variables. This example will generate 5 text editor objects, for the Name, Address, City, State and Zip fields.

If you want to edit a variable, just type in the name of the variable. If you want to edit a field name, make sure you spell it correctly, otherwise a variable will be automatically created instead.

#### Tags

To customize the generated form objects you can include one or more tags. Like HTML tags, these tags start and end with `<` and `>` characters. Some tags need to be attached to a specific field or variable, for example to specify generating a pop-up menu, checkbox, radio button etc. instead of a regular text editors, or to specify min and max values for a field or variable. Other tags should be placed at the top of the and control overall specifications – for example the font and text size. If you are creating a dialog, the constructor can even generate the buttons for you.

#### Checkboxes

Use the `<checkbox:value>` or `<check:value>` tag to generate a checkbox. The tag should be on the same line as the field or variable name. This example generates the same 5 text editor objects as the previous example, plus a checkbox for the Rush field (or variable).

As you can see, the on value of the checkbox is specified after the colon (the off value is always blank). If you don’t specify the on value it defaults to `"TRUE"`. Here is the form generated by this template:

#### Checkbox Groups

If the checkbox tag has multiple values, a group of checkboxes will be created. Unlike a group of radio buttons, this allows multiple values to be checked.

Here is the form generated by this template:

If multiple values are checked, the values will be separated by a separator character (or characters). The default separator character is a carriage return, but you can use the `<separator:text>` tag to specify any separator text you want.

The checkboxes are normally arranged vertically, but if the `<across>` tag is included on the same line they will be arranged horizontally.

Note that if checkboxes are arranged horizontally, the widths will be approximate, as seen here.

You will probably have to manually adjust the arrangement a bit for the best appearance.

#### Pop Up Menus

Use the `<popup:value,value,value>` or `<menu:value,value,value>` tag to generate a popup menu. The tag should be on the same line as the field or variable name. This example adds a pop-up menu for the credit card type.

Here is what this form will look like:

As shown in the example above, the `<popup>` tag includes a comma separated list of the items to appear in the pop-up menu. If you need to include a comma in a menu item you can specify the items with separate `<value>` tags, described below.

#### Radio Buttons

Use the `<radio:value,value,value>` tag to generate a group of radio buttons. The tag should be on the same line as the field or variable name. This example adds a text list for the credit card type.

The radio buttons are normally arranged vertically, with one radio button per line.

If you want to arrange the radio buttons horizontally, use the `<across>` tag, like this:

    Card<radio:Master Card,Visa,American Express,Discover><across>

Note that if radio buttons are arranged horizontally, the widths will be approximate. You will probably have to manually adjust the arrangement a bit for the best appearance.

As shown in the examples above, the `<radio>` tag includes a comma separated list of the items to appear in the pop-up menu. If you need to include a comma in a menu item you can specify the items with separate `<value>` tags, described below.

#### List

Use the `<list:value,value,value>` tag to generate a list. The tag should be on the same line as the field or variable name. This example adds a text list for the credit card type.

Here is the form generated from this template:

As shown in the example above, the tag includes a comma separated list of the items to appear in the pop-up menu. If you need to include a comma in a menu item you can specify the items with separate `<value>` tags, described below.

Lists default to six lines high. If there are more than six items in the list, you can scroll the list. You can also change the generated height of the list with the `<lines>` tag, described below.

#### Values with Commas

If you need to include values with commas with the `<popup>`, `<radio>`, or `<list>` tags you can specify the values in separate tags, like this:

This example generates a text list object with three choices, all of which contain commas.

When you use the `<value>` tag, you should not include a value in the primary object tag itself.

#### Width

To customize the width of a single text editor, popup button or list object use the `<width:dimension>` tag. The width is normally expressed in points (1 point = 1/72 inch) but you can also specify values in inches (`1 in` or `2.5 inch` or `0.75"`) or centimeters (`20 cm`).

The `<width>` tag only overrides the width for the line it is on.

For all objects without an explicitly set width, the width is set automatically (see Geometry section below to learn how to set the width for all objects).

#### Height

To change the height of a text editor or list object, use the `<lines:count>` tag. In this example all the fields will be one line high except for the Address field, which will be three lines high.

Here is the result:

The height doesn’t have to be an integer number of lines, but it does have to be at least 1. If the height is more than 2 lines high, a vertical scroll bar will be included in the editor object (of course you can manually remove it at any time).

Objects generated by the `<list>` tag are normally six lines high, but you can set the height to anything you want.

#### Numeric Values

The `<step>`, `<min>` and `<max>` tags customize text editor objects for numeric values. Use the `<step>` tag to automatically generate a stepper object to the right of the text editor:

Watch the resulting form in action:

The step value is normally 1, but you can set it to any numeric value. In this example, the stepper will increment or decrement the price by a nickel each time it is clicked.

Here is this stepper in action.

If you set a maximum value, a slider object will also be generated. In this example, the slider can be used to adjust the quantity from 0 to 12.

The slider appears to the right of the text editor object (and the stepper, if there is one).

In the movie above you may notice that the slide goes to zero. If you don’t want that, you can also set a minimum value, in this case, a minimum of one, not zero.

Note: Setting a minimum and maximum doesn’t prevent values larger or smaller than this from being typed into the text editor. If that is necessary, you would need to add additional programming.

#### Field/Variable Label

Each field or variable has a label to the left of it. Normally the text of this label is the same as the field or variable name, but you can specify different text with the `<label:text>` tag, as shown below. Note that when you specify a custom label, you must include any punctuation before or after the label text (in this example colons).

Now the first two labels are custom, instead of the actual field names.

You can also eliminate the label entirely by changing it to a single space.

Label Suffix Normally each label has a colon added as a suffix, but you can change the suffix (`<labelsuffix:value>`), and also add a prefix if you like (`<labelprefix:value>`).

Here is the custom prefix.

Note: The custom prefix and suffix are not added when you specify a custom label with the `<label:text>` tag.

#### Prompts

You can optionally specify that a prompt will appear when a field or variable being edited is empty. The prompt appears in gray text, and disappears as soon as the first character is entered into the field or variable. Use the `<prompt:text>` tag to specify a prompt for each line.

The prompt appears when the field or variable is empty, and disappears as soon as the first character is typed.

If you put an `<autoprompt>` tag at the top, the field or variable name will automatically be used as the prompt (unless a prompt is explicitly specified). The example below will produce exactly the same form objects as the example above. In this example, the prompts for the Description and Price fields are generated automatically.

Note: It’s rarely necessary, but you can also enable and disable automatic prompts by using `<autoprompt:yes>` and `<autoprompt:no>`.

#### Push Buttons

To generate one or more push buttons on a row, use the `<button:title>` or `<buttons:title,title>` tags. You can create multiple buttons either with multiple `<button>` tags or with a single `<buttons>` tag (in which case the button name are separated by commas).

The button is generated on a separate line:

The tag can also specify the button width and any code associated with the button, like this:

    <button:title:width:code>
    <buttons:title:width:code,title:width:code,title:width:code>

The width is normally specified in points, but can also be specified in inches or centimeters. Here is an example with two buttons that have custom width and code.

When multiple buttons are defined on the same line in the template like this, they are generated on the same line in the form.

#### Code

The `code:text>` tag defines procedure code for text editor, data button and pop-up menus. If the tag is on the same row as one of these objects, that object will use the specified code.

    Quantity<code:call adjustQTY>
    Description
    Price<code:call adjustPRICE>

If the `<code>` tag is on a line with no object on it, that code will be used for all following objects. In this example, the subroutine `logUpdate` will be called when any of the fields are modified.

    <code:call logUpdate>
    Quantity
    Description
    Price"

You can change the code at different points, or use `<code:>` to completely eliminate the code for additional objects.

#### Tooltips (Help)

The `<help>` tag defines a tooltip for the current row.

In data mode, the tooltip text will appear when the mouse hovers over this row.

#### Font and Size

You can change both the font and size of generated objects. Changing the size is more common, to do that use the `<size:points>` tag. Normally you would do this just once at the top. This example will generate text objects with text that is 1/3rd inch high (24 points)

Oh my, that text is big!

You can also specify that the size is regular (13 points), small (11 points) or mini (10 points). Note: Some objects, including checkboxes, radio buttons, and pop-up menus, can only be generated in these three sizes. You can’t make a 24 point checkbox, for example. You can, however, specify these three sizes either numerically or by their names (regular/small/mini).

This produces a nice and compact layout:

Use the `<font:name>` tag to change the font. If this tag is omitted, the system font will be used.

Here is the form with the custom font:

#### Geometry

The tags in this section allow you to change how generated objects are laid out. All of the tags in this section include measurement values. These values are normally expressed in points (1 point = 1/72 inch) but you can also specify values in inches (`1 in` or `2.5 inch` or `0.75"`) or centimeters (`20 cm`).

First up is `<spacing:distance>`. This specifies how far apart the objects are. The default is 2 points, but you can set it to larger or smaller values (even 0, though you probably don’t want to do that. This example spaces the objects 1/12th inch (6 points) apart.

You can see the extra spacing between the objects.

The `<fieldwidth:distance>` tag specifies how wide each text editor object should be. The default is 200 points (just under 3 inches). If the `<variablewidth>` tag is included, the field widths will vary, corresponding to the widths in the data sheet. The `<labelwidth:distance>` tag specifies how wide the labels on the left side are. The default is 120 points.

Here is the result:

The new objects are normally generated starting from 1/2 inch below and to the right of the top left corner of the form, but you can change this to any location. This example starts generating the objects starting at 1 centimeter from the top, and 15 centimeters from the left edge of the form.

    <top:1 cm><left:15 cm>
    Name
    Address
    City
    State
    Zip

Note: Explicitly specifying the position disables the auto-placement feature that allows you to move generated objects, then regenerate them and have them stay in the new position. Because of this, you’ll usually not want to explicitly set the position with these tags.

#### Field/Variable Prefix

Sometimes the names of your fields or variables may have a prefix that you don’t want included in the labels. For example, suppose your field names are SubscriberName, SubscriberAddress, etc., and you just want the labels to be Name, Address, etc. You can use the `<prefix>` tag to generate this.

    <prefix:Subscriber>"+cr()+
    Name
    Address
    City
    State
    Zip

#### Constructing Objects for a Dialog

If you are creating a dialog, use the `<dialog>` tag. This automatically generates Ok and Cancel buttons, and also adds the code necessary for proper dialog operation. If Ok/Cancel are not the buttons you need, you can include a comma separated list of buttons in the tag, like this,

    <Dialog:New Subscriber,Cancel>
    Name
    Address
    City
    State
    Zip

Buttons will be generated from right to left. You can have 1, 2, 3 or more buttons. You will probably need to adjust the width of the buttons after they are generated.

#### Removing Existing Form Objects

If the very first item in the template is the `<zapform>` tag, the form will be cleared before generating the new objects. Be careful with this tag – it will destroy everything in the form before adding the new objects!

Note: Even if you don’t include the `<zapform>` tag, this statement will clear any objects that were previously generated by this statement. In other words, even if you use this statement multiple times you’ll only end up with one set of generated objects.

#### Extra Tags

This statement will normally generate an error if it encounters tags that it doesn’t understand. However, if you put the `<ignoreunknowntags>` at the top of the template, unknown tags will be ignored. This can be handy if you want to create your own tags for other purposes.

#### Comments

You can include comments to yourself by starting a line with //. Note: Unlike Panorama procedures, you cannot start a comment in the middle of a line.

Comments are handy for temporarily disabling a line in the spec. Just put // at the beginning of the line and everything else in that line will be ignored.

See Also

- Aligning Objects
- Creating a New Form Object
- Data Button Object
- Duplicating Objects
- Fonts
- Form Object Appearance
- Grouping Objects
- info("clickedobjectname")
- Line Object
- Object Inspector Panel
- Object Library
- Oval Object
- Polygon Object
- Popup Menu Button Object
- Push Button Object
- Rectangle Object
- Rounded Rectangle Object
- Selecting Form Objects
- Smart Resize
- Star Object
- Text Display Object
- Text Editor Object
- Text Label Object
- Web Browser Object

History

Version | Status | Notes
1.0 | New | New in this version.