wijjit.config.DefaultConfig

class wijjit.config.DefaultConfig

Default configuration values for Wijjit.

These are the framework defaults. Override them by setting app.config values or loading from a config file.

All configuration keys should be UPPERCASE by convention.

__init__()

Methods

__init__()

Attributes

APP_TITLE	Terminal window title (OSC 0 / "title bar" text).
AUTO_FIT_LAYOUT	Shrink over-committed layouts to fit the terminal instead of clipping.
DEBUG	Master debug flag (enables various debug features).
DEBUG_INPUT_KEYBOARD	Log all keyboard events to debug log
DEBUG_INPUT_MOUSE	Log all mouse events to debug log
DEFAULT_THEME	'default', 'dark', 'light', or custom theme name
ENABLE_FOCUS_NAVIGATION	Enable Tab/Shift+Tab navigation between focusable elements
ENABLE_MOUSE	Enable mouse event tracking
ENABLE_SUSPEND	Enable Ctrl+Z suspend/background support (Linux/Unix only) When enabled, pressing Ctrl+Z will suspend the app to the background and 'fg' command will resume it.
EXECUTOR_MAX_WORKERS	Maximum worker threads for executor (None = auto-detect)
FOCUS_COLOR	Global focus color override - applies to all focused elements Format: RGB tuple like (0, 255, 255) for cyan, or None to use theme defaults When set, this color is applied to all :focus style fg_color
FULL_REPAINT_INTERVAL	Force a full-screen repaint every N seconds to evict foreign bytes (0 = disabled).
HARDWARE_CURSOR	Park the hardware terminal cursor on the focused text caret.
HIDE_CURSOR	Hide cursor during application runtime
HIGH_CONTRAST	Use high contrast colors
LOG_FILE	Log file path (None = no file logging)
LOG_FORMAT	Log format string (Python logging format)
LOG_LEVEL	'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
MAX_FPS	Maximum frames per second (None = unlimited, int = cap FPS)
MOUSE_TRACKING_MODE	'button_event', 'all_events', or 'drag'
NOTIFICATION_DURATION	Default notification duration in seconds
NOTIFICATION_MARGIN	Margin from screen edge (in characters)
NOTIFICATION_MAX_STACK	Maximum concurrent notifications (older ones are dismissed)
NOTIFICATION_POSITION	'top_right', 'top_left', 'bottom_right', 'bottom_left'
NOTIFICATION_SPACING	Spacing between stacked notifications (in lines)
NO_COLOR	Disable all ANSI colors (respects NO_COLOR env var standard) https://no-color.org/
QUIT_KEY	Key binding to quit application (e.g., 'ctrl+q', 'ctrl+c', 'q')
REDUCE_MOTION	Reduce or disable animations (for motion sensitivity)
REFRESH_INTERVAL	Auto-refresh interval in seconds (None = disabled, used for animations)
REMOTE	Run without claiming ownership of the process terminal.
RENDER_THROTTLE_MS	Minimum time between renders in milliseconds (throttling)
RUN_SYNC_IN_EXECUTOR	Run synchronous event handlers in thread pool executor
SHOW_BOUNDS	Visualize element bounds (draw rectangles around elements)
SHOW_FPS	Display FPS counter on screen
STYLE_FILE	Path to custom CSS stylesheet file for additional styles
SUPPRESS_INTERNAL_LOGGING_CONFIG	Suppress Wijjit's internal logging configuration When True, Wijjit will NOT configure its own loggers, giving the host application full control over logging.
TEMPLATE_AUTO_RELOAD	Automatically reload file templates when they change on disk (for development).
TEMPLATE_DIR	Template directory path for file-based templates loaded with wijjit.render_template().
THEME_FILE	Path to custom theme file (JSON or CSS format), overrides DEFAULT_THEME
UNICODE_SUPPORT	'auto' (detect), 'force' (always use), 'disable' (ASCII only)
USE_ALTERNATE_SCREEN	Use alternate screen buffer (recommended for full-screen TUIs)
WARN_SLOW_RENDER_MS	Warn when render time exceeds threshold (milliseconds, None = disabled)

ENABLE_MOUSE = True

Enable mouse event tracking

MOUSE_TRACKING_MODE = 'button_event'

‘button_event’, ‘all_events’, or ‘drag’

Type:

Mouse tracking mode

ENABLE_FOCUS_NAVIGATION = True

Enable Tab/Shift+Tab navigation between focusable elements

QUIT_KEY = 'ctrl+q'

Key binding to quit application (e.g., ‘ctrl+q’, ‘ctrl+c’, ‘q’)

USE_ALTERNATE_SCREEN = True

Use alternate screen buffer (recommended for full-screen TUIs)

HIDE_CURSOR = True

Hide cursor during application runtime

HARDWARE_CURSOR = True

Park the hardware terminal cursor on the focused text caret. When the focused element reports a caret cell (TextInput, TextArea, CodeEditor), each frame ends with a cursor-move + show-cursor escape so the real terminal cursor sits (and blinks) on the caret; it is hidden again when no caret is visible. Terminals and screen readers track the hardware cursor, so this improves accessibility over the painted reverse-video caret alone. Works with the default HIDE_CURSOR=True startup state; inline apps are unaffected.

APP_TITLE: str | None = None

Terminal window title (OSC 0 / “title bar” text). When set, Wijjit emits the title on startup so the terminal tab/window shows it. Most shells reset the title from their prompt hook when the app exits, so no explicit restore is performed. None leaves the terminal title untouched.

NO_COLOR = False

Disable all ANSI colors (respects NO_COLOR env var standard) https://no-color.org/

Read at import time. Wijjit re-reads the environment during construction via no_color_from_env(), so setting NO_COLOR after importing wijjit still takes effect.

FOCUS_COLOR = None

Global focus color override - applies to all focused elements Format: RGB tuple like (0, 255, 255) for cyan, or None to use theme defaults When set, this color is applied to all :focus style fg_color

DEFAULT_THEME = 'default'

‘default’, ‘dark’, ‘light’, or custom theme name

Type:

Default theme to use

THEME_FILE = None

Path to custom theme file (JSON or CSS format), overrides DEFAULT_THEME

STYLE_FILE = None

Path to custom CSS stylesheet file for additional styles

UNICODE_SUPPORT = 'auto'

‘auto’ (detect), ‘force’ (always use), ‘disable’ (ASCII only)

Type:

Unicode support

AUTO_FIT_LAYOUT = True

Shrink over-committed layouts to fit the terminal instead of clipping. When a container’s children ask for more space than the container has (typically hard-coded width=/height= values on a terminal smaller than the author’s), children with slack give space back in proportion, floored at the size their content genuinely needs. Set False to restore the pre-0.1.0 behaviour of letting the overflow clip.

REFRESH_INTERVAL = None

Auto-refresh interval in seconds (None = disabled, used for animations)

MAX_FPS = None

Maximum frames per second (None = unlimited, int = cap FPS)

RUN_SYNC_IN_EXECUTOR = False

Run synchronous event handlers in thread pool executor

EXECUTOR_MAX_WORKERS = None

Maximum worker threads for executor (None = auto-detect)

RENDER_THROTTLE_MS = 0

Minimum time between renders in milliseconds (throttling)

FULL_REPAINT_INTERVAL = 0.0

Force a full-screen repaint every N seconds to evict foreign bytes (0 = disabled). Diff rendering only emits changed cells, so anything a third-party library or subprocess writes to the terminal out-of-band lingers until a full redraw. When set, the event loop repaints the whole screen on this cadence so such corruption self-heals. Left disabled by default because a periodic full repaint negates the diff renderer’s bytes-saved advantage; apps that knowingly write to the terminal can instead call app.request_full_repaint() for a one-shot heal.

NOTIFICATION_DURATION = 3.0

Default notification duration in seconds

NOTIFICATION_POSITION = 'top_right'

‘top_right’, ‘top_left’, ‘bottom_right’, ‘bottom_left’

Type:

Notification position

NOTIFICATION_SPACING = 1

Spacing between stacked notifications (in lines)

NOTIFICATION_MARGIN = 2

Margin from screen edge (in characters)

NOTIFICATION_MAX_STACK = 5

Maximum concurrent notifications (older ones are dismissed)

LOG_LEVEL = 'WARNING'

‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

Type:

Logging level

LOG_FILE = None

Log file path (None = no file logging)

LOG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

Log format string (Python logging format)

SUPPRESS_INTERNAL_LOGGING_CONFIG = False

Suppress Wijjit’s internal logging configuration When True, Wijjit will NOT configure its own loggers, giving the host application full control over logging. Set this if you have pre-configured logging handlers for the ‘wijjit’ namespace and don’t want Wijjit to override them.

DEBUG = False

Master debug flag (enables various debug features).

Enabling DEBUG also turns on strict template undefined checking: the renderer uses jinja2.StrictUndefined, so referencing an undefined template name (e.g. a typo like {{ usename }}) raises jinja2.UndefinedError instead of silently rendering an empty string. When debugging, guard optional keys with state.get('k') or the |default filter (e.g. {{ maybe|default('') }}). The production default (DEBUG=False) stays lenient so one missing key cannot crash a running TUI.

SHOW_FPS = False

Display FPS counter on screen

SHOW_BOUNDS = False

Visualize element bounds (draw rectangles around elements)

DEBUG_INPUT_KEYBOARD = False

Log all keyboard events to debug log

DEBUG_INPUT_MOUSE = False

Log all mouse events to debug log

WARN_SLOW_RENDER_MS = None

Warn when render time exceeds threshold (milliseconds, None = disabled)

TEMPLATE_DIR = None

Template directory path for file-based templates loaded with wijjit.render_template(). When left as None, Wijjit auto-discovers a templates/ directory next to the module that constructs the app (Flask’s convention).

TEMPLATE_AUTO_RELOAD = False

Automatically reload file templates when they change on disk (for development). Wired into the Jinja2 environment’s auto_reload.

ENABLE_SUSPEND = True

Enable Ctrl+Z suspend/background support (Linux/Unix only) When enabled, pressing Ctrl+Z will suspend the app to the background and ‘fg’ command will resume it. On Windows, this option is ignored.

REMOTE = False

Run without claiming ownership of the process terminal. When True, the default terminal backend still writes to stdout but does NOT install the process-global SIGTERM/SIGHUP/atexit terminal-restore net or the SIGTSTP suspend handler. Set this when embedding a Wijjit app in a host process that manages the terminal itself. Custom transports (e.g. an SSH backend) express the same intent via TerminalBackend.owns_terminal and do not need this flag.

REDUCE_MOTION = False

Reduce or disable animations (for motion sensitivity)

HIGH_CONTRAST = False

Use high contrast colors