org.freedesktop.icons

Interface IconService

All Superinterfaces:

FreedesktopService<IconTheme>, ThemeService<IconTheme>

All Known Implementing Classes:

DefaultIconService, LinuxIconService

public interface IconService
extends ThemeService<IconTheme>

Implementations of this service interface provide an easy way for Java to use the freedesktop.org's Icon Theme Specification.

To use the API, you must add (in the order that the locations should be searched) at lease one Base directory using the #addBase(File) method.

You should also select a theme using #setSelectedTheme(IconTheme). If no theme is selected, the first theme found is used.

To find an icon file, use findIcon(String, int). Only supply the filename without the prefix (for example, user-home, not user-home.png). Specify a size in pixels to locate the icon that closest matches (use Integer.MAX_VALUE to get the biggest available and Integer.MIN_VALUE to get the smallest).

Themes are keyed by their internal name. This is the file name of the directory the theme definition file is located in.

If an icon is not found in the selected theme, the themes parent will then be searched, and then its parent etc until a theme with no parent is reached.

If the icon is not found, the hicolor theme will then be searched in the same manner. Finally, if the icon is still not found, then the root of each base directory will be searched for any image files that are prefixed with the required name.

When no icon file is found using any of the above methods, findIcon(String, int) will either return null or the location of the image-missing special image (if that can be found).

See the specification in the link above for a complete description of the search algorithm.

Method Summary

Modifier and Type	Method and Description
org.apache.commons.vfs2.FileObject	findIcon(String name, int size) Find the closest matching icon.
Iterator<String>	iconNames() Iterator over all the available icon names in the currently selected theme for a given size.
Iterator<org.apache.commons.vfs2.FileObject>	icons(int size) Iterator over all the available icons in the currently selected theme for a given size.
boolean	isIconExists(String name, int size) Find the closest matching icon.
void	postInit() Must be called after construction to set the initial theme.
void	setReturnMissingImage(boolean b) Set whether the special Missing image is returned when no other matches is found.

Methods inherited from interface org.freedesktop.themes.ThemeService

getSelectedTheme, setSelectedTheme

Methods inherited from interface org.freedesktop.FreedesktopService

addBase, getAllEntities, getBases, getEntities, getEntity, removeBase

Method Detail

postInit

void postInit()

Must be called after construction to set the initial theme.

findIcon

org.apache.commons.vfs2.FileObject findIcon(String name,
                                            int size)
                                     throws IOException

Find the closest matching icon. See the class description for IconService for a complete description of the search algorithm. null will only be returned if no matching icon can be found and the image-missing icon cannot be found either

Parameters:

name - name of icon

size - closest pixel size

Returns:

file icon file

Throws:

IOException

isIconExists

boolean isIconExists(String name,
                     int size)
              throws IOException

Find the closest matching icon. See the class description for IconService for a complete description of the search algorithm.

Parameters:

name - name of icon

size - closest pixel size

Returns:

file or null if no icon can be found

Throws:

IOException

setReturnMissingImage

void setReturnMissingImage(boolean b)

Set whether the special Missing image is returned when no other matches is found. If true and this image isn't found, an IOException will be thrown.

Parameters:

returnMissingImage - return Missing image

icons

Iterator<org.apache.commons.vfs2.FileObject> icons(int size)

Iterator over all the available icons in the currently selected theme for a given size.

Parameters:

size - preferred size

Returns:

icon iterator

iconNames

Iterator<String> iconNames()

Iterator over all the available icon names in the currently selected theme for a given size.

Parameters:

size - preferred size

Returns:

icon iterator