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 design custom dialogs to be used within a task.

NOTE: This activity must run on an interactive log in 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 dialogs to prompt the user for additional information or menu item selection. A custom dialog can be required that, for example, presents the user with specific option, and runs the appropriate subroutine based on the selected option. It such cases, the developer can 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 saves the layout definition as code embedded directly within the current task (.aml) file. If you are 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 includes the values for the various controls of the dialog, including any dynamic values selected by the user (if any). You can view the complete list 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). You can view the complete list from the Variables Debug Window.
Title Text No MyDialog WINDOWTITLE="MyDialog2" The title of the custom dialog. The title appears in the title bar when the dialog opens.
Bring dialog to front Yes/No No Yes WINDOWINFRONT="NO" If selected, at runtime, the dialog appears in front of other open windows. If disabled, it appears 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 of the custom dialog. The available options are:
  • Center of screen (Default) - The dialog is displayed directly in the center of the screen.
  • Upper left corner of screen - The dialog is displayed in the upper left corner of the screen.
  • Upper right corner of screen - The dialog is displayed in the upper right corner of the screen.
  • Lower right corner of screen - The dialog is displayed in the lower right corner of the screen.
  • Lower left corner of screen - The dialog is displayed in the lower left corner of the screen.
  • Custom location - The dialog is 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, select Capture mouse position.
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, select Capture mouse position.
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 automatically populates 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

The following 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>