Rapicorn - Experimental UI Toolkit - Source Code  13.07.0
Rapicorn Tutorial

Introduction

Rapicorn is a toolkit for rapid development of user interfaces for C++ and Python development. As of 2012, much is still in prototype/alpha development stage, but a strong set of foundation technologies has already been established.

Everybody is invited to participate with ideas, code, wiki contributions, artwork and of course to help with this tutorial.

The main tutorial page is hosted on the Rapicorn website. Contributions and feedback are best discussed in the Rapicorn forum or the talk page.

Hello Rapicorn

Like many others, Rapicorn is an event driven user interface (UI) toolkit, which determines its programming model. That is, Rapicorn is used to define and present UI elements (widgets) to the user and then waits and reacts to input events provided by the user. So in a nutshel, a Rapicorn program looks like this:

  1. Application Startup.
  2. Dialog creation and display.
  3. Events & Signals: handle user events with code in callback functions.
  4. Event Loop & Exit: Wait for events, loop and eventually exit the application.

So much for the theory, let's get started with the first application!

# Load and import a versioned Rapicorn module into the 'Rapicorn' namespace
import Rapicorn1307 as Rapicorn

# Setup the application object, unsing a unique application name.
app = Rapicorn.app_init ("Hello Rapicorn")

# Define the elements of the dialog window to be displayed.
hello_window = """
  <tmpl:define id="hello-window" inherit="Window">
    <Alignment padding="15">
      <VBox spacing="30">
        <Label markup-text="Hello World!"/>
        <Button on-click="CLICK">
          <Label markup-text="Close" />
        </Button>
      </VBox>
    </Alignment>
  </tmpl:define>
"""

# Register the 'hello-window' definition for later use, for this we need
# a unique domain string, it's easiest to reuse the application name.
app.load_string ("HelloRapicorn", hello_window)

# The above is all that is needed to allow us to create the window object.
window = app.create_window ("HelloRapicorn:hello-window")

# This function is called to handle the command we use for button clicks.
def command_handler (command_name, args):
  # When we see the 'CLICK' command, close down the Application
  if command_name == "CLICK":
    app.close_all();

# Call the handler when the Window::commands signal is emitted.
window.sig_commands_connect (command_handler)

# Preparations done, now it's time to show the window on the screen.
window.show()

# Pass control to the event loop, to wait and handle user commands.
app.loop()

1. Application Startup

Rapicorn is provided as a versioned Python module that's intended to be imported into the "Rapicorn" namespace. This way, Python scripts can be deliberately updated to new Rapicorn versions by changing just the import lines.

The app_init() function takes a string with a unique application name to identify its windows in desktop sessions and to associate saved configuration data. This function creates the Application object, initializes the library, loads configuration, data and graphics files.

2. Dialog Creation

The hello_window variable contains an XML syntax declaration which defines the way in which various widgets are combined to form a window which contains spacings, some text and a clickable button. All widgets and the properties (attributes) supported by each are described in the reference documentation, e.g. Rapicorn::Window, Rapicorn::Label and Rapicorn::Button. Note the Button's on-click attribute, the string assigned to it represents a "command" that is passed on to the Window::commands signal.

The hello_window definition first needs to be registered with the Application. We then create a window widget from this definition.

3. Events and Signals

As soon as Window widgets are shown on the screen, users can interact with them in various ways, e.g. through key presses, mouse movements, button presses, finger gestures, touches or swipes.

When a button is clicked, it responds with on-click notifications, which means a notification with a custom command is sent out for this window. The actual notification is carried out by the Window::commands signal. Signals are a means to connect custom callback functions to notifications, so by connecting our callback function to the Window::commands signal, our code can handle certain commands.

In order to react to users interacting with this window, we need to define a handler function 'command_handler' to be called on such occastions. For the purpose of this program, we simply request the Application object to close all currently opened windows, which eventually results in exiting the application.

To summarize for our example, the event loop, button and window will cause the Window::commands signal to be emitted when the button is clicked. This in turn causes the command_handler() to be called, which simply closes all open windows, so the application can stop.

Event Loop and Exit

After showing Window widgets on the screen, all applications need to enter the main event loop. The event loop simply waits for user input events on all windows currently open (plus related events like network IO, etc) and takes care of letting each widget process the events it needs, e.g. mouse clicks on a Button widget. By default, the loop keeps running and processes events as long as any Window is still open.

After all windows have been closed, the event loop sends out notifications that cause the Application object to stop the event loop from running and control is handed back to the main program. Most programs will simply exit at this point.

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines