Crate druid

Simple data-oriented GUI.

Druid lets you build simple interactive graphical applications that can be deployed on Windows, macOS, Linux, OpenBSD, FreeBSD and the web.

Druid is built on top of druid-shell, which implements all of the lower-level, platform-specific code, providing a common abstraction for things like key and mouse events, creating windows, and launching an application. Below druid-shell is piet, which is a cross-platform 2D graphics library, providing a simple and familiar drawing API that can be implemented for various platforms.

Druid is a data-driven, declarative framework. You describe your application model in terms of the Data trait, and then you build up a tree of widget s that can display and modify your data.

Your widgets handle Events, such as mouse movement, and can modify the data; these changes are then delivered to relevant widgets, which can update their state and redraw.

As your application grows, you can use Lenses to expose only certain subsets of your data model to certain subsets of your widget tree.

For more information you should read the Druid book.

Examples

For many more examples, see druid/examples.

use druid::widget::{Align, Flex, Label, TextBox};
use druid::{AppLauncher, Data, Env, Lens, LocalizedString, Widget, WindowDesc, WidgetExt};

const VERTICAL_WIDGET_SPACING: f64 = 20.0;
const TEXT_BOX_WIDTH: f64 = 200.0;
const WINDOW_TITLE: LocalizedString<HelloState> = LocalizedString::new("Hello World!");

#[derive(Clone, Data, Lens)]
struct HelloState {
    name: String,
}

fn main() {
    // describe the main window
    let main_window = WindowDesc::new(build_root_widget())
        .title(WINDOW_TITLE)
        .window_size((400.0, 400.0));

    // create the initial app state
    let initial_state = HelloState {
        name: "World".into(),
    };

    // start the application
    AppLauncher::with_window(main_window)
        .launch(initial_state)
        .expect("Failed to launch application");
}

fn build_root_widget() -> impl Widget<HelloState> {
    // a label that will determine its text based on the current app data.
    let label = Label::new(|data: &HelloState, _env: &Env| format!("Hello {}!", data.name));
    // a textbox that modifies `name`.
    let textbox = TextBox::new()
        .with_placeholder("Who are we greeting?")
        .fix_width(TEXT_BOX_WIDTH)
        .lens(HelloState::name);

    // arrange the two widgets vertically, with some padding
    let layout = Flex::column()
        .with_child(label)
        .with_spacer(VERTICAL_WIDGET_SPACING)
        .with_child(textbox);

    // center the two widgets in the available space
    Align::centered(layout)
}

Optional Features

Utility features:

• im - Efficient immutable data structures using the im crate, which is made available via the im module.
• svg - Scalable Vector Graphics for icons and other scalable images using the usvg crate.
• image - Bitmap image support using the image crate.
• x11 - Work-in-progress X11 backend instead of GTK.
• wayland - Work-in-progress Wayland backend, very experimental.
• serde - Serde support for some internal types (most Kurbo primitives).

Image format features:

• png
• jpeg
• jpeg_rayon
• gif
• bmp
• ico
• tiff
• webp
• pnm
• dds
• tga
• farbfeld
• dxt
• hdr

You can enable all these formats with image-all.

Features can be added with cargo. For example, in your Cargo.toml:

[dependencies.druid]
version = "0.8.3"
features = ["im", "svg", "image"]

Note for Windows apps

By default, Windows will open a console with your application’s window. If you don’t want the console to be shown, use #![windows_subsystem = "windows"] at the beginning of your crate.

Re-exports

• pub use shell::image;
• pub use shell::keyboard_types;

Modules

• commands
  Commands with special meaning, defined by Druid.
• debug_state
  A data structure for representing widget trees.
• env
  An environment which is passed downward into the widget tree.
• im
  Immutable Data Structures for Rust
• kurbo
  2D geometry, with a focus on curves.
• lens
  Implementations of Lens, a way of focusing on subfields of data.
• menu
  Window, application, and context menus
• piet
  A piet backend appropriate for the current platform.
• platform_menus
  Pre-configured, platform appropriate menus and menu items.
• scroll_component
  A component for embedding in another widget to provide consistent and extendable scrolling behavior
• tests
  Additional unit tests that cross file or module boundaries.
• text
  Editing and displaying text.
• theme
  Theme keys and initial values.
• widget
  Common widgets.

Macros

• lens
  Construct a lens accessing a type’s field
• widget_wrapper_body
  A macro to help implementation of WidgetWrapper for a direct wrapper. Use it in the body of the impl.
• widget_wrapper_pod_body
  A macro to help implementation of WidgetWrapper for a wrapper of a typed pod. Use it in the body of the impl.

Structs

• Affine
  A 2D affine transform.
• AppLauncher
  Handles initial setup of an application, and starts the runloop.
• Application
  The top level application object.
• BoxConstraints
  Constraints for layout.
• Clipboard
  A handle to the system clipboard.
• ClipboardFormat
  Data coupled with a type identifier.
• Command
  An arbitrary command.
• CursorDesc
  A platform-independent description of a custom cursor.
• DelegateCtx
  A context passed in to AppDelegate functions.
• DruidHandler
  The struct implements the druid-shell WinHandler trait.
• Env
  An environment passed down through all widget traversals.
• EventCtx
  A mutable context provided to event handling methods of widgets.
• ExtEventError
  An error that occurs if an external event cannot be submitted. This probably means that the application has gone away.
• ExtEventSink
  A thing that can move into other threads and be used to submit commands back to the running application.
• FileDialogOptions
  Options for file dialogs.
• FileInfo
  Information about the path to be opened or saved.
• FileSpec
  A description of a filetype, for specifying allowed types in a file dialog.
• HotKey
  A description of a keyboard shortcut.
• ImageBuf
  An in-memory pixel buffer.
• Insets
  Insets from the edges of a rectangle.
• Key
  A typed Env key.
• KeyEvent
  Information about a keyboard event.
• LayoutCtx
  A context provided to layout-handling methods of widgets.
• LifeCycleCtx
  A mutable context provided to the lifecycle method on widgets.
• LinearGradient
  A description of a linear gradient in the unit rect, which can be resolved to a fixed gradient.
• LocalizedString
  A string that can be localized based on the current locale.
• Menu
  A menu.
• MenuItem
  An item in a menu.
• Modifiers
  The modifiers.
• Monitor
  Monitor struct containing data about a monitor on the system
• MouseButtons
  A set of MouseButtons.
• MouseEvent
  The state of the mouse for a click, mouse-up, move, or wheel event.
• Notification
  A message passed up the tree from a Widget to its ancestors.
• PaintCtx
  A context passed to paint methods of widgets.
• Point
  A 2D point.
• RadialGradient
  A description of a radial gradient in the unit rect, which can be resolved to a fixed gradient.
• Rect
  A rectangle.
• Region
  A union of rectangles, useful for describing an area that needs to be repainted.
• RoundedRectRadii
  Radii for each corner of a rounded rectangle.
• Scale
  Coordinate scaling between pixels and display points.
• ScaledArea
  A specific area scaling state.
• Screen
  Information about the screen and monitors
• Selector
  An identifier for a particular command.
• SingleUse
  A wrapper type for Command payloads that should only be used once.
• Size
  A 2D size.
• TimerToken
  A token that uniquely identifies a running timer.
• UnitPoint
  A representation of a point relative to a unit rectangle.
• UpdateCtx
  A mutable context provided to data update methods of widgets.
• ValueTypeError
  The error type for environment access.
• Vec2
  A 2D vector.
• ViewContext
  Information about the widget’s surroundings.
• WidgetId
  A unique identifier for a single Widget.
• WidgetPod
  A container for one widget in the hierarchy.
• WidgetState
  Generic state for all widgets in the hierarchy.
• Window
  Per-window state not owned by user code.
• WindowConfig
  Window configuration that can be applied to a WindowBuilder, or to an existing WindowHandle. It does not include anything related to app data.
• WindowDesc
  A description of a window to be instantiated.
• WindowHandle
  A handle to a platform window object.
• WindowId
  A unique identifier for a window.

Enums

• Code
  Code is the physical position of a key.
• Color
  A datatype representing color.
• Cursor
  Mouse cursors.
• Event
  An event, propagated downwards during event flow.
• Handled
  An enum for specifying whether an event was handled.
• InternalEvent
  Internal events used by Druid inside WidgetPod.
• InternalLifeCycle
  Internal lifecycle events used by Druid inside WidgetPod.
• KeyOrValue
  Either a concrete T or a Key<T> that can be resolved in the Env.
• LifeCycle
  Application life cycle events.
• Location
  The location attribute contains an indication of the logical location of the key on the device.
• MouseButton
  An indicator of which mouse button was pressed.
• PlatformError
  Shell errors.
• RawMods
  A representation of the active modifier keys.
• RawWindowHandle
  An enum to simply combine the different possible raw window handle variants.
• SysMods
  A platform-agnostic representation of keyboard modifiers, for command handling.
• Target
  The target of a Command.
• Value
  A dynamic type representing all values that can be stored in an environment.
• WindowLevel
  Levels in the window system - Z order for display purposes. Describes the purpose of a window and should be mapped appropriately to match platform conventions.
• WindowSizePolicy
  Defines how a windows size should be determined
• WindowState
  Contains the different states a Window can be in.

Traits

• AppDelegate
  A type that provides hooks for handling and modifying top-level events.
• Data
  A trait used to represent value types.
• HasRawWindowHandle
  Window that wraps around a raw window handle.
• Lens
  A lens is a datatype that gives access to a part of a larger data structure.
• LensExt
  Helpers for manipulating Lenses
• RenderContext
  The main trait for rendering graphics.
• Scalable
  The Scalable trait describes how coordinates should be translated from display points into pixels and vice versa using a Scale.
• ValueType
  Values which can be stored in an environment.
• Widget
  The trait implemented by all widgets.
• WidgetExt
  A trait that provides extra methods for combining Widgets.

Type Definitions

• FormatId
  A type identifier for the system clipboard.
• KbKey
  The meaning (mapped value) of a keypress.

Derive Macros

• Data
  Generates implementations of the Data trait.
• Lens
  Generates lenses to access the fields of a struct.