add more details for doxygen

svn path=/trunk/; revision=11107

1 files changed, 58 insertions, 26 deletions

diff --git a/gtk/ui_util.h b/gtk/ui_util.h
index fc2e876582..55800f3844 100644
--- a/gtk/ui_util.h
+++ b/gtk/ui_util.h
@@ -1,7 +1,7 @@
 /* ui_util.h
  * Definitions for UI utility routines
  *
- * $Id: ui_util.h,v 1.13 2004/06/01 20:28:05 ulfl Exp $
+ * $Id: ui_util.h,v 1.14 2004/06/04 17:16:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -25,47 +25,77 @@
 #ifndef __GTKGUIUI_UTIL_H__
 #define __GTKGUIUI_UTIL_H__
 
-
-/** @file 
- * Utilities for Windows and other user interface functions.
+/** @defgroup windows_group Windows
  *
- * Some words about windows / dialogs.
- * 
- * delete event: the window managers "X" (e.g. upper right edge) of the window 
- *   was clicked, default handler will call gtk_widget_destroy()
- * destroy event: everything is already gone, only cleanup of left over ressources
- *   can/should be done now
+ * There are the following toplevel windows:
  *
- * Hint: don't use WIDGET_SET_SIZE() to set the size of a window,
- * use gtk_window_set_default_size() for that purpose!
+ * - @ref main_window_group
+ * - Statistic Windows (several different statistic windows)
  *
- * be sure, to call window_present() / window_destroy() appropriately, if you 
- *   want to have size and position handled by ui_util
+ * See: @ref howto_window_page for details.
+ * 
+ */
+
+/** @page howto_window_page How to develop a window / dialog
  *
- * A typical window / dialog will be created by:
+ * Windows and dialogs are related to each other. Dialogs are special kind of windows, but they behave
+ * slightly different. Dialogs stick on it's parent window, normal windows will be much more independant
+ * from it's parent window. Dialogs should be used to ask or note the user something, while windows should
+ * show data independantly from the main window.
+ * Dialogs are created by calling dlg_window_new() which in turn will call window_new().
+ * After that, dialogs can be developed the same way as windows, all window related functions in ui_util.h 
+ * can be used for both.
  *
- * window_new() will create a new window with default position and size,
- *   use dlg_window_new() if you need a dialog (transient to the main window)
+ * @section window_create Create a window
  *
- * gtk_window_set_default_size() to set the default size of the window, only
- *   needed, if the initial size is not appropriate, e.g. a scrolled_window_new() is used
- *   be sure the given is larger than the initial size, otherwise might get clipped content on GTK1
+ * A typical window / dialog will be created by the following calls:
  *
- * SIGNAL_CONNECT(my_win, "destroy", my_destroy_cb, NULL) callback, if some cleanup needs to be 
+ * - window_new() will create a new window with default position and size,
+ *   use dlg_window_new() if you need a dialog (transient to the main window)
+ * - gtk_window_set_default_size() to set the default size of the window. Only
+ *   needed, if the initial size is not appropriate, e.g. when a scrolled_window_new() is used.
+ *   Be sure that the given size is larger than the initial size, otherwise the window might
+ *   clip the content (at least on GTK1)
+ * - SIGNAL_CONNECT(my_win, "destroy", my_destroy_cb, NULL) callback, if some cleanup needs to be 
  *   done after the window is destroyed, e.g. free up memory, or set the window pointer
  *   of a singleton window (only one instance allowed, e.g. about dialog) back to zero
+ * - create and fill in the content and button widgets
+ * - gtk_widget_show_all() shows all the widgets in the window
+ * - window_present() present the window on screen and 
+ *   (if available) set previously saved position and size
  *
- * create and fill in the content and button widgets
+ * @section window_events Events
  *
- * gtk_widget_show_all() show all the widgets in the window
+ * The following events are usually interesting:
  *
- * window_present() present the window on screen and 
- *   (if available) set previously saved position and size
+ * - "delete_event": the window managers "X" (e.g. upper right edge) of the window 
+ *   was clicked, default handler will call gtk_widget_destroy()
+ * - "destroy": everything is already gone, only cleanup of left over ressources
+ *   can/should be done now
+ *
+ * @section window_hints Hints
  *
- * if you want to save size and position, be sure to call window_destroy() instead of only 
+ * If you want to save size and position, be sure to call window_destroy() instead of only 
  *   gtk_widget_destroy(), so you will probably have to SIGNAL_CONNECT to the "delete_event"!
+ *
+ * Don't use WIDGET_SET_SIZE() to set the size of a window,
+ * use gtk_window_set_default_size() for that purpose!
+ *
+ * Be sure to call window_present() / window_destroy() appropriately, if you 
+ *   want to have size and position of the window handled by ui_util.
+ *
+ */
+
+/** @file 
+ * Utilities for Windows and other user interface functions. See: @ref howto_window_page for details.
+ * @ingroup dialog_group
+ * @ingroup windows_group
  */
 
+/** @name Window Functions
+ *  @todo Move these window functions to a new file win_utils.h?
+ *  @{ */
+
 /** Create a new window with the Ethereal icon. 
  *  If you want to create a dialog, use dlg_window_new() instead. 
  *
@@ -178,6 +208,8 @@ extern void window_geom_recent_read_pair(const char *name, const char *key, cons
  */
 void reactivate_window(GtkWidget *win);
 
+/** @} */
+
 /** Create a GtkScrolledWindow, set its scrollbar placement appropriately,
  *  and remember it.
  *