diff --git a/definitions b/definitions index 413fe286..08faaea7 160000 --- a/definitions +++ b/definitions @@ -1 +1 @@ -Subproject commit 413fe286d0b6e51fd2fc47c0aadbd26a1a3c29ba +Subproject commit 08faaea744156f2f7eddc898eb46fd972453a1af diff --git a/docs/API/modules/bit.md b/docs/API/modules/bit.md deleted file mode 100644 index 356fb7ca..00000000 --- a/docs/API/modules/bit.md +++ /dev/null @@ -1,95 +0,0 @@ -# bit -> Integer, Bit Operations, provided by -> -> [Documentation](http://bitop.luajit.org/api.html) - - - - ---- -## Functions -### tobit(x : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Normalizes a number to the numeric range for bit operations and returns it. -> This function is usually not needed since all bit operations already normalize -> all of their input arguments. Check the operational semantics for details. -### tohex(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)[`?`](../../API/builtins/nil.md)) -> Converts its first argument to a hex string. The number of hex digits is -> given by the absolute value of the optional second argument. Positive numbers -> between 1 and 8 generate lowercase hex digits. Negative numbers generate -> uppercase hex digits. Only the least-significant 4*|n| bits are used. The -> default is to generate 8 lowercase hex digits. -### bnot(x : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise **not** of its argument. -### band(x1 : [`integer`](../../API/builtins/integer.md), ...[`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise and of all of its arguments. Note that more than two -> arguments are allowed. -### bor(x1 : [`integer`](../../API/builtins/integer.md), ...[`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise or of all of its arguments. Note that more than two -> arguments are allowed. -### xor(x1 : [`integer`](../../API/builtins/integer.md), ...[`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise xor of all of its arguments. Note that more than two -> arguments are allowed. -### lshift(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise logical left-shift of its first argument by the number of -> bits given by the second argument. -> -> Logical shifts treat the first argument as an unsigned number and shift in -> 0-bits. Arithmetic right-shift treats the most-significant bit as a sign bit -> and replicates it. Only the lower 5 bits of the shift count are used (reduces -> to the range [0..31]). -### rshift(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise logical right-shift of its first argument by the number of -> bits given by the second argument. -> -> Logical shifts treat the first argument as an unsigned number and shift in -> 0-bits. Arithmetic right-shift treats the most-significant bit as a sign bit -> and replicates it. Only the lower 5 bits of the shift count are used (reduces -> to the range [0..31]). -### arshift(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns the bitwise arithmetic right-shift of its first argument by the -> number of bits given by the second argument. -> -> Logical shifts treat the first argument as an unsigned number and shift in -> 0-bits. Arithmetic right-shift treats the most-significant bit as a sign bit -> and replicates it. Only the lower 5 bits of the shift count are used (reduces -> to the range [0..31]). -### rol(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns bitwise left rotation of its first argument by the number of bits -> given by the second argument. Bits shifted out on one side are shifted back -> in on the other side. -> -> Only the lower 5 bits of the rotate count are used (reduces to the range -> [0..31]). -### ror(x : [`integer`](../../API/builtins/integer.md), n : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Returns bitwise right rotation of its first argument by the number of bits -> given by the second argument. Bits shifted out on one side are shifted back -> in on the other side. -> -> Only the lower 5 bits of the rotate count are used (reduces to the range -> [0..31]). -### bswap(x : [`integer`](../../API/builtins/integer.md)) -`->`[`integer`](../../API/builtins/integer.md) - -> Swaps the bytes of its argument and returns it. This can be used to convert -> little-endian 32 bit numbers to big-endian 32 bit numbers or vice versa. - diff --git a/docs/API/renoise.md b/docs/API/renoise.md index c0800152..22cd8347 100644 --- a/docs/API/renoise.md +++ b/docs/API/renoise.md @@ -6,7 +6,7 @@ ## Constants ### API_VERSION : [`number`](../API/builtins/number.md) -> Currently 6.1. Any changes in the API which are not backwards compatible, +> Currently 6.2. Any changes in the API which are not backwards compatible, > will increase the internal API's major version number (e.g. from 1.4 -> 2.0). > All other backwards compatible changes, like new functionality, new functions > and classes which do not break existing scripts, will increase only the minor diff --git a/docs/API/renoise/renoise.Application.md b/docs/API/renoise/renoise.Application.md index 53660d01..d7db8cc5 100644 --- a/docs/API/renoise/renoise.Application.md +++ b/docs/API/renoise/renoise.Application.md @@ -24,12 +24,36 @@ ### installed_tools : table<[`string`](../../API/builtins/string.md), [`string`](../../API/builtins/string.md)> > **READ-ONLY** Returns information about all currently installed tools. +### installed_tools_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Fired when the list of installed tools changed. + +### audio_plugin_effects_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Fired when the list of available audio plugin effects changed, for example +> when scanning for new plugins in the preferences. +> Use the component's `available_plugins` or `available_devices` properties +> to access currently available devices which are supported by the component +> such as the track device chains. + +### audio_plugin_instruments_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Fired when the list of available audio plugin instruments changed, for example +> when scanning for new plugins in the preferences. + ### key_modifier_states : table<[`string`](../../API/builtins/string.md), [`string`](../../API/builtins/string.md)> +> **Deprecated.** **READ-ONLY** Use `key_modifier_flags` instead + +### key_modifier_flags : [`ModifierFlags`](#ModifierFlags) > **READ-ONLY** Access keyboard modifier states. ### window : [`renoise.ApplicationWindow`](../../API/renoise/renoise.ApplicationWindow.md) > **READ-ONLY** Access to the application's window. +### theme : [`renoise.ApplicationTheme`](../../API/renoise/renoise.ApplicationTheme.md) +> **READ-ONLY** Access to the application's color theme. + +### theme_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Fired, when *any* theme color changed. e.g. when a new theme got loaded +> or when theme colors got edited in the theme preferences. + ### active_clipboard_index : `1` | `2` | `3` | `4` > Range: (1 - 4) Get or set globally used clipboard "slots" in the application. @@ -50,17 +74,23 @@ > Opens a modal dialog with a title, text and custom button labels. > Returns the pressed button label or an empty string when canceled. -### show_custom_prompt([*self*](../../API/builtins/self.md), title : [`string`](../../API/builtins/string.md), content_view : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), button_labels : [`string`](../../API/builtins/string.md)[], key_handler : [`KeyHandler`](#KeyHandler)[`?`](../../API/builtins/nil.md), key_handler_options : [`KeyHandlerOptions`](#keyhandleroptions)[`?`](../../API/builtins/nil.md)) +### show_custom_prompt([*self*](../../API/builtins/self.md), title : [`string`](../../API/builtins/string.md), content_view : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), button_labels : [`string`](../../API/builtins/string.md)[], key_handler : [`KeyHandler`](#KeyHandler)[`?`](../../API/builtins/nil.md), key_handler_options : [`KeyHandlerOptions`](#keyhandleroptions)[`?`](../../API/builtins/nil.md), focus_handler : [`FocusHandler`](#FocusHandler)[`?`](../../API/builtins/nil.md)) `->`label : [`string`](../../API/builtins/string.md) -> Opens a modal dialog with a title, custom content and custom button labels. -> See: [renoise.ViewBuilder](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/viewbuilder.lua#17#10) for more info about custom views. -### show_custom_dialog([*self*](../../API/builtins/self.md), title : [`DialogTitle`](#DialogTitle), content_view : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), key_handler : [`KeyHandler`](#KeyHandler)[`?`](../../API/builtins/nil.md), key_handler_options : [`KeyHandlerOptions`](#keyhandleroptions)[`?`](../../API/builtins/nil.md)) +> Opens a modal dialog with a title, custom content and custom button labels. +> See: `renoise.ViewBuilder` for more info about custom views. +### show_custom_dialog([*self*](../../API/builtins/self.md), title : [`DialogTitle`](#DialogTitle), content_view : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), key_handler : [`KeyHandler`](#KeyHandler)[`?`](../../API/builtins/nil.md), key_handler_options : [`KeyHandlerOptions`](#keyhandleroptions)[`?`](../../API/builtins/nil.md), focus_handler : [`FocusHandler`](#FocusHandler)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Dialog`](../../API/renoise/renoise.Dialog.md) -> Shows a non modal dialog (a floating tool window) with custom content. +> Shows a non modal dialog (a floating tool window) with custom content. > When no key_handler is provided, the Escape key is used to close the dialog. -> See: [renoise.ViewBuilder](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/viewbuilder.lua#17#10) for more info about custom views. +> See: `renoise.ViewBuilder` for more info about custom views. +### show_menu([*self*](../../API/builtins/self.md), dialog : [`renoise.Dialog`](../../API/renoise/renoise.Dialog.md), menu_entries : [`DialogMenuEntry`](#dialogmenuentry)[], below_view : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[`?`](../../API/builtins/nil.md)) +> Shows a custom context menu on top of the given dialog. +> +> When specifying a view, the menu will be shown below the given view instance. +> The view instance must be part of the dialog that shows the menu and must be visible. +> By default the menu will be shown at the current mouse cursor position. ### prompt_for_path([*self*](../../API/builtins/self.md), title : [`DialogTitle`](#DialogTitle)) `->`path : [`string`](../../API/builtins/string.md) @@ -98,13 +128,13 @@ > The song is not created immediately, but soon after the call was made and > the user did not aborted the operation. In order to continue execution > with the new song, attach a notifier to 'renoise.app().new_document_observable' -> See: [renoise.ScriptingTool](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/tool.lua#19#10) for more info. +> See: `renoise.ScriptingTool` for more info. ### new_song_no_template([*self*](../../API/builtins/self.md)) > Create a new song document, avoiding template XRNS songs (when present) to be loaded. > The song is not created immediately, but soon after the call was made and > the user did not aborted the operation. In order to continue execution > with the new song, attach a notifier to 'renoise.app().new_document_observable' -> See: [renoise.ScriptingTool](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/tool.lua#19#10) for more info. +> See: `renoise.ScriptingTool` for more info. ### load_song([*self*](../../API/builtins/self.md), filename : [`string`](../../API/builtins/string.md)) > Load a new song document from the given filename (will ask to save > changes if needed, any errors are shown to the user). @@ -216,6 +246,42 @@ --- ## Structs +# DialogMenuEntry +> Defines a custom menu entry, shown in custom dialog windows. +> +> Separating entries: +> To divide entries into groups prepend one or more dashes to the name: +> ```md +> ---First Group Item +> Regular item +> ``` +> +> To create sub menus, define entries with a common path, using a colon as separator: +> ```md +> Main Menu Item +> Sub Menu:Sub Menu Item 1 +> Sub Menu:Sub Menu Item 2 +> ``` +> +> To insert a script menu entry into an existing context menu, see `ToolMenuEntry`. + +--- +## Properties +### name : [`string`](../../API/builtins/string.md) +> Name and optional path of the menu entry + +### invoke : fun() +> A function that is called as soon as the entry is clicked + +### active : [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md) +> Default: true. When false, the action will not be invoked and will be "greyed out". + +### selected : [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md) +> Default: false. When true, the entry will be marked as "this is a selected option" + + + + # KeyEvent --- @@ -224,7 +290,11 @@ > name of the key, like 'esc' or 'a' ### modifiers : [`ModifierStates`](#ModifierStates) -> the held down modifiers as a string +> **Deprecated.** Use `modifier_flags` instead +> **READ-ONLY** the held down modifiers as a string + +### modifier_flags : [`ModifierFlags`](#ModifierFlags) +> **READ-ONLY** the held down modifiers as flags ### character : [`string`](../../API/builtins/string.md)[`?`](../../API/builtins/nil.md) > possible character representation of the key @@ -244,18 +314,26 @@ --- ## Aliases +### ModifierFlags +{ alt : [`boolean`](../../API/builtins/boolean.md), control : [`boolean`](../../API/builtins/boolean.md), meta : [`boolean`](../../API/builtins/boolean.md), shift : [`boolean`](../../API/builtins/boolean.md) } +> The currently pressed/release key's modifiers as platform independent flags. +> On macOS "control" is their "Command" key and the "meta" keyboard is the "Control" key. +> On Windows the "meta" key is the "Windows" key and on Linux the "Super" key. + ### ModifierStates [`string`](../../API/builtins/string.md) -> The modifier keys will be provided as a string. +> **Deprecated.** Use `ModifierFlags` instead. +> +> The modifier keys will be provided as a string. > Possible keys are dependent on the platform > * Windows : "shift", "alt", "control", "winkey" > * Linux : "shift", "alt", "control", "meta" -> * Mac : "shift", "option", "control", "command" -> If multiple modifiers are held down, the string will be formatted as +> * Mac : "shift", "option", "control", "command". +> If multiple modifiers are held down, the string will be formatted as > " + " > Their order will correspond to the following precedence -> `shift + alt/option + control + winkey/meta/command` -> If no modifier is pressed, this will be an empty string +> `shift + alt/option + control + winkey/meta/command` +> If no modifier is pressed, this will be an empty string. @@ -281,9 +359,15 @@ [`string`](../../API/builtins/string.md) > The title that shows up at the title-bar of the dialog. +### FocusHandler +(dialogs : [`renoise.Dialog`](../../API/renoise/renoise.Dialog.md), focused : [`boolean`](../../API/builtins/boolean.md)) `->` [`KeyEvent`](#keyevent)[`?`](../../API/builtins/nil.md) +> Optional focus change notifier for a custom dialog. +> Will be called when the dialog gains of loses key focus. You maybe want to initialize +> your dloag's (modifier) keyboard states here. + ### KeyHandler (dialog : [`renoise.Dialog`](../../API/renoise/renoise.Dialog.md), key_event : [`KeyEvent`](#keyevent)) `->` [`KeyEvent`](#keyevent)[`?`](../../API/builtins/nil.md) -> Optional keyhandler to process key events on a custom dialog. +> Optional keyhandler to process key events on a custom dialog. > When returning the passed key from the key-handler function, the > key will be passed back to Renoise's key event chain, in order to allow > processing global Renoise key-bindings from your dialog. This will not work @@ -291,17 +375,25 @@ > because your dialog will steal the focus from all other Renoise views such as > the Pattern Editor, etc. +### ModifierFlags +{ alt : [`boolean`](../../API/builtins/boolean.md), control : [`boolean`](../../API/builtins/boolean.md), meta : [`boolean`](../../API/builtins/boolean.md), shift : [`boolean`](../../API/builtins/boolean.md) } +> The currently pressed/release key's modifiers as platform independent flags. +> On macOS "control" is their "Command" key and the "meta" keyboard is the "Control" key. +> On Windows the "meta" key is the "Windows" key and on Linux the "Super" key. + ### ModifierStates [`string`](../../API/builtins/string.md) -> The modifier keys will be provided as a string. +> **Deprecated.** Use `ModifierFlags` instead. +> +> The modifier keys will be provided as a string. > Possible keys are dependent on the platform > * Windows : "shift", "alt", "control", "winkey" > * Linux : "shift", "alt", "control", "meta" -> * Mac : "shift", "option", "control", "command" -> If multiple modifiers are held down, the string will be formatted as +> * Mac : "shift", "option", "control", "command". +> If multiple modifiers are held down, the string will be formatted as > " + " > Their order will correspond to the following precedence -> `shift + alt/option + control + winkey/meta/command` -> If no modifier is pressed, this will be an empty string +> `shift + alt/option + control + winkey/meta/command` +> If no modifier is pressed, this will be an empty string. diff --git a/docs/API/renoise/renoise.ApplicationTheme.md b/docs/API/renoise/renoise.ApplicationTheme.md new file mode 100644 index 00000000..260b7230 --- /dev/null +++ b/docs/API/renoise/renoise.ApplicationTheme.md @@ -0,0 +1,264 @@ +# renoise.ApplicationTheme +> Application's theme colors and other general color theme properties. +> +> Note: All properties and functions of the app theme are **read-only**, so the +> theme can't be modified here. Use the app's `renoise.Application:load_theme` +> function to load and apply new themes instead. +> +> Accessing colors and theme properties can be useful in custom viewbuilder +> widgets. + + + + +--- +## Properties +### colors : { [ThemeColor]: RGBColor } +> **READ-ONLY** Get all theme colors in a flat list of RGBColors. +> Color table keys are string identifiers as used in the theme XML file, +> but in lower case. +> +> Note that if you only need to access a single color from the theme, +> use `renoise.app().theme.color(color_name)` instead. +> +> To get notified of color changes, use `renoise.app().theme_observable` + +### knob_shade : [`number`](../../API/builtins/number.md) +> **READ-ONLY** Get theme's knob shade setting. Range: (1 - 2) + +### knob_shade_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### body_shade : [`number`](../../API/builtins/number.md) +> **READ-ONLY** Get theme's body shade setting. Range: (1 - 2) + +### body_shade_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### contrast : [`number`](../../API/builtins/number.md) +> **READ-ONLY** Get theme's contrast setting. Range: (-0.5 - 0.5) + +### contrast_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### texture_set : [`string`](../../API/builtins/string.md) +> **READ-ONLY** Get theme's texture set name + +### texture_set_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + + + +--- +## Functions +### color([*self*](../../API/builtins/self.md), color_name : [`ThemeColor`](#ThemeColor)) +`->`[`RGBColor`](#RGBColor) + +> Get a single color from the theme using a color identifier as used +> in the theme XML file - but in lower case. +> +> e.g. to access the button background color from the theme, use +> `renoise.app().theme.color("button_back")` +> +> To get notified of color changes, use `renoise.app().theme_observable` +> +> ```lua +> -- The application theme's colors +> color_name: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + + + +--- +## Aliases +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + + diff --git a/docs/API/renoise/renoise.ApplicationWindow.md b/docs/API/renoise/renoise.ApplicationWindow.md index 0611170a..21482fec 100644 --- a/docs/API/renoise/renoise.ApplicationWindow.md +++ b/docs/API/renoise/renoise.ApplicationWindow.md @@ -32,6 +32,23 @@ > LOWER_FRAME_TRACK_AUTOMATION: integer = 2, > } > ``` +### DiskBrowserCategory +> ```lua +> { +> DISK_BROWSER_CATEGORY_SONGS: integer = 1, +> DISK_BROWSER_CATEGORY_INSTRUMENTS: integer = 2, +> DISK_BROWSER_CATEGORY_SAMPLES: integer = 3, +> DISK_BROWSER_CATEGORY_OTHER: integer = 4, +> } +> ``` +### InstrumentBoxSlotSize +> ```lua +> { +> INSTRUMENT_BOX_SLOT_SIZE_SMALL: integer = 1, +> INSTRUMENT_BOX_SLOT_SIZE_MEDIUM: integer = 2, +> INSTRUMENT_BOX_SLOT_SIZE_LARGE: integer = 3, +> } +> ``` ### MixerFader > ```lua > { @@ -68,6 +85,11 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### disk_browser_category : [`renoise.ApplicationWindow.DiskBrowserCategory`](renoise.ApplicationWindow.md#DiskBrowserCategory) +### disk_browser_category_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### instrument_box_is_visible : [`boolean`](../../API/builtins/boolean.md) > InstrumentBox @@ -75,6 +97,13 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### instrument_box_slot_size : [`renoise.ApplicationWindow.InstrumentBoxSlotSize`](renoise.ApplicationWindow.md#InstrumentBoxSlotSize) +> InstrumentBox slot size + +### instrument_box_slot_size_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### instrument_editor_is_detached : [`boolean`](../../API/builtins/boolean.md) > Instrument Editor detaching. @@ -82,6 +111,29 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### instrument_properties_is_visible : [`boolean`](../../API/builtins/boolean.md) +> InstrumentProperties (below InstrumentBox) + +### instrument_properties_is_visible_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### instrument_properties_show_volume_transpose : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_trigger_options : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_scale_options : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_plugin : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_plugin_program : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_midi : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_midi_program : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_macros : [`boolean`](../../API/builtins/boolean.md) +### instrument_properties_show_phrases : [`boolean`](../../API/builtins/boolean.md) +### sample_properties_is_visible : [`boolean`](../../API/builtins/boolean.md) +> SampleProperties (below SampleNavigator) + +### sample_properties_is_visible_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### mixer_view_is_detached : [`boolean`](../../API/builtins/boolean.md) > Mixer View detaching. @@ -120,6 +172,13 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### right_frame_is_visible : [`boolean`](../../API/builtins/boolean.md) +> Frame with Disk Browser and Instrument Box. + +### right_frame_is_visible_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### pattern_matrix_is_visible : [`boolean`](../../API/builtins/boolean.md) > Pattern matrix, visible in pattern editor and mixer only... diff --git a/docs/API/renoise/renoise.DeviceParameter.md b/docs/API/renoise/renoise.DeviceParameter.md index 5c92d853..12390e87 100644 --- a/docs/API/renoise/renoise.DeviceParameter.md +++ b/docs/API/renoise/renoise.DeviceParameter.md @@ -18,6 +18,7 @@ ### name : [`string`](../../API/builtins/string.md) > **READ-ONLY** +### name_observable : [`renoise.Document.ObservableString`](../../API/renoise/renoise.Document.ObservableString.md) ### polarity : [`renoise.DeviceParameter.Polarity`](renoise.DeviceParameter.md#Polarity) > **READ-ONLY** diff --git a/docs/API/renoise/renoise.Dialog.md b/docs/API/renoise/renoise.Dialog.md index 28cf6727..0050f053 100644 --- a/docs/API/renoise/renoise.Dialog.md +++ b/docs/API/renoise/renoise.Dialog.md @@ -13,6 +13,9 @@ ### visible : [`boolean`](../../API/builtins/boolean.md) > **READ-ONLY** Check if a dialog is alive and visible. +### focused : [`boolean`](../../API/builtins/boolean.md) +> **READ-ONLY** Check if a dialog is visible and is the key window. + --- diff --git a/docs/API/renoise/renoise.Instrument.md b/docs/API/renoise/renoise.Instrument.md index ca579a8e..d4b2eb7e 100644 --- a/docs/API/renoise/renoise.Instrument.md +++ b/docs/API/renoise/renoise.Instrument.md @@ -208,7 +208,7 @@ ### macro([*self*](../../API/builtins/self.md), index : [`integer`](../../API/builtins/integer.md)) `->`instrument_macro : [`renoise.InstrumentMacro`](../../API/renoise/renoise.InstrumentMacro.md) -> Range: (1 - renoise.Instrument.NUMBER_OF_MACROS) +> Range: (1 - renoise.Instrument.NUMBER_OF_MACROS) > Access a single macro by index. > See also property `macros`. ### insert_phrase_at([*self*](../../API/builtins/self.md), index : [`integer`](../../API/builtins/integer.md)) diff --git a/docs/API/renoise/renoise.InstrumentDevice.md b/docs/API/renoise/renoise.InstrumentDevice.md index c437c445..0f23606e 100644 --- a/docs/API/renoise/renoise.InstrumentDevice.md +++ b/docs/API/renoise/renoise.InstrumentDevice.md @@ -1,4 +1,5 @@ # renoise.InstrumentDevice +> **Deprecated.** Use `renoise.InstrumentPluginDevice` instead. diff --git a/docs/API/renoise/renoise.InstrumentPhrase.md b/docs/API/renoise/renoise.InstrumentPhrase.md index a72c7b80..eafa831b 100644 --- a/docs/API/renoise/renoise.InstrumentPhrase.md +++ b/docs/API/renoise/renoise.InstrumentPhrase.md @@ -14,6 +14,13 @@ > KEY_TRACKING_OFFSET: integer = 3, > } > ``` +### PlaybackMode +> ```lua +> { +> PLAY_PATTERN: integer = 1, +> PLAY_SCRIPT: integer = 2, +> } +> ``` ### MAX_NUMBER_OF_LINES : [`integer`](../../API/builtins/integer.md) > Maximum number of lines that can be present in a phrase. @@ -38,6 +45,17 @@ ### mapping : [`renoise.InstrumentPhraseMapping`](../../API/renoise/renoise.InstrumentPhraseMapping.md) > (Key)Mapping properties of the phrase or nil when no mapping is present. +### playback_mode : [`renoise.InstrumentPhrase.PlaybackMode`](renoise.InstrumentPhrase.md#PlaybackMode) +> playback mode + +### playback_mode_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### script : [`renoise.InstrumentPhraseScript`](../../API/renoise/renoise.InstrumentPhraseScript.md) +> **READ-ONLY** Phrase script properties. Only used when `playback_mode` is +> set to `renoise.InstrumentPhrase.PLAY_SCRIPT` + ### is_empty : [`boolean`](../../API/builtins/boolean.md) > **READ-ONLY** > Quickly check if a phrase has some non empty pattern lines. @@ -187,7 +205,7 @@ > Check/add/remove notifier functions or methods, which are called by > Renoise as soon as any of the phrases's lines have changed. -> See: [renoise.Pattern.has_line_notifier](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/song/pattern.lua#86#9) for more details. +> See: `renoise.Pattern.has_line_notifier` for more details. ### add_line_notifier([*self*](../../API/builtins/self.md), func : [`PhraseLineChangeCallbackWithContext`](#PhraseLineChangeCallbackWithContext), obj : [`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md)) ### remove_line_notifier([*self*](../../API/builtins/self.md), func : [`PhraseLineChangeCallbackWithContext`](#PhraseLineChangeCallbackWithContext), obj : [`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md)) ### has_line_edited_notifier([*self*](../../API/builtins/self.md), func : [`PhraseLineChangeCallbackWithContext`](#PhraseLineChangeCallbackWithContext), obj : [`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md)) diff --git a/docs/API/renoise/renoise.InstrumentPhraseScript.md b/docs/API/renoise/renoise.InstrumentPhraseScript.md new file mode 100644 index 00000000..9cd16fe3 --- /dev/null +++ b/docs/API/renoise/renoise.InstrumentPhraseScript.md @@ -0,0 +1,104 @@ +# renoise.InstrumentPhraseScript + + + + +--- +## Properties +### editor_visible : [`boolean`](../../API/builtins/boolean.md) +> When false, a preview of the script is shown instead of a text editor. + +### editor_visible_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> fired, when the editor visibility changed. + +### parameters : [`renoise.DeviceParameter`](../../API/renoise/renoise.DeviceParameter.md)[] +> **READ-ONLY** List of script input parameters, if any. + +### parameters_observable : [`renoise.Document.ObservableList`](../../API/renoise/renoise.Document.ObservableList.md) +> fired, when the input parameter set changed. + +### paragraphs : [`string`](../../API/builtins/string.md)[] +> Script content. When changing paragraphs, changes are visible in the +> script editor, but are not applied for playback until they get committed. +> See also @function `commit` and @field `committed_observable`. + +### paragraphs_observable : [`renoise.Document.DocumentList`](../../API/renoise/renoise.Document.DocumentList.md) +> Notifier which is called when a paragraph got added or removed. + +### paragraphs_assignment_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Notifier which is called when existing paragraph content changed. + +### compile_error : [`string`](../../API/builtins/string.md) +> **READ-ONLY** When not empty, the script failed to compile. +> This error text is also visible to the user in the script preview. + +### compile_error_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### runtime_error : [`string`](../../API/builtins/string.md) +> **READ-ONLY** When not empty, script compiled successfully, but caused an +> error while running. This error text is also visible to the user in the +> script editor. + +### runtime_error_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### pending_changes : [`integer`](../../API/builtins/integer.md) +> **READ-ONLY** Number of changes since the last commit() or auto-commit call, +> that have been applied to the parapgraphs. +> Note: `auto-commit` only is applied for scripts which are currently edited. + +### pending_changes_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### committed_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Fired when script paragraph changes got committed: Either by an explicit +> `commit` call or via `auto-commit` in the editor when the script currently is +> edited. Script compile errors will be set or cleared *after* the observable +> fires as the commit & compilation happens asynchroniously in the player engine. + + + +--- +## Functions +### parameter([*self*](../../API/builtins/self.md), index : [`integer`](../../API/builtins/integer.md)) +`->`[`renoise.DeviceParameter`](../../API/renoise/renoise.DeviceParameter.md) + +> Access to a single input parameter by index. Use properties 'parameters' +> to iterate over all parameters and to query the parameter count. +### commit([*self*](../../API/builtins/self.md)) +> Commit paragraph changes for playback. +### render_to_pattern([*self*](../../API/builtins/self.md), options : [`RenderScriptOptions`](#renderscriptoptions), rendering_done_callback : (string : [`any`](../../API/builtins/any.md)[`?`](../../API/builtins/nil.md), integer : [`any`](../../API/builtins/any.md), integer : [`any`](../../API/builtins/any.md))) +> Render script content with the given options to the phrase pattern. +> Only committed content will be rendered, so make sure to commit changes first. +> Parameter `rendering_done_callback` carries along rendering results: +> - 1. optional error as string that happened while rendering. nil when succeeded. +> - 2. number of successfully rendered raw events (not pattern lines) or 0. +> - 3. number of skipped raw events, in case the pattern can't fit all events, or 0. +### render_to_clipboard([*self*](../../API/builtins/self.md), options : [`RenderScriptOptions`](#renderscriptoptions), rendering_done_callback : (string : [`any`](../../API/builtins/any.md)[`?`](../../API/builtins/nil.md), integer : [`any`](../../API/builtins/any.md), integer : [`any`](../../API/builtins/any.md))) +> Same as `render_to_pattern`, but rendering into a temporary phrase object in the clipboard, +> which can then be pasted by the user somewhere. + + + +--- +## Structs +# RenderScriptOptions +> Options for the render functions. All undefined properties will fall back to the +> user preferences values from the script preview + +--- +## Properties +### lpb : [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md) +> Lines per beat of the target phrase. + +### max_events : [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md) +> Maximum events (not pattern lines) that will be rendered + + + + + diff --git a/docs/API/renoise/renoise.InstrumentPluginProperties.md b/docs/API/renoise/renoise.InstrumentPluginProperties.md index 9513bb4a..1a9e873c 100644 --- a/docs/API/renoise/renoise.InstrumentPluginProperties.md +++ b/docs/API/renoise/renoise.InstrumentPluginProperties.md @@ -87,6 +87,15 @@ +--- +## Functions +### load_plugin([*self*](../../API/builtins/self.md), plugin_path : [`string`](../../API/builtins/string.md)) +`->`success : [`boolean`](../../API/builtins/boolean.md) + +> Load an existing, new, non aliased plugin. Pass an empty string to unload +> an already assigned plugin. plugin_path must be one of the available plugins +> See: `renoise.InstrumentPluginProperties.available_plugins` + --- diff --git a/docs/API/renoise/renoise.InstrumentTriggerOptions.md b/docs/API/renoise/renoise.InstrumentTriggerOptions.md index 9b6adaf3..6314159f 100644 --- a/docs/API/renoise/renoise.InstrumentTriggerOptions.md +++ b/docs/API/renoise/renoise.InstrumentTriggerOptions.md @@ -33,6 +33,45 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### mts_esp_tuning : [`boolean`](../../API/builtins/boolean.md) +> When true, act as MTS ESP client. Disables custom tunings. + +### mts_esp_tuning_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### tuning : [`number`](../../API/builtins/number.md)[] +> Array of custom pitch values relative to 1/1, used as custom tuning values for +> instrument sample playback. The root key is assumed to be middle C (48 in Renoise), +> The scale will be repeated, so only one octave of values should be defined. An +> octave may contain more or less than 12 notes. +> +> When set mts_esp_tuning is disabled. Set an empty table to disable custom tuning +> using default 12-TET tuning instead. +> +> Use property `tuning_name` to give your custom tuning a name. +> +> #### examples: +> ```lua +> -- Andreas Werckmeister's temperament III (the most famous one, 1681) +> local well_tempered_tuning = { +> 256/243, 1.117403, 32/27, 1.252827, 4/3, 1024/729, +> 1.494927, 128/81, 1.670436, 16/9, 1.879241, 2/1 +> } +> instrument.tuning = well_tempered_tuning +> ``` + +### tuning_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### tuning_name : [`string`](../../API/builtins/string.md) +> Name, as displayed in the UI for a custom tuning or a tuning loaded from a file. + +### tuning_name_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### quantize : [`renoise.InstrumentTriggerOptions.QuantizeMode`](renoise.InstrumentTriggerOptions.md#QuantizeMode) > Trigger quantization mode. @@ -56,3 +95,11 @@ +--- +## Functions +### load_tuning([*self*](../../API/builtins/self.md), filename : [`string`](../../API/builtins/string.md)) +`->`success : [`boolean`](../../API/builtins/boolean.md) + +> Load and apply a scala tuning file as custom tuning. Disables `mts_esp_tuning`. +> Any errors during the export are shown to the user. + diff --git a/docs/API/renoise/renoise.Midi.md b/docs/API/renoise/renoise.Midi.md index f3dbfb5d..c96c776a 100644 --- a/docs/API/renoise/renoise.Midi.md +++ b/docs/API/renoise/renoise.Midi.md @@ -28,7 +28,7 @@ > may happen when using ReWire slaves. ReWire adds virtual MIDI devices to > Renoise. > Already opened references to devices which are no longer available will -> do nothing: ou can use them as before and they will not fire any errors. +> do nothing: you can use them as before and they will not fire any errors. > The messages will simply go into the void... ### create_input_device(device_name : [`string`](../../API/builtins/string.md), callback : [`MidiMessageFunction`](#MidiMessageFunction) | [`MidiMessageMethod1`](#MidiMessageMethod1) | [`MidiMessageMethod2`](#MidiMessageMethod2)[`?`](../../API/builtins/nil.md), sysex_callback : [`MidiMessageFunction`](#MidiMessageFunction) | [`MidiMessageMethod1`](#MidiMessageMethod1) | [`MidiMessageMethod2`](#MidiMessageMethod2)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Midi.MidiInputDevice`](../../API/renoise/renoise.Midi.MidiInputDevice.md) diff --git a/docs/API/renoise/renoise.PatternSequencer.md b/docs/API/renoise/renoise.PatternSequencer.md index e01e37d3..3ee5f73b 100644 --- a/docs/API/renoise/renoise.PatternSequencer.md +++ b/docs/API/renoise/renoise.PatternSequencer.md @@ -25,6 +25,7 @@ > Pattern order list: Notifiers will only be fired when sequence positions are > added, removed or their order changed. To get notified of pattern assignment > changes use the property `pattern_assignments_observable`. +> Use `set_pattern` to change a single pattern in the sequence. ### pattern_sequence_observable : [`renoise.Document.ObservableList`](../../API/renoise/renoise.Document.ObservableList.md) > Track changes to document lists by attaching listener functions to it. @@ -59,6 +60,9 @@ > Access to a single sequence by index (the pattern number). Use property > `pattern_sequence` to iterate over the whole sequence and to query the > sequence count. +### set_pattern([*self*](../../API/builtins/self.md), sequence_index : [`integer`](../../API/builtins/integer.md), pattern_index : [`integer`](../../API/builtins/integer.md)) +> Change a single assigned pattern for the given sequence index. Use `pattern_sequence` +> to iterate or change the whole sequence and to query the sequence count. ### clone_range([*self*](../../API/builtins/self.md), from_sequence_index : [`integer`](../../API/builtins/integer.md), to_sequence_index : [`integer`](../../API/builtins/integer.md)) > Clone a sequence range, appending it right after to_sequence_index. > Slot muting is copied as well. diff --git a/docs/API/renoise/renoise.SQLite.md b/docs/API/renoise/renoise.SQLite.md new file mode 100644 index 00000000..69ec13e6 --- /dev/null +++ b/docs/API/renoise/renoise.SQLite.md @@ -0,0 +1,491 @@ +# renoise.SQLite + + + +## Constants +### Status +> ```lua +> { +> OK: integer = 0, +> ERROR: integer = 1, +> INTERNAL: integer = 2, +> PERM: integer = 3, +> ABORT: integer = 4, +> BUSY: integer = 5, +> LOCKED: integer = 6, +> NOMEM: integer = 7, +> READONLY: integer = 8, +> INTERRUPT: integer = 9, +> IOERR: integer = 10, +> CORRUPT: integer = 11, +> NOTFOUND: integer = 12, +> FULL: integer = 13, +> CANTOPEN: integer = 14, +> MISMATCH: integer = 20, +> MISUSE: integer = 21, +> NOLFS: integer = 22, +> FORMAT: integer = 24, +> RANGE: integer = 25, +> NOTADB: integer = 26, +> ROW: integer = 100, +> DONE: integer = 101, +> } +> ``` + + +--- +## Functions +### open(filename : [`string`](../../API/builtins/string.md)[`?`](../../API/builtins/nil.md), flags : [`SQLiteOpenFlags`](#SQLiteOpenFlags) | [`SQLiteOpenModes`](#SQLiteOpenModes)[`?`](../../API/builtins/nil.md)) +`->`[`SQLiteDatabase`](#sqlitedatabase)[`?`](../../API/builtins/nil.md), [`renoise.SQLite.Status`](renoise.SQLite.md#Status)[`?`](../../API/builtins/nil.md), [`string`](../../API/builtins/string.md)[`?`](../../API/builtins/nil.md) + +> Opens (or creates if it does not exist) a SQLite database either in memory +> or from the given file path. +> +> ### Examples: +> +> ```lua +> -- open an existing db in read-only mode. +> local db, status, error = renoise.SQLite.open('MyDatabase.sqlite', 'ro') +> if db then +> -- do some database calls... +> db:close() +> else +> -- handle error +> end +> +> -- open an in-memory db in read-write-create mode. +> local db, status, error = renoise.SQLite.open() +> if db then +> -- do some database calls... +> db:close() +> else +> -- handle error +> end +> ``` +> +> +> ```lua +> -- Configure database open mode. +> -- Default: "rwc" (read-write-create). +> -- Raw open mode flags from SQLite. +> -- See https://sqlite.org/c3ref/open.html#urifilenamesinsqlite3open +> flags: +> | "ro" +> | "rw" +> | "rwc" +> ``` + + + +--- +## Structs +# SQLiteDatabase + +--- +## Properties +### is_open : [`boolean`](../../API/builtins/boolean.md) +> **READ-ONLY** Whether or not the database is open. + +### is_closed : [`boolean`](../../API/builtins/boolean.md) +> **READ-ONLY** Whether or not the database is closed. + +### error_code : [`renoise.SQLite.Status`](renoise.SQLite.md#Status) +> **READ-ONLY** The most recent error code. + +### error_message : [`string`](../../API/builtins/string.md) +> **READ-ONLY** The most recent error message. + +### changes : [`integer`](../../API/builtins/integer.md) +> **READ-ONLY** Number of database rows that were changed, inserted, or deleted by +> the most recent SQL statement. +> Only changes that are directly specified by INSERT, UPDATE, or DELETE statements +> are counted. +> Auxiliary changes caused by triggers are not counted. Use `db.total_changes` +> to find the total number of changes. + +### total_changes : [`integer`](../../API/builtins/integer.md) +> **READ-ONLY** The number of database rows that have been modified by INSERT, +> UPDATE or DELETE statements since the database was opened. +> This includes UPDATE, INSERT and DELETE statements executed as part of +> trigger programs. All changes are counted as soon as the statement that +> produces them is completed by calling either `stmt:reset()` or `stmt:finalize()`. + +### last_insert_rowid : [`integer`](../../API/builtins/integer.md) +> **READ-ONLY** Gets the rowid of the most recent INSERT into the database. +> If no inserts have ever occurred, 0 is returned. +> (Each row in an SQLite table has a unique 64-bit signed integer +> key called the 'rowid'. This id is always available as an undeclared +> column named ROWID, OID, or _ROWID_. +> If the table has a column of type INTEGER PRIMARY KEY then that column +> is another alias for the rowid.) +> +> If an INSERT occurs within a trigger, then the rowid of the inserted +> row is returned as long as the trigger is running. Once the trigger terminates, +> the value returned reverts to the last value inserted before the trigger fired. + + + +--- +## Functions +### close([*self*](../../API/builtins/self.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Closes a database. All SQL statements prepared using `db:prepare()` should +> have been finalized before this function is called. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else a error code. +### prepare([*self*](../../API/builtins/self.md), sql : [`string`](../../API/builtins/string.md)) +`->`[`SQLiteStatement`](#sqlitestatement)[`?`](../../API/builtins/nil.md), [`renoise.SQLite.Status`](renoise.SQLite.md#Status), [`string`](../../API/builtins/string.md)[`?`](../../API/builtins/nil.md) + +> Compiles the SQL statement in string sql into an internal representation +> and returns this as userdata. The returned object should be used for all +> further method calls in connection with this specific SQL statement. +> +> The function returns the statement object and `renoise.SQLlite.Status.OK` +> on success or else nil, an error code and the error message. +> +> ### Examples: +> +> ```lua +> local statement, code, error = db:prepare("SELECT * from my_table") +> if statement then +> -- bind, step or do some queries +> else +> -- handle error +> end +> ``` +> See: `SQLiteStatement` +### finalize([*self*](../../API/builtins/self.md), temp_only : [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md)) +> Finalizes all statements that have not been explicitly finalized. +### execute([*self*](../../API/builtins/self.md), sql : [`string`](../../API/builtins/string.md), fun : fun(data: any, cols: integer, values: table, names: table)?, data : [`any`](../../API/builtins/any.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status), [`string`](../../API/builtins/string.md)[`?`](../../API/builtins/nil.md) + +> Compiles and executes the SQL statement(s) given in string sql. +> The statements are simply executed one after the other and not stored. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else an +> error code and the error message. +> +> If one or more of the SQL statements are queries, then the callback +> function specified in `fun` is invoked once for each row of the query +> result (if `fun` is `nil`, no callback is invoked). +> +> The callback receives four arguments: +> `data` (the third parameter of the `db:exec()` call), +> the number of columns in the row, a table with the column values +> and another table with the column names. +> +> The callback function should return `0`. If the callback returns +> a non-zero value then the query is aborted, all subsequent SQL statements +> are skipped and `db:exec()` returns `sqlite.ABORT`. +> +> ### Example: +> +> ```lua +> sql = [[ +> CREATE TABLE numbers(num1,num2,str); +> INSERT INTO numbers VALUES(1,11,"ABC"); +> INSERT INTO numbers VALUES(2,22,"DEF"); +> INSERT INTO numbers VALUES(3,33,"UVW"); +> INSERT INTO numbers VALUES(4,44,"XYZ"); +> SELECT * FROM numbers; +> ]] +> function show_row(udata,cols,values,names) +> assert(udata=='test_udata') +> print('exec:') +> for i=1,cols do print('',names[i],values[i]) end +> return 0 +> end +> db:execute(sql,show_row,'test_udata') +> ``` +### interrupt([*self*](../../API/builtins/self.md)) +> Causes any pending database operation to abort and return at the next opportunity. +### busy_handler([*self*](../../API/builtins/self.md), fun : (udata : [`any`](../../API/builtins/any.md), retries : [`integer`](../../API/builtins/integer.md)) `->` [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md), data : [`any`](../../API/builtins/any.md)) +> Sets or removes a busy handler for a SQLiteDatabase. +> `fun` is either a Lua function that implements the busy handler or `nil` +> to remove a previously set handler. This function returns nothing. +> The handler function is called with two parameters: `data` and the number +> of (re-)tries for a pending transaction. +> It should return `nil`, `false` or `0` if the transaction is to be aborted. +> All other values will result in another attempt to perform the transaction. +> +> (See the SQLite documentation for important hints about writing busy handlers.) +### busy_timeout([*self*](../../API/builtins/self.md), t : [`integer`](../../API/builtins/integer.md)) +> Sets a busy handler that waits for `t` milliseconds if a transaction cannot +> proceed. Calling this function will remove any busy handler set by `db:busy_handler()`; +> calling it with an argument less than or equal to 0 will turn off all busy handlers. +### nrows([*self*](../../API/builtins/self.md), sql : [`string`](../../API/builtins/string.md)) +`->`() `->` table<[`string`](../../API/builtins/string.md), [`SQLiteValue`](#SQLiteValue)>[`?`](../../API/builtins/nil.md) + +> Creates an iterator that returns the successive rows selected +> by the SQL statement given in string sql. +> +> Each call to the iterator returns a table in which the named fields correspond +> to the columns in the database. +### rows([*self*](../../API/builtins/self.md), sql : [`string`](../../API/builtins/string.md)) +`->`() `->` [`any`](../../API/builtins/any.md)[] + +> Creates an iterator that returns the successive rows selected by the SQL +> statement given in string `sql`. Each call to the iterator returns a table +> in which the numerical indices 1 to n correspond to the selected columns +> 1 to n in the database. +> +> ### Example: +> +> ```lua +> for a in db:rows('SELECT * FROM table') do +> for _,v in ipairs(a) do print(v) end +> end +> ``` +### urows([*self*](../../API/builtins/self.md), sql : [`string`](../../API/builtins/string.md)) +`->`() `->` [`SQLiteValue`](#SQLiteValue)[`?`](../../API/builtins/nil.md) + +> Creates an iterator that returns the successive rows selected by the SQL +> statement given in string sql. Each call to the iterator returns the values +> that correspond to the columns in the currently selected row. +> +> ### Example: +> +> ```lua +> for num1,num2 in db:urows('SELECT * FROM table') do +> print(num1,num2) +> end +> ``` + + + +--- +## Aliases +### SQLiteValue +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) + + + + +# SQLiteStatement +> Precompiled SQLite statements, as created with `db:prepare()`. + +--- +## Properties +### is_open : [`boolean`](../../API/builtins/boolean.md) +> **READ-ONLY** Whether or not the statement hasn't been finalized. + +### is_closed : [`boolean`](../../API/builtins/boolean.md) +> **READ-ONLY** Whether or not the statement has been finalized. + +### columns : [`integer`](../../API/builtins/integer.md) +> **READ-ONLY** Number of columns in the result set returned by the statement, +> or 0 if the statement does not return data (for example an UPDATE). + +### last_insert_rowid : [`integer`](../../API/builtins/integer.md) +> **READ-ONLY** rowid of the most recent INSERT into the database corresponding +> to this statement. + +### named_types : table<[`string`](../../API/builtins/string.md), [`string`](../../API/builtins/string.md)> +> **READ-ONLY** A table with the names and types of all columns in the current +> result set of the statement. + +### named_values : table<[`string`](../../API/builtins/string.md), [`SQLiteValue`](#SQLiteValue)> +> **READ-ONLY** A table with names and values of all columns in the current +> result row of a query. + +### names : [`string`](../../API/builtins/string.md)[] +> **READ-ONLY** A list of the names of all columns in the result set returned +> by the statement. + +### values : [`SQLiteValue`](#SQLiteValue)[] +> **READ-ONLY** A list of the values of all columns in the result set +> returned by the statement. + +### types : [`string`](../../API/builtins/string.md)[] +> **READ-ONLY** A list of the types of all columns in the result set returned +> by the statement. + +### unames : [`string`](../../API/builtins/string.md)[] +> **READ-ONLY** A list of the names of all columns in the result set returned +> by the statement. + +### utypes : [`string`](../../API/builtins/string.md)[] +> **READ-ONLY** A list of the types of all columns in the result set returned +> by the statement. + +### uvalues : [`SQLiteValue`](#SQLiteValue)[] +> **READ-ONLY** A list of the values of all columns in the current result +> row of a query. + + + +--- +## Functions +### name([*self*](../../API/builtins/self.md), n : [`integer`](../../API/builtins/integer.md)) +`->`[`string`](../../API/builtins/string.md) + +> The name of column `n` in the result set of the statement. +> (The left-most column is number 0.) +### value([*self*](../../API/builtins/self.md), n : [`integer`](../../API/builtins/integer.md)) +`->`[`SQLiteValue`](#SQLiteValue) + +> The value of column `n` in the result set of the statement. +> (The left-most column is number 0.) +### type([*self*](../../API/builtins/self.md), n : [`integer`](../../API/builtins/integer.md)) +`->`[`string`](../../API/builtins/string.md) + +> The type of column `n` in the result set of the statement. +> (The left-most column is number 0.) +### finalize([*self*](../../API/builtins/self.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Frees a prepared statement. +> +> If the statement was executed successfully, or not executed at all, +> then `renoise.SQLlite.Status.OK` is returned. If execution of the statement +> failed then an error code is returned. +### reset([*self*](../../API/builtins/self.md)) +> Resets the statement so that it is ready to be re-executed. +> Any statement variables that had values bound to them using +> the `stmt:bind*()` functions retain their values. +### step([*self*](../../API/builtins/self.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Evaluates the (next iteration of the) prepared statement. +> It will return one of the following values: +> - `renoise.SQLite.Status.BUSY`: the engine was unable to acquire the locks needed. +> If the statement is a COMMIT or occurs outside of an explicit transaction, +> then you can retry the statement. If the statement is not a COMMIT and +> occurs within a explicit transaction then you should rollback the transaction +> before continuing. +> - `renoise.SQLite.Status.DONE`: the statement has finished executing successfully. +> `stmt:step()` should not be called again on this statement without first +> calling `stmt:reset()` to reset the virtual machine back to the initial state. +> - `renoise.SQLite.Status.ROW`: this is returned each time a new row of data is ready. +> The values may be accessed using the column access functions. +> `stmt:step()` can be called again to retrieve the next row of data. +> - `renoise.SQLite.Status.ERROR`: a run-time error (e.g. a constraint violation) occurred. +> `stmt:step()` should not be called again. More information may be found by +> calling `db:error_message()`. A more specific error code can be obtained by calling +> `stmt:reset()`. +> - `renoise.SQLite.Status.MISUSE`: the function was called inappropriately. +> Perhaps because the statement has already been finalized or a previous call to +> `stmt:step()` has returned `sqlite.ERROR` or `sqlite.DONE`. +### bind_parameter_count([*self*](../../API/builtins/self.md)) +`->`[`integer`](../../API/builtins/integer.md) + +> Gets the largest statement parameter index in prepared statement stmt. +> When the statement parameters are of the forms ":AAA" or "?", then they +> are assigned sequentially increasing numbers beginning with one, so the +> value returned is the number of parameters. +> However if the same statement parameter name is used multiple times, +> each occurrence is given the same number, so the value returned is the +> number of unique statement parameter names. +> +> If statement parameters of the form "?NNN" are used (where NNN is an +> integer) then there might be gaps in the numbering and the value returned +> by this interface is the index of the statement parameter with the largest +> index value. +### bind_parameter_name([*self*](../../API/builtins/self.md), n : [`any`](../../API/builtins/any.md)) +`->`[`string`](../../API/builtins/string.md)[`?`](../../API/builtins/nil.md), [`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Gets the name of the `n`-th parameter in prepared statement stmt. +> Statement parameters of the form ":AAA" or "@AAA" or "$VVV" have +> a name which is the string ":AAA" or "@AAA" or "$VVV". +> In other words, the initial ":" or "$" or "@" is included as part of the name. +> Parameters of the form "?" or "?NNN" have no name. +> The first bound parameter has an index of 1. If the value `n` is out of +> range or if the `n`-th parameter is nameless, then nil is returned. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else a numerical error code. +> See: `renoise.SQLite.Status` +### bind([*self*](../../API/builtins/self.md), n : [`integer`](../../API/builtins/integer.md), value : [`boolean`](../../API/builtins/boolean.md) | [`string`](../../API/builtins/string.md) | [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Binds `value` to statement parameter `n`. If `value` is a string, it is +> bound as text, otherwise if it is a number it is bound as a double. +> If it is a boolean, it is bound as 0 or 1. +> If `value` is nil, any previous binding is removed. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else a error code. +### bind_blob([*self*](../../API/builtins/self.md), n : [`integer`](../../API/builtins/integer.md), blob : [`string`](../../API/builtins/string.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Binds string `blob` (which can be a binary string) as a blob to +> statement parameter `n`. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else a error code. +### bind_names([*self*](../../API/builtins/self.md), nametable : table) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Binds the values in `nametable` to statement parameters. +> +> If the statement parameters are named (i.e., of the form ":AAA" or "$AAA") +> then this function looks for appropriately named fields in nametable; +> if the statement parameters are not named, it looks for numerical fields 1 +> to the number of statement parameters. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else a error code. +### bind_values([*self*](../../API/builtins/self.md), ...[`boolean`](../../API/builtins/boolean.md) | [`string`](../../API/builtins/string.md) | [`number`](../../API/builtins/number.md)) +`->`[`renoise.SQLite.Status`](renoise.SQLite.md#Status) + +> Binds the given values to statement parameters. +> +> The function returns `renoise.SQLlite.Status.OK` on success or else a error code. +> See: `renoise.SQLite.Status` +### nrows([*self*](../../API/builtins/self.md)) +`->`() `->` table<[`string`](../../API/builtins/string.md), [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md)>[`?`](../../API/builtins/nil.md) + +> Creates an iterator over the names and values of the result +> set of the statement. Each iteration returns a table with the names +> and values for the current row. +> +> This is the prepared statement equivalent of `db:nrows()`. +> See: `SQLiteDatabase.nrows` +### rows([*self*](../../API/builtins/self.md)) +`->`() `->` [`any`](../../API/builtins/any.md)[] + +> Creates an iterator over the values of the result set of the statement. +> Each iteration returns an array with the values for the current row. +> This is the prepared statement equivalent of `db:rows()`. +> See: `SQLiteDatabase.rows` +### urows([*self*](../../API/builtins/self.md)) +`->`() `->` [`string`](../../API/builtins/string.md) | [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md) + +> Creates an iterator over the values of the result set of the statement. +> Each iteration returns the values for the current row. +> This is the prepared statement equivalent of `db:urows()`. +> See: `SQLiteDatabase.urows` + + + +--- +## Aliases +### SQLiteValue +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) + + + + + + + +--- +## Aliases +### SQLiteOpenFlags +[`integer`](../../API/builtins/integer.md) +> Raw open mode flags from SQLite. +> See https://sqlite.org/c3ref/open.html#urifilenamesinsqlite3open + +### SQLiteOpenModes +`"ro"` | `"rw"` | `"rwc"` +> ```lua +> -- Configure database open mode. +> -- Default: "rwc" (read-write-create). +> SQLiteOpenModes: +> | "ro" +> | "rw" +> | "rwc" +> ``` + +### SQLiteValue +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) + + + diff --git a/docs/API/renoise/renoise.SampleAhdrsModulationDevice.md b/docs/API/renoise/renoise.SampleAhdrsModulationDevice.md index e3494133..d479a9c9 100644 --- a/docs/API/renoise/renoise.SampleAhdrsModulationDevice.md +++ b/docs/API/renoise/renoise.SampleAhdrsModulationDevice.md @@ -19,6 +19,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleBuffer.md b/docs/API/renoise/renoise.SampleBuffer.md index ec748d2e..e11eb1fd 100644 --- a/docs/API/renoise/renoise.SampleBuffer.md +++ b/docs/API/renoise/renoise.SampleBuffer.md @@ -118,17 +118,26 @@ > IMPORTANT: before modifying buffers, call 'prepare_sample_data_changes'. > When you are done, call 'finalize_sample_data_changes' to generate undo/redo > data for your changes and update sample overview caches! -### prepare_sample_data_changes([*self*](../../API/builtins/self.md)) -> To be called once BEFORE sample data gets manipulated via 'set_sample_data'. -> This will prepare undo/redo data for the whole sample. See also -> 'finalize_sample_data_changes'. +### prepare_sample_data_changes([*self*](../../API/builtins/self.md), undo_redo_enabled : [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md)) +> To be called once **before** sample data gets manipulated via `set_sample_data`. +> This will prepare undo/redo data for the whole sample and does other internal +> housekeeping. Every *prepare_sample_data_changes* call must be paired with a +> *finalize_sample_data_changes* call. +> +> When param `undo_redo_enabled` is false, no undo/redo data is generated for the +> following changes. When undefined or true, the global "Enable Undo/Redo in Sample +> Editor" option is applied. +> +> See also 'finalize_sample_data_changes'. ### finalize_sample_data_changes([*self*](../../API/builtins/self.md)) -> To be called once AFTER the sample data is manipulated via 'set_sample_data'. -> This will create undo/redo data for the whole sample, and also update the -> sample view caches for the sample. The reason this isn't automatically -> invoked is to avoid performance overhead when changing sample data 'sample by -> sample'. Don't forget to call this after any data changes, or changes may not -> be visible in the GUI and can not be un/redone! +> To be called once *after* the sample data got manipulated via `set_sample_data`. +> This will create undo/redo data for the whole samples, and also updates the +> sample view caches for the sample. +> The reason this isn't automatically invoked is to avoid performance overhead when +> changing sample data 'sample by sample'. +> +> Don't forget to call this after any data changes, or changes may not be visible +> in the GUI and can not be un/redone! ### load_from([*self*](../../API/builtins/self.md), filename : [`string`](../../API/builtins/string.md)) `->`success : [`boolean`](../../API/builtins/boolean.md) diff --git a/docs/API/renoise/renoise.SampleDeviceChain.md b/docs/API/renoise/renoise.SampleDeviceChain.md index b2a971b0..e7ed2080 100644 --- a/docs/API/renoise/renoise.SampleDeviceChain.md +++ b/docs/API/renoise/renoise.SampleDeviceChain.md @@ -45,7 +45,7 @@ `->`new_device : [`renoise.AudioDevice`](../../API/renoise/renoise.AudioDevice.md) > Insert a new device at the given position. "device_path" must be an available device -> See: [renoise.SampleDeviceChain.available_devices](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/song/instrument/sample_device_chain.lua#24#10) +> See: `renoise.SampleDeviceChain.available_devices` ### delete_device_at([*self*](../../API/builtins/self.md), index : [`integer`](../../API/builtins/integer.md)) > Delete an existing device from a chain. The mixer device at index 1 can not > be deleted. diff --git a/docs/API/renoise/renoise.SampleEnvelopeModulationDevice.md b/docs/API/renoise/renoise.SampleEnvelopeModulationDevice.md index 47470ac2..c349e699 100644 --- a/docs/API/renoise/renoise.SampleEnvelopeModulationDevice.md +++ b/docs/API/renoise/renoise.SampleEnvelopeModulationDevice.md @@ -39,6 +39,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleFaderModulationDevice.md b/docs/API/renoise/renoise.SampleFaderModulationDevice.md index 5cfc581b..d9d792c6 100644 --- a/docs/API/renoise/renoise.SampleFaderModulationDevice.md +++ b/docs/API/renoise/renoise.SampleFaderModulationDevice.md @@ -31,6 +31,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleKeyTrackingModulationDevice.md b/docs/API/renoise/renoise.SampleKeyTrackingModulationDevice.md index 217d8c92..8d661f09 100644 --- a/docs/API/renoise/renoise.SampleKeyTrackingModulationDevice.md +++ b/docs/API/renoise/renoise.SampleKeyTrackingModulationDevice.md @@ -19,6 +19,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleLfoModulationDevice.md b/docs/API/renoise/renoise.SampleLfoModulationDevice.md index 6cdc83bc..1614298a 100644 --- a/docs/API/renoise/renoise.SampleLfoModulationDevice.md +++ b/docs/API/renoise/renoise.SampleLfoModulationDevice.md @@ -30,6 +30,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleModulationDevice.md b/docs/API/renoise/renoise.SampleModulationDevice.md index f015e556..92bc8015 100644 --- a/docs/API/renoise/renoise.SampleModulationDevice.md +++ b/docs/API/renoise/renoise.SampleModulationDevice.md @@ -41,6 +41,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleModulationSet.md b/docs/API/renoise/renoise.SampleModulationSet.md index 749a6ad2..a1834a32 100644 --- a/docs/API/renoise/renoise.SampleModulationSet.md +++ b/docs/API/renoise/renoise.SampleModulationSet.md @@ -59,8 +59,8 @@ > **READ-ONLY** List of available filter types depending on the filter_version. ### filter_type : [`FilterTypes`](#FilterTypes) -> The type of the filter selected for the modulation set. -> Songs made with previous versions of Renoise may use old filter types. +> The type of the filter selected for the modulation set. +> Songs made with previous versions of Renoise may use old filter types. ### filter_type_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener diff --git a/docs/API/renoise/renoise.SampleOperandModulationDevice.md b/docs/API/renoise/renoise.SampleOperandModulationDevice.md index f84c55a3..f9da73cc 100644 --- a/docs/API/renoise/renoise.SampleOperandModulationDevice.md +++ b/docs/API/renoise/renoise.SampleOperandModulationDevice.md @@ -19,6 +19,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleStepperModulationDevice.md b/docs/API/renoise/renoise.SampleStepperModulationDevice.md index 8ff798d8..dfdfa4bf 100644 --- a/docs/API/renoise/renoise.SampleStepperModulationDevice.md +++ b/docs/API/renoise/renoise.SampleStepperModulationDevice.md @@ -30,6 +30,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.SampleVelocityTrackingModulationDevice.md b/docs/API/renoise/renoise.SampleVelocityTrackingModulationDevice.md index cd9773f4..a0801e36 100644 --- a/docs/API/renoise/renoise.SampleVelocityTrackingModulationDevice.md +++ b/docs/API/renoise/renoise.SampleVelocityTrackingModulationDevice.md @@ -28,6 +28,8 @@ > functions to it. ### enabled : [`boolean`](../../API/builtins/boolean.md) +> **Deprecated.** Use `is_active` instead. + ### enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. diff --git a/docs/API/renoise/renoise.ScriptingTool.md b/docs/API/renoise/renoise.ScriptingTool.md index 807ef229..a9c5714f 100644 --- a/docs/API/renoise/renoise.ScriptingTool.md +++ b/docs/API/renoise/renoise.ScriptingTool.md @@ -52,6 +52,12 @@ > gets reloaded (only happens with the auto_reload debugging tools), in order > to connect the new script instance to the already running document. +### app_will_save_document_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Invoked just before the application document (song) is saved. +> This is the last chance to make any changes that should be part of +> the saved song. You could for example write your tool data to +> `renoise.song().tool_data` here. + ### app_saved_document_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Invoked each time the app's document (song) is successfully saved. > renoise.song().file_name will point to the filename that it was saved to. @@ -293,10 +299,12 @@ > + "Phrase Editor" > + "Phrase Mappings" > + "Phrase Grid" +> + "Phrase Script Editor" > + "Sample Navigator" > + "Sample Editor" > + "Sample Editor Ruler" > + "Sample Editor Slice Markers" +> + "Sample List" > + "Sample Mappings" > + "Sample FX Mixer" > + "Sample Modulation Matrix" @@ -314,6 +322,7 @@ > + "Tool Browser" > + "Script File Browser" > + "Script File Tabs" +> + "Script Editor" > ``` > Separating entries: > To divide entries into groups (separate entries with a line), prepend one or diff --git a/docs/API/renoise/renoise.Song.md b/docs/API/renoise/renoise.Song.md index 778fbba4..e6f92145 100644 --- a/docs/API/renoise/renoise.Song.md +++ b/docs/API/renoise/renoise.Song.md @@ -150,7 +150,7 @@ > functions to it. ### selected_sample_index : [`integer`](../../API/builtins/integer.md) -> **READ-ONLY** Selected sample index in the instrument's sample list. +> **READ-ONLY** Selected sample index in the instrument's sample list. > Only 0 when no samples are present in the selected instrument. ### selected_sample_modulation_set : [`renoise.SampleModulationSet`](../../API/renoise/renoise.SampleModulationSet.md) @@ -208,12 +208,17 @@ > **READ-ONLY** Selected device index in the track DSP chain editor. ### selected_device : [`renoise.AudioDevice`](../../API/renoise/renoise.AudioDevice.md) +> **Deprecated.** **READ-ONLY** Use 'selected_track_device' instead. + ### selected_device_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) -> Track changes to document properties or general states by attaching listener -> functions to it. +> **Deprecated.** Use 'selected_track_device_observable' instead. ### selected_device_index : [`integer`](../../API/builtins/integer.md) +> **Deprecated.** **READ-ONLY** Use 'selected_track_device_index' instead. + ### selected_parameter : [`renoise.DeviceParameter`](../../API/renoise/renoise.DeviceParameter.md) +> **Deprecated.** **READ-ONLY** Use 'selected_automation_parameter' instead. + ### selected_parameter_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. @@ -228,7 +233,7 @@ > functions to it. ### selected_automation_device : [`renoise.AudioDevice`](../../API/renoise/renoise.AudioDevice.md) -> **READ-ONLY** parent device of 'selected_automation_parameter'. not settable. +> **READ-ONLY** Parent device of 'selected_automation_parameter'. ### selected_automation_device_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener @@ -304,6 +309,34 @@ > --> select line 1 to 4, in the first track only > ``` +### selected_phrase_line : [`renoise.PatternLine`](../../API/renoise/renoise.PatternLine.md) +> **READ-ONLY** The currently edited line in the currently edited phrase. +> Nil when no phrase is selected. + +### selected_phrase_line_index : [`integer`](../../API/builtins/integer.md) +> The currently edited line index in the currently edited phrase. +> 0 when no phrase is selected. + +### selected_phrase_note_column : [`renoise.NoteColumn`](../../API/renoise/renoise.NoteColumn.md) +> **READ-ONLY** The currently edited column in the selected line in the currently +> edited phrase. Nil when no phrase is selected or when an effect column is selected. + +### selected_phrase_note_column_index : [`integer`](../../API/builtins/integer.md) +> The currently edited column index in the selected line in the currently edited +> phrase. 0 when no phrase is selected or when an effect column is selected. + +### selected_phrase_effect_column : [`renoise.EffectColumn`](../../API/renoise/renoise.EffectColumn.md) +> **READ-ONLY** The currently edited column in the selected line in the currently +> edited phrase. Nil when no phrase is selected or when a note column is selected. + +### selected_phrase_effect_column_index : [`integer`](../../API/builtins/integer.md) +> The currently edited effect column index in the selected line in the currently +> edited phrase. 0 when no phrase is selected or when a note column is selected. + +### selected_phrase_sub_column_type : [`renoise.Song.SubColumnType`](renoise.Song.md#SubColumnType) +> **READ-ONLY** The currently edited sub column type within the selected +> note/effect column in the current phrase. 0 when no phrase is selected. + ### selection_in_phrase : [`PhraseSelection`](#phraseselection)[`?`](../../API/builtins/nil.md) > Same as `selection_in_pattern` but for the currently selected phrase (if any). @@ -311,6 +344,9 @@ --- ## Functions +### is_undo_redoing([*self*](../../API/builtins/self.md)) +> True while an undo/redo action is invoked. This may be useful to check in notifiers, +> to figure out if the document currently changes because of an undo/redo operation. ### can_undo([*self*](../../API/builtins/self.md)) `->`[`boolean`](../../API/builtins/boolean.md) @@ -323,15 +359,27 @@ > Test if something in the song can be redone. ### redo([*self*](../../API/builtins/self.md)) > Redo a previously undo action. Will do nothing if nothing can be redone. -### describe_undo([*self*](../../API/builtins/self.md), description : [`any`](../../API/builtins/any.md)) +### describe_undo([*self*](../../API/builtins/self.md), description : [`string`](../../API/builtins/string.md)) > When modifying the song, Renoise will automatically add descriptions for > undo/redo by looking at what first changed (a track was inserted, a pattern > line changed, and so on). When the song is changed from an action in a menu > entry callback, the menu entry's label will automatically be used for the > undo description. -> If those auto-generated names do not work for you, or you want to use -> something more descriptive, you can (!before changing anything in the song!) +> If those auto-generated names do not work for you, or you want to use +> something more descriptive, you can, **before changing anything in the song**, > give your changes a custom undo description (like: "Generate Synth Sample") +### describe_batch_undo([*self*](../../API/builtins/self.md), description : [`string`](../../API/builtins/string.md), timeout_ms : [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md)) +> Same as `describe_undo`, but additionally this tries to merge the following +> changes to the document with the last one, if the description matches the last +> description and the given timeout was not reached since the last describe_batch_undo +> call. +> +> Calls to `describe_undo` from other tools, or from Renoise internally, will cancel +> batches and split the undo action. +> +> Batches can be useful to combine multiple changes in the document into a single +> udo/redo step, when the changes happen asynchroniously, for example a process +> sliced action (via Lua coroutines). ### insert_track_at([*self*](../../API/builtins/self.md), index : [`integer`](../../API/builtins/integer.md)) `->`[`renoise.Track`](../../API/renoise/renoise.Track.md) @@ -408,9 +456,6 @@ > Access to a single pattern by index. Use properties 'patterns' to iterate > over all patterns and to query the pattern count. -### cancel_rendering([*self*](../../API/builtins/self.md)) -> When rendering (see rendering, renoise.song().rendering_progress), -> the current render process is canceled. Otherwise, nothing is done. ### render([*self*](../../API/builtins/self.md), options : [`RenderOptions`](#renderoptions), filename : [`string`](../../API/builtins/string.md), rendering_done_callback : fun()) `->`success : [`boolean`](../../API/builtins/boolean.md), error : [`string`](../../API/builtins/string.md) @@ -438,6 +483,42 @@ > Parameter `rendering_done_callback` is ONLY called when rendering has succeeded. > You can do something with the file you've passed to the renderer here, like > for example loading the file into a sample buffer. +### cancel_rendering([*self*](../../API/builtins/self.md)) +> When rendering (see rendering, renoise.song().rendering_progress), +> the current render process is canceled. Otherwise, nothing is done. +### trigger_pattern_line([*self*](../../API/builtins/self.md), line_index : [`integer`](../../API/builtins/integer.md)) +> Trigger the given pattern line index in the current pattern for preview purposes. +> This works similar to the Renoise `PlayCurrentLine` keyboard shortcut, but does now +> advance the playback position. +> +> If you want to preview a single track's note only, mute other tracks before +> triggering the pattern line. To stop the preview, invoke `stop` from the transport. +> +> Transport playback must be stopped for this to work. If it's not, an error is +> thrown. +> +> This is evaluated from the GUI thread, not a real-time thread, so timing will +> be a little bit wonky. Don't try to use this as a custom sequencer! +### trigger_instrument_note_on([*self*](../../API/builtins/self.md), instrument_index : [`integer`](../../API/builtins/integer.md), track_index : [`integer`](../../API/builtins/integer.md), note : [`integer`](../../API/builtins/integer.md) | [`integer`](../../API/builtins/integer.md)[][`?`](../../API/builtins/nil.md), volume : [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md)) +> Trigger instrument playback with the specified note or a table of notes (a chord) +> and volume for preview purposes on the given track index. +> +> Send tracks can not play notes. When specifying a send track, notes will play on +> the master track instead. +> +> This is evaluated from the GUI thread, not a real-time thread, so timing will +> be a little bit wonky. Only use this to **preview instruments** from tools and +> not as a sequencer. +### trigger_instrument_note_off([*self*](../../API/builtins/self.md), instrument_index : [`integer`](../../API/builtins/integer.md), track_index : [`integer`](../../API/builtins/integer.md), note : [`integer`](../../API/builtins/integer.md) | [`integer`](../../API/builtins/integer.md)[][`?`](../../API/builtins/nil.md)) +> Stop instrument playback which previously got started via `trigger_instrument_note_on`. +### trigger_sample_note_on([*self*](../../API/builtins/self.md), instrument_index : [`integer`](../../API/builtins/integer.md), sample_index : [`integer`](../../API/builtins/integer.md), track_index : [`integer`](../../API/builtins/integer.md), note : [`integer`](../../API/builtins/integer.md)[`?`](../../API/builtins/nil.md), volume : [`number`](../../API/builtins/number.md)[`?`](../../API/builtins/nil.md), use_selection : [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md)) +> Trigger a sample with the specified note and volume for preview purposes on the +> given track. This directly triggers the sample, bypassing the instrument's keyzone. +> +> Only use this to **preview samples** from tools and not as a sequencer. +> See also `trigger_instrument_note_on`. +### trigger_sample_note_off([*self*](../../API/builtins/self.md), instrument_index : [`integer`](../../API/builtins/integer.md), sample_index : [`integer`](../../API/builtins/integer.md), track_index : [`integer`](../../API/builtins/integer.md), note : [`integer`](../../API/builtins/integer.md)[`?`](../../API/builtins/nil.md)) +> Stops sample playback that previously got triggered via `trigger_sample_note_on`. ### load_midi_mappings([*self*](../../API/builtins/self.md), filename : [`string`](../../API/builtins/string.md)) `->`success : [`boolean`](../../API/builtins/boolean.md), error : [`string`](../../API/builtins/string.md) diff --git a/docs/API/renoise/renoise.Transport.md b/docs/API/renoise/renoise.Transport.md index be6e940b..eeaedc23 100644 --- a/docs/API/renoise/renoise.Transport.md +++ b/docs/API/renoise/renoise.Transport.md @@ -25,6 +25,15 @@ > TIMING_MODEL_LPB: integer = 2, > } > ``` +### SyncMode +> ```lua +> { +> SYNC_MODE_INTERNAL: integer = 1, +> SYNC_MODE_MIDI_CLOCK: integer = 2, +> SYNC_MODE_ABLETON_LINK: integer = 3, +> SYNC_MODE_JACK: integer = 4, +> } +> ``` --- @@ -36,6 +45,15 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### sync_mode : [`renoise.Transport.SyncMode`](renoise.Transport.md#SyncMode) +> Transport sync mode. +> Note: `SYNC_MODE_JACK` only is available on Linux. Trying to enable it on +> other platforms will fire an error. + +### sync_mode_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### timing_model : [`renoise.Transport.TimingModel`](renoise.Transport.md#TimingModel) > *READ-ONLY* Old school speed or new LPB timing used? > With `TIMING_MODEL_SPEED`, tpl is used as speed factor. The lpb property @@ -118,14 +136,22 @@ ### loop_block_enabled : [`boolean`](../../API/builtins/boolean.md) > Block Loop On/Off -### loop_block_start_pos : [`renoise.SongPos`](../../API/renoise/renoise.SongPos.md) -> Start of block loop +### loop_block_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. ### loop_block_range_coeff : [`integer`](../../API/builtins/integer.md) > Range: (2 - 16) +### loop_block_range_coeff_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + +### loop_block_start_pos : [`renoise.SongPos`](../../API/renoise/renoise.SongPos.md) +> Start of block loop + ### edit_mode : [`boolean`](../../API/builtins/boolean.md) -> Edit modes +> Pattern edit/record mode On/Off ### edit_mode_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener @@ -145,15 +171,22 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### octave_enabled : [`boolean`](../../API/builtins/boolean.md) +> Enabled for MIDI keyboards + +### octave_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### metronome_enabled : [`boolean`](../../API/builtins/boolean.md) -> Metronome +> Metronome playback On/Off ### metronome_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. ### metronome_beats_per_bar : [`integer`](../../API/builtins/integer.md) -> Range: (1 - 16) +> Range: (1 - 16) or 0 = guess from pattern length ### metronome_beats_per_bar_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener @@ -167,7 +200,7 @@ > functions to it. ### metronome_precount_enabled : [`boolean`](../../API/builtins/boolean.md) -> Metronome precount +> Metronome precount playback On/Off ### metronome_precount_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener @@ -180,8 +213,15 @@ > Track changes to document properties or general states by attaching listener > functions to it. +### metronome_volume : [`number`](../../API/builtins/number.md) +> Range: (0 - math.db2lin(6)) + +### metronome_volume_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + ### record_quantize_enabled : [`boolean`](../../API/builtins/boolean.md) -> Quantize +> Record note quantization On/Off ### record_quantize_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener @@ -219,7 +259,7 @@ > functions to it. ### groove_enabled : [`boolean`](../../API/builtins/boolean.md) -> Groove. (aka Shuffle) +> Groove (aka Shuffle) ### groove_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener @@ -229,9 +269,12 @@ > table with 4 numbers in Range: (0 - 1) ### groove_assignment_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) -> Attach notifiers that will be called as soon as any groove value changed. +> Will be called as soon as any groove value changed. ### track_headroom : [`number`](../../API/builtins/number.md) +> Global Track Headroom +> To convert to dB: `dB = math.lin2db(renoise.Transport.track_headroom)` +> To convert from dB: `renoise.Transport.track_headroom = math.db2lin(dB)` > Range: (math.db2lin(-12) - math.db2lin(0)) ### track_headroom_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) @@ -246,12 +289,23 @@ > functions to it. ### keyboard_velocity : [`integer`](../../API/builtins/integer.md) +> Will return the default value of 127 when keyboard_velocity_enabled == false. > Range: (0 - 127) ### keyboard_velocity_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) > Track changes to document properties or general states by attaching listener > functions to it. +### sample_recording : [`boolean`](../../API/builtins/boolean.md) +> *READ-ONLY* true when sample sample dialog is visible and recording started. + +### sample_recording_sync_enabled : [`boolean`](../../API/builtins/boolean.md) +> Sample recording pattern quantization On/Off. + +### sample_recording_sync_enabled_observable : [`renoise.Document.Observable`](../../API/renoise/renoise.Document.Observable.md) +> Track changes to document properties or general states by attaching listener +> functions to it. + --- @@ -277,9 +331,12 @@ > Move the block loop one segment forwards, when possible. ### loop_block_move_backwards([*self*](../../API/builtins/self.md)) > Move the block loop one segment backwards, when possible. +### start_sample_recording([*self*](../../API/builtins/self.md)) +> Start a new sample recording when the sample dialog is visible. +### stop_sample_recording([*self*](../../API/builtins/self.md)) +> Stop sample recording when the sample dialog is visible and running ### start_stop_sample_recording([*self*](../../API/builtins/self.md)) -> Start a new sample recording when the sample dialog is visible, -> otherwise stop and finish it. +> **Deprecated.** Use `start_sample_recording` or `stop_sample_recording` instead. ### cancel_sample_recording([*self*](../../API/builtins/self.md)) > Cancel a currently running sample recording when the sample dialog > is visible, otherwise do nothing. diff --git a/docs/API/renoise/renoise.ViewBuilder.md b/docs/API/renoise/renoise.ViewBuilder.md index 5f11a0f2..21556676 100644 --- a/docs/API/renoise/renoise.ViewBuilder.md +++ b/docs/API/renoise/renoise.ViewBuilder.md @@ -15,15 +15,17 @@ > * Nested child views: Add child views to the currently specified view. > > #### examples: -> Creates a column view with `margin = 1` and adds two text views to the column. > ```lua +> -- creates a column view with `margin = 1` and adds two text views to the column. > vb:column { > margin = 1, -> vb:text { -> text = "Text1" -> }, -> vb:text { -> text = "Text1" +> views = { +> vb:text { +> text = "Text1" +> }, +> vb:text { +> text = "Text1" +> } > } > } > ``` @@ -80,11 +82,13 @@ > ```lua > vb:column { > margin = 1, -> vb:text { -> text = "Text1" -> }, -> vb:text { -> text = "Text2" +> views = { +> vb:text { +> text = "Text1" +> }, +> vb:text { +> text = "Text2" +> } > } > } > ``` @@ -96,11 +100,13 @@ > ```lua > vb:column { > margin = 1, -> vb:text { -> text = "Text1" -> }, -> vb:text { -> text = "Text2" +> views = { +> vb:text { +> text = "Text1" +> }, +> vb:text { +> text = "Text2" +> } > } > } > ``` @@ -112,11 +118,13 @@ > ```lua > vb:horizontal_aligner { > mode = "center", -> vb:text { -> text = "Text1" -> }, -> vb:text { -> text = "Text2" +> views = { +> vb:text { +> text = "Text1" +> }, +> vb:text { +> text = "Text2" +> } > } > } > ``` @@ -128,14 +136,39 @@ > ```lua > vb:horizontal_aligner { > mode = "center", -> vb:text { -> text = "Text1" -> }, -> vb:text { -> text = "Text2" +> views = { +> vb:text { +> text = "Text1" +> }, +> vb:text { +> text = "Text2" +> } > } > } > ``` +### stack([*self*](../../API/builtins/self.md), properties : [`StackViewProperties`](#stackviewproperties)[`?`](../../API/builtins/nil.md)) +`->`[`renoise.Views.Stack`](../../API/renoise/renoise.Views.Stack.md) + +> You can add nested child views when constructing stacks by including them +> in the constructor table. Use the view property `origin` to position them +> in the stack. +> +> ```lua +> --Stack multiple views +> vb:stack { +> views = { +> vb:text { +> origin = { 10, 10 }, +> text = "Text1" +> }, +> vb:text { +> origin = { 100, 20 }, +> text = "Text 2" +> } +> } +> } +> ``` +> See: `renoise.Views.Stack` ### space([*self*](../../API/builtins/self.md), properties : [`ViewProperties`](#viewproperties)) > You can create an empty space in layouts with a space. > @@ -143,85 +176,99 @@ > ```lua > --Empty space in layouts > vb:row { -> vb:button { -> text = "Some Button" -> }, -> vb:space { -- extra spacing between buttons -> width = 8 -> }, -> vb:button { -> text = "Another Button" -> }, +> views = { +> vb:button { +> text = "Some Button" +> }, +> vb:space { -- extra spacing between buttons +> width = 8 +> }, +> vb:button { +> text = "Another Button" +> }, +> } > } > ``` +### canvas([*self*](../../API/builtins/self.md), properties : [`CanvasViewProperties`](#canvasviewproperties)[`?`](../../API/builtins/nil.md)) +`->`[`renoise.Views.Canvas`](../../API/renoise/renoise.Views.Canvas.md) + +> See: `renoise.Views.Canvas` ### text([*self*](../../API/builtins/self.md), properties : [`TextViewProperties`](#textviewproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Text`](../../API/renoise/renoise.Views.Text.md) -> See: [renoise.Views.Text](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/text.lua#48#10) +> See: `renoise.Views.Text` ### multiline_text([*self*](../../API/builtins/self.md), properties : [`MultilineTextViewProperties`](#multilinetextviewproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.MultiLineText`](../../API/renoise/renoise.Views.MultiLineText.md) -> See: [renoise.Views.MultiLineText](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/multiline_text.lua#44#10) +> See: `renoise.Views.MultiLineText` ### textfield([*self*](../../API/builtins/self.md), properties : [`TextFieldProperties`](#textfieldproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.TextField`](../../API/renoise/renoise.Views.TextField.md) -> See: [renoise.Views.TextField](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/textfield.lua#41#10) +> See: `renoise.Views.TextField` ### multiline_textfield([*self*](../../API/builtins/self.md), properties : [`MultilineTextFieldProperties`](#multilinetextfieldproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.MultiLineTextField`](../../API/renoise/renoise.Views.MultiLineTextField.md) -> See: [renoise.Views.MultiLineTextField](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/multiline_textfield.lua#22#10) +> See: `renoise.Views.MultiLineTextField` +### link([*self*](../../API/builtins/self.md), properties : [`TextLinkViewProperties`](#textlinkviewproperties)[`?`](../../API/builtins/nil.md)) +`->`[`renoise.Views.TextLink`](../../API/renoise/renoise.Views.TextLink.md) + +> See: `renoise.Views.TextLink` ### bitmap([*self*](../../API/builtins/self.md), properties : [`BitmapViewProperties`](#bitmapviewproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Bitmap`](../../API/renoise/renoise.Views.Bitmap.md) -> See: [renoise.Views.Bitmap](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/bitmap.lua#63#10) +> See: `renoise.Views.Bitmap` ### button([*self*](../../API/builtins/self.md), properties : [`ButtonProperties`](#buttonproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Button`](../../API/renoise/renoise.Views.Button.md) -> See: [renoise.Views.Button](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/button.lua#40#10) +> See: `renoise.Views.Button` ### checkbox([*self*](../../API/builtins/self.md), properties : [`CheckBoxProperties`](#checkboxproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.CheckBox`](../../API/renoise/renoise.Views.CheckBox.md) -> See: [renoise.Views.CheckBox](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/checkbox.lua#28#10) +> See: `renoise.Views.CheckBox` ### switch([*self*](../../API/builtins/self.md), properties : [`ButtonSwitchProperties`](#buttonswitchproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Switch`](../../API/renoise/renoise.Views.Switch.md) -> See: [renoise.Views.Switch](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/switch.lua#30#10) +> See: `renoise.Views.Switch` ### popup([*self*](../../API/builtins/self.md), properties : [`PopUpMenuProperties`](#popupmenuproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Popup`](../../API/renoise/renoise.Views.Popup.md) -> See: [renoise.Views.Popup](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/popup.lua#25#10) +> See: `renoise.Views.Popup` ### chooser([*self*](../../API/builtins/self.md), properties : [`ChooserProperties`](#chooserproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Chooser`](../../API/renoise/renoise.Views.Chooser.md) -> See: [renoise.Views.Chooser](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/chooser.lua#19#10) +> See: `renoise.Views.Chooser` ### valuebox([*self*](../../API/builtins/self.md), properties : [`ValueBoxProperties`](#valueboxproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.ValueBox`](../../API/renoise/renoise.Views.ValueBox.md) -> See: [renoise.Views.ValueBox](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/valuebox.lua#51#10) +> See: `renoise.Views.ValueBox` ### value([*self*](../../API/builtins/self.md), properties : [`ValueViewProperties`](#valueviewproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Value`](../../API/renoise/renoise.Views.Value.md) -> See: [renoise.Views.Value](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/value.lua#20#10) +> See: `renoise.Views.Value` ### valuefield([*self*](../../API/builtins/self.md), properties : [`ValueFieldProperties`](#valuefieldproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.ValueField`](../../API/renoise/renoise.Views.ValueField.md) -> See: [renoise.Views.ValueField](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/valuefield.lua#20#10) +> See: `renoise.Views.ValueField` +### scrollbar([*self*](../../API/builtins/self.md), properties : [`ScrollBarProperties`](#scrollbarproperties)[`?`](../../API/builtins/nil.md)) +`->`[`renoise.Views.ScrollBar`](../../API/renoise/renoise.Views.ScrollBar.md) + +> See: `renoise.Views.ScrollBar` ### slider([*self*](../../API/builtins/self.md), properties : [`SliderProperties`](#sliderproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.Slider`](../../API/renoise/renoise.Views.Slider.md) -> See: [renoise.Views.Slider](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/slider.lua#42#10) +> See: `renoise.Views.Slider` ### minislider([*self*](../../API/builtins/self.md), properties : [`MiniSliderProperties`](#minisliderproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.MiniSlider`](../../API/renoise/renoise.Views.MiniSlider.md) -> See: [renoise.Views.MiniSlider](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/minislider.lua#18#10) +> See: `renoise.Views.MiniSlider` ### rotary([*self*](../../API/builtins/self.md), properties : [`RotaryEncoderProperties`](#rotaryencoderproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.RotaryEncoder`](../../API/renoise/renoise.Views.RotaryEncoder.md) -> See: [renoise.Views.RotaryEncoder](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/rotary.lua#23#10) +> See: `renoise.Views.RotaryEncoder` ### xypad([*self*](../../API/builtins/self.md), properties : [`XYPadProperties`](#xypadproperties)[`?`](../../API/builtins/nil.md)) `->`[`renoise.Views.XYPad`](../../API/renoise/renoise.Views.XYPad.md) -> See: [renoise.Views.XYPad](file:///c%3A/Users/emuell/Development/Renoise-XRNX/definitions/library/renoise/views/xypad.lua#64#10) +> See: `renoise.Views.XYPad` @@ -243,39 +290,78 @@ ### mode : [`AlignerMode`](#AlignerMode)[`?`](../../API/builtins/nil.md) > * Default: "left" (for horizontal_aligner) "top" (for vertical_aligner) +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle)[`?`](../../API/builtins/nil.md) +> Setup a background style for the view. + +### mouse_handler : [`MouseHandler`](#MouseHandler)[`?`](../../API/builtins/nil.md) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### mouse_events : [`MouseEventTypes`](#MouseEventTypes)[`?`](../../API/builtins/nil.md) +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### views : [`AlignerChildViews`](#AlignerChildViews)[`?`](../../API/builtins/nil.md) +> The aligner view's initial child views. +> Views can later on also be added and removed dynamically after construction via +> `aligner:add_view(child)` and `aligner:remove_view(child)` + ### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) > Unique identifier to resolve the view later on in the viewbuilder, > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + --- ## Aliases +### AlignerChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The aligner view's initial child views. +> Views can later on also be added and removed dynamically after construction via +> `aligner:add_view(child)` and `aligner:remove_view(child)` + ### AlignerMode `"bottom"` | `"center"` | `"distribute"` | `"justify"` | `"left"` | `"right"` | `"top"` > ```lua @@ -290,6 +376,78 @@ > | "distribute" -- equally distributes views over the aligners width/height > ``` +### MouseEventButton +`"left"` | `"middle"` | `"right"` +> ```lua +> -- Mouse button of a `MouseEvent` of type "up"|"down"|"double"|"drag". +> MouseEventButton: +> | "left" +> | "right" +> | "middle" +> ``` + +### MouseEventType +`"double"` | `"down"` | `"drag"` | `"enter"` | `"exit"` | `"move"` | `"up"` | `"wheel"` +> ```lua +> -- Event type of a `MouseEvent`. +> MouseEventType: +> | "enter" +> | "exit" +> | "move" +> | "down" +> | "up" +> | "double" +> | "drag" +> | "wheel" +> ``` + +### MouseEventTypes +[`MouseEventType`](#MouseEventType)[] +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### MouseEventWheelDirection +`"down"` | `"left"` | `"right"` | `"up"` +> ```lua +> -- Mouse wheel direction in a `MouseEvent` of type "wheel". +> MouseEventWheelDirection: +> | "up" +> | "down" +> | "left" +> | "right" +> ``` + +### MouseHandler +[`MouseHandlerNotifierFunction`](#MouseHandlerNotifierFunction) | [`MouseHandlerNotifierMethod1`](#MouseHandlerNotifierMethod1) | [`MouseHandlerNotifierMethod2`](#MouseHandlerNotifierMethod2) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### MouseHandlerNotifierFunction +(event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext), event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction) } + + +### MouseHandlerNotifierMethod2 +{ 1 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + +### NotifierMemberContext +[`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) + + ### RackMargin [`integer`](../../API/builtins/integer.md) > Set the "borders" of a rack (left, right, top and bottom inclusively) @@ -301,6 +459,59 @@ > rows, vertically in columns). > * Default: 0 (no spacing) +### ViewBackgroundStyle +`"body"` | `"border"` | `"group"` | `"invisible"` | `"panel"` | `"plain"` +> ```lua +> -- Setup a background style for the view. +> ViewBackgroundStyle: +> | "invisible" -- no background (Default) +> | "plain" -- undecorated, single coloured background +> | "border" -- same as plain, but with a bold nested border +> | "body" -- main "background" style, as used in dialog backgrounds +> | "panel" -- alternative "background" style, beveled +> | "group" -- background for "nested" groups within body +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -314,9 +525,28 @@ > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -335,6 +565,11 @@ ### mode : [`BitmapMode`](#BitmapMode)[`?`](../../API/builtins/nil.md) > Setup how the bitmap should be drawn, recolored. Available modes are: +### color : [`BitmapColor`](#BitmapColor)[`?`](../../API/builtins/nil.md) +> When set, the bitmap will be drawn in the specified color and `mode` is set +> to `custom_color`. Set `mode` to something else than `custom_color` or the +> `color` to `{0, 0, 0}` to enable a `plain` display mode. + ### bitmap : [`BitmapPath`](#BitmapPath)[`?`](../../API/builtins/nil.md) > Supported bitmap file formats are *.bmp, *.png or *.tif (no transparency). @@ -360,34 +595,145 @@ > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + --- ## Aliases +### BitmapColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the bitmap will be drawn in the specified color and `mode` is set +> -- to `custom_color`. Set `mode` to something else than `custom_color` or the +> -- `color` to `{0, 0, 0}` to enable a `plain` display mode. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> BitmapColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### BitmapImagePath [`string`](../../API/builtins/string.md) > You can load an image from your tool's directory, @@ -400,16 +746,19 @@ > If your custom path matches a built-in icon's (like "Icons/ArrowRight.bmp"), > your image will be loaded instead of the one from Renoise. > -> If you want to support high DPI UI scaling with your bitmaps like the built-in Icons, -> include high resolution versions with their filenames ending with "@4x" +> If you want to support high DPI UI scaling with your bitmaps like the +> built-in Icons, include high resolution versions with their filenames ending +> with "@4x" > The following rules will be used when loading bitmaps > * When UI scaling is 100%, only the base bitmaps are used. -> * When UI scaling is 125%, the base bitmaps are used, except if there is a `BitmapName@x1.25.bmp` variant. -> * For all other UI scaling > 125% the "@4x" variants are used and downscaled as needed, -> except when there is an exact match for the current UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) +> * When UI scaling is 125%, the base bitmaps are used, except if there is a +> ` BitmapName@x1.25.bmp` variant. +> * For all other UI scaling > 125% the "@4x" variants are used and +> downscaled as needed, except when there is an exact match for the current +> UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) ### BitmapMode -`"body_color"` | `"button_color"` | `"main_color"` | `"plain"` | `"transparent"` +`"body_color"` | `"button_color"` | `"custom_color"` | `"main_color"` | `"plain"` | `"transparent"` > ```lua > -- Setup how the bitmap should be drawn, recolored. Available modes are: > BitmapMode: @@ -418,6 +767,7 @@ > | "button_color" -- recolor the bitmap, using the theme's button color > | "body_color" -- same as 'button_back' but with body text/back color > | "main_color" -- same as 'button_back' but with main text/back colors +> | "custom_color" -- Recolor the bitmap using a custom color set by the `color' > ``` ### BitmapPath @@ -464,6 +814,146 @@ fun() { 1 : [`NotifierMemberFunction`](#NotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -477,9 +967,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -508,12 +1017,27 @@ fun() > so plain white is the target theme color, and all other colors blend into the > button's background color of the theme. +### align : [`ButtonAlignment`](#ButtonAlignment)[`?`](../../API/builtins/nil.md) +> Setup the buttons text's or bitmap's alignment within the button. + +### font : [`TextFontStyle`](#TextFontStyle)[`?`](../../API/builtins/nil.md) +> The style that the text should be displayed with. + ### color : [`ButtonColor`](#ButtonColor)[`?`](../../API/builtins/nil.md) > When set, the unpressed button's background will be drawn in the specified color. -> A text color is automatically selected unless explicitly set, to make sure it's +> A text color is automatically selected unless explicitly set, to make sure its +> always visible. +> Set color {0,0,0} to enable the theme colors for the button again. + +### secondary_color : [`ButtonColor`](#ButtonColor)[`?`](../../API/builtins/nil.md) +> When set, the unpressed button's background will be drawn in the specified color. +> A text color is automatically selected unless explicitly set, to make sure its > always visible. > Set color {0,0,0} to enable the theme colors for the button again. +### style : [`ButtonStyle`](#ButtonStyle)[`?`](../../API/builtins/nil.md) +> Get/set the style a button should be displayed with. + ### notifier : [`ButtonNotifier`](#ButtonNotifier)[`?`](../../API/builtins/nil.md) > A click notifier @@ -542,28 +1066,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -582,13 +1117,26 @@ fun() > If your custom path matches a built-in icon's (like "Icons/ArrowRight.bmp"), > your image will be loaded instead of the one from Renoise. > -> If you want to support high DPI UI scaling with your bitmaps like the built-in Icons, -> include high resolution versions with their filenames ending with "@4x" +> If you want to support high DPI UI scaling with your bitmaps like the +> built-in Icons, include high resolution versions with their filenames ending +> with "@4x" > The following rules will be used when loading bitmaps > * When UI scaling is 100%, only the base bitmaps are used. -> * When UI scaling is 125%, the base bitmaps are used, except if there is a `BitmapName@x1.25.bmp` variant. -> * For all other UI scaling > 125% the "@4x" variants are used and downscaled as needed, -> except when there is an exact match for the current UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) +> * When UI scaling is 125%, the base bitmaps are used, except if there is a +> ` BitmapName@x1.25.bmp` variant. +> * For all other UI scaling > 125% the "@4x" variants are used and +> downscaled as needed, except when there is an exact match for the current +> UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) + +### ButtonAlignment +`"center"` | `"left"` | `"right"` +> ```lua +> -- Setup the buttons text's or bitmap's alignment within the button. +> ButtonAlignment: +> | "left" -- aligned to the left +> | "right" -- aligned to the right +> | "center" -- center (default) +> ``` ### ButtonBitmapPath [`BitmapImagePath`](#BitmapImagePath) @@ -601,11 +1149,105 @@ fun() > button's background color of the theme. ### ButtonColor -[`RGBColor`](#RGBColor) -> When set, the unpressed button's background will be drawn in the specified color. -> A text color is automatically selected unless explicitly set, to make sure it's -> always visible. -> Set color {0,0,0} to enable the theme colors for the button again. +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the unpressed button's background will be drawn in the specified color. +> -- A text color is automatically selected unless explicitly set, to make sure its +> -- always visible. +> -- Set color {0,0,0} to enable the theme colors for the button again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> ButtonColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` ### ButtonLabel [`string`](../../API/builtins/string.md) @@ -616,6 +1258,19 @@ fun() [`NotifierFunction`](#NotifierFunction) | [`NotifierMethod1`](#NotifierMethod1) | [`NotifierMethod2`](#NotifierMethod2) > A click notifier +### ButtonStyle +`"normal"` | `"rounded"` | `"rounded_bottom"` | `"rounded_left"` | `"rounded_right"` | `"rounded_top"` +> ```lua +> -- Get/set the style a button should be displayed with. +> ButtonStyle: +> | "normal" -- (Default) +> | "rounded" -- rounded corners on all sides +> | "rounded_left" -- rounded left side +> | "rounded_right" -- rounded right side +> | "rounded_top" -- rounded left side +> | "rounded_bottom" -- rounded right side +> ``` + ### ControlActive [`boolean`](../../API/builtins/boolean.md) > Instead of making a control invisible, you can also make it inactive. @@ -659,6 +1314,152 @@ fun() > {0xFF, 0xFF, 0xFF} is white > {165, 73, 35} is the red from the Renoise logo +### TextFontStyle +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` +> ```lua +> -- The style that the text should be displayed with. +> TextFontStyle: +> | "normal" -- (Default) +> | "big" -- big text +> | "bold" -- bold font +> | "italic" -- italic font +> | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -672,9 +1473,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -725,28 +1545,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -805,6 +1636,46 @@ fun() [`integer`](../../API/builtins/integer.md) > The currently selected item's index +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -826,9 +1697,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -840,74 +1730,470 @@ fun() -# CheckBoxProperties +# CanvasViewProperties --- ## Properties -### bind : [`ViewBooleanObservable`](#ViewBooleanObservable)[`?`](../../API/builtins/nil.md) -> Bind the view's value to a renoise.Document.ObservableBoolean object. -> Automatically keep them in sync. -> The view will change the Observable value as soon as its value changes -> and change the view's value as soon as the Observable's value changes. -> Notifiers can be added to either the view or the Observable object. - -### value : [`CheckBoxBoolean`](#CheckBoxBoolean)[`?`](../../API/builtins/nil.md) -> The current state of the checkbox, expressed as boolean. -> * Default: false - -### notifier : [`CheckBoxBooleanNotifier`](#CheckBoxBooleanNotifier)[`?`](../../API/builtins/nil.md) -> A notifier for when the checkbox is toggled - -### active : [`ControlActive`](#ControlActive)[`?`](../../API/builtins/nil.md) -> Instead of making a control invisible, you can also make it inactive. -> Deactivated controls will still be shown, and will still show their -> currently assigned values, but will not allow changes. Most controls will -> display as "grayed out" to visualize the deactivated state. - -### midi_mapping : [`ControlMidiMappingString`](#ControlMidiMappingString)[`?`](../../API/builtins/nil.md) -> When set, the control will be highlighted when Renoise's MIDI mapping dialog -> is open. When clicked, it selects the specified string as a MIDI mapping -> target action. This target acton can either be one of the globally available -> mappings in Renoise, or those that were created by the tool itself. -> Target strings are not verified. When they point to nothing, the mapped MIDI -> message will do nothing and no error is fired. +### mode : [`CanvasMode`](#CanvasMode)[`?`](../../API/builtins/nil.md) +> How to draw the canvas context to screen: "transparent" draws with alpha from +> the canvas, "plain" ignores alpha values, which usually is a lot faster to draw. +> Use "plain" to speed up drawing background alike canvas views which cover the +> entire view area. Default: "transparent" + +### render : [`CanvasRenderFunction`](#CanvasRenderFunction)[`?`](../../API/builtins/nil.md) +> Rendering callback for a canvas. +> +> To update the canvas, use the canvas view's `update` function. +> This will will schedule a new drawing as soon as the backend is ready to draw. +> Always draw a complete image here, as the canvas will be completely empty in +> each new render call. +> +> **UI scaling**: the canvas context by default is set up, so that the global UI +> scaling gets applied. So all positions in the canvas context by default use +> **view sizes** and not pixels. If you want to draw in a raw pixel resolution +> reset the canvas transformation via `context.set_transform(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)` +> To query the actual canvas size in pixels, use the context's `size` property. + +### mouse_handler : [`MouseHandler`](#MouseHandler)[`?`](../../API/builtins/nil.md) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### mouse_events : [`MouseEventTypes`](#MouseEventTypes)[`?`](../../API/builtins/nil.md) +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### views : [`CanvasChildViews`](#CanvasChildViews)[`?`](../../API/builtins/nil.md) +> The canvas view's optional child views. +> Views can later on also be added and removed dynamically after construction via +> `stack:add_view(child)` and `stack:remove_view(child)` ### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) > Unique identifier to resolve the view later on in the viewbuilder, > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + --- ## Aliases -### BooleanValueNotifierFunction -(value : [`boolean`](../../API/builtins/boolean.md)) - +### CanvasChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The canvas view's optional child views. +> Views can later on also be added and removed dynamically after construction via +> `stack:add_view(child)` and `stack:remove_view(child)` + +### CanvasMode +`"plain"` | `"transparent"` +> ```lua +> -- How to draw the canvas context to screen: "transparent" draws with alpha from +> -- the canvas, "plain" ignores alpha values, which usually is a lot faster to draw. +> -- Use "plain" to speed up drawing background alike canvas views which cover the +> -- entire view area. Default: "transparent" +> CanvasMode: +> | "plain" +> | "transparent" +> ``` + +### CanvasRenderFunction +(context : [`renoise.Views.Canvas.Context`](../../API/renoise/renoise.Views.Canvas.Context.md)) +> Rendering callback for a canvas. +> +> To update the canvas, use the canvas view's `update` function. +> This will will schedule a new drawing as soon as the backend is ready to draw. +> Always draw a complete image here, as the canvas will be completely empty in +> each new render call. +> +> **UI scaling**: the canvas context by default is set up, so that the global UI +> scaling gets applied. So all positions in the canvas context by default use +> **view sizes** and not pixels. If you want to draw in a raw pixel resolution +> reset the canvas transformation via `context.set_transform(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)` +> To query the actual canvas size in pixels, use the context's `size` property. + +### MouseEventButton +`"left"` | `"middle"` | `"right"` +> ```lua +> -- Mouse button of a `MouseEvent` of type "up"|"down"|"double"|"drag". +> MouseEventButton: +> | "left" +> | "right" +> | "middle" +> ``` + +### MouseEventType +`"double"` | `"down"` | `"drag"` | `"enter"` | `"exit"` | `"move"` | `"up"` | `"wheel"` +> ```lua +> -- Event type of a `MouseEvent`. +> MouseEventType: +> | "enter" +> | "exit" +> | "move" +> | "down" +> | "up" +> | "double" +> | "drag" +> | "wheel" +> ``` + +### MouseEventTypes +[`MouseEventType`](#MouseEventType)[] +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### MouseEventWheelDirection +`"down"` | `"left"` | `"right"` | `"up"` +> ```lua +> -- Mouse wheel direction in a `MouseEvent` of type "wheel". +> MouseEventWheelDirection: +> | "up" +> | "down" +> | "left" +> | "right" +> ``` + +### MouseHandler +[`MouseHandlerNotifierFunction`](#MouseHandlerNotifierFunction) | [`MouseHandlerNotifierMethod1`](#MouseHandlerNotifierMethod1) | [`MouseHandlerNotifierMethod2`](#MouseHandlerNotifierMethod2) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### MouseHandlerNotifierFunction +(event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext), event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction) } + + +### MouseHandlerNotifierMethod2 +{ 1 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + +### NotifierMemberContext +[`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) + + +### RGBAColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md), 4 : [`integer`](../../API/builtins/integer.md) } +> A table of 4 bytes (ranging from 0 to 255) +> representing the red, green, blue, alpha channels of a color. +> {0xFF, 0xFF, 0xFF, 0xFF} is white +> {165, 73, 35, 0x80} is the red from the Renoise logo, half opaque. + +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size +> for example `vb:text { width = "80%"}`. The percentage values are +> relative to the view's parent size and will automatically update on size changes. + +### ViewId +[`string`](../../API/builtins/string.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + + +# CheckBoxProperties + +--- +## Properties +### bind : [`ViewBooleanObservable`](#ViewBooleanObservable)[`?`](../../API/builtins/nil.md) +> Bind the view's value to a renoise.Document.ObservableBoolean object. +> Automatically keep them in sync. +> The view will change the Observable value as soon as its value changes +> and change the view's value as soon as the Observable's value changes. +> Notifiers can be added to either the view or the Observable object. + +### value : [`CheckBoxBoolean`](#CheckBoxBoolean)[`?`](../../API/builtins/nil.md) +> The current state of the checkbox, expressed as boolean. +> * Default: false + +### notifier : [`CheckBoxBooleanNotifier`](#CheckBoxBooleanNotifier)[`?`](../../API/builtins/nil.md) +> A notifier for when the checkbox is toggled + +### active : [`ControlActive`](#ControlActive)[`?`](../../API/builtins/nil.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### midi_mapping : [`ControlMidiMappingString`](#ControlMidiMappingString)[`?`](../../API/builtins/nil.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + + + + + +--- +## Aliases +### BooleanValueNotifierFunction +(value : [`boolean`](../../API/builtins/boolean.md)) + ### BooleanValueNotifierMemberFunction (self : [`NotifierMemberContext`](#NotifierMemberContext), value : [`boolean`](../../API/builtins/boolean.md)) @@ -962,6 +2248,46 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -975,9 +2301,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1028,28 +2373,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -1108,6 +2464,46 @@ fun() [`integer`](../../API/builtins/integer.md) > The currently selected item's index +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -1129,9 +2525,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1174,6 +2589,13 @@ fun() ### notifier : [`NumberValueNotifier`](#NumberValueNotifier)[`?`](../../API/builtins/nil.md) > Set up a value notifier that will be called whenever the value changes +### polarity : [`SliderPolarity`](#SliderPolarity)[`?`](../../API/builtins/nil.md) +> Value polarity of the control. Bipolar controls show the value from the +> center to left and right or up and down and typically controls a range +> around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> right or bottom to top. +> * Default: "unipolar" + ### min : [`SliderMinValue`](#SliderMinValue)[`?`](../../API/builtins/nil.md) > The minimum value that can be set using the view > * Default: 0 @@ -1190,28 +2612,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -1280,6 +2713,59 @@ fun() [`number`](../../API/builtins/number.md) > The current value of the view +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -1301,9 +2787,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1315,6 +2820,83 @@ fun() +# MouseEvent +> Mouse event as passed to a layout view's "mouse_handler" function. + +--- +## Properties +### type : [`MouseEventType`](#MouseEventType) +> Mouse event type. Only enabled types are passed to the handler. + +### button : [`MouseEventButton`](#MouseEventButton)[`?`](../../API/builtins/nil.md) +> For "up"|"down"|"double"|"drag" events, the mouse button which got pressed, +> nil for all other events. + +### direction : [`MouseEventWheelDirection`](#MouseEventWheelDirection)[`?`](../../API/builtins/nil.md) +> For "wheel" events, the wheel's direction, nil for all other events. + +### position : { x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md) } +> Mouse cursor position in relative coordinates to the layout. + +### modifier_flags : { alt : [`boolean`](../../API/builtins/boolean.md), control : [`boolean`](../../API/builtins/boolean.md), meta : [`boolean`](../../API/builtins/boolean.md), shift : [`boolean`](../../API/builtins/boolean.md) } +> Currently pressed (held down) keyboard modifier buttons. + +### button_flags : { left : [`boolean`](../../API/builtins/boolean.md), middle : [`boolean`](../../API/builtins/boolean.md), right : [`boolean`](../../API/builtins/boolean.md) } +> Currently pressed (held down) mouse buttons. + +### hover_views : { id : [`string`](../../API/builtins/string.md), view : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md) }[] +> List of sub views and possible layout subview's subviews, that are located below +> the mouse cursor. In other words: all views that are located below the mouse cursor. +> The list is orderd by containing the top-most visible view first, so you usually will +> need to check the first table entry only. +> +> NB: Only views that got created with the same view builder instance as the layout, +> and only subviews with valid viewbuilder "id"s will show up here! + + + + + +--- +## Aliases +### MouseEventButton +`"left"` | `"middle"` | `"right"` +> ```lua +> -- Mouse button of a `MouseEvent` of type "up"|"down"|"double"|"drag". +> MouseEventButton: +> | "left" +> | "right" +> | "middle" +> ``` + +### MouseEventType +`"double"` | `"down"` | `"drag"` | `"enter"` | `"exit"` | `"move"` | `"up"` | `"wheel"` +> ```lua +> -- Event type of a `MouseEvent`. +> MouseEventType: +> | "enter" +> | "exit" +> | "move" +> | "down" +> | "up" +> | "double" +> | "drag" +> | "wheel" +> ``` + +### MouseEventWheelDirection +`"down"` | `"left"` | `"right"` | `"up"` +> ```lua +> -- Mouse wheel direction in a `MouseEvent` of type "wheel". +> MouseEventWheelDirection: +> | "up" +> | "down" +> | "left" +> | "right" +> ``` + + + # MultilineTextFieldProperties --- @@ -1363,28 +2945,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -1461,7 +3054,7 @@ fun() > * Default: false ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -1470,6 +3063,7 @@ fun() > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font > ``` ### TextMultilineString @@ -1489,6 +3083,46 @@ fun() > Exactly the same as "value"; provided for consistency. > * Default: "" +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -1502,6 +3136,25 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewStringListObservable [`renoise.Document.ObservableStringList`](../../API/renoise/renoise.Document.ObservableStringList.md) > Bind the view's value to a renoise.Document.ObservableStringList object. @@ -1512,7 +3165,7 @@ fun() ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1549,28 +3202,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -1588,7 +3252,7 @@ fun() > ``` ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -1597,6 +3261,7 @@ fun() > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font > ``` ### TextMultilineString @@ -1611,6 +3276,46 @@ fun() > line with newline characters like "text" > * Default: [] +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -1624,9 +3329,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1678,28 +3402,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -1759,6 +3494,46 @@ fun() [`integer`](../../API/builtins/integer.md) > The currently selected item's index +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -1780,9 +3555,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1807,7 +3601,7 @@ fun() > rows, vertically in columns). > * Default: 0 (no spacing) -### style : [`ViewBackgroundStyle`](#ViewBackgroundStyle)[`?`](../../API/builtins/nil.md) +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle)[`?`](../../API/builtins/nil.md) > Setup a background style for the view. ### uniform : [`RackUniformity`](#RackUniformity)[`?`](../../API/builtins/nil.md) @@ -1818,39 +3612,150 @@ fun() > as a child view size changes or new children are added. > * Default: false +### mouse_handler : [`MouseHandler`](#MouseHandler)[`?`](../../API/builtins/nil.md) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### mouse_events : [`MouseEventTypes`](#MouseEventTypes)[`?`](../../API/builtins/nil.md) +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### views : [`RackChildViews`](#RackChildViews)[`?`](../../API/builtins/nil.md) +> The rack view's initial child views. +> Views can later on also be added and removed dynamically after construction via +> `rack:add_view(child)` and `rack:remove_view(child)` + +### style : [`ViewBackgroundStyle`](#ViewBackgroundStyle)[`?`](../../API/builtins/nil.md) +> **Deprecated** Use `background` instead. + ### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) > Unique identifier to resolve the view later on in the viewbuilder, > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + --- ## Aliases +### MouseEventButton +`"left"` | `"middle"` | `"right"` +> ```lua +> -- Mouse button of a `MouseEvent` of type "up"|"down"|"double"|"drag". +> MouseEventButton: +> | "left" +> | "right" +> | "middle" +> ``` + +### MouseEventType +`"double"` | `"down"` | `"drag"` | `"enter"` | `"exit"` | `"move"` | `"up"` | `"wheel"` +> ```lua +> -- Event type of a `MouseEvent`. +> MouseEventType: +> | "enter" +> | "exit" +> | "move" +> | "down" +> | "up" +> | "double" +> | "drag" +> | "wheel" +> ``` + +### MouseEventTypes +[`MouseEventType`](#MouseEventType)[] +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### MouseEventWheelDirection +`"down"` | `"left"` | `"right"` | `"up"` +> ```lua +> -- Mouse wheel direction in a `MouseEvent` of type "wheel". +> MouseEventWheelDirection: +> | "up" +> | "down" +> | "left" +> | "right" +> ``` + +### MouseHandler +[`MouseHandlerNotifierFunction`](#MouseHandlerNotifierFunction) | [`MouseHandlerNotifierMethod1`](#MouseHandlerNotifierMethod1) | [`MouseHandlerNotifierMethod2`](#MouseHandlerNotifierMethod2) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### MouseHandlerNotifierFunction +(event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext), event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction) } + + +### MouseHandlerNotifierMethod2 +{ 1 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + +### NotifierMemberContext +[`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) + + +### RackChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The rack view's initial child views. +> Views can later on also be added and removed dynamically after construction via +> `rack:add_view(child)` and `rack:remove_view(child)` + ### RackMargin [`integer`](../../API/builtins/integer.md) > Set the "borders" of a rack (left, right, top and bottom inclusively) @@ -1884,6 +3789,46 @@ fun() > | "group" -- background for "nested" groups within body > ``` +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -1897,9 +3842,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -1942,6 +3906,13 @@ fun() ### notifier : [`NumberValueNotifier`](#NumberValueNotifier)[`?`](../../API/builtins/nil.md) > Set up a value notifier that will be called whenever the value changes +### polarity : [`SliderPolarity`](#SliderPolarity)[`?`](../../API/builtins/nil.md) +> Value polarity of the control. Bipolar controls show the value from the +> center to left and right or up and down and typically controls a range +> around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> right or bottom to top. +> * Default: "unipolar" + ### min : [`SliderMinValue`](#SliderMinValue)[`?`](../../API/builtins/nil.md) > The minimum value that can be set using the view > * Default: 0 @@ -1958,28 +3929,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -2048,6 +4030,59 @@ fun() [`number`](../../API/builtins/number.md) > The current value of the view +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -2069,9 +4104,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -2083,7 +4137,7 @@ fun() -# SliderProperties +# ScrollBarProperties --- ## Properties @@ -2108,56 +4162,69 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. -### value : [`SliderNumberValue`](#SliderNumberValue)[`?`](../../API/builtins/nil.md) -> The current value of the view +### value : [`ScrollbarValue`](#ScrollbarValue)[`?`](../../API/builtins/nil.md) +> Default 0. Offset value in range `min to max - pagestep`. ### notifier : [`NumberValueNotifier`](#NumberValueNotifier)[`?`](../../API/builtins/nil.md) > Set up a value notifier that will be called whenever the value changes -### min : [`SliderMinValue`](#SliderMinValue)[`?`](../../API/builtins/nil.md) -> The minimum value that can be set using the view -> * Default: 0 +### min : [`ScrollbarMin`](#ScrollbarMin)[`?`](../../API/builtins/nil.md) +> Default 0. Minimum offset value. -### max : [`SliderMaxValue`](#SliderMaxValue)[`?`](../../API/builtins/nil.md) -> The maximum value that can be set using the view -> * Default: 1.0 +### max : [`ScrollbarMax`](#ScrollbarMax)[`?`](../../API/builtins/nil.md) +> Default 100. Maximum offset value. -### steps : [`SliderStepAmounts`](#SliderStepAmounts)[`?`](../../API/builtins/nil.md) -> A table containing two numbers representing the step amounts for incrementing -> and decrementing by clicking the <> buttons. -> The first value is the small step (applied on left clicks) -> second value is the big step (applied on right clicks) +### step : [`ScrollbarStep`](#ScrollbarStep)[`?`](../../API/builtins/nil.md) +> Default 1. Amount the mouse-wheel or additional +/- buttons in the scroll bar +> move the scrollable area. -### default : [`SliderDefaultValue`](#SliderDefaultValue)[`?`](../../API/builtins/nil.md) -> The default value that will be re-applied on double-click +### pagestep : [`ScrollbarPagestep`](#ScrollbarPagestep)[`?`](../../API/builtins/nil.md) +> Default 100. Size of the currently visible area. + +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle)[`?`](../../API/builtins/nil.md) +> Setup a background style for the view. + +### autohide : [`ScrollbarAutoHide`](#ScrollbarAutoHide)[`?`](../../API/builtins/nil.md) +> Default: false. When true, view gets automatically hidden when no scrolling is needed ### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) > Unique identifier to resolve the view later on in the viewbuilder, > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -2208,30 +4275,83 @@ fun() { 1 : [`NumberValueNotifierMemberFunction`](#NumberValueNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } -### SliderDefaultValue -[`number`](../../API/builtins/number.md) -> The default value that will be re-applied on double-click +### ScrollbarAutoHide +[`boolean`](../../API/builtins/boolean.md) +> Default: false. When true, view gets automatically hidden when no scrolling is needed -### SliderMaxValue -[`number`](../../API/builtins/number.md) -> The maximum value that can be set using the view -> * Default: 1.0 +### ScrollbarMax +[`integer`](../../API/builtins/integer.md) +> Default 100. Maximum offset value. -### SliderMinValue -[`number`](../../API/builtins/number.md) -> The minimum value that can be set using the view -> * Default: 0 +### ScrollbarMin +[`integer`](../../API/builtins/integer.md) +> Default 0. Minimum offset value. -### SliderNumberValue -[`number`](../../API/builtins/number.md) -> The current value of the view +### ScrollbarPagestep +[`integer`](../../API/builtins/integer.md) +> Default 100. Size of the currently visible area. -### SliderStepAmounts -{ 1 : [`number`](../../API/builtins/number.md), 2 : [`number`](../../API/builtins/number.md) } -> A table containing two numbers representing the step amounts for incrementing -> and decrementing by clicking the <> buttons. -> The first value is the small step (applied on left clicks) -> second value is the big step (applied on right clicks) +### ScrollbarStep +[`integer`](../../API/builtins/integer.md) +> Default 1. Amount the mouse-wheel or additional +/- buttons in the scroll bar +> move the scrollable area. + +### ScrollbarValue +[`integer`](../../API/builtins/integer.md) +> Default 0. Offset value in range `min to max - pagestep`. + +### ViewBackgroundStyle +`"body"` | `"border"` | `"group"` | `"invisible"` | `"panel"` | `"plain"` +> ```lua +> -- Setup a background style for the view. +> ViewBackgroundStyle: +> | "invisible" -- no background (Default) +> | "plain" -- undecorated, single coloured background +> | "border" -- same as plain, but with a bold nested border +> | "body" -- main "background" style, as used in dialog backgrounds +> | "panel" -- alternative "background" style, beveled +> | "group" -- background for "nested" groups within body +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) @@ -2254,9 +4374,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -2268,58 +4407,583 @@ fun() -# TextFieldProperties +# SliderProperties --- ## Properties -### bind : [`ViewStringObservable`](#ViewStringObservable)[`?`](../../API/builtins/nil.md) -> Bind the view's value to a renoise.Document.ObservableString object. +### active : [`ControlActive`](#ControlActive)[`?`](../../API/builtins/nil.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### midi_mapping : [`ControlMidiMappingString`](#ControlMidiMappingString)[`?`](../../API/builtins/nil.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### bind : [`ViewNumberObservable`](#ViewNumberObservable)[`?`](../../API/builtins/nil.md) +> Bind the view's value to a renoise.Document.ObservableNumber object. > Automatically keep them in sync. > The view will change the Observable value as soon as its value changes > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. -### active : [`TextActive`](#TextActive)[`?`](../../API/builtins/nil.md) -> When false, text is displayed but can not be entered/modified by the user. -> * Default: true +### value : [`SliderNumberValue`](#SliderNumberValue)[`?`](../../API/builtins/nil.md) +> The current value of the view -### value : [`TextValue`](#TextValue)[`?`](../../API/builtins/nil.md) -> The currently shown text. The text will not be updated when editing, -> rather only after editing is complete (return is pressed, or focus is lost). -> * Default: "" +### notifier : [`NumberValueNotifier`](#NumberValueNotifier)[`?`](../../API/builtins/nil.md) +> Set up a value notifier that will be called whenever the value changes -### notifier : [`StringChangeNotifier`](#StringChangeNotifier)[`?`](../../API/builtins/nil.md) -> Set up a notifier for text changes +### polarity : [`SliderPolarity`](#SliderPolarity)[`?`](../../API/builtins/nil.md) +> Value polarity of the control. Bipolar controls show the value from the +> center to left and right or up and down and typically controls a range +> around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> right or bottom to top. +> * Default: "unipolar" -### text : [`TextValueAlias`](#TextValueAlias)[`?`](../../API/builtins/nil.md) -> Exactly the same as "value"; provided for consistency. -> * Default: "" +### min : [`SliderMinValue`](#SliderMinValue)[`?`](../../API/builtins/nil.md) +> The minimum value that can be set using the view +> * Default: 0 -### align : [`TextAlignment`](#TextAlignment)[`?`](../../API/builtins/nil.md) -> Setup the text's alignment. Applies only when the view's size is larger than -> the needed size to draw the text +### max : [`SliderMaxValue`](#SliderMaxValue)[`?`](../../API/builtins/nil.md) +> The maximum value that can be set using the view +> * Default: 1.0 -### edit_mode : [`TextEditMode`](#TextEditMode)[`?`](../../API/builtins/nil.md) -> True when the text field is focused. setting it at run-time programmatically -> will focus the text field or remove the focus (focus the dialog) accordingly. -> * Default: false +### steps : [`SliderStepAmounts`](#SliderStepAmounts)[`?`](../../API/builtins/nil.md) +> A table containing two numbers representing the step amounts for incrementing +> and decrementing by clicking the <> buttons. +> The first value is the small step (applied on left clicks) +> second value is the big step (applied on right clicks) + +### default : [`SliderDefaultValue`](#SliderDefaultValue)[`?`](../../API/builtins/nil.md) +> The default value that will be re-applied on double-click ### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) > Unique identifier to resolve the view later on in the viewbuilder, > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + + + + + +--- +## Aliases +### ControlActive +[`boolean`](../../API/builtins/boolean.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### ControlMidiMappingString +[`string`](../../API/builtins/string.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### NotifierFunction +fun() + + +### NotifierMemberContext +[`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) + + +### NumberValueNotifier +[`NumberValueNotifierFunction`](#NumberValueNotifierFunction) | [`NumberValueNotifierMethod1`](#NumberValueNotifierMethod1) | [`NumberValueNotifierMethod2`](#NumberValueNotifierMethod2) +> Set up a value notifier that will be called whenever the value changes + +### NumberValueNotifierFunction +(value : [`number`](../../API/builtins/number.md)) + + +### NumberValueNotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext), value : [`number`](../../API/builtins/number.md)) + + +### NumberValueNotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`NumberValueNotifierMemberFunction`](#NumberValueNotifierMemberFunction) } + + +### NumberValueNotifierMethod2 +{ 1 : [`NumberValueNotifierMemberFunction`](#NumberValueNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + +### SliderDefaultValue +[`number`](../../API/builtins/number.md) +> The default value that will be re-applied on double-click + +### SliderMaxValue +[`number`](../../API/builtins/number.md) +> The maximum value that can be set using the view +> * Default: 1.0 + +### SliderMinValue +[`number`](../../API/builtins/number.md) +> The minimum value that can be set using the view +> * Default: 0 + +### SliderNumberValue +[`number`](../../API/builtins/number.md) +> The current value of the view + +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + +### SliderStepAmounts +{ 1 : [`number`](../../API/builtins/number.md), 2 : [`number`](../../API/builtins/number.md) } +> A table containing two numbers representing the step amounts for incrementing +> and decrementing by clicking the <> buttons. +> The first value is the small step (applied on left clicks) +> second value is the big step (applied on right clicks) + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. > For nested views you can also specify relative size > for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> relative to the view's parent size and will automatically update on size changes. + +### ViewId +[`string`](../../API/builtins/string.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### ViewNumberObservable +[`renoise.Document.ObservableNumber`](../../API/renoise/renoise.Document.ObservableNumber.md) +> Bind the view's value to a renoise.Document.ObservableNumber object. +> Automatically keep them in sync. +> The view will change the Observable value as soon as its value changes +> and change the view's value as soon as the Observable's value changes. +> Notifiers can be added to either the view or the Observable object. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + + +# StackViewProperties + +--- +## Properties +### autosize : [`StackAutoSize`](#StackAutoSize)[`?`](../../API/builtins/nil.md) +> When set to true, the width and height of the stack will be automatically +> calculated and updated from the stack's child views, to ensure all views fit +> into the stack. +> When disabled, the width and height must be set manually. +> * Default: true + +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle)[`?`](../../API/builtins/nil.md) +> Setup a background style for the view. + +### mouse_handler : [`MouseHandler`](#MouseHandler)[`?`](../../API/builtins/nil.md) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### mouse_events : [`MouseEventTypes`](#MouseEventTypes)[`?`](../../API/builtins/nil.md) +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### views : [`StackChildViews`](#StackChildViews)[`?`](../../API/builtins/nil.md) +> The stack view's optional child views. +> Views can later on also be added and removed dynamically after construction via +> `stack:add_view(child)` and `stack:remove_view(child)` + +### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + + + + + +--- +## Aliases +### MouseEventButton +`"left"` | `"middle"` | `"right"` +> ```lua +> -- Mouse button of a `MouseEvent` of type "up"|"down"|"double"|"drag". +> MouseEventButton: +> | "left" +> | "right" +> | "middle" +> ``` + +### MouseEventType +`"double"` | `"down"` | `"drag"` | `"enter"` | `"exit"` | `"move"` | `"up"` | `"wheel"` +> ```lua +> -- Event type of a `MouseEvent`. +> MouseEventType: +> | "enter" +> | "exit" +> | "move" +> | "down" +> | "up" +> | "double" +> | "drag" +> | "wheel" +> ``` + +### MouseEventTypes +[`MouseEventType`](#MouseEventType)[] +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### MouseEventWheelDirection +`"down"` | `"left"` | `"right"` | `"up"` +> ```lua +> -- Mouse wheel direction in a `MouseEvent` of type "wheel". +> MouseEventWheelDirection: +> | "up" +> | "down" +> | "left" +> | "right" +> ``` + +### MouseHandler +[`MouseHandlerNotifierFunction`](#MouseHandlerNotifierFunction) | [`MouseHandlerNotifierMethod1`](#MouseHandlerNotifierMethod1) | [`MouseHandlerNotifierMethod2`](#MouseHandlerNotifierMethod2) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### MouseHandlerNotifierFunction +(event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext), event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction) } + + +### MouseHandlerNotifierMethod2 +{ 1 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + +### NotifierMemberContext +[`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) + + +### StackAutoSize +[`boolean`](../../API/builtins/boolean.md) +> When set to true, the width and height of the stack will be automatically +> calculated and updated from the stack's child views, to ensure all views fit +> into the stack. +> When disabled, the width and height must be set manually. +> * Default: true + +### StackChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The stack view's optional child views. +> Views can later on also be added and removed dynamically after construction via +> `stack:add_view(child)` and `stack:remove_view(child)` + +### ViewBackgroundStyle +`"body"` | `"border"` | `"group"` | `"invisible"` | `"panel"` | `"plain"` +> ```lua +> -- Setup a background style for the view. +> ViewBackgroundStyle: +> | "invisible" -- no background (Default) +> | "plain" -- undecorated, single coloured background +> | "border" -- same as plain, but with a bold nested border +> | "body" -- main "background" style, as used in dialog backgrounds +> | "panel" -- alternative "background" style, beveled +> | "group" -- background for "nested" groups within body +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. > For nested views you can also specify relative size > for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> relative to the view's parent size and will automatically update on size changes. + +### ViewId +[`string`](../../API/builtins/string.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + + +# TextFieldProperties + +--- +## Properties +### bind : [`ViewStringObservable`](#ViewStringObservable)[`?`](../../API/builtins/nil.md) +> Bind the view's value to a renoise.Document.ObservableString object. +> Automatically keep them in sync. +> The view will change the Observable value as soon as its value changes +> and change the view's value as soon as the Observable's value changes. +> Notifiers can be added to either the view or the Observable object. + +### active : [`TextActive`](#TextActive)[`?`](../../API/builtins/nil.md) +> When false, text is displayed but can not be entered/modified by the user. +> * Default: true + +### value : [`TextValue`](#TextValue)[`?`](../../API/builtins/nil.md) +> The currently shown text. The text will not be updated when editing, +> rather only after editing is complete (return is pressed, or focus is lost). +> * Default: "" + +### notifier : [`StringChangeNotifier`](#StringChangeNotifier)[`?`](../../API/builtins/nil.md) +> Set up a notifier for text changes + +### text : [`TextValueAlias`](#TextValueAlias)[`?`](../../API/builtins/nil.md) +> Exactly the same as "value"; provided for consistency. +> * Default: "" + +### align : [`TextAlignment`](#TextAlignment)[`?`](../../API/builtins/nil.md) +> Setup the text's alignment. Applies only when the view's size is larger than +> the needed size to draw the text + +### edit_mode : [`TextEditMode`](#TextEditMode)[`?`](../../API/builtins/nil.md) +> True when the text field is focused. setting it at run-time programmatically +> will focus the text field or remove the focus (focus the dialog) accordingly. +> * Default: false + +### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing @@ -2327,10 +4991,33 @@ fun() > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -2398,6 +5085,46 @@ fun() > Exactly the same as "value"; provided for consistency. > * Default: "" +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -2411,6 +5138,25 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewStringObservable [`renoise.Document.ObservableString`](../../API/renoise/renoise.Document.ObservableString.md) > Bind the view's value to a renoise.Document.ObservableString object. @@ -2421,7 +5167,479 @@ fun() ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + + +# TextLinkViewProperties + +--- +## Properties +### active : [`ControlActive`](#ControlActive)[`?`](../../API/builtins/nil.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### midi_mapping : [`ControlMidiMappingString`](#ControlMidiMappingString)[`?`](../../API/builtins/nil.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### notifier : [`ButtonNotifier`](#ButtonNotifier)[`?`](../../API/builtins/nil.md) +> A click notifier + +### pressed : [`ButtonNotifier`](#ButtonNotifier)[`?`](../../API/builtins/nil.md) +> A click notifier + +### released : [`ButtonNotifier`](#ButtonNotifier)[`?`](../../API/builtins/nil.md) +> A click notifier + +### text : [`TextSingleLineString`](#TextSingleLineString)[`?`](../../API/builtins/nil.md) +> The text that should be displayed. Setting a new text will resize +> the view in order to make the text fully visible (expanding only). +> * Default: "" + +### font : [`TextFontStyle`](#TextFontStyle)[`?`](../../API/builtins/nil.md) +> The style that the text should be displayed with. + +### style : [`TextStyle`](#TextStyle)[`?`](../../API/builtins/nil.md) +> Get/set the color style the text should be displayed with. + +### color : [`TextColor`](#TextColor)[`?`](../../API/builtins/nil.md) +> When set, the text will be drawn in the specified color. +> Set style to something else than "custom" or color to `{0, 0, 0}` +> to enable the default theme color for the text again. + +### orientation : [`TextOrientation`](#TextOrientation)[`?`](../../API/builtins/nil.md) +> Setup the texts's orientation (writing direction). + +### align : [`TextAlignment`](#TextAlignment)[`?`](../../API/builtins/nil.md) +> Setup the text's alignment. Applies only when the view's size is larger than +> the needed size to draw the text + +### id : [`ViewId`](#ViewId)[`?`](../../API/builtins/nil.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + + + + + +--- +## Aliases +### ButtonNotifier +[`NotifierFunction`](#NotifierFunction) | [`NotifierMethod1`](#NotifierMethod1) | [`NotifierMethod2`](#NotifierMethod2) +> A click notifier + +### ControlActive +[`boolean`](../../API/builtins/boolean.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### ControlMidiMappingString +[`string`](../../API/builtins/string.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### NotifierFunction +fun() + + +### NotifierMemberContext +[`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) + + +### NotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext)) + + +### NotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`NotifierMemberFunction`](#NotifierMemberFunction) } + + +### NotifierMethod2 +{ 1 : [`NotifierMemberFunction`](#NotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### TextAlignment +`"center"` | `"left"` | `"right"` +> ```lua +> -- Setup the text's alignment. Applies only when the view's size is larger than +> -- the needed size to draw the text +> TextAlignment: +> | "left" -- (Default) +> | "right" -- aligned to the right +> | "center" -- center text +> ``` + +### TextColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the text will be drawn in the specified color. +> -- Set style to something else than "custom" or color to `{0, 0, 0}` +> -- to enable the default theme color for the text again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> TextColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### TextFontStyle +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` +> ```lua +> -- The style that the text should be displayed with. +> TextFontStyle: +> | "normal" -- (Default) +> | "big" -- big text +> | "bold" -- bold font +> | "italic" -- italic font +> | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### TextOrientation +`"horizontal"` | `"horizontal-rl"` | `"vertical"` | `"vertical-tb"` +> ```lua +> -- Setup the texts's orientation (writing direction). +> TextOrientation: +> | "horizontal" -- Draw from left to right (Default) +> | "horizontal-rl" -- Draw from right to left +> | "vertical" -- Draw from bottom to top +> | "vertical-tb" -- Draw from top to bottom +> ``` + +### TextSingleLineString +[`string`](../../API/builtins/string.md) +> The text that should be displayed. Setting a new text will resize +> the view in order to make the text fully visible (expanding only). +> * Default: "" + +### TextStyle +`"custom"` | `"disabled"` | `"normal"` | `"strong"` +> ```lua +> -- Get/set the color style the text should be displayed with. +> TextStyle: +> | "normal" -- (Default) +> | "strong" -- highlighted color +> | "disabled" -- greyed out color +> | "custom" -- custom color +> ``` + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size +> for example `vb:text { width = "80%"}`. The percentage values are +> relative to the view's parent size and will automatically update on size changes. + +### ViewId +[`string`](../../API/builtins/string.md) +> Unique identifier to resolve the view later on in the viewbuilder, +> e.g. `vb.views.SomeString` or `vb.views["Some String"]` +> View ids must be unique within a single view builder instance. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -2448,6 +5666,14 @@ fun() ### style : [`TextStyle`](#TextStyle)[`?`](../../API/builtins/nil.md) > Get/set the color style the text should be displayed with. +### color : [`TextColor`](#TextColor)[`?`](../../API/builtins/nil.md) +> When set, the text will be drawn in the specified color. +> Set style to something else than "custom" or color to `{0, 0, 0}` +> to enable the default theme color for the text again. + +### orientation : [`TextOrientation`](#TextOrientation)[`?`](../../API/builtins/nil.md) +> Setup the texts's orientation (writing direction). + ### align : [`TextAlignment`](#TextAlignment)[`?`](../../API/builtins/nil.md) > Setup the text's alignment. Applies only when the view's size is larger than > the needed size to draw the text @@ -2457,34 +5683,52 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + --- ## Aliases +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + ### TextAlignment `"center"` | `"left"` | `"right"` > ```lua @@ -2496,8 +5740,108 @@ fun() > | "center" -- center text > ``` +### TextColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the text will be drawn in the specified color. +> -- Set style to something else than "custom" or color to `{0, 0, 0}` +> -- to enable the default theme color for the text again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> TextColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -2506,6 +5850,18 @@ fun() > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### TextOrientation +`"horizontal"` | `"horizontal-rl"` | `"vertical"` | `"vertical-tb"` +> ```lua +> -- Setup the texts's orientation (writing direction). +> TextOrientation: +> | "horizontal" -- Draw from left to right (Default) +> | "horizontal-rl" -- Draw from right to left +> | "vertical" -- Draw from bottom to top +> | "vertical-tb" -- Draw from top to bottom > ``` ### TextSingleLineString @@ -2515,13 +5871,147 @@ fun() > * Default: "" ### TextStyle -`"disabled"` | `"normal"` | `"strong"` +`"custom"` | `"disabled"` | `"normal"` | `"strong"` > ```lua > -- Get/set the color style the text should be displayed with. > TextStyle: > | "normal" -- (Default) > | "strong" -- highlighted color > | "disabled" -- greyed out color +> | "custom" -- custom color +> ``` + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" > ``` ### ViewDimension @@ -2537,9 +6027,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -2607,28 +6116,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -2717,6 +6237,46 @@ fun() > The minimum value that can be set using the view > * Default: 0 +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -2738,9 +6298,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -2806,28 +6385,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -2920,6 +6510,46 @@ fun() > | "center" -- center text > ``` +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -2941,9 +6571,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -2992,28 +6641,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + @@ -3073,7 +6733,7 @@ fun() > ``` ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -3082,6 +6742,47 @@ fun() > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" > ``` ### ViewDimension @@ -3105,9 +6806,28 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -3129,34 +6849,85 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + --- ## Aliases +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -3170,9 +6941,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -3207,28 +6997,39 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. -### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - -### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. - ### visible : [`ViewVisibility`](#ViewVisibility)[`?`](../../API/builtins/nil.md) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin)[`?`](../../API/builtins/nil.md) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension)[`?`](../../API/builtins/nil.md) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize)[`?`](../../API/builtins/nil.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### tooltip : [`ViewTooltip`](#ViewTooltip)[`?`](../../API/builtins/nil.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape)[`?`](../../API/builtins/nil.md) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### bind : [`XYPadObservables`](#XYPadObservables)[`?`](../../API/builtins/nil.md) > Bind the view's value to a pair of renoise.Document.ObservableNumber objects. > Automatically keep both values in sync. @@ -3304,6 +7105,46 @@ fun() [`number`](../../API/builtins/number.md) > The current value of the view +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -3317,9 +7158,28 @@ fun() > e.g. `vb.views.SomeString` or `vb.views["Some String"]` > View ids must be unique within a single view builder instance. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility @@ -3389,6 +7249,12 @@ fun() --- ## Aliases +### AlignerChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The aligner view's initial child views. +> Views can later on also be added and removed dynamically after construction via +> `aligner:add_view(child)` and `aligner:remove_view(child)` + ### AlignerMode `"bottom"` | `"center"` | `"distribute"` | `"justify"` | `"left"` | `"right"` | `"top"` > ```lua @@ -3403,6 +7269,106 @@ fun() > | "distribute" -- equally distributes views over the aligners width/height > ``` +### BitmapColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the bitmap will be drawn in the specified color and `mode` is set +> -- to `custom_color`. Set `mode` to something else than `custom_color` or the +> -- `color` to `{0, 0, 0}` to enable a `plain` display mode. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> BitmapColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### BitmapImagePath [`string`](../../API/builtins/string.md) > You can load an image from your tool's directory, @@ -3415,16 +7381,19 @@ fun() > If your custom path matches a built-in icon's (like "Icons/ArrowRight.bmp"), > your image will be loaded instead of the one from Renoise. > -> If you want to support high DPI UI scaling with your bitmaps like the built-in Icons, -> include high resolution versions with their filenames ending with "@4x" +> If you want to support high DPI UI scaling with your bitmaps like the +> built-in Icons, include high resolution versions with their filenames ending +> with "@4x" > The following rules will be used when loading bitmaps > * When UI scaling is 100%, only the base bitmaps are used. -> * When UI scaling is 125%, the base bitmaps are used, except if there is a `BitmapName@x1.25.bmp` variant. -> * For all other UI scaling > 125% the "@4x" variants are used and downscaled as needed, -> except when there is an exact match for the current UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) +> * When UI scaling is 125%, the base bitmaps are used, except if there is a +> ` BitmapName@x1.25.bmp` variant. +> * For all other UI scaling > 125% the "@4x" variants are used and +> downscaled as needed, except when there is an exact match for the current +> UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) ### BitmapMode -`"body_color"` | `"button_color"` | `"main_color"` | `"plain"` | `"transparent"` +`"body_color"` | `"button_color"` | `"custom_color"` | `"main_color"` | `"plain"` | `"transparent"` > ```lua > -- Setup how the bitmap should be drawn, recolored. Available modes are: > BitmapMode: @@ -3433,6 +7402,7 @@ fun() > | "button_color" -- recolor the bitmap, using the theme's button color > | "body_color" -- same as 'button_back' but with body text/back color > | "main_color" -- same as 'button_back' but with main text/back colors +> | "custom_color" -- Recolor the bitmap using a custom color set by the `color' > ``` ### BitmapPath @@ -3455,6 +7425,16 @@ fun() { 1 : [`BooleanValueNotifierMemberFunction`](#BooleanValueNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } +### ButtonAlignment +`"center"` | `"left"` | `"right"` +> ```lua +> -- Setup the buttons text's or bitmap's alignment within the button. +> ButtonAlignment: +> | "left" -- aligned to the left +> | "right" -- aligned to the right +> | "center" -- center (default) +> ``` + ### ButtonBitmapPath [`BitmapImagePath`](#BitmapImagePath) > If set, existing text is removed and the loaded image is displayed instead. @@ -3466,11 +7446,105 @@ fun() > button's background color of the theme. ### ButtonColor -[`RGBColor`](#RGBColor) -> When set, the unpressed button's background will be drawn in the specified color. -> A text color is automatically selected unless explicitly set, to make sure it's -> always visible. -> Set color {0,0,0} to enable the theme colors for the button again. +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the unpressed button's background will be drawn in the specified color. +> -- A text color is automatically selected unless explicitly set, to make sure its +> -- always visible. +> -- Set color {0,0,0} to enable the theme colors for the button again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> ButtonColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` ### ButtonLabel [`string`](../../API/builtins/string.md) @@ -3481,6 +7555,52 @@ fun() [`NotifierFunction`](#NotifierFunction) | [`NotifierMethod1`](#NotifierMethod1) | [`NotifierMethod2`](#NotifierMethod2) > A click notifier +### ButtonStyle +`"normal"` | `"rounded"` | `"rounded_bottom"` | `"rounded_left"` | `"rounded_right"` | `"rounded_top"` +> ```lua +> -- Get/set the style a button should be displayed with. +> ButtonStyle: +> | "normal" -- (Default) +> | "rounded" -- rounded corners on all sides +> | "rounded_left" -- rounded left side +> | "rounded_right" -- rounded right side +> | "rounded_top" -- rounded left side +> | "rounded_bottom" -- rounded right side +> ``` + +### CanvasChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The canvas view's optional child views. +> Views can later on also be added and removed dynamically after construction via +> `stack:add_view(child)` and `stack:remove_view(child)` + +### CanvasMode +`"plain"` | `"transparent"` +> ```lua +> -- How to draw the canvas context to screen: "transparent" draws with alpha from +> -- the canvas, "plain" ignores alpha values, which usually is a lot faster to draw. +> -- Use "plain" to speed up drawing background alike canvas views which cover the +> -- entire view area. Default: "transparent" +> CanvasMode: +> | "plain" +> | "transparent" +> ``` + +### CanvasRenderFunction +(context : [`renoise.Views.Canvas.Context`](../../API/renoise/renoise.Views.Canvas.Context.md)) +> Rendering callback for a canvas. +> +> To update the canvas, use the canvas view's `update` function. +> This will will schedule a new drawing as soon as the backend is ready to draw. +> Always draw a complete image here, as the canvas will be completely empty in +> each new render call. +> +> **UI scaling**: the canvas context by default is set up, so that the global UI +> scaling gets applied. So all positions in the canvas context by default use +> **view sizes** and not pixels. If you want to draw in a raw pixel resolution +> reset the canvas transformation via `context.set_transform(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)` +> To query the actual canvas size in pixels, use the context's `size` property. + ### CheckBoxBoolean [`boolean`](../../API/builtins/boolean.md) > The current state of the checkbox, expressed as boolean. @@ -3554,6 +7674,74 @@ fun() [`table`](../../API/builtins/table.md) | [`userdata`](../../API/builtins/userdata.md) +### MouseEventButton +`"left"` | `"middle"` | `"right"` +> ```lua +> -- Mouse button of a `MouseEvent` of type "up"|"down"|"double"|"drag". +> MouseEventButton: +> | "left" +> | "right" +> | "middle" +> ``` + +### MouseEventType +`"double"` | `"down"` | `"drag"` | `"enter"` | `"exit"` | `"move"` | `"up"` | `"wheel"` +> ```lua +> -- Event type of a `MouseEvent`. +> MouseEventType: +> | "enter" +> | "exit" +> | "move" +> | "down" +> | "up" +> | "double" +> | "drag" +> | "wheel" +> ``` + +### MouseEventTypes +[`MouseEventType`](#MouseEventType)[] +> The mouse event types that should be passed to your `mouse_handler` function. +> By default: `{ "down", "up", "double" }` +> Avoid adding event types that you don't use, especially "move" events as they do +> create quite some overhead. Also note that when enabling "drag", sub view controls +> can no longer handle drag events, even when you pass back the event in the handler, +> so only enable it when you want to completely override mouse drag behavior of +> *all* your content views. + +### MouseEventWheelDirection +`"down"` | `"left"` | `"right"` | `"up"` +> ```lua +> -- Mouse wheel direction in a `MouseEvent` of type "wheel". +> MouseEventWheelDirection: +> | "up" +> | "down" +> | "left" +> | "right" +> ``` + +### MouseHandler +[`MouseHandlerNotifierFunction`](#MouseHandlerNotifierFunction) | [`MouseHandlerNotifierMethod1`](#MouseHandlerNotifierMethod1) | [`MouseHandlerNotifierMethod2`](#MouseHandlerNotifierMethod2) +> Optional mouse event handler for a view. return nil when the event got handled +> to stop propagating the event. return the event instance, as passed, to pass it +> to the next view in the view hirarchy. + +### MouseHandlerNotifierFunction +(event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMemberFunction +(self : [`NotifierMemberContext`](#NotifierMemberContext), event : [`MouseEvent`](#mouseevent)) `->` [`MouseEvent`](#mouseevent)[`?`](../../API/builtins/nil.md) + + +### MouseHandlerNotifierMethod1 +{ 1 : [`NotifierMemberContext`](#NotifierMemberContext), 2 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction) } + + +### MouseHandlerNotifierMethod2 +{ 1 : [`MouseHandlerNotifierMemberFunction`](#MouseHandlerNotifierMemberFunction), 2 : [`NotifierMemberContext`](#NotifierMemberContext) } + + ### NotifierFunction fun() @@ -3607,6 +7795,13 @@ fun() > A list of buttons labels to show in order > The list can be empty, then "None" is displayed and the value won't change. +### RGBAColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md), 4 : [`integer`](../../API/builtins/integer.md) } +> A table of 4 bytes (ranging from 0 to 255) +> representing the red, green, blue, alpha channels of a color. +> {0xFF, 0xFF, 0xFF, 0xFF} is white +> {165, 73, 35, 0x80} is the red from the Renoise logo, half opaque. + ### RGBColor { 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } > A table of 3 bytes (ranging from 0 to 255) @@ -3614,6 +7809,12 @@ fun() > {0xFF, 0xFF, 0xFF} is white > {165, 73, 35} is the red from the Renoise logo +### RackChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The rack view's initial child views. +> Views can later on also be added and removed dynamically after construction via +> `rack:add_view(child)` and `rack:remove_view(child)` + ### RackMargin [`integer`](../../API/builtins/integer.md) > Set the "borders" of a rack (left, right, top and bottom inclusively) @@ -3634,6 +7835,31 @@ fun() > as a child view size changes or new children are added. > * Default: false +### ScrollbarAutoHide +[`boolean`](../../API/builtins/boolean.md) +> Default: false. When true, view gets automatically hidden when no scrolling is needed + +### ScrollbarMax +[`integer`](../../API/builtins/integer.md) +> Default 100. Maximum offset value. + +### ScrollbarMin +[`integer`](../../API/builtins/integer.md) +> Default 0. Minimum offset value. + +### ScrollbarPagestep +[`integer`](../../API/builtins/integer.md) +> Default 100. Size of the currently visible area. + +### ScrollbarStep +[`integer`](../../API/builtins/integer.md) +> Default 1. Amount the mouse-wheel or additional +/- buttons in the scroll bar +> move the scrollable area. + +### ScrollbarValue +[`integer`](../../API/builtins/integer.md) +> Default 0. Offset value in range `min to max - pagestep`. + ### SelectedItem [`integer`](../../API/builtins/integer.md) > The currently selected item's index @@ -3665,6 +7891,19 @@ fun() [`number`](../../API/builtins/number.md) > The current value of the view +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + ### SliderStepAmounts { 1 : [`number`](../../API/builtins/number.md), 2 : [`number`](../../API/builtins/number.md) } > A table containing two numbers representing the step amounts for incrementing @@ -3672,6 +7911,20 @@ fun() > The first value is the small step (applied on left clicks) > second value is the big step (applied on right clicks) +### StackAutoSize +[`boolean`](../../API/builtins/boolean.md) +> When set to true, the width and height of the stack will be automatically +> calculated and updated from the stack's child views, to ensure all views fit +> into the stack. +> When disabled, the width and height must be set manually. +> * Default: true + +### StackChildViews +[`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> The stack view's optional child views. +> Views can later on also be added and removed dynamically after construction via +> `stack:add_view(child)` and `stack:remove_view(child)` + ### StringChangeNotifier [`StringValueNotifierFunction`](#StringValueNotifierFunction) | [`StringValueNotifierMethod1`](#StringValueNotifierMethod1) | [`StringValueNotifierMethod2`](#StringValueNotifierMethod2) > Set up a notifier for text changes @@ -3718,6 +7971,106 @@ fun() > | "border" -- text on a bordered background > ``` +### TextColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the text will be drawn in the specified color. +> -- Set style to something else than "custom" or color to `{0, 0, 0}` +> -- to enable the default theme color for the text again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> TextColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### TextEditMode [`boolean`](../../API/builtins/boolean.md) > True when the text field is focused. setting it at run-time programmatically @@ -3725,7 +8078,7 @@ fun() > * Default: false ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -3734,6 +8087,7 @@ fun() > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font > ``` ### TextMultilineString @@ -3742,6 +8096,17 @@ fun() > Newlines (Windows, Mac or Unix styled) in the text can be used to create > paragraphs. +### TextOrientation +`"horizontal"` | `"horizontal-rl"` | `"vertical"` | `"vertical-tb"` +> ```lua +> -- Setup the texts's orientation (writing direction). +> TextOrientation: +> | "horizontal" -- Draw from left to right (Default) +> | "horizontal-rl" -- Draw from right to left +> | "vertical" -- Draw from bottom to top +> | "vertical-tb" -- Draw from top to bottom +> ``` + ### TextParagraphs [`string`](../../API/builtins/string.md)[] > A table of text lines to be used instead of specifying a single text @@ -3755,13 +8120,14 @@ fun() > * Default: "" ### TextStyle -`"disabled"` | `"normal"` | `"strong"` +`"custom"` | `"disabled"` | `"normal"` | `"strong"` > ```lua > -- Get/set the color style the text should be displayed with. > TextStyle: > | "normal" -- (Default) > | "strong" -- highlighted color > | "disabled" -- greyed out color +> | "custom" -- custom color > ``` ### TextValue @@ -3775,6 +8141,99 @@ fun() > Exactly the same as "value"; provided for consistency. > * Default: "" +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### ValueBoxMaxValue [`number`](../../API/builtins/number.md) > The maximum value that can be set using the view @@ -3806,6 +8265,46 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -3827,6 +8326,25 @@ fun() > and change the view's value as soon as the Observable's value changes. > Notifiers can be added to either the view or the Observable object. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewStringListObservable [`renoise.Document.ObservableStringList`](../../API/renoise/renoise.Document.ObservableStringList.md) > Bind the view's value to a renoise.Document.ObservableStringList object. @@ -3845,7 +8363,7 @@ fun() ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Aligner.md b/docs/API/renoise/renoise.Views.Aligner.md index 64a47466..eca821c6 100644 --- a/docs/API/renoise/renoise.Views.Aligner.md +++ b/docs/API/renoise/renoise.Views.Aligner.md @@ -23,28 +23,42 @@ ### mode : [`AlignerMode`](#AlignerMode) > * Default: "left" (for horizontal_aligner) "top" (for vertical_aligner) +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle) +> Setup a background style for the view. + ### visible : [`ViewVisibility`](#ViewVisibility) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -53,10 +67,19 @@ --- ## Functions -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -87,6 +110,59 @@ > rows, vertically in columns). > * Default: 0 (no spacing) +### ViewBackgroundStyle +`"body"` | `"border"` | `"group"` | `"invisible"` | `"panel"` | `"plain"` +> ```lua +> -- Setup a background style for the view. +> ViewBackgroundStyle: +> | "invisible" -- no background (Default) +> | "plain" -- undecorated, single coloured background +> | "border" -- same as plain, but with a bold nested border +> | "body" -- main "background" style, as used in dialog backgrounds +> | "panel" -- alternative "background" style, beveled +> | "group" -- background for "nested" groups within body +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -94,9 +170,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Bitmap.md b/docs/API/renoise/renoise.Views.Bitmap.md index 4935d77c..6add573c 100644 --- a/docs/API/renoise/renoise.Views.Bitmap.md +++ b/docs/API/renoise/renoise.Views.Bitmap.md @@ -24,6 +24,11 @@ ### mode : [`BitmapMode`](#BitmapMode) > Setup how the bitmap should be drawn, recolored. Available modes are: +### color : [`BitmapColor`](#BitmapColor) +> When set, the bitmap will be drawn in the specified color and `mode` is set +> to `custom_color`. Set `mode` to something else than `custom_color` or the +> `color` to `{0, 0, 0}` to enable a `plain` display mode. + ### bitmap : [`BitmapPath`](#BitmapPath) > Supported bitmap file formats are *.bmp, *.png or *.tif (no transparency). @@ -47,22 +52,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -75,15 +91,124 @@ > Add mouse click notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) > Remove mouse click notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead --- ## Aliases +### BitmapColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the bitmap will be drawn in the specified color and `mode` is set +> -- to `custom_color`. Set `mode` to something else than `custom_color` or the +> -- `color` to `{0, 0, 0}` to enable a `plain` display mode. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> BitmapColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### BitmapImagePath [`string`](../../API/builtins/string.md) > You can load an image from your tool's directory, @@ -96,16 +221,19 @@ > If your custom path matches a built-in icon's (like "Icons/ArrowRight.bmp"), > your image will be loaded instead of the one from Renoise. > -> If you want to support high DPI UI scaling with your bitmaps like the built-in Icons, -> include high resolution versions with their filenames ending with "@4x" +> If you want to support high DPI UI scaling with your bitmaps like the +> built-in Icons, include high resolution versions with their filenames ending +> with "@4x" > The following rules will be used when loading bitmaps > * When UI scaling is 100%, only the base bitmaps are used. -> * When UI scaling is 125%, the base bitmaps are used, except if there is a `BitmapName@x1.25.bmp` variant. -> * For all other UI scaling > 125% the "@4x" variants are used and downscaled as needed, -> except when there is an exact match for the current UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) +> * When UI scaling is 125%, the base bitmaps are used, except if there is a +> ` BitmapName@x1.25.bmp` variant. +> * For all other UI scaling > 125% the "@4x" variants are used and +> downscaled as needed, except when there is an exact match for the current +> UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) ### BitmapMode -`"body_color"` | `"button_color"` | `"main_color"` | `"plain"` | `"transparent"` +`"body_color"` | `"button_color"` | `"custom_color"` | `"main_color"` | `"plain"` | `"transparent"` > ```lua > -- Setup how the bitmap should be drawn, recolored. Available modes are: > BitmapMode: @@ -114,6 +242,7 @@ > | "button_color" -- recolor the bitmap, using the theme's button color > | "body_color" -- same as 'button_back' but with body text/back color > | "main_color" -- same as 'button_back' but with main text/back colors +> | "custom_color" -- Recolor the bitmap using a custom color set by the `color' > ``` ### BitmapPath @@ -140,6 +269,146 @@ fun() +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -147,9 +416,28 @@ fun() > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Button.md b/docs/API/renoise/renoise.Views.Button.md index 51ca731a..3df5984c 100644 --- a/docs/API/renoise/renoise.Views.Button.md +++ b/docs/API/renoise/renoise.Views.Button.md @@ -25,12 +25,26 @@ > so plain white is the target theme color, and all other colors blend into the > button's background color of the theme. +### align : [`ButtonAlignment`](#ButtonAlignment) +> Setup the buttons text's or bitmap's alignment within the button. + +### font : [`TextFontStyle`](#TextFontStyle) +> The style that the text should be displayed with. + ### color : [`ButtonColor`](#ButtonColor) > When set, the unpressed button's background will be drawn in the specified color. -> A text color is automatically selected unless explicitly set, to make sure it's +> A text color is automatically selected unless explicitly set, to make sure its > always visible. > Set color {0,0,0} to enable the theme colors for the button again. +### secondary_color : [`ButtonSecondaryColor`](#ButtonSecondaryColor) +> When set, the unpressed button's background text or bitmap will be drawn in the +> specified color. +> Set color {0,0,0} to enable the theme colors for the button again. + +### style : [`ButtonStyle`](#ButtonStyle) +> Get/set the style a button should be displayed with. + ### active : [`ControlActive`](#ControlActive) > Instead of making a control invisible, you can also make it inactive. > Deactivated controls will still be shown, and will still show their @@ -51,22 +65,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -84,10 +109,19 @@ ### add_released_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) ### remove_pressed_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) ### remove_released_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -105,13 +139,26 @@ > If your custom path matches a built-in icon's (like "Icons/ArrowRight.bmp"), > your image will be loaded instead of the one from Renoise. > -> If you want to support high DPI UI scaling with your bitmaps like the built-in Icons, -> include high resolution versions with their filenames ending with "@4x" +> If you want to support high DPI UI scaling with your bitmaps like the +> built-in Icons, include high resolution versions with their filenames ending +> with "@4x" > The following rules will be used when loading bitmaps > * When UI scaling is 100%, only the base bitmaps are used. -> * When UI scaling is 125%, the base bitmaps are used, except if there is a `BitmapName@x1.25.bmp` variant. -> * For all other UI scaling > 125% the "@4x" variants are used and downscaled as needed, -> except when there is an exact match for the current UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) +> * When UI scaling is 125%, the base bitmaps are used, except if there is a +> ` BitmapName@x1.25.bmp` variant. +> * For all other UI scaling > 125% the "@4x" variants are used and +> downscaled as needed, except when there is an exact match for the current +> UI scaling factor (e.g. `BitmapName@1.5x.bmp` for 150%) + +### ButtonAlignment +`"center"` | `"left"` | `"right"` +> ```lua +> -- Setup the buttons text's or bitmap's alignment within the button. +> ButtonAlignment: +> | "left" -- aligned to the left +> | "right" -- aligned to the right +> | "center" -- center (default) +> ``` ### ButtonBitmapPath [`BitmapImagePath`](#BitmapImagePath) @@ -124,17 +171,224 @@ > button's background color of the theme. ### ButtonColor -[`RGBColor`](#RGBColor) -> When set, the unpressed button's background will be drawn in the specified color. -> A text color is automatically selected unless explicitly set, to make sure it's -> always visible. -> Set color {0,0,0} to enable the theme colors for the button again. +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the unpressed button's background will be drawn in the specified color. +> -- A text color is automatically selected unless explicitly set, to make sure its +> -- always visible. +> -- Set color {0,0,0} to enable the theme colors for the button again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> ButtonColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` ### ButtonLabel [`string`](../../API/builtins/string.md) > The text label of the button > * Default: "" +### ButtonSecondaryColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the unpressed button's background text or bitmap will be drawn in the +> -- specified color. +> -- Set color {0,0,0} to enable the theme colors for the button again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> ButtonSecondaryColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ButtonStyle +`"normal"` | `"rounded"` | `"rounded_bottom"` | `"rounded_left"` | `"rounded_right"` | `"rounded_top"` +> ```lua +> -- Get/set the style a button should be displayed with. +> ButtonStyle: +> | "normal" -- (Default) +> | "rounded" -- rounded corners on all sides +> | "rounded_left" -- rounded left side +> | "rounded_right" -- rounded right side +> | "rounded_top" -- rounded left side +> | "rounded_bottom" -- rounded right side +> ``` + ### ControlActive [`boolean`](../../API/builtins/boolean.md) > Instead of making a control invisible, you can also make it inactive. @@ -162,6 +416,152 @@ fun() > {0xFF, 0xFF, 0xFF} is white > {165, 73, 35} is the red from the Renoise logo +### TextFontStyle +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` +> ```lua +> -- The style that the text should be displayed with. +> TextFontStyle: +> | "normal" -- (Default) +> | "big" -- big text +> | "bold" -- bold font +> | "italic" -- italic font +> | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -169,9 +569,28 @@ fun() > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Canvas.Context.md b/docs/API/renoise/renoise.Views.Canvas.Context.md new file mode 100644 index 00000000..9c06e0ef --- /dev/null +++ b/docs/API/renoise/renoise.Views.Canvas.Context.md @@ -0,0 +1,698 @@ +# renoise.Views.Canvas.Context +> Drawing context for a canvas view.
+> +> The context is *similar* to the HTML5 canvas 2d drawing context, with the +> following differences and limitations: +> +> * no text drawing: layer a renoise.Views.Text on top of this view instead. +> * no image and pattern drawing: layer a renoise.Views.Bitmap on top of this +> view, if you need to draw bitmaps in the canvas. +> * no shadow rendering: that would be awful slow +> * colors can be specified as strings or rgba tables in range [0-255]. when +> specifying strings, only renoise theme colors are supported (e.g. "button_back"). +> * to create gradients use the available `start_XXX` gradient functions +> instead of creating gradient objects. +> * to set a new fill or stroke color, use the `fill_color` and `stroke_color` +> properties instead of `fill/strokeStyle` +> +> This canvas implementation is based on 'canvas_ity' by Andrew Kensler +> https://github.com/a-e-k/canvas_ity +> +> [HTML5 Canvas Documentation](https://www.w3schools.com/tags/ref_canvas.asp) + + + + +--- +## Properties +### pixel_size : { height : [`integer`](../../API/builtins/integer.md), width : [`integer`](../../API/builtins/integer.md) } +> **READ_ONLY** Size of the render context backend **in raw pixel resolution**. +> This is the view ports size, multiplied with the global UI scaling factor. +> It does not change with transformations. + +### size : { height : [`integer`](../../API/builtins/integer.md), width : [`integer`](../../API/builtins/integer.md) } +> **READ_ONLY** Size of the render context **with transformations applied**. +> This initially will be the view's size. Calls to `transform` or `scale` +> may change the size further. + +### global_alpha : [`number`](../../API/builtins/number.md) +> The degree of opacity applied to all drawing operations.
+> +> If an operation already uses a transparent color, this can make it +> yet more transparent. It must be in the range from 0 for fully transparent +> to 255 for fully opaque. Defaults to 255 (opaque). + +### global_composite_operation : `"source_atop"` | `"source_copy"` | `"source_in"` | `"source_out"` | `"source_over"` | `"destination_atop"` | `"destination_in"` | `"destination_out"` | `"destination_over"` | `"exclusive_or"` | `"lighter"` +> Compositing operation for blending new drawing and old pixels.
+> +> The source_copy, source_in, source_out, destination_atop, and +> destination_in operations may clear parts of the canvas outside the +> new drawing but within the clip region. Defaults to "source_over". + +### fill_color : [`RGBColor`](#RGBColor) | [`RGBAColor`](#RGBAColor) | [`ThemeColor`](#ThemeColor) +> Set filling to use a constant color and opacity.
+> +> Defaults a constant color with 0,0,0,255 (opaque black). + +### stroke_color : [`RGBColor`](#RGBColor) | [`RGBAColor`](#RGBAColor) | [`ThemeColor`](#ThemeColor) +> Set stroking to use a constant color and opacity.
+> +> Defaults a constant color with 0,0,0,255 (opaque black). + +### line_cap : `"butt"` | `"square"` | `"circle"` +> Cap style for the ends of open subpaths and dash segments.
+> +> The actual shape may be affected by the current transform at the time +> of drawing. Only affects stroking. Defaults to "butt". + +### line_join : `"miter"` | `"bevel"` | `"rounded"` +> Join style for connecting lines within the paths.
+> +> The actual shape may be affected by the current transform at the time +> of drawing. Only affects stroking. Defaults to "miter". + +### line_width : [`number`](../../API/builtins/number.md) +> The width of the lines when stroking.
+> +> Initially this is measured in pixels, though the current transform +> at the time of drawing can affect this. Must be positive. Defaults to 1.0. + +### miter_limit : [`number`](../../API/builtins/number.md) +> Limit on maximum pointiness allowed for miter joins.
+> +> If the distance from the point where the lines intersect to the +> point where the outside edges of the join intersect exceeds this +> ratio relative to the line width, then a bevel join will be used +> instead, and the miter will be lopped off. Larger values allow +> pointier miters. Only affects stroking and only when the line join +> style is miter. Defaults to 10.0. + +### line_dash_offset : [`number`](../../API/builtins/number.md) +> Offset where each subpath starts the dash pattern.
+> +> Changing this shifts the location of the dashes along the path and +> animating it will produce a marching ants effect. Only affects +> stroking and only when a dash pattern is set. May be negative or +> exceed the length of the dash pattern, in which case it will wrap. +> Defaults to 0.0. + + + +--- +## Functions +### clip([*self*](../../API/builtins/self.md)) +> Restrict the clip region by the current path.
+> +> Intersects the current clip region with the interior of the current +> path (the region that would be filled), and replaces the current +> clip region with this intersection. Subsequent calls to clip can +> only reduce this further. When filling or stroking, only pixels +> within the current clip region will change. The current path is +> left unchanged by updating the clip region; begin a new path to +> clear it. Defaults to the entire canvas. +> +> Tip: to be able to reset the current clip region, save the canvas +> state first before clipping then restore the state to reset it. +### save([*self*](../../API/builtins/self.md)) +> Save the current state as though to a stack.
+> +> The full state of the canvas is saved, except for the pixels in the +> canvas buffer, and the current path. +> +> Tip: to be able to reset the current clip region, save the canvas +> state first before clipping then restore the state to reset it. +### restore([*self*](../../API/builtins/self.md)) +> Restore a previously saved state as though from a stack.
+> +> This does not affect the pixels in the canvas buffer or the current +> path. If the stack of canvas states is empty, this does nothing. +### fill_rect([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md), width : [`number`](../../API/builtins/number.md), height : [`number`](../../API/builtins/number.md)) +> Fill a rectangular area.
+> +> This behaves as though the current path were reset to a single +> rectangle and then filled as usual. However, the current path is +> not actually changed. The current transform at the time that this is +> called will affect the given point and rectangle. The width and/or +> the height may be negative but not zero. If either is zero, or the +> current transform is not invertible, this does nothing. +### stroke_rect([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md), width : [`number`](../../API/builtins/number.md), height : [`number`](../../API/builtins/number.md)) +> Stroke a rectangular area.
+> +> This behaves as though the current path were reset to a single +> rectangle and then stroked as usual. However, the current path is +> not actually changed. The current transform at the time that this +> is called will affect the given point and rectangle. The width +> and/or the height may be negative or zero. If both are zero, or +> the current transform is not invertible, this does nothing. If only +> one is zero, this behaves as though it strokes a single horizontal or +> vertical line. +### clear_rect([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md), width : [`number`](../../API/builtins/number.md), height : [`number`](../../API/builtins/number.md)) +> Clear a rectangular area back to transparent black.
+> +> The clip region may limit the area cleared. The current path is not +> affected by this clearing. The current transform at the time that +> this is called will affect the given point and rectangle. The width +> and/or the height may be negative or zero. If either is zero, or the +> current transform is not invertible, this does nothing. +### begin_path([*self*](../../API/builtins/self.md)) +> Reset the current path.
+> +> The current path and all subpaths will be cleared after this, and a +> new path can be built. +### close_path([*self*](../../API/builtins/self.md)) +> Close the current subpath.
+> +> Adds a straight line from the end of the current subpath back to its +> first point and marks the subpath as closed so that this line will +> join with the beginning of the path at this point. A new, empty +> subpath will be started beginning with the same first point. If the +> current path is empty, this does nothing. +### move_to([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md)) +> Create a new subpath.
+> +> The given point will become the first point of the new subpath and +> is subject to the current transform at the time this is called. +### line_to([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md)) +> Extend the current subpath with a straight line.
+> +> The line will go from the current end point (if the current path is +> not empty) to the given point, which will become the new end point. +> Its position is affected by the current transform at the time that +> this is called. If the current path was empty, this is equivalent +> to just a move. +### fill([*self*](../../API/builtins/self.md)) +> Draw the interior of the current path using the fill style.
+> +> Interior pixels are determined by the non-zero winding rule, with +> all open subpaths implicitly closed by a straight line beforehand. +> If shadows have been enabled by setting the shadow color with any +> opacity and either offsetting or blurring the shadows, then the +> shadows of the filled areas will be drawn first, followed by the +> filled areas themselves. Both will be blended into the canvas +> according to the global alpha, the global compositing operation, +> and the clip region. If the fill style is a gradient or a pattern, +> it will be affected by the current transform. The current path is +> left unchanged by filling; begin a new path to clear it. If the +> current transform is not invertible, this does nothing. +### stroke([*self*](../../API/builtins/self.md)) +> Draw the edges of the current path using the stroke style.
+> +> Edges of the path will be expanded into strokes according to the +> current dash pattern, dash offset, line width, line join style +> (and possibly miter limit), line cap, and transform. If shadows +> have been enabled by setting the shadow color with any opacity and +> either offsetting or blurring the shadows, then the shadow will be +> drawn for the stroked lines first, then the stroked lines themselves. +> Both will be blended into the canvas according to the global alpha, +> the global compositing operation, and the clip region. If the stroke +> style is a gradient or a pattern, it will be affected by the current +> transform. The current path is left unchanged by stroking; begin a +> new path to clear it. If the current transform is not invertible, +> this does nothing. +> +> Tip: to draw with a calligraphy-like angled brush effect, add a +> non-uniform scale transform just before stroking. +### set_line_dash([*self*](../../API/builtins/self.md), segments : [`number`](../../API/builtins/number.md)[]) +> Set or clear the line dash pattern.
+> +> Takes an array with entries alternately giving the lengths of dash +> and gap segments. All must be non-negative; if any are not, this +> does nothing. These will be used to draw with dashed lines when +> stroking, with each subpath starting at the length along the dash +> pattern indicated by the line dash offset. Initially these lengths +> are measured in pixels, though the current transform at the time of +> drawing can affect this. The count must be non-negative. If it is +> odd, the array will be appended to itself to make an even count. If +> it is zero, or the pointer is null, the dash pattern will be cleared +> and strokes will be drawn as solid lines. The array is copied and +> it is safe to change or destroy it after this call. Defaults to +> solid lines. +### set_fill_linear_gradient([*self*](../../API/builtins/self.md), start_x : [`number`](../../API/builtins/number.md), start_y : [`number`](../../API/builtins/number.md), end_x : [`number`](../../API/builtins/number.md), end_y : [`number`](../../API/builtins/number.md)) +> Set filling to use a linear gradient.
+> +> Positions the start and end points of the gradient and clears all +> color stops to reset the gradient to transparent black. Color stops +> can then be added again. When drawing, pixels will be painted with +> the color of the gradient at the nearest point on the line segment +> between the start and end points. This is affected by the current +> transform at the time of drawing. +### set_stroke_linear_gradient([*self*](../../API/builtins/self.md), start_x : [`number`](../../API/builtins/number.md), start_y : [`number`](../../API/builtins/number.md), end_x : [`number`](../../API/builtins/number.md), end_y : [`number`](../../API/builtins/number.md)) +> Set filling to use a linear gradient.
+> See: `renoise.Views.Canvas.Context` set_fill_linear_gradient +### set_fill_radial_gradient([*self*](../../API/builtins/self.md), start_x : [`number`](../../API/builtins/number.md), start_y : [`number`](../../API/builtins/number.md), start_radius : [`number`](../../API/builtins/number.md), end_x : [`number`](../../API/builtins/number.md), end_y : [`number`](../../API/builtins/number.md), end_radius : [`number`](../../API/builtins/number.md)) +> Set filling to use a radial gradient.
+> +> Positions the start and end circles of the gradient and clears all +> color stops to reset the gradient to transparent black. Color stops +> can then be added again. When drawing, pixels will be painted as +> though the starting circle moved and changed size linearly to match +> the ending circle, while sweeping through the colors of the gradient. +> Pixels not touched by the moving circle will be left transparent +> black. The radial gradient is affected by the current transform +> at the time of drawing. The radii must be non-negative. +### set_stroke_radial_gradient([*self*](../../API/builtins/self.md), start_x : [`number`](../../API/builtins/number.md), start_y : [`number`](../../API/builtins/number.md), start_radius : [`number`](../../API/builtins/number.md), end_x : [`number`](../../API/builtins/number.md), end_y : [`number`](../../API/builtins/number.md), end_radius : [`number`](../../API/builtins/number.md)) +> Set stroke to use a radial gradient.
+> See: `renoise.Views.Canvas.Context` set_fill_radial_gradient +### add_fill_color_stop([*self*](../../API/builtins/self.md), offset : [`number`](../../API/builtins/number.md), color : [`RGBAColor`](#RGBAColor) | [`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor)) +> Add a color stop to a linear or radial gradient fill.
+> +> Each color stop has an offset which defines its position from 0.0 at +> the start of the gradient to 1.0 at the end. Colors and opacity are +> linearly interpolated along the gradient between adjacent pairs of +> stops without premultiplying the alpha. If more than one stop is +> added for a given offset, the first one added is considered closest +> to 0.0 and the last is closest to 1.0. If no stop is at offset 0.0 +> or 1.0, the stops with the closest offsets will be extended. If no +> stops are added, the gradient will be fully transparent black. Set a +> new linear or radial gradient to clear all the stops and redefine the +> gradient colors. Color stops may be added to a gradient at any time. +> The color and opacity values will be clamped to the 0.0 to 1.0 range, +> inclusive. The offset must be in the 0.0 to 1.0 range, inclusive. +> If it is not, or if chosen style type is not currently set to a +> gradient, this does nothing. +> +> ```lua +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- A table of 4 bytes (ranging from 0 to 255) +> -- representing the red, green, blue, alpha channels of a color. +> -- {0xFF, 0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35, 0x80} is the red from the Renoise logo, half opaque. +> -- The application theme's colors +> color: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` +### add_stroke_color_stop([*self*](../../API/builtins/self.md), offset : [`number`](../../API/builtins/number.md), color : [`RGBAColor`](#RGBAColor) | [`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor)) +> Add a color stop to a linear or radial gradient stroke.
+> +> +> ```lua +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- A table of 4 bytes (ranging from 0 to 255) +> -- representing the red, green, blue, alpha channels of a color. +> -- {0xFF, 0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35, 0x80} is the red from the Renoise logo, half opaque. +> -- The application theme's colors +> color: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` +> See: `renoise.Views.Canvas.Context` add_fill_color_stop +### rect([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md), width : [`number`](../../API/builtins/number.md), height : [`number`](../../API/builtins/number.md)) +> Add a closed subpath in the shape of a rectangle.
+> +> The rectangle has one corner at the given point and then goes in the +> direction along the width before going in the direction of the height +> towards the opposite corner. The current transform at the time that +> this is called will affect the given point and rectangle. The width +> and/or the height may be negative or zero, and this can affect the +> winding direction. +### bezier_curve_to([*self*](../../API/builtins/self.md), control_1_x : [`number`](../../API/builtins/number.md), control_1_y : [`number`](../../API/builtins/number.md), control_2_x : [`number`](../../API/builtins/number.md), control_2_y : [`number`](../../API/builtins/number.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md)) +> Extend the current subpath with a cubic Bezier curve.
+> +> The curve will go from the current end point (or the first control +> point if the current path is empty) to the given point, which will +> become the new end point. The curve will be tangent toward the first +> control point at the beginning and tangent toward the second control +> point at the end. The current transform at the time that this is +> called will affect all points passed in. +> +> Tip: to make multiple curves join smoothly, ensure that each new end +> point is on a line between the adjacent control points. +### arc([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md), radius : [`number`](../../API/builtins/number.md), start_angle : [`number`](../../API/builtins/number.md), end_angle : [`number`](../../API/builtins/number.md), counter_clockwise : [`boolean`](../../API/builtins/boolean.md)[`?`](../../API/builtins/nil.md)) +> Extend the current subpath with an arc between two angles.
+> +> The arc is from the circle centered at the given point and with the +> given radius. A straight line will be added from the current end +> point to the starting point of the arc (unless the current path is +> empty), then the arc along the circle from the starting angle to the +> ending angle in the given direction will be added. If they are more +> than two pi radians apart in the given direction, the arc will stop +> after one full circle. The point at the ending angle will become +> the new end point of the path. Initially, the angles are clockwise +> relative to the x-axis. The current transform at the time that +> this is called will affect the passed in point, angles, and arc. +> The radius must be non-negative. +### arc_to([*self*](../../API/builtins/self.md), vertex_x : [`number`](../../API/builtins/number.md), vertex_y : [`number`](../../API/builtins/number.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md), radius : [`number`](../../API/builtins/number.md)) +> Extend the current subpath with an arc tangent to two lines.
+> +> The arc is from the circle with the given radius tangent to both +> the line from the current end point to the vertex, and to the line +> from the vertex to the given point. A straight line will be added +> from the current end point to the first tangent point (unless the +> current path is empty), then the shortest arc from the first to the +> second tangent points will be added. The second tangent point will +> become the new end point. If the radius is large, these tangent +> points may fall outside the line segments. The current transform +> at the time that this is called will affect the passed in points +> and the arc. If the current path was empty, this is equivalent to +> a move. If the arc would be degenerate, it is equivalent to a line +> to the vertex point. The radius must be non-negative. If it is not, +> or if the current transform is not invertible, this does nothing. +> +> Tip: to draw a polygon with rounded corners, call this once for each +> vertex and pass the midpoint of the adjacent edge as the second +> point; this works especially well for rounded boxes. +### quadratic_curve_to([*self*](../../API/builtins/self.md), control_x : [`number`](../../API/builtins/number.md), control_y : [`number`](../../API/builtins/number.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md)) +> Extend the current subpath with a quadratic Bezier curve.
+> +> The curve will go from the current end point (or the control point +> if the current path is empty) to the given point, which will become +> the new end point. The curve will be tangent toward the control +> point at both ends. The current transform at the time that this +> is called will affect both points passed in. +> +> Tip: to make multiple curves join smoothly, ensure that each new end +> point is on a line between the adjacent control points. +### scale([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md)) +> Scale the current transform.
+> +> Scaling may be non-uniform if the x and y scaling factors are +> different. When a scale factor is less than one, things will be +> shrunk in that direction. When a scale factor is greater than +> one, they will grow bigger. Negative scaling factors will flip or +> mirror it in that direction. The scaling factors must be non-zero. +> If either is zero, most drawing operations will do nothing. +### rotate([*self*](../../API/builtins/self.md), angle : [`number`](../../API/builtins/number.md)) +> Rotate the current transform.
+> +> The rotation is applied clockwise in a direction around the origin. +> +> Tip: to rotate around another point, first translate that point to +> the origin, then do the rotation, and then translate back. +### translate([*self*](../../API/builtins/self.md), x : [`number`](../../API/builtins/number.md), y : [`number`](../../API/builtins/number.md)) +> Translate the current transform.
+> +> By default, positive x values shift that many pixels to the right, +> while negative y values shift left, positive y values shift up, and +> negative y values shift down. +### transform([*self*](../../API/builtins/self.md), a : [`number`](../../API/builtins/number.md), b : [`number`](../../API/builtins/number.md), c : [`number`](../../API/builtins/number.md), d : [`number`](../../API/builtins/number.md), e : [`number`](../../API/builtins/number.md), f : [`number`](../../API/builtins/number.md)) +> Add an arbitrary transform to the current transform.
+> +> This takes six values for the upper two rows of a homogenous 3x3 +> matrix (i.e., {{a, c, e}, {b, d, f}, {0.0, 0.0, 1.0}}) describing an +> arbitrary affine transform and appends it to the current transform. +> The values can represent any affine transform such as scaling, +> rotation, translation, or skew, or any composition of affine +> transforms. The matrix must be invertible. If it is not, most +> drawing operations will do nothing. +### set_transform([*self*](../../API/builtins/self.md), a : [`number`](../../API/builtins/number.md), b : [`number`](../../API/builtins/number.md), c : [`number`](../../API/builtins/number.md), d : [`number`](../../API/builtins/number.md), e : [`number`](../../API/builtins/number.md), f : [`number`](../../API/builtins/number.md)) +> Replace the current transform.
+> +> This takes six values for the upper two rows of a homogenous 3x3 +> matrix (i.e., {{a, c, e}, {b, d, f}, {0.0, 0.0, 1.0}}) describing +> an arbitrary affine transform and replaces the current transform +> with it. The values can represent any affine transform such as +> scaling, rotation, translation, or skew, or any composition of +> affine transforms. The matrix must be invertible. If it is not, +> most drawing operations will do nothing. +> +> Tip: to reset the current transform back to the default, use +> 1.0, 0.0, 0.0, 1.0, 0.0, 0.0. + + + +--- +## Aliases +### RGBAColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md), 4 : [`integer`](../../API/builtins/integer.md) } +> A table of 4 bytes (ranging from 0 to 255) +> representing the red, green, blue, alpha channels of a color. +> {0xFF, 0xFF, 0xFF, 0xFF} is white +> {165, 73, 35, 0x80} is the red from the Renoise logo, half opaque. + +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + + diff --git a/docs/API/renoise/renoise.Views.Canvas.md b/docs/API/renoise/renoise.Views.Canvas.md new file mode 100644 index 00000000..f17fe957 --- /dev/null +++ b/docs/API/renoise/renoise.Views.Canvas.md @@ -0,0 +1,187 @@ +# renoise.Views.Canvas +> A canvas view lets you draw and handle mouse events in a completely +> customisable way. +> +> Note: The content is cached in a texture and not hardware accelerated, so +> it's not suitable for animations, but for static content such as custom +> backgrounds or bitmap-like views. +> ```text +> .--. +> .'_\/_'. +> '. /\ .' +> "||" +> || /\ +> /\ ||//\) +> (/\\||/ +> ______\||/_______ +> ``` + + + + +--- +## Properties +### mode : [`CanvasMode`](#CanvasMode) +> How to draw the canvas context to screen: "transparent" draws with alpha from +> the canvas, "plain" ignores alpha values, which usually is a lot faster to draw. +> Use "plain" to speed up drawing background alike canvas views which cover the +> entire view area. Default: "transparent" + +### visible : [`ViewVisibility`](#ViewVisibility) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + +### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> **READ-ONLY** Empty for all controls, for layout views this contains the +> layout child views in the order they got added + + + +--- +## Functions +### update([*self*](../../API/builtins/self.md)) +> Request background drawing contents of the canvas to be updated in the next +> UI draw cycle.
+> +> Size changes of the canvas view, global UI scaling changes, and color theme +> changes will automatically update the canvas, so this is only necessary to +> call when your draw content needs to be updated due to some internal state +> changes. +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead +### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead + + + +--- +## Aliases +### CanvasMode +`"plain"` | `"transparent"` +> ```lua +> -- How to draw the canvas context to screen: "transparent" draws with alpha from +> -- the canvas, "plain" ignores alpha values, which usually is a lot faster to draw. +> -- Use "plain" to speed up drawing background alike canvas views which cover the +> -- entire view area. Default: "transparent" +> CanvasMode: +> | "plain" +> | "transparent" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size +> for example `vb:text { width = "80%"}`. The percentage values are +> relative to the view's parent size and will automatically update on size changes. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + diff --git a/docs/API/renoise/renoise.Views.CheckBox.md b/docs/API/renoise/renoise.Views.CheckBox.md index abac0a82..11c622b4 100644 --- a/docs/API/renoise/renoise.Views.CheckBox.md +++ b/docs/API/renoise/renoise.Views.CheckBox.md @@ -36,22 +36,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -64,10 +75,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`BooleanValueNotifierFunction`](#BooleanValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -98,6 +118,46 @@ > Target strings are not verified. When they point to nothing, the mapped MIDI > message will do nothing and no error is fired. +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -105,9 +165,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Chooser.md b/docs/API/renoise/renoise.Views.Chooser.md index aaa97a8a..8038e754 100644 --- a/docs/API/renoise/renoise.Views.Chooser.md +++ b/docs/API/renoise/renoise.Views.Chooser.md @@ -38,22 +38,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -66,10 +77,19 @@ > Add index change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`IntegerValueNotifierFunction`](#IntegerValueNotifierFunction)) > Remove index change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -103,6 +123,46 @@ [`integer`](../../API/builtins/integer.md) > The currently selected item's index +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -110,9 +170,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Control.md b/docs/API/renoise/renoise.Views.Control.md index a87f7f27..1360338f 100644 --- a/docs/API/renoise/renoise.Views.Control.md +++ b/docs/API/renoise/renoise.Views.Control.md @@ -27,22 +27,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -51,10 +62,19 @@ --- ## Functions -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -76,6 +96,46 @@ > Target strings are not verified. When they point to nothing, the mapped MIDI > message will do nothing and no error is fired. +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -83,9 +143,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.MiniSlider.md b/docs/API/renoise/renoise.Views.MiniSlider.md index 2fb67aac..df00e797 100644 --- a/docs/API/renoise/renoise.Views.MiniSlider.md +++ b/docs/API/renoise/renoise.Views.MiniSlider.md @@ -25,6 +25,13 @@ > Target strings are not verified. When they point to nothing, the mapped MIDI > message will do nothing and no error is fired. +### polarity : [`SliderPolarity`](#SliderPolarity) +> Value polarity of the control. Bipolar controls show the value from the +> center to left and right or up and down and typically controls a range +> around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> right or bottom to top. +> * Default: "unipolar" + ### min : [`SliderMinValue`](#SliderMinValue) > The minimum value that can be set using the view > * Default: 0 @@ -45,22 +52,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -73,10 +91,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NumberValueNotifierFunction`](#NumberValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -120,6 +147,59 @@ [`number`](../../API/builtins/number.md) > The current value of the view +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -127,9 +207,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.MultiLineText.md b/docs/API/renoise/renoise.Views.MultiLineText.md index 574a0e3e..3ff911bb 100644 --- a/docs/API/renoise/renoise.Views.MultiLineText.md +++ b/docs/API/renoise/renoise.Views.MultiLineText.md @@ -23,6 +23,10 @@ > Newlines (Windows, Mac or Unix styled) in the text can be used to create > paragraphs. +### selected_text : [`TextMultilineSelectedString`](#TextMultilineSelectedString) +> **READ-ONLY** The currently selected text, if any. +> Newlines (Windows, Mac or Unix styled) will use the unix newline format. + ### paragraphs : [`TextParagraphs`](#TextParagraphs) > A table of text lines to be used instead of specifying a single text > line with newline characters like "text" @@ -40,22 +44,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -73,10 +88,19 @@ > paragraphs, just like in the "text" property. ### clear([*self*](../../API/builtins/self.md)) > Clear the whole text, same as multiline_text.text="". -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -93,7 +117,7 @@ > ``` ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -102,8 +126,14 @@ > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font > ``` +### TextMultilineSelectedString +[`string`](../../API/builtins/string.md) +> **READ-ONLY** The currently selected text, if any. +> Newlines (Windows, Mac or Unix styled) will use the unix newline format. + ### TextMultilineString [`string`](../../API/builtins/string.md) > The text that should be displayed. @@ -116,6 +146,46 @@ > line with newline characters like "text" > * Default: [] +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -123,9 +193,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.MultiLineTextField.md b/docs/API/renoise/renoise.Views.MultiLineTextField.md index cc19d78f..d28d754c 100644 --- a/docs/API/renoise/renoise.Views.MultiLineTextField.md +++ b/docs/API/renoise/renoise.Views.MultiLineTextField.md @@ -28,6 +28,10 @@ > Exactly the same as "value"; provided for consistency. > * Default: "" +### selected_text : [`TextMultilineSelectedString`](#TextMultilineSelectedString) +> **READ-ONLY** The currently selected text, if any. +> Newlines (Windows, Mac or Unix styled) will use the unix newline format. + ### paragraphs : [`TextParagraphs`](#TextParagraphs) > A table of text lines to be used instead of specifying a single text > line with newline characters like "text" @@ -50,22 +54,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -87,10 +102,19 @@ > create new paragraphs, otherwise a single paragraph is appended. ### clear([*self*](../../API/builtins/self.md)) > Clear the whole text. -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -122,7 +146,7 @@ > * Default: false ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -131,8 +155,14 @@ > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font > ``` +### TextMultilineSelectedString +[`string`](../../API/builtins/string.md) +> **READ-ONLY** The currently selected text, if any. +> Newlines (Windows, Mac or Unix styled) will use the unix newline format. + ### TextMultilineString [`string`](../../API/builtins/string.md) > The text that should be displayed. @@ -150,6 +180,46 @@ > Exactly the same as "value"; provided for consistency. > * Default: "" +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -157,9 +227,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Popup.md b/docs/API/renoise/renoise.Views.Popup.md index 995cfffc..cdfbab21 100644 --- a/docs/API/renoise/renoise.Views.Popup.md +++ b/docs/API/renoise/renoise.Views.Popup.md @@ -39,22 +39,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -67,10 +78,19 @@ > Add index change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`IntegerValueNotifierFunction`](#IntegerValueNotifierFunction)) > Remove index change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -105,6 +125,46 @@ [`integer`](../../API/builtins/integer.md) > The currently selected item's index +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -112,9 +172,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Rack.md b/docs/API/renoise/renoise.Views.Rack.md index fe8d55c6..d03a99d9 100644 --- a/docs/API/renoise/renoise.Views.Rack.md +++ b/docs/API/renoise/renoise.Views.Rack.md @@ -17,7 +17,7 @@ > rows, vertically in columns). > * Default: 0 (no spacing) -### style : [`ViewBackgroundStyle`](#ViewBackgroundStyle) +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle) > Setup a background style for the view. ### uniform : [`RackUniformity`](#RackUniformity) @@ -28,28 +28,42 @@ > as a child view size changes or new children are added. > * Default: false +### style : [`ViewBackgroundStyle`](#ViewBackgroundStyle) +> **Deprecated** Use `background` instead. + ### visible : [`ViewVisibility`](#ViewVisibility) > Set visible to false to hide a view (make it invisible without removing > it). Please note that view.visible will also return false when any of its > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -58,10 +72,19 @@ --- ## Functions -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -100,6 +123,46 @@ > | "group" -- background for "nested" groups within body > ``` +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -107,9 +170,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.RotaryEncoder.md b/docs/API/renoise/renoise.Views.RotaryEncoder.md index 19bea169..d4588c02 100644 --- a/docs/API/renoise/renoise.Views.RotaryEncoder.md +++ b/docs/API/renoise/renoise.Views.RotaryEncoder.md @@ -30,6 +30,13 @@ > Target strings are not verified. When they point to nothing, the mapped MIDI > message will do nothing and no error is fired. +### polarity : [`SliderPolarity`](#SliderPolarity) +> Value polarity of the control. Bipolar controls show the value from the +> center to left and right or up and down and typically controls a range +> around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> right or bottom to top. +> * Default: "unipolar" + ### min : [`SliderMinValue`](#SliderMinValue) > The minimum value that can be set using the view > * Default: 0 @@ -50,22 +57,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -78,10 +96,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NumberValueNotifierFunction`](#NumberValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -125,6 +152,59 @@ [`number`](../../API/builtins/number.md) > The current value of the view +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -132,9 +212,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.ScrollBar.md b/docs/API/renoise/renoise.Views.ScrollBar.md new file mode 100644 index 00000000..fca2dfe9 --- /dev/null +++ b/docs/API/renoise/renoise.Views.ScrollBar.md @@ -0,0 +1,261 @@ +# renoise.Views.ScrollBar +> A special slider alike control to scroll through some content. +> +> `min` and `max` define to the scrollable area's range. `pagesize` is the +> currently visible area within that range and `value` is the offset from +> `min` to `max - pagestep` within the whole scrollable area: +> +> ```text +> min value max +> | [xxxxxxxxxxxxxx] | +> <---pagestep---> +> <---------scroll-area------------> +> ``` +> +> Note that the *minimum offset value* is `min` and the *maximum offset +> value* is `max - pagestep`. +> +> A scrollbar can be horizontal or vertical. It will flip its orientation +> according to the set width and height. By default it's horizontal. + + + + +--- +## Properties +### active : [`ControlActive`](#ControlActive) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### midi_mapping : [`ControlMidiMappingString`](#ControlMidiMappingString) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### min : [`ScrollbarMin`](#ScrollbarMin) +> Default 0. Minimum offset value. + +### max : [`ScrollbarMax`](#ScrollbarMax) +> Default 100. Maximum offset value. + +### value : [`ScrollbarValue`](#ScrollbarValue) +> Default 0. Offset value in range `min to max - pagestep`. + +### step : [`ScrollbarStep`](#ScrollbarStep) +> Default 1. Amount the mouse-wheel or additional +/- buttons in the scroll bar +> move the scrollable area. + +### pagestep : [`ScrollbarPagestep`](#ScrollbarPagestep) +> Default 100. Size of the currently visible area. + +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle) +> Setup a background style for the view. + +### autohide : [`ScrollbarAutoHide`](#ScrollbarAutoHide) +> Default: false. When true, view gets automatically hidden when no scrolling is needed + +### visible : [`ViewVisibility`](#ViewVisibility) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + +### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> **READ-ONLY** Empty for all controls, for layout views this contains the +> layout child views in the order they got added + + + +--- +## Functions +### add_notifier([*self*](../../API/builtins/self.md), notifier : [`IntegerValueNotifierFunction`](#IntegerValueNotifierFunction)) +> Add offset value change notifier +### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`IntegerValueNotifierFunction`](#IntegerValueNotifierFunction)) +> Remove offset value change notifier +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead +### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead + + + +--- +## Aliases +### ControlActive +[`boolean`](../../API/builtins/boolean.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### ControlMidiMappingString +[`string`](../../API/builtins/string.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### IntegerValueNotifierFunction +(value : [`integer`](../../API/builtins/integer.md)) + + +### ScrollbarAutoHide +[`boolean`](../../API/builtins/boolean.md) +> Default: false. When true, view gets automatically hidden when no scrolling is needed + +### ScrollbarMax +[`integer`](../../API/builtins/integer.md) +> Default 100. Maximum offset value. + +### ScrollbarMin +[`integer`](../../API/builtins/integer.md) +> Default 0. Minimum offset value. + +### ScrollbarPagestep +[`integer`](../../API/builtins/integer.md) +> Default 100. Size of the currently visible area. + +### ScrollbarStep +[`integer`](../../API/builtins/integer.md) +> Default 1. Amount the mouse-wheel or additional +/- buttons in the scroll bar +> move the scrollable area. + +### ScrollbarValue +[`integer`](../../API/builtins/integer.md) +> Default 0. Offset value in range `min to max - pagestep`. + +### ViewBackgroundStyle +`"body"` | `"border"` | `"group"` | `"invisible"` | `"panel"` | `"plain"` +> ```lua +> -- Setup a background style for the view. +> ViewBackgroundStyle: +> | "invisible" -- no background (Default) +> | "plain" -- undecorated, single coloured background +> | "border" -- same as plain, but with a bold nested border +> | "body" -- main "background" style, as used in dialog backgrounds +> | "panel" -- alternative "background" style, beveled +> | "group" -- background for "nested" groups within body +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size +> for example `vb:text { width = "80%"}`. The percentage values are +> relative to the view's parent size and will automatically update on size changes. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + diff --git a/docs/API/renoise/renoise.Views.Slider.md b/docs/API/renoise/renoise.Views.Slider.md index c382b9b8..ee4cc074 100644 --- a/docs/API/renoise/renoise.Views.Slider.md +++ b/docs/API/renoise/renoise.Views.Slider.md @@ -27,6 +27,13 @@ > Target strings are not verified. When they point to nothing, the mapped MIDI > message will do nothing and no error is fired. +### polarity : [`SliderPolarity`](#SliderPolarity) +> Value polarity of the control. Bipolar controls show the value from the +> center to left and right or up and down and typically controls a range +> around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> right or bottom to top. +> * Default: "unipolar" + ### min : [`SliderMinValue`](#SliderMinValue) > The minimum value that can be set using the view > * Default: 0 @@ -53,22 +60,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -81,10 +99,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NumberValueNotifierFunction`](#NumberValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -128,6 +155,19 @@ [`number`](../../API/builtins/number.md) > The current value of the view +### SliderPolarity +`"bipolar"` | `"unipolar"` +> ```lua +> -- Value polarity of the control. Bipolar controls show the value from the +> -- center to left and right or up and down and typically controls a range +> -- around zero, e.g. -1 to 1. Unipolar controls show the value from left to +> -- right or bottom to top. +> -- * Default: "unipolar" +> SliderPolarity: +> | "unipolar" +> | "bipolar" +> ``` + ### SliderStepAmounts { 1 : [`number`](../../API/builtins/number.md), 2 : [`number`](../../API/builtins/number.md) } > A table containing two numbers representing the step amounts for incrementing @@ -135,6 +175,46 @@ > The first value is the small step (applied on left clicks) > second value is the big step (applied on right clicks) +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -142,9 +222,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Stack.md b/docs/API/renoise/renoise.Views.Stack.md new file mode 100644 index 00000000..27044813 --- /dev/null +++ b/docs/API/renoise/renoise.Views.Stack.md @@ -0,0 +1,179 @@ +# renoise.Views.Stack +> A Stack has no content on its own. It only *stacks* it's child views. +> The position of the child views in the stack can be freely set by using +> the `origin` property of the views. + + + + +--- +## Properties +### autosize : [`StackAutoSize`](#StackAutoSize) +> When set to true, the width and height of the stack will be automatically +> calculated and updated from the stack's child views, to ensure all views fit +> into the stack. +> When disabled, the width and height must be set manually. +> * Default: true + +### background : [`ViewBackgroundStyle`](#ViewBackgroundStyle) +> Setup a background style for the view. + +### visible : [`ViewVisibility`](#ViewVisibility) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + +### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> **READ-ONLY** Empty for all controls, for layout views this contains the +> layout child views in the order they got added + + + +--- +## Functions +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead +### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead + + + +--- +## Aliases +### StackAutoSize +[`boolean`](../../API/builtins/boolean.md) +> When set to true, the width and height of the stack will be automatically +> calculated and updated from the stack's child views, to ensure all views fit +> into the stack. +> When disabled, the width and height must be set manually. +> * Default: true + +### ViewBackgroundStyle +`"body"` | `"border"` | `"group"` | `"invisible"` | `"panel"` | `"plain"` +> ```lua +> -- Setup a background style for the view. +> ViewBackgroundStyle: +> | "invisible" -- no background (Default) +> | "plain" -- undecorated, single coloured background +> | "border" -- same as plain, but with a bold nested border +> | "body" -- main "background" style, as used in dialog backgrounds +> | "panel" -- alternative "background" style, beveled +> | "group" -- background for "nested" groups within body +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size +> for example `vb:text { width = "80%"}`. The percentage values are +> relative to the view's parent size and will automatically update on size changes. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + diff --git a/docs/API/renoise/renoise.Views.Switch.md b/docs/API/renoise/renoise.Views.Switch.md index 6558bdda..3afc50b7 100644 --- a/docs/API/renoise/renoise.Views.Switch.md +++ b/docs/API/renoise/renoise.Views.Switch.md @@ -38,22 +38,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -66,10 +77,19 @@ > Add index change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`IntegerValueNotifierFunction`](#IntegerValueNotifierFunction)) > Remove index change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -103,6 +123,46 @@ [`integer`](../../API/builtins/integer.md) > The currently selected item's index +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -110,9 +170,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.Text.md b/docs/API/renoise/renoise.Views.Text.md index 4c3bd9b4..9fc372f2 100644 --- a/docs/API/renoise/renoise.Views.Text.md +++ b/docs/API/renoise/renoise.Views.Text.md @@ -23,6 +23,14 @@ ### style : [`TextStyle`](#TextStyle) > Get/set the color style the text should be displayed with. +### color : [`TextColor`](#TextColor) +> When set, the text will be drawn in the specified color. +> Set style to something else than "custom" or color to `{0, 0, 0}` +> to enable the default theme color for the text again. + +### orientation : [`TextOrientation`](#TextOrientation) +> Setup the texts's orientation (writing direction). + ### align : [`TextAlignment`](#TextAlignment) > Setup the text's alignment. Applies only when the view's size is larger than > the needed size to draw the text @@ -33,22 +41,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -57,15 +76,31 @@ --- ## Functions -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead --- ## Aliases +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + ### TextAlignment `"center"` | `"left"` | `"right"` > ```lua @@ -77,8 +112,108 @@ > | "center" -- center text > ``` +### TextColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the text will be drawn in the specified color. +> -- Set style to something else than "custom" or color to `{0, 0, 0}` +> -- to enable the default theme color for the text again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> TextColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -87,6 +222,18 @@ > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### TextOrientation +`"horizontal"` | `"horizontal-rl"` | `"vertical"` | `"vertical-tb"` +> ```lua +> -- Setup the texts's orientation (writing direction). +> TextOrientation: +> | "horizontal" -- Draw from left to right (Default) +> | "horizontal-rl" -- Draw from right to left +> | "vertical" -- Draw from bottom to top +> | "vertical-tb" -- Draw from top to bottom > ``` ### TextSingleLineString @@ -96,13 +243,147 @@ > * Default: "" ### TextStyle -`"disabled"` | `"normal"` | `"strong"` +`"custom"` | `"disabled"` | `"normal"` | `"strong"` > ```lua > -- Get/set the color style the text should be displayed with. > TextStyle: > | "normal" -- (Default) > | "strong" -- highlighted color > | "disabled" -- greyed out color +> | "custom" -- custom color +> ``` + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" > ``` ### ViewDimension @@ -112,9 +393,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.TextField.md b/docs/API/renoise/renoise.Views.TextField.md index 7bd2a85e..d6f645fe 100644 --- a/docs/API/renoise/renoise.Views.TextField.md +++ b/docs/API/renoise/renoise.Views.TextField.md @@ -38,22 +38,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -66,10 +77,19 @@ > Add value change (text change) notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`StringValueNotifierFunction`](#StringValueNotifierFunction)) > Remove value change (text change) notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -112,6 +132,46 @@ > Exactly the same as "value"; provided for consistency. > * Default: "" +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -119,9 +179,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.TextLink.md b/docs/API/renoise/renoise.Views.TextLink.md new file mode 100644 index 00000000..a8203841 --- /dev/null +++ b/docs/API/renoise/renoise.Views.TextLink.md @@ -0,0 +1,467 @@ +# renoise.Views.TextLink +> Shows a text string which is highlighted when hovering with the mouse, +> and which can be clicked to perform some action. +> To create a hyperlink alike text, add a notifier which opens an url via: +> `renoise.app():open_url("https://some.url.com")` +> property. +> ```text +> *Text, * +> ``` + + + + +--- +## Properties +### active : [`ControlActive`](#ControlActive) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### midi_mapping : [`ControlMidiMappingString`](#ControlMidiMappingString)[`?`](../../API/builtins/nil.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### text : [`TextSingleLineString`](#TextSingleLineString) +> The text that should be displayed. Setting a new text will resize +> the view in order to make the text fully visible (expanding only). +> * Default: "" + +### font : [`TextFontStyle`](#TextFontStyle) +> The style that the text should be displayed with. + +### style : [`TextStyle`](#TextStyle) +> Get/set the color style the text should be displayed with. + +### color : [`TextColor`](#TextColor) +> When set, the text will be drawn in the specified color. +> Set style to something else than "custom" or color to `{0, 0, 0}` +> to enable the default theme color for the text again. + +### orientation : [`TextOrientation`](#TextOrientation) +> Setup the texts's orientation (writing direction). + +### align : [`TextAlignment`](#TextAlignment) +> Setup the text's alignment. Applies only when the view's size is larger than +> the needed size to draw the text + +### visible : [`ViewVisibility`](#ViewVisibility) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### width : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### tooltip : [`ViewTooltip`](#ViewTooltip) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + +### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] +> **READ-ONLY** Empty for all controls, for layout views this contains the +> layout child views in the order they got added + + + +--- +## Functions +### add_pressed_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) +> Add/remove text link hit/release notifier functions. +### add_released_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) +### remove_pressed_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) +### remove_released_notifier([*self*](../../API/builtins/self.md), notifier : [`NotifierFunction`](#NotifierFunction)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead +### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead + + + +--- +## Aliases +### ControlActive +[`boolean`](../../API/builtins/boolean.md) +> Instead of making a control invisible, you can also make it inactive. +> Deactivated controls will still be shown, and will still show their +> currently assigned values, but will not allow changes. Most controls will +> display as "grayed out" to visualize the deactivated state. + +### ControlMidiMappingString +[`string`](../../API/builtins/string.md) +> When set, the control will be highlighted when Renoise's MIDI mapping dialog +> is open. When clicked, it selects the specified string as a MIDI mapping +> target action. This target acton can either be one of the globally available +> mappings in Renoise, or those that were created by the tool itself. +> Target strings are not verified. When they point to nothing, the mapped MIDI +> message will do nothing and no error is fired. + +### NotifierFunction +fun() + + +### RGBColor +{ 1 : [`integer`](../../API/builtins/integer.md), 2 : [`integer`](../../API/builtins/integer.md), 3 : [`integer`](../../API/builtins/integer.md) } +> A table of 3 bytes (ranging from 0 to 255) +> representing the red, green and blue channels of a color. +> {0xFF, 0xFF, 0xFF} is white +> {165, 73, 35} is the red from the Renoise logo + +### TextAlignment +`"center"` | `"left"` | `"right"` +> ```lua +> -- Setup the text's alignment. Applies only when the view's size is larger than +> -- the needed size to draw the text +> TextAlignment: +> | "left" -- (Default) +> | "right" -- aligned to the right +> | "center" -- center text +> ``` + +### TextColor +[`RGBColor`](#RGBColor) | [`ThemeColor`](#ThemeColor) +> ```lua +> -- When set, the text will be drawn in the specified color. +> -- Set style to something else than "custom" or color to `{0, 0, 0}` +> -- to enable the default theme color for the text again. +> -- A table of 3 bytes (ranging from 0 to 255) +> -- representing the red, green and blue channels of a color. +> -- {0xFF, 0xFF, 0xFF} is white +> -- {165, 73, 35} is the red from the Renoise logo +> -- The application theme's colors +> TextColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### TextFontStyle +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` +> ```lua +> -- The style that the text should be displayed with. +> TextFontStyle: +> | "normal" -- (Default) +> | "big" -- big text +> | "bold" -- bold font +> | "italic" -- italic font +> | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### TextOrientation +`"horizontal"` | `"horizontal-rl"` | `"vertical"` | `"vertical-tb"` +> ```lua +> -- Setup the texts's orientation (writing direction). +> TextOrientation: +> | "horizontal" -- Draw from left to right (Default) +> | "horizontal-rl" -- Draw from right to left +> | "vertical" -- Draw from bottom to top +> | "vertical-tb" -- Draw from top to bottom +> ``` + +### TextSingleLineString +[`string`](../../API/builtins/string.md) +> The text that should be displayed. Setting a new text will resize +> the view in order to make the text fully visible (expanding only). +> * Default: "" + +### TextStyle +`"custom"` | `"disabled"` | `"normal"` | `"strong"` +> ```lua +> -- Get/set the color style the text should be displayed with. +> TextStyle: +> | "normal" -- (Default) +> | "strong" -- highlighted color +> | "disabled" -- greyed out color +> | "custom" -- custom color +> ``` + +### ThemeColor +`"alternate_main_back"` | `"alternate_main_font"` | `"automation_grid"` | `"automation_line_edge"` | `"automation_line_fill"` | `"automation_marker_diamond"` | `"automation_marker_pair"` | `"automation_marker_play"` | `"automation_marker_single"` | `"automation_point"` | `"body_back"` | `"body_font"` | `"button_back"` | `"button_font"` | `"button_highlight_font"` | `"default_color_01"` | `"default_color_02"` | `"default_color_03"` | `"default_color_04"` | `"default_color_05"` | `"default_color_06"` | `"default_color_07"` | `"default_color_08"` | `"default_color_09"` | `"default_color_10"` | `"default_color_11"` | `"default_color_12"` | `"default_color_13"` | `"default_color_14"` | `"default_color_15"` | `"default_color_16"` | `"folder"` | `"main_back"` | `"main_font"` | `"midi_mapping_back"` | `"midi_mapping_font"` | `"pattern_centerbar_back"` | `"pattern_centerbar_back_standby"` | `"pattern_centerbar_font"` | `"pattern_centerbar_font_standby"` | `"pattern_default_back"` | `"pattern_default_font"` | `"pattern_default_font_delay"` | `"pattern_default_font_dspfx"` | `"pattern_default_font_global"` | `"pattern_default_font_other"` | `"pattern_default_font_panning"` | `"pattern_default_font_pitch"` | `"pattern_default_font_unused"` | `"pattern_default_font_volume"` | `"pattern_highlighted_back"` | `"pattern_highlighted_font"` | `"pattern_highlighted_font_delay"` | `"pattern_highlighted_font_dspfx"` | `"pattern_highlighted_font_global"` | `"pattern_highlighted_font_other"` | `"pattern_highlighted_font_panning"` | `"pattern_highlighted_font_pitch"` | `"pattern_highlighted_font_unused"` | `"pattern_highlighted_font_volume"` | `"pattern_mute_state"` | `"pattern_playposition_back"` | `"pattern_playposition_font"` | `"pattern_selection"` | `"pattern_standby_selection"` | `"scrollbar"` | `"selected_button_back"` | `"selected_button_font"` | `"selection_back"` | `"selection_font"` | `"slider"` | `"standby_selection_back"` | `"standby_selection_font"` | `"strong_body_font"` | `"tooltip_back"` | `"tooltip_font"` | `"valuebox_back"` | `"valuebox_font"` | `"valuebox_font_icons"` | `"vumeter_back_clipped"` | `"vumeter_back_normal"` | `"vumeter_meter"` | `"vumeter_meter_high"` | `"vumeter_meter_low"` | `"vumeter_meter_middle"` | `"vumeter_peak"` +> ```lua +> -- The application theme's colors +> ThemeColor: +> | "main_back" +> | "main_font" +> | "alternate_main_back" +> | "alternate_main_font" +> | "body_back" +> | "body_font" +> | "strong_body_font" +> | "button_back" +> | "button_font" +> | "button_highlight_font" +> | "selected_button_back" +> | "selected_button_font" +> | "selection_back" +> | "selection_font" +> | "standby_selection_back" +> | "standby_selection_font" +> | "midi_mapping_back" +> | "midi_mapping_font" +> | "tooltip_back" +> | "tooltip_font" +> | "valuebox_back" +> | "valuebox_font" +> | "valuebox_font_icons" +> | "scrollbar" +> | "slider" +> | "folder" +> | "pattern_default_back" +> | "pattern_default_font" +> | "pattern_default_font_volume" +> | "pattern_default_font_panning" +> | "pattern_default_font_pitch" +> | "pattern_default_font_delay" +> | "pattern_default_font_global" +> | "pattern_default_font_other" +> | "pattern_default_font_dspfx" +> | "pattern_default_font_unused" +> | "pattern_highlighted_back" +> | "pattern_highlighted_font" +> | "pattern_highlighted_font_volume" +> | "pattern_highlighted_font_panning" +> | "pattern_highlighted_font_pitch" +> | "pattern_highlighted_font_delay" +> | "pattern_highlighted_font_global" +> | "pattern_highlighted_font_other" +> | "pattern_highlighted_font_dspfx" +> | "pattern_highlighted_font_unused" +> | "pattern_playposition_back" +> | "pattern_playposition_font" +> | "pattern_centerbar_back" +> | "pattern_centerbar_font" +> | "pattern_centerbar_back_standby" +> | "pattern_centerbar_font_standby" +> | "pattern_selection" +> | "pattern_standby_selection" +> | "pattern_mute_state" +> | "automation_grid" +> | "automation_line_edge" +> | "automation_line_fill" +> | "automation_point" +> | "automation_marker_play" +> | "automation_marker_single" +> | "automation_marker_pair" +> | "automation_marker_diamond" +> | "vumeter_meter" +> | "vumeter_meter_low" +> | "vumeter_meter_middle" +> | "vumeter_meter_high" +> | "vumeter_peak" +> | "vumeter_back_normal" +> | "vumeter_back_clipped" +> | "default_color_01" +> | "default_color_02" +> | "default_color_03" +> | "default_color_04" +> | "default_color_05" +> | "default_color_06" +> | "default_color_07" +> | "default_color_08" +> | "default_color_09" +> | "default_color_10" +> | "default_color_11" +> | "default_color_12" +> | "default_color_13" +> | "default_color_14" +> | "default_color_15" +> | "default_color_16" +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + +### ViewDimension +[`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size +> for example `vb:text { width = "80%"}`. The percentage values are +> relative to the view's parent size and will automatically update on size changes. + +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + +### ViewTooltip +[`string`](../../API/builtins/string.md) +> A ViewTooltip text that should be shown for this view on mouse hover. +> * Default: "" (no tip will be shown) + +### ViewVisibility +[`boolean`](../../API/builtins/boolean.md) +> Set visible to false to hide a view (make it invisible without removing +> it). Please note that view.visible will also return false when any of its +> parents are invisible (when its implicitly invisible). +> * Default: true + + diff --git a/docs/API/renoise/renoise.Views.Value.md b/docs/API/renoise/renoise.Views.Value.md index 9f708dc4..4615a10c 100644 --- a/docs/API/renoise/renoise.Views.Value.md +++ b/docs/API/renoise/renoise.Views.Value.md @@ -28,22 +28,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -56,10 +67,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NumberValueNotifierFunction`](#NumberValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -85,7 +105,7 @@ > ``` ### TextFontStyle -`"big"` | `"bold"` | `"italic"` | `"mono"` | `"normal"` +`"big"` | `"bold"` | `"code"` | `"italic"` | `"mono"` | `"normal"` > ```lua > -- The style that the text should be displayed with. > TextFontStyle: @@ -94,6 +114,47 @@ > | "bold" -- bold font > | "italic" -- italic font > | "mono" -- monospace font +> | "code" -- monospace code font +> ``` + +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" > ``` ### ViewDimension @@ -103,9 +164,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.ValueBox.md b/docs/API/renoise/renoise.Views.ValueBox.md index d896099f..4512dd96 100644 --- a/docs/API/renoise/renoise.Views.ValueBox.md +++ b/docs/API/renoise/renoise.Views.ValueBox.md @@ -49,22 +49,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -77,10 +88,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NumberValueNotifierFunction`](#NumberValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -127,6 +147,46 @@ > The minimum value that can be set using the view > * Default: 0 +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -134,9 +194,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.ValueField.md b/docs/API/renoise/renoise.Views.ValueField.md index 9685105c..1c01d1d9 100644 --- a/docs/API/renoise/renoise.Views.ValueField.md +++ b/docs/API/renoise/renoise.Views.ValueField.md @@ -48,22 +48,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -76,10 +87,19 @@ > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`NumberValueNotifierFunction`](#NumberValueNotifierFunction)) > Remove value change notifier -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead @@ -130,6 +150,46 @@ > | "center" -- center text > ``` +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -137,9 +197,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.View.md b/docs/API/renoise/renoise.Views.View.md index 8fb243af..a0f4c431 100644 --- a/docs/API/renoise/renoise.Views.View.md +++ b/docs/API/renoise/renoise.Views.View.md @@ -13,22 +13,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -37,15 +48,64 @@ --- ## Functions -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead ### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) -> Remove a child view from this view. +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead --- ## Aliases +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -53,9 +113,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/API/renoise/renoise.Views.XYPad.md b/docs/API/renoise/renoise.Views.XYPad.md index 88527938..7dd2c924 100644 --- a/docs/API/renoise/renoise.Views.XYPad.md +++ b/docs/API/renoise/renoise.Views.XYPad.md @@ -39,22 +39,33 @@ > parents are invisible (when its implicitly invisible). > * Default: true +### origin : [`ViewOrigin`](#ViewOrigin) +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + ### width : [`ViewDimension`](#ViewDimension) -> The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> **Deprecated.** Use property `size` instead. ### height : [`ViewDimension`](#ViewDimension) +> **Deprecated.** Use property `size` instead. + +### size : [`ViewSize`](#ViewSize) > The dimensions of a view has to be larger than 0. -> For nested views you can also specify relative size -> for example `vb:text { width = "80%"}`. The percentage values are -> relative to the view's parent size and will automatically update on size changes. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. ### tooltip : [`ViewTooltip`](#ViewTooltip) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) +### cursor : [`ViewCursorShape`](#ViewCursorShape) +> The cursor cursor for this view which apears on mouse hover. +> Using a "none" shape will use use underlying view's cursor or the default cursor. + ### views : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)[] > **READ-ONLY** Empty for all controls, for layout views this contains the > layout child views in the order they got added @@ -81,10 +92,19 @@ --- ## Functions -### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### add_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Add a new child view to this view. -### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +### remove_view([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) > Remove a child view from this view. +### swap_views([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> Swap position of two child views in this view. With a series of swaps views +> can be moved to any position in the parent. +### add_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `add_view` instead +### remove_child([*self*](../../API/builtins/self.md), child : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `remove_view` instead +### swap_childs([*self*](../../API/builtins/self.md), child1 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md), child2 : [`renoise.Views.View`](../../API/renoise/renoise.Views.View.md)) +> **Deprecated.** Use `swap_views` instead ### add_notifier([*self*](../../API/builtins/self.md), notifier : [`XYValueNotifierFunction`](#XYValueNotifierFunction)) > Add value change notifier ### remove_notifier([*self*](../../API/builtins/self.md), notifier : [`XYValueNotifierFunction`](#XYValueNotifierFunction)) @@ -124,6 +144,46 @@ [`number`](../../API/builtins/number.md) > The current value of the view +### ViewCursorShape +`"busy"` | `"change_value"` | `"crosshair"` | `"default"` | `"drag"` | `"drop"` | `"edit_text"` | `"empty"` | `"erase"` | `"extend_bottom"` | `"extend_bottom_alias"` | `"extend_left"` | `"extend_left_alias"` | `"extend_right"` | `"extend_right_alias"` | `"extend_top"` | `"extend_top_alias"` | `"marker"` | `"move"` | `"nodrop"` | `"none"` | `"pencil"` | `"play"` | `"resize_edge_diagonal_left"` | `"resize_edge_diagonal_right"` | `"resize_edge_horizontal"` | `"resize_edge_vertical"` | `"resize_horizontal"` | `"resize_vertical"` | `"zoom"` | `"zoom_horizontal"` | `"zoom_vertical"` +> ```lua +> -- The cursor cursor for this view which apears on mouse hover. +> -- Using a "none" shape will use use underlying view's cursor or the default cursor. +> ViewCursorShape: +> | "none" +> | "empty" +> | "default" +> | "change_value" +> | "edit_text" +> | "pencil" +> | "marker" +> | "crosshair" +> | "move" +> | "erase" +> | "play" +> | "drag" +> | "drop" +> | "nodrop" +> | "busy" +> | "resize_vertical" +> | "resize_horizontal" +> | "resize_edge_vertical" +> | "resize_edge_horizontal" +> | "resize_edge_diagonal_left" +> | "resize_edge_diagonal_right" +> | "extend_left" +> | "extend_right" +> | "extend_top" +> | "extend_bottom" +> | "extend_left_alias" +> | "extend_right_alias" +> | "extend_top_alias" +> | "extend_bottom_alias" +> | "zoom_vertical" +> | "zoom_horizontal" +> | "zoom" +> ``` + ### ViewDimension [`string`](../../API/builtins/string.md) | [`integer`](../../API/builtins/integer.md) > The dimensions of a view has to be larger than 0. @@ -131,9 +191,28 @@ > for example `vb:text { width = "80%"}`. The percentage values are > relative to the view's parent size and will automatically update on size changes. +### ViewOrigin +{ 1 : [`ViewPosition`](#ViewPosition), 2 : [`ViewPosition`](#ViewPosition) } | { x : [`ViewPosition`](#ViewPosition), y : [`ViewPosition`](#ViewPosition) } +> The position of a view within its parent view. +> Only the `stack` layouts allows to freely position child views. Other +> layout views will automatically set the origin, but the origin +> then still can be read in for example mouse handlers. + +### ViewPosition +[`integer`](../../API/builtins/integer.md) +> Horizontal (x) or Vertical (y) position of a view within its parent view. + +### ViewSize +{ 1 : [`ViewDimension`](#ViewDimension), 2 : [`ViewDimension`](#ViewDimension) } | { height : [`ViewDimension`](#ViewDimension), width : [`ViewDimension`](#ViewDimension) } +> The dimensions of a view has to be larger than 0. +> For nested views you can also specify relative size, for example +> `vb:text { size = { width = "80%", height = 20}}`. +> The percentage values are relative to the view's parent size and will +> automatically update when the parent view's size changes. + ### ViewTooltip [`string`](../../API/builtins/string.md) -> A tooltip text that should be shown for this view on mouse hover. +> A ViewTooltip text that should be shown for this view on mouse hover. > * Default: "" (no tip will be shown) ### ViewVisibility diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index b859c1ce..4639866b 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -10,21 +10,19 @@ - [Guides](guide/README.md) - [Classes](guide/classes.md) - [Observables](guide/observables.md) - - [Files & Bits](guide/files&bits.md) + - [Renoise Application](guide/application.md) + - [Renoise Song](guide/song.md) + - [Renoise Tool](guide/tool.md) + - [File IO & Bits](guide/files&bits.md) - [Sockets](guide/sockets.md) - [MIDI](guide/midi.md) - [OSC](guide/osc.md) - - [Pattern Iterator](guide/pattern_iterator.md) - - [Track Automation](guide/track_automation.md) - - [Sample Buffers](guide/sample_buffer.md) - - [Keybindings](guide/keybindings.md) - - [Menu Entries](guide/menus.md) - - [Views](guide/views.md) - - [Preferences](guide/preferences.md) + - [SQLite](guide/sqlite.md) - [API Reference](API/README.md) - [renoise](API/renoise.md) - [Application](API/renoise/renoise.Application.md) + - [ApplicationTheme](API/renoise/renoise.ApplicationTheme.md) - [ApplicationWindow](API/renoise/renoise.ApplicationWindow.md) - [AudioDevice](API/renoise/renoise.AudioDevice.md) - [DeviceParameter](API/renoise/renoise.DeviceParameter.md) @@ -52,6 +50,7 @@ - [InstrumentMidiOutputProperties](API/renoise/renoise.InstrumentMidiOutputProperties.md) - [InstrumentPhrase](API/renoise/renoise.InstrumentPhrase.md) - [InstrumentPhraseMapping](API/renoise/renoise.InstrumentPhraseMapping.md) + - [InstrumentPhraseScript](API/renoise/renoise.InstrumentPhraseScript.md) - [InstrumentPluginDevice](API/renoise/renoise.InstrumentPluginDevice.md) - [InstrumentPluginProperties](API/renoise/renoise.InstrumentPluginProperties.md) - [InstrumentTriggerOptions](API/renoise/renoise.InstrumentTriggerOptions.md) @@ -91,6 +90,7 @@ - [Socket.SocketServer](API/renoise/renoise.Socket.SocketServer.md) - [Song](API/renoise/renoise.Song.md) - [SongPos](API/renoise/renoise.SongPos.md) + - [SQLite](API/renoise/renoise.SQLite.md) - [Track](API/renoise/renoise.Track.md) - [Transport](API/renoise/renoise.Transport.md) - [ViewBuilder](API/renoise/renoise.ViewBuilder.md) @@ -98,6 +98,8 @@ - [Views.Aligner](API/renoise/renoise.Views.Aligner.md) - [Views.Bitmap](API/renoise/renoise.Views.Bitmap.md) - [Views.Button](API/renoise/renoise.Views.Button.md) + - [Views.Canvas](API/renoise/renoise.Views.Canvas.md) + - [Views.Canvas.Context](API/renoise/renoise.Views.Canvas.Context.md) - [Views.CheckBox](API/renoise/renoise.Views.CheckBox.md) - [Views.Chooser](API/renoise/renoise.Views.Chooser.md) - [Views.Control](API/renoise/renoise.Views.Control.md) @@ -107,17 +109,19 @@ - [Views.Popup](API/renoise/renoise.Views.Popup.md) - [Views.Rack](API/renoise/renoise.Views.Rack.md) - [Views.RotaryEncoder](API/renoise/renoise.Views.RotaryEncoder.md) + - [Views.ScrollBar](API/renoise/renoise.Views.ScrollBar.md) - [Views.Slider](API/renoise/renoise.Views.Slider.md) + - [Views.Stack](API/renoise/renoise.Views.Stack.md) - [Views.Switch](API/renoise/renoise.Views.Switch.md) - [Views.Text](API/renoise/renoise.Views.Text.md) - [Views.TextField](API/renoise/renoise.Views.TextField.md) + - [Views.TextLink](API/renoise/renoise.Views.TextLink.md) - [Views.Value](API/renoise/renoise.Views.Value.md) - [Views.ValueBox](API/renoise/renoise.Views.ValueBox.md) - [Views.ValueField](API/renoise/renoise.Views.ValueField.md) - [Views.View](API/renoise/renoise.Views.View.md) - [Views.XYPad](API/renoise/renoise.Views.XYPad.md) - [Module Extensions](API/modules.md) - - [bit](API/modules/bit.md) - [debug](API/modules/debug.md) - [global](API/modules/global.md) - [io](API/modules/io.md) diff --git a/docs/guide/README.md b/docs/guide/README.md index b8b14ead..022cdb35 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,3 +1,5 @@ # Guides to the Renoise API -In this section you can learn about different aspects of the API. These guides will assume you've already read the chapters in [our introduction](../start/development.md) and you are able to package and install tools. +Welcome to the guides for the Renoise Scripting API. + +In this section, you can learn about different aspects of the API through practical examples and explanations. These guides assume you have already read the chapters in our [introduction](../start/development.md) and are familiar with how to package and install tools. diff --git a/docs/guide/application.md b/docs/guide/application.md new file mode 100644 index 00000000..1eee2dfc --- /dev/null +++ b/docs/guide/application.md @@ -0,0 +1,178 @@ +# Renoise Application + +The `renoise.app()` function is the entry point for interacting with the Renoise application itself. It returns a [`renoise.Application`](../API/renoise/renoise.Application.md) object, which provides access to global application states, functions for user interaction like dialogs, and control over the main window. + +## Controlling the Application Window + +The [`renoise.ApplicationWindow`](../API/renoise/renoise.ApplicationWindow.md) object, accessed via `renoise.app().window`, allows you to query and control the state of the main Renoise UI. + +```lua +local window = renoise.app().window + +-- Toggle fullscreen mode +window.fullscreen = not window.fullscreen + +-- Check if the disk browser is visible +if window.disk_browser_is_visible then + print("Disk browser is currently open.") +end + +-- Switch the middle frame to the Mixer view +window.active_middle_frame = + renoise.ApplicationWindow.MIDDLE_FRAME_MIXER +``` + +You can also attach notifiers to many window properties to react to UI changes made by the user. + +```lua +local window = renoise.app().window + +-- Be notified when the disk browser visibility changes +function disk_browser_visibility_changed() + if window.disk_browser_is_visible then + renoise.app():show_status("Disk browser was opened.") + else + renoise.app():show_status("Disk browser was closed.") + end +end + +window.disk_browser_is_visible_observable:add_notifier( + disk_browser_visibility_changed +) +``` + +## Song and File Handling + +The application object provides functions to load, and save songs, instrument and other kinds of components. Note that these operations are not always instantaneous, as Renoise may need to prompt the user to save changes. + +To reliably execute code after a new song is created or loaded, you should use notifiers. + +```lua +local app = renoise.app() + +-- This will show a file dialog to the user. The song is not loaded immediately. +app:load_song("/path/to/some/song_file") + +-- To run code after a new song is ready, use a notifier. +-- This is typically done in your tool's initialization code. +function handle_new_document() + print("A new song was created or loaded. The new song name is: " .. + renoise.song().name) +end + +-- The 'new_document_observable' is fired after a new song is +--- successfully created or loaded. +renoise.tool().app_new_document_observable:add_notifier(handle_new_document) + +-- To save a song to a specific file: +app:save_song_as("/path/to/MyNewSong.xrns") +``` + +## Showing Dialogs and Messages + +A common task for tools is to communicate with the user. The application object provides several functions to show different kinds of dialogs and messages. + +### Simple Messages + +For simple notifications, you can use `show_message`, `show_error`, `show_warning`, or `show_status`. + +```lua +local app = renoise.app() + +-- Show a message in the status bar +app:show_status("This is a status message.") + +-- Show a modal info dialog +app:show_message("This is an informational message.") + +-- Show a modal warning dialog +app:show_warning("This is a warning message.") + +-- Show a modal error dialog +app:show_error("This is an error message.") +``` + +### User Prompts + +To ask the user for a choice, you can use `show_prompt`. It displays a dialog with custom buttons and returns the label of the button that was pressed. + +```lua +local app = renoise.app() + +local pressed_button = app:show_prompt( + "Confirm Action", + "Do you want to proceed?", + { "Yes", "No", "Cancel" } +) + +if pressed_button == "Yes" then + app:show_message("You chose to proceed.") +elseif pressed_button == "No" then + app:show_message("You chose not to proceed.") +else + app:show_message("You canceled the operation.") +end +``` + +### Custom Dialogs + +For more complex user interfaces, you can create custom non-modal dialogs (tool windows) with `show_custom_dialog`. This requires using the `renoise.ViewBuilder` API to construct the UI. + +```lua +-- A simple custom dialog example +local vb = renoise.ViewBuilder() + +local my_dialog = nil +local my_dialog_content = vb:column { + margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN, + spacing = renoise.ViewBuilder.DEFAULT_DIALOG_SPACING, + views = { + vb:text { + text = "This is a custom dialog." + }, + vb:button { + text = "Close Me", + notifier = function() + -- my_dialog is defined when calling show_custom_dialog + my_dialog:close() + end + } + } +} + +my_dialog = renoise.app():show_custom_dialog( + "My Tool Window", my_dialog_content +) +``` + +## File and Path Prompts + +Your tool might need to read from or write to files. The API provides functions to open native file browser dialogs. + +```lua +local app = renoise.app() + +-- Prompt the user to select a directory +local dir_path = app:prompt_for_path("Select a Project Folder") +if dir_path and #dir_path > 0 then + app:show_message("You selected the directory: " .. dir_path) +end + +-- Prompt the user to select a file to open +local file_to_read = app:prompt_for_filename_to_read( + { "txt", "lua" }, + "Open a Text File" +) +if file_to_read and #file_to_read > 0 then + app:show_message("You selected the file: " .. file_to_read) +end + +-- Prompt the user for a filename to save +local file_to_write = app:prompt_for_filename_to_write( + "xml", + "Save Configuration" +) +if file_to_write and #file_to_write > 0 then + app:show_message("File will be saved to: " .. file_to_write) +end +``` diff --git a/docs/guide/classes.md b/docs/guide/classes.md index bf841043..ee83c8f3 100644 --- a/docs/guide/classes.md +++ b/docs/guide/classes.md @@ -1,16 +1,15 @@ # Classes -The Lua language has by default no `class` construct. But the Renoises lua API has a simple OO support inbuilt -> `class "MyClass"`. All Renoise API objects use such classes and you can use them too in your tools. +The Lua language does not have a built-in `class` construct. However, the Renoise Lua API provides simple object-oriented programming support via a global `class()` function. All Renoise API objects use such classes, and you can use them in your tools as well. -See [luabind docs](https://www.rasterbar.com/products/luabind/docs.html#defining-classes-in-lua) -for more technical info and below for some simple examples +See the [luabind documentation](https://www.rasterbar.com/products/luabind/docs.html#defining-classes-in-lua) for more technical information, and the examples below for how to use them. ## Examples ```lua -- abstract class - class 'Animal' + function Animal:__init(name) self.name = name self.can_fly = nil @@ -19,8 +18,8 @@ class 'Animal' function Animal:__tostring() assert(self.can_fly ~= nil, "I don't know if I can fly or not") - return ("I am a %s (%s) and I %s fly"):format(self.name, type(self), - (self.can_fly and "can fly" or "can not fly")) + return ("I am a %s (%s) and I %s"):format(self.name, type(self), + (self.can_fly and "can fly" or "cannot fly")) end @@ -28,6 +27,7 @@ class 'Animal' -- MAMMAL class 'Mammal' (Animal) + function Mammal:__init(str) Animal.__init(self, str) self.can_fly = false @@ -35,6 +35,7 @@ class 'Mammal' (Animal) -- BIRD class 'Bird' (Animal) + function Bird:__init(str) Animal.__init(self, str) self.can_fly = true @@ -42,6 +43,7 @@ class 'Bird' (Animal) -- FISH class 'Fish' (Animal) + function Fish:__init(str) Animal.__init(self, str) self.can_fly = false @@ -50,50 +52,43 @@ class 'Fish' (Animal) -- run -local farm = table.create() +local farm = {} -farm:insert(Mammal("cow")) -farm:insert(Bird("sparrow")) -farm:insert(Fish("bass")) +table.insert(farm, Mammal("cow")) +table.insert(farm, Bird("sparrow")) +table.insert(farm, Fish("bass")) print(("type(Mammal('cow')) -> %s"):format(type(Mammal("cow")))) print(("type(Mammal) -> %s"):format(type(Mammal))) -for _,animal in pairs(farm) do +for _,animal in ipairs(farm) do print(animal) end ``` Something to keep in mind: -* constructor `function MyClass:__init(args)` must be defined for each class, - or the class can't be used to instantiate objects. - -* class defs are always global, so even locally defined classes will be - registered globally. +* A constructor, `function MyClass:__init(args)`, must be defined for each class, or the class cannot be used to instantiate objects. +* Class definitions are always global, so even locally defined classes will be registered globally. ## Class operators -You can overload most operators in Lua for your classes. You do this by -simply declaring a member function with the same name as an operator -(the name of the metamethods in Lua). +You can overload most operators in Lua for your classes. You do this by simply declaring a member function with the same name as an operator's corresponding metamethod in Lua. The operators you can overload are: -* __add -* __sub -* __mul -* __div -* __pow -* __lt -* __le -* __eq -* __call -* __unm -* __tostring -* __len - -Note: `__tostring` isn't really an operator, but it's the metamethod that is -called by the standard library's tostring() function. - +* `__add` (addition) +* `__sub` (subtraction) +* `__mul` (multiplication) +* `__div` (division) +* `__pow` (exponentiation) +* `__lt` (less than) +* `__le` (less than or equal to) +* `__eq` (equality) +* `__call` (function call) +* `__unm` (unary minus) +* `__tostring` (serialization) +* `__len` (length operator `#`) + +Note: `__tostring` isn't really an operator, but it's the metamethod that is called by the standard library's `tostring()` function. diff --git a/docs/guide/files&bits.md b/docs/guide/files&bits.md index 6dca9923..57efafaf 100644 --- a/docs/guide/files&bits.md +++ b/docs/guide/files&bits.md @@ -1,18 +1,21 @@ -# Files&Bits.lua +# File IO & Bits -In order to access the raw bits and bytes of some data, e.g. to read or write binary (file) streams, you can use the Lua `bit` library. It's built into the Renoise API. There's no need to `require` it. +The Renoise API uses Lua's standard [io library](https://www.lua.org/pil/21.html) to read or write external files. -See [bit documentation](https://bitop.luajit.org/) for more info and examples. +To access the raw bits and bytes of some data, for example, to read or write binary file streams, you can use the `bit` library. It's built into the Renoise API, so there's no need to `require` it. + +See the [LuaJIT bit library documentation](https://bitop.luajit.org/api.html) for more info and examples. ```lua --- reading integer numbers or raw bytes from a file +-- Reading integer numbers or raw bytes from a file local function read_word(file) local bytes = file:read(2) if (not bytes or #bytes < 2) then return nil else - return bit.bor(bytes:byte( 1), + -- little-endian + return bit.bor(bytes:byte(1), bit.lshift(bytes:byte(2), 8)) end end @@ -22,6 +25,7 @@ local function read_dword(file) if (not bytes or #bytes < 4) then return nil else + -- little-endian return bit.bor(bytes:byte(1), bit.lshift(bytes:byte(2), 8), bit.lshift(bytes:byte(3), 16), @@ -29,9 +33,13 @@ local function read_dword(file) end end --- and so on (adapt as needed to mess with endianess!) ... +-- and so on (adapt as needed to deal with endianness!) ... -local file = io.open("some_binary_file.bin", "rb") +local file, err = io.open("some_binary_file.bin", "rb") +if not file then + print("Could not open file: " .. tostring(err)) + return +end local bytes = file:read(512) @@ -45,5 +53,6 @@ end print(read_word(file) or "unexpected end of file") print(read_dword(file) or "unexpected end of file") -``` +file:close() +``` diff --git a/docs/guide/instruments.md b/docs/guide/instruments.md deleted file mode 100644 index 4a8b5c20..00000000 --- a/docs/guide/instruments.md +++ /dev/null @@ -1,71 +0,0 @@ -# Instruments.lua - -```lua ---[[ - -This procedure sorts instruments from biggest to smallest using the Bubble -Sort algorithm. - -Bubble sort is Computer Science 101 material. It is included as a code snippet -for learning purposes, but to be honest, this is a horrible idea. The -procedure "works" but will take a long time to finish. This is not a practical -solution, only educational. - -]]-- - --- Set up a table named 'placeholder' --- The key is the instrument position --- The value is the size of the sample(s) contained within - -local placeholder = { } -local instruments = renoise.song().instruments -local total = #instruments -for i = 1,total do - for j = 1,#instruments[i].samples do - placeholder[i] = 0 - if instruments[i].samples[j].sample_buffer.has_sample_data then - -- Shortcuts - local frames = instruments[i].samples[j].sample_buffer.number_of_frames - local n_channels = instruments[i].samples[j].sample_buffer.number_of_channels - local bits_per_sample = instruments[i].samples[j].sample_buffer.bit_depth - -- Calculate the size of the sample - local bytes_in_frame = n_channels * (bits_per_sample / 8) - local size = bytes_in_frame * frames - -- Append to the table - placeholder[i] = placeholder[i] + size - end - end -end - --- Debug: Before --- rprint(placeholder) - --- Bubble Sort - -local num_swaps = 0 -local i = 1 -while( i < total ) do - local j = i + 1 - while( j <= total ) do - if ( placeholder[j] > placeholder[i] ) then - local tmp = placeholder[j] - placeholder[j] = placeholder[i]; - renoise.song():swap_instruments_at(j, i) - placeholder[i] = tmp - num_swaps = num_swaps + 1 - end - j = j + 1; - end - i = i + 1; -end - --- Debug: After --- rprint(placeholder) - --- Alert box -local alert = renoise.app():show_prompt( - 'Bubble Sort Complete', - 'Total number of swaps was: ' .. num_swaps, - {'Ok'} -) -``` \ No newline at end of file diff --git a/docs/guide/keybindings.md b/docs/guide/keybindings.md deleted file mode 100644 index 08524450..00000000 --- a/docs/guide/keybindings.md +++ /dev/null @@ -1,57 +0,0 @@ -# Keybindings - -Tools can add custom key bindings somewhere in Renoise's existing set of bindings, which will be activated and -mapped by the user just as any other key binding in Renoise. - -Keybindings can be global (applied everywhere in the GUI) or can be local to a specific part of the GUI, like the Pattern Editor. - -Please note: there's no way to define default keyboard shortcuts for your entries. Users manually have to bind them in the keyboard prefs pane. As soon as they do, they'll get saved just like any other key binding in Renoise. - -To do so, we are using the tool's [add_keybinding](../API/renoise/renoise.ScriptingTool.md#add_keybinding) function. - -### Example - -```lua -renoise.tool():add_keybinding { - name = "Global:Tools:Example Script Shortcut", - invoke = function(repeated) - if (not repeated) then -- we ignore soft repeated keys here - renoise.app():show_prompt( - "Congrats!", - "You've pressed a magic keyboard combo ".. - "which was defined by a scripting tool.", - {"OK?"} - ) - end - end -} -``` - -### Scopes - -The scope, name and category of the key binding use the form: -`$scope:$topic_name:$binding_name`: - -* `scope` is where the shortcut will be applied, just like those -in the categories list for the keyboard assignment preference pane. -Your key binding will only fire, when the scope is currently focused, -except it's the global scope one. -Using an unavailable scope will not fire an error, instead it will render -the binding useless. It will be listed and mappable, but never be invoked. - -* `topic_name` is useful when grouping entries in the key assignment pane. -Use "tool" if you can't come up with something meaningful. - -* `binding_name` is the name of the binding. - -Currently available scopes are: - -See API Docs for [KeybindingEntry](../API/renoise/renoise.ScriptingTool.md#toolkeybindingentry). - -### Separating entries - -To divide entries into groups (separate entries with a line), prepend one or more dashes to the name, like - -```lua -"--- Main Menu:Tools:My Tool Group Starts Here" -``` \ No newline at end of file diff --git a/docs/guide/menus.md b/docs/guide/menus.md deleted file mode 100644 index a0e9ddea..00000000 --- a/docs/guide/menus.md +++ /dev/null @@ -1,47 +0,0 @@ -# Menu Entries - -You can add new menu entries into any existing context menus or the global menu in Renoise. - -To do so, we are using the tool's [add_menu_entry](../API/renoise/renoise.ScriptingTool.md#add_menu_entry) function. - -### Example - -```lua -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:My Tool:Show Message...", - invoke = function() - renoise.app():show_prompt( - "Congrats!", - "You've pressed then 'Show Message...' menu entry from the tools menu, ".. - "which was defined by a scripting tool.", - {"OK?"} - ) - end -} -``` - -### Avilable Menus - -You can place your entries in any context menu or any window menu in Renoise. To do so, use one of the specified categories in its name. - -See API Docs for [ToolMenuEntry](../API/renoise/renoise.ScriptingTool.md#toolmenuentry) for more info. - -### Separating Entries - -To divide entries into groups (separate entries with a line), prepend one or more dashes to the name, like - -```lua -"--- Main Menu:Tools:My Tool Group Starts Here" -``` - -### Entry Sub Groups - -To move entries into a menu sub groups, use a common path for them, like - -```lua -"Main Menu:Tools:My Tool Group:First Entry" -"Main Menu:Tools:My Tool Group:Second Entry" -"Main Menu:Tools:My Tool Group:Third Entry" -``` - - diff --git a/docs/guide/midi.md b/docs/guide/midi.md index 39747faa..9a604f21 100644 --- a/docs/guide/midi.md +++ b/docs/guide/midi.md @@ -1,19 +1,20 @@ -# Midi +# MIDI -The Renoise API allows you to access raw MIDI input and output devices from within your tool. -You can use this to add bi-directional MIDI controller support, for example. +The Renoise API allows you to access raw MIDI input and output devices from within your tool. You can use this to add features like bi-directional MIDI controller support. -## Midi input listener (function callback) +See the [`renoise.Midi`](../API/renoise/renoise.Midi.md) API for more details. + +## MIDI Input Listener (Function Callback) ```lua --- NOTE: the midi device will be closed when the local variable gets garbage --- collected. Make it global or assign it to something which is held globally --- to avoid that. +-- NOTE: The MIDI device will be closed when this local variable gets garbage +-- collected. Make it global or assign it to a table that is held globally +-- to keep it active. local midi_device = nil local inputs = renoise.Midi.available_input_devices() if not table.is_empty(inputs) then - -- use the first avilable device in this example + -- Use the first available device in this example local device_name = inputs[1] local function midi_callback(message) @@ -26,27 +27,28 @@ if not table.is_empty(inputs) then message[1], message[2], message[3])) end - -- note: sysex callback would be a optional 2nd arg... + -- The sysex callback is an optional second argument. midi_device = renoise.Midi.create_input_device( device_name, midi_callback) - -- stop dumping with 'midi_device:close()' ... + -- To stop listening, call: midi_device:close() end ``` -## Midi input and sysex listener (class callbacks) +## MIDI Input and SysEx Listener (Class Callbacks) ```lua class "MidiDumper" function MidiDumper:__init(device_name) self.device_name = device_name + self.device = nil end function MidiDumper:start() self.device = renoise.Midi.create_input_device( self.device_name, - { self, MidiDumper.midi_callback }, - { MidiDumper.sysex_callback, self } + { self, self.midi_callback }, + { self, self.sysex_callback } ) end @@ -67,25 +69,25 @@ class "MidiDumper" self.device_name, #message)) end --- NOTE: the midi device will be closed when the local variable gets garbage --- collected. Make it global or assign it to something which is held globally --- to avoid that. +-- NOTE: The MIDI device will be closed when this dumper object gets garbage +-- collected. Make it global or assign it to a table that is held globally +-- to keep it active. local midi_dumper = nil local inputs = renoise.Midi.available_input_devices() if not table.is_empty(inputs) then - -- use the first avilable device in this example + -- Use the first available device in this example local device_name = inputs[1] midi_dumper = MidiDumper(device_name) - -- will dump till midi_dumper:stop() is called or the MidiDumber object - -- is garbage collected... + -- This will dump MIDI messages until midi_dumper:stop() is called + -- or the MidiDumper object is garbage collected. midi_dumper:start() end ``` -## Midi output +## MIDI Output ```lua local outputs = renoise.Midi.available_output_devices() @@ -93,12 +95,12 @@ if not table.is_empty(outputs) then local device_name = outputs[1] local midi_device = renoise.Midi.create_output_device(device_name) - -- note on - midi_device:send { 0x90, 0x10, 0x7F } - -- sysex (MMC start) - midi_device:send { 0xF0, 0x7F, 0x00, 0x06, 0x02, 0xF7 } + -- Note On + midi_device:send({ 0x90, 0x10, 0x7F }) + -- SysEx (MMC Start) + midi_device:send({ 0xF0, 0x7F, 0x00, 0x06, 0x02, 0xF7 }) - -- no longer need the device in this example... + -- We no longer need the device in this example, so close it. midi_device:close() end -``` \ No newline at end of file +``` diff --git a/docs/guide/observables.md b/docs/guide/observables.md index 322790ee..960731d0 100644 --- a/docs/guide/observables.md +++ b/docs/guide/observables.md @@ -1,36 +1,39 @@ # Observables -The Renoise API makes extensive use of [the Observer pattern](https://en.wikipedia.org//wiki/Observer_pattern). In short, different values can be wrapped in Observable objects on which you can register notifier functions that will get called whenever the underlying value changes. This is a great way to react to changes without having to deal with constantly comparing the value to a cached state for example. +The Renoise API makes extensive use of the [Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern). In short, many values are wrapped in "Observable" objects. You can register "notifier" functions on these objects, which will be called whenever the underlying value changes. This is a powerful way to react to changes in the application state without constantly polling and comparing values. -When reading the [API](../API/README.md), you will find a lot of fields with `_observable` at the end. Let's see how we can utilize this feature by attaching a notifier so that our tool can do something whenever the user loads a new song. +When browsing the [API documentation](../API/README.md), you will find many properties with an `_observable` suffix. Let's see how to use this feature by attaching a notifier that runs when the user loads a new song. ```lua -local loaded_new_song = function() +local function on_new_document() renoise.app():show_message("Loaded a new song!") end -renoise.tool().app_new_document_observable:add_notifier(loaded_new_song) +-- Get the tool's new_document observable and add our function as a notifier. +renoise.tool().app_new_document_observable:add_notifier(on_new_document) ``` -Try loading a tool with this code inside and open new songs. Whenever you want to attach notifiers to fields on the song, you should do it inside this function to make sure a song is already loaded and that you reattach things when the song changes. To listen to changes on specific values, you usually have to add `_observable` the name of the field and add a notifier to that. +A common pattern is to attach notifiers to song-specific properties inside the `app_new_document_observable` notifier. This ensures that your notifiers are re-attached whenever a new song is loaded. To listen for changes on a specific value, you typically add `_observable` to the property name and add a notifier to it. -Let's extend the previous snippet so that it also fires whenever you change the name of an already loaded song. +Let's extend the previous snippet to also fire a message whenever the name of the song changes. ```lua -local new_name_was_set = function() - renoise.app():show_message("New name was set!\nName: " .. renoise.song().name) +local function on_song_name_changed() + local song_name = renoise.song().name + renoise.app():show_message("New name was set!\nName: " .. song_name) end -local loaded_new_song = function() +local function on_new_document() renoise.app():show_message("Loaded a new song!") - renoise.song().name_observable:add_notifier(new_name_was_set) + -- When a new song is loaded, attach a notifier to its name_observable + renoise.song().name_observable:add_notifier(on_song_name_changed) end -renoise.tool().app_new_document_observable:add_notifier(loaded_new_song) +renoise.tool().app_new_document_observable:add_notifier(on_new_document) ``` -Now try changing the name of the current song inside the first field of the *Song / Song Comments* dialog to see your message pop up. +Now, try changing the song title in the "Song Settings" tab to see your message pop up. -With this technique you can listen to all sorts of things which is very useful when you want your tool to change its behaviour or initialize itself each time the user selects a new instrument, track, sample and so on. +With this technique, you can listen to all sorts of events, which is very useful when you want your tool to react to user actions like selecting a new instrument, track, or sample. -There are different Observables for each primitive type like `ObservableBoolean`, `ObservableNumber` or `ObservableString` and ones that are for storing list of such values (`ObservableBooleanList` etc.). You can check out the entire [Observables API](../API/renoise/renoise.Document.Observable.md) to see them all. +There are different Observables for each primitive type, such as `ObservableBoolean`, `ObservableNumber`, or `ObservableString`, as well as list types like `ObservableBooleanList`. You can explore the entire [Observables API](../API/renoise/renoise.Document.Observable.md) to see them all. diff --git a/docs/guide/osc.md b/docs/guide/osc.md index 7344d188..a2fb1703 100644 --- a/docs/guide/osc.md +++ b/docs/guide/osc.md @@ -1,20 +1,22 @@ -# Osc +# OSC -The Renoise API allows you to create web sockets and provides tools to receive and send OSC data. This allows you to connect your tools to other OSC servers and send OSC data to existing clients. +The Renoise API allows you to create sockets and provides tools to send and receive Open Sound Control (OSC) data. This enables you to connect your tools to other OSC servers and clients, offering an alternative to MIDI for controlling and interacting with devices like a [monome](https://monome.org/docs/serialosc/osc). -In general, this can be used as an alternative to MIDI, e.g. to connect to OSC-enabled devices such as [monome](https://monome.org/docs/serialosc/osc). +See the [`renoise.Osc`](../API/renoise/renoise.Osc.md) and [`renoise.Socket`](../API/renoise/renoise.Socket.md) APIs for more details. -> [!NOTE] -> Using TCP instead of UDP as the socket protocol would likely also require manual [SLIP encoding/decoding](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol) of OSC message data. This is omitted here, so the examples below will only work with UDP servers/clients. +> [!NOTE] +> Using TCP instead of UDP as the socket protocol would likely require manual [SLIP encoding/decoding](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol) of OSC message data. This is not handled automatically, so the examples below will only work with UDP servers/clients. -## Osc Server (receive Osc from one or more Clients) +## OSC Server (Receiving OSC) + +This example creates a UDP server that listens for OSC messages on port 8008. ```lua --- create some shortcuts +-- Create some shortcuts local OscMessage = renoise.Osc.Message local OscBundle = renoise.Osc.Bundle --- open a socket connection to the server +-- Open a socket connection to listen for messages local server, socket_error = renoise.Socket.create_server( "localhost", 8008, renoise.Socket.PROTOCOL_UDP) @@ -26,52 +28,45 @@ end server:run { socket_message = function(socket, data) - -- decode the data to Osc + -- Decode the binary data to an OSC message or bundle local message_or_bundle, osc_error = renoise.Osc.from_binary_data(data) - -- show what we've got + -- Show what we've got if (message_or_bundle) then if (type(message_or_bundle) == "Message") then print(("Got OSC message: '%s'"):format(tostring(message_or_bundle))) elseif (type(message_or_bundle) == "Bundle") then print(("Got OSC bundle: '%s'"):format(tostring(message_or_bundle))) - - else - -- never will get in here end + -- Send a reply back to the client + local reply_message = OscMessage("/renoise/reply", { + { tag = "s", value = "Thank you for the message!" } + }) + socket:send(reply_message:to_binary_data()) + else print(("Got invalid OSC data, or data which is not " .. "OSC data at all. Error: '%s'"):format(osc_error)) end - - socket:send(("%s:%d: Thank you so much for the OSC message. " .. - "Here's one in return:"):format(socket.peer_address, socket.peer_port)) - - -- open a socket connection to the client - local client, socket_error = renoise.Socket.create_client( - socket.peer_address, socket.peer_port, renoise.Socket.PROTOCOL_UDP) - - if (not socket_error) then - client:send(OscMessage("/flowers")) - end end } --- shut off the server at any time with: +-- To shut down the server at any time, call: -- server:close() ``` +## OSC Client (Sending OSC) -## Osc Client & Message Construction (send Osc to a Server) +This example creates a UDP client to send OSC messages to a server on port 8008. ```lua --- create some shortcuts +-- Create some shortcuts local OscMessage = renoise.Osc.Message local OscBundle = renoise.Osc.Bundle --- open a socket connection to the server +-- Create a client to send messages to the server local client, socket_error = renoise.Socket.create_client( "localhost", 8008, renoise.Socket.PROTOCOL_UDP) @@ -81,30 +76,29 @@ if (socket_error) then return end --- construct and send messages +-- Construct and send a simple message client:send( - OscMessage("/someone/transport/start") + OscMessage("/transport/start"):to_binary_data() ) +-- Construct and send a message with arguments client:send( - OscMessage("/someone/transport/bpm", { - {tag="f", value=127.5} - }) -) - --- construct and send bundles -client:send( - OscBundle(os.clock(), OscMessage("/someone/transport/start")) + OscMessage("/transport/bpm", { + { tag = "f", value = 127.5 } + }):to_binary_data() ) +-- Construct and send a bundle of messages local message1 = OscMessage("/some/message") - local message2 = OscMessage("/another/one", { - {tag="b", value="with some blob data"}, - {tag="s", value="and a string"} + { tag = "b", value = "with some blob data" }, + { tag = "s", value = "and a string" } }) client:send( - OscBundle(os.clock(), {message1, message2}) + OscBundle(os.clock(), { message1, message2 }):to_binary_data() ) -``` \ No newline at end of file + +-- Close the client when done +client:close() +``` diff --git a/docs/guide/pattern_iterator.md b/docs/guide/pattern_iterator.md deleted file mode 100644 index 2e03aedc..00000000 --- a/docs/guide/pattern_iterator.md +++ /dev/null @@ -1,121 +0,0 @@ -# Pattern Iterator - -As a quick and efficient way to access the pattern data in phrases and the Renoise song, you can use the existing pattern iterators. Here are a few examples of how to use them. - -See also API docs for [renoise.PatternIterator](../API/renoise/renoise.PatternIterator.md). - -## Change notes in selection - -changes all "C-4"s to "E-4" in the selection in the current pattern - -```lua -local pattern_iter = renoise.song().pattern_iterator -local pattern_index = renoise.song().selected_pattern_index - -for pos,line in pattern_iter:lines_in_pattern(pattern_index) do - for _,note_column in pairs(line.note_columns) do - if (note_column.is_selected and - note_column.note_string == "C-4") then - note_column.note_string = "E-4" - end - end -end -``` - -## Generate a simple arp sequence - -... repeating in the current pattern & track from line 0 to the pattern end - -```lua -local pattern_iter = renoise.song().pattern_iterator - -local pattern_index = renoise.song().selected_pattern_index -local track_index = renoise.song().selected_track_index -local instrument_index = renoise.song().selected_instrument_index - -local EMPTY_VOLUME = renoise.PatternLine.EMPTY_VOLUME -local EMPTY_INSTRUMENT = renoise.PatternLine.EMPTY_INSTRUMENT - -local arp_sequence = { - {note="C-4", instrument = instrument_index, volume = 0x20}, - {note="E-4", instrument = instrument_index, volume = 0x40}, - {note="G-4", instrument = instrument_index, volume = 0x80}, - {note="OFF", instrument = EMPTY_INSTRUMENT, volume = EMPTY_VOLUME}, - {note="G-4", instrument = instrument_index, volume = EMPTY_VOLUME}, - {note="---", instrument = EMPTY_INSTRUMENT, volume = EMPTY_VOLUME}, - {note="E-4", instrument = instrument_index, volume = 0x40}, - {note="C-4", instrument = instrument_index, volume = 0x20}, -} - -for pos,line in pattern_iter:lines_in_pattern_track(pattern_index, track_index) do - if not table.is_empty(line.note_columns) then - - local note_column = line:note_column(1) - note_column:clear() - - local arp_index = math.mod(pos.line - 1, #arp_sequence) + 1 - note_column.note_string = arp_sequence[arp_index].note - note_column.instrument_value = arp_sequence[arp_index].instrument - note_column.volume_value = arp_sequence[arp_index].volume - end -end -``` - -## Hide empty volume, panning, and delay colums - -```lua -for track_index, track in pairs(renoise.song().tracks) do - -- Set some bools - local found_volume = false - local found_panning = false - local found_delay = false - local found_sample_effects = false - -- Check whether or not this is a regular track - if - track.type ~= renoise.Track.TRACK_TYPE_MASTER and - track.type ~= renoise.Track.TRACK_TYPE_SEND - then - -- Iterate through the regular track - local iter = renoise.song().pattern_iterator:lines_in_track(track_index) - for _,line in iter do - -- Check whether or not the line is empty - if not line.is_empty then - -- Check each column on the line - for _,note_column in ipairs(line.note_columns) do - -- Check for volume - if note_column.volume_value ~= renoise.PatternLine.EMPTY_VOLUME then - found_volume = true - end - -- Check for panning - if note_column.panning_value ~= renoise.PatternLine.EMPTY_PANNING then - found_panning = true - end - -- Check for delay - if note_column.delay_value ~= renoise.PatternLine.EMPTY_DELAY then - found_delay = true - end - -- Check for sample effects - if note_column.effect_number_value ~= renoise.PatternLine.EMPTY_EFFECT_NUMBER then - found_sample_effects = true - end - if note_column.effect_amount_value ~= renoise.PatternLine.EMPTY_EFFECT_AMOUNT then - found_sample_effects = true - end - - end - -- If we found something in all three vol, pan, and del - -- Then there's no point in continuing down the rest of the track - -- We break this loop and move on to the next track - if found_volume and found_panning and found_delay and found_sample_effects then - break - end - end - end - -- Set some properties - track.volume_column_visible = found_volume - track.panning_column_visible = found_panning - track.delay_column_visible = found_delay - track.sample_effects_column_visible = found_sample_effects - end -end -``` \ No newline at end of file diff --git a/docs/guide/preferences.md b/docs/guide/preferences.md deleted file mode 100644 index 76b87685..00000000 --- a/docs/guide/preferences.md +++ /dev/null @@ -1,159 +0,0 @@ -# Preferences - -Tools can have preferences just like Renoise. To use them we first need to create a renoise.Document object which holds the options that we want to store and restore. - -Documents in Renoise have all of their fields defined as an Observable type. This comes extra handy when you want to create some settings dialog that needs to be able change the behaviour of your tool and remember its state, while you also want to access these settings across your tool. By using the built-in Document API you get a lot of this functionality for free. - -Let's see an example of setting up an `options` object that can be used for the above things. - -Our goal here is to have three kinds of settings managed by the Document class and a dialog that can be used to change them. The tool will be able to randomize the song by changing BPM and creating a random number of tracks. - -We will also define a menu entry for opening our tool settings dialog, you can read more about menu entries in the [Menus](menus.md) guide, graphical dialogs are further discussed in [Views](views.md). - -```lua --- We are creating a new renoise Document by supplying a table of values. --- It has three fields, which will all get wrapped in an Observable --- * a boolean for whether or not the tools should randomize the BPM --- * another boolean for randomizing tracks --- * an integer representing how many tracks we want to have at maximum -local options = renoise.Document.create("RandomizerToolPreferences") { - randomize_bpm = true, - randomize_tracks = false, - max_tracks = 16 -} - --- once we have our options, we have to assign it to our tool -renoise.tool().preferences = options - --- we define a randomizer function --- when called, it will set a random BPM --- and add or remove tracks randomly -function randomize_song() - local song = renoise.song() - -- make sure you use .value when accessing the underlying value inside Observables - if options.randomize_bpm.value then - -- we are setting the BPM to a value between 60 and 180 - song.transport.bpm = 60 + math.random() * 120 - end - - if options.randomize_tracks.value then - -- let's figure out how many tracks we want based on the max_tracks option - local target_count = 1 + math.floor(math.random() * options.max_tracks.value) - - -- and cache the amount of regular tracks the song has - local current_count = song.sequencer_track_count - - -- we will either insert new tracks if there aren't enough - if current_count < target_count then - for i = 1, target_count - current_count do - song:insert_track_at(current_count) - end - else - -- or remove them if there is too much - for i = 1, current_count - target_count do - song:delete_track_at(song.sequencer_track_count) - end - end - end -end - --- let's define a function for a custom dialog --- it will contain checkboxes and a slider for our options -function show_options() - local vb = renoise.ViewBuilder() - - local dialog_content = vb:vertical_aligner { - margin = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN, - - vb:row { - vb:text { - text = "Randomize BPM" - }, - -- here we are binding our observable value to this checkbox - vb:checkbox { - bind = options.randomize_bpm - } - }, - vb:row { - vb:text { - text = "Randomize Tracks" - }, - -- the same thing for the boolean for tracks - vb:checkbox { - bind = options.randomize_tracks - } - }, - vb:row { - vb:text { - text = "Max Tracks" - }, - -- for the maximum tracks we create a value box - -- and restrict it to a range of [1..16] - vb:valuebox { - min = 1, - max = 16, - bind = options.max_tracks - } - }, - -- add a button that will execute the randomization based on our options - vb:row { - vb:button { - text = "Randomize", - pressed = randomize_song - } - } - } - renoise.app():show_custom_dialog( - "Randomizer Options", dialog_content - ) -end - --- finally we add a menu entry to open our options dialog -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Randomizer Options", - invoke = show_options -} - -``` - -As you can see all we had to do was to assign our observables to the `bind` field on the checkboxes and valuebox, Renoise will take care of updating our settings when the view changes and vice versa. - -Of course you could also use observables this way without them being included in your settings, but this is the most common usage pattern for them. - -## preferences.xml - -When you assign the preferences, Renoise will take care of saving and loading your settings. Your tool will have a `preferences.xml` file created in its folder with the values from your options table. As long as you are using simple types, you don't have to worry about (de)serializing values. - -Try restarting Renoise to see that the values you've set in your dialog will persist over different sessions. - -## Complex Documents - -For more complex applications (or if you just prefer doing things the Object-Oriented way) you can also inherit from `renoise.Document.DocumentNode` and register properties in the constructor. - -You could change the above Document creation to something like this: - -```lua ----@class RandomizerToolPreferences : renoise.Document.DocumentNode ----@field randomize_bpm renoise.Document.ObservableBoolean ----@field randomize_tracks renoise.Document.ObservableBoolean ----@field max_tracks renoise.Document.ObservableNumber -class "RandomizerToolPreferences" (renoise.Document.DocumentNode) - -function RandomizerToolPreferences:__init() - renoise.Document.DocumentNode.__init(self) - -- register an observable properties which will make up our Document - self:add_property("randomize_bpm", true) - self:add_property("randomize_tracks", false) - self:add_property("max_tracks", 16) -end - ----@type RandomizerToolPreferences -local options = RandomizerToolPreferences() - -renoise.tool().preferences = options -``` - -This allows you to create more complex documents. Have a look at the complete [Document API](../API/renoise/renoise.Document.md) for more info and details about what else you can load/store this way. - -> [!NOTE] -> This time we also included type annotations (like `---@class RandomizerToolPreferences`). These can help you with development but they aren't strictly necessary. You can read more about how to use them at the [LuaLS website](https://luals.github.io/). diff --git a/docs/guide/sample_buffer.md b/docs/guide/sample_buffer.md deleted file mode 100644 index fa35c5eb..00000000 --- a/docs/guide/sample_buffer.md +++ /dev/null @@ -1,72 +0,0 @@ -# SampleBuffer - -## Modify the selected sample - -```lua -local sample_buffer = renoise.song().selected_sample.sample_buffer - --- check if sample data is preset at all first -if (sample_buffer.has_sample_data) then - - -- before touching any sample, let renoise create undo data, when necessary - sample_buffer:prepare_sample_data_changes() - - -- modify sample data in the selection (defaults to the whole sample) - for channel = 1, sample_buffer.number_of_channels do - for frame = sample_buffer.selection_start, sample_buffer.selection_end do - local value = sample_buffer:sample_data(channel, frame) - value = -value -- do something with the value - sample_buffer:set_sample_data(channel, frame, value) - end - end - - -- let renoise update sample overviews and caches. apply bit depth - -- quantization. create undo/redo data if needed... - sample_buffer:finalize_sample_data_changes() - -else - renoise.app():show_warning("No sample preset...") -end -``` - -## Generate a new sample - -```lua -local selected_sample = renoise.song().selected_sample -local sample_buffer = selected_sample.sample_buffer - --- create new or overwrite sample data for our sound: -local sample_rate = 44100 -local num_channels = 1 -local bit_depth = 32 -local num_frames = sample_rate / 2 - -local allocation_succeeded = sample_buffer:create_sample_data( - sample_rate, bit_depth, num_channels, num_frames) - --- check for allocation failures -if (not allocation_succeeded) then - renoise.app():show_error("Out of memory. Failed to allocate sample data") - return -end - --- let renoise know we are about to change the sample buffer -sample_buffer:prepare_sample_data_changes() - --- fill in the sample data with an amazing zapp sound -for channel = 1,num_channels do - for frame = 1,num_frames do - local sample_value = math.sin(num_frames / frame) - sample_buffer:set_sample_data(channel, frame, sample_value) - end -end - --- let renoise update sample overviews and caches. apply bit depth --- quantization. finalize data for undo/redo, when needed... -sample_buffer:finalize_sample_data_changes() - --- setup a pingpong loop for our new sample -selected_sample.loop_mode = renoise.Sample.LOOP_MODE_PING_PONG -selected_sample.loop_start = 1 -selected_sample.loop_end = num_frames -``` \ No newline at end of file diff --git a/docs/guide/sockets.md b/docs/guide/sockets.md index aafada53..f5e6e6c4 100644 --- a/docs/guide/sockets.md +++ b/docs/guide/sockets.md @@ -1,41 +1,45 @@ # Sockets -The Renoise API allows you to create [network sockets](https://en.wikipedia.org/wiki/Network_socket). This can be used to communicate with other devices via UDP and TCP, e.g. to send or receive [OSC messages](./osc.md). +The Renoise API allows you to create [network sockets](https://en.wikipedia.org/wiki/Network_socket). This can be used to communicate with other devices and applications via UDP and TCP, for example, to send or receive [OSC messages](./osc.md). + +See the [`renoise.Socket`](../API/renoise/renoise.Socket.md) API for more details. > [!NOTE] -> There's no support for encrypted connections. So using protocols like HTTPs is not easily possible with the socket API in Renoise. +> There is no built-in support for encrypted connections. Therefore, using protocols like HTTPS is not directly possible with the socket API in Renoise. -## HTTP / GET client +## HTTP GET Client -Creates a TCP socket and connect it to www.wurst.de, http, giving up the connection attempt after 2 seconds. +This example creates a TCP socket, connects to a web server, and sends a simple HTTP GET request. ```lua +-- Connection will give up after 2 seconds local connection_timeout = 2000 local client, socket_error = renoise.Socket.create_client( - "www.wurst.de", 80, renoise.Socket.PROTOCOL_TCP, connection_timeout) + "www.renoise.com", 80, renoise.Socket.PROTOCOL_TCP, connection_timeout) if socket_error then - renoise.app():show_warning(socket_error) - return + renoise.app():show_warning(socket_error) + return end --- request something +-- Request the root document local succeeded, socket_error = - client:send("GET / HTTP/1.0\n\n") + client:send("GET / HTTP/1.0\r\nHost: www.renoise.com\r\n\r\n") if (socket_error) then - renoise.app():show_warning(socket_error) - return + renoise.app():show_warning(socket_error) + return end --- loop until we get no more data from the server. --- note: this is a silly example. we should check the HTTP --- header here and stop after receiveing "Content-Length" +-- Loop until we get no more data from the server. +-- Note: A robust implementation should parse the HTTP header +-- and use the "Content-Length" to determine when to stop. local receive_succeeded = false local receive_content = "" while (true) do + -- Timeout for receiving data is 500ms local receive_timeout = 500 local message, socket_error = @@ -43,40 +47,39 @@ while (true) do if (message) then receive_content = receive_content .. message .. "\n" - else if (socket_error == "timeout" or socket_error == "disconnected") then - -- could retry here on timeout. we just stop in this example... + -- Could retry on timeout, but we'll just stop in this example. receive_succeeded = true break else renoise.app():show_warning( - "'socket reveive' failed with the error: " .. socket_error) + "'socket receive' failed with the error: " .. socket_error) break end end end --- close the connection if it was not closed by the server +-- Close the connection if it was not already closed by the server if (client and client.is_open) then client:close() end --- show what we've got +-- Show what we've got if (receive_succeeded and #receive_content > 0) then - renoise.app():show_prompt( - "GET / HTTP/1.0 response", - receive_content, - {"OK"} - ) + renoise.app():show_prompt( + "HTTP GET Response", + receive_content, + {"OK"} + ) else - renoise.app():show_prompt( - "GET / HTTP/1.0 response", - "Socket receive timeout.", - {"OK"} - ) + renoise.app():show_prompt( + "HTTP GET Response", + "Socket receive timeout or no content.", + {"OK"} + ) end ``` @@ -87,7 +90,7 @@ local server, socket_error = renoise.Socket.create_server( "localhost", 1025, renoise.Socket.PROTOCOL_UDP) if socket_error then - app:show_warning( + renoise.app():show_warning( "Failed to start the echo server: " .. socket_error) else server:run { @@ -107,32 +110,33 @@ else socket_message = function(socket, message) print(("client %s:%d sent '%s'"):format( socket.peer_address, socket.peer_port, message)) - -- simply sent the message back + -- Simply send the message back socket:send(message) end } end --- will run and echo as long as the script runs... +-- This server will run and echo messages as long as the script is active. ``` ## Echo TCP Server (using a class as notifier) -...and allowing any addresses to connect by not specifying an address: +This example allows any address to connect by not specifying an address in `create_server`. ```lua class "EchoServer" function EchoServer:__init(port) - -- create a server socket - local server, socket_error = renoise.Socket.create_server(port) + -- Create a server socket + local server, socket_error = renoise.Socket.create_server( + "localhost", port, renoise.Socket.PROTOCOL_TCP) - if socket_error then - app:show_warning( - "Failed to start the echo server: " .. socket_error) - else - -- start running - self.server = server - self.server:run(self) - end + if socket_error then + renoise.app():show_warning( + "Failed to start the echo server: " .. socket_error) + else + -- Start running + self.server = server + self.server:run(self) + end end ---@param socket_error string @@ -151,13 +155,13 @@ class "EchoServer" function EchoServer:socket_message(socket, message) print(("client %s:%d sent '%s'"):format( socket.peer_address, socket.peer_port, message)) - -- simply sent the message back + -- Simply send the message back socket:send(message) end --- create and run the echo server on port 1025 +-- Create and run the echo server on port 1025 local echo_server = EchoServer(1025) --- will run and echo as long as the script runs or the EchoServer --- object is garbage collected... -``` \ No newline at end of file +-- The server will run as long as the script is active or the +-- echo_server object is garbage collected. +``` diff --git a/docs/guide/song.md b/docs/guide/song.md new file mode 100644 index 00000000..db669ca0 --- /dev/null +++ b/docs/guide/song.md @@ -0,0 +1,400 @@ +# Renoise Song + +The `renoise.song()` function is the main entry point for scripting in Renoise. It returns a [`renoise.Song`](../API/renoise/renoise.Song.md) object that represents the entire project currently loaded in the application. + +Here is a simplified tree view of the song object model: + +``` +renoise.song() +├── transport (BPM, LPB, playback control) +├── tracks[] (List of all tracks in the song) +│ ├── devices[] +│ │ └── parameters[] +│ └── ... +├── instruments[] (List of all instruments) +│ ├── samples[] +│ │ └── sample_buffer +│ └── ... +├── patterns[] (The pool of all available patterns) +│ └── tracks[] +│ ├── lines[] +│ │ ├── note_columns[] +│ │ └── ... +│ └── automation[] +├── sequencer (The pattern sequence matrix) +│ └── pattern_sequence[] +└── selected_track (And other `selected_...` properties) +``` + +Let's look at some important components in more detail. + +## Transport + +The [`renoise.Transport`](../API/renoise/renoise.Transport.md) object controls global song properties related to timing and playback. + +```lua +local song = renoise.song() +local transport = song.transport + +-- Read properties +print("Current BPM: " .. transport.bpm) +print("Current LinesPerBeat: " .. transport.lpb) + +-- Change properties +transport.bpm = 140 + +-- Start playback +if not transport.playing then + transport:start(renoise.Transport.PLAYMODE_RESTART_PATTERN) +end +``` + +## Tracks + +The `renoise.song().tracks` property is a list of all tracks in the song, including sequencer tracks, group tracks, send tracks, the master track. Each [`renoise.Track`](../API/renoise/renoise.Track.md) has its own device chain and other properties. + +```lua +local song = renoise.song() + +-- Iterate over all tracks +for _, track in ipairs(song.tracks) do + -- Check the track type + if track.type == renoise.Track.TRACK_TYPE_SEQUENCER then + print("Sequencer Track: " .. track.name) + -- Access the track's device chain + local devices = track.devices + print(" - Devices: " .. #devices) + end +end + +-- Access a specific track by its index (1-based) +local first_track = song.tracks[1] +first_track.name = "New Name" -- Set the track's name +``` + +### Track Devices and Parameters + +Once you have a device chain, you can iterate over its devices [`renoise.AudioDevice`](../API/renoise/renoise.AudioDevice.md) and parameters [`renoise.DeviceParameter`](../API/renoise/renoise.DeviceParameter.md). The first device in a track's chain is always the "Mixer" device, which contains the track's built-in parameters like volume and panning. + +```lua +local selected_track = renoise.song().selected_track +local mixer_device = selected_track.devices[1] + +print("Parameters for '" .. mixer_device.display_name .. "':") + +for _, param in ipairs(mixer_device.parameters) do + print(string.format(" - %s: %s", param.name, param.value_string)) +end +``` + +### Modifying Parameter Values + +You can read and write a parameter's value using its `.value` (a number from 0.0 to 1.0) or `.value_string` (a formatted string like "1.000 dB") properties. + +Also, the Mixer device properties can also be accessed directly from the track object. + +```lua +local selected_track = renoise.song().selected_track + +-- Access a parameter by its property name on the track object +local pre_volume = selected_track.prefx_volume +print("Pre-Mixer Volume is: " .. pre_volume.value_string) + +-- Set the value using a string +pre_volume.value_string = "1.0 dB" +-- Note: When reading the value back, the string may be formatted differently +assert(pre_volume.value_string == "1.000 dB") + +-- Set the value using a normalized number +local pre_width = selected_track.prefx_width +pre_width.value = 1.0 -- 100% wide +assert(pre_width.value == 1.0) +``` + +### Adding, Removing, and Swapping Devices + +You can dynamically manage the devices in a chain. To add a device, you need its identifier path, which you can query via `track.available_devices`. + +```lua +local track = renoise.song().selected_track + +print("Available devices:") +-- `rprint` is a Renoise extension which also pretty prints tables +rprint(track.available_devices) + +-- Get a random device path (excluding plugins to avoid popups) +local device_path +repeat + device_path = track.available_devices[ + math.random(1, #track.available_devices)] +until device_path:find("Native/") + +-- Insert the device at the end of the chain +local device_count = #track.devices +local new_device = track:insert_device_at( + device_path, device_count + 1) +assert(#track.devices == device_count + 1) +print("Added device: " .. new_device.display_name) + +-- Insert another one +track:insert_device_at(device_path, #track.devices + 1) + +-- Swap the last two devices +track:swap_devices_at(#track.devices, #track.devices - 1) +print("Swapped the last two devices.") + +-- Remove the last device +track:delete_device_at(#track.devices) +print("Removed the last added device.") +``` + +### PatternTrack Lines + +A [`renoise.PatternTrack`](../API/renoise/renoise.PatternTrack.md) holds pattern lines and automations for a single track in a single pattern. + +The following example writes a `C-4` note in the first pattern's track. + +```lua +local song = renoise.song() + +-- Get the first pattern in the song +local pattern = song.patterns[1] + +-- Get the first pattern track within that pattern +local pattern_track = pattern.tracks[1] + +-- Access a specific line (1-based) +local line = pattern_track:line(1) + +-- Access the first note column in that line +local note_column = line.note_columns[1] +if note_column then + -- Set a C-4 note + note_column.note_string = "C-4" +end +``` + +For efficiently iterating over pattern data, it's recommended to use the [`renoise.PatternIterator`](../API/renoise/renoise.PatternIterator.md). + +This example changes all `C-4` notes to `E-4` within the *current selection* in the pattern editor. + +```lua +local song = renoise.song() +local pattern_iter = song.pattern_iterator +local pattern_index = song.selected_pattern_index + +for pos,line in pattern_iter:lines_in_pattern(pattern_index) do + for _,note_column in ipairs(line.note_columns) do + if (note_column.is_selected and + note_column.note_string == "C-4") then + note_column.note_string = "E-4" + end + end +end +``` + +### PatternTrack Automation + +A [`renoise.PatternTrackAutomation`](../API/renoise/renoise.PatternTrackAutomation.md) automates track device parameters. + +This example accesses the automation for the parameter currently selected in the "Automation" tab in Renoise. + +```lua +local song = renoise.song() +local selected_parameter = song.selected_automation_parameter +local selected_pattern_track = song.selected_pattern_track + +-- Is a parameter selected? +if selected_parameter then + local automation = selected_pattern_track:find_automation( + selected_parameter) + + -- Check if automation for the selected parameter already exists + if not automation then + -- If not, create it for the current pattern/track + automation = selected_pattern_track:create_automation( + selected_parameter) + end + + ---- Do something with the automation ---- + + -- Iterate over all existing automation points + for _,point in ipairs(automation.points) do + print(("track automation: time=%s, value=%s"):format( + point.time, point.value)) + end + + -- Clear all points + automation.points = {} + + -- Insert a single new point at line 2 + automation:add_point_at(2, 0.5) + -- Change its value if it already exists + automation:add_point_at(2, 0.8) + -- Remove it again (a point must exist at this time) + automation:remove_point_at(2) + + -- Batch creation/insertion of points + local new_points = {} + for i=1, #selected_pattern_track.lines do + table.insert(new_points, { + time = i, + value = i / automation.length + }) + end + + -- Assign them (note: new_points must be sorted by time) + automation.points = new_points + + -- Change the automation's interpolation mode + automation.playmode = + renoise.PatternTrackAutomation.PLAYMODE_POINTS +end +``` + +## Instruments + +The `renoise.song().instruments` property contains a list of all instruments. An [`renoise.Instrument`](../API/renoise/renoise.Instrument.md) may contain phrases, midi in/out properties, plugin devices, samples, sample modulation, and sample DSP FX chains. + +```lua +local song = renoise.song() + +-- Get the selected instrument +local instrument = song.selected_instrument +if instrument then + print("Selected instrument: " .. instrument.name) + + -- Access its samples + if #instrument.samples > 0 then + print(" - It has " .. #instrument.samples .. " samples.") + local first_sample = instrument.samples[1] + print(" - First sample name: " .. first_sample.name) + end +end +``` + +### Samples + +The [`renoise.SampleBuffer`](../API/renoise/renoise.SampleBuffer.md) object provides low-level access to the audio data of a sample. + +This example inverts the phase of the selected sample data. + +```lua +local sample = renoise.song().selected_sample +if not sample then + print("No sample selected") + return +end + +local sample_buffer = sample.sample_buffer +if not sample_buffer.has_sample_data then + print("No sample buffer present") + return +end + +-- Before modifying sample data, let Renoise prepare for undo/redo actions +sample_buffer:prepare_sample_data_changes() + +-- Modify sample data in the selection (defaults to the whole sample) +for channel = 1, sample_buffer.number_of_channels do + for frame = sample_buffer.selection_start, sample_buffer.selection_end do + local value = sample_buffer:sample_data(channel, frame) + value = -value -- Invert the sample value + sample_buffer:set_sample_data(channel, frame, value) + end +end + +-- Let Renoise know the changes are done. This updates UI overviews, +-- applies bit-depth quantization, and finalizes the undo/redo data. +sample_buffer:finalize_sample_data_changes() +``` + +This example creates a new sample from scratch and generates a simple sine wave. + +```lua +local selected_sample = renoise.song().selected_sample +if not selected_sample then return end + +local sample_buffer = selected_sample.sample_buffer + +-- Define properties for the new sample data +local sample_rate = 44100 +local num_channels = 1 +local bit_depth = 32 +local num_frames = sample_rate / 2 -- half a second + +-- Create new or overwrite existing sample data +local allocation_succeeded = sample_buffer:create_sample_data( + sample_rate, bit_depth, num_channels, num_frames) + +-- Check for allocation failures +if not allocation_succeeded then + renoise.app():show_error("Out of memory. Failed to allocate sample data.") + return +end + +-- Let Renoise know we are about to change the sample buffer +sample_buffer:prepare_sample_data_changes() + +-- Fill the sample data with a sine wave +for frame = 1, num_frames do + -- We only have one channel, so we use 1 + local sample_value = math.sin((frame / num_frames) * math.pi * 2) + sample_buffer:set_sample_data(1, frame, sample_value) +end + +-- Finalize the changes +sample_buffer:finalize_sample_data_changes() + +-- Set up a ping-pong loop for our new sample +selected_sample.loop_mode = renoise.Sample.LOOP_MODE_PING_PONG +selected_sample.loop_start = 1 +selected_sample.loop_end = num_frames +``` + +## Sequencer + +The [`renoise.PatternSequencer`](../API/renoise/renoise.PatternSequencer.md) manages the arrangement of patterns in the song. + +The `pattern_sequence` property is a list of pattern indices that defines the playback order. + +```lua +local song = renoise.song() +local sequencer = song.sequencer + +print("Song sequence:") +for position, pattern_index in ipairs(sequencer.pattern_sequence) do + print(string.format(" Position %d: Pattern %d", position, pattern_index)) +end + +-- Set a new sequence +sequencer.pattern_sequence = { 1, 1 } + +-- Change the sequence: make the second slot play pattern 2 +sequencer:set_pattern(2, 2) + +-- Add a new slot at the end of the sequence, playing pattern 3 +sequencer:insert_sequence_at(#sequencer.pattern_sequence + 1, 3) +``` + +## Selected Elements + +The song object also provides convenient properties to directly access elements that are currently selected in the Renoise user interface. This is very useful for creating tools that operate on the user's current context. + +```lua +local song = renoise.song() + +-- Get the currently selected track object +local selected_track = song.selected_track +print("Selected track: " .. selected_track.name) + +-- Get the index of the selected pattern +local selected_pattern_index = song.selected_pattern_index +print("Selected pattern index: " .. selected_pattern_index) + +-- Get the selected device in a track's device chain +local selected_device = song.selected_track_device +if selected_device then + print("Selected device: " .. selected_device.display_name) +end +``` \ No newline at end of file diff --git a/docs/guide/sqlite.md b/docs/guide/sqlite.md new file mode 100644 index 00000000..be85949e --- /dev/null +++ b/docs/guide/sqlite.md @@ -0,0 +1,36 @@ +# SQLite Databases + +The Renoise API allows you to create or load [SQLite databases](https://sqlite.org). This can be used to either efficiently deal with large data blobs within your tools or to read existing database files from other applications. + +See [`renoise.SQLite`](../API/renoise/renoise.SQLite.md) for more info. + +A quick example on how to open and read from an existing database file: + +```lua +-- create a new database (rwc = read/write/create) +local db, status, error = renoise.SQLite.open("./some_test.db", "rwc") +-- NB: use renoise.SQLite.open() to create a in-memory db instead +print("Create:", db.is_open, db.error_code, db.error_message) + +local sql = [[ + CREATE TABLE numbers(num1,num2,str); + INSERT INTO numbers VALUES(1,11,"ABC"); + INSERT INTO numbers VALUES(2,22,"DEF"); + INSERT INTO numbers VALUES(3,33,"UVW"); + INSERT INTO numbers VALUES(4,44,"XYZ"); +]] + +print("Exec:", db:execute(sql)) +print("Changes:", db.changes, db.total_changes, db.error_message) + +-- read from an existing db using a prepared statement +local db, status, error = renoise.SQLite.open("./test.db", "ro") -- read-only +print("Open:", db.is_open, db.error_code, db.error_message) + +local stm = db:prepare("SELECT * from numbers") +print("Read:", stm.columns, stm.unames) + +for k in stm:rows() do + rprint(k) +end +``` \ No newline at end of file diff --git a/docs/guide/tool.md b/docs/guide/tool.md new file mode 100644 index 00000000..4cac880a --- /dev/null +++ b/docs/guide/tool.md @@ -0,0 +1,535 @@ +# Renoise Tool + +The `renoise.tool()` function is the entry point for interacting with your tool's own context. It returns a [`renoise.ScriptingTool`](../API/renoise/renoise.ScriptingTool.md) object, which allows you to integrate your tool with Renoise by adding menu entries, keybindings, and MIDI mappings. It also provides ways to handle application-wide events, manage timers, define preferences, and much more. + +## Menu Entries + +You can add new menu entries into any existing context menu or the main application menu in Renoise. + +To do so, use the tool's [`renoise.tool():add_menu_entry`](../API/renoise/renoise.ScriptingTool.md#add_menu_entry) function. + +### Example + +```lua +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:My Tool:Show Message...", + invoke = function() + renoise.app():show_prompt( + "Congrats!", + "You've pressed the 'Show Message...' menu entry from the tools menu, " .. + "which was defined by a scripting tool.", + {"OK?"} + ) + end +} +``` + +### Available Menus + +You can place your entries in any context menu or window menu in Renoise. To do so, specify the target menu category in the `name` property. + +For a complete list of available menu locations, see the API documentation for [`ToolMenuEntry`](../API/renoise/renoise.ScriptingTool.md#toolmenuentry). + +### Separating Entries + +To divide entries into groups with a separating line, prepend one or more dashes to the `name`, like so: + +```lua +name = "--- Main Menu:Tools:My Tool Group Starts Here" +``` + +### Entry Sub-Groups + +To group entries into a sub-menu, use a common path for them in the `name` property: + +```lua +"Main Menu:Tools:My Tool Group:First Entry" +"Main Menu:Tools:My Tool Group:Second Entry" +"Main Menu:Tools:My Tool Group:Third Entry" +``` + +## Keybindings + +Tools can add custom key bindings to Renoise's existing set of key commands. These new bindings can be activated and mapped by the user just like any other key binding in Renoise. + +Keybindings can be global (applied everywhere in the GUI) or local to a specific part of the GUI, like the Pattern Editor. + +> [!NOTE] +> There is no way to define default keyboard shortcuts for your entries. Users must manually bind them in the keyboard preferences pane. As soon as they do, the bindings are saved just like any other key binding in Renoise. + +To add a key binding, use the tool's [`renoise.tool():add_keybinding`](../API/renoise/renoise.ScriptingTool.md#add_keybinding) function. + +### Example + +```lua +renoise.tool():add_keybinding { + name = "Global:Tools:Example Script Shortcut", + invoke = function(repeated) + -- we ignore soft repeated keys here + if (not repeated) then + renoise.app():show_prompt( + "Congrats!", + "You've pressed a magic keyboard combo " .. + "which was defined by a scripting tool.", + {"OK"} + ) + end + end +} +``` + +### Scopes + +The scope, topic, and name of the key binding are defined in the `name` property, using the format: `$scope:$topic_name:$binding_name`. + +* `scope`: This is where the shortcut will be applied, corresponding to the categories in the keyboard assignment preference pane. Your key binding will only fire when its scope is focused, unless it's the `Global` scope. Using an unavailable scope will not cause an error, but it will render the binding useless—it will be listed and mappable, but never invoked. + +* `topic_name`: This is used for grouping entries in the key assignment pane. Use "Tools" if you can't come up with something more specific. + +* `binding_name`: This is the display name of the binding. + +For a list of available scopes, see the API documentation for [`ToolKeybindingEntry`](../API/renoise/renoise.ScriptingTool.md#toolkeybindingentry). + +### Separating entries + +To divide entries into groups with a separating line, prepend one or more dashes to the `name`, like so: + +```lua +name = "--- Main Menu:Tools:My Tool Group Starts Here" +``` + +## Custom GUIs + +You can create custom dialogs and tool windows for your tools using the [`renoise.ViewBuilder`](../API/renoise/renoise.ViewBuilder.md) and [`renoise.Application`](../API/renoise/renoise.Application.md). + +### Modal and Non-Modal Dialogs + +There are two main ways to show a custom view: + +```lua +-- Shows a modal dialog with a title, custom content, and custom button labels. +-- It blocks interaction with the main window until closed. +renoise.app():show_custom_prompt( + title, content_view, {button_labels} [, key_handler_func, key_handler_options]) + -> [pressed_button_index] +``` + +See the API docs for [`renoise.app():show_custom_prompt`](../API/renoise/renoise.Application.md#show_custom_prompt) for more info. + +```lua +-- Shows a non-modal dialog (a floating tool window) with custom content. +renoise.app():show_custom_dialog( + title, content_view [, key_handler_func, key_handler_options]) + -> [dialog_object] +``` + +See the API docs for [`renoise.app():show_custom_dialog`](../API/renoise/renoise.Application.md#show_custom_dialog) for more info. + +The optional `key_handler_func` allows you to capture keyboard events in the dialog. See the API docs for [`KeyHandler`](../API/renoise/renoise.Application.md#key_handler) for details. + +### Creating Views with ViewBuilder + +Widgets are created with the [`renoise.ViewBuilder`](../API/renoise/renoise.ViewBuilder.md) class. + +#### Hello World + +```lua +-- We start by instantiating a view builder object. +local vb = renoise.ViewBuilder() + +-- We will use a "column" view to stack other views vertically. +-- A column can: +-- 1. Show a background style. +-- 2. Stack child views vertically (vb:column) or horizontally (vb:row). +-- 3. Align child views using margins and spacing. + +local dialog_title = "Hello World" +local dialog_buttons = { "OK" } + +-- Fetch some constants to make the dialog look like Renoise's native views. +local DEFAULT_MARGIN = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN + +-- Start with a 'column' view to stack other views vertically. +local dialog_content = vb:column { + -- Set a margin around our main content. + margin = DEFAULT_MARGIN, + views = { + -- Create another column to group our text with a different background. + vb:column { + -- A background style that is usually used for "groups". + style = "group", + -- Add some margin inside the group to make it look nice. + margin = DEFAULT_MARGIN, + views = { + -- Finally, add the text to the inner column. + vb:text { + text = "from the Renoise Scripting API\n" .. + "in a vb:column with a background." + }, + } + } + } +} + +-- Show the custom content in a prompt. +renoise.app():show_custom_prompt( + dialog_title, dialog_content, dialog_buttons) +``` + +#### Dynamic Content + +GUIs are usually dynamic. To interact with widgets after they are created, you need a way to reference them. Here's how this works with the ViewBuilder API. + +```lua +local vb = renoise.ViewBuilder() + +-- You can build views step-by-step instead of nesting them all at once. +-- This can be clearer for complex layouts. + +-- This step-by-step approach: +local my_column_view = vb:column{} +my_column_view.margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN +my_column_view.style = "group" + +local my_text_view = vb:text{} +my_text_view.text = "My text" +my_column_view:add_child(my_text_view) + +-- ...is equivalent to this nested approach: +local my_column_view_nested = vb:column { + margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN, + style = "group", + views = { + vb:text { + text = "My text" + } + } +} + +-- The nested notation has a problem: you can't easily get references to your +-- views later (e.g., to hide them or change their text). This is what view +-- builder "id"s are for. + +-- Let's build a simple view that dynamically reacts to a button press. + +local DEFAULT_DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN +local DEFAULT_CONTROL_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING + +local dialog_title = "ViewBuilder IDs" +local dialog_buttons = {"OK"} + +local dialog_content = vb:column { + margin = DEFAULT_DIALOG_MARGIN, + spacing = DEFAULT_CONTROL_SPACING, + views = { + vb:text { + id = "my_text", -- We give the view a unique id here. + text = "Do what you see" + }, + vb:button { + text = "Hit Me!", + tooltip = "Hit this button to change the text above.", + notifier = function() + -- Here we resolve the id to get a reference to the text view. + local my_text_view = vb.views.my_text + my_text_view.text = "Button was hit." + end + } + } +} + +-- We are doing two things here: +-- 1. We create a vb:text view and give it a unique `id`. This id can be +-- used at any time to access this view via `vb.views.my_text`. +-- 2. We add a `vb:button` control with a `notifier` function. The notifier +-- is called as soon as the button is pressed. + +-- Please note that ids are unique per ViewBuilder object. You can create +-- multiple ViewBuilder instances (e.g., one for each component) to manage +-- different sets of ids. + +renoise.app():show_custom_prompt( + dialog_title, dialog_content, dialog_buttons) +``` + +#### More Examples + +See the `com.renoise.ExampleToolGui.xrnx` tool for more examples. This tool can be read as its own little guide and provides many more in-depth examples. + +The example tools can be downloaded as part of the XRNX Starter Pack from the [official repository's releases page](https://github.com/renoise/xrnx/releases). + +## MIDI Mappings + +You can extend Renoise's default MIDI mapping set or add custom MIDI mappings for your tool using [`renoise.tool():add_midi_mapping`](../API/renoise/renoise.ScriptingTool.md#add_midi_mapping). + +A tool's MIDI mapping can be used just like regular mappings: by manually binding it in the MIDI mapping dialog, or by assigning it to a custom GUI control via the `midi_mapping` property. + +```lua +renoise.tool():add_midi_mapping { + name = "My Tool:Control Something", + invoke = function(message) + -- message is a renoise.ScriptingTool.MidiMessage + if message.is_trigger then + renoise.app():show_status("MIDI trigger received!") + end + if message.is_abs_value then + local value = message.int_value + renoise.app():show_status("MIDI value received: " .. value) + end + end +} +``` + +The `name` property follows the format `$topic_name:$optional_sub_topic_name:$mapping_name` to organize mappings in the list. The `invoke` function receives a `MidiMessage` object that describes the incoming MIDI data. + +## File Import Hooks + +You can add support for new filetypes in Renoise using [`renoise.tool():add_file_import_hook`](../API/renoise/renoise.ScriptingTool.md#add_file_import_hook). Registered file types will appear in Renoise's disk browser and can be loaded via drag-and-drop. + +```lua +renoise.tool():add_file_import_hook { + category = "sample", + extensions = {"txt"}, + invoke = function(file_name) + -- This is a dummy example. A real implementation would + -- parse the file and create sample data. + local file = io.open(file_name, "r") + if not file then return false end + local content = file:read("*a") + file:close() + + local sample = renoise.song().selected_sample + if not sample then return false end + + -- For simplicity, we just show the content in a dialog + -- instead of creating a sample from it. + renoise.app():show_message( + "Imported TXT as Sample", + "File content:\n" .. content + ) + + -- Return true on success, false on failure. + return true + end +} +``` + +Your hook must specify a `category` (e.g., "sample", "instrument"), a list of file `extensions`, and an `invoke` function that performs the import logic. + + +## Timers + +Tools can register functions that are called periodically using [`renoise.tool():add_timer`](../API/renoise/renoise.ScriptingTool.md#add_timer). This is useful for background tasks or animations in custom GUIs. + +```lua +local tick_count = 0 +local function my_timer_func() + tick_count = tick_count + 1 + renoise.app():show_status("Timer tick: " .. tick_count) + if tick_count >= 10 then + -- To create a one-shot timer, remove it when it's no longer needed. + renoise.tool():remove_timer(my_timer_func) + renoise.app():show_status("Timer removed.") + end +end + +-- Call my_timer_func every 1000ms (1 second). +renoise.tool():add_timer(my_timer_func, 1000) +``` + +Timers are paused when modal dialogs are open. The interval is not guaranteed to be exact, but it's usually accurate to within a few milliseconds. + + +## Application Notifiers + +The tool object provides several `..._observable` properties that allow you to react to application-level events, such as loading a new song or the tool being shut down. This is the primary way to manage your tool's lifecycle. + +```lua +local function on_new_song() + local song_name = renoise.song() and renoise.song().name or "Untitled" + renoise.app():show_status("New song loaded: " .. song_name) +end + +-- Called every time a new song is created or loaded. +renoise.tool().app_new_document_observable:add_notifier(on_new_song) + +local function on_tool_shutdown() + -- This is a good place to clean up resources. + print("My tool is unloading.") +end + +-- Called right before the tool is unloaded. +renoise.tool().tool_will_unload_observable:add_notifier(on_tool_shutdown) +``` + +Some important notifiers include: +* `tool_finished_loading_observable`: Fired when the tool has been successfully loaded. +* `tool_will_unload_observable`: Fired just before the tool is disabled or reloaded. +* `app_new_document_observable`: Fired after a new song has been loaded. +* `app_release_document_observable`: Fired before the current song is closed. +* `app_will_save_document_observable` Fired just before the song is saved. +* `app_idle_observable`: Fired periodically, useful for low-priority background tasks. + +## Preferences + +Tools can have preferences that are saved and loaded by Renoise. To use them, we first need to create a [`renoise.Document`](../API/renoise/renoise.Document.md) object which holds the options that we want to store. + +Fields in a Renoise Document are defined as [Observable types](./observables.md). This is especially handy for settings dialogs, as UI widgets can be directly bound to these observable properties. The UI will automatically update the document, and vice-versa. + +Let's see an example of setting up an `options` object for a tool. Our goal is to have a few settings managed by a Document and a dialog to change them. The tool will be able to randomize the song's BPM and track count. + +We will also define a menu entry to open our tool's settings dialog. See the sections on [Menu Entries](#menu-entries) and [Custom GUIs](#custom-guis) for more details. + +```lua +-- Create a new renoise.Document by supplying a table of default values. +-- Each field will be wrapped in an Observable type (e.g., ObservableBoolean). +-- * a boolean for whether the tool should randomize the BPM +-- * a boolean for randomizing tracks +-- * an integer for the maximum number of tracks +local options = renoise.Document.create("RandomizerToolPreferences") { + randomize_bpm = true, + randomize_tracks = false, + max_tracks = 16 +} + +-- Once we have our options, we assign the document to our tool's preferences. +renoise.tool().preferences = options + +-- Define a randomizer function. +-- When called, it will set a random BPM and add or remove tracks. +local function randomize_song() + local song = renoise.song() + -- Use .value to access the underlying value of an Observable + if options.randomize_bpm.value then + -- Set BPM to a value between 60 and 180 + song.transport.bpm = 60 + math.random() * 120 + end + + if options.randomize_tracks.value then + -- Figure out how many tracks we want based on the max_tracks option + local target_count = 1 + math.floor(math.random() * options.max_tracks.value) + local current_count = song.sequencer_track_count + + if current_count < target_count then + -- Insert new tracks if there aren't enough + for i = 1, target_count - current_count do + song:insert_track_at(current_count) + end + else + -- Remove tracks if there are too many + for i = 1, current_count - target_count do + song:delete_track_at(song.sequencer_track_count) + end + end + end +end + +-- Define a function to show a custom dialog for our options. +function show_options() + local vb = renoise.ViewBuilder() + + local dialog_content = vb:column { + margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN, + views = { + -- Add randomize BPM option + vb:row { + views = { + -- Bind our observable value directly to this checkbox + vb:checkbox { + bind = options.randomize_bpm + }, + vb:text { + text = "Randomize BPM" + } + } + }, + -- Add randomize tracks option + vb:row { + views = { + -- Same for the randomize_tracks boolean + vb:checkbox { + bind = options.randomize_tracks + }, + vb:text { + text = "Randomize Tracks" + }, + } + }, + -- Add max tracks row + vb:row { + views = { + -- For max_tracks, create a valuebox and bind it. + -- Restrict it to a range of [1..16]. + vb:valuebox { + min = 1, + max = 16, + bind = options.max_tracks + }, + vb:text { + text = "Tracks Max" + } + } + }, + -- Add some space + vb:space{ + height = renoise.ViewBuilder.DEFAULT_DIALOG_SPACING + }, + -- Add a button that will execute the randomization + vb:button { + text = "Randomize Now", + notifier = randomize_song + } + } + } + + renoise.app():show_custom_dialog( + "Randomizer Options", dialog_content + ) +end + +-- Finally, add a menu entry to open our options dialog. +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Randomizer Options...", + invoke = show_options +} +``` + +As you can see, all we had to do was assign our observables to the `bind` property of the UI controls. Renoise handles the synchronization between the UI and the document automatically. + +### preferences.xml + +When you assign a document to `renoise.tool().preferences`, Renoise automatically saves its state to a `preferences.xml` file inside your tool's folder. As long as you use simple data types, you don't have to worry about serialization. + +Try restarting Renoise to see that the values you've set in your dialog persist between sessions. + +### Complex Documents + +For more complex applications, or if you prefer an object-oriented approach, you can create a class that inherits from [`renoise.Document.DocumentNode`](../API/renoise/renoise.Document.DocumentNode.md) and register properties in its constructor. + +You could rewrite the document creation from the example above like this: + +```lua +---@class RandomizerToolPreferences : renoise.Document.DocumentNode +---@field randomize_bpm renoise.Document.ObservableBoolean +---@field randomize_tracks renoise.Document.ObservableBoolean +---@field max_tracks renoise.Document.ObservableNumber +class "RandomizerToolPreferences" (renoise.Document.DocumentNode) + +function RandomizerToolPreferences:__init() + renoise.Document.DocumentNode.__init(self) + -- Register observable properties which will make up our Document + self:add_property("randomize_bpm", true) + self:add_property("randomize_tracks", false) + self:add_property("max_tracks", 16) +end + +---@type RandomizerToolPreferences +local options = RandomizerToolPreferences() + +renoise.tool().preferences = options +``` + +This approach allows you to build more structured and complex preference documents. See the complete [Document API](../API/renoise/renoise.Document.md) for more details on what you can store and how to manage it. + +> [!NOTE] +> This time we also included type annotations (like `---@class RandomizerToolPreferences`). These can help you with development when using a Lua language server like [LuaLS](https://luals.github.io/), but they are not required for the script to run. diff --git a/docs/guide/track_automation.md b/docs/guide/track_automation.md deleted file mode 100644 index b321acba..00000000 --- a/docs/guide/track_automation.md +++ /dev/null @@ -1,86 +0,0 @@ -# Track Automation - -## Access the selected parameters automation - -... selected in the "Automation" tab in Renoise - -```lua -local selected_track_parameter = renoise.song().selected_track_parameter -local selected_pattern_track = renoise.song().selected_pattern_track - --- is a parameter selected?. -if (selected_track_parameter) then - local selected_parameters_automation = selected_pattern_track:find_automation( - selected_track_parameter) - - -- is there automation for the seelcted parameter? - if (not selected_parameters_automation) then - - -- if not, create a new automation for the currently selected pattern/track - selected_parameters_automation = selected_pattern_track:create_automation( - selected_track_parameter) - end - - ---- do something with existing automation - - -- iterate over all existing automation points - for _,point in pairs(selected_parameters_automation.points) do - print(("track automation: time=%s, value=%s"):format( - point.time, point.value)) - end - - -- clear all points - selected_parameters_automation.points = {} - - -- insert a single new point at line 2 - selected_parameters_automation:add_point_at(2, 0.5) - -- change its value when it already exists - selected_parameters_automation:add_point_at(2, 0.8) - -- remove it again (must exist here) - selected_parameters_automation:remove_point_at(2) - - -- batch creation/insertion of points - local new_points = table.create() - for i=1,selected_parameters_automation.length do - new_points:insert { - time=i, - value=i/selected_parameters_automation.length - } - end - - -- assign them (note that new_points must be sorted by time) - selected_parameters_automation.points = new_points - - -- change the automations interpolation mode - selected_parameters_automation.playmode = - renoise.PatternTrackAutomation.PLAYMODE_CUBIC -end -``` - -## Add menu entries for automation - -```lua --- shows up in the automation list on the left of the "Automation" tab -renoise.tool():add_menu_entry { - name = "Track Automation:Do Something With Automation", - invoke = function() do_something_with_current_automation() end, - active = function() return can_do_something_with_current_automation() end -} - --- shows up in the context menu of the automation !rulers! -renoise.tool():add_menu_entry { - name = "Track Automation List:Do Something With Automation", - invoke = function() do_something_with_current_automation() end, - active = function() return can_do_something_with_current_automation() end -} - -function can_do_something_with_current_automation() - -- is a parameter selected and automation present? - return (renoise.song().selected_track_parameter ~= nil and - selected_pattern_track:find_automation(selected_track_parameter)) -end - -function do_something_with_current_automation() - -- do something with selected_parameters_automation -end -``` diff --git a/docs/guide/views.md b/docs/guide/views.md deleted file mode 100644 index 4cb7e61f..00000000 --- a/docs/guide/views.md +++ /dev/null @@ -1,189 +0,0 @@ -# Views - -Currently there are two ways to to create custom views in Tools: - -```lua --- Shows a modal dialog with a title, custom content and custom button labels: -renoise.app():show_custom_prompt( - title, content_view, {button_labels} [, key_handler_func, key_handler_options]) - -> [pressed button] -``` - -See API Docs for [show_custom_prompt](../API/renoise/renoise.Application.md#show_custom_prompt) for more info. - - -```lua --- Shows a non modal dialog, a floating tool window, with custom content: -renoise.app():show_custom_dialog( - title, content_view [, key_handler_func, key_handler_options]) - -> [dialog object] -``` - -See API Docs for [show_custom_dialog](../API/renoise/renoise.Application.md#show_custom_prompt) for more info. - -The `key_handler_func` in the custom dialog is optional. When defined, it should point to a function -with the signature noted below. - -See API Docs for [KeyHandler](../API/renoise/renoise.Application.md#key_handler) for more info. - - -## Creating Custom Views - -Widgets are created with the `renoise.ViewBuilder` class in the renoise API. - -See API Docs for [ViewBuilder](../API/renoise/renoise.ViewBuilder.md) for more info. - -### Hello World - -```lua --- We start by instantiating a view builder object. We'll use it to create views. -local vb = renoise.ViewBuilder() - --- Now we are going to use a "column" view. A column can do three things: --- 1. showing a background (if you don't want your views on the plain dialogs --- back) --- 2. "stack" other views (its child views) either vertically, or horizontally --- vertically = vb:column{} --- horizontally = vb:row{} --- 3. align child views via "margins" -> borders for nested views - -local dialog_title = "Hello World" -local dialog_buttons = { "OK" } - --- fetch some consts to let the dialog look like Renoises default views... -local DEFAULT_MARGIN = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN - --- start with a 'column' view, to stack other views vertically: -local dialog_content = vb:column { - -- set a border of DEFAULT_MARGIN around our main content - margin = DEFAULT_MARGIN, - - -- and create another column to align our text in a different background - vb:column { - -- background style that is usually used for "groups" - style = "group", - -- add again some "borders" to make it more pretty - margin = DEFAULT_MARGIN, - - -- now add the first text into the inner column - vb:text { - text = "from the Renoise Scripting API\n".. - "in a vb:column with a background" - }, - } -} - --- show the custom content in a prompt -renoise.app():show_custom_prompt( - dialog_title, dialog_content, dialog_buttons) -``` - -#### Dynamic Content - -GUIs usually are dynamic. They interact with the user. Do do so, you'll need to memorize references to some of your widgets. Here's an example on how this works in the Renoise View API. - -```lua -local vb = renoise.ViewBuilder() - --- we've used above an inlined style to create view. This is very elegant --- when creating only small & simple GUIs, but can also be confusing when the --- view hierarchy gets more complex. --- you actually can also build views step by step, instead of passing a table --- with properties, set the properties of the views manually: - -local DEFAULT_DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN - --- this: -local my_column_view = vb:column{} -my_column_view.margin = DEFAULT_DIALOG_MARGIN -my_column_view.style = "group" - -local my_text_view = vb:text{} -my_text_view.text = "My text" -my_column_view:add_child(my_text_view) - --- is exactly the same like this: -local my_column_view = vb:column{ - margin = DEFAULT_DIALOG_MARGIN, - style = "group", - vb:text{ - text = "My text" - } -} - --- In practice you should use a combination of the above two notations, but --- its recommended to setup & prepare components in separate steps while --- still using the inlined / nested notation: - -local my_first_column_view = vb:column { - -- some content -} - -local my_second_column_view = vb:column { - -- some more content -} - --- Then do the final layout: -local my_final_layout = vb:row { - my_first_column_view, - my_second_column_view -} - --- The inlined notation has a problem though: You can not memorize your views --- in local variables, in case you want to access them later (for example to --- hide/how them, change the text or whatever else). This is what viewbuilder --- "id"s are for. - --- Lets build up a simple view that dynamically reacts on a button hit: - -local DEFAULT_DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN -local DEFAULT_CONTROL_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING - -local dialog_title = "vb IDs" -local dialog_buttons = {"OK"}; - -local dialog_content = vb:column { - margin = DEFAULT_DIALOG_MARGIN, - spacing = DEFAULT_CONTROL_SPACING, - - vb:text { - id = "my_text", -- we're giving the view a unique id here - text = "Do what you see" - }, - - vb:button { - text = "Hit Me!", - tooltip = "Hit this button to change the above text.", - notifier = function() - -- here we resolve the id and access the above constructed view - local my_text_view = vb.views.my_text - my_text_view.text = "Button was hit." - end - } -} - --- We are doing two things here: --- First we do create a vb:text as usual, but this time we also give it an --- id "my_text_view". This id can then at any time be used to resolve this --- view. So we can use the inlined notation without having to create lots of --- local view refs - --- There's now also a first control present: a button. Controls may have --- notifiers. --- The buttons notifier is simply a function without arguments, which is --- called as soon as you hit the button. Tf you use other views like a --- value box, the notifiers will pass a value along your function... - --- Please note that ids are unique !per viewbuilder object!, so you can --- create several viewbuilders (one for each component) to access multiple --- sets of ids. - -renoise.app():show_custom_prompt( - dialog_title, dialog_content, dialog_buttons) -``` - -### More Examples - -See [com.renoise.ExampleToolGUI.xrnx](https://github.com/renoise/xrnx/tree/master/tools) for more examples. This tool be read as it's own little guide and provides a lot more in-depth examples. - -The example tools can also be downloaded as part of a XRNX Starter pack Bundle from the [releases page](https://github.com/renoise/xrnx/releases). diff --git a/docs/start/development.md b/docs/start/development.md index 22c26683..02660167 100644 --- a/docs/start/development.md +++ b/docs/start/development.md @@ -1,15 +1,12 @@ # Setting up your development environment -By default Renoise has all scripting utilities hidden to keep it simple for users who don't wish to mess around with code. If you want to write scripts, the first thing you have to do is to enable the hidden development tools. +To start developing Scripts in Renoise, use the following two menu entries inside the `Tools` menu on the top bar. -* For a quick test you can launch the Renoise executable with the `--scripting-dev` argument -* To have this mode enabled by default, you'll have to edit your `Config.xml` file inside Renoise's preferences folder. Search for the `` property and set it to `true`. To reveal the Config.xml path, click on the *Help / Show the Preferences Folder...* menu entry in Renoise. - +* `Scripting Terminal & Editor` - This will open the debugging console used to test things and see your tool's output +* `Reload All Tools` - This will force a reload of all installed and running tools. It can be useful when adding new tools by hand or when changing them. -Once scripting is enabled, you'll have the following entries inside the *Tools* menu on the top bar. - -* *Scripting Terminal & Editor* - This will open the debugging console used to test things and see your tool's output -* *Reload All Tools* - This will force a reload of all installed and running tools. It can be useful when adding new tools by hand or when changing them. +> [!NOTE] +> In previous versions of Renoise it was necessary to launch the Renoise executable with the `--scripting-dev` argument to see the above mentioned menue entries. ## Lua diff --git a/docs/start/possibilities.md b/docs/start/possibilities.md index 46797b21..ad30d683 100644 --- a/docs/start/possibilities.md +++ b/docs/start/possibilities.md @@ -36,20 +36,12 @@ Before you delve into writing your own scripts and tools, it worth considering w There are a few ways tool creators can make the functionality they provide available for users, below is a brief summary of the most used methods. -* [Define keybindings](../guide/keybindings.md) that can be assigned to shortcuts and executed from certain contexts in Renoise -* [Add new entries to menus](../guide/menus.md) like the *Tools* menu or one of the right-click context menus -* [Create custom views](../guide/views.md) that do things on button presses, slider drags and so on +* [Define keybindings](../guide/tool.md#keybindings) that can be assigned to shortcuts and executed from certain contexts in Renoise +* [Add new entries to menus](../guide/tool.md#menu-entries) like the *Tools* menu or one of the right-click context menus +* [Create custom views](../guide/tool.md#custom-guis) that do things on button presses, slider drags and so on * Listen to [MIDI](../guide/midi.md), [OSC](../guide/osc.md) or [WebSocket messages](../guide/sockets.md) to execute actions * [React to events inside Renoise](../guide/observables.md) like "do something any time a new song is loaded" - ## Limitations @@ -58,4 +50,4 @@ Finally, let's look at what is **not** possible via tools. * You cannot override the existing behaviour of Renoise. You can add functionality *on top* of what's already there, but you can't disable or change how the built-in features work. For example, you can create a completely custom GUI to compose patterns in a novel way but you cannot change how the built-in pattern editor works or looks like. Similarly, you can add a new shortcut that does something extra to the selected sample block or places new slices but you can't modify how the built-in autoslicing works. -* You cannot write real-time DSP code like synths, effects or modulators (except for scripts inside the [Formula device](https://tutorials.renoise.com/wiki/Meta_Devices#*Formula)), which is not using the Renoise Tool API. If you want to design your own synths and effects you should look into plugin development (using [DISTRHO](https://distrho.kx.studio/), [nih-plug](https://github.com/robbert-vdh/nih-plug) etc.), you could also use existing plugins that allow you to build your own DSP patches (like [plugdata](https://plugdata.org/) or [Cardinal](https://cardinal.kx.studio/)). Of course you can [generate and modify samples](../guide/sample_buffer.md) using your tool, but it will have to be implemented as offline rendering instead of real-time processing. +* You cannot write real-time DSP code like synths, effects or modulators (except for scripts inside the [Formula device](https://tutorials.renoise.com/wiki/Meta_Devices#*Formula)), which is not using the Renoise Tool API. If you want to design your own synths and effects you should look into plugin development (using [DISTRHO](https://distrho.kx.studio/), [nih-plug](https://github.com/robbert-vdh/nih-plug) etc.), you could also use existing plugins that allow you to build your own DSP patches (like [plugdata](https://plugdata.org/) or [Cardinal](https://cardinal.kx.studio/)). Of course you can [generate and modify samples](../guide/song.md#samples) using your tool, but it will have to be implemented as offline rendering instead of real-time processing. diff --git a/docs/start/tool.md b/docs/start/tool.md index 9b8e88bd..365142ed 100644 --- a/docs/start/tool.md +++ b/docs/start/tool.md @@ -2,71 +2,108 @@ There are a few things that all tools must conform to for Renoise to successfully recognize and load them. -* A tool is either a folder or a zip file with the extension `.xrnx` -* It has a lua script named `main.lua` which contains the tool's program -* And a `manifest.xml` file that has version info, description and more - ```sh com.name_of_creator.name_of_tool.xrnx ├── manifest.xml -└── main.lua +├── main.lua +├── cover.png +├── thumbnail.png +├── LICENSE +└── README.md ``` +A tool is a folder or a *zip file* with the extension `.xrnx`. + +#### Required files: +* `main.lua` contains the tool's program. +* `manifest.xml` is an XML file which describes your tool. + +#### Optional files: +* `cover.png` **600x350 px** is a large image, used on the tools page overview and on the pages of individual tools. +* `thumbnail.png` **120x45 px** is a small capsule image, used when tools are shown in a list on the tools website. +* `README.md` is a markdown-formatted file that the website will render on the tool's page. +* `LICENSE` is a raw text license file. + +The paths to the cover, thumbnail, readme, and license files can be customized using the `...File` tags in the manifest. See below for more info. + + > [!NOTE] -> You'll see that names of folders for most tools follow [reverse domain notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation), but don't worry, you don't have to actually own a domain to create and share your tools. Just use whatever nickname you want, just make sure it's not already taken by other devs to avoid confusion. +> You'll see that the names of tool folders follow [reverse domain notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation), but don't worry, you don't have to actually own a domain to create and share your tools. Just use whatever nickname you want, but make sure it's not already taken by other developers to avoid confusion. -If needed, you can split your tool into multiple files and use the ["require" function](https://www.lua.org/pil/8.1.html) to load them inside your main script, but first you will be fine just using a single main script. +If needed, you can split your tool into multiple files and use the ["require" function](https://www.lua.org/pil/8.1.html) to load them inside your main script, but to start with, you will be fine just using a single main script. -Some tools will also make use of other resources like icons, text files or audio samples, these should all be placed in the same folder (or any subfolders inside it). +Some tools will also make use of other resources like bitmaps or audio samples; these should all be placed in the same folder (or any subfolders inside it). Let's look at a basic tool to see what goes into these two files. You can find more elaborate examples by browsing the example tools. ## Manifest -The manifest is a short [XML](https://www.w3schools.com/XML/xml_whatis.asp) file with the name `manifest.xml`. It contains a few tag pairs like `...` and some text between them, Renoise reads these and loads your tool based on the information it finds inside. +The manifest is a short [XML](https://www.w3schools.com/XML/xml_whatis.asp) file with the name `manifest.xml`. It contains a few tag pairs like `...` and some text between them. Renoise reads these and loads your tool based on the information it finds within. Here is an entire manifest file from a HelloWorld tool: - ```xml - 6.1 + com.renoise.HelloWorld - 1.0 + 6.2 + 1.02 Your Name [your@email.com] Hello World - Tool Development + + Development, Workflow This tool is for printing "Hello World!" to the terminal when loaded. - http://tools.renoise.com - icon.png Windows, Mac, Linux + MIT + LICENSE.md + images/thumbnail.png + images/cover.png + docs/README.md + https://some.url/my-tool + https://some.url/my-tool-docs + https://some.url/my-tool + https://git.some.url/my-tool + https://some.url/donate ``` -Let's go through what each of these tags mean and what you should put inside them. +Let's go through what each of these tags means and what you should put inside them. -`` is the header for the XML file, this will stay the same across all tools. `` tells Renoise that this XML describes a tool. Don't change this. +`` is the header for the XML file; this will stay the same across all tools.
+`` tells Renoise that this XML describes a tool. Don't change this.
+`` is a XML comment, which will be ignored by Renoise. ### Required Properties -* `` The version of the Renoise API your tool is using. This should be `6.1` for the latest version. -* `` Should match the folder name of your tool **exactly** without the `.xrnx` at the end. -* `` The version of your tool, whenever you release a new update you should increase the version. Note that this is a **number value** and not a semantic version. So `1.02` is a valid version, while `1.0.2` **is not**. -* `` Your name and contact information. Whenever your tool crashes, this information is going to be provided for the user alongside the crash message, you should use some contact where you can accept possible bug reports or questions. -* `` Human readable name of your tool, it can be anything you want and you can change it anytime you feel like it. -* `` Category for your tool, which will be used to categorize your tool on the [official Tools page](https://www.renoise.com/tools) if you ever decide to submit it there -* `` A short description of your tool which will be displayed inside the *Tool Browser* in Renoise and on the Tools page. +* `` Should match the folder name of your tool **exactly**, without the `.xrnx` at the end. +* `` The version of the Renoise API your tool is using. This should be `6.2` for the latest version. +* `` The version of your tool. Whenever you release a new update, you should increase the version. Note that this is a **number value** and not a semantic version. So `1.02` is a valid version, while `1.0.2` **is not**. +* `` Your name and contact information. Whenever your tool crashes, this information is going to be provided for the user alongside the crash message. You should provide a contact method where you can receive bug reports or questions. +* `` The human-readable name of your tool. It can be anything you want, and you can change it anytime you feel like it. ### Optional Properties -* `` Your tool's website address if you have any. You could also put a forum topic or git repository here if you want. -* `` A relative path to an optional icon to your tool. -* `` List of platforms your tool supports separated by `,`. As long as you're only using the Renoise API, your tool will be automatically cross-platform, but once you do something OS specific you should communicate that here. +* `` One or more categories for your tool, separated via `,`, which will be used to categorize your tool on the [official Tools page](https://www.renoise.com/tools) if you ever decide to submit it there. See below for a valid list of categories. +* `` A short description of your tool which will be displayed inside the *Tool Browser* in Renoise and on the official Tools page. +* `` The type of license, e.g., *MIT* or *AGPL*. +* `` Relative path to the license file within the XRNX bundle. +* `` Relative path to the thumbnail icon file for the Tools page. +* `` Relative path to the cover image file for the Tools page. +* `` Relative path to a plain text or markdown documentation file. +* `` The URL of your tool's homepage. +* `` The URL of your tool's discussion page, e.g., on the Renoise forums. +* `` The URL of your tool's source code repository. +* `` A URL to a website where donations can be made to support your tool. +* `` A URL to a website where your tool's documentation can be viewed. + +#### Tool Categories + +Valid categories are: `Automation`, `Coding`, `Control`, `Development`, `Export`, `Game`, `Hardware`, `Import`, `Instrument`, `MIDI`, `Mixing`, `Modulation`, `Networking`, `OSC`, `Pattern Editor`, `Pattern`, `Phrases`, `Plugins`, `Recording`, `Rendering`, `Sample Editor`, `Sample` , `Sequencer`, `Slicing`, `Tuning`, `Workflow` -### Text Encoding +#### XML Text Encoding When writing the XML file in a regular text editor, ensure that text content is encoded correctly. Otherwise, the XML file will be invalid. @@ -84,4 +121,4 @@ Now that we have a manifest file, we can get to the exciting part of printing a print("Hello world!") ``` -Done! Now that you wrote your first tool you probably want to install and test it. +Done! Now that you have written your first tool, you probably want to install and test it. diff --git a/generate/Cargo.toml b/generate/Cargo.toml index a48f8580..e45944b0 100644 --- a/generate/Cargo.toml +++ b/generate/Cargo.toml @@ -5,4 +5,4 @@ edition = "2021" [dependencies] # luals-docs-gen = { path = "../../Crates/luals-docs-gen" } -luals-docs-gen = { git = "https://github.com/emuell/luals-docs-gen", tag = "v0.2.0" } +luals-docs-gen = { git = "https://github.com/emuell/luals-docs-gen", tag = "v0.2.2" } diff --git a/tools/com.renoise.ExampleTool.xrnx/icon.png b/tools/com.renoise.ExampleTool.xrnx/icon.png deleted file mode 100644 index ef2e179a..00000000 Binary files a/tools/com.renoise.ExampleTool.xrnx/icon.png and /dev/null differ diff --git a/tools/com.renoise.ExampleTool.xrnx/main.lua b/tools/com.renoise.ExampleTool.xrnx/main.lua index f29987b1..3d4c6af1 100644 --- a/tools/com.renoise.ExampleTool.xrnx/main.lua +++ b/tools/com.renoise.ExampleTool.xrnx/main.lua @@ -5,27 +5,27 @@ com.renoise.ExampleTool.xrnx/main.lua -- XRNX Bundle Layout: -- Tool scripts must describe themself through a manifest XML, to let Renoise --- know which API version it relies on, what "it can do" and so on, without --- actually loading it. See "manifest.xml" in this exampel tool for more info +-- know which API version it relies on, what "it can do" and so on, without +-- actually loading it. See "manifest.xml" in this exampel tool for more info -- please -- --- When the manifest loads and looks OK, the main file of the tool will be +-- When the manifest loads and looks OK, the main file of the tool will be -- loaded. This is this file -> "main.lua". -- -- You can load other files from here via LUAs 'require', or simply put --- all the code in here. This file simply is the main entry point of your tool. --- While initializing, you can register your tool with Renoise, by creating --- keybindings, menu entries or listening to events from the application. +-- all the code in here. This file simply is the main entry point of your tool. +-- While initializing, you can register your tool with Renoise, by creating +-- keybindings, menu entries or listening to events from the application. -- We will describe all this below now: - -------------------------------------------------------------------------------- -- preferences -------------------------------------------------------------------------------- --- tools can have preferences, just like Renoise. To use them we first need --- to create a renoise.Document object which holds the options that we want to +-- tools can have preferences, just like Renoise. To use them we first need +-- to create a renoise.Document object which holds the options that we want to -- store/restore +---@types ExampleToolPreferences local options = renoise.Document.create("ExampleToolPreferences") { show_debug_prints = false } @@ -33,29 +33,32 @@ local options = renoise.Document.create("ExampleToolPreferences") { -- then we simply register this document as the main preferences for the tool: renoise.tool().preferences = options --- show_debug_prints is now a persistent option which gets saved & restored --- for upcoming Renoise seesions, program launches. --- the preferences file for tools is saved inside the tools bundle as +-- show_debug_prints is now a persistent option which gets saved & restored +-- for upcoming Renoise seesions, program launches. +-- the preferences file for tools is saved inside the tools bundle as -- "preferences.xml" -- for more complex documents, or if you prefere doing things the OO way, you can -- also inherit from renoise.Document.DocumentNode and register properties there: -- -class "ExampleToolPreferences"(renoise.Document.DocumentNode) +---@class ExampleToolPreferences +---@field show_debug_prints renoise.Document.ObservableBoolean +class "ExampleToolPreferences" (renoise.Document.DocumentNode) function ExampleToolPreferences:__init() renoise.Document.DocumentNode.__init(self) - - -- register an observable property "show_debug_prints" which also will be + + -- register an observable property "show_debug_prints" which also will be -- loaded/saved with the document self:add_property("show_debug_prints", false) end +---@type ExampleToolPreferences : renoise.Document.DocumentNode local options = ExampleToolPreferences() renoise.tool().preferences = options -- which also allows you to create more complex documents. --- please have a look at the Renoise.Tool.API.txt for more info and details +-- please have a look at the Renoise.Tool.API.txt for more info and details -- about documents and what else you can load/store this way... @@ -63,20 +66,22 @@ renoise.tool().preferences = options -- custom song data -------------------------------------------------------------------------------- --- Tools also can inject/retain their state in Renoise songs as tool_data. --- This can be useful when the tool's state should be memorized on a song basis +-- Tools also can inject/retain their state in Renoise songs as tool_data. +-- This can be useful when the tool's state should be memorized on a song basis -- instead of globally (via preferences). -- --- renoise.song().tool_data is a string, so it can contain any serialized --- data. In this example we're using a renoise.Document.DocumentNode to manage +-- renoise.song().tool_data is a string, so it can contain any serialized +-- data. In this example we're using a renoise.Document.DocumentNode to manage -- the data which is then serialized/unserialized via the renoise.Document --- to_string/from_string functions. +-- to_string/from_string functions. -- -- See menu entry: --- 'Main Menu:Tools:Example Tool:Modify Song Local Data...' and +-- 'Main Menu:Tools:Example Tool:Modify Song Local Data...' and -- function 'handle_app_new_document_notification' below for a simple example. -class "ExampleToolSongData"(renoise.Document.DocumentNode) +---@class ExampleToolSongData : renoise.Document.DocumentNode +---@field counter renoise.Document.ObservableNumber +class "ExampleToolSongData" (renoise.Document.DocumentNode) function ExampleToolSongData:__init() renoise.Document.DocumentNode.__init(self) @@ -84,72 +89,74 @@ function ExampleToolSongData:__init() end function ExampleToolSongData:reset() - -- NB: from_string(to_string) avoids recreating the object and its members, + -- NB: from_string(to_string) avoids recreating the object and its members, -- which is useful when its members they are already referenced somwhere. self:from_string(ExampleToolSongData():to_string()) end +---@type ExampleToolSongData local song_data = ExampleToolSongData() + -------------------------------------------------------------------------------- -- menu entries -------------------------------------------------------------------------------- --- you can add new menu entries into any existing context menues or the global +-- you can add new menu entries into any existing context menues or the global -- menu in Renoise. to do so, we are using the tool's add_menu_entry function. --- Please have a look at "Renoise.ScriptingTool.API.txt" i nthe documentation +-- Please have a look at "Renoise.ScriptingTool.API.txt" i nthe documentation -- folder for a complete reference. -- --- Note: all "invoke" functions here are wrapped into a local function(), --- because the functions, variables that are used are not yet know here. +-- Note: all "invoke" functions here are wrapped into a local function(), +-- because the functions, variables that are used are not yet know here. -- They are defined below, later in this file... renoise.tool():add_menu_entry { name = "Main Menu:Tools:Example Tool:Enable Example Debug Prints", selected = function() return options.show_debug_prints.value end, - invoke = function() - options.show_debug_prints.value = not options.show_debug_prints.value + invoke = function() + options.show_debug_prints.value = not options.show_debug_prints.value end } renoise.tool():add_menu_entry { name = "--- Main Menu:Tools:Example Tool:Show Dialog...", - invoke = function() - show_dialog() + invoke = function() + show_dialog() end } renoise.tool():add_menu_entry { name = "Main Menu:Tools:Example Tool:Show Status Message", - invoke = function() - show_status_message() + invoke = function() + show_status_message() end } renoise.tool():add_menu_entry { name = "--- Main Menu:Tools:Example Tool:Modify Song Local Data...", - invoke = function() + invoke = function() -- update our song data - song_data.counter.value = song_data.counter.value + 1 + song_data.counter.value = song_data.counter.value + 1 -- update tool_data in the current song renoise.song().tool_data = song_data:to_string() - end + end } renoise.tool():add_menu_entry { name = "--- Main Menu:Tools:Example Tool:Add New Entry", - invoke = function() - insert_another_menu_entry() - end + invoke = function() + insert_another_menu_entry() + end } renoise.tool():add_menu_entry { name = "Main Menu:Tools:Example Tool:Remove Entry", - active = function() - return can_remove_menu_entry() + active = function() + return can_remove_menu_entry() end, - invoke = function() - remove_menu_entry() + invoke = function() + remove_menu_entry() end } @@ -158,12 +165,12 @@ renoise.tool():add_menu_entry { -- key bindings -------------------------------------------------------------------------------- --- you can also define keybindings for your script, which will be activated and +-- you can also define keybindings for your script, which will be activated and -- mapped by the user just as any other key binding in Renoise. --- Keybindings can be global (apploied everywhere in the GUI) or can be local +-- Keybindings can be global (apploied everywhere in the GUI) or can be local -- to a specific part of the GUI, liek the Pattern Editor. -- --- Again, have a look at "Renoise.ScriptingTool.API.txt" in the documentation +-- Again, have a look at "Renoise.ScriptingTool.API.txt" in the documentation -- folder for a complete reference. renoise.tool():add_keybinding { @@ -172,9 +179,9 @@ renoise.tool():add_keybinding { if (not repeated) then -- we ignore soft repeated keys here renoise.app():show_prompt( "Congrats!", - "You've pressed a magic keyboard combo ".. + "You've pressed a magic keyboard combo " .. "which was defined by a script example tool.", - {"OK?"} + { "OK?" } ) end end @@ -185,21 +192,21 @@ renoise.tool():add_keybinding { -- midi mappings -------------------------------------------------------------------------------- --- Tools also can extend Renoises internal MIDI mapping set. This way you can +-- Tools also can extend Renoises internal MIDI mapping set. This way you can -- add MIDI mappings to control your tool, or also write tools which do nothing -- more than extending Renoises default MIDI mapping set. -- --- Have a look at "Renoise.ScriptingTool.API.txt" in the documentation +-- Have a look at "Renoise.ScriptingTool.API.txt" in the documentation -- folder for a complete reference. Also have a look at the GlobalMidiActions.lua --- file for examples mappings (this is Renoises complete default MIDI mapping set) +-- file for examples mappings (this is Renoises complete default MIDI mapping set) -- and more descriptions of the passed message parameter. -renoise.tool():add_midi_mapping{ +renoise.tool():add_midi_mapping { name = "com.renoise.ExampleTool:Example MIDI Mapping", invoke = function(message) if (options.show_debug_prints.value) then print("com.renoise.ExampleTool: >> got midi_mapping message :") - + print((" message:is_trigger(): %s)"):format( message:is_trigger() and "yes" or "no")) print((" message:is_switch(): %s)"):format( @@ -208,7 +215,7 @@ renoise.tool():add_midi_mapping{ message:is_rel_value() and "yes" or "no")) print((" message:is_abs_value(): %s)"):format( message:is_abs_value() and "yes" or "no")) - + print((" message.int_value: %d)"):format( message.int_value)) print((" message.boolean_value: %s)"):format( @@ -222,22 +229,22 @@ renoise.tool():add_midi_mapping{ -- notifications -------------------------------------------------------------------------------- --- You can attach and detach from a set of script related notifications at any +-- You can attach and detach from a set of script related notifications at any -- time. Please see renoise.Document.API.txt -> Observable for more info -- Invoked, as soon as the application became the foreground window, -- for example when you alt-tab'ed to it, or switched with the mouse -- from another app to Renoise. renoise.tool().app_became_active_observable:add_notifier(function() - handle_app_became_active_notification() + handle_app_became_active_notification() end) - + -- Invoked, as soon as the application looses focus, another app -- became the foreground window. renoise.tool().app_resigned_active_observable:add_notifier(function() handle_app_resigned_active_notification() end) - + -- Invoked periodically in the background, more often when the work load -- is low. less often when Renoises work load is high. -- The exact interval is not defined and can not be relied on, but will be @@ -247,8 +254,8 @@ end) renoise.tool().app_idle_observable:add_notifier(function() handle_app_idle_notification() end) - --- Invoked right before a document (song) gets replaced with a new one. The old + +-- Invoked right before a document (song) gets replaced with a new one. The old -- document is still valid here. renoise.tool().app_release_document_observable:add_notifier(function() handle_app_release_document_notification() @@ -287,7 +294,7 @@ end) -- Note: When reloading the script causes an error, the old, last running -- script instance will continue to run. -- --- Finally: Changes in the actions menu may not be updated for new tools, +-- Finally: Changes in the actions menu may not be updated for new tools, -- unless you reload all tools manually with 'Reload Tools' in the menu. _AUTO_RELOAD_DEBUG = function() @@ -302,12 +309,12 @@ end -------------------------------------------------------------------------------- -- if you want to do something, each time the script gets loaded, then --- simply do it here, in the global namespace when your tool gets loaded. --- The script will start running as soon as Renoise started, and stop running --- as soon as it closes. +-- simply do it here, in the global namespace when your tool gets loaded. +-- The script will start running as soon as Renoise started, and stop running +-- as soon as it closes. -- --- IMPORTANT: this also means that there will be no song (yet) when this script --- initializes, so any access to app().current_document() or song() will fail +-- IMPORTANT: this also means that there will be no song (yet) when this script +-- initializes, so any access to app().current_document() or song() will fail -- here. -- If you really need the song to initialize your application, do this in -- the notifications.app_new_document functions or in your action callbacks... @@ -326,12 +333,11 @@ end function show_dialog() renoise.app():show_warning( ("This example does nothing more beside showing a warning message " .. - "and the current BPM, which has an amazing value of '%s'!"):format( - renoise.song().transport.bpm) + "and the current BPM, which has an amazing value of '%s'!"):format( + renoise.song().transport.bpm) ) end - -------------------------------------------------------------------------------- -- show_status_message @@ -343,11 +349,10 @@ function show_status_message() renoise.app():show_status( ("com.renoise.ExampleTool: Showing status message no. %d..."):format( - status_message_count) + status_message_count) ) end - -------------------------------------------------------------------------------- -- insert_another_menu_entry @@ -357,46 +362,43 @@ end local num_added_entries = 0 -function insert_another_menu_entry() +function insert_another_menu_entry() num_added_entries = num_added_entries + 1 - + local entry_name = ("Main Menu:Tools:Example Tool:New Entry %d"):format( num_added_entries) - + renoise.tool():add_menu_entry { name = entry_name, - invoke = function() + invoke = function() renoise.app():show_status( - ("New Entry %s was pressed..."):format(num_added_entries)) + ("New Entry %s was pressed..."):format(num_added_entries)) end } end - -------------------------------------------------------------------------------- -- can_remove_menu_entry -function can_remove_menu_entry() +function can_remove_menu_entry() return (num_added_entries > 0) end - -------------------------------------------------------------------------------- -- remove_menu_entry -function remove_menu_entry() +function remove_menu_entry() assert(can_remove_menu_entry(), "entry should not be invoked") - + renoise.tool():remove_menu_entry( ("Main Menu:Tools:Example Tool:New Entry %d"):format( - num_added_entries)) - + num_added_entries)) + num_added_entries = num_added_entries - 1 end - -------------------------------------------------------------------------------- -- implementation if the nofification callbacks, as attached above... @@ -409,7 +411,6 @@ function handle_app_became_active_notification() end end - -- handle_app_resigned_active_notification function handle_app_resigned_active_notification() @@ -418,7 +419,6 @@ function handle_app_resigned_active_notification() end end - -- handle_app_idle_notification local last_idle_time = os.clock() @@ -426,13 +426,12 @@ local last_idle_time = os.clock() function handle_app_idle_notification() if os.clock() - last_idle_time >= 10 then last_idle_time = os.clock() - if (options.show_debug_prints.value) then - print("com.renoise.ExampleTool: 10 second idle notification") - end - end + if (options.show_debug_prints.value) then + print("com.renoise.ExampleTool: 10 second idle notification") + end + end end - -- handle_app_release_document_notification function handle_app_release_document_notification() @@ -441,47 +440,44 @@ function handle_app_release_document_notification() end end - -- handle_app_new_document_notification function handle_app_new_document_notification() if (options.show_debug_prints.value) then - print(("com.renoise.ExampleTool: !! app_new_document notification".. + print(("com.renoise.ExampleTool: !! app_new_document notification" .. " (filename: '%s')"):format(renoise.song().file_name)) end -- reset or load existing song local tool data local tool_data = renoise.song().tool_data if (tool_data == nil) then -- no data present in the loaded song: reset song_data to its initial state - song_data:reset() + song_data:reset() if (options.show_debug_prints.value) then - print(("com.renoise.ExampleTool: !! reset custom song data".. + print(("com.renoise.ExampleTool: !! reset custom song data" .. " (data: '%d')"):format(song_data.counter.value)) end - else - -- there is some tool data present in the song: assign our song_data from the + else + -- there is some tool data present in the song: assign our song_data from the -- song's custom tool data string local succeeded, error = song_data:from_string(tool_data) if (options.show_debug_prints.value) then - print(("com.renoise.ExampleTool: !! loaded custom song data".. + print(("com.renoise.ExampleTool: !! loaded custom song data" .. " (data: '%d') - result: %s"):format( - song_data.counter.value, - succeeded and 'OK' or error)) + song_data.counter.value, + succeeded and 'OK' or error)) end end end - -- handle_app_saved_document_notification function handle_app_saved_document_notification() if (options.show_debug_prints.value) then - print(("com.renoise.ExampleTool: !! handle_app_saved_document ".. + print(("com.renoise.ExampleTool: !! handle_app_saved_document " .. "notification (filename: '%s')"):format(renoise.song().file_name)) end end - -- handle_auto_reload_debug_notification function handle_auto_reload_debug_notification() diff --git a/tools/com.renoise.ExampleTool.xrnx/manifest.xml b/tools/com.renoise.ExampleTool.xrnx/manifest.xml index c650701f..317fd19c 100644 --- a/tools/com.renoise.ExampleTool.xrnx/manifest.xml +++ b/tools/com.renoise.ExampleTool.xrnx/manifest.xml @@ -1,13 +1,13 @@ - 6.1 + 6.2 com.renoise.ExampleTool - 1.0 + 1.2 taktik [taktik@renoise.com] Renoise Scripting Tool Example - Tool Development - A XRNX tool which describes step by step and in depth how to create Renoise XRNX tools. Please have a look at the source files of this tool (manifest.xml and main.lua) for more info. Also creates a new menu 'Example Tool' in the global 'Tools' menu. + Development + Example tool which describes step by step and in depth how to create Renoise XRNX tools. Please have a look at the source files of this tool (manifest.xml and main.lua) for more info. Also creates a new menu 'Example Tool' in the global 'Tools' menu. http://scripting.renoise.com - icon.png + MIT Windows, Mac, Linux diff --git a/tools/com.renoise.ExampleTool.xrnx/preferences.xml b/tools/com.renoise.ExampleTool.xrnx/preferences.xml deleted file mode 100644 index d7c37f72..00000000 --- a/tools/com.renoise.ExampleTool.xrnx/preferences.xml +++ /dev/null @@ -1,4 +0,0 @@ - - - true - diff --git a/tools/com.renoise.ExampleToolGui.xrnx/main.lua b/tools/com.renoise.ExampleToolGui.xrnx/main.lua index 76db4071..1c4b2d8b 100644 --- a/tools/com.renoise.ExampleToolGui.xrnx/main.lua +++ b/tools/com.renoise.ExampleToolGui.xrnx/main.lua @@ -1,81 +1,26 @@ --[[============================================================================ com.renoise.ExampleToolGui.xrnx/main.lua -============================================================================]]-- - --- tool registration - --- (see com.renoise.ExampleTool.xrns/main.lua for a description of this --- header and tools in general) - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:1. Hello World...", - invoke = function() hello_world() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:2. Pretty Hello World...", - invoke = function() pretty_hello_world() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:3. Dynamic Content & Ids...", - invoke = function() dynamic_content() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:4. Batch Building Views (Matrix)...", - invoke = function() dynamic_building_matrix() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:5. Aligning & Auto Sizing...", - invoke = function() aligners_and_auto_sizing() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:6. Available Backgrounds & Text...", - invoke = function() available_backgrounds() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:7. Available Controls...", - invoke = function() available_controls() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:8. Documents & Views...", - invoke = function() documents_and_views() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:9. Keyboard Events...", - invoke = function() handle_key_events() end -} - -renoise.tool():add_menu_entry { - name = "Main Menu:Tools:Example Tool GUI:10. MIDI mapping...", - invoke = function() midi_mapping() end -} +============================================================================]] -- +-- see com.renoise.ExampleTool.xrns/main.lua for tools in general -------------------------------------------------------------------------------- --- Helper Function +-- Helper Functions -------------------------------------------------------------------------------- local function show_status(message) renoise.app():show_status(message) print(message) end - - + + -------------------------------------------------------------------------------- -- GUI -------------------------------------------------------------------------------- -- hello_world -function hello_world() - +local function hello_world() -- to create views, we do need to create a "viewbuilder object", which -- can be instantiated from the class renoise.ViewBuilder: local vb = renoise.ViewBuilder() @@ -107,23 +52,20 @@ function hello_world() text = "from the Renoise Scripting API" } - local dialog_buttons = {"OK"} + local dialog_buttons = { "OK" } renoise.app():show_custom_prompt( dialog_title, dialog_content, dialog_buttons) -- eh voila. Not pretty, but at least something to start with ;) We're going -- to make that a bit more pretty and advanced in the next example... - end - -------------------------------------------------------------------------------- -- pretty_hello_world -function pretty_hello_world() - +local function pretty_hello_world() -- Beside of texts, controls and backgrounds and so on, the viewbuilder also -- offers some helper views which will help you to 'align' and stack views. @@ -141,7 +83,7 @@ function pretty_hello_world() -- lets use all of this in a bit more complicated hello world view: local dialog_title = "Hello World" - local dialog_buttons = {"OK"}; + local dialog_buttons = { "OK" }; -- get some consts to let the dialog look like Renoises default views... local DEFAULT_MARGIN = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN @@ -157,12 +99,13 @@ function pretty_hello_world() style = "group", -- add again some "borders" to make it more pretty margin = DEFAULT_MARGIN, - - -- now add the first text into the inner column - vb:text { - text = "from the Renoise Scripting API\n".. - "in a vb:column with a background" - }, + -- now add a text *into* the column + views = { + vb:text { + text = "from the Renoise Scripting API\n" .. + "in a vb:column with a background" + } + } } } @@ -172,13 +115,11 @@ function pretty_hello_world() -- lets go on and start to use some real controls (buttons & stuff) now... end - -------------------------------------------------------------------------------- -- dynamic_content -function dynamic_content() - +local function dynamic_content() local vb = renoise.ViewBuilder() -- we've used above an inlined style to create view. This is very elegant @@ -190,42 +131,48 @@ function dynamic_content() local DEFAULT_DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN -- this: - local my_column_view = vb:column{} + local my_column_view = vb:column {} my_column_view.margin = DEFAULT_DIALOG_MARGIN my_column_view.style = "group" - local my_text_view = vb:text{} + local my_text_view = vb:text {} my_text_view.text = "My text" - my_column_view:add_child(my_text_view) + my_column_view:add_view(my_text_view) -- is exactly the same like this: - local my_column_view = vb:column{ + local my_column_view = vb:column { margin = DEFAULT_DIALOG_MARGIN, style = "group", - - vb:text{ - text = "My text" + views = { + vb:text { + text = "My text" + } } } - -- in practice you should use a combination of the above two notations, but -- its recommended to setup & prepare components in separate steps while -- still using the inlined / nested notation: local my_first_column_view = vb:column { - -- some content + views = { + -- some more content + } } local my_second_column_view = vb:column { - -- some more content + views = { + -- some more content + } } -- then do the final layout: local my_final_layout = vb:row { - my_first_column_view, - my_second_column_view + views = { + my_first_column_view, + my_second_column_view + } } -- the inlined notation has a problem though: you can not memorize your views @@ -239,24 +186,25 @@ function dynamic_content() local DEFAULT_CONTROL_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING local dialog_title = "vb IDs" - local dialog_buttons = {"OK"}; + local dialog_buttons = { "OK" }; local dialog_content = vb:column { margin = DEFAULT_DIALOG_MARGIN, spacing = DEFAULT_CONTROL_SPACING, - - vb:text { - id = "my_text", - text = "Do what you see" - }, - - vb:button { - text = "Hit Me!", - tooltip = "Hit this button to change the above text.", - notifier = function() - local my_text_view = vb.views.my_text - my_text_view.text = "Button was hit." - end + views = { + vb:text { + id = "my_text", + text = "Do what you see" + }, + vb:button { + text = "Hit Me!", + tooltip = "Hit this button to change the above text.", + notifier = function() + ---@type renoise.Views.Text + local text_view = vb.views.my_text + text_view.text = "Button was hit." + end + } } } @@ -278,18 +226,15 @@ function dynamic_content() renoise.app():show_custom_prompt( dialog_title, dialog_content, dialog_buttons) - end - -------------------------------------------------------------------------------- -- dynamic_building_matrix -function dynamic_building_matrix() - +local function dynamic_building_matrix() -- as shown in dynamic_content(), you can build views either in the "nested" - -- notation, or "by hand". You can of course also combine both ways, for + -- notation, or "by hand". You can of course also combine both ways, for -- example if you want to dynamically build equally behaving view "blocks" -- here is a simple example that creates a note-octave-matrix with buttons @@ -297,33 +242,32 @@ function dynamic_building_matrix() local vb = renoise.ViewBuilder() local CONTENT_MARGIN = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN - local BUTTON_WIDTH = 2*renoise.ViewBuilder.DEFAULT_CONTROL_HEIGHT + local BUTTON_WIDTH = 2 * renoise.ViewBuilder.DEFAULT_CONTROL_HEIGHT local NUM_OCTAVES = 10 local NUM_NOTES = 12 local note_strings = { - "C-", "C#", "D-", "D#", "E-", "F-", + "C-", "C#", "D-", "D#", "E-", "F-", "F#", "G-", "G#", "A-", "A#", "B-" } -- create the main content column, but don't add any views yet: - local dialog_content = vb:column { - margin = CONTENT_MARGIN + local dialog_content = vb:vertical_aligner { + margin = CONTENT_MARGIN, } - for octave = 1,NUM_OCTAVES do + for octave = 1, NUM_OCTAVES do -- create a row for each octave local octave_row = vb:row {} - - for note = 1,NUM_NOTES do + for note = 1, NUM_NOTES do local note_button = vb:button { + id = "button" .. octave .. note, width = BUTTON_WIDTH, - text = note_strings[note]..tostring(octave - 1), - + text = note_strings[note] .. tostring(octave - 1), notifier = function() -- functions do memorize all values in the scope they are - -- nested in (upvalues), so we can simply access the note and + -- nested in (upvalues), so we can simply access the note and -- octave from the loop here: show_status(("note_button %s%d got pressed"):format( note_strings[note], octave - 1)) @@ -331,28 +275,26 @@ function dynamic_building_matrix() } -- add the button by "hand" into the octave_row - octave_row:add_child(note_button) + octave_row:add_view(note_button) end - dialog_content:add_child(octave_row) + dialog_content:add_view(octave_row) end renoise.app():show_custom_dialog( "Batch Building Views", dialog_content) end - -------------------------------------------------------------------------------- -- aligners_and_auto_sizing -function aligners_and_auto_sizing() - +local function aligners_and_auto_sizing() -- beside of "stacking" views in columns and rows, its sometimes also useful -- to align some parts of the views for example centered or right -- this is what the view builders "horizontal_aligner" and "vertical_aligner" -- building blocks are for. - + -- related to this topic, we'll also show how you can auto size views: (size -- a view relative to its parents size). This is done by simply specifying -- percentage values for the sizes, like: width = "100%" @@ -368,217 +310,244 @@ function aligners_and_auto_sizing() id = "dialog_content", margin = DIALOG_MARGIN, spacing = CONTENT_SPACING, - - -- first center a text. We don't necessarily need aligners for this, - -- but simply resize the text to fill the entrire row in the column, - -- then tell the text view how it should align its content: - vb:text { - text = "horizontal_aligner", - width = "100%", - align = "center", - font = "bold" - }, - - -- add a large Textfield (this will be our largest view the other - -- views will align to) - vb:textfield { - value = "Large Text field", - width = 300 - }, - - -- align a text to the right, using 'align_horizontal' - -- aligners do have margins & spacings, just like columns, rows have, which - -- we now use to place a text 20 pixels on the right, top, bottom: - vb:horizontal_aligner { - mode = "right", - margin = 20, - + views = { + -- first center a text. We don't necessarily need aligners for this, + -- but simply resize the text to fill the entrire row in the column, + -- then tell the text view how it should align its content: vb:text { - text = "I'm right and margined", + text = "horizontal_aligner", + width = "100%", + align = "center", + font = "bold" }, - }, - - -- align a set of buttons to the left, using 'align_horizontal' - -- well, this is actually just what "row" does, but horizontal_aligner - -- automatically uses a width of "100%", while you can not use a "row" - -- with a relative width... - vb:horizontal_aligner { - mode = "left", - - vb:button { - text = "[", - width = 40 + -- add a large Textfield (this will be our largest view the other + -- views will align to) + vb:textfield { + value = "Large Text field", + width = 300 }, - vb:button { - text = "Left", - width = 80 + -- align a text to the right, using 'align_horizontal' + -- aligners do have margins & spacings, just like columns, rows have, which + -- we now use to place a text 20 pixels on the right, top, bottom: + vb:horizontal_aligner { + background = "group", + mode = "right", + margin = 5, + views = { + vb:text { + text = "I'm right and margined", + }, + } }, - vb:button { - text = "]", - width = 20 - } - }, - - -- align a set of buttons to the right, using 'align_horizontal' - vb:horizontal_aligner { - mode = "right", - - vb:button { - text = "[", - width = 40 + -- align a set of buttons to the left, using 'align_horizontal' + -- well, this is actually just what "row" does, but horizontal_aligner + -- automatically uses a width of "100%", while you can not use a "row" + -- with a relative width... + vb:horizontal_aligner { + mode = "left", + views = { + vb:button { + text = "[", + width = 40 + }, + vb:button { + text = "Left", + width = 80 + }, + vb:button { + text = "]", + width = 20 + } + } }, - vb:button { - text = "Right", - width = 80 + -- align a set of buttons to the right, using 'align_horizontal' + vb:horizontal_aligner { + mode = "right", + views = { + vb:button { + text = "[", + width = 40 + }, + vb:button { + text = "Right", + width = 80 + }, + vb:button { + text = "]", + width = 20 + } + } }, - vb:button { - text = "]", - width = 20 - } - }, - - -- align a set of buttons centered, using 'align_horizontal' - vb:horizontal_aligner { - mode = "center", - - vb:button { - text = "Center", - width = 80 - } - }, - - -- again a set of buttons centered, but with some spacing - vb:horizontal_aligner { - mode = "center", - spacing = 8, - - vb:button { - text = "[", - width = 40 + -- align a set of buttons centered, using 'align_horizontal' + vb:horizontal_aligner { + mode = "center", + views = { + vb:button { + text = "Center", + width = 80 + } + } }, - vb:button { - text = "Spacing = 8", - width = 80 + -- again a set of buttons centered, but with some spacing + vb:horizontal_aligner { + mode = "center", + spacing = 8, + views = { + vb:button { + text = "[", + width = 40 + }, + vb:button { + text = "Spacing = 8", + width = 80 + }, + vb:button { + text = "]", + width = 20 + } + } }, - vb:button { - text = "]", - width = 20 - } - }, - - -- show the "justify" align style - vb:horizontal_aligner { - mode = "justify", - spacing = 8, - - vb:button { - text = "[", - width = 40 + -- show the "justify" align style + vb:horizontal_aligner { + mode = "justify", + spacing = 8, + views = { + vb:button { + text = "[", + width = 40 + }, + vb:button { + text = "Justify", + width = 80 + }, + vb:button { + text = "]", + width = 20 + } + } }, - vb:button { - text = "Justify", - width = 80 + -- show the "distribute" align style + vb:horizontal_aligner { + mode = "distribute", + spacing = 8, + views = { + vb:button { + text = "[", + width = 40 + }, + vb:button { + text = "Distribute", + width = 80 + }, + vb:button { + text = "]", + width = 20 + } + } }, - vb:button { - text = "]", - width = 20 - } - }, - - -- show the "distribute" align style - vb:horizontal_aligner { - mode = "distribute", - spacing = 8, - - vb:button { - text = "[", - width = 40 + -- add a space before we start with a "new category" + vb:space { + height = 20 }, - vb:button { - text = "Distribute", - width = 80 + -- lets use a stack with relative width, height properties: + vb:text { + text = "stack", + font = "bold", + width = "100%", + align = "center" }, - vb:button { - text = "]", - width = 20 - } - }, - - - -- add a space before we start with a "new category" - vb:space { - height = 20 - }, - - -- lets use/show relative width, height properties: - vb:text { - text = "relative sizes", - font = "bold", - width = "100%", - align = "center" - }, - - - -- create a aligner again, but this time just to stack - -- some views: - vb:horizontal_aligner { - width = "100%", - - vb:button { - text = "20%", - width = "20%" + vb:stack { + background = "plain", + width = "100%", + views = { + vb:row { + width = 80, + height = 60, + origin = { 10, 10 }, + style = "group", + }, + vb:button { + origin = { x = 20, y = 20 }, + width = 100, + height = 30, + text = "Button in stack" + }, + vb:horizontal_aligner { + mode = "right", + margin = 10, + origin = { 0, 60 }, + width = "100%", + views = { + vb:text { + style = "strong", + text = "Text in stack" + } + } + } + } + }, + -- add a space before we start with a "new category" + vb:space { + height = 20 + }, + -- lets use/show relative width, height properties: + vb:text { + text = "relative sizes", + font = "bold", + width = "100%", + align = "center" }, + -- create a aligner again, but this time just to distribute + -- some views: + vb:horizontal_aligner { + width = "100%", + views = { + vb:button { + text = "20%", + width = "20%" + }, + vb:button { + text = "80%", + width = "80%" + }, + } + }, + -- again a space before we start with a "new category" + vb:space { + height = 20 + }, + -- not lets create a button that toggles another view. when toggling, we + -- do update the main racks size which also updates the dialogs size: + vb:text { + text = "resize racks & dialogs", + width = "100%", + align = "center", + font = "bold" + }, + -- add a button that hides the other view: vb:button { - text = "80%", - width = "80%" + text = "Click me", + notifier = function() + -- toggle visibility of the view on each click + vb.views.hide_me_text.visible = not vb.views.hide_me_text.visible + end, }, - }, - - - -- again a space before we start with a "new category" - vb:space { - height = 20 - }, - - -- not lets create a button that toggles another view. when toggling, we - -- do update the main racks size which also updates the dialogs size: - vb:text { - text = "resize racks & dialogs", - width = "100%", - align = "center", - font = "bold" - }, - - -- add a button that hides the other view: - vb:button { - text = "Click me", - notifier = function() - -- toggle visibility of the view on each click - vb.views.hide_me_text.visible = not vb.views.hide_me_text.visible - - -- and update the main content view size and thus also the dialog size - vb.views.dialog_content:resize() - end, - }, - - -- the text view that we are going to show/hide - vb:text { - id = "hide_me_text", - text = "Click the button above to hide this view", - }, + -- the text view that we are going to show/hide + vb:text { + id = "hide_me_text", + text = "Click the button above to hide this view", + }, + } } - - renoise.app():show_custom_dialog( - "Aligning & Auto Sizing", dialog_content) -end + renoise.app():show_custom_dialog("Aligning & Auto Sizing", dialog_content) +end -------------------------------------------------------------------------------- -- available_backgrounds -function available_backgrounds() - +local function available_backgrounds() -- lets go on by simply demonstrating the available views, starting with all -- background styles: @@ -592,88 +561,99 @@ function available_backgrounds() -- columns local group_back = vb:column { margin = CONTROL_MARGIN, - style = "group", - vb:text{ - text = "style = 'group'" + background = "group", + views = { + vb:text { + text = "style = 'group'" + } } } local plain_back = vb:column { margin = CONTROL_MARGIN, - style = "plain", - vb:text{ - text = "style = 'plain'" + background = "plain", + views = { + vb:text { + text = "style = 'plain'" + } } } local body_back = vb:column { margin = CONTROL_MARGIN, - style = "body", - vb:text{ - text = "style = 'body'" + background = "body", + views = { + vb:text { + text = "style = 'body'" + } } } local panel_back = vb:column { margin = CONTROL_MARGIN, - style = "panel", - vb:text{ - text = "style = 'panel'" + background = "panel", + views = { + vb:text { + text = "style = 'panel'" + } } } - + local border_back = vb:column { margin = CONTROL_MARGIN, - style = "border", - vb:text{ - text = "style = 'border'" + background = "border", + views = { + vb:text { + text = "style = 'border'" + } } } - + local multiline_text = vb:column { margin = CONTROL_MARGIN, - vb:multiline_text{ - width = 160, - height = 50, - text = [[ + views = { + vb:multiline_text { + width = 160, + height = 50, + text = [[ multiline_text: Long texts can be scrolled and/or autoformated with a 'multiline_text'. ]] + } } } - - -- and also use a non modal dialog this time: + + -- and also use a non modal dialog this time: renoise.app():show_custom_dialog( - "Backgrounds & Text", + "Backgrounds & Text", vb:column { margin = DIALOG_MARGIN, spacing = DIALOG_SPACING, uniform = true, - - group_back, - plain_back, - body_back, - panel_back, - border_back, - multiline_text + views = { + group_back, + plain_back, + body_back, + panel_back, + border_back, + multiline_text + } } ) end - -------------------------------------------------------------------------------- -- available_controls -function available_controls() - - -- now we create a dialog with all available controls (things that let the - -- user change "values"), so you get an idea how all the views look like, +local function available_controls() + -- now we create a dialog with all available controls (things that let the + -- user change "values"), so you get an idea how all the views look like, -- which views to choose from when creating a new custom GUIs. -- - -- but one note about controls & "values" in general first: as you'll see + -- but one note about controls & "values" in general first: as you'll see -- below, we do attach notifiers to the values of the controls. Notifiers are - -- callback functions that are called as soon as the user changed the views + -- callback functions that are called as soon as the user changed the views -- value through the GUI. To maintain something like an external state that -- you are going to use outside the view, make sure you do keep the views value -- and "your" value in sync. @@ -691,17 +671,17 @@ function available_controls() -- max = 0x7f -- } -- - -- there is another way of dealing with "values", which we will describe in the - -- next example more in detail. Basically you can also pass over an Observable - -- object to the view (not the raw number, boolen), which then will be used by - -- the view instead of its onw value. Any changes to this value can then tracked + -- there is another way of dealing with "values", which we will describe in the + -- next example more in detail. Basically you can also pass over an observable + -- object to the view (not the raw number, boolean), which then will be used by + -- the view instead of its onw value. Any changes to this value can then tracked -- outside of this view. This often is very useful to seperate the GUI code from -- the controller and data. Here is a simple example: -- -- -- (the controller part of your script) -- options.current_velocity = 0x7f -- options.current_velocity.add_notifier(current_value_changed_function) - + -- -- (and the GUI) -- vb:slider { -- bind = options.current_velocity, -- only gets a reference passed @@ -710,487 +690,732 @@ function available_controls() -- } -- we memorize a reference to the dialog this time, to close it + ---@type renoise.Dialog|nil local control_example_dialog = nil - + local vb = renoise.ViewBuilder() - - local DIALOG_MARGIN = - renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN - - local CONTENT_SPACING = - renoise.ViewBuilder.DEFAULT_CONTROL_SPACING - - local CONTENT_MARGIN = - renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN - - local DEFAULT_CONTROL_HEIGHT = - renoise.ViewBuilder.DEFAULT_CONTROL_HEIGHT - + + local DIALOG_MARGIN = + renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN + + local CONTENT_SPACING = + renoise.ViewBuilder.DEFAULT_CONTROL_SPACING + + local CONTENT_MARGIN = + renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN + + local DEFAULT_CONTROL_HEIGHT = + renoise.ViewBuilder.DEFAULT_CONTROL_HEIGHT + local DEFAULT_DIALOG_BUTTON_HEIGHT = - renoise.ViewBuilder.DEFAULT_DIALOG_BUTTON_HEIGHT - - local DEFAULT_MINI_CONTROL_HEIGHT = - renoise.ViewBuilder.DEFAULT_MINI_CONTROL_HEIGHT - + renoise.ViewBuilder.DEFAULT_DIALOG_BUTTON_HEIGHT + + local DEFAULT_MINI_CONTROL_HEIGHT = + renoise.ViewBuilder.DEFAULT_MINI_CONTROL_HEIGHT + local TEXT_ROW_WIDTH = 80 ---- CONTROL ROWS - + -- textfield local textfield_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:textfield" - }, - vb:textfield { - width = 120, - text = "Edit me", - notifier = function(text) - show_status(("textfield value changed to '%s'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:textfield" + }, + vb:textfield { + width = 120, + text = "Edit me", + notifier = function(text) + show_status(("textfield value changed to '%s'"): format(text)) - end + end + } } } --- multiline_textfield row local mltextfield_row = vb:row { - vb:text { - width = 80, - text = "vb:ml_textfield" - }, - vb:multiline_textfield { - width = 120, - height = 60, - value = "Paragraphs are separated with \\n's.\n\nEdit me", - notifier = function(value) - show_status(("multiline_textfield value changed to '%s'"): + views = { + vb:text { + width = 80, + text = "vb:ml_textfield" + }, + vb:multiline_textfield { + width = 120, + height = 60, + value = "Paragraphs are separated with \\n's.\n\nEdit me", + notifier = function(value) + show_status(("multiline_textfield value changed to '%s'"): format(value)) - end - }, + end + }, + } + } + + -- link + local link_row = vb:row { + spacing = CONTENT_SPACING, + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:link" + }, + vb:column { + uniform = true, + views = { + vb:link { + text = "scripting.renoise.com", + style = "strong", + notifier = function() + renoise.app():open_url("https://scripting.renoise.com") + end, + }, + vb:link { + active = false, + text = "disabled", + style = "strong", + notifier = function() + show_status("this will never be shown") + end, + }, + vb:link { + text = "Hit me too", + width = "100%", + align = "center", + font = "italic", + -- we also can handle presses, releases separately + pressed = function() + show_status("link was pressed") + end, + released = function() + show_status("link was released") + end, + } + } + } + } } - - -- bitmapview + + -- bitmapview local bitmapview_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:bitmap" - }, - vb:bitmap { - -- recolor to match the GUI theme: - mode = "body_color", - -- bitmaps names should be specified with a relative path using - -- your tool script bundle path as base: - bitmap = "Bitmaps/RenoiseLua.bmp", - notifier = function() - show_status("bitmapview was pressed") - end - }, - --[[ TODO vb:bitmap { - mode = "alpha", - bitmap = "Bitmaps/RenoiseLua.png", - notifier = function() - show_status("bitmapview was pressed") - end - } ]] + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:bitmap" + }, + vb:bitmap { + mode = "transparent", + -- bitmaps names should be specified with a relative path using + -- your tool script bundle path as base: + bitmap = "Bitmaps/RenoiseLua.png", + -- enable, to recolor the bitmap to match the GUI theme: + color = "selected_button_back", + notifier = function() + show_status("bitmapview was pressed") + end + }, + } } - - -- button + + -- button local button_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:button" - }, - vb:button { - text = "Hit me", - width = 60, - notifier = function() - show_status("button was hit") - end, - }, - vb:button { - -- buttons can also use bitmaps as icons: - bitmap = "Bitmaps/MiniPiano.bmp", - width = 20, - notifier = function() - show_status("button with bitmap was hit") - end, - }, - - vb:button { - -- buttons can also have custom text/back colors - text = "Color", - width = 30, - color = {0x22, 0xaa, 0xff}, - -- and we also can handle presses, releases separately - pressed = function() - show_status("button with custom colors was pressed") - end, - released = function() - show_status("button with custom colors was released") - end, + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:button" + }, + vb:button { + text = "Hit me", + width = 60, + notifier = function() + show_status("button was hit") + end, + }, + vb:button { + -- buttons can also use bitmaps as icons: + bitmap = "Bitmaps/MiniPiano.bmp", + width = 20, + notifier = function() + show_status("button with bitmap was hit") + end, + }, + vb:button { + -- buttons can also have custom text/back colors + text = "Color", + width = 50, + color = { 0x22, 0xaa, 0xff }, + secondary_color = { 0xff, 0xff, 0 }, + align = "center", + font = "italic", + -- and we also can handle presses, releases separately + pressed = function() + show_status("button with custom colors was pressed") + end, + released = function() + show_status("button with custom colors was released") + end, + } } } -- checkbox local checkbox_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:checkbox" - }, - vb:checkbox { - value = true, - notifier = function(value) - show_status(("checkbox value changed to '%s'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:checkbox" + }, + vb:checkbox { + value = true, + notifier = function(value) + show_status(("checkbox value changed to '%s'"): format(tostring(value))) - end, + end, + } } } - -- switch + -- switch local switch_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:switch" - }, - vb:switch { - id = "switch", - width = 100, - value = 2, - items = {"A", "B", "C"}, - notifier = function(new_index) - local switch = vb.views.switch - show_status(("switch value changed to '%s'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:switch" + }, + vb:switch { + id = "switch", + width = 100, + value = 2, + items = { "A", "B", "C" }, + notifier = function(new_index) + ---@type renoise.Views.Switch + local switch = vb.views.switch + show_status(("switch value changed to '%s'"): format(switch.items[new_index])) - end + end + } } } - -- popup + -- popup local popup_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:popup" - }, - vb:popup { - id = "popup", - width = 100, - value = 2, - items = {"First", "Second", "Third"}, - notifier = function(new_index) - local popup = vb.views.popup - show_status(("popup value changed to '%s'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:popup" + }, + vb:popup { + id = "popup", + width = 100, + value = 2, + items = { "First", "Second", "Third" }, + notifier = function(new_index) + ---@type renoise.Views.Popup + local popup = vb.views.popup + show_status(("popup value changed to '%s'"): format(popup.items[new_index])) - end + end + } } } - -- chooser + -- chooser local chooser_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:chooser" - }, - vb:chooser { - id = "chooser", - value = 4, - items = {"First", "Second", "Third", "Fourth"}, - notifier = function(new_index) - local chooser = vb.views.chooser - show_status(("chooser value changed to '%s'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:chooser" + }, + vb:chooser { + id = "chooser", + value = 4, + items = { "First", "Second", "Third", "Fourth" }, + notifier = function(new_index) + ---@type renoise.Views.Chooser + local chooser = vb.views.chooser + show_status(("chooser value changed to '%s'"): format(chooser.items[new_index])) - end + end + } } } - -- valuebox local valuebox_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:valuebox" - }, - vb:valuebox { - min = 0, - max = 55, - value = 5, - tostring = function(value) - return ("0x%.2X"):format(value) - end, - tonumber = function(str) - return tonumber(str, 0x10) - end, - notifier = function(value) - show_status(("valuebox value changed to '%d'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:valuebox" + }, + vb:valuebox { + min = -100, + max = math.huge, + value = 5, + notifier = function(value) + show_status(("valuebox value changed to '%d'"): format(value)) - end - } + end + } + } } -- valuebox_deactivated local valuebox_deactivated_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "(active=false)" - }, - vb:valuebox { - active = false, -- any control can be (de)activated - min = 0, - max = 55, - value = 5, - tostring = function(value) - return ("0x%.2X"):format(value) - end, - tonumber = function(str) - return tonumber(str, 0x10) - end, - notifier = function(value) - show_status(("valuebox value changed to '%d'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "(active=false)" + }, + vb:valuebox { + active = false, -- any control can be (de)activated + min = 0, + max = 55, + value = 5, + tostring = function(value) + return ("0x%.2X"):format(value) + end, + tonumber = function(str) + return tonumber(str, 0x10) + end, + notifier = function(value) + show_status(("valuebox value changed to '%d'"): format(value)) - end + end + } } } - -- valuefield + -- valuefield local valuefield_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:valuefield" - }, - vb:valuefield { - min = 0.0, - max = math.db2lin(6.0), - value = 1.0, - - tostring = function(value) - local db = math.lin2db(value) - if db > math.infdb then - return ("%.03f dB"):format(db) - else - return "-INF dB" - end - end, - - tonumber = function(str) - if str:lower():find("-inf") then - return 0.0 - else - local db = tonumber(str) - if (db ~= nil) then - return math.db2lin(db) + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:valuefield" + }, + vb:valuefield { + min = 0.0, + max = math.db2lin(6.0), + value = 1.0, + + tostring = function(value) + local db = math.lin2db(value) + if db > math.infdb then + return ("%.03f dB"):format(db) + else + return "-INF dB" end + end, + + tonumber = function(str) + if str:lower():find("-inf") then + return 0.0 + else + local db = tonumber(str) + if (db ~= nil) then + return math.db2lin(db) + end + end + end, + + notifier = function(value) + show_status(("valuefield value changed to '%f'"): + format(value)) end - end, - - notifier = function(value) - show_status(("valuefield value changed to '%f'"): + } + } + } + + -- scrollbar + local scrollbar_row = vb:row { + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:scrollbar" + }, + vb:scrollbar { + min = 50, + max = 100, + value = 65, + pagestep = 25, + autohide = true, + background = "plain", + notifier = function(value) + show_status(("scrollbar offset changed to '%.0f'"): format(value)) - end + end + } } } - + -- slider local slider_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:slider" - }, - vb:slider { - min = 1.0, - max = 100, - value = 20.0, - notifier = function(value) - show_status(("slider value changed to '%.1f'"): - format(value)) - end + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:slider" + }, + vb:slider { + polarity = "bipolar", + min = 1.0, + max = 100, + value = 20.0, + notifier = function(value) + show_status(("slider value changed to '%.1f'"):format(value)) + end + } } } -- minislider local minislider_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:minislider" - }, - vb:minislider { - min = 0, - max = 1, - value = 0.5, - notifier = function(value) - show_status(("mini slider value changed to '%.1f'"): - format(value)) - end + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:minislider" + }, + vb:minislider { + min = 0, + max = 1, + value = 0.5, + polarity = "bipolar", + notifier = function(value) + show_status(("mini slider value changed to '%.1f'"):format(value)) + end + } } } - - + -- rotary local rotary_row = vb:row { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:rotary" - }, - vb:rotary { - min = 2, - max = 4, - value = 3.5, - width = 2*DEFAULT_CONTROL_HEIGHT, - height = 2*DEFAULT_CONTROL_HEIGHT, - notifier = function(value) - show_status(("rotaty encoder value changed to '%.1f'"): - format(value)) - end + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:rotary" + }, + vb:rotary { + min = 2, + max = 4, + polarity = "bipolar", + value = 3.5, + width = 2 * DEFAULT_CONTROL_HEIGHT, + height = 2 * DEFAULT_CONTROL_HEIGHT, + notifier = function(value) + show_status(("rotaty encoder value changed to '%.1f'"):format(value)) + end + } } } - - + -- v sliders local vslider_column = vb:column { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:(mini)slider" - }, - vb:row { - vb:slider { - min = 1.0, - max = 100, - value = 20.0, - width = DEFAULT_CONTROL_HEIGHT, - height = 120, - notifier = function(value) - show_status(("v slider value changed to '%.1f'"): - format(value)) - end + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:v_sliders" }, - vb:minislider { - min = 1.0, - max = 100, - value = 20.0, - width = DEFAULT_MINI_CONTROL_HEIGHT, - height = 60, - notifier = function(value) - show_status(("v mini slider value changed to '%.1f'"): - format(value)) - end + vb:row { + spacing = 4, + views = { + vb:scrollbar { + min = 0, + max = 100, + value = 15, + pagestep = 25, + background = "plain", + width = DEFAULT_CONTROL_HEIGHT - 2, + height = 120, + notifier = function(value) + show_status(("v scrollbar offset changed to '%.0f'"):format(value)) + end + }, + vb:slider { + min = 1.0, + max = 100, + value = 20.0, + width = DEFAULT_CONTROL_HEIGHT, + height = 120, + notifier = function(value) + show_status(("v slider value changed to '%.1f'"):format(value)) + end + }, + vb:minislider { + min = 1.0, + max = 100, + value = 20.0, + width = DEFAULT_MINI_CONTROL_HEIGHT, + height = 60, + notifier = function(value) + show_status(("v mini slider value changed to '%.1f'"):format(value)) + end + } + } } } } - - + -- xy pad column local xypad_column = vb:column { - vb:text { - width = TEXT_ROW_WIDTH, - text = "vb:xypad" - }, - vb:column { - style = "border", -- cosmetics - margin = 4, - - vb:xypad { - width = 80, - height = 80, - value = {x=0.75, y=0.25}, - snapback = {x=0.5, y=0.5}, - notifier = function(value) - show_status(("xy pad value changed to '%.2f, %.2f'"): + views = { + vb:text { + width = TEXT_ROW_WIDTH, + text = "vb:xypad" + }, + vb:column { + style = "border", -- cosmetics + margin = 4, + + vb:xypad { + width = 80, + height = 80, + value = { x = 0.75, y = 0.25 }, + snapback = { x = 0.5, y = 0.5 }, + notifier = function(value) + show_status(("xy pad value changed to '%.2f, %.2f'"): format(value.x, value.y)) - end + end + } } } } - - + -- close button - local close_button_row = vb:horizontal_aligner { mode = "right", - - vb:button { - text = "Close", - width = 60, - height = DEFAULT_DIALOG_BUTTON_HEIGHT, - notifier = function() - control_example_dialog:close() - end, + views = { + vb:button { + text = "Close", + width = 60, + height = DEFAULT_DIALOG_BUTTON_HEIGHT, + notifier = function() + if control_example_dialog then + control_example_dialog:close() + end + end, + } } } - - + + ---- MAIN CONTENT & LAYOUT - + local dialog_content = vb:column { margin = DIALOG_MARGIN, spacing = CONTENT_SPACING, - - vb:row{ - spacing = 4*CONTENT_SPACING, - - vb:column { - spacing = CONTENT_SPACING, - - textfield_row, - mltextfield_row, - bitmapview_row - }, - - vb:column { - spacing = CONTENT_SPACING, - - button_row, - checkbox_row, - switch_row, - - vb:space {height = DEFAULT_CONTROL_HEIGHT}, - popup_row, - chooser_row, - - vb:space {height = DEFAULT_CONTROL_HEIGHT}, - valuefield_row, - valuebox_row, - valuebox_deactivated_row, + views = { + vb:row { + spacing = 4 * CONTENT_SPACING, + views = { + vb:column { + spacing = CONTENT_SPACING, + views = { + textfield_row, + mltextfield_row, + link_row, + bitmapview_row, + } + }, + + vb:column { + spacing = CONTENT_SPACING, + views = { + button_row, + checkbox_row, + switch_row, + vb:space { height = DEFAULT_CONTROL_HEIGHT }, + popup_row, + chooser_row, + vb:space { height = DEFAULT_CONTROL_HEIGHT }, + valuefield_row, + valuebox_row, + valuebox_deactivated_row, + }, + }, + + vb:column { + spacing = CONTENT_SPACING, + views = { + scrollbar_row, + slider_row, + minislider_row, + rotary_row, + vb:row { + views = { + vslider_column, + xypad_column + } + } + } + } + } }, + close_button_row + } + } - vb:column { - spacing = CONTENT_SPACING, - slider_row, - minislider_row, - rotary_row, - - vb:row{ vslider_column, xypad_column } - } - }, - - -- close - close_button_row - } - - -- DIALOG - + control_example_dialog = renoise.app():show_custom_dialog( "Available Controls", dialog_content ) - end +-------------------------------------------------------------------------------- + +-- canvas_view + +local function canvas_view() + -- A canvas view lets you draw and handle mouse events in a completely + -- customisable way. + -- + -- Canvas content is cached in a texture and **not** hardware accelerated, + -- so it's not suitable for animations, but for static content such as + -- custom backgrounds or bitmap-like views. + -- + -- In this example we are using a canvas to draw a custom background view + -- which is updated when the mouse is hovering in the view. + + local vb = renoise.ViewBuilder() + + local CANVAS_WIDTH = 250 + local CANVAS_HEIGHT = 250 + + local DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN + local CONTENT_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING + + local canvas_background = vb:canvas { + id = "canvas_view", + width = CANVAS_WIDTH, + height = CANVAS_HEIGHT, + -- we do not cover, paint on the entire canvas + -- if we would, set to "plain" to speed up drawing + mode = "transparent", + render = function(context) + -- Build a star path. + context:move_to(128, 28) + context:line_to(157, 87) + context:line_to(223, 97) + context:line_to(175, 143) + context:line_to(186, 208) + context:line_to(128, 178) + context:line_to(69, 208) + context:line_to(80, 143) + context:line_to(32, 97) + context:line_to(98, 87) + context:close_path() + -- Fill the star with yellow color. + local yellow = { 200, 200, 20, 255 } + context.fill_color = yellow + context:fill() + -- Draw the star with a thick red stroke and rounded points. + context.line_join = "rounded" + context.line_width = 12 + local red = { 200, 0, 50, 255 } + context.stroke_color = red + context:stroke() + -- Draw the star again with a dashed thinner orange stroke. + context:set_line_dash({ 21, 9, 1, 9, 7, 9, 1, 9 }) + context.line_dash_offset = 10.0 + context.line_cap = "circle" + context.line_width = 6; + local orange = { 250, 100, 10, 255 } + context.stroke_color = orange + context:stroke() + -- Add a shine layer over the star. + local white_000 = { 255, 255, 255, 0 } + local white_200 = { 255, 255, 255, 200 } + context:set_fill_linear_gradient(64, 0, 192, 256); + context:add_fill_color_stop(0.30, white_000); + context:add_fill_color_stop(0.35, white_200); + context:add_fill_color_stop(0.45, white_200); + context:add_fill_color_stop(0.50, white_000); + context.global_composite_operation = "source_atop"; + context:fill_rect(0, 0, context.size.width, context.size.height); + end, + } + + local mouse_pos = { x = -1, y = -1 } + local canvas_overlay = vb:canvas { + id = "canvas_overlay", + width = CANVAS_WIDTH, + height = CANVAS_HEIGHT, + mouse_events = { "enter", "exit", "move" }, + mouse_handler = function(event) + if event.type == "exit" or #event.hover_views > 0 then + mouse_pos = { x = -1, y = -1 } + else + mouse_pos = { x = event.position.x, y = event.position.y } + end + ---@type renoise.Views.Canvas + local overlay = vb.views.canvas_overlay + overlay:update() + end, + render = function(context) + -- Draw shine layer at the cursor position. + if mouse_pos.x > 0 and mouse_pos.y > 0 then + context:set_fill_radial_gradient( + mouse_pos.x, mouse_pos.y, 10, mouse_pos.x + 20, mouse_pos.y + 20, 50) + context:add_fill_color_stop(0.20, { 255, 255, 255, 80 }) + context:add_fill_color_stop(0.35, { 255, 255, 255, 100 }) + context:add_fill_color_stop(0.45, { 255, 255, 255, 200 }) + context:add_fill_color_stop(0.50, { 255, 255, 255, 0 }) + context:fill_rect(mouse_pos.x - 50, mouse_pos.y - 50, 100, 100) + end + end + } + + local dialog_content = vb:column { + margin = DIALOG_MARGIN, + views = { + vb:stack { + id = "stack", + autosize = true, + views = { + canvas_background, + canvas_overlay, + vb:link { + id = "link", + origin = { 0, CANVAS_HEIGHT }, + text = "HTML5 Canvas Tutorial", + notifier = function() + renoise.app():open_url( + "https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial" + ) + end + } + } + } + } + } + + renoise.app():show_custom_dialog("Canvas View", dialog_content) +end + -------------------------------------------------------------------------------- -- documents_and_views --- as already noted in 'available_controls'. views can also be attached to --- external document values, in order to seperate the controller code from the --- view code. We're going to do this tight now and do start by create a very --- simple example document. Please have a look at Renoise.Document.API for more +-- as already noted in 'available_controls'. views can also be attached to +-- external document values, in order to seperate the controller code from the +-- view code. We're going to do this tight now and do start by create a very +-- simple example document. Please have a look at Renoise.Document.API for more -- detail about such documents - -- DOCUMENT -- create a simple document +---@class ExampleDocument +---@field my_flag renoise.Document.ObservableBoolean +---@field some_velocity renoise.Document.ObservableNumber +---@field pad_x renoise.Document.ObservableNumber +---@field pad_y renoise.Document.ObservableNumber + +---@type ExampleDocument local example_document = renoise.Document.create("ExampleDocument") { my_flag = false, some_velocity = 127, @@ -1201,37 +1426,35 @@ local example_document = renoise.Document.create("ExampleDocument") { -- notifier callbacks local function my_flag_notifier() local my_flag_value = example_document.my_flag.value - - show_status(("'my_flag' changed to '%s' by either the GUI ".. + + show_status(("'my_flag' changed to '%s' by either the GUI " .. "or something else..."):format(my_flag_value and "True" or "False")) end local function some_velocity_notifier() local some_velocity = example_document.some_velocity.value - show_status(("'some_velocity' value changed to '%s' by either the GUI ".. + show_status(("'some_velocity' value changed to '%s' by either the GUI " .. "or something else..."):format(some_velocity)) end local function pad_value_notifier() local x, y = example_document.pad_x.value, example_document.pad_y.value - show_status(("'pad_xy' value changed to '%.2f,%.2f' by either the GUI ".. + show_status(("'pad_xy' value changed to '%.2f,%.2f' by either the GUI " .. "or something else..."):format(x, y)) end --- attach to the document +-- attach to the document example_document.my_flag:add_notifier(my_flag_notifier) example_document.some_velocity:add_notifier(some_velocity_notifier) example_document.pad_x:add_notifier(pad_value_notifier) example_document.pad_y:add_notifier(pad_value_notifier) - -- GUI -function documents_and_views() - +local function documents_and_views() local vb = renoise.ViewBuilder() local DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN @@ -1239,61 +1462,351 @@ function documents_and_views() -- now we pass over the document struct to the views local checkbox_row = vb:row { - vb:text { - text = "my_flag", width = 80 - }, - vb:checkbox { - bind = example_document.my_flag --> bind + views = { + vb:text { + text = "my_flag", + width = 80 + }, + vb:checkbox { + bind = example_document.my_flag --> bind + } } } - + local valuebox_row = vb:row { - vb:text { - text = "some_velocity", width = 80 - }, - vb:valuebox { - bind = example_document.some_velocity, --> bind - min = 0, - max = 0x7f + views = { + vb:text { + text = "some_velocity", + width = 80 + }, + vb:valuebox { + bind = example_document.some_velocity, --> bind + min = 0, + max = 0x7f + } } } - + local xypad_row = vb:row { - vb:xypad { - bind = { --> bind - x = example_document.pad_x, - y = example_document.pad_y - }, - width = valuebox_row.width, + views = { + vb:xypad { + bind = { --> bind + x = example_document.pad_x, + y = example_document.pad_y + }, + width = valuebox_row.width, + } } } - + renoise.app():show_custom_dialog( - "Documents & Views", - + "Documents & Views", vb:column { margin = DIALOG_MARGIN, spacing = CONTENT_SPACING, uniform = true, - - vb:column { - spacing = CONTENT_SPACING, - - checkbox_row, - valuebox_row - }, - xypad_row + views = { + vb:column { + spacing = CONTENT_SPACING, + views = { + checkbox_row, + valuebox_row + } + }, + xypad_row + } } ) end +-------------------------------------------------------------------------------- + +-- overflow_and_scrollbars + +local function overflow_and_scrollbars() + local vb = renoise.ViewBuilder() + + -- views can be larger than you actually want to show. there's no generic + -- overflow handling in the Renoise view API, but there is a scrollbar + -- widget, which can be used, for example, to scroll a content view within + -- a smaller view. + + -- below is an example of how to clamp the visible area of a view with a + -- stack view and and attached scrollbar. Actual scrolling is done by changing + -- the content views origin within the parent overflow view. + + -- in addition, the stack also has a mouse handler for scrolling the content + -- on mouse wheel events. + + -- please note that this is just one way to archive scrolling. You could + -- e.g. also rebuild the visible area of your view in e.g. grid depending + -- on the offset values of the slider bar instead of moving and clipping the + -- content view's origin. + + local DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN + local CONTROL_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING + local CONTROL_HEIGHT = renoise.ViewBuilder.DEFAULT_CONTROL_HEIGHT + + -- we do limit the height of the content to this value + local MAX_CONTENT_HEIGHT = 200 + -- change this to e.g. `8` and the scroll bar will disapear + local NUMBER_OF_ITEMS_TO_SHOW = 100 + + -- create some content with a lot of entries (rows in a column) + local content = vb:column { + uniform = true, + spacing = CONTROL_SPACING + } + for i = 1, NUMBER_OF_ITEMS_TO_SHOW, 1 do + content:add_view( + vb:row { + vb:checkbox { + value = false + }, + vb:text { + text = ("This is dummy row #%s"):format(i) } + }) + end + + -- now create a vertical scrollbar which has a max value of `content.height` + -- and a visible area (page size) of MAX_CONTENT_HEIGHT. + -- + -- changes to the scroll bar offset will be forwarded as changes to the origin + -- of the content view, so it slides beneth the parent overflow. + -- + -- scroll bar properties: + -- - min & max: full area that can be scrolled (height of the content here) + -- - pagestep: visible area (maximum content height here) + -- - value: this is the offset of the slider (y origin of the content here) + -- + -- please also note that offset values bust be in range `[(max - min) - pagestep]` + -- and NOT within `[min - max]` as it is with other sliders. + + local scrollbar = vb:scrollbar { + autohide = true, + width = CONTROL_HEIGHT, + height = math.min(content.height, MAX_CONTENT_HEIGHT), + min = 0, + max = content.height, + pagestep = math.min(content.height, MAX_CONTENT_HEIGHT), + notifier = function(offset) + content.origin = { x = 0, y = -offset } + end + } + + -- now create a stack which will holds the content and set its height to a + -- size that is smaller than the content. This will clip the display of the + -- content to a smaller size. + -- + -- NB: it's important to disable the "autosize" property of the stack here + -- else it would resize itself to conver the entire content. + local overflow = vb:stack { + autosize = false, + width = content.width, + height = math.min(content.height, MAX_CONTENT_HEIGHT), + mouse_events = { "wheel" }, + mouse_handler = function(event) + -- the moue wheel changes the scroll bar offset + if event.type == "wheel" then + if event.direction == "down" then + scrollbar.value = math.min(scrollbar.max - scrollbar.pagestep, + scrollbar.value + CONTROL_HEIGHT) + elseif event.direction == "up" then + scrollbar.value = math.max(0, + scrollbar.value - CONTROL_HEIGHT) + end + end + end, + views = { content } + } + + -- the dialog content now simply shows content and scroll bar side by side + local dialog_content = vb:row { + margin = DIALOG_MARGIN, + views = { + overflow, + scrollbar + } + } + + renoise.app():show_custom_dialog("Overflow & ScrollBar", dialog_content) +end -------------------------------------------------------------------------------- --- handle_key_events +-- handle_mouse_events + +local function handle_mouse_events() + local vb = renoise.ViewBuilder() + + -- Lets create a dialog with custom mouse handler here. + -- The dialog content uses a stack as its main content view. + -- + -- This content view has 3 sub views: + -- 1. a stack which is used as a background view + -- 2. another stack with a button and a bitmap overlay + -- 3. a status bar alike text + -- + -- The content stack also has a mouse handler set, which allows to track + -- mouse events within its view boundaries. We use it here to drag around + -- the button by capturing mouse "drag" events. + -- + -- Only layout views can have mouse_handers (rack, column, aligner & stack) + -- + -- Please note that "drag" and "move" events are by default disabled. We do + -- need to enable them in the "mouse_events" property. + + local CONTENT_HEIGHT = 500 + local CONTENT_WIDTH = 500 + + local BUTTON_HEIGHT = 100 + local BUTTON_WIDTH = 100 + + -- mouse drag status + local drag_status = { + -- are we currently dragging the button? + dragging = false, + -- initial offset of the mouse cursor within the drag button + offset = { x = 0, y = 0 }, + } + + local content = vb:stack { + id = "content", + -- enable all events, so we can show the event status + -- without the status text only "up", "down" and "drag" would be needed here + mouse_events = { + "enter", "exit", "move", "drag", "down", "up", "double", "wheel" + }, + -- install the actual handler function + mouse_handler = function(event) + -- update status text from the mouse event + local mod_flags = 0 + for _, v in pairs(event.modifier_flags) do + if v then + mod_flags = mod_flags + 1 + end + end + ---@type renoise.Views.Text + local status_text_view = vb.views["status_text"] + status_text_view.text = string.format( + [[Mouse Event: type: '%s', button: '%s', direction: '%s', position: '%d,%d' +hover_view (top-most): '%s', mod_flags: '%s']], + event.type, tostring(event.button), tostring(event.direction), + event.position.x, event.position.y, + (#event.hover_views > 0) and event.hover_views[1].id or "none", + tostring(mod_flags) + ) + -- start dragging the button with a mouse down + if event.type == "down" then + -- is the drag button view under the cusor? + for _, v in pairs(event.hover_views) do + if v.id == "drag_button" then + drag_status.dragging = true + break + end + end + if drag_status.dragging then + local drag_button = vb.views["drag_button"] + drag_status.dragging = true + drag_status.offset = { + x = event.position.x - drag_button.origin.x, + y = event.position.y - drag_button.origin.y + } + end + -- stop dragging the button with a mouse up event + elseif event.type == "up" and drag_status.dragging then + drag_status.dragging = false + -- drag the button around with the mouse "drag" events + elseif event.type == "drag" and drag_status.dragging then + local drag_button = vb.views["drag_button"] + local new_origin = { + x = event.position.x - drag_status.offset.x, + y = event.position.y - drag_status.offset.y + } + -- clamp origin so the button doesn't fall out of the parent view + new_origin.x = math.max(0, + math.min(CONTENT_WIDTH - BUTTON_WIDTH, new_origin.x)) + new_origin.y = math.max(0, + math.min(CONTENT_HEIGHT - BUTTON_HEIGHT, new_origin.y)) + -- apply the new origin + drag_button.origin = new_origin + end + if drag_status.dragging then + return nil -- consume the event + else + return event -- pass event to subviews + end + end, + -- content views + views = { + -- background, covering the entire content + vb:stack { + id = "background", + width = CONTENT_WIDTH, + height = CONTENT_HEIGHT, + background = "border" + }, + -- button stack to drag around, centered by default + vb:stack { + id = "drag_button", + origin = { + CONTENT_WIDTH / 2 - BUTTON_WIDTH / 2, + CONTENT_HEIGHT / 2 - BUTTON_HEIGHT / 2 + }, + vb:button { + id = "drag_button_button", + width = BUTTON_WIDTH, + height = BUTTON_HEIGHT, + text = "Drag me around", + style = "rounded" + }, + vb:bitmap { + id = "drag_button_bitmap", + origin = { -20, -20 }, + bitmap = "Bitmaps/RenoiseLua.png", + mode = "transparent" + }, + vb:button { + id = "drag_button_click", + origin = { BUTTON_WIDTH / 4, BUTTON_HEIGHT - 20 }, + width = BUTTON_WIDTH / 2, + height = 16, + text = "Click me", + pressed = function() + show_status("Button in button got clicked and cancels drag") + end + }, + }, + -- status text on bottom + vb:text { + id = "status_text", + text = "Move mouse cursor here to show some status...", + style = "strong", + font = "mono", + width = CONTENT_WIDTH, + height = 36, + origin = { 4, CONTENT_HEIGHT - 36 }, + } + } + } + + -- wrap into a dialog content view + local DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN + + local dialog_content = vb:column { + id = "dialog_content", + margin = DIALOG_MARGIN, + views = { content } + } + + renoise.app():show_custom_dialog("Custom Mouse Handling", dialog_content) +end + +-------------------------------------------------------------------------------- -function handle_key_events() +-- handle_key_events +local function handle_key_events() -- dialogs also allow you to handle keyboard events by your own. by default -- only the escape key is used to close the dialog when focused. If you want -- to do more fancy stuff, then simply pass a key_hander_func to the custom @@ -1305,42 +1818,50 @@ function handle_key_events() local CONTENT_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING local TEXT_ROW_WIDTH = 240 - - local content_view = vb:column { + + local content_view = vb:column { margin = DIALOG_MARGIN, spacing = CONTENT_SPACING, - - vb:text { - width = TEXT_ROW_WIDTH, - text = "Press some keyboard keys:" - }, - - vb:row { - style = "group", - - vb:multiline_text { - id = "key_text", + views = { + vb:text { width = TEXT_ROW_WIDTH, - height = 78, - paragraphs = { - "key.name:", - "key.modifiers:", - "key.character:", - "key.note:", - "key.repeat:" - }, - font = "mono", + text = "Press some keyboard keys:" + }, + vb:row { + style = "group", + views = { + vb:multiline_text { + id = "key_text", + width = TEXT_ROW_WIDTH, + height = 78, + paragraphs = { + "key.name:", + "key.modifiers:", + "key.character:", + "key.note:", + "key.repeat:" + }, + font = "mono", + } + } } } } - + local function key_handler(dialog, key) - + ---@type renoise.Views.MultiLineTextField + local key_text = vb.views.key_text -- update key_text to show what we got - vb.views.key_text.paragraphs = { - ("key.name: '%s'"):format(key.name), - ("key.modifiers: '%s'"):format(key.modifiers), - ("key.character: '%s'"):format(key.character or "nil"), + local modifier_flags = table.create {} + for _, m in pairs { "shift", "control", "alt", "meta" } do + if key.modifier_flags[m] then + modifier_flags:insert(m) + end + end + key_text.paragraphs = { + ("key.name: '%s'"):format(key.name), + ("key.modifier_flags: '%s'"):format(modifier_flags:concat(",")), + ("key.character: '%s'"):format(key.character or "nil"), ("key.note: '%s'"):format(tostring(key.note) or "nil"), ("key.repeated: '%s'"):format(key.repeated and "true" or "false") } @@ -1350,74 +1871,80 @@ function handle_key_events() dialog:close() end end - + -- show a dialog as usual, but this time also pass a keyboard handler ref renoise.app():show_custom_dialog( - "Handling Keyboard Events", content_view, key_handler) - + "Handling Keyboard Events", + content_view, + key_handler) end - -------------------------------------------------------------------------------- -function midi_mapping() - +local function midi_mapping() -- Tools can create their own MIDI mappings, and GUIs created from tools can - -- also make use of MIDI mapping frames: MIDI mapping frames are colored + -- also make use of MIDI mapping frames: MIDI mapping frames are colored -- overlays that are only visible when the MIDI mapping dialog in Renoise is - -- open. When visible, they show the currently assigned MIDI mappings and also + -- open. When visible, they show the currently assigned MIDI mappings and also -- to easily bind new messages. -- - -- In this example we do create two buttons: one which allows mapping an - -- existing function ("Transport:Playback:Start Playing [Trigger]") and one + -- In this example we do create two buttons: one which allows mapping an + -- existing function ("Transport:Playback:Start Playing [Trigger]") and one -- which we created in this tool ("com.renoise.ExampleToolGui:Example Mapping") -- See "renoise.tool():add_midi_mapping" below for the handler. -- - -- The 'midi_mapping' property can be used ony everything that's a 'control' + -- The 'midi_mapping' property can be used ony everything that's a 'control' -- in the viewbuilder. - -- + -- -- Please note that the buttons in this example will do nothing at all when - -- pressed with the mouse buttons. The MIDI mappings only apply to mapped + -- pressed with the mouse buttons. The MIDI mappings only apply to mapped -- MIDI, nothing else... local vb = renoise.ViewBuilder() - + local DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN local CONTENT_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING renoise.app():show_custom_dialog( - "Documents & Views", - + "Documents & Views", + vb:column { margin = DIALOG_MARGIN, spacing = CONTENT_SPACING, - - vb:text { - text = "Open the MIDI mapping dialog in Renoise to map:" - }, - vb:row { - vb:button { - width = 120, - text = "Start Playing", - midi_mapping = "Transport:Playback:Start Playing [Trigger]" - }, - vb:button { - width = 120, - text = "Custom Mapping", - midi_mapping = "com.renoise.ExampleToolGui:Example MIDI Mapping" + views = { + vb:text { + text = "Open the MIDI mapping dialog in Renoise to map:" }, + vb:row { + views = { + vb:button { + width = 120, + text = "Start Playing", + midi_mapping = "Transport:Playback:Start Playing [Trigger]" + }, + vb:switch { + width = 120, + items = { "1", "2" }, + midi_mapping = "com.renoise.ExampleToolGui:Example MIDI Mapping" + }, + } + } } } ) end + +-------------------------------------------------------------------------------- +-- Midi mappings +-------------------------------------------------------------------------------- + -- add a custom MIDI mapping, as used in the midi_mapping() example above -renoise.tool():add_midi_mapping{ +renoise.tool():add_midi_mapping { name = "com.renoise.ExampleToolGui:Example MIDI Mapping", invoke = function(message) print("com.renoise.ExampleToolGui: >> got midi_mapping message :") - print((" message:is_trigger(): %s)"):format( message:is_trigger() and "yes" or "no")) print((" message:is_switch(): %s)"):format( @@ -1426,7 +1953,7 @@ renoise.tool():add_midi_mapping{ message:is_rel_value() and "yes" or "no")) print((" message:is_abs_value(): %s)"):format( message:is_abs_value() and "yes" or "no")) - + print((" message.int_value: %d)"):format( message.int_value)) print((" message.boolean_value: %s)"):format( @@ -1434,10 +1961,77 @@ renoise.tool():add_midi_mapping{ end } - + +-------------------------------------------------------------------------------- +-- Menu entries -------------------------------------------------------------------------------- --- thats it - basically ;) Please have a look at the ViewBuilderAPI.txt for a --- complete list of properties & functions for all views... +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:1. Hello World...", + invoke = hello_world +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:2. Pretty Hello World...", + invoke = pretty_hello_world +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:3. Dynamic Content & Ids...", + invoke = dynamic_content +} +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:4. Batch Building Views (Matrix)...", + invoke = dynamic_building_matrix +} +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:5. Aligning & Auto Sizing...", + invoke = aligners_and_auto_sizing +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:6. Available Backgrounds & Text...", + invoke = available_backgrounds +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:7. Available Controls...", + invoke = available_controls +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:8. Documents & Views...", + invoke = documents_and_views +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:9. Canvas View...", + invoke = canvas_view +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:10. Overflow & ScrollBar...", + invoke = overflow_and_scrollbars +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:11. Mouse Events...", + invoke = handle_mouse_events +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:12. Keyboard Events...", + invoke = handle_key_events +} + +renoise.tool():add_menu_entry { + name = "Main Menu:Tools:Example Tool GUI:13. MIDI mapping...", + invoke = midi_mapping +} + +-------------------------------------------------------------------------------- + +-- thats it - basically ;) Please have a look at the ViewBuilderAPI.txt for a +-- complete list of properties & functions for all views... diff --git a/tools/com.renoise.ExampleToolGui.xrnx/manifest.xml b/tools/com.renoise.ExampleToolGui.xrnx/manifest.xml index 9ad7b01d..421dc113 100644 --- a/tools/com.renoise.ExampleToolGui.xrnx/manifest.xml +++ b/tools/com.renoise.ExampleToolGui.xrnx/manifest.xml @@ -1,11 +1,12 @@ - 6.1 + 6.2 com.renoise.ExampleToolGui - 1.0 + 1.2 taktik [taktik@renoise.com] Renoise ViewBuilder API Example - Tool Development - A XRNX tool which describes step by step how to create custom GUIs for your Renoise XRNX tools. Please have a look at the source files of this tool (manifest.xml and main.lua) for more info. Also creates a new menu 'Example Tool GUI' in the global 'Tools' menu. + Development + Example tool which describes step by step how to create custom GUIs for your Renoise XRNX tools. Please have a look at the source files of this tool (manifest.xml and main.lua) for more info. Also creates a new menu 'Example Tool GUI' in the global 'Tools' menu. + MIT http://scripting.renoise.com diff --git a/tools/com.renoise.ExampleToolSlicedProcess.xrnx/main.lua b/tools/com.renoise.ExampleToolSlicedProcess.xrnx/main.lua index b5def8d5..cfa77e6b 100644 --- a/tools/com.renoise.ExampleToolSlicedProcess.xrnx/main.lua +++ b/tools/com.renoise.ExampleToolSlicedProcess.xrnx/main.lua @@ -143,4 +143,3 @@ renoise.tool():add_menu_entry{ end } - diff --git a/tools/com.renoise.ExampleToolSlicedProcess.xrnx/manifest.xml b/tools/com.renoise.ExampleToolSlicedProcess.xrnx/manifest.xml index 9b76b5ed..4b82a703 100644 --- a/tools/com.renoise.ExampleToolSlicedProcess.xrnx/manifest.xml +++ b/tools/com.renoise.ExampleToolSlicedProcess.xrnx/manifest.xml @@ -1,10 +1,12 @@ - 6.1 + 6.2 com.renoise.ExampleToolSlicedProcess - 1.0 + 1.2 taktik [taktik@renoise.com] - Renoise Scripting Tool Example - Tool Development + Renoise Tool Processing Example + Development Example tool that shows how to use coroutines to slice up processing functions. + MIT + http://scripting.renoise.com diff --git a/tools/com.renoise.ExampleToolSlicedProcess.xrnx/process_slicer.lua b/tools/com.renoise.ExampleToolSlicedProcess.xrnx/process_slicer.lua index b348a269..108de857 100644 --- a/tools/com.renoise.ExampleToolSlicedProcess.xrnx/process_slicer.lua +++ b/tools/com.renoise.ExampleToolSlicedProcess.xrnx/process_slicer.lua @@ -4,42 +4,42 @@ process_slicer.lua --[[ -ProcessSlicer allows you to slice up a function which takes a lot of -processing time into multiple calls via Lua coroutines. +ProcessSlicer allows you to slice up a function which takes a lot of +processing time into multiple calls via Lua coroutines. * Example usage: local slicer = ProcessSlicer(my_process_func, argument1, argumentX) --- This starts calling 'my_process_func' in idle, passing all arguments +-- This starts calling 'my_process_func' in idle, passing all arguments -- you've specified in the ProcessSlicer constructor. -slicer:start() +slicer:start() -- To abort a running sliced process, you can call "stop" at any time --- from within your processing function of outside of it in the main thread. --- As soon as your process function returns, the slicer is automatically +-- from within your processing function of outside of it in the main thread. +-- As soon as your process function returns, the slicer is automatically -- stopped. -slicer:stop() +slicer:stop() --- To give processing time back to Renoise, call 'coroutine.yield()' +-- To give processing time back to Renoise, call 'coroutine.yield()' -- anywhere in your process function to temporarily yield back to Renoise: function my_process_func() for j=1,100 do - -- do something that needs a lot of time, and periodically call - -- "coroutine.yield()" to give processing time back to Renoise. Renoise - -- will switch back to this point of the function as soon as has done + -- do something that needs a lot of time, and periodically call + -- "coroutine.yield()" to give processing time back to Renoise. Renoise + -- will switch back to this point of the function as soon as has done -- "its" job: coroutine.yield() - end + end end * Drawbacks: -By slicing your processing function, you will also slice any changes that are +By slicing your processing function, you will also slice any changes that are done to the Renoise song into multiple undo actions (one action per slice/yield). -Modal dialogs will block the slicer, cause on_idle notifications are not fired then. +Modal dialogs will block the slicer, cause on_idle notifications are not fired then. It will even block your own process GUI when trying to show it modal. ]] @@ -47,15 +47,14 @@ It will even block your own process GUI when trying to show it modal. class "ProcessSlicer" function ProcessSlicer:__init(process_func, ...) - assert(type(process_func) == "function", + assert(type(process_func) == "function", "expected a function as first argument") self.__process_func = process_func - self.__process_func_args = {...} + self.__process_func_args = { ... } self.__process_thread = nil end - -------------------------------------------------------------------------------- -- returns true when the current process currently is running @@ -63,20 +62,18 @@ function ProcessSlicer:running() return (self.__process_thread ~= nil) end - -------------------------------------------------------------------------------- -- start a process function ProcessSlicer:start() assert(not self:running(), "process already running") - + self.__process_thread = coroutine.create(self.__process_func) - + renoise.tool().app_idle_observable:add_notifier( - ProcessSlicer.__on_idle, self) + { ProcessSlicer.__on_idle, self }) end - -------------------------------------------------------------------------------- -- stop a running process @@ -84,37 +81,34 @@ function ProcessSlicer:stop() assert(self:running(), "process not running") renoise.tool().app_idle_observable:remove_notifier( - ProcessSlicer.__on_idle, self) + { ProcessSlicer.__on_idle, self }) self.__process_thread = nil end - -------------------------------------------------------------------------------- --- function that gets called from Renoise to do idle stuff. switches back +-- function that gets called from Renoise to do idle stuff. switches back -- into the processing function or detaches the thread function ProcessSlicer:__on_idle() - assert(self.__process_thread ~= nil, "ProcessSlicer internal error: ".. + assert(self.__process_thread ~= nil, "ProcessSlicer internal error: " .. "expected no idle call with no thread running") - + -- continue or start the process while its still active if (coroutine.status(self.__process_thread) == 'suspended') then local succeeded, error_message = coroutine.resume( - self.__process_thread, unpack(self.__process_func_args)) - + self.__process_thread, table.unpack(self.__process_func_args)) + if (not succeeded) then -- stop the process on errors self:stop() -- and forward the error to the main thread - error(error_message) + error(error_message) end - - -- stop when the process function completed + + -- stop when the process function completed elseif (coroutine.status(self.__process_thread) == 'dead') then self:stop() end end - -