Home / Autodocs / workbench.library
NAME
- OpenWorkbenchObjectA
-
Open a drawer or launch a program as if the user had double-clicked on an icon. (V44)
SYNOPSIS
success = OpenWorkbenchObjectA(name,tags)
BOOL OpenWorkbenchObjectA(STRPTR name,struct TagItem *tags);
success = OpenWorkbenchObject(name,...);
BOOL OpenWorkbenchObject(STRPTR name,...);
D0 A0 A1
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.
TAGS
- WBOPENA_ArgLock (BPTR)
-
Corresponds to the WBArg->wa_Lock entry of a WBStartup message, to be sent to a program to be launched. The lock you provide will be duplicated when it is put into a WBArg list.
The WBOPENA_ArgLock determines the lock parameters to be associated with all following WBOPENA_ArgName tags.
This tag defaults to NULL.
- WBOPENA_ArgName (STRPTR)
-
Corresponds to the WBArg->wa_Name entry of a WBStartup message to be sent to a program to be launched. This tag can be used to construct a list of parameters to pass to the tool/project to be launched. It works in conjunction with the WBOPENA_ArgLock tag. The name you provide will be duplicated when it is put into a WBArg list.
- WBOPENA_Show (UBYTE)
-
If opening a drawer, change its show mode. You can either have the drawer show all files (DDFLAGS_SHOWALL) or only icons (DDFLAGS_SHOWICONS). If the drawer in question is already open, its show mode will be changed, too. This may result in the drawer's contents getting reread. Note that if you specify a show mode that is not among DDFLAGS_SHOWALL..SHOWICONS no change will occur; (V45)
- WBOPENA_ViewBy (UBYTE)
-
If opening a drawer, change its view mode. You can view the contents as icons (DDVM_BYICON), sorted by name (DDVM_BYNAME), sorted by date (DDVM_BYDATE), sorted by size (DDVM_BYSIZE) or by type (DDVM_BYTYPE). If the drawer in question is already open, its view mode will be changed, too. Note that if you specify a view mode that is not among DDVM_BYICON..BYTYPE no change will occur; (V45)
RESULT
- 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().
EXAMPLE
/* Launch Multiview with S:Startup-Sequence as its parameter. */
OpenWorkbenchObject("MultiView",
TAG_DONE);
/* Launch the application "Paint" with the project files "Image1"
OpenWorkbenchObject("Paint",
TAG_DONE);
/* Launch the application "Paint" with the project files "Image1"
OpenWorkbenchObject("Paint",
TAG_DONE);
OpenWorkbenchObject("MultiView",
WBOPENA_ArgLock, Lock("S:",SHARED_LOCK),
WBOPENA_ArgName, "Startup-Sequence",
WBOPENA_ArgName, "Startup-Sequence",
/* Launch the application "Paint" with the project files "Image1"
* and "Image2", which are both found in the drawer "Paint:Pictures".
*/
*/
WBOPENA_ArgLock, Lock("Paint:Pictures",SHARED_LOCK),
WBOPENA_ArgName, "Image1",
WBOPENA_ArgName, "Image2",
WBOPENA_ArgName, "Image1",
WBOPENA_ArgName, "Image2",
/* Launch the application "Paint" with the project files "Image1"
* and "Anim1", which are both found in the drawers "Paint:Pictures"
* and "Paint:Animations", respectively.
*/
* and "Paint:Animations", respectively.
*/
WBOPENA_ArgLock, Lock("Paint:Pictures",SHARED_LOCK),
WBOPENA_ArgName, "Image1",
WBOPENA_ArgLock, Lock("Paint:Animations",SHARED_LOCK),
WBOPENA_ArgName, "Anim1",
WBOPENA_ArgName, "Image1",
WBOPENA_ArgLock, Lock("Paint:Animations",SHARED_LOCK),
WBOPENA_ArgName, "Anim1",
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).
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).
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.
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.