superchoicedialog
superchoicedialog
CHOICELIST
,
CHOICE
,
OPTIONS

The superchoicedialog statement will display a dialog with a list of choices that can be selected. You can control the size of the alert, as well as several appearance options. If the alert has more than one button, info(“dialogtrigger”) will contain the name of the button that was pressed.

Parameters

This statement has three parameters:

choicelist – List of choices to display (carriage return delimited array).

choice – Specifies a field or variable containing the choice. On entry, this field or variable should contain the current choice (if any). On exit this field or variable will be set to the selected choice if the Ok button is pressed.

options – This parameter may contain one or more options that alter the operation of the dialog. See the description below for more information.

Description

This statement will display a dialog with a list of choices that can be selected. You can control the size of the dialog, as well as several appearance options. If the dialog has more than one button, info(“dialogtrigger”) will contain the name of the button that was pressed. Here is an example of how this dialog can be used.

    superchoicedialog info("files"),targetDatabase,{height=50% width=4in buttons="Open;Cancel"}

The superchoicedialog statement allows you to display a wide variety of dialogs without having to do any graphics work at all. Of course if you need even more customization you can always create any style you want using a form and the rundialog statement.

#### SuperChoiceDialog Options

The third parameter of the superchoicedialog statement is a list of options. This list uses a syntax similar to an HTML tag to specify one or more options. Each option is specified as an option=value pair, for example `height=300`, `title="Enter Quantity"`, etc. Values aren’t required to be quoted unless they contain spaces or special punctuation characters. (Tip: If you enclose the entire option parameter in pipes, curly brackets or “smart quotes” you will be able to use regular " quotes for the individual options, if necessary.)

The sections below describe each of the available superchoicedialog options.

#### Height and Width

If you don’t specify otherwise, the dialog will be 70 points high and 500 points wide, but you can specify any dimensions you want. By default the dimensions are specified in points (one point = 1/72 inch). This example specifies an alert that is 2 inches high and 4 inches wide.

    superchoicedialog AveryList,Label,{height=200 width=400}

You can also specify the dimensions in inches (`"` or `in`) or centimeters (`cm`), or as a percentage. See the superalert statement for details.

#### Multiple Columns

If your list contains tab characters (chr(9)) it can be displayed as multiple columns.

Each column is identified by a separate `column=` tag. This example defines a table with 5 columns. Since no width or alignment is specified, defaults will be used.

    superchoicedialog Contacts,ChosenContact,{
        column=Name
        column=Address
        column=City
        column=State
        column="Zip Code"
    }

You can add tags for width and/or alignment. The only caveat is that if you add a width or alignment specification for any column, you must do it for all columns. This example will not work properly:

    superchoicedialog InventoryList,ChosenItem,{
        column=Item
        column="List Price" width=12 align=right
    }

By default, widths are expressed in characters. This is the approximate width needed to display a certain number of characters. Please keep in mind that this is approximate, and the exact number of characters that will fit depends on the characters and the font. The nice thing about specifying the width in characters, however, is that the width will adjust automatically if you change the font size.

If you want to specify the width precisely, you can use the `widthunits=` tag to set the width to points, inches, centimeters (or cm) or characters.

    superchoicedialog Contacts,ChosenContact,{
        widthunits=inches
        column=Name width="1.5"
        column=Address width="2.5"
        column=City width="2.0"
        column=State width="0.5"
        column="Zip Code" width="1.0"
    }

#### TABLE COLUMNS ALTERNATE NOTATION

An alternate notation is available that allows all of the columns to be specified in a single columns= tag. When using this tag, each column name is separated by a comma.

    superchoicedialog Contacts,ChosenContact,{
        columns="Name,Address,City,State,Zip Code"
    }

You can also add width and alignment options to each column (alignment may be c or center, or r or right). When using this alternate notation it’s ok to specify the width and/or alignment for some columns but not others (the default width is 10, left aligned).

    superchoicedialog Contacts,ChosenContact,{
        columns="Name:12, Street:18, City:15c,State:4c,Zip:6c"
    }

The widths are normally specified in characters, but you can use the `widthunits=` tag to choose other options (see above).

#### TABLE APPEARANCE

There are several tags that modify the appearance of the table.

TableHeader= This tag controls whether or not the column names are displayed at the top of the table. If column names are specified they are normally displayed, but you can turn this off with off, false or no.

    superchoicedialog Contacts,ChosenContact,{
        tableheader=off
        columns="Name:12, Street:18, City:15c,State:4c,Zip:6c"
    }

AlternatingColors= This tag controls whether or not the table rows are displayed in alternating colors (white and light gray). This is the default for multi-column tables, but you can turn this off with off, false or no. Single column tables are usually displayed with a white background, but you can turn on alternating colors with on, true or yes. (You might want to turn off alternating colors if you are displaying a grid, see below).

    superchoicedialog Contacts,ChosenContact,{
        alternatingcolors=off
        columns="Name:12, Street:18, City:15c,State:4c,Zip:6c"
    }

VerticalGrid= This tag can be used to enable a vertical grid line between columns.

HorizontalGrid= This tag can be used to enable a solid horizontal grid line between rows.

DashedGrid= This tag can be used to enable a dashed horizontal grid line between rows.

TableTextSize= This tag controls the text size of the table. The available choides are Small, Medium (the default) and Large.

    superchoicedialog Contacts,ChosenContact,{
        tabletextsize=small
        columns="Name:12, Street:18, City:15c,State:4c,Zip:6c"
    }

#### TABLE SCROLL BARS

The table always includes a vertical scroll bar, and normally also includes a horizontal scroll bar if there is more than one column. You can disable the horizontal scroll bar with the `horizontalscroll=` tag.

    superchoicedialog Contacts,ChosenContact,{
        horizontalscroll=off
        columns="Name:12, Street:18, City:15c,State:4c,Zip:6c"
    }

If you want low profile scroll bars, use the scroll=thin tag.

    superchoicedialog Contacts,ChosenContact,{
        scroll=thin
        columns="Name:12, Street:18, City:15c,State:4c,Zip:6c"
    }

#### TABLE SORTING

You can sort the data before you pass it to the table, but the table can also sort (and optionally deduplicate) the data for you.

Sort Setting this tag to on, true or yes tells Panorama to sort the table.

DeDuplicate Setting this tag to on, true or yes tells Panorama to sort and deduplicate the items in the table.

#### Title & Caption

Use the `title=` option if you want to display a title at the top of the dialog (in the title bar).

    superchoicedialog AveryList,Label,{title="Choose the type of label"}

Use the `caption=` option if you want to display a title just above the list (in the body of the dialog window, not in the title bar).

    superchoicedialog commatocr("MasterCard,Visa,AMEX,Discover"),CardNumber,
        {caption="Please select type of card"}

The caption is normally one line high, but you can make it bigger.

    superchoicedialog commatocr("MasterCard,Visa,AMEX,Discover"),CardNumber,
        {caption="Please select type of card
    (primary card)" captionheight=2}

You can also change the font, size and color of the caption.

    superchoicedialog AvailableCards,CardNumber,{caption="Please select type of card"
        captionfont="Palatino" captionsize=14 captioncolor="#999999"}

#### Selection Constraints

You can specify constraints on the minimum and maximum number of items that can selected (normally the minimum is zero and the maximum is one). To set the minimum number of selected items, use the `min=` option. This dialog requires that at least 3 people be selected for a team.

    superchoicedialog Employees,Team,{... min=3 ...}

If less than 3 people are selected, the dialog won’t let you press the Ok button. If you do, an error message will be displayed. You can customize the message that appears with the `toofewmessage=` option:

    superchoicedialog Employees,Team,
        {... min=3 toofewmessage="Team must have at least three members!" ...}

To set the maximum number of selected values, use the `max=` option.

    superchoicedialog Employees,Team,{ ...
        min=3 toofewmessage="Team must have at least three members!"
        max=7 toofewmessage="Team must have no more than seven members!"
        ... }

If the maximum is greater than one, the user can hold down the Command or Shift keys to click and select multiple values in the list. If the maximum is one (the default), then only one value can be selected at a time, no matter what keys are pressed.

#### Buttons

Use the `buttons=` option to specify up to three buttons (the default is: Ok and Cancel). Each button is separated by a semicolon, and the first button listed is the default button.

    superchoicedialog AvailableCards,CardType,{buttons="Add;Cancel"}
    if info("dialogtrigger")="Add"
        ... do something for add
    elseif info("dialogtrigger")="Cancel"
        ... do something for cancel
    endif

The buttons will be displayed in the bottom right corner of the alert. They are displayed in reverse order. In the example above, the Add button is on the far right and is the default button. The Cancel button is displayed to its left.

The default button width is 80 points, you can also specify a button width in points by placing a colon followed by the width after the button name.

    superchoicedialog AvailableCards,CardType,{buttons="Submit:120;Cancel:80"}

#### Cancelling with the Window Close Button

Normally you set up a button for cancelling the dialog (see above). However, you can also enable the dialog’s close button (the red button in the upper left corner of the dialog) to perform this function. Use the true/false `closewindowbutton=` option to do this.

    superchoicedialog AvailableCards,CardType,{ ... closewindowbutton=yes ... }

#### Disabling Window Maximization

Normally the dialog’s maximization button (the green button in the upper left) is enabled, allowing the user to click to “zoom” the dialog to maximum size. If you want to disable this option, use the `maximizablewindow=` option, like this:

    superchoicedialog AvailableCards,CardType,{ ... maximizablewindow=no ... }

#### Text Appearance

The list of choices normally appears in the standard system font, but you can change the font, size, style and color. This example changes the edited text to be blue, bold, 15 point Tekton.

    superchoicedialog USStates,State,{font=Tekton size=15 style=bold color="#0000FF"}

The style options include `bold`, `italic` and `bolditalic`. The color is specified using HTML color notation (2 hex digits each for red, green and blue).

#### Background Color

The dialog normally has a light gray background. Use the `bgcolor=` option to specify a different color using HTML color notation (for example `blue` or `#0000FF`. This example uses a white background.

    superchoicedialog USStates,State,{bgcolor=white}

#### Default Options

You can set up default superchoicedialog options for a window, a database, or globally. To do so, simply define a variable named `SuperChoiceDefaultOptions` that contains the options. This example will set up a default alert font of Helvetica 12.

    fileglobal SuperChoiceDefaultOptions
    SuperChoiceDefaultOptions = {font="Helvetica" size=12}

Once this code is run, all superchoicedialog dialogs run while this database is active will default to Helvetica 12. (Of course the default can be overridden by explicitly including the options in the superchoicedialog option list.

History

Version | Status | Notes
10.0 | Updated | Carried over from Panorama 6.0, but can now display multiple columns. The ability to limit the minimum and/or maximun number of selected values is now documented. Also you can enable the window close box.