ICO File Tool Files

                                Icon File Tool


What is it?
--------------------------------------------------------------------------------

    Icon File Tool is a Java based icon file tool for reading and
    writing icon files. Includes features to perform the following tasks:

    1.
        Extract icons entries creating icon files for each extracted icon entry.
    2.
        Create an icon file with icon entries extracted from other icon files.
	3.
		List icon image information.
	4.
		View icon images and their image information.
	5.
		Report icon file mapping details.

    This is useful for creating icon files for other tools that build Windows
    EXE wrappers around Java programs.

	The Icon File Tool library includes an open API similar to the AC.lib-ICO
	solution. The Icon File Tool library doesn't improve upon the  AC.lib-ICO
	SPI features but does include additional features for creating icon files.

    The AC.lib-ICO classes from Christian Treber are partially used, slightly
    enhanced and partially rewritten for the purpose of creating icon files.
    The exe file is created using Launch4J.
    The expanded jar is created using the FatJar library.
    Ant is used to build the application.
    JUnit is used to test the application.
	Jakarta Commons IO is used to compare and read test files.
    Log4J is used to log error messages.

Limitations
--------------------------------------------------------------------------------

    Only 1, 4, 8 indexed BMP images and 24 and 32 RGB BMP images are supported.
    If an icon file contains other images such as PNG or JPG then those entries
	will be skipped. The other BMP entries will be processed.

	Also, no BMP compressions are supported.

Why?
--------------------------------------------------------------------------------

    I wanted to build a tool that generates an empty Java project folder that
    can be used to build Windows EXE files from Java programs.

The Latest Version
--------------------------------------------------------------------------------

    See the project at https://sourceforge.net/projects/winiconft/.

Installation
--------------------------------------------------------------------------------

    To run the application only the JAR or EXE file is necessary. The EXE is a
    wrapper around the JAR file.

    For Windows:

    Move the Icon File Tool.exe file to a folder that is on an execution
    path or add the location of Icon File Tool.exe to the execution
    pathing.

    Alternate For Windows:

    Users can modify and use the runjar.bat script as necessary.

    The Icon File Tool is a console application and no GUI is available.

Building
--------------------------------------------------------------------------------

    Install Ant.
    Install Launch4J.
    Copy fatjar.jar file into Ant's lib folder.
    Copy the example-build.properites file to user-build.properties.
    Modify the user-build.properties launch4j.programfiles.path value to match
    the Launch4J installation folder.

    Open command prompt in the dev folder.

    To produce the JAR file run
    ant jar

    On Windows to produce the EXE file run
    ant exe

    To clean the build work files run
    ant clean

Testing
--------------------------------------------------------------------------------

	The unit tests should all pass.

	The system tests will fail on icon files that contain icons other than BMP
	images.

Reference
--------------------------------------------------------------------------------

    To run:

    "Icon File Tool.exe" -clx {icon file}, [{icon file...}]
    or
    java -jar "Icon File Tool.jar" -clx {icon file}, [{icon file...}]

    The c, l, v, or x option determines the action to be performed against
    subsequent parameter(s).

	where

	-c Create first icon file with the icon entries of subsequent icon files.
	-l List icon image information.
	-n Include width, height, and bit per pixel in the extracted file name(s).
	-r Report file details.
	-v View icon image and information in GUI window.
	-x Extract icons entries creating icon files for each extracted icon entry.
	-help -h -? This message.

	If a file name begins with -- then it will not be treated as a switch and
	will be changed to a single -.

    Extract Example:

        "Icon File Tool.exe" -x example.ico

        This will produce two files: Icon1.ico & Icon2.ico.

    List Example:

        "Icon File Tool.exe" -l example.ico

        This will display information about the icon file header and
        information for each icon image in the example.ico file.

    Report Example:

        "Icon File Tool.exe" -r example.ico

        This will display file information about each icon image in the
        example.ico file.

    View Example:

        "Icon File Tool.exe" -v example.ico

        This will display the icon and information about the icon file header
        and information for each icon image in the example.ico file.

    Create Example:

        "Icon File Tool.exe" -c both.ico first.ico second.ico

        This will produce the file both.ico containing icon entries from both
        icon files; first.ico and second.ico.

Licensing
--------------------------------------------------------------------------------

    This software is licensed under the terms you may find in the file named
    "LICENSE" in this directory.


    Thanks for using Icon File Tool.

                            The Scheuble Group
                            <http://www.scheublegroup.com/>