Plugin System/API/UI Widgets

Glossary of Terms
A widget id (widget identifier) is a string used to identify a specific instance of a widget. Likely this will be a path, e.g. "main_menu/edit/copy" or "inventory1/search_field".

A property is an attribute (variable) of the widget, such as text label, color, size, or current value. Each widget type has a specific, pre-defined list of properties, depending on the characteristics of that widget type.

A screen space unit (SSU) is the unit of measure for widgets on the screen. Usually, 1 SSU = 1 pixel, but it may be smaller or larger on viewers which support scalable/zoomable UIs.

General Methods
The following methods (actions that can be performed) are shared among all UI widget types.


 * ListProps, GetProps, and SetProps (properties accessors)
 * Get Children. Accepts a widget id of the parent object. Returns an array of widget ids and types of the given widget's children (contained widgets, or list items). If the widget has no children, but the widget type supports children, returns an empty array. If the widget type can never have children, returns.
 * Add Child(ren). Accepts a widget id of the parent, and either a single child widget or array of multiple children. The children must be full widget definition structures (with type, name, and properties). This method can only be used for widget types that support children. Returns an error and does not add any children if the parent widget's type does not support children, or if any of the children are of an incompatible type (e.g. trying to add a button as the child of a menu).
 * Remove Child(ren). Accepts a partial widget structure (only name is required) or an array of same (to remove multiple children). Return an error and does not remove any children if any of the given child widgets are not actually children of the parent.

Widget Types
A partial list of possible widget types, their attributes, and their allowed child types.

Shared Properties (View)
These properties are supported by all widget types which inherit from "View".


 * name: Reference name for the widget. This is not displayed to the user. Names must be unique among all widgets under the same parent, but two widgets under different parents can have the same name. (Required string.)
 * enabled: If true, the widget can be interacted with. If false, the widget is "grayed out" and can't be interacted with. (Optional bool, default true.)
 * visible: If true, the widget is visible. If false, the widget is invisible. (Optional bool, default true.)
 * tool_tip: A string describing the widget or offering a tip about its usage. Usually displayed as a tool tip when the user's cursor pauses momentarily over the widget, but this is left up to the implementation. (Optional string, default empty.)
 * Size / position:
 * width, height: Specifies the width and height of the widget, in SSU. (Optional numbers, default varies by type and/or implementation.)
 * left, right: Specifies the horizontal position of the left and/or right edge(s) of the widget, relative to the parent widget, in SSU. Larger values are further to the right on the screen. If both left and right are specified, any specified width is ignored, and the widget is sized so that both the left and right sides are in the specified positions. (Optional numbers, default left = 0, right unspecified.)
 * top, bottom: Like left/right, but specifies the vertical position of the top and/or bottom edge(s) of the widget. Larger values are higher on the screen. If both top and bottom are specified, height is ignored, as with left/right and width.

Floaters
A floater is a window which can be moved around the screen. Some examples from Imprudence are the Inventory floater, Build (Tools) floater, and Chat/IM floater.

Inherits from View.

Allowed Child Types
Any except floaters.

Core Properties
These are properties which implementations are required to support.


 * title: The title of the floater, usually displayed along the top of the floater in a title bar. (Optional string, default empty.)

Optional Properties
These are properties which implementations are not required to support.


 * resizable: If true, the user is allowed to adjust the width and height of the floater. (Optional bool, default true.)
 * minimizable: If true, the user is allowed to minimize (aka. iconify or hide) and unminimize the floater. (Optional bool, default true.)
 * closeable: If true, the user is allowed to close the floater. (Optional bool, default true.)
 * min_width, min_height: The smallest allowed width and height (in SSU) that the floater can be made, whether by the user or by an API call. (Optional non-negative number or  for no minimum, default  .) Implementations may also have their own hard minimum width and/or height for floaters in general (e.g. to prevent the user from making them too small to see, or if the GUI library can't handle floaters below a certain size), which takes precedence if the values of these properties are smaller than the hard minimum.
 * max_width, max_height: Like min_width and min_height, but specifies the largest allowed width and height instead of the smallest. Implementations may have hard maximums, just as they may have hard minimums. (Optional non-negative integer, or  for no maximum, default  .)