[][src]Crate fltk

fltk-rs

Documentation Crates.io License Build

Rust bindings for the FLTK Graphical User Interface library.

The FLTK crate is a crossplatform lightweight gui library which can be statically linked to produce small, self-contained (no dependencies) and fast gui applications.

Here is a list of software using FLTK.

  • Link to the official FLTK repository.
  • Link to the official documentation.

Usage

Just add the following to your project's Cargo.toml file:

[dependencies]
fltk = "^0.8"

The library offers prebuilt static cfltk and fltk libraries, which can be added using the "fltk-bundled" flag:

[dependencies]
fltk = { version = "^0.8", features = ["fltk-bundled"] }

Since these are pre-built libraries using the Github actions CI, the currently supported operating systems are:

  • Windows 10 x64 (msvc and gnu).
  • MacOS 10.15 x64.
  • Ubuntu 18.04 or later, x64. The library is automatically statically linked to your binary. If however you would prefer dynamic linking, you can use the fltk-shared feature:
[dependencies.fltk]
version = "^0.8"
features = ["fltk-shared"]
# or
[dependencies]
fltk = { version = "^0.8", features = ["fltk-shared"] }

You can also enable ninja builds for a faster build of the C++ source using the "use-ninja" feature. Or if you have fltk already installed, you can use the fltk-system feature.

To use the master branch in your project, you can use:

[dependencies]
fltk = { git = "https://github.com/MoAlyousef/fltk-rs" }

An example hello world application:

    use fltk::{app::*, window::*};

    let app = App::default();
    let mut wind = Window::new(100, 100, 400, 300, "Hello from rust");
    wind.end();
    wind.show();
    app.run().unwrap();

Another example showing the basic callback functionality:

    use fltk::{app::*, button::*, frame::*, window::*};

    let app = App::default();
    let mut wind = Window::new(100, 100, 400, 300, "Hello from rust");
    let mut frame = Frame::new(0, 0, 400, 200, "");
    let mut but = Button::new(160, 210, 80, 40, "Click me!");
    wind.end();
    wind.show();
    but.set_callback(Box::new(move || frame.set_label("Hello World!")));
    app.run().unwrap();

Please check the examples directory for more examples. You will notice that all widgets are instantiated with a new() method, taking the x and y coordinates, the width and height of the widget, as well as a label which can be left blank if needed. Another way to initialize a widget is using the builder pattern: (The following buttons are equivalent)

let but1 = Button::new(10, 10, 80, 40, "Button 1");

let but2 = Button::default()
    .with_pos(10, 10)
    .with_size(80, 40)
    .with_label("Button 2");

An example of a counter showing use of the builder pattern:

    let app = app::App::default();
    let mut wind = Window::default()
        .with_size(160, 200)
        .center_screen()
        .with_label("Counter");
    let mut frame = Frame::default()
        .with_size(100, 40)
        .center_of(&wind)
        .with_label("0");
    let mut but_inc = Button::default()
        .size_of(&frame)
        .above_of(&frame, 0)
        .with_label("+");
    let mut but_dec = Button::default()
        .size_of(&frame)
        .below_of(&frame, 0)
        .with_label("-");
    wind.make_resizable(true);
    wind.end();
    wind.show();
    /* Event handling */

Events

Events can be handled using the set_callback method (as above) or the available fltk::app::set_callback() free function, which will handle the default trigger of each widget(like clicks for buttons):

    /* previous hello world code */
    but.set_callback(Box::new(move || frame.set_label("Hello World!")));
    app.run().unwrap();

Another way is to use message passing:

    /* previous counter code */
    let (s, r) = app::channel::<Message>();

    but_inc.emit(s, Message::Increment);
    but_dec.emit(s, Message::Decrement);

    while app.wait().unwrap() {
        let label: i32 = frame.label().parse().unwrap();
        match r.recv() {
            Some(Message::Increment) => frame.set_label(&(label + 1).to_string()),
            Some(Message::Decrement) => frame.set_label(&(label - 1).to_string()),
            None => (),
        }
    }

For the remainder of the code, check the full example here: https://github.com/MoAlyousef/fltk-rs/blob/master/examples/counter2.rs

For custom event handling, the handle() method can be used:

    some_widget.handle(Box::new(move |ev: Event| {
        match ev {
            /* handle ev */
        }
    }));

Handled or ignored events using the handle method should return true, unhandled events should return false. More examples are available in the examples directory.

Theming

FLTK offers 4 application themes (called schemes):

  • Base
  • Gtk
  • Gleam
  • Plastic

These can be set using the App::with_scheme() function.

let app = App::default().with_scheme(AppScheme::Gleam);

Themes of individual widgets can be optionally modified using the provided methods in the WidgetExt trait, such as set_color(), set_label_font(), set_frame() etc:

    some_button.set_color(Color::Light1); //! You can use one of the provided colors in the fltk enums
    some_button.set_color(Color::from_rgb(255, 0, 0)); //! Or you can specify a color by rgb or hex/u32 value
    some_button.set_color(Color::from_u32(0xffebee));
    some_button.set_frame(FrameType::RoundUpBox);
    some_button.set_font(Font::TimesItalic);

Features

The following are the features offered by the crate:

  • fltk-shared: Builds a shared lib of fltk
  • use-ninja: If you have ninja build installed, it builds faster than make or VS
  • system-fltk: If you would like to use the installed fltk library, should be FLTK 1.4
  • system-libpng: Uses the system libpng
  • system-libjpeg: Uses the system libjpeg
  • system-zlib: Uses the system zlib
  • legacy-opengl: Support of Lagacy OpenGL, the crate uses GLVND by default
  • fltk-bundled: Support for bundled versions of cfltk and fltk on selected platforms
  • enable-glwindow: Support for systems without OpenGL.

FAQ

please check the FAQ page for frequently asked questions, encountered issues, guides on deployment, and contribution.

Re-exports

pub use enums::*;
pub use prelude::*;

Modules

app
browser
button
dialog
draw
enums
frame
group
image
input
menu
misc
output
prelude
table
text
tree
valuator
widget
window