IBROWSE 2.0 - Icon browser/converter for HP100/200LX
----------------------------------------------------

NEW IN VERSION 2

- Ability to view Windows icons (.ICO files) and convert them to
  Palmtop format, intelligently handling the conversion of 16-
  colour icons to monochrome icons,
- Each icon is displayed lifesize, as well as full screen,
- Various minor menu and function key improvements.

ABOUT IBROWSE

IBROWSE is a browser for viewing HP Palmtop-format icon files,
and a tool to convert Windows-format icons into Palmtop-format
icons.

If you're like me, you've probably downloaded the various
ICONS.ZIP files from Compuserve (or wherever), and found your-
self with anything up to 50 .ICN files lurking about on your
Palmtop, with such helpful names as AAPLAY.ICN.  Then later,
when its time to actually use one (when adding an application to
the MORE screen), finding the most appropriate icon for the new
app stretches your perseverance to previously unknown limits.
There are no usable methods of browsing the icon files on a
Palmtop - the various methods (involving clever combinations of
Filer, the built-in icon editor (200LX), or System macros) are
either clumsy, time-consuming or both, and they make the three
default icons that the MORE program provides look more and more
attractive.

This is where IBROWSE comes in.  IBROWSE is a DOS program with
the same look and feel as the built-in apps, that allows you to
browse a set of icons.  Its functionality is, in essence:
give it a directory name, and it will display all the icon files
in that directory, one at a time, separated by one keystroke.
It can also display any icon file that you specify by name.

(New in version 2)  Also, it has the capability to view (colour)
Windows icons (.ICO) files as (monochrome) Palmtop icons,
performing the conversion on the fly, in memory.  The colour
mapping used in this conversion is configurable.  The converted
icon need only be saved to disk when the colour combinations are
ideal (if at all).

That's IBROWSE, in a nutshell.


INSTALLATION INSTRUCTIONS

IBROWSE comprises the following files:

IBROWSE.EXE       The program itself - will only run on a
                  100/200LX
IBROWSE.ICN       An icon file, in case you want to run IBROWSE
                  from the MORE screen
IBROWSE.TXT       This file

To install IBROWSE on your Palmtop, copy at least the
IBROWSE.EXE file to your Palmtop, and put it in the directory
that you usually run programs from (for example, C:\BIN).
Then simply type "IBROWSE" and press ENTER at the DOS prompt, or
select IBROWSE.EXE in Filer and press ENTER.

IBROWSE has the facility to specify on the command line the
directory that contains all your icons, so if you set IBROWSE up
correctly in the MORE screen, you'll never have to enter any
more path names when browsing icons.  For example, if you copied
IBROWSE.EXE into the C:\BIN directory, and all your available
icons live in the C:\_DAT\ICONS directory, this is how you would
set up IBROWSE to run in the MORE screen:

- First, copy the file IBROWSE.ICN into the same directory as
  the IBROWSE.EXE file.

- Press   MORE F2   to get the "Add Application" screen.

- Fill it in as follows:

     Name:      &Ibrowse

     Path:      c:\bin\ibrowse.exe c:\_dat\icons

     Comments:  

  Then TAB to the "Icon:" field (an appropriate icon should be
  displayed), and press F10.


USING IBROWSE

IBROWSE is a DOS program (a DOS .EXE).  It is NOT Sysmgr
compliant, but it does have the same look and feel as the other
built-in apps.  It will not run on a DOS machine (sorry).
All icons are displayed in their natural size, as well as full
screen.  Full screen they appear slightly stretched horizontally
(maybe I'll fix that in rev 2.1).

Command line arguments:

The command line usage of IBROWSE is as follows:

    IBROWSE [icon-directory]

If no directory is specified on the command line, or the one
specified is invalid, the directory containing the IBROWSE.EXE
file is used.  This directory becomes the "default" directory
for browsing/searching for icon files.

When IBROWSE first starts, it shows you the welcome screen.
From there, you're on your own, with an empty(ish) screen and
just the menus and function keys to play with.  The top line of
the screen should tell you the default icon directory.


Selecting Files/Directories:

At this point you probably want to see some icons.  There are
two ways of doing this:  View an individual icon file, or browse
a directory for all various icon files.  Either of these methods
can be done through the menus or the function keys (which are
detailed on the bottom line of the screen).

1. Selecting individual files:

        MENU OPTION:      File/Select File
        FUNCTION KEY:     F2 (File)

   Using either the above menu option or function key will allow
   you to select an individual icon file (Palmtop or Windows,
   Palmtop is the default) for viewing.  A dialog box is
   displayed prompting you to enter the name of the icon file
   that you are interested in (the name of the default directory
   is entered already for you as a guide, but you can backspace
   over this and type anything you want).  Enter the file name,
   and press ENTER (or F10) and the icon whose name you entered
   is displayed both lifesize and full screen.

   A filename that ends in .ICO is assumed to be a Windows icon,
   and an attempt will be made to convert it to Palmtop format
   (see the section below on Conversions).  Any other filename
   will be assumed to be a Palmtop icon file name.

   The name of the icon, and its type are displayed above the
   lifesize version of the icon.

2. Browsing entire directories:

        MENU OPTION:      File/Select dir
        FUNCTION KEY:     F3 (Dir)

   Using either the above menu option or function key will allow
   you to view all the icons of a particular format (Palmtop or
   Windows) in a particular directory.  A dialog box is
   displayed prompting you to enter the name of a directory (the
   name of the default directory is entered already for you as a
   guide, but you can backspace over this and type anything you
   want).  The dialog box also contains a checkbox allowing you
   to select Windows icons as the type of icon to be displayed
   (instead of Palmtop icons - You cannot browse both at the
   same time).  This checkbox is "checked" (or unchecked) by
   pressing the SPACE bar.

   Enter the name of the directory, choose the appropriate icon
   format type, and press ENTER (or F10) and IBROWSE will
   display all the icon files of that type in that directory,
   one at a time.  They are displayed in NATURAL DIRECTORY
   ORDER.  i.e. they are not sorted in any particular sequence,
   and certainly not alphabetically.

   The directory entered becomes the default directory.

3. Navigating the browse sequence:

   Certain other function keys and menu options have been made
   available to provide more control over the browse sequence:

        MENU OPTION:      Browse/Start
        FUNCTION KEY:     F4 (Browse or Start)

   This will start a browse of the default directory (the
   directory whose name is displayed in the top line of the
   screen), or restart the current browse (if there is one).
   Similar to "Select dir" (above), except you are not given the
   opportunity to enter the directory's name.

        MENU OPTION:      Browse/Next
        FUNCTION KEY:     F5 (Next)

   This will display the next icon file in the sequence.
   ENTER and SPACE do the same thing.

        MENU OPTION:      Browse/End
        FUNCTION KEY:     F6 (End)

   This will stop the current browse.
   ESC does the same thing.


Converting Windows icons:

Every time a Windows icon is selected, whether by entering its
name specifically or encountering it in the middle of a browse,
it is converted automatically to the Palmtop format before it is
displayed.  This conversion is done in memory - no corresponding
Palmtop icon file is created at this point.  The conversion is
made using a set of colour mappings, that determine which of the
16 possible colours of a Windows icon are to be mapped to
"black" in the displayed Palmtop icon, and which are to be
mapped to "white".  It is possible to modify this set of
mappings at any time.

This all becomes necessary because it is not possible to
automatically determine which combination of colours "mapped to
black" will produce the most aesthetically pleasing resultant
Palmtop icon.

The 16 colours are (in "numerical" order):

   Black
   Dark red
   Dark green
   Brown
   Dark blue
   Dark purple
   Grey blue
   Light grey
   Dark grey
   Red
   Bright green
   Yellow
   Bright blue
   Light purple
   Light blue
   White

There is a 17th "colour", which is, in fact, the transparent
"background" colour of a Windows icon (the part of the icon that
always assumes the colour of the background that the icon is
placed upon).  This background can also be mapped to either
black or white (white is the default).

In almost all icons, it would be appropriate to let the above
colour "black" be mapped to black, and "white" NOT to be mapped
to black, but the other colours are less obvious.  Yellow might
look good mapped to black in some icons, whereas it may be
better left as white in others.  For this reason, the mapping of
the colours has been made completely configurable.  The mapping
is controlled by a set of global colour settings that are
modified via a "Colours" dialog box (File/Colours, or F9).

When a Windows icon is first displayed, you may find that it
bears little resemblance to the colour version that you saw on
your desktop/notebook/whatever.  However, if you have an idea of
which colours (besides black) you wish to see displayed as black
in the Palmtop version, then select the "Colours" dialog box,
and check the boxes next to those colours (by using the SPACE
bar).  Press F10 to save these choices, and the icon will be
redisplayed using the new colour mapping.  A little
experimentation should produce a satisfactory icon.

An extra checkbox has been added to the "Colours" dialog box,
labelled "Reverse video".  This, when checked, reverses the
entire colour mapping (and thus the icon image), turning every
black icon white, and vice versa.

Apart from being colour images, Windows icons also differ from
Palmtop icons in their size.  Windows icons are 32x32 pixels in
size, while Palmtop icons are 44 pixels wide by 32 pixels high.
When converting windows icons to Palmtop icons, if we map each
Windows pixel to a single Palmtop pixel, and centre the
resultant image, we are left with two vertical "stripes", each
six pixels wide down each side of the resultant Palmtop image.
This is hard to avoid, so these "stripes" have simply been made
part of the "background" of the Palmtop icon.  i.e. if the
"background" checkbox in the "Colours" dialog box is checked,
these stripes will appear black, along with the rest of the
icon background.  Otherwise they are left as white.


Saving the converted icon:

When you have experimented with the colour mapping (if
necessary), and have an image on the screen which is what you
want, then it is time to save it as a Palmtop icon.  This is
done using the "File/Convert icon" menu option, or the F8
(Convert) function key.  This will display a dialog box
prompting for the name of the new icon to be created (or
overwritten).  The name of the current Windows icon (with the
.ICO changed to .ICN) is displayed as a default, but this can be
backspaced over and any valid filename may be typed in.
Pressing ENTER or F10 will create the new (Palmtop) icon file.


Getting Help:

        MENU OPTION:      Help/Help
        FUNCTION KEY:     F1 (Help)

These display a simple help screen.

        MENU OPTION:      Help/About

This displays the startup screen again.


Exiting the program:

There are several ways of exiting from IBROWSE.  These are:

        FUNCTION KEY:     F10 (Quit)
        MENU OPTION:      File/Exit
        MENU OPTION:      Quit
	CTRL-ALT-DEL      joke .....


ET CETERA

This program was written in C using HPCLIB - a library of C
functions written by Harry Konstas that allows a programmer to
design a program with a user interface similar to the HP built-
in apps.  It was compiled using the Microsoft Visual C++ v1.0
command-line compiler.

I'm a computer programmer by trade, but this is the first time
I've ever made a program available to the community at large, so
any comments (ideas, bugs, etc) would be greatly appreciated.
My Compuserve ID is listed below.  If you'd like a copy of the
source code, let me know and I'll mail it to you.

Mark Virtue
7/40 Sutherland St
Cremorne, NSW, 2090
Australia
Compuserve ID: 100353,3254

February 1995
