=======
IconKit
=======

:Maintainers: Quentin Mathe <qmathe@club-internet.fr>, Uli Kusterer
:Authors: Uli Kusterer, Nicolas Roard, Quentin Mathe
:License: Modified BSD License
:Version: 0.2

This framework provides icon theming and various facilities to create icons at
run-time by compositing by different elements.
The icon compositing is very useful for the consistency accross a set of icons 
(for example, using the same background) and permit to easily create icon 
families.
IconKit icon themes are a complement to Camaelon widget themes.

The compositing support and specially the system-wide caching of the generated 
and user-customized icons need more work before being usable. Patches are 
welcome :-) Get in touch with us if you are interested to work on that. 

To know more about IconKit:
<http://www.etoile-project.org/dev/0.4/IconKit>


Build and Install
-----------------

Read INSTALL document.


Mac OS X support
----------------

A subset of IconKit API is supported on Mac OS X (by relying on Carbon Icon 
Services).

**Warning:** Xcode 4 is required to build the project.


Developer Notes
===============

Example
-------

1) Create a NSImage composed of two images programmatically:

	// load 2 images
        NSImage* document = [[NSImage alloc] initWithContentsOfFile: @"document-background.tiff"];
        NSImage* applicationLogo = [NSImage imageNamed: @"logo.tiff"];

	// create a compositor with the background image
        IKCompositor* compositor = [[IKCompositor alloc] 
                initWithImage: document];

	// compose the logo on the background image in a defined rectangle (logo will be rescaled)
        [compositor compositeImage: applicationLogo 
                inRect: NSMakeRect (10,10,30,30)];

	// get the result
	NSImage* result = [compositor render];

2) Create a NSImage composed of two images using a plist describing the operations

	// load the plist
	NSDictionary* plist = [NSDictionary dictionaryWithContentsOfFile: @"test.plist"];

	// create a compositor with the plist
	IKCompositor* compositor = [[IKCompositor alloc] initWithPropertyList: plist];

	// get the result
	NSImage* result = [compositor render];

Here is the plist used in the example:

{
    compositingSize = {
	height = <*R48>;
	width = <*R48>;
    };
    originalSize = {
	height = <*R48>;
	width = <*R48>;
    };
    operations = (
	{
	    alpha = <*R1>;
	    operation = <*I2>;
	    path = "document-background.tiff";
	    position = <*I0>;
	    rectangle = {
		height = <*R0>;
		width = <*R0>;
		x = <*R0>;
		y = <*R0>;
	    };
	},
	{
	    alpha = <*R1>;
	    operation = <*I2>;
	    path = "logo.tiff";
	    position = <*I0>;
	    rectangle = {
		height = <*R30>;
		width = <*R30>;
		x = <*R10>;
		y = <*R10>;
	    };
	}
    );
}


Tests suite
-----------

UnitKit (bundled with Etoile) is required.

    Steps to produce a test bundle and run tests suite:

    * make test=yes 

    * ukrun