Menus

Table of Contents

• Overview
  • Main Menu Bar
  • Context Menus
  • Menu Items
• API
  • BeginMainMenuBar
  • EndMainMenuBar
  • BeginMenuBar
  • EndMenuBar
  • BeginMenu
  • EndMenu
  • BeginContextMenuItem
  • BeginContextMenuWindow
  • EndContextMenu
  • MenuItem
  • MenuItemChecked

Overview

Menus are windows that allow users to make a selection from a list of items. Below are descriptions of the various menus and how they can be utilized.

Main Menu Bar

This section describes the usage of the main menu bar. The main menu bar is rendered at the top of the window with menu items being added from left to right. When a menu item is clicked, a context menu is opened below the selected item. Creating the main menu bar can open anywhere in the code after the Slab.Update call. These functions should not be called within a BeginWindow/EndWindow call.

if Slab.BeginMainMenuBar() then
    if Slab.BeginMenu("File") then
        if Slab.BeginMenu("New") then
            if Slab.MenuItem("File") then
                -- Create a new file.
            end

            if Slab.MenuItem("Project") then
                -- Create a new project.
            end

            Slab.EndMenu()
        end

        Slab.MenuItem("Open")
        Slab.MenuItem("Save")
        Slab.MenuItem("Save As")

        Slab.Separator()

        if Slab.MenuItem("Quit") then
            love.event.quit()
        end

        Slab.EndMenu()
    end

    Slab.EndMainMenuBar()
end

Context Menus

These are menus which are rendered above all other controls to allow the user to make a selection out of a list of items. These can be opened up through the menu bar, or through a right-click action from the user on a given window or control. Menus and menu items make up the context menu and menus can be nested to allow a tree options to be displayed.

-- This is placed outside of a BeginWindow/EndWindow call for context menus in the void space.
if Slab.BeginContextMenuWindow() then
    Slab.MenuItem("Global Item 1")
    Slab.MenuItem("Global Item 2")

    if Slab.BeginMenu("Global Item 3") then
        Slab.MenuItem("Sub Item 1")
        Slab.MenuItem("Sub Item 2")
        Slab.EndMenu()
    end

    Slab.EndContextMenu()
end

Below is an example of creating context menus for different controls of a window.

Slab.Button("My Button 1")

if Slab.BeginContextMenuItem() then
    Slab.MenuItem("My Button 1 Item 1")
    Slab.MenuItem("My Button 1 Item 2")
    Slab.EndContextMenu()
end

Slab.Button("My Button 2")

if Slab.BeginContextMenuItem() then
    Slab.MenuItem("My Button 2 Item 1")
    Slab.MenuItem("My Button 2 Item 2")
    Slab.EndContextMenu()
end

Below is an example of a context menu specific for a window.

Slab.BeginWindow('MyFirstWindow', {Title = "My First Window"})
Slab.Button("My Button")

if Slab.BeginContextMenuWindow() then
    Slab.MenuItem("My Window Item 1")
    Slab.MenuItem("My Window Item 2")
    Slab.EndContextMenu()
end

Slab.EndWindow()

Context menus can also be opened using other mouse buttons. This is handled through the first parameter of BeginContextMenuItem/BeginContextMenuWindow, which specifies which mouse button to use when opening the menu.

Slab.BeginWindow('Left_Mouse_Context_Menu', {Title = "Left Mouse Context Menu"})
Slab.Button("Button")

if Slab.BeginContextMenuItem(1) then
    Slab.MenuItem("Context Menu Item 1")
    Slab.MenuItem("Context Menu item 2")

    Slab.EndContextMenu()
end

Slab.EndWindow()

Menu Items

Menu items make up the contents of a context menu. When a menu item is clicked, the function will return true. There are currently two types of menu items supported. They are the standard menu items and a checked menu item.

API

Below is a list of functions associated with the Menu API.

BeginMainMenuBar

This function begins the process for setting up the main menu bar. This should be called outside of any BeginWindow/EndWindow calls. The user should only call EndMainMenuBar if this function returns true. Use BeginMenu/EndMenu calls to add menu items on the main menu bar.

Return	Description
Boolean	Returns true if the main menu bar process has started.

EndMainMenuBar

This function should be called if BeginMainMenuBar returns true.

BeginMenuBar

This function begins the process of rendering a menu bar for a window. This should only be called within a BeginWindow/EndWindow context.

Parameter	Type	Description
IsMainMenuBar	Boolean	Is this menu bar for the main viewport. Used internally. Should be ignored for all other calls.

Return	Description
Boolean	Returns true if the menu bar process has started.

EndMenuBar

This function should be called if BeginMenuBar returns true.

BeginMenu

Adds a menu item that when the user hovers over, opens up an additional context menu. When used within a menu bar, BeginMenu calls will be added to the bar. Within a context menu, the menu item will be added within the context menu with an additional arrow to notify the user more options are available. If this function returns true, the user must call EndMenu.

Parameter	Type	Description
Label	String	The label to display for this menu.
Options	Table	List of options that control how this menu behaves.

Option	Type	Description
Enabled	Boolean	Determines if this menu is enabled. This value is true by default. Disabled items are displayed but cannot be interacted with.

Return	Description
Boolean	Returns true if the menu item is being hovered.

EndMenu

Finishes up a BeginMenu. This function must be called if BeginMenu returns true.

BeginContextMenuItem

Opens up a context menu based on if the user right clicks on the last item. This function should be placed immediately after an item call to open up a context menu for that specific item. If this function returns true, EndContextMenu must be called.

Parameter	Type	Description
Button	Number	The mouse button to use for opening up this context menu.

Return	Description
Boolean	Returns true if the user right clicks on the previous item call. EndContextMenu must be called in order for this to function properly.

BeginContextMenuWindow

Opens up a context menu based on if the user right clicks anywhere within the window. It is recommended to place this function at the end of a window's widget calls so that Slab can catch any BeginContextMenuItem calls before this call. If this function returns true, EndContextMenu must be called.

Parameter	Type	Description
Button	Number	The mouse button to use for opening up this context menu.

Return	Description
Boolean	Returns true if the user right clicks anywhere within the window. EndContextMenu must be called in order for this to function properly.

EndContextMenu

Finishes up any BeginContextMenuItem/BeginContextMenuWindow if they return true.

MenuItem

Adds a menu item to a given context menu.

Parameter	Type	Description
Label	String	The label to display to the user.
Options	Table	List of options that control how this menu behaves.

Option	Type	Description
Enabled	Boolean	Determines if this menu is enabled. This value is true by default. Disabled items are displayed but cannot be interacted with.

Return	Description
Boolean	Returns true if the user clicks on this menu item.

MenuItemChecked

Adds a menu item to a given context menu. If IsChecked is true, then a check mark will be rendered next to the label.

Parameter	Type	Description
Label	String	The label to display to the user.
IsChecked	Boolean	Determines if a check mark should be rendered next to the label.
Options	Table	List of options that control how this menu behaves.

Option	Type	Description
Enabled	Boolean	Determines if this menu is enabled. This value is true by default. Disabled items are displayed but cannot be interacted with.

Return	Description
Boolean	Returns true if the user clicks on this menu item.