=========================================================
WADDisplay ActiveX Control
Version 1.0, August 22nd, 2001
(c) 2001 Ty Matthews (ty@wwa.com) & Neal White III (neal_white_iii@hotmail.com)

http://www.telefragged.com/wally

Version History
---------------
1.0 : Initial public release
=========================================================


Overview
--------
WADDisplay is an ActiveX control which allows the developer to load in a WAD file and display images contained within the WAD file, by specifying the name of a particular image.  Due to numerous requests to provide code to handle this sort of thing, we decided to just build an OCX which accomplishes the task with little effort on the part of the developer.  The image selected is drawn completely inside the rectangle you give it for the control, with no border or anything else in between.  The image will be stretched to fit the size you give it.  For non-square images, the image will retain its aspect ratio and be centered either on the horizontal or vertical axis, depending on whether the image is taller than it is wide (IE 64x128) or wider than it is tall (IE 128x64.)  For images that meet this criteria, the void background will be painted in the color of your choosing.


Licensing
---------
This control is freeware to anyone who uses it as part of another freeware application.  If you are developing a shareware or commercial application and you wish to use this control, you must contact Ty and Neal for licensing details.


Installation
------------
The OCX file must be registered first on any machine that runs code which makes use of the control.  IE, if you've developed an app that you want to release on the world, the OCX must go along with it and be registered on the client before your code will work.  We're giving you the raw OCX without any install program so that you may write one yourself and place the file wherever you choose.  We recommend installing the OCX in C:\Windows\System just so people are less likely to delete it or move it.  Use REGSVR32 to take care of the COM DLL registration.


ProgID
------
The official COM prog ID for this control is "WADDisplay.WADDisplayCtrl.1"


WADDisplay Properties
---------------------
The following properties can be set on and/or get from the object.  Property name is denoted by brackets: [Property]  Type is denoted by braces: {string}

[WADFile] {string}  Sets/Gets the full path to the WAD file you want the object to use.  You must set this property to a valid WAD file before anything can be displayed.

[Gamma] {double}  Sets/Gets the gamma value for use in displaying the image.  Since many game images are fairly dark when viewing, this property allows you to brighten the display without changing the look of the actual image.  A value of 1.0 means no adjustment.  Anything below 1.0 makes it darker.  Anything above 1.0 is brighter.  1.25 is a good value for game textures, and so it is the default.

[Version] {double}  Gets the version of the currently-installed control.  It might be possible that this OCX was already installed on the user's machine, from some other program.  Wally doesn't make use of this control, but since it is now publicly available, someone else might have installed it.  If you don't forcefully replace any existing version when you install this OCX, you should check to make sure the version matches the minimum version your program will be able to work with.  IE, if you're developing your tool with version 1.5 of this OCX, and the client only has version 1.0, you should probably consider that an error as some things may not work as you're expecting.  This returns a value that directly matches the version number detailed in the header of this document.

[BackColor] {long}  Sets/Gets the background color that is displayed when the image is not perfectly square.  Since the control's display maintains aspect ratio, for these non-square images we have to fill in the background color with something.  This is a stock property, so you can set it using VB's Property Page.

[SelectedImage] {string}  Sets/Gets the current image to be displayed.  The name of the image is not case-sensitive.  If you specify a name that does not exist in the WAD file, the image that was already in the display position remains there.  Get this value to find out which image is currently being displayed.

[Error] {string}  Gets the last error message of the control.  If you specify an invalid WAD file, or the WAD file is corrupt, or the specified image could not be found, or any number of potential problems, this property will be updated to reflect the message.


WADDisplay Methods
------------------
The following methods can be called against the object.  Method name is denoted by brackets: [Method]  Parameters are denoted in parenthesis: (Parameter1 As string, Parameter2 As string)  Return value is denoted by braces: {string}

[GetFirstImage] () {string}   Returns a string representing the name of the first image in the WAD file.  The order that these images are stored in the object is indeterminant.  You must call this method first before you can call GetNextImage.  If there are no images in the WAD file, or the file failed to load properly, this will return an empty string.

[GetNextImage] () {string}  Returns the next string in the WAD file.  In combination with GetFirstImage(), this method will allow you to iterate through all of the images contained in the WAD file for display in a list box or other usage.  When there are no images in the WAD file, the string returned is empty.


Feedback/Comments/Suggestions
-----------------------------
If you have any suggestions for improving the control, or you've run into a bug or a problem, please send us a note and we'll take a look at it.




