icontheme 0.6.1

icontheme

D library for dealing with icon themes in freedesktop environments.

The most of desktop environments on Linux and BSD flavors follows Icon Theme Specification when searching for icons. The goal of icontheme library is to provide implementation of this specification in D programming language. Please feel free to propose enchancements or report any related bugs to Issues page.

Platform support

The library is crossplatform for the most part, though there's little sense to use it on systems that don't follow freedesktop specifications. icontheme is developed and tested on FreeBSD and Debian GNU/Linux.

Features

Implemented features

icontheme provides all basic operations to deal with icon themes and icon lookup:

• Reading index.theme files.
• Icon lookup. Finding the icon file closest to given size.
• Lookup of fallback icons that don't belong to any theme.
• Reading and using icon-theme.cache files. Those are usually generated by gtk-update-icon-cache.

Missing features

Features that currently should be handled by user, but may be implemented in the future versions of library.

• Installing icons to writable path.
• Automatic detection of icon theme currently used in system. This is separate task though and desktop environment dependent.
• Some features regarding icon theme caches are missing, because I could not find specification on this topic.

Generating documentation

Ddoc:

dub build --build=docs

Ddox:

dub build --build=ddox

Running tests

dub test

Brief

import std.array;
import std.exception;
import std.stdio;

import icontheme;

try {
    string[] searchIconDirs = baseIconDirs(); // Base directories to search themes and icons
    
    // First read icon theme and all related information.
    
    string themeName = ...; // theme name, e.g. "gnome" for GNOME, "oxygen" for KDE4, etc.
    
    IconThemeFile[] iconThemes;
    IconThemeFile iconTheme = openIconTheme(themeName, searchIconDirs); // Read index.theme file contained description if icon theme.
    
    if (iconTheme) {
        writeln("Name: ", iconTheme.name); // Display name of icon theme.
        writeln("Comment: ", iconTheme.comment); // Extended comment on icon theme.
        writeln("Is hidden: ", iconTheme.hidden); // Whether to hide the theme in a theme selection user interface.
        writeln("Subdirectories: ", iconTheme.directories); // Sub directories of icon theme.
        writeln("Inherits: ", iconTheme.inherits()); // Names of themes the main theme inherits from.
        writeln("Example: ", iconTheme.example()); // The name of an icon that should be used as an example of how this theme looks.
        
        iconThemes ~= iconTheme;
        iconThemes ~= openBaseThemes(iconTheme, searchIconDirs); // find and load themes the main theme inherits from.
    } else {
        stderr.writeln("Could not find theme");
    }
    
    foreach(theme; iconThemes) {
        theme.tryLoadCache(); // Use cache on icon lookups.
    }
    
    // Now search for icon by name
    
    // Allowed extensions of image files, in order of preference. Put here extensions that your application supports.
    // Icon Theme Specification requires to support PNG and XPM. SVG support is optional.
    string[] extensions = [".png", ".xpm"];
    
    string iconName = ...; // Some icon name, e.g. "folder" or "edit-copy".
    
    
    // Find largest icon file with such name among given themes and directories.
    string iconPath = findLargestIcon(iconName, iconThemes, searchIconDirs, extensions);
    
    // Or find icon file with size nearest to desired.
    
    size_t size = ...; // Desired icon size.
    iconPath = findClosestIcon(iconName, size, iconThemes, searchIconDirs, extensions); 
    
    // ... load icon from iconPath using preferable image library.
}
catch(IniLikeException e) { // Parsing error - found icon theme file is invalid or can't be read
    stderr.writeln(e.msg);
}

Examples

Describe icon theme

Prints the basic information about theme to stdout.

dub run icontheme:describetheme -- gnome

You also can pass the absolute path to file:

dub run icontheme:describetheme -- /usr/share/icons/gnome/index.theme

Or directory:

dub run icontheme:describetheme -- /usr/share/icons/gnome

Icon theme test

Parses all found index.theme and icon-theme.cache files in base icon directories. Writes errors (if any) to stderr. Use this example to check if the icontheme library can parse all themes and theme caches on your system.

dub run icontheme:iconthemetest

Run to print names of all examined index.theme and icon-theme.cache files to stdout:

dub run icontheme:iconthemetest -- --verbose

Find icon

Utility that finds icon by its name. By default search only in hicolor theme:

dub run icontheme:findicon -- nautilus

You can specify additional theme:

dub run icontheme:findicon -- --theme=gnome folder

And preferred size:

dub run icontheme:findicon -- --theme=gnome --size=32 folder

Allow using cache:

dub run icontheme:findicon -- --theme=gnome edit-copy --useCache

Print icons

Search icons in specified theme:

dub run icontheme:printicons -- --theme=gnome > result.txt

Include hicolor theme, base themes and icons that don't belong to any theme:

dub run icontheme:printicons -- --include-nonthemed --include-hicolor --include-base --theme=Faenza > result.txt