# Luakit Documentation / Classes / widget

# 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