wb.library Reference

Comprehensive function reference for wb.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/wb).

This page documents 16 functions of wb.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

AddAppIconA()

AddAppIconA - add an icon to Workbench's list of AppIcons. (V36)

Synopsis

AppIcon = AddAppIconA(id, userdata, text, msgport, D0 D0 D1 A0 A1

lock, diskobj, taglist) A2 A3 A4

struct AppIcon*AddAppIconA(ULONG, ULONG, char *, MsgPort*, BPTR,struct DiskObject*, TagItem*);

Alternate, varargs version: struct AppIcon*AddAppIcon(ULONG, ULONG, char *, MsgPort*, BPTR, struct DiskObject*, tag1, data1, tag2, data2, ... TAG_END );

Function

Attempt to add an icon to Workbench's list of AppIcons. If successful, the icon is displayed on the Workbench backdrop (the same place disk icons are displayed).

This call is provided to allow applications to be notified when
a graphical object (not neccessarely associated with a file)
gets 'manipulated'.

The notification consists of an AppMessage (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 AppIcon plus one.
   am_ArgList will be an array of pointers to WBArg structures.
   Refer to the 'WBStartup Message' section of the RKM for more info.
3. Dropping your AppIcon on another icon.  NOT SUPPORTED.
4. Invoking an "Icons"  item with your icon selected. (V44)
   You have to tell Workbench which menu items your icon
   responds to using the tag item list you provide to AddAppIconA().
   When one of the supported menu items is invoked, you
   will receive an AppMessage with the am_Class entry set to
   a value out of AMCLASSICON_Open..AMCLASSICON_EmptyTrash,
   corresponding to the menu item used.

Inputs

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 message of type 'MTYPE_APPICON' when your icon gets 'manipulated' (explained above). diskobj - pointer to a DiskObject 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 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 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 on it and pass that to AddAppIcon.)

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

Results

AppIcon - a pointer to an AppIcon structure which you pass to 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.

Notes

For this function call to succeed, Workbench must be open. This means that the LoadWB command was executed and the Workbench screen has been opened.

Example

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.

Bugs

In workbench.library versions 36 through 40 Info cannot be obtained on appicons.

See also

RemoveAppIcon(), WorkbenchControlA(), DrawIconStateA()

AddAppMenuItemA()

AddAppMenuItemA - add a menu item to Workbench's list (V36) of AppMenuItems.

Synopsis

AppMenuItem = AddAppMenuItemA(id, userdata, text, msgport, taglist) D0 D0 D1 A0 A1 A2

struct AppMenuItem*AddAppMenuItemA(ULONG, ULONG, char *, MsgPort*, TagItem*);

Alternate, varargs version: struct AppMenuItem*AddAppMenuItem(ULONG, ULONG, char *, MsgPort*, tag1, data1, tag2, data2, ... TAG_END );

Function

Attempt to add the text as a menu item to Workbench's list of AppMenuItems (the 'Tools' menu strip).

Inputs

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 menu item (char *); starting with V44, any menu label consisting entirely of '-', '_' or '~' characters will result in a separator bar to be added in place of a textual item. msgport - pointer to message port Workbench will use to send you an AppMessage message of type 'MTYPE_APPMENUITEM' when your menuitem gets selected. taglist - ptr to a list of tag items. Must be NULL for V2.0.

Results

AppMenuItem - a pointer to an appmenuitem structure which you pass to RemoveAppMenuItem when you want to remove the menuitem from Workbench's list of AppMenuItems. NULL if workbench was unable to add your menu item; typically happens when Workbench is not running or under low memory conditions.

          Starting with V44 NULL will be returned if you attempt to
          add an AppMenu item to a menu which already contains 63
          menu items.

Notes

For this function call to succeed, Workbench must be open. This means that the LoadWB command was executed and the Workbench screen has been opened.

You can add only a maximum of 62 menu items to the "Tools" menu.
Only a maximum of 31 sub items can be added to a menu item.

When you add a new menu item which sub items should be attached
to, the new menu item will not appear until after the first sub
item has been attached. The same is true when adding new menu
entries to the Workbench menu strip; titles will not appear
until you add the first menu item.

You can add only a maximum of 27 menu entries to the Workbench
menu strip. Only a maximum of 63 menu items can be added to
a menu entry.

Example

Here is how you create a menu item with two sub items attached:

struct MsgPort * port;
struct AppMenuItem * item;
struct AppMenuItem * sub1;
struct AppMenuItem * sub2;
ULONG key;

\* IMPORTANT: you *must* initialize the key to zero
 *            for backwards compatibility!
 *\
key = 0;
item = AddAppMenuItem(0,0,"AppMenu item with two sub items",port,
    WBAPPMENUA_GetKey,&key,
TAG_DONE);

\* IMPORTANT: always check for the key value to be non-zero! *\
if(key != 0 && item != NULL)
{
    sub1 = AddAppMenuItem(0,0,"Sub item #1",port,
        WBAPPMENUA_UseKey,key,
    TAG_DONE);

    sub2 = AddAppMenuItem(0,0,"Sub item #2",port,
        WBAPPMENUA_UseKey,key,
    TAG_DONE);

    \* ... do something useful with the menus ... *\

    RemoveAppMenuItem(sub1);
    RemoveAppMenuItem(sub2);
}

RemoveAppMenuItem(item);

Bugs

workbench.library V37 through V40 does not limit the number of menu items to 63. Any menu items after the 63rd will not be selectable. This bug was fixed in V44.

See also

RemoveAppMenuItem()

AddAppWindowA()

AddAppWindowA - add a window to Workbench's list of AppWindows. (V36)

Synopsis

AppWindow = AddAppWindowA(id, userdata, window, msgport, taglist) D0 D0 D1 A0 A1 A2

struct AppWindow*AddAppWindowA(ULONG, ULONG,Window*, MsgPort*,TagItem*);

Alternate, varargs version: struct AppWindow*AddAppWindow(ULONG, ULONG,Window*, MsgPort* tag1, data1, tag2, data2, ... TAG_END );

Function

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 (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 on them.

Inputs

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 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.

Results

AppWindow - a pointer to an AppWindow structure which you pass to 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.

Notes

The V2.0 icon editor is an example of an AppWindow. Note that app window applications generally want to call GetDiskObjectNew (as opposed to GetDiskObject) to get the disk object for the icon dropped in the window.

For this function call to succeed, Workbench must be open. This
means that the LoadWB command was executed and the Workbench
screen has been opened.

When removing an AppWindow, all its drop zones will be automatically
removed.

See also

AddAppWindowDropZoneA(), RemoveAppWindow()

AddAppWindowDropZoneA()

AddAppWindowDropZoneA -- Designate an AppWindow area as suitable for dropping icons on. (V44)

Synopsis

dropZone = AddAppWindowDropZoneA(appWindow,id,userData,tags) D0 A0 D0 D1 A1

struct AppWindowDropZone* AddAppWindowDropZoneA(struct AppWindow*aw, ULONG id,ULONG userData, TagItem* tags);

dropZone = AddAppWindowDropZone(appWindow,id,userData,zone,...)

struct AppWindowDropZone* AddAppWindowDropZone(struct AppWindow*aw, ULONG id,ULONG userData,...);

Function

Once it is created, Workbench will allow the user to drop an icon anywhere inside an AppWindow, regardless of whether the icon was dropped on an area designated for dropping icons on or not. With AddAppWindowDropZoneA() you can tell Workbench which AppWindow areas are suitable for dropping icons on.

Inputs

aw -- An AppWindow data structure, as returned by workbench.library/AddAppWindowA. 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. Later, when an icon is dropped on the designated area, the AppMessage sent to your port will have the am_ID member set to this value. userData -- this variable is strictly for your own use and is ignored by Workbench. Later, when an icon is dropped on the designated area, the AppMessage sent to your port will have the am_UserData member set to this value. tags -- List of attributes to control the position and size of the drop zone.

Results

dropZone -- A newly created drop zone identifier, or NULL if it could not be created; use dos.library/IoErr to find out what caused it to fail.

Notes

Once an AppWindow has a drop zone installed, Workbench will send a new type of AppMessage to your port if icons are dropped on a drop zone. Instead of AMTYPE_APPWINDOW type messages you will receive AMTYPE_APPWINDOWZONE messages. In fact, you will no longer hear any AMTYPE_APPWINDOW type messages since Workbench will allow users to drop icons only on drop zones. Be prepared to handle this.

Adding a drop zone to an AppWindow does not guarantee that only
AMTYPE_APPWINDOWZONE type messages will arrive at your message
port. In fact, the user may be able to drop an icon on the window
before the first drop zone is installed. Be prepared to handle
this.

Workbench checks drop zones in the order in which they were added
to the AppWindow. Thus, if two zones overlap, the zone that was
added first will be reported as hit.

An AppWindow starts out with its entire area available for dropping
icons on. Thus, you may receive AppMessages for icons dropped upon
your AppWindow before you have added the first drop zone to it.
Be prepared to handle this.

Drop zones must be created with a position and a size. If you omit
either one, this routine will fail.

When an icon is dropped on a drop zone, the AppMessage am_MouseX and
am_MouseY members will be relative to the window top left corner;
they WILL NOT be relative to the left/top edge of the drop zone.

See also

IoErr(), AddAppWindowA()

ChangeWorkbenchSelectionA()

ChangeWorkbenchSelectionA -- Change the selection states of icons displayed by Workbench. (V44)

Synopsis

success = ChangeWorkbenchSelectionA(name,hook,tags) D0 A0 A1 A2

BOOL ChangeWorkbenchSelectionA(STRPTR name,Hook*hook, TagItem*tags);

success = ChangeWorkbenchSelection(name,hook,...);

BOOL ChangeWorkbenchSelection(STRPTR name,Hook*hook,...);

Function

The icons displayed inside each Workbench window can be in selected or in unselected state. This routine allows you to change this state for every icon found in a particular window.

Inputs

name -- Name of the drawer whose icons should be submitted to the callback hook for testing; pass NULL as the name to have the icons in the Workbench backdrop (where disks and AppIcons live) passed through the hook. Note that the drawer whose icons you want to change must be open before you can make any changes.

hook -- Hook to be invoked for each icon in the window.

    The hook code will be invoked with the following parameters

    action = hookFunc(hook,reserved,ism)
       D0                A0     A2    A1

    ULONG hookFunc(struct Hook *hook,APTR reserved,
                   struct IconSelectMsg *ism);

    The reserved parameter will be set to NULL (V44).

    The IconSelectMsg contents are as follows:

        ism_Length
            Size of the IconSelectMsg data structure (in bytes).
            Since this message may need to grow in the future,
            always compare this value against the message size
            you expect. For V44, ism_Length is guaranteed to
            contain a value of 36. Expect this value to become
            larger in the future.

        ism_Drawer
            A lock on the drawer the object in question resides
            in. This may be NULL for the Workbench backdrop (where
            disks and AppIcons live).

        ism_Name
            Name of the object in question; please note that for
            disk icons the name does not end with a colon character
            (":").

        ism_Type
            This is one of WBDISK, WBDRAWER, WBTOOL, WBPROJECT,
            WBGARBAGE, WBDEVICE, WBKICK or WBAPPICON.

        ism_Selected
            TRUE if the object in question is currently selected,
            FALSE otherwise.

        ism_Tags
            The list of tag items passed to ChangeWorkbenchSelectionA().

        ism_DrawerWindow
            If the object in question is a drawer or disk and its
            associated window is currently open, then you will find
            a pointer to it here.

        ism_ParentWindow
            This is a pointer to the window the object resides in.

        ism_Left
        ism_Top
        ism_Width
        ism_Height
            These denote the position and size of the object in
            question, relative to the top left edge of the window
            it resides in.

    With the exception of the ism_Left and ism_Top members, the
    IconSelectMsg is read-only. The ism_Left/ism_Top members can
    be used to change the position of the icon.

    You hook code must return one of the following values:

        ISMACTION_Unselect
            Unselect the icon

        ISMACTION_Select
            Select the icon

        ISMACTION_Ignore
            Do not change the selection state of the icon.

        ISMACTION_Stop
            Do not change the selection state of the icon. Do not
            invoke the hook function again.

tags -- Additional options.

Results

result -- FALSE if the drawer in question could not be found, TRUE otherwise. If FALSE is returned, you can query the error code using dos.library/IoErr().

Notes

The name of the drawer to work on is interpreted relative to the current directory of the program to call ChangeWorkbenchSelectionA().

For this function call to succeed, Workbench must be open. This
means that the LoadWB command was executed and the Workbench
screen has been opened.

While the user is dragging icons, no on-screen rendering may
take place. In this state Workbench may refuse to execute the
ChangeWorkbenchSelection() call and return an error code instead
(ERROR_OBJECT_IN_USE).

Example

* Select the icon labeled "Prefs" in the drawer "SYS:". *\ struct Hook hook;

\* This hook code is responsible for selecting the icon. *\
BOOL
SelectPrefs(struct Hook *hook,APTR reserved,struct IconSelectMsg *ism)
{
    \* If the name matches, select it. Otherwise, leave its
     * select state alone.
     *\
    if(Stricmp(ism->ism_Name,"Prefs") == 0)
        return (ISMACTION_Select);

    return (ISMACTION_Ignore);
}

.
.
.

\* Set up the hook data structure. *\
hook.h_Entry = HookEntry;
hook.h_SubEntry = (HOOKFUNC)SelectPrefs;

\* And finally change the selection. *\
ChangeWorkbenchSelection("SYS:",&hook,TAG_END);

Bugs

This function must be considered unsafe for workbench.library version 44 due to unexpected side-effects triggered by changing the state of selection. This bug was fixed in version 45.

See also

IoErr()

CloseWorkbenchObjectA()

CloseWorkbenchObjectA -- Close a drawer as if the user had clicked on the window close gadget. (V44)

Synopsis

success = CloseWorkbenchObjectA(name,tags) D0 A0 A1

BOOL CloseWorkbenchObjectA(STRPTR name,TagItem*tags);

success = CloseWorkbenchObject(name,...);

BOOL CloseWorkbenchObject(STRPTR name,...);

Function

This routine attempts to close the named object as if the user had clicked on its drawer window close gadget.

Inputs

name -- Name of the drawer to be closed.

tags -- Additional options.

Results

result -- FALSE if the object in question could not be closed, TRUE otherwise. If FALSE is returned, you can query the error code using dos.library/IoErr().

Notes

The name of the drawer to be closed is interpreted relative to the current directory of the program to call CloseWorkbenchObjectA().

For this function call to succeed, Workbench must be open. This
means that the LoadWB command was executed and the Workbench
screen has been opened.

While the user is dragging icons, no on-screen rendering may
take place. In this state Workbench may refuse to execute the
CloseWorkbenchObject() call and return an error code instead
(ERROR_OBJECT_IN_USE).

Example

* Close the drawer "SYS:" *\ CloseWorkbenchObjectA("SYS:",NULL);

See also

IoErr(), OpenWorkbenchObjectA()

MakeWorkbenchObjectVisibleA()

MakeWorkbenchObjectVisibleA -- Change a Workbench window in such a way as to make a particular icon visible. (V44)

Synopsis

success = MakeWorkbenchObjectVisibleA(name,tags) D0 A0 A1

BOOL MakeWorkbenchObjectVisibleA(STRPTR name,TagItem*tags);

success = MakeWorkbenchObjectVisible(name,...);

BOOL MakeWorkbenchObjectVisible(STRPTR name,...);

Function

Due to how the scrollers of a Workbench window affect the positions of the icons inside that window, some icons may not be drawn inside the bounds of the window. By using MakeWorkbenchObjectVisibleA() the window scrollers can be made to scroll such a "hidden" icon into view.

Inputs

name -- Name of the icon to make visible. Note that the window the icon resides in must already be open.

tags -- Additional options.

Results

result -- FALSE if the icon in question could not be found, TRUE otherwise. If FALSE is returned, you can query the error code using dos.library/IoErr().

Notes

The name of the icon to make visible is interpreted relative to the current directory of the program to call MakeWorkbenchObjectVisibleA().

For this function call to succeed, Workbench must be open. This
means that the LoadWB command was executed and the Workbench
screen has been opened.

While the user is dragging icons, no on-screen rendering may
take place. In this state Workbench may refuse to execute the
MakeWorkbenchObjectVisible() call and return an error code instead
(ERROR_OBJECT_IN_USE).

Example

* Make the icon for the drawer "SYS:" visible. *\ MakeWorkbenchObjectVisible("SYS:",TAG_END);

See also

IoErr()

OpenWorkbenchObjectA()

OpenWorkbenchObjectA -- Open a drawer or launch a program as if the user had double-clicked on an icon. (V44)

Synopsis

success = OpenWorkbenchObjectA(name,tags) D0 A0 A1

BOOL OpenWorkbenchObjectA(STRPTR name,TagItem*tags);

success = OpenWorkbenchObject(name,...);

BOOL OpenWorkbenchObject(STRPTR name,...);

Function

This routine attempts to open the named object as if the user had double-clicked on its icon. This allows you to open drawers under program control or to have Workbench launch your programs.

Inputs

name -- Name of the object to be opened; this can be a drawer name, a tool name or a project name.

tags -- Additional options.

Results

result -- FALSE if the object in question could not be opened, TRUE otherwise. Note that TRUE may be returned even if the program the object represents could not be launched; this is due to limitations in the current (V44) Workbench design. If FALSE is returned, you can query the error code using dos.library/IoErr().

Notes

You need not specify fully qualified path names for programs to be launched. Workbench will look for files without fully qualified path names along its default Shell search path. In any case, Workbench will look for the tool to be launched in the current directory of the program that called OpenWorkbenchObjectA(). The same holds true for drawers.

When launching a program, Workbench will automatically figure
out which tool to use if the object in question is actually a
project file with a project icon. Note that if the project
icon's default tool cannot be found, you will not see any
error message.

Workbench transparently supports launching of Shell programs,
but this is not recommended. You should always launch Shell
programs from your own process.

If you open a drawer, all WBOPENA_Arg[..] parameters you may
have provided will be ignored.

For this function call to succeed, Workbench must be open. This
means that the LoadWB command was executed and the Workbench
screen has been opened.

While the user is dragging icons, no on-screen rendering may
take place. In this state Workbench may refuse to execute the
OpenWorkbenchObject() call and return an error code instead
(ERROR_OBJECT_IN_USE).

Example

* Launch Multiview with S:Startup-Sequence as its parameter. *\ OpenWorkbenchObject("MultiView", WBOPENA_ArgLock, Lock("S:",SHARED_LOCK), WBOPENA_ArgName, "Startup-Sequence", TAG_DONE);

\* Launch the application "Paint" with the project files "Image1"
 * and "Image2", which are both found in the drawer "Paint:Pictures".
 *\
OpenWorkbenchObject("Paint",
    WBOPENA_ArgLock, Lock("Paint:Pictures",SHARED_LOCK),
    WBOPENA_ArgName, "Image1",
    WBOPENA_ArgName, "Image2",
TAG_DONE);

\* Launch the application "Paint" with the project files "Image1"
 * and "Anim1", which are both found in the drawers "Paint:Pictures"
 * and "Paint:Animations", respectively.
 *\
OpenWorkbenchObject("Paint",
    WBOPENA_ArgLock, Lock("Paint:Pictures",SHARED_LOCK),
    WBOPENA_ArgName, "Image1",
    WBOPENA_ArgLock, Lock("Paint:Animations",SHARED_LOCK),
    WBOPENA_ArgName, "Anim1",
TAG_DONE);

Bugs

Up to and including version 45.38 this function was unsafe and could not be used to reliably launch Workbench programs without causing memory to be trashed. The only functionality considered safe involved opening drawer windows.

Up to and including version 45.2 it was not possible to open
project icons that did not have files associated with them.
This was fixed with version 45.38 which, if necessary, will
resort to reading the project icon associated with the file
name given rather than returning an error for the missing file.

Up to and including version 47.17 any object not having a real
icon was assumed to have to be started in Shell mode, which
made it impossible to open an iconless project unless it was
a Shell script. This was fixed with version 47.18, which will
read a default icon (usually depending on the file type) for
such a project, and run whatever default tool is specified in
that icon to open it.

Up to and including version 47.17 it was not reliable to open
a tool or a project without CurrentDir()ing to its parent
directory first, as that would cause an incorrect lock to be
passed to the launched program through the Workbench argument
array. This was fixed with version 47.18.

Up to and including version 47.17 opening an object with any
spaces in its name didn't work if its icon specified it should
be started in Shell mode. This was fixed with version 47.18.

See also

IoErr(), CloseWorkbenchObjectA()

RemoveAppIcon()

RemoveAppIcon - remove an icon from Workbench's list (V36) of AppIcons.

Synopsis

success = RemoveAppIcon(AppIcon) D0 A0

BOOL RemoveAppIcon(struct AppIcon*);

Function

Attempt to remove an AppIcon from Workbench's list of AppIcons.

Inputs

AppIcon - pointer to an AppIcon structure returned by AddAppIcon.

Results

success - TRUE if the icon could be removed, FALSE otherwise.

Notes

As with anything that deals with asynchronous operation, you will need to do a final check for messages on your AppMessage port for messages that may have come in between the last time you checked and the call to remove the AppIcon.

See also

AddAppIconA()

RemoveAppMenuItem()

RemoveAppMenuItem - remove a menu item from Workbench's list (V36) of AppMenuItems.

Synopsis

success = RemoveAppMenuItem(AppMenuItem) D0 A0

BOOL RemoveAppMenuItem(struct AppMenuItem*);

Function

Attempt to remove an AppMenuItem from Workbench's list of AppMenuItems.

Inputs

AppMenuItem - pointer to an AppMenuItem structure returned by AddAppMenuItem.

Results

success - TRUE if the menu could be removed, FALSE otherwise.

Notes

As with anything that deals with asynchronous operation, you will need to do a final check for messages on your AppMessage port for messages that may have come in between the last time you checked and the call to removed the AppMenuItem.

See also

AddAppMenuItemA()

RemoveAppWindow()

RemoveAppWindow - remove a window from Workbench's list (V36) of AppWindows.

Synopsis

success = RemoveAppWindow(AppWindow) D0 A0

BOOL RemoveAppWindow(struct AppWindow*);

Function

Attempt to remove an appwindow from Workbench's list of AppWindows.

Inputs

AppWindow - pointer to an AppWindow structure returned by AddAppWindow.

Results

success - TRUE if the window could be removed, FALSE otherwise.

Notes

As with anything that deals with asynchronous operation, you will need to do a final check for messages on your AppMessage port for messages that may have come in between the last time you checked and the call to removed the AppWindow.

Before the AppWindow is removed, all its drop zones will be removed
first. There is no need for you to call RemoveAppWindowDropZone()
for every single one.

See also

AddAppWindowA(), RemoveAppWindowDropZone()

RemoveAppWindowDropZone()

RemoveAppWindowDropZone -- Remove a drop zone from an AppWindow.

Synopsis

success = RemoveAppWindowDropZone(appWindow,dropZone) D0 A0 A1

BOOL RemoveAppWindowDropZone(struct AppWindow*, struct AppWindowDropZone*);

Function

Attempt to remove a drop zone from an AppWindow.

Inputs

appWindow -- pointer to an AppWindow structure returned by workbench.library/AddAppWindowA. A value of NULL will be ignored. dropZone -- pointer to an AppWindowDropZone returned by workbench.library/AddAppWindowDropZoneA. A value of NULL will be ignored.

Results

success - TRUE if the drop zone could be removed, FALSE otherwise. The reason for the failure can be obtained using dos.library/IoErr. This routine may fail if the specified drop zone is not registered with the AppWindow.

Notes

Due to the asynchronous nature of Workbench/user interaction, you may receive AppIcon drop zone messages for zones that you have just removed. These messages may arrive in the time between your code calling RemoveAppWindowDropZone() and Workbench responding to the drop zone removal request. Be prepared to handle this. Once a drop zone is removed, it will generate no new AppMessages.

See also

AddAppWindowDropZoneA()

UpdateWorkbench()

UpdateWorkbench - Tell Workbench of a new or deleted icon. (V37)

Synopsis

UpdateWorkbench(name, parentlock, action) A0 A1 D0

VOID UpdateWorkbench(char *, BPTR, LONG);

Function

This function does the "magic" of letting Workbench know that an object has been added, changed, or removed. The name is the name of the object, the lock is a lock on the directory that contains the object. The action determines what has happened. If UPDATEWB_ObjectAdded, the object is either NEW or has CHANGED. If UPDATEWB_ObjectRemoved, the object has been deleted.

Inputs

name - Name of the object (without the .info)

parentlock - Lock on the object's parent directory.

action - UPDATEWB_ObjectAdded for a new or changed object
         UPDATEWB_ObjectRemoved for a deleted object

Results

Workbench will update its display, if needed. An object that has been deleted will be removed from the display. An object that is new will be added to the respective display if it is not already there; if it is already there, its appearance will be changed if necessary.

Notes

Note that saying that a DISK icon has been deleted will not do much as disk icons must continue to be visible. Thus, this is currently a NO-OP. At some future date (maybe) it will change the disk icon to the default.

Example

* Remove the object named "Prefs" from the SYS: drawer display; * note that this will affect only the display, the drawer will * still remain on the file system, and telling Workbench to * rescan the drawer will reveal it again. *\ BPTR lock,old_dir;

lock = Lock("SYS:",SHARED_LOCK);
UpdateWorkbench("Prefs",lock,UPDATEWB_ObjectRemoved);
UnLock(lock);

\* Change the name of the file "RAM:Thursday"
 * to "Friday"; this works by first removing the
 * object from the display, renaming the object
 * and then telling Workbench that the object has
 * changed.
 *\
lock = Lock("RAM:",SHARED_LOCK);
UpdateWorkbench("Thursday",lock,UPDATEWB_ObjectRemoved);
old_dir = CurrentDir(lock);
Rename("Thursday","Friday");
CurrentDir(old_dir);
UpdateWorkbench("Friday",lock,UPDATEWB_ObjectAdded);
UnLock(lock);

See also

PutDiskObject(), DeleteDiskObject()

WBInfo()

WBInfo - Bring up the Information requester (V39)

Synopsis

worked = WBInfo(lock, name, screen) d0 a0 a1 a2

ULONG WBInfo(BPTR, STRPTR,Screen*);

Function

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.

Inputs

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

Results

worked - Returns TRUE if the requester came up, FALSE if it did not.

Note

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

WhichWorkbenchObjectA()

WhichWorkbenchObjectA -- Query whether a click at the specified coordinates would hit a Workbench icon or window. (V47)

Synopsis

which = WhichWorkbenchObjectA(window, mousex, mousey, tags) D0 A0 D0 D1 A1

ULONG WhichWorkbenchObjectA(Window*window, LONG mousex, LONG mousey, constTagItem*tags);

which = WhichWorkbenchObject(window, x, y, ...)

ULONG WhichWorkbenchObject(Window*window, LONG mousex, LONG mousey, ...);

Function

If the specified window is a Workbench drawer window, and the passed coordinates reside within the area of a visible icon belonging to it, the function returns the constant WBO_ICON. If the window is a Workbench drawer window, and the coordinates fall into a visible area of its surface without intersecting any of its icons, the constant WBO_DRAWER is returned. If the window is not a Workbench window, or the coordinates lie within an obscured area of the window or even outside of its bounds, WBO_NONE is returned.

If the window pointer is not NULL, the coordinates you provide
must be relative to the window's upper left corner.
You can also pass a NULL window pointer and screen-relative
coordinates, which will be translated to appropriate parameters
for the topmost window intersecting those coordinates.

A tag list allows you to specify additional parameters for this
function. Most of the available tags can be used to retrieve
further information on the icon and/or drawer window found at
the specified coordinates; as none may be there, you should
only use this information if the function did return a suitable
value (WBO_ICON for icon-related tags, and either WBO_DRAWER or
WBO_ICON for drawer-related tags).

Inputs

window -- A window, possibly belonging to Workbench, or NULL.

mousex -- Horizontal coordinate, relative to the window (or to
    the Workbench screen if the window is NULL).

mousey -- Vertical coordinate, relative to the window (or to
    the Workbench screen if the window is NULL).

tags -- Additional options.

Results

which -- WBO_ICON if a click at the given coordinates would actually hit a Workbench icon, WBO_DRAWER if it would hit a Workbench window but not any icons, WBO_NONE otherwise.

Notes

This function is only intended to be used by input helpers such as commodities which need to know whether a mouse click will end up hitting a Workbench object or not. For example, a "ClickToFront"-like commodity could take advantage of it to avoid bringing a window to front after a double-click if all the user really wanted to do was to open a Workbench icon. It could also prove useful to implement context-sensitive menus for Workbench icons and windows.

Usage of this function by normal applications is discouraged.

Example

// Find out if there's an icon at coordinates 400, 300. hit = WhichWorkbenchObject(window,400,300,TAG_END);

WorkbenchControlA()

WorkbenchControlA -- Query or modify Workbench and icon options. (V44)

Synopsis

success = WorkbenchControlA(name,tags) D0 A0 A1

BOOL WorkbenchControlA(STRPTR name,TagItem*tags);

success = WorkbenchControl(name,...);

BOOL WorkbenchControl(STRPTR name,...);

Function

With this function you can query or modify global Workbench parameters or local icon options.

Inputs

name -- Name of an object to query or modify.

tags -- Additional options.

Results

result -- FALSE if the requested action could not be performed, TRUE otherwise. If FALSE is returned, you can query the error code using dos.library/IoErr().

Notes

If this function returns FALSE, the expected result is undefined. For example, if you tried to obtain the list of currently running programs via the WBCTRLA_GetProgramList tag and WorkbenchControl() failed with an error code, do not expect the List pointer you passed in to be initialized.

This function may only be called by a Process.

This function may not process all tags if the Workbench is not
currently open. For V44, the following tags are support if
Workbench is closed:

    WBCTRLA_SetDefaultStackSize
    WBCTRLA_GetDefaultStackSize
    WBCTRLA_FreeHiddenDeviceList
    WBCTRLA_GetHiddenDeviceList
    WBCTRLA_AddHiddenDeviceName
    WBCTRLA_RemoveHiddenDeviceName
    WBCTRLA_SetTypeRestartTime
    WBCTRLA_GetTypeRestartTime

For V45 the following additional tags are supported while Workbench
is closed:

    WBCTRLA_GetCopyHook
    WBCTRLA_SetCopyHook
    WBCTRLA_GetDeleteHook
    WBCTRLA_SetDeleteHook
    WBCTRLA_GetTextInputHook
    WBCTRLA_SetTextInputHook

It should be noted that the copy hook code will never be
invoked if data can be moved on the file system just by
renaming it. Likewise, if an entire volume is to be copied
to a different volume by means of the DiskCopy program,
the copy hook code will not be invoked either.

Example

* Obtain a copy of the Workbench search path list, then * release it again. *\ BPTR pathList;

if(WorkbenchControl(NULL,
    WBCTRLA_DuplicateSearchPath,&pathList,
TAG_DONE))
{
    WorkbenchControl(NULL,
        WBCTRLA_FreeSearchPath,pathList,
    TAG_DONE);
}

\* Check if the drawer "SYS:" is open. *\
LONG isOpen;

if(WorkbenchControl("SYS:",
    WBCTRLA_IsOpen,&isOpen,
TAG_DONE))
{
    Printf("Drawer \"SYS:\" is %s.\n",
        isOpen ? "open" : "closed");
}

\* Print the list of all currently running
 * Workbench programs, then free the list again.
 *\
struct List * list;

if(WorkbenchControl(NULL,
    WBCTRLA_GetProgramList,&list,
TAG_DONE))
{
    struct Node * node;

    for(node = list->lh_Head ;
        node->ln_Succ != NULL ;
        node = node->ln_Succ)
    {
        Printf("%s\n",node->ln_Name);
    }

    WorkbenchControl(NULL,
        WBCTRLA_FreeProgramList,list,
    TAG_DONE);
}

See also

FreeDosObject(), IoErr()