Rapicorn Tutorial

Rapicorn is an experimental graphical user interface toolkit. Many things that programmers need to spell out explicitely in other toolkits are automated in Rapicorn and duplicate manual work is reduced as much as possible. It aims at bringing UI-design, UI-notation and UI-programming as close together as possible. This is accomplished by providing conscise ways for user interface notation and providing a simple to use programming interface.

This tutorial focuses on presentation of the established programming interface and guide through creation of exemplary user interface programs. The tutorial is a public joined efforts, everyone can contribute to it, fix or extend it's content by navigating to: http://www.testbit.eu/book/Rapicorn-Tutorial.

Hello World

Every programming or toolkit library comes with the obligatory "Hello World" example, so here are the neccessary steps for a Rapicorn "Hello World" program in C++.

The Program

Every program using Rapicorn needs to first initialize the core library and also initialize a particular viewport backend. Both can be accomplished by this call: Application::init_with_x11 (&argc, &argv, "Program Name");
Programs that display graphical user interfaces with Rapicorn generally need to load user interface description files, which can be accomplished by:

Application::auto_load ("i18n-domain", "ui-description.xml", argv[0]);

Windows defined in the user interface description files then need to be created and at some point shown to the user:
```
  Window window = Application::create_window ("main-window");
  window.show();
```
Most GUI programs will handle user input on demand after windows have initialy been displayed. For this, they enter an event loop and remain until users initiate application exit. In Rapicorn this is done by: Application::execute_loops();

Last but not least, GUI programs need a way to specify program actions to be executed when certain user interface elements like buttons are activated. In Rapicorn, such actions are hooked up as "command handlers" on a window: window.commands += handle_commands;. For this to work, a handle_commands() function needs to be supplied by the program, e.g.:

  static bool
  handle_commands (Window       &window,
                   const String &command,
                   const String &args)
  {
    if (command == "close")
      window.close();
    else
      printout ("%s(): unknown command: %s(%s)\n", __func__,
                command.c_str(), args.c_str());
    return true; // command was handled
  }

Putting it all together: examples/hello.cc.

The GUI

Apart from the program, a user interface definition file needs to be provided that defines main-window. All main windows need to derive from the Root widget, which provides basic functionality like on screen display (depending on the viewport backend being used) and event handling:

  <def:main-window inherit="Root"/>

It is generally a good idea to put an OuterShell into each root widget, to get some basic layout functionality, window border spacing and lighting effects:

  <def:main-window inherit="Root">
    <OuterShell/>
  </def:main-window>

A "Hello World" application of course needs to display the "Hello World" text, this can be accomplished by using a Label and setting its markup-text property:

  <Label>
    <prop:markup-text>
      <larger>Hello World!</larger>
    </prop:markup-text>
  </Label>

Finally, a Button is needed which allows closing of the window:

  <Button on-click="close">
    <Label markup-text="Close"/>
  </Button>

Putting both into the OuterShell will arrange them vertically. The end result is provided here: examples/hello.xml.