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) {
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;
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];
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;
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");
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
+/* @file desktop.h
+ * @author Niki
+ * @date 2021
+ *
+ * @brief Manipulate <tt>.desktop</tt> files (as described by
+ * <a href='https://freedesktop.org/'>FreeDesktop.org</a>)
+ *
+ * This structure helps you manipulate <tt>.desktop</tt> files (as described by
+ * <a href='https://freedesktop.org/'>FreeDesktop.org</a>).
+ *
+ * @note the desktop object can use icons; for the selection of those, an exact
+ * match will first be tried (same name as the <tt>desktop</tt> file, with
+ * a <tt>.png</tt> extension), then we will look into the local
+ * <tt>.local/share/icons</tt> and if we still haven't found an icon, into
+ * the theme (first by looking for a <tt>best_size</tt> sized icon and if
+ * not in <tt>scalable</tt>)
+ *
+ * @note we support the use of desktop objects for menu, too, and that includes
+ * submenu items support
+ */
#ifndef DESKTOP_H
#define DESKTOP_H
#include "array.h"
+/**
+ * The structure used to represent desktop objects.
+ */
typedef struct desktop_p desktop;
+/**
+ * Create a new desktop object from the given <tt>.desktop</tt> file.
+ *
+ * @param filename the path to the actual <tt>.desktop</tt> 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 <b>not</b> own it). */
+const char *desktop_get_name(desktop *self);
+/** Return the exec command of the desktop object (you do <b>not</b> own it). */
+const char *desktop_get_exec(desktop *self);
+/** Return the icon name of the desktop object (you do <b>not</b> own it). */
+const char *desktop_get_icon(desktop *self);
+/** Return the icon file of the desktop object (you do <b>not</b> 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 */