# Luakit Documentation / Modules / select_wm

# Module `select_wm`

Select a page element with a visual interface

This web module allows other Lua modules to select page elements with the same interface as that used by the follow mode plugin: a visual overlay is shown that allows the users to type to filter visible hints. For example, this module is used by the `formfiller` module when selecting a form to add.

## Functions

### select_wm.enter (page, elements, stylesheet, ignore_case)

Enter element selection mode on a web page.

The web page must not already be in element selection mode.

#### Parameters

- page
  Type: page
  The web page in which to enter element selection.
- elements
  Type: string or {dom_element}
  A selector to filter elements, or an array of elements.
- stylesheet
  Type: string
  The stylesheet to apply.
- ignore_case
  Type: boolean
  `true` if text case should be ignored.

#### Return Values

- {...}
  Table with data for the currently focused hint.
- number
  The number of currently visible hints.

### select_wm.leave (page)

Leave element selection mode on a web page.

The web page must be in element selection mode.

#### Parameters

- page
  Type: page or number
  The web page (or the web page id) in which to leave element selection.

### select_wm.changed (page, hint_pat, text_pat, text)

Update the element selection interface when user selection text changes.

The web page must be in element selection mode.

#### Parameters

- page
  Type: page
  The web page.
- hint_pat
  Type: string
  The hint pattern filter.
- text_pat
  Type: string
  The text pattern filter.
- text
  Type: string
  The full text.

#### Return Values

- table
  The currently focused hint.
- number
  The number of currently visible hints.

### select_wm.focus (page, step)

Update the element selection interface when the user moves the focus.

The web page must be in element selection mode.

###### Usage

    function handle_next (page)
        select_wm.focus(page, 1)
    end
    function handle_prev (page)
        select_wm.focus(page, -1)
    end

#### Parameters

- page
  Type: page
  The web page.
- step
  Type: number
  Relative number of tags to shift focus by.

#### Return Values

- table
  The currently focused hint.
- number
  The number of currently visible hints.

### select_wm.hints (page)

Get the current state of element hints on a web page.

The web page must be in element selection mode.

#### Parameters

- page
  Type: page
  The web page.

#### Return Values

- table
  The current hint state for `page`.

### select_wm.focused_hint (page)

Get the currently focused element hint on a web page.

The web page must be in element selection mode.

#### Parameters

- page
  Type: page
  The web page.

#### Return Values

- table
  The currently focused hint.

## Attribution

#### Copyright

- 2017 Aidan Holm