---
url: /slimgui/index.md
---
# Introduction

The Slimgui package provides modern Python bindings for the following libraries:

* [Dear ImGui](https://github.com/ocornut/imgui)
* [ImPlot](https://github.com/epezent/implot)

Features:

* API design that stays close to Dear ImGui while remaining natural to use from Python
* Python bindings for Dear ImGui and ImPlot with `.pyi` typing files for good IDE support
* Integrations for GLFW + PyOpenGL and Pyglet

The documentation is split into several parts:

* [Guide](/guide/getting-started)
* [Dear ImGui API reference](/api/imgui)
* [ImPlot API reference](/api/implot)
* [Recipes](/recipes/)

Further reading:

* [Slimgui on GitHub](https://github.com/nurpax/slimgui)
* [Release notes](https://github.com/nurpax/slimgui/releases)
* [Full documentation as LLM-friendly Markdown](/llms-full.txt)
---

---
url: /slimgui/guide/getting-started.md
---
# Getting Started

Slimgui requires Python 3.10 or newer.

Installation: `pip install slimgui`

To run the example, clone the repo, install dependencies and run:

```
git clone https://github.com/nurpax/slimgui
cd slimgui
pip install glfw pyopengl numpy requests
python example/app.py
```

Browse the example code: [example/](https://github.com/nurpax/slimgui/blob/main/example/)
---

---
url: /slimgui/guide/typing.md
---
# Typing

Slimgui has been developed with the following goals in mind:

* Support typing through `.pyi` files to enable good IDE support such as auto-complete, type checking, and docstrings.
* Closely match the Dear ImGui API but adapt for Python as necessary. Don't invent new API concepts.

The Slimgui API is similar to [pyimgui](https://github.com/pyimgui/pyimgui) except somewhat modernized:

* Enums in ImGui are exposed as typed Python enums using `enum.IntEnum` and `enum.IntFlag` to make it clear which API functions consume what type of enums.
* Vector types such as `ImVec2`, `ImVec4`, and `float*` arrays are converted to Python tuples such as `tuple[float, float]` for `ImVec2` and `tuple[float, float, float, float]` for `ImVec4`.
* Mutable bool args such as `bool* p_open` are input as normal `bool` values and returned as the second element of a 2-tuple. For example, `bool ImGui::Checkbox(const char* label, bool* v)` is translated to `def checkbox(label: str, v: bool) -> tuple[bool, bool]`, where the first element is the boolean return value of `ImGui::Checkbox()` and the second element is the new checkbox state.

## Public and Internal Types

Typical usage imports the public modules:

```python
from slimgui import imgui
from slimgui import implot
```

The underlying bindings live under `slimgui.slimgui_ext.imgui` and
`slimgui.slimgui_ext.implot`.

Those `slimgui_ext.*` modules exist because they expose the native binding layer directly.
The public `slimgui.imgui` and `slimgui.implot` modules then build on top of that layer by:

* re-exporting many enums and binding types
* adding some higher-level Python wrapper types

For example, some API signatures use wrapper types such as:

* `slimgui.imgui.WrappedContext`
* `slimgui.implot.WrappedContext`
* `slimgui.imgui.DrawList`

These are distinct from the lower-level types in `slimgui.slimgui_ext.*`, even when they are related internally.
---

---
url: /slimgui/api/imgui.md
---

# ImGui API reference

Slimgui is built against Dear ImGui version 1.92.4.

API reference documentation is primarily adapted from Dear ImGui main header [imgui.h](https://github.com/ocornut/imgui/blob/master/imgui.h),
with minor modifications to adapt symbol naming to Pythonic snake case.

See [Typing](/guide/typing) for an explanation of the public `imgui` module,
wrapper types such as `slimgui.imgui.DrawList`, and how they relate to the
underlying `slimgui.slimgui_ext.*` bindings.

## Context creation and access

Each context creates its own `FontAtlas` by default. You may instance one yourself and pass it to `create_context()` to share a font atlas between contexts.

### Functions

::: api-signature

```python
def create_context(
    shared_font_atlas: slimgui.slimgui_ext.imgui.FontAtlas | None = None,
) -> slimgui.imgui.WrappedContext:
    """
    Create an ImGui `Context`.  The newly created context is also set current.
    """
```

:::

::: api-signature

```python
def destroy_context(
    ctx: slimgui.imgui.WrappedContext | None,
):
    """
    Destroy ImGui `Context`.  `None` = destroy current context.
    """
```

:::

::: api-signature

```python
def get_current_context() -> slimgui.imgui.WrappedContext | None:
    """
    Get the current ImGui context.
    """
```

:::

::: api-signature

```python
def set_current_context(
    ctx: slimgui.imgui.WrappedContext,
) -> None:
    """
    Set the current ImGui context.
    """
```

:::

## Main

### Functions

::: api-signature

```python
def get_io() -> slimgui.slimgui_ext.imgui.IO:
    """
    Access the ImGui `IO` structure (mouse/keyboard/gamepad inputs, time, various configuration options/flags).
    """
```

:::

::: api-signature

```python
def get_style() -> slimgui.slimgui_ext.imgui.Style:
    """
    Access the `Style` structure (colors, sizes). Always use `push_style_color()`, `push_style_var()` to modify style mid-frame!
    """
```

:::

::: api-signature

```python
def get_platform_io() -> slimgui.slimgui_ext.imgui.PlatformIO:
    """
    Access the ImGui `PlatformIO` structure.
    """
```

:::

::: api-signature

```python
def new_frame():
    """
    ImGui::NewFrame() call but with some Python binding specific book keeping.
    """
```

:::

::: api-signature

```python
def end_frame() -> None:
    """
    Ends the Dear ImGui frame. automatically called by `render()`. If you don't need to render data (skipping rendering) you may call `end_frame()` without `render()`... but you'll have wasted CPU already! If you don't need to render, better to not create any windows and not call `new_frame()` at all!
    """
```

:::

::: api-signature

```python
def render() -> None:
    """
    Ends the Dear ImGui frame, finalize the draw data. You can then get call `get_draw_data()`.
    """
```

:::

::: api-signature

```python
def get_draw_data() -> DrawData:
    """
    Valid after `render()` and until the next call to `new_frame()`. Call ImGui_ImplXXXX_RenderDrawData() function in your Renderer Backend to render.
    """
```

:::

## Demo, Debug, Information

### Error recovery and debug options

Please see <https://github.com/ocornut/imgui/wiki/Error-Handling> for information.

Currently only the `IO.config_*` boolean options are exposed from Slimgui. `IM_ASSERT` is configured by default to raise a Python exception, but note that it is not always recoverable — your Python application may be in a bad state afterward.

### Functions

::: api-signature

```python
def show_demo_window(
    closable: bool = False,
) -> bool:
    """
    Create Demo window. demonstrate most ImGui features. call this to learn about the library! try to make it always available in your application!
    """
```

:::

::: api-signature

```python
def show_metrics_window(
    closable: bool = False,
) -> bool:
    """
    Create Metrics/Debugger window. display Dear ImGui internals: windows, draw commands, various internal state, etc.
    """
```

:::

::: api-signature

```python
def show_debug_log_window(
    closable: bool = False,
) -> bool:
    """
    Create Debug Log window. display a simplified log of important dear imgui events.
    """
```

:::

::: api-signature

```python
def show_id_stack_tool_window(
    closable: bool = False,
) -> bool:
    """
    Create Stack Tool window. hover items with mouse to query information about the source of their unique ID.
    """
```

:::

::: api-signature

```python
def show_about_window(
    closable: bool = False,
) -> bool:
    """
    Create About window. display Dear ImGui version, credits and build/system information.
    """
```

:::

::: api-signature

```python
def show_style_editor() -> None:
    """
    Add style editor block (not a window). you can pass in a reference ImGuiStyle structure to compare to, revert to and save to (else it uses the default style)
    """
```

:::

::: api-signature

```python
def show_style_selector(
    label: str,
) -> bool:
    """
    Add style selector block (not a window), essentially a combo listing the default styles.
    """
```

:::

::: api-signature

```python
def show_font_selector(
    label: str,
) -> None:
    """
    Add font selector block (not a window), essentially a combo listing the loaded fonts.
    """
```

:::

::: api-signature

```python
def show_user_guide() -> None:
    """
    Add basic help/info block (not a window): how to manipulate ImGui as an end-user (mouse/keyboard controls).
    """
```

:::

::: api-signature

```python
def get_version() -> str:
    """
    Get the compiled version string e.g. "1.80 WIP" (essentially the value for IMGUI_VERSION from the compiled version of imgui.cpp)
    """
```

:::

### Logging

::: api-signature

```python
def log_to_tty(
    auto_open_depth: int = -1,
) -> None:
    """
    Start logging to tty (stdout)
    """
```

:::

::: api-signature

```python
def log_to_file(
    auto_open_depth: int = -1,
    filename: str | None = None,
) -> None:
    """
    Start logging to file
    """
```

:::

::: api-signature

```python
def log_to_clipboard(
    auto_open_depth: int = -1,
) -> None:
    """
    Start logging to OS clipboard
    """
```

:::

::: api-signature

```python
def log_finish() -> None:
    """
    Stop logging (close file, etc.)
    """
```

:::

::: api-signature

```python
def log_buttons() -> None:
    """
    Helper to display buttons for logging to tty/file/clipboard
    """
```

:::

::: api-signature

```python
def log_text(
    text: str,
) -> None:
    """
    Pass text data straight to log (without being displayed)
    """
```

:::

::: api-signature

```python
def set_nanobind_leak_warnings(
    enable: bool,
) -> None:
```

:::

## Styles

Note: functions shown below intentionally do not accept `None` as the destination style.  Python wrappers with same name exist in the `slimgui` module that can be called with `None` that then modifies the current context's style.

### Functions

::: api-signature

```python
def style_colors_dark(
    dst: slimgui.slimgui_ext.imgui.Style | None = None,
) -> None:
    """
    Write dark mode styles into the destination style.  Set directly to context's style if dst is None.
    """
```

:::

::: api-signature

```python
def style_colors_light(
    dst: slimgui.slimgui_ext.imgui.Style | None = None,
) -> None:
    """
    Write light mode styles into the destination style.  Set directly to context's style if dst is None.
    """
```

:::

::: api-signature

```python
def style_colors_classic(
    dst: slimgui.slimgui_ext.imgui.Style | None = None,
) -> None:
    """
    Write classic mode styles into the destination style.  Set directly to context's style if dst is None.
    """
```

:::

## Windows

* `begin()` = push window to the stack and start appending to it. `end()` = pop window from the stack.
* Passing `closable = True` shows a window-closing widget in the upper-right corner of the window,
  which clicking will set the boolean to false when clicked.
* You may append multiple times to the same window during the same frame by calling `begin()`/`end()` pairs multiple times. Some information such as `flags` or `closable` will only be considered by the first call to `begin()`.
* `begin()` returns `False` to indicate the window is collapsed or fully clipped, so you may early out and omit submitting
  anything to the window. Always call a matching `end()` for each `begin()` call, regardless of its return value!

  Important: due to legacy reason, `begin()`/`end()` and `begin_child()`/`end_child()` are inconsistent with all other functions such as `begin_menu()`/`end_menu()`, `begin_popup()`/`end_popup()`, etc. where the `end_xxx()` call should only be called if the corresponding
  `begin_xxx()` function returned `True`. `begin()` and `begin_child()` are the only odd ones out. Will be fixed in a future update.
* Note that the bottom of window stack always contains a window called "Debug".

### Functions

::: api-signature

````python
def begin(
    name: str,
    closable: bool = False,
    flags: WindowFlags = WindowFlags.NONE,
) -> tuple[bool, bool]:
    """
    When the `closable` argument is set to `True`, the created window will display a close button.  The second bool of the return value will be `False` if the close button was pressed.  The intended usage is as follows:
    ```python
    win_open = True  # open/closed state

    visible, win_open = imgui.begin(..., closable=win_open)
    if visible:
        # render window contents here..
    imgui.end()
    ```
    """
````

:::

::: api-signature

```python
def end() -> None:
    """
    Every `begin()` call must be paired with a corresponding `end()` call, regardless of the return value of `begin()` return value.
    """
```

:::

## Child Windows

* Use child windows to begin into a self-contained independent scrolling/clipping regions within a host window. Child windows can embed their own child.
* Manual sizing (each axis can use a different setting e.g. `(0, 400)`):
  \== 0: use remaining parent window size for this axis.
  > 0: use specified size for this axis.
  > < 0: right/bottom-align to specified distance from available content boundaries.
* Specifying `ChildFlags.AUTO_RESIZE_X` or `ChildFlags.AUTO_RESIZE_Y` makes the sizing automatic based on child contents.
  Combining both `ChildFlags.AUTO_RESIZE_X` *and* `ChildFlags.AUTO_RESIZE_Y` defeats purpose of a scrolling region and is NOT recommended.
* `begin_child()` returns false to indicate the window is collapsed or fully clipped, so you may early out and omit submitting
  anything to the window. Always call a matching `end_child()` for each `begin_child()` call, regardless of its return value.

Important: due to legacy reason, `begin()`/`end()` and `begin_child()`/`end_child()` are inconsistent with all other functions such as `begin_menu()`/`end_menu()`, `begin_popup()`/`end_popup()`, etc. where the `end_xxx()` call should only be called if the corresponding `begin_xxx()` function returned true. `begin()` and `begin_child()` are the only odd ones out. Will be fixed in a future update.

### Functions

::: api-signature

```python
def begin_child(
    str_id: str,
    size: tuple[float, float] = (0.0, 0.0),
    child_flags: ChildFlags = ChildFlags.NONE,
    window_flags: WindowFlags = WindowFlags.NONE,
) -> bool:
```

:::

::: api-signature

```python
def end_child() -> None:
```

:::

## Window Utilities

* 'current window' = the window we are appending into while inside a `begin()`/`end()` block. 'next window' = next window we will `begin()` into.

### Functions

::: api-signature

```python
def is_window_appearing() -> bool:
```

:::

::: api-signature

```python
def is_window_collapsed() -> bool:
```

:::

::: api-signature

```python
def is_window_focused(
    flags: FocusedFlags = FocusedFlags.NONE,
) -> bool:
    """
    Is current window focused? or its root/child, depending on flags. see flags for options.
    """
```

:::

::: api-signature

```python
def is_window_hovered(
    flags: HoveredFlags = HoveredFlags.NONE,
) -> bool:
    """
    Is current window hovered and hoverable (e.g. not blocked by a popup/modal)? See `HoveredFlags` for options. IMPORTANT: If you are trying to check whether your mouse should be dispatched to Dear ImGui or to your underlying app, you should not use this function! Use the 'io.WantCaptureMouse' boolean for that! Refer to FAQ entry "How can I tell whether to dispatch mouse/keyboard to Dear ImGui or my application?" for details.
    """
```

:::

::: api-signature

```python
def get_window_draw_list() -> slimgui.imgui.DrawList:
    """
    Get draw list associated to the current window, to append your own drawing primitives.
    """
```

:::

::: api-signature

```python
def get_window_pos() -> tuple[float, float]:
    """
    Get current window position in screen space (IT IS UNLIKELY YOU EVER NEED TO USE THIS. Consider always using `get_cursor_screen_pos()` and `get_content_region_avail()` instead)
    """
```

:::

::: api-signature

```python
def get_window_size() -> tuple[float, float]:
    """
    Get current window size (IT IS UNLIKELY YOU EVER NEED TO USE THIS. Consider always using `get_cursor_screen_pos()` and `get_content_region_avail()` instead)
    """
```

:::

::: api-signature

```python
def get_window_width() -> float:
    """
    Get current window width (IT IS UNLIKELY YOU EVER NEED TO USE THIS). Shortcut for `get_window_size()`.x.
    """
```

:::

::: api-signature

```python
def get_window_height() -> float:
    """
    Get current window height (IT IS UNLIKELY YOU EVER NEED TO USE THIS). Shortcut for `get_window_size()`.y.
    """
```

:::

## Window Manipulation

* Prefer using `set_next_xxx` functions (before `begin`) rather than `set_xxx` functions (after `begin`).

### Functions

::: api-signature

```python
def set_next_window_pos(
    pos: tuple[float, float],
    cond: Cond = Cond.NONE,
    pivot: tuple[float, float] = (0.0, 0.0),
) -> None:
    """
    Set next window position. call before `begin()`. use pivot=(0.5,0.5) to center on given point, etc.
    """
```

:::

::: api-signature

```python
def set_next_window_size(
    size: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    Set next window size. set axis to 0.0 to force an auto-fit on this axis. call before `begin()`
    """
```

:::

::: api-signature

````python
def set_next_window_size_constraints(
    size_min: tuple[float, float],
    size_max: tuple[float, float],
    cb: Optional[Callable[[tuple[float, float], tuple[float, float], tuple[float, float], int], tuple[float, float]]] = None,
    user_data_id: int = 0,
) -> None:
    """
    Set next window size limits.  Use 0.0 or FLT_MAX if you don't want limits.  Use -1 for both min and max of same axis to preserve current size (which itself is a constraint).  Use callback to apply non-trivial programmatic constraints.

    This function still has some rough corners.  It only accepts an integer `user_data` argument.  If you need to pass a float through it, you could for example convert to fixed point and convert back to float in the constraint function.  Or you can capture any such values as a function closure.

    Use of constrain callbacks:
    ```python
    def aspect_ratio_constraint_16_9(_pos:  FVec2, _current_size: FVec2, desired_size: FVec2, _int_user_data: int) -> FVec2:
        aspect_ratio = 16.0 / 9
        new_desired_y = int(desired_size[0] / aspect_ratio)
        return (desired_size[0], new_desired_y)

    # usage:

    imgui.set_next_window_size_constraints((0, 0), (FLT_MAX, FLT_MAX), aspect_ratio_constraint_16_9)
    ```
    """
````

:::

::: api-signature

```python
def set_next_window_content_size(
    size: tuple[float, float],
) -> None:
    """
    Set next window content size (~ scrollable client area, which enforce the range of scrollbars). Not including window decorations (title bar, menu bar, etc.) nor WindowPadding. set an axis to 0.0 to leave it automatic. call before `begin()`
    """
```

:::

::: api-signature

```python
def set_next_window_collapsed(
    collapsed: bool,
    cond: Cond = Cond.NONE,
) -> None:
    """
    Set next window collapsed state. call before `begin()`
    """
```

:::

::: api-signature

```python
def set_next_window_focus() -> None:
    """
    Set next window to be focused / top-most. call before `begin()`
    """
```

:::

::: api-signature

```python
def set_next_window_scroll(
    scroll: tuple[float, float],
) -> None:
    """
    Set next window scrolling value (use < 0.0 to not affect a given axis).
    """
```

:::

::: api-signature

```python
def set_next_window_bg_alpha(
    alpha: float,
) -> None:
    """
    Set next window background color alpha. helper to easily override the Alpha component of `Col.WINDOW_BG`/ChildBg/PopupBg. you may also use `WindowFlags.NO_BACKGROUND`.
    """
```

:::

::: api-signature

```python
def set_window_pos(
    pos: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window position - call within `begin()`/`end()`. prefer using `set_next_window_pos()`, as this may incur tearing and side-effects.
    """
```

:::

::: api-signature

```python
def set_window_pos(
    name: str,
    pos: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window position - call within `begin()`/`end()`. prefer using `set_next_window_pos()`, as this may incur tearing and side-effects.
    """
```

:::

::: api-signature

```python
def set_window_size(
    size: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window size - call within `begin()`/`end()`. set to ImVec2(0, 0) to force an auto-fit. prefer using `set_next_window_size()`, as this may incur tearing and minor side-effects.
    """
```

:::

::: api-signature

```python
def set_window_size(
    name: str,
    size: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window size - call within `begin()`/`end()`. set to ImVec2(0, 0) to force an auto-fit. prefer using `set_next_window_size()`, as this may incur tearing and minor side-effects.
    """
```

:::

::: api-signature

```python
def set_window_collapsed(
    collapsed: bool,
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window collapsed state. prefer using `set_next_window_collapsed()`.
    """
```

:::

::: api-signature

```python
def set_window_collapsed(
    name: str,
    collapsed: bool,
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window collapsed state. prefer using `set_next_window_collapsed()`.
    """
```

:::

::: api-signature

```python
def set_window_focus() -> None:
    """
    (not recommended) set current window to be focused / top-most. prefer using `set_next_window_focus()`.
    """
```

:::

::: api-signature

```python
def set_window_focus(
    name: str,
) -> None:
    """
    (not recommended) set current window to be focused / top-most. prefer using `set_next_window_focus()`.
    """
```

:::

::: api-signature

```python
def set_window_pos(
    pos: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window position - call within `begin()`/`end()`. prefer using `set_next_window_pos()`, as this may incur tearing and side-effects.
    """
```

:::

::: api-signature

```python
def set_window_pos(
    name: str,
    pos: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window position - call within `begin()`/`end()`. prefer using `set_next_window_pos()`, as this may incur tearing and side-effects.
    """
```

:::

::: api-signature

```python
def set_window_size(
    size: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window size - call within `begin()`/`end()`. set to ImVec2(0, 0) to force an auto-fit. prefer using `set_next_window_size()`, as this may incur tearing and minor side-effects.
    """
```

:::

::: api-signature

```python
def set_window_size(
    name: str,
    size: tuple[float, float],
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window size - call within `begin()`/`end()`. set to ImVec2(0, 0) to force an auto-fit. prefer using `set_next_window_size()`, as this may incur tearing and minor side-effects.
    """
```

:::

::: api-signature

```python
def set_window_collapsed(
    collapsed: bool,
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window collapsed state. prefer using `set_next_window_collapsed()`.
    """
```

:::

::: api-signature

```python
def set_window_collapsed(
    name: str,
    collapsed: bool,
    cond: Cond = Cond.NONE,
) -> None:
    """
    (not recommended) set current window collapsed state. prefer using `set_next_window_collapsed()`.
    """
```

:::

::: api-signature

```python
def set_window_focus() -> None:
    """
    (not recommended) set current window to be focused / top-most. prefer using `set_next_window_focus()`.
    """
```

:::

::: api-signature

```python
def set_window_focus(
    name: str,
) -> None:
    """
    (not recommended) set current window to be focused / top-most. prefer using `set_next_window_focus()`.
    """
```

:::

## Windows Scrolling

* Any change of scroll will be applied at the beginning of next frame in the first call to `begin()`.
* You may instead use `set_next_window_scroll()` prior to calling `begin()` to avoid this delay, as an alternative to using `set_scroll_x()`/`set_scroll_y()`.

### Functions

::: api-signature

```python
def set_next_window_scroll(
    scroll: tuple[float, float],
) -> None:
    """
    Set next window scrolling value (use < 0.0 to not affect a given axis).
    """
```

:::

::: api-signature

```python
def get_scroll_x() -> float:
    """
    Get scrolling amount [0 .. `get_scroll_max_x()`]
    """
```

:::

::: api-signature

```python
def get_scroll_y() -> float:
    """
    Get scrolling amount [0 .. `get_scroll_max_y()`]
    """
```

:::

::: api-signature

```python
def set_scroll_x(
    scroll_x: float,
) -> None:
    """
    Set scrolling amount [0 .. `get_scroll_max_x()`]
    """
```

:::

::: api-signature

```python
def set_scroll_y(
    scroll_y: float,
) -> None:
    """
    Set scrolling amount [0 .. `get_scroll_max_y()`]
    """
```

:::

::: api-signature

```python
def get_scroll_max_x() -> float:
    """
    Get maximum scrolling amount ~~ ContentSize.x - WindowSize.x - DecorationsSize.x
    """
```

:::

::: api-signature

```python
def get_scroll_max_y() -> float:
    """
    Get maximum scrolling amount ~~ ContentSize.y - WindowSize.y - DecorationsSize.y
    """
```

:::

::: api-signature

```python
def set_scroll_here_x(
    center_x_ratio: float = 0.5,
) -> None:
    """
    Adjust scrolling amount to make current cursor position visible. center_x_ratio=0.0: left, 0.5: center, 1.0: right. When using to make a "default/current item" visible, consider using `set_item_default_focus()` instead.
    """
```

:::

::: api-signature

```python
def set_scroll_here_y(
    center_y_ratio: float = 0.5,
) -> None:
    """
    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 `set_item_default_focus()` instead.
    """
```

:::

::: api-signature

```python
def set_scroll_from_pos_x(
    local_x: float,
    center_x_ratio: float = 0.5,
) -> None:
    """
    Adjust scrolling amount to make given position visible. Generally `get_cursor_start_pos()` + offset to compute a valid position.
    """
```

:::

::: api-signature

```python
def set_scroll_from_pos_y(
    local_y: float,
    center_y_ratio: float = 0.5,
) -> None:
    """
    Adjust scrolling amount to make given position visible. Generally `get_cursor_start_pos()` + offset to compute a valid position.
    """
```

:::

## Parameter stacks (shared)

### Functions

::: api-signature

```python
def push_font(
    font: Font | None,
    font_size_base: float,
) -> None:
    """
    Use `None` as a shortcut to keep current font.  Use 0.0 for `font_size_base` to keep the current font size.
    """
```

:::

::: api-signature

```python
def pop_font() -> None:
```

:::

::: api-signature

```python
def push_style_color(
    idx: Col,
    col: int,
) -> None:
    """
    Modify a style color. always use this if you modify the style after `new_frame()`.
    """
```

:::

::: api-signature

```python
def push_style_color(
    idx: Col,
    col: tuple[float, float, float, float],
) -> None:
    """
    Modify a style color. always use this if you modify the style after `new_frame()`.
    """
```

:::

::: api-signature

```python
def push_style_color(
    idx: Col,
    col: tuple[float, float, float],
) -> None:
    """
    Modify a style color. always use this if you modify the style after `new_frame()`.
    """
```

:::

::: api-signature

```python
def pop_style_color(
    count: int = 1,
) -> None:
```

:::

::: api-signature

```python
def push_style_var(
    idx: StyleVar,
    val: float,
) -> None:
    """
    Modify a style float variable. always use this if you modify the style after `new_frame()`!
    """
```

:::

::: api-signature

```python
def push_style_var(
    idx: StyleVar,
    val: tuple[float, float],
) -> None:
    """
    Modify a style float variable. always use this if you modify the style after `new_frame()`!
    """
```

:::

::: api-signature

```python
def push_style_var_x(
    idx: StyleVar,
    val_x: float,
) -> None:
    """
    Modify X component of a style ImVec2 variable. "
    """
```

:::

::: api-signature

```python
def push_style_var_y(
    idx: StyleVar,
    val_y: float,
) -> None:
    """
    Modify Y component of a style ImVec2 variable. "
    """
```

:::

::: api-signature

```python
def pop_style_var(
    count: int = 1,
) -> None:
```

:::

::: api-signature

```python
def push_item_flag(
    option: ItemFlags,
    enabled: bool,
) -> None:
    """
    Modify specified shared item flag, e.g. `push_item_flag(ItemFlags.NO_TAB_STOP, true)`
    """
```

:::

::: api-signature

```python
def pop_item_flag() -> None:
```

:::

::: api-signature

```python
def get_item_flags() -> int:
    """
    Get generic flags of the last item.
    """
```

:::

## Parameter stacks (current window)

### Functions

::: api-signature

```python
def push_item_width(
    item_width: float,
) -> None:
    """
    Push width of items for common large "item+label" widgets. >0.0: width in pixels, <0.0 align xx pixels to the right of window (so -FLT_MIN always align width to the right side).
    """
```

:::

::: api-signature

```python
def pop_item_width() -> None:
```

:::

::: api-signature

```python
def set_next_item_width(
    item_width: float,
) -> None:
    """
    Set width of the _next_ common large "item+label" widget. >0.0: width in pixels, <0.0 align xx pixels to the right of window (so -FLT_MIN always align width to the right side)
    """
```

:::

::: api-signature

```python
def calc_item_width() -> float:
    """
    Width of item given pushed settings and current cursor position. NOT necessarily the width of last item unlike most 'Item' functions.
    """
```

:::

::: api-signature

```python
def push_text_wrap_pos(
    wrap_local_pos_x: float = 0.0,
) -> None:
```

:::

::: api-signature

```python
def pop_text_wrap_pos() -> None:
```

:::

## Style read access

* Use `show_style_editor()` function to interactively see/edit the colors.

### Functions

::: api-signature

```python
def get_font() -> slimgui.slimgui_ext.imgui.Font:
    """
    Get the current font.
    """
```

:::

::: api-signature

```python
def get_font_size() -> float:
    """
    Get current font size (= height in pixels) of current font, with global scale factors applied.

    - Use `style.font_size_base` to get value before global scale factors.
    - recap: `imgui.get_font_size() == style.font_size_base * (style.font_scale_main * style.font_scale_dpi * other_scaling_factors)`
    """
```

:::

Get current font size (= height in pixels) of current font, with global scale factors applied.

* Use `style.font_size_base` to get value before global scale factors.
* recap: `imgui.get_font_size() == style.font_size_base * (style.font_scale_main * style.font_scale_dpi * other_scaling_factors)`

::: api-signature

```python
def get_font_tex_uv_white_pixel() -> tuple[float, float]:
    """
    Get UV coordinate for a white pixel, useful to draw custom shapes via the ImDrawList API
    """
```

:::

::: api-signature

```python
def get_color_u32(
    idx: Col,
    alpha_mul: float = 1.0,
) -> int:
    """
    Retrieve given style color with style alpha applied and optional extra alpha multiplier, packed as a 32-bit value suitable for ImDrawList
    """
```

:::

::: api-signature

```python
def get_color_u32(
    col: tuple[float, float, float, float],
) -> int:
    """
    Retrieve given style color with style alpha applied and optional extra alpha multiplier, packed as a 32-bit value suitable for ImDrawList
    """
```

:::

::: api-signature

```python
def get_color_u32(
    col: int,
    alpha_mul: float = 1.0,
) -> int:
    """
    Retrieve given style color with style alpha applied and optional extra alpha multiplier, packed as a 32-bit value suitable for ImDrawList
    """
```

:::

::: api-signature

```python
def get_style_color_vec4(
    col: Col,
) -> tuple[float, float, float, float]:
    """
    Retrieve style color as stored in ImGuiStyle structure. use to feed back into `push_style_color()`, otherwise use `get_color_u32()` to get style color with style alpha baked in.
    """
```

:::

## Layout cursor positioning

* By "cursor" we mean the current output position.
* The typical widget behavior is to output themselves at the current cursor position, then move the cursor one line down.
* You can call `same_line()` between widgets to undo the last carriage return and output at the right of the preceding widget.
* YOU CAN DO 99% OF WHAT YOU NEED WITH ONLY `get_cursor_screen_pos()` and `get_content_region_avail()`.
* Attention! We currently have inconsistencies between window-local and absolute positions we will aim to fix with future API:
  * Absolute coordinate: `get_cursor_screen_pos()`, `set_cursor_screen_pos()`, all `DrawList` functions. -> this is the preferred way forward.
  * Window-local coordinates: `same_line(offset)`, `get_cursor_pos()`, `set_cursor_pos()`, `get_cursor_start_pos()`, `push_text_wrap_pos()`
  * Window-local coordinates: `get_content_region_max()`, `get_window_content_region_min()`, `get_window_content_region_max()` --> all obsoleted. YOU DON'T NEED THEM.
* `get_cursor_screen_pos()` = `get_cursor_pos()` + `get_window_pos()`. `get_window_pos()` is almost only ever useful to convert from window-local to absolute coordinates. Try not to use it.

### Functions

::: api-signature

```python
def get_cursor_screen_pos() -> tuple[float, float]:
    """
    Cursor position, absolute coordinates. THIS IS YOUR BEST FRIEND (prefer using this rather than `get_cursor_pos()`, also more useful to work with ImDrawList API).
    """
```

:::

::: api-signature

```python
def set_cursor_screen_pos(
    pos: tuple[float, float],
) -> None:
    """
    Cursor position, absolute coordinates. THIS IS YOUR BEST FRIEND.
    """
```

:::

::: api-signature

```python
def get_content_region_avail() -> tuple[float, float]:
    """
    Available space from current position. THIS IS YOUR BEST FRIEND.
    """
```

:::

::: api-signature

```python
def get_cursor_pos() -> tuple[float, float]:
    """
    [window-local] cursor position in window-local coordinates. This is not your best friend.
    """
```

:::

::: api-signature

```python
def get_cursor_pos_x() -> float:
    """
    [window-local] "
    """
```

:::

::: api-signature

```python
def get_cursor_pos_y() -> float:
    """
    [window-local] "
    """
```

:::

::: api-signature

```python
def set_cursor_pos(
    local_pos: tuple[float, float],
) -> None:
    """
    [window-local] "
    """
```

:::

::: api-signature

```python
def set_cursor_pos_x(
    local_x: float,
) -> None:
    """
    [window-local] "
    """
```

:::

::: api-signature

```python
def set_cursor_pos_y(
    local_y: float,
) -> None:
    """
    [window-local] "
    """
```

:::

::: api-signature

```python
def get_cursor_start_pos() -> tuple[float, float]:
    """
    [window-local] initial cursor position, in window-local coordinates. Call `get_cursor_screen_pos()` after `begin()` to get the absolute coordinates version.
    """
```

:::

## Other layout functions

### Functions

::: api-signature

```python
def separator() -> None:
    """
    Separator, generally horizontal. inside a menu bar or in horizontal layout mode, this becomes a vertical separator.
    """
```

:::

::: api-signature

```python
def same_line(
    offset_from_start_x: float = 0.0,
    spacing: float = -1.0,
) -> None:
    """
    Call between widgets or groups to layout them horizontally. X position given in window coordinates.
    """
```

:::

::: api-signature

```python
def new_line() -> None:
    """
    Undo a `same_line()` or force a new line when in a horizontal-layout context.
    """
```

:::

::: api-signature

```python
def spacing() -> None:
    """
    Add vertical spacing.
    """
```

:::

::: api-signature

```python
def dummy(
    size: tuple[float, float],
) -> None:
    """
    Add a dummy item of given size. unlike `invisible_button()`, `dummy()` won't take the mouse click or be navigable into.
    """
```

:::

::: api-signature

```python
def indent(
    indent_w: float = 0.0,
) -> None:
    """
    Move content position toward the right, by indent_w, or style.IndentSpacing if indent_w <= 0
    """
```

:::

::: api-signature

```python
def unindent(
    indent_w: float = 0.0,
) -> None:
    """
    Move content position back to the left, by indent_w, or style.IndentSpacing if indent_w <= 0
    """
```

:::

::: api-signature

```python
def begin_group() -> None:
    """
    Lock horizontal starting position
    """
```

:::

::: api-signature

```python
def end_group() -> None:
    """
    Unlock horizontal starting position + capture the whole group bounding box into one "item" (so you can use `is_item_hovered()` or layout primitives such as `same_line()` on whole group, etc.)
    """
```

:::

::: api-signature

```python
def align_text_to_frame_padding() -> None:
    """
    Vertically align upcoming text baseline to FramePadding.y so that it will align properly to regularly framed items (call if you have text on a line before a framed item)
    """
```

:::

::: api-signature

```python
def get_text_line_height() -> float:
    """
    ~ FontSize
    """
```

:::

::: api-signature

```python
def get_text_line_height_with_spacing() -> float:
    """
    ~ FontSize + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of text)
    """
```

:::

::: api-signature

```python
def get_frame_height() -> float:
    """
    ~ FontSize + style.FramePadding.y * 2
    """
```

:::

::: api-signature

```python
def get_frame_height_with_spacing() -> float:
    """
    ~ FontSize + style.FramePadding.y * 2 + style.ItemSpacing.y (distance in pixels between 2 consecutive lines of framed widgets)
    """
```

:::

## ID stack/scopes

Read the FAQ (docs/FAQ.md or http://dearimgui.com/faq) for more details about how ID are handled in dear imgui.

Those questions are answered and impacted by understanding of the ID stack system:

* "Q: Why is my widget not reacting when I click on it?"
* "Q: How can I have widgets with an empty label?"
* "Q: How can I have multiple widgets with the same label?"

Short version: ID are hashes of the entire ID stack. If you are creating widgets in a loop you most likely want to push a unique identifier (e.g. object pointer, loop index) to uniquely differentiate them.

You can also use the `"Label##foobar"` syntax within widget label to distinguish them from each others.

In this header file we use the `label`/`name` terminology to denote a string that will be displayed + used as an ID, whereas `str_id` denote a string that is only used as an ID and not normally displayed.

### Functions

::: api-signature

```python
def push_id(
    str_id: str,
) -> None:
    """
    Push string into the ID stack (will hash string).
    """
```

:::

::: api-signature

```python
def push_id(
    int_id: int,
) -> None:
    """
    Push string into the ID stack (will hash string).
    """
```

:::

::: api-signature

```python
def pop_id() -> None:
    """
    Pop from the ID stack.
    """
```

:::

::: api-signature

```python
def get_id(
    str_id: str,
) -> None:
    """
    Calculate unique ID (hash of whole ID stack + given parameter). e.g. if you want to query into ImGuiStorage yourself
    """
```

:::

::: api-signature

```python
def get_id(
    int_id: int,
) -> None:
    """
    Calculate unique ID (hash of whole ID stack + given parameter). e.g. if you want to query into ImGuiStorage yourself
    """
```

:::

## Widgets: Text

### Functions

::: api-signature

```python
def text(
    text: str,
) -> None:
    """
    Formatted text
    """
```

:::

::: api-signature

```python
def text_colored(
    col: tuple[float, float, float, float],
    text: str,
) -> None:
```

:::

::: api-signature

```python
def text_disabled(
    text: str,
) -> None:
```

:::

::: api-signature

```python
def text_wrapped(
    text: str,
) -> None:
```

:::

::: api-signature

```python
def label_text(
    label: str,
    text: str,
) -> None:
    """
    Display text+label aligned the same way as value+label widgets
    """
```

:::

::: api-signature

```python
def bullet_text(
    text: str,
) -> None:
    """
    Shortcut for `bullet()`+`text()`
    """
```

:::

::: api-signature

```python
def separator_text(
    text: str,
) -> None:
    """
    Currently: formatted text with a horizontal line
    """
```

:::

## Widgets: Main

* Most widgets return `True` when the value has been changed or when pressed/selected.
* You may also use one of the many `is_item_xxx` functions (e.g. `is_item_active()`, `is_item_hovered()`, etc.) to query widget state.

### Functions

::: api-signature

```python
def button(
    label: str,
    size: tuple[float, float] = (0.0, 0.0),
) -> bool:
    """
    Button
    """
```

:::

::: api-signature

```python
def small_button(
    label: str,
) -> bool:
    """
    Button with (FramePadding.y == 0) to easily embed within text
    """
```

:::

::: api-signature

```python
def invisible_button(
    str_id: str,
    size: tuple[float, float],
    flags: ButtonFlags = ButtonFlags.NONE,
) -> bool:
    """
    Flexible button behavior without the visuals, frequently useful to build custom behaviors using the public api (along with `is_item_active`, `is_item_hovered`, etc.)
    """
```

:::

::: api-signature

```python
def arrow_button(
    str_id: str,
    dir: Dir,
) -> bool:
    """
    Square button with an arrow shape
    """
```

:::

::: api-signature

```python
def checkbox(
    label: str,
    v: bool,
) -> tuple[bool, bool]:
```

:::

::: api-signature

```python
def checkbox_flags(
    label: str,
    flags: int,
    flags_value: int,
) -> tuple[bool, int]:
```

:::

::: api-signature

```python
def radio_button(
    label: str,
    active: bool,
) -> bool:
```

:::

::: api-signature

```python
def radio_button(
    label: str,
    v: int,
    v_button: int,
) -> tuple[bool, int]:
```

:::

::: api-signature

```python
def progress_bar(
    fraction: float,
    size_arg: tuple[float, float] = (-FLT_MIN, 0),
    overlay: str | None = None,
) -> None:
```

:::

::: api-signature

```python
def bullet() -> None:
    """
    Draw a small circle + keep the cursor on the same line. advance cursor x position by `get_tree_node_to_label_spacing()`, same distance that `tree_node()` uses
    """
```

:::

::: api-signature

```python
def text_link(
    label: str,
) -> None:
    """
    Hyperlink text button, return true when clicked
    """
```

:::

::: api-signature

```python
def text_link_open_url(
    label: str,
    url: str | None = None,
) -> None:
    """
    Hyperlink text button, automatically open file/url when clicked
    """
```

:::

## Widgets: Images

* Read about texture IDs and TextureRef in ImGui docs: [Image Loading and Displaying Examples](https://github.com/ocornut/imgui/wiki/Image-Loading-and-Displaying-Examples)
  * In general, you shouldn't need to worry about `TextureRef` -- all image functions also accept an integer texture ID.
* `uv0` and `uv1` are texture coordinates. Read about them from the same link above.
  * `image()` pads adds `StyleVar.IMAGE_BORDER_SIZE` on each side, `image_button()` adds `StyleVar.FRAME_PADDING` on each side.
  * `image_button()` draws a background based on regular `button()` color and optionally an inner background if specified.

### Functions

::: api-signature

```python
def image(
    tex_ref: TextureRef | int,
    image_size: tuple[float, float],
    uv0: tuple[float, float] = (0.0, 0.0),
    uv1: tuple[float, float] = (1.0, 1.0),
) -> None:
```

:::

::: api-signature

```python
def image_with_bg(
    tex_ref: TextureRef | int,
    image_size: tuple[float, float],
    uv0: tuple[float, float] = (0.0, 0.0),
    uv1: tuple[float, float] = (1.0, 1.0),
    bg_col: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
    tint_col: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0),
) -> None:
```

:::

::: api-signature

```python
def image_button(
    str_id: str,
    tex_ref: TextureRef | int,
    image_size: tuple[float, float],
    uv0: tuple[float, float] = (0.0, 0.0),
    uv1: tuple[float, float] = (1.0, 1.0),
    bg_col: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
    tint_col: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0),
) -> bool:
```

:::

## Widgets: Combo Box (Dropdown)

* The `begin_combo()`/`end_combo()` API allows you to manage your contents and selection state however you want it, by creating e.g. `selectable()` items.
* The old `combo()` API are helpers over `begin_combo()`/`end_combo()` which are kept available for convenience purposes. This is analogous to how `list_box` is created.

### Functions

::: api-signature

```python
def begin_combo(
    label: str,
    preview_value: str,
    flags: ComboFlags = ComboFlags.NONE,
) -> bool:
```

:::

::: api-signature

```python
def end_combo() -> None:
    """
    Only call `end_combo()` if `begin_combo()` returns true!
    """
```

:::

::: api-signature

```python
def combo(
    label: str,
    current_item: int,
    items: Sequence[str],
    popup_max_height_in_items: int = -1,
) -> tuple[bool, int]:
```

:::

## Widgets: Drag Sliders

* CTRL+Click on any drag box to turn them into an input box. Manually input values aren't clamped by default and can go off-bounds. Use `SliderFlags.ALWAYS_CLAMP` to always clamp.
* Adjust format string to decorate the value with a prefix, a suffix, or adapt the editing and display precision e.g. `"%.3f"` -> `1.234`; `"%5.2f secs"` -> `01.23 secs`; `"Biscuit: %.0f"` -> `Biscuit: 1`; etc.
* Format string may also be set to `None` or use the default format (`"%f"` or `"%d"`).
* Speed is per-pixel of mouse movement (`v_speed=0.2`: mouse needs to move by 5 pixels to increase value by 1). For keyboard/gamepad navigation, minimum speed is `max(v_speed, minimum_step_at_given_precision)`.
* Use `v_min < v_max` to clamp edits to given limits. Note that CTRL+Click manual input can override those limits if `SliderFlags.ALWAYS_CLAMP` is not used.
* Use `v_max = FLT_MAX` / `INT_MAX` etc. to avoid clamping to a maximum, same with `v_min = -FLT_MAX` / `INT_MIN` to avoid clamping to a minimum.
* We use the same sets of flags for `drag_xxx()` and `slider_xxx()` functions as the features are the same and it makes it easier to swap them.

### Functions

::: api-signature

```python
def drag_float(
    label: str,
    v: float,
    v_speed: float = 1.0,
    v_min: float = 0.0,
    v_max: float = 0.0,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, float]:
    """
    If v_min >= v_max we have no bound
    """
```

:::

::: api-signature

```python
def drag_float2(
    label: str,
    v: tuple[float, float],
    v_speed: float = 1.0,
    v_min: float = 0.0,
    v_max: float = 0.0,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[float, float]]:
```

:::

::: api-signature

```python
def drag_float3(
    label: str,
    v: tuple[float, float, float],
    v_speed: float = 1.0,
    v_min: float = 0.0,
    v_max: float = 0.0,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[float, float, float]]:
```

:::

::: api-signature

```python
def drag_float4(
    label: str,
    v: tuple[float, float, float, float],
    v_speed: float = 1.0,
    v_min: float = 0.0,
    v_max: float = 0.0,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[float, float, float, float]]:
```

:::

::: api-signature

```python
def drag_float_range2(
    label: str,
    v_current_min: float,
    v_current_max: float,
    v_speed: float = 1.0,
    v_min: float = 0.0,
    v_max: float = 0.0,
    format: str = '%.3f',
    format_max: str | None = None,
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, float, float]:
```

:::

::: api-signature

```python
def drag_int(
    label: str,
    v: int,
    v_speed: float = 1.0,
    v_min: int = 0,
    v_max: int = 0,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, int]:
    """
    If v_min >= v_max we have no bound
    """
```

:::

::: api-signature

```python
def drag_int2(
    label: str,
    v: tuple[int, int],
    v_speed: float = 1.0,
    v_min: int = 0,
    v_max: int = 0,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[int, int]]:
```

:::

::: api-signature

```python
def drag_int3(
    label: str,
    v: tuple[int, int, int],
    v_speed: float = 1.0,
    v_min: int = 0,
    v_max: int = 0,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[int, int, int]]:
```

:::

::: api-signature

```python
def drag_int4(
    label: str,
    v: tuple[int, int, int, int],
    v_speed: float = 1.0,
    v_min: int = 0,
    v_max: int = 0,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[int, int, int, int]]:
```

:::

::: api-signature

```python
def drag_int_range2(
    label: str,
    v_current_min: int,
    v_current_max: int,
    v_speed: float = 1.0,
    v_min: int = 0,
    v_max: int = 0,
    format: str = '%d',
    format_max: str | None = None,
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, int, int]:
```

:::

## Widgets: Regular Sliders

* CTRL+Click on any slider to turn it into an input box. Manually input values aren't clamped by default and can go off-bounds. Use `SliderFlags.ALWAYS_CLAMP` to always clamp.
* Adjust the format string to decorate the value with a prefix, a suffix, or adapt the editing and display precision, e.g., `"%.3f"` -> `1.234`; `"%5.2f secs"` -> `01.23 secs`; `"Biscuit: %.0f"` -> `Biscuit: 1`; etc.
* The format string may also be set to `None` or use the default format (`"%f"` or `"%d"`).

### Functions

::: api-signature

```python
def slider_float(
    label: str,
    v: float,
    v_min: float,
    v_max: float,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, float]:
    """
    Adjust format to decorate the value with a prefix or a suffix for in-slider labels or unit display.
    """
```

:::

::: api-signature

```python
def slider_float2(
    label: str,
    v: tuple[float, float],
    v_min: float,
    v_max: float,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[float, float]]:
```

:::

::: api-signature

```python
def slider_float3(
    label: str,
    v: tuple[float, float, float],
    v_min: float,
    v_max: float,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[float, float, float]]:
```

:::

::: api-signature

```python
def slider_float4(
    label: str,
    v: tuple[float, float, float, float],
    v_min: float,
    v_max: float,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[float, float, float, float]]:
```

:::

::: api-signature

```python
def slider_angle(
    label: str,
    v: float,
    v_degrees_min: float = -360.0,
    v_degrees_max: float = 360.0,
    format: str = '%.0f deg',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, float]:
```

:::

::: api-signature

```python
def slider_int(
    label: str,
    v: int,
    v_min: int,
    v_max: int,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, int]:
```

:::

::: api-signature

```python
def slider_int2(
    label: str,
    v: tuple[int, int],
    v_min: int,
    v_max: int,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[int, int]]:
```

:::

::: api-signature

```python
def slider_int3(
    label: str,
    v: tuple[int, int, int],
    v_min: int,
    v_max: int,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[int, int, int]]:
```

:::

::: api-signature

```python
def slider_int4(
    label: str,
    v: tuple[int, int, int, int],
    v_min: int,
    v_max: int,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, tuple[int, int, int, int]]:
```

:::

::: api-signature

```python
def vslider_float(
    label: str,
    size: tuple[float, float],
    v: float,
    v_min: float,
    v_max: float,
    format: str = '%.3f',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, float]:
```

:::

::: api-signature

```python
def vslider_int(
    label: str,
    size: tuple[float, float],
    v: int,
    v_min: int,
    v_max: int,
    format: str = '%d',
    flags: SliderFlags = SliderFlags.NONE,
) -> tuple[bool, int]:
```

:::

## Widgets: Input with Keyboard

* Most of the `InputTextFlags` flags are only useful for `input_text()` and not for `input_float_*`, `input_float_*`, `input_int_*`, etc.

### Functions

::: api-signature

```python
def input_text(
    label: str,
    text: str,
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, str]:
```

:::

::: api-signature

```python
def input_text_multiline(
    label: str,
    text: str,
    size: tuple[float, float] = (0.0, 0.0),
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, str]:
```

:::

::: api-signature

```python
def input_text_with_hint(
    label: str,
    hint: str,
    text: str,
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, str]:
```

:::

::: api-signature

```python
def input_float(
    label: str,
    v: float,
    step: float = 0.0,
    step_fast: float = 0.0,
    format: str = '%.3f',
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, float]:
```

:::

::: api-signature

```python
def input_float2(
    label: str,
    v: tuple[float, float],
    format: str = '%.3f',
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, tuple[float, float]]:
```

:::

::: api-signature

```python
def input_float3(
    label: str,
    v: tuple[float, float, float],
    format: str = '%.3f',
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, tuple[float, float, float]]:
```

:::

::: api-signature

```python
def input_float4(
    label: str,
    v: tuple[float, float, float, float],
    format: str = '%.3f',
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, tuple[float, float, float, float]]:
```

:::

::: api-signature

```python
def input_int(
    label: str,
    v: int,
    step: int = 1,
    step_fast: int = 100,
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, int]:
```

:::

::: api-signature

```python
def input_int2(
    label: str,
    v: tuple[int, int],
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, tuple[int, int]]:
```

:::

::: api-signature

```python
def input_int3(
    label: str,
    v: tuple[int, int, int],
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, tuple[int, int, int]]:
```

:::

::: api-signature

```python
def input_int4(
    label: str,
    v: tuple[int, int, int, int],
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, tuple[int, int, int, int]]:
```

:::

::: api-signature

```python
def input_double(
    label: str,
    v: float,
    step: float = 0.0,
    step_fast: float = 0.0,
    format: str = '%.6f',
    flags: InputTextFlags = InputTextFlags.NONE,
) -> tuple[bool, float]:
```

:::

## Widgets: Color Editor/Picker

Tip: the `color_edit_*` functions have a little color square that can be left-clicked to open a picker, and right-clicked to open an option menu.

### Functions

::: api-signature

```python
def color_edit3(
    label: str,
    col: tuple[float, float, float],
    flags: ColorEditFlags = ColorEditFlags.NONE,
) -> tuple[bool, tuple[float, float, float]]:
```

:::

::: api-signature

```python
def color_edit4(
    label: str,
    col: tuple[float, float, float, float],
    flags: ColorEditFlags = ColorEditFlags.NONE,
) -> tuple[bool, tuple[float, float, float, float]]:
```

:::

::: api-signature

```python
def color_picker3(
    label: str,
    col: tuple[float, float, float],
    flags: ColorEditFlags = ColorEditFlags.NONE,
) -> tuple[bool, tuple[float, float, float]]:
```

:::

::: api-signature

```python
def color_picker4(
    label: str,
    col: tuple[float, float, float, float],
    flags: ColorEditFlags = ColorEditFlags.NONE,
    ref_col: tuple[float, float, float, float] | None = None,
) -> tuple[bool, tuple[float, float, float, float]]:
```

:::

::: api-signature

```python
def color_button(
    desc_id: str,
    col: tuple[float, float, float, float],
    flags: ColorEditFlags = ColorEditFlags.NONE,
    size: tuple[float, float] = (0.0, 0.0),
) -> bool:
    """
    Display a color square/button, hover for details, return true when pressed.
    """
```

:::

::: api-signature

```python
def set_color_edit_options(
    flags: ColorEditFlags,
) -> None:
    """
    Initialize current options (generally on application startup) if you want to select a default format, picker type, etc. User will be able to change many settings, unless you pass the _NoOptions flag to your calls.
    """
```

:::

## Widgets: Trees

* `tree_node` functions return `True` when the node is open, in which case you need to also call `tree_pop()` when you are finished displaying the tree node contents.

### Functions

::: api-signature

```python
def tree_node(
    label: str,
    flags: TreeNodeFlags = TreeNodeFlags.NONE,
) -> bool:
```

:::

::: api-signature

```python
def tree_node(
    str_id: str,
    text: str,
    flags: TreeNodeFlags = TreeNodeFlags.NONE,
) -> bool:
```

:::

::: api-signature

```python
def tree_push(
    str_id: str,
) -> None:
    """
    ~ `indent()`+`push_id()`. Already called by `tree_node()` when returning true, but you can call `tree_push`/`tree_pop` yourself if desired.
    """
```

:::

::: api-signature

```python
def tree_pop() -> None:
    """
    ~ `unindent()`+`pop_id()`
    """
```

:::

::: api-signature

```python
def get_tree_node_to_label_spacing() -> float:
    """
    Horizontal distance preceding label when using `tree_node`*() or `bullet()` == (g.FontSize + style.FramePadding.x*2) for a regular unframed `tree_node`
    """
```

:::

::: api-signature

```python
def collapsing_header(
    label: str,
    visible: bool | None = None,
    flags: TreeNodeFlags = TreeNodeFlags.NONE,
) -> tuple[bool, bool | None]:
    """
    If returning 'true' the header is open. doesn't indent nor push on ID stack. user doesn't have to call `tree_pop()`.
    """
```

:::

::: api-signature

```python
def set_next_item_open(
    is_open: bool,
    cond: Cond = Cond.NONE,
) -> None:
    """
    Set next `tree_node`/`collapsing_header` open state.
    """
```

:::

## Widgets: Selectables

* A selectable highlights when hovered, and can display another color when selected.
* Neighbors selectable extend their highlight bounds in order to leave no gap between them. This is so a series of selected `selectable` appear contiguous.

### Functions

::: api-signature

```python
def selectable(
    label: str,
    selected: bool = False,
    flags: SelectableFlags = SelectableFlags.NONE,
    size: tuple[float, float] = (0.0, 0.0),
) -> tuple[bool, bool]:
    """
    The `selected` argument indicates whether the item is selected or not.

    When `size[0] == 0.0` use remaining width.  Use `size[0] > 0.0` to specify width.
    When `size[1] == 0.0` use label height.  Use `size[1] > 0.0` to specify height.

    The returned pair contains:

    - first element: a boolean indicating whether the item was clicked.
    - second element: the updated selection state of the item.
    """
```

:::

## Multi-selection system for `selectable()`, `checkbox()`, `tree_node()` functions \[BETA]

*TODO* Multi-selection is currently NOT supported in Slimgui.  [Issue #16](https://github.com/nurpax/slimgui/issues/16) tracks this implementation.

* This enables standard multi-selection/range-selection idioms (CTRL+Mouse/Keyboard, SHIFT+Mouse/Keyboard, etc.) in a way that also allows a clipper to be used.
* `SelectionUserData` is often used to store your item index within the current view (but may store something else).
* Read comments near `MultiSelectIO` for instructions/details and see 'Demo->Widgets->Selection State & Multi-Select' for demo.
* `tree_node()` is technically supported but... using this correctly is more complicated. You need some sort of linear/random access to your tree, which is suited to advanced tree setups already implementing filters and clipper. We will work on simplifying the current demo.
* `selection_size` and `items_count` parameters are optional and used by a few features. If they are costly for you to compute, you may avoid them.

## Widgets: List Boxes

* This is essentially a thin wrapper to using `begin_child()`/`end_child()` with the `ChildFlags.FRAME_STYLE` flag for stylistic changes and displaying a label.
* If you don't need a label, you can probably simply use `begin_child()` with the `ChildFlags.FRAME_STYLE` flag for the same result.
* You can submit contents and manage your selection state however you want, by creating e.g. `selectable()` or any other items.
* The simplified/old `list_box()` API are helpers over `begin_list_box()`/`end_list_box()` which are kept available for convenience purposes. This is analogous to how combos are created.
* Choose frame width:
  * `size.x > 0`: custom
  * `size.x < 0` or `-FLT_MIN`: right-align
  * `size.x = 0` (default): use current `item_width`
* Choose frame height:
  * `size.y > 0`: custom
  * `size.y < 0` or `-FLT_MIN`: bottom-align
  * `size.y = 0` (default): arbitrary default height which can fit ~7 items

### Functions

::: api-signature

```python
def begin_list_box(
    label: str,
    size: tuple[float, float] = (0.0, 0.0),
) -> bool:
    """
    Open a framed scrolling region
    """
```

:::

::: api-signature

```python
def end_list_box() -> None:
    """
    Only call `end_list_box()` if `begin_list_box()` returned true!
    """
```

:::

::: api-signature

```python
def list_box(
    label: str,
    current_item: int,
    items: Sequence[str],
    height_in_items: int = -1,
) -> tuple[bool, int]:
```

:::

## Widgets: Data Plotting

Consider using [ImPlot](https://github.com/epezent/implot) which is much better! Slimgui includes ImPlot bindings; see the [Slimgui ImPlot API reference](/api/implot) for details.

### Functions

::: api-signature

```python
def plot_lines(
    label: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), device='cpu', writable=False)],
    overlay_text: str | None = None,
    scale_min: float = FLT_MAX,
    scale_max: float = FLT_MAX,
    graph_size: tuple[float, float] = (0.0, 0.0),
) -> None:
```

:::

::: api-signature

```python
def plot_histogram(
    label: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), device='cpu', writable=False)],
    overlay_text: str | None = None,
    scale_min: float = FLT_MAX,
    scale_max: float = FLT_MAX,
    graph_size: tuple[float, float] = (0.0, 0.0),
) -> None:
```

:::

## Widgets: Value() Helpers

These are merely shortcuts to calling `text()` with a format string. Output single value in "name: value" format.

### Functions

## Widgets: Menus

* Use `begin_menu_bar()` on a window `WindowFlags.MENU_BAR` to append to its menu bar.
* Use `begin_main_menu_bar()` to create a menu bar at the top of the screen and append to it.
* Use `begin_menu()` to create a menu. You can call `begin_menu()` multiple times with the same identifier to append more items to it.
* Note that `menu_item()` keyboard shortcuts are displayed as a convenience but *not processed* by Dear ImGui at the moment.

### Functions

::: api-signature

```python
def begin_menu_bar() -> bool:
    """
    Append to menu-bar of current window (requires `WindowFlags.MENU_BAR` flag set on parent window).
    """
```

:::

::: api-signature

```python
def end_menu_bar() -> None:
    """
    Only call `end_menu_bar()` if `begin_menu_bar()` returns true!
    """
```

:::

::: api-signature

```python
def begin_main_menu_bar() -> bool:
    """
    Create and append to a full screen menu-bar.
    """
```

:::

::: api-signature

```python
def end_main_menu_bar() -> None:
    """
    Only call `end_main_menu_bar()` if `begin_main_menu_bar()` returns true!
    """
```

:::

::: api-signature

```python
def begin_menu(
    label: str,
    enabled: bool = True,
) -> bool:
    """
    Create a sub-menu entry. only call `end_menu()` if this returns true!
    """
```

:::

::: api-signature

```python
def end_menu() -> None:
    """
    Only call `end_menu()` if `begin_menu()` returns true!
    """
```

:::

::: api-signature

```python
def menu_item(
    label: str,
    shortcut: str | None = None,
    selected: bool = False,
    enabled: bool = True,
) -> tuple[bool, bool]:
    """
    Return true when activated.
    """
```

:::

## Tooltips

* Tooltips are windows following the mouse. They do not take focus away.
* A tooltip window can contain items of any types.
* `set_tooltip()` is more or less a shortcut for the below idiom  (with a subtlety that it discards any previously submitted tooltip):
  ```
  if begin_tooltip():
      text(...)
      end_tooltip()
  ```

::: api-signature

```python
def begin_tooltip() -> bool:
    """
    Begin/append a tooltip window.
    """
```

:::

::: api-signature

```python
def end_tooltip() -> None:
    """
    Only call `end_tooltip()` if `begin_tooltip()`/`begin_item_tooltip()` returns true!
    """
```

:::

::: api-signature

```python
def set_tooltip(
    text: str,
) -> None:
    """
    Set a text-only tooltip. Often used after a `is_item_hovered()` check. Override any previous call to `set_tooltip()`.
    """
```

:::

## Tooltip helpers

Tooltip helpers for showing a tooltip when hovering an item:

* `begin_item_tooltip()` is a shortcut for the `if is_item_hovered(HoveredFlags.FOR_TOOLTIP) and begin_tooltip()` idiom.
* `set_item_tooltip()` is a shortcut for the `if is_item_hovered(HoveredFlags.FOR_TOOLTIP): set_tooltip(...)` idiom.
* Where `HoveredFlags.FOR_TOOLTIP` itself is a shortcut to use `Style.hover_flags_for_tooltip_mouse` or `Style.hover_flags_for_tooltip_nav` depending on the active input type. For mouse, it defaults to `HoveredFlags.STATIONARY | HoveredFlags.DELAY_SHORT`.

### Functions

::: api-signature

```python
def begin_item_tooltip() -> bool:
    """
    Begin/append a tooltip window if preceding item was hovered.
    """
```

:::

::: api-signature

```python
def set_item_tooltip(
    text: str,
) -> None:
    """
    Set a text-only tooltip if preceding item was hovered. override any previous call to `set_tooltip()`.
    """
```

:::

## Popups, Modals

* Popups and modals block normal mouse hovering detection (and therefore most mouse interactions) behind them.
* If not modal: they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
* Their visibility state (~bool) is held internally instead of being held by the programmer as we are used to with regular `begin_*()` calls.
* The 3 properties above are related: we need to retain popup visibility state in the library because popups may be closed at any time.
* You can bypass the hovering restriction by using `HoveredFlags.ALLOW_WHEN_BLOCKED_BY_POPUP` when calling `is_item_hovered()` or `is_window_hovered()`.
* IMPORTANT: Popup identifiers are relative to the current ID stack, so `open_popup()` and `begin_popup()` generally need to be at the same level of the stack. This sometimes leads to confusing mistakes. May rework this in the future.
* `begin_popup()`: query popup state, if open start appending into the window. Call `end_popup()` afterwards if returned true. `WindowFlags` are forwarded to the window.
* `begin_popup_modal()`: block every interaction behind the window, cannot be closed by user, add a dimming background, has a title bar.

### Functions

::: api-signature

```python
def begin_popup(
    str_id: str,
    flags: WindowFlags = WindowFlags.NONE,
) -> bool:
    """
    Return true if the popup is open, and you can start outputting to it.
    """
```

:::

::: api-signature

```python
def begin_popup_modal(
    str_id: str,
    closable: bool = False,
    flags: WindowFlags = WindowFlags.NONE,
) -> tuple[bool, bool]:
    """
    Returns a tuple of bools.  If the first returned bool is `True`, the modal is open and you can start outputting to it.
    """
```

:::

::: api-signature

```python
def end_popup() -> None:
    """
    Only call `end_popup()` if BeginPopupXXX() returns true!
    """
```

:::

## Popups: open/close functions

* `open_popup()`: set popup state to open. `PopupFlags` are available for opening options.
* If not modal: they can be closed by clicking anywhere outside them, or by pressing ESCAPE.
* `close_current_popup()`: use inside the `begin_popup()`/`end_popup()` scope to close manually.
* `close_current_popup()` is called by default by `selectable()`/`menu_item()` when activated.
* Use `PopupFlags.NO_OPEN_OVER_EXISTING_POPUP` to avoid opening a popup if there's already one at the same level. This is equivalent to e.g. testing for `not is_any_popup_open()` prior to `open_popup()`.
* Use `is_window_appearing()` after `begin_popup()` to tell if a window just opened.

### Functions

::: api-signature

```python
def open_popup(
    str_id: str,
    flags: PopupFlags = PopupFlags.NONE,
) -> None:
    """
    Call to mark popup as open (don't call every frame!).
    """
```

:::

::: api-signature

```python
def open_popup_on_item_click(
    str_id: str | None = None,
    flags: PopupFlags = PopupFlags.MOUSE_BUTTON_RIGHT,
) -> None:
    """
    Helper to open popup when clicked on last item. Default to `PopupFlags.MOUSE_BUTTON_RIGHT` == 1. (note: actually triggers on the mouse _released_ event to be consistent with popup behaviors)
    """
```

:::

::: api-signature

```python
def close_current_popup() -> None:
    """
    Manually close the popup we have begin-ed into.
    """
```

:::

## Popups: open+begin combined functions helpers

* Helpers to do `open_popup()` + `begin_popup()` where the open action is triggered by, e.g., hovering an item and right-clicking.
* They are convenient to easily create context menus, hence the name.
* IMPORTANT: Notice that `begin_popup_context_xxx()` takes `PopupFlags` just like `open_popup()` and unlike `begin_popup()`. For full consistency, we may add `WindowFlags` to the `begin_popup_context_xxx()` functions in the future.

### Functions

::: api-signature

```python
def begin_popup_context_item(
    str_id: str | None = None,
    flags: PopupFlags = PopupFlags.MOUSE_BUTTON_RIGHT,
) -> bool:
    """
    Open+begin popup when clicked on last item. Use str_id==NULL to associate the popup to previous item. If you want to use that on a non-interactive item such as `text()` you need to pass in an explicit ID here. read comments in .cpp!
    """
```

:::

::: api-signature

```python
def begin_popup_context_window(
    str_id: str | None = None,
    flags: PopupFlags = PopupFlags.MOUSE_BUTTON_RIGHT,
) -> bool:
    """
    Open+begin popup when clicked on current window.
    """
```

:::

::: api-signature

```python
def begin_popup_context_void(
    str_id: str | None = None,
    flags: PopupFlags = PopupFlags.MOUSE_BUTTON_RIGHT,
) -> bool:
    """
    Open+begin popup when clicked in void (where there are no windows).
    """
```

:::

## Popups: query functions

* `is_popup_open()`: return true if the popup is open at the current `begin_popup()` level of the popup stack.
* `is_popup_open()` with `PopupFlags.ANY_POPUP_ID`: return true if any popup is open at the current `begin_popup()` level of the popup stack.
* `is_popup_open()` with `PopupFlags.ANY_POPUP_ID` + `PopupFlags.ANY_POPUP_LEVEL`: return true if any popup is open.

### Functions

::: api-signature

```python
def is_popup_open(
    str_id: str,
    flags: PopupFlags = PopupFlags.NONE,
) -> bool:
    """
    Return true if the popup is open.
    """
```

:::

## Tables

* Full-featured replacement for old Columns API.
* See Demo->Tables for demo code. See top of imgui\_tables.cpp for general commentary.
* See `TableFlags` and `TableColumnFlags` enums for a description of available flags.

The typical call flow is:

1. Call `begin_table()`, early out if returning `False`.
2. Optionally call `table_setup_column()` to submit column name/flags/defaults.
3. Optionally call `table_setup_scroll_freeze()` to request scroll freezing of columns/rows.
4. Optionally call `table_headers_row()` to submit a header row. Names are pulled from `table_setup_column()` data.
5. Populate contents:

* In most situations you can use `table_next_row()` + `table_set_column_index(N)` to start appending into a column.
* If you are using tables as a sort of grid, where every column is holding the same type of contents, you may prefer using `table_next_column()` instead of `table_next_row()` + `table_set_column_index()`. `table_next_column()` will automatically wrap-around into the next row if needed.
* IMPORTANT: Comparatively to the old `columns()` API, we need to call `table_next_column()` for the first column!
* Summary of possible call flow:
  * `table_next_row()` -> `table_set_column_index(0)` -> `text("Hello 0")` -> `table_set_column_index(1)` -> `text("Hello 1")`  // OK
  * `table_next_row()` -> `table_next_column()` -> `text("Hello 0")` -> `table_next_column()` -> `text("Hello 1")`  // OK
  * `table_next_column()` -> `text("Hello 0")` -> `table_next_column()` -> `text("Hello 1")`  // OK: `table_next_column()` automatically gets to next row!
  * `table_next_row()` -> `text("Hello 0")`  // Not OK! Missing `table_set_column_index()` or `table_next_column()`! Text will not appear!

6. Call `end_table()`

### Functions

::: api-signature

```python
def begin_table(
    str_id: str,
    column: int,
    flags: TableFlags = TableFlags.NONE,
    outer_size: tuple[float, float] = (0.0, 0.0),
    inner_width: float = 0.0,
) -> bool:
```

:::

::: api-signature

```python
def end_table() -> None:
    """
    Only call `end_table()` if `begin_table()` returns true!
    """
```

:::

::: api-signature

```python
def table_next_row(
    flags: TableRowFlags = TableRowFlags.NONE,
    min_row_height: float = 0.0,
) -> None:
    """
    Append into the first cell of a new row. 'min_row_height' include the minimum top and bottom padding aka CellPadding.y * 2.0.
    """
```

:::

::: api-signature

```python
def table_next_column() -> bool:
    """
    Append into the next column (or first column of next row if currently in last column). Return true when column is visible.
    """
```

:::

::: api-signature

```python
def table_set_column_index(
    column_n: int,
) -> bool:
    """
    Append into the specified column. Return true when column is visible.
    """
```

:::

## Tables: Headers & Columns declaration

* Use `table_setup_column()` to specify label, resizing policy, default width/weight, id, various other flags, etc.
* Use `table_headers_row()` to create a header row and automatically submit a `table_header()` for each column.
  Headers are required to perform: reordering, sorting, and opening the context menu.
  The context menu can also be made available in columns body using `TableFlags.CONTEXT_MENU_IN_BODY`.
* You may manually submit headers using `table_next_row()` + `table_header()` calls, but this is only useful in
  some advanced use cases (e.g., adding custom widgets in header row).
* Use `table_setup_scroll_freeze()` to lock columns/rows so they stay visible when scrolled.

### Functions

::: api-signature

```python
def table_setup_column(
    label: str,
    flags: TableColumnFlags = TableColumnFlags.NONE,
    init_width_or_weight: float = 0.0,
    user_id: int = 0,
) -> None:
```

:::

::: api-signature

```python
def table_setup_scroll_freeze(
    cols: int,
    rows: int,
) -> None:
    """
    Lock columns/rows so they stay visible when scrolled.
    """
```

:::

::: api-signature

```python
def table_header(
    label: str,
) -> None:
    """
    Submit one header cell manually (rarely used)
    """
```

:::

::: api-signature

```python
def table_headers_row() -> None:
    """
    Submit a row with headers cells based on data provided to `table_setup_column()` + submit context menu
    """
```

:::

::: api-signature

```python
def table_angled_headers_row() -> None:
    """
    Submit a row with angled headers for every column with the `TableColumnFlags.ANGLED_HEADER` flag. MUST BE FIRST ROW.
    """
```

:::

## Tables: Sorting & Miscellaneous functions

* Sorting: call `table_get_sort_specs()` to retrieve the latest sort specs for the table. Returns `None` when not sorting.
  When `sort_specs->SpecsDirty == True` you should sort your data. It will be `True` when sorting specs have changed since the last call, or the first time. Make sure to set `SpecsDirty = False` after sorting, else you may wastefully sort your data every frame!
* Functions args `column_n` treat the default value of -1 as the same as passing the current column index.

### Functions

::: api-signature

```python
def table_get_column_count() -> int:
    """
    Return number of columns (value passed to `begin_table`)
    """
```

:::

::: api-signature

```python
def table_get_column_index() -> int:
    """
    Return current column index.
    """
```

:::

::: api-signature

```python
def table_get_row_index() -> int:
    """
    Return current row index (header rows are accounted for)
    """
```

:::

::: api-signature

```python
def table_get_column_name(
    column_n: int = -1,
) -> str:
    """
    Return "" if column didn't have a name declared by `table_setup_column()`. Pass -1 to use current column.
    """
```

:::

::: api-signature

```python
def table_get_column_flags(
    column_n: int = -1,
) -> TableColumnFlags:
    """
    Return column flags so you can query their Enabled/Visible/Sorted/Hovered status flags. Pass -1 to use current column.
    """
```

:::

::: api-signature

```python
def table_set_column_enabled(
    column_n: int,
    v: bool,
) -> None:
    """
    Change user accessible enabled/disabled state of a column. Set to false to hide the column. User can use the context menu to change this themselves (right-click in headers, or right-click in columns body with `TableFlags.CONTEXT_MENU_IN_BODY`)
    """
```

:::

::: api-signature

```python
def table_get_hovered_column() -> int:
    """
    Return hovered column. return -1 when table is not hovered. return columns_count if the unused space at the right of visible columns is hovered. Can also use (`table_get_column_flags()` & `TableColumnFlags.IS_HOVERED`) instead.
    """
```

:::

::: api-signature

```python
def table_set_bg_color(
    target: TableBgTarget,
    color: tuple[float, float, float, float],
    column_n: int = -1,
) -> None:
    """
    Change the color of a cell, row, or column. See `TableBgTarget` flags for details.
    """
```

:::

## Legacy Columns API (prefer using Tables!)

* You can also use `same_line(pos_x)` to mimic simplified columns.

### Functions

::: api-signature

```python
def columns(
    count: int = 1,
    id: str | None = None,
    border: bool = True,
) -> None:
```

:::

::: api-signature

```python
def next_column() -> None:
    """
    Next column, defaults to current row or next row if the current row is finished
    """
```

:::

::: api-signature

```python
def get_column_index() -> int:
    """
    Get current column index
    """
```

:::

::: api-signature

```python
def get_column_width(
    column_index: int = -1,
) -> float:
    """
    Get column width (in pixels). pass -1 to use current column
    """
```

:::

::: api-signature

```python
def set_column_width(
    column_index: int,
    width: float,
) -> None:
    """
    Set column width (in pixels). pass -1 to use current column
    """
```

:::

::: api-signature

```python
def get_column_offset(
    column_index: int = -1,
) -> float:
    """
    Get position of column line (in pixels, from the left side of the contents region). pass -1 to use current column, otherwise 0..`get_columns_count()` inclusive. column 0 is typically 0.0
    """
```

:::

::: api-signature

```python
def set_column_offset(
    column_index: int,
    offset_x: float,
) -> None:
    """
    Set position of column line (in pixels, from the left side of the contents region). pass -1 to use current column
    """
```

:::

::: api-signature

```python
def get_columns_count() -> int:
```

:::

## Tab Bars, Tabs

* Note: Tabs are automatically created by the docking system (when in 'docking' branch). Use this to create tab bars/tabs yourself.

### Functions

::: api-signature

```python
def begin_tab_bar(
    str_id: str,
    flags: TabBarFlags = TabBarFlags.NONE,
) -> bool:
    """
    Create and append into a TabBar
    """
```

:::

::: api-signature

```python
def end_tab_bar() -> None:
    """
    Only call `end_tab_bar()` if `begin_tab_bar()` returns true!
    """
```

:::

::: api-signature

```python
def tab_item_button(
    label: str,
    flags: TabItemFlags = TabItemFlags.NONE,
) -> bool:
    """
    Create a Tab behaving like a button. return true when clicked. cannot be selected in the tab bar.
    """
```

:::

::: api-signature

```python
def set_tab_item_closed(
    label: str,
) -> None:
    """
    Notify TabBar or Docking system of a closed tab/window ahead (useful to reduce visual flicker on reorderable tab bars). For tab-bar: call after `begin_tab_bar()` and before Tab submissions. Otherwise call with a window name.
    """
```

:::

::: api-signature

````python
def begin_tab_item(
    str_id: str,
    closable: bool = False,
    flags: TabItemFlags = TabItemFlags.NONE,
) -> tuple[bool, bool]:
    """
    When the `closable` argument is set to `True`, the created tab will display a close button.  The second bool of the return value will be `False` if the close button was pressed.  The intended usage is as follows:

    ```
    tab_open = True  # open/closed state

    visible, tab_open = imgui.begin_tab_item(..., closable=tab_open)
    if visible:
        # render tab contents here..
    ```
    """
````

:::

::: api-signature

```python
def end_tab_item() -> None:
    """
    Only call `end_tab_item()` if `begin_tab_item()` returns true!
    """
```

:::

## Drag and Drop

* On source items, call `begin_drag_drop_source()`, if it returns true also call `set_drag_drop_payload()` + `end_drag_drop_source()`.
* On target candidates, call `begin_drag_drop_target()`, if it returns true also call `accept_drag_drop_payload()` + `end_drag_drop_target()`.
* If you stop calling `begin_drag_drop_source()` the payload is preserved however it won't have a preview tooltip (we currently display a fallback "..." tooltip, see [#1725](https://github.com/ocornut/imgui/issues/1725)).
* An item can be both drag source and drop target.

::: api-signature

```python
def begin_drag_drop_source(
    flags: DragDropFlags = DragDropFlags.NONE,
) -> bool:
    """
    Call after submitting an item which may be dragged. when this return true, you can call `set_drag_drop_payload()` + `end_drag_drop_source()`
    """
```

:::

::: api-signature

```python
def set_drag_drop_payload(
    type: str,
    data: bytes,
    cond: Cond = Cond.NONE,
) -> bool:
    """
    Type is a user defined string of maximum 32 characters. Strings starting with '_' are reserved for dear imgui internal types. Data is copied and held by imgui. Return true when payload has been accepted.
    """
```

:::

::: api-signature

```python
def end_drag_drop_source() -> None:
    """
    Only call `end_drag_drop_source()` if `begin_drag_drop_source()` returns true!
    """
```

:::

::: api-signature

```python
def begin_drag_drop_target() -> bool:
    """
    Call after submitting an item that may receive a payload. If this returns true, you can call `accept_drag_drop_payload()` + `end_drag_drop_target()`
    """
```

:::

::: api-signature

```python
def accept_drag_drop_payload(
    type: str,
    flags: slimgui.slimgui_ext.imgui.DragDropFlags = 0,
) -> slimgui.slimgui_ext.imgui.Payload | None:
    """
    Accept contents of a given type. If `DragDropFlags.ACCEPT_BEFORE_DELIVERY` is set you can peek into the payload before the mouse button is released.
    """
```

:::

::: api-signature

```python
def end_drag_drop_target() -> None:
    """
    Only call `end_drag_drop_target()` if `begin_drag_drop_target()` returns true!
    """
```

:::

::: api-signature

```python
def get_drag_drop_payload() -> slimgui.slimgui_ext.imgui.Payload | None:
    """
    Peek directly into the current payload from anywhere. Returns `None` when drag and drop is finished or inactive. Use `Payload.is_data_type()` to test for the payload type.
    """
```

:::

## Disabling \[BETA API]

* Disable all user interactions and dim items visuals (applying `Style.disabled_alpha` over current colors).
* These can be nested but cannot be used to enable an already disabled section (a single `begin_disabled(True)` in the stack is enough to keep everything disabled).
* Tooltip windows, by exception, are opted out of disabling.
* `begin_disabled(False)`/`end_disabled()` essentially does nothing but is provided to facilitate the use of boolean expressions (as a micro-optimization: if you have tens of thousands of `begin_disabled(False)`/`end_disabled()` pairs, you might want to reformulate your code to avoid making those calls).

### Functions

::: api-signature

```python
def begin_disabled(
    disabled: bool = True,
) -> None:
```

:::

::: api-signature

```python
def end_disabled() -> None:
```

:::

## Clipping

* Mouse hovering is affected by `push_clip_rect()` calls, unlike direct calls to `DrawList.push_clip_rect()` which are render only.

### Functions

::: api-signature

```python
def push_clip_rect(
    clip_rect_min: tuple[float, float],
    clip_rect_max: tuple[float, float],
    intersect_with_current_clip_rect: bool,
) -> None:
```

:::

::: api-signature

```python
def pop_clip_rect() -> None:
```

:::

## Focus, Activation

### Functions

::: api-signature

```python
def set_item_default_focus() -> None:
    """
    Make last item the default focused item of a newly appearing window.
    """
```

:::

::: api-signature

```python
def set_keyboard_focus_here(
    offset: int = 0,
) -> None:
    """
    Focus keyboard on the next widget. Use positive 'offset' to access sub components of a multiple component widget. Use -1 to access previous widget.
    """
```

:::

## Keyboard/Gamepad Navigation

::: api-signature

```python
def set_nav_cursor_visible(
    visible: bool,
) -> None:
    """
    Alter visibility of keyboard/gamepad cursor. by default: show when using an arrow key, hide when clicking with mouse.
    """
```

:::

## Overlapping mode

### Functions

::: api-signature

```python
def set_next_item_allow_overlap() -> None:
    """
    Allow next item to be overlapped by a subsequent item. Typically useful with `invisible_button()`, `selectable()`, `tree_node()` covering an area where subsequent items may need to be added. Note that both `selectable()` and `tree_node()` have dedicated flags doing this.
    """
```

:::

## Item/Widgets Utilities and Query Functions

* Most of the functions are referring to the previous Item that has been submitted.
* See Demo Window under "Widgets->Querying Status" for an interactive visualization of most of those functions.

### Functions

::: api-signature

```python
def is_item_hovered(
    flags: HoveredFlags = HoveredFlags.NONE,
) -> bool:
    """
    Is the last item hovered? (and usable, aka not blocked by a popup, etc.). See ImGuiHoveredFlags for more options.
    """
```

:::

::: api-signature

```python
def is_item_active() -> bool:
    """
    Is the last item active? (e.g. button being held, text field being edited. This will continuously return true while holding mouse button on an item. Items that don't interact will always return false)
    """
```

:::

::: api-signature

```python
def is_item_focused() -> bool:
    """
    Is the last item focused for keyboard/gamepad navigation?
    """
```

:::

::: api-signature

```python
def is_item_clicked(
    mouse_button: MouseButton = MouseButton.LEFT,
) -> bool:
    """
    Is the last item hovered and mouse clicked on? (**)  == `is_mouse_clicked(mouse_button)` && `is_item_hovered()`Important. (**) this is NOT equivalent to the behavior of e.g. `button()`. Read comments in function definition.
    """
```

:::

::: api-signature

```python
def is_item_visible() -> bool:
    """
    Is the last item visible? (items may be out of sight because of clipping/scrolling)
    """
```

:::

::: api-signature

```python
def is_item_edited() -> bool:
    """
    Did the last item modify its underlying value this frame? or was pressed? This is generally the same as the "bool" return value of many widgets.
    """
```

:::

::: api-signature

```python
def is_item_activated() -> bool:
    """
    Was the last item just made active (item was previously inactive).
    """
```

:::

::: api-signature

```python
def is_item_deactivated() -> bool:
    """
    Was the last item just made inactive (item was previously active). Useful for Undo/Redo patterns with widgets that require continuous editing.
    """
```

:::

::: api-signature

```python
def is_item_deactivated_after_edit() -> bool:
    """
    Was the last item just made inactive and made a value change when it was active? (e.g. Slider/Drag moved). Useful for Undo/Redo patterns with widgets that require continuous editing. Note that you may get false positives (some widgets such as `combo()`/`list_box()`/`selectable()` will return true even when clicking an already selected item).
    """
```

:::

::: api-signature

```python
def is_item_toggled_open() -> bool:
    """
    Was the last item open state toggled? set by `tree_node()`.
    """
```

:::

::: api-signature

```python
def is_any_item_hovered() -> bool:
    """
    Is any item hovered?
    """
```

:::

::: api-signature

```python
def is_any_item_active() -> bool:
    """
    Is any item active?
    """
```

:::

::: api-signature

```python
def is_any_item_focused() -> bool:
    """
    Is any item focused?
    """
```

:::

::: api-signature

```python
def get_item_id() -> int:
    """
    Get ID of last item (often roughly the same as `get_id(label)` beforehand)
    """
```

:::

::: api-signature

```python
def get_item_rect_min() -> tuple[float, float]:
    """
    Get upper-left bounding rectangle of the last item (screen space)
    """
```

:::

::: api-signature

```python
def get_item_rect_max() -> tuple[float, float]:
    """
    Get lower-right bounding rectangle of the last item (screen space)
    """
```

:::

::: api-signature

```python
def get_item_rect_size() -> tuple[float, float]:
    """
    Get size of last item
    """
```

:::

## Viewports

* Currently represents the Platform Window created by the application which is hosting our Dear ImGui windows.
* In 'docking' branch with multi-viewport enabled, we extend this concept to have multiple active viewports.
* In the future we will extend this concept further to also represent Platform Monitor and support a "no main platform window" operation mode.

### Functions

::: api-signature

```python
def get_main_viewport() -> Viewport:
    """
    Return primary/default viewport. This can never be NULL.
    """
```

:::

## Background/Foreground Draw Lists

### Functions

::: api-signature

```python
def get_background_draw_list() -> slimgui.imgui.DrawList:
    """
    This draw list will be the first rendered one. Useful to quickly draw shapes/text behind dear imgui contents.
    """
```

:::

::: api-signature

```python
def get_foreground_draw_list() -> slimgui.imgui.DrawList:
    """
    This draw list will be the last rendered one. Useful to quickly draw shapes/text over dear imgui contents.
    """
```

:::

## Miscellaneous Utilities

### Functions

::: api-signature

```python
def is_rect_visible(
    size: tuple[float, float],
) -> bool:
    """
    Test if rectangle (of given size, starting from cursor position) is visible / not clipped.
    """
```

:::

::: api-signature

```python
def is_rect_visible(
    rect_min: tuple[float, float],
    rect_max: tuple[float, float],
) -> bool:
    """
    Test if rectangle (of given size, starting from cursor position) is visible / not clipped.
    """
```

:::

::: api-signature

```python
def get_time() -> float:
    """
    Get global imgui time. incremented by io.DeltaTime every frame.
    """
```

:::

::: api-signature

```python
def get_frame_count() -> int:
    """
    Get global imgui frame count. incremented by 1 every frame.
    """
```

:::

::: api-signature

```python
def get_style_color_name(
    col: Col,
) -> str:
    """
    Get a string corresponding to the enum value (for display, saving, etc.).
    """
```

:::

### Clipboard

::: api-signature

```python
def get_clipboard_text() -> str:
    """
    Get clipboard text from the current platform backend.
    """
```

:::

::: api-signature

```python
def set_clipboard_text(
    text: str,
) -> None:
    """
    Set clipboard text through the current platform backend.
    """
```

:::

## Text Utilities

### Functions

::: api-signature

```python
def calc_text_size(
    text: str,
    hide_text_after_double_hash: bool = False,
    wrap_width: float = -1.0,
) -> tuple[float, float]:
```

:::

## Color Utilities

### Functions

::: api-signature

```python
def color_convert_u32_to_float4(
    arg: int,
    /,
) -> tuple[float, float, float, float]:
```

:::

::: api-signature

```python
def color_convert_float4_to_u32(
    arg: tuple[float, float, float, float],
    /,
) -> int:
```

:::

::: api-signature

```python
def color_convert_rgb_to_hsv(
    rgba: tuple[float, float, float, float],
) -> tuple[float, float, float, float]:
```

:::

::: api-signature

```python
def color_convert_hsv_to_rgb(
    hsv: tuple[float, float, float, float],
) -> tuple[float, float, float, float]:
```

:::

## Inputs Utilities: Keyboard/Mouse/Gamepad

* The `Key` enum contains all possible keyboard, mouse, and gamepad inputs (e.g., `Key.KEY_A`, `Key.MOUSE_LEFT`, `Key.GAMEPAD_DPAD_UP`).

### Functions

::: api-signature

```python
def is_key_down(
    key: Key,
) -> bool:
    """
    Is key being held.
    """
```

:::

::: api-signature

```python
def is_key_pressed(
    key: Key,
    repeat: bool = True,
) -> bool:
    """
    Was key pressed (went from !Down to Down)? Repeat rate uses io.KeyRepeatDelay / KeyRepeatRate.
    """
```

:::

::: api-signature

```python
def is_key_released(
    key: Key,
) -> bool:
    """
    Was key released (went from Down to !Down)?
    """
```

:::

::: api-signature

```python
def is_key_chord_pressed(
    key_chord: Key | int,
) -> bool:
    """
    Was key chord (mods + key) pressed, e.g. you can pass 'ImGuiMod_Ctrl | ImGuiKey_S' as a key-chord. This doesn't do any routing or focus check, please consider using `shortcut()` function instead.
    """
```

:::

::: api-signature

```python
def get_key_pressed_amount(
    key: Key,
    repeat_delay: float,
    rate: float,
) -> int:
    """
    Uses provided repeat rate/delay. return a count, most often 0 or 1 but might be >1 if RepeatRate is small enough that DeltaTime > RepeatRate
    """
```

:::

::: api-signature

```python
def get_key_name(
    key: Key,
) -> str:
    """
    [DEBUG] returns English name of the key. Those names are provided for debugging purpose and are not meant to be saved persistently nor compared.
    """
```

:::

::: api-signature

```python
def set_next_frame_want_capture_keyboard(
    want_capture_keyboard: bool,
) -> None:
```

:::

## Inputs Utilities: Shortcut Testing & Routing \[BETA]

A `key_chord` passed to the below shortcut functions is a `Key` value + an optional `Key.MOD_ALT/CTRL_SHIFT_SUPER`.  E.g.,

* `Key.KEY_C`: accepted by functions taking `Key` or `Key | int` (keychord arguments)
* `Key.MOD_CTRL | Key.KEY_C`: accepted by functions taking `Key | int` keychord arguments
* It's legal to only combine `KEY_*` values with a `MOD_*` value.

The general idea is that several callers may register interest in a shortcut, and only one owner gets it:

* Parent -> call Shortcut(Ctrl+S)  - when Parent is focused, Parent gets the shortcut
  * Child1 -> call Shortcut(Ctrl+S) - when Child1 is focused, Child1 gets the shortcut (Child1 overrides Parent shortcuts)
  * Child2 -> no call - when Child2 is focused, Parent gets the shortcut.

The whole system is order independent, so if Child1 makes its calls before Parent, results will be identical.
This is an important property as it facilitates working with foreign code or a larger codebase. To understand the difference:

* `is_key_chord_pressed()` compares mods and calls `is_key_pressed()` -> function has no side-effect.
* `shortcut()` submits a route, routes are resolved, if it currently can be routed it calls `is_key_chord_pressed()` -> function has (desirable) side-effects as it can prevent another call from getting the route.

You can visualize registered routes in the "Metrics/Debugger->Inputs" window.

### Functions

::: api-signature

```python
def shortcut(
    key_chord: Key | int,
    flags: InputFlags = InputFlags.NONE,
) -> bool:
    """
    Python bindings note: The original ImGui type for a ImGuiKeyChord is basically ImGuiKey that can be optionally bitwise-OR'd with a modifier key like ImGuiMod_Alt, ImGuiMod_Ctrl, etc.  In Python, this is modeled as a union of `Key` and int.  The int value is the modifier key.  You can use the `|` operator to combine them, e.g. `Key.A | Key.MOD_CTRL`.
    """
```

:::

::: api-signature

```python
def set_next_item_shortcut(
    key_chord: Key | int,
    flags: InputFlags = InputFlags.NONE,
) -> None:
    """
    Python bindings note: The original ImGui type for a ImGuiKeyChord is basically ImGuiKey that can be optionally bitwise-OR'd with a modifier key like ImGuiMod_Alt, ImGuiMod_Ctrl, etc.  In Python, this is modeled as a union of `Key` and int.  The int value is the modifier key.  You can use the `|` operator to combine them, e.g. `Key.A | Key.MOD_CTRL`.
    """
```

:::

::: api-signature

```python
def set_item_key_owner(
    key: Key,
) -> None:
    """
    Set key owner to last item ID if it is hovered or active.
    """
```

:::

## Inputs Utilities: Mouse

* To refer to a mouse button, you may use named enums in your code, e.g., `MouseButton.LEFT`, `MouseButton.RIGHT`.

### Functions

::: api-signature

```python
def is_mouse_down(
    button: MouseButton,
) -> bool:
    """
    Is mouse button held?
    """
```

:::

::: api-signature

```python
def is_mouse_clicked(
    button: MouseButton,
    repeat: bool = False,
) -> bool:
    """
    Did mouse button clicked? (went from !Down to Down). Same as `get_mouse_clicked_count()` == 1.
    """
```

:::

::: api-signature

```python
def is_mouse_released(
    button: MouseButton,
) -> bool:
    """
    Did mouse button released? (went from Down to !Down)
    """
```

:::

::: api-signature

```python
def is_mouse_double_clicked(
    button: MouseButton,
) -> bool:
    """
    Did mouse button double-clicked? Same as `get_mouse_clicked_count()` == 2. (note that a double-click will also report `is_mouse_clicked()` == true)
    """
```

:::

::: api-signature

```python
def is_mouse_released_with_delay(
    button: MouseButton,
    delay: float,
) -> bool:
    """
    Delayed mouse release (use very sparingly!). Generally used with 'delay >= io.MouseDoubleClickTime' + combined with a 'io.MouseClickedLastCount==1' test. This is a very rarely used UI idiom, but some apps use this: e.g. MS Explorer single click on an icon to rename.
    """
```

:::

::: api-signature

```python
def get_mouse_clicked_count(
    button: MouseButton,
) -> int:
    """
    Return the number of successive mouse-clicks at the time where a click happen (otherwise 0).
    """
```

:::

::: api-signature

```python
def is_mouse_hovering_rect(
    r_min: tuple[float, float],
    r_max: tuple[float, float],
    clip: bool = True,
) -> bool:
    """
    Is mouse hovering given bounding rect (in screen space). clipped by current clipping settings, but disregarding of other consideration of focus/window ordering/popup-block.
    """
```

:::

::: api-signature

```python
def is_mouse_pos_valid(
    mouse_pos: tuple[float, float] | None = None,
) -> bool:
    """
    By convention we use (-FLT_MAX,-FLT_MAX) to denote that there is no mouse available
    """
```

:::

::: api-signature

```python
def get_mouse_pos() -> tuple[float, float]:
    """
    Shortcut to `get_io()`.MousePos provided by user, to be consistent with other calls
    """
```

:::

::: api-signature

```python
def get_mouse_pos_on_opening_current_popup() -> tuple[float, float]:
    """
    Retrieve mouse position at the time of opening popup we have `begin_popup()` into (helper to avoid user backing that value themselves)
    """
```

:::

::: api-signature

```python
def is_mouse_dragging(
    button: MouseButton,
    lock_threshold: float = -1.0,
) -> bool:
    """
    Is mouse dragging? (uses io.MouseDraggingThreshold if lock_threshold < 0.0)
    """
```

:::

::: api-signature

```python
def get_mouse_drag_delta(
    button: MouseButton = MouseButton.LEFT,
    lock_threshold: float = -1.0,
) -> tuple[float, float]:
    """
    Return the delta from the initial clicking position while the mouse button is pressed or was just released. This is locked and return 0.0 until the mouse moves past a distance threshold at least once (uses io.MouseDraggingThreshold if lock_threshold < 0.0)
    """
```

:::

::: api-signature

```python
def reset_mouse_drag_delta(
    button: MouseButton = MouseButton.LEFT,
) -> None:
```

:::

::: api-signature

```python
def get_mouse_cursor() -> MouseCursor:
    """
    Get desired mouse cursor shape. Important: reset in `new_frame()`, this is updated during the frame. valid before `render()`. If you use software rendering by setting io.MouseDrawCursor ImGui will render those for you
    """
```

:::

::: api-signature

```python
def set_mouse_cursor(
    cursor_type: MouseCursor,
) -> None:
    """
    Set desired mouse cursor shape
    """
```

:::

::: api-signature

```python
def set_next_frame_want_capture_mouse(
    capture: bool,
) -> None:
```

:::

## Enum Reference

### Enum: BackendFlags

| Name | Description |
| --- | --- |
| NONE |  |
| HAS\_GAMEPAD | Backend Platform supports gamepad and currently has one connected. |
| HAS\_MOUSE\_CURSORS | Backend Platform supports honoring `get_mouse_cursor()` value to change the OS cursor shape. |
| HAS\_SET\_MOUSE\_POS | Backend Platform supports io.WantSetMousePos requests to reposition the OS mouse position (only used if io.ConfigNavMoveSetMousePos is set). |
| RENDERER\_HAS\_VTX\_OFFSET | Backend Renderer supports ImDrawCmd::VtxOffset. This enables output of large meshes (64K+ vertices) while still using 16-bit indices. |
| RENDERER\_HAS\_TEXTURES | Backend Renderer supports ImTextureData requests to create/update/destroy textures. This enables incremental texture updates and texture reloads. See https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md for instructions on how to upgrade your custom backend. |

### Enum: ButtonFlags

| Name | Description |
| --- | --- |
| NONE |  |
| MOUSE\_BUTTON\_LEFT | React on left mouse button (default) |
| MOUSE\_BUTTON\_RIGHT | React on right mouse button |
| MOUSE\_BUTTON\_MIDDLE | React on center mouse button |
| ENABLE\_NAV | `invisible_button()`: do not disable navigation/tabbing. Otherwise disabled by default. |
| ALLOW\_OVERLAP | Hit testing will allow subsequent widgets to overlap this one. Require previous frame HoveredId to match before being usable. Shortcut to calling `set_next_item_allow_overlap()`. |

### Enum: ChildFlags

| Name | Description |
| --- | --- |
| NONE |  |
| BORDERS | Show an outer border and enable WindowPadding. (IMPORTANT: this is always == 1 == true for legacy reason) |
| ALWAYS\_USE\_WINDOW\_PADDING | Pad with style.WindowPadding even if no border are drawn (no padding by default for non-bordered child windows because it makes more sense) |
| RESIZE\_X | Allow resize from right border (layout direction). Enable .ini saving (unless `WindowFlags.NO_SAVED_SETTINGS` passed to window flags) |
| RESIZE\_Y | Allow resize from bottom border (layout direction). |
| AUTO\_RESIZE\_X | Enable auto-resizing width. Read IMPORTANT: Size measurement" details above. |
| AUTO\_RESIZE\_Y | Enable auto-resizing height. Read IMPORTANT: Size measurement" details above. |
| ALWAYS\_AUTO\_RESIZE | Combined with AutoResizeX/AutoResizeY. Always measure size even when child is hidden, always return true, always disable clipping optimization! NOT RECOMMENDED. |
| FRAME\_STYLE | Style the child window like a framed item: use FrameBg, FrameRounding, FrameBorderSize, FramePadding instead of ChildBg, ChildRounding, ChildBorderSize, WindowPadding. |
| NAV\_FLATTENED | \[BETA] Share focus scope, allow keyboard/gamepad navigation to cross over parent border to this child or between sibling child windows. |

### Enum: Col

| Name | Description |
| --- | --- |
| TEXT |  |
| TEXT\_DISABLED |  |
| WINDOW\_BG | Background of normal windows |
| CHILD\_BG | Background of child windows |
| POPUP\_BG | Background of popups, menus, tooltips windows |
| BORDER |  |
| BORDER\_SHADOW |  |
| FRAME\_BG | Background of checkbox, radio button, plot, slider, text input |
| FRAME\_BG\_HOVERED |  |
| FRAME\_BG\_ACTIVE |  |
| TITLE\_BG | Title bar |
| TITLE\_BG\_ACTIVE | Title bar when focused |
| TITLE\_BG\_COLLAPSED | Title bar when collapsed |
| MENU\_BAR\_BG |  |
| SCROLLBAR\_BG |  |
| SCROLLBAR\_GRAB |  |
| SCROLLBAR\_GRAB\_HOVERED |  |
| SCROLLBAR\_GRAB\_ACTIVE |  |
| CHECK\_MARK | `checkbox` tick and `radio_button` circle |
| SLIDER\_GRAB |  |
| SLIDER\_GRAB\_ACTIVE |  |
| BUTTON |  |
| BUTTON\_HOVERED |  |
| BUTTON\_ACTIVE |  |
| HEADER | Header\* colors are used for `collapsing_header`, `tree_node`, `selectable`, `menu_item` |
| HEADER\_HOVERED |  |
| HEADER\_ACTIVE |  |
| SEPARATOR |  |
| SEPARATOR\_HOVERED |  |
| SEPARATOR\_ACTIVE |  |
| RESIZE\_GRIP | Resize grip in lower-right and lower-left corners of windows. |
| RESIZE\_GRIP\_HOVERED |  |
| RESIZE\_GRIP\_ACTIVE |  |
| INPUT\_TEXT\_CURSOR | `input_text` cursor/caret |
| TAB\_HOVERED | Tab background, when hovered |
| TAB | Tab background, when tab-bar is focused & tab is unselected |
| TAB\_SELECTED | Tab background, when tab-bar is focused & tab is selected |
| TAB\_SELECTED\_OVERLINE | Tab horizontal overline, when tab-bar is focused & tab is selected |
| TAB\_DIMMED | Tab background, when tab-bar is unfocused & tab is unselected |
| TAB\_DIMMED\_SELECTED | Tab background, when tab-bar is unfocused & tab is selected |
| TAB\_DIMMED\_SELECTED\_OVERLINE |  |
| PLOT\_LINES |  |
| PLOT\_LINES\_HOVERED |  |
| PLOT\_HISTOGRAM |  |
| PLOT\_HISTOGRAM\_HOVERED |  |
| TABLE\_HEADER\_BG | Table header background |
| TABLE\_BORDER\_STRONG | Table outer and header borders (prefer using Alpha=1.0 here) |
| TABLE\_BORDER\_LIGHT | Table inner borders (prefer using Alpha=1.0 here) |
| TABLE\_ROW\_BG | Table row background (even rows) |
| TABLE\_ROW\_BG\_ALT | Table row background (odd rows) |
| TEXT\_LINK | Hyperlink color |
| TEXT\_SELECTED\_BG | Selected text inside an `input_text` |
| TREE\_LINES | Tree node hierarchy outlines when using `TreeNodeFlags.DRAW_LINES` |
| DRAG\_DROP\_TARGET | Rectangle border highlighting a drop target |
| DRAG\_DROP\_TARGET\_BG | Rectangle background highlighting a drop target |
| UNSAVED\_MARKER | Unsaved Document marker (in window title and tabs) |
| NAV\_CURSOR | Color of keyboard/gamepad navigation cursor/rectangle, when visible |
| NAV\_WINDOWING\_HIGHLIGHT | Highlight window when using Ctrl+Tab |
| NAV\_WINDOWING\_DIM\_BG | Darken/colorize entire screen behind the Ctrl+Tab window list, when active |
| MODAL\_WINDOW\_DIM\_BG | Darken/colorize entire screen behind a modal window, when one is active |
| COUNT |  |

### Enum: ColorEditFlags

| Name | Description |
| --- | --- |
| NONE |  |
| NO\_ALPHA | ColorEdit, ColorPicker, `color_button`: ignore Alpha component (will only read 3 components from the input pointer). |
| NO\_PICKER | ColorEdit: disable picker when clicking on color square. |
| NO\_OPTIONS | ColorEdit: disable toggling options menu when right-clicking on inputs/small preview. |
| NO\_SMALL\_PREVIEW | ColorEdit, ColorPicker: disable color square preview next to the inputs. (e.g. to show only the inputs) |
| NO\_INPUTS | ColorEdit, ColorPicker: disable inputs sliders/text widgets (e.g. to show only the small preview color square). |
| NO\_TOOLTIP | ColorEdit, ColorPicker, `color_button`: disable tooltip when hovering the preview. |
| NO\_LABEL | ColorEdit, ColorPicker: disable display of inline text label (the label is still forwarded to the tooltip and picker). |
| NO\_SIDE\_PREVIEW | ColorPicker: disable bigger color preview on right side of the picker, use small color square preview instead. |
| NO\_DRAG\_DROP | ColorEdit: disable drag and drop target/source. `color_button`: disable drag and drop source. |
| NO\_BORDER | `color_button`: disable border (which is enforced by default) |
| NO\_COLOR\_MARKERS | ColorEdit: disable rendering R/G/B/A color marker. May also be disabled globally by setting style.ColorMarkerSize = 0. |
| ALPHA\_OPAQUE | ColorEdit, ColorPicker, `color_button`: disable alpha in the preview,. Contrary to \_NoAlpha it may still be edited when calling `color_edit4()`/`color_picker4()`. For `color_button()` this does the same as \_NoAlpha. |
| ALPHA\_NO\_BG | ColorEdit, ColorPicker, `color_button`: disable rendering a checkerboard background behind transparent color. |
| ALPHA\_PREVIEW\_HALF | ColorEdit, ColorPicker, `color_button`: display half opaque / half transparent preview. |
| ALPHA\_BAR | ColorEdit, ColorPicker: show vertical alpha bar/gradient in picker. |
| HDR | (WIP) ColorEdit: Currently only disable 0.0..1.0 limits in RGBA edition (note: you probably want to use `ColorEditFlags.FLOAT` flag as well). |
| DISPLAY\_RGB | ColorEdit: override *display* type among RGB/HSV/Hex. ColorPicker: select any combination using one or more of RGB/HSV/Hex. |
| DISPLAY\_HSV |  |
| DISPLAY\_HEX |  |
| UINT8 | ColorEdit, ColorPicker, `color_button`: *display* values formatted as 0..255. |
| FLOAT | ColorEdit, ColorPicker, `color_button`: *display* values formatted as 0.0..1.0 floats instead of 0..255 integers. No round-trip of value via integers. |
| PICKER\_HUE\_BAR | ColorPicker: bar for Hue, rectangle for Sat/Value. |
| PICKER\_HUE\_WHEEL | ColorPicker: wheel for Hue, triangle for Sat/Value. |
| INPUT\_RGB | ColorEdit, ColorPicker: input and output data in RGB format. |
| INPUT\_HSV | ColorEdit, ColorPicker: input and output data in HSV format. |

### Enum: ComboFlags

| Name | Description |
| --- | --- |
| NONE |  |
| POPUP\_ALIGN\_LEFT | Align the popup toward the left by default |
| HEIGHT\_SMALL | Max ~4 items visible. Tip: If you want your combo popup to be a specific size you can use `set_next_window_size_constraints()` prior to calling `begin_combo()` |
| HEIGHT\_REGULAR | Max ~8 items visible (default) |
| HEIGHT\_LARGE | Max ~20 items visible |
| HEIGHT\_LARGEST | As many fitting items as possible |
| NO\_ARROW\_BUTTON | Display on the preview box without the square arrow button |
| NO\_PREVIEW | Display only a square arrow button |
| WIDTH\_FIT\_PREVIEW | Width dynamically calculated from preview contents |

### Enum: Cond

| Name | Description |
| --- | --- |
| NONE | No condition (always set the variable), same as \_Always |
| ALWAYS | No condition (always set the variable), same as \_None |
| ONCE | Set the variable once per runtime session (only the first call will succeed) |
| FIRST\_USE\_EVER | Set the variable if the object/window has no persistently saved data (no entry in .ini file) |
| APPEARING | Set the variable if the object/window is appearing after being hidden/inactive (or the first time) |

### Enum: ConfigFlags

| Name | Description |
| --- | --- |
| NONE |  |
| NAV\_ENABLE\_KEYBOARD | Master keyboard navigation enable flag. Enable full Tabbing + directional arrows + Space/Enter to activate. Note: some features such as basic Tabbing and CtrL+Tab are enabled by regardless of this flag (and may be disabled via other means, see #4828, #9218). |
| NAV\_ENABLE\_GAMEPAD | Master gamepad navigation enable flag. Backend also needs to set `BackendFlags.HAS_GAMEPAD`. |
| NO\_MOUSE | Instruct dear imgui to disable mouse inputs and interactions. |
| NO\_MOUSE\_CURSOR\_CHANGE | Instruct backend to not alter mouse cursor shape and visibility. Use if the backend cursor changes are interfering with yours and you don't want to use `set_mouse_cursor()` to change mouse cursor. You may want to honor requests from imgui by reading `get_mouse_cursor()` yourself instead. |
| NO\_KEYBOARD | Instruct dear imgui to disable keyboard inputs and interactions. This is done by ignoring keyboard events and clearing existing states. |
| IS\_SRGB | Application is SRGB-aware. |
| IS\_TOUCH\_SCREEN | Application is using a touch screen instead of a mouse. |

### Enum: Dir

| Name | Description |
| --- | --- |
| NONE |  |
| LEFT |  |
| RIGHT |  |
| UP |  |
| DOWN |  |
| COUNT |  |

### Enum: DragDropFlags

| Name | Description |
| --- | --- |
| NONE |  |
| SOURCE\_NO\_PREVIEW\_TOOLTIP | Disable preview tooltip. By default, a successful call to `begin_drag_drop_source` opens a tooltip so you can display a preview or description of the source contents. This flag disables this behavior. |
| SOURCE\_NO\_DISABLE\_HOVER | By default, when dragging we clear data so that `is_item_hovered()` will return false, to avoid subsequent user code submitting tooltips. This flag disables this behavior so you can still call `is_item_hovered()` on the source item. |
| SOURCE\_NO\_HOLD\_TO\_OPEN\_OTHERS | Disable the behavior that allows to open tree nodes and collapsing header by holding over them while dragging a source item. |
| SOURCE\_ALLOW\_NULL\_ID | 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. |
| SOURCE\_EXTERN | External source (from outside of dear imgui), won't attempt to read current item/window info. Will always return true. Only one Extern source can be active simultaneously. |
| PAYLOAD\_AUTO\_EXPIRE | Automatically expire the payload if the source cease to be submitted (otherwise payloads are persisting while being dragged) |
| PAYLOAD\_NO\_CROSS\_CONTEXT | Hint to specify that the payload may not be copied outside current dear imgui context. |
| PAYLOAD\_NO\_CROSS\_PROCESS | Hint to specify that the payload may not be copied outside current process. |
| ACCEPT\_BEFORE\_DELIVERY | `accept_drag_drop_payload()` will returns true even before the mouse button is released. You can then call IsDelivery() to test if the payload needs to be delivered. |
| ACCEPT\_NO\_DRAW\_DEFAULT\_RECT | Do not draw the default highlight rectangle when hovering over target. |
| ACCEPT\_NO\_PREVIEW\_TOOLTIP | Request hiding the `begin_drag_drop_source` tooltip from the `begin_drag_drop_target` site. |
| ACCEPT\_DRAW\_AS\_HOVERED | Accepting item will render as if hovered. Useful for e.g. a `button()` used as a drop target. |
| ACCEPT\_PEEK\_ONLY | For peeking ahead and inspecting the payload before delivery. |

### Enum: DrawFlags

| Name | Description |
| --- | --- |
| NONE |  |
| CLOSED | PathStroke(), AddPolyline(): specify that shape should be closed (Important: this is always == 1 for legacy reason) |
| ROUND\_CORNERS\_TOP\_LEFT | AddRect(), AddRectFilled(), PathRect(): enable rounding top-left corner only (when rounding > 0.0, we default to all corners). Was 0x01. |
| ROUND\_CORNERS\_TOP\_RIGHT | AddRect(), AddRectFilled(), PathRect(): enable rounding top-right corner only (when rounding > 0.0, we default to all corners). Was 0x02. |
| ROUND\_CORNERS\_BOTTOM\_LEFT | AddRect(), AddRectFilled(), PathRect(): enable rounding bottom-left corner only (when rounding > 0.0, we default to all corners). Was 0x04. |
| ROUND\_CORNERS\_BOTTOM\_RIGHT | AddRect(), AddRectFilled(), PathRect(): enable rounding bottom-right corner only (when rounding > 0.0, we default to all corners). Wax 0x08. |
| ROUND\_CORNERS\_NONE | AddRect(), AddRectFilled(), PathRect(): disable rounding on all corners (when rounding > 0.0). This is NOT zero, NOT an implicit flag! |
| ROUND\_CORNERS\_TOP |  |
| ROUND\_CORNERS\_BOTTOM |  |
| ROUND\_CORNERS\_LEFT |  |
| ROUND\_CORNERS\_RIGHT |  |
| ROUND\_CORNERS\_ALL |  |

### Enum: FocusedFlags

| Name | Description |
| --- | --- |
| NONE |  |
| CHILD\_WINDOWS | Return true if any children of the window is focused |
| ROOT\_WINDOW | Test from root window (top most parent of the current hierarchy) |
| ANY\_WINDOW | Return true if any window is focused. Important: If you are trying to tell how to dispatch your low-level inputs, do NOT use this. Use 'io.WantCaptureMouse' instead! Please read the FAQ! |
| NO\_POPUP\_HIERARCHY | Do not consider popup hierarchy (do not treat popup emitter as parent of popup) (when used with \_ChildWindows or \_RootWindow) |
| ROOT\_AND\_CHILD\_WINDOWS |  |

### Enum: HoveredFlags

| Name | Description |
| --- | --- |
| NONE | 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. |
| CHILD\_WINDOWS | `is_window_hovered()` only: Return true if any children of the window is hovered |
| ROOT\_WINDOW | `is_window_hovered()` only: Test from root window (top most parent of the current hierarchy) |
| ANY\_WINDOW | `is_window_hovered()` only: Return true if any window is hovered |
| NO\_POPUP\_HIERARCHY | `is_window_hovered()` only: Do not consider popup hierarchy (do not treat popup emitter as parent of popup) (when used with \_ChildWindows or \_RootWindow) |
| ALLOW\_WHEN\_BLOCKED\_BY\_POPUP | Return true even if a popup window is normally blocking access to this item/window |
| ALLOW\_WHEN\_BLOCKED\_BY\_ACTIVE\_ITEM | Return true even if an active item is blocking access to this item/window. Useful for Drag and Drop patterns. |
| ALLOW\_WHEN\_OVERLAPPED\_BY\_ITEM | `is_item_hovered()` only: Return true even if the item uses AllowOverlap mode and is overlapped by another hoverable item. |
| ALLOW\_WHEN\_OVERLAPPED\_BY\_WINDOW | `is_item_hovered()` only: Return true even if the position is obstructed or overlapped by another window. |
| ALLOW\_WHEN\_DISABLED | `is_item_hovered()` only: Return true even if the item is disabled |
| NO\_NAV\_OVERRIDE | `is_item_hovered()` only: Disable using keyboard/gamepad navigation state when active, always query mouse |
| ALLOW\_WHEN\_OVERLAPPED |  |
| RECT\_ONLY |  |
| ROOT\_AND\_CHILD\_WINDOWS |  |
| FOR\_TOOLTIP | Shortcut for standard flags when using `is_item_hovered()` + `set_tooltip()` sequence. |
| STATIONARY | Require mouse to be stationary for style.HoverStationaryDelay (~0.15 sec) *at least one time*. After this, can move on same item/window. Using the stationary test tends to reduces the need for a long delay. |
| DELAY\_NONE | `is_item_hovered()` only: Return true immediately (default). As this is the default you generally ignore this. |
| DELAY\_SHORT | `is_item_hovered()` only: Return true after style.HoverDelayShort elapsed (~0.15 sec) (shared between items) + requires mouse to be stationary for style.HoverStationaryDelay (once per item). |
| DELAY\_NORMAL | `is_item_hovered()` only: Return true after style.HoverDelayNormal elapsed (~0.40 sec) (shared between items) + requires mouse to be stationary for style.HoverStationaryDelay (once per item). |
| NO\_SHARED\_DELAY | `is_item_hovered()` only: Disable shared delay system where moving from one item to the next keeps the previous timer for a short time (standard for tooltips with long delays) |

### Enum: InputFlags

| Name | Description |
| --- | --- |
| NONE |  |
| REPEAT | Enable repeat. Return true on successive repeats. Default for legacy `is_key_pressed()`. NOT Default for legacy `is_mouse_clicked()`. MUST BE == 1. |
| ROUTE\_ACTIVE | Route to active item only. |
| ROUTE\_FOCUSED | Route to windows in the focus stack (DEFAULT). Deep-most focused window takes inputs. Active item takes inputs over deep-most focused window. |
| ROUTE\_GLOBAL | Global route (unless a focused window or active item registered the route). |
| ROUTE\_ALWAYS | Do not register route, poll keys directly. |
| ROUTE\_OVER\_FOCUSED | Option: global route: higher priority than focused route (unless active item in focused route). |
| ROUTE\_OVER\_ACTIVE | Option: global route: higher priority than active item. Unlikely you need to use that: will interfere with every active items, e.g. Ctrl+A registered by `input_text` will be overridden by this. May not be fully honored as user/internal code is likely to always assume they can access keys when active. |
| ROUTE\_UNLESS\_BG\_FOCUSED | Option: global route: will not be applied if underlying background/void is focused (== no Dear ImGui windows are focused). Useful for overlay applications. |
| ROUTE\_FROM\_ROOT\_WINDOW | Option: route evaluated from the point of view of root window rather than current window. |
| TOOLTIP | Automatically display a tooltip when hovering item \[BETA] Unsure of right api (opt-in/opt-out) |

### Enum: InputTextFlags

| Name | Description |
| --- | --- |
| NONE |  |
| CHARS\_DECIMAL | Allow 0123456789.+-*/ |
| CHARS\_HEXADECIMAL | Allow 0123456789ABCDEFabcdef |
| CHARS\_SCIENTIFIC | Allow 0123456789.+-*/eE (Scientific notation input) |
| CHARS\_UPPERCASE | Turn a..z into A..Z |
| CHARS\_NO\_BLANK | Filter out spaces, tabs |
| ALLOW\_TAB\_INPUT | Pressing TAB input a '  ' character into the text field |
| ENTER\_RETURNS\_TRUE | Return 'true' when Enter is pressed (as opposed to every time the value was modified). Consider using `is_item_deactivated_after_edit()` instead! |
| ESCAPE\_CLEARS\_ALL | Escape key clears content if not empty, and deactivate otherwise (contrast to default behavior of Escape to revert) |
| CTRL\_ENTER\_FOR\_NEW\_LINE | In multi-line mode: validate with Enter, add new line with Ctrl+Enter (default is opposite: validate with Ctrl+Enter, add line with Enter). Note that Shift+Enter always enter a new line either way. |
| READ\_ONLY | Read-only mode |
| PASSWORD | Password mode, display all characters as '\*', disable copy |
| ALWAYS\_OVERWRITE | Overwrite mode |
| AUTO\_SELECT\_ALL | Select entire text when first taking mouse focus |
| PARSE\_EMPTY\_REF\_VAL | `input_float()`, `input_int()`, `input_scalar()` etc. only: parse empty string as zero value. |
| DISPLAY\_EMPTY\_REF\_VAL | `input_float()`, `input_int()`, `input_scalar()` etc. only: when value is zero, do not display it. Generally used with `InputTextFlags.PARSE_EMPTY_REF_VAL`. |
| NO\_HORIZONTAL\_SCROLL | Disable following the cursor horizontally |
| NO\_UNDO\_REDO | 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()`. |
| ELIDE\_LEFT | When text doesn't fit, elide left side to ensure right side stays visible. Useful for path/filenames. Single-line only! |
| CALLBACK\_COMPLETION | Callback on pressing TAB (for completion handling) |
| CALLBACK\_HISTORY | Callback on pressing Up/Down arrows (for history handling) |
| CALLBACK\_ALWAYS | Callback on each iteration. User code may query cursor position, modify text buffer. |
| CALLBACK\_CHAR\_FILTER | Callback on character inputs to replace or discard them. Modify 'EventChar' to replace or discard, or return 1 in callback to discard. |
| CALLBACK\_RESIZE | Callback on buffer capacity changes request (beyond 'buf\_size' parameter value), allowing the string to grow. Notify when the string wants to be resized (for string types which hold a cache of their Size). You will be provided a new BufSize in the callback and NEED to honor it. (see misc/cpp/imgui\_stdlib.h for an example of using this) |
| CALLBACK\_EDIT | Callback on any edit. Note that `input_text()` already returns true on edit + you can always use `is_item_edited()`. The callback is useful to manipulate the underlying buffer while focus is active. |
| WORD\_WRAP | `input_text_multiline()`: word-wrap lines that are too long. |

### Enum: ItemFlags

| Name | Description |
| --- | --- |
| NONE | (Default) |
| NO\_TAB\_STOP | Disable keyboard tabbing. This is a "lighter" version of `ItemFlags.NO_NAV`. |
| NO\_NAV | Disable any form of focusing (keyboard/gamepad directional navigation and `set_keyboard_focus_here()` calls). |
| NO\_NAV\_DEFAULT\_FOCUS | Disable item being a candidate for default focus (e.g. used by title bar items). |
| BUTTON\_REPEAT | Any button-like behavior will have repeat mode enabled (based on io.KeyRepeatDelay and io.KeyRepeatRate values). Note that you can also call `is_item_active()` after any button to tell if it is being held. |
| AUTO\_CLOSE\_POPUPS | `menu_item()`/`selectable()` automatically close their parent popup window. |
| ALLOW\_DUPLICATE\_ID | Allow submitting an item with the same identifier as an item already submitted this frame without triggering a warning tooltip if io.ConfigDebugHighlightIdConflicts is set. |
| DISABLED | \[Internal] Disable interactions. DOES NOT affect visuals. This is used by `begin_disabled()`/`end_disabled()` and only provided here so you can read back via `get_item_flags()`. |

### Enum: Key

| Name | Description |
| --- | --- |
| KEY\_NONE |  |
| KEY\_NAMED\_KEY\_BEGIN |  |
| KEY\_TAB |  |
| KEY\_LEFT\_ARROW |  |
| KEY\_RIGHT\_ARROW |  |
| KEY\_UP\_ARROW |  |
| KEY\_DOWN\_ARROW |  |
| KEY\_PAGE\_UP |  |
| KEY\_PAGE\_DOWN |  |
| KEY\_HOME |  |
| KEY\_END |  |
| KEY\_INSERT |  |
| KEY\_DELETE |  |
| KEY\_BACKSPACE |  |
| KEY\_SPACE |  |
| KEY\_ENTER |  |
| KEY\_ESCAPE |  |
| KEY\_LEFT\_CTRL |  |
| KEY\_LEFT\_SHIFT |  |
| KEY\_LEFT\_ALT |  |
| KEY\_LEFT\_SUPER |  |
| KEY\_RIGHT\_CTRL |  |
| KEY\_RIGHT\_SHIFT |  |
| KEY\_RIGHT\_ALT |  |
| KEY\_RIGHT\_SUPER |  |
| KEY\_MENU |  |
| KEY\_0 |  |
| KEY\_1 |  |
| KEY\_2 |  |
| KEY\_3 |  |
| KEY\_4 |  |
| KEY\_5 |  |
| KEY\_6 |  |
| KEY\_7 |  |
| KEY\_8 |  |
| KEY\_9 |  |
| KEY\_A |  |
| KEY\_B |  |
| KEY\_C |  |
| KEY\_D |  |
| KEY\_E |  |
| KEY\_F |  |
| KEY\_G |  |
| KEY\_H |  |
| KEY\_I |  |
| KEY\_J |  |
| KEY\_K |  |
| KEY\_L |  |
| KEY\_M |  |
| KEY\_N |  |
| KEY\_O |  |
| KEY\_P |  |
| KEY\_Q |  |
| KEY\_R |  |
| KEY\_S |  |
| KEY\_T |  |
| KEY\_U |  |
| KEY\_V |  |
| KEY\_W |  |
| KEY\_X |  |
| KEY\_Y |  |
| KEY\_Z |  |
| KEY\_F1 |  |
| KEY\_F2 |  |
| KEY\_F3 |  |
| KEY\_F4 |  |
| KEY\_F5 |  |
| KEY\_F6 |  |
| KEY\_F7 |  |
| KEY\_F8 |  |
| KEY\_F9 |  |
| KEY\_F10 |  |
| KEY\_F11 |  |
| KEY\_F12 |  |
| KEY\_F13 |  |
| KEY\_F14 |  |
| KEY\_F15 |  |
| KEY\_F16 |  |
| KEY\_F17 |  |
| KEY\_F18 |  |
| KEY\_F19 |  |
| KEY\_F20 |  |
| KEY\_F21 |  |
| KEY\_F22 |  |
| KEY\_F23 |  |
| KEY\_F24 |  |
| KEY\_APOSTROPHE |  |
| KEY\_COMMA |  |
| KEY\_MINUS |  |
| KEY\_PERIOD |  |
| KEY\_SLASH |  |
| KEY\_SEMICOLON |  |
| KEY\_EQUAL |  |
| KEY\_LEFT\_BRACKET |  |
| KEY\_BACKSLASH |  |
| KEY\_RIGHT\_BRACKET |  |
| KEY\_GRAVE\_ACCENT |  |
| KEY\_CAPS\_LOCK |  |
| KEY\_SCROLL\_LOCK |  |
| KEY\_NUM\_LOCK |  |
| KEY\_PRINT\_SCREEN |  |
| KEY\_PAUSE |  |
| KEY\_KEYPAD0 |  |
| KEY\_KEYPAD1 |  |
| KEY\_KEYPAD2 |  |
| KEY\_KEYPAD3 |  |
| KEY\_KEYPAD4 |  |
| KEY\_KEYPAD5 |  |
| KEY\_KEYPAD6 |  |
| KEY\_KEYPAD7 |  |
| KEY\_KEYPAD8 |  |
| KEY\_KEYPAD9 |  |
| KEY\_KEYPAD\_DECIMAL |  |
| KEY\_KEYPAD\_DIVIDE |  |
| KEY\_KEYPAD\_MULTIPLY |  |
| KEY\_KEYPAD\_SUBTRACT |  |
| KEY\_KEYPAD\_ADD |  |
| KEY\_KEYPAD\_ENTER |  |
| KEY\_KEYPAD\_EQUAL |  |
| KEY\_APP\_BACK |  |
| KEY\_APP\_FORWARD |  |
| KEY\_OEM102 |  |
| KEY\_GAMEPAD\_START |  |
| KEY\_GAMEPAD\_BACK |  |
| KEY\_GAMEPAD\_FACE\_LEFT |  |
| KEY\_GAMEPAD\_FACE\_RIGHT |  |
| KEY\_GAMEPAD\_FACE\_UP |  |
| KEY\_GAMEPAD\_FACE\_DOWN |  |
| KEY\_GAMEPAD\_DPAD\_LEFT |  |
| KEY\_GAMEPAD\_DPAD\_RIGHT |  |
| KEY\_GAMEPAD\_DPAD\_UP |  |
| KEY\_GAMEPAD\_DPAD\_DOWN |  |
| KEY\_GAMEPAD\_L1 |  |
| KEY\_GAMEPAD\_R1 |  |
| KEY\_GAMEPAD\_L2 |  |
| KEY\_GAMEPAD\_R2 |  |
| KEY\_GAMEPAD\_L3 |  |
| KEY\_GAMEPAD\_R3 |  |
| KEY\_GAMEPAD\_L\_STICK\_LEFT |  |
| KEY\_GAMEPAD\_L\_STICK\_RIGHT |  |
| KEY\_GAMEPAD\_L\_STICK\_UP |  |
| KEY\_GAMEPAD\_L\_STICK\_DOWN |  |
| KEY\_GAMEPAD\_R\_STICK\_LEFT |  |
| KEY\_GAMEPAD\_R\_STICK\_RIGHT |  |
| KEY\_GAMEPAD\_R\_STICK\_UP |  |
| KEY\_GAMEPAD\_R\_STICK\_DOWN |  |
| KEY\_MOUSE\_LEFT |  |
| KEY\_MOUSE\_RIGHT |  |
| KEY\_MOUSE\_MIDDLE |  |
| KEY\_MOUSE\_X1 |  |
| KEY\_MOUSE\_X2 |  |
| KEY\_MOUSE\_WHEEL\_X |  |
| KEY\_MOUSE\_WHEEL\_Y |  |
| KEY\_RESERVED\_FOR\_MOD\_CTRL |  |
| KEY\_RESERVED\_FOR\_MOD\_SHIFT |  |
| KEY\_RESERVED\_FOR\_MOD\_ALT |  |
| KEY\_RESERVED\_FOR\_MOD\_SUPER |  |
| KEY\_NAMED\_KEY\_END |  |
| KEY\_NAMED\_KEY\_COUNT |  |
| MOD\_NONE |  |
| MOD\_CTRL |  |
| MOD\_SHIFT |  |
| MOD\_ALT |  |
| MOD\_SUPER |  |

### Enum: MouseButton

| Name | Description |
| --- | --- |
| LEFT |  |
| RIGHT |  |
| MIDDLE |  |
| COUNT |  |

### Enum: MouseCursor

| Name | Description |
| --- | --- |
| NONE |  |
| ARROW |  |
| TEXT\_INPUT | When hovering over `input_text`, etc. |
| RESIZE\_ALL | (Unused by Dear ImGui functions) |
| RESIZE\_NS | When hovering over a horizontal border |
| RESIZE\_EW | When hovering over a vertical border or a column |
| RESIZE\_NESW | When hovering over the bottom-left corner of a window |
| RESIZE\_NWSE | When hovering over the bottom-right corner of a window |
| HAND | (Unused by Dear ImGui functions. Use for e.g. hyperlinks) |
| WAIT | When waiting for something to process/load. |
| PROGRESS | When waiting for something to process/load, but application is still interactive. |
| NOT\_ALLOWED | When hovering something with disallowed interaction. Usually a crossed circle. |
| COUNT |  |

### Enum: MouseSource

| Name | Description |
| --- | --- |
| MOUSE | Input is coming from an actual mouse. |
| TOUCH\_SCREEN | Input is coming from a touch screen (no hovering prior to initial press, less precise initial press aiming, dual-axis wheeling possible). |
| PEN | Input is coming from a pressure/magnetic pen (often used in conjunction with high-sampling rates). |
| COUNT |  |

### Enum: PopupFlags

| Name | Description |
| --- | --- |
| NONE |  |
| MOUSE\_BUTTON\_LEFT | For BeginPopupContext\*(): open on Left Mouse release. Only one button allowed! |
| MOUSE\_BUTTON\_RIGHT | For BeginPopupContext\*(): open on Right Mouse release. Only one button allowed! (default) |
| MOUSE\_BUTTON\_MIDDLE | For BeginPopupContext\*(): open on Middle Mouse release. Only one button allowed! |
| NO\_REOPEN | For `open_popup`*(), BeginPopupContext*(): don't reopen same popup if already open (won't reposition, won't reinitialize navigation) |
| NO\_OPEN\_OVER\_EXISTING\_POPUP | For `open_popup`*(), BeginPopupContext*(): don't open if there's already a popup at the same level of the popup stack |
| NO\_OPEN\_OVER\_ITEMS | For `begin_popup_context_window()`: don't return true when hovering items, only when hovering empty space |
| ANY\_POPUP\_ID | For `is_popup_open()`: ignore the ImGuiID parameter and test for any popup. |
| ANY\_POPUP\_LEVEL | For `is_popup_open()`: search/test at any level of the popup stack (default test in the current level) |
| ANY\_POPUP |  |

### Enum: SelectableFlags

| Name | Description |
| --- | --- |
| NONE |  |
| NO\_AUTO\_CLOSE\_POPUPS | Clicking this doesn't close parent popup window (overrides `ItemFlags.AUTO_CLOSE_POPUPS`) |
| SPAN\_ALL\_COLUMNS | Frame will span all columns of its container table (text will still fit in current column) |
| ALLOW\_DOUBLE\_CLICK | Generate press events on double clicks too |
| DISABLED | Cannot be selected, display grayed out text |
| ALLOW\_OVERLAP | Hit testing will allow subsequent widgets to overlap this one. Require previous frame HoveredId to match before being usable. Shortcut to calling `set_next_item_allow_overlap()`. |
| HIGHLIGHT | Make the item be displayed as if it is hovered |
| SELECT\_ON\_NAV | Auto-select when moved into, unless Ctrl is held. Automatic when in a `begin_multi_select()` block. |

### Enum: SliderFlags

| Name | Description |
| --- | --- |
| NONE |  |
| LOGARITHMIC | Make the widget logarithmic (linear otherwise). Consider using `SliderFlags.NO_ROUND_TO_FORMAT` with this if using a format-string with small amount of digits. |
| NO\_ROUND\_TO\_FORMAT | Disable rounding underlying value to match precision of the display format string (e.g. %.3f values are rounded to those 3 digits). |
| NO\_INPUT | Disable Ctrl+Click or Enter key allowing to input text directly into the widget. |
| WRAP\_AROUND | Enable wrapping around from max to min and from min to max. Only supported by DragXXX() functions for now. |
| CLAMP\_ON\_INPUT | Clamp value to min/max bounds when input manually with Ctrl+Click. By default Ctrl+Click allows going out of bounds. |
| CLAMP\_ZERO\_RANGE | Clamp even if min==max==0.0. Otherwise due to legacy reason DragXXX functions don't clamp with those values. When your clamping limits are dynamic you almost always want to use it. |
| NO\_SPEED\_TWEAKS | Disable keyboard modifiers altering tweak speed. Useful if you want to alter tweak speed yourself based on your own logic. |
| COLOR\_MARKERS | `drag_scalar_n()`, `slider_scalar_n()`: Draw R/G/B/A color markers on each component. |
| ALWAYS\_CLAMP |  |

### Enum: StyleVar

| Name | Description |
| --- | --- |
| ALPHA | Float     Alpha |
| DISABLED\_ALPHA | Float     DisabledAlpha |
| WINDOW\_PADDING | ImVec2    WindowPadding |
| WINDOW\_ROUNDING | Float     WindowRounding |
| WINDOW\_BORDER\_SIZE | Float     WindowBorderSize |
| WINDOW\_MIN\_SIZE | ImVec2    WindowMinSize |
| WINDOW\_TITLE\_ALIGN | ImVec2    WindowTitleAlign |
| CHILD\_ROUNDING | Float     ChildRounding |
| CHILD\_BORDER\_SIZE | Float     ChildBorderSize |
| POPUP\_ROUNDING | Float     PopupRounding |
| POPUP\_BORDER\_SIZE | Float     PopupBorderSize |
| FRAME\_PADDING | ImVec2    FramePadding |
| FRAME\_ROUNDING | Float     FrameRounding |
| FRAME\_BORDER\_SIZE | Float     FrameBorderSize |
| ITEM\_SPACING | ImVec2    ItemSpacing |
| ITEM\_INNER\_SPACING | ImVec2    ItemInnerSpacing |
| INDENT\_SPACING | Float     IndentSpacing |
| CELL\_PADDING | ImVec2    CellPadding |
| SCROLLBAR\_SIZE | Float     ScrollbarSize |
| SCROLLBAR\_ROUNDING | Float     ScrollbarRounding |
| SCROLLBAR\_PADDING | Float     ScrollbarPadding |
| GRAB\_MIN\_SIZE | Float     GrabMinSize |
| GRAB\_ROUNDING | Float     GrabRounding |
| IMAGE\_ROUNDING | Float     ImageRounding |
| IMAGE\_BORDER\_SIZE | Float     ImageBorderSize |
| TAB\_ROUNDING | Float     TabRounding |
| TAB\_BORDER\_SIZE | Float     TabBorderSize |
| TAB\_MIN\_WIDTH\_BASE | Float     TabMinWidthBase |
| TAB\_MIN\_WIDTH\_SHRINK | Float     TabMinWidthShrink |
| TAB\_BAR\_BORDER\_SIZE | Float     TabBarBorderSize |
| TAB\_BAR\_OVERLINE\_SIZE | Float     TabBarOverlineSize |
| TABLE\_ANGLED\_HEADERS\_ANGLE | Float     TableAngledHeadersAngle |
| TABLE\_ANGLED\_HEADERS\_TEXT\_ALIGN | ImVec2  TableAngledHeadersTextAlign |
| TREE\_LINES\_SIZE | Float     TreeLinesSize |
| TREE\_LINES\_ROUNDING | Float     TreeLinesRounding |
| BUTTON\_TEXT\_ALIGN | ImVec2    ButtonTextAlign |
| SELECTABLE\_TEXT\_ALIGN | ImVec2    SelectableTextAlign |
| SEPARATOR\_SIZE | Float     SeparatorSize |
| SEPARATOR\_TEXT\_BORDER\_SIZE | Float     SeparatorTextBorderSize |
| SEPARATOR\_TEXT\_ALIGN | ImVec2    SeparatorTextAlign |
| SEPARATOR\_TEXT\_PADDING | ImVec2    SeparatorTextPadding |
| COUNT |  |

### Enum: TabBarFlags

| Name | Description |
| --- | --- |
| NONE |  |
| REORDERABLE | Allow manually dragging tabs to re-order them + New tabs are appended at the end of list |
| AUTO\_SELECT\_NEW\_TABS | Automatically select new tabs when they appear |
| TAB\_LIST\_POPUP\_BUTTON | Disable buttons to open the tab list popup |
| NO\_CLOSE\_WITH\_MIDDLE\_MOUSE\_BUTTON | Disable behavior of closing tabs (that are submitted with p\_open != NULL) with middle mouse button. You may handle this behavior manually on user's side with if (`is_item_hovered()` && `is_mouse_clicked(2)`) \*p\_open = false. |
| NO\_TAB\_LIST\_SCROLLING\_BUTTONS | Disable scrolling buttons (apply when fitting policy is `TabBarFlags.FITTING_POLICY_SCROLL`) |
| NO\_TOOLTIP | Disable tooltips when hovering a tab |
| DRAW\_SELECTED\_OVERLINE | Draw selected overline markers over selected tab |
| FITTING\_POLICY\_MIXED | Shrink down tabs when they don't fit, until width is style.TabMinWidthShrink, then enable scrolling buttons. |
| FITTING\_POLICY\_SHRINK | Shrink down tabs when they don't fit |
| FITTING\_POLICY\_SCROLL | Enable scrolling buttons when tabs don't fit |

### Enum: TabItemFlags

| Name | Description |
| --- | --- |
| NONE |  |
| UNSAVED\_DOCUMENT | Display a dot next to the title + set `TabItemFlags.NO_ASSUMED_CLOSURE`. |
| SET\_SELECTED | Trigger flag to programmatically make the tab selected when calling `begin_tab_item()` |
| NO\_CLOSE\_WITH\_MIDDLE\_MOUSE\_BUTTON | Disable behavior of closing tabs (that are submitted with p\_open != NULL) with middle mouse button. You may handle this behavior manually on user's side with if (`is_item_hovered()` && `is_mouse_clicked(2)`) \*p\_open = false. |
| NO\_PUSH\_ID | Don't call `push_id()`/`pop_id()` on `begin_tab_item()`/`end_tab_item()` |
| NO\_TOOLTIP | Disable tooltip for the given tab |
| NO\_REORDER | Disable reordering this tab or having another tab cross over this tab |
| LEADING | Enforce the tab position to the left of the tab bar (after the tab list popup button) |
| TRAILING | Enforce the tab position to the right of the tab bar (before the scrolling buttons) |
| NO\_ASSUMED\_CLOSURE | Tab is selected when trying to close + closure is not immediately assumed (will wait for user to stop submitting the tab). Otherwise closure is assumed when pressing the X, so if you keep submitting the tab may reappear at end of tab bar. |

### Enum: TableBgTarget

| Name | Description |
| --- | --- |
| NONE |  |
| ROW\_BG0 | Set row background color 0 (generally used for background, automatically set when `TableFlags.ROW_BG` is used) |
| ROW\_BG1 | Set row background color 1 (generally used for selection marking) |
| CELL\_BG | Set cell background color (top-most color) |

### Enum: TableColumnFlags

| Name | Description |
| --- | --- |
| NONE |  |
| DISABLED | Overriding/master disable flag: hide column, won't show in context menu (unlike calling `table_set_column_enabled()` which manipulates the user accessible state) |
| DEFAULT\_HIDE | Default as a hidden/disabled column. |
| DEFAULT\_SORT | Default as a sorting column. |
| WIDTH\_STRETCH | Column will stretch. Preferable with horizontal scrolling disabled (default if table sizing policy is \_SizingStretchSame or \_SizingStretchProp). |
| WIDTH\_FIXED | Column will not stretch. Preferable with horizontal scrolling enabled (default if table sizing policy is \_SizingFixedFit and table is resizable). |
| NO\_RESIZE | Disable manual resizing. |
| NO\_REORDER | Disable manual reordering this column, this will also prevent other columns from crossing over this column. |
| NO\_HIDE | Disable ability to hide/disable this column. |
| NO\_CLIP | Disable clipping for this column (all NoClip columns will render in a same draw command). |
| NO\_SORT | Disable ability to sort on this field (even if `TableFlags.SORTABLE` is set on the table). |
| NO\_SORT\_ASCENDING | Disable ability to sort in the ascending direction. |
| NO\_SORT\_DESCENDING | Disable ability to sort in the descending direction. |
| NO\_HEADER\_LABEL | `table_headers_row()` will submit an empty label for this column. Convenient for some small columns. Name will still appear in context menu or in angled headers. You may append into this cell by calling `table_set_column_index()` right after the `table_headers_row()` call. |
| NO\_HEADER\_WIDTH | Disable header text width contribution to automatic column width. |
| PREFER\_SORT\_ASCENDING | Make the initial sort direction Ascending when first sorting on this column (default). |
| PREFER\_SORT\_DESCENDING | Make the initial sort direction Descending when first sorting on this column. |
| INDENT\_ENABLE | Use current `indent` value when entering cell (default for column 0). |
| INDENT\_DISABLE | Ignore current `indent` value when entering cell (default for columns > 0). Indentation changes *within* the cell will still be honored. |
| ANGLED\_HEADER | `table_headers_row()` will submit an angled header row for this column. Note this will add an extra row. |
| IS\_ENABLED | Status: is enabled == not hidden by user/api (referred to as "Hide" in \_DefaultHide and \_NoHide) flags. |
| IS\_VISIBLE | Status: is visible == is enabled AND not clipped by scrolling. |
| IS\_SORTED | Status: is currently part of the sort specs |
| IS\_HOVERED | Status: is hovered by mouse |

### Enum: TableFlags

| Name | Description |
| --- | --- |
| NONE |  |
| RESIZABLE | Enable resizing columns. |
| REORDERABLE | Enable reordering columns in header row. (Need calling `table_setup_column()` + `table_headers_row()` to display headers, or using `TableFlags.CONTEXT_MENU_IN_BODY` to access context-menu without headers). |
| HIDEABLE | Enable hiding/disabling columns in context menu. |
| SORTABLE | Enable sorting. Call `table_get_sort_specs()` to obtain sort specs. Also see `TableFlags.SORT_MULTI` and `TableFlags.SORT_TRISTATE`. |
| NO\_SAVED\_SETTINGS | Disable persisting columns order, width, visibility and sort settings in the .ini file. |
| CONTEXT\_MENU\_IN\_BODY | Right-click on columns body/contents will also display table context menu. By default it is available in `table_headers_row()`. |
| ROW\_BG | Set each RowBg color with `Col.TABLE_ROW_BG` or `Col.TABLE_ROW_BG_ALT` (equivalent of calling `table_set_bg_color` with ImGuiTableBgFlags\_RowBg0 on each row manually) |
| BORDERS\_INNER\_H | Draw horizontal borders between rows. |
| BORDERS\_OUTER\_H | Draw horizontal borders at the top and bottom. |
| BORDERS\_INNER\_V | Draw vertical borders between columns. |
| BORDERS\_OUTER\_V | Draw vertical borders on the left and right sides. |
| BORDERS\_H | Draw horizontal borders. |
| BORDERS\_V | Draw vertical borders. |
| BORDERS\_INNER | Draw inner borders. |
| BORDERS\_OUTER | Draw outer borders. |
| BORDERS | Draw all borders. |
| NO\_BORDERS\_IN\_BODY | \[ALPHA] Disable vertical borders in columns Body (borders will always appear in Headers). -> May move to style |
| NO\_BORDERS\_IN\_BODY\_UNTIL\_RESIZE | \[ALPHA] Disable vertical borders in columns Body until hovered for resize (borders will always appear in Headers). -> May move to style |
| SIZING\_FIXED\_FIT | `columns` default to \_WidthFixed or \_WidthAuto (if resizable or not resizable), matching contents width. |
| SIZING\_FIXED\_SAME | `columns` default to \_WidthFixed or \_WidthAuto (if resizable or not resizable), matching the maximum contents width of all columns. Implicitly enable `TableFlags.NO_KEEP_COLUMNS_VISIBLE`. |
| SIZING\_STRETCH\_PROP | `columns` default to \_WidthStretch with default weights proportional to each columns contents widths. |
| SIZING\_STRETCH\_SAME | `columns` default to \_WidthStretch with default weights all equal, unless overridden by `table_setup_column()`. |
| NO\_HOST\_EXTEND\_X | Make outer width auto-fit to columns, overriding outer\_size.x value. Only available when ScrollX/ScrollY are disabled and Stretch columns are not used. |
| NO\_HOST\_EXTEND\_Y | Make outer height stop exactly at outer\_size.y (prevent auto-extending table past the limit). Only available when ScrollX/ScrollY are disabled. Data below the limit will be clipped and not visible. |
| NO\_KEEP\_COLUMNS\_VISIBLE | Disable keeping column always minimally visible when ScrollX is off and table gets too small. Not recommended if columns are resizable. |
| PRECISE\_WIDTHS | Disable distributing remainder width to stretched columns (width allocation on a 100-wide table with 3 columns: Without this flag: 33,33,34. With this flag: 33,33,33). With larger number of columns, resizing will appear to be less smooth. |
| NO\_CLIP | Disable clipping rectangle for every individual columns (reduce draw command count, items will be able to overflow into other columns). Generally incompatible with `table_setup_scroll_freeze()`. |
| PAD\_OUTER\_X | Default if BordersOuterV is on. Enable outermost padding. Generally desirable if you have headers. |
| NO\_PAD\_OUTER\_X | Default if BordersOuterV is off. Disable outermost padding. |
| NO\_PAD\_INNER\_X | Disable inner padding between columns (double inner padding if BordersOuterV is on, single inner padding if BordersOuterV is off). |
| SCROLL\_X | Enable horizontal scrolling. Require 'outer\_size' parameter of `begin_table()` to specify the container size. Changes default sizing policy. Because this creates a child window, ScrollY is currently generally recommended when using ScrollX. |
| SCROLL\_Y | Enable vertical scrolling. Require 'outer\_size' parameter of `begin_table()` to specify the container size. |
| SORT\_MULTI | Hold shift when clicking headers to sort on multiple column. `table_get_sort_specs()` may return specs where (SpecsCount > 1). |
| SORT\_TRISTATE | Allow no sorting, disable default sorting. `table_get_sort_specs()` may return specs where (SpecsCount == 0). |
| HIGHLIGHT\_HOVERED\_COLUMN | Highlight column headers when hovered (may evolve into a fuller highlight) |

### Enum: TableRowFlags

| Name | Description |
| --- | --- |
| NONE |  |
| HEADERS | Identify header row (set default background color + width of its contents accounted differently for auto column width) |

### Enum: TextureFormat

| Name | Description |
| --- | --- |
| RGBA32 | 4 components per pixel, each is unsigned 8-bit. Total size = TexWidth \* TexHeight \* 4 |
| ALPHA8 | 1 component per pixel, each is unsigned 8-bit. Total size = TexWidth \* TexHeight |

### Enum: TextureStatus

| Name | Description |
| --- | --- |
| OK |  |
| DESTROYED | Backend destroyed the texture. |
| WANT\_CREATE | Requesting backend to create the texture. Set status OK when done. |
| WANT\_UPDATES | Requesting backend to update specific blocks of pixels (write to texture portions which have never been used before). Set status OK when done. |
| WANT\_DESTROY | Requesting backend to destroy the texture. Set status to Destroyed when done. |

### Enum: TreeNodeFlags

| Name | Description |
| --- | --- |
| NONE |  |
| SELECTED | Draw as selected |
| FRAMED | Draw frame with background (e.g. for `collapsing_header`) |
| ALLOW\_OVERLAP | Hit testing will allow subsequent widgets to overlap this one. Require previous frame HoveredId to match before being usable. Shortcut to calling `set_next_item_allow_overlap()`. |
| NO\_TREE\_PUSH\_ON\_OPEN | Don't do a `tree_push()` when open (e.g. for `collapsing_header`) = no extra indent nor pushing on ID stack |
| NO\_AUTO\_OPEN\_ON\_LOG | Don't automatically and temporarily open node when Logging is active (by default logging will automatically open tree nodes) |
| DEFAULT\_OPEN | Default node to be open |
| OPEN\_ON\_DOUBLE\_CLICK | Open on double-click instead of simple click (default for multi-select unless any \_OpenOnXXX behavior is set explicitly). Both behaviors may be combined. |
| OPEN\_ON\_ARROW | Open when clicking on the arrow part (default for multi-select unless any \_OpenOnXXX behavior is set explicitly). Both behaviors may be combined. |
| LEAF | No collapsing, no arrow (use as a convenience for leaf nodes). Note: will always open a tree/id scope and return true. If you never use that scope, add `TreeNodeFlags.NO_TREE_PUSH_ON_OPEN`. |
| BULLET | Display a bullet instead of arrow. IMPORTANT: node can still be marked open/close if you don't set the \_Leaf flag! |
| FRAME\_PADDING | 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()` before the node. |
| SPAN\_AVAIL\_WIDTH | Extend hit box to the right-most edge, even if not framed. This is not the default in order to allow adding other items on the same line without using AllowOverlap mode. |
| SPAN\_FULL\_WIDTH | Extend hit box to the left-most and right-most edges (cover the indent area). |
| SPAN\_LABEL\_WIDTH | Narrow hit box + narrow hovering highlight, will only cover the label text. |
| SPAN\_ALL\_COLUMNS | Frame will span all columns of its container table (label will still fit in current column) |
| LABEL\_SPAN\_ALL\_COLUMNS | Label will span all columns of its container table |
| NAV\_LEFT\_JUMPS\_TO\_PARENT | Nav: left arrow moves back to parent. This is processed in `tree_pop()` when there's an unfulfilled Left nav request remaining. |
| COLLAPSING\_HEADER |  |
| DRAW\_LINES\_NONE | No lines drawn |
| DRAW\_LINES\_FULL | Horizontal lines to child nodes. Vertical line drawn down to `tree_pop()` position: cover full contents. Faster (for large trees). |
| DRAW\_LINES\_TO\_NODES | Horizontal lines to child nodes. Vertical line drawn down to bottom-most child node. Slower (for large trees). |

### Enum: WindowFlags

| Name | Description |
| --- | --- |
| NONE |  |
| NO\_TITLE\_BAR | Disable title-bar |
| NO\_RESIZE | Disable user resizing with the lower-right grip |
| NO\_MOVE | Disable user moving the window |
| NO\_SCROLLBAR | Disable scrollbars (window can still scroll with mouse or programmatically) |
| NO\_SCROLL\_WITH\_MOUSE | Disable user vertically scrolling with mouse wheel. On child window, mouse wheel will be forwarded to the parent unless NoScrollbar is also set. |
| NO\_COLLAPSE | Disable user collapsing window by double-clicking on it. Also referred to as Window Menu Button (e.g. within a docking node). |
| ALWAYS\_AUTO\_RESIZE | Resize every window to its content every frame |
| NO\_BACKGROUND | Disable drawing background color (WindowBg, etc.) and outside border. Similar as using `set_next_window_bg_alpha(0.0)`. |
| NO\_SAVED\_SETTINGS | Never load/save settings in .ini file |
| NO\_MOUSE\_INPUTS | Disable catching mouse, hovering test with pass through. |
| MENU\_BAR | Has a menu-bar |
| HORIZONTAL\_SCROLLBAR | Allow horizontal scrollbar to appear (off by default). You may use `set_next_window_content_size((width,0.0))`; prior to calling `begin()` to specify width. Read code in imgui\_demo in the "Horizontal Scrolling" section. |
| NO\_FOCUS\_ON\_APPEARING | Disable taking focus when transitioning from hidden to visible state |
| NO\_BRING\_TO\_FRONT\_ON\_FOCUS | Disable bringing window to front when taking focus (e.g. clicking on it or programmatically giving it focus) |
| ALWAYS\_VERTICAL\_SCROLLBAR | Always show vertical scrollbar (even if ContentSize.y < Size.y) |
| ALWAYS\_HORIZONTAL\_SCROLLBAR | Always show horizontal scrollbar (even if ContentSize.x < Size.x) |
| NO\_NAV\_INPUTS | No keyboard/gamepad navigation within the window |
| NO\_NAV\_FOCUS | No focusing toward this window with keyboard/gamepad navigation (e.g. skipped by Ctrl+Tab) |
| UNSAVED\_DOCUMENT | Display a dot next to the title. When used in a tab/docking context, tab is selected when clicking the X + closure is not assumed (will wait for user to stop submitting the tab). Otherwise closure is assumed when pressing the X, so if you keep submitting the tab may reappear at end of tab bar. |
| NO\_NAV |  |
| NO\_DECORATION |  |
| NO\_INPUTS |  |
| CHILD\_WINDOW | Don't use! For internal use by `begin_child()` |
| TOOLTIP | Don't use! For internal use by `begin_tooltip()` |
| POPUP | Don't use! For internal use by `begin_popup()` |
| MODAL | Don't use! For internal use by `begin_popup_modal()` |
| CHILD\_MENU | Don't use! For internal use by `begin_menu()` |

### Enum: DrawListCallbackResult

| Name | Description |
| --- | --- |
| DRAW | No callback, backend should draw elements. |
| CALLBACK | Callback executed, no further processing of this command necessary. |
| RESET\_RENDER\_STATE | Reset render state token, backend should perform render state reset. |

## Class Reference

### Class: DrawList

::: api-signature

```python
DrawList.add_bezier_cubic(
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    p4: tuple[float, float],
    col: int,
    thickness: float,
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_bezier_quadratic(
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    col: int,
    thickness: float,
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_callback(
    callable: int | Callable[[DrawList, DrawCmd, int | bytes], None],
    userdata: int | bytes,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_circle(
    center: tuple[float, float],
    radius: float,
    col: int,
    num_segments: int = 0,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_circle_filled(
    center: tuple[float, float],
    radius: float,
    col: int,
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_concave_poly_filled(
    points: Sequence[tuple[float, float]],
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_concave_poly_filled(
    points: Annotated[NDArray[Any], dict(shape=(None, 2), device='cpu', writable=False)],
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_convex_poly_filled(
    points: Sequence[tuple[float, float]],
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_convex_poly_filled(
    points: Annotated[NDArray[Any], dict(shape=(None, 2), device='cpu', writable=False)],
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_draw_cmd() -> None:
    """
    This is useful if you need to forcefully create a new draw call (to allow for dependent rendering / blending). Otherwise primitives are merged into the same draw-call as much as possible.
    """
```

:::

::: api-signature

```python
DrawList.add_ellipse(
    center: tuple[float, float],
    radius: tuple[float, float],
    col: int,
    rot: float = 0.0,
    num_segments: int = 0,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_ellipse_filled(
    center: tuple[float, float],
    radius: tuple[float, float],
    col: int,
    rot: float = 0.0,
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_image(
    tex_ref: TextureRef | int,
    p_min: tuple[float, float],
    p_max: tuple[float, float],
    uv_min: tuple[float, float] = (0.0, 0.0),
    uv_max: tuple[float, float] = (1.0, 1.0),
    col: int = COL32_WHITE,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_image_quad(
    tex_ref: TextureRef | int,
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    p4: tuple[float, float],
    uv1: tuple[float, float] = (0.0, 0.0),
    uv2: tuple[float, float] = (1.0, 0.0),
    uv3: tuple[float, float] = (1.0, 1.0),
    uv4: tuple[float, float] = (0.0, 1.0),
    col: int = COL32_WHITE,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_image_rounded(
    tex_ref: TextureRef | int,
    p_min: tuple[float, float],
    p_max: tuple[float, float],
    uv_min: tuple[float, float],
    uv_max: tuple[float, float],
    col: int,
    rounding: float,
    flags: DrawFlags = DrawFlags.NONE,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_line(
    p1: tuple[float, float],
    p2: tuple[float, float],
    col: int,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_ngon(
    center: tuple[float, float],
    radius: float,
    col: int,
    num_segments: int,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_ngon_filled(
    center: tuple[float, float],
    radius: float,
    col: int,
    num_segments: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_polyline(
    points: Sequence[tuple[float, float]],
    col: int,
    flags: DrawFlags,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_polyline(
    points: Annotated[NDArray[Any], dict(shape=(None, 2), device='cpu', writable=False)],
    col: int,
    flags: DrawFlags,
    thickness: float,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_quad(
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    p4: tuple[float, float],
    col: int,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_quad_filled(
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    p4: tuple[float, float],
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_rect(
    p_min: tuple[float, float],
    p_max: tuple[float, float],
    col: int,
    rounding: float = 0.0,
    flags: DrawFlags = DrawFlags.NONE,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_rect_filled(
    p_min: tuple[float, float],
    p_max: tuple[float, float],
    col: int,
    rounding: float = 0.0,
    flags: DrawFlags = DrawFlags.NONE,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_rect_filled_multi_color(
    p_min: tuple[float, float],
    p_max: tuple[float, float],
    col_upr_left: int,
    col_upr_right: int,
    col_bot_right: int,
    col_bot_left: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_text(
    pos: tuple[float, float],
    col: int,
    text: str,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_text(
    font: Font,
    font_size: float,
    pos: tuple[float, float],
    col: int,
    text: str,
    wrap_width: float = 0.0,
    cpu_fine_clip_rect: tuple[float, float, float, float] | None = None,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_triangle(
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    col: int,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.add_triangle_filled(
    p1: tuple[float, float],
    p2: tuple[float, float],
    p3: tuple[float, float],
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.channels_merge() -> None:
```

:::

::: api-signature

```python
DrawList.channels_set_current(
    n: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.channels_split(
    count: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.commands -> Iterator[DrawCmd]:
```

:::

::: api-signature

```python
DrawList.get_clip_rect_max() -> tuple[float, float]:
```

:::

::: api-signature

```python
DrawList.get_clip_rect_min() -> tuple[float, float]:
```

:::

::: api-signature

```python
DrawList.idx_buffer_data -> int:
```

:::

::: api-signature

```python
DrawList.idx_buffer_size -> int:
```

:::

::: api-signature

```python
DrawList.path_arc_to(
    center: tuple[float, float],
    radius: float,
    a_min: float,
    a_max: float,
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_arc_to_fast(
    center: tuple[float, float],
    radius: float,
    a_min_of_12: int,
    a_max_of_12: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_bezier_cubic_curve_to(
    p2: tuple[float, float],
    p3: tuple[float, float],
    p4: tuple[float, float],
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_bezier_quadratic_curve_to(
    p2: tuple[float, float],
    p3: tuple[float, float],
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_clear() -> None:
```

:::

::: api-signature

```python
DrawList.path_elliptical_arc_to(
    center: tuple[float, float],
    radius: tuple[float, float],
    rot: float,
    a_min: float,
    a_max: float,
    num_segments: int = 0,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_fill_concave(
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_fill_convex(
    col: int,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_line_to(
    pos: tuple[float, float],
) -> None:
```

:::

::: api-signature

```python
DrawList.path_line_to_merge_duplicate(
    pos: tuple[float, float],
) -> None:
```

:::

::: api-signature

```python
DrawList.path_rect(
    rect_min: tuple[float, float],
    rect_max: tuple[float, float],
    rounding: float = 0.0,
    flags: DrawFlags = DrawFlags.NONE,
) -> None:
```

:::

::: api-signature

```python
DrawList.path_stroke(
    col: int,
    flags: DrawFlags = DrawFlags.NONE,
    thickness: float = 1.0,
) -> None:
```

:::

::: api-signature

```python
DrawList.pop_clip_rect() -> None:
```

:::

::: api-signature

```python
DrawList.pop_texture() -> None:
```

:::

::: api-signature

```python
DrawList.ptr() -> int:
    """
    Internal function for reference book keeping.
    """
```

:::

::: api-signature

```python
DrawList.push_clip_rect(
    clip_rect_min: tuple[float, float],
    clip_rect_max: tuple[float, float],
    intersect_with_current_clip_rect: bool = False,
) -> None:
    """
    Render-level scissoring. This is passed down to your render function but not used for CPU-side coarse clipping. Prefer using higher-level `imgui.push_clip_rect()` to affect logic (hit-testing and widget culling)
    """
```

:::

::: api-signature

```python
DrawList.push_clip_rect_full_screen() -> None:
```

:::

::: api-signature

```python
DrawList.push_texture(
    tex_ref: TextureRef | int,
) -> None:
```

:::

::: api-signature

```python
DrawList.vtx_buffer_data -> int:
```

:::

::: api-signature

```python
DrawList.vtx_buffer_size -> int:
```

:::
---

---
url: /slimgui/api/implot.md
---

# ImPlot API reference

See [Typing](/guide/typing) for an explanation of the public `imgui` / `implot`
modules and how they relate to the underlying `slimgui.slimgui_ext.*` bindings.

## ImPlot Data Types

Most `implot` plotting functions consume NumPy arrays.

Common accepted shapes include:

* `(N,)` for one-dimensional x/y/value arrays
* `(M, N)` for tabular inputs such as grouped bars or heatmaps
* scalar `np.ndarray` values for interactive tools that modify values in place
* small fixed-shape arrays such as `(2,)` or `(2, 2)` for plot tools

Examples:

```python
xs = np.linspace(0.0, 10.0, 1000)
ys = np.sin(xs)
implot.plot_line("sin(x)", xs, ys)
```

```python
ys = np.random.rand(10)
implot.plot_bars("bars", ys)
```

```python
values = np.random.rand(3, 4)
implot.plot_bar_groups(["A", "B", "C"], values)
```

The bindings generally convert numeric array dtypes automatically where that is safe.
Non-contiguous views are also supported in normal plotting use, for example `data_x[::2]`.

Interactive plot tools use mutable NumPy arrays so the binding can write updated values back
to Python. Examples include: `drag_point`, `drag_line_x`, `drag_line_y`, `drag_rect`.

Those APIs also accept optional scalar `np.ndarray` boolean outputs such as `out_clicked`,
`out_hovered`, and `out_held`.

## ImPlot API functions

### Contexts

::: api-signature

```python
def create_context() -> slimgui.implot.WrappedContext:
    """
    Create an ImPlot context.  Call this after `imgui.create_context()`.
    """
```

:::

::: api-signature

```python
def destroy_context(
    ctx: slimgui.implot.WrappedContext | None,
):
    """
    Destroys an ImPlot context. Call this before `imgui.destroy_context()`. `None` = destroy current context.
    """
```

:::

::: api-signature

```python
def get_current_context() -> slimgui.implot.WrappedContext | None:
    """
    Returns the current ImPlot context. `None` if no context has ben set.
    """
```

:::

::: api-signature

```python
def set_current_context(
    ctx: slimgui.implot.WrappedContext,
) -> None:
    """
    Sets the current ImPlot context.
    """
```

:::

### Begin/End Plot

::: api-signature

````python
def begin_plot(
    title_id: str,
    size: tuple[float, float] = (-1,0),
    flags: PlotFlags = PlotFlags.NONE,
) -> bool:
    """
    Starts a 2D plotting context. If this function returns `True`, `implot.end_plot()` MUST
    be called! You are encouraged to use the following convention:

    ```
    if implot.begin_plot(...):
        implot.plot_line(...)
        ...
        implot.end_plot()
    ```

    Important notes:

    - `title_id` must be unique to the current ImGui ID scope. If you need to avoid ID
      collisions or don't want to display a title in the plot, use double hashes
      (e.g. `"MyPlot##HiddenIdText"` or `"##NoTitle"`).

    - `size` is the **frame** size of the plot widget, not the plot area. The default
      size of plots (i.e. when `(0,0)`) can be modified in your `implot.Style`.
    """
````

:::

Starts a 2D plotting context. If this function returns `True`, `implot.end_plot()` MUST
be called! You are encouraged to use the following convention:

```
if implot.begin_plot(...):
    implot.plot_line(...)
    ...
    implot.end_plot()
```

Important notes:

* `title_id` must be unique to the current ImGui ID scope. If you need to avoid ID
  collisions or don't want to display a title in the plot, use double hashes
  (e.g. `"MyPlot##HiddenIdText"` or `"##NoTitle"`).

* `size` is the **frame** size of the plot widget, not the plot area. The default
  size of plots (i.e. when `(0,0)`) can be modified in your `implot.Style`.

::: api-signature

```python
def end_plot() -> None:
    """
    Only call `implot.end_plot()` if `implot.begin_plot()` returns `True`! Typically called at the end of an if statement conditioned on `implot.begin_plot()`. See example above.
    """
```

:::

### Subplots

`begin_subplots()` starts a subdivided plotting context.  If the function returns `True`,
`end_subplots()` MUST be called! Call `begin_plot()`/`end_plot()` at most `[rows*cols]`
times in between the begining and end of the subplot context.  Plots are
added in row major order (or use `SubplotFlags.COL_MAJOR` if you want column major).

Example:

```python
if implot.begin_subplots("My Subplot", 2, 3, (800, 400)):
    for i in range(6):
        if implot.begin_plot(...):
            implot.plot_line(...)
            ...
            implot.end_plot()
    implot.end_subplots()
```

Produces:

```
  [0] | [1] | [2]
  ----|-----|----
  [3] | [4] | [5]
```

Important notes:

* `title_id` must be unique to the current ImGui ID scope. If you need to avoid ID
  collisions or don't want to display a title in the plot, use double hashes
  (e.g. `"MySubplot##HiddenIdText"` or `"##NoTitle"`).
* `rows` and `cols` must be greater than 0.
* `size` is the size of the entire grid of subplots, not the individual plots
* `row_ratios` and `col_ratios` must have at exactly `rows` and `cols` elements,
  respectively, or an exception is raised.  These are the sizes of the rows and
  columns expressed in ratios.  If the user adjusts the dimensions, the arrays are
  updated with new ratios.
* The `row/col_ratios` arrays must be created with `dtype=np.float32`, e.g.
  `np.array([0.3, 0.7], dtype=np.float32)`.

Important notes regarding `begin_plot()` from inside of `begin_subplots()`:

* The `title_id` parameter of `begin_plot()` (see above) does NOT have to be
  unique when called inside of a subplot context. Subplot IDs are hashed
  for your convenience so you don't have call `imgui.push_id()` or generate unique title
  strings. Simply pass an empty string to `begin_plot()` unless you want to title
  each subplot.
* The `size` parameter of `begin_plot()` (see above) is ignored when inside of a
  subplot context. The actual size of the subplot will be based on the
  `size` value you pass to `begin_subplots()` and `row_ratios`/`col_ratios` if provided.

::: api-signature

```python
def begin_subplots(
    title_id: str,
    rows: int,
    cols: int,
    size: tuple[float, float],
    flags: SubplotFlags = SubplotFlags.NONE,
    row_ratios: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu')] | None = None,
    col_ratios: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu')] | None = None,
) -> bool:
    """
    See https://nurpax.github.io/slimgui/apiref_implot.html#subplots for details.
    """
```

:::

::: api-signature

```python
def end_subplots() -> None:
```

:::

### Setup

The following API allows you to set up and customize various aspects of the current plot. The functions should be called immediately after `begin_plot()` and before any other API calls. Typical usage is as follows:

```python
if implot.begin_plot(...):                     # 1) begin a new plot
    implot.setup_axis(im_axis_x1, "My X-Axis") # 2) make setup calls
    implot.setup_axis(im_axis_y1, "My Y-Axis")
    implot.setup_legend(im_plot_location_north)
    ...
    implot.setup_finish()                      # 3) [optional] explicitly finish setup
    implot.plot_line(...)                      # 4) plot items
    ...
    implot.end_plot()                          # 5) end the plot
```

**Important Notes**:

* Always call setup code at the top of your `begin_plot()` conditional statement.
* Setup is locked once you start plotting or explicitly call `setup_finish()`.\
  Do **NOT** call setup code after you begin plotting or after you make any non-setup API calls (e.g., utilities like `plot_to_pixels()` also lock setup).
* Calling `setup_finish` is **optional**, but it is probably good practice. If you do not call it yourself, the first subsequent plotting or utility function will call it for you.

::: api-signature

```python
def setup_axis(
    axis: Axis,
    label: str | None = None,
    flags: AxisFlags = AxisFlags.NONE,
) -> None:
    """
    Enables an axis or sets the label and/or flags for an existing axis. Leave `label=None` for no label.
    """
```

:::

::: api-signature

```python
def setup_axis_limits(
    axis: Axis,
    v_min: float,
    v_max: float,
    cond: Cond = Cond.ONCE,
) -> None:
    """
    Sets an axis range limits. If `Cond.ALWAYS` is used, the axes limits will be locked. Inversion with `v_min > v_max` is not supported; use `implot.setup_axis_limits` instead.
    """
```

:::

::: api-signature

```python
def setup_axis_format(
    axis: Axis,
    fmt: str,
) -> None:
    """
    Sets the format of numeric axis labels via formater specifier (default="%g"). Formated values will be double (i.e. use %f).  Note that the format string is specified in C printf syntax!
    """
```

:::

::: api-signature

```python
def setup_axis_ticks(
    axis: int,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    labels: Sequence[str] | None = None,
    keep_default: bool = False,
) -> None:
    """
    Sets an axis' ticks and optionally the labels. To keep the default ticks, set `keep_default=True`.
    """
```

:::

::: api-signature

```python
def setup_axis_ticks(
    axis: int,
    v_min: float,
    v_max: float,
    n_ticks: int,
    labels: Sequence[str] | None = None,
    keep_default: bool = False,
) -> None:
    """
    Sets an axis' ticks and optionally the labels. To keep the default ticks, set `keep_default=True`.
    """
```

:::

::: api-signature

```python
def setup_axis_scale(
    axis: Axis,
    scale: Scale,
) -> None:
    """
    Sets an axis' scale using built-in options.
    """
```

:::

::: api-signature

```python
def setup_axis_limits_constraints(
    axis: Axis,
    v_min: float,
    v_max: float,
) -> None:
    """
    Sets an axis' limits constraints.
    """
```

:::

::: api-signature

```python
def setup_axis_zoom_constraints(
    axis: Axis,
    z_min: float,
    z_max: float,
) -> None:
    """
    Sets an axis' zoom constraints.
    """
```

:::

::: api-signature

```python
def setup_axes(
    x_label: str | None,
    y_label: str | None,
    x_flags: AxisFlags = AxisFlags.NONE,
    y_flags: AxisFlags = AxisFlags.NONE,
) -> None:
    """
    Sets the label and/or flags for primary X and Y axes (shorthand for two calls to `implot.setup_Axis()`).
    """
```

:::

::: api-signature

```python
def setup_axes_limits(
    x_min: float,
    x_max: float,
    y_min: float,
    y_max: float,
    cond: Cond = Cond.ONCE,
) -> None:
    """
    Sets the primary X and Y axes range limits. If `Cond.ALWAYS` is used, the axes limits will be locked (shorthand for two calls to `implot.setup_axis_limits()`).
    """
```

:::

::: api-signature

```python
def setup_legend(
    location: Location,
    flags: LegendFlags = LegendFlags.NONE,
) -> None:
    """
    Sets up the plot legend. This can also be called immediately after `implot.begin_subplots()` when using `SubplotFlags.SHARE_ITEMS`.
    """
```

:::

::: api-signature

```python
def setup_mouse_text(
    location: Location,
    flags: MouseTextFlags = MouseTextFlags.NONE,
) -> None:
    """
    Set the location of the current plot's mouse position text (default = South|East).
    """
```

:::

::: api-signature

```python
def setup_finish() -> None:
    """
    Explicitly finalize plot setup. Once you call this, you cannot make anymore Setup calls for the current plot!

    Note that calling this function is OPTIONAL; it will be called by the first subsequent setup-locking API call.
    """
```

:::

Explicitly finalize plot setup. Once you call this, you cannot make anymore Setup calls for the current plot!

Note that calling this function is OPTIONAL; it will be called by the first subsequent setup-locking API call.

### SetNext

Though you should default to the `setup()` API above, there are some scenarios where (re)configuring a plot or axis before `begin_plot()` is needed (e.g., if using a preceding button or slider widget to change the plot limits). In this case, you can use the `set_next_*()` API below. While this is not as feature-rich as the `setup()` API, most common needs are provided. These functions can be called anywhere except inside of `begin_plot`/`end_plot`. For example:

```python
if imgui.button("Center Plot"):
    implot.set_next_axes_limits(-1, 1, -1, 1)
if implot.begin_plot(...):
    ...
    implot.end_plot()
```

**Important Notes**:

* You must still enable non-default axes with `setup_axis` for these functions to work properly.

::: api-signature

```python
def set_next_axis_limits(
    axis: Axis,
    v_min: float,
    v_max: float,
    cond: Cond = Cond.ONCE,
) -> None:
    """
    Sets an upcoming axis range limits. If ImPlotCond_Always is used, the axes limits will be locked.
    """
```

:::

::: api-signature

```python
def set_next_axis_to_fit(
    axis: Axis,
) -> None:
    """
    Set an upcoming axis to auto fit to its data.
    """
```

:::

::: api-signature

```python
def set_next_axes_limits(
    x_min: float,
    x_max: float,
    y_min: float,
    y_max: float,
    cond: Cond = Cond.ONCE,
) -> None:
    """
    Sets the upcoming primary X and Y axes range limits. If `Cond.ALWAYS` is used, the axes limits will be locked (shorthand for two calls to `implot.setup_axis_limits()`).
    """
```

:::

::: api-signature

```python
def set_next_axes_to_fit() -> None:
    """
    Sets all upcoming axes to auto fit to their data.
    """
```

:::

### Plot Items

The main plotting API is provied below. Call these functions between
Begin/EndPlot and after any Setup API calls. Each plots data on the current
x and y axes, which can be changed with `set_axis()`/`set_axes()`.

NB: All types are converted to double before plotting. You may lose information
if you try plotting extremely large 64-bit integral types. Proceed with caution!

::: api-signature

```python
def plot_line(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a standard 2D line plot. The x values are taken from the `xs` array, and the y values are taken from the `ys` array.
    """
```

:::

::: api-signature

```python
def plot_line(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    xscale: float = 1.0,
    xstart: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a standard 2D line plot. The x values are taken from the `xs` array, and the y values are taken from the `ys` array.
    """
```

:::

Plots a standard 2D line plot. The x values are spaced evenly along the x axis, starting at `xstart` and spaced by `xscale`. The y values are taken from the `values` array.

::: api-signature

```python
def plot_scatter(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a standard 2D scatter plot. Default marker is `Marker.CIRCLE`.
    """
```

:::

::: api-signature

```python
def plot_scatter(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    xscale: float = 1.0,
    xstart: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a standard 2D scatter plot. Default marker is `Marker.CIRCLE`.
    """
```

:::

::: api-signature

```python
def plot_stairs(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a stairstep graph. The y value is continued constantly to the right from every x position, i.e. the interval `[x[i], x[i+1])` has the value `y[i]`
    """
```

:::

::: api-signature

```python
def plot_stairs(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    xscale: float = 1.0,
    xstart: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a stairstep graph. The y value is continued constantly to the right from every x position, i.e. the interval `[x[i], x[i+1])` has the value `y[i]`
    """
```

:::

::: api-signature

```python
def plot_shaded(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys1: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys2: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a shaded (filled) region between two lines, or a line and a horizontal reference. Set `yref` to +/-INFINITY for infinite fill extents.
    """
```

:::

::: api-signature

```python
def plot_shaded(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    yref: float = 0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a shaded (filled) region between two lines, or a line and a horizontal reference. Set `yref` to +/-INFINITY for infinite fill extents.
    """
```

:::

::: api-signature

```python
def plot_shaded(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    yref: float = 0,
    xscale: float = 1.0,
    xstart: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a shaded (filled) region between two lines, or a line and a horizontal reference. Set `yref` to +/-INFINITY for infinite fill extents.
    """
```

:::

::: api-signature

```python
def plot_bars(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    bar_size: float,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a bar graph. Vertical by default. `bar_size` and `shift` are in plot units.
    """
```

:::

::: api-signature

```python
def plot_bars(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    bar_size: float = 0.67,
    shift: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a bar graph. Vertical by default. `bar_size` and `shift` are in plot units.
    """
```

:::

::: api-signature

```python
def plot_bar_groups(
    label_ids: Sequence[str],
    values: Annotated[NDArray[Any], dict(shape=(None, None), order='C', device='cpu', writable=False)],
    group_size: float = 0.67,
    shift: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a group of bars. `values` is a matrix with a shape `(item_count, group_count)`. `label_ids` should have `item_count` elements.
    """
```

:::

::: api-signature

```python
def plot_error_bars(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    err: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots vertical error bar. The label_id should be the same as the label_id of the associated line or bar plot.
    """
```

:::

::: api-signature

```python
def plot_error_bars(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    neg: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    pos: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots vertical error bar. The label_id should be the same as the label_id of the associated line or bar plot.
    """
```

:::

::: api-signature

```python
def plot_stems(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ref: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots stems. Vertical by default.
    """
```

:::

::: api-signature

```python
def plot_stems(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ref: float = 0.0,
    scale: float = 1.0,
    start: float = 0.0,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots stems. Vertical by default.
    """
```

:::

::: api-signature

```python
def plot_inf_lines(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots infinite vertical or horizontal lines (e.g. for references or asymptotes).
    """
```

:::

::: api-signature

```python
def plot_heatmap(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None, None), order='C', device='cpu', writable=False)],
    scale_min: float = 0,
    scale_max: float = 0.0,
    label_fmt: str | None = '%.1f',
    bounds_min: tuple[float, float] = (0.0, 0.0),
    bounds_max: tuple[float, float] = (1.0, 1.0),
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a 2D heatmap chart. `values` is expected to have shape (rows, cols). Leave `scale_min` and `scale_max` both at 0 for automatic color scaling, or set them to a predefined range. `label_fmt` can be set to `None` for no labels.
    """
```

:::

::: api-signature

```python
def plot_digital(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots digital data. Digital plots do not respond to y drag or zoom, and are always referenced to the bottom of the plot.
    """
```

:::

::: api-signature

```python
def plot_image(
    label_id: str,
    tex_ref: slimgui_ext.imgui.TextureRef | int,
    bounds_min: tuple[float, float],
    bounds_max: tuple[float, float],
    uv0: tuple[float, float] = (0,0),
    uv1: tuple[float, float] = (1,1),
    tint_col: tuple[float, float, float, float] = (1,1,1,1),
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots an axis-aligned image. `bounds_min`/`bounds_max` are in plot coordinates (y-up) and `uv0`/`uv1` are in texture coordinates (y-down).
    """
```

:::

::: api-signature

```python
def plot_text(
    text: str,
    x: float,
    y: float,
    pix_offset: tuple[float, float] = (0,0),
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a centered text label at point x,y with an optional pixel offset. Text color can be changed with `implot.push_style_color(Col.INLAY_TEXT, ...)`.
    """
```

:::

::: api-signature

```python
def plot_dummy(
    label_id: str,
    spec: PlotSpec | None = None,
) -> None:
    """
    Plots a dummy item (i.e. adds a legend entry colored by `Col.LINE`).
    """
```

:::

::: api-signature

```python
def plot_histogram(
    label_id: str,
    values: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    bins: int | Bin = Bin.STURGES,
    bar_scale: float = 1.0,
    range: tuple[float, float] | None = None,
    spec: PlotSpec | None = None,
) -> float:
    """
    Plots a horizontal histogram. `bins` can be a positive integer or a method specified with the `implot.Bin` enum. If `range` is left unspecified, the min/max of `values` will be used as the range.  Otherwise, outlier values outside of the range are not binned. The largest bin count or density is returned.
    """
```

:::

::: api-signature

```python
def plot_histogram2d(
    label_id: str,
    xs: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    ys: Annotated[NDArray[Any], dict(shape=(None,), order='C', device='cpu', writable=False)],
    x_bins: int | Bin = Bin.STURGES,
    y_bins: int | Bin = Bin.STURGES,
    range: tuple[tuple[float, float], tuple[float, float]] | None = None,
    spec: PlotSpec | None = None,
) -> float:
    """
    Plots two dimensional, bivariate histogram as a heatmap. `x_bins` and `y_bins` can be a positive integer or a method specified with the `implot.Bin` enum. If `range` is left unspecified, the min/max of `xs` an `ys` will be used as the ranges. Otherwise, outlier values outside of range are not binned. The largest bin count or density is returned.
    """
```

:::

The `range` parameter in `plot_histogram2d` is typed as a pair of float 2-tuples.  The first element is the range `(min,max)` for `xs`, the second for `ys`.

### Plot Tools

The following can be used to render interactive elements and/or annotations.
Like the item plotting functions above, they apply to the current x and y
axes, which can be changed with `set_axis()`/`set_axes()`. These functions return `True`
when user interaction causes the provided coordinates to change. Additional
user interactions can be retrieved through the optional output parameters.

Functions such as `drag_point`, `drag_line_x/y` and `drag_rect` use `np.array`s to pass in a mutable reference to float and bool values.

Be careful to use the right `dtype` for the input `np.arrays`: use `dtype=np.float64` for floats and `dtype=np.bool_` for bools.
For example, to specify a point for `drag_point`, you could create the array like so: `np.array([x, y], dtype=np.float64)`.
Search for `drag_line_x` in [example/implot\_demo\_window/implot.py](https://github.com/nurpax/slimgui/blob/main/example/implot_demo_window/implot.py) for more examples.

::: api-signature

```python
def drag_point(
    id: int,
    point: Annotated[NDArray[Any], dict(shape=(2), order='C', device='cpu')],
    col: tuple[float, float, float, float],
    size: float = 4.0,
    flags: DragToolFlags = DragToolFlags.NONE,
    out_clicked: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_hovered: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_held: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
) -> bool:
    """
    Shows a draggable point at `point`.  The updated drag position will be written to the `point` array.  Color `col` defaults to `imgui.Col.TEXT`.
    `out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the point is clicked, hovered, or held, respectively.
    Returns `True` if the point was dragged.

    The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See [https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools](https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools) for details.
    """
```

:::

Shows a draggable point at `point`.  The updated drag position will be written to the `point` array.  Color `col` defaults to `imgui.Col.TEXT`.
`out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the point is clicked, hovered, or held, respectively.
Returns `True` if the point was dragged.

The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See <https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools> for details.

::: api-signature

```python
def drag_line_x(
    id: int,
    x: Annotated[NDArray[Any], dict(shape=(), order='C', device='cpu')],
    col: tuple[float, float, float, float],
    thickness: float = 1,
    flags: DragToolFlags = DragToolFlags.NONE,
    out_clicked: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_hovered: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_held: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
) -> bool:
    """
    Shows a draggable vertical guide line at an x-value. The updated drag position will be written to the `x` array.  Color `col` defaults to `imgui.Col.TEXT`.
    `out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the point is clicked, hovered, or held, respectively.
    Returns `True` if the line was dragged.

    The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See [https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools](https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools) for details.
    """
```

:::

Shows a draggable vertical guide line at an x-value. The updated drag position will be written to the `x` array.  Color `col` defaults to `imgui.Col.TEXT`.
`out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the point is clicked, hovered, or held, respectively.
Returns `True` if the line was dragged.

The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See <https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools> for details.

::: api-signature

```python
def drag_line_y(
    id: int,
    y: Annotated[NDArray[Any], dict(shape=(), order='C', device='cpu')],
    col: tuple[float, float, float, float],
    thickness: float = 1,
    flags: DragToolFlags = DragToolFlags.NONE,
    out_clicked: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_hovered: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_held: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
) -> bool:
    """
    Shows a draggable horizontal guide line at a y-value. The updated drag position will be written to the `y` array.  Color `col` defaults to `imgui.Col.TEXT`.
    `out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the line is clicked, hovered, or held, respectively.
    Returns `True` if the line was dragged.

    The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See [https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools](https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools) for details.
    """
```

:::

Shows a draggable horizontal guide line at a y-value. The updated drag position will be written to the `y` array.  Color `col` defaults to `imgui.Col.TEXT`.
`out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the line is clicked, hovered, or held, respectively.
Returns `True` if the line was dragged.

The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See <https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools> for details.

::: api-signature

```python
def drag_rect(
    id: int,
    rect: Annotated[NDArray[Any], dict(shape=(2, 2), order='C', device='cpu')],
    col: tuple[float, float, float, float],
    flags: DragToolFlags = DragToolFlags.NONE,
    out_clicked: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_hovered: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
    out_held: Annotated[NDArray[numpy.bool], dict(shape=(), order='C', device='cpu')] | None = None,
) -> bool:
    """
    Shows a draggable rectangle at `[[x0, y0], [x1, y1]` coordinates, loaded from `rect`.  The updated drag rectangle will be written to the `point` array.  Color `col` defaults to `imgui.Col.TEXT`.
    `out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the point is clicked, hovered, or held, respectively.
    Returns `True` if the rectangle was dragged.

    The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See [https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools](https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools) for details.
    """
```

:::

Shows a draggable rectangle at `[[x0, y0], [x1, y1]` coordinates, loaded from `rect`.  The updated drag rectangle will be written to the `point` array.  Color `col` defaults to `imgui.Col.TEXT`.
`out_clicked`, `out_hovered`, and `out_held` are optional single bool np.arrays that will be set to `True` if the point is clicked, hovered, or held, respectively.
Returns `True` if the rectangle was dragged.

The input `np.array` arguments are motivated by being able to pass in a mutable reference value that the bound API functions can write to.  See <https://nurpax.github.io/slimgui/apiref_implot.html#plot-tools> for details.

::: api-signature

```python
def annotation(
    x: float,
    y: float,
    col: tuple[float, float, float, float],
    pix_offset: tuple[float, float],
    clamp: bool,
    round: bool = False,
) -> None:
    """
    Shows an annotation callout at a chosen point. Clamping keeps annotations in the plot area. Annotations are always rendered on top.
    """
```

:::

::: api-signature

```python
def annotation(
    x: float,
    y: float,
    col: tuple[float, float, float, float],
    pix_offset: tuple[float, float],
    clamp: bool,
    text: str,
) -> None:
    """
    Shows an annotation callout at a chosen point. Clamping keeps annotations in the plot area. Annotations are always rendered on top.
    """
```

:::

::: api-signature

```python
def tag_x(
    x: float,
    col: tuple[float, float, float, float],
    round: bool = False,
) -> None:
    """
    Shows a x-axis tag at the specified coordinate value.
    """
```

:::

::: api-signature

```python
def tag_x(
    x: float,
    col: tuple[float, float, float, float],
    text: str,
) -> None:
    """
    Shows a x-axis tag at the specified coordinate value.
    """
```

:::

::: api-signature

```python
def tag_y(
    y: float,
    col: tuple[float, float, float, float],
    round: bool = False,
) -> None:
    """
    Shows a y-axis tag at the specified coordinate value.
    """
```

:::

::: api-signature

```python
def tag_y(
    y: float,
    col: tuple[float, float, float, float],
    text: str,
) -> None:
    """
    Shows a y-axis tag at the specified coordinate value.
    """
```

:::

### Plot Utils

::: api-signature

```python
def set_axis(
    axis: Axis,
) -> None:
    """
    Select which axis/axes will be used for subsequent plot elements.
    """
```

:::

::: api-signature

```python
def set_axes(
    x_axis: Axis,
    y_axis: Axis,
) -> None:
    """
    Select which axis/axes will be used for subsequent plot elements.
    """
```

:::

::: api-signature

```python
def pixels_to_plot(
    pix: tuple[float, float],
    x_axis: Axis | int = AUTO,
    y_axis: Axis | int = AUTO,
) -> tuple[float, float]:
    """
    Convert pixels to a position in the current plot's coordinate system. Passing `implot.AUTO` uses the current axes.
    """
```

:::

::: api-signature

```python
def pixels_to_plot(
    x: float,
    y: float,
    x_axis: Axis | int = AUTO,
    y_axis: Axis | int = AUTO,
) -> tuple[float, float]:
    """
    Convert pixels to a position in the current plot's coordinate system. Passing `implot.AUTO` uses the current axes.
    """
```

:::

::: api-signature

```python
def plot_to_pixels(
    plt: tuple[float, float],
    x_axis: Axis | int = AUTO,
    y_axis: Axis | int = AUTO,
) -> tuple[float, float]:
    """
    Convert a position in the current plot's coordinate system to pixels. Passing `implot.AUTO` uses the current axes.
    """
```

:::

::: api-signature

```python
def plot_to_pixels(
    x: float,
    y: float,
    x_axis: Axis | int = AUTO,
    y_axis: Axis | int = AUTO,
) -> tuple[float, float]:
    """
    Convert a position in the current plot's coordinate system to pixels. Passing `implot.AUTO` uses the current axes.
    """
```

:::

::: api-signature

```python
def get_plot_pos() -> tuple[float, float]:
    """
    Get the current Plot position (top-left) in pixels.
    """
```

:::

::: api-signature

```python
def get_plot_size() -> tuple[float, float]:
    """
    Get the curent Plot size in pixels.
    """
```

:::

::: api-signature

```python
def get_plot_mouse_pos(
    x_axis: Axis | int = AUTO,
    y_axis: Axis | int = AUTO,
) -> tuple[float, float]:
    """
    Returns the mouse position in x,y coordinates of the current plot. Passing `implot.AUTO` uses the current axes.
    """
```

:::

::: api-signature

```python
def is_plot_hovered() -> bool:
    """
    Returns `True` if the plot area in the current plot is hovered.
    """
```

:::

::: api-signature

```python
def is_axis_hovered(
    axis: Axis,
) -> bool:
    """
    Returns `True` if the axis label area in the current plot is hovered.
    """
```

:::

::: api-signature

```python
def is_subplots_hovered() -> bool:
    """
    Returns `True` if the bounding frame of a subplot is hovered.
    """
```

:::

::: api-signature

```python
def is_plot_selected() -> bool:
    """
    Returns `True` if the current plot is being box selected.
    """
```

:::

::: api-signature

```python
def cancel_plot_selection() -> None:
    """
    Cancels a the current plot box selection.
    """
```

:::

::: api-signature

```python
def hide_next_item(
    hidden: bool = True,
    cond: Cond = Cond.ONCE,
) -> None:
    """
    Hides or shows the next plot item (i.e. as if it were toggled from the legend).

    Use `Cond.ALWAYS` if you need to forcefully set this every frame.
    """
```

:::

Hides or shows the next plot item (i.e. as if it were toggled from the legend).

Use `Cond.ALWAYS` if you need to forcefully set this every frame.

Use the following around calls to `begin_plot()`/`end_plot()` to align l/r/t/b padding.
Consider using `begin_subplots()`/`end_subplots()` first. They are more feature rich and
accomplish the same behaviour by default. The functions below offer lower
level control of plot alignment.

::: api-signature

```python
def begin_aligned_plots(
    group_id: str,
    vertical: bool = True,
) -> bool:
    """
    Align axis padding over multiple plots in a single row or column. `group_id` must
    be unique. If this function returns `True`, `implot.end_aligned_plots()` must be called.
    """
```

:::

::: api-signature

```python
def end_aligned_plots() -> None:
    """
    Only call `implot.end_aligned_plots()` if `implot.begin_aligned_plots()` returns `True`!
    """
```

:::

### Legend Utils

::: api-signature

```python
def begin_legend_popup(
    label_id: str,
    mouse_button: slimgui_ext.imgui.MouseButton = slimgui_ext.imgui.MouseButton.RIGHT,
) -> bool:
    """
    Begin a popup for a legend entry.
    """
```

:::

::: api-signature

```python
def end_legend_popup() -> None:
    """
    End a popup for a legend entry.
    """
```

:::

::: api-signature

```python
def is_legend_entry_hovered(
    label_id: str,
) -> bool:
    """
    Returns `True` if a plot item legend entry is hovered.
    """
```

:::

### Drag and Drop

::: api-signature

```python
def begin_drag_drop_target_plot() -> bool:
    """
    Turns the current plot's plotting area into a drag and drop target. Don't forget to call `implot.end_drag_drop_target()`!
    """
```

:::

::: api-signature

```python
def begin_drag_drop_target_axis(
    axis: Axis,
) -> bool:
    """
    Turns the current plot's X-axis into a drag and drop target. Don't forget to call `implot.end_drag_drop_target()`!
    """
```

:::

::: api-signature

```python
def begin_drag_drop_target_legend() -> bool:
    """
    Turns the current plot's legend into a drag and drop target. Don't forget to call `implot.end_drag_drop_target()`!
    """
```

:::

::: api-signature

```python
def end_drag_drop_target() -> None:
    """
    Ends a drag and drop target (currently just an alias for `imgui.end_drag_drop_target()`).
    """
```

:::

NB: By default, plot and axes drag and drop *sources* require holding the Ctrl modifier to initiate the drag.
You can change the modifier if desired. If `imgui.Key.MOD_NONE` is provided, the axes will be locked from panning.

::: api-signature

```python
def begin_drag_drop_source_plot(
    flags: slimgui_ext.imgui.DragDropFlags = slimgui_ext.imgui.DragDropFlags.NONE,
) -> bool:
    """
    Turns the current plot's plotting area into a drag and drop source. You must hold Ctrl. Don't forget to call `implot.end_drag_drop_source()`!
    """
```

:::

::: api-signature

```python
def begin_drag_drop_source_axis(
    axis: Axis,
    flags: slimgui_ext.imgui.DragDropFlags = slimgui_ext.imgui.DragDropFlags.NONE,
) -> bool:
    """
    Turns the current plot's X-axis into a drag and drop source. You must hold Ctrl. Don't forget to call `implot.end_drag_drop_source()`!
    """
```

:::

::: api-signature

```python
def begin_drag_drop_source_item(
    label_id: str,
    flags: slimgui_ext.imgui.DragDropFlags = slimgui_ext.imgui.DragDropFlags.NONE,
) -> bool:
    """
    Turns an item in the current plot's legend into drag and drop source. Don't forget to call `implot.end_drag_drop_source()`!
    """
```

:::

::: api-signature

```python
def end_drag_drop_source() -> None:
    """
    Ends a drag and drop source (currently just an alias for `imgui.end_drag_drop_source()`).
    """
```

:::

### Styling

Styling colors in ImPlot works similarly to styling colors in ImGui, but
with one important difference. Like ImGui, all style colors are stored in an
indexable array in ImPlotStyle. You can permanently modify these values through
GetStyle().Colors, or temporarily modify them with Push/Pop functions below.
However, by default all style colors in ImPlot default to a special color
IMPLOT\_AUTO\_COL. The behavior of this color depends upon the style color to
which it as applied:

1. For style colors associated with plot items (e.g. `Col.LINE`),
   `implot.AUTO_COL` tells ImPlot to color the item with the next unused
   color in the current colormap. Thus, every item will have a different
   color up to the number of colors in the colormap, at which point the
   colormap will roll over. For most use cases, you should not need to
   set these style colors to anything but `implot.AUTO_COL`; you are
   probably better off changing the current colormap. However, if you
   need to explicitly color a particular item you may either Push/Pop
   the style color around the item in question, or use the `set_next_*_style()`
   API below. If you permanently set one of these style colors to a specific
   color, or forget to call Pop, then all subsequent items will be styled
   with the color you set.

2. For style colors associated with plot styling (e.g. `Col.PLOT_BG`),
   `implot.AUTO_COL` tells ImPlot to set that color from color data in your
   `imgui.Style`. The `imgui.Col` that these style colors default to are
   detailed above, and in general have been mapped to produce plots visually
   consistent with your current ImGui style. Of course, you are free to
   manually set these colors to whatever you like, and further can Push/Pop
   them around individual plots for plot-specific styling (e.g. coloring axes).

::: api-signature

```python
def get_style() -> slimgui.slimgui_ext.implot.Style:
    """
    Provides access to plot style structure for permanant modifications to colors, sizes, etc.
    """
```

:::

::: api-signature

```python
def style_colors_auto(
    dst: Style | None = None,
) -> None:
    """
    Style plot colors for current ImGui style (default).
    """
```

:::

::: api-signature

```python
def style_colors_classic(
    dst: Style | None = None,
) -> None:
    """
    Style plot colors for ImGui "Classic".
    """
```

:::

::: api-signature

```python
def style_colors_dark(
    dst: Style | None = None,
) -> None:
    """
    Style plot colors for ImGui "Dark".
    """
```

:::

::: api-signature

```python
def style_colors_light(
    dst: Style | None = None,
) -> None:
    """
    Style plot colors for ImGui "Light".
    """
```

:::

Use `push_style_*` to temporarily modify your `implot.Style`. The modification
will last until the matching call to `pop_style_*`. You MUST call a pop for
every push, otherwise you will leak memory! This behaves just like ImGui.

::: api-signature

```python
def push_style_color(
    idx: Col,
    col: int,
) -> None:
    """
    Temporarily modify a style color. Don't forget to call `implot.pop_style_color()`!
    """
```

:::

::: api-signature

```python
def push_style_color(
    idx: Col,
    col: tuple[float, float, float, float],
) -> None:
    """
    Temporarily modify a style color. Don't forget to call `implot.pop_style_color()`!
    """
```

:::

::: api-signature

```python
def pop_style_color(
    count: int = 1,
) -> None:
    """
    Undo temporary style color modification(s). Undo multiple pushes at once by increasing count.
    """
```

:::

::: api-signature

```python
def push_style_var(
    idx: StyleVar,
    val: int,
) -> None:
    """
    Temporarily modify a style variable of int type. Don't forget to call `implot.pop_style_var()`!
    """
```

:::

::: api-signature

```python
def push_style_var(
    idx: StyleVar,
    val: float,
) -> None:
    """
    Temporarily modify a style variable of int type. Don't forget to call `implot.pop_style_var()`!
    """
```

:::

::: api-signature

```python
def push_style_var(
    idx: StyleVar,
    val: tuple[float, float],
) -> None:
    """
    Temporarily modify a style variable of int type. Don't forget to call `implot.pop_style_var()`!
    """
```

:::

Temporarily modify a style variable of float 2-tuple. Don't forget to call `implot.pop_style_var()`!

::: api-signature

```python
def pop_style_var(
    count: int = 1,
) -> None:
    """
    Undo temporary style variable modification(s). Undo multiple pushes at once by increasing count.
    """
```

:::

::: api-signature

```python
def get_last_item_color() -> tuple[float, float, float, float]:
    """
    Gets the last item primary color (i.e. its legend icon color)
    """
```

:::

::: api-signature

```python
def get_style_color_name(
    idx: Col,
) -> str:
    """
    Returns the string name for an `implot.Col`.
    """
```

:::

::: api-signature

```python
def get_marker_name(
    idx: Marker,
) -> str:
    """
    Returns the string name for an ImPlotMarker.
    """
```

:::

### Colormaps

Item styling is based on colormaps when the relevant `implot.Col.*` is set to
`implot.AUTO_COL` (default). Several built-in colormaps are available. You can
add and then push/pop your own colormaps as well. To permanently set a colormap,
modify the Colormap index member of your `implot.Style`.

Colormap data will be ignored and a custom color will be used if you have done one of the following:

1. Modified an item style color in your `implot.Style` to anything other than `implot.AUTO_COL`.
2. Pushed an item style color using `push_style_color()`.
3. Passed an explicit `PlotSpec` with a custom color to a plot item.

::: api-signature

```python
def get_colormap_count() -> int:
    """
    Returns the number of available colormaps (i.e. the built-in + user-added count).
    """
```

:::

::: api-signature

```python
def get_colormap_name(
    cmap: Colormap,
) -> str:
    """
    Returns a string name for a colormap given an index. Returns `None` if index is invalid.
    """
```

:::

::: api-signature

```python
def get_colormap_index(
    name: str,
) -> int:
    """
    Returns an index number for a colormap given a valid string name. Returns -1 if name is invalid.
    """
```

:::

::: api-signature

```python
def push_colormap(
    cmap: Colormap,
) -> None:
    """
    Temporarily switch to one of the built-in (i.e. ImPlotColormap_XXX) or user-added colormaps (i.e. a return value of `implot.add_colormap()`). Don't forget to call `implot.pop_colormap()`!
    """
```

:::

::: api-signature

```python
def push_colormap(
    name: str,
) -> None:
    """
    Temporarily switch to one of the built-in (i.e. ImPlotColormap_XXX) or user-added colormaps (i.e. a return value of `implot.add_colormap()`). Don't forget to call `implot.pop_colormap()`!
    """
```

:::

Push a colormap by string name. Use built-in names such as "Default", "Deep", "Jet", etc. or a string you provided to `implot.add_colormap(). Don't forget to call `implot.pop\_colormap()\`!

::: api-signature

```python
def pop_colormap(
    count: int = 1,
) -> None:
    """
    Undo temporary colormap modification(s). Undo multiple pushes at once by increasing count.
    """
```

:::

::: api-signature

```python
def next_colormap_color() -> tuple[float, float, float, float]:
    """
    Returns the next color from the current colormap and advances the colormap for the current plot.

    Can also be used with no return value to skip colors if desired. You need to call this between `implot.begin_plot()`/`implot.end_plot()`!
    """
```

:::

Returns the next color from the current colormap and advances the colormap for the current plot.

Can also be used with no return value to skip colors if desired. You need to call this between `implot.begin_plot()`/`implot.end_plot()`!

Colormap utils. If cmap = `implot.AUTO_COL` (default), the current colormap is assumed.
Pass an explicit colormap index (built-in or user-added) to specify otherwise.

::: api-signature

```python
def get_colormap_size(
    cmap: Colormap | int = AUTO,
) -> int:
    """
    Returns the size of a colormap.
    """
```

:::

::: api-signature

```python
def get_colormap_color(
    idx: int,
    cmap: Colormap | int = AUTO,
) -> tuple[float, float, float, float]:
    """
    Returns a color from a colormap given an index >= 0 (modulo will be performed).
    """
```

:::

::: api-signature

```python
def sample_colormap(
    t: float,
    cmap: Colormap | int = AUTO,
) -> tuple[float, float, float, float]:
    """
    Sample a color from the current colormap given t between 0 and 1.
    """
```

:::

::: api-signature

```python
def colormap_scale(
    label: str,
    scale_min: float,
    scale_max: float,
    size: tuple[float, float] = (0,0),
    format: str = '%g',
    flags: ColormapScaleFlags = ColormapScaleFlags.NONE,
    cmap: Colormap | int = AUTO,
) -> None:
    """
    Shows a vertical color scale with linear spaced ticks using the specified color map. Use double hashes to hide label (e.g. "##NoLabel"). If `scale_min > scale_max`, the scale to color mapping will be reversed.
    """
```

:::

::: api-signature

```python
def colormap_button(
    label: str,
    size: tuple[float, float] = (0,0),
    cmap: Colormap | int = AUTO,
) -> bool:
    """
    Shows a button with a colormap gradient brackground.
    """
```

:::

::: api-signature

```python
def bust_color_cache(
    plot_title_id: str | None = None,
) -> None:
    """
    When items in a plot sample their color from a colormap, the color is cached and does not change
    unless explicitly overriden. Therefore, if you change the colormap after the item has already been plotted,
    item colors will NOT update. If you need item colors to resample the new colormap, then use this
    function to bust the cached colors. If #plot_title_id is nullptr, then every item in EVERY existing plot
    will be cache busted. Otherwise only the plot specified by #plot_title_id will be busted. For the
    latter, this function must be called in the same ImGui ID scope that the plot is in. You should rarely if ever
    need this function, but it is available for applications that require runtime colormap swaps (e.g. Heatmaps demo).
    """
```

:::

### Input Mapping

::: api-signature

```python
def get_input_map() -> slimgui.slimgui_ext.implot.InputMap:
    """
    Provides access to input mapping structure for permanant modifications to controls for pan, select, etc.
    """
```

:::

::: api-signature

```python
def map_input_default(
    dst: InputMap | None = None,
) -> None:
    """
    Default input mapping: pan = LMB drag, box select = RMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.
    """
```

:::

::: api-signature

```python
def map_input_reverse(
    dst: InputMap | None = None,
) -> None:
    """
    Reverse input mapping: pan = RMB drag, box select = LMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.
    """
```

:::

### Miscellaneous

::: api-signature

```python
def item_icon(
    col: tuple[float, float, float, float],
) -> None:
    """
    Render icons similar to those that appear in legends (nifty for data lists).
    """
```

:::

::: api-signature

```python
def item_icon(
    col: int,
) -> None:
    """
    Render icons similar to those that appear in legends (nifty for data lists).
    """
```

:::

::: api-signature

```python
def colormap_icon(
    cmap: Colormap,
) -> None:
    """
    Render icons similar to those that appear in legends (nifty for data lists).
    """
```

:::

::: api-signature

```python
def get_plot_draw_list() -> slimgui.slimgui_ext.imgui.DrawList:
    """
    Get the plot draw list for custom rendering to the current plot area. Call between Begin/EndPlot.
    """
```

:::

::: api-signature

```python
def push_plot_clip_rect(
    expand: float = 0,
) -> None:
    """
    Push clip rect for rendering to current plot area. The rect can be expanded or contracted by #expand pixels. Call between `implot.begin_plot()`/`implot.end_plot()`.
    """
```

:::

::: api-signature

```python
def pop_plot_clip_rect() -> None:
    """
    Pop plot clip rect. Call between `implot.begin_plot()`/`implot.end_plot()`.
    """
```

:::

::: api-signature

```python
def show_style_selector(
    label: str,
) -> bool:
    """
    Shows ImPlot style selector dropdown menu.
    """
```

:::

::: api-signature

```python
def show_colormap_selector(
    label: str,
) -> bool:
    """
    Shows ImPlot colormap selector dropdown menu.
    """
```

:::

::: api-signature

```python
def show_input_map_selector(
    label: str,
) -> bool:
    """
    Shows ImPlot input map selector dropdown menu.
    """
```

:::

::: api-signature

```python
def show_style_editor(
    ref: Style | None = None,
) -> None:
    """
    Shows ImPlot style editor block (not a window).
    """
```

:::

::: api-signature

```python
def show_user_guide() -> None:
    """
    Add basic help/info block for end users (not a window).
    """
```

:::

::: api-signature

```python
def show_metrics_window(
    closable: bool = False,
) -> bool:
    """
    Shows ImPlot metrics/debug information window.
    """
```

:::

### Demo

::: api-signature

```python
def show_demo_window(
    closable: bool = False,
) -> bool:
    """
    Shows the ImPlot demo window.
    """
```

:::

## Class Reference

### Class: PlotSpec

`PlotSpec` configures a single plotted item. Pass it with the `spec=` argument to
functions such as `plot_line()`, `plot_scatter()`, and `plot_histogram2d()`.

This replaces the old `set_next_*_style()` helpers from earlier ImPlot versions.
Instead of mutating an implicit “next item” style, create a `PlotSpec` and pass it
explicitly to the plot call you want to affect.

Typical usage looks like this:

```python
spec = PlotSpec(
    line_color=(1, 0, 0, 1),
    line_weight=2.0,
    marker=implot.Marker.CIRCLE,
    flags=implot.ItemFlags.NO_LEGEND | implot.LineFlags.SEGMENTS,
)

implot.plot_line("My Line", xs, ys, spec=spec)
```

`PlotSpec()` by itself uses the same defaults as ImPlot, so you only need to set the
fields you want to override.

::: api-properties PlotSpec
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `line_color` | `tuple[float, float, float, float]` | `AUTO_COL` | Line color. `AUTO_COL` uses the next colormap color or the current item color. |
| `line_weight` | `float` | `1.0` | Line weight in pixels. Applies to lines, bar edges, and marker edges. |
| `fill_color` | `tuple[float, float, float, float]` | `AUTO_COL` | Fill color. `AUTO_COL` uses the next colormap color or the current item color. |
| `fill_alpha` | `float` | `1.0` | Alpha multiplier for `fill_color` and `marker_fill_color`. |
| `marker` | `int` | `Marker.NONE` | Marker type. Use `Marker.AUTO` to use the next unused marker. |
| `marker_size` | `float` | `4.0` | Marker size, as a radius in pixels. |
| `marker_line_color` | `tuple[float, float, float, float]` | `AUTO_COL` | Marker edge color. `AUTO_COL` uses `line_color`. |
| `marker_fill_color` | `tuple[float, float, float, float]` | `AUTO_COL` | Marker face color. `AUTO_COL` uses `line_color`. |
| `size` | `float` | `4.0` | Size in pixels for error bar whiskers or digital bar height. |
| `offset` | `int` | `0` | Data index offset. |
| `stride` | `int` | `AUTO` | Data stride in bytes. `AUTO` uses `sizeof(T)` for the plotted data type. |
| `flags` | `int` | `ItemFlags.NONE` | Optional item flags. Combine common `ItemFlags` with specialized plot flags. |
| `line_colors` | `NDArray[Any] \| None` | `None` | 1-dimensional NumPy array of packed ImU32 colors, dtype `numpy.uint32`, one value per line segment. If `None`, use `line_color` for all lines. |
| `fill_colors` | `NDArray[Any] \| None` | `None` | 1-dimensional NumPy array of packed ImU32 colors, dtype `numpy.uint32`, one value per filled segment. If `None`, use `fill_color` for all fills. |
| `marker_sizes` | `NDArray[Any] \| None` | `None` | 1-dimensional NumPy array of marker sizes, dtype `numpy.float32`, one value per marker. If `None`, use `marker_size` for all markers. |
| `marker_line_colors` | `NDArray[Any] \| None` | `None` | 1-dimensional NumPy array of packed ImU32 colors, dtype `numpy.uint32`, one value per marker edge. If `None`, use `marker_line_color` for all markers. |
| `marker_fill_colors` | `NDArray[Any] \| None` | `None` | 1-dimensional NumPy array of packed ImU32 colors, dtype `numpy.uint32`, one value per marker face. If `None`, use `marker_fill_color` for all markers. |
:::

### Class: Style

`Style` stores the global ImPlot styling state returned by `get_style()`. Modify its
fields when you want to change default plot appearance globally instead of on a
single plot item.

Use `PlotSpec` for per-item styling such as line color, markers, or specialized
item flags.

::: api-properties Style
| Property | Type | Description |
| --- | --- | --- |
| `plot_border_size` | `float` |  |
| `minor_alpha` | `float` |  |
| `major_tick_len` | `tuple[float, float]` |  |
| `minor_tick_len` | `tuple[float, float]` |  |
| `major_tick_size` | `tuple[float, float]` |  |
| `minor_tick_size` | `tuple[float, float]` |  |
| `major_grid_size` | `tuple[float, float]` |  |
| `minor_grid_size` | `tuple[float, float]` |  |
| `plot_padding` | `tuple[float, float]` |  |
| `label_padding` | `tuple[float, float]` |  |
| `legend_padding` | `tuple[float, float]` |  |
| `legend_inner_padding` | `tuple[float, float]` |  |
| `legend_spacing` | `tuple[float, float]` |  |
| `mouse_pos_padding` | `tuple[float, float]` |  |
| `annotation_padding` | `tuple[float, float]` |  |
| `fit_padding` | `tuple[float, float]` |  |
| `digital_padding` | `float` |  |
| `digital_spacing` | `float` |  |
| `plot_default_size` | `tuple[float, float]` |  |
| `plot_min_size` | `tuple[float, float]` |  |
| `colors` | `ColorsArray` |  |
| `colormap` | `int` |  |
| `use_local_time` | `bool` |  |
| `use_iso8601` | `bool` |  |
| `use_24hour_clock` | `bool` |  |
:::

## Enum Reference

### Enum: Axis

| Name | Description |
| --- | --- |
| X1 | Enabled by default |
| X2 | Disabled by default |
| X3 | Disabled by default |
| Y1 | Enabled by default |
| Y2 | Disabled by default |
| Y3 | Disabled by default |
| COUNT |  |

### Enum: Bin

| Name | Description |
| --- | --- |
| SQRT | K = sqrt(n) |
| STURGES | K = 1 + log2(n) |
| RICE | K = 2 \* cbrt(n) |
| SCOTT | W = 3.49 \* sigma / cbrt(n) |

### Enum: Col

| Name | Description |
| --- | --- |
| FRAME\_BG | Plot frame background color (defaults to `Col.FRAME_BG`) |
| PLOT\_BG | Plot area background color (defaults to `Col.WINDOW_BG`) |
| PLOT\_BORDER | Plot area border color (defaults to `Col.BORDER`) |
| LEGEND\_BG | Legend background color (defaults to `Col.POPUP_BG`) |
| LEGEND\_BORDER | Legend border color (defaults to `Col.PLOT_BORDER`) |
| LEGEND\_TEXT | Legend text color (defaults to `Col.INLAY_TEXT`) |
| TITLE\_TEXT | Plot title text color (defaults to `Col.TEXT`) |
| INLAY\_TEXT | Color of text appearing inside of plots (defaults to `Col.TEXT`) |
| AXIS\_TEXT | Axis label and tick labels color (defaults to `Col.TEXT`) |
| AXIS\_GRID | Axis grid color (defaults to 25% `Col.AXIS_TEXT`) |
| AXIS\_TICK | Axis tick color (defaults to AxisGrid) |
| AXIS\_BG | Background color of axis hover region (defaults to transparent) |
| AXIS\_BG\_HOVERED | Axis hover color (defaults to `Col.BUTTON_HOVERED`) |
| AXIS\_BG\_ACTIVE | Axis active color (defaults to `Col.BUTTON_ACTIVE`) |
| SELECTION | Box-selection color (defaults to yellow) |
| CROSSHAIRS | Crosshairs color (defaults to `Col.PLOT_BORDER`) |
| COUNT |  |

### Enum: Colormap

| Name | Description |
| --- | --- |
| DEEP | A.k.a. seaborn deep             (qual=true,  n=10) (default) |
| DARK | A.k.a. matplotlib "Set1"        (qual=true,  n=9 ) |
| PASTEL | A.k.a. matplotlib "Pastel1"     (qual=true,  n=9 ) |
| PAIRED | A.k.a. matplotlib "Paired"      (qual=true,  n=12) |
| VIRIDIS | A.k.a. matplotlib "viridis"     (qual=false, n=11) |
| PLASMA | A.k.a. matplotlib "plasma"      (qual=false, n=11) |
| HOT | A.k.a. matplotlib/MATLAB "hot"  (qual=false, n=11) |
| COOL | A.k.a. matplotlib/MATLAB "cool" (qual=false, n=11) |
| PINK | A.k.a. matplotlib/MATLAB "pink" (qual=false, n=11) |
| JET | A.k.a. MATLAB "jet"             (qual=false, n=11) |
| TWILIGHT | A.k.a. matplotlib "twilight"    (qual=false, n=11) |
| RD\_BU | Red/blue, Color Brewer          (qual=false, n=11) |
| BR\_BG | Brown/blue-green, Color Brewer  (qual=false, n=11) |
| PI\_YG | Pink/yellow-green, Color Brewer (qual=false, n=11) |
| SPECTRAL | Color spectrum, Color Brewer    (qual=false, n=11) |
| GREYS | White/black                     (qual=false, n=2 ) |

### Enum: Cond

| Name | Description |
| --- | --- |
| NONE | No condition (always set the variable), same as \_Always |
| ALWAYS | No condition (always set the variable) |
| ONCE | Set the variable once per runtime session (only the first call will succeed) |

### Enum: Location

| Name | Description |
| --- | --- |
| CENTER | Center-center |
| NORTH | Top-center |
| SOUTH | Bottom-center |
| WEST | Center-left |
| EAST | Center-right |
| NORTH\_WEST | Top-left |
| NORTH\_EAST | Top-right |
| SOUTH\_WEST | Bottom-left |
| SOUTH\_EAST | Bottom-right |

### Enum: Marker

| Name | Description |
| --- | --- |
| NONE | No marker |
| AUTO | Automatic marker selection |
| CIRCLE | A circle marker (default) |
| SQUARE | A square maker |
| DIAMOND | A diamond marker |
| UP | An upward-pointing triangle marker |
| DOWN | An downward-pointing triangle marker |
| LEFT | An leftward-pointing triangle marker |
| RIGHT | An rightward-pointing triangle marker |
| CROSS | A cross marker (not fill-able) |
| PLUS | A plus marker (not fill-able) |
| ASTERISK | A asterisk marker (not fill-able) |
| COUNT |  |

### Enum: Scale

| Name | Description |
| --- | --- |
| LINEAR | Default linear scale |
| TIME | Date/time scale |
| LOG10 | Base 10 logarithmic scale |
| SYM\_LOG | Symmetric log scale |

### Enum: StyleVar

| Name | Description |
| --- | --- |
| PLOT\_DEFAULT\_SIZE | ImVec2, default size used when ImVec2(0,0) is passed to BeginPlot |
| PLOT\_MIN\_SIZE | ImVec2, minimum size plot frame can be when shrunk |
| PLOT\_BORDER\_SIZE | Float,  thickness of border around plot area |
| MINOR\_ALPHA | Float,  alpha multiplier applied to minor axis grid lines |
| MAJOR\_TICK\_LEN | ImVec2, major tick lengths for X and Y axes |
| MINOR\_TICK\_LEN | ImVec2, minor tick lengths for X and Y axes |
| MAJOR\_TICK\_SIZE | ImVec2, line thickness of major ticks |
| MINOR\_TICK\_SIZE | ImVec2, line thickness of minor ticks |
| MAJOR\_GRID\_SIZE | ImVec2, line thickness of major grid lines |
| MINOR\_GRID\_SIZE | ImVec2, line thickness of minor grid lines |
| PLOT\_PADDING | ImVec2, padding between widget frame and plot area, labels, or outside legends (i.e. main padding) |
| LABEL\_PADDING | ImVec2, padding between axes labels, tick labels, and plot edge |
| LEGEND\_PADDING | ImVec2, legend padding from plot edges |
| LEGEND\_INNER\_PADDING | ImVec2, legend inner padding from legend edges |
| LEGEND\_SPACING | ImVec2, spacing between legend entries |
| MOUSE\_POS\_PADDING | ImVec2, padding between plot edge and interior info text |
| ANNOTATION\_PADDING | ImVec2, text padding around annotation labels |
| FIT\_PADDING | ImVec2, additional fit padding as a percentage of the fit extents (e.g. ImVec2(0.1,0.1) adds 10% to the fit extents of X and Y) |
| DIGITAL\_PADDING | Float,  digital plot padding from bottom in pixels |
| DIGITAL\_SPACING | Float,  digital plot spacing gap in pixels |
| COUNT |  |

### Enum: AxisFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_LABEL | The axis label will not be displayed (axis labels are also hidden if the supplied string name is nullptr) |
| NO\_GRID\_LINES | No grid lines will be displayed |
| NO\_TICK\_MARKS | No tick marks will be displayed |
| NO\_TICK\_LABELS | No text labels will be displayed |
| NO\_INITIAL\_FIT | Axis will not be initially fit to data extents on the first rendered frame |
| NO\_MENUS | The user will not be able to open context menus with right-click |
| NO\_SIDE\_SWITCH | The user will not be able to switch the axis side by dragging it |
| NO\_HIGHLIGHT | The axis will not have its background highlighted when hovered or held |
| OPPOSITE | Axis ticks and labels will be rendered on the conventionally opposite side (i.e, right or top) |
| FOREGROUND | Grid lines will be displayed in the foreground (i.e. on top of data) instead of the background |
| INVERT | The axis will be inverted |
| AUTO\_FIT | Axis will be auto-fitting to data extents |
| RANGE\_FIT | Axis will only fit points if the point is in the visible range of the **orthogonal** axis |
| PAN\_STRETCH | Panning in a locked or constrained state will cause the axis to stretch if possible |
| LOCK\_MIN | The axis minimum value will be locked when panning/zooming |
| LOCK\_MAX | The axis maximum value will be locked when panning/zooming |
| LOCK |  |
| NO\_DECORATIONS |  |
| AUX\_DEFAULT |  |

### Enum: BarGroupsFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| HORIZONTAL | Bar groups will be rendered horizontally on the current y-axis |
| STACKED | Items in a group will be stacked on top of each other |

### Enum: BarsFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| HORIZONTAL | Bars will be rendered horizontally on the current y-axis |

### Enum: ColormapScaleFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_LABEL | The colormap axis label will not be displayed |
| OPPOSITE | Render the colormap label and tick labels on the opposite side |
| INVERT | Invert the colormap bar and axis scale (this only affects rendering; if you only want to reverse the scale mapping, make scale\_min > scale\_max) |

### Enum: DigitalFlags

| Name | Description |
| --- | --- |
| NONE | Default |

### Enum: DragToolFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_CURSORS | Drag tools won't change cursor icons when hovered or held |
| NO\_FIT | The drag tool won't be considered for plot fits |
| NO\_INPUTS | Lock the tool from user inputs |
| DELAYED | Tool rendering will be delayed one frame; useful when applying position-constraints |

### Enum: DummyFlag

| Name | Description |
| --- | --- |
| NONE | Default |

### Enum: ErrorBarsFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| HORIZONTAL | Error bars will be rendered horizontally on the current y-axis |

### Enum: HeatmapFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| COL\_MAJOR | Data will be read in column major order |

### Enum: HistogramFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| HORIZONTAL | Histogram bars will be rendered horizontally (not supported by PlotHistogram2D) |
| CUMULATIVE | Each bin will contain its count plus the counts of all previous bins (not supported by PlotHistogram2D) |
| DENSITY | Counts will be normalized, i.e. the PDF will be visualized, or the CDF will be visualized if Cumulative is also set |
| NO\_OUTLIERS | Exclude values outside the specified histogram range from the count toward normalizing and cumulative counts |
| COL\_MAJOR | Data will be read in column major order (not supported by `plot_histogram`) |

### Enum: ImageFlag

| Name | Description |
| --- | --- |
| NONE | Default |

### Enum: InfLinesFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| HORIZONTAL | Lines will be rendered horizontally on the current y-axis |

### Enum: ItemFlags

| Name | Description |
| --- | --- |
| NONE |  |
| NO\_LEGEND | The item won't have a legend entry displayed |
| NO\_FIT | The item won't be considered for plot fits |

### Enum: LegendFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_BUTTONS | Legend icons will not function as hide/show buttons |
| NO\_HIGHLIGHT\_ITEM | Plot items will not be highlighted when their legend entry is hovered |
| NO\_HIGHLIGHT\_AXIS | Axes will not be highlighted when legend entries are hovered (only relevant if x/y-axis count > 1) |
| NO\_MENUS | The user will not be able to open context menus with right-click |
| OUTSIDE | Legend will be rendered outside of the plot area |
| HORIZONTAL | Legend entries will be displayed horizontally |
| SORT | Legend entries will be displayed in alphabetical order |
| REVERSE | Legend entries will be displayed in reverse order |

### Enum: LineFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| SEGMENTS | A line segment will be rendered from every two consecutive points |
| LOOP | The last and first point will be connected to form a closed loop |
| SKIP\_NA\_N | NaNs values will be skipped instead of rendered as missing data |
| NO\_CLIP | Markers (if displayed) on the edge of a plot will not be clipped |
| SHADED | A filled region between the line and horizontal origin will be rendered; use PlotShaded for more advanced cases |

### Enum: MouseTextFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_AUX\_AXES | Only show the mouse position for primary axes |
| NO\_FORMAT | Axes label formatters won't be used to render text |
| SHOW\_ALWAYS | Always display mouse position even if plot not hovered |

### Enum: PieChartFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NORMALIZE | Force normalization of pie chart values (i.e. always make a full circle if sum < 0) |
| IGNORE\_HIDDEN | Ignore hidden slices when drawing the pie chart (as if they were not there) |
| EXPLODING | Explode legend-hovered slice |
| NO\_SLICE\_BORDER | Do not draw slice borders |

### Enum: PlotFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_TITLE | The plot title will not be displayed (titles are also hidden if preceded by double hashes, e.g. "##MyPlot") |
| NO\_LEGEND | The legend will not be displayed |
| NO\_MOUSE\_TEXT | The mouse position, in plot coordinates, will not be displayed inside of the plot |
| NO\_INPUTS | The user will not be able to interact with the plot |
| NO\_MENUS | The user will not be able to open context menus |
| NO\_BOX\_SELECT | The user will not be able to box-select |
| NO\_FRAME | The ImGui frame will not be rendered |
| EQUAL | X and y axes pairs will be constrained to have the same units/pixel |
| CROSSHAIRS | The default mouse cursor will be replaced with a crosshair when hovered |
| CANVAS\_ONLY |  |

### Enum: ScatterFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_CLIP | Markers on the edge of a plot will not be clipped |

### Enum: ShadedFlags

| Name | Description |
| --- | --- |
| NONE | Default |

### Enum: StairsFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| PRE\_STEP | The y value is continued constantly to the left from every x position, i.e. the interval (x\[i-1], x\[i]] has the value y\[i] |
| SHADED | A filled region between the stairs and horizontal origin will be rendered; use PlotShaded for more advanced cases |

### Enum: StemsFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| HORIZONTAL | Stems will be rendered horizontally on the current y-axis |

### Enum: SubplotFlags

| Name | Description |
| --- | --- |
| NONE | Default |
| NO\_TITLE | The subplot title will not be displayed (titles are also hidden if preceded by double hashes, e.g. "##MySubplot") |
| NO\_LEGEND | The legend will not be displayed (only applicable if `SubplotFlags.SHARE_ITEMS` is enabled) |
| NO\_MENUS | The user will not be able to open context menus with right-click |
| NO\_RESIZE | Resize splitters between subplot cells will be not be provided |
| NO\_ALIGN | Subplot edges will not be aligned vertically or horizontally |
| SHARE\_ITEMS | Items across all subplots will be shared and rendered into a single legend entry |
| LINK\_ROWS | Link the y-axis limits of all plots in each row (does not apply to auxiliary axes) |
| LINK\_COLS | Link the x-axis limits of all plots in each column (does not apply to auxiliary axes) |
| LINK\_ALL\_X | Link the x-axis limits in every plot in the subplot (does not apply to auxiliary axes) |
| LINK\_ALL\_Y | Link the y-axis limits in every plot in the subplot (does not apply to auxiliary axes) |
| COL\_MAJOR | Subplots are added in column major order instead of the default row major order |

### Enum: TextFlag

| Name | Description |
| --- | --- |
| NONE | Default |
| VERTICAL | Text will be rendered vertically |
---

---
url: /slimgui/recipes.md
---
# Recipes

These recipes are focused, runnable examples of common Dear ImGui patterns as expressed through
Slimgui.

They are organized by task and UI pattern rather than by API symbol, so they work as a practical
companion to the API reference.

The same examples can also be explored interactively:

```bash
python3 example/run_examples.py
```
---

---
url: /slimgui/recipes/widgets.md
---

# Widgets

## Simple button

![Simple button](./images/button_simple.png)

Add a simple button.  The `imgui.button` returns `True` if the button was clicked.

```python
def button_simple():
    if imgui.button("Test Button"):
        logging.info("button clicked")
```

## Colored buttons

![Colored buttons](./images/button_colors.png)

Add a button.  The button base, hover and active states are colored separately.

```python
def button_colors():
    for i in range(7):
        base_color = imgui.color_convert_hsv_to_rgb((i/7.0, 0.6, 0.6, 1))
        hover_color = imgui.color_convert_hsv_to_rgb((i/7.0, 0.7, 0.7, 1))
        active_color = imgui.color_convert_hsv_to_rgb((i/7.0, 0.8, 0.8, 1))

        if i > 0:
            imgui.same_line()

        imgui.push_id(i)
        imgui.push_style_color(imgui.Col.BUTTON, base_color)
        imgui.push_style_color(imgui.Col.BUTTON_HOVERED, hover_color)
        imgui.push_style_color(imgui.Col.BUTTON_ACTIVE, active_color)
        if imgui.button("Click"):
            logging.info("Colored button clicked")
        imgui.pop_style_color(3)
        imgui.pop_id()
```
---

---
url: /slimgui/recipes/styles.md
---

# Styles

## Edit the global style object

![Edit the global style object](./images/styles_edit_style_object.png)

Edit `imgui.get_style()` directly when you want to make a small global tweak without replacing
the entire Dear ImGui preset.

This example changes only `frame_rounding` and `frame_padding`, renders a few controls with the
adjusted look, and then restores the original values. The important idea is that the style object
is global for the current context, so direct edits should be restored if you only want them to
affect one section of the UI.

```python
def styles_edit_style_object(state: EditStyleState):
    style = imgui.get_style()
    saved_frame_rounding = style.frame_rounding
    saved_frame_padding = style.frame_padding

    style.frame_rounding = 8.0
    style.frame_padding = (10.0, 6.0)

    imgui.separator_text("Rounded controls")
    _clicked, state.enable_rollout = imgui.checkbox("Enable rollout", state.enable_rollout)
    _clicked, state.lock_config = imgui.checkbox("Lock config", state.lock_config)
    imgui.button("Preview")
    imgui.same_line()
    imgui.button("Deploy")

    style.frame_rounding = saved_frame_rounding
    style.frame_padding = saved_frame_padding
```

## Scoped style push/pop

![Scoped style push/pop](./images/styles_scoped_push_pop.png)

Use `push_style_color()` and `push_style_var()` when you want styling changes to affect only a
small region of the interface.

The first block below changes button colors, frame rounding, and spacing for a compact toolbar.
The second block is rendered immediately afterwards without those pushes, which makes it clear that
the style changes were local and automatically reverted by the matching `pop_style_*()` calls.

```python
def styles_scoped_push_pop():
    imgui.text("Scoped toolbar styling")
    imgui.push_style_var(imgui.StyleVar.FRAME_ROUNDING, 999.0)
    imgui.push_style_var(imgui.StyleVar.ITEM_SPACING, (6.0, 6.0))
    imgui.push_style_color(imgui.Col.BUTTON, (0.20, 0.24, 0.31, 1.0))
    imgui.push_style_color(imgui.Col.BUTTON_HOVERED, (0.31, 0.45, 0.64, 1.0))
    imgui.push_style_color(imgui.Col.BUTTON_ACTIVE, (0.24, 0.36, 0.53, 1.0))

    imgui.push_id("row1")
    imgui.button("Build")
    imgui.same_line()
    imgui.button("Test")
    imgui.same_line()
    imgui.button("Ship")
    imgui.pop_id()

    imgui.pop_style_color(3)
    imgui.pop_style_var(2)

    imgui.separator_text("Default styling restored")
    imgui.push_id("row2")
    imgui.button("Build")
    imgui.same_line()
    imgui.button("Test")
    imgui.same_line()
    imgui.button("Ship")
    imgui.pop_id()
```

## Preset style with overrides

![Preset style with overrides](./images/styles_preset_with_overrides.png)

Start from one of Dear ImGui's built-in style presets and then override a few colors to establish
your own accent.

This pattern is often the fastest way to get to a coherent look: pick `dark`, `light`, or
`classic` as a base, then tweak a handful of colors that matter most for your product. The example
snapshots the current color table, applies the selected preset, adds a stronger accent to headers
and buttons, renders a preview panel, and restores the original colors before returning.

```python
def styles_preset_with_overrides(state: PresetStyleState):
    _clicked, state.preset = imgui.radio_button("Dark", state.preset, 0)
    imgui.same_line()
    _clicked, state.preset = imgui.radio_button("Light", state.preset, 1)
    imgui.same_line()
    _clicked, state.preset = imgui.radio_button("Classic", state.preset, 2)

    saved_colors = _snapshot_colors()
    if state.preset == 0:
        imgui.style_colors_dark()
        accent = (0.28, 0.53, 0.87, 1.0)
    elif state.preset == 1:
        imgui.style_colors_light()
        accent = (0.17, 0.46, 0.80, 1.0)
    else:
        imgui.style_colors_classic()
        accent = (0.34, 0.47, 0.76, 1.0)

    style = imgui.get_style()
    style.colors[imgui.Col.BUTTON] = accent
    style.colors[imgui.Col.BUTTON_HOVERED] = (
        min(accent[0] + 0.08, 1.0),
        min(accent[1] + 0.08, 1.0),
        min(accent[2] + 0.08, 1.0),
        1.0,
    )
    style.colors[imgui.Col.HEADER] = (
        accent[0] * 0.85,
        accent[1] * 0.85,
        accent[2] * 0.85,
        1.0,
    )

    imgui.begin_child("preset preview", (0, 0), imgui.ChildFlags.BORDERS)
    imgui.separator_text("Preview")
    imgui.checkbox("Enable feature", True)
    imgui.checkbox("Send reports", False)
    if imgui.begin_tab_bar("##preset-tabs"):
        if imgui.begin_tab_item("General")[0]:
            imgui.text_wrapped("Use a built-in preset as a starting point, then adjust the few colors that matter.")
            imgui.end_tab_item()
        if imgui.begin_tab_item("Advanced")[0]:
            imgui.text("Accent colors usually need the least work to make a preset feel custom.")
            imgui.end_tab_item()
        imgui.end_tab_bar()
    imgui.button("Confirm")
    imgui.same_line()
    imgui.button("Cancel")
    imgui.end_child()

    _restore_colors(saved_colors)
```

## Color palette popup

![Color palette popup](./images/styles_color_palette_popup.png)

Build a custom color-selection popup around `color_button()` and `color_picker4()`.

This example uses a compact swatch as the trigger, opens a popup with saved palette colors, and
embeds a full color picker in the same popup. The `backup_color` field makes the flow reversible,
which is useful for "try a few accent colors and cancel if needed" interactions.

```python
def styles_color_palette_popup(state: PaletteState):
    imgui.text("Accent color")
    opened = imgui.color_button(
        "##accent",
        state.color,
        imgui.ColorEditFlags.NO_TOOLTIP,
        (40, 24),
    )
    imgui.same_line()
    opened = imgui.button("Palette") or opened

    if opened:
        state.backup_color = state.color
        imgui.open_popup("accent-palette")

    if imgui.begin_popup("accent-palette"):
        imgui.text("Saved palette")
        for i, color in enumerate(state.palette):
            if i > 0:
                imgui.same_line()
            imgui.push_id(i)
            if imgui.color_button("##palette", color, imgui.ColorEditFlags.NO_TOOLTIP, (24, 24)):
                state.color = color
            imgui.pop_id()

        imgui.separator_text("Picker")
        changed, new_color = imgui.color_picker4(
            "##picker",
            state.color,
            imgui.ColorEditFlags.NO_SIDE_PREVIEW | imgui.ColorEditFlags.NO_SMALL_PREVIEW,
        )
        if changed:
            state.color = new_color

        if imgui.button("Revert"):
            state.color = state.backup_color
        imgui.same_line()
        if imgui.button("Close"):
            imgui.close_current_popup()

        imgui.end_popup()
```
---

---
url: /slimgui/recipes/layout.md
---

# Layout

## Master-detail layout with tabs

![Master-detail layout with tabs](./images/layout_master_detail_tabs.png)

Build a resizable master-detail layout with a child list on the left and tabs on the right.

This follows the same general pattern as the Dear ImGui demo's simple layout example: a left child
window is used for navigation, `same_line()` places a grouped detail pane beside it, and the right
side reserves its bottom row for actions by giving the inner child a height of
`-get_frame_height_with_spacing()`. The result is a compact application-style layout rather than a
one-off arrangement of widgets.

```python
def layout_master_detail_tabs(state: LayoutState):
    imgui.begin_child("left pane", (150, 0), imgui.ChildFlags.BORDERS | imgui.ChildFlags.RESIZE_X)
    for i in range(12):
        if imgui.selectable(f"MyObject {i}", state.selected == i, imgui.SelectableFlags.SELECT_ON_NAV)[0]:
            state.selected = i
    imgui.end_child()

    imgui.same_line()

    imgui.begin_group()
    imgui.begin_child("item view", (0, -imgui.get_frame_height_with_spacing()))
    imgui.text(f"MyObject: {state.selected}")
    imgui.separator()
    if imgui.begin_tab_bar("##details-tabs"):
        if imgui.begin_tab_item("Description")[0]:
            imgui.text_wrapped(
                "Use a resizable child window for navigation and reserve a single action row below the details pane."
            )
            imgui.end_tab_item()
        if imgui.begin_tab_item("Details")[0]:
            imgui.text("ID: 0123456789")
            imgui.text("Status: Ready")
            imgui.end_tab_item()
        imgui.end_tab_bar()
    imgui.end_child()

    if imgui.button("Revert"):
        pass
    imgui.same_line()
    if imgui.button("Save"):
        pass
    imgui.end_group()
```

## Item width patterns

![Item width patterns](./images/layout_item_width_patterns.png)

Use `push_item_width()` with fixed, right-aligned, and proportional widths.

This recipe demonstrates the width patterns from the Dear ImGui demo: a fixed pixel width, a width
aligned against the right edge using a negative value, a width derived from
`get_content_region_avail()`, and the `-FLT_MIN` idiom for "fill until the right edge". These
patterns are the building blocks for forms that need to stay readable while the window is resized.

```python
def layout_item_width_patterns(state: WidthState):
    _changed, state.show_indented = imgui.checkbox("Show indented items", state.show_indented)

    imgui.text("Fixed width")
    imgui.push_item_width(120)
    _changed, state.value = imgui.drag_float("float##fixed", state.value, 0.01, 0.0, 1.0)
    if state.show_indented:
        imgui.indent()
        _changed, state.value = imgui.drag_float("float##fixed-indented", state.value, 0.01, 0.0, 1.0)
        imgui.unindent()
    imgui.pop_item_width()

    imgui.text("Align to right edge minus 100")
    imgui.push_item_width(-100)
    _changed, state.value = imgui.drag_float("float##right-minus-100", state.value, 0.01, 0.0, 1.0)
    imgui.pop_item_width()

    imgui.text("Half of available width")
    imgui.push_item_width(imgui.get_content_region_avail()[0] * 0.5)
    _changed, state.value = imgui.drag_float("float##half-width", state.value, 0.01, 0.0, 1.0)
    imgui.pop_item_width()

    imgui.text("Align to right edge")
    imgui.push_item_width(-imgui.FLT_MIN)
    _changed, state.value = imgui.drag_float("float##fill-right", state.value, 0.01, 0.0, 1.0)
    imgui.pop_item_width()
```

## Group sizing

![Group sizing](./images/layout_group_sizing.png)

Capture a group's size and reuse it to size related widgets beside it.

`begin_group()` / `end_group()` lets multiple items behave like one logical item for layout. This
example measures the first grouped block with `get_item_rect_size()` and then reuses that size for a
histogram, two action buttons, and a list box beside it. The pattern is useful when different widget
types should share one visual footprint without hard-coding pixel sizes for each one separately.

```python
def layout_group_sizing(state: GroupSizingState):
    imgui.begin_group()
    imgui.begin_group()
    imgui.button("AAA")
    imgui.same_line()
    imgui.button("BBB")
    imgui.same_line()
    imgui.begin_group()
    imgui.button("CCC")
    imgui.button("DDD")
    imgui.end_group()
    imgui.same_line()
    imgui.button("EEE")
    imgui.end_group()
    imgui.set_item_tooltip("First group hovered")

    group_size = imgui.get_item_rect_size()
    imgui.plot_histogram(
        "##values",
        np.array([0.5, 0.2, 0.8, 0.6, 0.25], dtype=np.float32),
        graph_size=group_size,
    )

    half_width = (group_size[0] - imgui.get_style().item_spacing[0]) * 0.5
    imgui.button("ACTION", (half_width, group_size[1]))
    imgui.same_line()
    imgui.button("REACTION", (half_width, group_size[1]))
    imgui.end_group()

    imgui.same_line()
    imgui.button("LEVERAGE\nBUZZWORD", group_size)
    imgui.same_line()

    labels = ["Selected", "Not Selected"]
    if imgui.begin_list_box("List", group_size):
        for idx, label in enumerate(labels):
            if imgui.selectable(label, state.selection == idx)[0]:
                state.selection = idx
        imgui.end_list_box()
```

## Horizontal layout with same\_line()

![Horizontal layout with same\_line()](./images/layout_same_line_basics.png)

Use `same_line()` to keep multiple items on one row instead of advancing to a new line after
every widget.

This example covers three common horizontal layout patterns: placing text and buttons on the same
row, using explicit x-offsets for simple aligned columns, and manually wrapping a row of buttons
when there is no longer enough room to keep adding items on the current line.

```python
def layout_same_line_basics():
    imgui.text("Two items: Hello")
    imgui.same_line()
    imgui.text_colored((1.0, 1.0, 0.0, 1.0), "Sailor")

    imgui.text("Aligned")
    imgui.same_line(150)
    imgui.small_button("x=150")
    imgui.same_line(300)
    imgui.small_button("x=300")

    imgui.separator_text("Manual wrapping")
    button_size = (40, 40)
    right_edge = imgui.get_cursor_screen_pos()[0] + imgui.get_content_region_avail()[0]
    spacing_x = imgui.get_style().item_spacing[0]
    for i in range(10):
        imgui.push_id(i)
        imgui.button("Box", button_size)
        next_x2 = imgui.get_item_rect_max()[0] + spacing_x + button_size[0]
        if i + 1 < 10 and next_x2 < right_edge:
            imgui.same_line()
        imgui.pop_id()
```

## Text baseline alignment

![Text baseline alignment](./images/layout_text_baseline_alignment.png)

Use `align_text_to_frame_padding()` when a line starts with text and is followed by framed widgets.

Plain text and framed controls do not naturally share the same baseline. This recipe shows the
common fix: call `align_text_to_frame_padding()` before the text item so that labels, buttons, and
other controls sit on the same visual row more cleanly.

```python
def layout_text_baseline_alignment():
    imgui.text("Without alignment")
    imgui.same_line()
    imgui.button("Button A")

    imgui.align_text_to_frame_padding()
    imgui.text("With alignment")
    imgui.same_line()
    imgui.button("Button B")

    imgui.separator_text("Mixed row")
    imgui.align_text_to_frame_padding()
    imgui.text("Status")
    imgui.same_line()
    imgui.button("Apply")
    imgui.same_line()
    imgui.text("Ready")
    imgui.same_line()
    imgui.small_button("Help")
```

## Basic tab bar

![Basic tab bar](./images/layout_tabs_basic.png)

Build a small tabbed interface with `begin_tab_bar()` and `begin_tab_item()`.

Tabs are submitted every frame like the rest of the ImGui UI. The important pattern is to start
the tab bar, submit each tab item, render the contents only when that tab item is active, and then
end both the tab item and the tab bar.

```python
def layout_tabs_basic(state: TabsState):
    if imgui.begin_tab_bar("##demo-tabs"):
        if imgui.begin_tab_item("Summary")[0]:
            imgui.text_wrapped("Use tabs to split related views inside one window.")
            if imgui.button("Increment counter"):
                state.counter += 1
            imgui.text(f"Counter: {state.counter}")
            imgui.end_tab_item()

        visible, state.closable_details = imgui.begin_tab_item("Details", state.closable_details)
        if visible:
            imgui.text("A tab can manage its own open state.")
            imgui.checkbox("Enable option", True)
            imgui.end_tab_item()

        if imgui.begin_tab_item("Logs")[0]:
            imgui.text("Render the tab contents only when the tab is selected.")
            imgui.bullet_text("Build completed")
            imgui.bullet_text("Tests passed")
            imgui.end_tab_item()

        imgui.end_tab_bar()
```
---

---
url: /slimgui/recipes/implot.md
---

# ImPlot

## Line plot from x/y arrays

![Line plot from x/y arrays](./images/plot_line_basic.png)

Plot a line from explicit `x` and `y` NumPy arrays.

This is the most direct `implot.plot_line()` calling pattern: prepare one array for x-coordinates
and one array for y-values, then submit both arrays inside a `begin_plot()` / `end_plot()` block.
Use this form when your x-axis is not just an implicit sample index and you want full control over
the horizontal values shown in the plot.

```python
def plot_line_basic():
    xs = np.linspace(0.0, 10.0, 200)
    ys = np.sin(xs)

    if implot.begin_plot("Line Plot"):
        implot.plot_line("sin(x)", xs, ys)
        implot.end_plot()
```

## Line plot from values only

![Line plot from values only](./images/plot_line_values_only.png)

Plot a line from a single value array and let ImPlot infer the x-axis from the sample index.

This overload is useful when you only have y-values and want evenly spaced samples without creating
a separate x-array yourself. It is a compact way to plot a waveform or time series when the natural
x-coordinate is just "point 0, point 1, point 2, ...".

```python
def plot_line_values_only():
    ys = np.sin(np.linspace(0.0, 3.0 * np.pi, 200))

    if implot.begin_plot("Values Only"):
        implot.plot_line("wave", ys)
        implot.end_plot()
```

## Bar plot from values

![Bar plot from values](./images/plot_bars_basic.png)

Plot bars from a one-dimensional NumPy array.

`implot.plot_bars()` can consume a single array of values and place each bar at the corresponding
sample index. This is the simplest form for categorical or small summary data when you do not need
custom x-positions for the bars.

```python
def plot_bars_basic():
    ys = np.array([0.3, 0.8, 0.55, 0.9, 0.45], dtype=np.float32)

    if implot.begin_plot("Bars"):
        implot.plot_bars("bars", ys)
        implot.end_plot()
```

## Grouped bar plot

![Grouped bar plot](./images/plot_bar_groups_basic.png)

Plot grouped bars from a two-dimensional NumPy array.

`implot.plot_bar_groups()` expects tabular data where each row represents one labeled series and
each column represents one group position. The call to `setup_axes()` removes axis decorations here
so the grouped structure is easier to focus on in the example screenshot.

```python
def plot_bar_groups_basic():
    values = np.array(
        [
            [0.2, 0.4, 0.7, 0.5],
            [0.6, 0.3, 0.5, 0.8],
            [0.4, 0.7, 0.2, 0.6],
        ],
        dtype=np.float32,
    )

    if implot.begin_plot("Grouped Bars"):
        implot.setup_axes(
            None,
            None,
            implot.AxisFlags.NO_DECORATIONS,
            implot.AxisFlags.NO_DECORATIONS,
        )
        implot.plot_bar_groups(["A", "B", "C"], values)
        implot.end_plot()
```

## Scatter plot from x/y arrays

![Scatter plot from x/y arrays](./images/plot_scatter_basic.png)

Plot scatter points from x/y NumPy arrays.

Scatter plots use the same explicit x/y array pattern as line plots, but render disconnected points
instead of a continuous curve. This example builds a simple spiral from polar coordinates to show that
the points do not need to lie on a regular grid or be evenly spaced.

```python
def plot_scatter_basic():
    theta = np.linspace(0.0, 4.0 * np.pi, 80)
    radius = np.linspace(0.2, 1.0, 80)
    xs = radius * np.cos(theta)
    ys = radius * np.sin(theta)

    if implot.begin_plot("Scatter"):
        implot.plot_scatter("spiral", xs, ys)
        implot.end_plot()
```

## Per-point marker color arrays with PlotSpec

![Per-point marker color arrays with PlotSpec](./images/plot_spec_marker_color_arrays.png)

Use `PlotSpec` marker color arrays to style each scatter point with its own fill and outline colors.

Dear ImPlot 1.0 moved next-item styling into `PlotSpec`, including pointer-based arrays such as
`marker_fill_colors` and `marker_line_colors`. This recipe shows the Python form of that pattern: attach NumPy
arrays of packed `uint32` colors to a `PlotSpec`, then pass that spec to a plotting call. The
arrays stay attached to the `PlotSpec`, so the same object can be reused across frames and updated
by mutating the NumPy arrays in place.

The example uses `plot_scatter()` because marker fill and marker outline colors are applied
independently to each point. `marker_fill_colors` colors the marker interiors while
`marker_line_colors` colors the outlines.

```python
def plot_spec_marker_color_arrays():
    xs = np.linspace(0.0, 10.0, 9)
    ys = np.array([0.2, 0.8, 0.45, 1.1, 0.7, 1.35, 0.9, 1.55, 1.2], dtype=np.float64)
    marker_fill_colors = np.array(
        [
            0xFF4E79A7,
            0xFFF28E2B,
            0xFFE15759,
            0xFF76B7B2,
            0xFF59A14F,
            0xFFEDC948,
            0xFFB07AA1,
            0xFFFF9DA7,
            0xFF9C755F,
        ],
        dtype=np.uint32,
    )
    marker_line_colors = np.array(
        [
            0xFF1D3557,
            0xFF7A3E00,
            0xFF6A040F,
            0xFF184E4A,
            0xFF1B4332,
            0xFF7A5C00,
            0xFF5A3D66,
            0xFF8F3B4A,
            0xFF5C4033,
        ],
        dtype=np.uint32,
    )

    spec = implot.PlotSpec(
        marker=implot.Marker.CIRCLE,
        marker_size=8.0,
        line_weight=3.0,
        marker_fill_colors=marker_fill_colors,
        marker_line_colors=marker_line_colors,
    )

    if implot.begin_plot("PlotSpec Marker Color Arrays"):
        implot.plot_scatter("points", xs, ys, spec=spec)
        implot.end_plot()
```