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

1. 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");
2. 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]);

1. 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();
   

2. 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();
3. 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.