1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
/*!
**What is Conrod?**
## A Brief Summary
Conrod is a portable, 2D, [GUI][1] library for the [Rust programming language][2].
It provides an immediate-mode API that wraps a retained-mode widget state graph. This allows us to
expose a simple, robust and reactive interface while approaching the performance of traditional,
retained GUI frameworks.
We provide a set of primitive and commonly useful widgets, along with a [Widget] API that allows
for designing new, custom widgets composed of unique logic and other widgets.
Widgets are instantiated using the "Builder" aka "Method Chaining" pattern within an update loop.
In this sense, we can think of a Widget and its builder methods as a function with a highly
flexible and readable set of arguments.
## Screenshots and Videos
If you have an awesome looking GUI made with conrod, please send us a screenshot and we'll add it here :)
Here's [a youtube demo](https://www.youtube.com/watch?v=n2UrjogA0j0) of the all widgets example.
Here's [another youtube demo](https://www.youtube.com/watch?v=_ZXLCVibI8c) of conrod being used to create a basic synth editor.
**A multimedia timeline widget.**
<img src="http://imgur.com/34NEw90.png" alt="timeline" style="width:700px;">
**The [all_piston_window.rs example](https://github.com/PistonDevelopers/conrod/blob/master/backends/conrod_piston/examples/all_piston_window.rs).**
<img src="http://i.imgur.com/xKXISdc.png" alt="all_widgets.rs" style="width:700px;">
**The [canvas.rs example](https://github.com/PistonDevelopers/conrod/blob/master/backends/conrod_glium/examples/canvas.rs).**
<img src="http://i.imgur.com/YtjjEJX.png" alt="canvas.rs" style="width:700px;">
## Feature Overview
- **Reactive** and **Immediate** API. Produce the UI from your application state in one place, rather than as a separate entity spread across callbacks, instantiation, updates and drawing.
- A **Widget trait** to simplify the composition and design of widgets.
- **Scrolling** that is opt-in, generalised and easy-to-use. Call `.scroll_kids(true)` on a widget and it will become a scrollable container for its children.
- **Powerful layout and positioning**:
- Placement - `.middle()`, `.top_left_of(CANVAS)`, `.mid_right_with_margin(20.0)`, etc.
- Alignment - `.align_left()`, `.align_top_of(LABEL)`, etc.
- Relative - `.down(20.0)`, `.right_from(BUTTON, 40.0)`, `.x_y_relative(20.0, 42.0)`, etc.
- Absolute - `.x_y(6.0, 7.0)`
- Draggable pop-up / floating canvasses - `.floating(true)`.
- **WidgetMatrix** and **PositionMatrix** for instantiating a grid of widgets.
- **[Theme]**s for unique style and layout defaults.
- **[widget_ids!]** macro for easily and safely generating unique widget identifiers.
- Generic over events and graphics backends - compatible with:
- [glutin][7], [sdl2][8] and [glfw][9] [**Window**][10] backends.
- [gfx][11], [glium][12] and raw [opengl][13] [**Graphics**][14] backends.
- Provides a collection of commonly useful widgets.
## Available Widgets
The widgets that are provided by conrod can be broken into two sets: [**primitive**][3] and [**common
use**][4].
### Primitive Widgets
Primitive widgets are the fundamental graphical components in any conrod user interface. They are a
special set of widgets from which all other widgets may be composed. For example, a `Button` widget
may be composed of one `Rectangle` primitive widget and one `Text` primitive widget. A
`DropDownList` may be composed of *n* `Button` widgets, and in turn *n* `Rectangle` primitive
widgets and *n* `Text` primitive widgets.
When drawing the widget graph to the screen, conrod *only* draws the primitive widgets. This allows
widget designers to create custom widgets by simply instantiating other widgets, without having to
directly write any graphics code themselves. This also greatly simplifies the caching of common
widget state like text, positioning and styling as the primitive widgets take care of all of this
automatically.
The following are the primitive widgets provided by conrod:
- **[Line]**
- **[PointPath]**
- Shapes:
- **[Circle]**
- **[Rectangle]**
- **[Oval]**
- **[Polygon]**
- **[Text]** - automatic line-wrapping, line spacing, etc.
- **[Image]**
If conrod is lacking a primitive widget that you require, please let us know! There are currently
plans to allow for a user to design their own primitive widgets, however these will likely remain
low priority until requested.
### Common Use Widgets
Common use widgets are simply widgets that are commonly required by GUIs. There is nothing special
about these widgets in the sense that they could just as easily be implemented in an external
crate by third-party users. However, their usage is common enough that we choose to distribute them
with conrod itself.
The following are the common use widgets provided by conrod:
- **[BorderedRectangle]**
- **[Button]**
- **[Canvas]** - a container-like widget
- **[DropDownList]**
- **[EnvelopeEditor]**
- **[Matrix]**
- **[NumberDialer]**
- **[PlotPath]**
- **[Scrollbar]** - emits scroll events to some target scroll widget
- **[Slider]**
- **[Tabs]** - for easily switching between multiple [Canvas]ses with ease
- **[TextBox]** - an editable one-line text field
- **[TextEdit]** - an editable block of text
- **[TitleBar]**
- **[Toggle]**
- **[XYPad]**
The following are planned, but not yet implemented:
- [Menu Bar / Tool Bar](https://github.com/PistonDevelopers/conrod/issues/417)
- [Right-click Context Menu](https://github.com/PistonDevelopers/conrod/issues/394)
- [Graph / Chart](https://github.com/PistonDevelopers/conrod/issues/84)
- [File/Directory Navigator](https://github.com/PistonDevelopers/conrod/issues/381)
- [Advanced graph visualisation and control](https://github.com/PistonDevelopers/mush)
If you notice that we're missing important widgets, or if you have a widget that you feel would
make a nice addition to conrod, please let us know by leaving an [issue][5] or [pull request][6]!
Be sure to check [issues with the widget
label](https://github.com/PistonDevelopers/conrod/issues?q=is%3Aopen+is%3Aissue+label%3Awidget)
first, as your desired widget may have already been requested.
## "Immediate Mode"
### What is it?
The term "Immediate Mode" describes a style of user interface API.
In an immediate mode GUI, widgets are instantiated using functions in an *update* or *draw* loop.
This is quite different to the more traditional "retained mode", where widget *types* are
constructed during the *setup* stage.
Immediate mode encourages a less stateful, more data-driven design as the user interface is
instantiated as a *result* of the application state every frame or update. On the other hand,
retained user interfaces tend to work the other way around, driving the application by sending
events or triggering callback functions upon user interaction.
### Why use it?
Immediate mode tends to be the easier style to use for highly dynamic interfaces and those that
require frequent synchronisation with application state. This is because immediate widgets handle
changes in application state at the same place in which they are instantiated (during the update
or draw stage). While retained interface logic is often divided up between instantiation, updating,
drawing and event handling, immediate interfaces aim to consolidate all UI related logic within one
place.
Historically, due to their statelessness and frequent re-instantiation, immediate mode interfaces
have been known to pay the price of performance for their convenience. Although retained interfaces
can be more tedious to maintain and synchronise with application state, they are often less CPU
intensive as the majority of their state remains untouched following the application's setup stage.
### Is Conrod Immediate or Retained?
Conrod aims to adopt the best of both worlds by providing an immediate mode API over a hidden,
retained widget state graph. From the user's perspective conrod widgets tend to feel stateless, as
though they only exist for the lifetime of the scope in which they are instantiated. In actuality,
each widget's state is cached (or "retained") within the `Ui`'s internal widget graph. This allows
for efficient re-use of allocations and the ability to easily defer the drawing of widgets to a
stage that is more suited to the user's application. As a result, Conrod should be able to provide
the convenience of an immediate mode API alongside performance that approaches that of traditional,
retained GUIs.
## The Builder Pattern
The "Builder Pattern" describes the process of "building" a type by chaining together method calls.
Conrod uses this pattern within its API for widget instantiation. This pattern is perhaps easiest
to grasp with an example.
Let's say we have a `Button` widget. We want to make sure that a user may instantiate it with
specific dimensions, position, color, label, label font size and label color. A naiive constructor
might look like this:
```ignore
Button::new(dimensions,
position,
color::RED,
"DONT PRESS",
label_font_size,
label_color,
|| do_stuff(),
BUTTON_ID,
&mut ui);
```
The problem is that most of the time users will just want the `Button` to choose defaults straight
from the `Ui`'s `Theme`, rather than specifying every parameter for every instance of a `Button`
themselves. We want parameters to be *optional*. Perhaps then, we should make optional parameters
take an `Option`?
```ignore
Button::new(Some(dimensions),
Some(position),
None,
"DONT PRESS",
None,
None,
Some(|| do_stuff()),
BUTTON_ID,
&mut ui);
```
Although the user no longer has to think about the values for parameters they don't care about,
this is still extremely verbose and the `None` parameters seem quite ambiguous.
In some languages, this problem might be solved using a combination of features called "named
parameters" and "default parameters". If rust had these features, the above might look like this:
```ignore
Button::new(dimensions=dimensions,
position=position,
label="DONT PRESS",
react=|| do_stuff(),
id=BUTTON_ID,
ui=&mut ui);
```
Certainly an improvement in conciseness and readability. Although these features are not available
to us in Rust, there is a way in which we can emulate their behaviour - This is where the builder
pattern comes in.
By moving each parameter out of the `new` function args and into their own methods, we can treat
methods almost as though they are named parameters as in the above example. Here is what the above
might look like using the builder pattern:
```ignore
Button::new()
.dimensions(dimensions)
.position(position)
.label("DONT PRESS")
.react(|| do_stuff())
.id(BUTTON_ID)
.ui(&mut ui);
```
*This is in fact the method of widget instantiation used by conrod, though with some slight
differences in method naming (best to check the examples directory for a proper demo).*
Although this certainly seems like the nicest solution from an API perspective, the
attentive rustacean may notice that this requires extra work for the widget designer compared to
the previous examples. Previously, all work for widget instantiation was done within the `new`
function. The builder pattern implementation introduces a few differences worth noticing:
1. A method must be implemented on `Button` for every optional parameter.
2. The `Button::new` function must return some type that can be treated as a set of `Option`
arguments which can be set as it is passed from builder method to builder method.
3. There must be some method that indicates the end of building and the instantiation of the widget.
In Conrod, we are of the opinion that, in the common case, the extra work on behalf of the widget
designers is worth the benefits gained by the users. However, we also make a significant effort to
address each of the above points best we can in order to reduce the workload of widget developers:
1. We provide a [`builder_methods!`][builder_methods!] macro which reduces the boilerplate of builder method
implementation.
2. In Conrod, widgets are treated as a set of arguments to their state, rather than containing
their own state themselves. This suits the immediate mode style of conrod, where widget state is
hidden and stored within the `Ui`.
3. All Conrod widgets must take a unique identifier and a mutable reference to the `Ui`. We
consolidate this into a single `.set(ID, &mut ui)` method, which we also use as the indication
method to stop building and instantiate the widget within the `Ui`.
All of these points will be covered later in more detail within the widget implementation section
of the guide.
[1]: https://en.wikipedia.org/wiki/Graphical_user_interface "Wikipedia - Graphical User Interface"
[2]: https://www.rust-lang.org/ "The Rust Programming Language"
[3]: ./index.html#primitive-widgets "Primitive Widgets"
[4]: ./index.html#common-use-widgets "Common Use Widgets"
[5]: https://github.com/PistonDevelopers/conrod/issues "Conrod Github Issues"
[6]: https://github.com/PistonDevelopers/conrod/pulls "Conrod Github Pull Requests"
[7]: https://github.com/PistonDevelopers/glutin_window "glutin_window crate"
[8]: https://github.com/PistonDevelopers/sdl2_window "sdl2_window crate"
[9]: https://github.com/PistonDevelopers/glfw_window "glfw_window crate"
[10]: http://docs.piston.rs/piston/window/trait.Window.html "src Window trait"
[11]: https://github.com/PistonDevelopers/gfx_graphics "gfx_graphics crate"
[12]: https://github.com/PistonDevelopers/glium_graphics "glium_graphics crate"
[13]: https://github.com/PistonDevelopers/opengl_graphics "opengl_graphics crate"
[14]: http://docs.piston.rs/graphics/graphics/trait.Graphics.html "src Graphics trait"
[Widget]: ../../widget/trait.Widget.html "Widget trait"
[Theme]: ../../theme/struct.Theme.html "Theme struct"
[builder_methods!]: ../../macro.builder_methods!.html "builder_methods! macro"
[widget_ids!]: ../../macro.widget_ids!.html "widget_ids! macro"
[Line]: ../../widget/primitive/line/struct.Line.html "Line Widget"
[PointPath]: ../../widget/primitive/point_path/struct.PointPath.html "PointPath Widget"
[Circle]: ../../widget/primitive/shape/circle/struct.Circle.html "Circle Widget"
[Rectangle]: ../../widget/primitive/shape/rectangle/struct.Rectangle.html "Rectangle Widget"
[Oval]: ../../widget/primitive/shape/oval/struct.Oval.html "Oval Widget"
[Polygon]: ../../widget/primitive/shape/polygon/struct.Polygon.html "Polygon Widget"
[Text]: ../../widget/primitive/text/struct.Text.html "Text Widget"
[Image]: ../../widget/primitive/image/struct.Image.html "Image Widget"
[BorderedRectangle]: ../../widget/bordered_rectangle/struct.BorderedRectangle.html "BorderedRectangle Widget"
[Button]: ../../widget/button/struct.Button.html "Button Widget"
[Canvas]: ../../widget/canvas/struct.Canvas.html "Canvas Widget"
[DropDownList]: ../../widget/drop_down_list/struct.DropDownList.html "DropDownList Widget"
[EnvelopeEditor]: ../../widget/envelope_editor/struct.EnvelopeEditor.html "EnvelopeEditor Widget"
[NumberDialer]: ../../widget/number_dialer/struct.NumberDialer.html "NumberDialer Widget"
[PlotPath]: ../../widget/plot_path/struct.PlotPath.html "PlotPath Widget"
[Scrollbar]: ../../widget/scrollbar/struct.Scrollbar.html "Scrollbar Widget"
[Slider]: ../../widget/slider/struct.Slider.html "Slider Widget"
[Tabs]: ../../widget/tabs/struct.Tabs.html "Tabs Widget"
[TextBox]: ../../widget/text_box/struct.TextBox.html "TextBox Widget"
[TextEdit]: ../../widget/text_edit/struct.TextEdit.html "TextBox Widget"
[TitleBar]: ../../widget/title_bar/struct.TitleBar.html "TitleBar Widget"
[Toggle]: ../../widget/toggle/struct.Toggle.html "Toggle Widget"
[Matrix]: ../../widget/matrix/struct.Matrix.html "Matrix Widget"
[XYPad]: ../../widget/xy_pad/struct.XYPad.html "XYPad Widget"
*/