2 * Declarations of GTK+-specific UI utility routines
6 * Wireshark - Network traffic analyzer
7 * By Gerald Combs <gerald@wireshark.org>
8 * Copyright 1998 Gerald Combs
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.
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.
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.
25 #ifndef __GTKGUIUI_UTIL_H__
26 #define __GTKGUIUI_UTIL_H__
28 /** @defgroup windows_group Windows
30 * There are the following toplevel windows:
32 * - @ref main_window_group
33 * - Statistic Windows (several different statistic windows)
35 * See: @ref howto_window_page for details.
39 /** @page howto_window_page How to develop a window / dialog
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.
49 * @section window_create Create a window
51 * A typical window / dialog will be created by the following calls:
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
65 * @section window_events Events
67 * The following events are usually interesting:
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
74 * @section window_hints Hints
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"!
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!
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.
88 * Utilities for Windows and other user interface functions. See: @ref howto_window_page for details.
89 * @ingroup dialog_group
90 * @ingroup windows_group
93 /** @name Window Functions
94 * @todo Move these window functions to a new file win_utils.h?
97 /** Create a new window with the Wireshark icon.
98 * If you want to create a dialog, use dlg_window_new() instead.
100 * @param type window type, typical GTK_WINDOW_TOPLEVEL
101 * @param title the title for the new window
102 * @return the newly created window
104 extern GtkWidget *window_new(GtkWindowType type, const gchar *title);
106 /** Same as window_new(), but will keep its geometry values (size, position, ...).
107 * Be sure to use window_present() and window_destroy() appropriately!
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
114 extern GtkWidget *window_new_with_geom(GtkWindowType type, const gchar *title, const gchar *geom_name);
116 /** Create a new splash window, with no icon or title bar.
118 * @return the newly created window
120 extern GtkWidget *splash_window_new(void);
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.
125 * @param win the window from window_new()
127 extern void window_present(GtkWidget *win);
129 /** callback function for window_set_cancel_button() */
130 typedef void (*window_cancel_button_fct) (GtkWidget *w, gpointer data);
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.
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
140 extern void window_set_cancel_button(GtkWidget *win, GtkWidget *bt, window_cancel_button_fct cb);
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().
145 * @param win the window from window_new()
147 extern void window_destroy(GtkWidget *win);
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()
153 extern void window_cancel_button_cb(GtkWidget *w _U_, gpointer data);
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()
159 extern gboolean window_delete_event_cb(GtkWidget *win, GdkEvent *event _U_, gpointer user_data _U_);
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 */
171 gboolean set_maximized; /**< set the maximized state (GTK2 only) */
172 gboolean maximized; /**< the windows maximized state (GTK2 only) */
175 /** Get the geometry of a window.
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
181 extern void window_get_geometry(GtkWidget *win, window_geometry_t *geom);
182 /** Set the geometry of a window.
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
188 extern void window_set_geometry(GtkWidget *win, window_geometry_t *geom);
190 /** Write all geometry values of all windows to the recent file.
191 * Will call write_recent_geom() for every existing window type.
193 * @param rf recent file handle from caller
195 extern void window_geom_recent_write_all(gpointer rf);
197 /** Read in a single geometry key value pair from the recent file.
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")
203 extern void window_geom_recent_read_pair(const char *name, const char *key, const char *value);
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.
211 * @param win the window from window_new() to be reactivated
213 extern void reactivate_window(GtkWidget *win);
217 /** Create a GtkScrolledWindow, set its scrollbar placement appropriately,
220 * @param hadjustment horizontal adjustment
221 * @param vadjustment vertical adjustment
222 * @return the new scrolled window
224 extern GtkWidget *scrolled_window_new(GtkAdjustment *hadjustment,
225 GtkAdjustment *vadjustment);
227 /** Set the scrollbar placement of all scrolled windows based on user
229 extern void set_scrollbar_placement_all(void);
231 /** Create a GtkTreeView, give it the right styles, and remember it.
233 * @param model the model (the data) of this tree view
235 extern GtkWidget *tree_view_new(GtkTreeModel *model);
237 /** Create a simple list widget.
239 * @param cols number of columns
240 * @param titles the titles of all columns
241 * @return the new simple list widget
243 extern GtkWidget *simple_list_new(gint cols, const gchar **titles);
244 /** Append a row to the simple list.
246 * @param list the list from simple_list_new()
247 * @param ... row and title, finished by -1 (e.g.: 0, "first", 1, "second", -1).
249 extern void simple_list_append(GtkWidget *list, ...);
251 /*** Make a column look like a url
253 * @param list the list from simple_list_new()
254 * @param col the column to make the values lookk like urls
256 extern void simple_list_url_col(GtkWidget *list, gint col);
258 /*** Make a cell underline to look like links
260 * @param cell the cell renderer that will show the text as a link
263 extern void render_as_url(GtkCellRenderer *cell);
265 /** Set the styles of all Trees based upon user preferences. */
266 extern void set_tree_styles_all(void);
268 /** Convert an xpm picture into a GtkWidget showing it.
269 * Beware: Wireshark's main window must already be visible!
271 * @param xpm the character array containing the picture
272 * @return a newly created GtkWidget showing the picture
274 extern GtkWidget *xpm_to_widget(const char ** xpm);
276 /** Convert an xpm picture into a GtkWidget showing it.
277 * Beware: the given parent window must already be visible!
279 * @param parent the parent window of to widget to be generated
280 * @param xpm the character array containing the picture
281 * @return a newly created GtkWidget showing the picture
283 extern GtkWidget *xpm_to_widget_from_parent(GtkWidget *parent, const char ** xpm);
285 /** Convert an pixbuf data to a GtkWidget
287 * @param pb_data Inline pixbuf data. This should be created with "gdk-pixbuf-csource --raw"
289 extern GtkWidget *pixbuf_to_widget(const char * pb_data);
291 /** Copy a GString to the clipboard.
293 * @param str GString that is to be copied to the clipboard.
295 extern void copy_to_clipboard(GString *str);
297 /** Copy an array of bytes to the clipboard.
298 * Copies as mime-type application/octet_stream in GTK 2.
300 * @param data_p Pointer to data to be copied.
301 * @param len Number of bytes in the data to be copied.
303 extern void copy_binary_to_clipboard(const guint8* data_p, int len);
305 /** Create a new window title that includes user-defined preference string.
307 * @param caption string you want included in title (appended to user-defined string)
308 * @return a newly created title string including user-defined preference (if specified)
310 extern gchar *create_user_window_title(const gchar *caption);
312 /** Renders a float with two decimals precission, called from gtk_tree_view_column_set_cell_data_func().
313 * the user data must be the colum number.
314 * Present floats with two decimals
316 * @param column A GtkTreeColumn
317 * @param renderer The GtkCellRenderer that is being rendered by tree_column
318 * @param model The GtkTreeModel being rendered
319 * @param iter A GtkTreeIter of the current row rendered
320 * @param user_data must be the colum number to fetch the data from
322 void float_data_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
324 /** Renders a unsinged integer as a hexadecimal value, called from gtk_tree_view_column_set_cell_data_func()
325 * The user data must be the colum number.
326 * Present value as hexadecimal.
327 * @param column A GtkTreeColumn
328 * @param renderer The GtkCellRenderer that is being rendered by tree_column
329 * @param model The GtkTreeModel being rendered
330 * @param iter A GtkTreeIter of the current row rendered
331 * @param user_data must be the colum number to fetch the data from
333 void present_as_hex_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
335 /** Renders an unsigned 64 bits integer with space as thousand separator, called from gtk_tree_view_column_set_cell_data_func()
336 * The user data must be the colum number.
337 * Present value as hexadecimal.
338 * @param column A GtkTreeColumn
339 * @param renderer The GtkCellRenderer that is being rendered by tree_column
340 * @param model The GtkTreeModel being rendered
341 * @param iter A GtkTreeIter of the current row rendered
342 * @param user_data must be the colum number to fetch the data from
344 void u64_data_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
346 /** This function can be called from gtk_tree_view_column_set_cell_data_func()
347 * the user data must be the colum number.
348 * Present value as hexadecimal.
349 * @param column A GtkTreeColumn
350 * @param renderer The GtkCellRenderer that is being rendered by tree_column
351 * @param model The GtkTreeModel being rendered
352 * @param iter A GtkTreeIter of the current row rendered
353 * @param user_data must be the colum number to fetch the data from
355 void str_ptr_data_func(GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
357 /** This function can be called from gtk_tree_sortable_set_sort_func()
358 * the user data must be the colum number.
359 * Used together with str_ptr_data_func to sort the corresponding column.
360 * @param model The GtkTreeModel the comparison is within
361 * @param a A GtkTreeIter in model
362 * @param b Another GtkTreeIter in model
363 * @param user_data must be the colum number to fetch the data from
366 gint str_ptr_sort_func(GtkTreeModel *model,
371 /** Switch a GtkTReeView to fixed columns (speed optimization)
372 * @param view A GtkTreeView
374 void switch_to_fixed_col(GtkTreeView *view);
376 /** Return the size in pixels of a string displayed with the GtkWidget's font.
377 * @param view A GtkWidget
378 * @param str UTF8 string
380 gint get_default_col_size(GtkWidget *view, const gchar *str);
382 #endif /* __GTKGUIUI_UTIL_H__ */