RPA.Dialogs

Adds a checkbox that indicates a true or false value. The selection will be available in the name field of the result, and the label text will be shown next to the checkbox.

The boolean default value will define the initial checked state of the element.

Examples

*** Tasks ***
Add heading     Enable features
Add checkbox    name=vault        label=Enable vault       default=True
Add checkbox    name=triggers     label=Enable triggers    default=False
Add checkbox    name=assistants   label=Enable assistants  default=True
${result}=      Run dialog
IF    $result.vault
    Enable vault
END

Creates a drop-down menu with the given options. The selection the user makes will be available in the name field of the result.

The default argument can be one of the defined options, and the dialog automatically selects that option for the input.

A custom label text can also be added.

Examples

*** Tasks ***
Add heading     Select user type
Add drop-down
...    name=user_type
...    options=Admin,Maintainer,Operator
...    default=Operator
...    label=User type
${result}=      Run dialog
Log    User type should be: ${result.user_type}

Adds a button which opens a local file with the corresponding default application. Can be used for instance to display generated files from the robot to the end-user.

Optionally a custom label can be given for the button text. By default uses the filename of the linked file.

Examples

*** Tasks ***
${path}=   Generate order files
Add heading    Current orders
Add file    ${path}    label=Current
Run dialog

Adds a native file selection dialog for inputting one or more files. The list of selected files will be available in the name field of the result.

By default opens up in the user's home directory, but it can be set to a custom path with the source argument.

If the destination argument is not set, it returns the original paths to the selected files. If the destination directory is set, the files are copied there first and the new paths are returned.

The argument file_type restricts the possible file extensions that the user can select. The format of the argument is as follows: Description text (*.ext1;*.ext2;...). For instance, an argument to limit options to Excel files could be: Excel files (*.xls;*.xlsx).

To allow selecting more than one file, the multiple argument can be enabled.

Examples

*** Tasks ***
# This can be any one file
Add file input    name=anyting

# This can be multiple files
Add file input    name=multiple  multiple=True

# This opens the select dialog to a custom folder
Add file input    name=src       source=C:\Temp\Output\

# This copies selected files to a custom folder
Add file input    name=dest      destination=%{ROBOT_ROOT}

# This restricts files to certain types
Add file input    name=types     file_type=PDF files (*.pdf)

# Every file input result is a list of paths
${result}=    Run dialog
FOR    ${path}    IN    @{result.multiple}
    Log    Selected file: ${path}
END

See the keyword Add file for information about the inserted element itself.

The keyword uses Unix-style glob patterns for finding matching files, and the supported pattern expressions are as follow:

If a filename has any of these special characters, they can be escaped by wrapping them with square brackets.

Examples

*** Tasks ***
# Add all excel files
Add files    *.xlsx

# Add all log files in any subdirectory
Add files    **/*.log

# Add all PDFs between order0 and order9
Add files    order[0-9].pdf

Supported size values are Small, Medium, and Large. By default uses the value Medium.

Examples

*** Tasks ***
Add heading     User information  size=Large
Add heading     Location          size=Small
Add text input  address           label=User address
Run dialog

Adds a special hidden result field that is not visible to the user and always contains the given static value.

Can be used to keep user input together with already known values such as user IDs, or to ensure that dialogs with differing elements all have the same fields in results.

Examples

*** Tasks ***
Add hidden input   user_id   ${USER_ID}
Add text input     username
${result}=         Run dialog
Enter user information    ${result.user_id}    ${result.username}

Adds an icon which can be used to indicate status or the type of dialog being presented.

The currently supported icon types are:

The size of the icon can also be changed, to a given height/width of pixels.

Examples

*** Tasks ***
Add icon              Warning    size=64
Add heading           Do you want to delete this order?
Add submit buttons    buttons=No,Yes
${result}=    Run dialog

Adds an inline image to the dialog, which can either point to a local file path on the executing machine or to a remote URL.

By default the image is resized to fit the width of the dialog window, but the width and/or height can be explicitly defined to a custom value. If only one of the dimensions is given, the other is automatically changed to maintain the correct aspect ratio.

Examples

*** Tasks ***
Add image      company-logo.png
Add heading    To start, please press the Continue button   size=Small
Add submit buttons    Continue
Run dialog

Adds a clickable link element, which opens the user's default browser to the given url. Optionally a label can be given which is shown as the link text, instead of the raw URL.

Examples

*** Tasks ***
Add heading    An error occurred
Add text       See link for documentation
Add link       https://robocorp.com/docs    label=Troubleshooting
Run dialog

Adds a text field that hides the user's input. The entered content will be available in the name field of the result.

For customizing the look of the input, the label text can be given to add a descriptive label and the placholder text can be given to act as an example of the input value.

Examples

*** Tasks ***
Add heading    Change password
Add text input        username    label=Current username
Add password input    password    label=New password
${result}=    Run dialog
Change user password    ${result.username}  ${result.password}

Creates a set of radio buttons with the given options. The selection the user makes will be available in the name field of the result.

The default argument can be one of the defined options, and the dialog automatically selects that option for the input.

A custom label text can also be added.

Examples

*** Tasks ***
Add heading     Select user type
Add radio buttons
...    name=user_type
...    options=Admin,Maintainer,Operator
...    default=Operator
...    label=User type
${result}=      Run dialog
Log    User type should be: ${result.user_type}

The dialog automatically creates a button for closing itself. If there are no input fields, the button will say "Close". If there are one or more input fields, the button will say "Submit".

If the submit button should have a custom label or there should be multiple options to choose from when submitting, this keyword can be used to replace the automatically generated ones.

The result field will always be called submit and will contain the pressed button text as a value.

If one of the custom options should be the preferred option, the default argument controls which one is highlighted with an accent color.

Examples

*** Tasks ***
Add icon      Warning
Add heading   Delete user ${username}?
Add submit buttons    buttons=No,Yes    default=Yes
${result}=    Run dialog
IF   $result.submit == "Yes"
    Delete user    ${username}
END

Supported size values are Small, Medium, and Large. By default uses the value Medium.

Examples

*** Tasks ***
Add heading   An error occurred
Add text      There was an error while requesting user information
Add text      ${error}   size=Small
Run dialog

Adds a text field that can be filled by the user. The entered content will be available in the name field of the result.

For customizing the look of the input, the label text can be given to add a descriptive label and the placholder text can be given to act as an example of the input value.

If the rows argument is given as a number, the input is converted into a larger text area input with the given amount of rows by default.

Examples

*** Tasks ***
Add heading    Send feedback
Add text input    email    label=E-mail address
Add text input    message
...    label=Feedback
...    placeholder=Enter feedback here
...    rows=5
${result}=    Run dialog
Send feedback message    ${result.email}  ${result.message}

By default this is done automatically when a dialog is created.

Examples

*** Tasks ***
Add heading     Please input user information
FOR    ${user}   IN    @{users}
    Run dialog    clear=False
    Process page
END
Clear elements

See the keyword Close dialog for further information about usage and implications.

Examples

*** Tasks ***
${dialog1}=    Show dialog
A keyword which runs during the dialog

${dialog2}=    Show dialog
A keyword that fails during the dialog

# Close all dialogs without knowing which have been created
[Teardown]    Close all dialogs

Close a dialog that has been created with the keyword Show dialog.

Calling this keyword is not required if the user correctly submits a dialog or closes it manually. However, it can be used to forcefully hide a dialog if the result is no longer relevant.

If a forcefully closed dialog is waited, it will throw an exception to indicate that it was closed before receiving a valid result.

Examples

*** Tasks ***
# Display notification dialog while operation runs
${dialog}=    Show dialog    title=Please wait
Run process that takes a while
Close dialog    ${dialog}

Create a dialog from all the defined elements and block until the user has handled it.

Returns a result object with all input values. This keyword is a shorthand for the following expression:

*** Tasks ***
Run dialog
    [Arguments]  ${timeout}=180  &{options}
    ${dialog}=   Show dialog     &{options}
    ${result}=   Wait dialog     ${dialog}  timeout=${timeout}
    [Return]     ${result}

For more information about possible options for opening the dialog, see the documentation for the keyword Show dialog.

Examples

*** Tasks ***
Add heading     Please enter your username
Add text input  name=username
${result}=      Run dialog
Log    The username is: ${result.username}

Create a new dialog with all the defined elements, and show it to the user. Does not block, but instead immediately returns a new Dialog instance.

The return value can later be used to wait for the user to close the dialog and inspect the results.

By default the window has the title Dialog, but it can be changed with the argument title to any string.

The height argument accepts a static number in pixels, but defaults to the string value AUTO. In this mode the Dialog window tries to automatically resize itself to fit the defined content.

In comparison, the width argument only accepts pixel values, as all element types by default resize to fit the given window width.

With the clear argument it's possible to control if defined elements should be cleared after the dialog has been created. It can be set to False if the same content should be shown multiple times.

In certain applications it's useful to have the dialog always be on top of already opened applications. This can be set with the argument on_top, which is disabled by default.

For development purposes the debug agument can be enabled to allow opening browser developer tools.

If the dialog is still open when the execution ends, it's closed automatically.

Examples

*** Tasks ***
Add text input    name=username    label=Username
Add text input    name=address     label=Address
${dialog}=    Show dialog    title=Input form
Open browser to form page
${result}=    Wait dialog    ${dialog}
Insert user information      ${result.username}  ${result.address}

Returns a list of results from all dialogs that have not been handled before calling this keyword, in the order the dialogs were originally created.

If any dialog fails, this keyword throws the corresponding exception immediately and doesn't keep waiting for further results.

Examples

*** Tasks ***
# Create multiple dialogs
Show dialog    title=One
Show dialog    title=Two
Show dialog    title=Three

# Wait for all of them to complete
@{results}=    Wait all dialogs

# Loop through results
FOR    ${result}    IN    @{results}
    Log many    &{result}
END

Wait for a dialog to complete that has been created with the keyword Show dialog.

Blocks until a user has closed the dialog or until timeout amount of seconds has been reached.

If the user submitted the dialog, returns a result object. If the user closed the dialog window or timeout was reached, raises an exception.

Examples

*** Tasks ***
Add text input    name=username    label=Username
Add text input    name=address     label=Address
${dialog}=    Show dialog    title=Input form
Open browser to form page
${result}=    Wait dialog    ${dialog}
Insert user information      ${result.username}  ${result.address}