Widgets Reference
Last updated
Last updated
A Widget is an element of a graphical user interface (GUI), such as a button or slider, which facilitates user interaction. Audacity supplies a number of widget types for Nyquist plugins, which are ultimately derived from the WxWidgets toolkit. Fortunately, Nyquist plugin developers are largely spared from the complexities of WxWidgets, and can simply select which widgets they need by adding the appropriate "header" to the top of the plugin script.
The layout of a Nyquist plugin GUI is a simple list of widgets, one above the other.
Slider widgets are supported in all Audacity Nyquist plugin versions.
variable-name : [symbol] A Lisp symbol.
text-left : [string] Text that will appear to the left of the slider.
variable-type : [keyword] A "number" type, either int, float or real*:
int : integer [FIXNUM, an XLISP whole number]
float (or real*) : floating point [FLONUM, an XLISP number supporting decimal places]
text-right : [string] Text that will appear to the right of the slider.
initial-value : [int / float] Variable value [and slider position] at the first start of the plugin.
minimum : [int / float] Numeric variable value when the slider is moved to the left border.
maximum : [int / float] Numeric variable value when the slider is moved to the right border.
The variable value [the slider position] can be referenced by the variable name in the plugin code.
A text input box to the left of the slider allows the user to type in a value via the keyboard. As of Audacity 2.1.1, input values are validated to only allow input between minimum and maximum values.
The "real" keyword is deprecated. New plugins should use "float" as the variable type for floating point input.
The numeric text widget was introduced in Audacity 2.1.2.
variable-name : [symbol] A Lisp symbol.
text-left : [string] Text that will appear to the left of the text box.
variable-type : [keyword] A "number" type, either "int-text" or "float-text":
int-text : Integer [FIXNUM, an XLISP whole number]
float-text : Floating point [FLONUM, an XLISP number supporting decimal places]
text-right : [string] Text that will appear to the right of the text box.
initial-value : [int / float] Variable value at the first start of the plugin.
minimum : [int / float / NIL] Numeric minimum variable value that will pass validation.
maximum : [int / float / NIL] Numeric maximum variable value that will pass validation.
Minimum and maximum may be numeric values or "NIL". The minimum / maximum is not defined when set as "NIL" and is limited only by the numeric limit for the number type. The valid range for numbers depends on the computer platform. Typically the limits for integers are -2147483648 to 2147483647. The limits for floating point numbers are very large.
Examples of undefined minimum / maximum:
The text input widget ("string widget") is supported in plugins version 2 or above.
variable-name : [symbol] A Lisp symbol.
text-left : [string] Text that will appear to the left of the text input field.
variable-type : [keyword] Declares a "string" input type widget.
text-right : [string] Text that will appear to the right of the text input field.
default-string : [string] The string will appear inside the text field.
The text typed in by the user in the text field of the plugin window can be referred as a string variable from within the plugin code. All string characters are valid, though care must be taken with escape characters if the string is to be evaluated.
Examples how to use the text input widget can be found in the source code of the Apropos Plugin.
The multiple choice input widget is supported in plugins version 3 or above.
variable-name : [symbol] A Lisp symbol.
text-left : [string] Text that will appear to the left of the multiple-choice list.
variable-type : [keyword] Declares a "Multiple-Choice" type widget.
string-1,... : [string] For every string an entry in a list to choose from will be produced.
initial-value : the number of the list entry that will be displayed as the default choice at the first start of the plugin.
The list entries string-1, string-2, etc. are comma separated and internally represented by integer numbers. The first, top-most list entry string-1 will be represented by the number 0. The list entry chosen by the user can be determined by the integer value of the variable from within the plugin code.
An example of the 'choice' widget can be found sample-data-export.ny
Introduced in Audacity 2.3.0.
variable-name : [symbol] A Lisp symbol.
text-left : [string] Text that will appear to the left of the time control.
time : [keyword] A "time" widget.
text-right : [string] Text that will appear to the right of the time control.
initial-value : [int / float] Default value. Number (float or integer) in seconds.
minimum : [number] Minimum numeric value (float or integer) in seconds.
maximum : [number] Maximum numeric value (float or integer) in seconds.
Minimum and maximum may be numeric values or "NIL". The minimum / maximum is not defined when set as "NIL" and is limited to a range of 0 and the maximum supported by the current widget view.
This widget is to input durations. The value set is converted to seconds and assigned as the value of the widget variable.
Example taken from the Pluck effect:
In this example:
variable name is "dur",
text-left is "Duration (60s max)",
text-right is "" (empty string).
initial-value is 1 second.
minimum is 0.0 seconds.
maximum is 60 seconds.
The File Button Widget requires Audacity 2.3.0 or later.
variable-name : [symbol] A Lisp symbol.
text-left : [string] Text that will appear to the left of the file button widget.
variable-type : [keyword] Declares a "File-button" type widget.
button text : [string] Text that appears on the button.
default-file-path : [string] The default file path.
wildcard-filters : [string] File types to show in file browser (based on file extensions).
flags : [string] Option flags, based on wxWidgets File Dialog Styles).
The text widget was introduced in Audacity 2.3.0. Although not actually a "control", it shares similar syntax to all other Nyquist plugin widgets:
This widget adds a line of text (the "string") to the plugin GUI.
Best practice: While it may seem convenient to add text to an interface to explain how the plugin should be used, this widget should be used sparingly. Text descriptions should not be used as a substitute for good design. Plugin developers should also be aware that it is not currently possible to provide localization (translations) of text in any widgets in third party plugins.
