gtk/gui_utils.h

   1 /* gui_utils.h
   2  * Declarations of GTK+-specific UI utility routines
   3  *
   4  * $Id$
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23  */
  24
  25 #ifndef __GTKGUIUI_UTIL_H__
  26 #define __GTKGUIUI_UTIL_H__
  27
  28 /** @defgroup windows_group Windows
  29  *
  30  * There are the following toplevel windows:
  31  *
  32  * - @ref main_window_group
  33  * - Statistic Windows (several different statistic windows)
  34  *
  35  * See: @ref howto_window_page for details.
  36  *
  37  */
  38
  39 /** @page howto_window_page How to develop a window / dialog
  40  *
  41  * Windows and dialogs are related to each other. Dialogs are special kind of windows, but they behave
  42  * slightly different. Dialogs stick on it's parent window, normal windows will be much more independant
  43  * from it's parent window. Dialogs should be used to ask or note the user something, while windows should
  44  * show data independantly from the main window.
  45  * Dialogs are created by calling dlg_window_new() which in turn will call window_new().
  46  * After that, dialogs can be developed the same way as windows, all window related functions in gui_utils.h
  47  * can be used for both.
  48  *
  49  * @section window_create Create a window
  50  *
  51  * A typical window / dialog will be created by the following calls:
  52  *
  53  * - window_new() will create a new window with default position and size,
  54  *   use dlg_window_new() if you need a dialog (transient to the main window)
  55  * - gtk_window_set_default_size() to set the default size of the window. Only
  56  *   needed, if the initial size is not appropriate, e.g. when a scrolled_window_new() is used.
  57  *   Be sure that the given size is larger than the initial size, otherwise the window might
  58  *   clip the content (at least on GTK1)
  59  * - SIGNAL_CONNECT(my_win, "destroy", my_destroy_cb, NULL) callback, if some cleanup needs to be
  60  *   done after the window is destroyed, e.g. free up memory, or set the window pointer
  61  *   of a singleton window (only one instance allowed, e.g. about dialog) back to zero
  62  * - create and fill in the content and button widgets
  63  * - gtk_widget_show_all() shows all the widgets in the window
  64  * - window_present() present the window on screen and
  65  *   (if available) set previously saved position and size
  66  *
  67  * @section window_events Events
  68  *
  69  * The following events are usually interesting:
  70  *
  71  * - "delete_event": the window managers "X" (e.g. upper right edge) of the window
  72  *   was clicked, default handler will call gtk_widget_destroy()
  73  * - "destroy": everything is already gone, only cleanup of left over ressources
  74  *   can/should be done now
  75  *
  76  * @section window_hints Hints
  77  *
  78  * If you want to save size and position, be sure to call window_destroy() instead of only
  79  *   gtk_widget_destroy(), so you will probably have to SIGNAL_CONNECT to the "delete_event"!
  80  *
  81  * Don't use WIDGET_SET_SIZE() to set the size of a window,
  82  * use gtk_window_set_default_size() for that purpose!
  83  *
  84  * Be sure to call window_present() / window_destroy() appropriately, if you
  85  *   want to have size and position of the window handled by ui_util.
  86  *
  87  */
  88
  89 /** @file
  90  * Utilities for Windows and other user interface functions. See: @ref howto_window_page for details.
  91  * @ingroup dialog_group
  92  * @ingroup windows_group
  93  */
  94
  95 /** @name Window Functions
  96  *  @todo Move these window functions to a new file win_utils.h?
  97  *  @{ */
  98
  99 /** Create a new window with the Wireshark icon.
 100  *  If you want to create a dialog, use dlg_window_new() instead.
 101  *
 102  * @param type window type, typical GTK_WINDOW_TOPLEVEL
 103  * @param title the title for the new window
 104  * @return the newly created window
 105  */
 106 extern GtkWidget *window_new(GtkWindowType type, const gchar *title);
 107
 108 /** Same as window_new(), but will keep its geometry values (size, position, ...).
 109  *  Be sure to use window_present() and window_destroy() appropriately!
 110  *
 111  * @param type window type, typical GTK_WINDOW_TOPLEVEL
 112  * @param title the title for the new window
 113  * @param geom_name the name to distinguish this window, will also be used for the recent file (don't use special chars)
 114  * @return the newly created window
 115  */
 116 extern GtkWidget *window_new_with_geom(GtkWindowType type, const gchar *title, const gchar *geom_name);
 117
 118 /** Create a new splash window, with no icon or title bar.
 119  *
 120  * @return the newly created window
 121  */
 122 extern GtkWidget *splash_window_new(void);
 123
 124 /** Present the created window on the top of the screen. This will put the window on top and
 125  * (if available) set previously saved position and size.
 126  *
 127  * @param win the window from window_new()
 128  */
 129 extern void window_present(GtkWidget *win);
 130
 131 /** callback function for window_set_cancel_button() */
 132 typedef void (*window_cancel_button_fct) (GtkWidget *w, gpointer data);
 133
 134 /** Register the default cancel button "Cancel"/"Close"/"Ok" of this window.
 135  *  This will set the callback function for this button, grab this button as the default one and
 136  *  set the "ESC" key handler to call the callback function if key is pressed.
 137  *
 138  * @param win the window from window_new()
 139  * @param bt the default button of this window
 140  * @param cb callback function to be called, when this button is pressed
 141  */
 142 extern void window_set_cancel_button(GtkWidget *win, GtkWidget *bt, window_cancel_button_fct cb);
 143
 144 /** Remember the current window position / size and then destroy the window.
 145  *  It's important to call this instead of gtk_widget_destroy() when using window_new_with_geom().
 146  *
 147  * @param win the window from window_new()
 148  */
 149 extern void window_destroy(GtkWidget *win);
 150
 151 /** Default callback handler for cancel button "clicked" signal.
 152  *  Use this for window_set_cancel_button(), if no user specific functionality required,
 153  *  will simply call window_destroy()
 154  */
 155 extern void window_cancel_button_cb(GtkWidget *w _U_, gpointer data);
 156
 157 /** Default callback handler if the window managers X of the window was clicked (delete_event).
 158  *  Use this for SIGNAL_CONNECT(), if no user specific functionality required,
 159  *  will simply call window_destroy()
 160  */
 161 extern gboolean window_delete_event_cb(GtkWidget *win, GdkEvent *event _U_, gpointer user_data _U_);
 162
 163 /** geometry values for use in window_get_geometry() and window_set_geometry() */
 164 typedef struct window_geometry_s {
 165     gchar       *key;           /**< current key in hashtable (internally used only) */
 166     gboolean    set_pos;        /**< set the x and y position values */
 167     gint        x;              /**< the windows x position */
 168     gint        y;              /**< the windows y position */
 169     gboolean    set_size;       /**< set the width and height values */
 170     gint        width;          /**< the windows width */
 171     gint        height;         /**< the windows height */
 172
 173     gboolean    set_maximized;  /**< set the maximized state (GTK2 only) */
 174     gboolean    maximized;      /**< the windows maximized state (GTK2 only) */
 175 } window_geometry_t;
 176
 177 /** Get the geometry of a window.
 178  *
 179  * @param win the window from window_new()
 180  * @param geom the current geometry values of the window, the set_xy values will not be used
 181  * @todo if main uses the window_new_with_geom() to save size and such, make this function static
 182  */
 183 extern void window_get_geometry(GtkWidget *win, window_geometry_t *geom);
 184 /** Set the geometry of a window.
 185  *
 186  * @param win the window from window_new()
 187  * @param geom the new geometry values of the window
 188  * @todo if main uses the window_new_with_geom() to save size and such, make this function static
 189  */
 190 extern void window_set_geometry(GtkWidget *win, window_geometry_t *geom);
 191
 192 /** Write all geometry values of all windows to the recent file.
 193  * Will call write_recent_geom() for every existing window type.
 194  *
 195  * @param rf recent file handle from caller
 196  */
 197 extern void window_geom_recent_write_all(gpointer rf);
 198
 199 /** Read in a single geometry key value pair from the recent file.
 200  *
 201  * @param name the geom_name of the window
 202  * @param key the subkey of this pair (e.g. "x")
 203  * @param value the new value (e.g. "123")
 204  */
 205 extern void window_geom_recent_read_pair(const char *name, const char *key, const char *value);
 206
 207 /** Raise a top-level window and de-iconify it.
 208  *  This routine is used if the user has done something to
 209  *  ask that a window of a certain type be popped up when there can be only
 210  *  one such window and such a window has already been popped up - we
 211  *  pop up the existing one rather than creating a new one.
 212  *
 213  * @param win the window from window_new() to be reactivated
 214  */
 215 extern void reactivate_window(GtkWidget *win);
 216
 217 /** @} */
 218
 219 /** Create a GtkScrolledWindow, set its scrollbar placement appropriately,
 220  *  and remember it.
 221  *
 222  * @param hadjustment horizontal adjustment
 223  * @param vadjustment vertical adjustment
 224  * @return the new scrolled window
 225  */
 226 extern GtkWidget *scrolled_window_new(GtkAdjustment *hadjustment,
 227                                GtkAdjustment *vadjustment);
 228
 229 /** Set the scrollbar placement of all scrolled windows based on user
 230    preference. */
 231 extern void set_scrollbar_placement_all(void);
 232
 233 #if GTK_MAJOR_VERSION < 2
 234 /** Create a GtkCTree, give it the right styles, and remember it.
 235  *
 236  * @param columns the number of columns
 237  * @param tree_column which column has the tree graphic
 238  * @return the newly created GtkCTree
 239  */
 240 extern GtkWidget *ctree_new(gint columns, gint tree_column);
 241 /** Create a GtkCTree, give it the right styles, and remember it.
 242  *
 243  * @param columns the number of columns
 244  * @param tree_column which column has the tree graphic
 245  * @param titles the titles of all columns
 246  * @return the newly created GtkCTree
 247  */
 248 extern GtkWidget *ctree_new_with_titles(gint columns, gint tree_column,
 249                                  const gchar *titles[]);
 250 #else
 251 /** Create a GtkTreeView, give it the right styles, and remember it.
 252  *
 253  * @param model the model (the data) of this tree view
 254  */
 255 extern GtkWidget *tree_view_new(GtkTreeModel *model);
 256 #endif
 257
 258 /** Create a simple list widget.
 259  *
 260  * @param cols number of columns
 261  * @param titles the titles of all columns
 262  * @return the new simple list widget
 263  */
 264 extern GtkWidget *simple_list_new(gint cols, const gchar **titles);
 265 /** Append a row to the simple list.
 266  *
 267  * @param list the list from simple_list_new()
 268  * @param ... row and title, finished by -1 (e.g.: 0, "first", 1, "second", -1).
 269  */
 270 extern void simple_list_append(GtkWidget *list, ...);
 271
 272
 273
 274 /** Set the styles of all Trees based upon user preferences. */
 275 extern void set_tree_styles_all(void);
 276
 277 /** Convert an xpm picture into a GtkWidget showing it.
 278  * Beware: Wireshark's main window must already be visible!
 279  *
 280  * @param xpm the character array containing the picture
 281  * @return a newly created GtkWidget showing the picture
 282  */
 283 extern GtkWidget *xpm_to_widget(const char ** xpm);
 284
 285 /** Convert an xpm picture into a GtkWidget showing it.
 286  * Beware: the given parent window must already be visible!
 287  *
 288  * @param parent the parent window of to widget to be generated
 289  * @param xpm the character array containing the picture
 290  * @return a newly created GtkWidget showing the picture
 291  */
 292 extern GtkWidget *xpm_to_widget_from_parent(GtkWidget *parent, const char ** xpm);
 293
 294 /** Create a new hbox with an image packed into it
 295  * and return the box.
 296  *
 297  * @param xpm the character array containing the picture
 298  * @return a newly created GtkHBox containing the picture
 299  */
 300 GtkWidget *xpm_box( gchar **xpm );
 301
 302 /** Copy a GString to the clipboard.
 303  *
 304  * @param str GString that is to be copied to the clipboard.
 305  */
 306 extern void copy_to_clipboard(GString *str);
 307
 308 /** Create a new window title that includes user-defined preference string.
 309  *
 310  * @param caption string you want included in title (appended to user-defined string)
 311  * @return a newly created title string including user-defined preference (if specified)
 312  */
 313 extern gchar *create_user_window_title(const gchar *caption);
 314
 315
 316 #endif /* __GTKGUIUI_UTIL_H__ */