Table of Contents
-----------------
1. Overview
2. Introduction
3. Multiple servers and/or accounts
4. Automatic game state checking
5. Manual game state checking
6. Menu item click action
7. Menubar icon animation
8. Appearance in the menubar
9. Why don't I have to enter a password?


Overview
--------
This document contains a detailed description of the features of dgsmonX.

- The first section "Introduction" provides a short overview of dgsmonX' user
  interface and the first configuration steps you must perform before dgsmonX
  becomes useful
- The following sections go into more detail on certain configuration and usage
  aspects of dgsmonX
- The last section explains why dgsmonX does not need your password


Introduction
------------
dgsmonX monitors the games you have joined on one or more Dragon Go Servers
(DGS) and alerts you when it is your turn to move in any of these games.
Naturally you do not want to be bothered when it is *not* your turn - which will
probably be most of the time that dgsmonX is running. dgsmonX therefore tries to
be as unobtrusive as possible, staying in the background while it has nothing
to report, and coming to the fore only when it needs to notify you.

To achieve its goal of being inconspicuous, dgsmonX has been designed as a
faceless application. This means that when it is launched, it will not appear in
the Dock as normal applications do when they are started, nor does it display
an application window while it is running. All this with the purpose not to
clutter your desktop or take away screen estate from other, more important
applications that you are working with. The only clue you have that dgsmonX is
running is when you see its icon appear somewhere on the right-hand side of the
system menubar.

The system menubar icon serves two purposes:

1. When dgsmonX detects that it is your turn to move in any of the games that it
   is monitoring, it animates the menubar icon in a more or less annoying
   fashion so as to catch your attention.

2. When you click the menubar icon, a menu pops up which gives you access to
   dgsmonX's functions. These will be discussed in detail in the next sections.
   For now it is enough to say that the menu contains an item that you can use
   to configure dgsmonX, and one item that you can use to quit dgsmonX.

Before dgsmonX can do anything for you, you must tell it which Dragon Go Server
it should monitor for you, and which user name it should use for its checks.

The following list guides you through the initial configuration, step-by-step:
- Launch the application.
- Click the dgsmonX menubar icon to pop up the application's main menu.
- Select the "Preferences..." menu item to display the Preferences window.
- Select the "Servers" tab.
- Click the "+" button to add a new Dragon Go Server.
- Configure the server as follows:
  - Correct the default server's name and/or URL if they do not match your
    desired server name and/or URL. New servers always point to the canonical
    installation http://www.dragongoserver.net/.
  - Enter your user ID.
  - Click the "Test" button to check if the details you entered work correctly.
    After a moment, a message box will pop up to tell you whether dgsmonX
    succeeded in connecting to the server. [Note: This feature is not yet
    implemented in the current version of dgsmonX, at the moment the "Test"
    button is therefore always disabled.]
  - When you are satisfied that the server configuration works, check the
    "Monitor this server" button. This activates periodic checking for this
    server.
- Click the "Close" button to hide the Preferences window.

From now on, the Dragon Go Server that you have just configured is being
monitored by dgsmonX. As described above, when it is your turn dgsmonX will
animate the menubar icon to catch your attention.

Should you no longer need the services of dgsmonX, select "Quit" from the
applications's main menu in order to terminate the application.


Multiple servers and/or accounts
--------------------------------
When you add new DGS entries in the Preferences window (you have seen in the
Introduction chapter how you can do this), they default to the URL of the
canonical Dragon Go Server installation on the Internet
(http://www.dragongoserver.net/). dgsmonX does not prevent you from changing
the URL, though. dgsmonX therefore is capable of monitoring *any* Dragon Go
Server installation reachable over the network. This might be useful, for
instance, if someone runs a local Dragon Go Server using the DGS software which
is freely available at SourceForge.net
(http://sourceforge.net/projects/dragongoserver/).

Since dgsmonX does not restrict how you configure DGS entries, you can also
have dgsmonX check multiple accounts on the same DGS installation.


Automatic game state checking
-----------------------------
dgsmonX performs automatic game state checks in regular intervals. The default
interval is 15 minutes. You can change the interval in the Preferences window
to anything you like, although you can never go below 1 second.

An automatic game state check always includes all configured Dragon Go Servers
for which you have enabled monitoring (a checkbox that you can set/unset in the
Preferences window). The first series of game state checks is performed as soon
as possible after the application is launched. The next series of checks is run
after the monitoring time interval has elapsed. Periodic checks continue until
the application terminates. If a series of checks is in progress at that time,
it is interrupted.

Checks are also interrupted when the Preferences window is about to be
displayed. In addition, no checks are triggered while the Preferences window is
displayed. These limitations exist mainly for technical reasons. To compensate,
a new series of checks is triggered immediately when the Preferences window is
closed and if one of the following is true:
- The monitoring interval since the last series of checks has elapsed
- The previous series of checks has been interrupted by displaying the
  Preferences window


Manual game state checking
--------------------------
All configured Dragon Go Servers are represented in the application's main menu
by a menu item. The menu item is greyed out if monitoring is disabled for the
item's DGS. Otherwise the menu item appears normal, and you can select it to
trigger an immediate manual game state check for the item's DGS. The special
menu item "Check all" triggers an immediate game state check for *all* Dragon
Go Servers.

Manual checks are cancelled in the same way as are automatic checks when the
Preferences window is about to be displayed. If manual checks were cancelled,
they are not re-run when the Preferences window is closed.


Menu item click action
----------------------
In the Preferences window there is an option that lets you choose what should
happen when you click a DGS menu item. The default behaviour is just as
described above in the section "manual game state checking", but if you prefer
you can change the click action to open the server's status page in your default
web browser.

For this to work your browser must have a valid login session (i.e. the login
cookie must be set) because dgsmonX does not know your password and therefore
cannot perform a login for you.


Menubar icon animation
----------------------
When dgsmonX detects that it is your turn to move in any of the games that it
is monitoring, it animates the menubar icon in a more or less annoying fashion
so as to catch your attention.

The animation is very simple: The regular menubar icon is alternated with a
different icon that indicates that it is your turn. The default interval for
switching between icons is 3 seconds. You may change this in the Preferences
window to make it more or less annoying (i.e. make the animation faster or
slower).

To stop the animation, you must click on the application's menubar icon. This
indicates to dgsmonX that you have seen the notification. As a side effect, the
application's main menu will pop up.


Appearance in the menubar
-------------------------
The area on the right-hand side of the system menubar is limited and
applications such as dgsmonX that represent themselves in this area must take
care not to consume too much space. By default dgsmonX therefore displays only
a small icon.

If on your system there is sufficient space in the menubar you change the
appearance of the dgsmonX status item in the dgsmonX Preferences window. Instead
of an icon you can display a (predefined) text, or you can display both icon and
text. In addition, if it is your turn you can have dgsmonX display the number of
games where it is your turn.


Why don't I have to enter a password?
-------------------------------------
It's quite simple: The Dragon Go Server software allows clients such as dgsmonX
to perform game state checks without providing a password. You can try this out
yourself: Use your web browser to navigate to the following URL:

  http://www.dragongoserver.net/quick_status.php?user=your-user-name

(adjust the URL so that it contains your user name, and possibly a different
DGS server location).

If you now think that everybody in the whole wide world can request information
about *your* games - well, you are 100% correct. The question is: How do other
people benefit from this information? Probably not much, or at least that's
what the developers of the Dragon Go Server software concluded when they
implemented quick_status.php.
