superalert
superalert
MESSAGE
,
OPTIONS

The superalert statement will display a custom alert.

Parameters

This statement has two parameters:

message – The message that appears in the alert.

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 an alert. You can control the size of the alert, as well as many appearance options. The alert can have multiple custom buttons, in which case info(“dialogtrigger”) will contain the name of the button that was pressed. Here are some examples that illustrate how this statement can be used.

    superalert "Are you talking to me?",
        {height=120 width=200 font="#LabelFont" size=9 color="red" buttons="Yes:60;No:60"}
    superalert "hello there!",{height=2in width=50% buttons="Ok"}
    superalert "Look Out!",{image="Stop Sign"}
    superalert "For your information.",{image="Logo" imageedge=top imagealign=center height=10cm}
    superalert bigTextVariable,{scroll=yes height=-25 width=80%}

The superalert statement allows you to display a wide variety of alerts 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.

#### SuperAlert Options

The second parameter of the superalert 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 superalert options.

#### Height and Width

If you don’t specify otherwise, the alert will be 200 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.

    superalert message,{height=144 width=288}

You can also specify the dimensions in inches (`"` or `in`) or centimeters (`cm`).

    superalert message,{height=2" width=4"}
    superalert message,{height=5cm width=12cm}

Another option is to specify the dimensions as a percentage of the total screen width and height. This example creates an alert that is variable height (80% of the screen height) but fixed width (500 points, or about 7 inches).

    superalert message,{height=80% width=500}

If you specify a negative value for the height or width, the value actually controls the border height or width. This example creates an alert that is variable height, but with the top of the alert 1/2 inch from the top of the screen, and the bottom of the alert 1/2 inch from the bottom of the screen (wow, that’s a big alert!).

    superalert message,{height=-36 width=500}

Note: If the alert fits comfortably over the current window it will be centered over that window, otherwise it will be centered on the entire screen.

#### Title

Use the `title=` option if you want to display a title at the top of the alert.

    superalert message,{title="Expires in 30 days!"}

#### Buttons

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

    superalert message,{buttons="Yes;No;Other"}
    if info("dialogtrigger")="Yes"
        ... do something for yes
    elseif info("dialogtrigger")="No"
        ... do something for no
    elseif info("dialogtrigger")="Other"
        ... do something else
    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 Yes button is on the far right and is the default button. The No button is displayed to its left, and the Other button is displayed even further left.

Note: The first button is always the default button that is invoked if the user presses the Enter key (in the example above the Yes button is the default). The second button is always the default button that is invoked if the user presses the Escape key (i.e. they user want’s to cancel or indicate no).

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. In this example the One button will be an inch wide, but the Two button will be only a half inch.

    superalert message,{buttons="One:72;Two:36"}

#### Cancelling with the Window Close Button

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

    superalert message,{ ... closewindowbutton=yes ... }

Here is how to remove all buttons from the alert, so that the only way to close the alert is to click the close window button.

    superalert message,{ ... closewindowbutton=yes buttons=":0" ... }

#### Disabling Window Maximization

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

    superalert message,{ ... maximizablewindow=no ... }

#### Text Appearance

The message text in the alert is normally displayed using the standard system font, but you can change the font, size, style and color. This example will display the text using blue, bold, 15 point Tekton.

    superalert message,{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).

If you want to change the text appearance midstream, using the `style=rich` option. When this option is used, you can use RTML tags inside the message text to change appearance of the text at any point. See the richtextdisplay( function for the details on RTML tags. This example displays a dictionary entry, with the word itself displayed in bold.

    superalert "<b>"+word+"</b> -- "+definition,{style=rich}

If rich text is used, the font, size, and style options are ignored – you have to specify these options with tags.

#### Text Alignment

The message text is normally displayed in the upper left corner of the dialog, but you can use the `textalign=` option to move it to different positions. The most common alignments are `topleft` and `center`, but you can also use `topcenter`, `topright`, `leftcenter`, `rightcenter`, `bottomleft`, `bottomcenter` or `bottomright`.

    superalert "Danger!",{textalign=center}

Note: The alignment options only work for plain text. If rich text is used, the text is always top aligned, but can be center or right aligned by using the appropriate tags.

#### Scrolling

If the message is really long, you can add a scroll bar to your alert.

    superalert warandpeace,{height=80% scroll=yes}

Or, you can use a thin scroll bar.

    superalert warandpeace,{height=80% scroll=thin}

In either case, Panorama will add a thin border around the text.

#### Background Color

The alert normally has a white background. Use the `bgcolor=` option to specify a different color using HTML color notation. This example displays yellow text on a red background.

    superalert "Danger!",{textalign=center bgcolor=red color="#f9f587"}

#### Images & Icons

The superalert statement allows you to display an icon or image in the alert in addition to text. To display a stop, caution or note icon use the `icon=` option.

    superalert "Watch out",{icon=caution}

The `image=` option allows you to display any image you want within the alert. The image may be in a disk file or in the flash art gallery of the current database. If the image is in a disk file, the default location is the folder containing the current database, but you can specify any folder you want by specifying the complete path.

    superalert "Happy!",{image="Smiley Face.png"}

The `imageedge=` option specifies how the image should be placed relative to the text. `Left` means that the image will be placed to the left of the text. `Top` means that the image will be placed above the text. `Both` means the text will be placed both below and to the right of the image (the image in the upper left corner with the text in the lower right corner). `None` means that the text will be drawn on top of the image, essentially making the image a background. For all of these options the alert will adjust the text location based on the size of the image.

The `imagealign=` option specifies how the image should be aligned relative to the edges of the alert. The options are `topleft` (the default), `topcenter`, `topright`, `leftcenter` and `bottomcenter`.

The text position is automatically adjusted based on the image size. If the image is placed at the top (`imageedge=top`) the text is normally placed 3 points below the image. The `texttopadjust=` option allows you to change that spacing for better optical alignment. For example `texttopadjust=10` will place the text 10 points below the bottom of the image.

#### Automatically Closing after a Delay

The alert normally stays open until a button is clicked. Using the `timeout=` option, however, you can make the alert automatically close after a specified number of seconds. This example specifies a timeout of 30 seconds (of course the user can also press a button to dismiss the dialog sooner). When the timeout expires, the alert will close as if the rightmost button had been pressed.

    superalert fyi,{timeout=30}

If the alert has more than one button, the automatic timeout is normally the same as pressing the Ok button. However, you can alternately specify that the timeout triggers the Cancel button, like this:

    superalert fyi, {buttons="Ok;Cancel" timeout=30 timeoutbutton="cancel"}

Note: No matter what the actual names are, for the purposes of the timeout feature the first button is always the Ok button and the second button is the Cancel button. If the alert has a third button it cannot be triggered by the timeout.

#### Default Options

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

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

Once this code is run, all alerts 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 superalert option list.

History

Version | Status | Notes
10.2 | Updated | New "timeoutbutton" option allows either the Ok or Cancel button to be triggered by the automatic timeout feature.
10.0 | Updated | Carried over from Panorama 6.0, but now allows rich text to be displayed in the alert, and allows the close window button to be enabled.