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