< Previous | Contents | Manuals Home | Boris FX | Next >
User Interfaces
You can use the Dialog object to display a user interface for your exporter, importer, or tool. The user interface can consist of the usual checkboxes, buttons, data entry fields, etc. After creating a dialog, you populate it with fields, show it, then access the data entered as attributes of the dialog object. If the user cancels the displayed dialog, then entire script will be cancelled.
So that the user doesn’t have to keep on re-entering the same settings, each dialog’s final entries are stored away and then restored when that dialog box is shown again. If the operation is Export Again, the dialog box is not shown; the saved data is used instead. The script can cause this data to be reset, potentially when the user hits a button, or always cause the dialog box to be shown. If the script sets a dialog field explicitly, before showing the dialog, then the default and stored values will not be used. Export scripts using this latter explicit set override should probably check Scene.exportAgain and avoid making hidden changes to parameters in this case.
Most of the data-field-creating member function calls require an attribute name, which can be used to read or write the value of the field after the dialog is shown, and a prompt string, which is displayed in the user interface to explain what must be entered in the field. The attribute name must be a valid SynthEyes identifier name, with no embedded spaces or special characters.
dlg = NewDialog(“uniqid” [, "title"]) Create a new dialog object. The uniqid must
be unique across ALL DIALOGS of ALL SCRIPTS on the user’s system: it is used to identify the identify the settings of this dialog
for when it is re-opened later. It should be a simple alphanumeric string related to the script name. The title is optional, with no specific title the name of the script is used as the dialog title.
dlg.Always() Causes the dialog to be shown even during Export Again operations, when called before Show.
dlg.AddChoice(“attr”, “internal_choice_name”, "user_choice_name") Add
an additional choice to an existing Choice selector. The internal name is the (string) value read or written to the attribute in Sizzle, the external name is what is seen by the user in the drop-down selector. Repeat as many times as needed. Immediately reloads the panel if called after it has been shown. See also ResetChoices().
dlg.AddChoice(“attr”, “choice”) Add an additional choice to an existing
Choice selector. The listed string is used both internally and externally. Repeat as many times as needed. Immediately reloads the panel if called after it has been shown. See also ResetChoices().
dlg.BrowseTags(keyed_list) The keyed_list argument is interpreted as
substitutions to be applied when a file-browse button is clicked for Open(), Save(), or Path(), ie all occurrences of each key are replaced with its corresponding value. This allows locally-interpreted tags to be resolved by the respective browse buttons only if the browse button is pushed, while allowing tags to remain otherwise.
dlg.Button(“funcname”, “prompt”, “btn”) Create a push button. The button
will be labeled btn, and have a description of prompt . The funcname will be called when the button is pushed. It can also be set using SetFunction(). The function can change attribute values and the dialog will update.
See IsChecked/SetChecked for modal highlighting for use with Pick modes.
dlg.Check(“attr”, “prompt”, defv [, funcnm]) Create a checkbox. The defv
controls its initial state, and must be 0 or 1. The string funcnm is an optional function name to be called when the box is clicked. It can also be set using SetFunction().
dlg.Choice(“attr”, “prompt”, “defv”) Add a drop-down choice selector; the user will
be able to select one of the options added with AddChoice. The value of attr is a string: the selected choice, which can be read or written. See also AddChoice() and ResetChoices().
dlg.ChoiceText("attr") Returns the user prompt text for the currently-
selected value for the attribute attr. Useful for retrieving the human-readable version for choices that generate numeric codes for software use.
dlg.Close() Software-initiated close of the dialog. dlg.Detach( keepGoing) Create a detached (modeless) dialog. See
below. This line will terminate execution of the current function all or script. However, if there is an optional argument keepGoing with a value of 1 or more, execution will continue, allowing additional control-panel configuration operations to be performed before terminating the script (with the panel remaining open).
See discussion session below. dlg.EditableChoice(“attr”, “prompt”, “defv”) Creates a choice selector
equivalent to Choice(), except if the user double-clicks on the text, a dialog will appear that permits the user to change the text, after which the callback will be called. The callback must do a bit of work to keep track of the index of the currently-selected item (when the selection changes without the text changing), so that when the attribute value isn’t found in the list, the correct choice list element can be changed. After that the callback should call ResetChoices() and reload the choice set.
Note that this type is typically built with the two-argument version of AddChoice where the internal and external display text strings are the same, not the three-argument version.
dlg.Enable(“attr”, 0/1) Enable or disable the control(s) for this
attribute. The control must already be visible, ie in a Detach() call.
dlg.Float(“attr”, “prompt”, minv, defv, maxv) Create a floating-point input field.
The input will have an initial value of defv, and must fall within the range of minv to maxv.
dlg.HasAttribute("attr") Check whether this attribute exists in the dialog.
dlg.Hidden(“attr”, “defval”) Create a hidden string-valued attribute to
store extra information (such as compression method) without it being visible to the user, typically stored in response to a button push. The final field value is stored and restored just like a normal string field.
dlg.HidePresetButtons() The Default, Load, and Save buttons won’t be
displayed (on non-detached panels; detached panels don’t have them in the first place. Use this function when the Load/Save buttons aren’t appropriate for the panel’s functionality.
dlg.Info(“attr”, “prompt”, “info”) Create an unchangeable text input field. This
can be used to provide additional explanatory text to the user, perhaps to show other information such as the number of frames or image resolution.
dlg.Int(“attr”, “prompt”, minv, defv, maxv) Create an integer input field. The input
will have an initial value of defv, and must fall within the range of minv to maxv.
dlg.IsChecked(“attr”) The attribute must be a button, checkbox or
radio button. This call returns 0/1 depending on whether the item is currently checked (highlighted). Returns null if the attribute isn’t found. Typically for use with Pick operations. See SetChecked.
dlg.IsEnabled(“attr”) Returns 0/1 depending on whether the attribute is currently enabled (highlighted).
dlg.OpenFile(“attr”, “prompt”, “extn”) Create a data-entry field for a file name,
presumably to be read by the script (the file must exist). There will be a browse button as well as a text field. The extn is the file-name extension to use, or a space-separated list of extensions, or leave it empty for any file type. Set dlg.attr to define an initial filename. Note that it is up to the script to actually read the file. Use SetFunction to define an optional function to be called for user typing or after a file name is set.
dlg.Path(“attr”, “prompt” [, defv]) Create a data-entry field for a path (folder)
name with an initial value. The default value can be omitted. Use SetFunction to define an optional function to be called for user typing or after a file name is set.
dlg.Radio(“attr”, “prompt”, defv [, funcname]) Create a radio button. See also
StartRadio(). Only one radio button must have defv of 1, the rest should have defv of 0. If a string funcname is present, the function of that name is called when the button is pushed. It can also be set using SetFunction().
dlg.Reset() The dialog values are reset to the default values set by the script, overriding previously- stored values. Can be called during a pushbutton function evaluation, or immediately before a show to prevent values from a previous execution of the script from being used.
dlg.ResetChoices() Clear the set of choices so they can be reloaded. ResetChoices() and AddChoices() both act immediately (reloading the panel) if the panel is already displayed.
dlg.SaveFile(“attr”, “prompt”, “extn”) Create a data-entry field for a file name,
presumably to be written (the user must approve the over-write if the file already exists). The extn is the file-name extension to use, or a space-separated list of extensions, or leave it empty for any file type. Set dlg.attr to define an initial filename. Use SetFunction to define an optional function to be called for user typing or after a file name is set.
dlg.Separator(“attr”, fraction) Add vertical spacing between (groups of)
dialog attributes. The fraction is a fraction of the nominal vertical spacing, ie 1.0 is a full control’s worth; typically something like 0.5 will be good. The attribute name should be unique versus the others but is otherwise not too significant. You can examine the spacing and change it, but the value is only effective as the panel is built, not later.
dlg.SetChecked(“attr”, value) The attr must correspond to a button or
checkbox, or radio button. The selected item(s) become checked (highlighted) or not depending on the value. Typically used with Pick modes.
dlg.SetFunction(“attr”, “funcnm”) Define a function name that will be called
when the corresponding control is clicked. Set the function name to the empty string “” to remove a function. Affects buttons,
checkboxes, choices, radio buttons, strings, OpenFile, SaveFile, and Path.
dlg.SetPaired(“attr", 0/1) Use to give a button or checkbox attribute a
“paired” status before the dialog is shown. This is used for the second consecutive item to put the second one onto the same line of the dialog as the first, for a more compact layout.
dlg.SetPrecheck(“funcname”) Put a precheck function on the dialog; the
precheck function is called when the user clicks OK on the dialog, to give the function a change to examine the scene and dialog settings, potentially adjusting them. If the return value is 1, the OK happens normally and the dialog closes. If the return value is zero, the OK click is ignored, typically after other actions are taken by the function. If the return value is -1, the dialog and script execution is cancelled (ie after the function puts up another dialog with a cancel button). The Precheck function runs during Export Again before the dialog does not appear. If the Precheck function returns 0, then the dialog will appear and Scene.exportAgain will be zero. If the function returns 1, the dialog won’t appear, and if it returns -1, the script is cancelled.
dlg.SetTip("attr", "tooltip text") (SetTip preferred but also .SetToolTip,
.SetTTip, .SetTooltip). Sets a tooltip for the given attribute name, to better explain what the control is for. Tooltips must all be set before calling .Show to display the dialog.
dlg.Show() Display the assembled dialog and wait for user action. If this is an Export Again, the dialog will not be shown, but will have the saved settings. (See the Always function.)
dlg.StartRadio(“overall_name”, “overall_prompt”) Start a group of radio
buttons. The overall_name attribute will be set to the name of the attribute that is selected.
dlg.String(“attr”, “prompt”, “defstr”) Create a text input field. The defstr value is its
default value when the dialog is first displayed, or after a reset operation. Call SetFunction to supply a function to be called whenever the value of the field is changed.
Here’s an example of a small settings panel.
dlg = NewDialog(“MyFavorite”)
dlg.Int(“f1st”, “Start Frame”, 0, 0, shot.length) dlg.Check(“abs”, “Use Absolute Coordinates”, 0) dlg.StartRadio(“which”, “Trackers to Output”) dlg.Radio(“all”, “All”, 1)
dlg.Radio(“sel”, “Only selected”, 0) dlg.Button(“reset_dlg”, “Reset to defaults”, “Reset”) dlg.Show()
only_sel = dlg.sel bias = dlg.f1st
function reset_dlg() dlg.Reset()
end
You can use several dialogs (and dialog objects) within a single script, one after another, if necessary.
©2025 Boris FX, Inc. — UNOFFICIAL — Converted from original PDF.