osmocom
/
wireshark
14
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

add details for doxygen 

svn path=/trunk/; revision=11046
This commit is contained in:
Ulf Lamping 2004-05-31 15:47:34 +00:00
parent d5dec17fba
commit 8816b7e3c7
3 changed files with 248 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
gtk/compat_macros.h
View File

@ -1,7 +1,7 @@
/* compat_macros.h
* GTK-related Global defines, etc.
*
* $Id: compat_macros.h,v 1.15 2004/05/23 15:03:09 ulfl Exp $
* $Id: compat_macros.h,v 1.16 2004/05/31 15:47:34 ulfl Exp $
*
* Ethereal - Network traffic analyzer
* By Gerald Combs <gerald@ethereal.com>
@ -26,54 +26,151 @@
#define __COMPAT_MACROS_H__
/*
* helper macros fro gtk1.2/gtk2 compatibility :
* in gtk2, gtk_signal_xxx is deprecated in favor of g_signal_xxx
* gtk_object_xxx is deprecated in favor of g_object_xxx
/** @file
*
* Helper macros for gtk1.2/gtk2 compatibility :
* in gtk2, gtk_signal_xxx is deprecated in favor of g_signal_xxx,
* gtk_object_xxx is deprecated in favor of g_object_xxx,
* gtk_widget_set_usize is deprecated in favor of
* gtk_widget_set_size_request
* gtk_widget_set_size_request, ...
*/
#if GTK_MAJOR_VERSION < 2
/** Connect a signal handler to a particular object.
*
* @param widget the widget to connect to
* @param name name of the signal
* @param callback function pointer to attach to the signal
* @param arg value to pass to your function
* @return the connection id
*/
#define SIGNAL_CONNECT(widget, name, callback, arg) \
gtk_signal_connect(GTK_OBJECT(widget), name, GTK_SIGNAL_FUNC(callback), \
(gpointer)(arg))
/** This function is for registering a callback that will call another object's callback.
* That is, instead of passing the object which is responsible for the event as the first
* parameter of the callback, it is switched with the user data (so the object which emits
* the signal will be the last parameter, which is where the user data usually is).
*
* @param widget the widget to connect to
* @param name name of the signal
* @param callback function pointer to attach to the signal
* @param arg the object to pass as the first parameter to func
* @return the connection id
*/
#define SIGNAL_CONNECT_OBJECT(widget, name, callback, arg) \
gtk_signal_connect_object(GTK_OBJECT(widget), name, GTK_SIGNAL_FUNC(callback), \
(gpointer)(arg))
/** Destroys all connections for a particular object, with the given
* function-pointer and user-data.
*
* @param object the object which emits the signal
* @param func the function pointer to search for
* @param data the user data to search for
* @todo function only rarely used, think about removing it
*/
#define SIGNAL_DISCONNECT_BY_FUNC(object, func, data) \
gtk_signal_disconnect_by_func(GTK_OBJECT(object), func, data)
/** Each object carries around a table of associations from strings to pointers,
* this function lets you set an association. If the object already had an
* association with that name, the old association will be destroyed.
*
* @param widget object containing the associations
* @param key name of the key
* @param data data to associate with that key
*/
#define OBJECT_SET_DATA(widget, key, data) \
gtk_object_set_data(GTK_OBJECT(widget), key, (gpointer)data)
/** Like OBJECT_SET_DATA() except it adds notification for when the
* association is destroyed, either by gtk_object_remove_data() or when the
* object is destroyed.
*
* @param widget object containing the associations
* @param key name of the key
* @param data data to associate with that key
* @param destroy function to call when the association is destroyed
* @todo function only rarely used, think about removing it
*/
#define OBJECT_SET_DATA_FULL(widget, key, data, destroy) \
gtk_object_set_data_full(GTK_OBJECT(widget), key, (gpointer)(data), \
(GtkDestroyNotify)(destroy))
/** Get a named field from the object's table of associations (the object_data).
*
* @param widget object containing the associations
* @param key name of the key
* @return the data if found, or NULL if no such data exists
*/
#define OBJECT_GET_DATA(widget, key) \
gtk_object_get_data(GTK_OBJECT(widget), key)
/* WIDGET_SET_SIZE would better be named WIDGET_SET_MIN_SIZE. */
/* don't use WIDGET_SET_SIZE() to set the size of a dialog, */
/* use gtk_window_set_default_size() for that purpose! */
/** Sets the size of a widget. This will be useful to set the size of
* e.g. a GtkEntry. Don't use WIDGET_SET_SIZE() to set the size of a dialog
* or window, use gtk_window_set_default_size() for that purpose!
*
* @param widget a GtkWidget
* @param width new width, or -1 to unset
* @param height new height, or -1 to unset
* @todo WIDGET_SET_SIZE would better be named WIDGET_SET_MIN_SIZE
*/
#define WIDGET_SET_SIZE(widget, width, height) \
gtk_widget_set_usize(GTK_WIDGET(widget), width, height)
/** Emits a signal. This causes the default handler and user-connected
* handlers to be run.
*
* @param widget the object that emits the signal
* @param name the name of the signal
*/
#define SIGNAL_EMIT_BY_NAME(widget, name) \
gtk_signal_emit_by_name(GTK_OBJECT(widget), name)
/** Like SIGNAL_EMIT_BY_NAME(), but with one argument.
*
* @param widget the object that emits the signal
* @param name the name of the signal
* @param arg value to pass to the handlers
* @todo function only rarely used, think about removing it
*/
#define SIGNAL_EMIT_BY_NAME1(widget, name, arg) \
gtk_signal_emit_by_name(GTK_OBJECT(widget), name, arg)
/** This function aborts a signal's current emission. It will prevent the
* default method from running, if the signal was GTK_RUN_LAST and you
* connected normally (i.e. without the "after" flag). It will print a
* warning if used on a signal which isn't being emitted. It will lookup the
* signal id for you.
*
* @param widget the object whose signal handlers you wish to stop
* @param name the signal identifier, as returned by g_signal_lookup()
*/
#define SIGNAL_EMIT_STOP_BY_NAME(widget, name) \
gtk_signal_emit_stop_by_name(GTK_OBJECT(widget), name)
/** An entry for a GtkItemFactoryEntry array.
*
* @param path the path to this entry (e.g. "/File/Open")
* @param accelerator accelerator key (e.g. "<control>M") or NULL
* @param callback function to be called, when item is activated or NULL
* @param action the action number to use (usually 0)
* @param type special item type (e.g. "<Branch>", "<CheckItem>", ...) or NULL
* @param data data to pass to the callback function or NULL
*/
#define ITEM_FACTORY_ENTRY(path, accelerator, callback, action, type, data) \
{path, accelerator, GTK_MENU_FUNC(callback), action, type}
/** Like ITEM_FACTORY_ENTRY(), but using a stock icon (as data)
* @param path the path to this entry (e.g. "/File/Open")
* @param accelerator accelerator key (e.g. "<control>M") or NULL
* @param callback function to be called, when item is activated or NULL
* @param action the action number to use (usually 0)
* @param data the stock item id (e.g. GTK_STOCK_OK, unused by GTK1)
*/
#define ITEM_FACTORY_STOCK_ENTRY(path, accelerator, callback, action, data) \
{path, accelerator, GTK_MENU_FUNC(callback), action, NULL}

11
gtk/dlg_utils.h
View File

@ -1,7 +1,7 @@
/* dlg_utils.h
* Declarations of utilities to use when constructing dialogs
*
* $Id: dlg_utils.h,v 1.16 2004/05/31 13:42:58 ulfl Exp $
* $Id: dlg_utils.h,v 1.17 2004/05/31 15:47:34 ulfl Exp $
*
* Ethereal - Network traffic analyzer
* By Gerald Combs <gerald@ethereal.com>
@ -23,8 +23,8 @@
*/
/** @file
* This file will provide utility functions for dialog windows related to Ethereal's main window.
* It's depending on the window functions in ui_util.h. See window_new() and others in
* Utility functions for dialog windows related to Ethereal's main window,
* depending on the window functions in ui_util.h. See window_new() and others in
* ui_util.h for further explanation of dialogs and windows in Ethereal.
*/
@ -32,7 +32,8 @@
#define __DLG_UTILS_H__
/** Create a dialog box window that belongs to Ethereal's main window.
* See window_new() for usage.
* If you want to create a window, use window_new() instead.
* See window_new() for general window usage.
*
* @param title the title for the new dialog
* @return the newly created dialog
@ -80,7 +81,7 @@ extern void file_selection_set_extra_widget(GtkWidget *fs, GtkWidget *extra);
* @param file_te the GtkEntry the dialog will have to fill in the filename
* @param title the title for the file selection dialog
* @param action the desired action
* @todo use the toplevel widget as the parameter, not the button
* @todo use the parent widget as the first parameter, not the button
*/
extern void
file_selection_browse(GtkWidget *file_bt, GtkWidget *file_te, const char *title, file_selection_action_t action);

188
gtk/ui_util.h
View File

@ -1,7 +1,7 @@
/* ui_util.h
* Definitions for UI utility routines
*
* $Id: ui_util.h,v 1.11 2004/05/30 11:54:37 ulfl Exp $
* $Id: ui_util.h,v 1.12 2004/05/31 15:47:34 ulfl Exp $
*
* Ethereal - Network traffic analyzer
* By Gerald Combs <gerald@ethereal.com>
@ -26,7 +26,10 @@
#define __GTKGUIUI_UTIL_H__
/* Some words about windows / dialogs.
/** @file
* Windows and other user interface related utility functions.
*
* 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()
@ -41,10 +44,10 @@
*
* A typical window / dialog will be created by:
*
* window_new(...) will create a new window with default position and size
* 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
* 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
*
@ -54,110 +57,191 @@
*
* create and fill in the content and button widgets
*
* gtk_widget_show_all(my_win) show all the widgets in the window
* gtk_widget_show_all() show all the widgets in the window
*
* window_present(...) present the window on screen and
* window_present() present the window on screen and
* (if available) set previously saved position and size
*
* 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"!
*/
/* Create a new window, of the specified type, with the specified title
* (if any) and the Ethereal icon.
* If you want to create a dialog, use dlg_window_new() instead.
* type window type, typical GTK_WINDOW_TOPLEVEL
* title title to show, will also set the window class for saving size etc. */
/** Create a new window with the Ethereal icon.
* If you want to create a dialog, use dlg_window_new() instead.
*
* @param type window type, typical GTK_WINDOW_TOPLEVEL
* @param title the title for the new window
* @return the newly created window
*/
extern GtkWidget *window_new(GtkWindowType type, const gchar *title);
/* Same as window_new(), but will keep it's geometry values (size, position, ...).
* Be sure to use window_present() and window_destroy() appropriately! */
/** Same as window_new(), but will keep it's geometry values (size, position, ...).
* Be sure to use window_present() and window_destroy() appropriately!
*
* @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
* @return the newly created window
*/
extern GtkWidget *window_new_with_geom(GtkWindowType type, const gchar *title, const gchar *geom_name);
/* Present the created window. This will put the window on top and
* (if available) set previously saved position and size. */
/** Present the created window on the top of the screen. This will put the window on top and
* (if available) set previously saved position and size.
*
* @param win the window from window_new()
*/
extern void window_present(GtkWidget *win);
/** callback function for window_set_cancel_button() */
typedef void (*window_cancel_button_fct) (GtkWidget *w, gpointer data);
/* register the default cancel button "Cancel"/"Close"/"Ok" of this window */
/** Register the default cancel button "Cancel"/"Close"/"Ok" of this window.
* This will set the callback function for this button, grab this button as the default one and
* set the "ESC" key handler to call the callback function if key is pressed.
*
* @param win the window from window_new()
* @param bt the default button of this window
* @param cb callback function to be called, when this button is pressed
*/
extern void window_set_cancel_button(GtkWidget *win, GtkWidget *bt, window_cancel_button_fct cb);
/* Remember current window position and size and then destroy the window,
* it's important to call this instead of gtk_widget_destroy(); */
/** Remember the current window position / size and then destroy the window.
* It's important to call this instead of gtk_widget_destroy() when using window_new_with_geom().
*
* @param win the window from window_new()
*/
extern void window_destroy(GtkWidget *win);
/* default callback handler for cancel button "clicked" signal,
* use this for window_set_cancel_button(), will simply call window_destroy() */
/** Default callback handler for cancel button "clicked" signal.
* Use this for window_set_cancel_button(), if no user specific functionality required,
* will simply call window_destroy()
*/
extern void window_cancel_button_cb(GtkWidget *w _U_, gpointer data);
/* default callback handler: the window managers X of the window was clicked (delete_event),
* use this for SIGNAL_CONNECT(), will simply call window_destroy() */
extern gboolean
window_delete_event_cb(GtkWidget *win, GdkEvent *event _U_, gpointer user_data _U_);
/** 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,
* will simply call window_destroy()
*/
extern gboolean window_delete_event_cb(GtkWidget *win, GdkEvent *event _U_, gpointer user_data _U_);
/** geometry values for use in window_get_geometry() and window_set_geometry() */
typedef struct window_geometry_s {
gchar *key;
gboolean set_pos;
gint x;
gint y;
gboolean set_size;
gint width;
gint height;
gchar *key; /**< current key in hashtable (internally used only) */
gboolean set_pos; /**< set the x and y position values */
gint x; /**< the windows x position */
gint y; /**< the windows y position */
gboolean set_size; /**< set the width and height values */
gint width; /**< the windows width */
gint height; /**< the windows height */
gboolean set_maximized;/* this is valid in GTK2 only */
gboolean maximized; /* this is valid in GTK2 only */
gboolean set_maximized; /**< set the maximized state (GTK2 only) */
gboolean maximized; /**< the windows maximized state (GTK2 only) */
} window_geometry_t;
/* get the geometry of a window from window_new() */
/** 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
* @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);
/* set the geometry of a window from window_new() */
/** Set the geometry of a window.
*
* @param win the window from window_new()
* @param geom the new geometry values of the window
* @todo if main uses the window_new_with_geom() to save size and such, make this function static
*/
extern void window_set_geometry(GtkWidget *win, window_geometry_t *geom);
/* write all geometry values of all windows to the recent file */
/** Write all geometry values of all windows to the recent file.
* Will call write_recent_geom() for every existing window type.
*
* @param rf recent file handle from caller
*/
extern void window_geom_recent_write_all(gpointer rf);
/* read in a single geometry key value pair from the recent file */
/** Read in a single geometry key value pair from the recent file.
*
* @param name the geom_name of the window
* @param key the subkey of this pair (e.g. "x")
* @param value the new value (e.g. "123")
*/
extern void window_geom_recent_read_pair(const char *name, const char *key, const char *value);
/* Given a pointer to a GtkWidget for a top-level window, raise it and
de-iconify it. This routine is used if the user has done something to
ask that a window of a certain type be popped up when there can be only
one such window and such a window has already been popped up - we
pop up the existing one rather than creating a new one. */
/** Raise a top-level window and de-iconify it.
* This routine is used if the user has done something to
* ask that a window of a certain type be popped up when there can be only
* one such window and such a window has already been popped up - we
* pop up the existing one rather than creating a new one.
*
* @param win the window from window_new() to be reactivated
*/
void reactivate_window(GtkWidget *win);
/* Create a GtkScrolledWindow, set its scrollbar placement appropriately,
and remember it. */
/** Create a GtkScrolledWindow, set its scrollbar placement appropriately,
* and remember it.
*
* @param hadjustment horizontal adjustment
* @param vadjustment vertical adjustment
* @return the new scrolled window
*/
GtkWidget *scrolled_window_new(GtkAdjustment *hadjustment,
GtkAdjustment *vadjustment);
/* Set the scrollbar placement of all scrolled windows based on user
/** Set the scrollbar placement of all scrolled windows based on user
preference. */
void set_scrollbar_placement_all(void);
#if GTK_MAJOR_VERSION < 2
/* Create a GtkCTree, give it the right styles, and remember it. */
/** Create a GtkCTree, give it the right styles, and remember it.
*
* @param columns the number of columns
* @param tree_column which column has the tree graphic
* @return the newly created GtkCTree
*/
GtkWidget *ctree_new(gint columns, gint tree_column);
/** Create a GtkCTree, give it the right styles, and remember it.
*
* @param columns the number of columns
* @param tree_column which column has the tree graphic
* @param titles the titles of all columns
* @return the newly created GtkCTree
*/
GtkWidget *ctree_new_with_titles(gint columns, gint tree_column,
gchar *titles[]);
#else
/** Create a GtkTreeView, give it the right styles, and remember it.
*
* @param model the model (the data) of this tree view
*/
GtkWidget *tree_view_new(GtkTreeModel *model);
#endif
/* create a simple list widget */
/** Create a simple list widget.
*
* @param cols number of columns
* @param titles the titles of all columns
* @return the new simple list widget
*/
extern GtkWidget *simple_list_new(gint cols, gchar **titles);
/* append a row to the simple list */
/* use it like: simple_list_append(list, 0, "first", 1, "second", -1) */
/** Append a row to the simple list.
*
* @param list the list from simple_list_new()
* @param ... row and title, finished by -1 (e.g.: 0, "first", 1, "second", -1).
*/
extern void simple_list_append(GtkWidget *list, ...);
/* Set the styles of all Trees based upon user preferences. */
/** Set the styles of all Trees based upon user preferences. */
void set_tree_styles_all(void);
/* convert an xpm picture into a GtkWidget showing it (top_level must already be visible!) */
/** Convert an xpm picture into a GtkWidget showing it.
* Beware: Ethereal's main window must already be visible!
*
* @param xpm the character array containing the picture
* @return a newly created GtkWidget showing the picture
*/
GtkWidget *xpm_to_widget(const char ** xpm);
#endif /* __GTKGUIUI_UTIL_H__ */