NAME

Wx::Perl::IconDepot - Use icon libraries quick & easy

SYNOPSIS

 my $depot = new Wx::Perl::IconDepot(\@pathnames);
 $depot->SetThemes($theme1, $theme2, $theme3);
 my $wxbitmap = $depot->GetBitmap($name, $size, $context)
 my $wxicon = $depot->GetIcon($name, $size, $context)
 my $wximage = $depot->GetImage($name, $size, $context)

DESCRIPTION

This module allows Wx easy access to icon libraries used in desktops like KDE and GNOME.

It supports libraries containing scalable vector graphics like Breeze if Image::LibRSVG is installed. If not you are confined to bitmapped libraries like Oxygen or Adwaita.

On Windows you have to install icon libraries yourself in C:\ProgramData\Icons. You will find plenty of them on Github. Extract an icon set and copy the main folder of the theme (the one that contains the file 'index.theme') to C:\ProgramData\Icons. On Linux you will probably find some icon themes in /usr/share/icons.

The constructor takes a reference to a list of folders where it finds the icons libraries. If you specify nothing, it will assign default values for:

Windows: $ENV{ALLUSERSPROFILE} . '\Icons'. IconDepot will not create the folder if it does not exist.

Others: $ENV{HOME} . '/.local/share/icons', '/usr/share/icons'

PUBLIC METHODS

AvailableContexts($theme, [ $name, $size ] );

Returns a list of available contexts. If you set $name to undef if will return all contexts of size $size. If you set $size to undef it will return all contexts associated with icon $name. If you set $name and $size to undef it will return all known contexts in the theme. out $size it returns a list of all contexts found in $theme.

AvailableIcons($theme, [ $size, $context ] );

Returns a list of available icons. If you set $size to undef the list will contain names it found in all sizes. If you set $context to undef it will return names it found in all contexts. If you leave out both then you get a list of all available icons. Watch out, it might be pretty long.

AvailableSizes($theme, [ $name, $context ] );

Returns a list of available contexts. If you leave out $size it returns a list of all contexts found in $theme.

AvailableThemes

Returns a list of available themes it found while initiating the module.

FindImage($name, [ $size, $context, \$resize ] );

Returns the filename of an image in the library. Finds the best suitable version of the image in the library according to $size and $context. If it eventually returns an image of another size, it sets $resize to 1. This gives the opportunity to scale the image to the requested icon size. All parameters except $name are optional.

FindRawImage($name, [ $size, $context, \$resize ] );

Returns the filename of an image in the library. Finds the best suitable version of the image in the library according to $size and $context. If it eventually returns an image of another size, it sets $resize to 1. This gives the opportunity to scale the image to the requested icon size. All parameters except $name are optional.

FindLibImage($name, [ $size, $context, \$resize ] );

Returns the filename of an image in the library. Finds the best suitable version of the image in the library according to $size and $context. If it eventually returns an image of another size, it sets $resize to 1. This gives the opportunity to scale the image to the requested icon size. All parameters except $name are optional.

GetActiveThemes

Returns a list of active themes. Primary theme first then the fallback themes.

GetBitmap($name, [ $size, $context, $force ] );

Returns a Wx::Bitmap object. If you do not specify $size or the icon does not exist in the specified size, it will return the largest possible icon. $force can be 0 or 1. It is 0 by default. If you set it to 1 a missing icon image is returned instead of undef when the icon cannot be found.

GetIcon($name, [ $size, $context, $force ] );

Returns a Wx::Icon object. If you do not specify $size or the icon does not exist in the specified size, it will return the largest possible icon. $force can be 0 or 1. It is 0 by default. If you set it to 1 a missing icon image is returned instead of undef when the icon cannot be found.

GetImage($name, [ $size, $context, $force ] );

Returns a Wx::Image object. If you do not specify $size or the icon does not exist in the specified size, it will find the largest possible icon and scale it to the requested size. $force can be 0 or 1. It is 0 by default. If you set it to 1 a missing icon image is returned instead of undef when the icon cannot be found.

GetThemePath($theme)

Returns the full path to the folder containing $theme

IsImageFile($file)

Returns true if $file is an image. Otherwise returns false.

LoadImage($file)

Loads image $file and returns it as a Wx::Image object.

SetThemes($theme1, [ $theme2, $theme3 ] );

Initializes themes. $theme1 is the primary theme. The rest are subsequent fallback themes. I suggest to use your favourite theme as the first one and the theme that has the most icons as the last one.

PRIVATE METHODS

CollectThemes

Called during initialization. It scans the folders the constructor receives for icon libraries. It loads their index files and stores the info.

CreateIndex($themeindex)

Creates a searchable index from a loaded theme index file. Returns a reference to a hash.

FindImageC($sizeindex, $context)

Looks for an icon in $context for a given size index (a portion of a searchable index). If it can not find it, it looks for another version in all other contexts. Returns the first one it finds.

FindImageS($nameindex, $size, $context, \$resize)

Looks for an icon of $size for a given name index (a portion of a searchable index). If it can not find it it looks for another version in all other sizes. In this case it returns the biggest one it finds and sets $resize to 1.

FindINC($file)

Looks for a file in @INC. if found returns the full pathname.

GetMissingImage($size)

Returns a Wx::Image object of the missing image symbal on the requested size.

GetTheme($themename)

Looks for a searchable index of the theme. If it is not yet created it will be created first and stored in the index pool.

LoadThemeFile($file)

Loads a theme index file and returns the information in it in a hash. It returns a reference to this hash.

AUTHOR

Hans Jeuken (hansjeuken at xs4all dot nl)

BUGS

If you find any, please contact the author.

Icon libararies that depend on .svg images show up in the list of AvailableThemes when no support for scalable vector graphics is available.

TODO