GGZ Gaming Zone for KDE 4 - Tutorial 1
--------------------------------------

This is the first of the three tutorials about the kggz* libraries
in libkdegames, and it covers the kggzmod library.

What kggzmod is used for is to connect your game to the gaming zone, to
let it receive information about the players and spectators and scores,
and to let it submit requests to change the seat configuration or similarly.
It doesn't do anything else, in particular it doesn't let your game client
communicate with your game server. There are other libraries for this task,
some of them being part of kggznet.
The kggzmod library also doesn't offer graphical interfaces to display
the information or let the user modify anything - this would be the task of
the kggzgames library.
Therefore, kggzmod is a non-graphical base component for GGZ integration
of game clients.

KGGZMod::Module
---------------

Strictly spoken, this is the only class in kggzmod which must be known by
the game author. There are other classes, but some are used by kggzgames
on its own and some are only necessary for advanced features, so implementing
everything which KGGZMod::Module has to offer is already all of the work
for good GGZ integration.

A module object should only be created if the game runs in GGZ mode. The
static method ::isGGZ() can be used to check for this condition.
A module will offer two signals, one for data from the game server and one
for errors which might happen anywhere. Therefore, a good initialisation
code looks like:

void initMultiplayer()
{
  if(KGGZMod::Module::isGGZ())
  {
    KGGZMod::Module *mod = new KGGZMod::Module("mygame");
    connect(mod, SIGNAL(signalError()), SLOT(slotError()));
    connect(mod, SIGNAL(signalNetwork(int)), SLOT(slotNetwork(int)));
  }
}

Advanced usage is possible by also connecting the signalEvent() signal,
which will deliver a KGGZMod::Event object which might be casted to more
specialised KGGZMod::FooEvent objects. The module object also allows to
print out information about the player via ::self() or about other players
via ::players(), the first one being a KGGZMod::Player* object and the
second one being a list of them which contains oneself.

In order to finish GGZ mode, simply delete the KGGZMod::Module::instance()
object.

One word about the parameter to the constructor: Right now, this is a
meaningless string somehow related to the name of the game. In the future, we
want this to refer to the *.dsc file (see tutorial 0) so we can make the game
self-aware of its own version number and features. The API for this hasn't
been decided on yet.