Difference between revisions of "Nyquist Plug-ins Widgets"

Latest revision as of 20:01, 9 April 2023

Slider Widget

Slider widgets are supported in all Audacity Nyquist plug-in versions.

 ;control VARIABLE-NAME "text-left" variable-type "text-right" initial-value minimum maximum

• 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 plug-in.
• 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 plug-in 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 plug-ins should use "float" as the variable type for floating point input.

Numeric Text Widget

The numeric text widget was introduced in Audacity 2.1.2.

 ;control VARIABLE-NAME "text-left" variable-type "text-right" initial-value minimum maximum

• 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 plug-in.
• 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:

 ;control POS "Positive Integer" int-text "text-right" initial-value 0 nil
 ;control NEG "Negative Integer" int-text "text-right" initial-value nil 0
 ;control NUM "Any number" float-text "text-right" initial-value nil nil

String Widget (text input)

The text input widget ("string widget") is supported in plug-ins version 2 or above.

 ;control VARIABLE-NAME "text-left" string "text-right" "default-string"

• 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 plug-in window can be referred as a string variable from within the plug-in 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 Plug-in.

Multiple-Choice Widget

The multiple choice input widget is supported in plug-ins version 3 or above.

 ;control VARIABLE-NAME "text-left" choice "string-1,string-2,..." initial-value

• 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 plug-in.

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 plug-in code.

An example of the 'choice' widget can be found sample-data-export.ny

Time Widget

Introduced in Audacity 2.3.0.

 ;control VARIABLE-NAME "text-left" time "text-right" initial-value minimum maximum

• 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:

 ;control DUR "Duration (60s max)" time "" 1 0.0 60

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.

File-Button Widget

The File Button Widget requires Audacity 2.3.0 or later.

 ;control VARIABLE-NAME "text-left" file "button-text" "default-file-path" "wildcard-filters" "flags"

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

For more information about the File-Button Widget, see the Nyquist File-Button Tutorial.

Text Widget

The text widget was introduced in Audacity 2.3.0. Although not actually a "control", it shares similar syntax to all other Nyquist plug-in widgets:

 ;control text "string"

This widget adds a line of text (the "string") to the plug-in GUI.

While it may seem convenient to add text to an interface to explain how the plug-in should be used, this widget should be used sparingly. Text descriptions should not be used as a substitute for good design. Plug-in developers should also be aware that it is not currently possible to provide localization (translations) of text in any widgets in third party plug-ins.

|< Nyquist Plug-ins Reference