From f0618f244f062c883ef5cdd7cffc5111a610d4d5 Mon Sep 17 00:00:00 2001 From: Niki Roo Date: Tue, 8 Mar 2022 08:25:35 +0100 Subject: [PATCH] utils: desktop: jdoc --- src/utils/desktop.c | 20 +++++----- src/utils/desktop.h | 90 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 91 insertions(+), 19 deletions(-) diff --git a/src/utils/desktop.c b/src/utils/desktop.c index fbf0a31..bcdff7d 100644 --- a/src/utils/desktop.c +++ b/src/utils/desktop.c @@ -38,10 +38,10 @@ struct { int id; }typedef desktop_p; -/* PRIVATE FUNCTIONS */ -int desktop_compare(const void *a, const void* b); -char *desktop_concat(const char str1[], ...); -int desktop_test_file(const char filename[]); +/* Private functions */ +static int desktop_compare(const void *a, const void* b); +static char *desktop_concat(const char str1[], ...); +static int desktop_test_file(const char filename[]); /* */ desktop *new_desktop(const char filename[], int best_size) { @@ -255,9 +255,9 @@ desktop *desktop_find_id(array *children, int id) { return found; } -/* PRIVATE FUNCTIONS */ +/* Private functions */ -char *desktop_concat(const char str1[], ...) { +static char *desktop_concat(const char str1[], ...) { va_list args; size_t total; size_t prec; @@ -287,7 +287,7 @@ char *desktop_concat(const char str1[], ...) { return rep; } -int desktop_compare(const void *a, const void* b) { +static int desktop_compare(const void *a, const void* b) { desktop_p *me1 = ((desktop_p**) a)[0]; desktop_p *me2 = ((desktop_p**) b)[0]; @@ -299,7 +299,7 @@ int desktop_compare(const void *a, const void* b) { return strcmp(me1->name, me2->name); } -int desktop_test_file(const char filename[]) { +static int desktop_test_file(const char filename[]) { FILE *test; DIR *test_dir; @@ -325,8 +325,8 @@ int desktop_test_file(const char filename[]) { free(tmp); \ } while(0) -char *theme = NULL; -char *ltheme = NULL; +static char *theme = NULL; +static char *ltheme = NULL; char *desktop_find_icon(const char basename[], int icon_size) { char *tmp = NULL; char *home = getenv("HOME"); diff --git a/src/utils/desktop.h b/src/utils/desktop.h index d3a6a97..e6857f3 100644 --- a/src/utils/desktop.h +++ b/src/utils/desktop.h @@ -17,6 +17,26 @@ * along with this program. If not, see . */ +/* @file desktop.h + * @author Niki + * @date 2021 + * + * @brief Manipulate .desktop files (as described by + * FreeDesktop.org) + * + * This structure helps you manipulate .desktop files (as described by + * FreeDesktop.org). + * + * @note the desktop object can use icons; for the selection of those, an exact + * match will first be tried (same name as the desktop file, with + * a .png extension), then we will look into the local + * .local/share/icons and if we still haven't found an icon, into + * the theme (first by looking for a best_size sized icon and if + * not in scalable) + * + * @note we support the use of desktop objects for menu, too, and that includes + * submenu items support + */ #ifndef DESKTOP_H #define DESKTOP_H @@ -28,25 +48,77 @@ extern "C" { #include "array.h" +/** + * The structure used to represent desktop objects. + */ typedef struct desktop_p desktop; +/** + * Create a new desktop object from the given .desktop file. + * + * @param filename the path to the actual .desktop file + * @param best_size the default size for the icon (see icon selection in the + * description of the {@see desktop} object + * + * @return the desktop object + */ desktop *new_desktop(const char filename[], int best_size); -void free_desktop(desktop *app); -const char *desktop_get_name(desktop *app); -const char *desktop_get_exec(desktop *app); -const char *desktop_get_icon(desktop *app); -const char *desktop_get_icon_file(desktop *app); +/** + * Free the given desktop object + */ +void free_desktop(desktop *self); -// external id (that you may set/use yourself) -int desktop_get_id(desktop *app); -void desktop_set_id(desktop *app, int id); +/** Return the name of the desktop object (you do not own it). */ +const char *desktop_get_name(desktop *self); +/** Return the exec command of the desktop object (you do not own it). */ +const char *desktop_get_exec(desktop *self); +/** Return the icon name of the desktop object (you do not own it). */ +const char *desktop_get_icon(desktop *self); +/** Return the icon file of the desktop object (you do not own it). */ +const char *desktop_get_icon_file(desktop *self); +/** + * Return the external ID of this desktop object + * ({@see desktop_set_id(desktop*, int)}. + * + * @return the external ID + */ +int desktop_get_id(desktop *self); + +/** + * Set a custom external ID for this desktop object, for your own use. + * + * @param id the ID to set + */ +void desktop_set_id(desktop *self, int id); + +/** + * Return all the submenu items of this desktop objects (for a menu/submenu). + * + * TODO: switch to full objects + * @return an array of pointers to desktop objects + */ array *desktop_get_children(desktop *app); +/** + * Find a submenu item by the given ID ({@see desktop_set_id(desktop *, int)}). + * + * TODO: use full objects instead + * @param children the array of pointers to desktop objects to look through + * @param menu_id the ID of the submenu we want to find + * + * @return the given submenu if found, or NULL + */ desktop *desktop_find_id(array *children, int menu_id); -// Static +/** + * Look for the icon file related to this basename. + * + * @param basename the base name of the icon we want to look for + * @param icon_size the best_size to use for the icon (see the description of + * the {@desktop} object) + */ char *desktop_find_icon(const char basename[], int icon_size); #endif /* DESKTOP_H */ -- 2.27.0