User Tools

Site Tools



gui_api

ChangeLog for the recent update 18.4.2018: http://wiki.mmominion.com/doku.php?id=gui_api_changelog

GUI API Documentation

You can easily build your own ingame GUI or draw custom shapes / icons / pictures through LUA. Each rendered frame the “Gameloop.Draw” - LUA-Event is called. You need to register your LUA function for this event and then you can build your GUI in there.

Simple demo code firstaddon.zip you can download and extract into your addon folder: MINIONAPP\Bots\xxxx\LuaMods\

Example: To get you started, let's draw a simple window with a slider, create a new .lua file, add it to your addon's module.def and put the following code into that new lua file:

-- Draws a Window with a Slider:
my_gui = {}
my_gui.open = true
my_gui.visible = true
my_gui.hue = 125
 
function my_gui.Draw( event, ticks ) 	
 
	if ( my_gui.open ) then 
 
           GUI:SetNextWindowSize(250,400,GUI.SetCond_FirstUseEver) -- set the next window size, only on first ever, GUI.SetCond_FirstUseEver is one of many possible enums.
 
           --GUI:Begin takes in two arguments, the name of the window and the current "is open" bool. It returns "is visible/is not collapsed" and the "is open" bool again.
           --If the user would close our Window, "is open" would return "false", else it will keep returning "true" as long as the window is open.
	   my_gui.visible, my_gui.open = GUI:Begin("My Fancy GUI", my_gui.open)
 
           if ( my_gui.visible ) then -- visible is true/false depending if the window is collapsed or not, we don't have to render anything in it when it is collapsed
                -- Again the typical syntax, passing the current value "hue" to the function as argument and receiving back the (un-)changed value. 
	   	my_gui.hue = GUI:SliderInt("Master HUE",my_gui.hue,0,255)
	        d(my_gui.hue)  -- spam print out the current value
	   end
	   GUI:End()  -- THIS IS IMPORTANT! For EVERY BEGIN() you NEED to ALWAYS call END(), it does not matter if the window is visible/open or not! Same goes with BeginChild() & EndChild() and others !
        end	
end
RegisterEventHandler("Gameloop.Draw", my_gui.Draw, "My_GUI-AnyNameHereToIdentYourCode")


Important Information

  • To get an overview what is possible with the GUI, open the ingame console (CTRL + C) and execute this command: ml_gui.showtestwindow = true
  • AUTOMATIC TRANSLATIONS - Wrap all your static text like: GUI:Button(“I am a Label”) to GUI:Button(GetString(“I am a Label”)), this will allow automatic translation to all languages later on.
  • If you find something in that Testwindow but you are not sure how to code the same in LUA, have a look in the c++ source of it: https://github.com/ocornut/imgui/blob/master/imgui_demo.cpp, the used function names and syntax are 99% the same, just the arguments might be slightly different due to LUA not supporting references.
  • Underlined function arguments in the following API documentation are optional. Example: GUI:Begin(string name, bool open, windowflags flags)
  • Most UI Element “names” or “labels” are at the same time their internal identifier which has to be unique. You can use the following to make that happen:
Example: Same name in UI, different internal identifier:
GUI:Button("Banana")
GUI:Button("Banana##1")
Example: Different name in UI, same internal identifier: 
GUI:Button("Banana###123hohoho") 
GUI:Button("Pineapple###123hohoho")
Example: Different name in UI, same internal identifier with auto **Translations**: 
GUI:Button(GetString("Banana").."###123hohoho") 
GUI:Button(GetString("Pineapple").."###123hohoho")

Window Functions

  • GUI:ShowTestWindow(bool isopen)
    • Returns: bool isopen
    • Test window, demonstrates GUI features
  • GUI:ShowMetricsWindow(bool isopen)
    • Returns: bool isopen
    • Metrics window for debuggings
  • GUI:Begin(string name, bool open, windowflags flags)
    • Returns bool visible, bool open
    • visible means “not collapsed”, so can opt out early when window is collapsed. For WindowFlags, check the Enums & Flags further below on this page.
  • GUI:End()
    • For every GUI:Begin(..) call, you need to call GUI:End(), independent if the the window is opened/shown or not.
  • GUI:BeginChild(string name, int sizeX, int sizeY, bool border, windowflags flags
    • Begin a scrolling region. size==0.0f: use remaining window size, size<0.0f: use remaining window size minus abs(size). size>0.0f: fixed size. each axis can use a different mode, e.g. sizeX=0 & sizeY=400.
  • GUI:EndChild()
    • For every GUI:BeginChild(..) call, you need to call GUI:EndChild().
  • GUI:IsWindowAppearing()
    • Returns: bool
  • GUI:IsWindowCollapsed()
    • Returns: bool
  • GUI:IsWindowFocused(FocusedFlags flags)
    • Returns: bool
    • is current window focused? or its root/child, depending on flags. see flags for options.
  • GUI:IsWindowHovered(HoveredFlags flags)
    • Returns: bool
    • is current window hovered (and typically: not blocked by a popup/modal)? see flags for options.
  • GUI:GetWindowPos()
    • Returns: number x, number y
    • get current window position in screen space
  • GUI:GetWindowSize()
    • Returns: number x, number y
    • get current window size
  • GUI:GetWindowWidth()
    • Returns: number width
  • GUI:GetWindowHeight()
    • Returns: number height
  • GUI:GetContentRegionMax()
    • Returns: number x, number y
    • current content boundaries (typically window boundaries including scrolling, or current column boundaries), in windows coordinates
  • GUI:GetContentRegionAvail()
    • Returns: number x, number y
    • == GetContentRegionMax() - GetCursorPos()
  • GUI:GetContentRegionAvailWidth()
    • Returns: number width
  • GUI:GetWindowContentRegionMin()
    • Returns: number x, number y
    • content boundaries min (roughly (0,0)-Scroll), in window coordinates
  • GUI:GetWindowContentRegionMax()
    • Returns: number x, number y
    • content boundaries max (roughly (0,0)+Size-Scroll) where Size can be override with SetNextWindowContentSize(), in window coordinates
  • GUI:GetWindowContentRegionWidth()
    • Returns: number witdth
  • GUI:SetNextWindowPos( number X, number Y, SetCondflags flags, number pivotX, number pivotY)
    • set next window position. call before Begin()
  • GUI:SetNextWindowSize( number X, number Y, SetCondflags flags)
    • set next window size. set axis to 0.0f to force an auto-fit on this axis. call before Begin()
  • GUI:SetNextWindowContentSize( number X, number Y)
    • set next window content size (enforce the range of scrollbars). set axis to 0.0f to leave it automatic. call before Begin()
  • GUI:SetNextWindowCollapsed( bool collapsed, SetCondflags flags)
    • set next window collapsed state. call before Begin()
  • GUI:SetNextWindowFocus()
    • set next window to be focused / front-most. call before Begin()
  • GUI:SetWindowPos( number X, number Y, SetCondflags flags)
    • set current window position - call within Begin()/End().
  • GUI:SetWindowPos( string name, number X, number Y, SetCondflags flags)
    • set current window position - call within Begin()/End(). may incur tearing
  • GUI:SetWindowSize( number X, number Y, SetCondflags flags)
    • set current window size. set X,Y to 0 to force an auto-fit.
  • GUI:SetWindowSize( string name, number X, number Y, SetCondflags flags)
    • set named window size. set X,Y to 0 to force an auto-fit on this axis.
  • GUI:SetWindowCollapsed( bool collapsed, SetCondflags flags)
    • set current window collapsed state
  • GUI:SetWindowCollapsed( string name, bool collapsed, SetCondflags flags)
    • set named window collapsed state
  • GUI:SetWindowFocus( string name)
    • set current/named window to be focused / front-most
  • GUI:GetScrollX()
    • Returns: get scrolling amount [0..GetScrollMaxX()]
  • GUI:GetScrollY()
    • Returns: get scrolling amount [0..GetScrollMaxY()]
  • GUI:GetScrollMaxX()
    • Returns: get maximum scrolling amount ~~ ContentSize.X - WindowSize.X
  • GUI:GetScrollMaxY()
    • Returns: get maximum scrolling amount ~~ ContentSize.Y - WindowSize.Y
  • GUI:SetScrollX( number scrollX)
    • set scrolling amount [0..GetScrollMaxX()]
  • GUI:SetScrollY( number scrollX)
    • set scrolling amount [0..GetScrollMaxY()]
  • GUI:SetScrollHere( number center_y_ratio)
    • adjust scrolling amount to make current cursor position visible. center_y_ratio=0.0: top, 0.5: center, 1.0: bottom.
  • GUI:SetScrollFromPosY( number pos_y, number center_y_ratio)
    • adjust scrolling amount to make given position valid. use GetCursorPos() or GetCursorStartPos()+offset to get valid positions.
  • GUI:SetKeyboardFocusHere(number offset)
    • focus keyboard on the next widget. Use positive 'offset' to access sub components of a multiple component widget

Style

  • GUI:PushStyleColor(PushStyleColor flags, number R, number G, number B, number A)
    • sets the color for the following elements
  • GUI:PopStyleColor( number count )
    • removes the last pushed color style(s)
  • GUI:PushStyleVar(PushStyleVar flags, number val, number val2)
    • sets the style for the following elements
  • GUI:PopStyleVar( number count )
    • removes the last pushed style var(s)
  • GUI:GetColorU32( number r, number g, number b, number a )
    • Returns: number color
  • GUI:PushItemWidth( number item_width )
    • width of items for the common item+label case, pixels. 0.0f = default to ~2/3 of windows width, >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -1.0f always align width to the right side))
  • GUI:PopItemWidth( )
    • removes the last pushed item width
  • GUI:CalcItemWidth( )
    • width of item given pushed settings and current cursor position
  • GUI:PushTextWrapPos( number wrap_pos_x )
    • word-wrapping for Text*() commands. < 0.0f: no wrapping; 0.0f: wrap to end of window (or column); > 0.0f: wrap at 'wrap_pos_x' position in window local space
  • GUI:PopTextWrapPos( )
    • removes the last pushed wrap pos
  • GUI:PushAllowKeyboardFocus( bool val )
    • allow focusing using TAB/Shift-TAB, enabled by default but you can disable it for certain widgets
  • GUI:PopAllowKeyboardFocus( )
    • removes the last pushed keyboard focus setting
  • GUI:PushButtonRepeat( bool repeat)
    • in 'repeat' mode, Button functions return repeated true in a typematic manner.
  • GUI:PopButtonRepeat( )
    • removes the last pushed button repeat setting
  • GUI:GetWindowFontSize()
    • Returns: number size
    • size (also height in pixels) of current font with current scale applied
  • GUI:SetWindowFontSize( number scale)
    • per-window font scale. Adjust IO.FontGlobalScale if you want to scale all windows
  • GUI:GetGlobalFontSize()
    • Returns: number size of global font scale
  • GUI:SetGlobalFontSize( number scale)
    • sets global font scale

Layout

  • GUI:AlignFirstTextHeightToWidgets( )
    • If a line does not start with text but with an Icon or other GUI Element, call this before drawing the text to align the height correctly.
  • GUI:Separator( )
    • horizontal line
  • GUI:SameLine( number local_pos_x, number spacing_w )
    • call between widgets or groups to layout them horizontally
  • GUI:NewLine()
    • undo a SameLine()
  • GUI:Spacing( )
    • add spacing
  • GUI:Dummy( number sizeX, number sizeY )
    • add a dummy item of given size
  • GUI:Indent( )
    • move content position toward the right by style.IndentSpacing pixels
  • GUI:Unindent( )
    • move content position back to the left (cancel Indent)
  • GUI:BeginGroup( )
    • lock horizontal starting position. once closing a group it is seen as a single item (so you can use GUI:IsItemHovered() on a group, GUI:SameLine() between groups, etc.
  • GUI:EndGroup( )
    • Needs to be called for each GUI:BeginGroup()
  • GUI:Columns( number count, string name, bool border )
    • setup number of columns. use an identifier to distinguish multiple column sets. close with Columns(1).
  • GUI:NextColumn( )
    • next column
  • GUI:GetColumnIndex( )
    • Returns: number current column index
  • GUI:GetColumnOffset( number column_index )
    • Returns: number get position of column line (in pixels, from the left side of the contents region). pass -1 to use current column, otherwise 0..GUI:GetcolumnsCount() inclusive. column 0 is usually 0.0f and not resizable unless you call this
  • GUI:SetColumnOffset( number column_index, number offset_x )
    • set position of column line (in pixels, from the left side of the contents region). pass -1 to use current column
  • GUI:GetColumnWidth( number column_index )
    • Returns: number column width (== GUI:GetColumnOffset(GetColumnIndex()+1) - GUI:GetColumnOffset(GetColumnOffset())
  • GUI:SetColumnWidth( number column_index, number width )
    • set column width (in pixels). pass -1 to use current column
  • GUI:GetColumnsCount( )
    • Returns: number number of columns (what was passed to Columns())
  • GUI:GetTextLineHeight( )
    • Returns: number FontSize
  • GUI:GetTextLineHeightWithSpacing( )
    • Returns: number FontSize + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of text)
  • GUI:GetFrameHeight( )
    • Returns: number FontSize + style.FramePadding.y * 2
  • GUI:GetFrameHeightWithSpacing( )
    • Returns: number FontSize + style.FramePadding.y * 2 + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of framed widgets)

Cursor

  • GUI:GetCursorPos( )
    • Returns: number x, number y
    • cursor position is relative to window position
  • GUI:GetCursorPosX( )
    • Returns: number x
  • GUI:GetCursorPosY( )
    • Returns: number y
  • GUI:SetCursorPos( number x, number y )
    • sets cursor position is relative to window position
  • GUI:SetCursorPosX( number x )
    • sets cursor position x
  • GUI:SetCursorPosY( number y )
    • sets cursor position y
  • GUI:GetCursorStartPos( )
    • Returns: number x, number y
    • initial cursor position
  • GUI:GetCursorScreenPos( )
    • Returns: number x, number y
    • cursor position in absolute screen coordinates [0..io.DisplaySize]
  • GUI:SetCursorScreenPos( number x, number y )
    • cursor position in absolute screen coordinates [0..io.DisplaySize]

ID Scopes

If you are creating multiple GUI Elements you want to push a unique identifier so ImGui can differentiate them. You can also use “##extra” within your widget name to distinguish them from each others.

  • GUI:PushID( string id)
    • push identifier into the ID stack.
  • GUI:PopID( )
    • pops the last pushed identifier from the ID stack.
  • GUI:GetID( string id)
    • calculate unique ID

Widgets Main

  • GUI:Text( string text)
    • creates a text element
  • GUI:TextColored( number R, number G, number B, number A, string text)
    • creates a colored text element, number range is 0.0 - 1.0
  • GUI:TextDisabled( string text)
    • creates a disabled text element
  • GUI:TextWrapped( string text)
    • creates a text element which wraps
  • GUI:TextUnformatted( string text)
    • creates an unformatted text element
  • GUI:LabelText( string label, string text)
    • display text+label aligned the same way as value+label widgets
  • GUI:Bullet( )
    • creates a bullet element
  • GUI:BulletText( string text)
    • creates a bullet text element
  • GUI:Button( string label, number sizeX, number sizeY)
    • creates a buttom element
  • GUI:SmallButton( string label)
    • creates a smaller button element
  • GUI:ArrowButton( string label, Direction direction )
    • creates an arrowbutton
  • GUI:InvisibleButton( string label, number sizeX, number sizeY)
    • creates an invisible button element
  • GUI:ColorButton( string id, number R, number G, number B, number A, ColorEditMode flags, number sizeX, number sizeY)
    • Returns: bool pressed
  • GUI:FreeButton( string label, number posX, number posY, number sizeX, number sizeY)
    • creates a freely placable buttom element
  • GUI:FreeImageButton( /string internalid, string filepath, number posX, number posY, number sizeX, number sizeY)
    • creates a freely placable image buttom element
  • GUI:ImageButton(string internalid, string filepath, number sizeX, number sizeY, number UV0_x, number UV0_y, number UV1_x, number UV1_y, number framepadding,number bg_col_R, number bg_col_G, number bg_col_B, number bg_col_A, number tint_col_R, number tint_col_G, number tint_col_B, number tint_col_A )
    • creates an image button, scary eh ;) ? Simple usage: GUI:ImageButton( string internalid, string filepath, number sizeX, number sizeY).
    • < 0 frame_padding uses default frame padding settings. 0 for no padding
  • GUI:Image(string filepath, number sizeX, number sizeY, number UV0_x, number UV0_y, number UV1_x, number UV1_y, number bg_col_R, number bg_col_G, number bg_col_B, number bg_col_A, number tint_col_R, number tint_col_G, number tint_col_B, number tint_col_A )
    • Simple Usage: GUI:Image(string filepath, number sizeX, number sizeY)
  • GUI:Checkbox( string label, bool checked)
    • Returns: bool checked, bool pressed
  • GUI:CheckboxFlags( string label, number flags, number flags_value)
    • Returns: number flags, bool pressed
  • GUI:RadioButton( string label, bool active)
    • Returns: bool active
  • GUI:RadioButton( string label, bool active, number val)
    • Returns: number val, bool pressed
  • GUI:EndCombo()
    • only call EndCombo() if BeginCombo() returns true!
  • GUI:Combo( string label, number current_item_listindex, table itemlist, number height_in_items)
    • Returns: number current_item_listindex, bool changed
  • GUI:ProgressBar( number fraction, number SizeX, number SizeY, string overlay )
    • Guess what it draws ;)

Widgets Drags

(Tip: ctrl+click on a drag box to input text)

  • GUI:DragFloat( string label, number val, number v_speed, number v_min, number v_max, string display_format, number power)
    • Returns: number val, bool changed
    • display_format example “%.3f”, *If v_min >= v_max we have no bound
  • GUI:DragFloatRange2( string label, number v_current_min, number v_current_max, number v_speed, number v_min, number v_max, string display_format, string display_format_max, number power)
    • Returns: number val_min, number val_max, bool changed
    • display_format example “%.3f”, *If v_min >= v_max we have no bound
  • GUI:DragInt( string label, number val, number v_speed, number v_min, number v_max, string display_format)
    • Returns: number val, bool changed
    • display_format example “%.3f”, *If v_min >= v_max we have no bound
  • GUI:DragIntRange2( string label, number v_current_min, number v_current_max, number v_speed, number v_min, number v_max, string display_format, string display_format_max)
    • Returns: number val_min, number val_max, bool changed
    • display_format example “%.3f”, *If v_min >= v_max we have no bound

Widgets Input

  • GUI:InputText( string label, string text, InputTextFlags flags)
    • Returns: string text, bool changed
  • GUI:InputTextMultiline( string label, string text, number sizeX, number sizeY , InputTextFlags flags)
    • Returns: string text, bool changed
  • GUI:InputTextEditor( string label, string text, number sizeX, number sizeY , InputTextFlags flags)
    • Returns: string text, bool changed
    • Lua syntax highlighting version of GUI:InputTextMultiline
  • GUI:InputFloat( string label, number val, number step, number step_fast, number decimal_precision, InputTextFlags flags)
    • Returns: number val, bool changed
  • GUI:InputFloat2( string label, number val, number val2, number decimal_precision, InputTextFlags flags)
    • Returns: number val, number val2, bool changed
    • Draws 2 Input fields behind each other in the same line
  • GUI:InputFloat3( string label, number val, number val2, number val3, number decimal_precision, InputTextFlags flags)
    • Returns: number val, number val2, number val3, bool changed
    • Draws 3 Input fields behind each other in the same line
  • GUI:InputFloat4( string label, number val, number val2, number val3, number val4, number decimal_precision, InputTextFlags flags)
    • Returns: number val, number val2, number val3, number val4, bool changed
    • Draws 4 Input fields behind each other in the same line
  • GUI:InputInt( string label, number val, number step, number step_fast, InputTextFlags flags)
    • Returns: number val, bool changed
  • GUI:InputInt2( string label, number val, number val2, InputTextFlags flags)
    • Returns: number val, number val2, bool changed
    • Draws 2 Input fields behind each other in the same line
  • GUI:InputInt3( string label, number val, number val2, number val3, InputTextFlags flags)
    • Returns: number val, number val2, number val3, bool changed
    • Draws 3 Input fields behind each other in the same line
  • GUI:InputInt4( string label, number val, number val2, number val3, number val4, InputTextFlags flags)
    • Returns: number val, number val2, number val3, number val4, bool changed
    • Draws 4 Input fields behind each other in the same line

Widgets Sliders

  • GUI:SliderFloat( string label, number val, number v_min, number v_max, string display_format, number power)
    • Returns: number val, bool changed
  • GUI:SliderFloat2( string label, number val, number val2, number v_min, number v_max, string display_format, number power)
    • Returns: number val, number val2, bool changed
    • Draws 2 Input fields behind each other in the same line
  • GUI:SliderFloat3( string label, number val, number val2, number val3, number v_min, number v_max, string display_format, number power)
    • Returns: number val, number val2, number val3, bool changed
    • Draws 3 Input fields behind each other in the same line
  • GUI:SliderFloat4( string label, number val, number val2, number val3, number val4, number v_min, number v_max, string display_format, number power)
    • Returns: number val, number val2, number val3, number val4, bool changed
    • Draws 4 Input fields behind each other in the same line
  • GUI:SliderAngle( string label, number v_rad, number v_degrees_min, number v_degrees_max)
    • Returns: number val, bool changed
  • GUI:SliderInt( string label, number val, number v_min, number v_max, string display_format)
    • Returns: number val, bool changed
  • GUI:SliderInt2( string label, number val, number val2, number v_min, number v_max, string display_format)
    • Returns: number val, number val2, bool changed
  • GUI:SliderInt3( string label, number val, number val2, number val3, number v_min, number v_max, string display_format)
    • Returns: number val, number val2, number val3, bool changed
  • GUI:SliderInt4( string label, number val, number val2, number val3, number val4, number v_min, number v_max, string display_format)
    • Returns: number val, number val2, number val3, number val4, bool changed
  • GUI:VSliderFloat( string label, number sizeX, number sizeY, number val, number v_min, number v_max, string display_format, number power)
    • Returns: number val, bool changed
  • GUI:VSliderInt( string label, number sizeX, number sizeY, number val, number v_min, number v_max, string display_format)
    • Returns: number val, bool changed

Color Editor/Picker

  • GUI:ColorEdit3( string label, number R, number G, number B, ColorEditMode flags)
    • Returns: number R, number G, number B, bool changed
  • GUI:ColorEdit4( string label, number R, number G, number B, number A, ColorEditMode flags)
    • Returns: number R, number G, number B, number A, bool changed
  • GUI:ColorPicker3( string label, number R, number G, number B, ColorEditMode flags)
    • Returns: number R, number G, number B, bool changed
  • GUI:ColorPicker4( string label, number R, number G, number B, number A, ColorEditMode flags)
    • Returns: number R, number G, number B, number A, bool changed

Widgets Trees

  • GUI:TreeNode( string label)
    • Returns: bool changed , if returning 'true' the node is open and the user is responsible for calling TreePop()
  • GUI:TreeNode( string label, string args)
    • Returns: bool changed , if returning 'true' the node is open and the user is responsible for calling TreePop()
  • GUI:TreeNode( string label, TreeNodeFlag flags, string args)
    • Returns: bool changed , if returning 'true' the node is open and the user is responsible for calling TreePop()
  • GUI:TreePush( string id)
    • already called by TreeNode(), but you can call Push/Pop yourself for layouting purpose
  • GUI:TreePop( )
    • needs to be callled at the end of TreePush()
  • GUI:SetNextTreeNodeOpened( bool opened, SetCond flags)
    • set next tree node to be opened.
  • GUI:CollapsingHeader( string label, TreeNodeFlag flags)
    • Returns: bool collapsed, if returning 'true' the header is open. doesn't indent nor push on ID stack. user doesn't have to call TreePop().
  • GUI:CollapsingHeader( string label, bool p_open, TreeNodeFlag flag)
    • Returns: bool collapsed, when 'p_open' isn't NULL, display an additional small close button on upper right of the header

Widgets Lists

  • GUI:Selectable( string label, bool selected, SelectableFlag flags, number sizeX, number sizeY )
    • Returns: bool selected, bool changed
    • size.x==0.0: use remaining width, size.x>0.0: specify width. size.y==0.0: use label height, size.y>0.0: specify height
  • GUI:ListBox( string label, number current_listitem_index, table itemlist, number height_in_items )
    • Returns: number current_item_index, bool changed
  • GUI:ListBoxHeader( string label, number items_count, number height_in_items )
    • Returns: bool
    • use if you want to reimplement ListBox() will custom data or interactions. make sure to call ListBoxFooter() afterwards.
  • GUI:ListBoxFooter( )
    • terminate the scrolling region

Widgets Tooltip

  • GUI:SetTooltip( string label )
    • set tooltip under mouse-cursor, typically use with GUI:IsItemHovered. last call wins
  • GUI:BeginTooltip( )
    • use to create full-featured tooltip windows that aren't just text
  • GUI:EndTooltip( )
    • use to create full-featured tooltip windows that aren't just text

Widgets Menus

  • GUI:BeginMainMenuBar( )
    • Returns: bool opened
    • create and append to a full screen menu-bar. only call EndMainMenuBar() if this returns true!
  • GUI:EndMainMenuBar( )
    • End Menubar drawing
  • GUI:BeginMenuBar( )
    • Returns: bool opened
    • append to menu-bar of current window (requires ImGuiWindowFlags_MenuBar flag set). only call EndMenuBar() if this returns true!
  • GUI:EndMenuBar( )
    • End Menubar drawing
  • GUI:BeginMenu( string label, bool enabled )
    • Returns: bool opened
    • create a sub-menu entry. only call EndMenu() if this returns true!
  • GUI:EndMenu( )
    • End Menubar drawing
  • GUI:MenuItem( string label, string shortcut, bool selected, bool enabled)
    • Returns: bool activated, bool selected
    • Shortcuts are currently only visual, aka not working, you need to add that yourself

Widgets Popup

  • GUI:OpenPopup( string id)
    • mark popup as open. popups are closed when user click outside, or activate a pressable item, or CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block. popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level).
  • GUI:BeginPopup( string id, WindowFlags flags)
    • Returns: bool open
    • return true if popup if opened and start outputting to it. only call EndPopup() if BeginPopup() returned true!
  • GUI:BeginPopupModal( string name, bool opened, WindowFlags flags)
    • Returns bool visible, bool open
    • modal dialog (can't close them by clicking outside)
  • GUI:BeginPopupContextItem( string id, number mouse_button)
    • Returns bool open
    • helper to open and begin popup when clicked on last item
  • GUI:BeginPopupContextWindow( string id, number mouse_button, bool also_over_items)
    • Returns bool open
    • helper to open and begin popup when clicked on current window
  • GUI:BeginPopupContextVoid( string id, number mouse_button)
    • Returns bool open
    • helper to open and begin popup when clicked in void (no window)
  • GUI:EndPopup( )
    • needs to be called on opened popups
  • GUI:IsPopupOpen( string id)
    • Returns bool open
  • GUI:CloseCurrentPopup( )
    • close the popup we have begin-ed into. clicking on a MenuItem or Selectable automatically close the current popup.

Widgets Utilities

  • GUI:IsItemHovered( HoveredFlags flags )
    • Results: bool
    • is the last item hovered? (and usable, aka not blocked by a popup, etc.).
  • GUI:IsItemActive( )
    • Results: bool
    • is the last item active? (e.g. button being held, text field being edited- items that don't interact will always return false)
  • GUI:IsItemFocused( )
    • Results: bool
    • is the last item focused for keyboard/gamepad navigation?
  • GUI:IsItemClicked( int mousebutton == 0)
    • Results: bool
    • was the last item clicked? (e.g. button/node just clicked on)
  • GUI:IsItemVisible( )
    • Results: bool
    • was the last item visible? (aka not out of sight due to clipping/scrolling.)
  • GUI:IsAnyItemHovered( )
    • Results: bool
  • GUI:IsAnyItemActive( )
    • Results: bool
  • GUI:IsAnyItemFocused( )
    • Results: bool
    • is the any item focused for keyboard/gamepad navigation?
  • GUI:GetItemRectMin( )
    • Results: number x, number y
    • get bounding rect of last item in screen space
  • GUI:GetItemRectMax( )
    • Results: number x, number y
    • get bounding rect of last item in screen space
  • GUI:GetItemRectSize( )
    • Results: number x, number y
  • GUI:SetItemAllowOverlap( )
    • Allow last item to be overlapped by a subsequent item. sometimes useful with invisible buttons, selectables, etc. to catch unused area.
  • GUI:IsRectVisible( number x, number y)
    • Results: bool
    • test if rectangle of given size starting from cursor pos is visible (not clipped). to perform coarse clipping on user's side
  • GUI:GetTime( )
    • Results: number
  • GUI:GetFrameCount( )
    • Results: number
  • GUI:CalcTextSize( string text)
    • Results: number sizex, number sizey
  • GUI:CalcListClipping( number items_count, number items_height, number out_items_display_start, number out_items_display_end)
    • Results: number out1, number out2
    • calculate coarse clipping for large list of evenly sized items. Prefer using the ImGuiListClipper higher-level helper if you can.
  • GUI:BeginChildFrame( number guiID, number sizex, number sizey, WindowFlags flags)
    • Results: bool
    • helper to create a child window / scrolling region that looks like a normal widget frame
  • GUI:EndChildFrame( )
    • needs to be called at the end of BeginChildFrame.
  • GUI:ColorConvertU32ToFloat4( number U32val)
    • Returns: number val1,number val2,number val3,number val4
  • GUI:ColorConvertFloat4ToU32( number val1,number val2,number val3,number val4 )
    • Returns: number U32val
  • GUI:ColorConvertRGBtoHSV( number r, number g, number b)
    • Returns: number h, number s, number v
  • GUI:ColorConvertHSVtoRGB( number h, number s, number v)
    • Returns: number r, number g, number b
  • GUI:GetScreenSize()
    • Returns: number x, number y
  • GUI:IsMouseDown( number button)
    • Returns: bool
  • GUI:IsMouseClicked( number button, bool repeat)
    • Returns: bool
  • GUI:IsMouseDoubleClicked( number button)
    • Returns: bool
  • GUI:IsMouseReleased( number button)
    • Returns: bool
  • GUI:IsMouseHoveringWindow( number button)
    • Returns: bool
    • is mouse hovering current window (“window” in API names always refer to current window). disregarding of any consideration of being blocked by a popup. (unlike IsWindowHovered() this will return true even if the window is blocked because of a popup)
  • GUI:IsMouseHoveringAnyWindow( number button)
    • Returns: bool
  • GUI:IsMouseHoveringAnyWindow( number pos_minX, number pos_minY, number pos_maxX, number pos_maxY, bool clip)
    • Returns: bool
    • is mouse hovering given bounding rect (in screen space). clipped by current clipping settings. disregarding of consideration of focus/window ordering/blocked by a popup.
  • GUI:IsMouseDragging( number button, number lock_threshold)
    • Returns: bool
  • GUI:GetMousePos( )
    • Returns: number x, number y
  • GUI:GetMousePosOnOpeningCurrentPopup( )
    • Returns: number x, number y
    • retrieve backup of mouse positioning at the time of opening popup we have BeginPopup() into
  • GUI:GetMouseDragDelta( number button, number lock_threshold)
    • Returns: number x, number y
    • dragging amount since clicking.
  • GUI:ResetMouseDragDelta( number button)
    • Banana ;)
  • GUI:GetClipboardText()
    • get text data from the clipboard
  • GUI:SetClipboardText( string input)
    • set text data to the clipboard

Custom Widgets

  • GUI:Keybind( string label, number virtualKey, number width)
    • Returns: number virtualKey, string keyName, boolean changed
    • Clicking the widget will start a listener for the next key press event

Custom Drawing

Usage: GUI:AddCircleFilled( 300, 300, 475,GUI:ColorConvertFloat4ToU32(0.9,0.1,0.12,0.5)) IMPORTANT: Use GUI:ColorConvertFloat4ToU32() to calculatethe required numbercolor argument!!

  • GUI:AddLine( number X1, number Y1, number X2, number Y2, number color, number thickness = 1.0,)
  • GUI:AddRect( number X1, number Y1, number X2, number Y2, number color, number rounding= 0.0, number rounding_corners = 0.0)
  • GUI:AddRectFilled( number X1, number Y1, number X2, number Y2, number color, number rounding= 0.0, number rounding_corners = 0.0)
  • GUI:AddQuadFilled( number X1, number Y1, number X2, number Y2, number X3, number Y3, number X4, number Y4, number color)
  • GUI:AddTriangleFilled( number X1, number Y1, number X2, number Y2, number X3, number Y3, number color)
  • GUI:AddCircle( number X1, number Y1, number radius, number color, number num_segments= 12)
  • GUI:AddCircleFilled( number X1, number Y1, number radius, number color, number num_segments= 12)
  • GUI:AddText( number X1, number Y1, number color, string text)
  • GUI:AddImage( string texturepath, number X1, number Y1, number X2, number Y2)
  • RenderManager:WorldToScreen(table worldpos, bool true)
    • Returns: number X1, number Y1, screenpos
    • USE THIS ONE IF POSSIBLE, it is A LOT FASTER than the one below! Converts a worldposition x,y,z to a screenposition x,y , IF that point is currently visible on the screen
  • RenderManager:WorldToScreen(table worldpos)
    • Returns: table screenpos
    • Converts a worldposition x,y,z to a screenposition x,y , IF that point is currently visible on the screen

Enums & Flags

These are registered values in the GUI metatable. Usage: d(GUI.WindowFlags_NoMove) will print “2” into the console.

WindowFlags
  • GUI.WindowFlags_NoTitleBar
  • GUI.WindowFlags_NoResize
  • GUI.WindowFlags_NoMove
  • GUI.WindowFlags_NoScrollbar
  • GUI.WindowFlags_NoScrollWithMouse
  • GUI.WindowFlags_NoCollapse
  • GUI.WindowFlags_AlwaysAutoResize
  • GUI.WindowFlags_NoSavedSettings
  • GUI.WindowFlags_NoInputs
  • GUI.WindowFlags_MenuBar
  • GUI.WindowFlags_HorizontalScrollbar
  • GUI.WindowFlags_NoFocusOnAppearing
  • GUI.WindowFlags_NoBringToFrontOnFocus
  • GUI.WindowFlags_ForceVerticalScrollbar
  • GUI.WindowFlags_ForceHorizontalScrollbar
  • GUI.WindowFlags_AlwaysUseWindowPadding
InputTextFlags
  • GUI.InputTextFlags_CharsDecimal
  • GUI.InputTextFlags_CharsHexadecimal
  • GUI.InputTextFlags_CharsUppercase
  • GUI.InputTextFlags_CharsNoBlank
  • GUI.InputTextFlags_AutoSelectAll
  • GUI.InputTextFlags_EnterReturnsTrue
  • GUI.InputTextFlags_CallbackCompletion
  • GUI.InputTextFlags_CallbackHistory
  • GUI.InputTextFlags_CallbackAlways
  • GUI.InputTextFlags_CallbackCharFilter
  • GUI.InputTextFlags_AllowTabInput
  • GUI.InputTextFlags_CtrlEnterForNewLine
  • GUI.InputTextFlags_NoHorizontalScroll
  • GUI.InputTextFlags_AlwaysInsertMode
  • GUI.InputTextFlags_ReadOnly
  • GUI.InputTextFlags_NoUndoRedo
  • GUI.InputTextFlags_CharsScientific
  • GUI.InputTextFlags_Password
SelectableFlags
  • GUI.SelectableFlags_DontClosePopups
  • GUI.SelectableFlags_SpanAllColumns
  • GUI.SelectableFlags_AllowDoubleClick
ComboFlags
  • GUI.ComboFlags_PopupAlignLeft
  • GUI.ComboFlags_HeightSmall
  • GUI.ComboFlags_HeightRegular
  • GUI.ComboFlags_HeightLarge
  • GUI.ComboFlags_HeightLargest
  • GUI.ComboFlags_NoArrowButton
  • GUI.ComboFlags_NoPreview
PushStyleColor
  • GUI.Col_Text
  • GUI.Col_TextDisabled
  • GUI.Col_WindowBg
  • GUI.Col_ChildWindowBg
  • GUI.Col_Border
  • GUI.Col_BorderShadow
  • GUI.Col_FrameBg
  • GUI.Col_FrameBgHovered
  • GUI.Col_FrameBgActive
  • GUI.Col_TitleBg
  • GUI.Col_TitleBgCollapsed
  • GUI.Col_TitleBgActive
  • GUI.Col_MenuBarBg
  • GUI.Col_ScrollbarBg
  • GUI.Col_ScrollbarGrab
  • GUI.Col_ScrollbarGrabHovered
  • GUI.Col_ScrollbarGrabActive
  • GUI.Col_CheckMark
  • GUI.Col_SliderGrab
  • GUI.Col_SliderGrabActive
  • GUI.Col_Button
  • GUI.Col_ButtonHovered
  • GUI.Col_ButtonActive
  • GUI.Col_Header
  • GUI.Col_HeaderHovered
  • GUI.Col_HeaderActive
  • GUI.Col_Column
  • GUI.Col_ColumnHovered
  • GUI.Col_ColumnActive
  • GUI.Col_ResizeGrip
  • GUI.Col_ResizeGripHovered
  • GUI.Col_ResizeGripActive
  • GUI.Col_PlotLines
  • GUI.Col_PlotLinesHovered
  • GUI.Col_PlotHistogram
  • GUI.Col_PlotHistogramHovered
  • GUI.Col_TextSelectedBg
  • GUI.Col_TooltipBg
  • GUI.Col_ModalWindowDarkening
  • GUI.Col_DragDropTarget
  • GUI.Col_NavHighlight
  • GUI.Col_NavWindowingHighlight
PushStyleVar
  • GUI.StyleVar_Alpha
  • GUI.StyleVar_WindowPadding
  • GUI.StyleVar_WindowRounding
  • GUI.StyleVar_WindowBorderSize
  • GUI.StyleVar_WindowMinSize
  • GUI.StyleVar_ChildWindowRounding
  • GUI.StyleVar_ChildBorderSize
  • GUI.StyleVar_PopupRounding
  • GUI.StyleVar_PopupBorderSize
  • GUI.StyleVar_FramePadding
  • GUI.StyleVar_FrameRounding
  • GUI.StyleVar_FrameBorderSize
  • GUI.StyleVar_ItemSpacing
  • GUI.StyleVar_ItemInnerSpacing
  • GUI.StyleVar_IndentSpacing
  • GUI.StyleVar_ScrollbarSize
  • GUI.StyleVar_ScrollbarRounding
  • GUI.StyleVar_GrabMinSize
  • GUI.StyleVar_GrabRounding
  • GUI.StyleVar_ButtonTextAlign
ColorEditMode
  • for ColorEdit3() / ColorEdit4() / ColorPicker3() / ColorPicker4() / ColorButton()
  • GUI.ColorEditMode_NoAlpha
  • GUI.ColorEditMode_NoOptions
  • GUI.ColorEditMode_NoSmallPreview
  • GUI.ColorEditMode_NoInputs
  • GUI.ColorEditMode_NoTooltip
  • GUI.ColorEditMode_NoLabel
  • GUI.ColorEditMode_NoSidePreview
  • GUI.ColorEditMode_AlphaBar
  • GUI.ColorEditMode_AlphaPreview
  • GUI.ColorEditMode_AlphaPreviewHalf
  • GUI.ColorEditMode_HDR
  • GUI.ColorEditMode_Uint8
  • GUI.ColorEditMode_Float
  • GUI.ColorEditMode_PickerHueBar
  • GUI.ColorEditMode_PickerHueWheel
  • GUI.ColorEditMode_RGB
  • GUI.ColorEditMode_HSV
  • GUI.ColorEditMode_HEX
SetCondFlags
  • GUI.SetCond_Always
  • GUI.SetCond_Once
  • GUI.SetCond_FirstUseEver
  • GUI.SetCond_Appearing
DrawCornerFlags
  • GUI.DrawCornerFlag_TopLeft
  • GUI.DrawCornerFlag_TopRight
  • GUI.DrawCornerFlag_BottomLeft
  • GUI.DrawCornerFlag_BottomRight
FocusedFlags
  • GUI.FocusedFlags_ChildWindows
  • GUI.FocusedFlags_RootWindow
  • GUI.FocusedFlags_AnyWindow
HoveredFlags
  • GUI.HoveredFlags_Default
  • GUI.HoveredFlags_ChildWindows
  • GUI.HoveredFlags_RootWindow
  • GUI.HoveredFlags_AnyWindow
  • GUI.HoveredFlags_AllowWhenBlockedByPopup
  • GUI.HoveredFlags_AllowWhenBlockedByActiveItem
  • GUI.HoveredFlags_AllowWhenOverlapped
Directions
  • GUI.Dir_Left
  • GUI.Dir_Right
  • GUI.Dir_Up
  • GUI.Dir_Down
TreeNodeFlags
  • GUI.TreeNodeFlags_Selected
  • GUI.TreeNodeFlags_Framed
  • GUI.TreeNodeFlags_AllowItemOverlap
  • GUI.TreeNodeFlags_NoTreePushOnOpen
  • GUI.TreeNodeFlags_NoAutoOpenOnLog
  • GUI.TreeNodeFlags_SDefaultOpen
  • GUI.TreeNodeFlags_OpenOnDoubleClick
  • GUI.TreeNodeFlags_OpenOnArrow
  • GUI.TreeNodeFlags_Leaf
  • GUI.TreeNodeFlags_Bullet
  • GUI.TreeNodeFlags_FramePadding
  • GUI.TreeNodeFlags_NavLeftJumpsBackHere
  • GUI.TreeNodeFlags_CollapsingHeader
gui_api.txt · Last modified: 2023/04/21 07:34 by kali