Skip to main content

agg_gui/
lib.rs

1//! # agg-gui
2//!
3//! A Rust GUI framework built on [AGG](https://github.com/larsbrubaker/agg-rust)
4//! (Anti-Grain Geometry).
5//!
6//! ## Architecture
7//!
8//! ```text
9//! Application / Widgets
10//!   │
11//! GfxCtx (Cairo-style stateful 2D drawing API)
12//!   │
13//! AGG (rasterization) + Clipper2 (boolean geometry)
14//!   │
15//! Framebuffer (RGBA8, bottom-up Y-up row order)
16//!   │
17//! Platform (WGL native / WebGL WASM)
18//! ```
19//!
20//! ## Coordinate system
21//!
22//! The entire framework uses **first-quadrant (Y-up)** coordinates throughout.
23//! Origin is the bottom-left corner of the window. Positive Y goes upward.
24//! This is a non-negotiable architectural invariant — see the dev plan for
25//! the rationale.
26//!
27//! ## Module guide
28//!
29//! - [`widget`] / [`widgets`] — the [`App`] event/layout/paint driver and the
30//!   widget set (buttons, text editing, windows, flex layout, menus, …).
31//! - [`draw_ctx`] — the [`DrawCtx`] drawing trait every widget paints
32//!   through; [`gfx_ctx`] is the software AGG implementation.
33//! - [`theme`] — dark / light / system visuals read via `ctx.visuals()`.
34//! - [`overlay_insets`] + [`widgets::ReserveInset`] + [`card`] — safe-area
35//!   overlay placement: reserved screen edges (the on-screen keyboard
36//!   reserves itself), and anchored info cards that measure, word-wrap,
37//!   flip, and clamp so floating content never hides under sibling chrome.
38//! - [`input_profile`] / [`ux_scale`] — touch-device detection and the
39//!   mobile UX zoom; [`widgets::on_screen_keyboard`] is the in-canvas
40//!   keyboard with keyboard-avoidance handled by [`App::layout`].
41//! - `winit_adapter` (feature `winit-adapter`) and, on WASM,
42//!   `web_adapter` (`install_keyboard_listeners` = typing + clipboard
43//!   for any browser shell) — platform glue. The repo's `demo-wgpu` crate
44//!   adds turn-key `native_shell` / `web_shell` runners on top.
45
46pub mod animation;
47pub mod app_state;
48pub mod card;
49pub mod clipboard;
50pub mod color;
51pub mod cursor;
52pub mod device_scale;
53pub mod draw_ctx;
54pub mod event;
55pub mod focus;
56pub mod font_settings;
57pub mod framebuffer;
58pub mod geometry;
59pub mod gfx_ctx;
60pub mod gl_renderer;
61pub mod input_profile;
62pub mod layout_props;
63pub mod lcd_coverage;
64pub mod lcd_gfx_ctx;
65pub mod overlay_insets;
66pub mod paints;
67pub mod persistence;
68pub mod pixel_bounds;
69pub mod platform;
70pub mod screenshot;
71pub mod snap;
72pub mod svg;
73pub mod text;
74pub mod theme;
75pub mod timestep;
76pub mod touch_state;
77pub mod undo;
78pub mod ux_scale;
79#[cfg(target_arch = "wasm32")]
80pub mod wasm_clipboard;
81pub mod widget;
82pub mod widgets;
83
84/// Adapter helpers bridging `winit` types (keyboard, mouse, modifiers,
85/// cursor) to this crate's input/cursor types.  Enabled with the
86/// `winit-adapter` feature so consumers that don't use winit don't pull
87/// the dep.
88#[cfg(feature = "winit-adapter")]
89pub mod winit_adapter;
90
91/// Adapter helpers for web/JS targets — DOM KeyboardEvent key-string →
92/// [`Key`] parser and CSS cursor-name for [`CursorIcon`].  Compiled only
93/// for `wasm32` targets.
94#[cfg(target_arch = "wasm32")]
95pub mod web_adapter;
96
97// Re-export the most commonly used types at the crate root.
98pub use app_state::{OsWindowHandle, OsWindowState};
99pub use color::Color;
100pub use cursor::{current_cursor_icon, reset_cursor_icon, set_cursor_icon, CursorIcon};
101pub use device_scale::{device_scale, set_device_scale};
102pub use draw_ctx::{DrawCtx, FillRule, GlPaint};
103pub use event::{Event, EventResult, Key, Modifiers, MouseButton};
104pub use font_settings::current_typography_epoch;
105pub use framebuffer::Framebuffer;
106pub use geometry::{Point, Rect, Size};
107pub use gfx_ctx::GfxCtx;
108pub use layout_props::{resolve_fit_or_stretch, HAnchor, Insets, VAnchor, WidgetBase};
109pub use platform::{current_platform, platform_from_name, set_platform, Platform};
110pub use screenshot::ScreenshotHandle;
111pub use snap::{
112    compute_snap, next_snap_id, ResizeEdge as SnapResizeEdge, SnapGuide, SnapId, SnapMode,
113    SnapOverlay, SnapResult, Snappable, DEFAULT_THRESHOLD as SNAP_DEFAULT_THRESHOLD,
114};
115pub use svg::{
116    compare_svg_rgba, parse_svg, render_svg, render_svg_at_size, render_svg_at_size_with_options,
117    render_svg_at_size_with_resources, render_svg_to_framebuffer,
118    render_svg_to_framebuffer_at_size, render_svg_to_framebuffer_at_size_with_options,
119    render_svg_to_framebuffer_at_size_with_resources, render_svg_to_framebuffer_with_options,
120    render_svg_to_lcd_buffer, render_svg_to_lcd_buffer_at_size,
121    render_svg_to_lcd_buffer_at_size_with_options, render_svg_to_lcd_buffer_at_size_with_resources,
122    render_svg_to_lcd_buffer_with_options, render_svg_tree, render_svg_tree_at_size,
123    render_svg_tree_region_at_size, render_svg_tree_region_to_framebuffer_at_size,
124    render_svg_tree_to_framebuffer, render_svg_tree_to_framebuffer_at_size,
125    render_svg_tree_to_lcd_buffer, render_svg_tree_to_lcd_buffer_at_size, render_svg_with_options,
126    set_default_svg_parse_options, svg_fontdb_from_font_data, SvgCompareResult,
127    SvgCompareThresholds, SvgParseOptions, SvgRenderError, SvgTree, DEFAULT_ALPHA_TOLERANCE,
128    DEFAULT_MISMATCH_RATIO, DEFAULT_OPAQUE_RGB_TOLERANCE, DEFAULT_TRANSLUCENT_RGB_TOLERANCE,
129    DEFAULT_VISUAL_RGB_TOLERANCE,
130};
131pub use text::{measure_text_metrics, Font, TextMetrics};
132pub use theme::{
133    current_visuals, current_visuals_epoch, set_visuals, AccentColor, ThemePreference, Visuals,
134};
135pub use timestep::{FixedTimestep, StepBatch, FIXED_DT, MAX_STEPS_PER_DRAW, SIMULATION_HZ};
136pub use touch_state::{current_multi_touch, MultiTouchInfo, TouchDeviceId, TouchId, TouchPhase};
137pub use undo::{DoUndoActions, UndoBuffer, UndoRedoCommand};
138#[cfg(feature = "reflect")]
139pub use widget::{apply_inspector_edit, reflect_fields, InspectorEdit};
140pub use widget::{
141    apply_widget_base_edit, collect_inspector_nodes, current_mouse_world, current_viewport,
142    find_widget_by_id, find_widget_by_id_mut, find_widget_by_type, App, BackbufferKind,
143    BackbufferSpec, BackbufferState, InspectorNode, InspectorOverlay, Widget, WidgetBaseEdit,
144    WidgetBaseField,
145};
146pub use widgets::{
147    color_wheel_picker_dialog, current_scroll_style, current_scroll_visibility, paint_sparkline,
148    set_scroll_style, set_scroll_visibility, shared_frame_history, shared_run_mode, Button,
149    CellInfo, Checkbox, CollapsingHeader, ColorPicker, ColorWheelPicker, ComboBox, Conditional,
150    Container, DragValue, FlexColumn, FlexRow, FrameHistory, HeaderInfo, Hyperlink, ImageView,
151    InspectorPanel, InspectorSavedState, Label, LabelAlign, MarkdownView, MenuBar, MenuBarStrip,
152    MenuEntry, MenuItem, MenuResponse, MenuSelection, MenuShortcut, ModalSheet, NodeIcon, Padding,
153    PerformanceView, PopupMenu, ProgressBar, QrView, RadioGroup, Rebuilder, Resize, RunMode,
154    RunModeDesc, RunModeRow, ScrollBarColor, ScrollBarKind, ScrollBarStyle, ScrollBarVisibility,
155    ScrollView, Separator, SharedFrameHistory, ShortcutKey, SizedBox, Slider, Spacer, Splitter,
156    Stack, TabView, Table, TableBuilder, TableColumn, TableRows, TextArea, TextField, ToggleSwitch,
157    Tooltip, TopMenu, TreeView, Window,
158};
159
160// Re-export AGG types so callers don't need to import agg-rust directly.
161pub use agg_rust::comp_op::CompOp;
162pub use agg_rust::math_stroke::{LineCap, LineJoin};
163pub use agg_rust::trans_affine::TransAffine;
164
165#[cfg(test)]
166mod tests;