workbench
Index
struct AppIcon * AddAppIconA(
IPTR id,
IPTR userdata,
const char * text,
struct MsgPort * msgport,
BPTR lock,
struct DiskObject * diskobj,
struct TagItem * taglist );
struct AppIcon * AddAppIcon(
IPTR id,
IPTR userdata,
const char * text,
struct MsgPort * msgport,
BPTR lock,
struct DiskObject * diskobj,
TAG tag, ... );
Add an icon to the workbench's list of AppIcons. If a workbench is
running, the icon will appear on the workbench screen given that the
call is successful.
When a user interacts with the AppIcon, an AppMessage of type
MTYPE_APPICON is sent to the message port specified. The different
supported actions are:
1. User double-clicking on the icon. am_NumArgs is zero and am_ArgList is
NULL.
2. Dropping one or more icons on the AppIcon. am_Numargs is the number of
icons dropped plus one; am_ArgList is an array of pointers to WBArg
structures of the icons dropped.
3. Dropping the AppIcon on another icon -- NOT SUPPORTED.
4. Invoking an "Icons" menu item when the AppIcon is selected. am_Class
will be set to a value in AMCLASSICON_Open ... AMCLASSICON_EmptyTrash.
id -- AppIcon identification number; only for your use (ignored by
workbench.library)
userdata -- user specific data (ignored by workbench.library)
text -- name of the icon
lock -- currently unused (must be set to NULL)
msgport -- message port to which notification messages will be sent
diskobj -- pointer to a DiskObject structure filled in as described
below:
do_Magic -- 0
do_Version -- 0
do_Gadget -- a gadget structure filled in as follows:
NextGadget -- NULL
LeftEdge -- 0
TopEdge -- 0
Width -- width of icon hit box
Height -- height of icon hit box
Flags -- 0 or GADGHIMAGE
Activation -- 0
GadgetType -- 0
GadgetRender -- pointer to an Image structure
filled in as follows:
LeftEdge -- 0
TopEdge -- 0
Width -- width of image (must be <=
width of icon hit box)
Height -- height of image (must be <=
height of icon hit box)
Depth -- number of bit planes of
image
ImageData -- pointer to word aligned
image data
PlanePick -- plane mask
((1 << depth) - 1)
PlaneOnOff -- 0
NextImage -- NULL
SelectRender -- NULL
GadgetText -- NULL
MutualExclude -- NULL
SpecialInfo -- NULL
GadgetID -- NULL
UserData -- NULL
do_Type -- 0
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 -- 0
taglist -- tags (see below)
WBAPPICONA_SupportsOpen (BOOL)
Set to TRUE if the AppIcon should respond to the "Open" menu.
[default = TRUE]
WBAPPICONA_SupportsCopy (BOOL)
Set to TRUE if the AppIcon should respond to the "Copy" menu.
[default = FALSE]
WBAPPICONA_SupportsRename (BOOL)
Set to TRUE if the AppIcon should respond to the "Rename" menu.
[default = FALSE]
WBAPPICONA_SupportsInformation (BOOL)
Set to TRUE if the AppIcon should respond to the "Information" menu.
[default = FALSE]
WBAPPICONA_SupportsSnapshot (BOOL)
Set to TRUE if the AppIcon should respond to the "Snapshot" menu.
[default = FALSE]
WBAPPICONA_SupportsUnSnapshot (BOOL)
Set to TRUE if the AppIcon should respond to the "UnSnapshot" menu.
[default = FALSE]
WBAPPICONA_SupportsLeaveOut (BOOL)
Set to TRUE if the AppIcon should respond to the "Leave Out" menu.
[default = FALSE]
WBAPPICONA_SupportsPutAway (BOOL)
Set to TRUE if the AppIcon should respond to the "Put Away" menu.
[default = FALSE]
WBAPPICONA_SupportsDelete (BOOL)
Set to TRUE if the AppIcon should respond to the "Delete" menu.
[default = FALSE]
WBAPPICONA_SupportsFormatDisk (BOOL)
Set to TRUE if the AppIcon should respond to the "Format Disk" menu.
[default = FALSE]
WBAPPICONA_SupportsEmptyTrash (BOOL)
Set to TRUE if the AppIcon should respond to the "Empty Trash" menu.
[default = FALSE]
WBAPPICONA_PropagatePosition (BOOL)
Set to TRUE if the AppIcon's position should be updated in the DiskObject
passed to this function when the AppIcon is moved. If this is set to TRUE,
workbench.library will assume that the structure is not freed as long as
the AppIcon is alive.
[default = FALSE]
WBAPPICONA_RenderHook (struct Hook *)
Pointer to a hook that will be invoked when the AppIcon is rendered.
Using this hook and WorkbenchControlA() dynamic or animated AppIcons may
be created. The hook will be called with the following parameters:
result = hookFunc(hook, reserved, arm);
where the 'hookFunc' has the prototype
LONG hookFunc(struct Hook *hook, APTR reserved,
struct AppIconRenderMsg *arm);
If the hook function returns TRUE, the regular image of the AppIcon will
be drawn; if it returns FALSE, nothing will be drawn. This allows you to
do all the icon rendering except for when dragging the icon on the screen.
WBAPPICONA_NotifySelectState (BOOL)
When TRUE, you will be notificed whenever the AppIcon becomes selected or
unselected; the am_Class will be set to AMCLASSICON_Selected or
AMCLASSICON_Unselected.
A pointer to an AppIcon structure -- which should be used with
RemoveAppIcon() when you want to remove the icon -- or NULL if it was
not possible to add the AppIcon.
Contrary to AmigaOS, AppIcons may be added when there is no workbench
application running.
struct AppMenuItem * AddAppMenuItemA(
IPTR id,
IPTR userdata,
APTR text,
struct MsgPort * msgport,
struct TagItem * taglist );
struct AppMenuItem * AddAppMenuItem(
IPTR id,
IPTR userdata,
APTR text,
struct MsgPort * msgport,
TAG tag, ... );
Try to add a menu item to workbench.library's list of AppMenuItems (this
will be shown in the 'Tools' menu strip in Workbench).
id -- menu item identifier; for your convenience (ignored by
workbench.library)
userdata -- user specific data (ignored by workbench.library)
text -- menu item text; any text consisting merely of '-','_' and
'~' characters corresponds to a separator bar instead of
a textual item
msgport -- port to which notification messages regarding the menu
item will be sent
taglist -- tags (see below)
WBAPPMENUA_CommandKeyString (STRPTR)
Command key assigned to this menu item. If the string is empty, it will
be ignored as will it if the command key is already in use by another
menu item. Only the first character of the string will be used.
[default = NULL]
A pointer to an AppMenuItem which you pass to RemoveAppMenuItem() when
you want to remove the menu item. If it was not possible to add the menu
item, NULL will be returned.
Contrary to AmigaOS, this function will report success even when there
is no running workbench application.
struct AppWindow * AddAppWindowA(
IPTR id,
IPTR userdata,
struct Window * window,
struct MsgPort * msgport,
struct TagItem * taglist );
struct AppWindow * AddAppWindow(
IPTR id,
IPTR userdata,
struct Window * window,
struct MsgPort * msgport,
TAG tag, ... );
Try to add an AppWindow to workbench.library's list of AppWindows.
The supplied message port will be used to send notification messages
whenever an icon is dropped on the window. The message will be of
type 'AMTYPE_APPWINDOW' and am_ArgList will point to the list of icons
that were dropped in the window.
id -- window identifier; for your convenience (ignored by
workbench.library)
userdata -- user specific data (ignored by workbench.library)
window -- pointer to the window to add AppWindow functionality to
msgport -- port to which notification messages regarding the window
will be sent
taglist -- tags (must be NULL)
A pointer to an AppWindow structure to use with RemoveAppWindow() when
you want to remove the window from the list of AppWindows, or NULL
if it was not possible to add the window to the AppWindow list.
Applications generally want to call GetDiskObjectNew() -- rather than
GetDiskObject() -- to get disk objects for icons dropped in the window.
Contrary to AmigaOS, this function will succeed even when there
is no running workbench application.
struct AppWindowDropZone * AddAppWindowDropZoneA(
struct AppWindow * aw,
IPTR id,
IPTR userdata,
struct TagItem * tags );
struct AppWindowDropZone * AddAppWindowDropZone(
struct AppWindow * aw,
IPTR id,
IPTR userdata,
TAG tag, ... );
A regular AppWindow, when created with AddAppWindowA() will respond to
dropping icons anywhere in the window. With this function you can specify
which parts of the window are suitable for dropping icons on.
aw -- An AppWindow structure as returned by AddAppWindowA()
id -- drop zone identifier; for your convenience (ignored by
workbench.library)
taglist -- tags (see below)
WBDZA_Left (WORD)
Left edge of the drop zone relative to the left window edge.
WBDZA_RelRight (WORD)
Left edge of the drop zone relative to the right window edge. A value
of -20 would create a zone located 20 pixels to the left of the right
window edge.
WBDZA_Top (WORD)
Top edge of the drop zone relative to the top of the window.
WBDZA_RelBottom (WORD)
Top edge of the drop zone relative to the window height; a value of -20
would create a zone located 20 pixels above the window bottom edge.
WBDZA_Width (WORD)
Widthof the drop zone in pixels.
WBDZA_RelWidth (WORD)
Width of the drop zone relative to the width of the window; a value of
-20 would create a zone that is 20 pixels narrower than the window.
WBDZA_Height (WORD)
Height of the drop zone in pixels.
WBDZA_RelHeight
Height of the drop zone relative to the height of the window; a value of
-20 would create a zone that is 20 pixels smaller than the window.
WBDZA_Box (struct IBox *)
Position and size of the drop zone
WBDZA_Hook (struct Hook *)
Pointer to a hook that will be called whenever the mouse enters or leaves
your drop zone. The hook will be called with the following parameters.
hookFunc(hook, reserved, arm);
where the 'hookFunc' is prototyped as:
LONG hookFunc(struct Hook *hook, APTR reserved,
struct AppWindowDropZoneMsg *adzm);
Your hook function should always return 0. You must limit the rendering
done in the 'hookFunc' to simple graphics.library operations as otherwise
you risk deadlocking the system.
A drop zone identifier or NULL if the drop zone could not be created.
When a drop zone is installed, the messages received when icons are
dropped are of type 'AMTYPE_APPWINDOWZONE' instead of 'AMTYPE_APPWINDOW'.
You must be able to handle both types of messages if you call this
function.
Drop zones must be created with a position and a size; otherwise this
function 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 and NOT
relative to the drop zone coordinates.
BOOL ChangeWorkbenchSelectionA(
STRPTR name,
struct Hook * hook,
struct TagItem * tags );
BOOL ChangeWorkbenchSelection(
STRPTR name,
struct Hook * hook,
TAG tag, ... );
BOOL CloseWorkbenchObjectA(
STRPTR name,
struct TagItem * tags );
BOOL CloseWorkbenchObject(
STRPTR name,
TAG tag, ... );
struct DiskObject * GetNextAppIcon(
struct DiskObject * lastdiskobj,
char * text );
Accesses AppIcon information from workbench.library. This function
is meant for iterations through wblibsґ AppIcon storage as needed
to display those.
Initialised with a NULL as the first argument, it iterates
through all AppIcons stored in workbench.library by returning the
pointer to the next AppIconґs DiskObject structure and copies the
name of the given AppIcon to the given array. The function returns
a NULL if the end of AppIcon list was reached or if no AppIcons
were stored.
lastdiskobj -- NULL (initial value) or pointer to a DiskObject
structure stored in workbench.library
text -- char array pointer to store AppIconґs name in
A pointer to an DiskObject structure -- which should be used within
the next function call to access the next AppIcon -- or NULL if no
AppIcons were found or end of list was reached.
struct DiskObject *_nb_dob = NULL;
char text[32];
while ( _nb_dob = GetNextAppIcon(_nb_dob, &text) )
{
printf("appicon found: %s \n", text);
}
BOOL MakeWorkbenchObjectVisibleA(
STRPTR name,
struct TagItem * tags );
BOOL MakeWorkbenchObjectVisible(
STRPTR name,
TAG tag, ... );
BOOL OpenWorkbenchObjectA(
STRPTR name,
struct TagItem * tags );
BOOL OpenWorkbenchObject(
STRPTR name,
TAG tag, ... );
BOOL QuoteWorkbench(
ULONG stringNum );
BOOL RegisterWorkbench(
struct MsgPort * messageport );
The workbench application uses this function to register itself with
the library. When it has done this, the library sends messages to the
specified port about actions the application is supposed to carry out.
All messages sent to the message port are of struct WBHandlerMessage,
which is specified in <workbench/handler.h>. The wbhm_Type field
identifies the type of message and which part of the wbhm_Data union
is relevant. The following types are currently defined:
WBHM_TYPE_SHOW
Intuition has (re)opened the Workbench Screen, and request that
you open all your windows. When the message is replied, Intuition
assumes that the windows have been opened.
WBHM_TYPE_HIDE
Intuition is about to close the Workbench Screen, and request that
you close all your windows. When the message is replied, Intuition
assumes that the windows have been closed and will try to close the
screen.
WBHM_TYPE_OPEN
Request to open the specified drawer.
WBHM_TYPE_UPDATE
The state of the specified disk object has changed, and this
message serves as a notification and suggestion that you should
update its visual representation to the user. For example, it
might have been deleted or renamed.
messageport - The message port to send the to.
TRUE if the message port was successfully registered, FALSE otherwise.
The registration will fail if an other message port has already been
registered earlier or if a NULL pointer was passed in.
As you can read above, only one workbench application can be registered
at a time. This is intentional. Note that "workbench application" in
this context means the program that is the file manager and handles
the GUI, not a program that is started using OpenWorkbenchObjectA()!
BOOL RemoveAppIcon(
struct AppIcon * appIcon );
Try to remove an AppIcon from workbench.library's list of AppIcons.
appIcon -- pointer to an AppIcon got from AddAppIconA()
TRUE if the icon could be removed, FALSE otherwise.
You must do a final check for messages on your AppMessage port as messages
may have been sent between the last time you checked and the call to
this function.
BOOL RemoveAppMenuItem(
struct AppMenuItem * appMenuItem );
Try to remove an AppMenuItem from workbench.library's list of AppMenuItems.
Pointer to an AppMenuItem structure as returned by AddAppMenuItem().
TRUE if the menu item could be removed, FALSE otherwise.
You have to do a final check for messages on your AppMenuItem message
port as messages may have arrived between the last time you checked this
and the call to this function.
BOOL RemoveAppWindow(
struct AppWindow * appWindow );
Try to remove an AppWindow from workbench.library's list of AppWindow:s.
appWindow -- pointer to AppWindow structure got from AddAppWindow().
TRUE if the window could be removed, FALSE otherwise.
You have to do another check for messages on the AppWindow message port
you specified at the AppWindow creation time (AddAppWindow()) after the
window is removed as it may have arrived messages between the last time
you checked and the call of this function.
Before the AppWindow is removed, all its drop zones will be removed.
Thus there is no need to call RemoveAppWindowDropZone() explicitly.
BOOL RemoveAppWindowDropZone(
struct AppWindow * aw,
struct AppWindowDropZone * dropZone );
Try to remove a drop zone from an AppWindow.
appWindow -- pointer to the AppWindow (as returned by AddAppWindow()) to
try to remove the drop zone from; a value of NULL will
result in no operation
dropZone -- pointer to an AppWindowDropZone (as returned by
AddAppWindowDropZone()); a value of NULL will result in
no operation
TRUE if the drop zone could be removed, FALSE otherwise. In case of
failure, the reason may be obtained from dos.library/IoErr(). This
function may fail if the specified drop zone is not registered with
the supplied AppWindow.
You must check for drop zone messages for zones that you just removed as
there might have been messages sent between the last time you checked and
the call to this function.
BOOL SendAppWindowMessage(
struct Window * win,
ULONG numfiles,
char ** files,
UWORD class,
WORD mousex,
WORD mousey,
ULONG seconds,
ULONG micros );
This function sends the given list of files to a registered
AppWindow's application. If the window is not an AppWindow, nothing
is done.
win - window that should be checked
numfiles - number of files in the attached array of string pointers
files - files "list"
char *FileList[] =
{"images:image1.png", "images:image2.png", "images:image3.png"};
SendAppWindowMessage(myWindow, 3, FileList);
BOOL StartWorkbench(
ULONG flags,
APTR ptr );
BOOL UnregisterWorkbench(
struct MsgPort * messageport );
The workbench application uses this functions to unregister itself
with the library. When it is done, messages will no longer be sent.
msgport - The message port of that was earlier passed in to
RegisterWorkbench().
TRUE if the message port was successfully unregistered, FALSE otherwise.
The unregistration will fail if the message port isn't the same that
was passed in with RegisterWorkbench() earlier or if the passed
in pointer is NULL.
Note that "Workbench Application" in this context means the program that
is the file manager and handles the GUI of Workbench, not a program that
is started from Workbench!
BOOL UpdateWorkbench(
CONST_STRPTR name,
BPTR parentlock,
LONG action );
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.
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
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.
BOOL UpdateWorkbenchObjectA(
STRPTR name,
LONG type,
struct TagItem * tags );
BOOL UpdateWorkbenchObject(
STRPTR name,
LONG type,
TAG tag, ... );
Informs the workbench application that an object has changed, and that
it should update it's visual representation.
name - Name of object that has changed.
type - Type of object (WBDISK, WBTOOL, ...).
tags - Additional options.
No tags are defined at this time.
This function is TEMPORARY! It will hopefully go away before AROS 1.0,
and it might change it's API several times before that!
The existance of this function is a bug itself. It should be removed
once there is a adequate notification API in dos.library that works.
BOOL WBConfig(
ULONG unk1,
ULONG unk2 );
BOOL WBInfo(
BPTR lock,
CONST_STRPTR name,
struct Screen * screen );
lock - Lock to directory or disk
name - Name of the object in directory.
Note: also for def icons, name has to be passed without .info
extension to be able to edit def icon attributes. Passing a
name.info should open information on the .info file itself (a
binary file without any icon attributes). This behavior is
confirmed with Workbench.
screen argument is currently ingored
BOOL WorkbenchControlA(
STRPTR name,
struct TagItem * tags );
BOOL WorkbenchControl(
STRPTR name,
TAG tag, ... );
|
|
