CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-imgui

Cython-based Python bindings for dear imgui - a bloat-free immediate mode graphical user interface library

Pending
Overview
Eval results
Files

input.mddocs/

Input Handling

Mouse and keyboard input handling, item state queries, and focus management. Provides detailed information about user interactions with widgets and windows, enabling responsive and interactive user interfaces.

Capabilities

Item State Queries

Functions to check the state of the last widget that was drawn.

def is_item_hovered(flags: int = 0) -> bool:
    """Check if last item is hovered by mouse."""

def is_item_focused() -> bool:
    """Check if last item is focused (for keyboard input)."""

def is_item_active() -> bool:
    """Check if last item is active (being clicked or edited)."""

def is_item_clicked(mouse_button: int = 0) -> bool:
    """Check if last item was clicked this frame."""

def is_item_visible() -> bool:
    """Check if last item is visible (not clipped)."""

def is_item_edited() -> bool:
    """Check if last item value was modified this frame."""

def is_item_activated() -> bool:
    """Check if last item was activated this frame (started being active)."""

def is_item_deactivated() -> bool:
    """Check if last item was deactivated this frame (stopped being active)."""

def is_item_deactivated_after_edit() -> bool:
    """Check if last item was deactivated after being edited."""

def is_item_toggled_open() -> bool:
    """Check if last tree item open state was toggled."""

def is_any_item_hovered() -> bool:
    """Check if any item is hovered."""

def is_any_item_active() -> bool:
    """Check if any item is active."""

def is_any_item_focused() -> bool:
    """Check if any item is focused."""

Focus Management

Functions to control keyboard focus and set default focus targets.

def set_item_default_focus() -> None:
    """Set last item as default focus when window opens."""

def set_keyboard_focus_here(offset: int = 0) -> None:
    """Set keyboard focus to next widget or offset widgets ahead."""

Keyboard Input

Functions for detecting keyboard input and key states.

def get_key_index(key: int) -> int:
    """Map ImGuiKey to user key index."""

def is_key_pressed(key_index: int, repeat: bool = False) -> bool:
    """Check if key was pressed this frame."""

def is_key_down(key_index: int) -> bool:
    """Check if key is currently being held down."""

Mouse Input

Functions for detecting mouse input, position, and interaction states.

def is_mouse_clicked(button: int = 0, repeat: bool = False) -> bool:
    """Check if mouse button was clicked this frame."""

def is_mouse_double_clicked(button: int = 0) -> bool:
    """Check if mouse button was double-clicked this frame."""

def is_mouse_released(button: int = 0) -> bool:
    """Check if mouse button was released this frame."""

def is_mouse_down(button: int = 0) -> bool:
    """Check if mouse button is currently pressed."""

def is_mouse_dragging(button: int = 0, lock_threshold: float = -1.0) -> bool:
    """Check if mouse is dragging with specified button."""

def is_mouse_hovering_rect(r_min_x: float, r_min_y: float, r_max_x: float, r_max_y: float, clip: bool = True) -> bool:
    """Check if mouse is hovering over specified rectangle."""

def get_mouse_pos() -> tuple[float, float]:
    """Get current mouse position as (x, y)."""

def get_mouse_drag_delta(button: int = 0, lock_threshold: float = -1.0) -> tuple[float, float]:
    """Get mouse drag delta as (dx, dy)."""

def reset_mouse_drag_delta(button: int = 0) -> None:
    """Reset mouse drag delta for specified button."""

def get_mouse_cursor() -> int:
    """Get current mouse cursor type."""

def set_mouse_cursor(cursor_type: int) -> None:
    """Set mouse cursor type."""

def capture_mouse_from_app(want_capture_mouse_value: bool = True) -> None:
    """Set mouse capture flag."""

Key and Mouse Constants

Constants for keyboard keys and mouse buttons.

# Key constants
KEY_TAB: int
KEY_LEFT_ARROW: int
KEY_RIGHT_ARROW: int
KEY_UP_ARROW: int
KEY_DOWN_ARROW: int
KEY_PAGE_UP: int
KEY_PAGE_DOWN: int
KEY_HOME: int
KEY_END: int
KEY_INSERT: int
KEY_DELETE: int
KEY_BACKSPACE: int
KEY_SPACE: int
KEY_ENTER: int
KEY_ESCAPE: int
KEY_PAD_ENTER: int
KEY_A: int  # For Ctrl+A (select all)
KEY_C: int  # For Ctrl+C (copy)
KEY_V: int  # For Ctrl+V (paste)
KEY_X: int  # For Ctrl+X (cut)
KEY_Y: int  # For Ctrl+Y (redo)
KEY_Z: int  # For Ctrl+Z (undo)

# Key modifier constants
KEY_MOD_NONE: int
KEY_MOD_CTRL: int
KEY_MOD_SHIFT: int
KEY_MOD_ALT: int
KEY_MOD_SUPER: int

# Mouse button constants
MOUSE_BUTTON_LEFT: int
MOUSE_BUTTON_RIGHT: int
MOUSE_BUTTON_MIDDLE: int

# Mouse cursor constants
MOUSE_CURSOR_NONE: int
MOUSE_CURSOR_ARROW: int
MOUSE_CURSOR_TEXT_INPUT: int
MOUSE_CURSOR_RESIZE_ALL: int
MOUSE_CURSOR_RESIZE_NS: int
MOUSE_CURSOR_RESIZE_EW: int
MOUSE_CURSOR_RESIZE_NESW: int
MOUSE_CURSOR_RESIZE_NWSE: int
MOUSE_CURSOR_HAND: int
MOUSE_CURSOR_NOT_ALLOWED: int

Hover and Focus Flags

Constants for controlling hover and focus detection behavior.

# Hover flags
HOVERED_NONE: int
HOVERED_CHILD_WINDOWS: int
HOVERED_ROOT_WINDOW: int
HOVERED_ANY_WINDOW: int
HOVERED_ALLOW_WHEN_BLOCKED_BY_POPUP: int
HOVERED_ALLOW_WHEN_BLOCKED_BY_ACTIVE_ITEM: int
HOVERED_ALLOW_WHEN_OVERLAPPED: int
HOVERED_ALLOW_WHEN_DISABLED: int
HOVERED_RECT_ONLY: int
HOVERED_ROOT_AND_CHILD_WINDOWS: int

# Focus flags
FOCUS_NONE: int
FOCUS_CHILD_WINDOWS: int
FOCUS_ROOT_WINDOW: int
FOCUS_ANY_WINDOW: int
FOCUS_ROOT_AND_CHILD_WINDOWS: int

Usage Examples

Item State Detection

import imgui

# Check button interaction
if imgui.button("My Button"):
    print("Button was clicked!")

# Additional state queries for the button
if imgui.is_item_hovered():
    print("Button is hovered")
    imgui.set_tooltip("This is a tooltip!")

if imgui.is_item_active():
    print("Button is being pressed")

Input Field Handling

text_value = ""
changed, text_value = imgui.input_text("Input", text_value, 256)

if changed:
    print(f"Text changed to: {text_value}")

if imgui.is_item_focused():
    print("Input field is focused")

if imgui.is_item_edited():
    print("Input field was edited this frame")

Mouse Interaction

# Custom mouse handling
mouse_pos = imgui.get_mouse_pos()
imgui.text(f"Mouse position: {mouse_pos[0]:.1f}, {mouse_pos[1]:.1f}")

if imgui.is_mouse_clicked(imgui.MOUSE_BUTTON_LEFT):
    print("Left mouse button clicked!")

if imgui.is_mouse_dragging(imgui.MOUSE_BUTTON_LEFT):
    drag_delta = imgui.get_mouse_drag_delta(imgui.MOUSE_BUTTON_LEFT)
    imgui.text(f"Dragging: {drag_delta[0]:.1f}, {drag_delta[1]:.1f}")

Keyboard Input

# Check for specific key presses
if imgui.is_key_pressed(imgui.KEY_SPACE):
    print("Space key was pressed!")

if imgui.is_key_down(imgui.KEY_CTRL) and imgui.is_key_pressed(imgui.KEY_S):
    print("Ctrl+S was pressed!")

# Set focus programmatically
if imgui.button("Focus Next"):
    imgui.set_keyboard_focus_here(1)  # Focus next widget

imgui.input_text("Will be focused", "", 256)

Custom Mouse Cursor

# Change mouse cursor based on context
if imgui.is_item_hovered():
    imgui.set_mouse_cursor(imgui.MOUSE_CURSOR_HAND)
else:
    imgui.set_mouse_cursor(imgui.MOUSE_CURSOR_ARROW)

Focus Management

# Set default focus when window first appears
imgui.set_item_default_focus()
changed, text = imgui.input_text("Default Focus", "", 256)

# Focus management with buttons
if imgui.button("Focus Input"):
    imgui.set_keyboard_focus_here(1)

imgui.input_text("Target Input", "", 256)

# Check global focus state
if imgui.is_any_item_focused():
    imgui.text("Something has keyboard focus")

Advanced State Queries

if imgui.button("State Demo"):
    pass

# Detailed state information
states = []
if imgui.is_item_hovered(): states.append("Hovered")
if imgui.is_item_active(): states.append("Active")
if imgui.is_item_focused(): states.append("Focused")
if imgui.is_item_clicked(): states.append("Clicked")
if imgui.is_item_visible(): states.append("Visible")

if states:
    imgui.text(f"Button states: {', '.join(states)}")
else:
    imgui.text("Button states: None")

Drag and Drop Detection

# Detect dragging for custom drag and drop
if imgui.button("Drag Me"):
    pass

if imgui.is_item_active() and imgui.is_mouse_dragging(imgui.MOUSE_BUTTON_LEFT):
    drag_delta = imgui.get_mouse_drag_delta(imgui.MOUSE_BUTTON_LEFT)
    imgui.text(f"Dragging button: {drag_delta[0]:.1f}, {drag_delta[1]:.1f}")

Install with Tessl CLI

npx tessl i tessl/pypi-imgui

docs

drawing.md

index.md

input.md

integrations.md

layout.md

menus.md

styling.md

tables.md

tabs.md

widgets.md

windows.md

tile.json