Eyeon:Script/Reference/Applications/Fusion/Classes/Composition/AskUser
From VFXPedia
Contents |
Composition : AskUser
Arguments
AskUser(name, { table of inputs } )
Each input is a table structured as follows :
- {Input Name, Input Type, Options ...}
This name is the index value for the controls value as set by the user (i.e. dialog.Control or dialog["Control Name"]). It is also the label shown next to the control in the dialog, unless the Name option is also provided for the control.
A string value describing the type of control to display. Valid strings are FileBrowse,PathBrowse, Position, Slider, Screw, Checkbox, Dropdown, and Text. Each Input type has its own properties and optional values, which are described below.
Different control types accept different options that determine how that control appears and behaves in the dialog. |
Returns
Returns a table containing the responses from the user, or nil if the user cancels the dialog.
Remarks
The AskUser function displays a dialog to the user, requesting input using a variety of common fusion controls such as sliders, menus and textboxes. All script execution stops until the user responds to the dialog by selecting OK or Cancel. This function can only be called interactively, command line scripts cannot use this function.
The second argument of this function recieves a table of inputs describing which controls to display. Each entry in the table is another table describing the control and its options. For example, if you wanted to display a dialog that requested a path from a user, you might use the following script.
Requirements
- eyeonScript 5.0
- Fusion 5.0
Examples
dialog = {} dialog[1] = {"Select a Directory","PathBrowse"} ret = composition:AskUser("A Sample Dialog", dialog )''' dump(ret)
You could also have built this example dialog without first
constructing the variable 'dialog' by constructing the tables within the AskUser function itself, as shown below.
Examples
ret = composition:AskUser("A Sample Dialog", { {"Select a Directory", "PathBrowse"} } ) dump(ret)
To add a second control to this dialog, you simply add a new table to the list of controls.
Examples
dialog = {} dialog[1] = {"Select a Directory", "PathBrowse"} dialog[2] = {"A Check Box", "Checkbox", Default = 1} ret = composition:AskUser("A Sample Dialog", { dialog }) dump(ret) ret = composition:AskUser("A Sample Dialog", { {"Select a Directory", "PathBrowse"}, {"A Check Box", "Checkbox", Default = 1} } ) dump(ret)
The AskUser() function returns a table of values containing the responses from the user. The table is organized as {control name = value, control name = value}. So the return value from our above example (as shown by dump()) might be :
table: 00A2D118 Select a Directory = C:\Izyk\Fusion\ A Check Box = 1
If we wanted to test against the return value of our checkbox, we might write code like this :
if ret["A Check Box"] == 1 then print("Hello!")''' end
The name "A Check Box" is automatically used as the index for the checkbox controls return value. That's not a very friendly name for an index, it would be easier if we could just test ret.controlname instead of ret["controlname"]. We could use the name option of the Checkbox control to specify our own label, and use something a little easier for the name of the control as eyeonScript sees it.
Examples
ret = composition:AskUser("A Sample Dialog", { {"dlgDir", Name = "Select a Directory", "PathBrowse"}, {"dlgCheck", Name = A Check Box", "Checkbox", Default = 1} } ) if ret.aCheck == 1 then print("Hello!") end
Each control has it own list of options, as described below.
Control Types
|
Text |
Displays the Fusion textedit control, which is used to enter large amounts of Text into a control. |
A number specifying how many lines of text to display in the control.
A true or false value that determines whether the text entered into this control will wrap to the next line when it reaches the end of the line.
If this option is set to true the control will not allow any editing of the text within the control. Use for displaying non-editable information.
The name of a true type font to use when displaying text in this control.
A number specifying the font size used to display the text in this control. |
|
FileBrowse PathBrowse |
The FileBrowse input allows you to browse to select a file on disk, while the PathBrowse input allows you to select a directory. |
Set this option to true if the dialog is used to select a path or file which does not yet exist (i.e. when selecting a file to save to) |
|
Slider |
Displays a standard Fusion slider control. Labels can be set for the high and low ends of the slider using the following options. |
The text label used for the low (left) end of the slider.
The text label used for the high (right) end of the slider. |
|
Checkbox |
Displays a Fusion standard checkbox control. You can display several of these controls next to each other using the NumAcross option. |
The default state for the checkbox, use 0 to leave the checkbox deselected, or 1 to enable the checkbox. Defaults to 0 if not specified.
If the NumAcross value is set the dialog will reserve space to display two or more checkboxes next to each other. The NumAcross value must be set for all checkboxes to be displayed on the same row. See examples below for more information. |
|
Position |
Displays a pair of edit boxes used to enter X & Y co-ordinates for a center control or other positional value. The default value for this control is a table with two values, one for the X value and one for the Y value. This control returns a table of values. |
A table with two numeric entries specifying the value for the x and y co-ordinates. |
|
Screw |
Displays the standard Fusion thumbwheel or screw control. This control is identical to a slider in almost all respects except that its range is infinite, and so it is well suited for angle controls and other values without practical limits. |
|
|
Dropdown |
Displays the standard Fusion drop down menu for selecting from a list of options. This control exposes an option called Options which takes a table containing the values for the drop down menu. Note that the index for the Options table starts at 0, not 1 like is common in most eyeonScript tables. So if you wish to set a default for the first entry in a list, you would use Default = 0, for the second Default = 1, and so on. |
A number specifying the index of the options table (below) to use as a default value for the drop down box when it is created.
A table of strings describing the values displayed by the drop down box. |
Generic Control Options
Several of the Options are common to several controls. For example, the name option can be used with any type of control, and the DisplayedPrecision option can be used with any control that displays and returns numeric values. The commonly used options for controls are described here :
- Name (string)
This option can be used to specify a more reasonable name for this inputs index in the returned table than the one used as a label for the control.
- Default (string)
The default value displayed when the control is first shown.
- Min (integer)
Sets the minimum value allowed by the slider or screw control.
- Max (numeric)
Sets the maximum value allowed by the slider or screw control.
- DisplayedPrecision (numeric)
Use this option to set how much precision is used for numeric controls like sliders, screws and position controls. A value of 2 would allow two decimal places of precision - i.e. 2.10 instead of 2.105
- Integer (boolean)
If true the slider or screw control will only allow integer (non decimal) values, otherwise the slider will provide full precision. Defaults to false if not specified.
Examples
-- This example shows a dialog that contains all of the various control types composition_path = composition:GetAttrs().COMPS_FileName msg = "This dialog is only an example. It does not actually do anything, ".. "so you should not expect to see a useful result from running this script." d = {} d[1] = {"File", Name = "Select A Source File", "FileBrowse", Default = composition_path} d[2] = {"Path", Name = "New Destination", "PathBrowse" } d[3] = {"Copies",Name = "Number of Copies", "Slider", Default = 1.0, Integer = true, Min = 1, Max = 5 } d[4] = {"Angle", Name = "Angle", "Screw", Default = 180, Min = 0, Max = 360} d[5] = {"Menu", Name = "Select One", "Dropdown", Options = {"Good", "Better", "Best"}, Default = 1} d[6] = {"Center",Name = "Center", "Position", Default = {0.5, 0.5} } d[7] = {"Invert",Name = "Invert", "Checkbox", NumAcross = 2 } d[8] = {"Save", Name = "Save Settings", "Checkbox", NumAcross = 2, Default = 1 } d[9] = {"Msg", Name = "Warning", "Text", ReadOnly = true, Lines = 5, Wrap = true, Default = msg} dialog = composition:AskUser("A Sample Dialog", d)''' if dialog == nil then print("You cancelled the dialog!") else dump(dialog) end
Tips for AskUser (edit)
- Fusion 6.1 build 697 added "Multibutton". Usage is identical to Dropdown.
- Fusion 6.2 now allows "ClipBrowse" rather than "FileBrowse" to get sequence gathering and appropriate file filters.
AskUser in Python
The AskUser function in Python expects a dictionary object but you can't use the "syntactic sugar" of LUA tables, which allows you to omit indices. You have to add 1, 2 and so on and you have to use strings for key names (like "Default") as well. So this is the Python version of one of the examples above:
dialog = {1: {1: "dlgDir", "Name": "Select a Directory", 2: "PathBrowse"}, 2: {1: "dlgCheck", "Name": "A Check Box", 2: "Checkbox", "Default": 1}} ret = composition.AskUser("A sample dialog", dialog)
This is an example of a dropdown list. It's a good idea to build the nested dictionaries step by step instead of all at once.
dropdown = {1: "ping", 2: "pong"} dialog = {} dialog[1] = {1: "choice", 2: "Dropdown", "Options": dropdown} comp.AskUser("This is a dropdown", dialog)
AskUser returns a dictionary of return values or "None" if the dialog was canceled.
