<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="page.css" type="text/css">
<title>Documentation: Icons and Images</title>
</head>
<body alink="#990033" bgcolor="#ffffff" link="#990033" text="#000000"
vlink="#990033">
<!---- TOPIC TITLE WITH LOGO--->
<table border="0" cellpadding="cellspacing=2" width="100%">
<tbody>
<tr>
<td><a href="http://www.fox-toolkit.org" target="_top"><img
src="art/foxlogo_small.jpg" border="0"></a></td>
<td id="HEADLINE" valign="bottom" width="100%"><b>Documentation:
Icons and Images <a href="icons.html" target="_top" align="left"><font
size="-2">[Remove Frame]</font></a>
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
<p></p>
<!--- TOPIC TITLE WITH LOGO --->
<ul>
<p>Icons and Images are part an parcel of attractive, user-friendly
Graphical User Interfaces these days. Consequently, considerable
effort has been expended in designing FOX to allow icon- and image-rich
applications to be developed with the greatest ease.<br>
In FOX, Images and Icons are objects that represent picture data.
Images are simple pictures, whereas Icons are pictures with a <i>shape
mask</i> that may be used to effectively mask out a certain area of the
picture, and allow part the background to peek through as if the
picture were transparent in some areas.<br>
Both Icons and Images may have <b>Client</b> <b>side</b> <b><i>pixel
data</i></b> as well as an <b>X Server side</b> <b><i>pixmap</i></b>
representation. The typical application will construct the
client-side pixel data by filling the Icon or Image with a picture,
then create the server-side representation [after contact with the X
Server has been established] by calling i<tt>con->create()</tt>,
which creates an server side <i>pixmap</i> and uses a call to <tt>icon->render()</tt>
to fill the pixmap with the pixel data .</p>
<p>Note that this is a two-step process which is very similar to that
of constructing and creating regular FOX Widgets. This is no
accident. The FOX philosophy is to construct [client-side] data
structures such as Widgets and Icons and Images etc., then with all the
information available, create their X Server side representation in one
fell swoop by calling <tt>app->create()</tt>.</p>
<p>When you have given Buttons or Labels or other FOX Widgets icons,
a call to that Widget's <tt>create()</tt> member function will also
automatically call its icon <tt>create()</tt>. To allow icons to
be shared by multiple Widgets, it is specifically allowed to call <tt>create()</tt>
more than once on an icon or image.</p>
<p>In many cases, after calling an icon's create() member function,
there is no need to keep the client-side pixel data around; thus, FOX
icons will in most cases release the memory taken up by the pixel
data. Should you want to repeatedly change the pixel data,
however, FXIcon and FXImage have an option <b>IMAGE_KEEP</b> to allow
you to hang on to the pixel data in the client. After making
changes to the pixel data, you can call <tt>icon->render()</tt>
again to render it into the pixmap.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
<tbody>
<tr>
<td id="HEADLINE" valign="bottom" width="100%"><b>Image Formats
Supported
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>Currently, FOX supports <b>CUR, </b><b>BMP</b>, <b>GIF</b>,
<b>ICO, </b><b>IFF, </b><b>JPEG</b>, <b>PCX, PNG</b>, <b>PPM,
RAS, RGB, </b><b>TGA, TIFF, XBM, </b>and<b> XPM</b> based icons and
images. The most preferred format is <span
style="font-weight: bold;">GIF,</span> as it is about 10 times more
compact than <span style="font-weight: bold;">XPM,</span> and about 2
times more compact than BMP. This is of some concern, as
applications may have lots of icons [some analysis of our own
applications revealed than one application's executable had about 1MB
worth of XPM icons; with GIF, this would have been less than a 100kB].</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
<tbody>
<tr>
<td id="HEADLINE" valign="bottom" width="100%"><b>Incorporating
Icons and Images into an Application
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>One crucial problem with icon-rich applications is where to keep
all those icons; obviously, keeping icons in separate files allows
end-users to substitute icons and perhaps change them with an Icon
Editor program. However, such a scenario also poses a
maintainance problem:- software becomes extraordinarily dependent on
specifics of a user installation, and end-users may actually break
software by substituting corrupted icon files by accident, or perhaps
other applications may overwrite them. Another common problem is
the need for end-users to set paths and environment variables.</p>
<p>To eliminate these problems, the FOX approach is to <b><i>embed</i></b>
all icons and images right into the application's executable.
This is done by simply by compiling the icons into the code in the form
of C data statements, and then linking them in.</p>
<p>XPM and XBM icons or images can be directly included into the
source code, as these formats are basically just C++ data arrays
already and there is consequently no reason to use reswrap. <br>
XPM is particularly convenient as it allows you to build icons even
without a graphical icon editor. Other image formats need to be
transformed into a C++ data array with a small build-time utility
called <a name="RESWRAP"></a><b><i>reswrap</i></b>, which is provided
in the FOX distribution.</p>
<p>Reswrap allows you to generate the C/C++ data arrays automatically
from the icons during the build process of your application; simply add
a few rules into your Makefile, or, under VC++, use the reswrap program
in a so-called <em>Utility Project</em>. For example, given as input a
GIF file image such as below:</p>
<p></p>
<center><img src="art/bigpenguin.png" height="57" width="48"><br>
Figure 1. Linux Penguin from file <i>bigpenguin.gif</i>.</center>
<p></p>
<p> After processing this file, reswrap generates a C data
statement such as:</p>
<pre>/* Generated by reswrap from file <i>bigpenguin.gif</i> */<br>const unsigned char bigpenguin[]={<br> 0x47,0x49,0x46,0x38,0x37,0x61,0x30,0x00,0x39,0x00,0xf3,0x00,0x00,0xb2,0xc0,0xdc,<br> ...............................................................................<br> ...............................................................................<br> 0xf4,0xe0,0x63,0x90,0x7c,0x7d,0x40,0xc5,0x92,0x0c,0x34,0x39,0x41,0x04,0x00,0x3b<br> };<br></pre>
<p>This can then be subsequently compiled into an object file, and
linked
in with the executable. To make use of such an icon, FOX supports
deserialization from a <i>memory stream</i>. The icon data above could
be used as follows to create an Icon:</p>
<pre>FXIcon *tux_icon = new FXGIFIcon(application,bigpenguin);<br></pre>
<p>Wait! Is that all? Yes it is! This <i>one</i> statement
creates
an icon object, then <i>deserializes</i> the icon data from the GIF
stream
to build the icon's internal pixel data. A subsequent call:</p>
<pre>tux_icon->create();</pre>
<p>Will create an X pixmap, render the icon into it, and subsequently
release
the pixel data after it is no longer needed. If you had created
the
icon with the IMAGE_KEEP option, the pixel data would have been kept
around
for subsequent manipulation by your application, and perhaps repeated
rendering.
To draw the icon in a window, simply:</p>
<pre>dc.drawIcon(tux_icon,x,y);<br></pre>
<p>will do the job.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
<tbody>
<tr>
<td id="HEADLINE" valign="bottom" width="100%"><b>Bitmaps
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>Bitmaps (XBM images) in FOX behave very much like images.
Except, unlike Images which are always 24 bits, and in color, Bitmaps
are only one bit, or blank and white. Typical uses for Bitmaps
are the creation of patterns and stipples, or shape masks against which
other primitives are clipped. <br>
In terms of constructing and using Bitmaps in FOX, it is completely
analoguous:</p>
<pre>
// Bitmap Data, in XBM Format
#define gray_width 32
#define gray_height 2
static unsigned char gray_bits[] = {0x55, 0x55, 0x55, 0x55, 0xaa, 0xaa, 0xaa, 0xaa};
// Construct a bitmap object
FXBitmap *grayBitmap=new FXBitmap(application, gray_bits, 0, gray_width, gray_height);
</pre>
<p>In terms of using Bitmaps for subsequent tiling and stippling
operations,
remember that MS-Windows has certain size limits such patterns;
X-Windows
has no such limit, but presumably smaller patterns are more
efficient.
It is probably a good idea to keep so widths such as 8,16, or 32.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
<tbody>
<tr>
<td id="HEADLINE" valign="bottom" width="100%"><b>Cursors
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>Cursors can be constructed in FOX to change the shape of the
mouse-cursor.
Constructing Cursors is very similar to constructing Bitmaps, except
that
Cursors comprise two bitmaps, a picture and a shape mask; also, Cursors
have a so-called hot-spot, the point inside the cursor-glyph which is
``pointer
to'' by the mouse. <br>
FOX currently also supports color cursors with an alpha component, i.e.
partially transparent cursors. This is limited to certain
platforms; on platforms where color cursors are not supported, the
color image is thresholded to a simple black/white image with the alpha
channel mapping to fully transparent. Designing your color
cursors with contrasting colors ensures that they will look reasonable
on such platforms.<br>
</p>
<p>Besides defining your own ``custom'' cursors, FOX also allows you
to
simply create a ``stock'' cursor, i.e. a cursor whose shape has already
been predefined by the system.
To create a custom Cursor:</p>
<pre>// Picture bits, in XBM Format<br>#define resize_width 32<br>#define resize_height 32<br>#define resize_x_hot 9<br>#define resize_y_hot 9<br>static unsigned char resize_bits[] = {<br> 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xfc, 0x00, 0x00, 0x00,<br> ....<br> 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};<br><br>// Shape bits, in XBM Format<br>#define resize_mask_width 32<br>#define resize_mask_height 32<br>#define resize_mask_x_hot 9<br>#define resize_mask_y_hot 9<br>static unsigned char resize_mask_bits[] = {<br> 0x00, 0x00, 0x00, 0x00, 0xfe, 0x01, 0x00, 0x00, 0xfe, 0x01, 0x00, 0x00,<br> ....<br> 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};<br><br><br> // Resize corner<br> resizeCursor=new FXCursor(application,resize_bits,resize_mask_bits,resize_width,resize_height,resize_x_hot,resize_y_hot);<br></pre>
<p>To create a stock Cursor:</p>
<pre>// Text Cursor<br>IBeamCursor=new FXCursor(application,CURSOR_IBEAM);<br></pre>
<p>If you define your own Custom Cursors, make sure the size is
exactly
32x32. MS-Windows does not support any other sizes. Also, the
shape
and the picture will have to be the same size.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
<tbody>
<tr>
<td id="HEADLINE" valign="bottom" width="100%"><b>If Icons Look
Funny...
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>Sometimes, your icons may look funny. This is usually
because FOX Icon routines determine the wrong value for the
transparency color. FOX can handle images with a true
alpha-channel, or images with a special transparency color. The
latter is the more common approach, as many file formats do not support
true alpha channels. <br>
Different image formats guess the transparency color in different ways.
For <b><i>GIF</i></b> Images, FOX uses the following algorithm:</p>
<ul>
<li>If a transparent color is found in the GIF file, that color is
used.</li>
<li>If not, the background color is used.</li>
<li>If the option IMAGE_ALPHACOLOR is used when constructing the
icon, the specified color is used.</li>
<li>Finally, if the option IMAGE_OPAQUE is used, the icon is forced
to be non-transparent.</li>
</ul>
<p><br>
For <b><i>BMP</i></b> images, there is no background or transparency
color in the image file format; the algorithm is simpler:</p>
<ul>
<li>The assumed transparency color is the same as the default GUI
background color, which is FXRGB(192,192,192).</li>
<li>If the option IMAGE_ALPHACOLOR is used when constructing the
icon, the specified color is used.</li>
<li>Finally, if the option IMAGE_OPAQUE is used, the icon is forced
to be non-transparent.</li>
</ul>
<p>In most cases, you will create your icons simply as below:</p>
<pre>new FXGIFIcon(app,picture_data);<br></pre>
<p>In some cases, when you want to override the transparency
color,construct your icons as:</p>
<pre>new FXGIFIcon(app,picture_data,FXRGB(192,192,192),IMAGE_ALPHACOLOR);<br></pre>
<p>To create an completely opaque icon:</p>
<pre>new FXGIFIcon(app,picture_data,0,IMAGE_OPQUE);<br></pre>
<p>For more information on graphics file formats and their
idiosyncracies,
see the <a
href="http://www.dcs.ed.ac.uk/%7Emxr/gfx/index-hi.html">Graphics
File Format Web Site</a>.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
<tbody>
<tr>
<td id="HEADLINE" valign="bottom" width="100%"><b>More on Reswrap
<br>
<img src="art/line.gif" height="1" width="100%"></b></td>
</tr>
</tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>The reswrap tool has a number of options to make it convenient to
build
C source and header files automatically from image files as a part of
your
regular project build process. Reswrap is normally invoked as
follows:</p>
<pre>reswrap [options] [-o[a] outfile] files....<br></pre>
<p>Invoking reswrap with <tt>-o outfile</tt> will make reswrap write
its output
on the file <b><i>outfile</i></b>. With <tt>-oa outfile</tt>,
reswrap
will append additional data at the end of <b><i>outfile</i></b>.
<br>
Any number of input files may be specified. Reswrap typically
produces one data statement for each of the input files specified on
the
command line.</p>
<p>Reswrap understands a few additional options:</p>
<p><b><i>-h</i></b>
</p>
<blockquote>Will print out a summary of the supported options.</blockquote>
<b><i>-v</i></b>
<blockquote>Will print out the version number.</blockquote>
<b><i>-d</i></b>
<blockquote>Reswrap normally generates its output as hexadecimal
numbers;
the -d option will make reswrap generate decimal numbers.</blockquote>
<b><i>-x</i></b>
<blockquote>Forces reswrap to generate hexadecimal numbers [the
default].</blockquote>
<b><i>-e</i></b>
<blockquote>Places the storage modifier <b><tt>extern</tt></b> in
front
of the data array, ensuring that the data array can be linked with
other
compilation units.</blockquote>
<b><i>-i</i></b>
<blockquote>Instead of a data array statement, reswrap will generate
a
declaration only. For example,</blockquote>
<pre>reswrap -i bigpenguin.gif<br></pre>
<blockquote>will produce the output:</blockquote>
<pre>/* Generated by reswrap from file bigpenguin.gif<br>*/<br>extern const unsigned char bigpenguin[];<br></pre>
<p>Which you could include as a header file into whichever source
file
needs access to the data.<br>
<br>
<b><i>-s</i></b>
</p>
<blockquote>This option suppresses comments inserted by reswrap to
indicate
the original file name from which the data statement was generated.</blockquote>
<b><i>-n name</i></b>
<blockquote>Instead of taking the filename less the extension,
reswrap
substitutes <i>name</i> for the name of the resource.</blockquote>
<b><i>-c cols</i></b>
<blockquote>Uses <i>cols</i> columns instead of the default 16
columns
in the data statements generated by reswrap.</blockquote>
<b><i>-ppm</i></b>
<blockquote>Assumes the source file is a Portable Pixmap (ppm)
file.
Reswrap will output a simple rgb array.</blockquote>
Example of using reswrap in your Application's Makefile:
<p></p>
<pre>OBJECTS = icons.o myapp.o<br>ICONS = bigpenguin.gif applogo.gif<br>icons.h: $(ICONS)<br> reswrap -e -o icons.h $(ICONS)<br><br>icons.cc: $(ICONS)<br> reswrap -o icons.cc $(ICONS)<br><br>myapp: $(OBJECTS)<br> gcc -o myapp $(OBJECTS) -lFOX -lm -lSM -lICE -lXext -lX11<br><br>myapp.o: myapp.cc icons.h<br></pre>
<p>This will cause make to generate two files, <tt>icons.h</tt> and <tt>icons.cc</tt>
which contain the declarations and definitions respectively for all the
reswrapped icons listed in the ICONS variable.</p>
</ul>
<!--- COPYRIGHT -->
<p>
<table cellpadding="0" cellspacing="0" width="100%">
<tbody>
<tr>
<td id="HEADLINE" align="right" valign="top" width="100%"><img
src="art/line.gif" height="1" width="100%"><font size="-1">
Copyright © 1997-2005 Jeroen van der Zijp</font>
</td>
</tr>
</tbody>
</table>
</p>
<!--- COPYRIGHT -->
</body>
</html>
