MNG4IE
A simple ActiveX control for displaying MNG animations in Internet Explorer

By Jason Summers  <jason1@pobox.com>
Version 1.0.4  26 Jan 2003
Web site: <http://pobox.com/~jason1/mng4ie/>


COPYRIGHT NOTICE

Copyright (c) 2002-2003 by Jason Summers <jason1@pobox.com>

THIS SOFTWARE IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, BUT WITHOUT 
ANY WARRANTY; WITHOUT EVEN THE IMPLIED WARRANTY OF MERCHANTABILITY OR 
FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND 
PERFORMANCE OF THE LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, 
YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL 
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE 
THIS SOFTWARE AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING 
ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 
USE OR INABILITY TO USE THIS SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF 
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 
PARTIES OR A FAILURE OF THIS SOFTWARE TO OPERATE WITH ANY OTHER PROGRAMS), 
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGES.

Permission is granted to anyone to use this software for any purpose, 
including commercial applications, and to alter it and redistribute it 
freely, subject to the following restrictions:

 1. The origin of this source code must not be misrepresented;
    you must not claim that you wrote the original software.
 2. Altered source versions must be plainly marked as such, and must not
    be misrepresented as being the original source.
 3. Altered binary versions must not be misrepresented as being the
    original.
 4. This Copyright notice may not be removed or altered from any source
    or altered source distribution, although you may add a Copyright
    notice for yourself for any code that you have written.


This software uses several third-party libraries (listed below), some of 
which are optional. If you redistribute MNG4IE, it is your responsibility 
to comply with the licenses of any libraries used.

This package includes a compiled executable ActiveX file, mng4ie.dll. This 
file includes code from lcms, which is distributed under the LGPL. To the 
best of my understanding, that basically means that anyone distributing that 
file must (1) make it possible for the recipient to modify the plug-in to 
use a new or modified version of lcms, and (2) make available the lcms 
source code. Requirement (1) is satisfied by the inclusion of the source 
code. For requirement (2), you can find out how to get the lcms source code
at the web site listed at the beginning of this document, if necessary.

---------

Based on libmng.
   Copyright (c) 2000-2002 Gerard Juyn (gerard@libmng.com)
   <http://www.libmng.com/>

Uses the zlib compression library.
   (C) 1995-2002 Jean-loup Gailly and Mark Adler

This software is based in part on the work of the Independent JPEG Group.
   Copyright (C) 1991-1998, Thomas G. Lane

Uses the lcms color management library by Mart Maria.
   (distributed under the GNU LESSER GENERAL PUBLIC LICENSE)

---------

SECURITY NOTICE

Although I've tried to write it carefully, MNG4IE has not had any sort of 
security audit. Due to the nature of ActiveX controls when used in web 
browsers, it is possible for certain types of bugs to exist which may 
allow remote web sites to take control of your computer or do harm to it 
by sending a carefully constructed data file to the plug-in. If you are 
paranoid about security, you may not wish to leave MNG4IE installed for an 
extended period of time.

---------

INTRODUCTION

MNG4IE is a free ActiveX control which displays the MNG image/animation 
format. It is specifically designed for use in Microsoft's Internet 
Explorer web browser. It configures itself to handle the following MIME 
types:

 video/x-mng
 video/mng
 image/x-jng
 image/jng

For best results, documents to be viewed should have the file extension 
".mng" or ".jng".

It can also display PNG image files, but it would cause too many problems 
for it to try to take over the PNG data type.

If you are configuring a web server to support MNG and JNG, the correct
MIME types to use are "video/x-mng" and "image/x-jng", since the MIME types
have not, as of this writing, been officially registered.


REQUIREMENTS

MNG4IE requires a 32-bit Windows operating system (Windows 95 or higher), 
and Internet Explorer 4.0 or higher. It requires that your IE security 
settings be set low enough to run ActiveX controls (the default settings 
are sufficiently low).


INSTALLATION

At the MNG4IE web site, there may be an auto-installation system set up to 
allow you to install MNG4IE via the web with just a few mouse clicks.

Alternatively, it is available in a ZIP file. You can install it by 
copying the mng4ie.dll file to some permanent location on your hard disk, 
and running the "regsvr32.exe" utility on it. For example, create a new 
folder at "C:\Program Files\MNG4IE", unzip the "mng4ie.dll", "reg.bat", 
and "unreg.bat" into that folder, then run reg.bat.


UNINSTALLATION - If you auto-installed via the web

Use Windows Explorer to browse to the "Downloaded Program Files" subfolder 
of your WINDOWS (or WINNT, or whatever) folder, right click on the 
"MNG4IE" item, and select "Remove" from the menu.


UNINSTALLATION - If you installed manually from the ZIP file

Run "regsvr32.exe /u mng4ie.dll", or run the unreg.bat file. Then, if you 
wish, delete the files you unzipped.


HOW TO USE (FOR END USERS)

Right-click on an MNG image as it is being displayed to get a menu with some 
of the usual features.

Right-click and choose "Properties" to display some internal information
about the image. Some images have embedded text information that will be
shown in the "Image comments" area. For technical reasons, some or all of
the comments may not be available until the animation completes a full loop.


HOW TO USE (FOR WEB DEVELOPERS)

First, if at all possible, configure your web server (not browser) to 
assign the MIME type "video/x-mng" to files that end in ".mng", and
assign type "image/x-jng" to files that end in ".jng".

One way to embed MNG files in a web is to use the nonstandard <embed> tag. 
For example:

  <embed src="foo.mng" width="100" height="100" type="video/x-mng">

Or instead, you can instead use IE's nonstandard version of the <object> 
tag. This example enforces the use of MNG4IE (rather than some other MNG 
viewer).

  <object width=100 height=100
    classid="CLSID:99715EC0-AAFD-11D6-A49D-4D4E47344945">
   <param name="src" value="foo.mng">
  </object>

You can also add a "codebase" attribute to offer auto-installation if
it is not already installed. See the MNG4IE web site for an example.
If you do this, please point to your own copy of the CAB file. If you
point people directly to mine, I'll break the link.

True transparency is not supported, although the background color of the
web page will be used when possible. If you want to use a different
background color in the transparent areas, you can you can supply a
specify a color by using the BGCOLOR attribute in the EMBED tag, i.e.:
  <embed src="foo.mng" bgcolor="#ff0000"  ...>

or in a PARAM tag:
  ... <param name="bgcolor" value="#ff0000"> ...

You cannot use color names like "red"; you must use the hexadecimal format 
as in the example.

An image can be made into a "hotlink" by including an HREF parameter and 
optionally a TARGET attribute. For example:

  <embed src="foo.mng" href="http://www.libpng.org/pub/mng/"
   target="_blank" ...>

[The "target" attribute doesn't seem to work quite right, however.]


MNG4IE also has (very limited) scripting capability. Currently it offers 
just one property and one method:

 * property "Version" (read-only), which returns an integer
     representing the version number
 * method "Animate()": call Animate(0) to freeze the animation,
     and Animate(1) to resume the animation.


HISTORY

v1.0.4
* Updated binary to libmng 1.0.5rc3.
* More-aggressively registers itself with Windows.

v1.0.3
* Updated binary to libmng 1.0.5b3.

v1.0.2
* Fixed some timer-related bugs that may have been causing crashes.
* Updated binary to libmng 1.0.5b2.

v1.0.1:
* Updated binary to libmng 1.0.5b1 and lcms 1.09b.
* Added support for the experimental (nonstandard) "Dynamic MNG" feature
  available in the new version of libmng.
* Partial transparency support. Supports solid background colors, but not
  background images.
* Rearranged the "About"/"Image Comments" dialog boxes.
* Source code is mostly Unicode-compatible.

v1.0.0:
* Original release.


SOURCE CODE

The C++ source code is included. 

This is an ATL ActiveX control, and requires ATL 3.0 (or higher?). I think 
that means it pretty much requires Microsoft Visual C++ 6.0 or higher. For 
example, it will not compile with ATL 2.x, which is what is included with 
MSVC++ 5. It's possible that it could be compiled by other C++ compilers, 
but I expect that will be difficult.

To compile it, you'll also need:

- libmng MNG library <http://www.libmng.com/>. I've only tested it with 
libmng 1.0.5, but it's probably also compatible with other versions, maybe 
with minor changes.

libmng in turn uses some other libraries:

    - zlib compression library

    - IJG JPEG library

    - [optional] lcms "Little Color Management System" library. 

If you include lcms, turn on the MNG_FULL_CMS option in libmng_conf.h (or 
define MNG_FULL_CMS in your project settings) before compiling. Note that 
lcms is distributed under the LGPL -- be sure you understand the 
implications of that before distributing any resulting executable files.

If you don't include lcms, comment out the "#define MNG4IE_CMS" line in 
mng4iectl.cpp.

I also recommend turning on the MNG_ERROR_TELLTALE and 
MNG_SUPPORT_DYNAMICMNG options in libmng_conf.h or your libmng project 
settings.

