User Tools

Site Tools

en


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. 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)


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
  • 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")

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)
    • 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:GetWindowFontSize( 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:AlignTextToFramePadding( )
    • 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: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:IsHovered(). 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 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)
    • 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
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: 2018/04/24 10:48 by fxfire