Dialog - Custom

Declaration

<AMSHOWDIALOG 
ACTIVITY="custom" FILENAME="text" RESULTSTRUCTURE="text" 
WINDOWTITLE="text" POSITION="text (options)" />

Description: Displays a custom dialog constructed using the Dialog Designer, an IDE that provides a graphical tool to easily design custom dialogs to be used within a task.

NOTE: This activity must be executed on an interactive logon session.

Practical Usage

Used to display a custom dialog box constructed by the developer. A dialog box is a temporary window that appears to retrieve user input. An application typically uses dialog boxes to prompt the user for additional information or selection from menu items. A custom dialog box may be required that, for example, presents the user with specific options, and then runs the appropriate subroutine based on the option they chose. It such cases, the developer may need to create a custom dialog.

General Parameters

Property

Type

Required

Default

Markup

Description

Location of layout

---

---

---

---

Specifies the location of the custom dialog layout. This is a graphical parameter only used during design time, therefore, contains no properties or markups. The available options are:

  • Layout is embedded in task file - If creating a new custom dialog, selecting this option will save the layout definition as code embedded directly within the current task (.aml) file. If editing an existing custom dialog, selecting this option allows changes to be made to the layout embedded within the current task file.

  • Layout is located in an external file - If creating a new custom dialog, selecting this option saves the layout definition to a .XML file located externally. If editing an existing custom dialog, selecting this option allows changes to be made to an existing layout previously saved to an external .XML file.

Layout

Text

Yes if layout is embedded in task file

(Empty)

LAYOUT=[Embedded]

The custom layout is embedded within the task. This parameter is active only if the Location of layout parameteris set to Layout is embedded in task file. To create or edit the custom dialog, click Edit Layout.See Dialog Designer for more details.

Filename

Text

Yes if layout is from external file

(Empty)

FILENAME="c:\temp\layout.xml"

The path and filename of the custom layout saved externally. This parameter is active only if the Location of layout parameteris set to is set to Layout is located in an external file. Click the folder icon to navigate to theto the external .xml file. To edit the custom layout, click Edit Layout. See Dialog Designer for more details.

Create and populate dialog data

Text

Yes

(Empty)

RESULTSTRUCTURE="theStructure"

The name of the dataset to create and populate with dialog data. This dataset will include the values for the various controls of the dialog, including any dynamic values that were selected by the user (if any). The complete list can be viewed from the Variables Debug Window.

Create and populate dialog metadata

Text

No

(Empty)

RESULTMETADATA="theMetadata"

The name of the dataset to create and populate with dialog metadata. This dataset will include the values for the various dialog controls, including any dynamic values that were selected by the user (if any). The complete list can be viewed from the Variables Debug Window.

Title

Text

No

MyDialog

WINDOWTITLE="MyDialog2"

The title of the custom dialog box. This title will appear in the title bar when the dialog box opens.

Bring dialog to front

Yes/No

No

Yes

WINDOWINFRONT="NO"

If set to YES, at runtime, the dialog box will appear in front of other open windows. If set to NO, it will appear behind other open windows (assuming other windows are currently displayed).

Advanced Parameters

Property

Type

Required

Default

Markup

Description

Position

Text (Options)

No

Center of screen

POSITION="lower_right"

Specifies the screen position that the custom dialog will be displayed. The available options are:

  • Center of screen - The dialog will be displayed directly in the center of the screen.

  • Upper left corner of screen - The dialog will be displayed in the upper left corner of the screen.

  • Upper right corner of screen - The dialog will be displayed in the upper right corner of the screen.

  • Lower right corner of screen - The dialog will be displayed in the lower right corner of the screen.

  • Lower left corner of screen - The dialog will be displayed in the lower left corner of the screen.

  • Custom location - The dialog will be displayed in a user defined custom location.

Window coordinates (X)

Number

Yes if Position parameter is set to Custom location

---

XPOS="3335"

The X window coordinate relative to the screen. To capture a position using the mouse, enable the option Capture mouse position below.

Window coordinates (Y)

 

Yes if Position parameter is set to Custom location

---

YPOS="772"

The X window coordinate relative to the screen. To capture a position using the mouse, enable the option Capture mouse position below.

Capture mouse position (press Space to capture)

---

---

---

---

If enabled, allows the screen position to be captured by the mouse. To capture a specific area on your screen, hover the cursor over the desired position and press the Space bar on your keyboard. This will automatically populate the X and Y window coordinates.