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 __GUI_UTILS_H__
  26 #define __GUI_UTILS_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. A dialog sticks on its parent window; A normal window will be much more independent
  43  * from its parent window. Dialogs should be used to ask or tell the user something, while windows should
  44  * show data which is independent of 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() will 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  * - g_signal_connect(my_win, "destroy", my_destroy_cb, NULL) will create a callback if some cleanup
  58  *     needs to be done after the window is destroyed, e.g. free up memory, or set the window pointer
  59  *   of a singleton window (only one instance allowed, e.g. about dialog) back to zero
  60  * - create and fill in the content and button widgets
  61  * - gtk_widget_show_all() shows all the widgets in the window
  62  * - window_present() will present the window on screen and
  63  *     (if available) set previously saved position and size
  64  *
  65  * @section window_events Events
  66  *
  67  * The following events are usually interesting:
  68  *
  69  * - "delete_event": the window manager's "X" (e.g. upper right edge) of the window
  70  *     was clicked; the default handler will call gtk_widget_destroy()
  71  * - "destroy": everything is already gone; only cleanup of left over resources
  72  *     can/should be done now
  73  *
  74  * @section window_hints Hints
  75  *
  76  * If you want to save size and position, be sure to call window_destroy() instead of only
  77  *   gtk_widget_destroy(), so you will probably have to g_signal_connect() to the "delete_event"!
  78  *
  79  * Don't use gtk_widget_set_size_request() to set the size of a window;
  80  *   use gtk_window_set_default_size() for that purpose!
  81  *
  82  * Be sure to call window_present() / window_destroy() appropriately, if you
  83  *   want to have size and position of the window handled by ui_util.
  84  *
  85  */
  86
  87 /** @file
  88  * Utilities for Windows and other user interface functions. See: @ref howto_window_page for details.
  89  * @ingroup dialog_group
  90  * @ingroup windows_group
  91  */
  92
  93 /** @name Window Functions
  94  *  @todo Move these window functions to a new file win_utils.h?
  95  *  @{ */
  96
  97 /** Create a new window with the Wireshark icon.
  98  *  If you want to create a dialog, use dlg_window_new() instead.
  99  *
 100  * @param type window type, typical GTK_WINDOW_TOPLEVEL
 101  * @param title the title for the new window
 102  * @return the newly created window
 103  */
 104 extern GtkWidget *window_new(GtkWindowType type, const gchar *title);
 105
 106 /** Same as window_new(), but will keep its geometry values (size, position, ...).
 107  *  Be sure to use window_present() and window_destroy() appropriately!
 108  *
 109  * @param type window type, typical GTK_WINDOW_TOPLEVEL
 110  * @param title the title for the new window
 111  * @param geom_name the name to distinguish this window; will also be used for the recent file (don't use special chars)
 112  * @return the newly created window
 113  */
 114 extern GtkWidget *window_new_with_geom(GtkWindowType type, const gchar *title, const gchar *geom_name);
 115
 116 /** Create a new splash window, with no icon or title bar.
 117  *
 118  * @return the newly created window
 119  */
 120 extern GtkWidget *splash_window_new(void);
 121
 122 /** Present the created window on the top of the screen. This will put the window on top and
 123  * (if available) set previously saved position and size.
 124  *
 125  * @param win the window from window_new()
 126  */
 127 extern void window_present(GtkWidget *win);
 128
 129 /** callback function for window_set_cancel_button() */
 130 typedef void (*window_cancel_button_fct) (GtkWidget *w, gpointer data);
 131
 132 /** Register the default cancel button "Cancel"/"Close"/"Ok" of this window.
 133  *  This will set the callback function for this button, grab this button as the default one and
 134  *  set the "ESC" key handler to call the callback function if key is pressed.
 135  *
 136  * @param win the window from window_new()
 137  * @param bt the default button of this window
 138  * @param cb callback function to be called, when this button is pressed
 139  */
 140 extern void window_set_cancel_button(GtkWidget *win, GtkWidget *bt, window_cancel_button_fct cb);
 141
 142 /** Remember the current window position / size and then destroy the window.
 143  *  It's important to call this instead of gtk_widget_destroy() when using window_new_with_geom().
 144  *
 145  * @param win the window from window_new()
 146  */
 147 extern void window_destroy(GtkWidget *win);
 148
 149 /** Default callback handler for cancel button "clicked" signal.
 150  *  Use this for window_set_cancel_button(), if no user specific functionality required,
 151  *  will simply call window_destroy()
 152  */
 153 extern void window_cancel_button_cb(GtkWidget *w _U_, gpointer data);
 154
 155 /** Default callback handler if the window manager's X of the window was clicked (delete_event).
 156  *  Use this for g_signal_connect(), if no user specific functionality required,
 157  *  will simply call window_destroy()
 158  */
 159 extern gboolean window_delete_event_cb(GtkWidget *win, GdkEvent *event _U_, gpointer user_data _U_);
 160
 161 /** geometry values for use in window_get_geometry() and window_set_geometry() */
 162 typedef struct window_geometry_s {
 163     gchar       *key;           /**< current key in hashtable (internally used only) */
 164     gboolean    set_pos;        /**< set the x and y position values */
 165     gint        x;              /**< the windows x position */
 166     gint        y;              /**< the windows y position */
 167     gboolean    set_size;       /**< set the width and height values */
 168     gint        width;          /**< the windows width */
 169     gint        height;         /**< the windows height */
 170
 171     gboolean    set_maximized;  /**< set the maximized state (GTK2 only) */
 172     gboolean    maximized;      /**< the windows maximized state (GTK2 only) */
 173 } window_geometry_t;
 174
 175 /** Get the geometry of a window.
 176  *
 177  * @param win the window from window_new()
 178  * @param geom the current geometry values of the window; the set_xy values will not be used
 179  * @todo if main uses the window_new_with_geom() to save size and such, make this function static
 180  */
 181 extern void window_get_geometry(GtkWidget *win, window_geometry_t *geom);
 182 /** Set the geometry of a window.
 183  *
 184  * @param win the window from window_new()
 185  * @param geom the new geometry values of the window
 186  * @todo if main uses the window_new_with_geom() to save size and such, make this function static
 187  */
 188 extern void window_set_geometry(GtkWidget *win, window_geometry_t *geom);
 189
 190 /** Write all geometry values of all windows to the recent file.
 191  * Will call write_recent_geom() for every existing window type.
 192  *
 193  * @param rf recent file handle from caller
 194  */
 195 extern void window_geom_recent_write_all(gpointer rf);
 196
 197 /** Read in a single geometry key value pair from the recent file.
 198  *
 199  * @param name the geom_name of the window
 200  * @param key the subkey of this pair (e.g. "x")
 201  * @param value the new value (e.g. "123")
 202  */
 203 extern void window_geom_recent_read_pair(const char *name, const char *key, const char *value);
 204
 205 /** Raise a top-level window and de-iconify it.
 206  *  This routine is used if the user has done something to
 207  *  ask that a window of a certain type be popped up when there can be only
 208  *  one such window and such a window has already been popped up - we
 209  *  pop up the existing one rather than creating a new one.
 210  *
 211  * @param win the window from window_new() to be reactivated
 212  */
 213 extern void reactivate_window(GtkWidget *win);
 214
 215 /** @} */
 216
 217 /** Create a GtkScrolledWindow, set its scrollbar placement appropriately,
 218  *  and remember it.
 219  *
 220  * @param hadjustment horizontal adjustment
 221  * @param vadjustment vertical adjustment
 222  * @return the new scrolled window
 223  */
 224 extern GtkWidget *scrolled_window_new(GtkAdjustment *hadjustment,
 225                                GtkAdjustment *vadjustment);
 226
 227 /** Set the scrollbar placement of all scrolled windows based on user
 228    preference. */
 229 extern void set_scrollbar_placement_all(void);
 230
 231 /** Create a GtkTreeView, give it the right styles, and remember it.
 232  *
 233  * @param model The model (the data) of this tree view.
 234  */
 235 extern GtkWidget *tree_view_new(GtkTreeModel *model);
 236
 237 /** Move the currently-selected item in a list store up or down one position.
 238  *
 239  * @param tree GtkTreeView using a GtkListStore.
 240  * @param move_up TRUE to move the selected item up or FALSE to move it down.
 241  * @return TRUE if successful, FALSE otherwise.
 242  */
 243 extern gboolean tree_view_list_store_move_selection(GtkTreeView *tree, gboolean move_up);
 244
 245 /** Find the selected row in a list store.
 246  *
 247  * @param tree GtkTreeView using a GtkListStore.
 248  * @return The selected row number or -1 if no row is selected.
 249  */
 250 extern gint tree_view_list_store_get_selected_row(GtkTreeView *tree);
 251
 252 /** Create a simple list widget.
 253  *
 254  * @param cols number of columns
 255  * @param titles the titles of all columns
 256  * @return the new simple list widget
 257  */
 258 extern GtkWidget *simple_list_new(gint cols, const gchar **titles);
 259 /** Append a row to the simple list.
 260  *
 261  * @param list the list from simple_list_new()
 262  * @param ... row and title, finished by -1 (e.g.: 0, "first", 1, "second", -1).
 263  */
 264 extern void simple_list_append(GtkWidget *list, ...);
 265
 266 /*** Make a column look like a url
 267  *
 268  * @param list the list from simple_list_new()
 269  * @param col the column to make the values lookk like urls
 270  */
 271 extern void simple_list_url_col(GtkWidget *list, gint col);
 272
 273 /*** Make a cell underline to look like links
 274  *
 275  * @param cell the cell renderer that will show the text as a link
 276  */
 277
 278 extern void render_as_url(GtkCellRenderer *cell);
 279
 280 /** Set the styles of all Trees based upon user preferences. */
 281 extern void set_tree_styles_all(void);
 282
 283 /** Convert an xpm picture into a GtkWidget showing it.
 284  * Beware: Wireshark's main window must already be visible!
 285  *
 286  * @param xpm the character array containing the picture
 287  * @return a newly created GtkWidget showing the picture
 288  */
 289 extern GtkWidget *xpm_to_widget(const char ** xpm);
 290
 291 /** Convert an xpm picture into a GtkWidget showing it.
 292  * Beware: the given parent window must already be visible!
 293  *
 294  * @param parent the parent window of to widget to be generated
 295  * @param xpm the character array containing the picture
 296  * @return a newly created GtkWidget showing the picture
 297  */
 298 /*extern GtkWidget *xpm_to_widget_from_parent(GtkWidget *parent, const char ** xpm);*/
 299
 300 /** Convert an pixbuf data to a GtkWidget
 301  *
 302  * @param pb_data Inline pixbuf data. This should be created with "gdk-pixbuf-csource --raw"
 303  */
 304 extern GtkWidget *pixbuf_to_widget(const char * pb_data);
 305
 306 /** Copy a GString to the clipboard.
 307  *
 308  * @param str GString that is to be copied to the clipboard.
 309  */
 310 extern void copy_to_clipboard(GString *str);
 311
 312 /** Copy an array of bytes to the clipboard.
 313  * Copies as mime-type application/octet_stream in GTK 2.
 314  *
 315  * @param data_p Pointer to data to be copied.
 316  * @param len Number of bytes in the data to be copied.
 317  */
 318 extern void copy_binary_to_clipboard(const guint8* data_p, int len);
 319
 320 /** Create a new window title that includes user-defined preference string.
 321  *
 322  * @param caption string you want included in title (appended to user-defined string)
 323  * @return a newly created title string including user-defined preference (if specified)
 324  */
 325 extern gchar *create_user_window_title(const gchar *caption);
 326
 327 /** Construct the main window's title with the current main_window_name optionally appended
 328  *  with the user-specified title and/or wireshark version.
 329  *  Display the result in the main window's title bar and in its icon title
 330  */
 331 extern void update_main_window_title(void);
 332
 333 /** Renders a float with two decimals precission, called from gtk_tree_view_column_set_cell_data_func().
 334  * the user data must be the colum number.
 335  * Present floats with two decimals
 336  *
 337  * @param column A GtkTreeColumn
 338  * @param renderer The GtkCellRenderer that is being rendered by tree_column
 339  * @param model The GtkTreeModel being rendered
 340  * @param iter A GtkTreeIter of the current row rendered
 341  * @param user_data must be the colum number to fetch the data from
 342  */
 343 void float_data_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
 344
 345 /** Renders a unsinged integer as a hexadecimal value, called from gtk_tree_view_column_set_cell_data_func()
 346  * The user data must be the colum number.
 347  * Present value as hexadecimal.
 348  * @param column A GtkTreeColumn
 349  * @param renderer The GtkCellRenderer that is being rendered by tree_column
 350  * @param model The GtkTreeModel being rendered
 351  * @param iter A GtkTreeIter of the current row rendered
 352  * @param user_data must be the colum number to fetch the data from
 353  */
 354 void present_as_hex_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
 355
 356 /** Renders an unsigned 64 bits integer with space as thousand separator, called from gtk_tree_view_column_set_cell_data_func()
 357  * The user data must be the colum number.
 358  * Present value as hexadecimal.
 359  * @param column A GtkTreeColumn
 360  * @param renderer The GtkCellRenderer that is being rendered by tree_column
 361  * @param model The GtkTreeModel being rendered
 362  * @param iter A GtkTreeIter of the current row rendered
 363  * @param user_data must be the colum number to fetch the data from
 364  */
 365 void u64_data_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
 366
 367 /** This function can be called from gtk_tree_view_column_set_cell_data_func()
 368  * the user data must be the colum number.
 369  * Present value as hexadecimal.
 370  * @param column A GtkTreeColumn
 371  * @param renderer The GtkCellRenderer that is being rendered by tree_column
 372  * @param model The GtkTreeModel being rendered
 373  * @param iter A GtkTreeIter of the current row rendered
 374  * @param user_data must be the colum number to fetch the data from
 375  */
 376 void str_ptr_data_func(GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
 377
 378 /** This function can be called from gtk_tree_sortable_set_sort_func()
 379  * the user data must be the colum number.
 380  * Used together with str_ptr_data_func to sort the corresponding column.
 381  * @param model The GtkTreeModel the comparison is within
 382  * @param a A GtkTreeIter in model
 383  * @param b Another GtkTreeIter in model
 384  * @param user_data must be the colum number to fetch the data from
 385  */
 386
 387 gint str_ptr_sort_func(GtkTreeModel *model,
 388                        GtkTreeIter  *a,
 389                        GtkTreeIter  *b,
 390                        gpointer      user_data);
 391
 392 /** Switch a GtkTReeView to fixed columns (speed optimization)
 393  * @param view A GtkTreeView
 394  */
 395 void switch_to_fixed_col(GtkTreeView *view);
 396
 397 /** Return the size in pixels of a string displayed with the GtkWidget's font.
 398  * @param view A GtkWidget
 399  * @param str UTF8 string
 400  */
 401 gint get_default_col_size(GtkWidget *view, const gchar *str);
 402
 403
 404 /** --------------------------------------------------
 405  * ws_combo_box_text_and_pointer convenience functions
 406  *  (Code adapted from GtkComboBox.c)
 407  */
 408
 409 /**
 410  * ws_combo_box_new_text_and_pointer_full:
 411  *
 412  * Convenience function which constructs a new "text and pointer" combo box, which
 413  * is a #GtkComboBox just displaying strings and storing a pointer associated with
 414  * each combo_box entry; The pointer can be retrieved when an entry is selected.
 415  * Also: optionally returns the cell renderer for the combo box.
 416  * If you use this function to create a text_and_pointer combo_box,
 417  * you should only manipulate its data source with the
 418  * following convenience functions:
 419  *   ws_combo_box_append_text_and_pointer()
 420  *   ws_combo_box_append_text_and_pointer_full()
 421  *
 422  * @param cell_p  pointer to return the 'GtkCellRenderer *' for the combo box (or NULL).
 423  * @return A pointer to a new text_and_pointer combo_box.
 424  */
 425 GtkWidget *ws_combo_box_new_text_and_pointer_full(GtkCellRenderer **cell_p);
 426
 427 /**
 428  * ws_combo_box_new_text_and_pointer:
 429  *
 430  * Convenience function which constructs a new "text and pointer" combo box, which
 431  * is a #GtkComboBox just displaying strings and storing a pointer associated with
 432  * each combo_box entry; The pointer can be retrieved when an entry is selected.
 433  * If you use this function to create a text_and_pointer combo_box,
 434  * you should only manipulate its data source with the
 435  * following convenience functions:
 436  *   ws_combo_box_append_text_and_pointer()
 437  *   ws_combo_box_append_text_and_pointer_full()
 438  *
 439  * @return A pointer to a new text_and_pointer combo_box.
 440  */
 441 GtkWidget *ws_combo_box_new_text_and_pointer(void);
 442
 443 /**
 444  * ws_combo_box_clear_text_and_pointer:
 445  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 446  *
 447  * Clears all the text_and_pointer entries in the text_and_pointer combo_box.
 448  * Note: A "changed" signal will be emitted after the clear if there was
 449  * an active (selected) entry before the clear.
 450  * You should use this function only with combo boxes constructed with
 451  * ws_combo_box_new_text_and_pointer().
 452  */
 453 void ws_combo_box_clear_text_and_pointer(GtkComboBox *combo_box);
 454
 455 /**
 456  * ws_combo_box_append_text_and_pointer_full:
 457  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 458  * @param parent_iter Parent row for apending; NULL if appending to tree top-level;
 459  * @param text A string to be displayed as an entry in the dropdown list of the combo_box
 460  * @param ptr  A pointer to be associated with this entry of the combo_box
 461  * @param sensitive TRUE/FALSE to set sensitivity of the entry
 462  * @return A GtkTreeIter pointing to the appended GtkVomboBox entry.
 463  *
 464  * Appends text and ptr to the list of strings and pointers stored in combo_box.
 465  * The text and ptr can be appended to any existing level of the tree_store.
 466  * The sensitivity of the row will be set as requested.
 467  * Note that you can only use this function with combo boxes constructed with
 468  * ws_combo_box_new_text_and_pointer().
 469  */
 470 GtkTreeIter
 471 ws_combo_box_append_text_and_pointer_full(GtkComboBox   *combo_box,
 472                                           GtkTreeIter   *parent_iter,
 473                                           const gchar   *text,
 474                                           const gpointer ptr,
 475                                           const gboolean sensitive);
 476
 477 /**
 478  * ws_combo_box_append_text_and_pointer:
 479  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 480  * @param text A string to be displayed as an entry in the dropdown list of the combo_box
 481  * @param ptr  A pointer to be associated with this entry of the combo_box
 482  * @return A GtkTreeIter pointing to the appended GtkComboBox entry.
 483  *
 484  * Appends text and ptr to the list of strings and pointers stored in combo_box. Note that
 485  * you can only use this function with combo boxes constructed with
 486  * ws_combo_box_new_text_and_pointer().
 487  */
 488 GtkTreeIter
 489 ws_combo_box_append_text_and_pointer(GtkComboBox    *combo_box,
 490                                      const gchar    *text,
 491                                      const gpointer  ptr);
 492
 493 /**
 494  * ws_combo_box_get_active_pointer:
 495  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 496  * @param ptr  A pointer to a location in which to store the pointer associated with the active entry
 497  * @return TRUE if an entry is selected (i.e: an active entry exists); FALSE otherwise
 498  *
 499  * You can only use this function with combo boxes constructed with
 500  * ws_combo_box_new_text_and_pointer().
 501  */
 502 gboolean ws_combo_box_get_active_pointer(GtkComboBox *combo_box, gpointer *ptr);
 503
 504 /**
 505  * ws_combo_box_get_active:
 506  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 507  * @return Index of the active entry; -1 if no entry is selected;
 508  *         Note: If the active item is not an immediate child of root of the tree then
 509  *          the index returned is that of the top-level for the acftive entry.
 510  */
 511 gint ws_combo_box_get_active(GtkComboBox *combo_box);
 512
 513 /**
 514  * ws_combo_box_set_active:
 515  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 516  * @param idx Index of the entry which is to be set as active (ie: selected).
 517  *        Index refers to the immediate children of the tree.
 518  */
 519 void ws_combo_box_set_active(GtkComboBox *combo_box, gint idx);
 520
 521 /**
 522  * ws_combo_box_set_active_iter:
 523  * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
 524  * @param iter of the entry which is to be set as active (ie: selected).
 525  */
 526 void
 527 ws_combo_box_set_active_iter(GtkComboBox *combo_box, GtkTreeIter *iter);
 528
 529 #if GTK_CHECK_VERSION(2,22,0)
 530 #if !GTK_CHECK_VERSION(3,0,0)
 531 GdkPixbuf *gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
 532                                         gint             src_x,
 533                                         gint             src_y,
 534                                         gint             width,
 535                                         gint             height);
 536 #endif
 537 #endif
 538 #endif /* __GUI_UTIL__H__ */