RPA.Dialogs library | Robocorp documentation

RPA.Dialogs

Add checkbox

Add a checkbox element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result field
label	str	null	Label text for checkbox
default	bool	False	Default checked state

param name:	Name of result field
param label:	Label text for checkbox
param default:	Default checked state

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.

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

Add Date Input

Add a date input element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of the result field
default	date, str, None	None	The default set date
label	str, None	None	Label for the date input field

param name:	Name of the result field
param default:	The default set date
param label:	Label for the date input field

Displays a date input widget. The selection the user makes will be available as a date object in the name field of the result. The default argument can be a pre-set date as object or string in "YYYY-MM-DD" format, otherwise the current date is used.

Examples

Add heading Enter your birthdate Add Date Input birthdate default=1993-04-26 ${result} = Run dialog Log To Console User birthdate year should be: ${result.birthdate.year}

Add Dialog Next Page Button

Add a next page button

Arguments

Argument	Type	Default value	Description
label	str	null	The text displayed on the button

param label:	The text displayed on the button

The next page button will delimit the next elements of the dialog in a separate view, so that they will only be displayed after pressing the button, creating a wizard experience in the dialog.

Examples

Add heading Send feedback Add text input email label=E-mail address Add dialog next page button label=next Add text input name label=Name Add dialog next page button label=next Add checkbox name=contact ... label=Do you want us to contact you? ... default=True Add dialog next page button label=next Add text input message ... label=Feedback ... placeholder=Enter feedback here ... rows=5 Add submit buttons buttons=submit ${result}= Run dialog Send feedback message ${result.email} ${result.message} Run dialog

Add drop-down

Add a drop-down element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result field
options	List[str], str	null	List of drop-down options
default	str, None	None	The default selection
label	str, None	None	Label for input field

param name:	Name of result field
param options:	List of drop-down options
param default:	The default selection
param label:	Label for input field

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

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}

Add file

Add a file element, which links to a local file

Arguments

Argument	Type	Default value	Description
path	str	null	The path to the file
label	str, None	None	A custom label text for the file

param path:	The path to the file
param label:	A custom label text for the file

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

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

Add file input

Add a file input element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result field
label	str, None	None	Label for input field
source	str, None	None	Default source directory
destination	str, None	None	Target directory for selected files
file_type	str, None	None	Accepted file types
multiple	bool	False	Allow selecting multiple files

param destination:
param name:	Name of result field
param label:	Label for input field
param source:	Default source directory
	Target directory for selected files
param file_type:
	Accepted file types
param multiple:	Allow selecting multiple files

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

# 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

Add files

Add multiple file elements according to the given file pattern

Arguments

Argument	Type	Default value	Description
pattern	str	null	File matching pattern

param pattern:	File matching pattern

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:

Pattern	Meaning
`*`	Match everything
`?`	Match any single character
`[seq]`	Match any character in seq
`[!seq]`	Match any character not in seq
`**`	Match all files, directories, and subdirectories

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

Examples

# 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

Add heading

Add a centered heading text element

Arguments

Argument	Type	Default value	Description
heading	str	null	The text content for the heading
size	Size	Medium	The size of the heading

param heading:	The text content for the heading
param size:	The size of the heading

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

Examples

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

Add hidden input

Add a hidden input element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result feild
value	str	null	Value for input

param name:	Name of result feild
param value:	Value for input

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

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

Add icon

Add an icon element

Arguments

Argument	Type	Default value	Description
variant	Icon	null	The icon type
size	int	48	The size of the icon

param variant:	The icon type
param size:	The size of the icon

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

The currently supported icon types are:

Name	Description
Success	A green check mark
Warning	An orange warning triangle
Failure	A red cross or X mark

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

Examples

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

Add image

Add an image element, from a local file or remote URL

Arguments

Argument	Type	Default value	Description
url_or_path	str	null	The location of the image
width	int, None	None	The static width of the image, in pixels
height	int, None	None	The static height of the image, in pixels

param url_or_path:
	The location of the image
param width:	The static width of the image, in pixels
param height:	The static height of the image, in pixels

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

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

Add link

Add an external URL link element

Arguments

Argument	Type	Default value	Description
url	str	null	The URL for the link
label	str, None	None	A custom label text for the link

param url:	The URL for the link
param label:	A custom label text for the link

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

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

Add password input

Add a password input element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result field
label	str, None	None	Label for field
placeholder	str, None	None	Placeholder text in input field

param placeholder:
param name:	Name of result field
param label:	Label for field
	Placeholder text in input field

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

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}

Add radio buttons

Add radio button elements

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result field
options	List[str], str	null	List of drop-down options
default	str, None	None	The default selection
label	str, None	None	Label for input field

param name:	Name of result field
param options:	List of drop-down options
param default:	The default selection
param label:	Label for input field

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

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}

Add submit buttons

Add custom submit buttons

Arguments

Argument	Type	Default value	Description
buttons	List[str], str	null	Submit button options
default	str, None	None	The primary button

param buttons:	Submit button options
param default:	The primary button

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

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

Add text

Add a text paragraph element, for larger bodies of text

Arguments

Argument	Type	Default value	Description
text	str	null	The text content for the paragraph
size	Size	Medium	The size of the text

param text:	The text content for the paragraph
param size:	The size of the text

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

Examples

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

Add text input

Add a text input element

Arguments

Argument	Type	Default value	Description
name	str	null	Name of result field
label	str, None	None	Label for field
placeholder	str, None	None	Placeholder text in input field
rows	int, None	None	Number of input rows

param placeholder:
param name:	Name of result field
param label:	Label for field
	Placeholder text in input field
param rows:	Number of input rows

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

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}

Clear elements

Remove all previously defined elements and start from a clean state

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

Examples

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

Close all dialogs

Close all dialogs opened by this library.

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

Examples

${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 dialog

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

Arguments

Argument	Type	Default value	Description
dialog	Dialog	null	An instance of a Dialog

param dialog:	An instance of a 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

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

Run dialog

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

Arguments

Argument	Type	Default value	Description
timeout	int	180	Time to wait for dialog to complete, in seconds
options	Any	null	Options for the dialog

param timeout:	Time to wait for dialog to complete, in seconds
param options:	Options for the dialog

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

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

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

Show dialog

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.

Arguments

Argument	Type	Default value	Description
title	str	Dialog	Title of dialog
height	int, str	AUTO	Height of dialog (in pixels or 'AUTO')
width	int	480	Width of dialog (in pixels)
on_top	bool	False	Show dialog always on top of other windows
clear	bool	True	Remove all defined elements
debug	bool	False	Allow opening developer tools in Dialog window

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

param title:	Title of dialog
param height:	Height of dialog (in pixels or 'AUTO')
param width:	Width of dialog (in pixels)
param on_top:	Show dialog always on top of other windows
param clear:	Remove all defined elements
param debug:	Allow opening developer tools in Dialog window

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

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}

Wait all dialogs

Wait for all opened dialogs to be handled by the user.

Arguments

Argument	Type	Default value	Description
timeout	int	300	Time to wait for dialogs to complete, in seconds

param timeout:	Time to wait for dialogs to complete, in seconds

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.

Argument	Type	Default value	Description
dialog	Dialog	null	An instance of a Dialog
timeout	int	300	Time to wait for dialog to complete, in seconds

param dialog:	An instance of a Dialog
param timeout:	Time to wait for dialog to complete, in seconds

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.