Help files

The Custom Dialog Designer

Dialog vs. Custom Dialog

WinAutomation offers a wide variety of dialog-producing actions, categorized under "Message Boxes" in the Actions' pane. Selection dialogs allow you to assign a value to a variable (be it Text, Date, List Selection, File or Folder) while the Process is running. Once the value is entered, the user can either press the "OK" or the "Cancel" button. This button choice can also be assigned to a variable (%ButtonPressed%). Simple, default dialogs come in handy when there is only one configurable parameter that needs to be set. For example, it is very common to include a "Display Select File Dialog" action at the beginning of a Process and use the value assigned to the %SelectedFile% throughout the remaining actions.

With a Custom Dialog on the other hand, you may configure multiple parameters in a single action. Custom Dialogs buttons are not limited to "OK"/"Cancel" and can also invoke Functions, with the Dialog itself optionally persisting throughout the Function execution. Nearly every aspect of the Custom Dialog and its controls is configurable including, but not limited to, their general appearance, positioning and displayed text.

Given such flexibility, the "Display Custom Dialog" action will allow you create a fully featured Graphical User Interface (GUI) for your Process, with the ease of drag and drop.

The Custom Dialog Designer

When you initially place a "Display Custom Dialog" action into your Process, the Custom Dialog Designer automatically opens up:

designacustomdialog1.png

To bring it up again for any consequent modifications, double click on the action and press on the "Open Designer" button.

The Designer Window consists of two panes: Your Form on the left and the Drag & Drop controls on the right. You may select any of the tabs of the Drag & Drop controls pane, to reveal the controls of the corresponding category or edit the Dialog's properties. Controls can be added or rearranged by drag and drop.

For example, to add a "Title" control, select "Misc" and drag the Title from the pane on the right, to your form on the left:

designacustomdialog2.png

When a control is added to the form, the control's property editor comes up:

designacustomdialog3.png

With the help of the editor, you may modify the control's properties. As always, you can insert preexisting variables in any of the fields by clicking on the gear (gear.png) icon. When you are done editing, press the "Save" button. Saving also updates the live preview of the dialog presented on Your Form.

designacustomdialog4.png

If you need to modify any of the control's properties at a later point, left click on the placed control so that the property editor reappears.

Control Types

Input

Simple Input

Holds a single-line text value, the most common form of input.

Multiline Input

Holds a multi line text value, suitable for short messages or lists. The value returned is still a single Text variable containing line breaks, which can be split if necessary.

Password

Similar to the Simple Input, but masks typed characters so that passwords do not appear on the screen as plaintext.

Combobox

The Combobox allows the user to either make a selection from a pre-defined list or type their own, custom, value. The value returned is a list variable containing the text of the selected item(s).

File

Lets you select one or multiple Files or a Folder. The value returned is a File/Folder variable for single items, or a File List Variable when you allow multiple item selection.

Date

Holds and returns a Date Time variable. If no value is entered by the user, the current date and time is returned.

Radios / Checkboxes

Inline Radios

Select among a group of radio-buttons that are distributed horizontally. Only single item can be selected inside a group. The text/label of the selected item is the value returned.

Multiline Radios

Select among a group of radio-buttons that are distributed vertically. Only single item can be selected inside a group. The text/label of the selected item is the value returned.

Checkbox

A single checkbox that the user can leave checked, or uncheck. Returns a Boolen variable with the value %True% when the box is checked, %False% otherwise.

Select

Select

Similar to the Combobox, but does not allow the insertion of custom values: the user can select only among the existing options.

Multiple Select

Allows the selection of multiple items from the provided list. The value returned is a single Text variable containing the text/labels of the selected items, separated by linebreaks.

Button Groups: Button groups can contain one or more buttons, each one with its own name, style and assigned operation. You may modify the buttons belonging to a group by bringing up the property editor:

designacustomdialog5.png

You will find more information regarding the configurable button properties, in the Button Properties subsection, below.

Miscellaneous

Title

A Title control is a large text label, suitable for titling the entire form or sections of it. Does not return any value.

Placeholder Text

Simple text control. You can use it for displaying any desired text at any part of the form. Does not return any value.

Link

Adds a text control that when clicked, opens up the system's default browser and navigates to the specified linked URL. Does not return any value.

Horizontal Ruler

Adds a horizontal dividing ruler, suitable for dividing controls into logical groups. Does not return any value.

Control Properties

General Properties

ID / Name

Used for retrieving the value entered/selection made for this specific control. Must be unique and cannot contain spaces.

Label / Text

The text displayed as label to the control or on the control itself.

Link

Specific to Link controls - The URL of the target page for this Link control.

Enter Password

Specific to Password Inputs - Allows the entry of unescaped '%' characters inside the default password property.

Default Value

The value that the control will be prepopulated with, when the dialog is first shown.

Default Password

Specific to Password Inputs - Similarly to the default value, enter here the value that the Password control will hold when the Custom Dialog opens.

File Selector Title

Specific to File Inputs - The text to be used as title of the "Select File Dialog" that emerges when the "..." button of the control is pressed.

Pick

Specific to File Inputs - Specifies whether the file selection dialog will allow File(s) or Folder selection.

Multiple Selection

Specific to File Inputs - When selecting files, specify whether the user is allowed to select only one or multiple.

Short Description

A small, optional description that gets displayed the legend of the control.

Popup Help Text

The pop-up text to be displayed when the user hovers over the info icon on the right of the control.

Size

The size that the control should have. (Overrides CSS style)

Extra CSS Class

You can assign an extra CSS class on the control, which is useful for custom styling.

Button Properties

Button Name

Defines name of the button and also the text displayed on it.

Function to Run

Select a Function from the drop down list to assign it to the button. Once the User presses the button, the selected function will be invoked. You may have only one function executing per custom dialog at a time.

Theme

Select among various appearance styles for the button.

Close

Choose whether the custom dialog should close when the button gets pressed.

Whenever a button that has not be set as the "Cancel Button" gets pressed, all input gets validated against the following rules, where they may apply:

Validation

Required

Specify whether populating this input field is mandatory.

Allowed Value

Specify the accepted format of the user-supplied input value. You may choose one of the pre-defined formats, or define your own, custom one.

File Filter

Specific to File Inputs - The file filter applied to the "Select File Dialog" that emerges when the "..." button of the control is pressed.

Check if File Exists

Specific to File Inputs - Specify whether the selected file(s) are required to exist.

Min/Max Date

Specific to Date Inputs - Restricts the range of the date supplied.

Validation fails will prevent function execution and Custom Dialog termination. Moreover, a validation fail always produces an appropriate error message on the form.

Dialog Properties

Title

Specify the title to be used for the Custom Dialog.

Initial State

Choose among Minimized, Maximized and Normal states for the Custom Dialog's Window.

Initial Position

Specify an initial position for the Custom Dialog's Window. When "custom" is selected, you have to also specify the coordinates (X,Y)

Height

Specify the height of the Custom Dialog's Window.

Width

Specify the width of the Custom Dialog's Window.

Accept Button

Specify a button to be automatically pressed when the user presses Enter with the dialog open.

Cancel Button

Specify a button to be automatically pressed when the user presses Escape with the dialog open. Validation of input is skipped.

Dialog Icon

Specify a custom icon for the dialog. The icon is visible both on the task bar and the upper left corner of the Custom Dialog's Window.

Keep on Top

Specify whether the Custom Dialog's Window should remain on top of all other windows.

Allow Resizing

Allow/Disallow resizing of the Custom Dialog's Window.

Retrieving Entered Values from a Custom Dialog

The input controls of a Custom Dialog hold useful values, entered by the user in runtime. All of the populated values get stored inside a Data Row variable as defined in the "Display Custom Dialog" action's properties (default variable name: %CustomDialogResults%). Values are available to functions invoked by a button press on the Dialog and actions following the "Display Custom Dialog" action.

Input controls store their value on a "column" with the ID/Name of the corresponding control. For instance, the value populated into the "Combobox1" control can be accessed as such:

%CustomDialogResults["Combobox1"]% (Assuming that the default names were kept)

Some controls may hold a variable with additional properties or even a list. You may access the properties and the list items as well:

%CustomDialogResults["File"].Size% is the size of the selected file and

%CustomDialogResults["MultipleSelect"][0]% is the first selected item.

Advanced Customization of the Dialog's appearance

You may add your own CSS rules applying to the Custom Dialog and its controls, in the Advanced Tab of the "Display Custom Dialog" action. Styling rules entered inside the "CSS Theming Overrides" box are effective immediately; you can preview them on the Custom Dialog Designer, or view them directly at the resulting Dialog that is produced during runtime.

Each control can be assigned an "Extra CSS Class" through the corresponding property. A CSS class allows you to set a particular style for one or many HTML elements with that particular class in your custom CSS rules.