Write a Guide / Tutorial

[mitchmindtree]

The Guide should probably be structured to look something like this:

• 1. What is Conrod
  • A brief summary of 2D GUI, Conrod use-cases.
  • some screenshots / video demos
  • list the available widgets
  • link to examples
  • A brief intro to "Immediate Mode" aka OMG why do I construct the Widget EVERY FRAME?!
    • how does IMGUI work (explain caching etc)
    • why did we use IMGUI (pros/cons)
  • The "Builder Pattern" (why use it, how it works)
• 2. Using Conrod (to create a basic app GUI)
  • A walk-through showing how to use Conrod to make a GUI with a small demonstration app.
  • Setup a basic window using glium.
  • Create a demo App struct with some dummy data.
  • Writing a ui function for the app.
  • Generate a list of IDs using the widget_ids! macro (not yet implemented).
  • Draw a basic widget (i.e. Button).
  • Demo Positionable, Colorable, etc traits (show where to find all available builder methods / traits for a widget in the docs).
  • Slightly more complicated widget (DropDownList)
  • Attach widgets to a parent "canvas" (demo different internal canvasses).
• 3. Using and Customising Themes
  • Explanation of how Conrod uses Themes.
  • How to use a Theme (load from json).
  • How to make a custom Theme (use in demo app from previous chapter).
  • How to add custom widget styling to a Theme.
• 4. Designing custom Widgets using Conrod's Widget trait
  • Start with basics by demoing how to make a Button.
  • Discuss how widget state is stored within the Graph and how each of the different types of IDs/indices relate to each other.
  • Move on to a more advanced example composing a widget from other widgets.
• 5. How to use Conrod with your own backend
  • Demo how to use conrod's render::Primitives to draw to a custom backend.
• 6. Contributing to Conrod
  • Details about the library innards
  • New widgets are welcome etc

I think it'd make sense to do this in markdown for now (i.e. a GUIDE.md) but I'm open to any other suggestions 👍

[olsonjeffery]

Hi, I know it's not super helpful to just make a request without offering to help, but would it worth considering adding discussion tuts around using conrod as the GUI layer while using lower-level (than piston) frameworks (like glium or gfx-rs) for actual graphics?

That's my current situation. I'm using gfx-rs for the main graphics b/c im doing a 2d charmap/tilemap thing on a plane mesh + shader stuff. I would like to use piston for the GUI portion while taking on all the piston-idiomatic baggage (or taking it on the degree least neccesary.. eg how to use piston when i'm creating windows via raw glutin calls?).

[mitchmindtree]

@olsonjeffery good point! I've edited the comment above with a 5th chapter. No problem btw, any ideas / requests are welcome 👍

[jarrett]

I'm starting to use Conrod heavily on a real project, and I need it to be documented for possible future devs. So I was thinking I might just take a stab at this guide. What form should it take? A Markdown file? A web page? A wiki?

[mitchmindtree]

@jarrett that would be great! Yeah I think a GUIDE.md at the top level is probably a good idea for now 👍 I'll add it to the top comment.

[Phlosioneer]

List of available widgets is outdated - Image widget added in #696.

[mitchmindtree]

@Phlosioneer thanks, fixed in #731.

[enricostano]

Some broken link fixed #829