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 `agg-gui-shell` (native)
44//!   and `agg-gui-web-shell` (browser) crates add turn-key runners on top.
45
46pub mod animation;
47pub mod app_state;
48pub mod card;
49pub mod clipboard;
50pub mod color;
51pub mod confetti;
52pub mod cursor;
53pub mod device_scale;
54pub mod draw_cell;
55pub mod draw_ctx;
56pub mod event;
57pub mod focus;
58pub mod font_settings;
59pub mod framebuffer;
60pub mod fullscreen;
61pub mod gamepad;
62pub mod geometry;
63pub mod gfx_ctx;
64pub mod gl_renderer;
65pub mod input_profile;
66pub mod layout_props;
67pub mod lcd_coverage;
68pub mod lcd_gfx_ctx;
69pub mod overlay_insets;
70pub mod paints;
71pub mod persistence;
72pub mod pixel_bounds;
73pub mod platform;
74pub mod screenshot;
75pub mod snap;
76pub mod svg;
77pub mod text;
78pub mod theme;
79pub mod tilt;
80pub mod timestep;
81pub mod touch_emulation;
82pub mod touch_points;
83pub mod touch_state;
84pub mod undo;
85pub mod ux_scale;
86pub mod vector_icon;
87#[cfg(target_arch = "wasm32")]
88pub mod wasm_clipboard;
89/// Wheel-delta normalization for shells: OS / DOM scroll deltas → the
90/// *notch* count `Event::MouseWheel` carries.
91pub mod wheel;
92pub mod widget;
93pub mod widgets;
94
95/// Adapter helpers bridging `winit` types (keyboard, mouse, modifiers,
96/// cursor) to this crate's input/cursor types.  Enabled with the
97/// `winit-adapter` feature so consumers that don't use winit don't pull
98/// the dep.
99#[cfg(feature = "winit-adapter")]
100pub mod winit_adapter;
101
102/// Adapter helpers for web/JS targets — DOM KeyboardEvent key-string →
103/// [`Key`] parser and CSS cursor-name for [`CursorIcon`].  Compiled only
104/// for `wasm32` targets.
105#[cfg(target_arch = "wasm32")]
106pub mod web_adapter;
107
108// Re-export the most commonly used types at the crate root.
109pub use app_state::{OsWindowHandle, OsWindowState};
110pub use color::Color;
111pub use cursor::{current_cursor_icon, reset_cursor_icon, set_cursor_icon, CursorIcon};
112pub use device_scale::{device_scale, set_device_scale};
113pub use draw_cell::{DrawCell, DrawRefCell, DrawRefMut};
114pub use draw_ctx::{DrawCtx, FillRule, GlPaint};
115pub use event::{Event, EventResult, Key, Modifiers, MouseButton};
116pub use font_settings::current_typography_epoch;
117pub use framebuffer::Framebuffer;
118pub use geometry::{Point, Rect, Size};
119pub use gfx_ctx::GfxCtx;
120pub use layout_props::{resolve_fit_or_stretch, HAnchor, Insets, VAnchor, WidgetBase};
121pub use platform::{current_platform, platform_from_name, set_platform, Platform};
122pub use screenshot::ScreenshotHandle;
123pub use snap::{
124    compute_snap, next_snap_id, ResizeEdge as SnapResizeEdge, SnapGuide, SnapId, SnapMode,
125    SnapOverlay, SnapResult, Snappable, DEFAULT_THRESHOLD as SNAP_DEFAULT_THRESHOLD,
126};
127pub use svg::{
128    compare_svg_rgba, parse_svg, render_svg, render_svg_at_size, render_svg_at_size_with_options,
129    render_svg_at_size_with_resources, render_svg_to_framebuffer,
130    render_svg_to_framebuffer_at_size, render_svg_to_framebuffer_at_size_with_options,
131    render_svg_to_framebuffer_at_size_with_resources, render_svg_to_framebuffer_with_options,
132    render_svg_to_lcd_buffer, render_svg_to_lcd_buffer_at_size,
133    render_svg_to_lcd_buffer_at_size_with_options, render_svg_to_lcd_buffer_at_size_with_resources,
134    render_svg_to_lcd_buffer_with_options, render_svg_tree, render_svg_tree_at_size,
135    render_svg_tree_region_at_size, render_svg_tree_region_to_framebuffer_at_size,
136    render_svg_tree_to_framebuffer, render_svg_tree_to_framebuffer_at_size,
137    render_svg_tree_to_lcd_buffer, render_svg_tree_to_lcd_buffer_at_size, render_svg_with_options,
138    set_default_svg_parse_options, svg_fontdb_from_font_data, SvgCompareResult,
139    SvgCompareThresholds, SvgParseOptions, SvgRenderError, SvgTree, DEFAULT_ALPHA_TOLERANCE,
140    DEFAULT_MISMATCH_RATIO, DEFAULT_OPAQUE_RGB_TOLERANCE, DEFAULT_TRANSLUCENT_RGB_TOLERANCE,
141    DEFAULT_VISUAL_RGB_TOLERANCE,
142};
143pub use text::{measure_text_metrics, Font, TextMetrics};
144pub use theme::{
145    current_visuals, current_visuals_epoch, set_visuals, AccentColor, ThemePreference, Visuals,
146};
147pub use timestep::{FixedTimestep, StepBatch, FIXED_DT, MAX_STEPS_PER_DRAW, SIMULATION_HZ};
148pub use touch_emulation::{EmuCmd, TouchMouseEmu, TOUCH_SCROLL_THRESHOLD};
149pub use touch_state::{current_multi_touch, MultiTouchInfo, TouchDeviceId, TouchId, TouchPhase};
150pub use undo::{DoUndoActions, Settings as UndoerSettings, UndoBuffer, UndoRedoCommand, Undoer};
151#[cfg(feature = "reflect")]
152pub use widget::{apply_inspector_edit, reflect_fields, InspectorEdit};
153pub use widget::{
154    apply_widget_base_edit, collect_inspector_nodes, current_mouse_world, current_viewport,
155    debug_draw_report, find_widget_by_id, find_widget_by_id_mut, find_widget_by_type,
156    find_widget_screen_rect, App, BackbufferKind, BackbufferSpec, BackbufferState, InspectorNode,
157    InspectorOverlay, Widget, WidgetBaseEdit, WidgetBaseField,
158};
159pub use widgets::{
160    color_wheel_picker_dialog, color_wheel_picker_dialog_with_on_close, current_scroll_style,
161    current_scroll_visibility, paint_sparkline, set_scroll_style, set_scroll_visibility,
162    set_tooltip_timings, shared_frame_history, shared_run_mode, single_font_resolver,
163    tooltip_timings, Align, Align2, Button, CellInfo, Checkbox, ClickAwayAction, CloseReason,
164    CollapsingHeader, ColorPicker, ColorWheelPicker, ComboBox, Conditional, Container, DragValue,
165    FlexColumn, FlexRow, FrameHistory, HandleShape, HeaderInfo, Hyperlink, ImageView,
166    InspectorPanel, InspectorSavedState, Label, LabelAlign, MarkdownView, MenuBar, MenuBarStrip,
167    MenuEntry, MenuItem, MenuResponse, MenuSelection, MenuShortcut, ModalSheet, NodeIcon, Padding,
168    PerformanceView, Popup, PopupClickOutcome, PopupCloseBehavior, PopupMenu, ProgressBar, QrView,
169    RadioGroup, Rebuilder, RectAlign, Resize, RichCommand, RichDoc, RichEditHandle, RichTextEdit,
170    RichTextToolbar, RichTextView, RunMode, RunModeDesc, RunModeRow, Scene, SceneTransform,
171    ScrollBarColor, ScrollBarKind, ScrollBarStyle, ScrollBarVisibility, ScrollView,
172    SegmentedControl, Separator, SharedFrameHistory, SharedResolver, ShortcutKey, SizedBox, Slider,
173    SliderClamping, SliderOrientation, Spacer, Spinner, SpinnerSize, Splitter, SplitterRatio,
174    Stack, TabView, Table, TableBuilder, TableColumn, TableRows, TextArea, TextAreaScrollInfo,
175    TextEditState, TextField, TextHAlign, TextVAlign, ToggleSwitch, Tooltip, TooltipTimings,
176    TopMenu, TreeView, Window, DEFAULT_COLUMN_GAP, DEFAULT_ROW_GAP,
177};
178
179// Re-export AGG types so callers don't need to import agg-rust directly.
180pub use agg_rust::comp_op::CompOp;
181pub use agg_rust::math_stroke::{LineCap, LineJoin};
182pub use agg_rust::trans_affine::TransAffine;
183
184#[cfg(test)]
185mod tests;