Context menu

A context menu is a clickable list of options in a panel. Options can run a function, trigger an event, open a submenu, show a progress bar, or show an image and details when highlighted. While a context menu is open it takes the mouse and keyboard.

You register a menu once with an id, then show it by that id.

registerMenuCopy Anchor Link

exports.lation_ui:registerMenu(menu)

Pass a list of menus to register several in one call. Registering an id again replaces the old menu. It raises an error when menu isn't a table or has no id.

The header, with the back button and the header icon, shows only when the menu has a title or subtitle; Backspace goes back either way. title, subtitle and each option's title and description take text formatting.

options can also be a table keyed by option title, as ox_lib takes it. lation ui turns it into a list, but Lua doesn't keep the order of a keyed table, so use a list when the order matters.

OptionsCopy Anchor Link

An option can use onSelect, event and serverEvent together; they run in that order. An option with menu opens that menu and runs none of them. An option with none of them and no menu does nothing when selected.

MetadataCopy Anchor Link

metadata takes any of these shapes:

-- Plain lines
metadata = { 'Owner: Lation', 'Plate: LATN 01' }

-- Label and value pairs, each with an optional bar
metadata = {
    { label = 'Fuel', value = '64%', progress = 64, progressColor = '#10B981' },
    { label = 'Mileage', value = 12840 }
}

-- A keyed table, shown as "key: value"
metadata = { Owner = 'Lation', Plate = 'LATN 01' }

CallbacksCopy Anchor Link

onSelectCopy Anchor Link

onSelect = function(args) end

Runs when the player clicks the option, presses Enter on it or presses its keybind. The menu closes first, unless the option has shouldClose = false.

onExitCopy Anchor Link

onExit = function() end

Runs when the player closes the menu with Escape, or when your script calls hideMenu(true). It doesn't run when the menu closes because an option was selected.

onBackCopy Anchor Link

onBack = function() end

Runs when the player goes back to the parent menu with the back button or Backspace, just before the parent opens.

showMenuCopy Anchor Link

exports.lation_ui:showMenu(id)

Opens the menu, in place of any context menu already open. It raises an error if no menu has that id.

hideMenuCopy Anchor Link

exports.lation_ui:hideMenu(onExit)

Closes the open menu and gives the mouse and keyboard back.

exports.lation_ui:hideMenu(true)

getOpenMenuCopy Anchor Link

local id = exports.lation_ui:getOpenMenu()

if exports.lation_ui:getOpenMenu() == 'garage_menu' then
    exports.lation_ui:hideMenu()
end

ControlsCopy Anchor Link

ExampleCopy Anchor Link

exports.lation_ui:registerMenu({
    id = 'garage_menu',
    title = 'Garage',
    subtitle = 'Pick a vehicle',
    headerIcon = 'fas fa-warehouse',
    options = {
        {
            title = 'Sultan RS',
            description = 'Plate LATN 01',
            icon = 'fas fa-car',
            progress = 64,
            progressColor = '#10B981',
            metadata = {
                { label = 'Fuel', value = '64%' },
                { label = 'Engine', value = '92%' }
            },
            serverEvent = 'my_garage:takeOut',
            args = { plate = 'LATN 01' }
        },
        {
            title = 'Impounded vehicles',
            icon = 'fas fa-ban',
            menu = 'garage_impound'
        },
        {
            title = 'Garage full',
            icon = 'fas fa-circle-info',
            readOnly = true
        }
    }
})

exports.lation_ui:registerMenu({
    id = 'garage_impound',
    title = 'Impound',
    menu = 'garage_menu',
    options = {
        {
            title = 'Pay release fee',
            description = '$500',
            icon = 'fas fa-dollar-sign',
            keybind = 'E',
            onSelect = function(args)
                print('Paying fee for', args.plate)
            end,
            args = { plate = 'LATN 02' }
        }
    }
})

exports.lation_ui:showMenu('garage_menu')