Class widget

GTK+ user interface widgets
This module is only available from the UI process Lua state.

The widget class provides a wrapper around GTK's widget system, allowing Lua code to build and modify the user interface.

This page lists functions, methods, and properties common to all widget types, as well as some methods and properties that are common to a subset of widget types. Documentation pages for specific widget types will list only properties, methods, functions, and signals that are unique to each type of widget.

Note: some user interface widgets are also provided by the lousy.widget library.

Widget types

The following widget types are available:

  • box: A box for packing other widgets vertically or horizontally.
  • drawing_area: A widget used for external drawing.
  • entry: A text input box.
  • event_box: A widget used to receive events for some kinds of sub-widgets.
  • image: A widget used to display an image.
  • label: A text label that displays short strings of formatted text.
  • notebook: Groups a set of widgets, only one of which will be visible at a time.
  • overlay: Allows laying widgets over the top of other widgets.
  • paned: A two-pane interface widget, with a draggable slider between panes.
  • scrolled: A widget that allows its contents to be scrolled.
  • socket: A widget that allows drawing from an external GTK program.
  • spinner: A loading spinner, used to indicate activity of indefinite duration.
  • webview: Shows the contents of a web page and allows page interaction.
  • window: A window contains all other user interface elements.

Creating a new widget

To create a new widget, use the widget constructor:

local view = widget{ type = ... }

The type field must be provided.

Destroying a webview widget

view:destroy()

Functions

widget (props)

Create a new widget. It is mandatory to specify a type as an initial property, as this is needed to construct the widget internally.

Parameters

  • props
    Type: table
    Initial widget properties. A type field is mandatory.

Return Values

  • widget
    The newly-constructed widget.

Methods

widget:show ()

Show the widget.

widget:hide ()

Hide the widget.

widget:focus ()

Move the input focus for the widget's window to the widget. If the widget is a window, it will instead unfocus the currently focused widget within the window.

widget:destroy ()

Destroy the widget.

widget:replace (other)

Remove the widget from its parent, replacing it with other. All child properties, such as the arrangement and relative position of the widget within its parent, are maintained.

If the widget does not have a parent, this method does nothing.

Parameters

  • other
    Type: widget
    The replacement widget.

widget:remove (child)

Remove a specific child widget from the widget. Only certain types of widgets have this property: specifically, the box, event box, notebook, paned, and window widgets.

Parameters

  • child
    Type: widget
    The child widget to remove.

widget:send_key (keystring, modifiers)

Send synthetic key events to the widget. This function parses a vim-like keystring into single keys and sends them to the widget. When window.act_on_synthetic_keys is disabled, synthetic key events will not trigger other key bindings.

Parameters

  • keystring
    Type: string
    The string representing the keys to send.
  • modifiers
    Type: table
    The key modifiers table.

Properties

widget.type

Type: string
Read-only
The type of the widget. Must be specified during creation, and cannot be modified later.

widget.is_alive

Type: boolean
Read-only
Whether the widget is alive. If it is not (i.e. it has been destroyed), then this is the only property that can be accessed without raising an error.

widget.margin

Type: integer
Read-write
Combined property for all widget margins, in pixels.

widget.margin_top

Type: integer
Read-write
The margin above the widget, in pixels.

widget.margin_bottom

Type: integer
Read-write
The margin below the widget, in pixels.

widget.margin_left

Type: integer
Read-write
The margin to the left of the widget, in pixels.

widget.margin_right

Type: integer
Read-write
The margin to the right of the widget, in pixels.

widget.parent

Type: widget or nil
Read-only
The widget's parent widget, if it has one.

widget.child

Type: widget or nil
Read-write
The widget's single child widget, if it has one. Only certain types of widgets have this property; specifically, the event box, overlay, scrolled, and window widgets.

widget.focused

Type: boolean
Read-only
Whether the widget has the input focus.

widget.visible

Type: boolean
Read-write
Whether the widget is visible.

widget.tooltip

Type: string
Default: nil
Read-write
The text displayed in the tooltip shown when the cursor is hovered above the widget, or nil if no tooltip should be displayed.

widget.width

Type: integer
Read-only
The width of the widget, in pixels.

widget.height

Type: integer
Read-only
The height of the widget, in pixels.

widget.min_size

Type: table
Read-write
The minimum size of the widget, in pixels.

widget.children

Type: {widget}
Read-only
A newly-created array of the widget's children. Modification of this array does not affect the user interface. Only certain types of widgets have this property: specifically, the box, event box, notebook, paned, and window widgets.

Signals

"create"

Emitted on the widget library when a new widget has been created.

Parameters

  • widget
    Type: widget
    The newly-created widget.

"destroy"

Emitted when the widget is about to be destroyed.

"resize"

Emitted when the widget has been resized.

"focus"

Emitted when the webview widget gains the input focus.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"unfocus"

Emitted when the webview widget loses the input focus.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"parent-set"

Emitted when the widget is either added or removed from a parent widget.

Parameters

  • parent
    Type: widget or nil
    The widget's parent, or nil.

Attribution

Copyright

  • 2010 Mason Larobina