Vendetta/helium/api

All API functions for the Helium library are listed below.

Utility functions

Provides functions for operating on iup objects, but don't create iup objects themselves.
Function	Description
map_dialog	Similar to iup's :map(), but recursively activates all map_cb() functions in every child iup object. Many helium objects require this to render correctly.
index_container	Iterates over an iup tree and returns the lua table equivilant. Intended for debugging use only.
iup_prepend	Intended to behave like iup.Append(), but the child is put before instead of after other children
iup_insert	Intended to behave like iup.Append(), but the child can be inserted at an arbitrary location
is_iup	Behaves similarly to iup.IsValid(), but only checks if the object is an iup element.
get_mouse_abs_pos	Retrieves the pixel coordinates of the mouse position. Used internally to place subdialogs.
scale_size	Using the known scaling value of Font.Default, applies a consistant scale to the provided value
scale_2x	A preset function wrapper around scale_size to provide an iup size attribute's expected format.
iter_nums_from_string	A function to split numbers from a non-numerically delimited string, returned as a table. When used with an iup size attribute, returns the values {x, y}

Async functions

These are asynchronous variants of the utility functions
Function	Description
async map_dialog	asynchronous method to map a dialog and execute all embedded map_cb. triggers callback on complete
async index_container	asynchronous method to index an iup container, getting a table representation on callback
async prepend	asynchronous method to add an element to the top of an iup struc. triggers callback on complete
async insert	asynchronous method to insert an element in an iup struc. triggers callback on complete
tween value	Tween from one value to another over time with ease-in-out

Primitive objects

These provide preset singular iup objects for building basic interface objects with more easily.
Function	Description
clearframe	A frame preset with no image and no border; should be visually invisible.
solidframe	A frame preset with a thin border.
borderframe	Description
highlite_panel	An image used internally for 'highlite on mouse hover' behavior.
page rule	Inserts a border into the frame similar to an html page rule
progressbar	A set of basic preset values for an iup.progressbar
hslider	A horizontal scroll bar object
vslider	A vertical scroll bar object
cyclebutton	A button that changes its contents every press, cycling through indexed options.

Constructed objects

Constructs are functions that create multiple iup objects contained within a frame parent.
Function	Description
hexpandbox	A frame-style object that operates like a horizontal 'drawer'; when open, the contents are seen. when closed, the contents are hidden.
vexpandbox	A frame-style object that operates like a vertical 'drawer'; when open, the contents are seen. when closed, the contents are hidden.
vscroll	A frame-style object that allows its contents to be scrolled vertically. This does NOT rely on a 'control' list or iup.matrix
hscroll	A frame-style object that allows its contents to be scrolled horizontally. This does NOT rely on an iup.matrix
ascroll	A freely controlled viewport area.
hbuttonlist	A frame containing a horizontal list of buttons, intended for use as a tab row
vbuttonlist	A frame containing a vertical list of buttons, intended for use as a tab row
coverbutton	This hides an invisible button over the child element, providing on-click functionality to non-clickable objects and frames
coverbutton	Like a coverbutton, but all attributes are passed to the core button object for more advanced control
select_text	A preset of coverbutton over a label element
link_text	A preset of select_text that mimics a hyperlink to open a webpage
ticker	Two buttons and a field for inputting and editing a numeric entry
slide_toggle	A "toggle" object that mimics the popular mobile switch style
multi_button	A three-button setup; two to navigate left and right through options, and a central button to activate the displayed item
bg_frame	Acts like a background element handler
shrink_label	A text element that automatically handles word-wrapping functionality

Preset dialogs

Presets are full dialogs worth of items, with completely custom behaviors and purpose-built uses.
Function	Description
subdialog	Creates a modal-style dialog that can be positioned on the screen (defaults to center).
context_menu	Creates a preset of the subdialog that mimics the behavior of a single-layer context menu.
alert box	Creates a very simple subdialog at center screen to show the user a single message.
choice box	Creates a very simple subdialog for prompting the user to make a selection of two options.
list box	Creates a very simple subdialog for prompting the user to make a selection from a list.
reader	Creates a large subdialog for displaying a large amount of text in a multiline element.
input box	Creates a very simple subdialog for prompting the user to enter a string.

Drag-and-drop functionality

Helium provides these to create easy drag and drop functionality.
Function	Description
drag_item	Creates a transparent field above the target object. this has a drag behavior associated with it. Intended to be paired with a drag_target object.
drag_target	Creates a transparent field above the target objects. this has a drop behavior associated with it. Intended to be paired with a drag_item object.

Color and paint submodule

Helium provides these to create easy methods to select both RGB and indexed ship colors.
The paint module is currently not implemented; these are features targeting helium v1.1.0
Function	Description
paint_panel	Creates a single color thumbnail for ship paint colors.
color_panel	Creates a single color thumbnail for RGB color selection.
paint_select	A full palette list for user selection. Each vertical column lists a general color, with indexes from light to dark.
color_select	Contains RGB color finding controls.
color_picker	A custom dialog that allows the user to select from a palette list, recent selections, or use a color finder.

Preset widgets

End-result items used for single-function purpose that don't fit in other categories are kept in the widgets table.
The widgets table is currently not implemented; these are features targeting helium v1.1.0
Function	Description
clock	A preset clock widget with timezone selection and 12/24 hour display.
stopwatch	A preset stopwatch widget. action returns either _start or _stop, .
numpad	A preset number pad entry widget.
marquee_text	A preset label display that scrolls its contents. Uses multiple labels to give the semblance of continuous scrolling
marquee_obj	A preset display that scrolls its contents. Must be provided with a generator to duplicate displayed contents.