iconify()		Amiga Programmer's Manual		iconify()

NAME
	iconify -- Create an icon on the screen that can be dragged
		   around.

SYNOPSIS
	#include "iconify.h"
	int		success;

	success = 
	 iconify (LeftEdge, TopEdge, Width, Height, Screen, ptr, Type);
	UWORD		*LeftEdge, *TopEdge;
	UWORD		Width, Height;
	struct Screen	*Screen;
	APTR		ptr;
	int		Type;

DESCRIPTION
	Iconify() is a subroutine that creates an icon on the Amiga screen
	that can be subsequently dragged around, and double-clicked on.

	Iconify() creates an icon at screen location (*LeftEdge, *TopEdge)
	and of size (Width, Height), in pixels.  The icon is created on
	the screen specified.  If Screen is NULL, the icon will be created
	on the WorkBench screen.

	The Type variable tells iconify() how to make the icon.  Based on
	the value contained in Type, ptr may be interpreted in one of three
	different ways:

	ICON_IMAGE:
		ptr points to an initialized structure of type Image
		(intuition.h).  The image contained in the structure will
		be used as the icon image.

	ICON_BORDER:
		ptr points to an initialized structure of type Border
		(intuition.h).  The drawing instructions contained in the
		border structure will be used to render the icon.

	ICON_FUNCTION:
		[This is by far the most interesting one.]  ptr points to
		a function that will be called by iconify() N times a
		second (where N is a compile-time constant).  The format
		of the call is:

		(* ((void (*)()) ptr)) (win, val);
		struct Window	*win;
		WORD		val;

		When the icon is first created, your function will be
		called with val equal to one (non-zero).  This should be
		used as a flag to your function to call any initialization
		code it may need (such as caching the icon size, setting
		draw modes, etc.).  On every subsequent call, val will be
		equal to zero.

		win points to the window which is your icon (the icon is in
		fact a window-sized drag gadget).  This may be used for
		rendering purposes (animated icons, for example).

	After the icon is created, iconify() will wait until the icon has
	been double-clicked on.  If the icon is of type ICON_FUNCTION,
	iconify() will also call the supplied function N times a second
	while waiting for the double-click.
	
	When the icon is double-clicked, iconify() will update the values
	pointed to by LeftEdge and TopEdge.  This is so that, in subsequent
	invocations of iconify(), the icon will be where the user last left
	it.  Thus, it is the responsibility of the calling program to
	maintain these values.

	After updating these values, iconify() will remove the icon from
	the screen, and return to the caller with a non-zero value.  If any
	of iconify()'s internal operations fail, a zero value will be
	returned.  It is strongly suggested that this be checked for by
	the calling program.

VIEW TO OUTSIDE PROGRAMS
	Icons created with iconify() will look like small windows (this is
	largely due to the fact that they are small windows).  Outside
	programs may wish to differentiate between 'real' windows, and
	objects created with iconify().
	
	To this end, iconify() writes the 32-bit constant 0x49434f4e
	(which just happens to be the word 'ICON' in ASCII) into the
	window's UserData field.  Outside programs that are manipulating
	windows can check for this so they can avoid touching icons (or so
	that they can specifically find icons if they want).

AUTHOR
	Leo L. Schwab
	61 Martens Blvd.
	San Rafael, CA   94901-5028
	{ihnp4!ptsfa,hplabs}!{well!unicom}!ewhac

SEE ALSO
	Amiga Rom Kernel Manual
	Intuition: The Amiga User Interface

BUGS
	There are NO bugs in MY code.  However, there may be any number
	of undesireable features (but I doubt it).