File chooser

The File chooser provides easy access to your file system.

It works in two modes:

• Upload — Allows you to access files from your storage during runtime and refer to them in the action code. When a file is uploaded to the model folder, the engine executes the user action code.
• Download — Allows you to save data provided by the model. During runtime, the file chooser waits for a file with a specified name to appear in the system, then becomes enabled. To download the file, click the file chooser control.

Take a look at this simple demo model where the File chooser is combined with a Text file element to allow you to select a file before starting the model:

To add a file chooser

1. Drag the  File Chooser element from the Controls palette into the graphical editor.
2. Go to the Properties section.
3. Select the type of your file chooser. For data input, select Upload. Your file will be stored in the model folder as read-only. If you need to obtain data from the model, select Download. You will have access to the file as soon as it is generated.
4. In the Action field, you can enter the code to execute each time a file is uploaded or downloaded using the file chooser. This code can read the file and use the data in the model. The relative name of a selected file is available here as a local String variable named value.

General

Name — The name of the element. It is used to identify and access the control from code.

Show name — Specifies if the file chooser name is displayed next to the control.

Lock — Specifies if the file chooser is fixed on the canvas. You cannot move or select a locked element in the graphical editor.

Ignore — If selected, the element is excluded from the model.

Type — Specifies the type of the dialog. Select Upload if you need to upload files to the model and read the data. Select Download if you plan to use this control to obtain data from the model.

Title — The title of the file chooser. While Name is used to refer to the control in code and may be displayed next to the the control, the Title appears inside the box (if the field is not empty).

File name filters — [Visible if Type: Upload] In this field, specify the file extensions your file chooser will accept.

File — [Visible if Type: Download] In this field, specify a name for the future file.

Action — The code to execute when the user uploads or downloads a file through the file chooser. The relative name of a selected file is available here as a local String variable named value.

Appearance

Enabled — Specifies whether the file chooser is active during runtime using a Boolean expression or a check box.

Background color — Defines the background color for the dialog box. Click the control and pick a color from a range of the most popular ones or choose a custom color using the Colors dialog box.

Only using Windows with the classic theme can assure the correct behavior of this feature. Other operating systems may not support file choosers with custom background colors.

Text color — Defines the text color for the dialog box. Click the control and pick a color from a range of the most popular ones or choose a custom color using the Colors dialog box.

Font — Adjusts the size of the text inside the file chooser using a drop-down menu.

Italic — If selected, the text inside the file chooser will be italicized.

Bold — If selected, the text inside the file chooser will be emphasized in bold.

Position and size

Level — The level this control belongs to.

X — The X-coordinate of the control’s upper left corner.

Y — The Y-coordinate of the control’s upper left corner.

Width — The width of the control (in pixels).

Height — The height of the control (in pixels).

Visibility and presentation

Visible — If selected, the file chooser is shown during runtime. To introduce a dynamic value, click the  button and enter the code in the input field. The control will be visible when the specified expression evaluates to true.

Agent presentation — If selected, the control is included in the agent presentation. This means that if the agent hosting this control is embedded in another agent, the control will remain visible.

Agent icon — If selected, the file chooser will be considered a part of the agent’s icon.

Expert

Replication — The number of copies of this control that you want created. If this field is left empty, only one control will be created. This field can be set to a dynamic expression.

Obtaining and assigning values

Function	Description
String getValue()	Returns the name of the selected file. If no file is selected, returns an empty String.
void setValue(String fileName)	Assigns a file name to a fileName variable. Does not execute the user action code. fileName — the file name.
void setValue(String fileName, boolean callAction)	Assigns a file name to a fileName variable. Executes the user action code (if there is any) when the callAction parameter is true. fileName — the file name. callAction — if true, the existing user action code will be executed.
void setValueToDefault()	Assigns a default value to the file chooser. Does not execute the user action code.

Enabling and disabling

Function	Description
boolean isEnabled()	Tests if the control is enabled (returns true) or disabled (returns false).
void setEnabled(boolean yes)	Sets the control as enabled or disabled in runtime. yes — The file chooser will be enabled if true and disabled if false.

Executing the action

Function	Description
void action()	Executes the action associated with the file chooser.

Position

Function	Description
double getX()	Returns the X-coordinate of the control (upper left corner).
double getY()	Returns the Y-coordinate of the control (upper left corner).
void setX(double x)	Assigns the X-coordinate to the control (upper left corner). x — the new X-coordinate value.
void setY(double y)	Assigns the Y-coordinate to the control (upper left corner). y — the new Y-coordinate value.
void setPos(double x, double y)	Assigns new coordinates to the control (upper left corner). x — the new X-coordinate value. y — the new Y-coordinate value.

Size

Function	Description
double getWidth()	Returns the width of the control in pixels.
double getHeight()	Returns the height of the control in pixels.
void setWidth(double width)	Assigns width as the width of the control in pixels.
void setHeight(double height)	Assigns height as the height of the control in pixels.

Visibility

Function	Description
boolean isVisible()	Returns the visibility of the control.
void setVisible(boolean v)	Sets the visibility of the control. v — visibility: if true, the control is set to be visible, if false, it is not.

Group

Function	Description
ShapeGroup getGroup()	Returns the group containing this control.

Level

Function	Description
Level getLevel()	Returns the level on which this control is located.

How can we improve this article?

Send