@database "wb"

@Node Main "wb.doc"
@toc "Includes_&_Autodocs/Main"
    @{" AddAppIconA() " Link "AddAppIconA()"}
    @{" AddAppMenuItemA() " Link "AddAppMenuItemA()"}
    @{" AddAppWindowA() " Link "AddAppWindowA()"}
    @{" RemoveAppIcon() " Link "RemoveAppIcon()"}
    @{" RemoveAppMenuItem() " Link "RemoveAppMenuItem()"}
    @{" RemoveAppWindow() " Link "RemoveAppWindow()"}
    @{" WBInfo() " Link "WBInfo()"}
@EndNode

@Node "AddAppIconA()" "workbench.library/AddAppIconA"

@{b}   NAME@{ub}
	AddAppIconA - add an icon to workbench's list of appicons.       (V36)

@{b}   SYNOPSIS@{ub}
	AppIcon = AddAppIconA(id, userdata, text, msgport,
	   D0		      D0     D1      A0     A1

					lock, diskobj, taglist)
					 A2      A3      A4

	struct AppIcon *AddAppIconA(ULONG, ULONG, char *,
		struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *, struct @{"FileLock" Link "includes/dos/dosextens.h/Main" 455} *, struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *,
		struct @{"TagItem" Link "includes/utility/tagitem.h/Main" 31} *);

	Alternate, varargs version:
	struct AppIcon *AddAppIcon(ULONG, ULONG, char *,
			struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *, struct @{"FileLock" Link "includes/dos/dosextens.h/Main" 455} *,
			struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *,
			tag1, data1,
			tag2, data2,
			...
			TAG_END );

@{b}   FUNCTION@{ub}
	Attempt to add an icon to workbench's list of appicons.  If
	successful, the icon is displayed on the workbench (the same
	place disk icons are displayed).
	This call is provided to allow applications to be notified when
	a graphical object (non neccessarely associated with a file)
	gets 'manipulated'. (explained later).
	The notification consists of an @{"AppMessage" Link "includes/workbench/workbench.h/Main" 108} (found in workbench.h/i)
	of type 'MTYPE_APPICON' arriving at the message port you specified.
	The types of 'manipulation' that can occur are:
	1. Double-clicking on the icon.  am_NumArgs will be zero and
	   am_ArgList will be NULL.
	2. Dropping an icon or icons on your appicon.  am_NumArgs will
          be the number of icons dropped on your app icon plus one.
          am_ArgList will be an array of ptrs to @{"WBArg" Link "includes/workbench/startup.h/Main" 33} structures.
          Refer to the 'WBStartup Message' section of the RKM for more info.
	3. Dropping your appicon on another icon.  NOT SUPPORTED.

@{b}   INPUTS@{ub}
	id - this variable is strictly for your own use and is ignored by
	     workbench.  Typical uses in C are in switch and case statements,
	     and in assembly language table lookup.
	userdata - this variable is strictly for your own use and is ignored
		   by workbench.
	text - name of icon (char *)
	lock - NULL    (Currently unused)
	msgport - pointer to message port workbench will use to send you an
		  @{"AppMessage" Link "includes/workbench/workbench.h/Main" 108} message of type 'MTYPE_APPICON' when your icon
		  gets 'manipulated' (explained above).
	diskobj - pointer to a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} structure filled in as follows:
	    do_Magic - NULL
	    do_Version - NULL
	    do_Gadget - a gadget structure filled in as follows:
		NextGadget - NULL
		LeftEdge - NULL
		TopEdge - NULL
		Width - width of icon hit-box
		Height - height of icon hit-box
		Flags - NULL or GADGHIMAGE
		Activation - NULL
		GadgetType - NULL
		GadgetRender - pointer to @{"Image" Link "includes/intuition/intuition.h/Main" 705} structure filled in as follows:
		    LeftEdge - NULL
		    TopEdge - NULL
		    Width - width of image (must be <= Width of hit box)
		    Height - height of image (must be <= Height of hit box)
		    Depth - # of bit-planes in image
		    ImageData - pointer to actual word aligned bits (CHIP MEM)
		    PlanePick - Plane mask ((1 << depth) - 1)
		    PlaneOnOff - 0
		    NextImage - NULL
		SelectRender - pointer to alternate @{"Image" Link "includes/intuition/intuition.h/Main" 705} struct or NULL
		GadgetText - NULL
		MutualExclude - NULL
		SpecialInfo - NULL
		GadgetID - NULL
		UserData - NULL
	    do_Type - NULL
	    do_DefaultTool - NULL
	    do_ToolTypes - NULL
	    do_CurrentX - NO_ICON_POSITION (recommended)
	    do_CurrentY - NO_ICON_POSITION (recommended)
	    do_DrawerData - NULL
	    do_ToolWindow - NULL
	    do_StackSize - NULL

	(an easy way to create one of these (a DiskObject) is to create an icon
        with the V2.0 icon editor and save it out.  Your application can then
        call @{"GetDiskObject" Link "icon/GetDiskObject()"} on it and pass that to AddAppIcon.)

	taglist - ptr to a list of tag items.  Must be NULL for V2.0.

@{b}   RESULTS@{ub}
	AppIcon - a pointer to an appicon structure which you pass to
		  @{"RemoveAppIcon" Link "wb/RemoveAppIcon()"} when you want to remove the icon
		  from workbench's list of appicons.  NULL
		  if workbench was unable to add your icon; typically
		  happens when workbench is not running or under low
		  memory conditions.

@{b}   EXAMPLE@{ub}
	You could design a print-spooler icon and add it to the workbench.
	Any file dropped on the print spooler would be printed.  If the
	user double-clicked (opened) your printer-spooler icon, you could
	open a window showing the status of the print spool, allow changes
	to print priorities, allow deletions, etc.  If you registered this
	window as an 'appwindow' (explained in workbench.library AddAppWindow)
	files could also be dropped in the window and added to the spool.

@{b}   SEE ALSO@{ub}
	@{"RemoveAppIcon()" Link "RemoveAppIcon()"}

@{b}   BUGS@{ub}
	Currently @{"Info" Link "dos/Info()"} cannot be obtained on appicons.

@EndNode

@Node "AddAppMenuItemA()" "workbench.library/AddAppMenuItemA"

@{b}   NAME@{ub}
	AddAppMenuItemA - add a menuitem to workbench's list             (V36)
                         of appmenuitems.

@{b}   SYNOPSIS@{ub}
	@{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} = AddAppMenuItemA(id, userdata, text, msgport, taglist)
	D0			      D0     D1      A0     A1       A2

	struct @{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} *AddAppMenuItemA(ULONG, ULONG, char *,
						struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *,
						struct @{"TagItem" Link "includes/utility/tagitem.h/Main" 31} *);

	Alternate, varargs version:
	struct @{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} *AddAppMenuItem(ULONG, ULONG, char *,
					struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *,
					tag1, data1,
					tag2, data2,
					...
					TAG_END );

@{b}   FUNCTION@{ub}
	Attempt to add the text as a menuitem to workbench's list
	of appmenuitems (the 'Tools' menu strip).

@{b}   INPUTS@{ub}
	id - this variable is strictly for your own use and is ignored by
	     workbench.  Typical uses in C are in switch and case statements,
	     and in assembly language table lookup.
	userdata - this variable is strictly for your own use and is ignored
		   by workbench.
	text - text for the menuitem (char *)
	msgport - pointer to message port workbench will use to send you an
		  @{"AppMessage" Link "includes/workbench/workbench.h/Main" 108} message of type 'MTYPE_APPMENUITEM' when your
		  menuitem gets selected.
	taglist - ptr to a list of tag items.  Must be NULL for V2.0.

@{b}   RESULTS@{ub}
	@{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} - a pointer to an appmenuitem structure which you pass to
		      @{"RemoveAppMenuItem" Link "wb/RemoveAppMenuItem()"} when you want to remove the menuitem
		      from workbench's list of appmenuitems.  NULL if
		      workbench was unable to add your menuitem; typically
		      happens when workbench is not running or under low
		      memory conditions.

@{b}   SEE ALSO@{ub}
	@{"RemoveAppMenuItem()" Link "RemoveAppMenuItem()"}

@{b}   BUGS@{ub}
	Currently does not limit the system to 63 menu items...
	Any menu items after the 63rd will not be selectable.

@EndNode

@Node "AddAppWindowA()" "workbench.library/AddAppWindowA"

@{b}   NAME@{ub}
	AddAppWindowA - add a window to workbench's list of appwindows.  (V36)

@{b}   SYNOPSIS@{ub}
	@{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} = AddAppWindowA(id, userdata, window, msgport, taglist)
	D0			  D0     D1       A0      A1       A2

	struct @{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} *AddAppWindowA(ULONG, ULONG, struct @{"Window" Link "includes/intuition/intuition.h/Main" 909} *,
					struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *, struct @{"TagItem" Link "includes/utility/tagitem.h/Main" 31} *);

	Alternate, varargs version:
	struct @{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} *AddAppWindow(ULONG, ULONG, struct @{"Window" Link "includes/intuition/intuition.h/Main" 909} *,
					struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *
					tag1, data1,
					tag2, data2,
					...
					TAG_END );

@{b}   FUNCTION@{ub}
	Attempt to add the window to workbench's list of appwindows.
	Normally non-workbench windows (those not opened by workbench)
	cannot have icons dropped in them.  This call is provided to
	allow applications to be notified when an icon or icons get
	dropped inside a window that they have registered with workbench.
	The notification consists of an @{"AppMessage" Link "includes/workbench/workbench.h/Main" 108} (found in workbench.h/i)
	of type 'MTYPE_APPWINDOW' arriving at the message port you specified.
	What you do with the list of icons (pointed to by am_ArgList) is
	up to you, but generally you would want to call @{"GetDiskObjectNew" Link "icon/GetDiskObjectNew()"} on
	them.

@{b}   INPUTS@{ub}
	id - this variable is strictly for your own use and is ignored by
	     workbench.  Typical uses in C are in switch and case statements,
	     and in assembly language table lookup.
	userdata - this variable is strictly for your own use and is ignored
		   by workbench.
	window - pointer to window to add.
	msgport - pointer to message port workbench will use to send you an
		  @{"AppMessage" Link "includes/workbench/workbench.h/Main" 108} message of type 'MTYPE_APPWINDOW' when your
		  window gets an icon or icons dropped in it.
	taglist - ptr to a list of tag items.  Must be NULL for V2.0.

@{b}   RESULTS@{ub}
	@{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} - a pointer to an appwindow structure which you pass to
		    @{"RemoveAppWindow" Link "wb/RemoveAppWindow()"} when you want to remove the window
		    from workbench's list of appwindows.  NULL
		    if workbench was unable to add your window; typically
		    happens when workbench is not running or under low
		    memory conditions.

@{b}   SEE ALSO@{ub}
	@{"RemoveAppWindow()" Link "RemoveAppWindow()"}

@{b}   NOTES@{ub}
       The V2.0 icon editor is an example of an app window.  Note that app
       window applications generally want to call @{"GetDiskObjectNew" Link "icon/GetDiskObjectNew()"}
       (as opposed to GetDiskObject) to get the disk object for the icon
       dropped in the window.

@{b}   BUGS@{ub}
	None

@EndNode

@Node "RemoveAppIcon()" "workbench.library/RemoveAppIcon"

@{b}   NAME@{ub}
	RemoveAppIcon - remove an icon from workbench's list            (V36)
                         of appicons.

@{b}   SYNOPSIS@{ub}
	error = RemoveAppIcon(AppIcon)
         D0                     A0
	@{"BOOL" Link "includes/exec/types.h/Main" 68} RemoveAppIcon(struct AppIcon *);

@{b}   FUNCTION@{ub}
	Attempt to remove an appicon from workbench's list of appicons.

@{b}   INPUTS@{ub}
	AppIcon - pointer to an AppIcon structure returned by AddAppIcon.

@{b}   RESULTS@{ub}
	error - Currently always TRUE...

@{b}   NOTES@{ub}
	As with anything that deals with async operation, you will need to
	do a final check for messages on your App message port for messages
	that may have come in between the last time you checked and the
	call to removed the App.

@{b}   SEE ALSO@{ub}
	@{"AddAppIconA()" Link "AddAppIconA()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "RemoveAppMenuItem()" "workbench.library/RemoveAppMenuItem"

@{b}   NAME@{ub}
	RemoveAppMenuItem - remove a menuitem from workbench's list      (V36)
			    of appmenuitems.

@{b}   SYNOPSIS@{ub}
	error = RemoveAppMenuItem(AppMenuItem)
         D0                            A0
	@{"BOOL" Link "includes/exec/types.h/Main" 68} RemoveAppMenuItem(struct @{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} *);

@{b}   FUNCTION@{ub}
	Attempt to remove an appmenuitem from workbench's list
	of appmenuitems.

@{b}   INPUTS@{ub}
	@{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} - pointer to an @{"AppMenuItem" Link "includes/workbench/workbench.h/Main" 136} structure returned by
		      AddAppMenuItem.

@{b}   RESULTS@{ub}
	error - Currently always TRUE...

@{b}   NOTES@{ub}
	As with anything that deals with async operation, you will need to
	do a final check for messages on your App message port for messages
	that may have come in between the last time you checked and the
	call to removed the App.

@{b}   SEE ALSO@{ub}
	@{"AddAppMenuItemA()" Link "AddAppMenuItemA()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "RemoveAppWindow()" "workbench.library/RemoveAppWindow"

@{b}   NAME@{ub}
	RemoveAppWindow - remove a window from workbench's list         (V36)
                          of appwindows.

@{b}   SYNOPSIS@{ub}
	error = RemoveAppWindow(AppWindow)
         D0                       A0
	@{"BOOL" Link "includes/exec/types.h/Main" 68} RemoveAppWindow(struct @{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} *);

@{b}   FUNCTION@{ub}
	Attempt to remove an appwindow from workbench's list of appwindows.

@{b}   INPUTS@{ub}
	@{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} - pointer to an @{"AppWindow" Link "includes/workbench/workbench.h/Main" 134} structure returned by
		    AddAppWindow.

@{b}   RESULTS@{ub}
	error - Currently always TRUE...

@{b}   NOTES@{ub}
	As with anything that deals with async operation, you will need to
	do a final check for messages on your App message port for messages
	that may have come in between the last time you checked and the
	call to removed the App.

@{b}   SEE ALSO@{ub}
	@{"AddAppWindowA()" Link "AddAppWindowA()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "WBInfo()" "workbench.library/WBInfo"

@{b}   NAME@{ub}
	WBInfo - Bring up the Information requrester                     (V39)

@{b}   SYNOPSIS@{ub}
	worked = WBInfo(lock, name, screen)
	d0              a0    a1    a2

	ULONG WBInfo(BPTR, @{"STRPTR" Link "includes/exec/types.h/Main" 53}, struct @{"Screen" Link "includes/intuition/screens.h/Main" 132} *);

@{b}   FUNCTION@{ub}
	This is the LVO that Workbench calls to bring up the Icon Information
	requester.  External applications may also call this requester.
	In addition, if someone were to wish to replace this requester
	with another one, they could do so via a @{"SetFunction" Link "exec/SetFunction()"}.

@{b}   INPUTS@{ub}
	lock   - A lock on the parent directory
	name   - The name of the icon contained within above directory
	screen - A screen pointer on which the requester is to show up

@{b}   RESULTS@{ub}
	worked - Returns TRUE if the requester came up, FALSE if it did not.

@{b}   NOTE@{ub}
	Note that this LVO may be called many times by different tasks
	before other calls return.  Thus, the code must be 100% re-entrant.

@{b}   SEE ALSO@{ub}
	icon.library

@{b}   BUGS@{ub}

@EndNode

