From a6a63670a28ce5ef0a45f73218eeda83e031821d Mon Sep 17 00:00:00 2001 From: Colin Clark Date: Wed, 21 Apr 2021 10:03:26 +0100 Subject: [PATCH] Convert comments in .h files to Doxygen style comments --- src/bar.h | 24 ++-- src/bar_exif.h | 3 +- src/bar_keywords.h | 4 +- src/cache-loader.h | 2 +- src/collect-io.h | 19 ++- src/collect.h | 4 +- src/dnd.h | 5 +- src/editors.h | 49 +++---- src/exif-int.h | 22 ++-- src/exif.h | 9 +- src/filedata.h | 15 ++- src/filefilter.h | 5 +- src/format_raw.h | 5 +- src/fullscreen.h | 14 +- src/history_list.h | 6 +- src/image-load.h | 17 ++- src/image.h | 35 ++++- src/md5-util.h | 20 ++- src/options.h | 53 +++++--- src/pan-view/pan-types.h | 5 +- src/pan-view/pan-view-filter.h | 12 +- src/pan-view/pan-view-search.h | 10 +- src/pixbuf-renderer.h | 150 +++++++++++++-------- src/preferences.h | 5 +- src/print.h | 5 +- src/thumb_standard.h | 4 +- src/typedefs.h | 231 +++++++++++++++++---------------- src/ui_bookmark.h | 5 +- src/ui_fileops.h | 15 ++- src/ui_menu.h | 9 +- src/ui_misc.h | 49 +++++-- src/ui_spinner.h | 16 ++- src/ui_tree_edit.h | 51 ++++++-- src/ui_utildlg.h | 23 ++-- 34 files changed, 573 insertions(+), 328 deletions(-) diff --git a/src/bar.h b/src/bar.h index 7e4d7c2b..05b4091d 100644 --- a/src/bar.h +++ b/src/bar.h @@ -34,19 +34,17 @@ typedef enum { typedef struct _PaneData PaneData; struct _PaneData { - /* filled in by pane */ - void (*pane_set_fd)(GtkWidget *pane, FileData *fd); - void (*pane_notify_selection)(GtkWidget *pane, gint count); - gint (*pane_event)(GtkWidget *pane, GdkEvent *event); - void (*pane_write_config)(GtkWidget *pane, GString *outstr, gint indent); - GtkWidget *title; - gboolean expanded; - gchar *id; - PaneType type; - - /* filled in by bar */ - GtkWidget *bar; - LayoutWindow *lw; + void (*pane_set_fd)(GtkWidget *pane, FileData *fd); /**< filled in by pane */ + void (*pane_notify_selection)(GtkWidget *pane, gint count); /**< filled in by pane */ + gint (*pane_event)(GtkWidget *pane, GdkEvent *event); /**< filled in by pane */ + void (*pane_write_config)(GtkWidget *pane, GString *outstr, gint indent); /**< filled in by pane */ + GtkWidget *title; /**< filled in by pane */ + gboolean expanded; /**< filled in by pane */ + gchar *id; /**< filled in by pane */ + PaneType type; /**< filled in by pane */ + + GtkWidget *bar; /**< filled in by bar */ + LayoutWindow *lw; /**< filled in by bar */ }; diff --git a/src/bar_exif.h b/src/bar_exif.h index 1395e842..30a7ab13 100644 --- a/src/bar_exif.h +++ b/src/bar_exif.h @@ -27,8 +27,7 @@ void bar_pane_exif_update_from_config(GtkWidget *pane, const gchar **attribute_n void bar_pane_exif_entry_add_from_config(GtkWidget *pane, const gchar **attribute_names, const gchar **attribute_values); -/* these are exposed for when duplication of the exif bar's text is needed */ -GList *bar_pane_exif_list(); +GList *bar_pane_exif_list(); /**< these are exposed for when duplication of the exif bar's text is needed */ #endif /* vim: set shiftwidth=8 softtabstop=0 cindent cinoptions={1s: */ diff --git a/src/bar_keywords.h b/src/bar_keywords.h index 1fe87a0e..d63e1dcb 100644 --- a/src/bar_keywords.h +++ b/src/bar_keywords.h @@ -25,8 +25,8 @@ GtkWidget *bar_pane_keywords_new_from_config(const gchar **attribute_names, const gchar **attribute_values); void bar_pane_keywords_update_from_config(GtkWidget *pane, const gchar **attribute_names, const gchar **attribute_values); void bar_pane_keywords_entry_add_from_config(GtkWidget *pane, const gchar **attribute_names, const gchar **attribute_values); -/* used in search.c */ -GList *keyword_list_pull(GtkWidget *text_widget); + +GList *keyword_list_pull(GtkWidget *text_widget); /**< used in search.c */ GList *keyword_list_get(); void keyword_list_set(GList *keyword_list); diff --git a/src/cache-loader.h b/src/cache-loader.h index 8cc5eb1a..3d876303 100644 --- a/src/cache-loader.h +++ b/src/cache-loader.h @@ -53,7 +53,7 @@ struct _CacheLoader { gboolean error; ImageLoader *il; - guint idle_id; /* event source id */ + guint idle_id; /**< event source id */ }; diff --git a/src/collect-io.h b/src/collect-io.h index 78f1cb38..bf0c81b0 100644 --- a/src/collect-io.h +++ b/src/collect-io.h @@ -41,7 +41,9 @@ gboolean collection_save(CollectionData *cd, const gchar *path); gboolean collection_load_only_geometry(CollectionData *cd, const gchar *path); -/* these are used to update collections contained in user's collection +/** + * \headerfile collect_manager_moved + * these are used to update collections contained in user's collection * folder when moving or renaming files. * also handles: * deletes file when newpath == NULL @@ -49,11 +51,22 @@ gboolean collection_load_only_geometry(CollectionData *cd, const gchar *path); */ void collect_manager_moved(FileData *fd); -/* add or removing from a specific collection */ +/** + * \headerfile collect_manager_add + * add from a specific collection + */ void collect_manager_add(FileData *fd, const gchar *collection); + +/** + * \headerfile collect_manager_remove + * removing from a specific collection + */ void collect_manager_remove(FileData *fd, const gchar *collection); -/* commit pending operations to disk */ +/** + * \headerfile collect_manager_flush + * commit pending operations to disk + */ void collect_manager_flush(void); void collect_manager_notify_cb(FileData *fd, NotifyType type, gpointer data); diff --git a/src/collect.h b/src/collect.h index f5226a73..efa4521d 100644 --- a/src/collect.h +++ b/src/collect.h @@ -51,7 +51,9 @@ void collection_path_changed(CollectionData *cd); gint collection_to_number(CollectionData *cd); CollectionData *collection_from_number(gint n); -/* pass a NULL pointer to whatever you don't need +/** + * \headerfile collection_from_dnd_data + * pass a NULL pointer to whatever you don't need * use free_selected_list to free list, and * g_list_free to free info_list, which is a list of * CollectInfo pointers into CollectionData diff --git a/src/dnd.h b/src/dnd.h index c1589df0..2ae29faa 100644 --- a/src/dnd.h +++ b/src/dnd.h @@ -42,7 +42,10 @@ extern GtkTargetEntry dnd_file_drop_types[]; extern gint dnd_file_drop_types_count; -/* sets a drag icon to pixbuf, if items is > 1, text is drawn onto icon to indicate value */ +/** + * \headerfile dnd_set_drag_icon + * sets a drag icon to pixbuf, if items is > 1, text is drawn onto icon to indicate value + */ void dnd_set_drag_icon(GtkWidget *widget, GdkDragContext *context, GdkPixbuf *pixbuf, gint items); void dnd_set_drag_label(GtkWidget *widget, GdkDragContext *context, const gchar *text); diff --git a/src/editors.h b/src/editors.h index 6f0df218..83da3a8f 100644 --- a/src/editors.h +++ b/src/editors.h @@ -33,7 +33,7 @@ typedef enum { EDITOR_FOR_EACH = 0x00000200, EDITOR_SINGLE_COMMAND = 0x00000400, EDITOR_NO_PARAM = 0x00000800, - /* below are errors */ + /**< below are errors */ EDITOR_ERROR_EMPTY = 0x00020000, EDITOR_ERROR_SYNTAX = 0x00040000, EDITOR_ERROR_INCOMPATIBLE = 0x00080000, @@ -41,35 +41,38 @@ typedef enum { EDITOR_ERROR_CANT_EXEC = 0x00200000, EDITOR_ERROR_STATUS = 0x00400000, EDITOR_ERROR_SKIPPED = 0x00800000, - /* mask to match errors only */ + /**< mask to match errors only */ EDITOR_ERROR_MASK = 0xffff0000, } EditorFlags; struct _EditorDescription { - gchar *key; /* desktop file name, not including path, including extension */ - gchar *name; /* Name, localized name presented to user */ - gchar *icon; /* Icon */ - gchar *exec; /* Exec */ + gchar *key; /**< desktop file name, not including path, including extension */ + gchar *name; /**< Name, localized name presented to user */ + gchar *icon; /**< Icon */ + gchar *exec; /**< Exec */ gchar *menu_path; gchar *hotkey; GList *ext_list; gchar *file; - gchar *comment; /* .desktop Comment key, used to show a tooltip */ + gchar *comment; /**< .desktop Comment key, used to show a tooltip */ EditorFlags flags; - gboolean hidden; /* explicitly hidden, shown in configuration dialog */ - gboolean ignored; /* not interesting, do not show at all */ - gboolean disabled; /* display disabled by user */ + gboolean hidden; /**< explicitly hidden, shown in configuration dialog */ + gboolean ignored; /**< not interesting, do not show at all */ + gboolean disabled; /**< display disabled by user */ }; #define EDITOR_ERRORS(flags) ((flags) & EDITOR_ERROR_MASK) #define EDITOR_ERRORS_BUT_SKIPPED(flags) (!!(((flags) & EDITOR_ERROR_MASK) && !((flags) & EDITOR_ERROR_SKIPPED))) -/* return values from callback function */ +/** + * \enum + * return values from callback function + */ enum { - EDITOR_CB_CONTINUE = 0, /* continue multiple editor execution on remaining files*/ - EDITOR_CB_SKIP, /* skip the remaining files */ - EDITOR_CB_SUSPEND /* suspend execution, one of editor_resume or editor_skip + EDITOR_CB_CONTINUE = 0, /**< continue multiple editor execution on remaining files*/ + EDITOR_CB_SKIP, /**< skip the remaining files */ + EDITOR_CB_SUSPEND /**< suspend execution, one of editor_resume or editor_skip must be called later */ }; @@ -96,14 +99,16 @@ gboolean editor_read_desktop_file(const gchar *path); GList *editor_list_get(void); -/* -Callback is called even on skipped files, with the EDITOR_ERROR_SKIPPED flag set. -It is a good place to call file_data_change_info_free(). - -ed - pointer that can be used for editor_resume/editor_skip or NULL if all files were already processed -flags - flags above -list - list of processed FileData structures, typically single file or whole list passed to start_editor_* -data - generic pointer +/** + * \typedef EditorCallback + * + * Callback is called even on skipped files, with the #EDITOR_ERROR_SKIPPED flag set. + * It is a good place to call file_data_change_info_free(). + * + * \param ed - pointer that can be used for editor_resume/editor_skip or NULL if all files were already processed \n + * \param flags - flags above \n + * \param list - list of processed #FileData structures, typically single file or whole list passed to start_editor_* \n + * \param data - generic pointer */ typedef gint (*EditorCallback) (gpointer ed, EditorFlags flags, GList *list, gpointer data); diff --git a/src/exif-int.h b/src/exif-int.h index 5287b553..6eabbd05 100644 --- a/src/exif-int.h +++ b/src/exif-int.h @@ -44,8 +44,7 @@ struct _ExifFormatAttrib const gchar *description; }; -/* the list of known tag data formats */ -extern ExifFormatAttrib ExifFormatList[]; +extern ExifFormatAttrib ExifFormatList[]; /**< the list of known tag data formats */ /* @@ -60,8 +59,8 @@ typedef struct _ExifTextList ExifTextList; struct _ExifData { gchar *path; - GList *items; /* list of (ExifItem *) */ - GList *current; /* for exif_get_next_item */ + GList *items; /**< list of (ExifItem *) */ + GList *current; /**< for exif_get_next_item */ }; @@ -106,14 +105,11 @@ struct _ExifTextList -/* the known exif tags list */ -extern ExifMarker ExifKnownMarkersList[]; +extern ExifMarker ExifKnownMarkersList[]; /**< the known exif tags list */ -/* the unknown tags utilize this generic list */ -extern ExifMarker ExifUnknownMarkersList[]; +extern ExifMarker ExifUnknownMarkersList[]; /**< the unknown tags utilize this generic list */ -/* the list of specially formatted keys, for human readable output */ -extern ExifFormattedText ExifFormattedList[]; +extern ExifFormattedText ExifFormattedList[]; /**< the list of specially formatted keys, for human readable output */ /* @@ -122,8 +118,10 @@ extern ExifFormattedText ExifFormattedList[]; *----------------------------------------------------------------------------- */ - -/* usually for debugging to stdout */ +/** + * \headerfile exif_write_data_list + * usually for debugging to stdout + */ void exif_write_data_list(ExifData *exif, FILE *f, gint human_readable_list); diff --git a/src/exif.h b/src/exif.h index 6e2ca064..37d675ea 100644 --- a/src/exif.h +++ b/src/exif.h @@ -108,9 +108,12 @@ ExifData *exif_read(gchar *path, gchar *sidecar_path, GHashTable *modified_xmp); ExifData *exif_read_fd(FileData *fd); void exif_free_fd(FileData *fd, ExifData *exif); -/* exif_read returns processed data (merged from image and sidecar, etc.) - this function gives access to the original data from the image. - original data are part of the processed data and should not be freed separately */ +/** + * \headerfile exif_get_original + * exif_read returns processed data (merged from image and sidecar, etc.) + * this function gives access to the original data from the image. + * original data are part of the processed data and should not be freed separately + */ ExifData *exif_get_original(ExifData *processed); diff --git a/src/filedata.h b/src/filedata.h index 736dab03..7631d0e6 100644 --- a/src/filedata.h +++ b/src/filedata.h @@ -32,13 +32,22 @@ gchar *text_from_size(gint64 size); gchar *text_from_size_abrev(gint64 size); const gchar *text_from_time(time_t t); -/* scan for sidecar files - expensive */ +/** + * \headerfile file_data_new_group + * scan for sidecar files - expensive + */ FileData *file_data_new_group(const gchar *path_utf8); -/* should be used on helper files which can't have sidecars */ +/** + * \headerfile file_data_new_no_grouping + * should be used on helper files which can't have sidecars + */ FileData *file_data_new_no_grouping(const gchar *path_utf8); -/* should be used on dirs */ +/** + * \headerfile file_data_new_dir + * should be used on dirs + */ FileData *file_data_new_dir(const gchar *path_utf8); FileData *file_data_new_simple(const gchar *path_utf8); diff --git a/src/filefilter.h b/src/filefilter.h index 06140b33..1e3ab0dc 100644 --- a/src/filefilter.h +++ b/src/filefilter.h @@ -34,7 +34,10 @@ struct _FilterEntry { gboolean allow_sidecar; }; -/* you can change, but not add or remove entries from the returned list */ +/** + * \headerfile filter_get_list + * you can change, but not add or remove entries from the returned list + */ GList *filter_get_list(void); void filter_remove_entry(FilterEntry *fe); diff --git a/src/format_raw.h b/src/format_raw.h index 78acb82e..820de62e 100644 --- a/src/format_raw.h +++ b/src/format_raw.h @@ -80,7 +80,10 @@ gboolean format_exif_makernote_parse(ExifData *exif, guchar *tiff, guint offset, FORMAT_RAW_EXIF_NONE, NULL, \ "Tiff debugger MM", format_debug_tiff_raw } -/* used for debugging only */ +/** + * \headerfile format_debug_tiff_raw + * used for debugging only + */ gint format_debug_tiff_raw(guchar *data, const guint len, guint *image_offset, guint *exif_offset); #endif diff --git a/src/fullscreen.h b/src/fullscreen.h index 69d263d1..0eae9428 100644 --- a/src/fullscreen.h +++ b/src/fullscreen.h @@ -30,14 +30,14 @@ FullScreenData *fullscreen_start(GtkWidget *window, ImageWindow *imd, void fullscreen_stop(FullScreenData *fs); -/* screen numbers for fullscreen_prefs are as follows: - * 0 use default display size - * 101 screen 0, monitor 0 - * 102 screen 0, monitor 1 - * 201 screen 1, monitor 0 +/** + * \struct ScreenData + * screen numbers for fullscreen_prefs are as follows: \n + * 0 use default display size \n + * 101 screen 0, monitor 0 \n + * 102 screen 0, monitor 1 \n + * 201 screen 1, monitor 0 \n */ - - typedef struct _ScreenData ScreenData; struct _ScreenData { gint number; diff --git a/src/history_list.h b/src/history_list.h index f9040de4..51cf38d9 100644 --- a/src/history_list.h +++ b/src/history_list.h @@ -44,7 +44,11 @@ const gchar *image_chain_back(); const gchar *image_chain_forward(); void image_chain_append_end(const gchar *path); -/* the returned GList is internal, don't free it */ + +/** + * \headerfile history_list_get_by_key + * the returned GList is internal, don't free it + */ GList *history_list_get_by_key(const gchar *key); diff --git a/src/image-load.h b/src/image-load.h index a209fa31..420faa18 100644 --- a/src/image-load.h +++ b/src/image-load.h @@ -85,14 +85,14 @@ struct _ImageLoader gboolean shrunk; gboolean done; - guint idle_id; /* event source id */ + guint idle_id; /**< event source id */ gint idle_priority; gpointer *loader; GError *error; ImageLoaderBackend backend; - guint idle_done_id; /* event source id */ + guint idle_done_id; /**< event source id */ GList *area_param_list; GList *area_param_delayed_list; @@ -125,10 +125,15 @@ ImageLoader *image_loader_new(FileData *fd); void image_loader_free(ImageLoader *il); -/* delay area_ready signals */ +/** + * \headerfile image_loader_delay_area_ready + * delay area_ready signals + */ void image_loader_delay_area_ready(ImageLoader *il, gboolean enable); -/* Speed up loading when you only need at most width x height size image, +/** + * \headerfile image_loader_set_requested_size + * Speed up loading when you only need at most width x height size image, * only the jpeg GdkPixbuf loader benefits from it - so there is no * guarantee that the image will scale down to the requested size.. */ @@ -136,7 +141,9 @@ void image_loader_set_requested_size(ImageLoader *il, gint width, gint height); void image_loader_set_buffer_size(ImageLoader *il, guint size); -/* this only has effect if used before image_loader_start() +/** + * \headerfile image_loader_set_priority + * this only has effect if used before image_loader_start() * default is G_PRIORITY_DEFAULT_IDLE */ void image_loader_set_priority(ImageLoader *il, gint priority); diff --git a/src/image.h b/src/image.h index be963124..e7d088d6 100644 --- a/src/image.h +++ b/src/image.h @@ -63,7 +63,10 @@ const gchar *image_get_path(ImageWindow *imd); const gchar *image_get_name(ImageWindow *imd); FileData *image_get_fd(ImageWindow *imd); -/* merely changes path string, does not change the image! */ +/** + * \headerfile image_set_fd + * merely changes path string, does not change the image! + */ void image_set_fd(ImageWindow *imd, FileData *fd); /* load a new image */ @@ -111,13 +114,22 @@ void image_stereo_swap(ImageWindow *imd); StereoPixbufData image_stereo_pixbuf_get(ImageWindow *imd); void image_stereo_pixbuf_set(ImageWindow *imd, StereoPixbufData stereo_mode); -/* read ahead, pass NULL to cancel */ +/** + * \headerfile image_prebuffer_set + * read ahead, pass NULL to cancel + */ void image_prebuffer_set(ImageWindow *imd, FileData *fd); -/* auto refresh */ +/** + * \headerfile image_auto_refresh_enable + * auto refresh + */ void image_auto_refresh_enable(ImageWindow *imd, gboolean enable); -/* allow top window to be resized ? */ +/** + * \headerfile image_top_window_set_sync + * allow top window to be resized ? + */ void image_top_window_set_sync(ImageWindow *imd, gboolean allow_sync); /* background of image */ @@ -135,10 +147,16 @@ void image_color_profile_set_use(ImageWindow *imd, gboolean enable); gboolean image_color_profile_get_use(ImageWindow *imd); gboolean image_color_profile_get_status(ImageWindow *imd, gchar **image_profile, gchar **screen_profile); -/* set delayed page flipping */ +/** + * \headerfile image_set_delay_flip + * set delayed page flipping + */ void image_set_delay_flip(ImageWindow *imd, gint delay); -/* wallpaper util */ +/** + * \headerfile image_to_root_window + * wallpaper util + */ void image_to_root_window(ImageWindow *imd, gboolean scaled); @@ -150,7 +168,10 @@ void image_set_image_as_tiles(ImageWindow *imd, gint width, gint height, gpointer data, gdouble zoom); -/* reset default options */ +/** + * \headerfile image_options_sync + * reset default options + */ void image_options_sync(void); void image_get_rectangle(gint *x1, gint *y1, gint *x2, gint *y2); diff --git a/src/md5-util.h b/src/md5-util.h index 8a666c36..f74a05ec 100644 --- a/src/md5-util.h +++ b/src/md5-util.h @@ -54,14 +54,28 @@ void md5_init(MD5Context *ctx); void md5_update(MD5Context *ctx, const guchar *buf, guint32 len); void md5_final(MD5Context *ctx, guchar digest[16]); -/* generate digest from memory buffer */ +/** + * \headerfile md5_get_digest + * generate digest from memory buffer + */ void md5_get_digest(const guchar *buffer, gint buffer_size, guchar digest[16]); -/* generate digest from file */ +/** + * \headerfile md5_get_digest_from_file + * generate digest from file + */ gboolean md5_get_digest_from_file(const gchar *path, guchar digest[16]); -/* convert digest to/from a NULL terminated text string, in ascii encoding */ +/** + * \headerfile md5_digest_to_text + * convert digest to a NULL terminated text string, in ascii encoding + */ gchar *md5_digest_to_text(guchar digest[16]); + +/** + * \headerfile md5_digest_from_text + * convert digest from a NULL terminated text string, in ascii encoding + */ gboolean md5_digest_from_text(const gchar *text, guchar digest[16]); diff --git a/src/options.h b/src/options.h index a5d5cf8a..d9a5bbe2 100644 --- a/src/options.h +++ b/src/options.h @@ -69,7 +69,7 @@ struct _ConfOptions gint log_window_lines; - gboolean marks_save; // save marks on exit + gboolean marks_save; /**< save marks on exit */ gchar *marks_tooltips[FILEDATA_MARKS_SIZE]; gboolean with_rename; @@ -78,19 +78,34 @@ struct _ConfOptions gchar *help_search_engine; - /* info sidebar component heights */ + /** + * \struct info_comment + * info sidebar component height + */ struct { gint height; } info_comment; + /** + * \struct info_keywords + * info sidebar component height + */ struct { gint height; } info_keywords; + /** + * \struct info_title + * info sidebar component height + */ struct { gint height; } info_title; + /** + * \struct info_rating + * info sidebar component height + */ struct { gint height; } info_rating; @@ -121,15 +136,15 @@ struct _ConfOptions gint max_autofit_size; gint max_enlargement_size; - gint tile_cache_max; /* in megabytes */ - gint image_cache_max; /* in megabytes */ + gint tile_cache_max; /**< in megabytes */ + gint image_cache_max; /**< in megabytes */ gboolean enable_read_ahead; ZoomMode zoom_mode; gboolean zoom_2pass; gboolean zoom_to_fit_allow_expand; guint zoom_quality; - gint zoom_increment; /* 100 is 1.0, 5 is 0.05, 200 is 2.0, etc. */ + gint zoom_increment; /**< 100 is 1.0, 5 is 0.05, 200 is 2.0, etc. */ gboolean use_clutter_renderer; gboolean use_custom_border_color_in_fullscreen; @@ -182,13 +197,13 @@ struct _ConfOptions struct { SortType method; gboolean ascending; - gboolean case_sensitive; /* file sorting method (case) */ + gboolean case_sensitive; /**< file sorting method (case) */ gboolean natural; } file_sort; /* slideshow */ struct { - gint delay; /* in tenths of a second */ + gint delay; /**< in tenths of a second */ gboolean random; gboolean repeat; } slideshow; @@ -272,7 +287,11 @@ struct _ConfOptions gint fixed_w, fixed_h; gint fixed_x1, fixed_y1; gint fixed_x2, fixed_y2; - struct { /* options in this struct are packed to mode and fsmode entries */ + /** + * \struct tmp + * options in this struct are packed to mode and fsmode entries + */ + struct { gboolean mirror_right; gboolean mirror_left; gboolean flip_right; @@ -288,7 +307,10 @@ struct _ConfOptions } tmp; } stereo; - /* copy move rename */ + /** + * \struct cp_mv_rn + * copy move rename + */ struct { gint auto_start; gchar *auto_end; @@ -321,18 +343,15 @@ struct _ConfOptions gchar *template_string; } printer; - /* user-definable mouse buttons */ - gchar *mouse_button_8; - gchar *mouse_button_9; + gchar *mouse_button_8; /**< user-definable mouse buttons */ + gchar *mouse_button_9; /**< user-definable mouse buttons */ - /* class file filter */ - gboolean class_filter[FILE_FORMAT_CLASSES]; + gboolean class_filter[FILE_FORMAT_CLASSES]; /**< class file filter */ gboolean read_metadata_in_idle; - /* GPU - see main.c */ - gboolean disable_gpu; - gboolean override_disable_gpu; + gboolean disable_gpu; /**< GPU - see main.c */ + gboolean override_disable_gpu; /**< GPU - see main.c */ GList *disabled_plugins; }; diff --git a/src/pan-view/pan-types.h b/src/pan-view/pan-types.h index 9fd8916c..a90b2b42 100644 --- a/src/pan-view/pan-types.h +++ b/src/pan-view/pan-types.h @@ -179,7 +179,10 @@ struct _PanViewSearchUi GtkWidget *search_button_arrow; }; -// Defined in pan-view-filter.h +/** + * \typedef _PanViewFilterUi + * Defined in pan-view-filter.h + */ typedef struct _PanViewFilterUi PanViewFilterUi; typedef struct _PanWindow PanWindow; diff --git a/src/pan-view/pan-view-filter.h b/src/pan-view/pan-view-filter.h index 818da35d..1125ed84 100644 --- a/src/pan-view/pan-view-filter.h +++ b/src/pan-view/pan-view-filter.h @@ -58,7 +58,7 @@ struct _PanViewFilterUi GtkWidget *filter_check_buttons[FILE_FORMAT_CLASSES]; GtkListStore *filter_mode_model; GtkWidget *filter_mode_combo; - GList *filter_elements; // List of PanViewFilterElement. + GList *filter_elements; /**< List of #PanViewFilterElement. */ gint filter_classes; }; @@ -68,10 +68,16 @@ void pan_filter_activate_cb(const gchar *text, gpointer data); void pan_filter_toggle_cb(GtkWidget *button, gpointer data); void pan_filter_toggle_button_cb(GtkWidget *button, gpointer data); -// Creates a new PanViewFilterUi instance and returns it. +/** + * \headerfile pan_filter_ui_new + * Creates a new #PanViewFilterUi instance and returns it. + */ PanViewFilterUi *pan_filter_ui_new(PanWindow *pw); -// Destroys the specified PanViewFilterUi and sets the pointer to NULL. +/** + * \headerfile pan_filter_ui_destroy + * Destroys the specified #PanViewFilterUi and sets the pointer to NULL. + */ void pan_filter_ui_destroy(PanViewFilterUi **ui); gboolean pan_filter_fd_list(GList **fd_list, GList *filter_elements, gint filter_classes); diff --git a/src/pan-view/pan-view-search.h b/src/pan-view/pan-view-search.h index 88784b72..180dad07 100644 --- a/src/pan-view/pan-view-search.h +++ b/src/pan-view/pan-view-search.h @@ -30,10 +30,16 @@ void pan_search_activate(PanWindow *pw); void pan_search_activate_cb(const gchar *text, gpointer data); void pan_search_toggle_cb(GtkWidget *button, gpointer data); -// Creates a new PanViewSearchUi instance and returns it. +/** + * \headerfile pan_search_ui_new + * Creates a new #PanViewSearchUi instance and returns it. + */ PanViewSearchUi *pan_search_ui_new(PanWindow *pw); -// Destroys the specified PanViewSearchUi and sets the pointer to NULL. +/** + * \headerfile pan_search_ui_destroy + * Destroys the specified #PanViewSearchUi and sets the pointer to NULL. + */ void pan_search_ui_destroy(PanViewSearchUi **ui); #endif diff --git a/src/pixbuf-renderer.h b/src/pixbuf-renderer.h index fc1c4048..91f228fb 100644 --- a/src/pixbuf-renderer.h +++ b/src/pixbuf-renderer.h @@ -29,18 +29,35 @@ #define IS_PIXBUF_RENDERER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), TYPE_PIXBUF_RENDERER)) #define PIXBUF_RENDERER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), TYPE_PIXBUF_RENDERER, PixbufRendererClass)) -/* alpha channel checkerboard (same as gimp) */ +/** + * \def PR_ALPHA_CHECK_SIZE + * alpha channel checkerboard (same as gimp) + */ #define PR_ALPHA_CHECK_SIZE 16 -/* when scaling image to below this size, use nearest pixel for scaling + +/** + * \def PR_MIN_SCALE_SIZE + * when scaling image to below this size, use nearest pixel for scaling * (below about 4, the other scale types become slow generating their conversion tables) */ #define PR_MIN_SCALE_SIZE 8 -/* default size of tile cache (MiB) */ +/** + * \def PR_CACHE_SIZE_DEFAULT + * default size of tile cache (MiB) + */ #define PR_CACHE_SIZE_DEFAULT 8 -/* round A up/down to integer count of B */ +/** + * \def ROUND_UP + * round A up to integer count of B + */ #define ROUND_UP(A,B) ((gint)(((A)+(B)-1)/(B))*(B)) + +/** + * \def ROUND_DOWN + * round A down to integer count of B + */ #define ROUND_DOWN(A,B) ((gint)(((A))/(B))*(B)) @@ -66,33 +83,33 @@ typedef enum { } PixbufRendererScrollResetType; typedef enum { - TILE_RENDER_NONE = 0, /* do nothing */ - TILE_RENDER_AREA, /* render an area of the tile */ - TILE_RENDER_ALL /* render the whole tile */ + TILE_RENDER_NONE = 0, /**< do nothing */ + TILE_RENDER_AREA, /**< render an area of the tile */ + TILE_RENDER_ALL /**< render the whole tile */ } ImageRenderType; typedef enum { OVL_NORMAL = 0, - OVL_RELATIVE = 1 << 0, /* x,y coordinates are relative, negative values start bottom right */ - /* OVL_HIDE_ON_SCROLL = 1 << 1*/ /* hide temporarily when scrolling (not yet implemented) */ + OVL_RELATIVE = 1 << 0, /**< x,y coordinates are relative, negative values start bottom right */ + /* OVL_HIDE_ON_SCROLL = 1 << 1*/ /**< hide temporarily when scrolling (not yet implemented) */ } OverlayRendererFlags; struct _RendererFuncs { // void (*redraw)(void *renderer, gint x, gint y, gint w, gint h, // gint clamp, ImageRenderType render, gboolean new_data, gboolean only_existing); - void (*area_changed)(void *renderer, gint src_x, gint src_y, gint src_w, gint src_h); /* pixbuf area changed */ + void (*area_changed)(void *renderer, gint src_x, gint src_y, gint src_w, gint src_h); /**< pixbuf area changed */ void (*invalidate_region)(void *renderer, gint x, gint y, gint w, gint h); - void (*scroll)(void *renderer, gint x_off, gint y_off); /* scroll */ - void (*update_viewport)(void *renderer); /* window / wiewport / border color has changed */ - void (*update_pixbuf)(void *renderer, gboolean lazy); /* pixbuf has changed */ - void (*update_zoom)(void *renderer, gboolean lazy); /* zoom has changed */ + void (*scroll)(void *renderer, gint x_off, gint y_off); /**< scroll */ + void (*update_viewport)(void *renderer); /**< window / wiewport / border color has changed */ + void (*update_pixbuf)(void *renderer, gboolean lazy); /**< pixbuf has changed */ + void (*update_zoom)(void *renderer, gboolean lazy); /**< zoom has changed */ gint (*overlay_add)(void *renderer, GdkPixbuf *pixbuf, gint x, gint y, OverlayRendererFlags flags); void (*overlay_set)(void *renderer, gint id, GdkPixbuf *pixbuf, gint x, gint y); gboolean (*overlay_get)(void *renderer, gint id, GdkPixbuf **pixbuf, gint *x, gint *y); - void (*stereo_set)(void *renderer, gint stereo_mode); /* set stereo mode */ + void (*stereo_set)(void *renderer, gint stereo_mode); /**< set stereo mode */ void (*free)(void *renderer); }; @@ -101,46 +118,46 @@ struct _PixbufRenderer { GtkEventBox eventbox; - gint image_width; /* image actual dimensions (pixels) */ + gint image_width; /**< image actual dimensions (pixels) */ gint image_height; - gint stereo_pixbuf_offset_right; /* offset of the right part of the stereo image in pixbuf */ - gint stereo_pixbuf_offset_left; /* offset of the left part of the stereo image in pixbuf */ + gint stereo_pixbuf_offset_right; /**< offset of the right part of the stereo image in pixbuf */ + gint stereo_pixbuf_offset_left; /**< offset of the left part of the stereo image in pixbuf */ GdkPixbuf *pixbuf; - gint window_width; /* allocated size of window (drawing area) */ + gint window_width; /**< allocated size of window (drawing area) */ gint window_height; - gint viewport_width; /* allocated size of viewport (same as window for normal mode, half of window for SBS mode) */ + gint viewport_width; /**< allocated size of viewport (same as window for normal mode, half of window for SBS mode) */ gint viewport_height; - gint x_offset; /* offset of image start (non-zero when viewport < window) */ + gint x_offset; /**< offset of image start (non-zero when viewport < window) */ gint y_offset; - gint x_mouse; /* coordinates of the mouse taken from GtkEvent */ + gint x_mouse; /**< coordinates of the mouse taken from GtkEvent */ gint y_mouse; - gint vis_width; /* dimensions of visible part of image */ + gint vis_width; /**< dimensions of visible part of image */ gint vis_height; - gint width; /* size of scaled image (result) */ + gint width; /**< size of scaled image (result) */ gint height; - gint x_scroll; /* scroll offset of image (into width, height to start drawing) */ + gint x_scroll; /**< scroll offset of image (into width, height to start drawing) */ gint y_scroll; - gdouble norm_center_x; /* coordinates of viewport center in the image, in range 0.0 - 1.0 */ - gdouble norm_center_y; /* these coordinates are used for PR_SCROLL_RESET_NOCHANGE and should be preserved over periods with NULL pixbuf */ + gdouble norm_center_x; /**< coordinates of viewport center in the image, in range 0.0 - 1.0 */ + gdouble norm_center_y; /**< these coordinates are used for PR_SCROLL_RESET_NOCHANGE and should be preserved over periods with NULL pixbuf */ - gdouble subpixel_x_scroll; /* subpixel scroll alignment, used to prevent accumulation of rounding errors */ + gdouble subpixel_x_scroll; /**< subpixel scroll alignment, used to prevent accumulation of rounding errors */ gdouble subpixel_y_scroll; gdouble zoom_min; gdouble zoom_max; - gdouble zoom; /* zoom we want (0 is auto) */ - gdouble scale; /* zoom we got (should never be 0) */ + gdouble zoom; /**< zoom we want (0 is auto) */ + gdouble scale; /**< zoom we got (should never be 0) */ - gdouble aspect_ratio; /* screen pixel aspect ratio (2.0 for 3DTV SBS mode) */ + gdouble aspect_ratio; /**< screen pixel aspect ratio (2.0 for 3DTV SBS mode) */ GdkInterpType zoom_quality; gboolean zoom_2pass; @@ -150,7 +167,7 @@ struct _PixbufRenderer gboolean has_frame; - GtkWidget *parent_window; /* resize parent_window when image dimensions change */ + GtkWidget *parent_window; /**< resize parent_window when image dimensions change */ gboolean window_fit; gboolean window_limit; @@ -171,7 +188,7 @@ struct _PixbufRenderer gboolean source_tiles_enabled; gint source_tiles_cache_size; - GList *source_tiles; /* list of active source tiles */ + GList *source_tiles; /**< list of active source tiles */ gint source_tile_width; gint source_tile_height; @@ -187,9 +204,9 @@ struct _PixbufRenderer gboolean delay_flip; gboolean loading; gboolean complete; - gboolean debug_updated; /* debug only */ + gboolean debug_updated; /**< debug only */ - guint scroller_id; /* event source id */ + guint scroller_id; /**< event source id */ gint scroller_overlay; gint scroller_x; gint scroller_y; @@ -240,11 +257,15 @@ PixbufRenderer *pixbuf_renderer_new(void); void pixbuf_renderer_set_parent(PixbufRenderer *pr, GtkWindow *window); GtkWindow *pixbuf_renderer_get_parent(PixbufRenderer *pr); -/* display a pixbuf */ - +/** + * \headerfile pixbuf_renderer_set_pixbuf + * display a pixbuf + */ void pixbuf_renderer_set_pixbuf(PixbufRenderer *pr, GdkPixbuf *pixbuf, gdouble zoom); -/* same as pixbuf_renderer_set_pixbuf but waits with redrawing for pixbuf_renderer_area_changed */ +/** + * \headerfile pixbuf_renderer_set_pixbuf_lazy + * same as pixbuf_renderer_set_pixbuf but waits with redrawing for pixbuf_renderer_area_changed */ void pixbuf_renderer_set_pixbuf_lazy(PixbufRenderer *pr, GdkPixbuf *pixbuf, gdouble zoom, gint orientation, StereoPixbufData stereo_data); @@ -253,13 +274,18 @@ GdkPixbuf *pixbuf_renderer_get_pixbuf(PixbufRenderer *pr); void pixbuf_renderer_set_orientation(PixbufRenderer *pr, gint orientation); gint pixbuf_renderer_get_orientation(PixbufRenderer *pr); -/* sets the format of stereo data in the input pixbuf */ +/** + * \headerfile pixbuf_renderer_set_stereo_data + * sets the format of stereo data in the input pixbuf + */ void pixbuf_renderer_set_stereo_data(PixbufRenderer *pr, StereoPixbufData stereo_data); void pixbuf_renderer_set_post_process_func(PixbufRenderer *pr, PixbufRendererPostProcessFunc func, gpointer user_data, gboolean slow); -/* display an on-request array of pixbuf tiles */ - +/** + * \headerfile pixbuf_renderer_set_tiles + * display an on-request array of pixbuf tiles + */ void pixbuf_renderer_set_tiles(PixbufRenderer *pr, gint width, gint height, gint tile_width, gint tile_height, gint cache_size, PixbufRendererTileRequestFunc func_request, @@ -269,13 +295,17 @@ void pixbuf_renderer_set_tiles(PixbufRenderer *pr, gint width, gint height, void pixbuf_renderer_set_tiles_size(PixbufRenderer *pr, gint width, gint height); gint pixbuf_renderer_get_tiles(PixbufRenderer *pr); -/* move image data from source to pr, source is then set to NULL image */ - +/** + * \headerfile pixbuf_renderer_move + * move image data from source to pr, source is then set to NULL image + */ void pixbuf_renderer_move(PixbufRenderer *pr, PixbufRenderer *source); void pixbuf_renderer_copy(PixbufRenderer *pr, PixbufRenderer *source); -/* update region of existing image */ - +/** + * \headerfile pixbuf_renderer_area_changed + * update region of existing image + */ void pixbuf_renderer_area_changed(PixbufRenderer *pr, gint x, gint y, gint width, gint height); /* scrolling */ @@ -302,15 +332,23 @@ void pixbuf_renderer_zoom_set_limits(PixbufRenderer *pr, gdouble min, gdouble ma gboolean pixbuf_renderer_get_image_size(PixbufRenderer *pr, gint *width, gint *height); gboolean pixbuf_renderer_get_scaled_size(PixbufRenderer *pr, gint *width, gint *height); -/* region of image in pixel coordinates */ +/** + * \headerfile pixbuf_renderer_get_visible_rect + * region of image in pixel coordinates + */ gboolean pixbuf_renderer_get_visible_rect(PixbufRenderer *pr, GdkRectangle *rect); -/* actual size of the PixbufRenderer window minus borders, +/** + * \headerfile pixbuf_renderer_get_virtual_rect + * actual size of the PixbufRenderer window minus borders, * x and y are the scroll offset and include zoom factor. */ gboolean pixbuf_renderer_get_virtual_rect(PixbufRenderer *pr, GdkRectangle *rect); -/* background color */ +/** + * \headerfile pixbuf_renderer_set_color + * background color + */ void pixbuf_renderer_set_color(PixbufRenderer *pr, GdkColor *color); /* overlay */ @@ -322,7 +360,11 @@ gboolean pixbuf_renderer_overlay_get(PixbufRenderer *pr, gint id, GdkPixbuf **pi void pixbuf_renderer_overlay_remove(PixbufRenderer *pr, gint id); gboolean pixbuf_renderer_get_mouse_position(PixbufRenderer *pr, gint *x_pixel, gint *y_pixel); -/* x_pixel and y_pixel are the pixel coordinates \see pixbuf_renderer_get_mouse_position */ + +/** + * \headerfile pixbuf_renderer_get_pixel_colors + * x_pixel and y_pixel are the pixel coordinates see #pixbuf_renderer_get_mouse_position + */ gboolean pixbuf_renderer_get_pixel_colors(PixbufRenderer *pr, gint x_pixel, gint y_pixel, gint *r_mouse, gint *g_mouse, gint *b_mouse); @@ -333,8 +375,10 @@ void pixbuf_renderer_stereo_set(PixbufRenderer *pr, gint stereo_mode); gint pixbuf_renderer_stereo_get(PixbufRenderer *pr); void pixbuf_renderer_stereo_fixed_set(PixbufRenderer *pr, gint width, gint height, gint x1, gint y1, gint x2, gint y2); -/* protected - for renderer use only*/ - +/** + * \struct _SourceTile + * protected - for renderer use only + */ typedef struct _SourceTile SourceTile; struct _SourceTile { @@ -351,12 +395,12 @@ gboolean pr_clip_region(gint x, gint y, gint w, gint h, void pr_render_complete_signal(PixbufRenderer *pr); void pr_tile_coords_map_orientation(gint orientation, - gdouble tile_x, gdouble tile_y, /* coordinates of the tile */ + gdouble tile_x, gdouble tile_y, /**< coordinates of the tile */ gdouble image_w, gdouble image_h, gdouble tile_w, gdouble tile_h, gdouble *res_x, gdouble *res_y); void pr_tile_region_map_orientation(gint orientation, - gint area_x, gint area_y, /* coordinates of the area inside tile */ + gint area_x, gint area_y, /**< coordinates of the area inside tile */ gint tile_w, gint tile_h, gint area_w, gint area_h, gint *res_x, gint *res_y, diff --git a/src/preferences.h b/src/preferences.h index 1ec987ba..d40675b9 100644 --- a/src/preferences.h +++ b/src/preferences.h @@ -26,7 +26,10 @@ void show_config_window(void); void show_about_window(LayoutWindow *lw); -/* reusable helper functions */ +/** + * \headerfile config_entry_to_option + * reusable helper functions + */ void config_entry_to_option(GtkWidget *entry, gchar **option, gchar *(*func)(const gchar *)); diff --git a/src/print.h b/src/print.h index 1c85ce56..e7b68eb5 100644 --- a/src/print.h +++ b/src/print.h @@ -23,7 +23,10 @@ #define PRINT_H -/* do not free selection or list, the print window takes control of them */ +/** + * \headerfile print_window_new + * do not free selection or list, the print window takes control of them + */ void print_window_new(FileData *fd, GList *selection, GList *list, GtkWidget *parent); diff --git a/src/thumb_standard.h b/src/thumb_standard.h index 8544253d..418f723b 100644 --- a/src/thumb_standard.h +++ b/src/thumb_standard.h @@ -86,7 +86,9 @@ void thumb_loader_std_free(ThumbLoaderStd *tl); GdkPixbuf *thumb_loader_std_get_pixbuf(ThumbLoaderStd *tl); -/* validates a non local thumbnail file, +/** + * \headerfile thumb_loader_std_thumb_file_validate + * validates a non local thumbnail file, * calling func_valid with the information when app is idle * for thumbnail's without a file: uri, validates against allowed_age in days */ diff --git a/src/typedefs.h b/src/typedefs.h index 1291e0ed..1fccfe5e 100644 --- a/src/typedefs.h +++ b/src/typedefs.h @@ -48,16 +48,14 @@ typedef enum { DIRVIEW_LIST, DIRVIEW_TREE, - // Keep this up to date! - DIRVIEW_LAST = DIRVIEW_TREE + DIRVIEW_LAST = DIRVIEW_TREE /**< Keep this up to date! */ } DirViewType; typedef enum { FILEVIEW_LIST, FILEVIEW_ICON, - // Keep this up to date! - FILEVIEW_LAST = FILEVIEW_ICON + FILEVIEW_LAST = FILEVIEW_ICON /**< Keep this up to date! */ } FileViewType; #define CMD_COPY "geeqie-copy-command.desktop" @@ -80,7 +78,10 @@ typedef enum { SORT_CLASS } SortType; -/* drag and drop default action */ +/** + * \typedef DnDAction + * drag and drop default action + */ typedef enum { DND_ACTION_ASK, DND_ACTION_COPY, @@ -88,9 +89,9 @@ typedef enum { } DnDAction; typedef enum { - ALTER_NONE, /* do nothing */ + ALTER_NONE, /**< do nothing */ ALTER_ROTATE_90, - ALTER_ROTATE_90_CC, /* counterclockwise */ + ALTER_ROTATE_90_CC, /**< counterclockwise */ ALTER_ROTATE_180, ALTER_MIRROR, ALTER_FLIP, @@ -156,15 +157,17 @@ typedef enum { FILE_FORMAT_CLASSES } FileFormatClass; -/* defined in preferences.c */ -extern gchar *format_class_list[]; +extern gchar *format_class_list[]; /**< defined in preferences.c */ +/** + * \typedef SecureSaveErrno + * see err field in #SecureSaveInfo + */ typedef enum { SS_ERR_NONE = 0, SS_ERR_DISABLED, /**< secsave is disabled. */ SS_ERR_OUT_OF_MEM, /**< memory allocation failure */ - /* see err field in SecureSaveInfo */ SS_ERR_OPEN_READ, SS_ERR_OPEN_WRITE, SS_ERR_STAT, @@ -181,14 +184,14 @@ typedef enum { } NotifyPriority; typedef enum { - NOTIFY_MARKS = 1 << 1, /* changed marks */ - NOTIFY_PIXBUF = 1 << 2, /* image was read into fd->pixbuf */ - NOTIFY_HISTMAP = 1 << 3, /* histmap was read into fd->histmap */ - NOTIFY_ORIENTATION = 1 << 4, /* image was rotated */ - NOTIFY_METADATA = 1 << 5, /* changed image metadata, not yet written */ - NOTIFY_GROUPING = 1 << 6, /* change in fd->sidecar_files or fd->parent */ - NOTIFY_REREAD = 1 << 7, /* changed file size, date, etc., file name remains unchanged */ - NOTIFY_CHANGE = 1 << 8 /* generic change described by fd->change */ + NOTIFY_MARKS = 1 << 1, /**< changed marks */ + NOTIFY_PIXBUF = 1 << 2, /**< image was read into fd->pixbuf */ + NOTIFY_HISTMAP = 1 << 3, /**< histmap was read into fd->histmap */ + NOTIFY_ORIENTATION = 1 << 4, /**< image was rotated */ + NOTIFY_METADATA = 1 << 5, /**< changed image metadata, not yet written */ + NOTIFY_GROUPING = 1 << 6, /**< change in fd->sidecar_files or fd->parent */ + NOTIFY_REREAD = 1 << 7, /**< changed file size, date, etc., file name remains unchanged */ + NOTIFY_CHANGE = 1 << 8 /**< generic change described by fd->change */ } NotifyType; typedef enum { @@ -199,7 +202,7 @@ typedef enum { CHANGE_WARN_CHANGED_EXT = 1 << 3, CHANGE_WARN_UNSAVED_META = 1 << 4, CHANGE_WARN_NO_WRITE_PERM_DEST_DIR = 1 << 5, - CHANGE_ERROR_MASK = (~0U) << 8, /* the values below are fatal errors */ + CHANGE_ERROR_MASK = (~0U) << 8, /**< the values below are fatal errors */ CHANGE_NO_READ_PERM = 1 << 8, CHANGE_NO_WRITE_PERM_DIR = 1 << 9, CHANGE_NO_DEST_DIR = 1 << 10, @@ -211,8 +214,8 @@ typedef enum { } ChangeError; typedef enum { - METADATA_PLAIN = 0, /* format that can be edited and written back */ - METADATA_FORMATTED = 1 /* for display only */ + METADATA_PLAIN = 0, /**< format that can be edited and written back */ + METADATA_FORMATTED = 1 /**< for display only */ } MetadataFormat; typedef enum { @@ -228,21 +231,21 @@ typedef enum { } ToolbarType; typedef enum { - PR_STEREO_NONE = 0, /* do nothing */ - PR_STEREO_DUAL = 1 << 0, /* independent stereo buffers, for example nvidia opengl */ - PR_STEREO_FIXED = 1 << 1, /* custom position */ - PR_STEREO_HORIZ = 1 << 2, /* side by side */ - PR_STEREO_VERT = 1 << 3, /* above below */ - PR_STEREO_RIGHT = 1 << 4, /* render right buffer */ - PR_STEREO_ANAGLYPH_RC = 1 << 5, /* anaglyph red-cyan */ - PR_STEREO_ANAGLYPH_GM = 1 << 6, /* anaglyph green-magenta */ - PR_STEREO_ANAGLYPH_YB = 1 << 7, /* anaglyph yellow-blue */ - PR_STEREO_ANAGLYPH_GRAY_RC = 1 << 8, /* anaglyph gray red-cyan*/ - PR_STEREO_ANAGLYPH_GRAY_GM = 1 << 9, /* anaglyph gray green-magenta */ - PR_STEREO_ANAGLYPH_GRAY_YB = 1 << 10, /* anaglyph gray yellow-blue */ - PR_STEREO_ANAGLYPH_DB_RC = 1 << 11, /* anaglyph dubois red-cyan */ - PR_STEREO_ANAGLYPH_DB_GM = 1 << 12, /* anaglyph dubois green-magenta */ - PR_STEREO_ANAGLYPH_DB_YB = 1 << 13, /* anaglyph dubois yellow-blue */ + PR_STEREO_NONE = 0, /**< do nothing */ + PR_STEREO_DUAL = 1 << 0, /**< independent stereo buffers, for example nvidia opengl */ + PR_STEREO_FIXED = 1 << 1, /**< custom position */ + PR_STEREO_HORIZ = 1 << 2, /**< side by side */ + PR_STEREO_VERT = 1 << 3, /**< above below */ + PR_STEREO_RIGHT = 1 << 4, /**< render right buffer */ + PR_STEREO_ANAGLYPH_RC = 1 << 5, /**< anaglyph red-cyan */ + PR_STEREO_ANAGLYPH_GM = 1 << 6, /**< anaglyph green-magenta */ + PR_STEREO_ANAGLYPH_YB = 1 << 7, /**< anaglyph yellow-blue */ + PR_STEREO_ANAGLYPH_GRAY_RC = 1 << 8, /**< anaglyph gray red-cyan*/ + PR_STEREO_ANAGLYPH_GRAY_GM = 1 << 9, /**< anaglyph gray green-magenta */ + PR_STEREO_ANAGLYPH_GRAY_YB = 1 << 10, /**< anaglyph gray yellow-blue */ + PR_STEREO_ANAGLYPH_DB_RC = 1 << 11, /**< anaglyph dubois red-cyan */ + PR_STEREO_ANAGLYPH_DB_GM = 1 << 12, /**< anaglyph dubois green-magenta */ + PR_STEREO_ANAGLYPH_DB_YB = 1 << 13, /**< anaglyph dubois yellow-blue */ PR_STEREO_ANAGLYPH = PR_STEREO_ANAGLYPH_RC | PR_STEREO_ANAGLYPH_GM | PR_STEREO_ANAGLYPH_YB | @@ -251,18 +254,18 @@ typedef enum { PR_STEREO_ANAGLYPH_GRAY_YB | PR_STEREO_ANAGLYPH_DB_RC | PR_STEREO_ANAGLYPH_DB_GM | - PR_STEREO_ANAGLYPH_DB_YB, /* anaglyph mask */ + PR_STEREO_ANAGLYPH_DB_YB, /**< anaglyph mask */ - PR_STEREO_MIRROR_LEFT = 1 << 14, /* mirror */ - PR_STEREO_FLIP_LEFT = 1 << 15, /* flip */ + PR_STEREO_MIRROR_LEFT = 1 << 14, /**< mirror */ + PR_STEREO_FLIP_LEFT = 1 << 15, /**< flip */ - PR_STEREO_MIRROR_RIGHT = 1 << 16, /* mirror */ - PR_STEREO_FLIP_RIGHT = 1 << 17, /* flip */ + PR_STEREO_MIRROR_RIGHT = 1 << 16, /**< mirror */ + PR_STEREO_FLIP_RIGHT = 1 << 17, /**< flip */ - PR_STEREO_MIRROR = PR_STEREO_MIRROR_LEFT | PR_STEREO_MIRROR_RIGHT, /* mirror mask*/ - PR_STEREO_FLIP = PR_STEREO_FLIP_LEFT | PR_STEREO_FLIP_RIGHT, /* flip mask*/ - PR_STEREO_SWAP = 1 << 18, /* swap left and right buffers */ - PR_STEREO_TEMP_DISABLE = 1 << 19, /* temporarily disable stereo mode if source image is not stereo */ + PR_STEREO_MIRROR = PR_STEREO_MIRROR_LEFT | PR_STEREO_MIRROR_RIGHT, /**< mirror mask*/ + PR_STEREO_FLIP = PR_STEREO_FLIP_LEFT | PR_STEREO_FLIP_RIGHT, /**< flip mask*/ + PR_STEREO_SWAP = 1 << 18, /**< swap left and right buffers */ + PR_STEREO_TEMP_DISABLE = 1 << 19, /**< temporarily disable stereo mode if source image is not stereo */ PR_STEREO_HALF = 1 << 20 } PixbufRendererStereoMode; @@ -343,16 +346,16 @@ typedef struct _EditorDescription EditorDescription; typedef struct _CommandLine CommandLine; struct _Histogram { - gint histogram_channel; /* drawing mode for histogram */ - gint histogram_mode; /* logarithmical or not */ - guint vgrid; /* number of vertical divisions, 0 for none */ - guint hgrid; /* number of horizontal divisions, 0 for none */ + gint histogram_channel; /**< drawing mode for histogram */ + gint histogram_mode; /**< logarithmical or not */ + guint vgrid; /**< number of vertical divisions, 0 for none */ + guint hgrid; /**< number of horizontal divisions, 0 for none */ struct { - int R; /* red */ - int G; /* green */ - int B; /* blue */ - int A; /* alpha */ - } grid_color; /* grid color */ + int R; /**< red */ + int G; /**< green */ + int B; /**< blue */ + int A; /**< alpha */ + } grid_color; /**< grid color */ }; @@ -369,7 +372,7 @@ struct _ThumbLoader gboolean standard_loader; ImageLoader *il; - FileData *fd; /* fd->pixbuf contains final (scaled) image when done */ + FileData *fd; /**< fd->pixbuf contains final (scaled) image when done */ gboolean cache_enable; gboolean cache_hit; @@ -384,7 +387,7 @@ struct _ThumbLoader gpointer data; - guint idle_done_id; /* event source id */ + guint idle_done_id; /**< event source id */ }; struct _AnimationData @@ -431,8 +434,7 @@ struct _CollectionData gint window_w; gint window_h; - /* contents changed since save flag */ - gboolean changed; + gboolean changed; /**< contents changed since save flag */ GHashTable *existence; }; @@ -452,7 +454,7 @@ struct _CollectTable CollectInfo *click_info; GtkWidget *tip_window; - guint tip_delay_id; /* event source id */ + guint tip_delay_id; /**< event source id */ CollectInfo *tip_info; GdkWindow *marker_window; @@ -469,14 +471,13 @@ struct _CollectTable CollectInfo *drop_info; GList *drop_list; - guint sync_idle_id; /* event source id */ - guint drop_idle_id; /* event source id */ + guint sync_idle_id; /**< event source id */ + guint drop_idle_id; /**< event source id */ gboolean show_text; gboolean show_stars; - /* file list for edit menu */ - GList *editmenu_fd_list; + GList *editmenu_fd_list; /**< file list for edit menu */ }; struct _CollectWindow @@ -497,28 +498,28 @@ typedef void (* ImageTileDisposeFunc)(ImageWindow *imd, gint x, gint y, struct _ImageWindow { - GtkWidget *widget; /* use this to add it and show it */ + GtkWidget *widget; /**< use this to add it and show it */ GtkWidget *pr; GtkWidget *frame; FileData *image_fd; - gboolean unknown; /* failed to load image */ + gboolean unknown; /**< failed to load image */ - ImageLoader *il; /* FIXME - image loader should probably go to FileData, but it must first support + ImageLoader *il; /**< FIXME - image loader should probably go to FileData, but it must first support sending callbacks to multiple ImageWindows in parallel */ - gint has_frame; /* not boolean, see image_new() */ + gint has_frame; /**< not boolean, see image_new() */ /* top level (not necessarily parent) window */ - gboolean top_window_sync; /* resize top_window when image dimensions change */ - GtkWidget *top_window; /* window that gets title, and window to resize when 'fitting' */ - gchar *title; /* window title to display left of file name */ - gchar *title_right; /* window title to display right of file name */ - gboolean title_show_zoom; /* option to include zoom in window title */ + gboolean top_window_sync; /**< resize top_window when image dimensions change */ + GtkWidget *top_window; /**< window that gets title, and window to resize when 'fitting' */ + gchar *title; /**< window title to display left of file name */ + gchar *title_right; /**< window title to display right of file name */ + gboolean title_show_zoom; /**< option to include zoom in window title */ gboolean completed; - ImageState state; /* mask of IMAGE_STATE_* flags about current image */ + ImageState state; /**< mask of IMAGE_STATE_* flags about current image */ void (*func_update)(ImageWindow *imd, gpointer data); void (*func_complete)(ImageWindow *imd, gint preload, gpointer data); @@ -542,7 +543,10 @@ struct _ImageWindow gpointer data_scroll; gpointer data_focus_in; - /* scroll notification (for scroll bar implementation) */ + /** + * \headerfile func_scroll_notify + * scroll notification (for scroll bar implementation) + */ void (*func_scroll_notify)(ImageWindow *, gint x, gint y, gint width, gint height, gpointer); gpointer data_scroll_notify; @@ -589,7 +593,7 @@ struct _FileDataChangeInfo { struct _FileData { guint magick; gint type; - gchar *original_path; /* key to file_data_pool hash table */ + gchar *original_path; /**< key to file_data_pool hash table */ gchar *path; const gchar *name; const gchar *extension; @@ -600,26 +604,26 @@ struct _FileData { gint64 size; time_t date; time_t cdate; - mode_t mode; /* this is needed at least for notification in view_dir because it is preserved after the file/directory is deleted */ + mode_t mode; /**< this is needed at least for notification in view_dir because it is preserved after the file/directory is deleted */ gint sidecar_priority; - guint marks; /* each bit represents one mark */ - guint valid_marks; /* zero bit means that the corresponding mark needs to be reread */ + guint marks; /**< each bit represents one mark */ + guint valid_marks; /**< zero bit means that the corresponding mark needs to be reread */ GList *sidecar_files; - FileData *parent; /* parent file if this is a sidecar file, NULL otherwise */ - FileDataChangeInfo *change; /* for rename, move ... */ + FileData *parent; /**< parent file if this is a sidecar file, NULL otherwise */ + FileDataChangeInfo *change; /**< for rename, move ... */ GdkPixbuf *thumb_pixbuf; - GdkPixbuf *pixbuf; /* full-size image, only complete images, NULL during loading + GdkPixbuf *pixbuf; /**< full-size image, only complete images, NULL during loading all FileData with non-NULL pixbuf are referenced by image_cache */ HistMap *histmap; gboolean locked; gint ref; - gint version; /* increased when any field in this structure is changed */ + gint version; /**< increased when any field in this structure is changed */ gboolean disable_grouping; gint user_orientation; @@ -628,7 +632,7 @@ struct _FileData { ExifData *exif; time_t exifdate; time_t exifdate_digitized; - GHashTable *modified_xmp; // hash table which contains unwritten xmp metadata in format: key->list of string values + GHashTable *modified_xmp; /**< hash table which contains unwritten xmp metadata in format: key->list of string values */ GList *cached_metadata; gint rating; gboolean metadata_in_idle_loaded; @@ -637,7 +641,7 @@ struct _FileData { gchar *group; gchar *sym_link; - SelectionType selected; // Used by view_file_icon. + SelectionType selected; /**< Used by view_file_icon. */ gint page_num; gint page_total; @@ -793,11 +797,11 @@ struct _LayoutWindow // gint tools_float; // gint tools_hidden; - GtkWidget *menu_tool_bar; /*Combined menu and toolbar box */ - GtkWidget *menu_bar; /* referenced by lw, exist during whole lw lifetime */ + GtkWidget *menu_tool_bar; /**< Combined menu and toolbar box */ + GtkWidget *menu_bar; /**< referenced by lw, exist during whole lw lifetime */ /* toolbar */ - GtkWidget *toolbar[TOOLBAR_COUNT]; /* referenced by lw, exist during whole lw lifetime */ + GtkWidget *toolbar[TOOLBAR_COUNT]; /**< referenced by lw, exist during whole lw lifetime */ // gint toolbar_hidden; // GtkWidget *thumb_button; @@ -827,15 +831,13 @@ struct _LayoutWindow SortType sort_method; gboolean sort_ascend; - /* status bar */ - - GtkWidget *info_box; - GtkWidget *info_progress_bar; - GtkWidget *info_sort; - GtkWidget *info_status; - GtkWidget *info_details; - GtkWidget *info_zoom; - GtkWidget *info_pixel; + GtkWidget *info_box; /**< status bar */ + GtkWidget *info_progress_bar; /**< status bar */ + GtkWidget *info_sort; /**< status bar */ + GtkWidget *info_status; /**< status bar */ + GtkWidget *info_details; /**< status bar */ + GtkWidget *info_zoom; /**< status bar */ + GtkWidget *info_pixel; /**< status bar */ /* slide show */ @@ -853,18 +855,18 @@ struct _LayoutWindow /* misc */ - GtkWidget *utility_box; /* referenced by lw, exist during whole lw lifetime */ - GtkWidget *utility_paned; /* between image and bar */ + GtkWidget *utility_box; /**< referenced by lw, exist during whole lw lifetime */ + GtkWidget *utility_paned; /**< between image and bar */ GtkWidget *bar_sort; GtkWidget *bar; - gboolean bar_sort_enabled; /* Set during start-up, and checked when the editors have loaded */ + gboolean bar_sort_enabled; /**< Set during start-up, and checked when the editors have loaded */ // gint bar_enabled; // gint bar_width; GtkWidget *exif_window; - GtkWidget *sar_window; /* Search and Run window */ + GtkWidget *sar_window; /**< Search and Run window */ AnimationData *animation; @@ -885,7 +887,7 @@ struct _ViewDir FileData *drop_fd; GList *drop_list; - guint drop_scroll_id; /* event source id */ + guint drop_scroll_id; /**< event source id */ /* func list */ void (*select_func)(ViewDir *vd, FileData *fd, gpointer data); @@ -908,7 +910,7 @@ struct _ViewDirInfoList struct _ViewDirInfoTree { - guint drop_expand_id; /* event source id */ + guint drop_expand_id; /**< event source id */ gint busy_ref; }; @@ -965,11 +967,10 @@ struct _ViewFile guint stars_id; /* refresh */ - guint refresh_idle_id; /* event source id */ - time_t time_refresh_set; /* time when refresh_idle_id was set */ + guint refresh_idle_id; /**< event source id */ + time_t time_refresh_set; /**< time when refresh_idle_id was set */ - /* file list for edit menu */ - GList *editmenu_fd_list; + GList *editmenu_fd_list; /**< file list for edit menu */ guint read_metadata_in_idle_id; }; @@ -981,7 +982,7 @@ struct _ViewFileInfoList gboolean thumbs_enabled; - guint select_idle_id; /* event source id */ + guint select_idle_id; /**< event source id */ }; struct _ViewFileInfoIcon @@ -994,7 +995,7 @@ struct _ViewFileInfoIcon FileData *prev_selection; GtkWidget *tip_window; - guint tip_delay_id; /* event source id */ + guint tip_delay_id; /**< event source id */ FileData *tip_fd; FileData *click_fd; @@ -1008,8 +1009,8 @@ struct _ViewFileInfoIcon struct _SlideShowData { - LayoutWindow *lw; /* use this window to display the slideshow */ - ImageWindow *imd; /* use this window only if lw is not available, + LayoutWindow *lw; /**< use this window to display the slideshow */ + ImageWindow *imd; /**< use this window only if lw is not available, FIXME: it is probably required only by img-view.c and should be dropped with it */ GList *filelist; @@ -1022,7 +1023,7 @@ struct _SlideShowData FileData *slide_fd; guint slide_count; - guint timeout_id; /* event source id */ + guint timeout_id; /**< event source id */ gboolean from_selection; @@ -1040,17 +1041,17 @@ struct _FullScreenData GtkWidget *normal_window; ImageWindow *normal_imd; - guint hide_mouse_id; /* event source id */ - guint busy_mouse_id; /* event source id */ + guint hide_mouse_id; /**< event source id */ + guint busy_mouse_id; /**< event source id */ gint cursor_state; - guint saver_block_id; /* event source id */ + guint saver_block_id; /**< event source id */ void (*stop_func)(FullScreenData *, gpointer); gpointer stop_data; - gboolean same_region; /* the returned region will overlap the current location of widget. */ + gboolean same_region; /**< the returned region will overlap the current location of widget. */ }; struct _PixmapFolders diff --git a/src/ui_bookmark.h b/src/ui_bookmark.h index de2f30e1..276e869c 100644 --- a/src/ui_bookmark.h +++ b/src/ui_bookmark.h @@ -33,7 +33,10 @@ void bookmark_list_set_editable(GtkWidget *list, gint editable); void bookmark_list_set_only_directories(GtkWidget *list, gint only_directories); void bookmark_list_add(GtkWidget *list, const gchar *name, const gchar *path); -/* allows apps to set up the defaults */ +/** + * \headerfile bookmark_add_default + * allows apps to set up the defaults + */ void bookmark_add_default(const gchar *name, const gchar *path); diff --git a/src/ui_fileops.h b/src/ui_fileops.h index 0eba9d0c..3542560e 100644 --- a/src/ui_fileops.h +++ b/src/ui_fileops.h @@ -80,7 +80,9 @@ gboolean move_file(const gchar *s, const gchar *t); gboolean rename_file(const gchar *s, const gchar *t); gchar *get_current_dir(void); -/* return True on success, it is up to you to free +/** + * \headerfile string_list_free + * return True on success, it is up to you to free * the lists with string_list_free() */ void string_list_free(GList *list); @@ -96,7 +98,10 @@ gchar *remove_extension_from_path(const gchar *path); gboolean file_extension_match(const gchar *path, const gchar *ext); -/* warning note: this modifies path string! */ +/** + * \headerfile parse_out_relatives + * warning note: this modifies path string! + */ void parse_out_relatives(gchar *path); gboolean file_in_path(const gchar *name); @@ -104,9 +109,11 @@ gboolean file_in_path(const gchar *name); gboolean recursive_mkdir_if_not_exists(const gchar *path, mode_t mode); -/* generate md5 string from file, +/** + * \headerfile md5_text_from_file_utf8 + * generate md5 string from file, * on failure returns newly allocated copy of error_text, error_text may be NULL - */ + */ gchar *md5_text_from_file_utf8(const gchar *path, const gchar *error_text); gboolean md5_get_digest_from_file_utf8(const gchar *path, guchar digest[16]); diff --git a/src/ui_menu.h b/src/ui_menu.h index 4c9faa5f..3c9b6ae4 100644 --- a/src/ui_menu.h +++ b/src/ui_menu.h @@ -37,13 +37,18 @@ GtkWidget *menu_item_add_radio(GtkWidget *menu, const gchar *label, gpointer ite GCallback func, gpointer data); void menu_item_add_divider(GtkWidget *menu); -/* use to avoid mnemonics, for example filenames */ +/** + * \headerfile menu_item_add_simple + * use to avoid mnemonics, for example filenames + */ GtkWidget *menu_item_add_simple(GtkWidget *menu, const gchar *label, GCallback func, gpointer data); GtkWidget *popup_menu_short_lived(void); -/* clamp a menu's position to within the screen +/** + * \headerfile popup_menu_position_clamp + * clamp a menu's position to within the screen * if menu will attempt to stay out of region y to y+height */ gboolean popup_menu_position_clamp(GtkMenu *menu, gint *x, gint *y, gint height); diff --git a/src/ui_misc.h b/src/ui_misc.h index b260e422..671f83f0 100644 --- a/src/ui_misc.h +++ b/src/ui_misc.h @@ -32,30 +32,61 @@ /* HIG 2.0 chapter 8 defines: */ -/* space between elements within control (ex: icon and it's text) */ +/** + * \def PREF_PAD_GAP + * space between elements within control (ex: icon and it's text) + */ #define PREF_PAD_GAP 6 -/* space between label and control(s) */ + +/** + * \def PREF_PAD_SPACE + * space between label and control(s) + */ #define PREF_PAD_SPACE 12 -/* space between window border and controls */ + +/** + * \def PREF_PAD_BORDER + * space between window border and controls + */ #define PREF_PAD_BORDER 12 -/* indent for group members */ + +/** + * \def PREF_PAD_INDENT + * indent for group members + */ #define PREF_PAD_INDENT 12 -/* vertical space between groups */ + +/** + * \def PREF_PAD_GROUP + * vertical space between groups + */ #define PREF_PAD_GROUP 18 /* HIG 2.0 chapter 3.13 defines: */ -/* gap between buttons in a dialog */ +/** + * \def PREF_PAD_BUTTON_GAP + * gap between buttons in a dialog + */ #define PREF_PAD_BUTTON_GAP 6 -/* space between buttons in a dialog and it's contents */ + +/** + * \def PREF_PAD_BUTTON_SPACE + * space between buttons in a dialog and it's contents + */ #define PREF_PAD_BUTTON_SPACE 24 /* and these are not in the GNOME HIG */ -/* gap between similar toolbar items (buttons) */ +/** + * \def PREF_PAD_TOOLBAR_GAP + * gap between similar toolbar items (buttons) + */ #define PREF_PAD_TOOLBAR_GAP 0 -/* HIG 2.0 states 6 pixels between icons and text, +/** + * \def PREF_PAD_BUTTON_ICON_GAP + * HIG 2.0 states 6 pixels between icons and text, * but GTK's stock buttons ignore this (hard coded to 2), we do it too for consistency */ #define PREF_PAD_BUTTON_ICON_GAP 2 diff --git a/src/ui_spinner.h b/src/ui_spinner.h index bf602c49..bae7c96e 100644 --- a/src/ui_spinner.h +++ b/src/ui_spinner.h @@ -29,17 +29,19 @@ extern const guint8 icon_spinner[]; extern const guint8 icon_tabcomp[]; -/* if path is NULL, the built in spinner is used, +/** + * \headerfile spinner_new + * if path is NULL, the built in spinner is used, * otherwise path must be the location of the first image of the - * spinner without the 00.png portion of the pathname, example: + * spinner without the 00.png portion of the pathname, example: \n * - * /path/to/spinnerimg_ + * /path/to/spinnerimg_ \n * - * the files required are then: + * the files required are then: \n * - * /path/to/spinnerimg_00.png non-animated state - * /path/to/spinnerimg_01.png animation frame 1 - * /path/to/spinnerimg_02.png animation frame 2 + * /path/to/spinnerimg_00.png non-animated state \n + * /path/to/spinnerimg_01.png animation frame 1 \n + * /path/to/spinnerimg_02.png animation frame 2 \n * [continues to last frame...] */ GtkWidget *spinner_new(const gchar *path, gint interval); diff --git a/src/ui_tree_edit.h b/src/ui_tree_edit.h index fc7ef712..72ca94b6 100644 --- a/src/ui_tree_edit.h +++ b/src/ui_tree_edit.h @@ -42,57 +42,80 @@ struct _TreeEditData }; -/* +/** + * \headerfile tree_edit_by_path * edit_func: return TRUE if rename successful, FALSE on failure. */ gboolean tree_edit_by_path(GtkTreeView *tree, GtkTreePath *tpath, gint column, const gchar *text, gboolean (*edit_func)(TreeEditData *, const gchar *, const gchar *, gpointer), gpointer data); -/* returns location of cell in screen coordinates */ +/** + * \headerfile tree_view_get_cell_origin + * returns location of cell in screen coordinates + */ gboolean tree_view_get_cell_origin(GtkTreeView *widget, GtkTreePath *tpath, gint column, gboolean text_cell_only, gint *x, gint *y, gint *width, gint *height); -/* similar to above, but limits the returned area to that of the tree window */ + +/** + * \headerfile tree_view_get_cell_clamped + * similar to above, but limits the returned area to that of the tree window + */ void tree_view_get_cell_clamped(GtkTreeView *widget, GtkTreePath *tpath, gint column, gboolean text_cell_only, gint *x, gint *y, gint *width, gint *height); -/* return 0 = row visible, -1 = row is above, 1 = row is below visible region - * if fully_visible is TRUE, the behavior changes to return -1/1 if _any_ part of the cell is out of view */ +/** + * \headerfile tree_view_row_get_visibility + * return 0 = row visible, -1 = row is above, 1 = row is below visible region \n + * if fully_visible is TRUE, the behavior changes to return -1/1 if _any_ part of the cell is out of view + */ gint tree_view_row_get_visibility(GtkTreeView *widget, GtkTreeIter *iter, gboolean fully_visible); -/* scrolls to make row visible, if necessary +/** + * \headerfile tree_view_row_make_visible + * scrolls to make row visible, if necessary * return is same as above (before the scroll) */ gint tree_view_row_make_visible(GtkTreeView *widget, GtkTreeIter *iter, gboolean center); -/* if iter is location of cursor, moves cursor to nearest row */ +/** + * \headerfile tree_view_move_cursor_away + * if iter is location of cursor, moves cursor to nearest row + */ gboolean tree_view_move_cursor_away(GtkTreeView *widget, GtkTreeIter *iter, gboolean only_selected); -/* utility to return row position of given GtkTreePath +/** + * \headerfile tree_path_to_row + * utility to return row position of given GtkTreePath */ gint tree_path_to_row(GtkTreePath *tpath); -/* shifts a GdkColor values lighter or darker - * val is percent from 1 to 100, or -1 for default (usually 10%) +/** + * \headerfile shift_color + * shifts a GdkColor values lighter or darker \n + * val is percent from 1 to 100, or -1 for default (usually 10%) \n * direction is -1 darker, 0 auto, 1 lighter */ void shift_color(GdkColor *src, gshort val, gint direction); -/* +/** + * \headerfile style_shift_color * Shifts a style's color for given state - * Useful for alternating dark/light rows in lists. + * Useful for alternating dark/light rows in lists. \n * * shift_value is 1 to 100, representing the percent of the shift. */ void style_shift_color(GtkStyle *style, GtkStateType type, gshort shift_value, gint direction); -/* +/** + * \def STYLE_SHIFT_STANDARD * The standard shift percent for alternating list row colors */ #define STYLE_SHIFT_STANDARD 10 -/* +/** + * \headerfile widget_auto_scroll_start * auto scroll, set scroll_speed or region_size to -1 to their respective the defaults * notify_func will be called before a scroll, return FALSE to turn off autoscroll */ diff --git a/src/ui_utildlg.h b/src/ui_utildlg.h index 963d3271..05ae012c 100644 --- a/src/ui_utildlg.h +++ b/src/ui_utildlg.h @@ -28,10 +28,10 @@ typedef struct _GenericDialog GenericDialog; struct _GenericDialog { - GtkWidget *dialog; /* window */ - GtkWidget *vbox; /* place to add widgets */ + GtkWidget *dialog; /**< window */ + GtkWidget *vbox; /**< place to add widgets */ - GtkWidget *hbox; /* button hbox */ + GtkWidget *hbox; /**< button hbox */ gboolean auto_close; @@ -39,8 +39,8 @@ struct _GenericDialog void (*cancel_cb)(GenericDialog *, gpointer); gpointer data; - /* private */ - GtkWidget *cancel_button; + GtkWidget *cancel_button; /**< private */ + }; typedef struct _FileDialog FileDialog; @@ -59,7 +59,10 @@ struct _FileDialog }; -/* When parent is not NULL, the dialog is set as a transient of the window containing parent */ +/** + * \headerfile generic_dialog_new + * When parent is not NULL, the dialog is set as a transient of the window containing parent + */ GenericDialog *generic_dialog_new(const gchar *title, const gchar *role, GtkWidget *parent, gboolean auto_close, @@ -87,10 +90,12 @@ void file_dialog_close(FileDialog *fd); GtkWidget *file_dialog_add_button(FileDialog *fd, const gchar *stock_id, const gchar *text, void (*func_cb)(FileDialog *, gpointer), gboolean is_default); -/* default_path is default base directory, and is only used if no history - * exists for history_key (HOME is used if default_path is NULL). +/** + * \headerfile file_dialog_add_path_widgets + * default_path is default base directory, and is only used if no history + * exists for history_key (HOME is used if default_path is NULL). * path can be a full path or only a file name. If name only, appended to - * the default_path or the last history (see default_path) + * the default_path or the last history (see default_path) */ void file_dialog_add_path_widgets(FileDialog *fd, const gchar *default_path, const gchar *path, const gchar *history_key, const gchar *filter, const gchar *filter_desc); -- 2.20.1