Client

Last updated on

local menu = OPX.Api.Get('menu')

From client code inside opx_infinity. Every function answers a Result ({ ok = true, value } or { ok = false, error }). None yields, unless the spec opts in with yield = true. Codes: Refusal codes.

Open

Opens a menu from a spec. The spec is refused whole on the first bad field.

menu.Open(spec)

Parameters

• spec: table — see The menu spec

Returns

• Result — value { handle, id, nodes }

• Another owner's menu open: menu_busy, unless spec.steal = true.

• The same owner opening again replaces its menu (close reason reopened).

local menu = OPX.Api.Get('menu')
local opened = menu.Open({
  owner = 'mymodule',
  title = 'GARAGE',
  items = {
    { id = 'out', label = 'Take out', icon = 'vehicle' },
    { id = 'lights', label = 'Lights', toggle = false },
    { label = 'Close', close = true },
  },
  on = function(p)
    if p.action == 'select' and p.itemId == 'out' then --[[ ... ]] end
  end,
})
if not opened.ok then print(opened.error) end

Close

Closes the menu.

menu.Close(handle, reason)

Parameters

• handle: integer — required (handle_required)
• reason?: string
  • Max 32 characters, passed to the close callback. Default caller.

Returns

• Result — value true

Update

Rebuilds the open menu and keeps the player's position (submenus stay open while a row with the same id still exists).

menu.Update(handle, patch)
menu.Update(patch)

Parameters

• handle?: integer
• patch: table
  • Patchable: items, title, on, data, closeOnSelect, reportFocus, status, statusBad, cursor.
  • items is all or nothing. Geometry and focus are fixed at open.

Returns

• Result — value true

menu.Update(opened.value.handle, { title = 'GARAGE (2)' })

SetStatus

Shows text as a toast. There is no status line under the list any more.

menu.SetStatus(handle, text, bad)

Parameters

• handle?: integer
• text: string — max 120 characters
• bad?: boolean — red when true

Returns

• Result — value true

State

What is on screen now.

menu.State()

Returns

• Result — value { open = false } or { open, handle, owner, menu, title, depth, index, total, itemId, label, value }

Keys

For a caller printing its own key hint.

menu.Keys()

Returns

• Result — value { backend, keys, labels }
  • backend: page, or none when no surface exists
  • keys: maps UP DOWN LEFT RIGHT SELECT BACK to ARROW UP … ENTER, BACKSPACE
  • labels: the locale words

The menu spec

Limits: 200 rows per level, 400 rows across the whole tree, 8 levels deep. Only the visible window of rows is sent to the page. Checking a spec costs roughly 240 instructions per row: for more than a few dozen rows, page them or pass yield = true from a thread.

CreateThread(function()
  local opened = menu.Open({ owner = 'mymodule', items = rows, on = onAction, yield = true })
  if not opened.ok then print(opened.error) end
end)

Rows

A row's kind comes from its shape. Tested in this order; the first match wins.

Fields every row may carry:

Confirm rows

A row with confirm opens a two-row level instead of acting. The first row keeps things as they are (a back row, so Enter pressed without looking does nothing); the second does what the row said, under the same id and data, so on receives the select it always did.

items = {
  { id = 'delete', label = 'Delete outfit', icon = 'trash', confirm = { yes = 'Delete outfit', no = 'Keep it' } },
  { id = 'sell', label = 'Sell', confirm = true },
},
on = function(p)
  if p.action == 'select' and p.itemId == 'delete' then --[[ only after the second row ]] end
end,

The action payload

on(payload) and the opx:on:menu:action event receive the same table.