SWF Army Knife™ (pronounced "Swiff Army Knife") is a “shell” program that runs around your SWF file. The SWF file will contain all interface and interactivity elements, but SAK is there for doing things that Flash cannot. At runtime, SAK imports “Main.swf” and sets itself to the window dimensions of the SWF. It then sends to various required variables in the SWF file information that is helpful in the process of communicating with SAK. For SAK to run properly a number of specific variables and functions must be present in the root timeline when the SWF starts up. You can see these in the provided sample flash file “Main.fla” .

Special notes about the use of SAK.

The SWF file associated with SAK must be named “Main.swf” and can either be located in the same folder as the SAK executable or in a subfolder called “data”. Any other name or location will cause a runtime error. This is set up so you can have the Mac/PC executables in the root folder of your cd rom and all other files can be located in subfolders.

To call an SAK function:

1) Set sakReturnVar = “” to reset its value.

2) Assign appropriate values to gSendVar array. SAK will read these for processing your function request.

3) Call appropriate getURL(“event:sakFunctionGoesHere”)

When SAK is finished processing a request, it performs the following actions:

(see code examples and explanations below)

The return value is written to “sakOutput.txt” (if debugMode is true).
sakReturnVar is set to the returned value.
sakReturn() is called.
sakDone variable is set to “true”

SAK uses getURL(“event:commandName”) to call functions in SAK. Please note that getURL() is read at the end of a series of functions no matter what order it is placed in. For this reason, to use functions that return a value that you will be using, there are a few different ways to make Flash wait for SAK to process a return.

Use setInterval() function with an if statement that checks to see if sakDone = “true” . If it is, you can now process the returned value in sakReturnVar.
Place commands in separate frames of a movie clip. Ex:

Frame 1 set sakDone = “false”, assign correct variables to gSendVar, call getURL function.
Frame 2 leave blank
Frame 3 on enterframe check for sakDone = “true”, if not, then gotoAndPlay(_currentframe - 1). If it is true then go to the next frame.
Frame 4 process the information returned in sakReturnVar
Use the provided switch/case function sakReturn(). This function is always called by SAK whether it is used or not and has been provided for added functionality and options.

You can use any or all of these methods in any combination to help process the information returned. Examples are in the provided Main.fla file.

//REQUIRED VARIABLES WITH EVERY USE OF SWF Army Knife™//

(Explanation precedes item)

//setting gExitLock to true will disable esc key from quitting program

var gExitLock = true;

//setting gFullScreen to true will have program start in full screen mode.

var gFullScreen = true;

//setting gWindowToggle to true will activate the TAB key to toggle between fullscreen and window mode.

var gWindowToggle = true;

// setting gBGTransparent to true will allow only objects to be opaque against the SAK background color.

//**Note, this does not mask out the window and it could cause a performance problem if your flash program has heavy animation.

// If you are encountering performance lags in your animation, make sure this is set to false and retry.

var gBGTransparent = true;

//Item Delimeter based on platform. If MacOS, ID = ":" if Windows, ID = "\\" This is set by SWF Army Knife™ at runtime. When using windows

“\” slashes in flash string, always use double slashes”\\” so it does not drop it when passed across. ID is automatically set to “\\” on windows.

var ID:String;

//variables to send to SWF Army Knife™. Array that is to be set each time SAK function called.

var gSendVar = [ ];

// This variable is set to true by SWF Army Knife™ when it has finished. You can use this to signal that it is done. This should be set to false just prior to calling a SAK function.

var sakDone = false;

//SWFPath is assigned by SWF Army Knife™. It is the path to the current instance of SWF Army Knife™. String path returned.

var SWFPath;

// When DebugMode is set to true and the program is not located on a locked drive then return values will be written to a file called "sakOutPut" in the same folder as SWF Army Knife™.

var sakDebugMode = true;

//If myCommand variable is used, it will be returned in the output file to accompany the return value.

var myCommand;

// SWF Army Knife™ returns all values to this variable.

var sakReturnVar = "";

//*******************************************************//

function sakReturn() {

////// check which command entered and perform function based on command. Not all commands are here, only the commands whose purpose is to return a value. You can add as you need. /////

switch (myCommand) {

case 'gFileOpenDialog' :

//enter function here//

break;

case 'gFileSaveAsDialog' :

//enter function here//

break;

case 'gGetFileNameInFolder' :

//enter function here//

break;

case 'gFileExists' :

//enter function here//

break;

case 'gFolderSelectDialog' :

//enter function here//

break;

case 'gVolumeSelectDialog' :

//enter function here//

break;

case 'gVolumeGetFreeBytes' :

//enter function here//

break;

case 'gVolumeGetTotalBytes' :

//enter function here//

break;

case 'gVolumeIsRemovable' :

//enter function here//

break;

}

////// END REQUIRED VARIABLES AND FUNCTION/////

Windows and Macintosh Platform Notes

SAK has been programmed to work the same on both platforms.

System support:

MacOSX (classic and OS9 may work but not supported)

Windows 2000/XP (98 and ME may work but not supported)

Macromedia Flash MX/MX2004

Due to the difference in path delimeters between Mac and Windows, two variables “sakPath” and “ID” have been provided and are assigned at runtime based on the user’s current system. SakPath will contain the full path with correct delimeters to the currently running SAK. Windows path delimeter is “ \ ” but in Flash strings, this character must be doubled or it will be interpreted as a special character, therefore ID is returned as “ \\ ” on windows platform. SAK functions that return a full path to a file or folder have the option of returning as “Flash safe” with double slashes for immediately plugging the path into a function or as a normal path with single slashes.

When you download SAK, you will get two versions – 1 Macintosh and 1 Windows compatible executable. Functionality will all be the same, and you can name them anything you desire or change the icons for CD ROM distribution. It is recommended that you keep a clean copy of the programs and sample movie in a safe place.

Debugging SAK in Author mode

When sakDebugMode is set to true and the program is not located on a locked drive then return values will be written to a file called "sakOutput.txt" in the same folder as SWF Army Knife™. A recommended method of using this file is to open this file with a web browser and hit refresh/reload each time you want to view the results. Each time SAK is started up, “sakOutput.txt” starts over.

Sample Movie notes

Provided with the SAK program is a sample movie with all available functions set up in either buttons or root variables, depending on the requirements. This movie sets the button text at runtime, so opening the flash file will look like a series of blank green buttons. If you click on each button, the property bar will display the button name, which serves as the text of that button and also the command which is sent to SAK when it is clicked. If you now look at the actions panel, you will see myVariables being given its values as well as an explanation of what values need to be provided and where. This information is sent to the root variable gSendVar, where SAK will read them in and process them when the appropriate function is called. If you double-click on a button, you will see the following:

on (press) {

// reset variable

_root.sakReturnVar = "";

// myCommand will be returned in sakOutPut.txt to make it easier to tell what each value refers to.

_root.myCommand = this._name;

// load myVariables into gSendVar at root. SWF Army Knife™ will get its variables from this to process the getURL command

// You don't need myVariables variable, it is just how it was done for this example.

_root.gSendVar = this.myVariables;

// Call function in SWF Army Knife once gSendVar has been assigned. getURL is always read last so if you are processing a return

// value, you need to make flash wait for SWF Army Knife™ to return the value.

getURL("event:"+_root.myCommand);

}

The first command _root.sakReturnVar = ""; resets the variable on the root timeline to an empty string. SAK will return any values returned to this variable. This does not necessarily need to be done, because SAK replaces the entire string when it returns a value. If there is a conflict in returned values though, inserting this command may clear it up.

Setting _root.myCommand is what the sakReturn() function uses to determine what actions to take. It is also helpful in debugging your program because the value of myComand will be printed before the value that is added to the debug file “sakOutput.txt” to identify what function is producing which returned value. An example return will look like this: “(gFolderCreate) 1“ if myCommand is set and will only read “1” if it is not. As you can see here, myCommand is getting its value from the instance name of the particular button that was pushed. myCommand must be set any time you require a return value from SAK.

The third command, _root.gSendVar = this.myVariables; is an abstraction which gathers the variables from the host button that was clicked on, and then this sends it to gSendVar in the root timeline. You can just as easily set this to _root.gSendVar = [var1, var2]; if you are calling this on its own without the added abstraction. gSendVar MUST receive the correct variables or SAK cannot process the command correctly. Read the notes carefully for each command.

The final command is the one that calls the function to SAK after the variables have been set. This too is abstracted, but using the myCommand value. It could have been written like this though: getURL("event:gAlert”); The abstraction is convenient since myCommand needed to be set anyway.

The sample movie was set up this way merely for convenience. The root timeline has examples of functions set up without the various abstractions that are present in the buttons.

All of the buttons have been tested and work, the way they are set up, some require a certain order for them to be performed in for them to work correctly. For instance, gFolderCreate must be clicked before gFolderRename can be called or there will be no folder to be renamed. gfolderDelete then looks for the renamed folder and deletes that. gFolderCopy requires that you click on gFolderCreate and then you can click on gFolderMove and they will now work. Take a look at the variables provided and you will understand the order that they were set up in.

Functions ---------------------------------------------------------------------------------------------

gOpenFile

Opens a document, with the application that it is associated with.

Number of variables: 2 [ FileName , State ]

//notes: FileName = Full path to file.

State choices:

//"Normal" shows in its usual state.

//"Hidden" is not visible.

//"Maximised" shows as a maximised window.

//"Minimised" shows as an minimised icon.

//ex:

myVariables = [_root.SWFPath+ "testFiles"+_root.ID+"Test_PDF.pdf", "Maximised"];

Returns: Integer. >32 it was successful. < 32 is an error.

gCopyFile

Copies file to new name and/or location.

//Number of variables: 2 [currentFilePath, pathToCopyTo]

//ex:

myVariables = [“D:\\Test_PDF.pdf", “C:\\Test_PDF_copy.pdf"];

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFileRename

Renames file.

//Number of variables: 2 [currentFileName, newFileName] (full path to file names are required)

//notes: For safety, SWF Army Knife™ will only allow renaming files that were created or copied during the current session.

//ex:

myVariables = [“C:\\Test_PDF_copy.pdf", “C:\\Test_PDF_renamed.pdf"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gDeleteFile

Deletes named file.

//Number of variables: 1 [filePath]

//notes: For safety, SWF Army Knife™ will only allow deleting files that were created or copied during the current session.

//ex:

myVariables = [_root.SWFPath+ "copyfolder"+_root.ID+"Test_PDF_renamed.pdf"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFileMove

Moves file within the same drive.

//Number of variables: 1 [originalFilePath, newFilePath]

//notes: For safety, SWF Army Knife™ will only allow moving files that were created, renamed or copied during the current session.

//ex:

myVariables = [“C:\\fileName.pdf", “C:\\newFolder\\ fileName.pdf"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFileOpenDialog

Opens standard file open dialog.

//Number of variables: 2 [initialPath, convertToFlashSafePath]

//notes:(convertToFlashSafePath determines whether or not to convert to a flash safe file path with "\\" instead of "\" values are "true" or "false")

//ex:

myVariables = [_root.SWFPath,"true"]

Returns String: full path to selected file. It does not actually open it.

------------------------------------------- Table of Contents ------------------------------------------

gFileSaveAsDialog

Opens standard file save dialog.

//Number of variables: 5 [initialFolder, fileName, dialogBoxPromptText, forceOverWrite, convertToFlashSafePath]

//notes:(convertToFlashSafePath determines whether or not to convert to a flash safe file path with "\\" instead of "\" values are "true" or "false")

//ex:

myVariables = [_root.SWFPath, "myFile", "Enter a file name", "true", "true"]

Returns String: full path to named file. It does not actually save anything.

------------------------------------------- Table of Contents ------------------------------------------

gPrintDocument

Sends named file to printer.

//Number of variables: 1 [filePath]

//notes: tries to determine default program to open file in and then prints from that program

//ex:

myVariables = [_root.SWFPath+ "testFiles"+_root.ID+"Test_PDF.pdf"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFileRunApp

Runs either Windows ” .exe” or Mac” .app” file.

//Number of variables: 1 [appPath]

//ex:

if (_root.ID == ":") { //Mac platform

myVariables = [_root.SWFPath+"testFiles"+_root.ID+"testRunApp.app"];

} else {

myVariables = [_root.SWFPath+"testFiles"+_root.ID+"testRunApp.exe"];

}

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFileExists

Checks to see that file exists.

//Number of variables: 1 [filePath] Full path should be used.

//ex:

myVariables = [“C:\\Test_PDF.pdf"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gLinkCreate

Creates a shortcut (Windows) or alias (Macintosh) for the file(filePath) at designated location.

//Number of variables: 2 [filePath, locationToCreateLink]

//notes: creates shortcut(win) or alias(mac) of selected file in locationToCreateLink.

//ex:

if (_root.ID == ":") {  //Mac Platform

myVariables = [“MacHD:testRunApp.app", MacHD:copyFolder"];

} else {

myVariables = [“C:\\testRunApp.exe", “C:\\copyFolder"];

}

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gGetFileNameInFolder

Searches and returns the file designated by fileNumber.

//Number of variables: 2 [pathToFolder, fileNumber]

//notes:

//ex:

myVariables = [“C:\\FolderName”, 4]

Returns String: name of specified file number in folder.

------------------------------------------- Table of Contents ------------------------------------------

gGoToNetPage

Launches designated URL. Since getURL is usurped by SAK for its actions, this replaces the normal getURL command for web addresses. Opens in system default browser.

//Number of variables: 1 [URL] (URL must be full URL or can be relative if located on http or ftp server.)

//ex:

myVariables = ["http://www.anigem.com"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFolderSelect

Opens system standard folder select dialog.

//Number of variables: 1 [convertToFlashSafePath]

//notes:(convertToFlashSafePath determines whether or not to convert to a flash safe file path with "\\" instead of "\". Values are "true" or "false")

//ex:

myVariables = ["true"]

Returns String: Full path to specified folder. Ends with platform delimeter.

------------------------------------------- Table of Contents ------------------------------------------

gFolderCreate

Create folder in designated location. Following example is a cross-platform call using path and delimeters designated by SAK at runtime.

//Number of variables: 1 [folderPath]

//ex:

myVariables = [_root.SWFPath+ "copyFolder"+_root.ID+"testFolder"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFolderRename

Rename specified folder.

//Number of variables: 2 [currentFileName, newFileName] (full or relative paths required)

//notes: For safety, SWF Army Knife™ will only allow renaming folders that were created or copied during the current session. Following example is a cross-platform call using path and delimeters designated by SAK at runtime.

//ex:

myVariables = [_root.SWFPath+ "copyFolder"+_root.ID+"testFolder", _root.SWFPath+ "copyFolder"+_root.ID+"testFolder_renamed"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFolderDelete

Deletes specified folder.

//Number of variables: 1 [folderPath]

//notes: For safety, SWF Army Knife™ will only allow deleting folders that were created or copied during the current session. Following example is a cross-platform call using path and delimeters designated by SAK at runtime.

//ex:

myVariables = [_root.SWFPath+ "copyFolder"+_root.ID+"testFolder_renamed"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFolderCopy

Copy folder and files within to new location.

//Number of variables: 3 [currentFolder, newFolder, copySubFoldersTrueOrFalse] (copies all files within currentFolder to newFolder)

//notes: If copySubFoldersTrueOrFalse is set to true, all subfolders and their contents will be copied as well. Following example is a cross-platform call using path and delimeters designated by SAK at runtime.

//ex:

myVariables = [_root.SWFPath+"copyfolder"+_root.ID+"testFolder", _root.SWFPath + "testFolder", "true"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gFolderMove

Move folder and files to new location on same drive.

//Number of variables: 2 [currentFolderLocation, newFolderLocation]

//notes: Folders can only be moved within the same drive. Use copyFolder to copy between two different drives. Following example is a cross-platform call using path and delimeters designated by SAK at runtime.

//ex:

myVariables = [_root.SWFPath+"copyfolder"+_root.ID+"testFolder", _root.SWFPath+"testFolder"]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gVolumeSelectDialog

Opens system standard volume select dialog.

//Number of variables: 1 [dialogBoxTitle]

//ex:

myVariables = ["Choose a volume"]

Returns: String: Name of selected volume.

------------------------------------------- Table of Contents ------------------------------------------

gVolumeGetFreeBytes

Returns number of free bytes on named drive.

//Number of variables: 1 [volumeName]

//ex:

myVariables = [“C:\\”];

Returns: Integer

------------------------------------------- Table of Contents ------------------------------------------

gVolumeGetTotalBytes

Returns number of total bytes on named drive.

//Number of variables: 1 [volumeName]

//ex:

myVariables = [“C:\\”]

Returns: Integer

------------------------------------------- Table of Contents ------------------------------------------

gVolumeIsRemovable

Determines whether named drive is removable ie: cdrom, dvdrom, etc.

//Number of variables: 1 [volumeName]

//ex:

myVariables = [_root.SWFPath]

Returns: Integer: True (1) if removable, False (0) if not removable.

------------------------------------------- Table of Contents ------------------------------------------

gVolumeEject

Ejects specified drive.

//Number of variables: 1 [volumeName]

//ex:

myVariables = [“D:\\”]

Returns: Integer: True (1) if successful, False (0) if an error occurs

------------------------------------------- Table of Contents ------------------------------------------

gAlert

Throws system alert with designated text.

//Number of variables: 1 [textToAlert]

//ex:

myVariables = ["this is a flash alert"];

Returns nothing

------------------------------------------- Table of Contents ------------------------------------------

gAbout

Throws system alert with SWF Army Knife™ information.

//Number of variables: 0

Returns String: SWF Army Knife™ version info.

------------------------------------------- Table of Contents ------------------------------------------

gQuit

Quits SAK.

//Number of variables: 0

Returns nothing

------------------------------------------- Table of Contents ------------------------------------------

gBGColor

Sets SAK background color to color designated by RGB values.

//Number of variables: 3 - [r,g,b] values

//ex:

myVariables = [200,5,20]

Returns nothing

------------------------------------------- Table of Contents ------------------------------------------

gFullScreen

Switches SAK to either Full Screen mode, (SAK background color covering all of monitor 1 and SWF file stretched to height of monitor 1 and with width proportionally sized), or window mode(SAK window sized to SWF dimensions. With option of titleBar visible or invisible.)

//Number of variables: 2 – [windowMode, titlebar] windowMode (false = fullscreen), titleBar visible = true/false

//Notes: if windowMode set to false, titleBar is automatically hidden and flash program is scaled proportionally to height of monitor. If windowMode set to true, 2nd variable determines whether the titlebar will be visible or not.

//ex:

myVariables = ["true", "false"]

Returns nothing

------------------------------------------- Table of Contents ------------------------------------------