

WPPicture - An OS/2 Workplace Shell class for displaying bitmaps
Copyright (C) 1996 Michael J. Barillier, All Rights Reserved

*DEVELOPMENT VERSION* 1996 September 08


Michael J. Barillier
1378 Dartmouth Ct.
St. Charles MO 63303

e-mail: mjb@mo.net
Web: http://mo.net/~mjb/


---------------------------------------------------------------------------
Contents

  What this class does  . . . . . . . . . . . . . . . . . . . .     [intro]
  Installation  . . . . . . . . . . . . . . . . . . . . . . . .   [install]
  Usage   . . . . . . . . . . . . . . . . . . . . . . . . . . .     [usage]
  Creating pictures using REXX  . . . . . . . . . . . . . . . .  [rxcreate]
  Known bugs and limitations  . . . . . . . . . . . . . . . . .      [bugs]
  Support   . . . . . . . . . . . . . . . . . . . . . . . . . .   [support]
  Legal   . . . . . . . . . . . . . . . . . . . . . . . . . . .     [legal]


---------------------------------------------------------------------------
What this class does                                                [intro]

Suppose you have a cool bitmap that you'd like to have visible on your
desktop.  There are a number of good OS/2 utilities for viewing a bitmap,
but kicking off an app like PM View is overkill, as is the method I have
used in the past of creating a folder and setting the background bitmap.  I
wanted a way to click on an icon and have a bitmap of, say, Lake Tahoe in
Winter pop up (Lake Tahoe - yeah, that's it).  So having nothing better to
do I whipped up the WPPicture class.  Just drag a template to your desktop,
specify a bitmap filename, double-click the object and there's Lake Tahoe
(or your favorite image off alt.binaries.pictures.erotica, if you're so
inclined).

NOTE: This class is still under development! (See Known bugs and
limitations below.)  Apparently I don't have as much free time as I think.
While there are a couple of features that I haven't got around to yet,
WPPicture will still display images, and since it may be a while before I
get to those features I might as well release this module as it is.


---------------------------------------------------------------------------
Installation                                                      [install]

Run install.cmd (no kidding).  install.cmd is a REXX program that looks
for your system DLLs and help files and copies wppic.dll and wppic.hlp,
then registers the WPPicture class with the Workplace Shell.  As a caveat,
install scans drives starting from C: looking for config.sys (from which it
uses the LIBPATH statement to search for the system DLL subdirectory).  If
you have some weird multi-boot system with C: set up for DOS or Windoze
(which also have config.syses) and OS/2 on D: or some other drive, you may
have to hack on the install program a bit since install will grab the wrong
version of config.sys first.


---------------------------------------------------------------------------
Usage                                                               [usage]

This is a trivial WPS class.  This section can probably be skipped if
you're impatient ...

After running the install program, open the Templates folder.  There should
be a template named Picture there (sorry for the lame icon, but like I
said, I have less free time than I thought).  Drag a copy of the template
to a folder or the Desktop.  When the template is dropped, the picture's
Settings notebook will pop up.  Either type in the name of a bitmap file
(sorry, it's gotta be a .BMP - see Known bugs and limitations) or click on
the Find button to get a standard OS/2 file dialog.  When a file is
selected its image will show up in the Preview area.  You can then go to
the General page and change the name of the object if "Picture" doesn't
fire your rockets.

When the picture object is double-clicked, the image will appear (as if by
magic) on the Desktop.  The picture can be moved around using the mouse and
the left button (or the right if you've switched the buttons around,
naturally).  Double-clicking the left button will close the image, or the
Close item on the pop-up menu (click with the right button on the picture)
can be used.

As a side note, I usually use PMJPEG to resize an image and map the colors
to the system palette.  OS/2 only tries to map the bitmap's colors to the
closest matching system color, which usually makes your picture look like a
bad paint-by-numbers image.  PMJPEG (and PM View) uses color dithering
which ends up looking significantly better.


---------------------------------------------------------------------------
Creating pictures using REXX                                     [rxcreate]

You can use REXX and the SysCreateObject function to create Picture
objects.  The following example illustrates the steps required:

    /* Create a picture on the desktop */

    call rxfuncadd 'syscreateobject', 'rexxutil', 'syscreateobject'

    call syscreateobject 'WPPicture', 'My Picture', '<WP_DESKTOP>',
            'BMPFILENAME=c:\bitmaps\me.bmp'

BMPFILENAME is a WPPicture setup key value that tells the picture object
where to find the bitmap file.


---------------------------------------------------------------------------
Known bugs and limitations                                           [bugs]

THIS CLASS IS STILL UNDER CONSTRUCTION.  I've tried to remove all the bugs
I could find, but I'm sure there are a couple still lurking about.  If you
find a bug, drop me a note at mjb@mo.net.

o WPPicture chokes on some of the OS/2 system bitmaps.  I suspect that the
  header size values in these files are not correct, but that OS/2 is being
  a bit more forgiving than I am when it parses the file.

o Selecting Close from a picture's pop-up menu on the Task List (click the
  right button on the Task List entry of an open Picture) doesn't work.

o As for limitations, the biggest is that WPPicture only reads .BMP files
  (no JPEGs, GIFs, TIFFs or whatever).  I haven't found this to be much of
  a limitation since, as I mentioned above, I usually use PMJPEG to edit
  the image a bit, and it's just as easy to save the file as a BMP.

o Help is not completed.

o I want to add code to change the object's icon to a small version of the
  image.  Unfortunately there is no GpiBitmapToIcon system function, and my
  recent attempts to blast a copy of the image into a memory DC have been
  unsuccessful.  If anyone has a code sample that will convert an HBITMAP
  into an icon, I'd appreciate a look (and I'll send you an updated copy of
  WPPicture directly).


---------------------------------------------------------------------------
Support                                                           [support]

Support is limited, this being development code.  If a bug shows up I'll be
glad to make every attempt to fix it (I've been running this version on my
PC at home for a while and haven't seen any flakiness).  Send me a message
at mjb@mo.net with as much detailed information as you can regarding any
bug.  If you think the bug is image-related (such as incorrectly parsing a
valid bitmap file), send me a copy of the file as well (if possible).


---------------------------------------------------------------------------
Legal                                                               [legal]

This software may be freely distributed.  If you think that this is without
a doubt the coolest code ever conceived and feel the author deserves
compensation, do not hesitate to send whatever you believe is a fair and
just amount.  If, on the other hand, you think that this is without a doubt
the most useless piece of trash ever dumped on humanity, well, I don't
care.

DISCLAIMER OF WARRANTY

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, WHETHER
EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  SOME JURISDICTIONS DO
NOT ALLOW EXCLUSIONS OF AN IMPLIED WARRANTY, SO THIS DISCLAIMER MAY NOT
APPLY TO YOU AND YOU MAY HAVE OTHER LEGAL RIGHTS THAT VARY BY JURISDICTION.
