Set the auto-positioning starting point to the position of a certain ui-element.

Means, autpositioning will place the next ui-element either underneath(when using reagirl.NextLine()) or next to the right of ui-element with element_id.

Note: when passing tabs as parameter, the next ui-element will be placed underneath it(as if you had used reagirl.NextLine())

Starts a new line, when autopositioning ui-elements using the _add-functions.

Gets/Sets the color of the background.

Adds a button to a gui.

You can autoposition the button by setting x and/or y to nil, which will position the new button after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

The run-function gets as parameter:
- string element_id - the element_id as string of the pressed button that uses this run-function

Gets a button's disabled(non clickable)-state.

Gets a button's radius.

Sets a button as disabled(non clickable).

Sets the radius of a button.

Adds a checkbox to a gui.

You can autoposition the checkbox by setting x and/or y to nil, which will position the new checkbox after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

The run-function will get two parameters:
- string element_id - the element_id of the toggled checkbox
- boolean checkstate - the new checkstate of the checkbox

Note: to align multiple lines of checkboxes under each other, check out Checkbox_SetWidth.

Gets a checkbox's current checked-state.

Gets a checkbox's disabled(non clickable)-state.

Sets a checkbox's state of the checkbox.

Sets a checkbox as disabled(non clickable).

Unlinks a checkbox from extstate/ini-file/configvar.

Adds a dropdown-menu to a gui.

You can autoposition the dropdown-menu by setting x and/or y to nil, which will position the new dropdown-menu after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

The run-function gets as parameters:
- string element_id - the element_id
- integer selected_menu_entry - the selected menu entry number
- string selected_menu_entry_name - the name of the selected menu entry

Gets the width of a drop down menu.

Gets a dropdown-menu's disabled(non clickable)-state.

Gets a dropdown-menu's menu-items and the index of the currently selected menu-item.

Sets the width of a dropdownmenu.

Sets a drop down menu as disabled(non clickable)-state.

Sets a dropdown-menu's menuitems and the index of the currently selected menu-item.

Focuses a specific tab of a ReaGirl-gui-window.

Parameter gui_name is the same as the name set in the first parameter of Gui_Open.

You can set a focused tab even if the window isn't opened yet. It will be focused the next time the specified gui-window is opened.
It also works for opened gui-windows.

Focuses an opened ReaGirl-gui-window.

Parameter gui_name is the same as the name set in the first parameter of Gui_Open.

Returns false, if no window with the window name is currently opened.

Gets the current width, height, position and dockstate of a ReaGirl-gui-window.

Returns nil if no such window exists/was ever opened.

Returns, if a specific gui-window is open.

Resets a ReaGirl-gui-window to it's default window dimensions and dockstate.

Sets a new width, height, position and dockstate of a ReaGirl-gui-window.

To keep a parameter to its current state, set it to nil.

Adds a function that shall be run when someone hits Enter while the gui is opened.

Adds a function that shall be run when the gui is closed with reagirl.Gui_Close()

Good to do clean up or committing of settings.

Closes the gui-window.

Forces a refresh of the gui.

Returns the current boundaries of the ui-elements. Means, from 0 to the the farthest ui-element-width/height at right/bottom edge of the gui-window.
These boundaries are where the scrolling happens. If the boundaries are smaller/equal window size, all ui-elements are visible in the window and therefore no scrolling happens.

The first four retvals return the boundaries of all visible ui-elements, the last four return the boundaries of all ui-elements, including invisible.
Sticky ui-elements will be ignored.

Checks, whether the gui-window is open.

Manages the gui-window.

Put this function in a defer-loop. It will manage, draw, show the gui.

Creates a new gui by removing all currently(if available) ui-elements.

Opens a gui-window. If x and/or y are not given, it will be opened centered.

ReaGirl stores in the background the position, size and dockstate of the window. Set restore_old_window_state=true to automatically reopen the window with the position, size and dockstate of the window when it was closed the last time.

Prevents the closing of the gui via esc-key for one defer-cycle.

Prevents the user from hitting the enter-key for one cycle, so the run-function for the enter-key is not run in this cycle.

Prevents the scrolling of the gui via keyboard/mousewheel/swiping for this defer-cycle.

Adds an image to the gui. This image can run a function when clicked on it.

Very important: write into meaningOfUI_Element a small description of what the image shows. This will help blind people know, what the image means and what to do with it.
If you can't know what the image shows(an image viewer for instance) explain what's the purpose of the image like "cover image for the project" or something.
Keep in mind: blind people can't see the image so any kind of description will help them understand your script.

You can have different images for different scaling-ratios. You put them into the same folder and name them like:
image-filename.png - 1x-scaling
image-filename-2x.png - 2x-scaling
image-filename-3x.png - 3x-scaling
image-filename-4x.png - 4x-scaling
image-filename-5x.png - 5x-scaling
image-filename-6x.png - 6x-scaling
image-filename-7x.png - 7x-scaling
image-filename-8x.png - 8x-scaling

If a filename doesn't exist, it reverts to the default one for 1x-scaling.

ReaGirl will obey transparency set in png-images.
  
Images can be set to draggable. See Image_GetDraggable and Image_SetDraggable for enabling
dragging of the image to a destination ui-element.

The run_function will get three parameters:
- string element_id - the guid of the image
- string filename - the filename of the image
- optional string dropped_element_id - the element_id of the destination, where the image has been
dragged to
  
You can autoposition the image by setting x and/or y to nil, which will position the new image after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

If you want to force the image to be displayed with correct aspect ratio, see Image_KeepAspectRatio.

Clears the image with a set r-g-b-color. It also clears the previously loaded image-filename.

Gets the width and height of an image.

Gets the current draggable state of an image.

When draggable==true: if the user drags the image onto a different ui-element, the run_function of
the image will get a third parameter, holding the element_id of the destination-ui-element of the dragging.
Otherwise this third parameter will be nil.

Add a note in the meaningOfUI_element and the name of the image/caption of the ui-element, which clarifies, which ui-element is a source
and which is a target for dragging operations, so blind users know, which image can be dragged and whereto.
Otherwise, blind users will not know what to do!

Returns the filename of the currently loaded image.

Set if the image shall keep its aspect ratio when shown.

Loads a new image-file of an existing image in the gui.

You can have different images for different scaling-ratios. You put them into the same folder and name them like:
image-filename.png - 1x-scaling
image-filename-2x.png - 2x-scaling
image-filename-3x.png - 3x-scaling
image-filename-4x.png - 4x-scaling
image-filename-5x.png - 5x-scaling
image-filename-6x.png - 6x-scaling
image-filename-7x.png - 7x-scaling
image-filename-8x.png - 8x-scaling

If a scaled-filename doesn't exist, the function reverts to the default one for 1x-scaling.

Realoads an image.

Sets the width and height of an image.

Sets the current draggable state of an image.

When draggable==true: if the user drags the image onto a different ui-element, the run_function of
the image will get a third parameter, holding the element_id of the destination-ui-element of the dragging.
Otherwise this third parameter will be nil.

Add a note in the meaningOfUI_element and the name of the image/caption of the ui-element, which clarifies, which ui-element is a source
and which is a target for dragging operations, so blind users know, which image can be dragged and whereto.
Otherwise, blind users will not know what to do!

Adds an inputbox to a gui.

You can autoposition the inputbox by setting x and/or y to nil, which will position the new inputbox after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

The caption will be shown before the inputbox.    

Unlike other ui-elements, this one has the option for two run_functions, one for when the user hits enter in the inputbox and one for when the user types anything into the inputbox.

Important:
Screen reader users get an additional dialog shown when entering text, that will NOT run the run-function for typed text. This is due some limitations in Reaper's API and can't be circumvented.
So you can't rely only on the run_function_type but also need to add a run_function_enter, when you want to use the value immediately when typed in your script(like setting as a setting into an ini-file).
Otherwise blind users would be able to enter text but it will be ignored at hitting enter by your code, which would be unfortunate.

The run-functions get as parameters:
- string element_id - the element_id as string
- string text - the currently entered text

Gets an inputbox's current cursor offset.

Gets an inputbox's disabled(non clickable)-state.

gets an inputbox to show * instead of the text(for password entry, etc)

Gets an inputbox's currently selected text.

Gets an inputbox's current text.

Sets an inputbox as disabled(non clickable).

Sets an inputbox's shown text when nothing has been input.

Sets an inputbox to show * instead of the text(for password entry, etc)

Sets a new text of an inputbox.

Will remove newlines from it.

Adds a label to the gui.

You can autoposition the label by setting x and/or y to nil, which will position the new label after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

It is possible to make labels draggable. See Label_SetDraggable and Label_GetDraggable for how to do it.

The run-function will get as parameters:
- string element_id - the element_id of the clicked label
- optional string dropped_element_id - the element_id of the ui-element, onto which the label was dragged

Sets a backdrop from label to underneath a specific ui-element defined by dest_element_id.
It will be autosized. The width will be determined from all ui-elements currently visible, the height will be determined by the position and height of dest_element_id.

To use it: determine, which ui-element shall be the lowest inside the rectangle(like one directly above the bottom line of the backdrop.)
Any ui-element in the same line does the trick. However, you should choose the highest ui-element in the lowest line or the backdrop might be drawn through it.

Gets the alignment of a label.

Sets a background-rectangle in line-style for this label. You can use this to "include" different ui-elements of a common context underneath this label.
That way, you can structure your guis a little better.

Set height to 1 to just have a line before and after the first line of the label-text.

Gets the current draggable state of a label.

When draggable==true: if the user drags the label onto a different ui-element, the run_function of
the label will get a second parameter, holding the element_id of the destination-ui-element of the dragging.
Otherwise this second parameter will be nil.

Add a note in the meaningOfUI_element of the label of the ui-element, which clarifies, which ui-element is a source
and which is a target for dragging operations, so blind users know, which label can be dragged and whereto.
Otherwise, blind users will not know what to do!

Gets the font-size of a label.

Gets the style of a label.

Sets the font-size of a label.

Sets a background-rectangle in line-style for this label. You can use this to "include" different ui-elements of a common context underneath this label.
That way, you can structure your guis a little better.

Set height to 1 to just have a line before and after the first line of the label-text.

Sets the current draggable state of a label.

When draggable==true: if the user drags the label onto a different ui-element, the run_function of
the label will get a second parameter, holding the element_id of the destination-ui-element of the dragging.
Otherwise this second parameter will be nil.

Add a note in the meaningOfUI_element of the ui-element, which clarifies, which ui-element is a source
and which is a target for dragging operations, so blind users know, which label can be dragged and whereto.
Otherwise, blind users will not know what to do!

Sets the font-size of a label.

Sets a new label text to an already existing label.

Sets the style of a label.

You can combine different styles with each other in style1 through style3.

Converts a Base64-encoded string into a normal string.

Returns nil in case of an error

Converts a string into a Base64-Encoded string.

Returns nil in case of an error

Returns the version-number of the installed ReaGirl.

Checks, if guid is a valid guid. Can also be used for strings, that contain a guid somewhere in them(strict=false)

A valid guid is a string that follows the following pattern:
{........-....-....-....-............}
where . is a hexadecimal value(0-F)

Checks clickstate and mouseclick/wheel-behavior, since last time calling this function and returns their states.
Allows you to get click, doubleclick, dragging, including the appropriate coordinates and mousewheel-states.

Much more convenient, than fiddling around with gfx.mouse_cap

Note: After doubleclicked, this will not return mouse-clicked-states, until the mouse-button is released. So any mouse-clicks during that can be only gotten from the retval mouse_cap.
      This is to prevent automatic mouse-dragging after double-clicks.

Reserves a framebuffer which will not be used by ReaGirl for drawing.
So if you want to code additional ui-elements, you can reserve an image buffer for blitting that way.

nil, if no additional framebuffer is available

Resizes an image, keeping its aspect-ratio. You can set a background-color for non rectangular-images.

Resizing upwards will probably cause artifacts!

Note: this uses image 1023 as temporary buffer so don't use image 1023, when using this function!

Gets the current scaling-factor

Sets a new scaling-factor that overrides auto-scaling/scaling preferences

Sends a message to the screen reader

Use this only when needed, means, don't permanently send messages. Otherwise, they will be cut off and the user doesn't get them.

Adds a slider to a gui.

You can autoposition the slider by setting x and/or y to nil, which will position the new slider after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

The caption will be shown before, the unit will be shown after the slider.
Note: when setting the unit to nil, no unit and number will be shown at the end of the slider.

Also note: when the number of steps is too many to be shown in a narrow slider, step-values may be skipped.

The run-function will get as parameters:
- string element_id - the element_id of the slider that uses this run-function
- integer value - the current slider-value

Gets the current set value of the slider.

Gets the width of a slider.

Gets the current disability state of the slider.

Gets the current set maximum-value of the slider.

Gets the current set minimum-value of the slider.

Gets the current set value of the slider.

Resets the current set value of the slider to the default value.

Sets the default value of the slider.

Will not check, whether it is a valid value settable using the stepsize!

Sets the width of a slider.

Sets a slider disabled.

Sets the maximum value of the slider.

If current slider-value is bigger than maximum, the current slider-value will be changed to maximum.

Sets the minimum value of the slider.

If current slider-value is smaller than minimum, the current slider-value will be changed to minimum.

Sets the current value of the slider.

Will not check, whether it is a valid value settable using the stepsize!

Adds a tab to a gui.

You can autoposition the tab by setting x and/or y to nil, which will position the new tab after the last ui-element.
To autoposition into the next line, use reagirl.NextLine()

You can also have a background drawn by the tab, which could be set to a specific size or set to autosize.
When set to autosize, it will enclose ui-elements currently visible in the gui.
If you don't want a background, set w_background or h_background to 0.

Keep in mind, that using auto-sizing of the background might lead to smaller backgrounds than the tabs themselves when there's only a few ui-elements available!

The run-function will get as parameters:
- string element_id - the tab's element-id
- integer selected_tab - the clicked tab
- string selected_tab_name - the clicked tab-name

Gets the selected tab of a tabs-element.

Sets the selected tab of a tabs-element.

Sets the ui-elements for a tab from a table.

The element_ids in the table element_ids_table consists of all ui-elements that shall be visible when this tab is selected.

gets the rectangle for focused ui-element. Can be used for custom ui-element, who need to control the focus-rectangle due some of their own ui-elements incorporated, like options in radio-buttons, etc.

the first four retvals give the set-position(including possible negative values), the second four retvals give the actual window-coordinates.

Get the ui-element-guid, that is currently focused.

Get the ui-element-guid, where the mouse is currently.

gets/sets the caption of the ui-element

gets/sets the meaningOfUI_Element of the ui-element, which will describe, how to use the ui-element to blind persons.

Very important when seting meaning_Of_UI_Elements for images: write into meaningOfUI_Element a small description of what the image shows. This will help blind people know, what the image means and what to do with it.
If you can't know what the image shows(an image viewer for instance) explain what's the purpose of the image like "cover image for the project" or something.
Keep in mind: blind people can't see the image so any kind of description will help them understand your script.

gets/sets the position of the ui-element

gets/sets the run_function of the ui-element, which will be run, when the ui-element is toggled

gets/sets the hidden-state of the ui-element

gets/sets the context-menu and context-menu-run-function of a ui-element.

Setting this will show a context-menu, when the user rightclicks the ui-element.

Parameter menu is a list of fields separated by | characters. Each field represents a menu item.
Fields can start with special characters:

# : grayed out
! : checked
> : this menu item shows a submenu
< : last item in the current submenu

The menu_runfunction will be called with two parameters:
  string element_id - the guid of the ui-element, whose context-menu has been used
  integer selection - the index of the menu-item selected by the user

gets/sets the dropzone-run-function of a ui-element.

This will be called, when the user drag'n'drops files onto this ui-element.

The dropzone_function will be called with two parameters:
  string element_id - the guid of the ui-element, on which files were dropped
  table filenames - a table with all dropped filenames
  
It's also possible, that fx were dropped onto a drop-zone, since Reaper allows that.
So if you just want to have filenames, check, if the filename is not of format "@fx:fx_ident"

returns the type of the ui-element

returns, if ui-element with element_id is at mouse-position

Returns the x and y position as well as width and height of the last added ui-element.

Removes a ui-element.

sets the rectangle for focused ui-element. Can be used for custom ui-element, who need to control the focus-rectangle due some of their own ui-elements incorporated, like options in radio-buttons, etc.

Set an ui-element focused.

Set ui-elements stored in a table to hidden or visible.

returns, if any of the gui-elements are outside of the window and by how much.

Good for management of resizing window or scrollbars.

Sets a maximum window size that will be enforced by ReaGirl.

Sets a minimum window size that will be enforced by ReaGirl.

Sets window focus back to the ReaGirl-gui-window.