Basics
This chapter will introduce some of the most important aspects of gtkmm coding. These will be demonstrated with simple working example code. However, this is just a taster, so you need to look at the other chapters for more substantial information.
Your existing knowledge of C++ will help you with gtkmm as it would with any library. Unless we state otherwise, you can expect gtkmm classes to behave like any other C++ class, and you can expect to use your existing C++ techniques with gtkmm classes.

Simple Example
To begin our introduction to gtkmm, we'll start with the simplest program possible. This program will create an empty 200 x 200 pixel window.
Source Code
File: base.cc (For use with gtkmm 3, not gtkmm 2)

#include <gtkmm.h>

int main(int argc, char *argv[])
{
  Glib::RefPtr<Gtk::Application> app =
    Gtk::Application::create(argc, argv,
      "org.gtkmm.examples.base");

  Gtk::Window window;
  window.set_default_size(200, 200);

  return app->run(window);
}

We will now explain each line of the example

#include <gtkmm.h>

All gtkmm programs must include certain gtkmm headers; gtkmm.h includes the entire gtkmm kit. This is usually not a good idea, because it includes a megabyte or so of headers, but for simple programs, it suffices.
The next statement:

Glib::RefPtr<Gtk::Application> app = Gtk::Application::create(argc, argv, "org.gtkmm.examples.base");

creates a Gtk::Application object, stored in a RefPtr smartpointer. This is needed in all gtkmm applications. The create() method 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 recognize for your application to parse or ignore. This ensures that all gtkmm applications accept the same set of standard arguments.
The next two lines of code create a window and set its default (initial) size:

Gtk::Window window;
window.set_default_size(200, 200);

The last line shows the window and enters the gtkmm main processing loop, which will finish when the window is closed. Your main() function will then return with an appropriate success or error code.

return app->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 gtkmm-3.0 --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. Note also that simple.cc must come before the pkg-config invocation on the command line.

Headers and Linking
Although we have shown the compilation command for the 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 gtkmm-documentation package, 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) gtkmm installations. This program 'knows' what compiler switches are needed to compile programs that use gtkmm. 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.
However, this is even simpler when using the PKG_CHECK_MODULES() macro in a standard configure.ac file with autoconf and automake. For instance:

PKG_CHECK_MODULES([MYAPP], [gtkmm-3.0 >= 3.8.0])

This checks for the presence of gtkmm and defines MYAPP_LIBS and MYAPP_CFLAGS for use in your Makefile.am files.
gtkmm-3.0 is the name of the current stable API. There was an older API called gtkmm-2-4 which installs in parallel when it is available. There were several versions of gtkmm-2.4, such as gtkmm 2.10 and there are several versions of the gtkmm-3.0 API. Note that the API name does not change for every version because that would be an incompatible API and ABI break. Theoretically, there might be a future gtkmm-4.0 API which would install in parallel with gtkmm-3.0 without affecting existing applications.
Note that if you mention extra modules in addition to gtkmm-3.0, they should be separated by spaces, not commas.
Openismus has more basic help with automake and autoconf.

Widgets
gtkmm applications consist of windows containing widgets, such as buttons and text boxes. In some other systems, widgets are called "controls". For each widget in your application's windows, there is a C++ object in your application's code. So you just need to call a method of the widget's class to affect the visible widget.
Widgets are arranged inside container widgets such as frames and notebooks, in a hierarchy of widgets within widgets. Some of these container widgets, such as Gtk::Grid, are not visible - they exist only to arrange other widgets. Here is some example code that adds 2 Gtk::Button widgets to a Gtk::Box container widget:

m_box.pack_start(m_Button1);
m_box.pack_start(m_Button2);

and here is how to add the Gtk::Box, containing those buttons, to a Gtk::Frame, which has a visible frame and title:

m_frame.add(m_box);

Most of the chapters in this book deal with specific widgets. See the Container Widgets section for more details about adding widgets to container widgets.
Although you can specify the layout and appearance of windows and widgets with C++ code, you will probably find it more convenient to design your user interfaces with Glade and load them at runtime with Gtk::Builder. See the Glade and Gtk::Builder chapter.
Although gtkmm widget instances have lifetimes and scopes just like those of other C++ classes, gtkmm has an optional time-saving feature that you will see in some of the examples. Gtk::manage() allows you to say that a child widget is owned by the container into which you place it. This allows you to new the widget, add it to the container and forget about deleting it. You can learn more about gtkmm memory management techniques in the Memory Management chapter.

Signals
gtkmm, like most GUI toolkits, is event-driven. When an event occurs, such as the press of a mouse button, the appropriate signal will be emitted by the Widget that was pressed. Each Widget has a different set of signals that it can emit. To make a button click result in an action, we set up a signal handler to catch the button's "clicked" signal.
gtkmm uses the libsigc++ library to implement signals. Here is an example line of code that connects a Gtk::Button's "clicked" signal with a signal handler called "on_button_clicked":

m_button1.signal_clicked().connect( sigc::mem_fun(*this,
  &HelloWorld::on_button_clicked) );

For more detailed information about signals, see the appendix.
For information about implementing your own signals rather than just connecting to the existing gtkmm signals, see the appendix.

Glib::ustring
You might be surprised to learn that gtkmm doesn't use std::string in its interfaces. Instead it uses Glib::ustring, which is so similar and unobtrusive that you could actually pretend that each Glib::ustring is a std::string and ignore the rest of this section. But read on if you want to use languages other than English in your application.
std::string uses 8 bit per character, but 8 bits aren't enough to encode languages such as Arabic, Chinese, and Japanese. Although the encodings for these languages have now been specified by the Unicode Consortium, the C and C++ languages do not yet provide any standardised Unicode support. GTK+ and GNOME chose to implement Unicode using UTF-8, and that's what is wrapped by Glib::ustring. It provides almost exactly the same interface as std::string, along with automatic conversions to and from std::string.
One of the benefits of UTF-8 is that you don't need to use it unless you want to, so you don't need to retrofit all of your code at once. std::string will still work for 7-bit ASCII strings. But when you try to localize your application for languages like Chinese, for instance, you will start to see strange errors, and possible crashes. Then all you need to do is start using Glib::ustring instead.
Note that UTF-8 isn't compatible with 8-bit encodings like ISO-8859-1. For instance, German umlauts are not in the ASCII range and need more than 1 byte in the UTF-8 encoding. If your code contains 8-bit string literals, you have to convert them to UTF-8 (e.g. the Bavarian greeting "Grüß Gott" would be "Gr\xC3\xBC\xC3\x9F Gott").
You should avoid C-style pointer arithmetic, and functions such as strlen(). In UTF-8, each character might need anywhere from 1 to 6 bytes, so it's not possible to assume that the next byte is another character. Glib::ustring worries about the details of this for you so you can use methods such as Glib::ustring::substr() while still thinking in terms of characters instead of bytes.
Unlike the Windows UCS-2 Unicode solution, this does not require any special compiler options to process string literals, and it does not result in Unicode executables and libraries which are incompatible with ASCII ones.
Reference
See the Internationalization section for information about providing the UTF-8 string literals.

Intermediate types
Some API related to gtkmm uses intermediate data containers, such as Glib::StringArrayHandle, instead of a specific Standard C++ container such as std::vector or std::list, though gtkmm itself now uses just std::vector since gtkmm 3.0.
You should not declare these types yourself. You should instead use whatever Standard C++ container you prefer. glibmm will do the conversion for you. Here are some of these intermediate types:
Glib::StringArrayHandle or Glib::ArrayHandle<Glib::ustring>: Use std::vector<Glib::ustring>, std::list<Glib::ustring>, const char*[], etc.
Glib::ListHandle<Gtk::Widget*>: Use std::vector<Gtk::Widget*>, std::list<Gtk::Widget*>, etc.
Glib::SListHandle<Gtk::Widget*>: Use std::vector<Gtk::Widget*>, std::list<Gtk::Widget*>, etc.

Mixing C and C++ APIs
You can use C APIs which do not yet have convenient C++ interfaces. It is generally not a problem to use C APIs from C++, and gtkmm helps by providing access to the underlying C object, and providing an easy way to create a C++ wrapper object from a C object, provided that the C API is also based on the GObject system.
To use a gtkmm instance with a C function that requires a C GObject instance, use the gobj() function to obtain a pointer to the underlying GObject instance. For instance

Gtk::Button* button = new Gtk::Button("example");
gtk_button_do_something_new(button->gobj());

To obtain a gtkmm instance from a C GObject instance, use the Glib::wrap() function. For instance

GtkButton* cbutton = get_a_button();
Gtk::Button* button = Glib::wrap(cbutton);

Hello World in gtkmm
We've now learned enough to look at a real example. In accordance with an ancient tradition of computer science, we now introduce Hello World, a la gtkmm:
Source Code
File: helloworld.h (For use with gtkmm 3, not gtkmm 2)

#ifndef GTKMM_EXAMPLE_HELLOWORLD_H
#define GTKMM_EXAMPLE_HELLOWORLD_H

#include <gtkmm/button.h>
#include <gtkmm/window.h>

class HelloWorld : public Gtk::Window
{

public:
  HelloWorld();
  virtual ~HelloWorld();

protected:
  //Signal handlers:
  void on_button_clicked();

  //Member widgets:
  Gtk::Button m_button;
};

#endif // GTKMM_EXAMPLE_HELLOWORLD_H

File: main.cc (For use with gtkmm 3, not gtkmm 2)

#include "helloworld.h"
#include <gtkmm/application.h>

int main (int argc, char *argv[])
{
  Glib::RefPtr<Gtk::Application> app = Gtk::Application::create(argc, argv, "org.gtkmm.example");

  HelloWorld helloworld;

  //Shows the window and returns when it is closed.
  return app->run(helloworld);
}

File: helloworld.cc (For use with gtkmm 3, not gtkmm 2)

#include "helloworld.h"
#include <iostream>

HelloWorld::HelloWorld()
: m_button("Hello World")   // creates a new button with label "Hello World".
{
  // Sets the border width of the window.
  set_border_width(10);

  // When the button receives the "clicked" signal, it will call the
  // on_button_clicked() method defined below.
  m_button.signal_clicked().connect(sigc::mem_fun(*this,
              &HelloWorld::on_button_clicked));

  // This packs the button into the Window (a container).
  add(m_button);

  // The final step is to display this newly created widget...
  m_button.show();
}

HelloWorld::~HelloWorld()
{
}

void HelloWorld::on_button_clicked()
{
  std::cout << "Hello World" << std::endl;
}

Try to compile and run it before going on. You should see something like this:

Hello World
Pretty thrilling, eh? Let's examine the code. First, the HelloWorld class:

class HelloWorld : public Gtk::Window
{

public:
  HelloWorld();
  virtual ~HelloWorld();

protected:
  //Signal handlers:
  virtual void on_button_clicked();

  //Member widgets:
  Gtk::Button m_button;
};

This class implements the "Hello World" window. It's derived from Gtk::Window, and has a single Gtk::Button as a member. We've chosen to use the constructor to do all of the initialisation work for the window, including setting up the signals. Here it is, with the comments omitted:

HelloWorld::HelloWorld()
:
  m_button ("Hello World")
{
  set_border_width(10);
  m_button.signal_clicked().connect(sigc::mem_fun(*this,
    &HelloWorld::on_button_clicked));
  add(m_button);.
  m_button.show();
}

Notice that we've used an initialiser statement to give the m_button object the label "Hello World".
Next we call the Window's set_border_width() method. This sets the amount of space between the sides of the window and the widget it contains.
We then hook up a signal handler to m_button's clicked signal. This prints our friendly greeting to stdout.
Next, we use the Window's add() method to put m_button in the Window. (add() comes from Gtk::Container, which is described in the chapter on container widgets.) The add() method places the Widget in the Window, but it doesn't display the widget. gtkmm widgets are always invisible when you create them - to display them, you must call their show() method, which is what we do in the next line.
Now let's look at our program's main() function. Here it is, without comments:

int main(int argc, char** argv)
{
  Glib::RefPtr<Gtk::Application> app = Gtk::Application::create(argc, argv, "org.gtkmm.example");

  HelloWorld helloworld;
  return app->run(helloworld);
}

First we instantiate an object stored in a RefPtr smartpointer called app. This is of type Gtk::Application. Every gtkmm program must have one of these. We pass our command-line arguments to its create() method. It takes the arguments it wants, and leaves you the rest, as we described earlier.
Next we make an object of our HelloWorld class, whose constructor takes no arguments, but it isn't visible yet. When we call Gtk::Application::run(), giving it the helloworld Window, it shows the Window and starts the gtkmm event loop. During the event loop gtkmm idles, waiting for actions from the user, and responding appropriately. When the user closes the Window, run() will return, causing the final line of our main() function be to executed. The application will then finish.