Autodocs
Libraries:
workbench.library
AddAppIconA
AddAppMenuItemA
AddAppWindowA
AddAppWindowDropZoneA
ChangeWorkbenchSelectionA
CloseWorkbenchObjectA
MakeWorkbenchObjectVisibleA
OpenWorkbenchObjectA
RemoveAppIcon
RemoveAppMenuItem
RemoveAppWindow
RemoveAppWindowDropZone
UpdateWorkbench
WBInfo
WorkbenchControlA
Include
GuruMeditation
|
Docs » Autodocs » workbench.library » WorkbenchControlA
WorkbenchControlA -- Query or modify Workbench and icon
options. (V44)
success = WorkbenchControlA(name,tags)
D0 A0 A1
BOOL WorkbenchControlA(STRPTR name,struct TagItem *tags);
success = WorkbenchControl(name,...);
BOOL WorkbenchControl(STRPTR name,...);
With this function you can query or modify global Workbench
parameters or local icon options.
name -- Name of an object to query or modify.
tags -- Additional options.
WBCTRLA_IsOpen (LONG *) -- Check if the named object is
currently open. In this case, the function "name"
parameter refers to the drawer that should be
tested; the result value will be set to TRUE if
the named drawer is currently open, FALSE otherwise.
WBCTRLA_DuplicateSearchPath (BPTR *) -- This is a safe way
to obtain a copy of the Workbench search path list.
You will receive a BPTR to a path list, such as can
be stored in the cli_CommandDir pointer of a
CommandLineInterface structure. Note that this is really
a copy of the Workbench search path list and not a reference
to the data associated with the Workbench process. Thus,
it can be freed by FreeDosObject(DOS_CLI,..), if part of
a CommandLineInterface structure.
WBCTRLA_FreeSearchPath (BPTR) -- If you did not attach the
data returned by the WBCTRLA_DuplicateSearchPath
to a CLI, to be freed automatically later, you can
pass it back to WorkbenchControlA() to be released.
WBCTRLA_GetDefaultStackSize (ULONG *) -- Get the default stack
size used by Workbench when launching Shell programs
or programs without a valid stack size number.
The default stack size is 4096 bytes.
WBCTRLA_SetDefaultStackSize (ULONG) -- Set the default stack
size used by Workbench when launching Shell programs
or programs without a valid stack size number. You cannot
set a stack size number smaller than 4096 bytes
WBCTRLA_RedrawAppIcon (struct AppIcon *) -- This tag will cause
Workbench to redraw an AppIcon. Note that due to which state
the Workbench is currently in, it may refuse to redraw the
icon.
WBCTRLA_GetProgramList (struct List **) -- You can obtain a list
of currently running Workbench programs; every entry of this
list will have the complete path to the program and the
program name in its Node->ln_Name. When you no longer need
the list, don't forget to free it again using the tag
WBCTRLA_FreeProgramList.
Note that the list you will receive may be empty. Be
prepared to handle this.
WBCTRLA_FreeProgramList (struct List *) -- With this tag you can
free the list allocated by the WBCTRLA_GetProgramList tag.
WBCTRLA_GetSelectedIconList (struct List **) -- You can obtain a
list of currently selected icons; every entry of this
list will have the complete path to the icon and the
icon name in its Node->ln_Name. Some icons do not enter the
list, such as AppIcons. When you no longer need the list,
don't forget to free it again using the tag
WBCTRLA_FreeSelectedIconList.
Note that the list you will receive may be empty. Be
prepared to handle this.
WBCTRLA_FreeSelectedIconList (struct List *) -- With this tag
you can free the list allocated by the
WBCTRLA_GetSelectedIconList tag.
WBCTRLA_GetOpenDrawerList (struct List **) -- You can obtain a
list of currently open drawers and volumes; every entry of this
list will have the complete drawer path name in its Node->ln_Name.
When you no longer need the list, don't forget to free it
again using the tag WBCTRLA_FreeOpenDrawerList.
Note that the list you will receive may be empty. Be
prepared to handle this.
WBCTRLA_FreeOpenDrawerList (struct List *) -- With this tag
you can free the list allocated by the
WBCTRLA_GetOpenDrawerList tag.
WBCTRLA_AddHiddenDeviceName (STRPTR) -- Name of a device which
Workbench should not display a disk or device icon for.
Any such device will be effectively hidden from the Workbench
backdrop. The name must include a terminating colon character,
such as in "DF0:".
Note that adding new entries to this list may not immediately
take effect.
WBCTRLA_RemoveHiddenDeviceName (STRPTR) -- Name of a device on
the list of devices to be hidden which should be removed.
The name must include a terminating colon character,
such as in "DF0:". Trying to remove an entry from the list
that is not on it will have no effect.
Note that removing entries from this list may not immediately
take effect.
WBCTRLA_GetHiddenDeviceList (struct List **) -- This will obtain
the list of devices whose contents which Workbench will not
display.
Note that the list you will receive may be empty. Be
prepared to handle this.
WBCTRLA_FreeHiddenDeviceList (struct List *) -- With this tag
you can free the list allocated by the
WBCTRLA_GetHiddenDeviceList tag.
WBCTRLA_GetTypeRestartTime (ULONG *) -- Get the number of seconds
that have to pass before typing the next character in a drawer
window will restart with a new file name.
WBCTRLA_SetTypeRestartTime (ULONG) -- Set the number of seconds
that have to pass before typing the next character in a drawer
window will restart with a new file name. You must specify a
number greater than 0. Default type restart time is 3 seconds.
WBCTRLA_GetCopyHook (struct Hook **) -- Obtain the hook that will be
invoked when Workbench starts to copy files and data; this
may be NULL which means that Workbench will use the built-in
copy/move code (V45).
WBCTRLA_SetCopyHook (struct Hook *) -- Install the hook that will be
invoked when Workbench starts to copy files and data.
To make Workbench use the built-in copy code, use a NULL
hook pointer. Note: the hook cannot be replaced if Workbench is
currently copying data; WorkbenchControl() will stop and
return with an error code of ERROR_OBJECT_IN_USE set (V45).
The hook will be invoked with three kinds of messages: exactly
one CopyBeginMsg, one CopyDataMsg for each file or drawer to
be copied and exactly one CopyEndMsg after all files and drawers
have been copied.
NOTE: you may examine the contents of the message your hook
code receives, but they may not be changed!
The hook will be invoked with the following parameters:
error = hookFunc(hook,reserved,message)
D0 A0 A2 A1
LONG hookFunc(struct Hook *hook,APTR reserved,
struct CopyBeginMsg *message);
-- or --
LONG hookFunc(struct Hook *hook,APTR reserved,
struct CopyDataMsg *message);
-- or --
LONG hookFunc(struct Hook *hook,APTR reserved,
struct CopyEndMsg *message);
The reserved parameter will always be set to NULL (V45).
The copying process starts by invoking the hook with a
CopyBeginMsg whose contents look like this:
cbm_Length
Size of the CopyBeginMsg in bytes; this may grow
in future Workbench releases.
cbm_Action
For a CopyBeginMsg this will always be set to
CPACTION_Begin.
cbm_SourceDrawer
This will be a Lock on the source drawer.
cbm_DestinationDrawer
This will be a Lock on the destination drawer.
You will receive exactly one CopyBeginMsg before copying
starts. You will need to set up all the information and data
you need for copying and return an error code in case your
initialization failed; this should be an error code from
<dos/dos.h>, e.g. ERROR_NO_FREE_STORE. If your initialization
could be completed successfully, a value of 0 should be returned.
Once the initialization has been completed successfully, your
hook code will receive a CopyDataMsg for every file or drawer
that needs to be copied. Your code will have to figure out for
itself whether the source is a file, a directory or even a
volume. Directories and volumes need to be copied recursively
by copying files and directories located at deeper levels of
the file system.
The contents of a CopyDataMsg look like this:
cdm_Length
Size of the CopyDataMsg in bytes; this may grow
in future Workbench releases.
cdm_Action
For a CopyDataMsg this will always be set to
CPACTION_Copy.
cdm_SourceLock
A lock on the source file/drawer's parent directory; this
may be NULL in case an entire volume is to be copied.
cdm_SourceName
Name of the source file/drawer to be copied, relative
to the parent drawer it is located in and to which you
will find a Lock supplied in the cdm_SourceLock member.
For volumes that Lock may be NULL.
cdm_DestinationLock
A lock on the drawer in which the destination file or
drawer is to be created.
cdm_DestinationName
Name of the file or drawer the source data should be
copied to. In most cases this name matches the source
name, but if data is to be duplicated (such as through
the Workbench "Copy" command), then the name will be
different.
cdm_DestinationX
cdm_DestinationY
After the copy process has successfully completed and the
copied drawer/file icon has to be written, it should be
placed at this position when it is written to disk.
Your copy code is responsible for notifying Workbench of any
icons newly created as a result of the copying process. If an error
crops up during copying or the process is aborted, your code must
return a non-zero error code (as listed in <dos/dos.h> or in
<dos/dosasl.h>). A return code of 0 indicates success; Workbench
will proceed to invoke your code again with another file/drawer
name.
When the copy process has completed, either successfully or due
to an error, your hook code will be invoked exactly once with
a CopyEndMsg. This allows you to perform any cleanup operations
that may be necessary. The contents of a CopyEndMsg look like
this:
cem_Length
Size of the CopyEndMsg in bytes; this may grow
in future Workbench releases.
cem_Action
For a CopyEndMsg this will always be set to
CPACTION_End.
Note that Workbench will not recurse into directories,
supplying you with the names of all files and directories
to be copied; it will generally only supply the names of
the files and drawers that are currently selected. You will
have to handle all the necessary recursion by yourself.
WBCTRLA_GetDeleteHook (struct Hook **) -- Obtain the hook that will
be invoked when Workbench discards files and drawers or empties
the trashcan. This may be NULL which means that Workbench will
use the built-in deletion code (V45).
WBCTRLA_SetDeleteHook (struct Hook *) -- Install the hook that will
be invoked when Workbench discards files and drawers or empties
the trash can. To make Workbench use the built-in deletion code,
use a NULL hook pointer. Note: the hook cannot be replaced if
Workbench is currently deleting files and drawers or the trashcan
is being emptied; WorkbenchControl() will stop and return with an
error code of ERROR_OBJECT_IN_USE set (V45).
The hook will be invoked with six different kinds of messages,
depending upon what operation is to be performed. If the files
and drawers are to be discarded you will receive exactly one
DeleteBeginMsg with its dbm_Action member set to
DLACTION_BeginDiscard, followed by a DeleteDataMsg for each
file or drawer to be deleted and eventually exactly one
DeleteEndMsg when the deletion process is finished. If the
trashcan is to be emptied you will receive exactly one
DeleteBeginMsg with its dbm_Action member set to
DLACTION_BeginEmptyTrash, followed by exactly one DeleteDataMsg
and eventually exactly one DeleteEndMsg.
NOTE: you may examine the contents of the message your hook
code receives, but they may not be changed!
The hook will be invoked with the following parameters:
error = hookFunc(hook,reserved,message)
D0 A0 A2 A1
LONG hookFunc(struct Hook *hook,APTR reserved,
struct DeleteBeginMsg *message);
-- or --
LONG hookFunc(struct Hook *hook,APTR reserved,
struct DeleteDataMsg *message);
-- or --
LONG hookFunc(struct Hook *hook,APTR reserved,
struct DeleteEndMsg *message);
The reserved parameter will always be set to NULL (V45).
The deletion process starts by invoking the hook with a
DeleteBeginMsg whose contents look like this:
dbm_Length
Size of the DeleteBeginMsg in bytes; this may grow
in future Workbench releases.
dbm_Action
For a DeleteBeginMsg this will either be set to
DLACTION_BeginDiscard or to DLACTION_BeginEmptyTrash.
DLACTION_BeginDiscard is sent if the "Delete" menu
item was invoked, and DLACTION_BeginEmptyTrash will
be sent if the "Empty Trash" menu item was invoked.
You will receive exactly one DeleteBeginMsg before deletion
starts. You will need to set up all the information and data
you need for deleting and return an error code in case your
initialization failed; this should be an error code from
<dos/dos.h>, e.g. ERROR_NO_FREE_STORE. If your initialization
could be completed successfully, a value of 0 should be returned.
NOTE: if you return a value of -1, then Workbench will drop
right into the original deletion code. However, this only
works for the actions DLACTION_BeginDiscard and
DLACTION_BeginEmptyTrash. This means you can skip the
deletion process when it begins, but you cannot skip
it while it is running.
Once the initialization has been completed successfully, your
hook code will receive a DeleteDataMsg for every file or drawer
that needs to be deleted. Its contents look like this:
ddm_Length
Size of the DeleteDataMsg in bytes; this may grow
in future Workbench releases.
ddm_Action
This may be either DLACTION_DeleteContents or
DLACTION_DeleteObject, depending on exactly what
should be deleted.
If DLACTION_DeleteContents is received it means
that the object described by lock and name is a
directory: the contents of the directory are to
be deleted, but the empty directory itself
*MUST NOT* be deleted.
If DLACTION_DeleteObject is received it means that
the object described by lock and name is either a
file or an empty directory which should be deleted.
Typically, if the trash can is to be emptied you will
receive exactly one DLACTION_DeleteContents type
message. If drawers are to be deleted, you will first
receive a DLACTION_DeleteContents type message, followed
by a DLACTION_DeleteObject message to delete the then
empty directory.
ddm_Lock
A lock on the parent directory of the object whose
contents or which itself should be deleted.
ddm_Name
The name of the object whose contents or which itself
should be deleted.
Your deletion code is responsible for notifying Workbench of any
icons removed as a result of the deletion process. If an error
crops up during deletion or the process is aborted, your code must
return a non-zero error code (as listed in <dos/dos.h> or in
<dos/dosasl.h>). A return code of 0 indicates success; Workbench
will proceed to invoke your code again with another file/drawer
name.
When the deletion process has completed, either successfully or due
to an error, your hook code will be invoked exactly once with
a DeleteEndMsg. This allows you to perform any cleanup operations
that may be necessary. The contents of a DeleteEndMsg look like
this:
dem_Length
Size of the DeleteEndMsg in bytes; this may grow
in future Workbench releases.
dem_Action
For a DeleteEndMsg this will always be set to
DLACTION_End.
Note that Workbench will not recurse into directories,
supplying you with the names of all files and directories
to be deleted; it will generally only supply the names of
the files and drawers that are currently selected. You will
have to handle all the necessary recursion by yourself.
WBCTRLA_GetTextInputHook (struct Hook **) -- Obtain the hook that will
be invoked when Workbench requests that the user enters text,
such as when a file is to be renamed or a new drawer is to be
created. This may be NULL which means that Workbench will
use the built-in text input code (V45).
WBCTRLA_SetTextInputHook (struct Hook *) -- Install the hook that will
be invoked when Workbench requests that the user enters text,
such as when a file is to be renamed or a new drawer is to be
created. To make Workbench use the built-in text input code,
use a NULL hook pointer. Note: the hook cannot be replaced if
Workbench is currently requesting text to be entered;
WorkbenchControl() will stop and return with an error code of
ERROR_OBJECT_IN_USE set.
The hook will be invoked with the following parameters:
error = hookFunc(hook,reserved,message)
D0 A0 A2 A1
LONG hookFunc(struct Hook *hook,APTR reserved,
struct TextInputMsg *message);
You should return a value of 0 when your hook code has
done its job. If a value of -1 is returned, then Workbench
will drop right back into the original text input code.
The reserved parameter will always be set to NULL (V45).
NOTE: you may examine the contents of the message your hook
code receives, but they may not be changed!
The contents of the TextInputMsg look like this:
tim_Length
Size of the TextInputMsg in bytes; this may grow
in future Workbench releases.
tim_Action
This can be one the following values:
TIACTION_Rename
You will find the name of the file or drawer
to be renamed in tim_Prompt; you must ask the
user to change the name and then rename the
file or drawer in question, including the
corresponding icon, if there is one.
Note that the current directory of the process
on whose context your hook code is invoked will
be the directory in which the file/drawer to be
renamed is located.
TIACTION_RelabelVolume
You will find the name of the volume to be
relabled in tim_Prompt (the name does not
include a trailing colon); you must ask the
user to change the name and the relabel the
volume.
Note that the current directory of the process
on whose context your hook code is invoked will
be the root directory of the volume to be
relabeled.
TIACTION_NewDrawer
You will find the name of a new drawer to be
created in tim_Prompt; Workbench will have
provided a name that is not yet used by any
drawer or file in the current directory of
the process on whose context your hook code
is invoked. You must ask the user to change
the name of the drawer and then create it,
including the corresponding icon.
TIACTION_Execute
You will have to ask the user to supply the
name and parameters of a program or ARexx
to be executed, and then execute that program.
The tim_Prompt member is set to NULL and has
no meaning for this type of message.
tim_Prompt
See the descriptions for the individual actions.
Note that your code will have to perform exactly the same
duties as the built-in Workbench code. It does not merely
replace the text entry code, it replaces the entire process
associated with the respective function. (V45)
WBCTRLA_AddSetupCleanupHook (struct Hook *) -- Add a hook which
will be invoked before Workbench shuts down and after
Workbench has initialized itself.
The hook will be invoked with the following parameters:
error = hookFunc(hook,reserved,message)
D0 A0 A2 A1
LONG hookFunc(struct Hook *hook,APTR reserved,
struct SetupCleanupHookMsg *message);
The 'error' return code is used only for a special
case of message sent (see below) and will otherwise
be ignored. The reserved parameter will always be set
to NULL (V45).
NOTE: You may examine the contents of the message your hook
code receives, but they may not be changed!
The contents of the SetupCleanupHookMsg look like this:
schm_Length
Size of the SetupCleanupHookMsg in bytes; this may grow
in future Workbench releases.
schm_State
This can be one the following values:
SCHMSTATE_TryCleanup
Workbench is attempting to shut down, but there
may still be windows open on the Workbench screen
which cannot be closed. You are given the
opportunity to close any windows you may have open
before Workbench checks its own resources and verifies
that the Workbench screen can in fact be closed. If
your code requires that Workbench stays open, return
a non-zero value as the error result code (e.g.
ERROR_OBJECT_IN_USE); otherwise, return a value of 0.
NOTE: Since any of the installed hooks may signal
Workbench that it cannot be closed just yet,
it may happen that your hook will never see
a SCHMSTATE_TryCleanup message.
If one of the hooks reported that Workbench
should not be closed yet, be prepared to
receiver another message, but this time of
type SCHMSTATE_Setup; in case you let go of
all resources upon receiving the previous
SCHMSTATE_TryCleanup message, this gives
you the opportunity to reclaim them. Note
too that *all* hooks will receive this
SCHMSTATE_TryCleanup message, regardless
of whether they previously received a
SCHMSTATE_TryCleanup message or not.
SCHMSTATE_Cleanup
Workbench is about to shut down; your hook
is invoked directly before Workbench closes
all its windows and disposes of any other
resources it may have allocated. Do not delay
this process, whatever you need to do in your
hook code, do it quickly!
NOTE: The result your hook code returns will
be ignored.
Your hook may receive a SCHMSTATE_Cleanup
message without seeing a SCHMSTATE_TryCleanup
message first. This will be the case if
Workbench resets its internal state
variables; it does not indicate a Workbench
shutdown. A complete Workbench shutdown is
indicated by receiving the following messages
in exactly the order given:
SCHMSTATE_TryCleanup
SCHMSTATE_Cleanup
In other words, there will be no message of
the type SCHMSTATE_Setup to directly follow
the SCHMSTATE_TryCleanup message.
SCHMSTATE_Setup
Workbench is (again) in operational state.
Your hook is invoked right after the initialization
has completed successfully. This is your chance
to claim any resources you might need.
NOTE: The result your hook code returns will be
ignored.
You may receive any number of messages of
this type. Workbench *does not* keep track
of which hook previously received one of
the messages telling it to shut down.
Workbench will check the list of hooks already installed and
return an error in case an attempt is made to add the same
hook twice (V45).
WBCTRLA_RemSetupCleanupHook (struct Hook *) -- Remove a hook
previously installed using the WBCTRLA_AddSetupCleanupHook
tag. Workbench will verify that the hook was in fact installed
before and return an error in case the hook was never ever
installed (V45).
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().
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.
/* 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);
}
dos.library/FreeDosObject(), dos.library/IoErr(), <dos/dosextens.h>
|
