Loads icons with IconTheme. More...

#include <edelib/IconLoader.h>

Static Public Member Functions
static void	init (const char *theme)

static void	init (void)

static void	shutdown (void)

static bool	inited (void)

static void	reload (const char *theme)

static void	repoll (void)

static Fl_Shared_Image *	get (const char *name, IconSizes sz, IconContext ctx=ICON_CONTEXT_ANY, unsigned long options=0)

static String	get_path (const char *name, IconSizes sz, IconContext ctx=ICON_CONTEXT_ANY)

static bool	set (Fl_Widget widget, const char name, IconSizes sz, IconContext ctx=ICON_CONTEXT_ANY, unsigned long options=0)

static const IconTheme *	theme (void)

static void	set_fallback_icon (const char *name)

static const char *	get_fallback_icon (void)

static const char **	get_builtin_xpm_icon (IconSizes sz)

Detailed Description

Loads icons with IconTheme.

IconLoader will initialize icon theme via IconTheme and load given icon name or display it in target widget. It will also cache common requests for faster access or utilize Fl_Shared_Image for direct access to the image object.

One of the main goals of IconLoader, besides loading icons in various ways, is to allow dinamically icon pixmaps update on widgets, when icon theme was changed. With this, application would receive a new icon pixmaps without knowing that or without needs to be restarted. To allow this, you should let IconLoader load and set images on widgets (described briefly bellow).

Icons are searched and fetched via plain icon name; that name does not contains path nor extension. Using this approach (assuming common names are used), you can easily switch between themes without changing icon names. So, to load foo.png you should use foo name.

Here is the sample how to correctly display icon in Fl_Button object:

*  // ...
*  IconLoader::init();
*  // ...
*  Fl_Button* button = new Fl_Button(...);
*  IconLoader::set(button, "utilities-terminal", ICON_SIZE_MEDIUM);
* 

With this, utilities-terminal icon with requested size will be searched, and displayed in Fl_Button widget. If this icon wasn't found, a fallback icon will be used for that (by default empty icon is used).

Also, with this, IconLoader will track these widgets so when icon theme was changed, they would be appropriately refreshed.

IconLoader::init() should not be called if edelib::Window class is used; it will call it automatically.

To dinamically change icon theme and reload loaded icons, IconLoader::reload() should be used. This function will correctly update icon paths and redraw widgets. When Window class is used, it will automatically call reload() when theme was changed, so there is no need to call it manually.

Member Function Documentation

static Fl_Shared_Image* get	(	const char *	name,
		IconSizes	sz,
		IconContext	ctx = `ICON_CONTEXT_ANY`,
		unsigned long	options = `0`
	)

static

Returns image object by searching icon that matches name, size and context. First, it will check if name is absolute path to the icon (unless ICON_LOADER_OPTION_NO_ABSOLUTE_PATH was used in options) and will try to load it. If fails, it will consult icon theme.

Returned icon will match sz size; if it is larger or smaller than the loaded, it will be scalled to the given size. If ICON_LOADER_OPTION_NO_ICON_SCALE was set, scaling will not be done.

If icon wasn't found, fallback icon will be loaded. If fails, NULL will be returned. For further members of Fl_Shared_Image, see FLTK documentation.

options is used to OR IconLoaderOptions values.

static const char** get_builtin_xpm_icon ( IconSizes sz )

static

Returns XPM icon with given size. These icons are always present in edelib and should be used in cases when icon is not present in icon theme, or give icon theme wasn't installed at all.

static const char* get_fallback_icon ( void )

static

Return the name of fallback icon. Default is empty.

static String get_path	(	const char *	name,
		IconSizes	sz,
		IconContext	ctx = `ICON_CONTEXT_ANY`
	)

static

Returns full path to given icon name. If icon wasn't found, returned string will be empty.

static void init ( const char * theme )

static

Initialize loader code and load given theme name. This function must be called before further calls

static void init ( void )

inlinestatic

Initialize loader code using default theme name (

See Also: IconTheme::default_theme_name())

static bool inited ( void )

static

Check if data was loaded

static void reload ( const char * theme )

static

Reload IconLoader with the new theme. This function is preferred to load another theme than shutdown()/init() combination, since it will not clear all internal data.

Note: This function should not be used when edelib::Window is used for window construcion; edelib::Window tracks icon theme changes via XSETTINGS protocol and when needed, it will call this function. Manually calling it (but edelib::Window is used), will change icon theme but XSETTINGS data will not be synced, yielding different themes in edelib and XSETTINGS aware toolkits (like Gtk+).

static void repoll ( void )

static

Refresh internal cached icon paths. This function should be used in conjuction with set() or get() functions. Since IconLoader can't dinamically track life of image objects or widget objects it will not be able to clear cached paths when these get destroyed. Paths are needed to be kept in case when icon theme was changed during program execution.

This function should be used when there are large number of set()/get() and where widgets gets destroyed in the short period of time. If this wasn't used, internal cache would grow needlessly.

static bool set	(	Fl_Widget *	widget,
		const char *	name,
		IconSizes	sz,
		IconContext	ctx = `ICON_CONTEXT_ANY`,
		unsigned long	options = `0`
	)

static

Load given icon and set widget to use it (it will call widget's image() function for that). This is the function you should use to set icon inside the widget, because it allows dynamic refreshing when icon theme was changed by redrawing the widget.

It will try to load icon the sam way as get() does: first it will check if name is absolute path then will go in icon theme. If this fails, it will try to load fallback icon and if succeeded (in one of the cases), it will redraw the widget (unless ICON_LOADER_OPTION_NO_WIDGET_REDRAW was OR-ed in options).

To retrieve the image object of set image, you can use image() function from given widget object.

static void set_fallback_icon ( const char * name )

static

Set fallback icon name. This name will be used to search alternative icon in icon theme when the target one wasn't found. Defauly fallback icon is empty.

Note: icon name will not be copied so make sure to have given string in static memory

static void shutdown ( void )

static

Shutdowns loader by cleaning internal data. Call init() to load it again

static const IconTheme* theme ( void )

static

Returns IconTheme object.

The documentation for this class was generated from the following file:

edelib/IconLoader.h

Static Public Member Functions

Detailed Description

Member Function Documentation