Widgets

Fluid's widget APIs are stored in the scripts/gui folder and installed as a standard feature of the Parasol Framework.

To use an API listed in this guide, the script must make an appropriate require call for the interface. For example:

require 'gui/toolbar'

Loading a widget API makes it available under the gui interface, using the same name as the API. For instance, gui.toolbar(). Unless specified otherwise, the standard method of instantiating a widget is to call the interface with the following template:

new_widget = gui.widget_api({ Options... })

For example:

toolbar = gui.toolbar({
   target      = viewport,
   xOffset     = 0,
   y           = y,
   iconSize    = 22,
   createItems = function(Bar)
      Bar.addGroup(1, 'Clipboard', 3)
      Bar.addItem(2, 'Cut', 'Cut', 'tools/not_an_icon', itemCallback)
      Bar.addItem(3, 'Copy', 'Copy', 'tools/copy', itemCallback)
      Bar.addItem(4, 'Paste', 'Paste', 'tools/paste', itemCallback)
   end
})

If you require deeper insight on how a certain aspect of a widget works, don't hesitate to view the source code for the API. The state information for widgets isn't typically documented, but can be learned from the code. All code is available in its original form and includes comments where needed.

Events

Many widgets support event triggers through an optional event setting. This can be leveraged to receive notification of events such as user hovering and focus changes. Here's an example that would work for almost any widget:

events = {
   activate = function(Widget, Event)
      print('The widget has been actived.')
   end,
   focus = function widgetFocus(Widget)
      print('User gave focus to this widget.')
   end
}

Events are standardised, and follow the function protoype function(Widget, { Event }) where Event contains key values relating to what occurred, if applicable. Standardisation means you are free to use the same function across many different widget types if desired.

Index

Button | Checkbox | Colour Dialog | Combobox | Dialog | Divider | File Dialog | File View | Font Dialog | Icon | Input | Menu | Menubar | Scrollbar | Toolbar | Tooltip | Window | Views

Widget Interfaces

button

gui.button({ Options... })

The gui.button() interface creates and manages buttons in the UI.

Valid options are:

Option	Description
target	Required. Refers to a viewport that will contain the button.
icon	An optional icon to display alongside the text.
text	A label to display in the button.
events	A table of event triggers. Supported events are activate, show, focus, lostFocus, cursorEntry, cursorExit, enable, disable
width	Width of the button (including any label).
x, y	The top-left position of the widget.
xOffset, yOffset	Offsets can be defined as an alternative to x and y.

Supported methods:

Method	Description
:disable()	Disable user interactivity.
:enable()	Enable user interactivity.

checkbox

gui.checkbox({ Options... })

The gui.checkbox() interface creates and manages checkboxes in the UI.

Valid options are:

Option	Description
target	Required. Refers to a viewport that will contain the checkbox.
label	A label to display next to the checkbox.
events	A table of event triggers. Supported events are activate, show, focus, lostFocus, enable and disable.
state	1 = Selected, 0 = Not selected, -1 = Indeterminate
align	The checkbox icon can be aligned to the left or to the right. Defaults to left.
width	Width of the checkbox (including any label).
x, y	The top-left position of the widget.
xOffset, yOffset	Offsets can be defined as an alternative to x and y.

Supported methods:

Method	Description
:disable()	Disable user interactivity.
:enable()	Enable user interactivity.

colourdialog

gui.dialog.colour({ Options... })

The colour dialog interface standardises user colour selection. On activation, it presents the user with a small window containing common colours, personal colours and a rainbow palette. The dialog will close once the user selects a colour, or cancels the dialog window.

If the dialog box is modal, the call will not return until the user has responded to the dialog.

Valid options are:

Option	Description
popOver	Place the dialog window over the referenced surface.
target	Open the dialog window within the referenced viewport.
modal	Set to true if the dialog box needs to be modal (prevents interaction with other windows).
path	The initial selection path.
feedback	A callback to receive the user's response to the dialog, using the prototype function(Colour). The Colour will refer to the user's selected colour in RGB string format, e.g. 128,255,64. In the event that the dialog is cancelled, the Colour is set to nil.
colour	The default colour in R,G,B format.
title	Give the window a title other than the default.

combobox

gui.combobox({ Options... })

The gui.combobox() interface creates and manages comboboxes in the UI.

Valid options are:

Option	Description
target	Required. The viewport that will contain the widget.
items	Required. List of menu items (refer to gui.menu() for formatting)
events	A table of event triggers. Supported events are activate, show, focus, lostFocus, enable, disable.
flushEdges	Set to true if the widget needs to be squared off for flush edges.
text	A preset string to display in the box. If not set, defaults to first entry in items.
vfx	A special effect to apply to the widget on its creation.
showIcons	If true, show icons in the drop-down list.
allowCustom	If true, the user can enter enter text that isn't in the combobox list.
noTranslation	Do not translate strings to the user's native language.
width	Width of the box (including any label).
x, y	The top-left position of the widget.
xOffset, yOffset	Offsets can be defined as an alternative to x and y.

Supported methods:

Method	Description
:disable()	Disable user interactivity.
:enable()	Enable user interactivity.

dialog

gui.dialog.message({ Options... })

The gui.dialog.message() interface displays message boxes in the UI. If the dialog box is modal, the call will not return until the user has responded to the dialog. The dialog box should be managed as a dynamic resource, i.e. created as necessary and deallocated once the user has responded (i.e. set all references to nil). Retaining dialog boxes in memory will provide no descernible speed improvement to the user.

Valid options are:

Option	Description
checkboxLabel	Adds a user checkbox to the dialog if a label name is specified here.
checkboxState	If true, the checkbox created by checkboxLabel will be pre-selected.
feedback	Refers to a function that will receive the user's response to the dialog, which must be in the format function(Dialog, Response, State). Response refers to a table item provided by the caller in the options parameter. If the dialog was cancelled then the Response is nil. The State parameter will be set if the userInput or checkboxLabel options were defined when the dialog was created. The State table will contain input and checkbox values that indicate their state at the time.
fmtMessage	This RIPL formatted message will be displayed in the dialog.
icon	Window icon, in the format category/name.
image	An icon to display alongside the dialog message, in the format category/name.
modal	Set to true if the dialog box needs to be modal (prevents interaction with other windows).
message	A plain message string to display in the dialog.
options	A list of clickable user responses that will be displayed in the dialog. Each entry must include a text label and icon value.
popover	Place the dialog window over the surface referenced here.
secret	Set to true if the userInput string should be kept secret (e.g. a password).
type	Categorise the dialog type (see below).
target	Open the dialog window within the surface referenced here.
title	A title for the dialog window.
userInput	Set to true if the user can enter custom text. Set to a string if the input box must be pre-filled.

The type option can be set to one of the following values:

Type	Description
message	The default setting.
critical	A highly critical error is being reported to the user.
error	An error is being reported to the user.
warning	A warning message is being reported to the user.
attention	The dialog requests the user's immediate attention.
alarm	The dialog is presented as a response to a preset alarm.
help	Help text is being presented in the dialog.
info	The dialog is providing the user with specific information on a topic.
question	A question is being asked of the user.
request	A request is being made (e.g. dialog requires user to type in input).
temporary	The dialog box will disappear after a short time-out period has expired.

Supported methods are:

Method	Description
setMessage(Message, Formatted)	Change the message displayed in the dialog. Set Formatted to true if the Message is in RIPL format.
wait()	Waits for the user to respond to the dialog.

Example usage:

gui.dialog.message({
   modal     = true,
   image     = 'items/warning',
   title     = 'Hamlet has a question',
   message   = 'To be or not to be?',
   userInput = 'That is the question',
   checkboxLabel = '\'Tis nobler to suffer',
   options = {
      { id=1, text='To be', icon='items/checkmark' },
      { id=2, text='Not to be', icon='items/cancel' }
   },
   feedback = function(Dialog, Response, State)
      print('Response received.')
   end
})

divider

gui.divider({ Options... })

The gui.divider() interface is used to break up the space between viewports and allow them to be user adjustable.

For a horizontal split, the configuration must specify two viewports that are positioned to the left and right of the divider, or top and bottom for a vertical split. For the viewport on the far side of the divider, define (x, xOffset) and (y, yOffset) pairs as necessary to ensure that the viewport is correctly anchored.

Example usage:

gui.divider({ left=leftViewport, right=rightViewport, minA=50, minB=50 })

Valid options are:

Option	Description
left	Viewport on the left (A) side. Must be paired with a viewport on the right.
right	Viewport on the right (B) side.
top	Viewport on the top (A) side. Must be paired with a viewport on the bottom.
bottom	Viewport on the bottom (B) side.
minA/B	Minimum pixel size of the A or B side.
maxA/B	Maximum pixel size of the A or B side.
fixedSize	Set if the divider position should remain fixed when the window is resized (default is proportional).
style	Set to none, default or alt for an alternative divider style.

filedialog

gui.dialog.file({ Options... })

Use the file dialog interface to prompt the user into selecting an existing file, or declaring a new one. The dialog will return the user's choice via the feedback function.

If the dialog box is modal, the call will not return until the user has responded to the dialog.

Note that the dialog box should be managed as a dynamic resource, i.e. created as necessary and deallocated once the user has responded (i.e. set all references to nil). Retaining dialog boxes in memory will provide no descernible speed improvement to the user.

Valid options are:

Option	Description
popOver	Place the dialog window over the referenced surface.
target	Open the dialog window within the referenced surface.
modal	Set to true if the dialog box needs to be modal (prevents interaction with other windows).
okText	Override the text to display in the OK button.
cancelText	Override the text to display in the Cancel button.
filter	Name of the default filter to apply from the filterList.
filterList	List of items for the combobox filter, e.g. { { name='All Files', pattern='*' } }
icon	The icon to use for the dialog window.
path	The initial selection path.
selectFolder	Set to true if folders can be selected.
multiSelect	Set to true if more than one item can be selected.
userInput	Set to true if the user can enter custom text.
warnExists	If true, confirm with the user if the selected file should be overwritten.
feedback	Refers to a function that will receive the user's response to the dialog. Use the format function(Dialog, Files). Files refers to an array of the selected file names (full path is not included, refer to currentPath for the folder). If the dialog is cancelled, Files will be set to nil.

fileview

gui.fileview(View, { Options... })

The fileview interface enhances any view object, such as listview or columnview to create a file system browser. The following example illustrates basic usage:

gui.fileview(view, {
   showParent = true,
   showHidden = true,
   autoMode   = 'open',
   pathChanged = function(FileView, Path)
   end,
   fileSelected = function(FileView)
   end
})

Valid options are:

Option	Description
autoMode	Automatically perform open, edit or view if a folder or file is activated by the user.
fileSelected	Callback for the user selecting a file, in the format function(FileView). Use the selection(), selectionFile() and selectionPath() methods for information on the selected item.
filter	Show only the files that match this wildcard filter, e.g. *.csv.
limitPath	Limit browsing to this folder and its sub-folders.
noExtensions	If true, file extensions are not displayed when this option is active.
noFiles	If true, do not display files in the file list.
pathChanged	Callback for changes to the path, in the format function(FileView, Path).
showParent	If true, the file view will display an item in the file list that reverts to the parent folder when activated.
showHidden	If true, show hidden files.
showSystem	If true, show system files.
showDocs	If true, show document views.
sysKeys	If true, system key monitoring and relevant default behaviours are active when this option is enabled. Cut, Copy, Paste and Select-All key combinations are provided to the user in this mode.

Available methods are:

Method	Description
browse(Path)	Browse the folder at Path.
byteSize()	Returns the size of the browsed storage device.
bytesFree()	Returns the amount of free space on the browsed storage device.
bytesUsed()	Returns the amount of used space on the browsed storage device.
copyFiles()	Apply all selected items to the clipboard with a copy operation.
copyFilesTo(Path)	Copy all selected items to Path.
createFolder()	Prompt the user to create a new folder.
createShortcut()	Prompt the user to create a shortcut.
cutFiles()	Apply all selected items to the clipboard with a cut operation.
deleteFiles()	Prompt the user and delete all selected items.
editFiles()	Run the default edit command for all currently selected files.
filter(Filter)	Apply a wildcard Filter to limit the display to matching file names.
moveFilesTo(Path)	Move all selected items to the destination Path.
openFiles()	Run the default open command for all currently selected files.
parentFolder()	Browse the parent folder of the current path.
pasteFiles()	Paste files from the clipboard to the current path.
refresh()	Force a refresh of the view.
renameFile()	Prompt the user to rename the selected item.
selectionPath()	Returns the complete, fully-qualified path of the most recently selected item.
selection()	Returns the name of the currently selected item, as it appears to the user.
selectionFile()	Returns the currently selected file or folder (fully-qualified).
viewFiles()	Run the default view command for all currently selected files.

fontdialog

gui.dialog.fontdialog({ Options... })

The font dialog interface provides a standardised way of asking the user to select a font, and/or choosing font style information. If the dialog box is modal, the call will not return until the user has responded to the dialog.

Valid options are:

Option	Description
colour	Preset the font colour. The default is black.
example	Overrides the example text normally printed in the dialog.
face	Preset the font's face and additional details, using the format Face:Size:Style:Colour. Defaults to Noto Sans.
feedback	Refers to a function that will receive the user's response to the dialog. Must be in the format function(Dialog, Accepted). Accepted is true if the user did not cancel the dialog. The receiver can query the Dialog state to get the user's selection details.
pointSize	Preset the size of the font, measured in points.
popOver	Place the dialog window over the referenced surface.
modal	Set to true if the dialog box needs to be modal (prevents interaction with other windows).
path	The initial selection path.
style	Preset the font's style, e.g. Bold Italic. The default is Regular.
target	Open the dialog window within the referenced surface.
title	Set a custom title for the dialog window.

The dialog state consists of the following readable fields:

Field	Description
colour	The font colour, expressed as an rgba table.
compactFace	Defined when the user selects a font, this string is in the format Face:Size:Style:Colour.
face	The currently selected font face.
pointSize	The currently selected point size.
style	The currently selected style.

icon

gui.icon({ Options... })

The icon interface provides a convenient way of creating and managing interactive icons. The following example illustrates typical usage:

gui.icon({
   target = viewport,
   x      = 10,
   y      = 10,
   text   = 'File Manager',
   image  = 'programs/filemanager',
   events = {
      activate = function(Icon, Event)
         print('Icon activated.')
      end
   }
})

Valid options are:

Option	Description
target	Required. Refers to a viewport that will contain the icon.
image	The name of an icon file to display, in the format category/name. Alternatively a custom SVG file can be used if a full path location is given.
x, y	The top-left position of the icon.
size	The preferred size of the icon, in pixels.
text	A string to display in the icon.
events	A table of event triggers. Supported events are activate and show, in the format function(Icon, { Parameters... }). When the activate event is called, A name key will be defined that can be one of click, dblclick and altclick (e.g. right mouse button).
theme	Set to light or dark for an appropriately coloured icon.

input

gui.input({ Options... })

The input interface creates and manages input boxes in the UI.

Valid options are:

Option	Description
events	A table of event triggers. Supported events are activate, show, cursorEntry, cursorExit, disable, enable, focus, lostFocus and keypress.
flushEdges	Set to true if the box needs to be squared off for flush edges.
inputMask	Restrict input with a pattern that is compliant with Lua 5.1's string.find().
label	A text label for the widget.
secret	Set to true if the input box needs to hide a secret phrase from view.
selected	Set to true if the input text should be pre-selected for the user.
target	Required. Refers to a viewport that will contain the widget.
text	A preset string to display in the input box.
width	Width of the box (including any label).
x, y	The top-left position of the widget.
xOffset, yOffset	Offsets can be defined as an alternative to x and y.

Supported methods:

Method	Description
:disable()	Disable user interactivity.
:enable()	Enable user interactivity.

menu

gui.menu({ Options... })

The menu interface provides a convenient interface for creating and managing menus.

The following example illustrates typical usage:

gui.menu({
   target = surface,
   x = 10, y = 10,
   config = {
      { item='New File', icon='items/file_new', qualifier='CTRL', key='N', feedback=clicked },
      { item='Open File', icon='office/documents', qualifier='CTRL', key='O', feedback=clicked }
   }
})

Valid options are:

Option	Description
client	Optional vector deemed responsible for instantiating the menu. Recommended to enable keyboard navigation for the user.
config	Required. A list of items for configuring the content of the menu.
noTranslation	If true, do not translate menu text to the user's native language.
popup	If true, locks the position of the menu to the mouse pointer and also grabs the UI focus.
style	The visual style can be set to menubar, list or popup, according to the purpose of the menu.
target	Optional reference to a surface that will contain the menu. Viewports are not supported.
x, y	The top-left position of the menu.
width	The preferred width of the menu, in pixels.

The key-values for the config option are as follows:

Key	Description
item	Name of the menu item.
icon	Icon to display alongside the menu text.
qualifier	The shortcut key qualifer, typically CTRL or ALT
key	The shortcut key for the menu item.
feedback	A callback function for when the menu item is activated. Must be in the format feedback(Menu, Item).

Custom key values are permitted in the config items and will be ignored by the menu interface. It is recommended that they are prefixed with c_ to differentiate them from reserved key values.

menubar

gui.menubar({ Options... })

The MenuBar interface creates and manages the use of items and groups of items in the UI, typically using icons, text or both for item representation. Each item performs a specific application function that is activated via a callback mechanism.

The following example illustrates typical usage:

gui.menubar({
   target = viewport,
   x = 0, y = 0, xOffset = 0,
   createItems = function(Bar)
      Bar.addItem(1, 'File', 'devices/harddisk', menuCallback, {
         { item='New File', icon='items/file_new', qualifier='CTRL', key='N', feedback=clicked },
         { item='Open File', icon='office/documents', qualifier='CTRL', key='O', feedback=clicked },
         { item='Reload Document', icon='items/reload', key='F5', feedback=clicked },
         { item='Save File', icon='items/file_save', qualifier='CTRL', key='S', feedback=clicked }
      })
      Bar.addItem(2, 'Edit', 'tools/edit', menuCallback, {
         { item='Undo', icon='items/undo', qualifier='CTRL', key='Z', feedback=clicked },
         { item='Redo', icon='items/redo', qualifier='CTRL', key='Y', feedback=clicked },
         { menu={ text='Clipboard', icon='items/clipboard',
             items={
               { item='Cut', icon='tools/cut', qualifier='CTRL', key='X', feedback=clicked },
               { item='Copy', icon='tools/copy', qualifier='CTRL', key='C', feedback=clicked },
               { item='Paste', icon='tools/paste', qualifier='CTRL', key='V', feedback=clicked }
             }
           }
         }
      })
   end
})

Valid options are:

Option	Description
createItems	Required. A function that will define the items to display in the menubar.
x, y	The top-left position of the menubar.
xOffset	Optional x-offset. Defaults to 0.

The createItems function must be provided, and is called when the menubar is performing its layout operation. The Bar parameter refers to the menubar's state, and the client is expected to use it to call addItem() for each item requiring representation.

Supported menubar methods are:

Method	Description
addItem(ID, Name, Icon, Function, Menu)	To be used for the creation of menu items during createItems. The ID must be unique. Name will be printed in the menubar. Icon can refer to an icon that will accompany the item, in the format category/icon. Function will be called if the user chooses the item, and is in the format function(Bar, Item). Menu is a config table that is forwarded to the menu interface for creating the menu drop-down.
disableItem(ID)	Disable the item identified by ID.
enableItem(ID)	Enable the item identified by ID.

scrollbar

gui.scrollbar({ Options... })

The Scrollbar interface creates horizontal and vertical scrollbars for moving content within a viewport.

The following example illustrates typical usage:

gui.scrollbar({
   target = viewport,
   view   = viewport_view,
   page   = viewport_page
})

Valid options are:

Option	Description
target	Required. Refers to a viewport that will contain the scrollbar.
view	Required. A viewport that is within the target and contains the page content. Note that the dimensions of the view will be controlled by the scrollbar, notably the XOffset and YOffset, which the client should set to zero.
page	Required. A viewport within the view. The page will contain the content for display and must use fixed width and height values.
breadth	Overrides the breadth of the scrollbar in pixel units.
direction	Limits scrolling to vertical or horizontal if desired. Both axis are enabled by default.

Functionality:

Method	Description
scrollPage(DeltaX, DeltaY)	Move the page by (DeltaX, DeltaY) pixel units. Movement conforms to view restrictions.
setDynamicPageSize(NominalWidth, MinWidth, Height)	In dynamic page mode, a NominalWidth declares the length of the longest item. The page width is automatically expanded to the view's width in this mode, while Height behaves normally. Setting a MinWidth is optional. It should be noted that this feature is not compatible with horizontal scrolling.
setFixedPageSize(Width, Height)	Defines a fixed page size of Width x Height.

Internally the scrollbar code works by monitoring the FM_PATH_CHANGED event of the provided view and page. The recalcSlidersFromView() function is responsible for making adjustments to the scrollbars, and alters their visibility as required.

toolbar

gui.toolbar({ Options... })

The toolbar interface creates and manages the use of items and groups of items in the UI, typically using icons, text or both for item representation. Each item performs a specific application function that is activated via a callback mechanism.

The following example illustrates basic usage:

tbar = gui.toolbar({
   target = viewport,
   x = 0, y = 0, xOffset = 0,
   createItems = function(Bar)
      Bar.addGroup(1, 'Navigation', 2)
      Bar.addItem(2, 'Root', 'Root Directory', 'devices/harddisk', itemCallback)
      Bar.addItem(3, 'Parent', 'Parent Folder', 'arrows/arrow_nw', itemCallback)
      Bar.addGroup(4, 'Clipboard', 3)
      Bar.addItem(5, 'Cut', 'Cut', 'tools/not_an_icon', itemCallback)
      Bar.addItem(6, 'Copy', 'Copy', 'tools/copy', itemCallback)
      Bar.addItem(7, 'Paste', 'Paste', 'tools/paste', itemCallback)
   end
})

Valid options are:

Option	Description
cellMargin	The amount of whitespace at the four edges of each item, measured in pixels.
createItems	Required. Defines the items that will be displayed in the toolbar.
groupMargin	The amount of margin space assigned to groups.
iconSize	Optional. The preferred size of the toolbar icons, in pixels. This determines the overall size of the toolbar.
orientation	Defaults to horizontal (left to right item arrangement). Set to vertical for top to bottom.
theme	Set to light or dark for appropriately coloured icons.
x, y	The x and y coordinates of the toolbar.
xOffset	Optional x offset. If not defined then the toolbar width is calculated based on the number of items.

The createItems function must be provided, and is called when the toolbar is performing its layout operation. The Bar parameter refers to the toolbar's state, and the client is expected to use it to call addItem() for each item requiring representation.

Supported toolbar methods are:

Method	Description
addBreak()	To be used for the creation of toolbar breaks during createItems. Inserts a visual break between the last item and the next.
addItem(ID, Name, Icon, Function)	To be used for the creation of toolbar items during createItems. The ID must be unique. Name will be printed in the toolbar if no Icon is specified, and will also appears in tooltips. Icon can refer to an icon that will represent the item, in the format category/icon. Function will be called if the user chooses the item, and is in the format function(Bar, Item).
addGroup(ID, Name, Span)	To be used for the creation of toolbar groups during createItems. Call this method before adding a series of items that form a natural group. For instance to group Cut, Copy and Paste items under 'Clipboard', call this method with a Span of 3 and then create the three items.
disableItem(ID)	Disable the item identified by ID.
enableItem(ID)	Enable the item identified by ID.
deselectItem(ID)	Deselect a previously selected item identified by ID.
selectItem(ID, Exclusive)	Mark a toolbar item as selected, which results in the toolbar item being drawn with a special background to indicate that the item is active. If Exclusive is true, existing selected items are deselected.

The returned toolbar interface includes the following read-only key-values:

Key	Description
viewport	The viewport that hosts the toolbar's UI.

tooltip

gui.tooltip({ Options... })

The tooltip interface creates a tooltip on the display that vanishes when the user moves the mouse cursor.

Valid options are:

Option	Description
text	The text to display inside the tool-tip
icon	Optional icon to display alongside the text.

The surface representing the tooltip will be readable from the surface field. Early termination of the tooltip is possible by calling the free() method.

window

gui.window({ Options... })

The window interface creates and manages windows in the UI. The table returned by this interface is tracked as a resource, and will need to be stored in at least one variable to keep the window active. If all references to the window are cleared, the window will be closed during garbage collection.

Valid options are:

Option	Description
aspectRatio	If true, enforces the aspect ratio defined by the minWidth and minHeight values.
center	Centers the window on screen if true.
client	Readable, defines the client boundaries around the frame.
close	Enables the close widget if true (default).
events	A table of event triggers. Supported events are show, focus, lostFocus, close, minimise and maximise.
focus	If false, the window does not automatically receive the focus when displayed.
icon	An icon to display in the titlebar.
insideWidth, insideHeight	Alternative to width and height; defines the internal size of the window.
maximise	Enables the maximise widget if true (default).
menubar	Optional configuration for a menubar.
minWidth, minHeight	The minimum acceptable width and height of the client area.
minimise	Enables the minimise widget if true (default).
modal	If true, the window acts as a modal dialog.
moveToBack	Enables the move-to-back widget if true (default).
orientation	Set to portrait or landspace to indicate orientation when fullscreen.
popOver	Keep the window in front of this surface.
quit	If true, sends a quit message to the client application when the window closes.
stickToFront	If true, keep the window at the front of the display at all times.
target	Optional reference to a viewport or surface that will contain the window.
title	A label to display in the window titlebar.
width, height	Size of the window.
x, y	The top-left position of the window.

Available methods are:

Method	Description
:show()	Display the window if not already shown.
:getClientSize()	Returns the size of the client area as { x, y, width, height }.
:getSize()	Returns the size of the window as { x, y, width, height }.
:hide()	Hide the window and move the user focus to the next active window.
:resize(X, Y, Width, Height)	Alter the window dimensions. Values can be set to nil to leave them unchanged.
:resizeClientArea(Width, Height)	Alter the internal size of the window and adjust the border automatically. Values can be set to nil to leave them unchanged.
:minimise()	Minimise the window.
:maximise()	Maximise the window.
:moveToBack()	Move the window to the back of the display.
:moveToFront()	Move the window to the front of the display.
:parentSize()	Return the width and height of the space hosting the window.

---

Views

There are currently two available interfaces for configuring views; columnview and listview. These are supported by a common library that ensures consistency in their interface design. This section declares the common functionality available for all views, and subsequent sections declare specific features for each type.

Items in the view are stored as a list of tables. They can be set by declaring items on initialisation, or at any other time with the addItems() method. Here's a working example of an item list that could be used to identify entries in a filesystem folder:

{ { id=1, group='file', path='parasol:system/', name='document.txt', size=1232, dateCreated='2018-08-02T17:14' },
  { id=2, group='folder', path='parasol:system/', name='config', icon='category/name' }
}

The id, group, name and icon keys are standard. The rest are considered to be custom attributes defined by the client. This table describes the standard item attributes:

Key	Description
id	A unique identifier for the item; this is primarily for client use.
group	The name of a common group to which the item belongs, e.g. file or folder.
name	The name of the item; this will be displayed as the item's name in the view.
icon	An icon to display with the item, in the format folder/icon.
colour	An rgba table that declares the colour to use when printing the item's name.

Common initialisation options for all views are:

Option	Description
dragDrop	Set to true to enable support for drag and drop.
items	Declare a list of items for immediate display after initialisation.
multiSelect	If true, more than one item can be selected at a time by the user.
noIcons	Do not display icons if true.
sensitive	If true, activation will occur when a new item is selected (double click no longer necessary).
target	The surface or vector viewport that will host the view.
width, height	Width and height values of the viewport, defaults to 100%.
x, y	Top left coordinates. Defaults to 0, 0.
xOffset, yOffset	Offsets can be defined as an alternative to width and height.

Listening to events is possible with the following callback options, all of which must be in the form of function(View, Reason, Item).

Option	Event Description
itemSelected	An item has been selected by the user.
itemActivated	An item has been activated by the user, e.g. by double clicking or pressing enter.
itemDeselected	An item has been deselected by the user.
activeChange	The active item has changed (includes reporting of deselection events)

The Reason value can be one of the following:

Value	Description
clear	All items in the view were removed.
inverted	Item automatically deselected due to an invert operation.
moved	The item has been deselected due to moving position.
user	Selected by user interaction (click or keypress).
manual	Item was manually selected (by the application, not the user).

After creation of the view, the following fields can be read from the view table:

Option	Description
hItem	Refers to the most recently highlighted item.
sItem	Refers to the most recently selected item.

Available methods are:

Method	Description
addItem(Item)	Add a single Item to the end of the view.
addItems(Items)	Add the provided list of Items to the end of the view.
clear()	Remove all items from the view. Relevant client callbacks will still be called.
deselectAll()	All items are immediately deselected.
disable()	Disable the view.
enable()	Re-enable the view.
loadItems(Items)	Load a new set of items and display them for the user. Any existing items will be cleared.
selectedItems()	Returns a table of all currently selected items.
selectItems(Conditional)	Manually select an item(s). The client must provide a Conditional function in the form function(Item). It must return true for any Item that needs to be selected.
selectAll()	All items are immediately selected.
sort(Attrib, Ascending)	Sort items by Attrib, which must appear in all items.
invertSelection()	Invert the selection of all items in the view.

columnview

gui.columnView({ Options... })

The gui.columnView() interface is used to display data to the user in the form of tabulated items.

The following initialisation options are specific to this interface:

Option	Description
columns	Declares the visible columns as a table of key-values.

Valid keys for the columns option are as follows:

Key	Description
attrib	Required. The column will be represented by this key value.
title	The name of the column; this will be displayed in the banner.
width	The pixel width of the column.
type	The type of the column, which will be reflected in the attrib values. Valid types are bytesize, date, numeric, seconds, float. Anything else is considered a string.
align	Align the column content to the left or right.
showIcons	Set to true to show icons alongside column text.

Here's an example of a valid columns list:

{ { attrib='name',        title='Name', width=160, showIcons=true },
  { attrib='size',        title='Size', width=70, type='bytesize', align='right' },
  { attrib='dateCreated', title='Date', width=100, type='date', align='right' }
}

Methods specific to the columnview interface are:

Method	Description
:setColumns(Columns)	Redefines the list of columns that will be displayed.
:sortColumn(Column, Ascending)	Sort all items by the given Column, which can be an index number or column name.

listview

gui.listview({ Options... })

The following initialisation options are specific to this interface:

Option	Description
compact	Activates compact styling; 1 = Tabulate horizontally; 2 = Compress horizontally
textAttrib	Declares the attribute to use as the main text when drawing each item. Defaults to text.