Item
Updated for version 3.38.
Back to MenuUI
All items including menus inherit the Item class. This means that all values and functions that this class has they have too. This includes Menus too.
Item / Button / Divider
Creation
Can be created inside menu type items:
Or if a Divider:
You can also create a quick divider like this
Parameters
Basic values
name
String
The name of the item, used to identify the item
text
String
The text or String_id(if localized) of the item's title
help
String
If defined, this will show help text in a tooltip near the item
on_callback
Function
The function that should be called if the item got its value changed or pressed(buttons only) The function gets called with the "item" parameter which you can use to get the value from
enabled
Boolean
Is the item enabled. If disabled, the item is grayed out
visible
Boolean
Should the item be rendered?
label
Any
Sets a "label" to the item, can be used if you need to mark a few items, delete items with label x or get items with label x
position
Function/String/Table
Sets a custom position for the item, this overrides align items Function: function(item) item:Panel():set_position(0, 10) end String: Left, Right, Top, Bottom, Center(can be combined) Table: {0, 10}
index
Number
Lets you insert the item in a specific place, setting this to 1 will put it as first item
on_right_click
Function
A function that should be called when pressing right click on an item(will not work if you have a context menu and did not change its key from right click)
inherit_value
Table
A table where you can define values to only inherit to the items. If you put a value inside of it and have a different value outside of it the outer one will not be inherited. Values that can inherit from other values like help_localized can from localized, will not inherit as you'd expect them to
private
Table
A table that sets private values, any value inside of it, will not inherit to the children at all
highlight
Boolean
Should the item be highlighted as soon as it's created?
divider_type
Boolean
This makes the item a "divider". Essentially disabling some mouse events. This usually means that no callbacks will be called and the item doesn't highlight at all. For groups this disables closing/opening of the group making them static
ignore_align
Boolean
Should align items ignore the item when aligning?
count_as_aligned
Boolean
Normally, if you set a custom position to the item or use ignore_align, MenuUI will ignore the item when aligning the item (no item will use its position) This bypasses this behavior
Inherit values
Values that if are defined from a menu, are inherited by their items.
localized
Boolean
Is the item localized? defaults to false
items_localized
Boolean
Are context menu or combobox items localized? Defaults to localized value
help_localized
Boolean
Is the help text localized? Defaults to localized value
size
Number
The size of the item, defaults to 18
offset
Number/Table
How much is the item pushed in its x and y position(will shrink the item horizontally)
text_offset
Number/Table
Offset but for the text inside the item (if present)
font
String/Idstring
Font of the item. Defaults to "fonts/font_large_mf"
font_size
Number
Font size of the item, default to size
kerning
Number
The kerning of the text, like spacing between characters
text_align
String
The horizontal placement of the text inside its own body, defaults to left. Can be left, right, center or justified
text_vertical
String
Same as text_vertical but vertically, defaults to top. Can be top, bottom or center
size_by_text
Boolean
Sets the item's size based of its text(used mostly by buttons and dividers)
bg_callbacks
Boolean
Background callbacks call through menu ui's update function instead of calling the callback right away. This is done sometimes to avoid erroring in some place or not having to wait for callbacks to finish in the main thread. Usually this should be turned off
Context menu
items
Table
Tells the item you need a context menu. The items can be defined like this: lua{{text = "Item" on_callback = ClassClbk(self, "clbk")}, "An item without callback"} Currently you can't use a context menu on a ComboBox
open_list_key
String/Idstring
Changes the key that opens the list(only mouse keys, left = "0" right = "1"(default))
searchbox
Boolean
Adds a searchbox to the context menu
Customization values
Who doesn't like that ;)
* - Does not inherit
foreground
Color
The foreground color, this includes text, anything beyond the background
foreground_highlight
Color
The foreground but when highlighted
auto_foreground
Boolean
MenuUI will try to guess which foreground color(white or black) will fit to the background color
background_color
Color
Color of the background for the item
full_bg_color
Color
Background that menu type items use in order to differentiate from background_color. You should use this value for menu type items
unhighlight_color
Color
Color of the item when un-highlighted (uses background_color otherwise)
highlight_color
Color
The color of the background for the item but when highlighted
accent_color
Color
Accent color of the item, is set automatically for things like border color, scroll color and more
line_color
Color
Some items like the textbox and combobox have a line below their control, this controls their color, defaults to accent_color
enabled_alpha
Float 0-1
The opacity of the item while enabled, defaults to 1
disabled_alpha
Float 0-1
The opacity of the item when disabled, defaults to 0.5
control_slice
Float 0-1
The "slice" of the control, for example, the slider's slide, defaults to 0.5(50%)
w
Number
A constant width for the item
*max_width
Number
This sets a maximum value for the width
*min_width
Number
This sets a minimum value for the width
*max_height
Number
This sets a maximum value for the height
*min_height
Number
This sets a minimum value for the height
*last_y_offset
Number
Normally when the align items function reaches the end, it takes the last item's offset(or the one with largest bottom position) and adds it to the menu's height, this overrides it.
background_alpha
Number
Opacity for the background
context_background_color
Color
Color of the context menu if present. Defaults to background_color (if set) or black color
scroll_color
Color
Color of any scroll (menu's scroll, context menu scroll etc)
click_btn
Idstring
Sets the mouse button that runs the callback of the item
range_color
Table
A table that has tables with starting and ending point of the text they want to color and then the color that text should be. For example {0, 10, Color.blue} will color characters 0 to 10 green. You can also put the starting point and then the color which would assume you want the color to continue until the end of text like this: {10, Color.green}
alone_in_row
Boolean
Determines if the item should be alone in a row (used only with align_method set to "centered_grid" or "reversed_centered_grid")
Animation values
Hopefully expanded in the future
animate_colors
Boolean
Should colors in the item be animated(on highlighting/un-highlighting)
Border values
border_color
Color
Color for the border if used
border_visible
Boolean
Sets the whole border visible
border_left
Boolean
Sets the left border visible
border_right
Boolean
Sets the right border visible
border_top
Boolean
Sets the top border visible
border_bottom
Boolean
Sets the bottom border visible
border_lock_height
Boolean
Locks the height of the border to the title's height instead of the whole item
border_center_as_title
Boolean
Positions the border around the title
border_position_below_title
Boolean
Sets the bottom border below the title
border_size
Number
The size of the border, probably can be used to set a size for the all border sides
border_width
Number
Width of the border
border_height
Number
Height of the border
Context menu values
context_screen_offset_y
Number
defaults to 32. Offset from top and bottom of the screen for context menus so they float a little
context_font_size
Number
defaults to 20. The text font size for context menus.
context_text_offset
Number/Table
The text offset for context menus. Offsets are either a Number for both X,Y offsets or a table
Menu specific values
delay_align_items
Boolean
Delay align items is for any item that is a menu to essentially delay the align of items (which meant to reduce the amount of aligns are called) this is a good optimization method for complicated menus that you want MenuUI to automatically align
background_visible
Boolean
Should background be visible? Defaults to true if the menu is not Group
background_blur
Boolean
Should the background be a blurred background? (background_color wil not work with this)
auto_align
Boolean
Should the menu automatically align items when for example, an item gets added or removed, an item gets its visibilty toggled? If you have many items it would be more recommended to set this to false and use manual align by calling menu:AlignItems(true) when you do things such as adding/removing items
Functions
Get
Name()
String
Returns the name of the item
Text()
String
Returns the text of the item
Label()
Any
Returns the label of the item if is set
Enabled()
Boolean
Returns if the item is enabled
Visible()
Boolean
Returns if the item is visible
Value()
Any
Returns the value of the item. Only relevant for items that use a value
Index()
Number
Returns the place of the item. You should use this instead of item.index as this will find the exact place of it
Key()
String
Returns a unique key for the item based on diesel panel (Changes when item is recreated)
alive()
Boolean
Returns if the item's GUI panel is alive. Lets you do stuff like this: alive(item)
Panel()
Diesel Panel
Returns the GUI panel of the item
Parent()
Item
Returns the parent menu of the item
ParentPanel()
Diesel Panel
Returns the parent GUI panel of the item's panel
TextHeight()
Number
Returns the height of the title. Will return 0 if no title is present
title_alive()
Boolean
Returns whether the item has an alive title GUI text, mostly used internally
Set
SetEnabled(Boolean enabled)
Sets whether the item is enabled or not
SetVisible(Boolean visible, Boolean no_align)
Sets whether the item is visible or not. Normally if you set something visible or not the menu has to update itself so it can re-align items properly no_align can disable that if is set to true(mostly used for optimization)
SetText(String text)
Sets the title of the item
SetTextLight(String text)
Like SetText but lighter. Don't use ths blindly
SetCallback(Function callback)
Sets a callback for the item
SetLabel(Any label)
Sets a label for the item
Configure(params)
Sets new parameters for the item and recreats the item
SetIndex(Number index, Boolean no_align)
Sets an index for the item, no_align will disable auto aligning if is set to true(important for the item's position to update)
SetLayer(Number layer)
Sets a layer for the item. In other words, the higher the layer the higher it will be among other panels
SetEnabledAlpha(Number alpha)
Sets enabled alpha
SetDisabledAlpha(Number alpha)
Sets disabled alpha
SetBorder(Table config)
Updates the border based on config parameter
SetPointer(String pointer)
Basically the same as MenuUI:SetPointer
SetParam(String k, Any v)
Sets the parameter with the name k to the value of v
Other
Destroy()
Destroys the item (Don't worry it's safe to call)
RunCallback(Function clbk, ...)
Runs clbk or on_callback if is set, the callback will be called with the item as first parameter and then ... which can be anything
TryRendering()
A function mostly used internally to check if the item should render. It will not render if it's outside of the visible area. This is done for optimization
Position and Size functions
Get
X()
Number
Returns the X position
Y()
Number
Returns the Y position
W()/Width()
Number
Returns the width
H()/Height()
Number
Returns the height
Right
Number
Returns the right position
Position()
String/Table/Function
Returns the last set position(not exact position)
Location()/LeftTop()
Table
Returns the exact position of the item(X,Y)
RightTop()
Table
Returns right and top(Y) position
Bottom()
Number
Returns bottom position
LeftBottom()
Table
Returns left(X) and bottom position
RightBottom()
Table
Returns right and bottom position
Center()
Table
Returns the center X,Y position
CenterX()
Number
Returns the center X position
CenterY()
Number
Returns the center Y position
OuterWidth()
Number
Returns the X position added with X offset
OuterHeight()
Number
Returns the Y position added with Y offset
Offset()
Table
Returns the offset
OffsetX()
Number
Returns the X offset
OffsetY()
Number
Returns the Y offset
TextOffset()
Table
Returns the text offset
TextOffsetX()
Number
Returns the X text offset
TextOffsetY()
Number
Returns the Y text offset
Inside(Number x, Number y)
Boolean
Returns whether x and y is inside the diesel panel of the item
MouseFocused(Number x, Number y)
Boolean
A better version of Inside that checks if the item is alive and visible and will use the mouse position if x and y are not defined
Set
SetPosition(Number x, Number y)
Sets an exact position using X and Y
SetPosition(Table position)
Sets an exact position using X and Y inside a table(like {0, 10})
SetPosition(Function position)
Sets a position function, might look like this: function(item) item:Panel():set_x(0) end
SetPosition(String position)
Sets a String position for the item, like: Left, Right, Top, Bottom, Center(can be combined)
Other
Menu functions
This is more relevant for menu type items but items can use these too.
Almost all item creation functions use params parameter as the settings of the item. How it should be called, how it looks.
Item creation
All functions return the item that is created
Button(Table params)/Divider(Table params)
Toggle(Table params)
ComboBox(Table params)
TextBox(Table params)/NumberBox(Table params)
ColorTextBox(Table params)
Slider(Table params)
KeyBind(Table params)
Image/ImageButton(Table params)
Holder(Table params)
Menu(Table params)
Group(Table params)/DivGroup(Table params)
NoteBook(Table params)
ToolBox(Table params)
PopupMenu(Table params)
Text(String text, Table params)
Quick function to create a divider without needing to use a table
Create(String type, ...)
Allows creating any type of item from one function. For example Item:Create("Button", {text = "something"}). There are specific cases you'd want to use it
Get
GetItem(String name, Boolean shallow)
Any item
Searches for an item. name name of the item, shallow limits search to current menu
GetItemValue(String name, Boolean shallow)
Any value
Uses GetItem function to get the item and its value (Safe function)
GetMenu(String name, Boolean shallow)
Any item that is a menu
Searches for an item of type menu. name name of the menu, shallow limit search to the current menu? Or search the items of the items?
GetMenus(match, deep, menus)
Any item that is a menu
Returns a table of menus that have a matching name to match. deep searches inside children too
GetItemWithType(name, type, shallow)
Any item
Basically like GetItem but with type specifity
GetItemByLabel(Any label, Boolean shallow)
Any item
Like GetItem but uses label value instead of name
GetItemByLabel(Any label, Boolean shallow)
Any item
Basically GetItem but uses a label instead of a name
Items()
Table
Returns the list of the items (Be careful it's not a cloned list and any changes to it can affect the items)
ItemsWidth()
Number
Returns the width of the items panel, very useful when you're trying to fit items in the menu
ItemsHeight()
Number
Returns the height of the items panel
ItemsPanel()
Diesel Panel
Returns the items panel
ShouldClose()
Booolean
Used mostly by MenuUI root class to know whether the menu is focused
ChildrenMouseFocused(x, y, excluded_label)
Boolean
Like MouseFocused but checks the children. excluded_label will not check items with their label set to it
GetIndex(Item item)
Number
Returns the index of item
Set
SetItemValue(String name, ...)
Uses GetItem function to get the item and set its value. Use it as you would use a normal SetValue function (Safe function)
SetChecked(String name, Boolean checked, Boolean run_callback)
A quick function to find a Toggle item and set its value to checked. run_callback will run the callback when changed
Other
RecreateItems()
Recreats all items
AlignItems(Boolean menus, Boolean no_parent)
Aligns items using the set align_method, menus sets whether to align first the children menus before aligning for the menu, no_parent will disable aligning of parent menu after the menu is aligned(note that when menus is on it sets no_parent to true for the children so it won't cause a stack overflow)
ClearItems(Any label)
Clear all items. label if a label is defined, this will only remove items that have the label
RecreateItem(Item item, Boolean align_items)
Recreats an item. item the item that should be recreated, align_items should items be re-aligned after the recreation?
RemoveItem(Item item)
Removes an item. Same as Item:Destroy()
Making items into menus
You can also make items into "menus" by creating an item inside of that item like this: We use "size_by_text" to make the item small enough so it won't clog the whole item.
By default items have align_method set to "grid_from_right" which positions the items from the right side.
This method replaces override_panel which was really hacky and weird to use.
Warning! Even though you can make items into menus they're not a replacement for menu type items!
Last updated