a1200   NEWS   APPS   DOCS   ABOUT
a1200
----
a1200
----
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

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)
D0 A0 A1
BOOL OpenWorkbenchObjectA(STRPTR name,struct TagItem *tags);
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",
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);

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

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.

SEE ALSO

dos.library/IoErr(), workbench.library/CloseWorkbenchObjectA(), <workbench/startup.h>

Comments

Name:
E-mail: Use this if you want a message if you get a response, will not be shown.
Comment:
Select correct short for:

Spaceballs

SPB
PDX
SNT
HZ

Comments:

$VER: d0.se 1.14 Copyright © 2011-2020 Tobias Geijersson support at d0 dot se