Various settings for the installed application class.
stationery: If true, an instance of the application will be placed in the Stationery Notebook when the application is installed. The instance will have default parameters. You can also create customized stationery instances using the STATNRY subdirectory. See appmon.h for more details.
accessory: If true, an instance of the application will be placed in the Accessories Palette. The instance will have default parameters. You can also create customized accessories instances using the ACESSRY subdirectory. See appmon.h for more details.
hotMode: If true, instances of the application are created in hot mode by default. Note that you can change a document's hot mode flag at msglnit time (or at any other time) using msgAppSetHotMode.
See app.h for more details.
allowEmbedding: If true, instances of the application allow child applications to be embedded within them. This parameter cannot be modified on a per-document basis.
confirmDelete: If true, PenPoint will ask for user confirmation before deleting any instance of the application. This parameter cannot be modified on a per-document basis.
deinstallable: If false, users will be prevented from deinstalling the application class.
120 PENPOINT API REFERENCE
Part 2 I PenPoint Application Framework
systemApp: If true, users will not see the application on the list of choices for importing documents.
lowMemoryApp: If false, users will be prevented from activating instances of the application when the system is low on memory.
fullEnvironment: If true, instance 0 of the application will have a full environment, including a resource list and floating window list. If false, these two items are destroyed, saving memory. In general, if your application does no processing in instance 0 (i.e., it simply calls AppMonitorMainO), you should set fullEnvironment to false to save unneeded memory.
typedef struct APP MGR FLAGS
U16 stationery 1;
U16 accessory 1;
U16 hotMode 1;
U16 allowEmbedding 1;
U16 confirmDelete 1;
U16 deinstallable 1;
U16 systemApp 1;
U16 lowMemoryApp 1;
U16 fullEnvironment 1;
U16 reserved1 7;
U16 reserved2 16;
APP _ MGR _FLAGS, *P_APP_MGR_FLAGS;
",. AppMgr Metrics and NEW Structure
II
Put in stationery notebook.II
Put in accessory palette.II
Create docs in hot mode.II
Allow child embedded apps.II
Confirm document deletes.II
App class deinstallable.II
Disable imports into this app.II
Allow activation under low memory.II
Initialize instance 0 environment.II
Reserved.II
Reserved.Public instance data for an installed application class. Also the new structure for creating a new installed application class.
OS_PROG_HANDLE programHandlei
U32 reserved[4]i
APP MGR FLAGS flagsi
APP MGR_METRICS, *P_APP_MGR_METRICS, APP_MGR_NEW_ONLY, *P_APP_MGR_NEW_ONLYi
msgNew
Install a new application class.
II
na: App monitor dir.Takes P _APP _MGR_NEW, returns STATUS. Category: class message.
*define appMgrNewFields classNewFields APP_MGR_NEW_ONLY
\
\ appMgri
Ar£!uments
MO$SCi£!e Arguments
APPMGR.H 121 Common #defines and typedefs
typedef struct APP_MGR_NEW { appMgrNewFields
} APP_MGR_NEW, *P_APP_MGR_NEW;
The fields you commonly set are:
pArgs->object.uid your application class's uid
pArgs->cls.pMsg your application class's method table
pArgs->cls.ancestor your application class's ancestor (usually clsApp) pArgs->cls.size size of a document's instance data
pArgs->cls.newArgsSize size of the _NEW struct for the app class pArgs->appMgr.defaultRect rectangle to open doc to when floating pArgs->appMgr.company your company's name
pArgs->appMgr.defaultDocName name of new documents of this application pArgs->appMgr.copyright copyright notice
pArgs->appMgr.flags (see description of flags above)
clsAppMgr objects cannot be locked, so clsAppMgr forces pArgs->object.key to
o.
msgNewDefaults
Initializes APP _MGR_NEW structure to default values.
Takes P _APP _MGR_NEW, returns STATUS. Category: class message.
typedef struct APP_MGR_NEW { appMgrNewFields
} APP_MGR_NEW, *P_APP~GR_NEW;
Zeroes out pArgs->appMgr and sets
pArgs->object.cap 1= objCapCall objCapSend 1 objCapScavenge;
pArgs->appMgr.flags.stationery
=
true;pArgs->appMgr.flags.accessory
=
false;pArgs->appMgr.flags.allowEmbedding
=
true;pArgs->appMgr.flags.confirmDelete
=
true;pArgs->appMgr.flags.deinstallable
=
true;pArgs->appMgr. flags. systernApp false;
pArgs->appMgr.flags.hotMode false;
pArgs->appMgr.appWinClass clsAppWin;
// Default rect: 300 x 300 points, centered in theRootWindow WIN_METRICS wm;
ObjCallRet(rnsgWinGetMetrics, theRootWindow, &wm, s);
pArgs->appMgr.defaultRect.size.w 300;
pArgs->appMgr.defaultRect.size.h 300;
pArgs->appMgr.defaultRect.origin.x
=
(wm.bounds.size.w/2)-(pArgs->appMgr.defaultRect.size.w/2);
pArgs->appMgr.defaultRect.origin.y
=
(wm.bounds.size.h/2)-(pArgs->appMgr.defaultRect.size.h/2);
122 PEN POINT API REFERENCE
Mes$t1~e Ar;~p,Hnerlt$
Part 2 / PenPoint Application Framework
msgAppMgrGetMetrics
Passes back the AppMgr metrics.
Takes P _APP _MGR_METRICS, returns STATUS. Category: class message.
#define msgAppMgrGetMetrics MakeMsg(clsAppMgr, 1) typedef struct APP MGR METRICS {
name [nameBuf Length];
version [nameBuf Length];
company [nameBuf Length];
defaultDocName[nameBufLength];
Creates a directory entry for a new document.
Takes P _APP _MGR_CREATE, returns STATUS.
II
na: App monitor dir.#define msgAppMgrCreate MakeMsg(clsAppMgr, 2) typedef struct APP_MGR_CREATE
FS LOCATOR locator;
II
Parent doc. uid must be of clsAppDir.P STRING pName;
II
in/out: Name of new app.U32 sequence;
II
Sequence of new app in parent app.BOOLEAN renumber;
II
true=update global sequence is.U32 reserved[2];
II
reserved.APP_MGR_CREATE, *P_APP_MGR_CREATE;
This message transitions a document from the Non-Existent state to the Created state.
clsAppMgr creates a new file system directory entry for the new document, using the name im pName.
clsAppMgr also stamps the new directory with the application's class.
If pName is pNull, clsAppMgr creates a unique name, based on the application name. If pName is not pNull, it points to a client-allocated buffer that must be nameBufLength bytes long.
After msgAppMgrCreate, the document will appear in the appropriate table of contents or icon window. But the application instance itself will not be created until msgAppMgrActivate, which transitions the document from the Created state to the Activated state.
stsFSNodeNotFound Invalid pArgs->locator
Comments
Arguments
Comments
APPMGR.H 123 Common #defines and typedefs
msgAppMgrActivate
Activates a document.
Takes P _APP _MGR_ACTIVATE, returns STATUS.
#define msgAppMgrActivate typedef struct APP MGR ACTIVATE
MakeMsg(clsAppMgr, 3) OBJECT wi~Dev7
II
Window device to activate app on.FS LOCATOR locator;
II
Location of doc to activate.OBJECT parent;
II
Parent doc uid.OBJECT uid;
II
out: activated doc uid.APP_MGR_ACTIVATE, *P_APP_MGR ACTIVATE;
#define stsAppMgrLowMemNoActivate MakeStatus(clsAppMgr, 3)
This message transitions a document from the Created or Dormant state to the Activated state.
clsAppMgr creates a new process for the document, and a new instance of the application class in the new process. The Application Framework will then send the new application instance msgApplnit if the document was in the Created state, or msgAppRestore if the document was in the Dormant state.
stsAppMgrLowMemNoActivate Document could not be activated due to low memory conditions.
stsFSNodeNotFound Invalid pArgs->locator.
msgAppMgrMove
Moves a document to a new location.
#define msgAppMgrMove MakeMsg(clsAppMgr, 4) typedef struct APP MGR MOVE COpy STYLE
U16 showConfirm - - 1;-
II
show confirmation UI U16 showProgress 1;II
show progress ur U16 reserved 14;II
reserved.U16 reserved2 16;
II
reserved.APP_MGR_MOVE_COPY_STYLE, *P_APP_MGR_MOVE_COPY_STYLE;
typedef struct APP_MGR_MOVE_COPY {
FS LOCATOR locator;
II
Source document location.OBJECT source;
II
Source object.OBJECT dest;
II
Destination object.XY32 xy;
II
x,y location in dest object.CHAR name[nameBufLength];11 in:out New doc name;
BOOLEAN renumber;
II
true=update global sequence is.APP_MGR_MOVE_COPY_STYLE style;
II
Move/copy style.OBJECT appWin;
II
out: move/copied appwin.APP_MGR_MOVE_COPY, *P_APP_MGR_MOVE_COPY;
clsAppMgr will display the appropriate VI to show the progress of any time-consuming moves.
If the move fails due to low memory, user cancellation, etc., msgAppMgrMove will nevertheless return a value >= stsOK. The user will have been notified of the condition via standard error messaging facilities.
msgAppMgrCopy
Copies a document to a new location.
Takes P _APP _MGR_MOVE_COPY, returns STATUS.
#define msgAppMgrCopy MakeMsg(clsAppMgr, 5)
'24 PENPOINTAPI REFERENCE
Message ArS1umenrs
MessoS1e Ar-guments
Part 2 / PenPoint Application Framework
typedef struct APP_MGR_MOVE_COPY (
FS_LOCATOR locator;
II
Source document location.OBJECT source;
II
Source object.OBJECT dest;
II
Destination object.XY32 xy;
II
x,y location in dest object.CHAR name[nameBufLength];11 in:out New doc name;
BOOLEAN renumber;
II
true=update global sequence *s.APP_MGR_MOVE_COPY_STYLE style;
II
Move/copy style.OBJECT appWin;
II
out: move/copied appwin.APP_MGR_MOVE_COPY, *P_APP_MGR_MOVE_COPY;
dsAppMgr will display the appropriate UI to show the progress of any time-consuming copies.
If the copy fails due to low memory, user cancellation, etc., msgAppMgrCopy will nevertheless return a value >= stsOK. The user will have been notified of the condition via standard error messaging facilities.
msgAppMgrFSMove
Low-level move message used internally by msgAppMgrMove.
Takes P _APP _MGR_FS_MOVE_COPY, returns STATUS. Category: internal use only.
*define msgAppMgrFSMove MakeMsg(clsAppMgr, 17) typedef struct APP_MGR_FS_MOVE_COPY
FS LOCATOR source;
II
Source doc location.FS LOCATOR dest;
II
Location of new parent doc.U32 sequence;
II
Sequence of new doc in parent doc.CHAR name[nameBufLength];11 in/out: Name of new doc.
U32 reserved[2];
II
reserved.APP_MGR_FS_MOVE_COPY, *P_APP_MGR_FS_MOVE_COPY;
msgAppMgrFSCopy
Low-level copy message used internally by msgAppMgrCopy.
Takes P _APP _MGR_FS_MOVE_COPY, returns STATUS. Category: internal use only.
*define msgAppMgrFSCopy MakeMsg(clsAppMgr, 18) typedef struct APP_MGR_FS_MOVE_COPY
FS LOCATOR source;
II
Source doc location.FS LOCATOR dest;
II
Location of new parent doc.U32 sequence;
II
Sequence of new doc in parent doc.CHAR name[nameBufLength];11 in/out: Name of new doc.
U32 reserved[2];
II
reserved.APP MGR FS MOVE_COPY, *P_APP_MGR_FS_MOVE_COPY;
msgAppMgrDelete
Deletes a document.
Takes P _APP _MGR_DELETE, returns STATUS.
*define msgAppMgrDelete typedef struct APP_MGR_DELETE
MakeMsg(clsAppMgr, 6) FS_LOCATOR locator;
II
Document to delete.BOOLEAN renumber;
II
true=update global sequence *s.U32 reserved[2];
II
reserved.APP_MGR_DELETE, *P_APP_MGR_DELETE;
This message transitions a document from the Created or Dormant state to the Non-Existent state. The document is deleted along with all of its directory nodes, embedded documents, document processes, and so on.
Arguments
APPMGR.H '125 Common #defines and typedefs
msgAppMgrRename
Renames a document.
Takes P _APP _MGR_RENAME, returns STATUS.
#define msgAppMgrRename MakeMsg(clsAppMgr, 7) typedef struct APP_MGR_RENAME
FS_LOCATOR locator;
II
Location of app to rename.P STRING pName;
II
in/out: New app name.U32 reserved[2];
II
reserved.APP _ MGR _RENAME, *P _ APP _ MGR _RENAME;
pName must point to a buffer nameBufLength long.
stsAppBadName Invalid new name.
stsAppDuplicateName Name already in use.
msgAppMgrShutdown
Unconditionally shuts down an application instance and all children.
Takes P_FS_LOCATOR, returns STATUS.
#define msgAppMgrShutdown MakeMsg(clsAppMgr, 8)
This message transitions a document from the Activated or Opened state to the Dormant state. The document is not given the opportunity to veto the shutdown. The document is sent msgAppSave before the shutdown, so it can file its data.
msgAppMgrGetRoot
Passes back the root application (clsRootContainerApp) of a tree of applications.
Takes P_APP_MGR_GET_ROOT, returns STATUS.
#define msgAppMgrGetRoot typedef struct APP_MGR_GET_ROOT
FS LOCATOR locator;
char path [fsPathBuf Length];
UUID uuid;
OBJECT app;
U32 reserved[2];
APP_MGR_GET_ROOT, *P_APP_MGR_GET_ROOT;
msgAppMgrSetlconBitmap
Specifies the large application icon bitmap.
Takes OBJECT, returns STATUS.
#define msgAppMgrSetIconBitmap
msgAppMgrSetSmalllconBitmap
Specifies the small application icon bitmap.
Takes OBJECT, returns STATUS.
#define msgAppMgrSetSmallIconBitmap
MakeMsg(clsAppMgr, 9)
II
Location of app.II
out: Path to root.II
out: Root uuidiII
out: Root app. objNull if inactive.II
reserved.MakeMsg(clsAppMgr, 10)
MakeMsg(clsAppMgr, 11)
126 PENPOINT API REFERENCE
Part 2 I Pen Point Application Framework
msgAppMgrRevert
Reverts a document to its most recently filed copy.
Takes P _FS_LOCATOR, returns STATUS.
#define msgAppMgrRevert
msgAppMgrRenumber
Renumbers an application heirarchy.
Takes P_FS_LOCATOR, returns STATUS.
#define msgAppMgrRenumber
MakeMsg(clsAppMgr, 12)
MakeMsg(clsAppMgr, 13) The FS_LOCA TOR must be a locator for a clsRootContainerApp.
msgAppMgrDumpSubtree
Dumps the attributes of a subtree of documents.
Takes P _FS_LOCA TOR, returns STATUS.
#define msgAppMgrDumpSubtree MakeMsg(clsAppMgr, 14)
The information is output to the debug window or device. The dumped fields for each node are:
• document name
• UUID (low 32 bits followed by high 32 bits)
• old UUID (low 32 bits followed by high 32 bits)
• application class
• number of children
• sequence number
msgAppMgrGetResList
Creates a resource list, given an application UUID.
Takes P_APP_MGR_GET_RES_LlST, returns STATUS.
#define msgAppMgrGetResList MakeMsg(clsAppMgr, 15) typedef struct APP MGR GET RES LIST {
UUID appuuID; -
II-App
uuid.OBJECT resList;
II
in/out: resource file list.APP_MGR_GET_RES_LIST, *P_APP_MGR_GET_RES_LIST;
The resource list will contain the document resource file, the application resource file, the preference resource file, and the system resource file. resList should be set to objNull or a well-known uid.
APPMON.H
This file contains the API definition for clsAppMonitor.
clsAppMonitor inherits from clsApp.
Provides the standard behavior for an application's monitor object.
You create an application monitor when you call AppMonitorMain from your main routine, when processCount is zero. An application monitor drives application installation and helps with deinstallation. It also controls displaying global application options, maintaining global state, and importing files.
You should subclass clsAppMonitor if your application needs to do a more sophisticated installation (such as installing shared dictionaries or data files), to support file import, to set and save global application configurations, and to provide file converters. See the section below on Subclassing.