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

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

dlg.SetTooltip("attr", "tooltip text") (Also .SetToolTip, .SetTTip, .SetTip). 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 >