  icoutils documentation
  Oskar Liljeblad
  2001-03-09

  This document describes the icoutils programs.
  ______________________________________________________________________

  Table of Contents


  1. Introduction
     1.1 Introduction
     1.2 Background
     1.3 Home Page for icoutils
     1.4 Copyright

  2. What is icoutils
     2.1 Concepts
     2.2 Components
     2.3 Resource Types

  3. icotool
     3.1 Command line options
     3.2 Examples

  4. wrestool
     4.1 Command line options
     4.2 Examples

  5. extresso
     5.1 Command line options
     5.2 Examples
     5.3 Resource Scripts
     5.4 genresscript

  6. Post-Matters
     6.1 Feedback
     6.2 Known Bugs
     6.3 Things To Do


  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn



  11..11..  IInnttrroodduuccttiioonn

  The iiccoouuttiillss programs deal with Microsoft Windows icons and cursors.
  The included programs are "wrestool", "icotool" and "extresso".

  Resources (such as icons and cursors, but not only those) can be
  extracted from Windows executable and library files with "wrestool".
  Conversion of these files to XPM images is done with "icotool".
  "extresso" automates these tasks with the help of special resource
  scripts.


  11..22..  BBaacckkggrroouunndd

  In the summer of 1998, I wrote a program called iiccoouuttiill. I wanted to
  re-use icons found in Windows 98 in icewm. Icewm does not read icon
  files, but supports _._X_P_M images. icoutil was able to extract XPM
  images from _._I_C_O files. But the ICO files had to come from somewhere -
  namely DLL and EXE binaries. I did at that time not know how the
  structure of these files, but was able to write a program called
  eexxttrriiccoo that used Win32 methods to extract icon resources from such
  binaries. Because of this it was necessary to run extrico in a Win32
  environment.

  The program icoutil was later rewritten and replaced with iiccoottooooll.  I
  also removed extrico, replacing it with wwrreessttooooll to read DLL and EXE
  files and extract resources without the need of Windows.

  With eexxttrreessssoo, that automates these tasks, the iiccoouuttiillss programs were
  formed. The first version was released in June, 1999.


  11..33..  HHoommee PPaaggee ffoorr iiccoouuttiillss

  http://www.student.lu.se/~nbi98oli/


  11..44..  CCooppyyrriigghhtt

  The icoutils programs are copyright (C) 1998-2001 Oskar Liljeblad.

  The icoutils programs are licensed under the terms of the GNU General
  Public License.

  You should have received a copy of the GNU General Public License
  along with icoutils; see the file COPYING. If not, write to the Free
  Software Foundation, 59 Temple Place - Suite 330, Boston, MA
  02111-1307, USA.


  22..  WWhhaatt iiss iiccoouuttiillss



  22..11..  CCoonncceeppttss

  The following concepts are used by the icoutils programs:


     iiccoonn ffiillee
        An icon file contains a number of images. Image properties are
        width, height, number of colors, color RGB data, image data,
        mask data.  An icon file is basicly a set of BMP images. The
        extension of these files found in Windows 3.0 and later is _._I_C_O.


     ccuurrssoorr ffiillee
        Cursor files are exactly the same as icon files, with the
        exception that four bytes, for each image, are used to store the
        cursor hotspot. The extension of cursor files is _._C_U_R.


     mmoodduullee
        Microsoft Windows executables (_._E_X_E) and dynamicly linked
        libraries (_._D_L_L) are usually named modules.

        32-bit modules (here 32 means size of memory addresses in the
        file) are used in Windows 9x, NT 4 and later. 16-bit modules are
        found in Windows 3.x.


     rreessoouurrccee
        A resource is a piece of data embedded into a Windows module.

        In 32-bit modules, resources are arranged by type, name and
        language (one directory tree for each type, and name).  In
        16-bit modules, resources are arranged by type and name only.
        Types and names may be either an integer or a string.

        There are several types of resources; most of them are listed in
        the ``Resource Types'' section.


     rreessoouurrccee ssccrriipptt
        Resource scripts are simple files used by extresso to extract
        resources from listed files. (Resource scripts are specific to
        extresso.)

        The format of resource scripts is described in the ``Resource
        Scripts'' section.



  22..22..  CCoommppoonneennttss

  The icoutils programs consists of three programs; icotool, wrestool
  and extresso. They are described in separate sections.


  22..33..  RReessoouurrccee TTyyppeess

  The wrestool program recognizes the resource types list below.  The
  ids of these resources are always numeric and not strings.

  Not all resource types are supported by wrestool. However, if you know
  the format of the data in the resource, you can use the "--raw" option
  to extract it. (This way you can extract resources of any type.)


     ccuurrssoorr ((11))
        A single cursor bitmap image. Read as part of group_cursor
        resources.


     bbiittmmaapp ((22))
        A bitmap image. (I need to do more research on this.)


     iiccoonn ((33))
        A single icon bitmap image. Read as part of group_icon
        resources.  This resource is similar to cursor resource; cursors
        contain four additional bytes of hotspot coordinates.


     mmeennuu ((44))
        Resources for menus (in popup and menubars).  Currently,
        wrestool does not support this resource type.


     ddiiaalloogg ((55))
        Definitions (widgets with locations) for dialog boxes.
        Currently, wrestool does not support this resource type.


     ssttrriinngg ((66))
        The string table resource, containing a number of unicode
        strings. Currently, wrestool does not support this resource
        type.



     ffoonnttddiirr ((77))
        The font directory, containing information on a number of font
        resources (8). Windows non-TTF font (_._F_O_N) files are actually
        libraries with resources in them. Currently, wrestool does not
        support this resource type.


     ffoonntt ((88))
        A single font - the contents of a _._F_N_T file. Read as part of
        fontdir resources. Currently, wrestool does not support this
        resource type.


     aacccceelleerraattoorr ((99))
        Keyboard accelerator tables.  Currently, wrestool does not
        support this resource type.


     rrccddaattaa ((1100))
        Arbitrary resource data, user-defined. There are no restrictions
        to the format of these resources.


     mmeessssaaggeelliisstt ((1111))
        Not supported.


     ggrroouupp__ccuurrssoorr ((1122))
        A set of cursors. With a few modifications (and with cursor
        resources), this resource can be extracted as a .CUR file.


     ggrroouupp__iiccoonn ((1144))
        A set of icons. With a few modifications (and with icons
        resources), this resource can be extracted as a .ICO file.


     vveerrssiioonn ((1166))
        Version information, stored as binary data. Could be extracted
        without modifications, but the data is of probably little use.
        Currently, wrestool does not support this resource type.


     ddllggiinncclluuddee ((1177))
        Not supported.


     pplluuggppllaayy ((1199))
        Not supported.


     vvxxdd ((2200))
        Not supported.


     aanniiccuurrssoorr ((2211))
        Animated cursors. Currently, wrestool does not support animated
        cursor or icons, nor does icotool.


     aanniiiiccoonn ((2222))
        Animated icons. I have only seen these in Windows 3.x.
        Currently, wrestool does not support animated cursor or icons,
        nor does icotool.


  33..  iiccoottooooll

  Usage:


       icotool [OPTIONS]... [FILE]...



  The icotool program reads _._I_C_O or _._C_U_R files, and lists or extracts
  the images they contain. At this time, the only supported image format
  is XPM. icotool does not require any libraries to make XPM files.

  Filters, specified as command line options, control what images to
  extract.


  33..11..  CCoommmmaanndd lliinnee ooppttiioonnss


     --xx,, ----eexxttrraacctt
        Extract images in file. (By default, images will be extracted to
        standard out if --output was not specified.)


     --ll,, ----lliisstt
        Output list of images in file (default).


     --cc,, ----ccrreeaattee
        Create icon files from specified images (not yet implemented).


     --ii,, ----iinnddeexx==NNUUMMBBEERR
        Index of the image to perform operation on.


     --ww,, ----wwiiddtthh==PPIIXXEELLSS
        Match images of this specific width only.


     --hh,, ----hheeiigghhtt==PPIIXXEELLSS
        Match images of this specific height only.


     --CC,, ----ccoolloorrss==CCOOUUNNTT
        Match images of this number of colors only.


     --XX,, ----hhoottssppoott--xx==PPIIXXEELLSS
        If matching cursor, match only cursor where the hotspot X-
        coordinate is this value.


     --YY,, ----hhoottssppoott--yy==PPIIXXEELLSS
        If matching cursor, match only cursor where the hotspot Y-
        coordinate is this value.


     ----iiccoonn
        Match icon files only.


     ----ccuurrssoorr
        Match cursor files only.
     --aa,, ----aallll
        Perform operation on all images (default)


     --oo,, ----oouuttppuutt==PPAATTHH
        Speicifies where to place extracted images. If PATH does not
        refer to an existing directory, and does not end with a slash
        ('/'), all output will be written to the file denoted by PATH.
        (This means that if you extract multiple images, PATH will
        contain the last images only.)


     --OO,, ----oouuttppuutt--bbaassee==BBAASSEE
        Similar to --output, but here BASE is the basename of extracted
        files.  For example, if BASE is "tmp_", the extracted image
        files would be named "tmp_C_WxH.FMT" (where C is number of
        colors, W width and H height).

        This option cannot be combined with the --output option.


     ----ffoorrmmaatt==FFOORRMMAATT
        Extraction format; "xpm", or "ppm". At this time, only the "xpm"
        format is supported though.


     --mm,, ----iimmaaggee--mmooddee==MMOODDEE
        Controls what will be extracted of each image; "image" for image
        data only, "mask" for only mask, or "both" for both (default).


     --vv,, ----vveerrbboossee
        Explain what is being done. The verbose option may be specified
        more than once, like "-vv", to make icotool even more verbose.


     ----hheellpp
        Display a help message and exit.


     ----vveerrssiioonn
        Output version information and exit.



  33..22..  EExxaammpplleess

  List all images in file "demo.ico":


       $ icotool -l demo.ico
       --icon --index=0 --width=32 --height=32 --colors=16
       --icon --index=1 --width=16 --height=16 --colors=16
       --icon --index=2 --width=48 --height=48 --colors=16
       --icon --index=3 --width=16 --height=16 --colors=256
       --icon --index=4 --width=32 --height=32 --colors=256
       --icon --index=5 --width=48 --height=48 --colors=256
       $



  List only 16-color images in "demo.ico":



  $ icotool -l --colors=16 demo.ico
  --icon --index=0 --width=32 --height=32 --colors=16
  --icon --index=1 --width=16 --height=16 --colors=16
  --icon --index=2 --width=48 --height=48 --colors=16
  $



  Extract all images to current directory, naming the destination files
  "demo.ico_C_WxH.xpm":


       $ icotool -x --output=. demo.ico
       $ ls *.xpm
       demo.ico_16_16x16.xpm  demo.ico_16_48x48.xpm   demo.ico_256_32x32.xpm
       demo.ico_16_32x32.xpm  demo.ico_256_16x16.xpm  demo.ico_256_48x48.xpm
       $



  Extract all 256-color icon images in all .ico files in the current
  dir, placing the extracted images in "img/"


       $ icotool -x -oimg/ -C256 *.ico
       $



  44..  wwrreessttooooll

  Usage:


       wrestool [OPTIONS]... [FILE]...



  The wrestool program reads 16- or 32-bit Windows binaries (_._E_X_E and
  _._D_L_L files), and lists or extracts the resources they contain. Some
  resources require processing before they can be written to files;
  wrestool is able to do this with icon and cursor resources.

  Filters, specified as command line options, control what resources to
  extract.


  44..11..  CCoommmmaanndd lliinnee ooppttiioonnss


     --xx,, ----eexxttrraacctt
        Extract resources. (By default, resources will be extracted to
        standard out if --output was not specified.)


     --ll,, ----lliisstt
        Output list of resources (default).


     --tt,, ----ttyyppee==[[++||--]]IIDD
        Resource type identifier of affected resources. If preceeded
        with a dash ("-"), id must be numeric; if preceeded with a plus
        sign ("+"), id must be a string.

        The type ID may also be the name of a resource type. (If this is
        the case, a leading dash or plus sign may not be included.) A
        list of resource types can be found in the ``Resource Types''
        section.


     --nn,, ----nnaammee==[[++||--]]IIDD
        Resource name identifier of affected resources. Like the --type
        option, a leading dash or plus sign controls the datatype of the
        id.


     --LL,, ----llaanngguuaaggee==[[++||--]]IIDD
        Resource language identifier. Has no effect when processing
        16-bit libraries.


     ----aallll
        Perform operation on all resource (default).


     --oo,, ----oouuttppuutt==PPAATTHH
        Where to place extracted resources. If PATH does not refer to an
        existing directory, and does not end with a slash ("/"), all
        output will be written to the file PATH. (This means that if you
        extract multiple resources, PATH will contain the last resource
        only.)


     --RR,, ----rraaww
        Do not parse resource contents - extract raw data. (This option
        will probably be replaced with --format=raw in future version of
        icoutils.)


     --vv,, ----vveerrbboossee
        Explain what is being done. The verbose option may be specified
        more than once, like "-vv", to make wrestool even more verbose.


     ----hheellpp
        Display a help message and exit.


     ----vveerrssiioonn
        Output version information and exit.



  44..22..  EExxaammpplleess

  List all resources in file "write.exe":


       $ wrestool -l write.exe
       --type=3 --name=1 --lang=1033 [type=icon offset=0x3120 size=752]
       --type=3 --name=2 --lang=1033 [type=icon offset=0x3410 size=304]
       --type=14 --name=1 --lang=1033 [type=group_icon offset=0x3540 size=34]
       --type=16 --name=1 --lang=1033 [type=version offset=0x3564 size=808]
       $



  List all (group-) icon resource in file "write.exe":


       $ wrestool -l --type=group_icon write.exe
       --type=14 --name=1 --lang=1033 [type=group_icon offset=0x3540 size=34]
       $



  Extract all icons to current directory, naming the destination files
  "write.exe_T_N.ico":


       $ wrestool -x --output=. -t14 write.exe
       $ ls *.xpm
       write.exe_14_1.ico
       $



  Combining wrestool and icotool to extract icon images of an icon
  resource:


       $ wrestool -x write.exe -t14 -n1 | icotool -x -o. -
       $ ls *.xpm
       write.exe_14_1.ico_16_16x16.xpm  write.exe_14_1.ico_16_32x32.xpm
       $



  55..  eexxttrreessssoo

  Usage:


       extresso [OPTIONS]... [FILE]...



  The extresso program reads resource scripts, and uses wrestool to
  extract the listed resources and icotool to convert them (if
  necessary).


  55..11..  CCoommmmaanndd lliinnee ooppttiioonnss



     --oo,, ----oouuttppuutt==DDIIRR
        Where to place extracted files (default `.').


     ----ffoorrmmaatt==FFOORRMMAATT
        Extraction format of icon resources, passed to icotool.


     --bb,, ----bbaassee==DDIIRR
        Base directory of local files in scripts. (This will be appended
        to the "file" lines in the scripts.)

     --ii,, ----iinntteerraaccttiivvee
        Prompt before extraction.


     --vv,, ----vveerrbboossee
        Explain what is being done.


     ----hheellpp
        Display a help message and exit.


     ----vveerrssiioonn
        Output version information and exit.



  55..22..  EExxaammpplleess


  Extract all resources from "shell32.dll" using the resource script
  "win98_shell32", assuming Windows 98 is available in "/mnt/C/windows",
  and placing output in "out/":


       $ extresso ../data/resscripts/win98_shell32 --base=/mnt/C/windows --output=out/
       $ find out/ -type f | wc -l
       339
       $



  55..33..  RReessoouurrccee SSccrriippttss

  This section needs to be written. For now, I recommend you take a look
  at the included resource scripts.


  55..44..  ggeennrreessssccrriipptt

  The genresscript program takes any number of Windows binaries, and
  outputs a resource script with all resources from the binaries listed.
  (Everything but the destination filename will be filled in in the
  script.)

  This is useful when you already have extracted images and want to
  create a resource script of them.



  66..  PPoosstt--MMaatttteerrss



  66..11..  FFeeeeddbbaacckk

  I would really like to hear from you about icoutils. Especially
  interesting would be

  +o  Bug-reports and patches.


  +o  Ideas for new features.

  +o  Suggestions for changes.

  +o  Spelling and grammar mistakes in the documentation.

     Email can be sent to the author, Oskar Liljeblad, at
     osk@hem.passagen.se.


  66..22..  KKnnoowwnn BBuuggss

  See the BUGS file.


  66..33..  TThhiinnggss TToo DDoo

  See the TODO file.



