API Reference

Application

Application and window management, JS bridge, and file dialogs.

class iskg.app.Application(title: str = 'ISKG App', width: int = 800, height: int = 600, scanlines: bool = True, vignette: bool = True, theme: str = 'ifaz', debug: bool = False)[source]

Bases: object

Main application entry point.

Creates a native window via pywebview, renders all widgets as HTML/CSS/JS, and manages the JS bridge for event handling.

Usage:

app = Application("My App", 800, 600)
label = Label(text="Hello")
app.add(label)
app.run()

Pass debug=True to log JavaScript errors to stderr:

app = Application(debug=True)

add(widget: Widget) → Widget[source]

Register a root-level widget with the application.

Widgets must be added to the app before run() is called.

alert(message: str) → None[source]: Show a browser-style alert dialog.

color_dialog(title: str = 'Choose Color', initial_color: str = '#000000') → str | None[source]

Open a color picker dialog.

Uses GTK on Linux, falls back to a browser <input type="color"> on Windows/macOS.

Returns a hex string (e.g. "#ff8800") or None.

confirm(message: str) → None[source]: Show a browser-style confirm dialog.

current_theme() → str[source]: Return the name of the currently active theme.

property debug: bool

execute_js(js_code: str) → Application[source]: Execute arbitrary JavaScript in the webview window.

file_dialog(dialog_type: str = 'open', directory: str = '', file_types: list[str] | None = None, allow_multiple: bool = False) → Any | None[source]

Open a native OS file dialog.

Uses GTK directly (same toolkit as pywebview underneath) with explicit dialog sizing. Falls back to pywebview’s built-in dialog.

Parameters:

dialog_type – "open", "save", or "folder".
directory – starting directory path.
file_types – list of extensions like ["*.txt", "*.py"].
allow_multiple – allow multiple file selection (open only).

font_dialog(title: str = 'Choose Font', initial_font: str = '') → dict[str, Any] | None[source]

Open a font picker dialog.

Uses GTK on Linux, falls back to a browser prompt on Windows/macOS.

Returns a dict with keys family, size, weight, style, or None.

geometry(x: int | None = None, y: int | None = None, w: int | None = None, h: int | None = None) → tuple[int, int, int, int][source]: Get or set the window position and size.

get_clipboard() → str[source]: Read text from the system clipboard (requires pyperclip).

on_close(callback: Callable) → None[source]: Register a callback to call when the window is closed.

quit() → None[source]: Close the application window and exit the main loop.

register_theme(name: str, overrides: dict[str, str]) → Application[source]

Register a new theme for runtime use.

Parameters:

name – unique theme name (e.g. "mytheme").
overrides – dict of CSS custom properties, e.g. {"--bg-primary": "#000", "--text": "#fff"}.

remove(widget: Widget) → None[source]: Unregister a root-level widget.

run(extra_js: str = '') → None[source]

Open the window and start the application main loop.

Blocks until the window is closed. Redirects GTK stderr warnings to /dev/null during execution.

Parameters:: extra_js – additional JavaScript to execute on startup (e.g. tooltip init code).

set_clipboard(text: str) → None[source]: Copy text to the system clipboard (requires pyperclip).

set_theme(name: str) → Application[source]

Switch the UI theme at runtime.

Parameters:: name – one of "ifaz", "cold", "warm", "night", or a custom name previously registered via register_theme().

title(text: str | None = None) → str[source]: Get or set the window title.

winfo_screendpi() → int[source]: Return the screen DPI (approximate, requires a running window).

winfo_screenheight() → int[source]: Return the screen height in pixels (requires a running window).

winfo_screenwidth() → int[source]: Return the screen width in pixels (requires a running window).

iskg.app.Window: alias of Application

Base Widget

Base Widget class with layout engines (pack/grid/place), event bindings, style rendering, and widget tree management.

class iskg.base.Widget(parent: Widget | None = None, **kwargs: Any)[source]

Bases: object

Base class for all ISKG widgets.

Manages widget identity, parent-child tree, layout configuration, style rendering, event bindings, and bridge communication with the JavaScript frontend.

Every concrete widget (Button, Label, Frame, etc.) inherits from this class.

add(child: Widget) → None[source]: Add a child widget to this widget’s children list.

after(ms: int, callback: Callable) → _Timer[source]

Schedule a function to run after ms milliseconds.

Parameters:

ms – delay in milliseconds.
callback – function to call (no arguments).

Returns:

A _Timer with .cancel() and .running.

after_cancel(timer_id: str) → None[source]: Cancel a timer by its string ID (legacy).

property app: Any: The Application instance this widget belongs to, or None.

bind(event: str, callback: Callable) → None[source]

Bind a callback to an event.

Supports standard bridge events ("click", "change", etc.), tkinter-style key events ("<KeyPress-a>", "<KeyRelease-Return>", "<Control-c>", "<Key>"), and virtual events ("<<CustomEvent>>").

Key event callbacks receive a dict with key, code, ctrl, alt, shift.

cget(key: str) → Any[source]: Get a widget configuration value by key.

config(**kwargs: Any) → Widget[source]

Configure widget properties.

Accepts any keyword argument; underscores in keys are converted to hyphens for CSS. Common keys: fg, bg, font_size, padding, border_color, opacity, etc.

Also accepts state ("normal", "disabled", "readonly"), visible (bool), textvariable, and variable which are handled specially.

property cursor: str

destroy() → None[source]: Destroy this widget and all its children.

event_generate(event: str, data: Any = None) → bool[source]

Generate a virtual event that bubbles up the parent chain.

Parameters:

event – event name (e.g. "<<Custom>>", "click", "change").
data – optional data passed to the callback.

Returns:

True if propagation should stop (callback returned "break").

focus() → None[source]: Move keyboard focus to this widget.

focus_next() → None[source]: Move focus to the next widget in tab order.

focus_prev() → None[source]: Move focus to the previous widget in tab order.

focus_set() → None: Move keyboard focus to this widget.

grid(row: int = 0, column: int = 0, rowspan: int = 1, columnspan: int = 1, sticky: str = '', padx: int = 0, pady: int = 0) → Widget[source]

Arrange this widget using grid layout.

Parameters:

row – row index (0-based).
column – column index (0-based).
rowspan – number of rows to span.
columnspan – number of columns to span.
sticky – combination of "n", "s", "e", "w", or "c" for center.
padx – horizontal padding.
pady – vertical padding.

To control row/column weights and minimum sizes, use grid_columnconfigure() and grid_rowconfigure() on the parent Frame.

grid_forget() → None[source]: Remove from grid layout (position lost). Call grid() with new parameters to re-display.

grid_remove() → None[source]: Remove from grid layout, remembering position. Call grid() with the same parameters to restore.

property height: int | None

hide() → None[source]: Hide this widget.

pack(side: str = 'top', fill: str = 'none', expand: bool = False, padx: int = 0, pady: int = 0, anchor: str = 'nw') → Widget[source]

Arrange this widget using pack layout.

Parameters:

side – "top", "left", "bottom", or "right".
fill – "none", "x", "y", or "both".
expand – whether to take extra space.
padx – horizontal padding in pixels.
pady – vertical padding in pixels.
anchor – "nw", "n", "ne", "w", "e", "sw", "s", "se".

pack_forget() → None: Remove from grid layout (position lost). Call grid() with new parameters to re-display.

property parent: Widget | None: Parent widget, or None if this is a root widget.

place(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None, anchor: str = 'nw') → Widget[source]

Position this widget at absolute coordinates.

Parameters:

x – left offset in pixels.
y – top offset in pixels.
width – explicit width in pixels, or None for auto.
height – explicit height in pixels, or None for auto.
anchor – "nw", "n", "ne", "w", "e", "sw", "s", "se".

remove(child: Widget) → None[source]: Remove a child widget from this widget’s children list.

show() → None[source]: Show this widget.

property state: str: Get the widget state ("normal", "disabled", "readonly").

property takefocus: bool: Whether this widget can receive keyboard focus. Default True for interactive widgets (Button, Entry, etc.), False for containers.

property tooltip: str: Get/set the hover tooltip text for this widget.

unbind(event: str) → None[source]: Remove a previously bound event callback.

update() → None[source]: Force a sync update of this widget’s rendering.

property visible: bool: Whether the widget is visible.

property widget_id: str: Unique identifier for this widget instance.

property width: int | None

Widget Controls

class iskg.widgets._controls.Button(parent: Widget | None = None, text: str = '', command: Callable | None = None, **kwargs: Any)[source]

API Reference

Application

Base Widget

Widget Controls

Widget Display

Widget Containers

Widget Text

Widget Data

Widget Canvas

Widget Menus

Widget Dialogs

Widget Misc

Template & Bridge

Theme

Themes

Fonts