Chapter
2: Hello World

Hello World is a simple program that contains one widget: a button.
It's
the classic 'hello
world' example XFC style. The window displayed cannot be closed by the
window manager. Instead, it can only be closed by clicking the button.

HelloWorld::HelloWorld()
: Gtk::WidgetSignals(this)
{
// Sets the title of the window
set_title("Hello World");

// Set the default size of the
window
set_default_size(200, -1);

// Sets the border width of the window.
set_border_width(10);

// Creates a new button with the label "Hello World".
Gtk::Button *button = new Gtk::Button("Click me...");

// When the button receives the "clicked" signal, it
calls the on_hello() slot.
button->signal_clicked().connect(sigc::mem_fun(this,
&HelloWorld::on_hello));

// This will cause the window to be destroyed by
calling HelloWindow's inherited dispose method.
button->signal_clicked().connect(sigc::mem_fun(this,
&HelloWorld::dispose));

// This packs the button into the window (a
Gtk::Container).
add(*button);

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

HelloWorld::~HelloWorld()
{
}

bool
HelloWorld::on_delete_event(const Gdk::EventAny& event)
{
// When the window is given the "delete_event"
signal (this is given by the window manager,
// usually by the "close" option, or on the
titlebar), the on_delete_event() slot is called.
// If you return false a "destroy" signal is
emitted. Returning true means you don't want
// the window to be destroyed. This is useful for
popping up 'are you sure you want to quit?'
// type dialogs.
std::cout << "delete event occurred" <<
'\n';
return true;
}

Compiling Hello World

If you compiled and installed XFC yourself, you will find the source
code for Hello World in the
<examples/tutorial/chapter02> source directory along with a Makefile. If
XFC came pre-installed, or you installed it from an RPM package, you
will
find the source code in the
</usr/share/doc/xfcui-X.X/examples/tutorial/chapter02> subdirectory. In
this case you will have to create the Makefile yourself (replace X.X
with the
version number of the libXFCui library you have installed).

To create a Makefile for Hello World, add the following lines to a new
text file
and save it using the name "Makefile":

Stepping through the source code

Every program needs to include
the first header file. It provides access to library initialization
functions and the main event loop. The second
header file declares the Gtk::Window object and the
last header file declares Gtk::WidgetSignals, the virtual signal
handler class for Gtk::Widget. Next, a using statement is used to open the
Xfc:: namespace so that type names don't need to be prefixed with Xfc::

using namespace Xfc;

The HelloWorld class is derived from Gtk::Window and
Gtk::WidgetSignals. The
Gtk::Window inheritance path
looks like this:

HelloWorld redeclares the Gtk::WidgetSignalsvirtualon_delete_event()
handler so it can override its default
behaviour. Next,
it declares an on_hello() method that responds to button clicks.
The only other methods declared are the constructor and destructor.

Obviously, the "clicked" signal is emitted when the button is clicked
with the mouse
pointer. signal_clicked() is the proxy signal function for
Gtk::Button::clicked_signal.
You can connect more than one slot to a signal. Here we connect a
second slot that calls the window's inherited dispose() method so that
when the button is clicked our window is destroyed.

Just a brief word about dispose(). When you want
to destroy a widget you call dispose(). There is no destroy
method in XFC. The name dispose is used because it better reflects
what happens when a widget is destroyed. In GTK+ 2.0, when you ask for
a widget to be destroyed it may not be destroyed immediately.
Instead, it gets marked for destruction and is disposed of later when
its reference count drops to zero.

Next we make a packing call which that tells XFC that the button is to
be
placed
in the window where it will be displayed. Note that HelloWorld is also
a Gtk::Container and a container can only contain one widget. There
are other widgets, such as boxes and tables, which are designed to
layout multiple widgets in various ways.

add(*button);

The final step in the constructor is to display
the newly created
button by making it visible:

button->show();

The on_delete_event() handler is a
bit special. It's the
predefinedvirtual signal handler for the 'delete_event' signal. Adelete_event is occurs when the window manager sends this
event to the application. We
have a choice here as to what to do about these events. We can
ignore them, make some sort of response, or simply quit the
application. The value you return from this handler lets GTK+ know what
action to take. By returning true we let GTK+ know that we
don't
want to have the 'destroy_signal' emitted, keeping our
application running. By returning false, we ask that the
destroy_signal
be emitted.

on_delete_event() uses a C++ console output statement to
display the message "delete event occurred". It does this
by using the output operator <<. The << causes whatever
expression is on its right side to be output to the device on the left.
'cout'
is the predefined identifier that stands for console output and refers
to the computer screen. To use cout in your program you include the
C++ header file <iostream>.

Next is the slot method that will be called when the button is clicked.
It uses a C++ console output statement to display the message "Hello
World" on the screen:

I assume you know about the main() function. As with other
applications, all XFC applications must have
one of these:

int
main(int argc, char
*argv[]);

After the initial using statementthe first line of
code calls init() to initializes the toolkit:

init(&argc, &argv);

This function initializes
the library for use, sets up default signal handlers, and checks the
arguments passed to your application on the command line, looking for
one of the following:

--gtk-module

--g-fatal-warnings

--gtk-debug

--gtk-no-debug

--gdk-debug

--gdk-no-debug

--display

--sync

--name

--class

Any argument it recognizes is removed from the list, and 'argc' and
'argv' are modified to make it look like the argument never existed,
allowing your
application to parse the remaining arguments.

Next, an instance of HelloWindow is created on the stack.

HelloWorld
window;

The Xfc::Main::quit()function causes the program to end.
This function tells GTK+ that it is to exit from the main event loop
when
control is returned to it. There is no need to write a method that
calls
this function. Instead, we simply generate a slot for it and connect
that slot to our main window's destroy signal. The next line
accomplishes this:

window.signal_destroy().connect(sigc::ptr_fun(&Xfc::Main::quit));

The window widget is shown last so
the whole window will pop up at
once rather than seeing the window pop up, and then the button form
inside of it. Although with such a simple example, you'd never notice.

window.show();

And of course, we call run() to start the main processing
loop
which then waits for events to come from the X server.

run();

And the final return. Control returns
here after Xfc::Main::quit() is called.

return 0;

When you click the mouse on a XFC button, the widget emits a 'clicked'
signal. In order for us to use this information, XFC sets up the
Gtk::Button 'clicked_signal' signal to catch that signal and dispatch
it
to any connected slots. In our example, when the button we created
is clicked, theon_hello() method is called first and then
the
window's inherited Gtk::Object::dispose()
method which destroys the window. This causes the window to
emit the "destroy"signal, which is caught by its Gtk::Object'destroy_signal', which calls Xfc::Main::quit(), which
simply exits.

Another course of events is to use the window manager to kill the
window, which will cause the 'delete_event' to be emitted. This
is caught by the Gtk::Window 'delete_event_signal' which calls our
on_delete_event()
method. If we return true here, the window will be left as is
and nothing will happen. Returning false will cause GTK+ to
emit
the 'destroy' signal which of course calls Xfc::Main::quit().

The next chapter
takes you through building another XFC application: Hello Buttons, an
enhanced version of Hello World which uses a packing box to add two
button widgets to a main window.