Capturing command-line arguments

Back to: Apollo Documentation home page

An Apollo application receives command-line arguments through invocation events. An invocation event is dispatched whenever the operating system starts or attempts to start a given Apollo application. If command-line arguments are supplied, the InvokeEvent object will contain an Arguments array containing the argument values.

With the InvokeEvent, you can:

• Get command-line arguments
• Get the directory from which an application was launched
• Get the path to the file that triggered the application invocation
• Get command-line arguments from subsequent invocations of an application

Contents
Invocation Event basics Getting command-line arguments Getting the directory from which an application was launched Getting the path to a file that triggered the application invocation Getting command-line arguments from subsequent invocations of an application SWF-based invocation event example HTML-based invocation event example

---

Invocation Event basics

An invocation event is dispatched to your application whenever it is invoked (for example, by a user double-clicking the application icon in the desktop environment). Only one instance of an Apollo application will be started. On subsequent invocations, Apollo will dispatch a new invocation event to the running instance.

Your application can receive invocation events by registering a listener with its Shell object:

Shell.shell.addEventListener(InvokeEvent.INVOKE,onInvokeEvent);

And add an event handler:

var arguments:Array;
var currentDir:File;
public function onInvokeEvent(invocation:InvokeEvent):void{
    arguments = invocation.arguments;
    currentDir = invocation.currentDirectory;
}

Note: Until a listener is registered, invocation events are queued, not discarded. As soon as a listener is registered, all the queued invocation events will be delivered.

Getting command-line arguments

The InvokeEvent.arguments property contains an array of the arguments passed by the operating system when an Apollo application is invoked. If the arguments contain relative file paths, you can typically resolve the paths using the currentDirectory property.

Arguments to a program are treated as white-space delimited strings, unless quoted with double quotes:

Arguments	Array
foo bar	{foo,bar}
foo "foo bar"	{foo,foo bar}
"foo" “bar?	{foo,bar}
\"foo\" \"bar\"	{"foo","bar"}

Note: The Mac OS X Finder automatically passes the process serial number as an argument with the form -psn_NNN (where NNN is the process serial number).

Getting the directory from which an application was launched

The InvokeEvent.currentDirectory property contains a File object representing the directory from which the application was launched.

Getting the path to a file that triggered the application invocation

When an application is invoked because a file of a type registered by the application is opened, the native path to the file is included in the command-line arguments as a string. (It is your application’s responsibility to open or perform the intended operation on the file.)

Note: Automatic file registration is not supported in this Apollo Alpha release.

Getting command-line arguments from subsequent invocations of an application

The new InvokeEvent object dispatched for each subsequent invocation of your application contains the command line arguments and invocation directory.

SWF-based invocation event example

The following example demonstrates how to register listener for and handle the InvokeEvent. The example logs all the invocation events received and displays the current directory and command-line arguments.

<?xml version="1.0" encoding="utf-8"?>
<mx:ApolloApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
    applicationComplete="init()" title="Invocation Event Log">
    <mx:Script>
    <![CDATA[
    import flash.events.InvokeEvent;
    import flash.system.Shell;

    public function init():void{
        Shell.shell.addEventListener(InvokeEvent.INVOKE,onInvoke);
    }
		
    public function onInvoke(invokeEvent:InvokeEvent):void{
        var now:String = new Date().toTimeString();
        logEvent("Invoke event received: " + now);
				
        if(invokeEvent.currentDirectory != null){
            logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath);
        } else {
            logEvent("--no directory information available--");
        }
				
        if(invokeEvent.arguments.length > 0){
            logEvent("Arguments: " + invokeEvent.arguments.toString());
        } else {
            logEvent("--no arguments--");
        }
    }
			
    public function logEvent(entry:String):void {
        log.text += entry + "\n";
        trace(entry);
    }
    ]]>
    </mx:Script>
    <mx:TextArea id="log" width="100%" height="100%" editable="false"
        valueCommit="log.verticalScrollPosition=log.textHeight;"/>
</mx:ApolloApplication>

HTML-based invocation event example

The following example demonstrates how to register listener for and handle the InvokeEvent. The example logs all the invocation events received and displays the current directory and command-line arguments.

<html>
<head>
<title>Invocation Event Log</title>
<script type="text/javascript"><!-- 
  
function appLoad(){
    if(window.runtime){
        runtime.trace("Invocation Event Log.");
        runtime.flash.system.Shell.shell.addEventListener(
                   runtime.flash.events.InvokeEvent.INVOKE,onInvoke);
    }
}
  
function onInvoke(invokeEvent){
    logEvent("Invoke event received.");
    if(invokeEvent.currentDirectory){
        logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath);
    } else {
        logEvent("--no directory information available--");
    }
				
    if(invokeEvent.arguments.length > 0){
        logEvent("Arguments: " + invokeEvent.arguments.toString());
    } else {
        logEvent("--no arguments--");
    }
}
  
function logEvent(message){
    var logger = document.getElementById('log');
    var line = document.createElement('p');
    line.innerHTML = message;
    logger.appendChild(line);
		
    if(window.runtime){
        runtime.trace(message);
    }
}

window.unload = function(){
    if(window.runtime){
        runtime.flash.system.Shell.shell.removeEventListener(
                runtime.flash.events.InvokeEvent.INVOKE,onInvoke);
    }
}

--></script>
</head>

<body onLoad="appLoad();">
    <div id="log"/>
</body>
</html>

---

Back to: Apollo Documentation home page