/*
 * Copyright (C) 1989-94 GROUPE BULL
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
 * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * Except as contained in this notice, the name of GROUPE BULL shall not be
 * used in advertising or otherwise to promote the sale, use or other dealings
 * in this Software without prior written authorization from GROUPE BULL.
 */

				The XPM
			Frequently Asked Questions

This article contains the answers to some Frequently Asked Questions about the
XPM format and/or library. If you don't find the answer to your problem here,
then you can mail either to lehors@sophia.inria.fr or to the mailing list
xpm-talk@sophia.inria.fr.

                               Contents

1. How do I convert my images to or from XPM ?
2. Why are my XPM files said to be invalid ?
3. Why does my program core dumps using XPM ?
4. Why does my program core dumps using XPM with a widget ?
5. What exactly triggers the creation of a mask when using XPM ?
6. How should I use the mask ?
7. Is there a string to pixmap converter somewhere ?
8. How can I edit XPM icons ?
9. Is there a colection of icons somewhere ?

----------------------------------------------------------------------
1. How do I convert my images to or from XPM ?
----------------------------------------------------------------------

  Netpbm is surely the best image conversion package that I know of. It defines
  formats for color, gray and monochrom images and provides a set of filters.
  Thus a GIF image can be converted to XPM with something like:

  $ giftoppm youricon.gif | ppmtoxpm > youricon.xpm

----------------------------------------------------------------------
2. Why are my XPM files said to be invalid ?
----------------------------------------------------------------------

  There are three official versions of the XPM format. The XPM library since
  version 3.3 can read all them but writes out only XPM 3. Also the small
  program called sxpm which is part of the XPM library package can be used to
  automatically translate XPM 1 and 2 files to XPM 3 with a command such as:

  $ sxpm -nod yourxpm1or2file -o yourxpm3file

  Also, the XPM format defines "None" to be the color name meaning
  "transparent", but IXI used to hack the XPM library in its early days to
  handle transparency as "#Transparent". This makes IXI format not compatible
  with the official XPM format, and so not readable neither by the official XPM
  library nor any of the programs built on top of it.

  The only solutions are either to stick on IXI programs which can deal with
  their format or convert your files to the standard XPM format. This can be
  done simply by changing "#Transparent" to "None".

----------------------------------------------------------------------
3. Why does my program core dumps using XPM ?
----------------------------------------------------------------------

  Be sure the XpmAttributes structure you pass by reference as a valid
  valuemask. You can give NULL instead if you don't want to use an
  XpmAttributes but if you do you MUST initialize its valuemask component to
  some valid value, at least 0, otherwise unpredictable errors can occur.

  So instead of doing something like:

      XpmAttributes attrib;

      XpmReadFileToPixmap(dpy, d, filename, &pixmap, &mask, &attrib);

  you should do:

      XpmAttributes attrib;

      attrib.valuemask = 0;
      XpmReadFileToPixmap(dpy, d, filename, &pixmap, &mask, &attrib);

----------------------------------------------------------------------
4. Why does my program core dumps using XPM with a widget ?
----------------------------------------------------------------------

  o First the XPM library is Xlib level, so don't pass your widget as a
    Drawable parameter. A Drawable is either a Window or a Pixmap. The widget's
    window can do the job but:

  o Then a widget only gets a Window when realized, so passing XtWindow(widget)
    with a not yet realized widget is wrong. Either realize you widget first or
    use another window. Since the Drawable parameter is only used to specify
    the screen to which the pixmap must be created on, most of the time the
    default root window is just fine.

----------------------------------------------------------------------
5. What exactly triggers the creation of a mask when using XPM ?
----------------------------------------------------------------------

  Basically a mask is created if "None" is used as one of the color of the
  pixmap. Be aware that this is not only true if it is used in the XPM of the
  pixmap since the colors can be overriden at load time. So a mask is created
  if the "None" color is used at load time, coming either from the XPM
  definition or the color overriding.

----------------------------------------------------------------------
6. How should I use the mask ?
----------------------------------------------------------------------

  There are basically two ways of using the mask:

  o Use the mask as a shapemask with the X11 Nonrectangular Saphe Window
    Extension. Typically this is what should be done when the icon is used in a
    desktop.

  o Use the mask as a clipmask in the GC you pass to XCopyArea when drawing the
    pixmap. So the "transparent" pixels being not actually drawn will get the
    underlying pixels colors.

----------------------------------------------------------------------
7. Is there a string to pixmap converter for Motif ?
----------------------------------------------------------------------

  Not yet, but Motif 2.0 will support XPM pixmap as well as XBM bitmaps.

----------------------------------------------------------------------
8. How can I edit XPM icons ?
----------------------------------------------------------------------

  As listed below several editors either commercial or not are supporting the
  XPM format. However, pixmap is the one I would recommend since it is freely
  available and, being fully dedicated to XPM, it allows to edit all the
  special things, such as the symbolic color names, which makes XPM different
  from all the other image formats. Pixmap can always be found by ftp from
  ftp.x.org (contrib) and avahi.inria.fr (pub/pixmap).

                                XPM Icon Editors
                                ================

  Program         Source/Author           Platforms       SA      XPM     cost
  ----------------------------------------------------------------------------
  pixmap          Lionel Mallet           source          yes      3       NC
     * version 2 soon to be available
     * current version doesn't work on 24-plane displays

  pixt            J. Michael Flanery      source          yes      1       NC
     * doesn't work on 24-plane displays

  X.desktop       IXI                     DECstation      no       3      N/A
                                        ?
     * current version doesn't work on 24-plane displays

  olpixmap        USL                     Sun             ?        ?       ?
                                        SVR4.2, UnixWare

  xfedor          Daniel Dardailler       source          yes      3       NC
     * doesn't work on 24-plane displays
     * only uses XLIB

  SCOpaint        SCO/Wing Eng            ODT             yes     2.8     N/A
     * included with the ODT package

  pme.icn         Icon Project            source          yes      3       NC
     * written in the Icon language

  PixEditT        Free Widget Foundation  source          yes      3       NC
     * there is currently no support for editing the colormap

  xscribble       ?                       source          yes      ?       NC
     * requires the FWF

  vueicon         Hewlett-Packard         HP              yes      3      N/A
     * included with Vue3.0

  iconedit V3     SunSoft                 Sparc/Sun3      yes      2      N/A

  Pixmap Editor   ICS                     ?               yes      ?       ?
     * this is a Widget, not a complete program

  ezX             Sunrise Software        ?               ?        ?      N/A

  SA - Stand Alone program
  NC - No Charge (i.e. free); most programs are copyrighted.
  XPM - XPM format supported
  source - built from source code; likely works on all standard X platforms
  N/A - icon editor is normally distributed with other software


  Send updates, additions, corrections, etc. to 
     dsmith@ann-arbor.applicon.slb.com (or dsmith@aaaca1.sinet.slb.com)

----------------------------------------------------------------------
9. Is there a collection of icons somewhere ?
----------------------------------------------------------------------

  At least there is one freely available: Anthony's X Icon Library. You can
  found it on several ftp servers. It contains only small icons (less than
  about 100x100 pixels in size) which are stored in groups in a logical
  way. Color icons are stored in XPM format and Black & White icons in XBM.
