--- a/ApplicationModel.st	Wed Jul 23 15:47:25 2008 +0200
+++ b/ApplicationModel.st	Thu Jul 31 15:21:05 2008 +0200
@@ -97,6 +97,43 @@
         StandardSystemView
         WindowGroup DeviceWorkstation
 "
+!
+
+howToDealWithMultipleApplicationInstances
+"
+    The following relates to StandAlone applications (i.e. compiled exe's) only.
+    If the user attempts to open another of the applications documents (after the first instance
+    of the application has already been opened), it is sometimes required to notify the first
+    application about this and to ask it to open an extra window on the second-clicked document.
+    In other words: to get another of the first instances' windows instead of opening a window
+    by the second application.
+
+    This is implemented via the following mechanism (see StandaloneStartup):
+        the first application instance leaves the information about its existence somewhere
+            (under win32: in the registry, the window-ID of its main window is remembered;
+             under unix, its stored into a locked file).
+        a mutex is created to prevent a race on this informationduring startup
+            (under win32: a mutex proper; under unix, the above locked file will do)
+
+    when the app is started the second time, it will not be able to aquire the mutex (and therefore
+    knows, that its the second instance). It will then send an event-message (win32: via copyData;
+    unix. via sendClientEvent), to the first instance and pass the fileName of the document which
+    is to be opened. The first instance receives this event and opens another window for it.
+    The second instance simply exits and stops execution.
+    This guarantees that only one instance of an application is executing (if desired).
+
+    The implementation is found in:
+        StandaloneStartup:
+            checkForAndExitIfAnotherApplicationInstanceIsRunning
+
+        here:
+            processOpenPathCommand:aFilename
+
+    By default, the event is ignored - subclasses which want to support that behavior MUST
+    redefine processOpenPathCommand: in ApplicationModel and also make sure that
+    checkForAndExitIfAnotherApplicationInstanceIsRunning is called for in StandaloneStartup.
+            
+"
 ! !
 
 !ApplicationModel class methodsFor:'initialization'!
@@ -3041,6 +3078,13 @@
 copyDataEvent:parameter eventData:msgData
     "a client message - very Win32 specific and only useful for special applications.
      Subclasses prepared to receive them should redefine this method"
+
+    |messageStream command argument|
+
+    messageStream := msgData asString readStream.
+    command := messageStream upTo: $:.
+    argument := messageStream upTo: Character null.
+    self processApplicationCommand:command with:argument
 !
 
 dispatchEvent:event
@@ -3129,6 +3173,25 @@
     "Modified: / 18.6.1998 / 19:14:16 / cg"
 !
 
+processApplicationCommand:command with:argument
+    "a message from a secondary application instance (the exe has been started again).
+     Typically, the command is one like 'openPath:', as generated in StandaloneStartup."
+
+    command = 'openPath' ifTrue:[
+        self processOpenPathCommand:argument.
+        ^ self.
+    ].
+
+    Transcript showCR: 'Invalid command received: ', command.
+!
+
+processOpenPathCommand:argument
+    "a message from a secondary application instance (the exe has been started again)
+     to open another window on document as found in the pathName argument.
+     Left blank (i.e. ignored) here, but can be redefined to open up another application
+     editor window if supported."
+!
+
 requestForWindowClose
     "the applicationWindow wants to know, if a close
      is ok. Return false if not."
@@ -3172,7 +3235,7 @@
 !ApplicationModel class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libview2/ApplicationModel.st,v 1.257 2008-07-23 13:47:25 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libview2/ApplicationModel.st,v 1.258 2008-07-31 13:21:05 cg Exp $'
 ! !
 
 ApplicationModel initialize!