fltk-rs
Rust bindings for the FLTK Graphical User Interface library.
The fltk crate is a cross-platform lightweight gui library which can be statically linked to produce small, self-contained and fast gui applications.
Resources:
- Book
- Documentation
- Videos
- Discussions
- Examples
- Demos
- 7guis-fltk-rs
- FLTK-RS-Examples
- Erco's FLTK cheat page, which is an excellent FLTK C++ reference.
Why choose FLTK?
- Lightweight. Small binary, around 1mb after stripping. Small memory footprint.
- Speed. Fast to install, fast to build, fast at startup and fast at runtime.
- Single executable. No DLLs to deploy.
- Supports old architectures.
- FLTK's permissive license which allows static linking for closed-source applications.
- Themeability (4 supported schemes: Base, GTK, Plastic and Gleam), and additional theming using fltk-theme.
- Provides around 80 customizable widgets.
- Has inbuilt image support.
Here is a list of software using FLTK. For software using fltk-rs, check here.
Usage
Just add the following to your project's Cargo.toml file:
[]
= "^1.2"
To use the latest changes in the repo:
[]
= { = "^1.2", = "https://github.com/fltk-rs/fltk-rs" }
To use the bundled libs (available for x64 windows (msvc & gnu (msys2-mingw)), x64 linux & macos):
[]
= { = "^1.2", = ["fltk-bundled"] }
The library is automatically built and statically linked to your binary.
An example hello world application:
use ;
Another example showing the basic callback functionality:
use ;
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)
use ;
let but1 = new;
let but2 = default
.with_pos
.with_size
.with_label;
An example of a counter showing use of the builder pattern:
use ;
Alternatively, you can use packs, columns, rows to layout your widgets (or the fltk-flex crate for flexbox layouts):
use ;
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;
another_but.set_callback;
app.run.unwrap;
Another way is to use message passing:
/* previous counter code */
let = ;
but_inc.emit;
but_dec.emit;
while app.wait
For the remainder of the code, check the full example here.
For custom event handling, the handle() method can be used:
some_widget.handle;
Handled or ignored events using the handle method should return true, unhandled events should return false. More examples are available in the fltk/examples directory.
For an alternative event handling mechanism using on_<event>
methods, check the fltk-evented crate.
Theming
FLTK offers 4 application schemes:
- Base
- Gtk
- Gleam
- Plastic
(Additional theming can be found in the fltk-theme crate)
These can be set using the App::with_scheme()
method.
let app = default.with_scheme;
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; // You can use one of the provided colors in the fltk enums
some_button.set_color; // Or you can specify a color by rgb or hex/u32 value
some_button.set_color;
some_button.set_frame;
some_button.set_font;
For default application colors, fltk-rs provides app::background()
, app::background2()
and app::foreground()
. You can also specify the default application selection/inactive colors, font, label size, frame type, scrollbar size, menu line-spacing. Additionally the fltk-theme crate offers some other predefined color maps (dark theme, tan etc) and widget themes which can be loaded into your application.
Dependencies
Rust (version > 1.45), CMake (version > 3.11), Git and a C++11 compiler need to be installed and in your PATH for a cross-platform build from source. Ninja is recommended, but not required. This crate also offers a bundled form of fltk on selected x86_64 platforms (Windows (msvc and gnu), MacOS, Linux), this can be enabled using the fltk-bundled feature flag as mentioned in the usage section (this requires curl and tar to download and unpack the bundled libraries).
- Windows:
- MSVC: Windows SDK
- Gnu: No dependencies
- MacOS: No dependencies.
- Linux/BSD: X11 and OpenGL development headers need to be installed for development. The libraries themselves are normally available on linux/bsd distros with a graphical user interface.
For Debian-based GUI distributions, that means running:
$ sudo apt-get install libx11-dev libxext-dev libxft-dev libxinerama-dev libxcursor-dev libxrender-dev libxfixes-dev libpango1.0-dev libgl1-mesa-dev libglu1-mesa-dev
For RHEL-based GUI distributions, that means running:
$ sudo yum groupinstall "X Software Development" && yum install pango-devel libXinerama-devel
For Arch-based GUI distributions, that means running:
$ sudo pacman -S libx11 libxext libxft libxinerama libxcursor libxrender libxfixes pango cairo libgl mesa --needed
For Alpine linux:
$ apk add pango-dev fontconfig-dev libxinerama-dev libxfixes-dev libxcursor-dev mesa-gl
For NixOS (Linux distribution) this nix-shell
environment can be used:
$ nix-shell --packages rustc cmake git gcc xorg.libXext xorg.libXft xorg.libXinerama xorg.libXcursor xorg.libXrender xorg.libXfixes libcerf pango cairo libGL mesa pkg-config
Features
The following are the features offered by the crate:
- use-ninja: Uses the ninja build system if available for a faster build, especially on Windows.
- no-pango: Build without pango support on Linux/BSD, if rtl/cjk font support is not needed.
- fltk-bundled: Support for bundled versions of cfltk and fltk on selected platforms (requires curl and tar)
- enable-glwindow: Support for drawing using OpenGL functions.
- system-libpng: Uses the system libpng
- system-libjpeg: Uses the system libjpeg
- system-zlib: Uses the system zlib
FAQ
please check the FAQ page for frequently asked questions, encountered issues, guides on deployment, and contribution.
Building
To build, just run:
$ git clone https://github.com/fltk-rs/fltk-rs
$ cd fltk-rs
$ cargo build
Examples
To run the examples:
$ cargo run --example editor
$ cargo run --example calculator
$ cargo run --example calculator2
$ cargo run --example terminal
$ cargo run --example counter
$ cargo run --example hello
$ cargo run --example hello_button
$ cargo run --example fb
$ cargo run --example pong
$ cargo run --example custom_widgets
$ cargo run --example custom_dial
...
Using custom theming and also FLTK provided default schemes like Gtk:
Different frame types which can be used with many different widgets such as Frame, Button widgets, In/Output widgets...etc.
More interesting examples can be found in the fltk-rs-demos repo. Also a nice implementation of the 7guis tasks can be found here. Various advanced examples can also be found here.
Currently implemented types:
Image types:
- SharedImage
- BmpImage
- JpegImage
- GifImage
- PngImage
- SvgImage
- Pixmap
- RgbImage
- XpmImage
- XbmImage
- PnmImage
- TiledImage
Widgets:
- Buttons
- Button
- RadioButton
- ToggleButton
- RoundButton
- CheckButton
- LightButton
- RepeatButton
- RadioLightButton
- RadioRoundButton
- Dialogs
- Native FileDialog
- FileChooser
- HelpDialog
- Message dialog
- Alert dialog
- Password dialog
- Choice dialog
- Input dialog
- ColorChooser dialog
- Frame (Fl_Box)
- Windows
- Window
- SingleWindow (single buffered)
- DoubleWindow (double buffered)
- MenuWindow
- OverlayWindow
- GlWindow (requires the "enable-glwindow" flag)
- GlutWindow (requires the "enable-glwindow" flag)
- Groups
- Group
- Pack (Horizontal and Vertical)
- Tabs
- Scroll
- Tile
- Wizard
- ColorChooser
- VGrid
- HGrid
- Column (vertical pack supporting auto layout)
- Row (horizontal pack supporting auto layout)
- Flex
- Text display widgets
- TextDisplay
- TextEditor
- SimpleTerminal
- Input widgets
- Input
- IntInput
- FloatInput
- MultilineInput
- SecretInput
- FileInput
- Output widgets
- Output
- MultilineOutput
- Menu widgets
- MenuBar
- MenuItem
- Choice (dropdown list)
- SysMenuBar (MacOS menu bar which appears at the top of the screen)
- Valuator widgets
- Slider
- NiceSlider
- ValueSlider
- Dial
- LineDial
- Counter
- Scrollbar
- Roller
- Adjuster
- ValueInput
- ValueOutput
- FillSlider
- FillDial
- HorSlider (Horizontal slider)
- HorFillSlider
- HorNiceSlider
- HorValueSlider
- Browsing widgets
- Browser
- SelectBrowser
- HoldBrowser
- MultiBrowser
- FileBrowser
- CheckBrowser
- Miscelaneous widgets
- Spinner
- Clock (Round and Square)
- Chart (several chart types are available)
- Progress (progress bar)
- Tooltip
- InputChoice
- HelpView
- Table widgets
- Table
- TableRow
- SmartTable (via the fltk-table crate)
- Trees
- Tree
- TreeItem
Drawing primitives
(In the draw module)
Surface types:
- Printer.
- ImageSurface.
- SvgFileSurface.
Tutorials
- Basics
- New basics (Uses fltk post 1.0)
- User input
- Client-side web todo app
- Create a media player using the vlc crate
- Custom dialogs
- Add drag and drop to the editor example
- Drawing things with fltk
- Working with images
- Audio player with custom widgets
- Use FLUID (RAD tool) with Rust
- multiple windows and embedding windows
- FLTK Rust tutorial: Improve FLTK's toggle button appearance!
- FLTK Rust: Customizing your app and widgets
- FLTK Rust: fltk-table, a boilerplate-less table creating crate
- FLTK Rust: intro into the fltk-evented crate
More videos in the playlist here. Some of the demo projects can be found here.