WorkbenchControlA

Query or modify Workbench and icon options. (V44)

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

see next

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

WBCTRLA_GetDiskInfoHook (struct Hook **)

Obtain the hook that will be invoked when Workbench detects an unreadable disk, such as a a MS-Dos formatted disk unreadable for the the DF0: handler. This hook may then decide what to do about the drive, i.e. whether a the drive is to be shown or not. This hook may be NULL which makes the workbench use the default algorithm, i.e. show the "disk unreadable" icon. (V47)

WBCTRLA_SetDiskInfoHook (struct Hook *)

Install the hook that will be invoked when Workbench detects an unreable disk, such that a Amiga formatted disk unreadable by CrossDos. To make Workbench use the default algorith, which is to show the "Unreadable" icon, pass a NULL here. Note: the hook cannot be replaced if it is currently used. WorkbenchControl() will then stop and return with ERROR_OBJECT_IN_USE set.

The hook will be invoked with the following parameters:

state = hookFunc(hook,info,msgport)

D0 A0 A2 A1

where "info" is of type "struct InfoData *" (see <dos/dos.h>) that was already retrieved from the handler with all values filled in, and msgport is of type "struct MsgPort *", which points to the communication message port of the handler from which this information was obtained and is to be modified by the hook. The returned state is the value of id_DiskState to be used instead. If the value from info->id_DiskState is passed out, then the disk will remain to be shown as "Unreadable". If instead ID_NO_DISK_PRESENT is returned, the icon will be hidden. (V47)

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.

dos.library/FreeDosObject dos.library/IoErr <dos/dosextens.h>