Noble.Menu

An extended implementation of playdate.ui.gridview, meant for 1-dimensional, single-screen text menus.

Setup

Noble.Menu.new([__activate=true[, __alignment=Noble.Text.ALIGN_LEFT[, __localized=false[, __color=Graphics.kColorBlack[, __padding=2[, __horizontalPadding[, __margin=2[, __font=Noble.Text.getCurrentFont()[, __selectedCornerRadius=__font:getHeight()/4[, __selectedOutlineThickness=1]]]]]]]]]])
Create a new menu object.

Parameters

  • __activate boolean = true (default)
    Activate this menu upon creation.
  • __alignment = Noble.Text.ALIGN_LEFT (default)
    The text alignment of menu items.
  • __localized boolean = false (default)
    If true, menu item names are localization keys rather than display names.
  • __color = Graphics.kColorBlack (default)
    The color of menu item text. The selected highlight will be the inverse color.
  • __padding integer = 2 (default)
    Cell padding for menu items.
  • __horizontalPadding integer (optional)
    Use this to override horizontal padding, useful for certain fonts. If nil, uses __padding.
  • __margin integer = 2 (default)
    Spacing between menu items.
  • __font = Noble.Text.getCurrentFont() (default)
    If nil, uses current set font.
  • __selectedCornerRadius integer = __font:getHeight()/4 (default)
    Sets rounded corners for a selected menu item.
  • __selectedOutlineThickness integer = 1 (default)
    Sets the outline thickness for selected items.

Returns

    menu, a new menu item.

See

Usage

local menu = Noble.Menu.new(
	true,
	Noble.Text.ALIGN_CENTER,
	false,
	Graphics.kColorWhite,
	4, 6,
	Noble.Text.large,
	nil, 3
)
menu:addItem("Play Game", function() TitleScreen:playGame() end)
menu:addItem("Options", function() Noble.transition(OptionsScreen) end)
menu:addItem("Credits", function() Noble.transition(CreditsScreen) end)
menu:addItem(__nameOrKey[, __clickHandler[, __position[, __displayName[, __displayNameIsALocalizationKey=false]]]])
Adds a item to this menu.

Parameters

  • __nameOrKey string
    The name of this menu item. It can be a display name or a localization key. Must be unique.
  • __clickHandler function (optional)
    The function that runs when this menu item is "clicked."
  • __position integer (optional)
    Insert the item at a specific position. If not set, adds to the end of the list.
  • __displayName string (optional)
    You can create an optional, separate display name for this item. You can add or change this at runtime via setItemDisplayName.
  • __displayNameIsALocalizationKey boolean = false (default)
    If true, will treat the __displayName as a localization key. This is separate from this menu's localized value.

See

menu:removeItem([__menuItem=#menu.itemNames])
Removes a item from this menu.

Parameters

  • __menuItem int or string = #menu.itemNames (default)
    The menu item to remove. You can enter either the item's name/key or it's position. If left blank, removes the last item.

See

Properties

menu.localized
  • _ boolean = false (default)
    Indicates whether this menu's item names are treated as localization keys.
menu.currentItemNumber
  • _ integer
    The current menu item's index.

    This is meant as a read-only value. Do not modify it directly.

See

menu.currentItemName
  • _ string
    The current menu item's name.

    This is meant as a read-only value. Do not modify it directly.

See

menu.width
  • _ integer
    The width of the widest menu item plus the menu's horizontal padding.

    This is meant as a read-only value. Do not modify it directly.

Methods

menu:activate()
Activate this menu. This selects the most recently selected menu item (or the first item if none have been previously selected), and enables this menu's selectPrevious, selectNext, and click methods.

Usage

local menu = Noble.Menu.new(false)
menu:activate()
menu:deactivate()
Deactivate this menu. This deselects all menu items, and disables this menu's selectPrevious, selectNext, and click methods.

Usage

local menu = Noble.Menu.new(true)
menu:deactivate()
menu:isActive()
Check to see if this menu is currently active.

Returns

    bool
menu:selectPrevious([__force=false[, __wrapSelection=true]])
Selects the previous item in this menu. This menu must be active.

Parameters

  • __force boolean = false (default)
    Force this method to run, even if this menu is not active.
  • __wrapSelection boolean = true (default)
    Selects the final menu item if the first menu item is currently selected.

See

Usage

TitleScreen.inputHandler.upButtonDown = function()
	menu:selectPrevious()
end
menu:selectNext([__force=false[, __wrapSelection=true]])
Selects the next previous item in this menu. This menu must be active.

Parameters

  • __force boolean = false (default)
    Force this method to run, even if this menu is not active.
  • __wrapSelection boolean = true (default)
    Selects the first menu item if the final menu item is currently selected.

See

Usage

TitleScreen.inputHandler.downButtonDown = function()
	menu:selectNext()
end
menu:select(__menuItem[, __force=false])
Selects a specific item in this menu, either by it's index, or it's name. This menu must be active.

Parameters

  • __menuItem int or string
    The menu item to select. You can enter the item's number or it's name/key.
  • __force boolean = false (default)
    Force this method to run, even if this menu is not active.

See

Usage

function resetMenu()
	menu:select(1, true)
	menu:deactivate()
end
function resetMenu()
	menu:select("Play Game", true)
	menu:deactivate()
end
menu:click([__force=false])
Runs the function associated with the currently selected menu item. This menu must be active.

Parameters

  • __force boolean = false (default)
    Force this method to run, even if this menu is not active.

See

Usage

TitleScreen.inputHandler.AButtonDown = function()
	menu:click()
end
menu:getItemDisplayName(__itemName)
Gets the display name of a menu item.

If a menu item does not have a display name, then the __nameOrKey (or its localized string) will be returned instead. This method is used internally when draw is called.

If this menu's localized value is true, a returned __nameOrKey will always be localized, but a returned display name is only localized if the __displayNameIsALocalizationKey argument was set to true when the display name was added.

Parameters

  • __itemName string
    The menu item you want the display name of.

Returns

    string

See

menu:setItemDisplayName(__itemName, __displayName[, __displayNameIsALocalizationKey=false])
When you add a menu item, you can give it a display name that's different from it's actual name. This method adds or changes the display name of a menu item.

Parameters

  • __itemName string
    The menu item name (or key if this menu uses localization keys).
  • __displayName string
    The display name.
  • __displayNameIsALocalizationKey boolean = false (default)
    Set to use to indicate that this display name is a localization key. This setting is separate from localized

Usage

function changeDifficultyLevel(__level)
	menu:setItemDisplayName("Difficulty", "Difficulty: " .. __level)
end

Tables

menu.itemNames
A string "array" of menu item strings/keys. You cannot add or remove menu items by modifying this table. It is meant as a read-only table, provided for convenience when iterating, etc. Modifying its values may break other methods.

See

Usage

for i = 1, #menu.itemNames, 1 do
	menu.clickHandlers[menu.itemNames[i]]	= nil -- Clears all click handlers, for some reason.
end
menu.clickHandlers
A table of functions associated with menu items. Items are a defined when calling addItem, but their associated functions may be modified afterward.

You cannot add or remove menu items by modifying this table.

See

Usage

local menu = Noble.Menu.new(true)
menu.addItem("Play Game")
menu.addItem("Options")

menu.clickHandlers["Play Game"] = function() TitleScreen:playGame() end
menu.clickHandlers["Options"] = function() Noble.transition(OptionsScreen) end
local menu = Noble.Menu.new(true)
menu.addItem("Play Game")
menu.addItem("Options")

menu.clickHandlers = {
	["Play Game"] = function TitleScreen:playGame() end,
	["Options"] = function() Noble.transition(OptionsScreen) end
}
menu.itemPositions
A key/value table of menu item indices.

This is meant as a read-only table, provided for convenience. Modifying its values will break other methods.

Usage

menu.itemPositions["Play Game"]	-- 1
menu.itemPositions["Options"]	-- 2
menu.itemWidths
A key/value table of pixel widths for each menu item, based on its text. Useful for animation, layout, etc.

This is meant as a read-only table, provided for convenience. Modifying its values will break other methods.

Usage

local playGameMenuItemWidth = menu.itemWidths["Play Game"]

Drawing

menu:draw(__x, __y)
Draw's this menu to the screen. You may call this manually, but ideally, you will put it in in your scene's update or drawBackground method.

Parameters

  • __x
  • __y

Usage

function YourScene:update()
	YourScene.super.update(self)
	menu:draw(50, 100)
end
menu:drawItem(__x, __y, __itemIndex)
This method is called for every non-selected item when draw is called. You shouldn't call this directly, but you may re-implement it if you wish.

Parameters

  • __x
  • __y
  • __itemIndex

See

Usage

-- This is the default implementation for this method.
function menu:drawItem(__x, __y, __itemIndex)
	Graphics.setImageDrawMode(self.fillMode)
	local xAdjustment = 0
	if (self.alignment == Noble.Text.ALIGN_CENTER) then
		xAdjustment = self.width/2 - self.horizontalPadding/2
	elseif (self.alignment == Noble.Text.ALIGN_RIGHT) then
		xAdjustment = self.width - self.horizontalPadding
	end
	Noble.Text.draw(self.itemNames[__itemIndex], __x + self.horizontalPadding/2 + xAdjustment, __y + self.padding/2, self.alignment, self.localized, self.font)
end
menu:drawSelectedItem(__x, __y, __itemIndex)
This method is called for every selected item when draw is called. You shouldn't call this directly, but you may re-implement it if you wish.

Parameters

  • __x
  • __y
  • __itemIndex

See

Usage

-- This is the default implementation for this method.
function menu:drawSelectedItem(__x, __y, __itemIndex)
	local xAdjustmentText = 0
	local xAdjustmentRect = 0
	if (self.alignment == Noble.Text.ALIGN_CENTER) then
		xAdjustmentText = self.width/2 - self.horizontalPadding/2
	xAdjustmentRect = self.width/2 - self.itemWidths[self.itemNames[__itemIndex]]/2 - self.horizontalPadding/2
	elseif (self.alignment == Noble.Text.ALIGN_RIGHT) then
		xAdjustmentText = self.width - self.horizontalPadding
		xAdjustmentRect = self.width - self.itemWidths[self.itemNames[__itemIndex]] - self.horizontalPadding
	end
	Graphics.setColor(self.color)
	Graphics.fillRoundRect(__x + xAdjustmentRect, __y, self.itemWidths[self.itemNames[__itemIndex]]+self.horizontalPadding, self.textHeight+self.padding, self.selectedCornerRadius)
	Graphics.setColor(self.otherColor)
	Graphics.setLineWidth(self.selectedOutlineThickness)
	Graphics.drawRoundRect(__x + xAdjustmentRect, __y, self.itemWidths[self.itemNames[__itemIndex]]+self.horizontalPadding, self.textHeight+self.padding, self.selectedCornerRadius)
	Graphics.setImageDrawMode(self.otherFillMode)
	Noble.Text.draw(self.itemNames[__itemIndex], __x + self.horizontalPadding/2 + xAdjustmentText, __y+self.padding/2, self.alignment, self.localized, self.font)
end
Noble Engine by Mark LaCroix, Noble Robot Documentation created using LDoc 1.5.0.