An easy-to-use, 2D GUI library written entirely in Rust.

PistonDevelopers

Last update: Jan 1, 2023

Related tags

Overview

Conrod

An easy-to-use, 2D GUI library written entirely in Rust.

Guide

What is Conrod?
Getting Started
- Installing Rust and Cargo
- Running the Conrod Examples
Hello World
Using and Customising Themes
- What is a Theme?
- Custom Themes
- Serializing Themes
Designing Custom Widgets (using the Widget trait)
- The Widget trait
- The widget_style! macro
- The builder_methods! macro
- Making a Button widget
Custom Graphics and Window Backends
- Demonstration of Backend Implementation (using glium and glutin)
Internals
- The Ui's Widget Graph
- Ui::set_widgets - How does it work?
FAQ

The Guide is a work-in-progress. If a section is not linked, it is likely not yet implemented.

Crates

Crate	Badges	Description
`conrod_core`		The fundamentals for any conrod project.
`conrod_derive`		Provides the `WidgetCommon` and `WidgetStyle` derive macros.
`conrod_winit`		Simplifies using `conrod_core` with `winit`
`conrod_gfx`		Simplifies using `conrod_core` with the gfx ecosystem
`conrod_glium`		Simplifies using `conrod_core` with `glium`
`conrod_piston`		Simplifies using `conrod_core` with `piston`
`conrod_vulkano`		Simplifies using `conrod_core` with `vulkano`

Current State

We're just starting to reach a stable-ish API pattern! There will still be some large changes, however these are more likely to be new features than API overhauls.

To get a clearer idea of where we're at see the issues and in particular, the 1.0.0 milestone.

Contributing

Want to help out? See Piston's how to contribute guide.

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Example Assets

Google Noto (Apache2)

Comments

[Breaking Change] Replace elmesque crate with primitive graphics widgets (see comment for more details).
~~This is a WIP - Do not merge just yet.~~

This is quite a hefty change, and in turn is leaking into quite a few areas:

Add the widget::primitive module, hosting all primitive widgets. This module should contain all the primitive widgets a widget designer could possibly need to implement their own complex widgets.

Added an example demonstrating each of the primitive widgets.

Widgets will now compose themselves of primitive graphics widgets rather than drawing their own Elements or Forms. This allows us to remove the elmesque crate and use our own graphics layout instead, in turn providing a far simpler (and more efficient) graphics backend.

Theme will now support custom widget styling (rather than hard-coded style types).

Added methods to the Sizeable trait that allow setting a Widget's dimensions to match the dimensions of some other Widget.

Added a TitleBar widget, which Canvas will now use instead of its own custom TitleBar type.

Added a Widget::picking_passthrough(bool) method which allows a user to indicate whether their widget should be pick-able by the mouse or other widget picking methods. This is useful for primitive graphics widgets that are only designed to be used as graphical elements, and that are not themselves interactive.

Fixed a bug in Graph::scroll_offset where the behaviour would be incorrect if two widgets shared both Edge::Depth and Edge::Position.

Removed Label widget in favour of new Text primitive widget that handles automatic line-wrapping, line-spacing, etc.

Moved color.rs module from elmesque into conrod.

Removes rustc-serialize as the first step towards using serde (perhaps as a feature).

All-in-all I think this should be a massive API improvement, and allow conrod to be a lot simpler to work with regarding graphics (elmesque has been a common point of confusion). It should also be much faster than elmesque as drawing will no longer require near as many allocations.

Closes #421. Closes #466. Closes #506. Closes #509. Closes #522. Closes #555. Makes a start on #576. Closes #581. Closes #582. Closes #616. Closes #617. Fixes #628. Closes #629.
opened by mitchmindtree 25
Update to latest changes in graphics and piston_window crates. Removes some unused dev-dependencies.

Don't merge yet.

Since updating, all of the colours in all of the examples have become much lighter:

Before

After

It's possible that there might be some other change we have to update to in conrod, but perhaps also possible that there may have been a bug introduced to the graphics or gfx_graphics crates during the update to the latest gfx. Will look into this soon as this should be fixed before merging this PR. Ping @bvssvni

opened by mitchmindtree 23
Relicense under dual MIT/Apache-2.0
This issue was automatically generated. Feel free to close without ceremony if you do not agree with re-licensing or if it is not possible for other reasons. Respond to @cmr with any questions or concerns, or pop over to #rust-offtopic on IRC to discuss.

You're receiving this because someone (perhaps the project maintainer) published a crates.io package with the license as "MIT" xor "Apache-2.0" and the repository field pointing here.

TL;DR the Rust ecosystem is largely Apache-2.0. Being available under that license is good for interoperation. The MIT license as an add-on can be nice for GPLv2 projects to use your code.

Why?

The MIT license requires reproducing countless copies of the same copyright header with different names in the copyright field, for every MIT library in use. The Apache license does not have this drawback. However, this is not the primary motivation for me creating these issues. The Apache license also has protections from patent trolls and an explicit contribution licensing clause. However, the Apache license is incompatible with GPLv2. This is why Rust is dual-licensed as MIT/Apache (the "primary" license being Apache, MIT only for GPLv2 compat), and doing so would be wise for this project. This also makes this crate suitable for inclusion and unrestricted sharing in the Rust standard distribution and other projects using dual MIT/Apache, such as my personal ulterior motive, the Robigalia project.

Some ask, "Does this really apply to binary redistributions? Does MIT really require reproducing the whole thing?" I'm not a lawyer, and I can't give legal advice, but some Google Android apps include open source attributions using this interpretation. Others also agree with it. But, again, the copyright notice redistribution is not the primary motivation for the dual-licensing. It's stronger protections to licensees and better interoperation with the wider Rust ecosystem.

How?

To do this, get explicit approval from each contributor of copyrightable work (as not all contributions qualify for copyright, due to not being a "creative work", e.g. a typo fix) and then add the following to your README:

## License Licensed under either of * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option. ### Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

and in your license headers, if you have them, use the following boilerplate (based on that used in Rust):

// Copyright 2016 conrod Developers // // Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or // http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms.

It's commonly asked whether license headers are required. I'm not comfortable making an official recommendation either way, but the Apache license recommends it in their appendix on how to use the license.

Be sure to add the relevant LICENSE-{MIT,APACHE} files. You can copy these from the Rust repo for a plain-text version.

And don't forget to update the license metadata in your Cargo.toml to:

license = "MIT OR Apache-2.0"

I'll be going through projects which agree to be relicensed and have approval by the necessary contributors and doing this changes, so feel free to leave the heavy lifting to me!

Contributor checkoff

To agree to relicensing, comment with :

I license past and future contributions under the dual MIT/Apache-2.0 license, allowing licensees to chose either at their option.

Or, if you're a contributor, you can check the box in this repo next to your name. My scripts will pick this exact phrase up and check your checkbox, but I'll come through and manually review this issue later as well.

[x] @BenMcH

[x] @EleDiaz

[x] @Esption

[ ] @Potpourri

[x] @Ryman

[x] @TheNeikos

[x] @Vinatorul

[x] @aepsil0n

[ ] @alexchandel

[x] @benaryorg

[x] @bheart

[ ] @burtonageo

[x] @bvssvni

[x] @cmr

[x] @cybergeek94

[x] @dcampbell24

[ ] @debloper

[x] @ebfull

[x] @eklavya

[x] @evenlis

[x] @frewsxcv

[x] @gaudecker

[x] @gchp

[x] @indiv0

[x] @iwillspeak

[x] @jarrett

[x] @leonkunert

[x] @lifthrasiir

[x] @mitchmindtree

[x] @natemara

[x] @steveklabnik

[x] @stjahns

[x] @stratact

[ ] @tjtolon

[ ] @waynenilsen

[ ] @yuripourre

[x] @zummenix
opened by emberian 22
The Road to Pure Rust
Requiring users to compile / install C libraries is a real pity. It would be amazing if Conrod required nothing more than

[dependencies] conrod = "*"

I think we still have two dependencies that require having C libraries installed on the user's system:

[x] SDL2

~~This is only used for the example, but should be easily replaced by glutin :) #312~~ Conrod is now backend agnostic and all examples now use glutin.

[x] FreeType

~~This one may be trickier to handle. Is anyone aware of any purely rust font-rendering?~~ Now replaced with rusttype!
discussion
opened by mitchmindtree 22
Defer rendering of widgets in order to resolve drawing conflicts.
Current Problem

We are unable to solve drawing conflicts between multiple widgets.

i.e. when drawing an open DropDownList, the dropped menu will be covered by the widget below if that widget is drawn after the DropDownList. This is becuase the UiContext has know way of re-ordering the rendering of widgets.

Solution

Rather than calling .draw(graphics_backend) as the final builder method for every widget call and rendering each widget in its exact call site, I'm proposing that instead we store each called widget in the UiContext within something like a Vec<&mut Drawable>. Finally, once the user has finished calling all of their widget functions, they can call uic.draw(graphics_backend) which will:

resolve conflicts between widgets and

call the .draw(..) method for every stored widget in the correct order.

Positives

One less builder method for every widget.

Correctly ordered widget drawing.

Negatives

the need to call uic.draw(..) at the end of the render cycle.

the UiContext will need to store more widget information throughout the render cycle.

draft medium discussion
opened by mitchmindtree 22
Minimal fix for list cropping problem

This fixes a problem where a scrollable canvas gets strangely cropped when inside another scrollable region. This also applies to List, ListSelect and DropDownList. To demonstrate the problem I've added a scrollable canvas and a List to the all_piston_window example on this commit: tdaffin@b84ae50

I think that this will fix https://github.com/PistonDevelopers/conrod/issues/955

opened by tdaffin 21
Can not run examples
When I try to run the examples I get a panic:

thread '<main>' panicked at 'called `Result::unwrap()` on an `Err` value: OsError("glx::ChooseFBConfig failed")', ../src/libcore/result.rs:731 An unknown error occurred

Any idea what I am doing wrong?

I am on Arch Linux and I tried using both stable and nightly rust
bug
opened by azerupi 18
Examples don't work

When I try to run the exaples that error occurs:

thread '<main>' panicked at 'called 'Result::unwrap()' on an 'Err' value: "Couldn\'t find any pixel format that matches the criterias."', ../src/libcore/result.rs:746

With an earlier version of conrod I had no problems...
bug

opened by luleyleo 17
Compatibility with FRP event handling
As I mentioned in this blog post (also nice for motivation and background, in case anybody is unaware of what I'm trying to do), it would be pretty cool, if conrod's UI could be used in conjunction with FRP event logic. Now I assume that conrod does a lot of (imperative) event handling logic on its own. I'm not particularly familiar with its internals though.

I wonder if it is possible to find some common ground between a functional approach and what conrod currently implements. Possibly at least the rendering part could be shared, though I'm afraid most of the event handling logic cannot be shared.

In any case, I would be glad about your thoughts regarding whether it makes sense to try to use parts of conrod in this way and how it could be done. There are two concrete questions:

Is conrod's rendering of UI elements decoupled from its event handling logic?

How do you see the relation between UI rendering, conrod's current event handling and a future functional reactive event handling?

discussion
opened by milibopp 17
Various issues with docs and examples

I've been trying to sort out how Conrod relates to Piston Graphics. Is Conrod an alternative, or are the two intended to be complementary? Currently, Conrod feels like an alternative to Graphics because, e.g., Conrod and Graphics have different Color types.

Should this be explained in the readme? If so, could write that up and do a PR.

opened by jarrett 16
Examples Don't Run

This on Linux x64, Rust 1.8, Rustup, for all the examples, although "cargo test" passes OK:

$ cargo run --example all_widgets Running target/debug/examples/all_widgets thread '
' panicked at 'Failed to get root window: XError { description: "GLXBadFBConfig", error_code: 178, request_code: 155, minor_code: 34 }', ../src/libcore/result.rs:746 note: Run with RUST_BACKTRACE=1 for a backtrace. Process didn't exit successfully: target/debug/examples/all_widgets (exit code: 101)

help wanted

opened by Bluebird45 15
Stepping away from conrod (alternative GUI recommendations + opening for maintainers within)

Hi folks! As alluded to in #1453, I've been progressively less and less active on conrod over the past year or so. This has been due in part to being spread thin across many different projects including contract work and other open source projects (mostly nannou).

More recently, progress on the excellent egui library has removed the last of my need to hack on conrod. egui has a very similar architecture and set of goals, but with a design that is much better thought out.

conrod was very much born out of necessity, many years ago in the Rust 0.10 era - a time when there were no other pure-Rust, immediate-mode, platform-agnostic GUI libraries out there at all. It evolved, with many re-writes over time as it was my first major library, and many of us were still working out the ins and outs of Rust library design in general.

Today, many nicer options are well underway and I think egui in particular is clearly a better choice. It has a more concise and flexible way of working with the Ui context, a much broader range of widgets, the ability to write custom widgets as simple functions, much more advanced text formatting and handling, and a nice thorough web demo of all widgets. I don't particularly like egui's default style or look, however the styling is very configurable, most of the supported widgets respond well, and it's trivial to write custom widgets - all of which is better than I can say for conrod.

I've started using egui in my personal projects, and plan to deprecate nannou's use of the nannou_conrod crate in examples in favour of nannou_egui. I still have a handful of old projects that have very large and complex conrod GUIs that aren't worth a re-write but may need maintenance in the future, however beyond this I no longer plan to continue maintenance of conrod itself.

I'm quite proud of conrod and what folks have been able to build with it. I think it has served as a nice bridge from the early days of pre-Rust to today where a much wider selection of more serious GUI libraries exist. If you're looking for a nicer conrod, I'll recommend egui, however if you're open to different kinds of GUI you should also check out iced, druid, orbtk, azul and sixtyfps.

I'll do a PR that adds a notice to the README that points to this text and publish a patch release so that the notice is visible on crates.io too.

Maintainers

If you have contributed in the past or have a publicly available demonstration of your use/investment in conrod and would like to take over maintenance, or if you already have access (@PistonDevelopers/admins, @PistonDevelopers/pistoncollaborator, @alvinhochun) and would like to take the lead on conrod from here on out, let me know here so that I can pass you the reins.

Thanks all for your interest/contributions toward conrod over the years!
information

opened by mitchmindtree 7
Add `#[must_use]` to widgets

The widgets is not shown unless we call .set(_, _) for the widget. Therefore, it might be a good idea to set #[must_use] to Widget-related classes. (I'm new to conrod so I am not sure at all if I am saying right thing, please correct me if I am wrong.)

opened by TonalidadeHidrica 0
Add Sdl2 backend
This is the Take 3 of providing SDL2 backend for cornod.

I didn't use OpenGL

When it comes to using SDL2, there are a big choice: to use OpenGL or not to use. In the prior art,

#996 authored by @jonas-schievink does not rely on OpenGL (consequently not on cornod_gfx etc) but used only the feature of "pure SDL2" (including SDL2_gfx).

#1055 and #1084 authored by @elrnv does use OpenGL.

In this PR, I took the course of not using it, because I wanted to keep the dependencies minimal.

I checked that all the features of DemoApp works, but feel free to pointing out anything I am missing.

Credits go to:

@elrnv for event conversion code. I copy-pasted all your work (but included as the author when committing that part!).

@jonas-schievink for how to render text. Although I refined the implementation and adopt newer APIs, the work could have not been done without your code.

About Rust version

Since I could not find the information of MSRV, I developed conrod_sdl2 crate with 1.57.0 and Rust 2021 Edition. If I should use older ones, I would update the code.

About the addition to the dependency

I added thiserror to minimize the boilerplates on error handling, and smallvec for a iterator-friendly container of up-to-two events. If this matters, let me know and I'll think the other way.

Notes on graphics

When you run all_sdl2, you will see the thin diagonal lines as well as horizontal and vertical noize-like lines. These are probably due to overlapping extremely-thin transparent triangles. Unlike GL families, triangles in SDL seems not be cut out for forming complex polygons from many triangles. I think this is inevitable, as long as we use pure SDL2.
opened by TonalidadeHidrica 1
Is the source code of "JAW - Jen Audio Workstation" published?

Hi @mitchmindtree ,

I'm looking for a GUI framework written in Rust for my DAW-like project and really interested in the option of choosing cornod. Especially I found a very intriguing example in this old blog post, in which there is a screenshot of a music-editor like window, with title "JAW - Jen Audio Workstation". Let me quote the picture here:

This app seems especially unique in that it contains custom timeline-style widget, seemingly associated to a timeline of measures and beats. My project will require such custom widget to, so I am eager to refer to the code to see how can I implement them. Similar GUI component can be found in the guide too:

So what I am very interested in is that: is the source code of JAW, or at least the timeline example, is published somewhere?

opened by TonalidadeHidrica 0
Is it possible to use conrod in retained mode?

Conrod's description states that it's an immediate-mode wrapper over a retained-mode UI. Is it possible to use it in retained mode? That is, create the UI once, then query it for events, update widgets by their id, and so on.

opened by danielkeller 0
Questions regarding this project
Hi, I have some questions regarding this project:

Can I make regular GUI applications (such as menus, buttons and stuff) or is this more aimed at computer graphics design art work?

Is this cross compatible between Linux, Windows, web version and Android (write once run everywhere)? If it doesn't support all of the mentioned platforms which platforms does it support?

If it supports web version would it be a web application, or html/css or both?

Is it well maintained?

Does it give me the ability to make my own custom UI, something like this for example:

And can I mimic Android's native UI?

Is there a chat platforms such as Discord or Matrix (Element) for this project?
opened by Raj2032 0

Owner

PistonDevelopers

The Piston game engine organization for maintenance and research

GitHub

Simple and portable (but not inflexible) GUI library in C that uses the native GUI technologies of each platform it supports.

libui: a portable GUI library for C This README is being written. Status It has come to my attention that I have not been particularly clear about how