To begin the introduction to maemomm, a simple program will suffice. This program will create a window with a label to display 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;  
}

Each line of the example will now be explained:

#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, which is needed in all gtkmm and maemomm applications. The constructor for this object initialises 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 previous 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 the compilation command for this simple example was shown previously, the automake and autoconf tools should be used instead, 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, with appropriate build files, so the build commands will not be shown in future. You will just need to find the appropriate directory and type make. See the Installation section for more information on maemomm-documentation.

pkg-config is present in all (correctly installed) maemomm installations, and is used to simplify compilation. This program 'knows' which 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.