Gui core

Core Module - Gui - Used to define new gui elements and gui event handlers

Usage

-- Defining a button that prints the player's name
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
:on_click(function(player,element,event)
    player.print(player.name)
end)
-- Defining a button with a custom style
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
:style{
    height = 25,
    width = 100
}
:on_click(function(player,element,event)
    player.print(player.name)
end)
-- Defining a button using a custom function
local example_flow_with_button =
Gui.element(function(event_trigger,parent)
    -- Add the flow the button is in
    local flow =
    parent.add{
        name = 'example_flow',
        type = 'flow'
    }

    -- Get the players name
    local player = game.players[parent.player_index]
    local player_name = player.name

    -- Add the button
    local element =
    flow.add{
        name = event_trigger,
        type = 'button',
        caption = 'Example Button: '..player_name
    }

    -- Set the style of the button
    local style = element.style
    style.height = 25
    style.width = 100]
    style.font_color = player.color

    -- Return the element
    return element
end)
:on_click(function(player,element,event)
    player.print(player.name)
end)
-- Drawing an element
local exmple_button_element = example_button(parent)
local example_flow_with_button = example_flow_with_button(parent)

Dependencies

utils.event
mod-gui

Tables

top_elements Contains the uids of the elements that will show on the top flow and the auth function
left_elements Contains the uids of the elements that will show on the left flow and the open on join function
defines Table of all the elements which have been registed with the draw function and event handlers
file_paths An index used for debuging to find the file where different elements where registered
_prototype_element The element prototype which is returned from Gui.element
_mt_element The prototype metatable applied to new element defines

Fields

uid The current highest uid that is being used, will not increase during runtime

Element Define

element(element_define) Base function used to define new elements, can be used with a table or with a function
Gui._prototype_element:style(style_define) Extension of Gui.element when using the table method, values applied after the element is drawn
Gui._prototype_element:add_to_top_flow([authenticator]) Adds an element to be drawn to the top flow when a player joins
Gui._prototype_element:add_to_left_flow([open_on_join]) Adds an element to be drawn to the left flow when a player joins

Element Events

Gui._prototype_element.on_opened Called when the player opens a GUI.
Gui._prototype_element.on_closed Called when the player closes the GUI they have open.
Gui._prototype_element.on_click Called when LuaGuiElement is clicked.
Gui._prototype_element.on_confirmed Called when a LuaGuiElement is confirmed, for example by pressing Enter in a textfield.
Gui._prototype_element.on_checked_changed Called when LuaGuiElement checked state is changed (related to checkboxes and radio buttons).
Gui._prototype_element.on_elem_changed Called when LuaGuiElement element value is changed (related to choose element buttons).
Gui._prototype_element.on_location_changed Called when LuaGuiElement element location is changed (related to frames in player.gui.screen).
Gui._prototype_element.on_tab_changed Called when LuaGuiElement selected tab is changed (related to tabbed-panes).
Gui._prototype_element.on_selection_changed Called when LuaGuiElement selection state is changed (related to drop-downs and listboxes).
Gui._prototype_element.on_switch_changed Called when LuaGuiElement switch state is changed (related to switches).
Gui._prototype_element.on_text_change Called when LuaGuiElement text is changed by the player.
Gui._prototype_element.on_value_changed Called when LuaGuiElement slider value is changed (related to the slider element).

Top Flow

toggle_top_flow Button which toggles the top flow elements
top_flow_button_style The style that should be used for buttons on the top flow
get_top_flow(player) Gets the flow which contains the elements for the top flow
update_top_flow(player) Updates the visible states of all the elements on a players top flow
toggle_top_flow(player[, state]) Toggles the visible states of all the elements on a players top flow

Left Flow

hide_left_flow Button which hides the elements in the left flow
get_left_flow(player) Gets the flow which contains the elements for the left flow
hide_left_flow(player) Hides all left elements for a player
toggle_left_element(player, element_define[, state]) Toggles the visible state of all a left element for a player

Helper Functions

get_player_from_element(element) Get the player that owns a gui element
toggle_enabled_state(element[, state]) Will toggle the enabled state of an element or set it to the one given
toggle_visible_state(element[, state]) Will toggle the visible state of an element or set it to the one given
destroy_if_valid(element) Destory a gui element without causing any errors, likly if the element may have already been removed
alignment(parent[, horizontal_align='right'][, vertical_align='center'][, name='alignment']) Draw a flow that has custom element alignments, default is right align
scroll_table(parent, height, column_count[, name='scroll']) Draw a scroll pane that has a table inside of it
header(parent, caption[, tooltip][, add_alignment=false][, name='header']) Used to add a header to a frame, this has the option for a custom right alignment flow for buttons

Dependencies

# utils.event
# mod-gui

Tables

# top_elements

Contains the uids of the elements that will show on the top flow and the auth function

# left_elements

Contains the uids of the elements that will show on the left flow and the open on join function

# defines

Table of all the elements which have been registed with the draw function and event handlers

# file_paths

An index used for debuging to find the file where different elements where registered

# _prototype_element

The element prototype which is returned from Gui.element

# _mt_element

The prototype metatable applied to new element defines

Fields:
  • __call

Fields

# uid

The current highest uid that is being used, will not increase during runtime

  • uid

Element Define

# element(element_define)

Base function used to define new elements, can be used with a table or with a function

Parameters:
  • element_define : (table or function) used to define how the element is draw, using a table is the simplist way of doing this
Returns:
  • (table) the new element define that is used to register events to this element
Usage: 
-- Defining an element with a table
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
-- Defining an element with a function
local example_flow_with_button =
Gui.element(function(event_trigger,parent,...)
    -- Add the flow the button is in
    local flow =
    parent.add{
        name = 'example_flow',
        type = 'flow'
    }

    -- Add the button
    local element =
    flow.add{
        name = event_trigger,
        type = 'button',
        caption = 'Example Button'
    }

    -- Set the style of the button
    local style = element.style
    style.height = 25
    style.width = 100

    -- Return the element
    return element
end)
# Gui._prototype_element:style(style_define)

Extension of Gui.element when using the table method, values applied after the element is drawn

Parameters:
  • style_define : (table or function) used to define how the style is applied, using a table is the simplist way of doing this
Returns:
  • (table) the new element define that is used to register events to this element
Usage: 
-- Setting the height and width of the example button
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
:style{
    height = 25,
    width = 100
}
-- Using a function to set the style
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
:style(function(style,element,...)
    local player = game.players[element.player_index]
    style.height = 25
    style.width = 100
    style.font_color = player.color
end)
# Gui._prototype_element:add_to_top_flow([authenticator])

Adds an element to be drawn to the top flow when a player joins

Parameters:
  • authenticator : (function) called during toggle or update to decide if the element should be visible (optional)
Returns:
  • (table) the new element define that is used to register events to this element
Usage: 
-- Adding the example button
example_button:add_to_top_flow(function(player)
    -- example button will only show when game time is less than 1 minute
    return player.online_time < 3600
end)
# Gui._prototype_element:add_to_left_flow([open_on_join])

Adds an element to be drawn to the left flow when a player joins

Parameters:
  • open_on_join : (boolean or function) called during first darw to decide if the element is visible (optional)
Returns:
  • (table) the new element define that is used to register events to this element
Usage: 
-- Adding the example button
example_flow_with_button:add_to_left_flow(true)

Element Events

# Gui._prototype_element.on_opened

Called when the player opens a GUI.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_closed

Called when the player closes the GUI they have open.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_click

Called when LuaGuiElement is clicked.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_confirmed

Called when a LuaGuiElement is confirmed, for example by pressing Enter in a textfield.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_checked_changed

Called when LuaGuiElement checked state is changed (related to checkboxes and radio buttons).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_elem_changed

Called when LuaGuiElement element value is changed (related to choose element buttons).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_location_changed

Called when LuaGuiElement element location is changed (related to frames in player.gui.screen).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_tab_changed

Called when LuaGuiElement selected tab is changed (related to tabbed-panes).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_selection_changed

Called when LuaGuiElement selection state is changed (related to drop-downs and listboxes).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_switch_changed

Called when LuaGuiElement switch state is changed (related to switches).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_text_change

Called when LuaGuiElement text is changed by the player.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_value_changed

Called when LuaGuiElement slider value is changed (related to the slider element).

  • handler : (function) the event handler which will be called

Top Flow

# toggle_top_flow

Button which toggles the top flow elements

# top_flow_button_style

The style that should be used for buttons on the top flow

# get_top_flow(player)

Gets the flow which contains the elements for the top flow

(player)

Parameters:
  • player : (LuaPlayer) the player that you want to get the flow for
Returns: Usage: 
-- Geting your top element flow
local top_flow = Gui.get_top_flow(game.player)
# update_top_flow(player)

Updates the visible states of all the elements on a players top flow

Parameters:
  • player : (LuaPlayer) the player that you want to update the flow for
Usage: 
-- Update your flow
Gui.update_top_flow(game.player)
# toggle_top_flow(player[, state])

Toggles the visible states of all the elements on a players top flow

Parameters:
  • player : (LuaPlayer) the player that you want to toggle the flow for
  • state : (boolean) if given then the state will be set to this state (optional)
Returns:
  • (boolean) the new visible state of the top flow
Usage: 
-- Toggle your flow
Gui.toggle_top_flow(game.player)
-- Open your top flow
Gui.toggle_top_flow(game.player,true)

Left Flow

# hide_left_flow

Button which hides the elements in the left flow

# get_left_flow(player)

Gets the flow which contains the elements for the left flow

(player)

Parameters:
  • player : (LuaPlayer) the player that you want to get the flow for
Returns: Usage: 
-- Geting your left element flow
local left_flow = Gui.get_left_flow(game.player)
# hide_left_flow(player)

Hides all left elements for a player

Parameters:
  • player : (LuaPlayer) the player to hide the elements for
Usage: 
-- Hide your left elements
Gui.hide_left_flow(game.player)
# toggle_left_element(player, element_define[, state])

Toggles the visible state of all a left element for a player

Parameters:
  • player : (LuaPlayer) the player that you want to toggle the element for
  • element_define : (table) the element that you want to toggle for the player
  • state : (boolean) if given then the state will be set to this state (optional)
Returns:
  • (boolean) the new visible state of the element
Usage: 
-- Toggle your example button
Gui.toggle_top_flow(game.player,example_flow_with_button)
-- Open your example button
Gui.toggle_top_flow(game.player,example_flow_with_button,true)

Helper Functions

# get_player_from_element(element)

Get the player that owns a gui element

Parameters:
  • element : (LuaGuiElement) the element that you want to get the owner of
Returns:
  • (LuaPlayer) the player that owns this element
Usage: 
-- Geting the owner of an element
local player = Gui.get_player_from_element(element)
# toggle_enabled_state(element[, state])

Will toggle the enabled state of an element or set it to the one given

Parameters:
  • element : (LuaGuiElement) the element that you want to toggle the state of
  • state : (boolean) the state that you want to set (optional)
Returns:
  • (boolean) the new enabled state that the element has
Usage: 
-- Toggling the the enabled state
local new_enabled_state = Gui.toggle_enabled_state(element)
# toggle_visible_state(element[, state])

Will toggle the visible state of an element or set it to the one given

Parameters:
  • element : (LuaGuiElement) the element that you want to toggle the state of
  • state : (boolean) the state that you want to set (optional)
Returns:
  • (boolean) the new visible state that the element has
Usage: 
-- Toggling the the visible state
local new_visible_state = Gui.toggle_visible_state(element)
# destroy_if_valid(element)

Destory a gui element without causing any errors, likly if the element may have already been removed

Parameters: Returns:
  • (boolean) true if the element was valid and has been removed
Usage: 
-- Likely use case for element not existing
Gui.destroy_if_valid(element[child_name])
# alignment(parent[, horizontal_align='right'][, vertical_align='center'][, name='alignment'])

Draw a flow that has custom element alignments, default is right align

Parameters:
  • parent : (LuaGuiElement) the parent element that the alignment flow will be added to
  • horizontal_align : (string) the horizontal alignment of the elements in the flow (default: 'right')
  • vertical_align : (string) the vertical alignment of the elements in the flow (default: 'center')
  • name : (string) the name of the alignment flow (default: 'alignment')
Returns: Usage: 
-- Adding a right align flow
local alignment = Gui.alignment(element,'example_right_alignment')
-- Adding a horizontal center and top align flow
local alignment = Gui.alignment(element,'example_center_top_alignment','center','top')
# scroll_table(parent, height, column_count[, name='scroll'])

Draw a scroll pane that has a table inside of it

Parameters:
  • parent : (LuaGuiElement) the parent element that the scroll table will be added to
  • height : (number) the maximum height for the scroll pane
  • column_count : (number) the number of columns that the table will have
  • name : (string) the name of the scroll pane that is added, the table is always called 'table' (default: 'scroll')
Returns: Usage: 
-- Adding a scroll table with max height of 200 and column count of 3
local scroll_table = Gui.scroll_table(element,'example_scroll_table',200,3)
# header(parent, caption[, tooltip][, add_alignment=false][, name='header'])

Used to add a header to a frame, this has the option for a custom right alignment flow for buttons

Parameters:
  • parent : (LuaGuiElement) the parent element that the header will be added to
  • caption : (string or LocalizedString) the caption that will be shown on the header
  • tooltip : (string or LocalizedString) the tooltip that will be shown on the header (optional)
  • add_alignment : (boolean) when true an alignment flow will be added for buttons (default: false)
  • name : (string) the name of the header that is being added, the alignment is always called 'alignment' (default: 'header')
Returns:
  • (LuaGuiElement) either the header or the header alignment if add_alignment is true
Usage: 
-- Adding a custom header
local header_alignment = Gui.header(
    element,
    'example_header',
    'Example Caption',
    'Example Tooltip',
    true
)
generated by LDoc
Last updated 2019-10-25 23:42:24 UTC