Builds:

(Windows)
(OS X & Linux)

pyimgui¶

Python bindings for the amazing dear imgui C++ library - a Bloat-free Immediate Mode Graphical User Interface.

Installation¶

pyimgui is available on PyPI so you can easily install it with pip:

pip install imgui[full]

Above command will install imgui package with additional dependencies for all built-in rendering backend integrations (pygame, cocos2d, etc.). If you don’t want to install all additional dependencies you can always use bare pip install imgui command or select a specific set of extra requirements:

for pygame backend use pip install imgui[pygame]
for GLFW3 backend use pip install imgui[glfw]
for SDL2 backend use pip install imgui[sdl2]
for Cocos2d backend use pip install imgui[cocos2d]
for pyglet backend use pip install imgui[pyglet]

Package is distributed in form of built wheels so it does not require compilation on most operating systems. For more details about compatibility with diffferent OSes and Python versions see the Project ditribution section of this documentation page.

Project status¶

The imgui package provides support for the majority of core ImGui widgets and functionalities. Some low-level API elements and complex widgets (like plots) may be missing. We are working hard to provide 100% feature mapping of the core ImGui library. The completion badge shows up-to-date status of that goal.

Project distribution¶

This project has working build pipeline on Appveyor and Travis and builds succesfully for all major operating systems with different architectures:

Windows (32bit & 64bit)
Linux (32bit & 64bit)
OS X (universal build)

Right now we are ready to shipping the built wheels for these three systems (even for Linux using manylinux1 wheels). The build pipeline covers multiple Python versions:

py27
py33
py34
py35
py36
py37
py38

pyimgui provides documentation with multiple visual examples. Thanks to custom Sphinx extensions we are able to render GUI examples off screen directly from docstring snippets. These examples work also as automated functional tests. Documentation is hosted on pyimgui.readthedocs.io.

If none of these wheels work in your environment you can install the imgui package by compiling it directly from sdist distribution using one of following commands:

# will install Cython as extra dependency and compile from Cython sources
pip install imgui[Cython] --no-binary imgui

# will compile from pre-generated C++ sources
pip install imgui --no-binary imgui

Development tips¶

We have tried hard to make the process of bootstrapping this project as simple as possible.

In order to build and install project locally ,ake sure you have created and activated virtual environment using virtualenv or python -m venv (for newer Python releases). Then you can just run:

make build

This command will bootstrap whole environment (pull git submodules, install dev requirements etc.) and build the project. make will automatically install imgui in the development/editable mode. Then you can run some examples found in the doc/examples directory in order to verify if project is working.

For building documentation and running tests you will need some additional requirements from doc/requirements-test.txt.

You can run tests with:

py.test

If you have any problems with building or installing the project just ask us for help by creating GitHub issue.

Contents¶

Usage guide¶

First steps with imgui¶

In this tutorial you will learn how to use imgui library and how to create your first immediate mode GUI in Python.

What is immediate mode GUI¶

pyimgui is a Python wrapper around ImGui C++ library that allows you to easily define custom user interfaces no matter what game engine or graphic library you want to use. It is a immediate mode GUI library (opposed to retained mode). In short, retained mode means that there is no general GUI definition for your application but only direct calls that create new windows and widgets or query their state whenever they are needed and on every frame that is rendered.

Actual pipeline of drawing commands is constructed as you go and executed only when you need it. Defining whole GUI on every frame may seem counterintuitive and inefficient. Anyway, such approach is very flexible and allows you to iterate your UI designs very fast.

If you want to learn more about the general philosophy behind this technique watch following video where Casey Muratori thoroughly explains the idea of immediate mode user interfaces:

Using pyimgui¶

The imgui Python library consists of two main components

The imgui.core submodule. It provides functions that allow you to define new windows and widgets, query their state, and control the GUI context within your application. For the sake of simplicity all public functions from imgui.core submodule are also available in the root imgui namespace.
The imgui.integrations subpackage. It provides utilities that allow you to easily integrate ImGui with popular Python frameworks and engines.

Basic GUI drawing loop¶

Despite being an immediate mode GUI library ImGui doesn’t draw immediately anything every time you call any function from imgui.core module. Calls to the window and widget functions just create new entries in the list of drawing commands to be executed during next frame rendering. You alone decide when to start new frame context and when to execute all drawing commands.

Following is the basic rendering loop as its simplest:

import imgui

# initilize imgui context (see documentation)
imgui.create_context()
imgui.get_io().display_size = 100, 100
imgui.get_io().fonts.get_tex_data_as_rgba32()

# start new frame context
imgui.new_frame()

# open new window context
imgui.begin("Your first window!", True)

# draw text label inside of current window
imgui.text("Hello world!")

# close current window context
imgui.end()

# pass all drawing comands to the rendering pipeline
# and close frame context
imgui.render()
imgui.end_frame()

Above loop should result in following interface:

Of course this is not enough to create fully working GUI application with pyimgui. The bare imgui.core module is not able to render anything on its own. The imgui.render() function just passes abstract ImGui drawing commands to your rendering backend. In order to make it work you will first have to initialize the rendering backend of your choice.

Using built-in rendering backend integrations¶

The imgui.integrations sub-package provides multiple modules that aim to ease integration with various Python rendering engines, frameworks, and libraries:

imgui.integrations.cocos2d integrates pyimgui with Cocos2d game engine.
imgui.integrations.glfw integrates pyimgui with GLFW OpenGL windowing library through glfw Python package .
imgui.integrations.pygame integrates pyimgui with pygame game engine.
imgui.integrations.sdl2 integrates pyimgui with SDL2 library through PySDL2 Python package
imgui.integrations.pyglet integrates pyimgui with pyglet library.
imgui.integrations.opengl provides bare integration with OpenGL both in fixed pipeline and programmable pipeline mode. It does not provide any windowing facilities (so cannot be used as a standalone renderer) but serves as a good starting point for new custom integrations with other OpenGL-based frameworks and engines. It is based on PyOpenGL library.

Note that pyimgui does not include any of integrated backend requirement during installation as default. Still it is possible to install all additional requirements using setuptools extras feature. Just specify your integration submodule name for backend of your choicse as an extra tag during imgui installation with pip install command e.g.:

$ pip install imgui[sdl2]
$ pip install imgui[pygame]

If you want you can install pyimgui with multiple backends at once:

$ pip install imgui[glfw,cocos2d,pygame,sdl2,pyglet]

You can even request to install all requirements for every supported backend and every optional feature using single full extras option:

$ pip install imgui[full]

For actual examples of using these backends see the doc/examples directory of the project page on GitHub.

Using fonts¶

ImGui is able to load and display fonts. It is capable of handling both OTF and TTF fonts.

To load and configure fonts you should use the _FontAtlas object available through _IO.fonts attribute. Neither _FontAtlas nor _IO.fonts are meant to be instantiated by user. You access them through the imgui.get_io() function:

import imgui

io = imgui.get_io()

Once you have access to the font atlas you can load custom fonts by providing path of the OTF or TTF file to the _FontAtlas.add_font_from_file_ttf() method:

io = imgui.get_io()
io.fonts.add_font_from_file_ttf(
    font_file_path, font_pixel_size, glyph_ranges
)

The _FontAtlas.add_font_from_file_ttf() acccepts three important arguments:

filename (int): path to OTF or TTF file
size_pixels (int): font size in pixels
glyph_ranges (_StaticGlyphRanges): ranges of glyphs to load from the font file

Once all your fonts are loaded you can rasterize font into texture that will be later used by your renderer on all widgets containing text. Remember that core of the ImGui library is completely decoupled from the rendering pipeline. It means that your renderer implementation is responsible for rendering fonts from the texture and ImGui only provides the abstract draw calls for rendering part of the textures and doesn’t even know what is actual implementation behind them.

For OpenGL renderers you can generate texture for all your loaded fonts using following code:

import imgui
from OpenGL import GL as gl

io = imgui.get_io()

last_texture = gl.glGetIntegerv(gl.GL_TEXTURE_BINDING_2D)

width, height, pixels = io.fonts.get_tex_data_as_rgba32()

font_texture = gl.glGenTextures(1)

gl.glBindTexture(gl.GL_TEXTURE_2D, font_texture)
gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_MIN_FILTER, gl.GL_LINEAR)
gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_MAG_FILTER, gl.GL_LINEAR)
gl.glTexImage2D(gl.GL_TEXTURE_2D, 0, gl.GL_RGBA, width, height, 0, gl.GL_RGBA, gl.GL_UNSIGNED_BYTE, pixels)

io.fonts.texture_id = font_texture
gl.glBindTexture(gl.GL_TEXTURE_2D, last_texture)

Fortunately you don’t have to do this all by yourself. Every built-in integration class from imgui.integrations sub-package provides refresh_font_texture() that does this for you in a way that is native for given rendering pipeline.

Following example shows how this usually looks in practice:

io = imgui.get_io()
new_font = io.fonts.add_font_from_file_ttf(
    "DroidSans.ttf", 20,
)
impl.refresh_font_texture()

# later in frame code

imgui.begin("Default Window")

imgui.text("Text displayed using default font")

with imgui.font(new_font):
    imgui.text("Text displayed using custom font")

imgui.end()

Above code should render following result:

High-density screens¶

On some high-density displays like Retina Display fonts may appear blurred. It’s because font sizes are specified in screen size pixels but on high-density screens actual framebuffer will be much bigger so font texture needs to be slightly stretched.

In order to curcumvent this effect you can tell ImGui to generate bigger font

textures and set proper global font scaling factor as on following example:

import imgui

io = imgui.get_io()

# Font scaling factor is display dependent (different displays
# may have different densities), so you will have to find
# actual factor on your own
font_scaling_factor = 2
font_size_in_pixels = 30

io.fonts.add_font_from_file_ttf(
    "DroidSans.ttf", font_size_in_pixels * font_scaling_factor
)
io.font_global_scale /= font_scaling_factor

So how to relaibly guess required font scaling factor? One of the ways is to compare window size with size of the actual framebuffer assigned to that window. Implementation will be different for each rendering library. Here is one of possible examples for glfw:

win_w, win_h = glfw.get_window_size(window)
fb_w, fb_h = glfw.get_framebuffer_size(window)
font_scaling_factor = max(float(fb_w) / win_w, float(fb_h) / win_h)

If you set global scaling factor then you should also probably clear whole font atlas before adding any font atlas using _FontAtlas.clear(). Otherwise default built in font that is loaded on imgui startpup will be too small to read. Its place will be taken by first font you add to the atlas.

Using conditions¶

Many imgui functions accept conditions argument. It allows you to specify when values/procedures specified by given API function should be applied.

Available values for conditions are:

Using window flags¶

New windows created using begin() function can be customized/tuned with additional flags argument. This argument is an integer bitfield so many different flags can be joined together with | operator.

Example:

imgui.set_next_window_size(300, 90)
imgui.set_next_window_position(10, 0)
imgui.begin(
    "Custom window",
    flags=imgui.WINDOW_MENU_BAR
)
imgui.text("Custom window with menu bar and borders")
imgui.end()

imgui.set_next_window_size(300, 90)
imgui.set_next_window_position(10, 100)
imgui.begin("Default Window")
imgui.text("Default window with title bar")
imgui.end()

Outputs:

Window flags are also available for new scrollable child regions created with begin_child() function.

Example:

imgui.begin("Scrollale regions with flags")

imgui.begin_child(
    "Child 1", height=70, border=True,
    flags=imgui.WINDOW_ALWAYS_HORIZONTAL_SCROLLBAR
)
imgui.text("inside region 1")
imgui.end_child()

imgui.begin_child(
    "Child 2", height=70, border=True,
    flags=imgui.WINDOW_ALWAYS_VERTICAL_SCROLLBAR
)
imgui.text("inside region 2")
imgui.end_child()

imgui.end()

Outputs:

List of all available window flags (click to see documentation):

Using tree node flags¶

TreeNode functions accept various flags to manage their behaviour.

List of all available tree node flags (click to see documentation):

Using selectable flags¶

Selectable/Lists functions accept various flags to manage their behaviour.

List of all available selectable flags (click to see documentation):

Using input text flags¶

InpuText functions accept various flags to manage their behaviour.

List of all available input text flags (click to see documentation):

API reference¶

imgui package¶

imgui.ALWAYS = 1¶: Set the variable always

imgui.ONCE = 2¶: Only set the variable on the first call per runtime session

imgui.FIRST_USE_EVER = 4¶: Only set the variable if the window doesn’t exist in the .ini file

imgui.APPEARING = 8¶: Only set the variable if the window is appearing after being inactive (or the first time)

imgui.KEY_TAB = 0¶: for tabbing through fields

imgui.KEY_LEFT_ARROW = 1¶: for text edit

imgui.KEY_RIGHT_ARROW = 2¶: for text edit

imgui.KEY_UP_ARROW = 3¶: for text edit

imgui.KEY_DOWN_ARROW = 4¶: for text edit

imgui.KEY_HOME = 7¶: for text edit

imgui.KEY_END = 8¶: for text edit

imgui.KEY_INSERT = 9¶: for text edit

imgui.KEY_DELETE = 10¶: for text edit

imgui.KEY_BACKSPACE = 11¶: for text edit

imgui.KEY_SPACE = 12¶: for text edit

imgui.KEY_ENTER = 13¶: for text edit

imgui.KEY_ESCAPE = 14¶: for text edit

imgui.KEY_A = 15¶: for text edit CTRL+A – select all

imgui.KEY_C = 16¶: for text edit CTRL+C – copy

imgui.KEY_V = 17¶: for text edit CTRL+V – paste

imgui.KEY_X = 18¶: for text edit CTRL+X – cut

imgui.KEY_Y = 19¶: for text edit CTRL+Y – redo

imgui.KEY_Z = 20¶: for text edit CTRL+Z – undo

imgui.STYLE_ALPHA = 0¶: associated type – float.

imgui.STYLE_WINDOW_PADDING = 1¶: associated type – Vec2.

imgui.STYLE_WINDOW_ROUNDING = 2¶: associated type – float.

imgui.STYLE_WINDOW_BORDERSIZE = 3¶: associated type – float.

imgui.STYLE_WINDOW_MIN_SIZE = 4¶: associated type – Vec2.

imgui.STYLE_WINDOW_TITLE_ALIGN = 5¶: associated type – Vec2.

imgui.STYLE_CHILD_ROUNDING = 6¶: associated type – float.

imgui.STYLE_CHILD_BORDERSIZE = 7¶: associated type – float.

imgui.STYLE_POPUP_ROUNDING = 8¶: associated type – float.

imgui.STYLE_POPUP_BORDERSIZE = 9¶: associated type – float.

imgui.STYLE_FRAME_PADDING = 10¶: associated type – Vec2.

imgui.STYLE_FRAME_ROUNDING = 11¶: associated type – float.

imgui.STYLE_FRAME_BORDERSIZE = 12¶: associated type – float.

imgui.STYLE_ITEM_SPACING = 13¶: associated type – Vec2.

imgui.STYLE_ITEM_INNER_SPACING = 14¶: associated type – Vec2.

imgui.STYLE_INDENT_SPACING = 15¶: associated type – float.

imgui.STYLE_SCROLLBAR_SIZE = 16¶: associated type – float.

imgui.STYLE_SCROLLBAR_ROUNDING = 17¶: associated type – float.

imgui.STYLE_GRAB_MIN_SIZE = 18¶: associated type – float.

imgui.STYLE_GRAB_ROUNDING = 19¶: associated type – float.

imgui.STYLE_BUTTON_TEXT_ALIGN = 20¶: associated type – flags ImGuiAlign_*.

imgui.WINDOW_NO_TITLE_BAR = 1¶: Disable title-bar.

imgui.WINDOW_NO_RESIZE = 2¶: Disable user resizing with the lower-right grip.

imgui.WINDOW_NO_MOVE = 4¶: Disable user moving the window.

imgui.WINDOW_NO_SCROLLBAR = 8¶: Disable scrollbars (window can still scroll with mouse or programatically).

imgui.WINDOW_NO_SCROLL_WITH_MOUSE = 16¶: Disable user vertically scrolling with mouse wheel.

imgui.WINDOW_NO_COLLAPSE = 32¶: Disable user collapsing window by double-clicking on it.

imgui.WINDOW_ALWAYS_AUTO_RESIZE = 64¶: Resize every window to its content every frame.

imgui.WINDOW_NO_SAVED_SETTINGS = 256¶: Never load/save settings in .ini file.

imgui.WINDOW_NO_INPUTS = 512¶: Disable catching mouse or keyboard inputs.

imgui.WINDOW_MENU_BAR = 1024¶: Has a menu-bar.

imgui.WINDOW_HORIZONTAL_SCROLLING_BAR = 2048¶: Allow horizontal scrollbar to appear (off by default).

imgui.WINDOW_NO_FOCUS_ON_APPEARING = 4096¶: Disable taking focus when transitioning from hidden to visible state.

imgui.WINDOW_NO_BRING_TO_FRONT_ON_FOCUS = 8192¶: Disable bringing window to front when taking focus (e.g. clicking on it or programatically giving it focus).

imgui.WINDOW_ALWAYS_VERTICAL_SCROLLBAR = 16384¶: Always show vertical scrollbar (even if ContentSize.y < Size.y).

imgui.WINDOW_ALWAYS_HORIZONTAL_SCROLLBAR = 32768¶: Always show horizontal scrollbar (even if ContentSize.x < Size.x).

imgui.WINDOW_ALWAYS_USE_WINDOW_PADDING = 65536¶: Ensure child windows without border uses style.WindowPadding (ignored by default for non-bordered child windows, because more convenient).

imgui.TREE_NODE_SELECTED = 1¶: Draw as selected

imgui.TREE_NODE_FRAMED = 2¶: Full colored frame (e.g. for imgui.core.collapsing_header()).

imgui.TREE_NODE_ALLOW_ITEM_OVERLAP = 4¶: Hit testing to allow subsequent widgets to overlap this one

imgui.TREE_NODE_NO_TREE_PUSH_ON_OPEN = 8¶: Don’t do a TreePush() when open (e.g. for imgui.core.collapsing_header()). No extra indent nor pushing on ID stack.

imgui.TREE_NODE_NO_AUTO_OPEN_ON_LOG = 16¶: Don’t automatically and temporarily open node when Logging is active (by default logging will automatically open tree nodes).

imgui.TREE_NODE_DEFAULT_OPEN = 32¶: Default node to be open.

imgui.TREE_NODE_OPEN_ON_DOUBLE_CLICK = 64¶: Need double-click to open node.

imgui.TREE_NODE_OPEN_ON_ARROW = 128¶: Only open when clicking on the arrow part. If TREE_NODE_OPEN_ON_DOUBLE_CLICK is also set, single-click arrow or double-click all box to open.

imgui.TREE_NODE_LEAF = 256¶: No collapsing, no arrow (use as a convenience for leaf nodes).

imgui.TREE_NODE_BULLET = 512¶: Display a bullet instead of arrow.

imgui.TREE_NODE_FRAME_PADDING = 1024¶: Use FramePadding (even for an unframed text node) to vertically align text baseline to regular widget height. Equivalent to calling align_text_to_frame_padding()

imgui.TREE_NODE_COLLAPSING_HEADER = 26¶: Shortcut – imgui.TREE_NODE_FRAMED | imgui.TREE_NODE_NO_AUTO_OPEN_ON_LOG.

imgui.SELECTABLE_DONT_CLOSE_POPUPS = 1¶: Clicking this don’t close parent popup window.

imgui.SELECTABLE_SPAN_ALL_COLUMNS = 2¶: Selectable frame can span all columns (text will still fit in current column).

imgui.SELECTABLE_ALLOW_DOUBLE_CLICK = 4¶: Generate press events on double clicks too.

imgui.COMBO_POPUP_ALIGN_LEFT = 1¶: Align the popup toward the left by default

imgui.COMBO_HEIGHT_SMALL = 2¶: Max ~4 items visible. Tip – If you want your combo popup to be a specific size you can use SetNextWindowSizeConstraints() prior to calling BeginCombo()

imgui.COMBO_HEIGHT_REGULAR = 4¶: Max ~8 items visible (default)

imgui.COMBO_HEIGHT_LARGE = 8¶: Max ~20 items visible

imgui.COMBO_HEIGHT_LARGEST = 16¶: As many fitting items as possible

imgui.COMBO_NO_ARROW_BUTTON = 32¶: Display on the preview box without the square arrow button

imgui.COMBO_NO_PREVIEW = 64¶: Display only a square arrow button

imgui.COMBO_HEIGHT_MASK = 30¶: Shortcut – imgui.COMBO_HEIGHT_SMALL | imgui.COMBO_HEIGHT_REGULAR | imgui.COMBO_HEIGHT_LARGE | imgui.COMBO_HEIGHT_LARGEST.

imgui.FOCUS_CHILD_WINDOWS = 1¶: IsWindowFocused() – Return true if any children of the window is focused

imgui.FOCUS_ROOT_WINDOW = 2¶: IsWindowFocused() – Test from root window (top most parent of the current hierarchy)

imgui.FOCUS_ANY_WINDOW = 4¶: IsWindowFocused() – Return true if any window is focused

imgui.FOCUS_ROOT_AND_CHILD_WINDOWS = 3¶: Shortcut – imgui.FOCUS_CHILD_WINDOWS | imgui.FOCUS_ROOT_WINDOW.

imgui.HOVERED_NONE = 0¶: Return true if directly over the item/window, not obstructed by another window, not obstructed by an active popup or modal blocking inputs under them.

imgui.HOVERED_CHILD_WINDOWS = 1¶: IsWindowHovered() only – Return true if any children of the window is hovered

imgui.HOVERED_ROOT_WINDOW = 2¶: IsWindowHovered() only – Test from root window (top most parent of the current hierarchy)

imgui.HOVERED_ANY_WINDOW = 4¶: IsWindowHovered() only – Return true if any window is hovered

imgui.HOVERED_ALLOW_WHEN_BLOCKED_BY_POPUP = 8¶: Return true even if a popup window is normally blocking access to this item/window

imgui.HOVERED_ALLOW_WHEN_BLOCKED_BY_ACTIVE_ITEM = 32¶: Return true even if an active item is blocking access to this item/window. Useful for Drag and Drop patterns.

imgui.HOVERED_ALLOW_WHEN_OVERLAPPED = 64¶: Return true even if the position is overlapped by another window

imgui.HOVERED_RECT_ONLY = 104¶: Shortcut – imgui.HOVERED_ALLOW_WHEN_BLOCKED_BY_POPUP | imgui.HOVERED_ALLOW_WHEN_BLOCKED_BY_ACTIVE_ITEM | imgui.HOVERED_ALLOW_WHEN_OVERLAPPED.

imgui.HOVERED_ROOT_AND_CHILD_WINDOWS = 3¶: Shortcut – imgui.HOVERED_ROOT_WINDOW | imgui.HOVERED_CHILD_WINDOWS.

imgui.DRAG_DROP_SOURCE_NO_PREVIEW_TOOLTIP = 1¶: By default, a successful call to BeginDragDropSource opens a tooltip so you can display a preview or description of the source contents. This flag disable this behavior.

imgui.DRAG_DROP_SOURCE_NO_DISABLE_HOVER = 2¶: By default, when dragging we clear data so that IsItemHovered() will return true, to avoid subsequent user code submitting tooltips. This flag disable this behavior so you can still call IsItemHovered() on the source item.

imgui.DRAG_DROP_SOURCE_NO_HOLD_TO_OPEN_OTHERS = 4¶: Disable the behavior that allows to open tree nodes and collapsing header by holding over them while dragging a source item.

imgui.DRAG_DROP_SOURCE_ALLOW_NULL_ID = 8¶: Allow items such as Text(), Image() that have no unique identifier to be used as drag source, by manufacturing a temporary identifier based on their window-relative position. This is extremely unusual within the dear imgui ecosystem and so we made it explicit.

imgui.DRAG_DROP_SOURCE_EXTERN = 16¶: External source (from outside of imgui), won’t attempt to read current item/window info. Will always return true. Only one Extern source can be active simultaneously.

imgui.DRAG_DROP_SOURCE_AUTO_EXPIRE_PAYLOAD = 32¶: Automatically expire the payload if the source cease to be submitted (otherwise payloads are persisting while being dragged)

imgui.DRAG_DROP_ACCEPT_BEFORE_DELIVERY = 1024¶: AcceptDragDropPayload() will returns true even before the mouse button is released. You can then call IsDelivery() to test if the payload needs to be delivered.

imgui.DRAG_DROP_ACCEPT_NO_DRAW_DEFAULT_RECT = 2048¶: Do not draw the default highlight rectangle when hovering over target.

imgui.DRAG_DROP_ACCEPT_PEEK_ONLY = 3072¶: For peeking ahead and inspecting the payload before delivery.

imgui.DIRECTION_NONE = -1¶: Direction None

imgui.DIRECTION_LEFT = 0¶: Direction Left

imgui.DIRECTION_RIGHT = 1¶: Direction Right

imgui.DIRECTION_UP = 2¶: Direction Up

imgui.DIRECTION_DOWN = 3¶: Direction Down

imgui.MOUSE_CURSOR_TEXT_INPUT = 1¶: When hovering over InputText, etc.

imgui.MOUSE_CURSOR_RESIZE_ALL = 2¶: Unused

imgui.MOUSE_CURSOR_RESIZE_NS = 3¶: When hovering over an horizontal border

imgui.MOUSE_CURSOR_RESIZE_EW = 4¶: When hovering over a vertical border or a column

imgui.MOUSE_CURSOR_RESIZE_NESW = 5¶: When hovering over the bottom-left corner of a window

imgui.MOUSE_CURSOR_RESIZE_NWSE = 6¶: When hovering over the bottom-right corner of a window

imgui.INPUT_TEXT_CHARS_DECIMAL = 1¶: Allow 0123456789.+-*/

imgui.INPUT_TEXT_CHARS_HEXADECIMAL = 2¶: Allow 0123456789ABCDEFabcdef

imgui.INPUT_TEXT_CHARS_UPPERCASE = 4¶: Turn a..z into A..Z

imgui.INPUT_TEXT_CHARS_NO_BLANK = 8¶: Filter out spaces, tabs

imgui.INPUT_TEXT_AUTO_SELECT_ALL = 16¶: Select entire text when first taking mouse focus

imgui.INPUT_TEXT_ENTER_RETURNS_TRUE = 32¶: Return ‘true’ when Enter is pressed (as opposed to when the value was modified)

imgui.INPUT_TEXT_CALLBACK_COMPLETION = 64¶: Call user function on pressing TAB (for completion handling)

imgui.INPUT_TEXT_CALLBACK_HISTORY = 128¶: Call user function on pressing Up/Down arrows (for history handling)

imgui.INPUT_TEXT_CALLBACK_ALWAYS = 256¶: Call user function every time. User code may query cursor position, modify text buffer.

imgui.INPUT_TEXT_CALLBACK_CHAR_FILTER = 512¶: Call user function to filter character. Modify data->EventChar to replace/filter input, or return 1 to discard character.

imgui.INPUT_TEXT_ALLOW_TAB_INPUT = 1024¶: Pressing TAB input a ‘t’ character into the text field

imgui.INPUT_TEXT_CTRL_ENTER_FOR_NEW_LINE = 2048¶: In multi-line mode, allow exiting edition by pressing Enter. Ctrl+Enter to add new line (by default adds new lines with Enter).

imgui.INPUT_TEXT_NO_HORIZONTAL_SCROLL = 4096¶: Disable following the cursor horizontally

imgui.INPUT_TEXT_ALWAYS_INSERT_MODE = 8192¶: Insert mode

imgui.INPUT_TEXT_READ_ONLY = 16384¶: Read-only mode

imgui.INPUT_TEXT_PASSWORD = 32768¶: Password mode, display all characters as ‘*’

imgui.INPUT_TEXT_NO_UNDO_REDO = 65536¶: Disable undo/redo. Note that input text owns the text data while active, if you want to provide your own undo/redo stack you need e.g. to call clear_active_id().

class imgui.Vec2(x, y)¶

__getnewargs__()¶: Return self as a plain tuple. Used by copy and pickle.

__getstate__()¶: Exclude the OrderedDict from pickling

__repr__()¶: Return a nicely formatted representation string

x¶: Alias for field number 0

y¶: Alias for field number 1

class imgui.Vec4(x, y, z, w)¶

__getnewargs__()¶: Return self as a plain tuple. Used by copy and pickle.

__getstate__()¶: Exclude the OrderedDict from pickling

__repr__()¶: Return a nicely formatted representation string

w¶: Alias for field number 3

x¶: Alias for field number 0

y¶: Alias for field number 1

z¶: Alias for field number 2

imgui.core module¶

class imgui.core._IO¶

Main ImGui I/O context class used for ImGui configuration.

This class is not intended to be instantiated by user (thus _ name prefix). It should be accessed through obtained with get_io() function.

Example:

import imgui

io = imgui.get_io()

__reduce__()¶: _IO.__reduce_cython__(self)

__setstate__()¶: _IO.__setstate_cython__(self, __pyx_state)

add_input_character(self, ImWchar c)¶

config_cursor_blink¶

config_mac_osx_behaviors¶

config_resize_windows_from_edges¶

delta_time¶

display_fb_scale¶

display_size¶

display_visible_max¶

display_visible_min¶

font_allow_user_scaling¶

font_global_scale¶

fonts¶

framerate¶

ini_saving_rate¶

key_alt¶

key_ctrl¶

key_map¶

key_repeat_delay¶

key_repeat_rate¶

key_shift¶

key_super¶

keys_down¶

log_file_name¶

metrics_active_windows¶

metrics_render_vertices¶

mouse_double_click_max_distance¶

mouse_double_click_time¶

mouse_down¶

mouse_drag_threshold¶

mouse_draw_cursor¶

mouse_pos¶

mouse_wheel¶

nav_active¶

nav_visible¶

want_capture_keyboard¶

want_capture_mouse¶

want_save_ini_setting¶

want_set_mouse_pos¶

want_text_input¶

class imgui.core._FontAtlas¶

Font atlas object responsible for controling and loading fonts.

This class is not intended to be instantiated by user (thus _ name prefix). It should be accessed through _IO.fonts attribute of _IO obtained with get_io() function.

Example:

import imgui

io = imgui.get_io()
io.fonts.add_font_default()

__reduce__()¶: _FontAtlas.__reduce_cython__(self)

__setstate__()¶: _FontAtlas.__setstate_cython__(self, __pyx_state)

add_font_default(self)¶

add_font_from_file_ttf(self, str filename, float size_pixels, _StaticGlyphRanges glyph_ranges=None)¶

clear(self)¶

clear_fonts(self)¶

clear_input_data(self)¶

clear_tex_data(self)¶

get_glyph_ranges_chinese(self)¶

get_glyph_ranges_chinese_full(self)¶

get_glyph_ranges_cyrillic(self)¶

get_glyph_ranges_default(self)¶

get_glyph_ranges_japanese(self)¶

get_glyph_ranges_korean(self)¶

get_glyph_ranges_latin(self)¶

get_tex_data_as_alpha8(self)¶

get_tex_data_as_rgba32(self)¶

texture_id¶

Note – difference in mapping (maps actual TexID and not TextureID)

Note: texture ID type is implementation dependent. It is usually integer (at least for OpenGL).

class imgui.core._DrawList¶

Low level drawing API.

_DrawList instance can be acquired by calling get_window_draw_list().

__reduce__()¶: _DrawList.__reduce_cython__(self)

__setstate__()¶: _DrawList.__setstate_cython__(self, __pyx_state)

add_circle(self, float centre_x, float centre_y, float radius, ImU32 col, int num_segments=12, float thickness=1.0)¶

Add a circle to the draw list.

Example:

imgui.begin("Circle example")
draw_list = imgui.get_window_draw_list()
draw_list.add_circle(100, 60, 30, imgui.get_color_u32_rgba(1,1,0,1), thickness=3)
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_circle_0.png

Parameters:	centre_x (float) – circle centre coordinates centre_y (float) – circle centre coordinates radius (float) – circle radius col (ImU32) – RGBA color specification num_segments (ImU32) – Number of segments, defaults to 12 thickness (float) – Line thickness

Wraps API:

void ImDrawList::AddCircle(
    const ImVec2& centre,
    float radius,
    ImU32 col,
    int num_segments = 12,
    float thickness = 1.0
)

add_circle_filled(self, float centre_x, float centre_y, float radius, ImU32 col, ImU32 num_segments=12)¶

Add a filled circle to the draw list.

Example:

imgui.begin("Filled circle example")
draw_list = imgui.get_window_draw_list()
draw_list.add_circle_filled(100, 60, 30, imgui.get_color_u32_rgba(1,1,0,1))
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_circle_filled_0.png

Parameters:	centre_x (float) – circle centre coordinates centre_y (float) – circle centre coordinates radius (float) – circle radius col (ImU32) – RGBA color specification num_segments (ImU32) – Number of segments, defaults to 12

Wraps API:

void ImDrawList::AddCircleFilled(
    const ImVec2& centre,
    float radius,
    ImU32 col,
    int num_segments = 12
)

add_image(self, texture_id, tuple a, tuple b, tuple uv_a=(0, 0), tuple uv_b=(1, 1), ImU32 col=0xffffffff)¶

Add image to the draw list. Aspect ratio is not preserved.

Example:

imgui.begin("Image example")
texture_id = imgui.get_io().fonts.texture_id
draw_list = imgui.get_window_draw_list()
draw_list.add_image(texture_id, (20, 35), (180, 80), col=imgui.get_color_u32_rgba(0.5,0.5,1,1))
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_image_0.png

Parameters:	texture_id (object) – ID of the texture to draw a (tuple) – top-left image corner coordinates, b (tuple) – bottom-right image corner coordinates, uv_a (tuple) – UV coordinates of the top-left corner, defaults to (0, 0) uv_b (tuple) – UV coordinates of the bottom-right corner, defaults to (1, 1) col (ImU32) – tint color, defaults to 0xffffffff (no tint)

Wraps API:

void ImDrawList::AddImage(
    ImTextureID user_texture_id,
    const ImVec2& a,
    const ImVec2& b,
    const ImVec2& uv_a = ImVec2(0,0),
    const ImVec2& uv_b = ImVec2(1,1),
    ImU32 col = 0xFFFFFFFF
)

add_line(self, float start_x, float start_y, float end_x, float end_y, ImU32 col, float thickness=1.0)¶

Add a straight line to the draw list.

Example:

imgui.begin("Line example")
draw_list = imgui.get_window_draw_list()
draw_list.add_line(20, 35, 180, 80, imgui.get_color_u32_rgba(1,1,0,1), 3)
draw_list.add_line(180, 35, 20, 80, imgui.get_color_u32_rgba(1,0,0,1), 3)
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_line_0.png

Parameters:	start_x (float) – X coordinate of first point start_y (float) – Y coordinate of first point end_x (float) – X coordinate of second point end_y (float) – Y coordinate of second point col (ImU32) – RGBA color specification thickness (float) – Line thickness in pixels

Wraps API:

void ImDrawList::AddLine(
    const ImVec2& a,
    const ImVec2& b,
    ImU32 col,
    float thickness = 1.0f
)

add_polyline(self, list points, ImU32 col, bool closed=False, float thickness=1.0)¶

Add a optionally closed polyline to the draw list.

Example:

imgui.begin("Polyline example")
draw_list = imgui.get_window_draw_list()
draw_list.add_polyline([(20, 35), (90, 35), (55, 80)], imgui.get_color_u32_rgba(1,1,0,1), closed=False, thickness=3)
draw_list.add_polyline([(110, 35), (180, 35), (145, 80)], imgui.get_color_u32_rgba(1,0,0,1), closed=True, thickness=3)
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_polyline_0.png

Parameters:	points (list) – list of points col (float) – RGBA color specification closed (bool) – close the polyline to form a polygon thickness (float) – line thickness

Wraps API:

void ImDrawList::AddPolyline(
    const ImVec2* points,
    int num_points,
    ImU32 col,
    bool closed,
    float thickness
)

add_rect(self, float upper_left_x, float upper_left_y, float lower_right_x, float lower_right_y, ImU32 col, float rounding=0.0, ImGuiWindowFlags rounding_corners_flags=0xF, float thickness=1.0)¶

Add a rectangle outline to the draw list.

Example:

imgui.begin("Rect example")
draw_list = imgui.get_window_draw_list()
draw_list.add_rect(20, 35, 90, 80, imgui.get_color_u32_rgba(1,1,0,1), thickness=3)
draw_list.add_rect(110, 35, 180, 80, imgui.get_color_u32_rgba(1,0,0,1), rounding=5, thickness=3)
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_rect_0.png

Parameters:

upper_left_x (float) – X coordinate of top-left corner
upper_left_y (float) – Y coordinate of top-left corner
lower_right_x (float) – X coordinate of lower-right corner
lower_right_y (float) – Y coordinate of lower-right corner
col (ImU32) – RGBA color specification
rounding (float) – Degree of rounding, defaults to 0.0
rounding_corners_flags (ImDrawCornerFlags) – Draw flags, defaults to ImDrawCornerFlags_ALL
thickness (float) – Line thickness, defaults to 1.0

Wraps API:

void ImDrawList::AddRect(
    const ImVec2& a,
    const ImVec2& b,
    ImU32 col,
    float rounding = 0.0f,
    int rounding_corners_flags = ImDrawCornerFlags_All,
    float thickness = 1.0f
)

add_rect_filled(self, float upper_left_x, float upper_left_y, float lower_right_x, float lower_right_y, ImU32 col, float rounding=0.0, ImGuiWindowFlags rounding_corners_flags=0xF)¶

Add a filled rectangle to the draw list.

Example:

imgui.begin("Filled rect example")
draw_list = imgui.get_window_draw_list()
draw_list.add_rect_filled(20, 35, 90, 80, imgui.get_color_u32_rgba(1,1,0,1))
draw_list.add_rect_filled(110, 35, 180, 80, imgui.get_color_u32_rgba(1,0,0,1), 5)
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_rect_filled_0.png

Parameters:

upper_left_x (float) – X coordinate of top-left corner
upper_left_y (float) – Y coordinate of top-left corner
lower_right_x (float) – X coordinate of lower-right corner
lower_right_y (float) – Y coordinate of lower-right corner
col (ImU32) – RGBA color specification
rounding (float) – Degree of rounding, defaults to 0.0
rounding_corners_flags (ImDrawCornerFlags) – Draw flags, defaults to ImDrawCornerFlags_ALL

Wraps API:

void ImDrawList::AddRectFilled(
    const ImVec2& a,
    const ImVec2& b,
    ImU32 col,
    float rounding = 0.0f,
    int rounding_corners_flags = ImDrawCornerFlags_All
)

add_text(self, float pos_x, float pos_y, ImU32 col, str text)¶

Add text to the draw list.

Example:

imgui.begin("Text example")
draw_list = imgui.get_window_draw_list()
draw_list.add_text(20, 35, imgui.get_color_u32_rgba(1,1,0,1), "Hello!")
imgui.end()

Outputs:

_images/imgui.core._drawlist.add_text_0.png

Parameters:	pos_x (float) – X coordinate of the text’s upper-left corner pos_y (float) – Y coordinate of the text’s upper-left corner col (ImU32) – RGBA color specification text (str) – text

Wraps API:

void ImDrawList::AddText(
    const ImVec2& pos,
    ImU32 col,
    const char* text_begin,
    const char* text_end = NULL
)

channels_merge(self)¶

channels_set_current(self, int idx)¶

channels_split(self, int channels_count)¶: Warning - be careful with using channels as “layers”. Child windows are always drawn after their parent, so they will paint over its channels. To paint over child windows, use OverlayDrawList.

cmd_buffer_data¶

cmd_buffer_size¶

commands¶

idx_buffer_data¶

idx_buffer_size¶

vtx_buffer_data¶

vtx_buffer_size¶

Todo

consider inlining every occurence of _cast_args_ImVecX (profile)

class imgui.core.GuiStyle¶

Container for ImGui style information

__eq__¶: x.__eq__(y) <==> x==y

__ge__¶: x.__ge__(y) <==> x>=y

__gt__¶: x.__gt__(y) <==> x>y

__le__¶: x.__le__(y) <==> x<=y

__lt__¶: x.__lt__(y) <==> x<y

__ne__¶: x.__ne__(y) <==> x!=y

__reduce__()¶: GuiStyle.__reduce_cython__(self)

__setstate__()¶: GuiStyle.__setstate_cython__(self, __pyx_state)

alpha¶

Global alpha blending parameter for windows

Returns:	float

anti_aliased_fill¶

anti_aliased_lines¶

button_text_align¶

child_border_size¶

child_rounding¶

color(self, ImGuiCol variable)¶

colors¶

Retrieve and modify style colors through list-like interface.

Example:

style = imgui.get_style()
imgui.begin("Color window")
imgui.columns(4)
for color in range(0, imgui.COLOR_COUNT):
    imgui.text("Color: {}".format(color))
    imgui.color_button("color#{}".format(color), *style.colors[color])
    imgui.next_column()

imgui.end()

Outputs:

visual_examples/imgui.core.guistyle.colors_0.png

columns_min_spacing¶

static create()¶

curve_tessellation_tolerance¶

display_safe_area_padding¶

display_window_padding¶

frame_border_size¶

frame_padding¶

frame_rounding¶

grab_min_size¶

grab_rounding¶

indent_spacing¶

item_inner_spacing¶

item_spacing¶

mouse_cursor_scale¶

popup_border_size¶

popup_rounding¶

scrollbar_rounding¶

scrollbar_size¶

touch_extra_padding¶

window_border_size¶

window_min_size¶

window_padding¶

window_rounding¶

window_title_align¶

exception imgui.core.ImGuiError¶

imgui.core.accept_drag_drop_payload(str type, ImGuiDragDropFlags flags=0)¶

Get the drag and drop payload. Only call after begin_drag_drop_target() returns True.

Note: this is a beta API.

For a complete example see begin_drag_drop_source().

Parameters:	type (str) – user defined type with maximum 32 bytes. flags (ImGuiDragDropFlags) – DragDrop flags.
Returns:	bytes – the payload data that was set by `set_drag_drop_payload()`.

Wraps API:

const ImGuiPayload* AcceptDragDropPayload(const char* type, ImGuiDragDropFlags flags = 0)

imgui.core.begin(str label, closable=False, ImGuiWindowFlags flags=0)¶

Begin a window.

Example:

imgui.begin("Example: empty window")
imgui.end()

Outputs:

Parameters:	label (str) – label of the window. closable (bool) – define if window is closable. flags – Window flags. See: list of available flags.
Returns:	tuple – `(expanded, opened)` tuple of bools. If window is collapsed `expanded==True`. The value of `opened` is always True for non-closable and open windows but changes state to False on close button click for closable windows.

Wraps API:

Begin(
    const char* name,
    bool* p_open = NULL,
    ImGuiWindowFlags flags = 0
)

imgui.core.begin_child¶

Begin a scrolling region.

Note: sizing of child region allows for three modes: * 0.0 - use remaining window size * >0.0 - fixed size * <0.0 - use remaining window size minus abs(size)

Example:

imgui.begin("Example: child region")

imgui.begin_child("region", 150, -50, border=True)
imgui.text("inside region")
imgui.end_child()

imgui.text("outside region")
imgui.end()

Outputs:

Parameters:	label (str or int) – Child region identifier. width (float) – Region width. See note about sizing. height (float) – Region height. See note about sizing. border (bool) – True if should display border. Defaults to False. flags – Window flags. See: list of available flags.
Returns:	bool – True if region is visible

Wraps API:

bool BeginChild(
    const char* str_id,
    const ImVec2& size = ImVec2(0,0),
    bool border = false,
    ImGuiWindowFlags flags = 0
)

bool BeginChild(
    ImGuiID id,
    const ImVec2& size = ImVec2(0,0),
    bool border = false,
    ImGuiWindowFlags flags = 0
)

imgui.core.begin_drag_drop_source(ImGuiDragDropFlags flags=0)¶

Set the current item as a drag and drop source. If this return True, you can call set_drag_drop_payload() and end_drag_drop_source().

Note: this is a beta API.

Parameters:	flags (ImGuiDragDropFlags) – DragDrop flags.
Returns:	bool – True while a drag starting at this source is occurring

Example:

imgui.begin("Example: drag and drop")

imgui.button('source')
if imgui.begin_drag_drop_source():
    imgui.set_drag_drop_payload('itemtype', b'payload')
    imgui.button('dragged source')
    imgui.end_drag_drop_source()

imgui.button('dest')
if imgui.begin_drag_drop_target():
    payload = imgui.accept_drag_drop_payload('itemtype')
    if payload is not None:
        print('Received:', payload)
    imgui.end_drag_drop_target()

imgui.end()

Outputs:

visual_examples/imgui.core.begin_drag_drop_source_0.png

Wraps API:

bool BeginDragDropSource(ImGuiDragDropFlags flags = 0)

imgui.core.begin_drag_drop_target()¶

Set the current item as a drag and drop target. If this return True, you can call accept_drag_drop_payload() and end_drag_drop_target().

Note: this is a beta API.

Returns:	bool – True when a drag hovers over the target

For a complete example see begin_drag_drop_source().

Wraps API:

bool BeginDragDropTarget()

imgui.core.begin_group()¶

Start item group and lock its horizontal starting position.

Captures group bounding box into one “item”. Thanks to this you can use is_item_hovered() or layout primitives such as same_line() on whole group, etc.

Example:

imgui.begin("Example: item groups")

imgui.begin_group()
imgui.text("First group (buttons):")
imgui.button("Button A")
imgui.button("Button B")
imgui.end_group()

imgui.same_line(spacing=50)

imgui.begin_group()
imgui.text("Second group (text and bullet texts):")
imgui.bullet_text("Bullet A")
imgui.bullet_text("Bullet B")
imgui.end_group()

imgui.end()

Outputs:

Wraps API:

void BeginGroup()

imgui.core.begin_main_menu_bar()¶

Create new full-screen menu bar.

Only call end_main_menu_bar() if this function returns True!

Example:

if imgui.begin_main_menu_bar():
    # first menu dropdown
    if imgui.begin_menu('File', True):
        imgui.menu_item('New', 'Ctrl+N', False, True)
        imgui.menu_item('Open ...', 'Ctrl+O', False, True)

        # submenu
        if imgui.begin_menu('Open Recent', True):
            imgui.menu_item('doc.txt', None, False, True)
            imgui.end_menu()

        imgui.end_menu()

    imgui.end_main_menu_bar()

Outputs:

_images/imgui.core.begin_main_menu_bar_0.png

Returns:	bool – True if main menu bar is displayed (opened).

Wraps API:

bool BeginMainMenuBar()

imgui.core.begin_menu(str label, enabled=True)¶

Create new expandable menu in current menu bar.

Only call end_menu() if this returns True!

For practical example how to use this function, please see documentation of begin_main_menu_bar() or begin_menu_bar().

Parameters:	label (str) – label of the menu. enabled (bool) – define if menu is enabled or disabled.
Returns:	bool – True if the menu is displayed (opened).

Wraps API:

bool BeginMenu(
    const char* label,
    bool enabled
)

imgui.core.begin_menu_bar()¶

Append new menu menu bar to current window.

This function is different from begin_main_menu_bar(), as this is child-window specific. Only call end_menu_bar() if this returns True!

Note: this requires WINDOW_MENU_BAR flag to be set for the current window. Without this flag set the begin_menu_bar() function will always return False.

Example:

flags = imgui.WINDOW_MENU_BAR

imgui.begin("Child Window - File Browser", flags=flags)

if imgui.begin_menu_bar():
    if imgui.begin_menu('File'):
        imgui.menu_item('Close')
        imgui.end_menu()

    imgui.end_menu_bar()

imgui.end()

Outputs:

Returns:	bool – True if menu bar is displayed (opened).

Wraps API:

bool BeginMenuBar()

imgui.core.begin_popup(str label, ImGuiWindowFlags flags=0)¶

Open a popup window.

Returns True if the popup is open and you can start outputting content to it. Only call end_popup() if begin_popup() returned true.

Example:

imgui.begin("Example: simple popup")

if imgui.button("select"):
    imgui.open_popup("select-popup")

imgui.same_line()

if imgui.begin_popup("select-popup"):
    imgui.text("Select one")
    imgui.separator()
    imgui.selectable("One")
    imgui.selectable("Two")
    imgui.selectable("Three")
    imgui.end_popup()

imgui.end()

Outputs:

Parameters:	label (str) – label of the modal window.
Returns:	opened (bool) – True if popup is opened.

Wraps API:

bool BeginPopup(
    const char* str_id,
    ImGuiWindowFlags flags = 0
)

imgui.core.begin_popup_context_item(str label=None, int mouse_button=1)¶

This is a helper function to handle the most simple case of associating one named popup to one given widget.

Example:

imgui.begin("Example: popup context view")
imgui.text("Right-click to set value.")
if imgui.begin_popup_context_item("Item Context Menu", mouse_button=0):
    imgui.selectable("Set to Zero")
    imgui.end_popup()
imgui.end()

Outputs:

Parameters:	label (str) – label of item. mouse_button (int) – mouse button identifier: 0 - left button, 1 - right button, 2 - middle button
Returns:	opened (bool) – opened can be False when the popup is completely clipped (e.g. zero size display).

Wraps API:

bool BeginPopupContextItem(
    const char* str_id = NULL,
    int mouse_button = 1
)

imgui.core.begin_popup_context_window(str label=None, bool also_over_items=True, int mouse_button=1)¶

Helper function to open and begin popup when clicked on current window.

As all popup functions it should end with end_popup().

Example:

imgui.begin("Example: popup context window")
if imgui.begin_popup_context_window(mouse_button=0):
    imgui.selectable("Clear")
    imgui.end_popup()
imgui.end()

Outputs:

Parameters:	label (str) – label of the window also_over_items (bool) – display on top of widget. mouse_button (int) – mouse button identifier: 0 - left button 1 - right button 2 - middle button
Returns:	opened (bool) – if the context window is opened.

Wraps API:

bool BeginPopupContextWindow(
    const char* str_id = NULL,
    bool also_over_items = true,
    int mouse_button = 1
)

imgui.core.begin_popup_modal(str title, visible=None, ImGuiWindowFlags flags=0)¶

Begin pouring popup contents.

Differes from begin_popup() with its modality - meaning it opens up on top of every other window.

Example:

imgui.begin("Example: simple popup modal")

if imgui.button("Open Modal popup"):
    imgui.open_popup("select-popup")

imgui.same_line()

if imgui.begin_popup_modal("select-popup")[0]:
    imgui.text("Select an option:")
    imgui.separator()
    imgui.selectable("One")
    imgui.selectable("Two")
    imgui.selectable("Three")
    imgui.end_popup()

imgui.end()

Outputs:

Parameters:	title (str) – label of the modal window. visible (bool) – define if popup is visible or not. flags – Window flags. See: list of available flags.
Returns:	tuple – `(opened, visible)` tuple of bools. opened can be `False` when the popup is completely clipped (e.g. zero size display).

Wraps API:

bool BeginPopupModal(
    const char* name,
    bool* p_open = NULL,
    ImGuiWindowFlags extra_flags = 0
)

imgui.core.begin_tooltip()¶

Use to create full-featured tooltip windows that aren’t just text.

Example:

imgui.begin("Example: tooltip")
imgui.button("Click me!")
if imgui.is_item_hovered():
    imgui.begin_tooltip()
    imgui.text("This button is clickable.")
    imgui.text("This button has full window tooltip.")
    texture_id = imgui.get_io().fonts.texture_id
    imgui.image(texture_id, 512, 64, border_color=(1, 0, 0, 1))
    imgui.end_tooltip()
imgui.end()

Outputs:

Wraps API:

void BeginTooltip()

imgui.core.bullet()¶

Display a small circle and keep the cursor on the same line.

Example:

imgui.begin("Example: bullets")

for i in range(10):
    imgui.bullet()

imgui.end()

Outputs:

Wraps API:

void Bullet()

imgui.core.bullet_text(str text)¶

Display bullet and text.

This is shortcut for:

imgui.bullet()
imgui.text(text)

Example:

imgui.begin("Example: bullet text")
imgui.bullet_text("Bullet 1")
imgui.bullet_text("Bullet 2")
imgui.bullet_text("Bullet 3")
imgui.end()

Outputs:

Parameters:	text (str) – text to display.

Wraps API:

void BulletText(const char* fmt, ...)

imgui.core.button(str label, width=0, height=0)¶

Display button.

Example:

imgui.begin("Example: button")
imgui.button("Button 1")
imgui.button("Button 2")
imgui.end()

Outputs:

Parameters:	label (str) – button label. width (float) – button width. height (float) – button height.
Returns:	bool – True if clicked.

Wraps API:

bool Button(const char* label, const ImVec2& size = ImVec2(0,0))

imgui.core.calculate_item_width()¶

Calculate and return the current item width.

Returns:	float – calculated item width.

Wraps API:

float CalcItemWidth()

imgui.core.checkbox(str label, bool state)¶

Display checkbox widget.

Example:

# note: these should be initialized outside of the main interaction
#       loop
checkbox1_enabled = True
checkbox2_enabled = False

imgui.new_frame()
imgui.begin("Example: checkboxes")

# note: first element of return two-tuple notifies if there was a click
#       event in currently processed frame and second element is actual
#       checkbox state.
_, checkbox1_enabled = imgui.checkbox("Checkbox 1", checkbox1_enabled)
_, checkbox2_enabled = imgui.checkbox("Checkbox 2", checkbox2_enabled)

imgui.text("Checkbox 1 state value: {}".format(checkbox1_enabled))
imgui.text("Checkbox 2 state value: {}".format(checkbox2_enabled))

imgui.end()

Outputs:

Parameters:	label (str) – text label for checkbox widget. state (bool) – current (desired) state of the checkbox. If it has to change, the new state will be returned as a second item of the return value.
Returns:	tuple – a `(clicked, state)` two-tuple indicating click event and the current state of the checkbox.

Wraps API:

bool Checkbox(const char* label, bool* v)

imgui.core.checkbox_flags(str label, unsigned int flags, unsigned int flags_value)¶

Display checkbox widget that handle integer flags (bit fields).

It is useful for handling window/style flags or any kind of flags implemented as integer bitfields.

Example:

flags = imgui.WINDOW_NO_RESIZE | imgui.WINDOW_NO_MOVE

imgui.begin("Example: checkboxes for flags", flags=flags)

clicked, flags = imgui.checkbox_flags(
    "No resize", flags, imgui.WINDOW_NO_RESIZE
)
clicked, flags = imgui.checkbox_flags(
    "No move", flags, imgui.WINDOW_NO_MOVE
)
clicked, flags = imgui.checkbox_flags(
    "No collapse", flags, imgui.WINDOW_NO_COLLAPSE
)
# note: it also allows to use multiple flags at once
clicked, flags = imgui.checkbox_flags(
    "No resize & no move", flags,
    imgui.WINDOW_NO_RESIZE | imgui.WINDOW_NO_MOVE
)
imgui.text("Current flags value: {0:b}".format(flags))
imgui.end()

Outputs:

Parameters:

label (str) – text label for checkbox widget.
flags (int) – current state of the flags associated with checkbox. Actual state of checkbox (toggled/untoggled) is calculated from this argument and flags_value argument. If it has to change, the new state will be returned as a second item of the return value.
flags_value (int) – values of flags this widget can toggle. Represents bitmask in flags bitfield. Allows multiple flags to be toggled at once (specify using bit OR operator |, see example above).

Returns:

tuple – a (clicked, flags) two-tuple indicating click event and the current state of the flags controlled with this checkbox.

Wraps API:

bool CheckboxFlags(
    const char* label, unsigned int* flags,
    unsigned int flags_value
)

imgui.core.close_current_popup()¶

Close the current popup window begin-ed directly above this call. Clicking on a menu_item() or selectable() automatically close the current popup.

For practical example how to use this function, please see documentation of open_popup().

Wraps API:

void CloseCurrentPopup()

imgui.core.collapsing_header(str text, visible=None, ImGuiTreeNodeFlags flags=0)¶

Collapsable/Expandable header view.

Returns ‘true’ if the header is open. Doesn’t indent or push to stack, so no need to call any pop function.

Example:

visible = True

imgui.begin("Example: collapsing header")
expanded, visible = imgui.collapsing_header("Expand me!", visible)

if expanded:
    imgui.text("Now you see me!")
imgui.end()

Outputs:

_images/imgui.core.collapsing_header_0.png

Parameters:	text (str) – Tree node label visible (bool or None) – Force visibility of a header. If set to True shows additional (X) close button. If set to False header is not visible at all. If set to None header is always visible and close button is not displayed. flags – TreeNode flags. See: list of available flags.
Returns:	tuple – a `(expanded, visible)` two-tuple indicating if item was expanded and whether the header is visible or not (only if `visible` input argument is True/False).

Wraps API:

bool CollapsingHeader(const char* label, ImGuiTreeNodeFlags flags = 0)

bool CollapsingHeader(
    const char* label,
    bool* p_open,
    ImGuiTreeNodeFlags flags = 0
)

imgui.core.color_button(str desc_id, float r, float g, float b, a=1., flags=0, float width=0, float height=0)¶

Display colored button.

Example:

imgui.begin("Example: color button")
imgui.color_button("Button 1", 1, 0, 0, 1, 0, 10, 10)
imgui.color_button("Button 2", 0, 1, 0, 1, 0, 10, 10)
imgui.color_button("Wide Button", 0, 0, 1, 1, 0, 20, 10)
imgui.color_button("Tall Button", 1, 0, 1, 1, 0, 10, 20)
imgui.end()

Outputs:

Parameters:	#r (float) – red color intensity. #g (float) – green color intensity. #b (float) – blue color instensity. #a (float) – alpha intensity. #ImGuiColorEditFlags – Color edit flags. Zero for none. #width (float) – Width of the color button #height (float) – Height of the color button
Returns:	bool – True if button is clicked.

Wraps API:

bool ColorButton(
    const char* desc_id,
    const ImVec4& col,
    ImGuiColorEditFlags flags,
    ImVec2 size
)

imgui.core.color_edit3(str label, float r, float g, float b)¶

Display color edit widget for color without alpha value.

Example:

# note: the variable that contains the color data, should be initialized
#       outside of the main interaction loop
color_1 = 1., .0, .5
color_2 = 0., .8, .3

imgui.begin("Example: color edit without alpha")

# note: first element of return two-tuple notifies if the color was changed
#       in currently processed frame and second element is current value
#       of color
changed, color_1 = imgui.color_edit3("Color 1", *color_1)
changed, color_2 = imgui.color_edit3("Color 2", *color_2)

imgui.end()

Outputs:

Parameters:	label (str) – color edit label. r (float) – red color intensity. g (float) – green color intensity. b (float) – blue color instensity.
Returns:	tuple – a `(bool changed, float color[3])` tuple that contains indicator of color change and current value of color

Wraps API:

bool ColorEdit3(const char* label, float col[3])

imgui.core.color_edit4(str label, float r, float g, float b, float a, bool show_alpha=True)¶

Display color edit widget for color with alpha value.

Example:

# note: the variable that contains the color data, should be initialized
#       outside of the main interaction loop
color = 1., .0, .5, 1.

imgui.begin("Example: color edit with alpha")

# note: first element of return two-tuple notifies if the color was changed
#       in currently processed frame and second element is current value
#       of color and alpha
_, color = imgui.color_edit4("Alpha", *color, show_alpha=True)
_, color = imgui.color_edit4("No alpha", *color, show_alpha=False)

imgui.end()

Outputs:

Parameters:	label (str) – color edit label. r (float) – red color intensity. g (float) – green color intensity. b (float) – blue color instensity. a (float) – alpha intensity. show_alpha (bool) – if set to True wiget allows to modify alpha
Returns:	tuple – a `(bool changed, float color[4])` tuple that contains indicator of color change and current value of color and alpha

Wraps API:

ColorEdit4(
    const char* label, float col[4], bool show_alpha = true
)

imgui.core.columns(int count=1, str identifier=None, bool border=True)¶

Setup number of columns. Use an identifier to distinguish multiple column sets. close with columns(1).

Example:

imgui.begin("Example: Columns - File list")
imgui.columns(4, 'fileLlist')
imgui.separator()
imgui.text("ID")
imgui.next_column()
imgui.text("File")
imgui.next_column()
imgui.text("Size")
imgui.next_column()
imgui.text("Last Modified")
imgui.next_column()
imgui.separator()
imgui.set_column_offset(1, 40)

imgui.next_column()
imgui.text('FileA.txt')
imgui.next_column()
imgui.text('57 Kb')
imgui.next_column()
imgui.text('12th Feb, 2016 12:19:01')
imgui.next_column()

imgui.next_column()
imgui.text('ImageQ.png')
imgui.next_column()
imgui.text('349 Kb')
imgui.next_column()
imgui.text('1st Mar, 2016 06:38:22')
imgui.next_column()

imgui.columns(1)
imgui.end()

Outputs:

Parameters:	count (int) – Columns count. identifier (str) – Table identifier. border (bool) – Display border, defaults to `True`.

Wraps API:

void Columns(
    int count = 1,
    const char* id = NULL,
    bool border = true
)

imgui.core.combo(str label, int current, list items, int height_in_items=-1)¶

Display combo widget.

Example:

current = 2
imgui.begin("Example: combo widget")

clicked, current = imgui.combo(
    "combo", current, ["first", "second", "third"]
)

imgui.end()

Outputs:

Parameters:	label (str) – combo label. current (int) – index of selected item. items (list) – list of string labels for items. height_in_items (int) – height of dropdown in items. Defaults to -1 (autosized).
Returns:	tuple – a `(changed, current)` tuple indicating change of selection and current index of selected item.

Wraps API:

bool Combo(
    const char* label, int* current_item,
    const char* items_separated_by_zeros,
    int height_in_items = -1
)

imgui.core.create_context(_FontAtlas shared_font_atlas=None)¶

CreateContext

Todo

Add an example

Wraps API:

ImGuiContext* CreateContext(
        # note: optional
        ImFontAtlas* shared_font_atlas = NULL);
)

imgui.core.destroy_context(_ImGuiContext ctx=None)¶

DestroyContext

Wraps API:

DestroyContext(
        # note: optional
        ImGuiContext* ctx = NULL);

imgui.core.drag_float(str label, float value, float change_speed=1.0, float min_value=0.0, float max_value=0.0, str format='%.3f', float power=1.)¶

Display float drag widget.

Todo

Consider replacing format with something that allows for safer way to specify display format without loosing the functionality of wrapped function.

Example:

value = 42.0

imgui.begin("Example: drag float")
changed, value = imgui.drag_float(
    "Default", value,
)
changed, value = imgui.drag_float(
    "Less precise", value, format="%.1f"
)
imgui.text("Changed: %s, Value: %s" % (changed, value))
imgui.end()

Outputs:

Parameters:

label (str) – widget label.
value (float) – drag values,
change_speed (float) – how fast values change on drag.
min_value (float) – min value allowed by widget.
max_value (float) – max value allowed by widget.
format (str) – display format string as C-style printf format string. Warning: Highly unsafe when used without care. May lead to segmentation faults and other memory violation issues.
power (float) – index of the power function applied to the value.

Returns:

tuple – a (changed, value) tuple that contains indicator of widget state change and the current drag value.

Wraps API:

bool DragFloat(
    const char* label,
    float* v,
    float v_speed = 1.0f,
    float v_min = 0.0f,
    float v_max = 0.0f,
    const char* format = "%.3f",
    float power = 1.0f
)

imgui.core.drag_float2(str label, float value0, float value1, float change_speed=1.0, float min_value=0.0, float max_value=0.0, str format='%.3f', float power=1.)¶

Display float drag widget with 2 values.

Example:

values = 88.0, 42.0

imgui.begin("Example: drag float")
changed, values = imgui.drag_float2(
    "Default", *values
)
changed, values = imgui.drag_float2(
    "Less precise", *values, format="%.1f"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:

label (str) – widget label.
value0, value1 (float) – drag values.
change_speed (float) – how fast values change on drag.
min_value (float) – min value allowed by widget.
max_value (float) – max value allowed by widget.
format (str) – display format string as C-style printf format string. Warning: highly unsafe. See drag_float().
power (float) – index of the power function applied to the value.

Returns:

tuple – a (changed, values) tuple that contains indicator of widget state change and the tuple of current drag values.

Wraps API:

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* format = "%.3f",
    float power = 1.0f
)

imgui.core.drag_float3(str label, float value0, float value1, float value2, float change_speed=1.0, float min_value=0.0, float max_value=0.0, str format='%.3f', float power=1.)¶

Display float drag widget with 3 values.

Example:

values = 88.0, 42.0, 69.0

imgui.begin("Example: drag float")
changed, values = imgui.drag_float3(
    "Default", *values
)
changed, values = imgui.drag_float3(
    "Less precise", *values, format="%.1f"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:

label (str) – widget label.
value0, value1, value2 (float) – drag values.
change_speed (float) – how fast values change on drag.
min_value (float) – min value allowed by widget.
max_value (float) – max value allowed by widget.
format (str) – display format string as C-style printf format string. Warning: highly unsafe. See drag_float().
power (float) – index of the power function applied to the value.

Returns:

tuple – a (changed, values) tuple that contains indicator of widget state change and the tuple of current drag values.

Wraps API:

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* format = "%.3f",
    float power = 1.0f
)

imgui.core.drag_float4(str label, float value0, float value1, float value2, float value3, float change_speed=1.0, float min_value=0.0, float max_value=0.0, str format='%.3f', float power=1.)¶

Display float drag widget with 4 values.

Example:

values = 88.0, 42.0, 69.0, 0.0

imgui.begin("Example: drag float")
changed, values = imgui.drag_float4(
    "Default", *values
)
changed, values = imgui.drag_float4(
    "Less precise", *values, format="%.1f"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:

label (str) – widget label.
value0, value1, value2, value3 (float) – drag values.
change_speed (float) – how fast values change on drag.
min_value (float) – min value allowed by widget.
max_value (float) – max value allowed by widget.
format (str) – display format string as C-style printf format string. Warning: highly unsafe. See drag_float().
power (float) – index of the power function applied to the value.

Returns:

tuple – a (changed, values) tuple that contains indicator of widget state change and the tuple of current drag values.

Wraps API:

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* format = "%.3f",
    float power = 1.0f
)

imgui.core.drag_int(str label, int value, float change_speed=1.0, int min_value=0, int max_value=0, str format='%d')¶

Display int drag widget.

Todo

Consider replacing format with something that allows for safer way to specify display format without loosing the functionality of wrapped function.

Example:

value = 42

imgui.begin("Example: drag int")
changed, value = imgui.drag_int("drag int", value,)
imgui.text("Changed: %s, Value: %s" % (changed, value))
imgui.end()

Outputs:

Parameters:

label (str) – widget label.
value (int) – drag value,
change_speed (float) – how fast values change on drag.
min_value (int) – min value allowed by widget.
max_value (int) – max value allowed by widget.
format (str) – display format string as C-style printf format string. Warning: Highly unsafe when used without care. May lead to segmentation faults and other memory violation issues.

Returns:

tuple – a (changed, value) tuple that contains indicator of widget state change and the current drag value.

Wraps API:

bool DragInt(
    const char* label,
    int* v,
    float v_speed = 1.0f,
    int v_min = 0.0f,
    int v_max = 0.0f,
    const char* format = "%d",
)

imgui.core.drag_int2(str label, int value0, int value1, float change_speed=1.0, int min_value=0, int max_value=0, str format='%d')¶

Display int drag widget with 2 values.

Example:

values = 88, 42

imgui.begin("Example: drag int")
changed, values = imgui.drag_int2(
    "drag ints", *values
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (int) – drag values. change_speed (float) – how fast values change on drag. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `drag_int()`.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current drag values.

Wraps API:

bool DragInt2(
    const char* label,
    int v[2],
    float v_speed = 1.0f,
    int v_min = 0.0f,
    int v_max = 0.0f,
    const char* format = "%d",
)

imgui.core.drag_int3(str label, int value0, int value1, int value2, float change_speed=1.0, int min_value=0, int max_value=0, str format='%d')¶

Display int drag widget with 3 values.

Example:

values = 88, 42, 69

imgui.begin("Example: drag int")
changed, values = imgui.drag_int3(
    "drag ints", *values
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (int) – drag values. change_speed (float) – how fast values change on drag. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `drag_int()`.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current drag values.

Wraps API:

bool DragInt3(
    const char* label,
    int v[3],
    float v_speed = 1.0f,
    int v_min = 0.0f,
    int v_max = 0.0f,
    const char* format = "%d",
)

imgui.core.drag_int4(str label, int value0, int value1, int value2, int value3, float change_speed=1.0, int min_value=0, int max_value=0, str format='%d')¶

Display int drag widget with 4 values.

Example:

values = 88, 42, 69, 0

imgui.begin("Example: drag int")
changed, values = imgui.drag_int4(
    "drag ints", *values
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (int) – drag values. change_speed (float) – how fast values change on drag. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `drag_int()`.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current drag values.

Wraps API:

bool DragInt4(
    const char* label,
    int v[4],
    float v_speed = 1.0f,
    int v_min = 0.0f,
    int v_max = 0.0f,
    const char* format = "%d",
)

imgui.core.dummy(width, height)¶

Add dummy element of given size.

Example:

imgui.begin("Example: dummy elements")

imgui.text("Some text with bullets:")
imgui.bullet_text("Bullet A")
imgui.bullet_text("Bullet B")

imgui.dummy(0, 50)
imgui.bullet_text("Text after dummy")

imgui.end()

Outputs:

Wraps API:

void Dummy(const ImVec2& size)

imgui.core.end()¶

End a window.

This finishes appending to current window, and pops it off the window stack. See: begin().

Wraps API:

void End()

imgui.core.end_child()¶

End scrolling region.

Wraps API:

void EndChild()

imgui.core.end_drag_drop_source()¶

End the drag and drop source. Only call after begin_drag_drop_source() returns True.

Note: this is a beta API.

For a complete example see begin_drag_drop_source().

Wraps API:

void EndDragDropSource()

imgui.core.end_drag_drop_target()¶

End the drag and drop source. Only call after begin_drag_drop_target() returns True.

Note: this is a beta API.

For a complete example see begin_drag_drop_source().

Wraps API:

void EndDragDropTarget()

imgui.core.end_frame()¶

End a frame.

ends the ImGui frame. automatically called by Render(), so most likely don’t need to ever call that yourself directly. If you don’t need to render you may call end_frame() but you’ll have wasted CPU already. If you don’t need to render, better to not create any imgui windows instead!

Wraps API:

void EndFrame()

imgui.core.end_group()¶

End group (see: begin_group).

Wraps API:

void EndGroup()

imgui.core.end_main_menu_bar()¶

Close main menu bar context.

Only call this function if the end_main_menu_bar() returns True.

For practical example how to use this function see documentation of begin_main_menu_bar().

Wraps API:

bool EndMainMenuBar()

imgui.core.end_menu()¶

Close menu context.

Only call this function if the begin_menu() returns True.

For practical example how to use this function, please see documentation of begin_main_menu_bar() or begin_menu_bar().

Wraps API:

void EndMenu()

imgui.core.end_menu_bar()¶

Close menu bar context.

Only call this function if the begin_menu_bar() returns true.

For practical example how to use this function see documentation of begin_menu_bar().

Wraps API:

void EndMenuBar()

imgui.core.end_popup()¶

End a popup window.

Should be called after each XYZPopupXYZ function.

For practical example how to use this function, please see documentation of open_popup().

Wraps API:

void EndPopup()

imgui.core.end_tooltip()¶

End tooltip window.

See begin_tooltip() for full usage example.

Wraps API:

void EndTooltip()

imgui.core.get_color_u32(ImU32 col)¶

retrieve given style color with style alpha applied and optional extra alpha multiplier

Returns:	ImU32 – 32-bit RGBA color

Wraps API:

ImU32 GetColorU32(ImU32 col)

imgui.core.get_color_u32_idx(ImGuiCol idx, float alpha_mul=1.0)¶

retrieve given style color with style alpha applied and optional extra alpha multiplier

Returns:	ImU32 – 32-bit RGBA color

Wraps API:

ImU32 GetColorU32(ImGuiCol idx, alpha_mul)

imgui.core.get_color_u32_rgba(float r, float g, float b, float a)¶

retrieve given color with style alpha applied

Returns:	ImU32 – 32-bit RGBA color

Wraps API:

ImU32 GetColorU32(const ImVec4& col)

imgui.core.get_column_index()¶

Returns the current column index.

For a complete example see columns().

Returns:	int – the current column index.

Wraps API:

int GetColumnIndex()

imgui.core.get_column_offset(int column_index=-1)¶

Returns position of column line (in pixels, from the left side of the contents region). Pass -1 to use current column, otherwise 0 to get_columns_count(). Column 0 is usually 0.0f and not resizable unless you call this method.

For a complete example see columns().

Parameters:	column_index (int) – index of the column to get the offset for.
Returns:	float – the position in pixels from the left side.

Wraps API:

float GetColumnOffset(int column_index = -1)

imgui.core.get_column_width(int column_index=-1)¶

Return the column width.

For a complete example see columns().

Parameters:	column_index (int) – index of the column to get the width for.

Wraps API:

void GetColumnWidth(int column_index = -1)

imgui.core.get_columns_count()¶

Get count of the columns in the current table.

For a complete example see columns().

Returns:	int – columns count.

Wraps API:

int GetColumnsCount()

imgui.core.get_content_region_available()¶

Get available content region.

It is shortcut for:

Returns:	Vec2 – available content region size two-tuple `(width, height)`

Wraps API:

ImVec2 GetContentRegionMax()

imgui.core.get_content_region_available_width()¶

Get available content region width.

Returns:	float – available content region width.

Wraps API:

float GetContentRegionAvailWidth()

imgui.core.get_content_region_max()¶

Get current content boundaries in window coordinates.

Typically window boundaries include scrolling, or current column boundaries.

Returns:	Vec2 – content boundaries two-tuple `(width, height)`

Wraps API:

ImVec2 GetContentRegionMax()

imgui.core.get_current_context()¶

GetCurrentContext

Wraps API:

ImGuiContext* GetCurrentContext();

imgui.core.get_cursor_pos()¶

Get the cursor position.

Wraps API:

ImVec2 GetCursorPos()

imgui.core.get_cursor_position()¶

get_cursor_pos() Get the cursor position.

Wraps API:

ImVec2 GetCursorPos()

imgui.core.get_cursor_screen_pos()¶

Get the cursor position in absolute screen coordinates [0..io.DisplaySize] (useful to work with ImDrawList API)

Wraps API:

ImVec2 GetCursorScreenPos()

imgui.core.get_cursor_screen_position()¶

get_cursor_screen_pos() Get the cursor position in absolute screen coordinates [0..io.DisplaySize] (useful to work with ImDrawList API)

Wraps API:

ImVec2 GetCursorScreenPos()

imgui.core.get_cursor_start_pos()¶

Get the initial cursor position.

Wraps API:

ImVec2 GetCursorStartPos()

imgui.core.get_cursor_start_position()¶

get_cursor_start_pos() Get the initial cursor position.

Wraps API:

ImVec2 GetCursorStartPos()

imgui.core.get_draw_data()¶

Get draw data.

valid after render() and until the next call to new_frame(). This is what you have to render.

Returns:	_DrawData – draw data for all draw calls required to display gui

Wraps API:

ImDrawData* GetDrawData()

imgui.core.get_font_size()¶

get current font size (= height in pixels) of current font with current scale applied

Returns:	float – current font size (height in pixels)

Wraps API:

float GetFontSize()

imgui.core.get_frame_height()¶

~ FontSize + style.FramePadding.y * 2

Wraps API:

float GetFrameHeight()

float GetFrameHeightWithSpacing() except +

imgui.core.get_frame_height_with_spacing()¶

~ FontSize + style.FramePadding.y * 2 + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of framed widgets)

Wraps API:

float GetFrameHeightWithSpacing()

imgui.core.get_io()¶

imgui.core.get_item_rect_max()¶

Get bounding rect of the last item in screen space.

Returns:	Vec2 – item maximum boundaries two-tuple `(width, height)`

Wraps API:

ImVec2 GetItemRectMax()

imgui.core.get_item_rect_min()¶

Get bounding rect of the last item in screen space.

Returns:	Vec2 – item minimum boundaries two-tuple `(width, height)`

Wraps API:

ImVec2 GetItemRectMin()

imgui.core.get_item_rect_size()¶

Get bounding rect of the last item in screen space.

Returns:	Vec2 – item boundaries two-tuple `(width, height)`

Wraps API:

ImVec2 GetItemRectSize()

imgui.core.get_mouse_cursor()¶

Return the mouse cursor id.

Wraps API:

ImGuiMouseCursor GetMouseCursor()

imgui.core.get_mouse_drag_delta(int button=0, float lock_threshold=-1.0)¶

Dragging amount since clicking.

Parameters:	button (int) – mouse button index. lock_threshold (float) – if less than -1.0 uses io.MouseDraggingThreshold.
Returns:	Vec2 – mouse position two-tuple `(x, y)`

Wraps API:

ImVec2 GetMouseDragDelta(int button = 0, float lock_threshold = -1.0f)

imgui.core.get_mouse_pos()¶

Current mouse position.

Returns:	Vec2 – mouse position two-tuple `(x, y)`

Wraps API:

ImVec2 GetMousePos()

imgui.core.get_mouse_position()¶

get_mouse_pos() Current mouse position.

Returns:

Vec2: mouse position two-tuple (x, y)

Wraps API:
ImVec2 GetMousePos()

imgui.core.get_overlay_draw_list()¶

Get a special draw list that will be drawn last (over all windows).

Useful for drawing overlays.

Returns:	ImDrawList*

Wraps API:

ImDrawList* GetWindowDrawList()

imgui.core.get_scroll_max_x()¶

get maximum scrolling amount ~~ ContentSize.X - WindowSize.X

Returns:	float – the maximum scroll X amount

Wraps API:

int GetScrollMaxX()

imgui.core.get_scroll_max_y()¶

get maximum scrolling amount ~~ ContentSize.X - WindowSize.X

Returns:	float – the maximum scroll Y amount

Wraps API:

int GetScrollMaxY()

imgui.core.get_scroll_x()¶

get scrolling amount [0..GetScrollMaxX()]

Returns:	float – the current scroll X value

Wraps API:

int GetScrollX()

imgui.core.get_scroll_y()¶

get scrolling amount [0..GetScrollMaxY()]

Returns:	float – the current scroll Y value

Wraps API:

int GetScrollY()

imgui.core.get_style()¶

imgui.core.get_style_color_name(int index)¶

Get the style color name for a given ImGuiCol index.

Wraps API:

const char* GetStyleColorName(ImGuiCol idx)

imgui.core.get_text_line_height()¶

Get text line height.

Returns:	int – text line height.

Wraps API:

void GetTextLineHeight()

imgui.core.get_text_line_height_with_spacing()¶

Get text line height, with spacing.

Returns:	int – text line height, with spacing.

Wraps API:

void GetTextLineHeightWithSpacing()

imgui.core.get_time()¶

Seconds since program start.

Returns:	float – the time (seconds since program start)

Wraps API:

float GetTime()

imgui.core.get_version()¶

Get the version of Dear ImGui.

Wraps API:

void GetVersion()

imgui.core.get_window_content_region_max()¶

Get maximal current window content boundaries in window coordinates.

It translates roughly to: (0, 0) + Size - Scroll

Returns:	Vec2 – content boundaries two-tuple `(width, height)`

Wraps API:

ImVec2 GetWindowContentRegionMin()

imgui.core.get_window_content_region_min()¶

Get minimal current window content boundaries in window coordinates.

It translates roughly to: (0, 0) - Scroll

Returns:	Vec2 – content boundaries two-tuple `(width, height)`

Wraps API:

ImVec2 GetWindowContentRegionMin()

imgui.core.get_window_content_region_width()¶

Get available current window content region width.

Returns:	float – available content region width.

Wraps API:

float GetWindowContentRegionWidth()

imgui.core.get_window_draw_list()¶

Get the draw list associated with the window, to append your own drawing primitives

It may be useful if you want to do your own drawing via the _DrawList API.

Example:

pos_x = 10
pos_y = 10
sz = 20

draw_list = imgui.get_window_draw_list()

for i in range(0, imgui.COLOR_COUNT):
    name = imgui.get_style_color_name(i);
    draw_list.add_rect_filled(pos_x, pos_y, pos_x+sz, pos_y+sz, imgui.get_color_u32_idx(i));
    imgui.dummy(sz, sz);
    imgui.same_line();

rgba_color = imgui.get_color_u32_rgba(1, 1, 0, 1);
draw_list.add_rect_filled(pos_x, pos_y, pos_x+sz, pos_y+sz, rgba_color);

Outputs:

_images/imgui.core.get_window_draw_list_0.png

Returns:	ImDrawList*

Wraps API:

ImDrawList* GetWindowDrawList()

imgui.core.get_window_height()¶

Get current window height.

Returns:	float – height of current window.

Wraps API:

float GetWindowHeight()

imgui.core.get_window_position()¶

Get current window position.

It may be useful if you want to do your own drawing via the DrawList api.

Returns:	Vec2 – two-tuple of window coordinates in screen space.

Wraps API:

ImVec2 GetWindowPos()

imgui.core.get_window_size()¶

Get current window size.

Returns:	Vec2 – two-tuple of window dimensions.

Wraps API:

ImVec2 GetWindowSize()

imgui.core.get_window_width()¶

Get current window width.

Returns:	float – width of current window.

Wraps API:

float GetWindowWidth()

imgui.core.image(texture_id, float width, float height, tuple uv0=(0, 0), tuple uv1=(1, 1), tuple tint_color=(1, 1, 1, 1), tuple border_color=(0, 0, 0, 0))¶

Display image.

Example:

texture_id = imgui.get_io().fonts.texture_id

imgui.begin("Example: image display")
imgui.image(texture_id, 512, 64, border_color=(1, 0, 0, 1))
imgui.end()

Outputs:

Parameters:

texture_id (object) – user data defining texture id. Argument type is implementation dependent. For OpenGL it is usually an integer.
size (Vec2) – image display size two-tuple.
uv0 (Vec2) – UV coordinates for 1st corner (lower-left for OpenGL). Defaults to (0, 0).
uv1 (Vec2) – UV coordinates for 2nd corner (upper-right for OpenGL). Defaults to (1, 1).
tint_color (Vec4) – Image tint color. Defaults to white.
border_color (Vec4) – Image border color. Defaults to transparent.

Wraps API:

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

imgui.core.image_button(texture_id, float width, float height, tuple uv0=(0, 0), tuple uv1=(1, 1), tuple tint_color=(1, 1, 1, 1), tuple border_color=(0, 0, 0, 0), int frame_padding=-1)¶

Display image.

Todo

add example with some preconfigured image

Parameters:

texture_id (object) – user data defining texture id. Argument type is implementation dependent. For OpenGL it is usually an integer.
size (Vec2) – image display size two-tuple.
uv0 (Vec2) – UV coordinates for 1st corner (lower-left for OpenGL). Defaults to (0, 0).
uv1 (Vec2) – UV coordinates for 2nd corner (upper-right for OpenGL). Defaults to (1, 1).
tint_color (Vec4) – Image tint color. Defaults to white.
border_color (Vec4) – Image border color. Defaults to transparent.
frame_padding (int) – Frame padding (0: no padding, <0 default padding).

Returns:

bool – True if clicked.

Wraps API:

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

imgui.core.indent(float width=0.0)¶

Move content to right by indent width.

Example:

imgui.begin("Example: item indenting")

imgui.text("Some text with bullets:")

imgui.bullet_text("Bullet A")
imgui.indent()
imgui.bullet_text("Bullet B (first indented)")
imgui.bullet_text("Bullet C (indent continues)")
imgui.unindent()
imgui.bullet_text("Bullet D (indent cleared)")

imgui.end()

Outputs:

Parameters:	width (float) – fixed width of indent. If less or equal 0 it defaults to global indent spacing or value set using style value stack (see `push_style_var`).

Wraps API:

void Indent(float indent_w = 0.0f)

imgui.core.input_double(str label, int value, int step=1, int step_fast=100, str format='%.6f', ImGuiInputTextFlags flags=0)¶

Display integer input widget.

Example:

double_val = 3.14159265358979323846
imgui.begin("Example: integer input")
changed, double_val = imgui.input_double('Type multiplier:', double_val)
imgui.text('You wrote: %i' % double_val)
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (int) – textbox value step (int) – incremental step step_fast (int) – fast incremental step format = (str) – format string flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current textbox content.

Wraps API:

bool InputInt(
    const char* label,
    int* v,
    int step = 1,
    int step_fast = 100,
    _bytes(format),
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_float(str label, float value, float step=0.0, float step_fast=0.0, str format='%.3f', ImGuiInputTextFlags flags=0)¶

Display float input widget.

Example:

float_val = 0.4
imgui.begin("Example: float input")
changed, float_val = imgui.input_float('Type coefficient:', float_val)
imgui.text('You wrote: %f' % float_val)
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (float) – textbox value step (float) – incremental step step_fast (float) – fast incremental step format = (str) – format string flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current textbox content.

Wraps API:

bool InputFloat(
    const char* label,
    float* v,
    float step = 0.0f,
    float step_fast = 0.0f,
    const char* format = "%.3f",
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_float2(str label, float value0, float value1, str format='%.3f', ImGuiInputTextFlags flags=0)¶

Display two-float input widget.

Example:

values = 0.4, 3.2
imgui.begin("Example: two float inputs")
changed, values = imgui.input_float2('Type here:', *values)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (float) – input values. format = (str) – format string flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of textbox state change and the tuple of current values.

Wraps API:

bool InputFloat2(
    const char* label,
    float v[2],
    const char* format = "%.3f",
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_float3(str label, float value0, float value1, float value2, str format='%.3f', ImGuiInputTextFlags flags=0)¶

Display three-float input widget.

Example:

values = 0.4, 3.2, 29.3
imgui.begin("Example: three float inputs")
changed, values = imgui.input_float3('Type here:', *values)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2 (float) – input values. format = (str) – format string flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of textbox state change and the tuple of current values.

Wraps API:

bool InputFloat3(
    const char* label,
    float v[3],
    const char* format = "%.3f",
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_float4(str label, float value0, float value1, float value2, float value3, str format='%.3f', ImGuiInputTextFlags flags=0)¶

Display four-float input widget.

Example:

values = 0.4, 3.2, 29.3, 12.9
imgui.begin("Example: four float inputs")
changed, values = imgui.input_float4('Type here:', *values)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2, value3 (float) – input values. format = (str) – format string flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of textbox state change and the tuple of current values.

Wraps API:

bool InputFloat4(
    const char* label,
    float v[4],
    const char* format = "%.3f",
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_int(str label, int value, int step=1, int step_fast=100, ImGuiInputTextFlags flags=0)¶

Display integer input widget.

Example:

int_val = 3
imgui.begin("Example: integer input")
changed, int_val = imgui.input_int('Type multiplier:', int_val)
imgui.text('You wrote: %i' % int_val)
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (int) – textbox value step (int) – incremental step step_fast (int) – fast incremental step flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current textbox content.

Wraps API:

bool InputInt(
    const char* label,
    int* v,
    int step = 1,
    int step_fast = 100,
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_int2(str label, int value0, int value1, ImGuiInputTextFlags flags=0)¶

Display two-integer input widget.

Example:

values = 4, 12
imgui.begin("Example: two int inputs")
changed, values = imgui.input_int2('Type here:', *values)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (int) – textbox values flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current textbox content.

Wraps API:

bool InputInt2(
    const char* label,
    int v[2],
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_int3(str label, int value0, int value1, int value2, ImGuiInputTextFlags flags=0)¶

Display three-integer input widget.

Example:

values = 4, 12, 28
imgui.begin("Example: three int inputs")
changed, values = imgui.input_int3('Type here:', *values)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2 (int) – textbox values flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current textbox content.

Wraps API:

bool InputInt3(
    const char* label,
    int v[3],
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_int4(str label, int value0, int value1, int value2, int value3, ImGuiInputTextFlags flags=0)¶

Display four-integer input widget.

Example:

values = 4, 12, 28, 73
imgui.begin("Example: four int inputs")
changed, values = imgui.input_int4('Type here:', *values)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2, value3 (int) – textbox values flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current textbox content.

Wraps API:

bool InputInt4(
    const char* label,
    int v[4],
    ImGuiInputTextFlags extra_flags = 0
)

imgui.core.input_text(str label, str value, int buffer_length, ImGuiInputTextFlags flags=0)¶

Display text input widget.

buffer_length is the maximum allowed length of the content.

Example:

text_val = 'Please, type the coefficient here.'
imgui.begin("Example: text input")
changed, text_val = imgui.input_text(
    'Amount:',
    text_val,
    256
)
imgui.text('You wrote:')
imgui.same_line()
imgui.text(text_val)
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (str) – textbox value buffer_length (int) – length of the content buffer flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current text contents.

Wraps API:

bool InputText(
    const char* label,
    char* buf,
    size_t buf_size,
    ImGuiInputTextFlags flags = 0,
    ImGuiInputTextCallback callback = NULL,
    void* user_data = NULL
)

imgui.core.input_text_multiline(str label, str value, int buffer_length, float width=0, float height=0, ImGuiInputTextFlags flags=0)¶

Display multiline text input widget.

buffer_length is the maximum allowed length of the content.

Example:

text_val = 'Type the your message here.'
imgui.begin("Example: text input")
changed, text_val = imgui.input_text_multiline(
    'Message:',
    text_val,
    2056
)
imgui.text('You wrote:')
imgui.same_line()
imgui.text(text_val)
imgui.end()

Outputs:

_images/imgui.core.input_text_multiline_0.png

Parameters:	label (str) – widget label. value (str) – textbox value buffer_length (int) – length of the content buffer width (float) – width of the textbox height (float) – height of the textbox flags – InputText flags. See: list of available flags.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of textbox state change and the current text contents.

Wraps API:

bool InputTextMultiline(
    const char* label,
    char* buf,
    size_t buf_size,
    const ImVec2& size = ImVec2(0,0),
    ImGuiInputTextFlags flags = 0,
    ImGuiInputTextCallback callback = NULL,
    void* user_data = NULL
)

imgui.core.invisible_button(str identifier, width, height)¶

Create invisible button.

Example:

imgui.begin("Example: invisible button :)")
imgui.invisible_button("Button 1", 200, 200)
imgui.small_button("Button 2")
imgui.end()

Outputs:

Parameters:	identifier (str) – Button identifier. Like label on `button()` but it is not displayed. width (float) – button width. height (float) – button height.
Returns:	bool – True if button is clicked.

Wraps API:

bool InvisibleButton(const char* str_id, const ImVec2& size)

imgui.core.is_any_item_active()¶

Was any of the items active.

Returns:	bool – True if any item is active, otherwise False.

Wraps API:

bool IsAnyItemActive()

imgui.core.is_any_item_focused()¶

Is any of the items focused.

Returns:	bool – True if any item is focused, otherwise False.

Wraps API:

bool IsAnyItemFocused()

imgui.core.is_any_item_hovered()¶

Was any of the items hovered.

Returns:	bool – True if any item is hovered, otherwise False.

Wraps API:

bool IsAnyItemHovered()

imgui.core.is_item_active()¶

Was the last item active? For ex. button being held or text field being edited. Items that don’t interact will always return false.

Returns:	bool – True if item is active, otherwise False.

Wraps API:

bool IsItemActive()

imgui.core.is_item_clicked(int mouse_button=0)¶

Was the last item clicked? For ex. button or node that was just being clicked on.

Returns:	bool – True if item is clicked, otherwise False.

Wraps API:

bool IsItemClicked(int mouse_button = 0)

imgui.core.is_item_focused()¶

Check if the last item is focused

Returns:	bool – True if item is focused, otherwise False.

Wraps API:

bool IsItemFocused()

imgui.core.is_item_hovered(ImGuiHoveredFlags flags=0)¶

Check if the last item is hovered by mouse.

Returns:	bool – True if item is hovered by mouse, otherwise False.

Wraps API:

bool IsItemHovered(ImGuiHoveredFlags flags = 0)

imgui.core.is_item_visible()¶

Was the last item visible? Aka not out of sight due to clipping/scrolling.

Returns:	bool – True if item is visible, otherwise False.

Wraps API:

bool IsItemVisible()

imgui.core.is_mouse_clicked(int button=0, bool repeat=False)¶

Returns if the mouse was clicked this frame.

Parameters:	button (int) – mouse button index. repeat (float)
Returns:	bool – if the mouse was clicked this frame.

Wraps API:

bool IsMouseClicked(int button, bool repeat = false)

imgui.core.is_mouse_double_clicked(int button=0)¶

Return True if mouse was double-clicked.

Note: A double-click returns false in IsMouseClicked().

Parameters:	button (int) – mouse button index.
Returns:	bool – if mouse is double clicked.

Wraps API:

bool IsMouseDoubleClicked(int button);

imgui.core.is_mouse_down(int button=0)¶

Returns if the mouse is down.

Parameters:	button (int) – mouse button index.
Returns:	bool – if the mouse is down.

Wraps API:

bool IsMouseDown(int button)

imgui.core.is_mouse_dragging(int button=0, float lock_threshold=-1.0)¶

Returns if mouse is dragging.

Parameters:	button (int) – mouse button index. lock_threshold (float) – if less than -1.0 uses io.MouseDraggingThreshold.
Returns:	bool – if mouse is dragging.

Wraps API:

bool IsMouseDragging(int button = 0, float lock_threshold = -1.0f)

imgui.core.is_mouse_hovering_rect(float r_min_x, float r_min_y, float r_max_x, float r_max_y, bool clip=True)¶

Test if mouse is hovering rectangle with given coordinates.

Parameters:	r_min_x, r_min_y (float) – x,y coordinate of the upper-left corner r_max_x, r_max_y (float) – x,y coordinate of the lower-right corner
Returns:	bool – True if mouse is hovering the rectangle.

Wraps API:

bool IsMouseHoveringRect(
    const ImVec2& r_min,
    const ImVec2& r_max,
    bool clip = true
)

imgui.core.is_mouse_released(int button=0)¶

Returns if the mouse was released this frame.

Parameters:	button (int) – mouse button index.
Returns:	bool – if the mouse was released this frame.

Wraps API:

bool IsMouseReleased(int button)

imgui.core.is_rect_visible(float size_width, float size_height)¶

Test if a rectangle of the given size, starting from the cursor position is visible (not clipped).

Parameters:	size_width (float) – width of the rect size_height (float) – height of the rect
Returns:	bool – True if rect is visible, otherwise False.

Wraps API:

bool IsRectVisible(const ImVec2& size)

imgui.core.is_window_appearing()¶

Check if current window is appearing.

Returns:	bool – True if window is appearing

imgui.core.is_window_collapsed()¶

Check if current window is collapsed.

Returns:	bool – True if window is collapsed

imgui.core.is_window_focused(ImGuiHoveredFlags flags=0)¶

Is current window focused.

Returns:	bool – True if current window is on focus, otherwise False.

Wraps API:

bool IsWindowFocused(ImGuiFocusedFlags flags = 0)

imgui.core.is_window_hovered(ImGuiHoveredFlags flags=0)¶

Is current window hovered and hoverable (not blocked by a popup). Differentiate child windows from each others.

Returns:	bool – True if current window is hovered, otherwise False.

Wraps API:

bool IsWindowHovered(ImGuiFocusedFlags flags = 0)

imgui.core.label_text(str label, str text)¶

Display text+label aligned the same way as value+label widgets.

Example:

imgui.begin("Example: text with label")
imgui.label_text("my label", "my text")
imgui.end()

Outputs:

Parameters:	label (str) – label to display. text (str) – text to display.

Wraps API:

void LabelText(const char* label, const char* fmt, ...)

imgui.core.listbox(str label, int current, list items, int height_in_items=-1)¶

Show listbox widget.

Example:

current = 2
imgui.begin("Example: listbox widget")

clicked, current = imgui.listbox(
    "List", current, ["first", "second", "third"]
)

imgui.end()

Outputs:

Parameters:	label (str) – The label. current (int) – index of selected item. items (list) – list of string labels for items. height_in_items (int) – height of dropdown in items. Defaults to -1 (autosized).
Returns:	tuple – a `(changed, current)` tuple indicating change of selection and current index of selected item.

Wraps API:

bool ListBox(
    const char* label,
    int* current_item,
    const char* items[],
    int items_count,
    int height_in_items = -1
)

imgui.core.listbox_footer()¶

Closing the listbox, previously opened by listbox_header().

See listbox_header() for usage example.

Wraps API:

void ListBoxFooter()

imgui.core.listbox_header(str label, width=0, height=0)¶

For use if you want to reimplement listbox() with custom data or interactions. You need to call listbox_footer() at the end.

Example:

imgui.begin("Example: custom listbox")

imgui.listbox_header("List", 200, 100)

imgui.selectable("Selected", True)
imgui.selectable("Not Selected", False)

imgui.listbox_footer()

imgui.end()

Outputs:

Parameters:	label (str) – The label. width (float) – button width. height (float) – button height.
Returns:	opened (bool) – If the item is opened or closed.

Wraps API:

bool ListBoxHeader(
    const char* label,
    const ImVec2& size = ImVec2(0,0)
)

imgui.core.menu_item(str label, str shortcut=None, bool selected=False, enabled=True)¶

Create a menu item.

Item shortcuts are displayed for convenience but not processed by ImGui at the moment. Using selected arguement it is possible to show and trigger a check mark next to the menu item label.

For practical example how to use this function, please see documentation of begin_main_menu_bar() or begin_menu_bar().

Parameters:	label (str) – label of the menu item. shortcut (str) – shortcut text of the menu item. selected (bool) – define if menu item is selected. enabled (bool) – define if menu item is enabled or disabled.
Returns:	tuple – a `(clicked, state)` two-tuple indicating if item was clicked by the user and the current state of item (visibility of the check mark).

Wraps API:

MenuItem(
    const char* label,
    const char* shortcut,
    bool* p_selected,
    bool enabled = true
)

imgui.core.new_frame()¶

Start a new frame.

After calling this you can submit any command from this point until next new_frame() or render().

Wraps API:

void NewFrame()

imgui.core.new_line()¶

Undo same_line() call.

Wraps API:

void NewLine()

imgui.core.next_column()¶

Move to the next column drawing.

For a complete example see columns().

Wraps API:

void NextColumn()

imgui.core.open_popup(str label)¶

Open a popup window.

Marks a popup window as open. Popups are closed when user click outside, or activate a pressable item, or close_current_popup() is called within a begin_popup()/end_popup() block. Popup identifiers are relative to the current ID-stack (so open_popup() and begin_popup() needs to be at the same level).

Example:

imgui.begin("Example: simple popup")
if imgui.button('Toggle..'):
    imgui.open_popup("toggle")
if imgui.begin_popup("toggle"):
    if imgui.begin_menu('Sub-menu'):
        _, _ = imgui.menu_item('Click me')
        imgui.end_menu()
    imgui.end_popup()
imgui.end()

Outputs:

Parameters:	label (str) – label of the modal window.

Wraps API:

void OpenPopup(
    const char* str_id
)

imgui.core.plot_histogram(str label, __Pyx_memviewslice values, int values_count=-1, int values_offset=0, str overlay_text=None, float scale_min=FLT_MAX, float scale_max=FLT_MAX, graph_size=(0, 0), int stride=<???>)¶

Plot a histogram of float values.

Parameters:

label (str) – A plot label that will be displayed on the plot’s right side. If you want the label to be invisible, add "##" before the label’s text: "my_label" -> "##my_label"
values (array of floats) – the y-values. It must be a type that supports Cython’s Memoryviews, (See: http://docs.cython.org/en/latest/src/userguide/memoryviews.html) for example a numpy array.
overlay_text (str or None, optional) – Overlay text.
scale_min (float, optional) – y-value at the bottom of the plot.
scale_max (float, optional) – y-value at the top of the plot.
graph_size (tuple of two floats, optional) – plot size in pixels. Note: In ImGui 1.49, (-1,-1) will NOT auto-size the plot. To do that, use get_content_region_available() and pass in the right size.

Note: These low-level parameters are exposed if needed for performance:

values_offset (int): Index of first element to display
values_count (int): Number of values to display. -1 will use the

entire array.
stride (int): Number of bytes to move to read next element.

Example:

from array import array
from random import random

# NOTE: this example will not work under py27 due do incompatible
# implementation of array and memoryview().
histogram_values = array('f', [random() for _ in range(20)])

imgui.begin("Plot example")
imgui.plot_histogram("histogram(random())", histogram_values)
imgui.end()

Outputs:

Wraps API:

void PlotHistogram(
    const char* label, const float* values, int values_count,
    # note: optional
    int values_offset,
    const char* overlay_text,
    float scale_min,
    float scale_max,
    ImVec2 graph_size,
    int stride
)

imgui.core.plot_lines(str label, __Pyx_memviewslice values, int values_count=-1, int values_offset=0, str overlay_text=None, float scale_min=FLT_MAX, float scale_max=FLT_MAX, graph_size=(0, 0), int stride=<???>)¶

Plot a 1D array of float values.

Parameters:

label (str) – A plot label that will be displayed on the plot’s right side. If you want the label to be invisible, add "##" before the label’s text: "my_label" -> "##my_label"
values (array of floats) – the y-values. It must be a type that supports Cython’s Memoryviews, (See: http://docs.cython.org/en/latest/src/userguide/memoryviews.html) for example a numpy array.
overlay_text (str or None, optional) – Overlay text.
scale_min (float, optional) – y-value at the bottom of the plot.
scale_max (float, optional) – y-value at the top of the plot.
graph_size (tuple of two floats, optional) – plot size in pixels. Note: In ImGui 1.49, (-1,-1) will NOT auto-size the plot. To do that, use get_content_region_available() and pass in the right size.

Note: These low-level parameters are exposed if needed for performance:

values_offset (int): Index of first element to display
values_count (int): Number of values to display. -1 will use the

entire array.
stride (int): Number of bytes to move to read next element.

Example:

from array import array
from math import sin
# NOTE: this example will not work under py27 due do incompatible
# implementation of array and memoryview().
plot_values = array('f', [sin(x * 0.1) for x in range(100)])

imgui.begin("Plot example")
imgui.plot_lines("Sin(t)", plot_values)
imgui.end()

Outputs:

Wraps API:

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

imgui.core.pop_font()¶

Pop font on a stack.

For example usage see push_font().

Parameters:	font (_Font) – font object retrieved from `add_font_from_file_ttf`.

Wraps API:

void PopFont()

imgui.core.pop_id()¶

Pop from the ID stack

wraps::: PopID()

imgui.core.pop_item_width()¶

Reset width back to the default width.

Note: This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers. See: push_item_width().

Wraps API:

void PopItemWidth()

imgui.core.pop_style_color(unsigned int count=1)¶

Pop style color from stack.

Note: This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers. See: push_style_color().

Parameters:	count (int) – number of variables to pop from style color stack.

Wraps API:

void PopStyleColor(int count = 1)

imgui.core.pop_style_var(unsigned int count=1)¶

Pop style variables from stack.

Note: This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers. See: push_style_var().

Parameters:	count (int) – number of variables to pop from style variable stack.

Wraps API:

void PopStyleVar(int count = 1)

imgui.core.pop_text_wrap_pos()¶

Pop the text wrapping position from the stack.

Note: This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers. See: push_text_wrap_pos().

Wraps API:

void PopTextWrapPos()

imgui.core.pop_text_wrap_position()¶

pop_text_wrap_pos() Pop the text wrapping position from the stack.

Note: This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers. See: push_text_wrap_pos().

Wraps API:
void PopTextWrapPos()

imgui.core.push_font(_Font font)¶

Push font on a stack.

Example:

io = imgui.get_io()

new_font = io.fonts.add_font_from_file_ttf(
    "DroidSans.ttf", 20,
)
impl.refresh_font_texture()

# later in frame code

imgui.begin("Default Window")

imgui.text("Text displayed using default font")

imgui.push_font(new_font)
imgui.text("Text displayed using custom font")
imgui.pop_font()

imgui.end()

Outputs:

Note: Pushed fonts should be poped with pop_font() within the same frame. In order to avoid manual push/pop functions you can use the font() context manager.

Parameters:	font (_Font) – font object retrieved from `add_font_from_file_ttf`.

Wraps API:

void PushFont(ImFont*)

imgui.core.push_id(str str_id)¶

Push an ID into the ID stack

Parameters:

id (str) – ID to push

wraps::: PushID(const char* str_id)

imgui.core.push_item_width(float item_width)¶

Push item width in the stack.

Note: sizing of child region allows for three modes:

0.0 - default to ~2/3 of windows width
>0.0 - width in pixels
<0.0 - align xx pixels to the right of window (so -1.0f always align width to the right side)

Note: width pushed on stack need to be poped using pop_item_width() or it will be applied to all subsequent children components.

Example:

imgui.begin("Example: item width")

# custom width
imgui.push_item_width(imgui.get_window_width() * 0.33)
imgui.text('Lorem Ipsum ...')
imgui.slider_float('float slider', 10.2, 0.0, 20.0, '%.2f', 1.0)
imgui.pop_item_width()

# default width
imgui.text('Lorem Ipsum ...')
imgui.slider_float('float slider', 10.2, 0.0, 20.0, '%.2f', 1.0)

imgui.end()

Outputs:

_images/imgui.core.push_item_width_0.png

Parameters:	item_width (float) – width of the component

Wraps API:

void PushItemWidth(float item_width)

imgui.core.push_style_color(ImGuiCol variable, float r, float g, float b, float a=1.)¶

Push style color on stack.

Note: variables pushed on stack need to be popped using pop_style_color() until the end of current frame. This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers.

Example:

imgui.begin("Example: Color variables")
imgui.push_style_color(imgui.COLOR_TEXT, 1.0, 0.0, 0.0)
imgui.text("Colored text")
imgui.pop_style_color(1)
imgui.end()

Outputs:

_images/imgui.core.push_style_color_0.png

Parameters:	variable – imgui style color constant r (float) – red color intensity. g (float) – green color intensity. b (float) – blue color instensity. a (float) – alpha intensity.

Wraps API:

PushStyleColor(ImGuiCol idx, const ImVec4& col)

imgui.core.push_style_var(ImGuiStyleVar variable, value)¶

Push style variable on stack.

This function accepts both float and float two-tuples as value argument. ImGui core implementation will verify if passed value has type compatibile with given style variable. If not, it will raise exception.

Note: variables pushed on stack need to be poped using pop_style_var() until the end of current frame. This implementation guards you from segfaults caused by redundant stack pops (raises exception if this happens) but generally it is safer and easier to use styled() or istyled() context managers.

Example:

imgui.begin("Example: style variables")
imgui.push_style_var(imgui.STYLE_ALPHA, 0.2)
imgui.text("Alpha text")
imgui.pop_style_var(1)
imgui.end()

Outputs:

Parameters:	variable – imgui style variable constant value (float or two-tuple) – style variable value

Wraps API:

PushStyleVar(ImGuiStyleVar idx, float val)

imgui.core.push_text_wrap_pos(float wrap_pos_x=0.0)¶

Word-wrapping function for text*() commands.

Note: wrapping position allows these modes: * 0.0 - wrap to end of window (or column) * >0.0 - wrap at ‘wrap_pos_x’ position in window local space * <0.0 - no wrapping

Parameters:	wrap_pos_x (float) – calculated item width.

Wraps API:

float PushTextWrapPos(float wrap_pos_x = 0.0f)

imgui.core.push_text_wrap_position()¶

push_text_wrap_pos(float wrap_pos_x=0.0) Word-wrapping function for text*() commands.

Note: wrapping position allows these modes: * 0.0 - wrap to end of window (or column) * >0.0 - wrap at ‘wrap_pos_x’ position in window local space * <0.0 - no wrapping

Args:

wrap_pos_x (float): calculated item width.

Wraps API:
float PushTextWrapPos(float wrap_pos_x = 0.0f)

imgui.core.radio_button(str label, bool active)¶

Display radio button widget

Example:

# note: the variable that contains the state of the radio_button, should be initialized
#       outside of the main interaction loop
radio_active = True

imgui.begin("Example: radio buttons")

if imgui.radio_button("Radio button", radio_active):
    radio_active = not radio_active

imgui.end()

Outputs:

Parameters:	label (str) – button label. active (bool) – state of the radio button.
Returns:	bool – True if clicked.

Wraps API:

bool RadioButton(const char* label, bool active)

imgui.core.render()¶

Finalize frame, set rendering data, and run render callback (if set).

Wraps API:

void Render()

imgui.core.reset_mouse_drag_delta(int button=0)¶

Reset the mouse dragging delta.

Parameters:	button (int) – mouse button index.

Wraps API:

void ResetMouseDragDelta(int button = 0)

imgui.core.same_line(float position=0.0, float spacing=-1.0)¶

Call between widgets or groups to layout them horizontally.

Example:

imgui.begin("Example: same line widgets")

imgui.text("same_line() with defaults:")
imgui.button("yes"); imgui.same_line()
imgui.button("no")

imgui.text("same_line() with fixed position:")
imgui.button("yes"); imgui.same_line(position=50)
imgui.button("no")

imgui.text("same_line() with spacing:")
imgui.button("yes"); imgui.same_line(spacing=50)
imgui.button("no")

imgui.end()

Outputs:

Parameters:	position (float) – fixed horizontal position position. spacing (float) – spacing between elements.

Wraps API:

void SameLine(float pos_x = 0.0f, float spacing_w = -1.0f)

imgui.core.selectable(str label, selected=False, ImGuiTreeNodeFlags flags=0, width=0, height=0)¶

Selectable text. Returns ‘true’ if the item is pressed.

Width of 0.0 will use the available width in the parent container. Height of 0.0 will use the available height in the parent container.

Example:

selected = [False, False]
imgui.begin("Example: selectable")
_, selected[0] = imgui.selectable(
    "1. I am selectable", selected[0]
)
_, selected[1] = imgui.selectable(
    "2. I am selectable too", selected[1]
)
imgui.text("3. I am not selectable")
imgui.end()

Outputs:

Parameters:	label (str) – The label. selected (bool) – defines if item is selected or not. flags – Selectable flags. See: list of available flags. width (float) – button width. height (float) – button height.
Returns:	tuple – a `(opened, selected)` two-tuple indicating if item was clicked by the user and the current state of item.

Wraps API:

bool Selectable(
    const char* label,
    bool selected = false,
    ImGuiSelectableFlags flags = 0,
    const ImVec2& size = ImVec2(0,0)
)

bool Selectable(
    const char* label,
    bool* selected,
    ImGuiSelectableFlags flags = 0,
    const ImVec2& size = ImVec2(0,0)
)

imgui.core.separator()¶

Add vertical line as a separator beween elements.

Example:

imgui.begin("Example: separators")

imgui.text("Some text with bullets")
imgui.bullet_text("Bullet A")
imgui.bullet_text("Bullet A")

imgui.separator()

imgui.text("Another text with bullets")
imgui.bullet_text("Bullet A")
imgui.bullet_text("Bullet A")

imgui.end()

Outputs:

Wraps API:

void Separator()

imgui.core.set_column_offset(int column_index, float offset_x)¶

Set the position of column line (in pixels, from the left side of the contents region). Pass -1 to use current column.

For a complete example see columns().

Parameters:	column_index (int) – index of the column to get the offset for. offset_x (float) – offset in pixels.

Wraps API:

void SetColumnOffset(int column_index, float offset_x)

imgui.core.set_column_width(int column_index, float width)¶

Set the position of column line (in pixels, from the left side of the contents region). Pass -1 to use current column.

For a complete example see columns().

Parameters:	column_index (int) – index of the column to set the width for. width (float) – width in pixels.

Wraps API:

void SetColumnWidth(int column_index, float width)

imgui.core.set_current_context(_ImGuiContext ctx)¶

SetCurrentContext

Wraps API:

SetCurrentContext(
        ImGuiContext *ctx);

imgui.core.set_cursor_pos(local_pos)¶

Set the cursor position in local coordinates [0..<window size>] (useful to work with ImDrawList API)

Wraps API:

ImVec2 SetCursorScreenPos(const ImVec2& screen_pos)

imgui.core.set_cursor_position()¶

set_cursor_pos(local_pos) Set the cursor position in local coordinates [0..<window size>] (useful to work with ImDrawList API)

Wraps API:

ImVec2 SetCursorScreenPos(const ImVec2& screen_pos)

imgui.core.set_cursor_screen_pos(screen_pos)¶

Set the cursor position in absolute screen coordinates [0..io.DisplaySize] (useful to work with ImDrawList API)

Wraps API:

ImVec2 SetCursorScreenPos(const ImVec2& screen_pos)

imgui.core.set_cursor_screen_position()¶

set_cursor_screen_pos(screen_pos) Set the cursor position in absolute screen coordinates [0..io.DisplaySize] (useful to work with ImDrawList API)

Wraps API:

ImVec2 SetCursorScreenPos(const ImVec2& screen_pos)

imgui.core.set_drag_drop_payload(str type, bytes data, ImGuiCond condition=0)¶

Set the payload for a drag and drop source. Only call after begin_drag_drop_source() returns True.

Note: this is a beta API.

For a complete example see begin_drag_drop_source().

Parameters:	type (str) – user defined type with maximum 32 bytes. data (bytes) – the data for the payload; will be copied and stored internally. condition (condition flag) – defines on which condition value should be set. Defaults to `imgui.ALWAYS`.

Wraps API:

bool SetDragDropPayload(const char* type, const void* data, size_t size, ImGuiCond cond = 0)

imgui.core.set_item_allow_overlap()¶

Allow last item to be overlapped by a subsequent item. Sometimes useful with invisible buttons, selectables, etc. to catch unused area.

Wraps API:

void SetItemAllowOverlap()

imgui.core.set_item_default_focus()¶

Make last item the default focused item of a window. Please use instead of “if (is_window_appearing()) set_scroll_here()” to signify “default item”.

Wraps API:

void SetItemDefaultFocus()

imgui.core.set_keyboard_focus_here(int offset=0)¶

Focus keyboard on the next widget. Use positive ‘offset’ to access sub components of a multiple component widget. Use -1 to access previous widget.

Wraps API:

void SetKeyboardFocusHere(int offset = 0)

imgui.core.set_mouse_cursor(ImGuiMouseCursor mouse_cursor_type)¶

Set the mouse cursor id.

Parameters:	mouse_cursor_type (ImGuiMouseCursor) – mouse cursor type.

Wraps API:

void SetMouseCursor(ImGuiMouseCursor type)

imgui.core.set_next_window_bg_alpha(float alpha)¶

set next window background color alpha. helper to easily modify ImGuiCol_WindowBg/ChildBg/PopupBg.

Wraps API:

void SetNextWindowBgAlpha(float)

imgui.core.set_next_window_collapsed(bool collapsed, ImGuiCond condition=ALWAYS)¶

Set next window collapsed state.

Example:

imgui.set_next_window_collapsed(True)
imgui.begin("Example: collapsed window")
imgui.end()

Outputs:

_images/imgui.core.set_next_window_collapsed_0.png

Parameters:	collapsed (bool) – set to True if window has to be collapsed. condition (condition flag) – defines on which condition value should be set. Defaults to `imgui.ALWAYS`.

Wraps API:

void SetNextWindowCollapsed(
    bool collapsed, ImGuiCond cond = 0
)

imgui.core.set_next_window_focus()¶

Set next window to be focused (most front).

Wraps API:

void SetNextWindowFocus()

imgui.core.set_next_window_position(float x, float y, ImGuiCond condition=ALWAYS, float pivot_x=0, float pivot_y=0)¶

Set next window position.

Call before begin().

Parameters:	x (float) – x window coordinate y (float) – y window coordinate condition (condition flag) – defines on which condition value should be set. Defaults to `imgui.ALWAYS`. pivot_x (float) – pivot x window coordinate pivot_y (float) – pivot y window coordinate

Example:

imgui.set_next_window_size(20, 20)

for index in range(5):
    imgui.set_next_window_position(index * 40, 5)
    imgui.begin(str(index))
    imgui.end()

Outputs:

_images/imgui.core.set_next_window_position_0.png

Wraps API:

void SetNextWindowPos(
    const ImVec2& pos,
    ImGuiCond cond = 0,
    const ImVec2& pivot = ImVec2(0,0)
)

imgui.core.set_next_window_size(float width, float height, ImGuiCond condition=ALWAYS)¶

Set next window size.

Call before begin().

Parameters:	width (float) – window width. Value 0.0 enables autofit. height (float) – window height. Value 0.0 enables autofit. condition (condition flag) – defines on which condition value should be set. Defaults to `imgui.ALWAYS`.

Example:

imgui.set_next_window_position(io.display_size.x * 0.5, io.display_size.y * 0.5, 1, pivot_x = 0.5, pivot_y = 0.5)

imgui.set_next_window_size(80, 180)
imgui.begin("High")
imgui.end()

Outputs:

_images/imgui.core.set_next_window_size_0.png

Wraps API:

void SetNextWindowSize(
    const ImVec2& size, ImGuiCond cond = 0
)

imgui.core.set_scroll_from_pos_y(float pos_y, float center_y_ratio=0.5)¶

Set scroll from position Y

adjust scrolling amount to make given position valid. use GetCursorPos() or GetCursorStartPos()+offset to get valid positions.

Parameters:	float pos_y float center_y_ratio = 0.5f

Wraps API:

void SetScrollFromPosY(float pos_y, float center_y_ratio = 0.5f)

imgui.core.set_scroll_here(float center_y_ratio=0.5)¶

Set scroll here.

adjust scrolling amount to make current cursor position visible. center_y_ratio=0.0: top, 0.5: center, 1.0: bottom. When using to make a “default/current item” visible, consider using SetItemDefaultFocus() instead.

Parameters:	float center_y_ratio = 0.5f

Wraps API:

void SetScrollHere(float center_y_ratio = 0.5f)

imgui.core.set_scroll_x(float scroll_x)¶

set scrolling amount [0..SetScrollMaxX()]

Wraps API:

int SetScrollX(float)

imgui.core.set_scroll_y(float scroll_y)¶

set scrolling amount [0..SetScrollMaxY()]

Wraps API:

int SetScrollY(flot)

imgui.core.set_tooltip(str text)¶

Set tooltip under mouse-cursor.

Usually used with is_item_hovered(). For a complex tooltip window see begin_tooltip().

Example:

imgui.begin("Example: tooltip")
imgui.button("Hover me!")
if imgui.is_item_hovered():
    imgui.set_tooltip("Please?")
imgui.end()

Outputs:

Wraps API:

void SetTooltip(const char* fmt, ...)

imgui.core.set_window_focus()¶

Set window to be focused

Wraps API:

void SetWindowFocus()

imgui.core.set_window_font_scale(float scale)¶

Adjust per-window font scale for current window.

Function should be called inside window context so after calling begin().

Note: use get_io().font_global_scale if you want to scale all windows.

Example:

imgui.begin("Example: font scale")
imgui.set_window_font_scale(2.0)
imgui.text("Bigger font")
imgui.end()

Outputs:

_images/imgui.core.set_window_font_scale_0.png

Parameters:	scale (float) – font scale

Wraps API:

void SetWindowFontScale(float scale)

imgui.core.set_window_size(float width, float height, ImGuiCond condition=ONCE)¶

Set window size

Call inside begin().

Note: usage of this function is not recommended. prefer using set_next_window_size() as this may incur tearing and minor side-effects.

Parameters:	width (float) – window width. Value 0.0 enables autofit. height (float) – window height. Value 0.0 enables autofit. condition (condition flag) – defines on which condition value should be set. Defaults to `imgui.ONCE`.

Example:

imgui.begin("Window size")
imgui.set_window_size(80, 180)
imgui.end()

Outputs:

visual_examples/imgui.core.set_window_size_0.png

Wraps API:

void SetWindowSize(
    const ImVec2& size,
    ImGuiCond cond = 0,
)

imgui.core.show_demo_window(closable=False)¶

Show ImGui demo window.

Example:

imgui.show_demo_window()

Outputs:

_images/imgui.core.show_demo_window_0.png

Parameters:	closable (bool) – define if window is closable.
Returns:	bool – True if window is not closed (False trigerred by close button).

Wraps API:

void ShowDemoWindow(bool* p_open = NULL)

imgui.core.show_font_selector(str label)¶

imgui.core.show_metrics_window(closable=False)¶

Show ImGui metrics window.

Example:

imgui.show_metrics_window()

Outputs:

_images/imgui.core.show_metrics_window_0.png

Parameters:	closable (bool) – define if window is closable.
Returns:	bool – True if window is not closed (False trigerred by close button).

Wraps API:

void ShowMetricsWindow(bool* p_open = NULL)

imgui.core.show_style_editor(GuiStyle style=None)¶

Show ImGui style editor.

Example:

imgui.begin("Example: my style editor")
imgui.show_style_editor()
imgui.end()

Outputs:

_images/imgui.core.show_style_editor_0.png

Parameters:	style (GuiStyle) – style editor state container.

Wraps API:

void ShowStyleEditor(ImGuiStyle* ref = NULL)

imgui.core.show_style_selector(str label)¶

imgui.core.show_test_window()¶

Show ImGui demo window.

Example:

imgui.show_test_window()

Outputs:

_images/imgui.core.show_test_window_0.png

Wraps API:

void ShowDemoWindow()

imgui.core.show_user_guide()¶

Show ImGui user guide editor.

Example:

imgui.begin("Example: user guide")
imgui.show_user_guide()
imgui.end()

Outputs:

_images/imgui.core.show_user_guide_0.png

Wraps API:

void ShowUserGuide()

imgui.core.slider_float(str label, float value, float min_value, float max_value, str format='%.3f', float power=1.0)¶

Display float slider widget. Use power different from 1.0 for logarithmic sliders.

Example:

value = 88.2

imgui.begin("Example: slider float")
changed, value = imgui.slider_float(
    "slide floats", value,
    min_value=0.0, max_value=100.0,
    format="%.0f",
    power=1.0
)
imgui.text("Changed: %s, Value: %s" % (changed, value))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (float) – slider values. min_value (float) – min value allowed by widget. max_value (float) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_float()`. power (float) – how fast values changes on slide.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the current slider value.

Wraps API:

bool SliderFloat(
    const char* label,
    float v,
    float v_min,
    float v_max,
    const char* format = "%.3f",
    float power = 1.0f
)

imgui.core.slider_float2(str label, float value0, float value1, float min_value, float max_value, str format='%.3f', float power=1.0)¶

Display float slider widget with 2 values. Use power different from 1.0 for logarithmic sliders.

Example:

values = 88.2, 42.6

imgui.begin("Example: slider float2")
changed, values = imgui.slider_float2(
    "slide floats", *values,
    min_value=0.0, max_value=100.0,
    format="%.0f",
    power=1.0
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (float) – slider values. min_value (float) – min value allowed by widget. max_value (float) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_float()`. power (float) – how fast values changes on slide.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current slider values.

Wraps API:

bool SliderFloat2(
    const char* label,
    float v[2],
    float v_min,
    float v_max,
    const char* format = "%.3f",
    float power = 1.0f
)

imgui.core.slider_float3(str label, float value0, float value1, float value2, float min_value, float max_value, str format='%.3f', float power=1.0)¶

Display float slider widget with 3 values. Use power different from 1.0 for logarithmic sliders.

Example:

values = 88.2, 42.6, 69.1

imgui.begin("Example: slider float3")
changed, values = imgui.slider_float3(
    "slide floats", *values,
    min_value=0.0, max_value=100.0,
    format="%.0f",
    power=1.0
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2 (float) – slider values. min_value (float) – min value allowed by widget. max_value (float) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_float()`. power (float) – how fast values changes on slide.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current slider values.

Wraps API:

bool SliderFloat3(
    const char* label,
    float v[3],
    float v_min,
    float v_max,
    const char* format = "%.3f",
    float power = 1.0f
)

imgui.core.slider_float4(str label, float value0, float value1, float value2, float value3, float min_value, float max_value, str format='%.3f', float power=1.0)¶

Display float slider widget with 4 values. Use power different from 1.0 for logarithmic sliders.

Example:

values = 88.2, 42.6, 69.1, 0.3

imgui.begin("Example: slider float4")
changed, values = imgui.slider_float4(
    "slide floats", *values,
    min_value=0.0, max_value=100.0,
    format="%.0f",
    power=1.0
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:

label (str) – widget label.
value0, value1, value2, value3 (float) – slider values.
min_value (float) – min value allowed by widget.
max_value (float) – max value allowed by widget.
format (str) – display format string as C-style printf format string. Warning: highly unsafe. See slider_float().
power (float) – how fast values changes on slide.

Returns:

tuple – a (changed, values) tuple that contains indicator of widget state change and the tuple of current slider values.

Wraps API:

bool SliderFloat4(
    const char* label,
    float v[4],
    float v_min,
    float v_max,
    const char* format = "%.3f",
    float power = 1.0f
)

imgui.core.slider_int(str label, int value, int min_value, int max_value, str format='%.f')¶

Display int slider widget

Example:

value = 88

imgui.begin("Example: slider int")
changed, values = imgui.slider_int(
    "slide ints", value,
    min_value=0, max_value=100,
    format="%d"
)
imgui.text("Changed: %s, Values: %s" % (changed, value))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (int) – slider value. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_int()`.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of widget state change and the slider value.

Wraps API:

bool SliderInt(
    const char* label,
    int v,
    int v_min,
    int v_max,
    const char* format = "%.3f"
)

imgui.core.slider_int2(str label, int value0, int value1, int min_value, int max_value, str format='%.f')¶

Display int slider widget with 2 values.

Example:

values = 88, 27

imgui.begin("Example: slider int2")
changed, values = imgui.slider_int2(
    "slide ints2", *values,
    min_value=0, max_value=100,
    format="%d"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1 (int) – slider values. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_int()`.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current slider values.

Wraps API:

bool SliderInt2(
    const char* label,
    int v[2],
    int v_min,
    int v_max,
    const char* format = "%.3f"
)

imgui.core.slider_int3(str label, int value0, int value1, int value2, int min_value, int max_value, str format='%.f')¶

Display int slider widget with 3 values.

Example:

values = 88, 27, 3

imgui.begin("Example: slider int3")
changed, values = imgui.slider_int3(
    "slide ints3", *values,
    min_value=0, max_value=100,
    format="%d"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2 (int) – slider values. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_int()`.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current slider values.

Wraps API:

bool SliderInt3(
    const char* label,
    int v[3],
    int v_min,
    int v_max,
    const char* format = "%.3f"
)

imgui.core.slider_int4(str label, int value0, int value1, int value2, int value3, int min_value, int max_value, str format='%.f')¶

Display int slider widget with 4 values.

Example:

values = 88, 42, 69, 0

imgui.begin("Example: slider int4")
changed, values = imgui.slider_int4(
    "slide ints", *values,
    min_value=0, max_value=100, format="%d"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value0, value1, value2, value3 (int) – slider values. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_int()`.
Returns:	tuple – a `(changed, values)` tuple that contains indicator of widget state change and the tuple of current slider values.

Wraps API:

bool SliderInt4(
    const char* label,
    int v[4],
    int v_min,
    int v_max,
    const char* format = "%.3f"
)

imgui.core.small_button(str label)¶

Display small button (with 0 frame padding).

Example:

imgui.begin("Example: button")
imgui.small_button("Button 1")
imgui.small_button("Button 2")
imgui.end()

Outputs:

Parameters:	label (str) – button label.
Returns:	bool – True if clicked.

Wraps API:

bool SmallButton(const char* label)

imgui.core.spacing()¶

Add vertical spacing beween elements.

Example:

imgui.begin("Example: vertical spacing")

imgui.text("Some text with bullets:")
imgui.bullet_text("Bullet A")
imgui.bullet_text("Bullet A")

imgui.spacing(); imgui.spacing()

imgui.text("Another text with bullets:")
imgui.bullet_text("Bullet A")
imgui.bullet_text("Bullet A")

imgui.end()

Outputs:

Wraps API:

void Spacing()

imgui.core.style_colors_classic(GuiStyle dst=None)¶

Set the style to Classic.

classic imgui style.

Wraps API:

void StyleColorsClassic(ImGuiStyle* dst = NULL)

imgui.core.style_colors_dark(GuiStyle dst=None)¶

Set the style to Dark.

new, recommended style (default)

Wraps API:

void StyleColorsDark(ImGuiStyle* dst = NULL)

imgui.core.style_colors_light(GuiStyle dst=None)¶

Set the style to Light.

best used with borders and a custom, thicker font

Wraps API:

void StyleColorsLight(ImGuiStyle* dst = NULL)

imgui.core.text(str text)¶

Add text to current widget stack.

Example:

imgui.begin("Example: simple text")
imgui.text("Simple text")
imgui.end()

Outputs:

Parameters:	text (str) – text to display.

Wraps API:

Text(const char* fmt, ...)

imgui.core.text_colored(str text, float r, float g, float b, float a=1.)¶

Add colored text to current widget stack.

It is a shortcut for:

imgui.push_style_color(imgui.COLOR_TEXT, r, g, b, a)
imgui.text(text)
imgui.pop_style_color()

Example:

imgui.begin("Example: colored text")
imgui.text_colored("Colored text", 1, 0, 0)
imgui.end()

Outputs:

Parameters:	text (str) – text to display. r (float) – red color intensity. g (float) – green color intensity. b (float) – blue color instensity. a (float) – alpha intensity.

Wraps API:

TextColored(const ImVec4& col, const char* fmt, ...)

imgui.core.text_unformatted(str text)¶

Big area text display - the size is defined by it’s container. Recommended for long chunks of text.

Example:

imgui.begin("Example: unformatted text")
imgui.text_unformatted("Really ... long ... text")
imgui.end()

Outputs:

_images/imgui.core.text_unformatted_0.png

Parameters:	text (str) – text to display.

Wraps API:

TextUnformatted(const char* text, const char* text_end = NULL)

imgui.core.tree_node(str text, ImGuiTreeNodeFlags flags=0)¶

Draw a tree node.

Returns ‘true’ if the node is drawn, call tree_pop() to finish.

Example:

imgui.begin("Example: tree node")
if imgui.tree_node("Expand me!", imgui.TREE_NODE_DEFAULT_OPEN):
    imgui.text("Lorem Ipsum")
    imgui.tree_pop()
imgui.end()

Outputs:

Parameters:	text (str) – Tree node label flags – TreeNode flags. See: list of available flags.
Returns:	bool – True if tree node is displayed (opened).

Wraps API:

bool TreeNode(const char* label)
bool TreeNodeEx(const char* label, ImGuiTreeNodeFlags flags = 0)

imgui.core.tree_pop()¶

Called to clear the tree nodes stack and return back the identation.

Same as calls to unindent() and pop_id(). For a tree example see tree_node().

Wraps API:

void TreePop()

imgui.core.unindent(float width=0.0)¶

Move content to left by indent width.

Example:

imgui.begin("Example: item unindenting")

imgui.text("Some text with bullets:")

imgui.bullet_text("Bullet A")
imgui.unindent(10)
imgui.bullet_text("Bullet B (first unindented)")
imgui.bullet_text("Bullet C (unindent continues)")
imgui.indent(10)
imgui.bullet_text("Bullet C (unindent cleared)")

imgui.end()

Outputs:

Parameters:	width (float) – fixed width of indent. If less or equal 0 it defaults to global indent spacing or value set using style value stack (see `push_style_var`).

Wraps API:

void Unindent(float indent_w = 0.0f)

imgui.core.v_slider_float(str label, float width, float height, float value, float min_value, float max_value, str format='%.f', float power=1.0)¶

Display vertical float slider widget with the specified width and height.

Example:

width = 20
height = 100
value = 88

imgui.begin("Example: vertical slider float")
changed, values = imgui.v_slider_float(
    "vertical slider float",
    width, height, value,
    min_value=0, max_value=100,
    format="%0.3f", power = 1.0
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (float) – slider value. min_value (float) – min value allowed by widget. max_value (float) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_float()`. power (float) – how fast values changes on slide.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of widget state change and the slider value.

Wraps API:

bool VSliderFloat(
    const char* label,
    const ImVec2& size,
    float v,
    float v_min,
    floatint v_max,
    const char* format = "%.3f",
    float power=1.0
)

imgui.core.v_slider_int(str label, float width, float height, int value, int min_value, int max_value, str format='%d')¶

Display vertical int slider widget with the specified width and height.

Example:

width = 20
height = 100
value = 88

imgui.begin("Example: vertical slider int")
changed, values = imgui.v_slider_int(
    "vertical slider int",
    width, height, value,
    min_value=0, max_value=100,
    format="%d"
)
imgui.text("Changed: %s, Values: %s" % (changed, values))
imgui.end()

Outputs:

Parameters:	label (str) – widget label. value (int) – slider value. min_value (int) – min value allowed by widget. max_value (int) – max value allowed by widget. format (str) – display format string as C-style `printf` format string. Warning: highly unsafe. See `slider_int()`.
Returns:	tuple – a `(changed, value)` tuple that contains indicator of widget state change and the slider value.

Wraps API:

bool VSliderInt(
    const char* label,
    const ImVec2& size,
    int v,
    int v_min,
    int v_max,
    const char* format = "%.3f"
)

imgui.extra module¶

This module provides extra utilities that are not part of core ImGui C++ API but are useful in Python application.

imgui.extra.font(*args, **kwds)¶

_py_font(_Font font) Use specified font in given context.

Example:

io = imgui.get_io()

new_font = io.fonts.add_font_from_file_ttf("DroidSans.ttf", 20)
impl.refresh_font_texture()

# later in frame code

imgui.begin("Default Window")

imgui.text("Text displayed using default font")
with imgui.font(new_font):
    imgui.text("Text displayed using custom font")

imgui.end()

Outputs:

visual_examples/1eee3be367ecdb3ce9868aa97e5adc40c1bfb00f.png

Args:: font (_Font): font object retrieved from add_font_from_file_ttf.

imgui.extra.styled(*args, **kwds)¶: _py_styled(ImGuiStyleVar variable, value)

imgui.extra.istyled(*args, **kwds)¶: _py_istyled(*variables_and_values)

imgui.extra.colored(*args, **kwds)¶: _py_colored(ImGuiCol variable, float r, float g, float b, float a=1.)

imgui.extra.vertex_buffer_vertex_pos_offset()¶: _py_vertex_buffer_vertex_pos_offset()

imgui.extra.vertex_buffer_vertex_uv_offset()¶: _py_vertex_buffer_vertex_uv_offset()

imgui.extra.vertex_buffer_vertex_col_offset()¶: _py_vertex_buffer_vertex_col_offset()

imgui.extra.vertex_buffer_vertex_size()¶: _py_vertex_buffer_vertex_size()

pyimgui

Navigation

Related Topics

Support

pyimgui¶

Installation¶

Project status¶

Project distribution¶

Development tips¶

Contents¶

Usage guide¶

First steps with imgui¶

What is immediate mode GUI¶

Using pyimgui¶

Basic GUI drawing loop¶

Using built-in rendering backend integrations¶

Using fonts¶

High-density screens¶

Using conditions¶

Using window flags¶

Using tree node flags¶

Using selectable flags¶

Using input text flags¶

API reference¶

imgui package¶

imgui.core module¶

imgui.extra module¶

imgui.integrations subpackage¶

imgui.integrations.cocos2d module¶

imgui.integrations.glfw module¶

imgui.integrations.opengl module¶

imgui.integrations.pygame module¶

imgui.integrations.sdl2 module¶

Indices and tables¶