1Introduction
2============
3
4icon-slicer is a utility for generating icon themes and libXcursor
5cursor themes.
6
7The inputs to icon-slicer are conceptually:
8
9 A) A set of multi-layer images, one for each size.
10 B) A XML theme description file
11
12Each image contains all the cursors arranged in a grid; For
13cursors the layers are:
14
15 - A layer with a dot for the hotspot of each cursor
16 - The main image or first animation frame for multi-frame
17 animated cursors
18 - The second animation frame for multi-frame animated cursors
19 - ...
20
21For icons, the layers are:
22
23 - A layer with the images
24 - An optional layer with attachment points for emblems
25 - An optional layer with boxes for embedding text into
26 icons.
27
28In practice, since loading of multilayer images is not supported by
29standard image libraries, each layer is input as a separate image
30file.
31
32The theme description file contains, among other things, information about
33the source images to read, the location of each named cursor or icon
34within the grid, and a set of aliases from names to other names.
35
36
37Installation
38============
39
40icon-slicer requires GTK+-2.0 or newer for the gdk-pixbuf image
41manipulation library. It probably is already on your system; if not,
42it is available from ftp://ftp.gtk.org. It also requires the
43popt library from the RPM distribution. (Should be commonly
44available on most Linux distributions, even if they don't use RPM.)
45
46Once you have those installed, building icon-slicer is a simple
47./configure ; make ; make install. If you installed GTK+ in a
48non-standard location, say /opt/gtk, then you will need to set
49PKG_CONFIG_PATH to include /opt/gtk/lib/pkgconfig.
50
51
52Invocation
53==========
54
55icon-slicer takes some number of theme description files as input,
56along with options:
57
58 --output-dir=DIRECTORY
59 The directory into which to write output. Mandatory.
60
61 --image-dir=DIRECTORY
62 The directory in which to find source images. If not
63 specified, the current working directory is used.
64
65
66Theme file format
67=================
68
69The tags in the Theme file format are:
70
71<theme>: The toplevel element. There must be
72 exactly one of these.
73
74 Attributes:
75 name: The name of the theme. Required.
76
77 typedir: default type portion of output directory for icons
78 in this theme.
79
80 Child elements:
81 <alias>, <layout>, <source>
82
83<alias>: The alias element defines an alias of one cursor name to
84 another cursor or of one icon name to an another icon. An icon
85 alias can also have a display name associated which overrides the
86 display name of the target alias.
87
88 Attributes:
89 name: The name of the alias. Required.
90 target: The name cursor (or alias) to which the
91 alias points. Required.
92 typedir: type portion of output directory. Optional
93
94 Child elements:
95 DisplayName
96
97<source>: Defines a multilayer source
98
99 Attributes:
100 size: The nominal size of the cursors in the
101 this source. This is used when selecting a
102 cursor. Required.
103
104 sizedir: size portion of output directory name for
105 icons. Optional.
106
107 gridsize: The size of the grid used for this
108 source. Defaults to the same as 'size'.
109 Optional.
110
111 margin: border around the entire source outside of
112 all grid cells. Optional.
113
114 spacing: spacing between the cells of the grid. Optional.
115
116 Child elements:
117 <image>
118
119<image>: One layer in a multilayer source
120
121 Attributes:
122 file: The filename to get the image from. Required.
123 use: Either an integer indicating what animation
124 frame this is (0, 1, ...) or "hotspot" to
125 indicate that this frame contains hotspots. If not
126 present, the same as giving '0'
127
128 Child elements:
129 None
130
131<layout>: Defines the layout of cursors or icons within the grid.
132
133 Attributes:
134 None
135
136 Child elements:
137 <row>
138
139<row>: Defines one row of cursors or icons within the grid
140
141 Attributes:
142 None
143
144 Child elements:
145 <cursor>
146 <icon>
147
148<cursor>: Defines a single cursor. If there are no
149 child <frame> elements, it is assumed to be a non-animated
150 cursor with a single frame in it. Otherwise, one
151 or more frames is specified with child <frame> elements.
152
153 Attributes:
154 name: The name of the cursor. Required.
155
156 Child elements:
157 <frame>
158
159<frame>: Defines one frame of a multiframe cursor.
160
161 Attributes:
162 delay: The delay before the next frame is shown in
163 milliseconds. Optional. (If you don't specify the delays
164 for a multiframe animation, the result is undefined.)
165
166 Child elements:
167 None
168
169<icon>: Defines a single icon.
170
171 Attributes:
172 name: The name of the icon. Required.
173
174 typedir: type portion of output directory. Optional
175
176 Child elements:
177 displayname
178
179<displayname>: Defines a possibly translated display name
180 for an icon or an alias.
181
182 Attributes:
183 str: The untranslated value of the display name
184
185 Child elements:
186 locale
187
188<locale>: Defines one translated value for a <displayname> element
189
190 Attributes:
191 lang: Language for which this is a translation
192 str: The translated value of the display name
193
194 Child elements:
195 None
196
197Note that icon-slicer doesn't actually use a full XML parser, but
198the XML-subset GMarkup parser from GLib, so some less common XML
199constructs may not work.
200
201
202Note about icon output location
203===============================
204
205Cursors are always output in [outputdir]/cursors; for icons
206and icon aliases, it's a bit more complicated.
207
208Define [sizedir] to be the 'sizedir' attribute of
209the applicable <source> element, if any. [typedir] to be
210the 'typedir' attribute of the icon or alias, if any,
211or the 'typedir' attribute specified for the <theme>
212element if not specified for the icon or alias. Then
213the output directory is:
214
215 [outputdir]/[sizedir]/[typedir]
216
217Where either sizedir or typedir is allowed to be empty,
218but not both.
219
220
221Makefile example
222================
223
224Makefile rules for generating and installing a theme look like:
225
226sample_sources = \
227 sample.cursortheme \
228 sample-cursors-24-1.png \
229 sample-cursors-24-hotspot.png \
230 sample.icontheme \
231 sample-icons-24.png \
232 sample-icons-16.png
233
234Sample.stamp: $(sample_sources) $(icon_slicer)
235 rm -rf Sample \
236 && mkdir Sample \
237 && icon_slicer \
238 --output-dir=Sample \
239 --image-dir=$(srcdir) \
240 $(srcdir)/sample.cursortheme \
241 $(srcdir)/sample.icontheme \
242 && touch Sample.stamp
243
244install:
245 rm -rf $(datadir)/icons/Sample
246 dirs=`find Sample -type d -print` ; \
247 for d in $$dirs ; do \
248 mkdir -p $(datadir)/icons/$$d ; \
249 done
250 files=`find Sample -type f -print` ; \
251 for f in $$files ; do \
252 install -m 0644 $$f $(datadir)/icons/$$f ; \
253 done
254 links=`find Sample -type l -print` ; \
255 for l in $$links ; do \
256 cp -d $$l $(datadir)/icons/$$l ; \
257 done
258
259uninstall:
260 rm -rf $(datadir)/icons/Sample
261
262License
263=======
264
265Copyright © 2003 Red Hat, Inc.
266
267Permission to use, copy, modify, distribute, and sell this software and its
268documentation for any purpose is hereby granted without fee, provided that
269the above copyright notice appear in all copies and that both that
270copyright notice and this permission notice appear in supporting
271documentation, and that the name of Red Hat not be used in advertising or
272publicity pertaining to distribution of the software without specific,
273written prior permission. Red Hat makes no representations about the
274suitability of this software for any purpose. It is provided "as is"
275without express or implied warranty.
276
277RED HAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
278IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL RED HAT
279BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
280WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
281OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
282CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
283
284
