Namespace: gui

The gui namespace contains functions that are used for working with Ashita’s in-game GUI system. (Powered by ImGui)

This allows addons to create rich user interfaces.

You can access this namespace via:

ashita.gui.

Because of the nature of these functions and the amount of functions that exist, I do not plan to create full documentation for each function. You can find an example of the ImGui demo application ported to an Ashita addon here instead.

This will serve as a demo of how to use these functions: https://gist.github.com/atom0s/188283e6ff097f37fa31400f22ec8762

In order to make use of the GUI features properly, your addon should require the imguidef library via:

require 'imguidef';

By including this helper file, this also exposes these GUI functions via a global ‘imgui’. Instead of having to use ‘ashita.gui.’ before every call, instead you just need to use ‘imgui.’ instead. For example:

-- before
local hide = ashita.gui.GetHide();
 
-- after
local hide = imgui.GetHide();

Most of the calls are straight-forward and used as they are in C++. However, some of them had to have minor changes to work with Lua’s types and lack of pointers. The following is a list of how things are implemented.

Please note, the following changes apply to ALL functions listed below:

  • Any function that takes ImVec2(…) is replaced by two float values instead.
  • Any function that takes ImVec4(…) is replaced by four float values instead.
    • Example (Before): void SetNextWindowPos(const ImVec2& pos, ImGuiSetCond cond = 0);
    • Example (After): void SetNextWindowPos(float pos_x, float pos_y, ImGuiSetCond cond = 0);
  • Any function that returns ImVec2(…) instead returns two values.
  • Any function that returns ImVec4(…) instead returns four values.
    • Example (Before): ImVec2 GetWindowPos(void);
    • Example (After): pos_x, pos_y = GetWindowPos();
  • Any function that takes a pointer value is replaced with an ImGuiVar variable instead. (See more info on ImGuiVar below.)
  • Any function that accepts varargs ‘…’ are not handled as such. Instead they accept only a single string. Use Lua’s * buildt-in string.format function to format strings.
  • Any function that accepts va_list as an argument type is not implemented as Lua has no way to do this natively.

  • bool GetHideObjects(void) const;
  • void SetHideObjects(bool bHide);
    • Implemented as ‘imgui.GetHide()’ and ‘imgui.SetHide(hide)’.
  • ImGuiIO& GetIO(void);
  • ImGuiStyle& GetStyle(void);
  • ImDrawData* GetDrawData(void);
    • Not implemented through these functions.
    • GetIO can be accessed via ‘imgui.io’.
    • GetStyle can be accessed via ‘imgui.style’.
    • GetDrawData is not implemented at all currently.
  • void ShowUserGuide(void);
  • void ShowStyleEditor(ImGuiStyle* ref = NULL);
  • void ShowTestWindow(bool* p_open = NULL);
  • void ShowMetricsWindow(bool* p_open = NULL);
  • bool Begin(const char* name, bool* p_open = NULL, ImGuiWindowFlags flags = 0);
  • bool Begin(const char* name, bool* p_open, const ImVec2& size_on_first_use, float bg_alpha = -1.0f, ImGuiWindowFlags flags = 0);
  • void End(void);
  • bool BeginChild(const char* str_id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags extra_flags = 0);
  • bool BeginChild(ImGuiID id, const ImVec2& size = ImVec2(0, 0), bool border = false, ImGuiWindowFlags extra_flags = 0);
  • void EndChild(void);
  • ImVec2 GetContentRegionMax(void);
  • ImVec2 GetContentRegionAvail(void);
  • float GetContentRegionAvailWidth(void);
  • ImVec2 GetWindowContentRegionMin(void);
  • ImVec2 GetWindowContentRegionMax(void);
  • float GetWindowContentRegionWidth(void);
  • ImDrawList* GetWindowDrawList(void);
  • ImVec2 GetWindowPos(void);
  • ImVec2 GetWindowSize(void);
  • float GetWindowWidth(void);
  • float GetWindowHeight(void);
  • bool IsWindowCollapsed(void);
  • void SetWindowFontScale(float scale);
  • void SetNextWindowPos(const ImVec2& pos, ImGuiSetCond cond = 0);
  • void SetNextWindowPosCenter(ImGuiSetCond cond = 0);
  • void SetNextWindowSize(const ImVec2& size, ImGuiSetCond cond = 0);
  • void SetNextWindowSizeConstraints(const ImVec2& size_min, const ImVec2& size_max, ImGuiSizeConstraintCallback custom_callback = NULL, void* custom_callback_data = NULL);
    • callback is implemented as a string. It is the name to a Lua function to call when the callback is invoked. (custom_callback_data is not implemented.)
  • void SetNextWindowContentSize(const ImVec2& size);
  • void SetNextWindowContentWidth(float width);
  • void SetNextWindowCollapsed(bool collapsed, ImGuiSetCond cond = 0);
  • void SetNextWindowFocus(void);
  • void SetWindowPos(const ImVec2& pos, ImGuiSetCond cond = 0);
  • void SetWindowSize(const ImVec2& size, ImGuiSetCond cond = 0);
  • void SetWindowCollapsed(bool collapsed, ImGuiSetCond cond = 0);
  • void SetWindowFocus(void);
  • void SetWindowPos(const char* name, const ImVec2& pos, ImGuiSetCond cond = 0);
  • void SetWindowSize(const char* name, const ImVec2& size, ImGuiSetCond cond = 0);
  • void SetWindowCollapsed(const char* name, bool collapsed, ImGuiSetCond cond = 0);
  • void SetWindowFocus(const char* name);
  • float GetScrollX(void);
  • float GetScrollY(void);
  • float GetScrollMaxX(void);
  • float GetScrollMaxY(void);
  • void SetScrollX(float scroll_x);
  • void SetScrollY(float scroll_y);
  • void SetScrollHere(float center_y_ratio = 0.5f);
  • void SetScrollFromPosY(float pos_y, float center_y_ratio = 0.5f);
  • void SetKeyboardFocusHere(int offset = 0);
  • void SetStateStorage(ImGuiStorage* tree);
  • ImGuiStorage* GetStateStorage(void);
  • void PushFont(ImFont* font);
  • void PopFont(void);
  • void PushStyleColor(ImGuiCol idx, const ImVec4& col);
  • void PopStyleColor(int count = 1);
  • void PushStyleVar(ImGuiStyleVar idx, float val);
  • void PushStyleVar(ImGuiStyleVar idx, const ImVec2& val);
  • void PopStyleVar(int count = 1);
  • ImFont* GetFont(void);
  • float GetFontSize(void);
  • ImVec2 GetFontTexUvWhitePixel(void);
  • ImU32 GetColorU32(ImGuiCol idx, float alpha_mul = 1.0f);
  • ImU32 GetColorU32(const ImVec4& col);
  • void PushItemWidth(float item_width);
  • void PopItemWidth(void);
  • float CalcItemWidth(void);
  • void PushTextWrapPos(float wrap_pos_x = 0.0f);
  • void PopTextWrapPos(void);
  • void PushAllowKeyboardFocus(bool v);
  • void PopAllowKeyboardFocus(void);
  • void PushButtonRepeat(bool repeat);
  • void PopButtonRepeat(void);
  • void Separator(void);
  • void SameLine(float pos_x = 0.0f, float spacing_w = -1.0f);
  • void NewLine(void);
  • void Spacing(void);
  • void Dummy(const ImVec2& size);
  • void Indent(float indent_w = 0.0f);
  • void Unindent(float indent_w = 0.0f);
  • void BeginGroup(void);
  • void EndGroup(void);
  • ImVec2 GetCursorPos(void);
  • float GetCursorPosX(void);
  • float GetCursorPosY(void);
  • void SetCursorPos(const ImVec2& local_pos);
  • void SetCursorPosX(float x);
  • void SetCursorPosY(float y);
  • ImVec2 GetCursorStartPos(void);
  • ImVec2 GetCursorScreenPos(void);
  • void SetCursorScreenPos(const ImVec2& pos);
  • void AlignFirstTextHeightToWidgets(void);
  • float GetTextLineHeight(void);
  • float GetTextLineHeightWithSpacing(void);
  • float GetItemsLineHeightWithSpacing(void);
  • void Columns(int count = 1, const char* id = NULL, bool border = true);
  • void NextColumn(void);
  • int GetColumnIndex(void);
  • float GetColumnOffset(int column_index = -1);
  • void SetColumnOffset(int column_index, float offset_x);
  • float GetColumnWidth(int column_index = -1);
  • int GetColumnsCount(void);
  • void PushID(const char* str_id);
  • void PushID(const char* str_id_begin, const char* str_id_end);
  • void PushID(const void* ptr_id);
  • void PushID(int int_id);
  • void PopID(void);
  • ImGuiID GetID(const char* str_id);
  • ImGuiID GetID(const char* str_id_begin, const char* str_id_end);
  • ImGuiID GetID(const void* ptr_id);
  • void Text(const char* fmt, …);
  • void TextV(const char* fmt, va_list args);
  • void TextColored(const ImVec4& col, const char* fmt, …);
  • void TextColoredV(const ImVec4& col, const char* fmt, va_list args);
  • void TextDisabled(const char* fmt, …);
  • void TextDisabledV(const char* fmt, va_list args);
  • void TextWrapped(const char* fmt, …);
  • void TextWrappedV(const char* fmt, va_list args);
  • void TextUnformatted(const char* text, const char* text_end = NULL);
    • There may be some issues with this function. It may change in the future.
  • void LabelText(const char* label, const char* fmt, …);
  • void LabelTextV(const char* label, const char* fmt, va_list args);
  • void Bullet(void);
  • void BulletText(const char* fmt, …);
  • void BulletTextV(const char* fmt, va_list args);
  • bool Button(const char* label, const ImVec2& size = ImVec2(0, 0));
  • bool SmallButton(const char* label);
  • bool InvisibleButton(const char* str_id, const ImVec2& size);
  • void Image(ImTextureID user_texture_id, const ImVec2& size, const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1, 1), const ImVec4& tint_col = ImVec4(1, 1, 1, 1), const ImVec4& border_col = ImVec4(0, 0, 0, 0));
  • bool ImageButton(ImTextureID user_texture_id, const ImVec2& size, const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1, 1), int frame_padding = -1, const ImVec4& bg_col = ImVec4(0, 0, 0, 0), const ImVec4& tint_col = ImVec4(1, 1, 1, 1));
  • bool Checkbox(const char* label, bool* v);
  • bool CheckboxFlags(const char* label, unsigned int* flags, unsigned int flags_value);
  • bool RadioButton(const char* label, bool active);
  • bool RadioButton(const char* label, int* v, int v_button);
  • bool Combo(const char* label, int* current_item, const char%%**%% items, int items_count, int height_in_items = -1);
  • bool Combo(const char* label, int* current_item, const char* items_separated_by_zeros, int height_in_items = -1);
  • bool Combo(const char* label, int* current_item, bool(items_getter)(void data, int idx, const char%%*%% out_text), void data, int items_count, int height_in_items = -1);
  • bool ColorButton(const ImVec4& col, bool small_height = false, bool outline_border = true);
  • bool ColorEdit3(const char* label, float col[3]);
  • bool ColorEdit4(const char* label, float col[4], bool show_alpha = true);
  • void ColorEditMode(ImGuiColorEditMode mode);
  • void PlotLines(const char* label, const float* values, int values_count, int values_offset = 0, const char* overlay_text = NULL, float scale_min = FLT_MAX, float scale_max = FLT_MAX, ImVec2 graph_size = ImVec2(0, 0), int stride = sizeof(float));
    • Implemented in a custom manner to support an array of float values, using a Lua table. Call is setup as:
      • imgui.PlotLines(label, values_table, values_count, values_offset, overlay_text, scale_min, scale_max, graph_size_x, graph_size_y, stride);
      • Default values are still present starting at values_offset.
  • void PlotLines(const char* label, float(values_getter)(void data, int idx), void* data, int values_count, int values_offset = 0, const char* overlay_text = NULL, float scale_min = FLT_MAX, float scale_max = FLT_MAX, ImVec2 graph_size = ImVec2(0, 0));
  • void PlotHistogram(const char* label, const float* values, int values_count, int values_offset = 0, const char* overlay_text = NULL, float scale_min = FLT_MAX, float scale_max = FLT_MAX, ImVec2 graph_size = ImVec2(0, 0), int stride = sizeof(float));
    • Implemented in a custom manner to support an array of float values, using a Lua table. Call is setup as:
      • imgui.PlotHistogram(label, values_table, values_count, values_offset, overlay_text, scale_min, scale_max, graph_size_x, graph_size_y, stride);
      • Default values are still present starting at values_offset.
  • void PlotHistogram(const char* label, float(values_getter)(void data, int idx), void* data, int values_count, int values_offset = 0, const char* overlay_text = NULL, float scale_min = FLT_MAX, float scale_max = FLT_MAX, ImVec2 graph_size = ImVec2(0, 0));
  • void ProgressBar(float fraction, const ImVec2& size_arg = ImVec2(-1, 0), const char* overlay = NULL);
  • bool DragFloat(const char* label, float* v, float v_speed = 1.0f, float v_min = 0.0f, float v_max = 0.0f, const char* display_format = “%.3f”, float power = 1.0f);
  • bool DragFloat2(const char* label, float v[2], float v_speed = 1.0f, float v_min = 0.0f, float v_max = 0.0f, const char* display_format = “%.3f”, float power = 1.0f);
  • bool DragFloat3(const char* label, float v[3], float v_speed = 1.0f, float v_min = 0.0f, float v_max = 0.0f, const char* display_format = “%.3f”, float power = 1.0f);
  • bool DragFloat4(const char* label, float v[4], float v_speed = 1.0f, float v_min = 0.0f, float v_max = 0.0f, const char* display_format = “%.3f”, float power = 1.0f);
  • bool DragFloatRange2(const char* label, float* v_current_min, float* v_current_max, float v_speed = 1.0f, float v_min = 0.0f, float v_max = 0.0f, const char* display_format = “%.3f”, const char* display_format_max = NULL, float power = 1.0f);
  • bool DragInt(const char* label, int* v, float v_speed = 1.0f, int v_min = 0, int v_max = 0, const char* display_format = “%.0f”);
  • bool DragInt2(const char* label, int v[2], float v_speed = 1.0f, int v_min = 0, int v_max = 0, const char* display_format = “%.0f”);
  • bool DragInt3(const char* label, int v[3], float v_speed = 1.0f, int v_min = 0, int v_max = 0, const char* display_format = “%.0f”);
  • bool DragInt4(const char* label, int v[4], float v_speed = 1.0f, int v_min = 0, int v_max = 0, const char* display_format = “%.0f”);
  • bool DragIntRange2(const char* label, int* v_current_min, int* v_current_max, float v_speed = 1.0f, int v_min = 0, int v_max = 0, const char* display_format = “%.0f”, const char* display_format_max = NULL);
  • bool InputText(const char* label, char* buf, size_t buf_size, ImGuiInputTextFlags flags = 0, ImGuiTextEditCallback callback = NULL, void* user_data = NULL);
    • callback is implemented as a string. It is the name to a Lua function to call when the callback is invoked. (user_data is not implemented.)
  • bool InputTextMultiline(const char* label, char* buf, size_t buf_size, const ImVec2& size = ImVec2(0, 0), ImGuiInputTextFlags flags = 0, ImGuiTextEditCallback callback = NULL, void* user_data = NULL);
    • callback is implemented as a string. It is the name to a Lua function to call when the callback is invoked. (user_data is not implemented.)
  • bool InputFloat(const char* label, float* v, float step = 0.0f, float step_fast = 0.0f, int decimal_precision = -1, ImGuiInputTextFlags extra_flags = 0);
  • bool InputFloat2(const char* label, float v[2], int decimal_precision = -1, ImGuiInputTextFlags extra_flags = 0);
  • bool InputFloat3(const char* label, float v[3], int decimal_precision = -1, ImGuiInputTextFlags extra_flags = 0);
  • bool InputFloat4(const char* label, float v[4], int decimal_precision = -1, ImGuiInputTextFlags extra_flags = 0);
  • bool InputInt(const char* label, int* v, int step = 1, int step_fast = 100, ImGuiInputTextFlags extra_flags = 0);
  • bool InputInt2(const char* label, int v[2], ImGuiInputTextFlags extra_flags = 0);
  • bool InputInt3(const char* label, int v[3], ImGuiInputTextFlags extra_flags = 0);
  • bool InputInt4(const char* label, int v[4], ImGuiInputTextFlags extra_flags = 0);
  • bool SliderFloat(const char* label, float* v, float v_min, float v_max, const char* display_format = “%.3f”, float power = 1.0f);
  • bool SliderFloat2(const char* label, float v[2], float v_min, float v_max, const char* display_format = “%.3f”, float power = 1.0f);
  • bool SliderFloat3(const char* label, float v[3], float v_min, float v_max, const char* display_format = “%.3f”, float power = 1.0f);
  • bool SliderFloat4(const char* label, float v[4], float v_min, float v_max, const char* display_format = “%.3f”, float power = 1.0f);
  • bool SliderAngle(const char* label, float* v_rad, float v_degrees_min = -360.0f, float v_degrees_max = +360.0f);
  • bool SliderInt(const char* label, int* v, int v_min, int v_max, const char* display_format = “%.0f”);
  • bool SliderInt2(const char* label, int v[2], int v_min, int v_max, const char* display_format = “%.0f”);
  • bool SliderInt3(const char* label, int v[3], int v_min, int v_max, const char* display_format = “%.0f”);
  • bool SliderInt4(const char* label, int v[4], int v_min, int v_max, const char* display_format = “%.0f”);
  • bool VSliderFloat(const char* label, const ImVec2& size, float* v, float v_min, float v_max, const char* display_format = “%.3f”, float power = 1.0f);
  • bool VSliderInt(const char* label, const ImVec2& size, int* v, int v_min, int v_max, const char* display_format = “%.0f”);
  • bool TreeNode(const char* label);
  • bool TreeNode(const char* str_id, const char* fmt, …);
  • bool TreeNode(const void* ptr_id, const char* fmt, …);
  • bool TreeNodeV(const char* str_id, const char* fmt, va_list args);
  • bool TreeNodeV(const void* ptr_id, const char* fmt, va_list args);
  • bool TreeNodeEx(const char* label, ImGuiTreeNodeFlags flags = 0);
  • bool TreeNodeEx(const char* str_id, ImGuiTreeNodeFlags flags, const char* fmt, …);
  • bool TreeNodeEx(const void* ptr_id, ImGuiTreeNodeFlags flags, const char* fmt, …);
  • bool TreeNodeExV(const char* str_id, ImGuiTreeNodeFlags flags, const char* fmt, va_list args);
  • bool TreeNodeExV(const void* ptr_id, ImGuiTreeNodeFlags flags, const char* fmt, va_list args);
  • void TreePush(const char* str_id = NULL);
  • void TreePush(const void* ptr_id = NULL);
  • void TreePop(void);
  • void TreeAdvanceToLabelPos(void);
  • float GetTreeNodeToLabelSpacing(void);
  • void SetNextTreeNodeOpen(bool is_open, ImGuiSetCond cond = 0);
  • bool CollapsingHeader(const char* label, ImGuiTreeNodeFlags flags = 0);
  • bool CollapsingHeader(const char* label, bool* p_open, ImGuiTreeNodeFlags flags = 0);
  • bool Selectable(const char* label, bool selected = false, ImGuiSelectableFlags flags = 0, const ImVec2& size = ImVec2(0, 0));
  • bool Selectable(const char* label, bool* p_selected, ImGuiSelectableFlags flags = 0, const ImVec2& size = ImVec2(0, 0));
  • bool ListBox(const char* label, int* current_item, const char%%**%% items, int items_count, int height_in_items = -1);
  • bool ListBox(const char* label, int* current_item, const char* items_separated_by_zeros, int height_in_items = -1);
  • bool ListBox(const char* label, int* current_item, bool(items_getter)(void data, int idx, const char%%*%% out_text), void data, int items_count, int height_in_items = -1);
  • bool ListBoxHeader(const char* label, const ImVec2& size = ImVec2(0, 0));
  • bool ListBoxHeader(const char* label, int items_count, int height_in_items = -1);
  • void ListBoxFooter(void);
  • void Value(const char* prefix, bool b);
  • void Value(const char* prefix, int v);
  • void Value(const char* prefix, unsigned int v);
  • void Value(const char* prefix, float v, const char* float_format = NULL);
    • Value functions take an extra argument due to not being able to differentiate between the types in Lua.
      • Value(prefix, type, b);
      • Value(prefix, type, v);
      • Value(prefix, type, v);
      • Value(prefix, type, v, float_format);
        • Type: 0 = bool
        • Type: 1 = int
        • Type: 2 = unsigned int
        • Type: 3 = float
  • void ValueColor(const char* prefix, const ImVec4& v);
  • void ValueColor(const char* prefix, unsigned int v);
  • void SetTooltip(const char* fmt, …);
  • void SetTooltipV(const char* fmt, va_list args);
  • void BeginTooltip(void);
  • void EndTooltip(void);
  • bool BeginMainMenuBar(void);
  • void EndMainMenuBar(void);
  • bool BeginMenuBar(void);
  • void EndMenuBar(void);
  • bool BeginMenu(const char* label, bool enabled = true);
  • void EndMenu(void);
  • bool MenuItem(const char* label, const char* shortcut = NULL, bool selected = false, bool enabled = true);
  • bool MenuItem(const char* label, const char* shortcut, bool* p_selected, bool enabled = true);
  • void OpenPopup(const char* str_id);
  • bool BeginPopup(const char* str_id);
  • bool BeginPopupModal(const char* name, bool* p_open = NULL, ImGuiWindowFlags extra_flags = 0);
  • bool BeginPopupContextItem(const char* str_id, int mouse_button = 1);
  • bool BeginPopupContextWindow(bool also_over_items = true, const char* str_id = NULL, int mouse_button = 1);
  • bool BeginPopupContextVoid(const char* str_id = NULL, int mouse_button = 1);
  • void EndPopup(void);
  • void CloseCurrentPopup(void);
  • void LogToTTY(int max_depth = -1);
  • void LogToFile(int max_depth = -1, const char* filename = NULL);
  • void LogToClipboard(int max_depth = -1);
  • void LogFinish(void);
  • void LogButtons(void);
  • void LogText(const char* fmt, …);
    • These logging functions should not be relied on, they may be removed in the future.
  • void PushClipRect(const ImVec2& clip_rect_min, const ImVec2& clip_rect_max, bool intersect_with_current_clip_rect);
  • void PopClipRect(void);
  • bool IsItemHovered(void);
  • bool IsItemHoveredRect(void);
  • bool IsItemActive(void);
  • bool IsItemClicked(int mouse_button = 0);
  • bool IsItemVisible(void);
  • bool IsAnyItemHovered(void);
  • bool IsAnyItemActive(void);
  • ImVec2 GetItemRectMin(void);
  • ImVec2 GetItemRectMax(void);
  • ImVec2 GetItemRectSize(void);
  • void SetItemAllowOverlap(void);
  • bool IsWindowHovered(void);
  • bool IsWindowFocused(void);
  • bool IsRootWindowFocused(void);
  • bool IsRootWindowOrAnyChildFocused(void);
  • bool IsRootWindowOrAnyChildHovered(void);
  • bool IsRectVisible(const ImVec2& size);
  • bool IsPosHoveringAnyWindow(const ImVec2& pos);
  • float GetTime(void);
  • int GetFrameCount(void);
  • const char* GetStyleColName(ImGuiCol idx);
  • ImVec2 CalcItemRectClosestPoint(const ImVec2& pos, bool on_edge = false, float outward = +0.0f);
    • Not implementing this unless its requested.
  • ImVec2 CalcTextSize(const char* text, const char* text_end = NULL, bool hide_text_after_double_hash = false, float wrap_width = -1.0f);
    • Not implementing this unless it’s requested.
  • void CalcListClipping(int items_count, float items_height, int* out_items_display_start, int* out_items_display_end);
    • Not implementing this unless it’s requested.
  • bool BeginChildFrame(ImGuiID id, const ImVec2& size, ImGuiWindowFlags extra_flags = 0);
  • void EndChildFrame(void);
  • ImVec4 ColorConvertU32ToFloat4(ImU32 in);
  • ImU32 ColorConvertFloat4ToU32(const ImVec4& in);
  • void ColorConvertRGBtoHSV(float r, float g, float b, float& out_h, float& out_s, float& out_v);
    • Lua does not support ‘out’ values, instead, this function will return out_h, out_s, out_v.
  • void ColorConvertHSVtoRGB(float h, float s, float v, float& out_r, float& out_g, float& out_b);
    • Lua does not support ‘out’ values, instead, this function will return out_r, out_g, out_b.
  • int GetKeyIndex(ImGuiKey key);
  • bool IsKeyDown(int key_index);
  • bool IsKeyPressed(int key_index, bool repeat = true);
  • bool IsKeyReleased(int key_index);
  • bool IsMouseDown(int button);
  • bool IsMouseClicked(int button, bool repeat = false);
  • bool IsMouseDoubleClicked(int button);
  • bool IsMouseReleased(int button);
  • bool IsMouseHoveringWindow(void);
  • bool IsMouseHoveringAnyWindow(void);
  • bool IsMouseHoveringRect(const ImVec2& r_min, const ImVec2& r_max, bool clip = true);
  • bool IsMouseDragging(int button = 0, float lock_threshold = -1.0f);
  • ImVec2 GetMousePos(void);
  • ImVec2 GetMousePosOnOpeningCurrentPopup(void);
  • ImVec2 GetMouseDragDelta(int button = 0, float lock_threshold = -1.0f);
  • void ResetMouseDragDelta(int button = 0);
  • ImGuiMouseCursor GetMouseCursor(void);
  • void SetMouseCursor(ImGuiMouseCursor type);
  • void CaptureKeyboardFromApp(bool capture = true);
  • void CaptureMouseFromApp(bool capture = true);
  • void* MemAlloc(size_t sz);
    • Not implementing this function.
  • void MemFree(void* ptr);
    • Not implementing this function.
  • const char* GetClipboardText(void);
  • void SetClipboardText(const char* text);
  • const char* GetVersion(void);
  • ImGuiContext* CreateContext(void* (malloc_fn)(size_t) = NULL, void(free_fn)(void*) = NULL);
    • Not implementing this function.
  • void DestroyContext(ImGuiContext* ctx);
    • Not implementing this function.
  • ImGuiContext* GetCurrentContext(void);
    • Not implementing this function.
  • void SetCurrentContext(ImGuiContext* ctx);
    • Not implementing this function.

Notes

InputText / InputTextMultiline - The callback, if present, should be a string that points to a callback function like this:

  • The callbacks data is a imgui.ImGuiTextEditCallbackData structure instance.
if (imgui.InputText('test', test_text_input_buffer, 1024, imgui.bor(ImGuiInputTextFlags_EnterReturnsTrue,ImGuiInputTextFlags_CallbackCompletion,ImGuiInputTextFlags_CallbackHistory), 'test_callback')) then
    print('Enter was pressed!');
end
     
function test_callback(data)
    print('Callback was fired!');
    return 0;
end

SetNextWindowSizeConstraints - The callback, if present, should be a string that points to a callback function like this:

  • The callbacks data is a imgui.ImGuiSizeConstraintCallbackData structure instance.
function SquareResizeConstraint(data)
    data.DesiredSize = ImVec2(math.max(data.DesiredSize.x, data.DesiredSize.y), math.max(data.DesiredSize.x, data.DesiredSize.y));    
end
 
imgui.SetNextWindowSizeConstraints(0, 0, float_max, float_max, 'SquareResizeConstraint');

ImGuiSizeConstraintCallbackData

The ImGuiSizeConstraintCallbackData structure contains information used for window resizing callbacks. This allows users to adjust how their window(s) resize if they want to use certain constraints.

The following data is exposed in this structure, to Lua addons:

struct ImGuiSizeConstraintCallbackData
{
    ImVec2 Pos;         // The current window position, for reference. (Read Only)
    ImVec2 CurrentSize; // The current window size, for reference. (Read Only)
    ImVec2 DesiredSize; // The desired contraint to apply to the resizing of the window. (Based on the mouse position.)
};

You should edit the DesiredSize field to constrain the window to your liking. This value takes an ImVec2 of two floats, for example:

DesiredSize = ImVec(200, 200);

Example

The following example would apply a sizing constraint to keep the window in a square shape. (Similar to aspect ratio resizing.)

function SquareResizeConstraint(data)
    data.DesiredSize = ImVec2(math.max(data.DesiredSize.x, data.DesiredSize.y), math.max(data.DesiredSize.x, data.DesiredSize.y));    
end
 
imgui.SetNextWindowSizeConstraints(0, 0, float_max, float_max, 'SquareResizeConstraint');

ImGuiTextEditCallbackData

The ImGuiTextEditCallbackData structure contains information used for an InputText callback function. This can be useful for determining the type of callback that was fired as well as what data was used to cause the callback.

The following data is exposed in this structure, to Lua addons:

struct ImGuiTextEditCallbackData
{
    ImGuiInputTextFlags EventFlags;    // ImGuiInputTextFlags_Callback... value from the ImGuiInputTextFlags_ enumeration. (Read Only)
    ImGuiInputTextFlags Flags;         // The flags of the input creation call. (Read Only)
    bool                ReadOnly;      // The readonly flag of the input box. (Read Only)
    ImWchar             EventChar;     // The character that was input.
    ImGuiKey            EventKey;      // The key pressed to cause this event. (Read Only)
    char*               Buf;           // The current buffer of text in the input.
    int                 BufTextLen;    // The current length of text in buf.
    int                 BufSize;       // Maximum length that buf can hold. (Read Only)
    bool                BufDirty;      // Must be set to true if Buf or BufTextLen is modified.
    int                 CursorPos;     // The current carrot position within the input text.
    int                 SelectionStart;// The selection start position.
    int                 SelectionEnd;  // The selection end position.
     
    void DeleteChars(int pos, int count);
    void InsertChars(int pos, const char* new_text);
    bool HasSelection();
};

Some fields are read-only and cannot be edited.

If you edit the ‘Buf’ field, you must update the BufTextLen to the new length as well as set BufDirty to true in order for it to be properly updated. To do this easily you can make use of the DeleteChars and InsertChars functions which will handle the property adjustments for you.

You may also want to set CursorPos to the end of the string for a more expected result.


ImGui IO Table

The ImGui IO table holds various I/O related properties and information about the current state of ImGui.

You can access this table via:

-- Includes the various defintions and such for ImGui, also adding the imgui global..
require 'imguidef';

-- Obtain the io table..
local io = imgui.io;

Please Note: The imgui.io table differs from the main imgui functions! Please be sure to read the following notes carefully!!

The imgui.io table differs from the functions found within the ‘imgui’ table. The io table is implemented in a different manner and can make use of certain types such as ImVec2, ImVec4, etc. Because of this, things are used a little differently. But it should be straight forward enough.

Here are some examples of how you can make use of the imgui.io table properties:

-- Getting the display size.. (ImVec2)
local display_x = imgui.io.DisplaySize.x;
local display_y = imgui.io.DisplaySize.y;
 
-- Setting the display size.. (ImVec2)
imgui.io.DisplaySize = ImVec2(100, 100);
 
-- Obtaining if the left mouse button is down..
local isMouseDown = imgui.io.MouseDown[0];
 
-- Setting if the left mouse button is down manually..
local mouseDown = imgui.io.MouseDown;
mouseDown[0] = true;
imgui.io.MouseDown = mouseDown;

Any property that is within an array must be done in the above manner. You cannot directly index these arrays and set their values. You must pull the array, edit it, then reset the full array to make changes.


ImGui IO Table Properties

The table holds the following properties:

  • ImVec2 DisplaySize - The current display size for ImGui to render within.
  • float DeltaTime - Time elapsed since the last frame.
  • float IniSavingRate - Maximum time between saving current window positions.
  • const char* IniFilename - The path to the imgui.ini file.
  • const char* LogFilename - The path to the imgui_log.txt file.
  • float MouseDoubleClickTime - Time for a double-click to register.
  • float MouseDoubleClickMaxDist - Distance threshold to stay in to validate a double-click (in pixels).
  • float MouseDragThreshold - Distance threshold to before considering we are dragging.
  • int KeyMap[19] - Map of indices into the KeysDown entries array. (Used to translate key codes.)
  • float KeyRepeatDelay - Time before a key begins repeating while being held down.
  • float KeyRepeatRate - Time between each key repeat while being held down.
  • void* UserData - Custom defined user data.
  • ImFontAtlas* Fonts - Current atlas of loaded fonts. (Not implemented for Lua usage.)
  • float FontGlobalScale - Global scale for all fonts to use.
  • bool FontAllowUserScaling - Allows users to scroll in and out of ImGui when enabled.
  • ImVec2 DisplayFramebufferScale - Used for retina displays where window coords differ from frame buffer coords.
  • ImVec2 DisplayVisibleMin - Not used.
  • ImVec2 DisplayVisibleMax - Not used.
  • bool WordMovementUsesAltKey - Not used.
  • bool ShortcutsUseSuperKey - Not used.
  • bool DoubleClickSelectsWord - Not used.
  • bool MultiSelectUsesSuperKey - Not used.
  • ImVec2 MousePos - The current position of the mouse.
  • bool MouseDown[5] - Current mouse button states. (Starts at index 0: left, right, middle, +extras)
  • float MouseWheel - Current mouse wheel rotation offset.
  • bool MouseDrawCursor - Enables ImGui to render a cursor.
  • bool KeyCtrl - Flag that is true if Ctrl is pressed.
  • bool KeyShift - Flag that is true if Shift is pressed.
  • bool KeyAlt - Flag that is true if Alt is pressed.
  • bool KeySuper - Flag that is true if Windows key is pressed.
  • bool KeysDown[512] - Array of flags set to true if various keys are down.
  • ImWchar InputCharacters[16 + 1] - List of characters currently being input.
  • bool WantCaptureMouse - Flag that is true if ImGui is currently capturing the mouse.
  • bool WantCaptureKeyboard - Flag that is true if ImGui is currently capturing the keyboard.
  • bool WantTextInput - Flag that is true if ImGui is currently capturing input.
  • float Framerate - Estimated frames per second.
  • int MetricsAllocs - Number of current memory allocations.
  • int MetricsRenderVertices - Number of current vertices being rendered.
  • int MetricsRenderIndices - Number of indices being rendered.
  • int MetricsActiveWindows - Number of windows that are currently active.
  • ImVec2 MousePosPrev - The previous mouse position during the last frame.
  • ImVec2 MouseDelta - The current mouse delta.
  • bool MouseClicked[5] - Array of flags that determine if a mouse button was clicked since the last frame.
  • ImVec2 MouseClickedPos[5] - Array of positions that hold where a given button clicked since the last frame.
  • float MouseClickedTime[5] - Array of times that hold when a given button was clicked since the last frame.
  • bool MouseDoubleClicked[5] - Array of flags that hold if a mouse button was double clicked since the last frame.
  • bool MouseReleased[5] - Array of flags that hold if a mouse button was released since the last frame.
  • bool MouseDownOwned[5] - Array of flags that hold if a click started within an ImGui controls space since the last frame.
  • float MouseDownDuration[5] - Array of time that holds the duration since a mouse button was clicked down.
  • float MouseDownDurationPrev[5] - Array of time that holds the duration since a mouse button was clicked down (previously).
  • float MouseDragMaxDistanceSqr[5] - Array of distance (square rooted) that the mouse has traveled since a mouse click.
  • float KeysDownDuration[512] - Array of time that holds the duration of a key down.
  • float KeysDownDurationPrev[512] - Array of time that holds the duration of a key down (previously).

ImGui Style Table

The ImGui Style table the current visual style of ImGui and the various properties that can alter it.

You can access this table via:

-- Includes the various defintions and such for ImGui, also adding the imgui global..
require 'imguidef';

-- Obtain the style table..
local style = imgui.style;

Please Note: The imgui.style table differs from the main imgui functions! Please be sure to read the following notes carefully!!

The imgui.style table differs from the functions found within the ‘imgui’ table. The style table is implemented in a different manner and can make use of certain types such as ImVec2, ImVec4, etc. Because of this, things are used a little differently. But it should be straight forward enough.

Here are some examples of how you can make use of the imgui.style table properties:

-- Obtain the style table..
local s = imgui.style;
 
-- Set the rounding properties to 0..
s.GrabRounding = 0;
s.FrameRounding = 0;
s.ScrollbarRounding = 0;
s.WindowRounding = 0;
 
-- Set a color to black..
local colors = imgui.style.Colors;
colors[ImGuiCol_WindowBg] = ImVec4(0.0, 0.0, 0.0, 1.0);
imgui.style.Colors = colors;

Any property that is within an array must be done in the above manner. You cannot directly index these arrays and set their values. You must pull the array, edit it, then reset the full array to make changes.


ImGui Style Table Properties

The table holds the following properties:

  • float Alpha - Global alpha amount that applies to the entire ImGui rendering.
  • ImVec2 WindowPadding - The default window padding applied to windows.
  • ImVec2 WindowMinSize - The minimum window size.
  • float WindowRounding - The amount of rounding to apply to the window corners.
  • ImVec2 WindowTitleAlign - The alignment of the title of a window.
  • float ChildWindowRounding - Child window corner rounding.
  • ImVec2 FramePadding - Padding applied to framed rectangles.
  • float FrameRounding - Rounding applied to framed rectangles.
  • ImVec2 ItemSpacing - The amount of spacing between widgets and lines.
  • ImVec2 ItemInnerSpacing - The amount of spacing within elements of a composed widget. (ex. label inside of a slider.)
  • ImVec2 TouchExtraPadding - Padding added to controls to enhance touch usage. (Not used.)
  • float IndentSpacing - Default horizontal indentation amount.
  • float ColumnsMinSpacing - Minimum horizontal spacing between two columns.
  • float ScrollbarSize - Default size of a scroll bar. (Width if vertical, Height if horizontal.)
  • float ScrollbarRounding - The amount of rounding to apply to scrollbar corners.
  • float GrabMinSize - Minimum width/height of a grab box for sliders / scrollbars.
  • float GrabRounding - The amount of rounding to apply to grips.
  • ImVec2 DisplayWindowPadding - Window positions are clamped to be visible within the display area by at least this amount. Only covers regular windows.
  • ImVec2 DisplaySafeAreaPadding - If you cannot see the edge of your screen (e.g. on a TV) increase the safe area padding. Covers popups/tooltips as well regular windows.
  • bool AntiAliasedLines - Enable anti-aliasing on lines / borders.
  • bool AntiAliasedShapes - Enable anti-aliasing on filled shapes.
  • float CurveTessellationTol - Tessellation tolerance. Decrease for highly tessellated curves (higher quality, more polygons), increase to reduce quality.
  • ImVec4 Colors[43] - Array of colors used by ImGui to render the theme. (See the list of ImGuiCol_ properties in the imgui.lua library file for more info.)