< 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.

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.

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.

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.

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.Detach() Create a detached (modeless) dialog. See below. This line will terminate execution of the script.

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.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.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 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 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.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 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.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, OpenFile, SaveFile, and Path.

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.

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.

Detached Panels

< Previous | Contents | Manuals Home | Boris FX | Next >