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 » OpenWorkbenchObjectA
OpenWorkbenchObjectA -- Open a drawer or launch a program as if
the user had double-clicked on an icon. (V44)
success = OpenWorkbenchObjectA(name,tags)
D0 A0 A1
BOOL OpenWorkbenchObjectA(STRPTR name,struct TagItem *tags);
success = OpenWorkbenchObject(name,...);
BOOL OpenWorkbenchObject(STRPTR name,...);
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.
name -- Name of the object to be opened; this can be a drawer
name, a tool name or a project name.
tags -- Additional options.
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 -- 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().
/* 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);
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).
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.
dos.library/IoErr(), workbench.library/CloseWorkbenchObjectA(), <workbench/startup.h>
|
