Toolbar core

Core Module - Toolbar

Dependencies

expcore.gui
expcore.roles
utils.event
utils.game
mod-gui
Gui.concept.button

Permissions

allowed(player, concept_name) Used to test if a player is allowed to use a button on the toolbar, if you are not using expcore.roles then change this function
set_permission_alias(concept_name, alias) Use to add an alias for the allowed test, alias is what is tested for rather than the concept name

Buttons

add_button_concept(concept) Adds a concept to be drawn to the button area and allows it to be toggled with the toggle toolbar button
update_buttons(player) Updates all the buttons for a player, this means hide and show buttons based on permissions
get_visible_buttons(player) Returns an array of buttons names that the given player is able to see, returns none if toolbar hidden
toolbar-button The base element to be used with the toolbar, others can be used but this is recomented

Frames

add_frame_concept(concept) Adds a frame concept to the toolbar frame area, this will not add a button to the toolbar
hide_frames(player) Hides all the frames for a player
get_visible_frames(player) Gets an array of the names of all the visible frames for a player
toolbar-frame The base toolbar frame, others can be used but this is recomented
Toolbar.frame:get_content(player) Gets the content area of the frame concept for this player, each player only has one area
Toolbar.frame:toggle_visible_state(player) Toggles the visibilty of this concept for the given player
Toolbar.frame:get_visible_state(player) Gets the current visibilty state of this conept for this player
Toolbar.frame:update(player[, event]) Triggers an update of the content within the concept for this player, uses on_update handlers
Toolbar.frame:update_all([event]) Triggers an update of the content with in this frame for all players

Other Elements

toolbar The main toolbar element, draws, updates, and controls the other concepts
toolbar-toggle Button which toggles the the visible state of all toolbar buttons, triggers on_button_update
toolbar-clear Button which hides all visible toolbar frames, triggers on_hide_frames

Dependencies

# expcore.gui
# expcore.roles
# utils.event
# utils.game
# mod-gui
# Gui.concept.button

Permissions

# allowed(player, concept_name)

Used to test if a player is allowed to use a button on the toolbar, if you are not using expcore.roles then change this function

Parameters:
  • player : (LuaPlayer) the player you want ot test is allowed to use this button
  • concept_name : (string) the name of the button concept that you want to see if the player is allowed to use
Returns:
  • (boolean) true if the player is allowed to use it
Usage:
-- Test if a player can use 'test-player-list'
local allowed = Toolbar.allowed(game.player,'test-player-list')
# set_permission_alias(concept_name, alias)

Use to add an alias for the allowed test, alias is what is tested for rather than the concept name

Parameters:
  • concept_name : (string) the name of the concept that will point to this alias
  • alias : (string) the permission string that will be tested when this concept is used with Toolbar.allowed
Usage:
-- Adding an alias for the 'test-player-list' concept
Toolbar.set_permission_alias('test-player-list','gui/player-list')

Buttons

# add_button_concept(concept)

Adds a concept to be drawn to the button area and allows it to be toggled with the toggle toolbar button

Parameters:
  • concept : (table) the gui concept that you want to add to the button area
Usage:
-- Adding a basic button to the toolbar
local new_button =
Gui.new_concept('button')
:set_caption('Click Me')
:on_click(function(event)
    event.player.print('You Clicked Me!!')
end)

Toolbar.add_button_concept(new_button)
# update_buttons(player)

Updates all the buttons for a player, this means hide and show buttons based on permissions

Parameters:
  • player : (LuaPlayer) the player to update the toolbar buttons for
Usage:
-- Updating your toolbar
Toolbar.update_buttons(player)
# get_visible_buttons(player)

Returns an array of buttons names that the given player is able to see, returns none if toolbar hidden

Parameters:
  • player : (LuaPlayer) the player you want to get the visible buttons of
Returns:
  • (table) an array of names of the visible buttons
Usage:
-- Get a list of all your visible buttons
Toolbar.get_visible_buttons(game.player)
# toolbar-button

The base element to be used with the toolbar, others can be used but this is recomented

Properties / Events:
  • permission_alias : (string) the alias used with Toolbar.allowed
Usage:
-- Adding a basic button to the toolbar, note no need to call Toolbar.add_button_concept
Gui.new_concept('toolbar-button')
:set_caption('Click Me')
:on_click(function(event)
    event.player.print('You Clicked Me!!')
end)

Frames

# add_frame_concept(concept)

Adds a frame concept to the toolbar frame area, this will not add a button to the toolbar

Parameters:
  • concept : (table) the gui concept that you want to add to the toolbar frame area
Usage:
-- Adding a basic frame to the frame area
local new_frame =
Gui.new_concept('frame')
:set_title('Test')

Toolbar.add_frame_concept(new_frame)
# hide_frames(player)

Hides all the frames for a player

Parameters:
  • player : (LuaPlayer) the player to hide the frames for
Usage:
-- Hiding all your frames
Toolbar.hide_frames(game.player)
# get_visible_frames(player)

Gets an array of the names of all the visible frames for a player

Parameters:
  • player : (LuaPlayer) the player that you want to get the visible frames of
Returns:
  • (table) an array of names of the visible frames for the given player
Usage:
-- Get all your visible frames
Toolbar.get_visible_frames(game.player)
# toolbar-frame

The base toolbar frame, others can be used but this is recomented

Properties / Events:
  • on_update : fired when the frame is to have its content updated
  • open_by_default : (boolean) weather the frame should be open when a player first joins
  • use_container : (boolean) true by default and will place a container inside the frame for content
  • direction : (string) the direction that the items in the frame are added
Usage:
-- Adding a basic player list
local player_list =
Gui.new_concept('toolbar-frame')
:set_permission_alias('player_list')
:set_caption('Player List')
:toggle_with_click()

:define_draw(function(properties,parent,element)
    local list_area =
    element.add{
        name = 'scroll',
        type = 'scroll-pane',
        direction = 'vertical',
        horizontal_scroll_policy = 'never',
        vertical_scroll_policy = 'auto-and-reserve-space'
    }
    Gui.set_padding(list_area,1,1,2,2)
    list_area.style.horizontally_stretchable = true
    list_area.style.maximal_height = 200

    for _,player in pairs(game.connected_players) do
        list_area.add{
            type='label',
            caption=player.name
        }
    end
end)

:on_update(function(event)
    local list_area = event.element.scroll
    list_area.clear()

    for _,player in pairs(game.connected_players) do
        list_area.add{
            type='label',
            caption=player.name
        }
    end
end)
# Toolbar.frame:get_content(player)

Gets the content area of the frame concept for this player, each player only has one area

Parameters:
  • player : (LuaPlayer) the player that you want to get the frame content for
Returns:
  • (LuaGuiElement) the content area of this concept for this player
Usage:
-- Get the content area of a concept
local frame = player_list:get_content(game.player)
# Toolbar.frame:toggle_visible_state(player)

Toggles the visibilty of this concept for the given player

Parameters:
  • player : (LuaPlayer) the player that you want to toggle the frame for
Returns:
  • (boolean) the new state of the visibilty of this concept for the player
Usage:
-- Toggle the frame for your self
player_list:toggle_visible_state(game.player)
# Toolbar.frame:get_visible_state(player)

Gets the current visibilty state of this conept for this player

Parameters:
  • player : (LuaPlayer) the player that you want the visibilty state for
Returns:
  • (boolean) the current visiblity state of this concept to the player
Usage:
-- Getting the current visiblity state
# Toolbar.frame:update(player[, event])

Triggers an update of the content within the concept for this player, uses on_update handlers

Parameters:
  • player : (LuaPlayer) the player to update the concept content for
  • event : (table) the event data that you want to pass to the update handlers (optional)
Usage:
-- Updating the frame for your player
player_list:update(game.player)
# Toolbar.frame:update_all([event])

Triggers an update of the content with in this frame for all players

Parameters:
  • event : (table) the event data that you want to pass to the update handlers (optional)
Usage:
-- Update the grame for all players
player_list:update_all()

Other Elements

# toolbar

The main toolbar element, draws, updates, and controls the other concepts

Properties / Events:
  • on_button_update : fired when the buttons are updated for a player
  • on_hide_frames : fired when the frames are hidden for a player
# toolbar-toggle

Button which toggles the the visible state of all toolbar buttons, triggers on_button_update

# toolbar-clear

Button which hides all visible toolbar frames, triggers on_hide_frames