Builds:
pyimgui¶
Python bindings for the amazing dear imgui C++ library - a Bloat-free Immediate Mode Graphical User Interface.
Documentation: pyimgui.readthedocs.io
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 fromimgui.core
submodule are also available in the rootimgui
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()
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 packageimgui.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()
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()
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()
List of all available window flags (click to see documentation):
imgui.WINDOW_NO_TITLE_BAR
imgui.WINDOW_NO_RESIZE
imgui.WINDOW_NO_MOVE
imgui.WINDOW_NO_SCROLLBAR
imgui.WINDOW_NO_SCROLL_WITH_MOUSE
imgui.WINDOW_NO_COLLAPSE
imgui.WINDOW_ALWAYS_AUTO_RESIZE
imgui.WINDOW_NO_SAVED_SETTINGS
imgui.WINDOW_NO_INPUTS
imgui.WINDOW_MENU_BAR
imgui.WINDOW_HORIZONTAL_SCROLLING_BAR
imgui.WINDOW_NO_FOCUS_ON_APPEARING
imgui.WINDOW_NO_BRING_TO_FRONT_ON_FOCUS
imgui.WINDOW_ALWAYS_VERTICAL_SCROLLBAR
imgui.WINDOW_ALWAYS_HORIZONTAL_SCROLLBAR
imgui.WINDOW_ALWAYS_USE_WINDOW_PADDING
Using tree node flags¶
TreeNode functions accept various flags to manage their behaviour.
List of all available tree node flags (click to see documentation):
imgui.TREE_NODE_SELECTED
imgui.TREE_NODE_FRAME
imgui.TREE_NODE_ALLOW_OVERLAP_MODE
imgui.TREE_NODE_NO_TREE_PUSH_ON_OPEN
imgui.TREE_NODE_NO_AUTO_OPEN_ON_LOG
imgui.TREE_NODE_DEFAULT_OPEN
imgui.TREE_NODE_OPEN_ON_DOUBLE_CLICK
imgui.TREE_NODE_OPEN_ON_ARROW
imgui.TREE_NODE_LEAF
imgui.TREE_NODE_BULLET
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):
imgui.INPUT_TEXT_CHARS_DECIMAL
imgui.INPUT_TEXT_CHARS_HEXADECIMAL
imgui.INPUT_TEXT_CHARS_UPPERCASE
imgui.INPUT_TEXT_CHARS_NO_BLANK
imgui.INPUT_TEXT_AUTO_SELECT_ALL
imgui.INPUT_TEXT_ENTER_RETURNS_TRUE
imgui.INPUT_TEXT_CALLBACK_COMPLETION
imgui.INPUT_TEXT_CALLBACK_HISTORY
imgui.INPUT_TEXT_CALLBACK_ALWAYS
imgui.INPUT_TEXT_CALLBACK_CHAR_FILTER
imgui.INPUT_TEXT_ALLOW_TAB_INPUT
imgui.INPUT_TEXT_CTRL_ENTER_FOR_NEW_LINE
imgui.INPUT_TEXT_NO_HORIZONTAL_SCROLL
imgui.INPUT_TEXT_ALWAYS_INSERT_MODE
imgui.INPUT_TEXT_READ_ONLY
imgui.INPUT_TEXT_PASSWORD
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. forimgui.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
¶
-
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 withget_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: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: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: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: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: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: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: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: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
¶
-
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:
-
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 collapsedexpanded==True
. The value ofopened
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()
andend_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: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()
andend_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 assame_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()
Create new full-screen menu bar.
Only callend_main_menu_bar()
if this function returnsTrue
!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:Returns: bool – True if main menu bar is displayed (opened). Wraps API:
bool BeginMainMenuBar()
Create new expandable menu in current menu bar.
Only call
end_menu()
if this returnsTrue
!For practical example how to use this function, please see documentation of
begin_main_menu_bar()
orbegin_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 )
Append new menu menu bar to current window.
This function is different from
begin_main_menu_bar()
, as this is child-window specific. Only callend_menu_bar()
if this returnsTrue
!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 returnFalse
.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 callend_popup()
ifbegin_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 beFalse
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, ...)
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()
orselectable()
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: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 ifvisible
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 )
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 colorWraps 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 alphaWraps 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. Seedrag_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. Seedrag_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. Seedrag_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. Seedrag_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. Seedrag_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. Seedrag_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()
Close main menu bar context.
Only call this function if the
end_main_menu_bar()
returnsTrue
.For practical example how to use this function see documentation of
begin_main_menu_bar()
.Wraps API:
bool EndMainMenuBar()
Close menu context.
Only call this function if the
begin_menu()
returnsTrue
.For practical example how to use this function, please see documentation of
begin_main_menu_bar()
orbegin_menu_bar()
.Wraps API:
void EndMenu()
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 tonew_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: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) )
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: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 )
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)
- identifier (str) – Button identifier. Like label on
-
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 )
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 calllistbox_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) )
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()
orbegin_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()
orrender()
.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 abegin_popup()
/end_popup()
block. Popup identifiers are relative to the current ID-stack (soopen_popup()
andbegin_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 )
- label (str) – A plot label that will be displayed on the plot’s right
side. If you want the label to be invisible, add
-
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) )
- label (str) – A plot label that will be displayed on the plot’s right
side. If you want the label to be invisible, add
-
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()
oristyled()
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()
oristyled()
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()
oristyled()
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()
oristyled()
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()
oristyled()
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 thefont()
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: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 usestyled()
oristyled()
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: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 usestyled()
oristyled()
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 wrappingParameters: 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)
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: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: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: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 seebegin_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: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: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: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: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: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: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: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. Seeslider_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. Seeslider_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. Seeslider_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. Seeslider_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. Seeslider_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. Seeslider_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. Seeslider_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. Seeslider_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" )
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 fontWraps 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: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()
andpop_id()
. For a tree example seetree_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. Seeslider_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. Seeslider_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:- Args:
- font (_Font): font object retrieved from
add_font_from_file_ttf
.
-
imgui.extra.
styled
(*args, **kwds)¶ _py_styled(ImGuiStyleVar variable, value)
-
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()
-
imgui.extra.
index_buffer_index_size
()¶ _py_index_buffer_index_size()