Dialog - Custom

Declaration

<AMSHOWDIALOG ACTIVITY="custom" FILENAME="text" LAYOUT="text" RESULTSTRUCTURE="text" WINDOWTITLE="text" RESULTMETADATA="text" XPOS="number" YPOS="number"  />

Related Topics    

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 constructed by the developer. A dialog is a temporary window that appears to retrieve user input. An application typically uses dialoges to prompt the user for additional information or selection from menu items. A custom dialog 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.

Parameters

General

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 Location of layout is set to 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 parameter is 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 Location of layout is set to Layout is located in an external file (Empty) FILENAME="c:\temp\layout.xml" The path and file name of the custom layout saved externally. This parameter is active only if the Location of layout parameter is set to is set to Layout is located in an external file. Click the folder icon to navigate to the to 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. This title will appear in the title bar when the dialog opens.
Bring dialog to front Yes/No No Yes WINDOWINFRONT="NO" If selected, at runtime, the dialog will appear in front of other open windows. If disabled, it will appear behind other open windows (assuming other windows are currently displayed).

Advanced

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 (default) - 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.

Description

Error Causes

On Error

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description

This sample task presents a custom dialog prompting the user to select a date. A second dialog displays the date selected by the user.

Copy 
 <AMSHOWDIALOG ACTIVITY="custom" RESULTSTRUCTURE="dialog_data" WINDOWTITLE="TheDialog" RESULTMETADATA="dialog_metadata">&lt;AutoMateDialogDesigner&gt;&lt;Property name="ErrorCaption"&gt;FormDesigner&lt;/Property&gt;&lt;Property name="AutoAlignAid"&gt;SnapToGrid&lt;/Property&gt;&lt;Property name="DesignerContextMenu"&gt;False&lt;/Property&gt;&lt;Property name="AutoScroll"&gt;False&lt;/Property&gt;&lt;Property name="AutoScrollMargin"&gt;0,0&lt;/Property&gt;&lt;Property name="AutoScrollMinSize"&gt;0,0&lt;/Property&gt;&lt;Property name="AccessibleDescription"/&gt;&lt;Property name="AccessibleName"/&gt; &lt;Property name="AccessibleRole"&gt;Default&lt;/Property&gt;&lt;Property name="AllowDrop"&gt;False&lt;/Property&gt;&lt;Property name="AutoScrollOffset"&gt;0,0&lt;/Property&gt;&lt;Property name="BackColor"&gt;GradientInactiveCaption&lt;/Property&gt;&lt;Property name="BackgroundImageLayout"&gt;Tile&lt;/Property&gt;&lt;Property name="CausesValidation"&gt;True&lt;/Property&gt;/&gt;&lt;Property name="Controls"&gt;&lt;Object type="System.Windows.Forms.DateTimePicker,System.Windows.Forms,Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="DateTimePicker1"&gt;&lt;Property name="DataBindings"&gt;&lt;Property name="DefaultDataSourceUpdateMode"&gt;OnValidation&lt;/Property&gt;&lt;/Property&gt;&lt;Property name="Location"&gt;16, 56&lt;/Property&gt;&lt;Property name="Name"&gt;DateTimePicker1&lt;/Property&gt;&lt;Property name="Size"&gt;336, 32&lt;/Property&gt;&lt;Property name="TabIndex"&gt;2&lt;/Property&gt;&lt;/Object&gt;&lt;Object type="System.Windows.Forms.Label, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="Label1"&gt;&lt;Property name="ImageAlign"&gt;TopCenter&lt;/Property&gt;&lt;Property name="Text"&gt;Please select a date from the calendar below.&lt;/Property&gt;&lt;Property name="UseCompatibleTextRendering"&gt;True&lt;/Property&gt;&lt;Property name="BackColor"&gt;GradientInactiveCaption&lt;/Property&gt;&lt;Property name="Cursor"&gt;Default&lt;/Property&gt;&lt;Property name="DataBindings"&gt;&lt;Property name="DefaultDataSourceUpdateMode"&gt;OnValidation&lt;/Property&gt;&lt;/Property&gt;&lt;Property name="Font"&gt;Segoe UI, 14pt&lt;/Property&gt;&lt;Property name="ForeColor"&gt;ControlText&lt;/Property&gt;&lt;Property name="Location"&gt;0, 8&lt;/Property&gt;&lt;Property name="Name"&gt;Label1&lt;/Property&gt;&lt;Property name="RightToLeft"&gt;No&lt;/Property&gt;&lt;Property name="Size"&gt;472, 24&lt;/Property&gt;&lt;Property name="TabIndex"&gt;1&lt;/Property&gt;&lt;/Object&gt;&lt;/Property&gt;&lt;Property name="Cursor"&gt;Default&lt;/Property&gt;&lt;Property name="DataBindings"&gt;&lt;Property name="DefaultDataSourceUpdateMode"&gt;OnValidation&lt;/Property&gt;&lt;/Property&gt;&lt;Property name="Font"&gt;Segoe UI, 14pt&lt;/Property&gt;&lt;Property name="ForeColor"&gt;ControlText&lt;/Property&gt;&lt;Property name="Location"&gt;0, 0&lt;/Property&gt;&lt;Property name="Margin"&gt;3, 3, 3, 3&lt;/Property&gt;&lt;Property name="MaximumSize"&gt;0, 0&lt;/Property&gt;&lt;Property name="MinimumSize"&gt;0, 0&lt;/Property&gt;&lt;Property name="RightToLeft"&gt;No&lt;/Property&gt;&lt;Property name="Size"&gt;484, 326&lt;/Property&gt;&lt;Property name="Tag"/&gt;&lt;Property name="Text"&gt;&lt;/Property&gt;&lt;Property name="UseWaitCursor"&gt;False&lt;/Property&gt;&lt;Property name="Padding"&gt;0, 0, 0, 0&lt;/Property&gt;&lt;Property name="ImeMode"&gt;NoControl&lt;/Property&gt;&lt;CustomProperties&gt;&lt;Property name="HostFormLocation"&gt;0, 0&lt;/Property&gt;&lt;Property name="HostFormSize"&gt;500, 400&lt;/Property&gt;&lt;/CustomProperties&gt;&lt;/AutoMateDialogDesigner&gt;</AMSHOWDIALOG>
 <AMSHOWDIALOG>The selected date is:%dialog_data.DateTimePicker1.Value%</AMSHOWDIALOG>