To begin our introduction to maemomm, we'll start with the simplest program possible. This program will create a window with a label to displaying some text.

Source Code

File: main.cc

#include <hildonmm.h>

int main(int argc, char *argv[])
{
  // Initialize gtkmm:
  Gtk::Main kit(&argc, &argv);
  Hildon::init();

  Glib::set_application_name("Hildon-Widgetsmm Example");
   
  // Create Window and set it to the Program instance().
  Hildon::Window window;
  Hildon::Program::get_instance()->add_window(window);

  // Add example label to window.
  Gtk::Label label("Hildon::Program Example");
  window.add(label);
  label.show();
  
  // Begin the main application.
  kit.run(window);

  return 0;  
}

We will now explain each line of the example

#include <hildonmm/program.h>

All maemomm programs must include the maemomm headers. The hildonmm.h and hildon-fmmm.h headers include the entire maemomm API. This is usually not a good idea, because it indirectly includes many headers, slowing down compilation, but for simple programs it suffices.

The next line:

Gtk::Main kit(argc, argv);

Creates a Gtk::Main object. This is needed in all gtkmm and maemomm applications. The constructor for this object initializes gtkmm, and checks the arguments passed to your application on the command line, looking for standard options such as -display. It takes these from the argument list, leaving anything it does not recognise for your application to parse or ignore. This ensures that all gtkmm and maemomm applications accept the same set of standard arguments.

Hildon::Program Reference

Glib::set_application_name("Hildonmm example");

This sets the name of the application. Maemo displays this name at the top of the screen. Alternatively, one can call the set_title() method of Hildon::Window to set the title displayed by Maemo.

The next two lines of code create and display a window, as you might do in a regular gtkmm application.

Hildon::Window window;
Hildon::Program::get_instance()->add_window(window);
Gtk::Label label("Hildon::Program example");
window.add(label);
window.show_all();

Usually you will derive your own window class from Hildon::Window and add widgets to it in the constructor. Note that you must then add all windows to your program. A Hildon::Program instance is always present in all maemomm applications and can be accessed using the static Hildon::Program::get_instance() method.

Hildon::Window Reference

Hildon::Program Reference

The last line shows the window and enters the maemomm main processing loop, which will finish when the window is closed.

kit.run(window);

After putting the source code in simple.cc you can compile the above program with gcc using:

g++ simple.cc -o simple `pkg-config hildonmm hildon-fmmm --cflags --libs`

Note that you must surround the pkg-config invocation with backquotes. Backquotes cause the shell to execute the command inside them, and to use the command's output as part of the command line.

Although we have shown the compilation command for this simple example, you really should use the automake and autoconf tools, as described in "Autoconf, Automake, Libtool", by G. V. Vaughan et al. The examples used in this book are included in the maemomm-documentation package (see the introduction section), with appropriate build files, so we won't show the build commands in future. You'll just need to find the appropriate directory and type make.

To simplify compilation, we use pkg-config, which is present in all (properly installed) maemomm installations. This program 'knows' what compiler switches are needed to compile programs that use maemomm. The --cflags option causes pkg-config to output a list of include directories for the compiler to look in; the --libs option requests the list of libraries for the compiler to link with and the directories to find them in. Try running it from your shell-prompt to see the results on your system.