From 9a2cdc2db834a05bb8c4c6c8a961b92ee09a19f3 Mon Sep 17 00:00:00 2001 From: Rob Kendrick Date: Tue, 31 Oct 2006 16:19:21 +0000 Subject: Skeleton implementation of new themes API, complete with documentation, for discussion purposes. svn path=/trunk/netsurf/; revision=3021 --- utils/themes.c | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ utils/themes.h | 32 ++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 utils/themes.c create mode 100644 utils/themes.h (limited to 'utils') diff --git a/utils/themes.c b/utils/themes.c new file mode 100644 index 000000000..4f5322134 --- /dev/null +++ b/utils/themes.c @@ -0,0 +1,134 @@ +/* + * This file is part of NetSurf, http://netsurf.sourceforge.net/ + * Licensed under the GNU General Public License, + * http://www.opensource.org/licenses/gpl-license + * Copyright 2006 Rob Kendrick + */ + +#include "netsurf/utils/themes.h" + +struct theme_descriptor; + +/** + * Initialise the themes interface. This must be called once only before any + * other themes_ functions are called. It will enumerate all the themes + * found in the directory path names passed. Further themes can be added at + * runtime by using themes_add_new(). + * + * \param directories An array of directory path names that will be scanned + * in turn to find installed themes. Earlier directories + * take precedence over ones mentioned later. + */ +void themes_initialise(const unsigned char *directories[]) +{ + +} + +/** + * Close the themes system, freeing any open themes, and destroying any + * associated bitmaps that have been created from it. + */ +void themes_finalise(void) +{ + +} + +/** + * Add a new theme to the themes system. This is primarily of use to let + * NetSurf know about themes that were installed after NetSurf started - for + * example, from the "Install Theme" user interface. + * + * \param filename The filename, including full directory path, to the new + * theme. This theme will superceed any previous theme + * that has the same theme name. + */ +void themes_add_new(const unsigned char *filename); + +/** + * Open a theme for use. This increases the theme's use-count. + * + * \param themename Name of the theme to open. This is just the theme + * name, not the file name. + * \return struct theme_descriptor for use with other calls when refering to + * this theme. NULL if the theme is unknown to the theme system. + */ +struct theme_descriptor *themes_open(const unsigned char *themename) +{ + +} + +/** + * Decreases a theme's usage count, freeing memory assoicated with it should + * it reach zero. This will also destroy any bitmaps that have been created + * from it. + * + * \param theme Theme that the caller is finished with. + */ +void themes_close(struct theme_descriptor *theme) +{ + +} + +/** + * Enumerate known themes + * \param ctx Set to NULL for initial call. It will be updated after each call + * to point to the next result. + * \return struct theme_descriptor for use with other calls, or NULL if there + * are no more themes known. Note that this does not increase the + * theme's usage count - you should call themes_open() with the result + * of themes_get_name() if you wish to use this theme. + */ +struct theme_descriptor *themes_enumerate(void **ctx) +{ + +} + +/** + * Return a NetSurf bitmap structure for an image stored within the theme + * container. Note that this bitmap will become invalid if the theme's usage + * count reaches zero due to calls to themes_close() + * + * \param theme The theme you wish to retrieve an image from. If this is NULL, + * the default theme, as set by themes_set_default(), will be used. + * \param name The name of the image within the theme you wish to retrieve. + * \return struct bitmap containing the decoded image. + */ +struct bitmap *theme_get_image(struct theme_descriptor *theme, + const unsigned char *name) +{ + +} + +/** + * Set the default theme to use. This calls themes_open() to increase the + * theme's usage count. It will also call themes_close() on the previous + * default, if there was one. + * + * \param themename The name of the theme to set as the new default. + */ +void themes_set_default(const unsigned char *themename) +{ + +} + +/** + * Return the name of a theme from a struct theme_descriptor. + * + * \param theme The theme whose name to return + * \return Name of theme + */ +const unsigned char *themes_get_name(struct theme_descriptor *theme) +{ + +} + +/** + * Return the author of a theme from a struct theme_descriptor. + * + * \param theme The theme whose author to return + * \return Author of the theme. + */ +const unsigned char *themes_get_author(struct theme_descriptor *theme) +{ + +} diff --git a/utils/themes.h b/utils/themes.h new file mode 100644 index 000000000..8d3336f7c --- /dev/null +++ b/utils/themes.h @@ -0,0 +1,32 @@ +/* + * This file is part of NetSurf, http://netsurf.sourceforge.net/ + * Licensed under the GNU General Public License, + * http://www.opensource.org/licenses/gpl-license + * Copyright 2006 Rob Kendrick + */ + +#ifndef __THEMES_H__ +#define __THEMES_H__ + +#include "netsurf/image/bitmap.h" + +struct theme_descriptor; + +void themes_initialise(void); +void themes_finalise(void); + +void themes_add_new(const unsigned char *filename); + +struct theme_descriptor *themes_open(const unsigned char *themename; +void themes_close(struct theme_descriptor *theme); +struct theme_descriptor *themes_enumerate(void **ctx); + +struct bitmap *theme_get_image(struct theme_descriptor *theme, + const unsigned char *name); + +void themes_set_default(const unsigned char *themename); + +const unsigned char *themes_get_name(struct theme_descriptor *theme); +const unsigned char *themes_get_author(struct theme_descriptor *theme); + +#endif /* __THEMES_H__ */ -- cgit v1.2.3