Skip to content

README.md

Latest commit

 

History

History
131 lines (94 loc) · 5.98 KB

README.md

File metadata and controls

131 lines (94 loc) · 5.98 KB
Raw

Desktop UI building blocks

Use these widgets in your own Qt application. Create one QApplication before constructing widgets, retain worker owners until they finish, and keep expensive file or command work off the GUI thread.

For shared workflows, see the user guide directory. For integration contracts, start at the developer hub.

PySide application setup

Install PySide6, then initialize the application once:

from commonUtils.ui import pyside as qt

app = qt.initialize_q_app()
window = qt.QMainWindow()
window.setWindowTitle('My tool')
window.resize(800, 600)
window.show()
app.exec()

Reusable file browser

Start with the complete browser window example. It opens a folder and adds your own context-menu action. The feature guide then shows custom file types, information panels, double-click handlers and thumbnails.

The browser guide covers navigation, search, storage views and embedding. Browser workers load previews and directory metadata; your action handlers still run on the GUI thread unless you schedule a worker.

Background work and downloads

Use OperationProgress to run cancellable work and show progress. Its runnable example includes safe close handling. For streamed external processes, use tasks.process_runner.ProcessRunner and tasks.process_progress.ProcessProgressWindow; command execution covers the non-Qt alternative. Streams handles copying and hashing.

Readers and editors

Component Guide
Markdown reader, source/formatted editing Markdown
Code editing, gutters and syntax Code editor
Plain UTF-8 editor and INI settings editor Configuration, user guide
Archive contents and member selection Archive view
Shared reader menus, fullscreen controls and recent paths Browser features

The plain editor exposes save(), reload() and can_close(). Ask can_close() before removing an editor so it can offer Save, Discard or Cancel. Readers can open independently or through a consumer's document host.

Reusable docking workspaces

A Workspace hosts widgets as dockable tabs. Supply a widget factory and let each view decide whether it can close. The workspace and presentation guide covers worker lifetime, native floating panes, outlines, notifications and document hosting.

Indexed search in the browser

See the browser guide. The index reference explains persistence, partial results and cancellation.

Selection preview

See the browser guide. File classes supply read-only panels; applications supply editing actions separately.

Shared navigation settings

Configuration describes wheel preferences. Browser indexing uses event-driven updates and explicit refresh; ordinary browsing remains available. Pause methods are programmatic APIs, not visible controls. See the index reference.

Opt-in Slate appearance

from commonUtils.ui.appearance.theme import apply_theme

controller = apply_theme(app)
controller.set_mode('dark')  # 'light' or 'system' also work.

The theme applies only when requested. System mode follows OS appearance; [Theme] mode=... in the shared settings INI chooses its starting mode.

Backends and diagnostics

For scripts without Qt, select the native message-box backend explicitly:

from commonUtils import ui

ui.use_pyside = False
ui.display_msg_box_ok('My tool', 'Finished')

Qt callers import commonUtils.ui.pyside and initialize QApplication first. Workers must not open dialogs or touch widgets. Shared workers capture failures under noninteractive logging and return them to their GUI owner. Critical diagnostics raise DebugException.

Library overview

Styling and settings layers

See shared styling for the four font roles, accent and dark tint, application opt-in, and central-settings navigation callback. [Styling] theme_mode is the preferred theme source; [Theme] mode remains a fallback for older hosts. See layered configuration for the resettable software/personal editor and host-owned path registration.

Module organization

Implementations are grouped by responsibility. Use the grouped module paths for imports and mock patch targets; former flat forwarding modules have been removed. The UI facade and these packages preserve lazy Qt loading. Shared configuration continues to live at ui/settings.ini.

  • Docking workspaces: Docking, tab gestures, splitting, floating windows and native workspace menus.
  • Background task presentation: Qt workers, cancellable operation progress, streamed processes and download dialogs. Runtime operations and streams remain outside the UI layer.
  • Shared reader controls: Reader menus, fullscreen controls, read-aloud presentation and wheel navigation shared by document readers.
  • Settings editor widgets: Typed INI editors, layered overrides, settings sections and font previews. Parsing, persistence and host-owned paths remain in configuration.
  • Shared UI appearance: Opt-in themes, live font styling and palette-aware painted icons.
  • Optional native Toga components: Configurable destinations, native Back routing, chrome restoration and image gestures. Consumers supply workflows and package the Android bridges.