-------------------------------------------------------------------------------
Notes on using .glade layout files for the libglade version of the GTK2 client
-------------------------------------------------------------------------------

1) The GTK V2 client uses two different Glade Designer XML files.  The first
   describes the client's main game window, and the second describes all of
   the other dialogs that the client uses.  The default XML layouts are
   defined in the main.h header file, but one or both may be specified with
   command-line arguments.

   At the time of this writing, the default window is defined by gtk-v2.glade
   and the common dialogs are defined in dialogs.glade.

2) To launch the GTK V2 client and use of a different layout template, start
   the client with a command similar to the following example.

     crossfire-client-gtk2 -window_xml /path/to/layout.glade

   If something does not work as expected, be sure to start the client from a
   console window.  The client will report informational and error messages.

   To specify a different common dialog XML file, append an additional
   argument on the command-line:

     -dialog_xml /path/to/dialogs.glade

   Presently there are no alternative dialog files supplied with the project.

3) If the -window_xml parameter is not accepted, the client is an old client
   that does not support libglade.  This could happen if a recent client is
   compiled but the system does not have the libglade-2.0 libraries on it.
   Check the output of ./configure.  It may report that the gtk-v2 client will
   not be built.  If this happens, the client on the system will be an old one
   with a date and time that do not correspond to the current build.

4) As of SVN revision 8406, crossfire-client-gtk2 saves window position data in
   a file named per the layout instead of the legacy file ~/crossfire/gwinpos2.
   For example, if a player saves window positions while using gtk-v2.glade,
   they will be stored in ~/.crossfire/gtk-v2.pos, but if playing with a layout
   called caelestis.glade, they will be saved in caelestis.pos.  This means the
   client is able to remember saved sizes for each layout individually.

5) The first time a layout is used, the ~/.crossfire/<layoutname>.pos file will
   not exist so the client will use default sizes that were defined inside the
   <layoutname>.glade file at design time.  This means that as long as the
   defaults are smaller than the desktop, the client window should be laid out
   nicely.

   If, however, the desktop size is smaller than the default sizes, the client
   may look bad, and it may be tricky to find the size bars if panes overlap.
   With patience, they may be found and used to size the client panes better.
   Use the Client Save Window Position command to save the adjustments.  They
   will be used to restore the saved settings the next time the client is
   started.

   If the desktop is smaller than it was last time the .pos file was created,
   it is possible that the saved positions are no good.  In this case, it may
   be wise to delete the .pos file and try out the default settings.


-------------------------------------------------------------------------------
Notes about designing .glade files for the libglade version of the GTK2 client
-------------------------------------------------------------------------------

1) All windows that should not be initially displayed when the application
   starts must have the "visible" property set to "no".  This property is on
   the "Common" tab.

   The following windows should not be initially visible:

     metaserver_window
     keybinding_window
     msgctrl_window
     config_window
     spell_window
     skill_window
     about_window

   Reference:

     http://developer.gnome.org/doc/API/2.0/libglade/libglade-embedding.html

   IMPORTANT:

   The root window "visible" property must also be set to "no" in order for
   saved screen size settings to be restorable when the application starts up.
   This really means that all dialogs and windows should be set as not visible.

2) All hpane and vpane resizeable widgets that need to be saved when the user
   selects Client | Save Window Position should have a name that begins with
   either "hpaned_" or "vpaned_".  The client will only save window positions
   for the widgets named in this way (this is the default naming convention
   used by the Glade Designer application).

3) Set all hpaned and vpaned size bars to result in a default layout that has
   a decent appearance.  It is not sufficient to have the layout look good in
   the layout designer.  You must verify that the Position property on the
   Widget tab is set and that it's checkbox is checked.  Also see note 11 for
   another important tip regarding setting the size of widgets.

4) When creating tabbed notebooks be sure the first tab is the tab that should
   be visible when the client starts up or when the dialog is first displayed.

5) Most layouts may be altered by creatively cut/pasting elements.  Do not use
   copy/paste, as that will cause the widgets to be renamed.

6) The inventory icon pane is an excellent "temporary" holding area that may
   be used to hold widgets while other areas of the layout are being worked
   on.

7) More complex changes may be made by temporarily expanding the outer vbox
   container and using the bottom rows to paste things into.  Be careful when
   reducing it back to the original size.  Glade Designer deletes the bottom
   layers first, even if there are empty ones in the middle.  Any widgets in
   the removed layer are lost.

8) Save periodically, and keep working copies.  It is very easy to ruin a
   layout so that it is hard to return to a proper state, and widget errors
   may cause the client to crash at run-time when it is most inconvenient.

   Oddly, there is not a Save As menu item in the Glade Designer tool.  Even
   so, it is possible to save your design as a different file to prevent
   overwriting the last good save.  Use Project | Options... | Project File:
   to pick a new name.  After change the name there, File | Save will save
   to the new file name without overwriting the file that was originally
   opened.

9) When adding a combo box that is to be dynamically filled at run-time, be
   absolutely sure to press the ellipsis "..." button next to the empty Items:
   box, then press the OK button on the Edit Text Property dialog.  This
   causes the XML file combo box definition to contain an essential property:

     <property name="items" translatable="yes"></property>

   Without this property, at run-time the following code snippet will set
   model to NULL.

     model = gtk_combo_box_get_model(GTK_COMBO_BOX(config_combobox_theme));
     count =  gtk_tree_model_iter_n_children(model, NULL);

   This construct is used several times in config.c's setup_config_window().
   When model is NULL, the subsequent code that attempts to use the model
   generates console errors like:

     (crossfire-client-gtk2:9632): Gtk-CRITICAL **:
     gtk_tree_model_iter_n_children: assertion `GTK_IS_TREE_MODEL (tree_model)'
     failed

     (crossfire-client-gtk2:9632): Gtk-CRITICAL **: gtk_combo_box_append_text:
     assertion `GTK_IS_LIST_STORE (combo_box->priv->model)' failed

     (crossfire-client-gtk2:9632): Gtk-CRITICAL **: gtk_combo_box_append_text:
     assertion `GTK_IS_LIST_STORE (combo_box->priv->model)' failed

     (crossfire-client-gtk2:9632): Gtk-CRITICAL **: gtk_combo_box_append_text:
     assertion `GTK_IS_LIST_STORE (combo_box->priv->model)' failed

     (crossfire-client-gtk2:9632): Gtk-CRITICAL **:
     gtk_tree_model_iter_n_children: assertion `GTK_IS_TREE_MODEL (tree_model)'
     failed

10) The Magic Map page in map_notebook must be the second tab to maintain
    compatibility with the client's standard main.h define "MAGIC_MAP_PAGE 1".
    The page/tab number is zero-based, so "1" corresponds to the second tab.

11) In general, do not set widget Width and Height properties on the Common
    tab in the Glade Designer.  This is in effect placing a size request for
    the widget, and can prevent the player from sizing the widget smaller than
    the size set at design time.  This is especially important with respect to
    the map and magic map drawing areas, tables, treeviews, and other large UI
    elements (hboxes, vboxes, notebooks, etc).  A player should generally have
    the freedom to make a widget smaller than it was originally designed in
    the layout.

    Note, though, that this is not a hard and fast rule.  Sometimes setting a
    size is very helpful.  For example, in the GTK V1 layout (and a few others)
    progressbars are set to use a smaller height dimension size than their
    default.  Since a player never expects to be able to set the thickness of
    the bar, setting that dimension is useful to attain a particular look (I.E.
    make the progressbar more compact).

12) All dialogs defined in dialogs.glade should have their Deletable property
    set to "No" in the XML (done while working in the Glade-3 designer).  This
    tells window managers not to put an [X] close icon on the window frame.
    Without this, the [X] close deletes the dialog so it cannot be resurrected
    without restarting the client.  In some cases a segmentation fault occurs
    and the client crashes.  To cover cases where certain window managers do
    not honor the GTK Deletable property, connect the delete_event for each
    dialog to gtk_widget_hide_on_delete() in the C code.  For example:

        g_signal_connect((gpointer) about_window, "delete_event",
            G_CALLBACK(gtk_widget_hide_on_delete), NULL);


-------------------------------------------------------------------------------
Other Helpful Hints
-------------------------------------------------------------------------------

1) Sometimes when making significant layout changes or when glade misbehaves
   and does not let you visually see an select an empty cell (vboxes have been
   noted as problematic if an empty cell is bounded by two cells with content).
   When this happens, it is quite possible to use a text editor to move items
   into the empty cell.  Naturally you have to be able to look at the XML
   structure to know how to keep it intact.  Make backups before making
   manual edits.

2) When editing .glade files by hand, use of a text editor that is capable of
   collapsing XML structures is recommended.  Even without such and editor, it
   can be handle to use a browser alongside the editor.  To do so, make a copy
   of the .glade file, but save it with a .xml extension, and then open it in
   FireFox or another XML-aware browser.  Use the expand/collapse features to
   learn or reveal the structure of the XML.
