<doc>
  <legacy_id>3023</legacy_id>
  <name>relaunch</name>
  <type>message</type>
  <syntax>
    <example>relaunch <i>commandlinearguments</i></example>
  </syntax>
  <library></library>
  <objects>
    <stack/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <keyword tag="$">$ Keyword</keyword>
    <message tag="startup">startup Message</message>
  </references>
  <history>
    <introduced version="2.7.3">Added.</introduced>
  </history>
  <platforms>
    <windows/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
  </classes>
  <security>
  </security>
  <summary>After having launched an application, upon launching a successive instance the LiveCode engine will send a relaunch message to the first stack of the application.</summary>
  <examples>
    <example>on relaunch pDocument</p><p>  openDocument pDocument</p><p>end relaunch</example>
  </examples>
  <description>
    <p>The relaunch message implements support for "single instance applications" on Windows. This means that if you launch an instance of your application, a successive launch will send a message to the existing instance.</p><p/><p>It can be used in the following three ways:</p><p>    1. If the message is passed, then the new instance continues running.</p><p>    2. If "background" is returned, then the new instance is terminated.</p><p>    3. If nothing is returned but the message is not passed, then the new instance is terminated and the existing instance's "defaultStack" is made the foreground window.</p><p/><p>If there are no existing instances, the new instance will run.</p><p/><p>The relaunch message is passed a variable number of arguments depending on the command-line the new instance is started up with. The processing is the same that is performed for the $n global variables before application startup. i.e. the command-line string is split into words, each word has any leading and trailing quotes stripped and '\' is replaced by '/'.</p><p/><p>A basic example stack demonstrating the relaunch command can be found in the Resources/Examples folder within this LiveCode distribution folder.</p><p/><p><b>Note:</b> The new instance will wait for an existing instance to respond to the message before continuing.</p><p/><p><b>Note:</b> You must not initiate any modal loops (e.g. caused by answer file, popup, modal commands) within the body of the relaunch handler as this will cause an automatic 'pass'. Instead, send a message to be executed</p><p> immediately after the relaunch handler has returned (i.e. use 'send processRelaunch to me in 0 millisecs').</p><p/><p><b>Note:</b> This feature is only available in the standalone engine, as the IDE engine uses the relaunch facitily to suport loading of stack files into an existing instance of the IDE by double clicking on a file in the Windows shell.</p>
  </description>
</doc>