* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
-#ifndef __GTKGUIUI_UTIL_H__
-#define __GTKGUIUI_UTIL_H__
+#ifndef __GUI_UTILS_H__
+#define __GUI_UTILS_H__
/** @defgroup windows_group Windows
*
/** @page howto_window_page How to develop a window / dialog
*
* 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.
+ * slightly different. A dialog sticks on its parent window; A normal window will be much more independent
+ * from its parent window. Dialogs should be used to ask or tell the user something, while windows should
+ * show data which is independent of 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 gui_utils.h
+ * After that, dialogs can be developed the same way as windows; all window related functions in gui_utils.h
* can be used for both.
*
* @section window_create Create a window
* A typical window / dialog will be created by the following calls:
*
* - 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.
- * - 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
+ * use dlg_window_new() if you need a dialog (transient to the main window)
+ * - gtk_window_set_default_size() will 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.
+ * - g_signal_connect(my_win, "destroy", my_destroy_cb, NULL) will create a 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
+ * - window_present() will present the window on screen and
+ * (if available) set previously saved position and size
*
* @section window_events Events
*
* The following events are usually interesting:
*
- * - "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
+ * - "delete_event": the window manager's "X" (e.g. upper right edge) of the window
+ * was clicked; the default handler will call gtk_widget_destroy()
+ * - "destroy": everything is already gone; only cleanup of left over resources
+ * 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
- * gtk_widget_destroy(), so you will probably have to SIGNAL_CONNECT to the "delete_event"!
+ * gtk_widget_destroy(), so you will probably have to g_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!
+ * Don't use gtk_widget_set_size_request() 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.
*
* @param type window type, typical GTK_WINDOW_TOPLEVEL
* @param title the title for the new window
- * @param geom_name the name to distinguish this window, will also be used for the recent file (don't use special chars)
+ * @param geom_name the name to distinguish this window; will also be used for the recent file (don't use special chars)
* @return the newly created window
*/
extern GtkWidget *window_new_with_geom(GtkWindowType type, const gchar *title, const gchar *geom_name);
*/
extern void window_cancel_button_cb(GtkWidget *w _U_, gpointer data);
-/** Default callback handler if the window managers X of the window was clicked (delete_event).
- * Use this for SIGNAL_CONNECT(), if no user specific functionality required,
+/** Default callback handler if the window manager's X of the window was clicked (delete_event).
+ * Use this for g_signal_connect(), if no user specific functionality required,
* will simply call window_destroy()
*/
extern gboolean window_delete_event_cb(GtkWidget *win, GdkEvent *event _U_, gpointer user_data _U_);
/** Get the geometry of a window.
*
* @param win the window from window_new()
- * @param geom the current geometry values of the window, the set_xy values will not be used
+ * @param geom the current geometry values of the window; the set_xy values will not be used
* @todo if main uses the window_new_with_geom() to save size and such, make this function static
*/
extern void window_get_geometry(GtkWidget *win, window_geometry_t *geom);
/** Create a GtkTreeView, give it the right styles, and remember it.
*
- * @param model the model (the data) of this tree view
+ * @param model The model (the data) of this tree view.
*/
extern GtkWidget *tree_view_new(GtkTreeModel *model);
+/** Move the currently-selected item in a list store up or down one position.
+ *
+ * @param tree GtkTreeView using a GtkListStore.
+ * @param move_up TRUE to move the selected item up or FALSE to move it down.
+ * @return TRUE if successful, FALSE otherwise.
+ */
+extern gboolean tree_view_list_store_move_selection(GtkTreeView *tree, gboolean move_up);
+
+/** Find the selected row in a list store.
+ *
+ * @param tree GtkTreeView using a GtkListStore.
+ * @return The selected row number or -1 if no row is selected.
+ */
+extern gint tree_view_list_store_get_selected_row(GtkTreeView *tree);
+
/** Create a simple list widget.
*
* @param cols number of columns
*/
extern void simple_list_append(GtkWidget *list, ...);
+/*** Make a column look like a url
+ *
+ * @param list the list from simple_list_new()
+ * @param col the column to make the values lookk like urls
+ */
+extern void simple_list_url_col(GtkWidget *list, gint col);
+
+/*** Make a cell underline to look like links
+ *
+ * @param cell the cell renderer that will show the text as a link
+ */
+extern void render_as_url(GtkCellRenderer *cell);
/** Set the styles of all Trees based upon user preferences. */
extern void set_tree_styles_all(void);
* @param xpm the character array containing the picture
* @return a newly created GtkWidget showing the picture
*/
-extern GtkWidget *xpm_to_widget_from_parent(GtkWidget *parent, const char ** xpm);
+/*extern GtkWidget *xpm_to_widget_from_parent(GtkWidget *parent, const char ** xpm);*/
+
+/** Convert an pixbuf data to a GtkWidget
+ *
+ * @param pb_data Inline pixbuf data. This should be created with "gdk-pixbuf-csource --raw"
+ */
+extern GtkWidget *pixbuf_to_widget(const char * pb_data);
/** Copy a GString to the clipboard.
*
*/
extern gchar *create_user_window_title(const gchar *caption);
-#endif /* __GTKGUIUI_UTIL_H__ */
+/** Construct the main window's title with the current main_window_name optionally appended
+ * with the user-specified title and/or wireshark version.
+ * Display the result in the main window's title bar and in its icon title
+ */
+extern void update_main_window_title(void);
+
+/** Renders a float with two decimals precission, called from gtk_tree_view_column_set_cell_data_func().
+ * the user data must be the colum number.
+ * Present floats with two decimals
+ *
+ * @param column A GtkTreeColumn
+ * @param renderer The GtkCellRenderer that is being rendered by tree_column
+ * @param model The GtkTreeModel being rendered
+ * @param iter A GtkTreeIter of the current row rendered
+ * @param user_data must be the colum number to fetch the data from
+ */
+void float_data_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
+
+/** Renders a unsinged integer as a hexadecimal value, called from gtk_tree_view_column_set_cell_data_func()
+ * The user data must be the colum number.
+ * Present value as hexadecimal.
+ * @param column A GtkTreeColumn
+ * @param renderer The GtkCellRenderer that is being rendered by tree_column
+ * @param model The GtkTreeModel being rendered
+ * @param iter A GtkTreeIter of the current row rendered
+ * @param user_data must be the colum number to fetch the data from
+ */
+void present_as_hex_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
+
+/** Renders an unsigned 64 bits integer with space as thousand separator, called from gtk_tree_view_column_set_cell_data_func()
+ * The user data must be the colum number.
+ * Present value as hexadecimal.
+ * @param column A GtkTreeColumn
+ * @param renderer The GtkCellRenderer that is being rendered by tree_column
+ * @param model The GtkTreeModel being rendered
+ * @param iter A GtkTreeIter of the current row rendered
+ * @param user_data must be the colum number to fetch the data from
+ */
+void u64_data_func (GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
+
+/** This function can be called from gtk_tree_view_column_set_cell_data_func()
+ * the user data must be the colum number.
+ * Present value as hexadecimal.
+ * @param column A GtkTreeColumn
+ * @param renderer The GtkCellRenderer that is being rendered by tree_column
+ * @param model The GtkTreeModel being rendered
+ * @param iter A GtkTreeIter of the current row rendered
+ * @param user_data must be the colum number to fetch the data from
+ */
+void str_ptr_data_func(GtkTreeViewColumn *column, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data);
+
+/** This function can be called from gtk_tree_sortable_set_sort_func()
+ * the user data must be the colum number.
+ * Used together with str_ptr_data_func to sort the corresponding column.
+ * @param model The GtkTreeModel the comparison is within
+ * @param a A GtkTreeIter in model
+ * @param b Another GtkTreeIter in model
+ * @param user_data must be the colum number to fetch the data from
+ */
+
+gint str_ptr_sort_func(GtkTreeModel *model,
+ GtkTreeIter *a,
+ GtkTreeIter *b,
+ gpointer user_data);
+
+/** Switch a GtkTReeView to fixed columns (speed optimization)
+ * @param view A GtkTreeView
+ */
+void switch_to_fixed_col(GtkTreeView *view);
+
+/** Return the size in pixels of a string displayed with the GtkWidget's font.
+ * @param view A GtkWidget
+ * @param str UTF8 string
+ */
+gint get_default_col_size(GtkWidget *view, const gchar *str);
+
+
+/** --------------------------------------------------
+ * ws_combo_box_text_and_pointer convenience functions
+ * (Code adapted from GtkComboBox.c)
+ */
+
+/**
+ * ws_combo_box_new_text_and_pointer_full:
+ *
+ * Convenience function which constructs a new "text and pointer" combo box, which
+ * is a #GtkComboBox just displaying strings and storing a pointer associated with
+ * each combo_box entry; The pointer can be retrieved when an entry is selected.
+ * Also: optionally returns the cell renderer for the combo box.
+ * If you use this function to create a text_and_pointer combo_box,
+ * you should only manipulate its data source with the
+ * following convenience functions:
+ * ws_combo_box_append_text_and_pointer()
+ * ws_combo_box_append_text_and_pointer_full()
+ *
+ * @param cell_p pointer to return the 'GtkCellRenderer *' for the combo box (or NULL).
+ * @return A pointer to a new text_and_pointer combo_box.
+ */
+GtkWidget *ws_combo_box_new_text_and_pointer_full(GtkCellRenderer **cell_p);
+
+/**
+ * ws_combo_box_new_text_and_pointer:
+ *
+ * Convenience function which constructs a new "text and pointer" combo box, which
+ * is a #GtkComboBox just displaying strings and storing a pointer associated with
+ * each combo_box entry; The pointer can be retrieved when an entry is selected.
+ * If you use this function to create a text_and_pointer combo_box,
+ * you should only manipulate its data source with the
+ * following convenience functions:
+ * ws_combo_box_append_text_and_pointer()
+ * ws_combo_box_append_text_and_pointer_full()
+ *
+ * @return A pointer to a new text_and_pointer combo_box.
+ */
+GtkWidget *ws_combo_box_new_text_and_pointer(void);
+
+/**
+ * ws_combo_box_clear_text_and_pointer:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ *
+ * Clears all the text_and_pointer entries in the text_and_pointer combo_box.
+ * Note: A "changed" signal will be emitted after the clear if there was
+ * an active (selected) entry before the clear.
+ * You should use this function only with combo boxes constructed with
+ * ws_combo_box_new_text_and_pointer().
+ */
+void ws_combo_box_clear_text_and_pointer(GtkComboBox *combo_box);
+
+/**
+ * ws_combo_box_append_text_and_pointer_full:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ * @param parent_iter Parent row for apending; NULL if appending to tree top-level;
+ * @param text A string to be displayed as an entry in the dropdown list of the combo_box
+ * @param ptr A pointer to be associated with this entry of the combo_box
+ * @param sensitive TRUE/FALSE to set sensitivity of the entry
+ * @return A GtkTreeIter pointing to the appended GtkVomboBox entry.
+ *
+ * Appends text and ptr to the list of strings and pointers stored in combo_box.
+ * The text and ptr can be appended to any existing level of the tree_store.
+ * The sensitivity of the row will be set as requested.
+ * Note that you can only use this function with combo boxes constructed with
+ * ws_combo_box_new_text_and_pointer().
+ */
+GtkTreeIter
+ws_combo_box_append_text_and_pointer_full(GtkComboBox *combo_box,
+ GtkTreeIter *parent_iter,
+ const gchar *text,
+ const gpointer ptr,
+ const gboolean sensitive);
+
+/**
+ * ws_combo_box_append_text_and_pointer:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ * @param text A string to be displayed as an entry in the dropdown list of the combo_box
+ * @param ptr A pointer to be associated with this entry of the combo_box
+ * @return A GtkTreeIter pointing to the appended GtkComboBox entry.
+ *
+ * Appends text and ptr to the list of strings and pointers stored in combo_box. Note that
+ * you can only use this function with combo boxes constructed with
+ * ws_combo_box_new_text_and_pointer().
+ */
+GtkTreeIter
+ws_combo_box_append_text_and_pointer(GtkComboBox *combo_box,
+ const gchar *text,
+ const gpointer ptr);
+
+/**
+ * ws_combo_box_get_active_pointer:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ * @param ptr A pointer to a location in which to store the pointer associated with the active entry
+ * @return TRUE if an entry is selected (i.e: an active entry exists); FALSE otherwise
+ *
+ * You can only use this function with combo boxes constructed with
+ * ws_combo_box_new_text_and_pointer().
+ */
+gboolean ws_combo_box_get_active_pointer(GtkComboBox *combo_box, gpointer *ptr);
+
+/**
+ * ws_combo_box_get_active:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ * @return Index of the active entry; -1 if no entry is selected;
+ * Note: If the active item is not an immediate child of root of the tree then
+ * the index returned is that of the top-level for the acftive entry.
+ */
+gint ws_combo_box_get_active(GtkComboBox *combo_box);
+
+/**
+ * ws_combo_box_set_active:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ * @param idx Index of the entry which is to be set as active (ie: selected).
+ * Index refers to the immediate children of the tree.
+ */
+void ws_combo_box_set_active(GtkComboBox *combo_box, gint idx);
+
+/**
+ * ws_combo_box_set_active_iter:
+ * @param combo_box A #GtkComboBox constructed using ws_combo_box_new_text_and_pointer()
+ * @param iter of the entry which is to be set as active (ie: selected).
+ */
+void
+ws_combo_box_set_active_iter(GtkComboBox *combo_box, GtkTreeIter *iter);
+
+#if GTK_CHECK_VERSION(2,22,0)
+#if !GTK_CHECK_VERSION(3,0,0)
+GdkPixbuf *gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
+ gint src_x,
+ gint src_y,
+ gint width,
+ gint height);
+#endif
+#endif
+#endif /* __GUI_UTIL__H__ */