## 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