Buddy API 4

Buddy API is an Xtra for use with Adobe Director and Authorware which allows access to system functions. This help file covers version 4 of both Windows and Macintosh Buddy API.

Installation

Registration

Distributing your applications

Loading Buddy API Functions

What's new in this release

Important Information

You should carefully read the following terms and conditions before using this software. Your use of this software indicates your acceptance of these terms and conditions.

Disclaimer of Warranty

This software and the accompanying files are provided "as is" and without warranties as to performance of merchantability or any other warranties whether expressed or implied.

The user must assume the entire risk of using Buddy API.

Copyright

Buddy API Copyright © 1995-2008 Magic Modules Pty Ltd

All rights reserved.

Contact

All enquiries, including support, to Gary Smith - buddy@mods.com.au

The latest version of Buddy API is available at

http://www.mods.com.au/budapi

14th March 2008

Information functions | System functions | File functions
Window functions | Function index | Contents


Installation

Windows Director 11

Place the 'Buddy API Xtra.x32' and the 'Buddy API Help.chm' files into the Director\Configuration\Xtras folder.

If you are planning to also make Macintosh projectors, then place the 'baMac.x32' file into the Director\Configuration\Xtras folder. Place the 'Buddy API Xtra.cpio' file from the Macintosh Buddy API 4 download into the Director\Configuration\Cross Platform Resources\Macintosh\Xtras folder. Open the xtrainfo.txt file in the Director\Configuration folder and add this line to the bottom of the file:

[#namePPC:"Buddy API Xtra", #nameW32:"Buddy API Xtra.x32"]

The baMac.x32 file is a Windows xtra that contains all the Buddy functions that are Mac only, eg baGestalt. This allows you to author the Mac only functions on a Windows system. The xtra itself does nothing and should not be distributed.

Windows Director MX2004

Place the 'Buddy API Xtra.x32' file and the 'Buddy API Help.chm' into the Director\Configuration\Xtras folder (the Director\Xtras folder for versions earlier than MX2004)

If you are planning to also make Macintosh projectors, then place the 'baMac.x32' file into the Director\Configuration\Xtras folder. You will need to download the 1.7 version of Macintosh Buddy API and place the 'Buddy API OSX Xtra.rsrc' and 'Buddy API OSX Xtra.data' files into the Director\Configuration\Cross Platform Resources\Macintosh\Xtras folder. Open the xtrainfo.txt file in the Director\Configuration folder and add this line to the bottom of the file:

[#namePPC:"Buddy API OSX Xtra", #nameW32:"Buddy API Xtra.x32"]

Windows Authorware

Place the 'Buddy API Xtra.x32' file and the 'Buddy API Help.chm' into the Authorware\Xtras folder.

Macintosh Director 11

Place the 'Buddy API Xtra.xtra' file into the Director\Configuration\Xtras folder. Place the 'Buddy API.help' file into the /Library/Documentation/Help folder. If you prefer, you can use the Windows Help file if you have a CHM viewer ( eg http://chmox.sourceforge.net) installed. In this case, place the 'Buddy API Help.chm' file into the same folder as the xtra.

If you are planning to also make Windows projectors, then place the 'baWin.xtra' file into the Director\Configuration\Xtras folder. Place the 'Buddy API Xtra.x32' file from the Windows Buddy API 4 download into the Director\Configuration\Cross Platform Resources\Windows\Xtras folder. Open the xtrainfo.txt file in the Director\Configuration folder and add this line to the bottom of the file:

[#namePPC:"Buddy API Xtra", #nameW32:"Buddy API Xtra.x32"]

The baWin.xtra file is a Macintosh xtra that contains all the Buddy functions that are Windows only, eg baReadRegString. This allows you to author the Windows only functions on a Macintosh system. The xtra itself does nothing and should not be distributed.


Registration

Please note that previous Macintosh versions of Buddy API did not need to be registered. From Version 4, the Macintosh will need to be registered.

There are two methods for registering Buddy API. You can use the registration utility at http://www.mods.com.au/budapi/download/bareg4.zip to create a registered copy of the xtra; or you can use baRegister in your script. You can choose to use either method.

There isn't a separate registered version - you use the registration utility to convert the unregistered version available on the web site into a registered version for your own use. This scheme means you can always download and register the latest version from the web site. Please read the readme file included with the registration utility for full details on the process involved.

After going through the registration process, you can use the Xtra version without using the baRegister command - although you can still do so if you wish to.

Please note that your licence agreement http://www.mods.com.au/budapi/license.htm prohibits you from distributing the registered version unless it is included as a part of your own software product. We also ask that if you are making your product available for free download from the internet, that you include the unregistered version and use the baRegister command.

Details on pricing and ordering of Buddy API can be found at http://www.mods.com.au/budapi/pricing.htm


Distributing your applications

Xtra distribution

There are a number of ways the Xtra can be distributed with your projector or packaged application.

You can place the Xtra in a folder called ‘Xtras’ in the same folder as your projector/application. This is the recommended method, particularly if your application will run from a slow medium such as CD-ROM. This method will provide the fastest loading application, because the Xtra will not need to be extracted every time your application runs.

In Director, you can embed the Xtra into the projector. To embed the xtra, you need to manually add it to the list of Xtras to be embedded. Choose the Modify -> Movie -> Xtras menu. A dialog box will appear. Click the ‘Add’ button, and select ‘Buddy API Xtra’. Make sure that the Include in projector option is checked.

Making cross platform projectors under Director 11

Using Director 11, it is possible to make Mac projectors under Windows, and vice versa.

To make a OSX projector from Windows, place the 'Buddy API Xtra.cpio' file from the Macintosh Buddy API 4 download into the Director\Configuration\Cross Platform Resources\Macintosh\Xtras folder. Open the xtrainfo.txt file in the Director\Configuration folder and add this line to the bottom of the file:

[#namePPC:"Buddy API Xtra", #nameW32:"Buddy API Xtra.x32"]

To make a Windows projector from an OSX system, you need to place the Buddy API Xtra.x32 file into the Director:Configuration:Cross Platform Resources:Windows:Xtras folder.

In both cases, you then need to change the xtrainfo.txt file in the Director\Configuration folder. Add this line to the end of the file.

[#namePPC:"Buddy API Xtra", #nameW32:"Buddy API Xtra.x32"]

Note that if you have renamed the xtra file names, make sure that you change the names in the above line.

Note that you do not have to do the above steps if you do not intend to embed the xtra in the projector. You can also make the cross-platform projector and include the xtra in a separate xtras folder.

Making cross platform projectors under Director MX 2004

Using Director MX 2004, it is possible to make Mac projectors under Windows, and vice versa.

To make a OSX projector from Windows, you need to use version 1.7 of the Macintosh version. Place the flattened copies of the Mac xtra - Buddy API OSX Xtra.rsrc and Buddy API OSX Xtra.data - (included in the Mac download) into the Director\Configuration\Cross Platform Resources\Macintosh\Xtras folder.

To make a Windows projector from an OSX system, you need to place the Buddy API Xtra.x32 file into the Director:Configuration:Cross Platform Resources:Windows:Xtras folder.

In both cases, you then need to change the xtrainfo.txt file in the Director MX 2004\Configuration folder. Add this line to the end of the file.

[#namePPC:"Buddy API OSX Xtra", #nameW32:"budapi.x32"]

Note that if you have renamed the xtra file names, make sure that you change the names in the above line.


Loading Buddy Functions

Director

After placing the Xtra in your Xtras folder and restarting Director, the Buddy API functions will become available for use. All the functions are global functions and can be called without using the lingo openxlib or new commands. You can enter code as provided in this help file in any Director script. You can also test the functions in the Message window.

Authorware

After placing the Xtra in your Xtras folder and restarting Authorware, the Buddy API functions will become available for use. You can type the code directly into a calculation icon. The list of functions can be viewed by selecting 'Functions' from the 'Window' menu, then choosing 'Xtra BudAPI' from the category list.


What's new in this release

Windows

Support for Unicode file names under Director 11.

The supported Windows versions are 2000, XP and Vista.

The following functions are new:

baTaskDialog | shows a Vista style Task Dialog
baGetFiles | displays a file selection dialog
baMouseClick | simulates a mouse click
baLanguage | gets the user language
baCapsLockOn | determines the state of the Caps Lock key
baSetCapsLockOn | sets the state of the Caps Lock key
baSetNumLockOn | sets the state of the Num Lock key
baNumLockOn | determines the state of the Num Lock key
baIsLimited | checks if the program is being run as a Limited user under Vista
baIsVirtualized | checks if program's file access is being virtualized under Vista
baSetCursor | sets a system cursor
baLoadDefaultCursors | loads the user's default cursors
baCreateGUID | creates a unique GUID
baCreatePMCommonGroup | creates a Start Menu group

Macintosh

Support for Unicode file names under Director 11.

Universal Binary support for Intel Macs.

This version only works with Director 11.

The Macintosh version now requires registration.

The minimum OSX version is 10.4.

The following functions are new:

baGetFiles | displays a file selection dialog
baMouseClick | simulates a mouse click
baMultiDisplayInfo | returns information about a display
baMultiDisplayList | returns a list of installed monitors
baSetMultiDisplay | sets display settings
baBundleApp | returns the executable file in a bundle
baShell | executes a file


Function list

Function index

About | FileExists | MsgBox | SetFileDate
ActivateWindow | FileList | MsgBoxButtons | SetFileInfo
ActiveWindow | FilePermissions | MsgBoxEx | SetFilePermissions
AddSysItems | FileSize | MultiDisplayInfo | SetMultiDisplay
Administrator | FileSize | MultiDisplayList | SetNumLockOn
 | FileType |  | SetParent
baBundleApp | FileVersion | NextActiveWindow | SetPattern
 | FindApp | NumLockOn | SetPrinter
CapsLockOn | FindClose |  | SetScreenSaver
ChildWindowList | FindDrive | OpenFile | SetSystemTime
ClipWindow | FindFirstFile | OpenURL | SetVolume
CloseApp | FindNextFile |  | SetWallpaper
CloseWindow | FindWindow | PageSetupDlg | SetWindowDepth
CommandArgs | FlushIni | PasteText | SetWindowTitle
ComputerName | FolderExists | PlaceCursor | Shell
CopyFile | FolderList | PMGroupList | ShortFileName
CopyFileProgress | FolderSize | PMIconList | Sleep
CopyText | FontInstalled | PMSubGroupList | SoundCard
CopyXFiles | FontList | Previous | StageHandle
CopyXFilesProgress | FontStyleList | PrintDlg | SysFolder
CpuInfo | FreeCursor | PrinterInfo | SystemTime
CreateFolder | Functions | PrintFile |
CreateGUID |  | Prompt | TaskDialog
CreatePMGroup | Gestalt |  | TempFileName
CreatePMIcon | GestaltExists | ReadIni |
 | GetDisk | ReadRegBinary | UnixName
DecryptText | GetFilename | ReadRegMulti | UserName
DeleteFile | GetFiles | ReadRegNumber | UserShortName
DeleteFolder | GetFolder | ReadRegString |
DeleteIniEntry | GetRegistration | RecycleFile | Version
DeleteIniSection | GetVolume | RefreshDesktop |
DeletePMGroup | GetWindow | baRefreshFiles | WaitForWindow
DeletePMIcon |  | Register | WaitTillActive
DeleteReg | HfsName | RegKeyList | WindowDepth
DeleteXFiles | HideTaskBar | RegValueList | WindowExists
DesktopColor |  | RemoveSysItems | WindowInfo
DisableDiskErrors | InstallFont | RenameFile | WindowList
DisableKeys | IsBundle | ResolveShortcut | WindowToBack
DisableMouse | IsLimited | RestrictCursor | WindowToFront
DisableScreenSaver | IsVirtualized | ReturnUnixNames | WinHandle
DisableSwitching |  | RunProgram | WinHelp
DiskInfo | KeyBeenPressed |  | WriteIni
DiskList | KeyIsDown | SaveRegistration | WriteRegBinary
 |  | ScreenInfo | WriteRegMulti
EjectDisk | Language | ScreenSaverTime | WriteRegString
EncryptFile | LoadDefaultCursors | SendKeys |
EncryptText | LogIn | SendMsg | XCopy
Environment | LongFileName | SetCapsLockOn | XCopyProgress
ExitWindows |  | SetCurrentDir | XDelete
 | MakeShortcut | SetCursor |
FileAge | MakeShortcutEx | SetDesktopColor |
FileAttributes | MemoryInfo | SetDisplay |
FileCreator | MouseClick | SetDisplayEx |
FileDate | MoveOnReboot | SetEnvironment |
FileDateEx | MoveWindow | SetFileAttributes |


Information functions

baVersion | returns version info (Windows, NT, DOS, QuickTime, VFW)
baSysFolder | returns location of system folders (windows, system, temp, etc)
baCpuInfo | gets information (type, speed) about the processor installed
baDiskInfo | gets information (type, size, name, number) about a disk
baDiskList | returns list of available drives
baMemoryInfo | gets information about system memory
baFindApp | finds the application associated with a file type
baReadIni | reads Windows ini file
baWriteIni | writes an entry to a Windows ini file
baFlushIni | forces Windows to write an ini file to disk
baDeleteIniEntry | deletes entry from an .ini file
baDeleteIniSection | deletes section from an .ini file
baReadRegString | reads Registry string value
baWriteRegString | writes string value to the Registry
baReadRegNumber | reads Registry number value
baWriteRegNumber | writes number value to the Registry
baReadRegBinary | reads Registry binary value
baWriteRegBinary | writes binary value to the Registry
baReadRegMulti | reads Registry multi string value
baWriteRegMulti | writes multi string value to the Registry
baDeleteReg | deletes Registry entry
baRegKeyList | returns a list of sub-keys inside a registry key
baRegValueList | returns a list of values inside a registry key
baSoundCard | checks whether a sound card is installed
baFontInstalled | checks whether a font is installed
baFontList | returns a list of installed fonts
baFontStyleList | returns a list of available styles for a TrueType font
baCommandArgs | returns the command line arguments the application was started with
baPrevious | checks whether a previous instance is running
baScreenInfo | gets information (width, height, etc) of the screen
baMultiDisplayInfo | gets information about the screens in the system
baMultiDisplayList | gets list of the screens in the system
baGestalt | returns the value of a Gestalt selector
baGestaltExists | checks if a Gestalt selector exists


baVersion

Version

Description:

baVersion returns a string containing version information.

Platforms:

Windows and Macintosh

Usage:

Result = baVersion( VersionType )

Arguments:

String.
VersionType is the type of version you are interested in.
Can be one of the following:
"os" | the current operating system Windows Macintosh
"windows" | Windows version Windows
"nt" | version of Windows NT Windows
"dos" | DOS version Windows
"build" | the Windows build version Windows
"service pack" | the service pack installed Windows
"sp string" | returns the service pack as a string
"nt type" | the NT product type Windows
"64Bit" | returns true if running on 64 bit Windows Windows
"Wow64" | returns true if running under Wow64 Windows
"vfw" | Video for Windows version Windows
"qt" | QuickTime 2 and earlier versions Windows Macintosh
"qt3" | QuickTime 3 and later versions Windows Macintosh
"mac" | Macintosh version Macintosh
"classic" | returns true if running in classic mode under OSX Macintosh

Returns:

String.
Returns the version information requested.

Examples:

Director:
WinVer = baVersion( "windows" )

Authorware:
WinVer := baVersion( "windows" )

Notes:

Possible returns for baVersion( "os" ) are "Win95", "Win98", "WinME", "WinNT", "Win2000", "WinXP", "WinVista", "Mac9", "Mac10".

On Windows, Apple made considerable changes to QuickTime between versions 2 and 3, and both may coexist on the same system. "qt" will report the version of QuickTime prior to version 3, "qt3" will report any version 3 or later. On Macintosh, only one version of QuickTime can be installed at once and "qt" will return the version of any QuickTime installed.


baSysFolder

SysFolder

Description:

baSysFolder gets the location of a system directory.

Platforms:

Windows and Macintosh

Usage:

Result = baSysFolder( Folder )

Arguments:

String.
Folder is the name of the folder to return. Can be one of the following:
Windows |
"windows" | returns the Windows folder
"system" | the System folder
"system16" | the System folder for 16 bit files
"system32" | the System folder for 32 bit files
"temp" | the folder used for temporary files
"current" | the current DOS directory
"desktop" | the desktop folder
"common desktop" | the common desktop folder for all users
"groups" | the program groups folder in the start menu
"common groups" | the common program groups folder for all users
"start menu" | the start menu folder
"common start menu" | the common start menu for all users
"personal" | the users personal documents folder
"favorites" | the users favorites folder
"startup" | the 'Start Up' program group folder
"common startup" | the 'Start Up' folder for all users
"recent" | the 'Recent documents' folder
"sendto" | the 'Send To' folder
"network" | the 'Network Neighborhood' folder
"fonts" | the 'Fonts' folder
"shellnew" | the new documents template folder
"program files" | the program files folder
"common files" | the common folder in the program files folder
"profile" | the users profile folder
"music" | the users My Music folder
"video" | the users My Videos folder
"pictures" | the users My Pictures folder
"appdata" | the users Application Data folder
"local appdata" | the users Local Application Data
"program data" | the Program Data folder
"public" | the Public folder (Vista only)
"users" | the 'Users' folder (Vista only)
Macintosh: |
"system" | the System Folder
"prefs" | the Preferences folder
"temp" | the Temporary Items folder on the startup disk
"desktop" | the Desktop folder on the startup disk
"trash" | the trash can
"startup" | the Startup Items folder
"apple" | the Apple Menu Items folder
"control panels" | the Control Panels folder
"extensions" | the Extensions folder
"fonts" | the Fonts folder
"boot" | the name of the start up disk
"personal" | the users personal documents folder
"apps" | The applications folder
"favorites" | the users favorites folder
"music" | the users Music folder
"video" | the users Videos folder
"pictures" | the users Pictures folder
"appdata" | the Application Support folder
"library" | the Library folder
"shared" | a shared folder readable and writeable for all users
"profile' | the users profile folder
"users" | the 'Users' folder
"public" | the Public folder

Returns:

String.
Returns the requested folder.

Examples:

Director:
WinDir = baSysFolder( "windows" )

Authorware:
WinDir := baSysFolder( "windows" )

Notes:

The string that is returned will always end with a folder separator.

On Windows, as well as the above folders, you can also pass in the number of a special folder. These numbers are listed in the ShlObj.h header file in the Windows Platform SDK. For example, to get the Cookies folder, you can use baSysFolder( "33" ). If you pass in a number, it will be passed directly to the SHGetSpecialFolderLocation API call. The numbers in the header file are listed n hex, you will need to convert them to decimal to use this function.

On Macintosh, you can also use a four character code to find other folders. For example, you can use baSysFolder( “laun” ) to find the Launcher Items folder. You can find a list of the possible folder codes in the <Folders.h> programming header file in the Universal Headers available from Apple. Not all of the listed folders will be available on all systems or under all Mac OS versions.

On Macintosh, the folders exist in domains - User, Local or System. This function attempts to find the most appropriate domain for the folder. To explicitly search in a particular domain, add "user", "local" or "system" to the folder name. For example:

put baSysFolder( "libary" )
-- "/Library"

put baSysFolder( "system library" )
-- "/System/Library"

Not all folders will exist in all domains.


baCpuInfo

CpuInfo

Description:

baCpuInfo returns information about the processor installed.

Platforms:

Windows

Usage:

Result = baCpuInfo( InfoType )

Arguments:

String.
InfoType is the type of information to get. Can be:
"vendor" | the processor manufacturer
"type" | returns the type of processor
"model" | the model of the processor
"stepping" | the stepping revision number
"speed" | the speed of the processor in mHz

Returns:

Integer or string depending on the InfoType.
See the Notes section for details on interpreting the return.

Examples:

Director:
Cpu = baCpuInfo( "type" )

Authorware:
Cpu := baCpuInfo( "type" )

Notes:

The "vendor" option returns a string containing the name of the manufacturer of the processor. This will be a 12 character string, the most common returns will be "GenuineIntel", "AuthenticAMD" and "CryixInstead" but there will be others for chips from IBM, Compaq, DEC and others.

This function contains identification code from Intel and AMD and is only reliable with those processors. Other brands will report that they are equivalent to an Intel processor, but that will not necessarily be a valid comparison.

To determine the actual processor model, you need to interpret both the "type" and "model" options. The "type" option will identify a general family of processor eg: 486, Pentium or K6. The "model" option will give specific information about the model within a particular family. "stepping" is the revision number of a specific model, and will not generally be useful. Refer to the following table to determine a processor.

Intel CPUs |  |  | AMD CPUs |  |
Description | Type | Model | Description | Type | Model
486 DX | 4 | 0, 1 | K5 | 5 | < 6
486 SX | 4 | 2 | K6 | 5 | 6, 7
486 DX2 | 4 | 3, 7 | K6-II | 5 | 8
486 SL | 4 | 4 | K6-III | 5 | 9
486 SX2 | 4 | 5 | Athlon | 6 | 1-10
486 DX4 | 4 | 8 | Duron | 6 | 3, 6, 7
Pentium | 5 | 1, 2 | Athlon XP/MP | 6 | 8
Pentium Overdrive | 5 | 3 | Sempron Model 8 | 6 | 8
Pentium MMX | 5 | 4 | Athlon XP-M | 6 | 10
Pentium Pro | 6 | 1 | Sempron Model 10 | 6 | 10
Pentium II (r1) | 6 | 3 |  |  |
Pentium II (r2) | 6 | 5 |  |  |
Celeron (r1) | 6 | 5 |  |  |
Celeron (r2) | 6 | 6 |  |  |
Pentium III | 6 | 7, 8, 11 |  |  |
Pentium III Xeon | 6 | 8, 10 |  |  |
Pentium 4 | 15 | 0 - 3 |  |  |
Pentium 4 D | 15 | 4 - 6 |  |  |
Core Duo | 6 | 14 |  |  |
Core 2 Duo | 6 | 15 |  |  |
Core 2 Extreme | 6 | 7 |  |  |

The "speed" returned is only an approximation within a variation of about 10%. If the processor has been overclocked, the speed it is running at will be returned. Intel specifically warn against quoting this number to users, because it can not be guaranteed to be accurate. Use this number as a guide only.


baDiskInfo

DiskInfo

Description:

baDiskInfo returns the information about a disk.

Platforms:

Windows and Macintosh

Usage:

Result = baDiskInfo( Drive, InfoType )

Arguments:

String, string.
Drive is the letter of the drive to get the information of.
InfoType is the type of information to get. Can be:
"type" | returns the type of drive Windows Macintosh
"name" | returns the volume name Windows
"size" | returns the size of the disk in Kb Windows Macintosh
"free" | returns the amount of free space in Kb Windows Macintosh
"number" | returns the serial number of the disk Windows

Returns:

Depends on InfoType.

"type"

string.
The type of drive. Can be:
"Hard" | Fixed hard drive.
"Floppy" | Floppy disk drive.
"CD-ROM" | CD/DVD drive.
"Network" | Network drive.
"Removable" | Removable drive eg Zip, Syquest.
"RAM" | RAM drive.
"Invalid" | Drive doesn't exist, or is of unknown type.

"name"

string.
The name of the disk or an empty string if the disk doesn't exist.

"size"

integer.
The size of the disk in Kb, or 0 if the disk doesn't exist.

"free"

integer.
The amount of free space on the disk in Kb, or 0 if the disk doesn't exist.

"number"

integer.
The serial number of the disk, or 0 if the disk doesn't exist.

Examples:

Director:
Size = baDiskInfo( "a" , "size" )
Label = baDiskInfo( "k" , "name" )

Authorware:
Size := baDiskInfo( "c" , "size" )
Label := baDiskInfo( "k" , "name" )

Notes:

On Windows, the drive argument is the letter of the drive; on Macintosh it is the name of the disk.

On Windows, Floppy drives as reported as Removable.

See also:

baFindDrive
baDiskList


baDiskList

DiskList

Description:

baDiskList returns a list of available drives.

Platforms:

Windows and Macintosh

Usage:

Result = baDiskList( )

Arguments:

None.

Returns:

List.
Returns list of available drives.

Examples:

Director:
disks = baDiskList( )

Authorware:
disks := baDiskList( )

Notes:

On Windows, removable drives such as CD-ROMs drives are returned even if there is not a disk in the drive.

On Macintosh, the names of the drives will be returned, on Windows the drive letter will be returned.

See also:

baFindDrive
baDiskInfo


baMemoryInfo

MemoryInfo

Description:

baMemoryInfo returns information about system memory.

Platforms:

Windows and Macintosh

Usage:

Result = baMemoryInfo( InfoType )

Arguments:

String.
InfoType is the type of information to get. Can be:
"ram" | the amount of physical ram installed Windows Macintosh
"free ram" | the amount of physical ram not being used Windows Macintosh
"swap" | the size of the current swap file Windows
"free swap" | the amount of the swap file not being used Windows
"virtual" | the size of the virtual address space Windows
"free virtual" | the amount of free memory in the virtual address space Windows
"load" | the percentage of physical memory in use Windows
"free" | the amount of free memory, including physical and virtual Macintosh
"max block" | the largest block of memory, including physical and virtual Macintosh

Returns:

Float.
Returns the information in bytes.

Examples:

Director:
ram = baMemoryInfo( "ram" )

Authorware:
free := baMemoryInfo( "free ram" )

Notes:

On Macintosh, the free and max block options return a large meaningless number. This is due to the memory management system of OSX.


baFindApp

FindApp

Description:

baFindApp returns the application associated with a file type.

Platforms:

Windows and Macintosh

Usage:

Result = baFindApp( Extension )

Arguments:

String.
Extension is the extension of the file type.

Returns:

String.
Returns the full path name to the application. Returns an empty string if the extension is not associated with or a program, or the associated program does not exist.

Examples:

Director:
Notepad = baFindApp( ".txt" )

Authorware:
Notepad := baFindApp( ".txt" )

Notes:

On Windows, Microsoft guidelines state that if a program registers a file extension, and the path to the executable file is a long file name, then that name must be included in quotes. If an installation program doesn't follow these guidelines, then this function may fail. Specifically, if the path name to the executable contains a space, then this function will not be able to return the path to the executable. Adobe Acrobat Reader 3 is one program that does not register itself correctly - it does not place quotes around the executable name in the registry. The baFindApp function has been written around this particular problem with Acrobat, and will use other methods to locate Acrobat if it is asked to find the application associated with "pdf" files. You do not have to include the . with the extension.

On Macintosh, each application has it’s own unique four character identifier eg, “CARO” for Acrobat, “MOSS” for Netscape, “MSIE” for Internet Explorer. There are a number of shareware utilities available which will tell you the creator type of a application, such as File Buddy by Laurence Harris, or you can use baFileCreator.
You can also use extensions to find an application. For example, baFindApp( ".txt" ) will return the application that will open .txt files that don't have a file type/creator. You must use a . at the beginning of the extension.
If the application found is inside a bundle, then the name that is returned is the name to the bundle. You can tell if a bundle has been returned because it will end in a folder separator.
For example, baFindApp( ".txt" ) may return "OSX:Applications:TextEdit.app:" You can pass this name into other Buddy functions, eg baOpenFile.

See also:

baOpenFile


baReadIni

ReadIni

Description:

baReadIni gets a string from a Windows ini file.

Platforms:

Windows and Macintosh

Usage:

Result = baReadIni( Section, Keyname, Default, IniFile )

Arguments:

String, string, string, string.
Section is the section name of the ini file.
Keyname is the name of the key
Default is the string that is returned if the file, section or key doesn't exist.
IniFile is the name if the ini file to use.

Returns:

String.
Returns the value associated with the Keyname. If the IniFile, Section or Keyname doesn't exist, then the return will be the Default string.

Examples:

Director:
Name = baReadIni( "CurrentUser", "UserName", "Error", "Userdat.ini" )

Authorware:
Name := baReadIni( "CurrentUser", "UserName", "Error", "Userdat.ini" )

Notes:

An entry in a ini file has the following format :

[Section]
Keyname=string

This function will return the string after the equals sign. When using this function, the Section name you use should not include the square brackets around the name. The Keyname should not include the equals sign. For example the ini file for the example above might look something like this

[CurrentUser]
UserName=Gary Smith
Password=mypw
ModulesCompleted=4

The IniFile can be in any directory. On Windows, if the full path is not specified the file will be assumed to be in the Windows directory, on the Macintosh it will be assumed to be in the Preferences folder.

The ini file does not have to have an .ini extension: any extension can be used.

This function returns a maximum of 32000 characters.

This function will not read Unicode characters.

See also:

baWriteIni
baFlushIni
baDeleteIniEntry
baDeleteIniSection


baWriteIni

WriteIni

Description:

baWriteIni writes a string into a Windows ini file.

Platforms:

Windows and Macintosh

Usage:

Result = baWriteIni( Section, Keyname, NewValue, IniFile )

Arguments:

String, string, string, string.
Section is the section name of the ini file.
Keyname is the name of the key
NewValue is the string to write into the file.
IniFile is the name if the ini file to use.

Returns:

Integer.
Returns 1 if the function was successful, else 0.

Examples:

Director:
OK = baWriteIni( "CurrentUser", "UserName", "Gary Smith", "Userdat.ini" )

Authorware:
OK := baWriteIni( "CurrentUser", "UserName", "Gary Smith", "Userdat.ini" )

Notes:

An entry in a Windows ini file has the following format :

[Section]
Keyname=string

This function will write the string after the equals sign. When using this function, the Section name you use should not include the square brackets around the name. The Keyname should not include the equals sign. For example the ini file for the example above might look something like this

[CurrentUser]
UserName=Gary Smith
Password=mypw
ModulesCompleted=4

The IniFile can be in any directory. On Windows if the full path name is not specified, the file will be created in the Windows directory, on the Macintosh it will be created in the Preferences folder.

The ini file does not have to have an .ini extension: any extension can be used.

If the ini file does not exist, then it will be created.

This function will write a maximum of 32000 characters.

This function will not write Unicode characters.

See also:

baReadIni
baFlushIni
baDeleteIniEntry
baDeleteIniSection


baFlushIni

FlushIni

Description:

baFlushIni forces Windows to write an ini file to disk.

Platforms:

Windows

Usage:

baFlushIni( Filename )

Arguments:

String.
Filename is the name of the ini file to flush.

Returns:

Void.

Examples:

Director:
baFlushIni( the moviePath & "data.ini" )

Authorware:
baFlushIni( FileLocation ^ "data.ini" )

Notes:

This function is for use with the other ini file functions. When Windows writes an ini file it keeps it cached for a short time. This does not cause problems when using only the ini functions. However, if you want to write an ini file, then immediately do something else with it, say, encrypt it, then you should use this function to force Windows to write the file to disk before you use it.

eg.

baWriteIni( "data", "password", pw, iniFile ) -- write ini file
baFlushIni( iniFile ) -- force it to disk
baEncryptFile( iniFile, key ) -- encrypt it

This function is not needed if you are only using baWriteIni and baReadIni on your ini files.

See also:

baReadIni
baWriteIni
baDeleteIniEntry
baDeleteIniSection


baDeleteIniEntry

DeleteIniEntry

Description:

baDeleteIniEntry deletes an entry from an ini file.

Platforms:

Windows

Usage:

baDeleteIniEntry( Section, Keyname, Filename )

Arguments:

String, string, string.
Section is the name of the section the entry is in.
Keyname is the entry to delete
Filename is the name of the ini file.

Returns:

Void.

Examples:

Director:
baDeleteIniEntry( "Users", "Name", the moviePath & "data.ini" )

Authorware:
baDeleteIniEntry( "Users", "Name", FileLocation ^ "data.ini" )

See also:

baReadIni
baWriteIni
baDeleteIniSection


baDeleteIniSection

DeleteIniSection

Description:

baDeleteIniSection deletes a section from an ini file.

Platforms:

Windows

Usage:

baDeleteIniSection( Section, Filename )

Arguments:

String, string.
Section is the name of the section the entry is in
Filename is the name of the ini file

Returns:

Void.

Examples:

Director:
baDeleteIniSection( "Users", the moviePath & "data.ini" )

Authorware:
baDeleteIniSection( "Users", FileLocation ^ "data.ini" )

See also:

baReadIni
baWriteIni
baDeleteIniEntry


baReadRegString

ReadRegString

Description:

baReadRegString gets a string from the Windows Registry.

Platforms:

Windows

Usage:

Result = baReadRegString( KeyName, ValueName, Default, Branch )

Arguments:

String, string, string, string.
KeyName is the name of the key.
ValueName is the name of the value.
Default is the string that is returned if the key/value doesn't exist.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

String.
Returns the value associated with the Keyname. If the Keyname doesn't exist, then the return will be the Default string.

Examples:

Director:
Name = baReadRegString( "Courses\Computers\101", "CurrentUser", "Error", "HKEY_CLASSES_ROOT" )

Authorware:
Name := baReadRegString( "Courses\\Computers\\101", "CurrentUser", "Error", "HKEY_CLASSES_ROOT" )

Notes:

A Registry entry consists of keys and sub-keys, similar to the directories and sub-directories in the Windows file system. 32 bit Windows adds Values to the registry. These can be thought of as files within the key.

To get the (Default) value of a key use an empty string for the ValueName argument.

This function returns a maximum of 2000 characters.

See also:

baWriteRegString
baReadRegNumber
baWriteRegNumber
baReadRegBinary
baWriteRegBinary
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baReadRegNumber

ReadRegNumber

Description:

baReadRegNumber gets a number from the Windows Registry.

Platforms:

Windows

Usage:

Result = baReadRegNumber( KeyName, ValueName, Default, Branch )

Arguments:

String, string, integer, string.
KeyName is the name of the key.
ValueName is the name of the value.
Default is the string that is returned if the key/value doesn't exist.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

Integer.
Returns the value associated with the Keyname. If the Keyname doesn't exist, then the return will be the Default value.

Examples:

Director:
Name = baReadRegNumber( "Courses\Computers", "Course", 0, "HKEY_CLASSES_ROOT" )

Authorware:
Name := baReadRegNumber( "Courses\\Computers", "Course", 0, "HKEY_CLASSES_ROOT" )

Notes:

A Registry entry consists of keys and sub-keys, similar to the directories and sub-directories in the Windows file system. 32 bit Windows adds Values to the registry. These can be thought of as files within the key.

See also:

baReadRegString
baWriteRegString
baWriteRegNumber
baReadRegBinary
baWriteRegBinary
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baWriteRegNumber

WriteRegNumber

Description:

baWriteRegNumber writes a number into the Windows Registry.

Platforms:

Windows

Usage:

Result = baWriteRegNumber( KeyName, ValueName, NewData, Branch )

Arguments:

String, string, integer, string.
KeyName is the name of the key.
ValueName is the name of the value.
NewData is the number that will be written to the registr
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

Integer.
Returns 1 if the function is successful, otherwise 0.

Examples:

Director:
OK = baWriteRegNumber( "Courses\Computers", "Course", 101 , "HKEY_CLASSES_ROOT" )

Authorware:
OK := baWriteRegNumber( "Courses\\Computers", "Course", 101 , "HKEY_CLASSES_ROOT" )

Notes:

A Registry entry consists of keys and sub-keys, similar to the directories and sub-directories in the Windows file system. 32 bit Windows adds Values to the registry. These can be thought of as files within the key.

See also:

baReadRegString
baWriteRegString
baReadRegNumber
baReadRegBinary
baWriteRegBinary
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baReadRegBinary

ReadRegBinary

Description:

baReadRegBinary gets a binary value from the Windows Registry.

Platforms:

Windows

Usage:

Result = baReadRegBinary( KeyName, ValueName, Default, Branch )

Arguments:

String, string, string, string.
KeyName is the name of the key.
ValueName is the name of the value.
Default is the string that is returned if the key/value doesn't exist.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

List.
Returns a list containing the binary value stored in Keyname. If the Keyname doesn't exist, then the return will be a list containing just the Default value.

Examples:

Director:
data = baReadRegBinary( "Courses\Computers", "Data", "error, "HKEY_CLASSES_ROOT" )

Authorware:
data := baReadRegBinary( "Courses\\Computers", "Data", "error", "HKEY_CLASSES_ROOT" )

Notes:

The return will be a list containing the binary values. eg:

[ 23, 45, 68, 0, 3, 5, 0 ]

Note that these values will not be the same values as shown in RegEdit - the values in RegEdit are in hex, while the Xtra returns the decimal equivalents. If the key does not exist, then a list with the default value (as a string) as its only entry will be returned, eg:

["error"]

A Registry entry consists of keys and sub-keys, similar to the directories and sub-directories in the Windows file system. 32 bit Windows adds Values to the registry. These can be thought of as files within the key.

See also:

baWriteRegBinary
baReadRegString
baWriteRegString
baReadRegNumber
baWriteRegNumber
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baWriteRegBinary

WriteRegBinary

Description:

baWriteRegBinary writes a binary value into the Windows Registry.

Platforms:

Windows

Usage:

Result = baWriteRegBinary( KeyName, ValueName, Data, Branch )

Arguments:

String, string, list.
KeyName is the name of the key.
ValueName is the name of the value.
Data is a list containing the numbers that will be written to the registry.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

Integer.
Returns 1 if the function is successful, otherwise 0.

Examples:

Director:
OK = baWriteRegBinary( "Courses\Computers", "Course", [10, 23, 0, 0, 45, 13], "HKEY_CLASSES_ROOT" )

Authorware:
OK := baWriteRegBinary( "Courses\\Computers", "Course", [10, 23, 0, 0, 45, 13], "HKEY_CLASSES_ROOT" )

Notes:

The values used must be decimal numbers, not hex as is used in RegEdit.

See also:

baReadRegBinary
baReadRegString
baWriteRegString
baReadRegNumber
baWriteRegNumber
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baReadRegMulti

ReadRegMulti

Description:

baReadRegMulti gets a multi string value from the Windows Registry.

Platforms:

Windows

Usage:

Result = baReadRegBinary( KeyName, ValueName, Default, Branch )

Arguments:

String, string, string, string.
KeyName is the name of the key.
ValueName is the name of the value.
Default is the string that is returned if the key/value doesn't exist.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

List.
Returns a list containing the strings stored in Keyname. If the Keyname doesn't exist, then the return will be a list containing just the Default value.

Examples:

Director:
data = baReadRegMulti( "Courses\Computers", "Data", "error, "HKEY_CLASSES_ROOT" )

Authorware:
data := baReadRegMulti( "Courses\\Computers", "Data", "error", "HKEY_CLASSES_ROOT" )

Notes:

The multi string type of registry entry consists of a series of strings.

The return will a list containing the string values. eg:

[ "date", "20011121, "time", "231823" ]

If the key does not exist, then a list with the default value (as a string) as its only entry will be returned, eg:

["error"]

A Registry entry consists of keys and sub-keys, similar to the directories and sub-directories in the Windows file system. These can be thought of as files within the key.

See also:

baWriteRegMulti
baWriteRegBinary
baReadRegString
baWriteRegString
baReadRegNumber
baWriteRegNumber
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baWriteRegMulti

WriteRegMulti

Description:

baWriteRegMulti writes a multi string value into the Windows Registry.

Platforms:

Windows

Usage:

Result = baWriteRegBinary( KeyName, ValueName, Data, Branch )

Arguments:

String, string, list (Xtra) or string (UCD), string.
KeyName is the name of the key.
ValueName is the name of the value.
Data is a list containing the strings that will be written to the registry.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

Integer.
Returns 1 if the function is successful, otherwise 0.

Examples:

Director:
OK = baWriteRegMulti( "Courses\Computers", "Course", [ "name", "fred" ], "HKEY_CLASSES_ROOT" )

Authorware:
OK := baWriteRegBinary( "Courses\\Computers", "Course", [ "name", "fred" ], "HKEY_CLASSES_ROOT" )

See also:

baReadRegMulti
baReadRegBinary
baReadRegString
baWriteRegString
baReadRegNumber
baWriteRegNumber
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList


baDeleteReg

DeleteReg

Description:

baDeleteReg deletes a key or value from the Windows Registry.

Platforms:

Windows

Usage:

Result = baDeleteReg( KeyName, ValueName, Branch )

Arguments:

String, string, string.
KeyName is the name of the key.
ValueName is the name of the value. A empty string will delete the entire KeyName.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

Integer.
Returns 1 if the function is successful, otherwise 0.

Examples:

Director:
OK = baDeleteReg( "Courses\Computers", "Course", "HKEY_CLASSES_ROOT" )

Authorware:
OK := baDeleteReg( "Courses\\Computers", "Course", HKEY_CLASSES_ROOT" )

Notes:

Under Windows NT/2000/XP/Vista a key can only be deleted if it is empty. Under Windows 95/08/ME, all sub keys will also be deleted.

See also:

baReadRegString
baWriteRegString
baReadRegNumber
baReadRegNumber
baReadRegBinary
baWriteRegBinary
baRegKeyList
baRegValueList


baRegKeyList

RegKeyList

Description:

baRegKeyList returns a list of sub-keys inside a registry key.

Platforms:

Windows

Usage:

Result = baRegKeyList( KeyName, Branch )

Arguments:

KeyName is the name of the key.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

List (Xtra) or String (UCD).
Returns a list of the keys, or an empty list/string if the key doesn't exist or is empty.

Examples:

Director:
keyList = baRegKeyList( "Software\Adobe", "HKEY_LOCAL_MACHINE" )

Authorware:
keyList := baRegKeyList( "Software\\Adobe", "HKEY_LOCAL_MACHINE" )

See also:

baReadRegString
baWriteRegString
baReadRegNumber
baReadRegNumber
baReadRegBinary
baWriteRegBinary
baDeleteReg
baRegValueList


baRegValueList

RegValueList

Description:

baRegValueList returns a list of values inside a registry key.

Platforms:

Windows

Usage:

Result = baRegValueList( KeyName, Branch )

Arguments:

String, string.
KeyName is the name of the key.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

List
Returns a list of the keys, or an empty list/string if the key doesn't exist or is empty.

Examples:

Director:
valueList = baRegValueList( "Netscape\Netscape Navigator", "HKEY_LOCAL_MACHINE" )

Authorware:
valueList := baRegValueList( "Software\\Adobe", "HKEY_LOCAL_MACHINE" )

See also:

baReadRegString
baWriteRegString
baReadRegNumber
baReadRegNumber
baReadRegBinary
baWriteRegBinary
baDeleteReg
baRegKeyList


baSoundCard

SoundCard

Description:

baSoundCard checks whether a sound card is installed.

Platforms:

Windows

Usage:

Result = baSoundCard()

Arguments:

None.

Returns:

Integer.
Returns 1 if a sound card is installed, else 0.

Examples:

Director:
Sound = baSoundCard( )

Authorware:
Sound := baSoundCard( )


baFontInstalled

FontInstalled

Description:

baFontInstalled reports whether or not a TrueType or Bitmap font is installed.

Platforms:

Windows and Macintosh

Usage:

Result = baFontInstalled( FontName, Style )

Arguments:

String, string.
FontName is the name of the font family eg "Arial".
Style is the specific style eg "Bold". Use an empty string ("") to see if the basic font is installed. The style is ignored if FontName is a Bitmap font.

Returns:

Integer.
Returns 1 if the font is presently installed, otherwise 0.

Examples:

Director:
FontOK = baFontInstalled( "Arial", "Bold Italic" )

Authorware:
FontOK := baFontInstalled( "Arial", "Bold Italic" )

Notes:

If you ask for a specific font style, then the function will only return true if that style is present. For example, if you ask for "Arial", "Bold" and only the normal Arial is installed, this function will return 0. Some fonts may have different names for the styles, eg "Black" for bold and "Oblique" for italic. You must use the names built into the font.

On Macintosh, the Style argument is ignored.

See also:

baFontStyleList
baFontList
baInstallFont


baFontList

FontList

Description:

baFontList returns a list of all installed fonts.

Platforms:

Windows

Usage:

Result = baFontList( FontType )

Arguments:

String.
FontType is the type of fonts to list. Can be:
"All" | all fonts
"TrueType" | only true type fonts
"Bitmap" | only bitmap fonts
"Device" | only device or printer fonts
"Vector" | only vector fonts

Returns:

List.
Returns the list of fonts found.

Examples:

Director:
ttList = baFontList( "TrueType" )

Authorware:
fontList := baFontList( "All" )

Notes:

Postscript fonts handled by ATM are listed as device fonts.

See also:

baFontStyleList
baFontInstalled
baInstallFont


baFontStyleList

FontStyleList

Description:

baFontStyleList returns a list of available styles for a TrueType font.

Platforms:

Windows

Usage:

Result = baFontStyleList( FontName )

Arguments:

String.
FontName is the name of the font.

Returns:

List.
Returns the list of font styles found.

Examples:

Director:
styleList = baFontStyleList( "Arial" )

Authorware:
styleList := baFontStyleList( "Arial" )

Notes:

This function is only applicable to TrueType fonts - other types of fonts will return an empty list. Only styles that are actually installed will be returned. Styles created on-the-fly by Windows will not.

See also:

baFontList
baFontInstalled
baInstallFont


baCommandArgs

CommandArgs

Description:

baCommandArgs returns the arguments the application was started with.

Platforms:

Windows

Usage:

Result = baCommandArgs( )

Arguments:

None.

Returns:

String.
Returns the command line arguments, or an empty string if there were none.

Examples:

Director:
Args = baCommandArgs( )

Authorware:
Args := baCommandArgs( )


baPrevious

Previous

Description:

baPrevious checks whether a previous instance of a projector or packaged file is running.

Platforms:

Windows

Usage:

Result = baPrevious( Activate )

Arguments:

Integer.
If Activate is true, the previous instance is activated and brought to the front.

Returns:

Integer.
Returns the window handle of the previous instance if one is running, else 0.

Examples:

Director:
if baPrevious( true ) <> 0 then quit

Authorware:
if baPrevious( true ) <> 0 then quit(0)

Notes:

Both Director and Authorware open their display windows before scripts are executed. This means that the window of the second instance will appear before the previous one can be activated.

Under Windows NT/2000/XP/Vista, this function will only find the first instance opened. For example, if you open three copies of a projector, then quit the first one, baPrevious in the third projector will return 0 - it can not recognise the second projector as a previous instance. Under Windows 95 and 3.1, the third projector will be able to identify the second projector as a previous instance.

If you are running a full screen Director projector use this script to activate the previous instance. The example given above will make the stage move to a new position.

wnd = baPrevious( false )
if wnd <> 0 then
baWindowToFront( wnd )
quit
end if


baScreenInfo

ScreenInfo

Description:

baScreenInfo returns information about the screen.

Platforms:

Windows

Usage:

Result = baScreenInfo( InfoType )

Arguments:

String.
The type of information to get. Can be:
"height" | the height of the screen in pixels
"width" | the width of the screen in pixels
"depth" | the colour depth of the screen in bits
"fontheight" | the height of the system font in pixels
"titlebar height" | the height of the system title bars
"menubar height" | the height of system menus
"refresh" | the current refresh frequency of the display adaptor

Returns:

Integer.

Examples:

Director:
ScrHgt = baScreenInfo( "height" )

Authorware:
ScrRefresh := baScreenInfo( "refresh" )

See also:

baSetDisplay
baSetDisplayEx


baMultiDisplayInfo

MultiDisplayInfo

Description:

baMultiDisplayInfo returns information about the screens.

Platforms:

Windows and macintosh

Usage:

Result = baMultiDisplayInfo( Monitor, InfoType )

Arguments:

String, string.
Monitor is the monitor to get the information of; eg "\\.\DISPLAY1". You can also use "primary" to get the primary display, or "secondary" to get the secondary display.
InfoType is the type of information to get. Can be:
"height" | the height of the screen in pixels
"width" | the width of the screen in pixels
"depth" | the colour depth of the screen in bits
"refresh" | the current refresh frequency of the display adaptor
"xpos" | the x position of the monitor in relation to the primary monitor
"ypos" | the y position of the monitor in relation to the primary monitor
"number" | the number of monitors in the system. The Monitor is ignored
"primary" | the name of the primary display. The Monitor is ignored
"secondary" | the name of the secondary display. The Monitor is ignored
"card" | the name of the card powering the monitor. Windows only
"modes" | returns a list of all the modes the monitor supports

Returns:

String.
Returns the information requested, or an empty string if unsuccessful.

Examples:

Director:
ScrHgt = baMultiDisplayInfo( "primary", "height" )

Authorware:
monitors := baMultiDisplayInfo( "", "number" )

Notes:

On Macintosh, not all screens support user selected refresh rates. In these cases, a refresh rate of 0 is returned.

On Macintosh, displays are identified by a number, eg "6204534".

See also:

baSetMultiDisplay
baMultiDisplayList
baSetDisplay
baSetDisplayEx


baMultiDisplayList

MultiDisplayList

Description:

baMultiDisplayList returns a list of all displays.

Platforms:

Windows and Macintosh

Usage:

Result = baMultiDisplayList( )

Arguments:

None.

Returns:

List.
Returns a list of all the connected displays. eg:
["\\.\DISPLAY1", "\\.\DISPLAY2"]

Examples:

Director:
monitors = baMultiDisplayList( )

Authorware:
monitors := baMultiDisplayList( )

Notes:

On Macintosh, displays are identified by a number, eg "6204534".

See also:

baSetMultiDisplay
baMultiDisplayInfo
baSetDisplay
baSetDisplayEx


baGestalt

Gestalt

Description: | baGestalt returns the gestalt value of a Selector.
Platforms: | Macintosh
Usage: | Result = baGestalt( Selector )
Arguments: | String. Selector is the four character code to get the value of.
Returns: | Integer. The value of the Selector.
Examples: | Director: set qt = baGestaltExists( “qtim” ) Authorware: sys := baGestaltExists( “sysv” )
Notes: | The format and interpretation of the value returned will depend on the Selector used. For some Selectors 0 is a valid return if you want to check whether or not a Selector is actually available use baGestaltExists.
See also: | baGestaltExists


baGestaltExists

GestaltExists

Description: | baGestaltExists checks whether a gestalt Selector exists.
Platforms: | Macintosh
Usage: | Result = baGestaltExists( Selector )
Arguments: | String. Selector is the four character code to check.
Returns: | Integer. Returns 1 if the Selector exists, otherwise 0.
Examples: | Director: set qt = baGestalt( “qtim” ) Authorware: sys := baGestalt( “sysv” )
Notes: | This function checks whether or not a Selector is available. To check the value of a Selector, use baGestalt
See also: | baGestalt


System functions

baDisableDiskErrors | disables the 'Drive not ready' error message
baDisableKeys | disables/enables key presses
baDisableMouse | disables/enables mouse clicks
baDisableSwitching | disables/enables task switching
baDisableScreenSaver | disables/enables the screen saver
baScreenSaverTime | sets the screen saver time out
baSetScreenSaver | sets the screen saver
baSetWallpaper | sets the desktop wallpaper
baSetPattern | sets the desktop pattern
baDesktopColor | returns the desktop color
baSetDesktopColor | sets the desktop color
baSetDisplay | sets the screen size and depth
baSetDisplayEx | sets the screen size and depth
baSetMultiDisplay | sets the screen size and depth
baExitWindows | exits or restarts Windows
baRunProgram | runs an external program
baWinHelp | shows a Windows help file
baMsgBox | shows standard system message box
baMsgBoxEx | shows custom message box
baMsgBoxButtons | sets the button text for baMsgBox
baPrompt | shows prompt dialog box
baLogIn | shows log in dialog box
baTaskDialog | shows a Vista style Task Dialog
baSleep | pauses the calling Director/Authorware program
baHideTaskBar | shows/hides the task bar or dock
baSetCurrentDir | changes the DOS current directory
baCopyText | copies text to the clipboard
baPasteText | pastes text from the clipboard
baEncryptText | encrypts a text string
baDecryptText | decrypts a text string
baPlaceCursor | positions the cursor
baRestrictCursor | restricts the cursor to a specific screen area
baFreeCursor | allows the cursor to move anywhere on the screen
baSetVolume | sets the volume of wave and midi files and audio CD
baGetVolume | gets the current sound volume of wave and midi files and audio CD
baEnvironment | returns an environment variable
baSetEnvironment | sets an environment variable
baAdministrator | returns Administrator status
baUserName | returns name of current user
baUserShortName | returns short name of user
baComputerName | returns name of computer
baLanguage | returns the language currently in use
baIsLimited | checks if the program is being run as a Limited user under Vista.
baIsVirtualized | checks if program's file access is being virtualized under Vista.
baInstallFont | installs TrueType or bitmap font
baKeyIsDown | checks whether a key is being held down
baKeyBeenPressed | checks whether a key has been pressed
Virtual key codes | a list of key codes
baCapsLockOn | determines the state of the Caps Lock key
baSetCapsLockOn | sets the state of the Caps Lock key
baNumLockOn | determines the state of the Num Lock key
baSetNumLockOn | sets the state of the Num Lock key
baEjectDisk | ejects CD
baCreatePMGroup | creates a Start Menu group
baCreatePMCommonGroup | creates a Start Menu group
baDeletePMGroup | deletes a Start Menu group
baPMGroupList | returns list of Start Menu groups
baPMSubGroupList | returns list of Start Menu groups inside another group
baCreatePMIcon | creates a Start Menu icon
baDeletePMGroup | deletes a Start Menu icon
baPMIconList | returns list of icons in a Start Menu group
baSystemTime | returns the current system time/date
baSetSystemTime | sets the system time/date
baPrinterInfo | returns information about the installed printer
baSetPrinter | changes settings for the default printer
baPrintDlg | shows printer dialog box
baPageSetupDlg | shows page setup dialog box
baRefreshDesktop | refreshes the desktop icons
baRefreshFiles | refreshes the desktop database
baSetCursor | sets a system cursor
baLoadDefaultCursors | loads the user's default cursors
baCreateGUID | creates a unique GUID


baDisableDiskErrors

DisableDiskErrors

Description: | baDisableDiskErrors allows you to suppress the Windows 'drive not ready' error message.
Platforms: | Windows
Usage: | baDisableDiskErrors( State )
Arguments: | Integer. State determines whether or not the error messages are shown. Can be either true or false.
Returns: | Void.
Examples: | Director: baDisableDiskErrors( true ) Authorware: baDisableDiskErrors( true )
Notes: | This function disables the 'drive not ready' error message that occurs when Windows tries to access a file when there isn't a disk in the drive. This is a system wide setting and you should enable the disk errors again as soon as possible after disabling them.


baDisableKeys

DisableKeys

Description:

baDisableKeys allows you to disable key presses.

Platforms:

Windows

Usage:

Result = baDisableKeys( Disable, WindowHandle )

Arguments:

Integer, integer.
WindowHandle is the handle of the window to disable. To disable the keys on all windows, use 0.
If Disable is true, key presses will be disabled.
If Disable is false, key presses will be enabled again - the WindowHandle argument is ignored.

Returns:

Integer.
When disabling the keys, returns 1 if the function was successful, otherwise 0.
When enabling the keys, will always return 1.

Examples:

Director:
KeysOff = baDisableKeys( true , baWinHandle() )

Authorware:
KeysOff := baDisableKeys( true , baWinHandle() )

Notes:

If you disable the keys using this function, make sure that you enable the function before your application quits.


baDisableMouse

DisableMouse

Description:

baDisableMouse allows you to disable mouse clicks.

Platforms:

Windows

Usage:

Result = baDisableMouse( Disable , WindowHandle )

Arguments:

Integer, integer.
WindowHandle is the handle of the window to disable. To disable clicks on all windows, use 0.
If Disable is true, mouse clicks will be disabled.
If Disable is false, all mouse clicks will be enabled again - the WindowHandle argument is ignored.

Returns:

Integer.
When disabling the mouse, returns 1 if the function was successful, otherwise 0.
When enabling the mouse, will always return 1.

Examples:

Director:
MouseOff = baDisableMouse( true , baWinHandle() )

Authorware:
MouseOff := baDisableMouse( true , baWinHandle() )

Notes:

If you disable the mouse using this function, make sure that you enable the function before your application quits.

Note that the cursor will still be visible and movable.


baDisableSwitching

DisableSwitching

Description:

baDisableSwitching disables the task switching keys - Alt-Tab, Alt-Esc, and Ctrl-Esc. On Windows 95, the Ctrl-Alt-Del command is also disabled.

Platforms:

Windows and Macintosh

Usage:

baDisableSwitching( On )

Arguments:

Integer.
If On is true, then task switching will be disabled.

Returns:

Void.

Examples:

Director:
baDisableSwitching( true )

Authorware:
baDisableSwitching( true )

Notes:

If you disable switching, you should restore it again before your application quits.

For this function to work, you must first set the Director property exitLock to true. Add this code set the exitLock to true before you call this function. This will also mean that your user can not quit the application using Alt-F4, Esc, etc.

Ctrl-Alt-Delete will still be enabled under Windows NT, 2000, XP and Vista.

On Macintosh, system hot keys, for example for Dashboard and Expose, will still be active. This function must be called after the projecter has been started and been completely loaded; do not call in the prepareMovie or startMovie handlers or the function will not work.


baDisableScreenSaver

DisableScreenSaver

Description: | baDisableScreenSaver allows you to enable/disable the screen saver.
Platforms: | Windows
Usage: | Result = baDisableScreenSaver( State )
Arguments: | Integer. State can be either true or false.
Returns: | Integer. Returns 1 if the screen saver was previously active, or 0 if is was inactive.
Examples: | Director: OldSS = baDisableScreenSaver( false ) Authorware: OldSS := baDisableScreenSaver( false )
Notes: | This function does not actually start the screen saver. It just determines whether or not the screen saver will appear after it's time out period has passed. If your user has previously elected not to have a screen saver active, then this function will have no effect.
See also: | baScreenSaverTime baSetScreenSaver


baScreenSaverTime

ScreenSaverTime

Description:

baScreenSaverTime allows you to set the screen saver time out.

Platforms:

Windows

Usage:

Result = baScreenSaverTime( Time )

Arguments:

Integer.
Time is the value to set the screen saver time out to, in seconds.

Returns:

Integer.
Returns the previous time out value.

Examples:

Director:
OldTime = baScreenSaverTime( 120 )

Authorware:
OldTime := baScreenSaverTime( 120 )

See also:

baDisableScreenSaver
baSetScreenSaver


baSetScreenSaver

SetScreenSaver

Description:

baSetScreenSaver allows you to set the screen saver file.

Platforms:

Windows

Usage:

Result = baSetScreenSaver( FileName )

Arguments:

String.
FileName is the file name of the screen saver.

Returns:

String.
Returns the file name of the previous screen saver.

Examples:

Director:
OldSS = baSetScreenSaver( "c:\windows\ss.scr" )

Authorware:
OldSS := baSetScreenSaver( "c:\\windows\\ss.scr" )

Notes:

You should use the full path name of the screen saver. A empty string will disable screen saving. This function will also enable the screen saver.

See also:

baDisableScreenSaver
baScreenSaverTime


baSetWallpaper

SetWallpaper

Description:

baSetWallpaper allows you to set the desktop wallpaper.

Platforms:

Windows and Macintosh

Usage:

Result = baSetWallpaper( FileName , Tile )

Arguments:

String, integer
FileName is the file name of the wallpaper.
Tile is the placement of the wallpaper. Can be one of:
0 Center
1 Tile
2 Stretch

Returns:

String.
Returns the file name of the previous wallpaper.

Examples:

Director:
Old = baSetWallpaper( "c:\windows\arcade.bmp", 0 )

Authorware:
Old := baSetWallpaper( "c:\\windows\\arcade.bmp", 0 )

Notes:

You should use the full path name of the wallpaper. A empty string will remove the wallpaper.

On Macintosh, the Tile argument is ignored and the previous wallpaper is not returned.

See also:

baSetPattern


baSetPattern

SetPattern

Description:

baSetPattern allows you to set the desktop pattern.

Platforms:

Windows

Usage:

Result = baSetPattern( Name , Pattern )

Arguments:

String, string.
Name is the name of the pattern.
Pattern is a string containing the pattern.

Returns:

String.
Returns the previous pattern.

Examples:

Director:
Old = baSetPattern( "Bricks" , "187 95 174 93 186 117 234 245" )

Authorware:
Old := baSetPattern( "Bricks" , "187 95 174 93 186 117 234 245" )

Notes:

The standard Windows patterns are listed in the contol.ini file.

See also:

baSetWallpaper


baDesktopColor

DesktopColor

Description:

baDesktopColor returns the desktop color.

Platforms:

Windows

Usage:

Result = baDesktopColor( )

Arguments:

Void.

Returns:

List.
Returns the desktop color.

Examples:

Director:
col = baDesktopColor()

Authorware:
col := baDesktopColor()

Notes:

A property list will be returned with #red, #green and #blue values. For example:

[#red: 0, #green: 128, #blue: 128]

See also:

baSetDesktopColor


baSetDesktopColor

SetDesktopColor

Description:

baSetDesktopColor sets the desktop color.

Platforms:

Windows

Usage:

Result = baDesktopColor( red, green, blue )

Arguments:

Integer, integer, integer.

Returns:

Void.

Examples:

Director:
baSetDesktopColor( 0, 128, 128 )

Authorware:
baSetDesktopColor( 0, 128, 128 )

See also:

baDesktopColor


baSetDisplay

SetDisplay

Description:

baSetDisplay sets the screen size and depth.

Platforms:

Windows and Macintosh

Usage:

Result = baSetDisplay( Width , Height , Depth , Mode , Force )

Arguments:

Integer, integer, integer, string, integer.
Width is the new width of the screen in pixels.
Height is the new height of the screen in pixels.
Depth is the new depth of the screen in bits.
Mode is the way in which the new display is set. On Windows, can be:
"temp" | temporarily change the display settings.
"perm" | permanently change the display settings.
"test" | tests whether the display can be set without restarting.

Mode is ignored on Macintosh.

If Force is true, forces the display to change. Ignored on Macintosh.

Returns:

Integer.
Returns 0 if the display was changed or can be changed without restarting.
Returns 1 if Windows will need to be restarted for the change to take effect.
Returns less than 0 if another error occurred, eg invalid screen size.

Examples:

Director:
OK = baSetDisplay( 640 , 480 , 8 , "temp" , false )

Authorware:
OK := baSetDisplay( 640 , 480 , 8 , "temp" , false )

Notes:

Not all display cards and drivers support screen changing without restarting.

The force option is not officially supported by Microsoft. It forces the display to change without restarting. This may work correctly with some video cards and drivers, but can cause palette problems on others, and crash the system on some. You are advised to only use this option on known hardware and after extensive testing.

If you use the "temp" mode, then the user's preferred screen display will be returned when the system is restarted. You can not set a "temp" mode unless it can be changed without restarting Windows.

The "temp" mode should only be used if you do not intend the user to be able to access the task bar or desktop while your program is running. When using the "temp" mode, Windows may not position the desktop icons and task bar in usable positions.

You are encouraged to use the newer MultiDisplay functions instead of this one.

See also:

baSetDisplayEx
baSetMultiDisplay
baMultiDisplayInfo


baSetDisplayEx

SetDisplayEx

Description:

baSetDisplayEx sets the screen size and depth.

Platforms:

Windows

Usage:

Result = baSetDisplay( Width , Height , Depth , Refresh, Mode , Force )

Arguments:

Integer, integer, integer, integer, string, integer.
Width is the new width of the screen in pixels.
Height is the new height of the screen in pixels.
Depth is the new depth of the screen in bits.
Refresh is the new refresh frequency.
Mode is the way in which the new display is set. Can be:
"temp" | temporarily change the display settings.
"perm" | permanently change the display settings.
"test" | tests whether the display can be set without restarting.
If Force is true, forces the display to change.

Returns:

Integer.
Returns 0 if the display was changed or can be changed without restarting.
Returns 1 if Windows will need to be restarted for the change to take effect.
Returns less than 0 if another error occurred, eg invalid screen size.

Examples:

Director:
OK = baSetDisplayEx( 640 , 480 , 8 , 75 , "temp" , false )

Authorware:
OK := baSetDisplayEx( 640 , 480 , 8 , 75 , "temp" , false )

Notes:

Not all display cards and drivers support screen changing without restarting.

The force option is not officially supported by Microsoft. It forces the display to change without restarting. This may work correctly with some video cards and drivers, but can cause palette problems on others, and crash the system on some. You are advised to only use this option on known hardware and after extensive testing.

If you use the "temp" mode, then the user's preferred screen display will be returned when the system is restarted. You can not set a "temp" mode unless it can be changed without restarting Windows.

The "temp" mode should only be used if you do not intend the user to be able to access the task bar or desktop while your program is running. When using the "temp" mode, Windows may not position the desktop icons and task bar in usable positions.

Use can use baScreenInfo( "refresh" ) to get the current refresh frequency. It is possible to set a frequency that the display card is capable of using but that the monitor can not handle.

The refresh option will only work on NT/2000/XP/Vista.

You are encouraged to use the newer MultiDisplay functions instead of this one.

See also:

baSetDisplay
baSetMultiDisplay
baScreenInfo


baSetMultiDisplay

SetMultiDisplay

Description:

baSetMultiDisplay sets the screen size and depth of multiple monitors.

Platforms:

Windows and Macintosh

Usage:

Result = baSetMultiDisplay( Monitor, Width , Height , Depth , Refresh, Mode , Flags )

Arguments:

String, integer, integer, integer, integer, string, integer.
Monitor is the monitor to change.
Width is the new width of the screen in pixels.
Height is the new height of the screen in pixels.
Depth is the new depth of the screen in bits.
Refresh is the new refresh frequency.
Mode is the way in which the new display is set. On Windows, can be:
"temp" | temporarily change the display settings.
"perm" | permanently change the display settings.
"test" | tests whether the display can be set without restarting.

Mode is ignored on Macintosh.

Flags changes options of the function. Ignored on Macintosh.

Returns:

Integer.
Returns 0 if the display was changed or can be changed without restarting.
Returns 1 if Windows will need to be restarted for the change to take effect.
Returns less than 0 if another error occurred, eg invalid screen size.

Examples:

Director:
OK = baSetMultiDisplay( "primary", 640 , 480 , 8 , 75 , "temp" , 2 )

Authorware:
OK := baSetMultiDisplay( "primary", 640 , 480 , 8 , 75 , "temp" , 2 )

Notes:

Monitor is the name of the monitor to change, eg: " \\.\DISPLAY1" (Windows) or "64298569" (Macintosh). You can get a list of the current monitors by calling baMultiDisplayList. You can use a value of "primary" to set the primary display without knowing its name, and "secondary" to change the secondary display.

There are 2 flags defined:

1 | Forces the display to change even if it doesn't support changing. Use with caution. Windows only
2 | When the projector quits, the screen settings will be reset to their original values. Using this flag means there is no need for you to restore the display before you quit the projector. All displays in the system will be reset, not just the display specified in the function. On Macintosh, the screen display will always return to the user's original vales when your projector quits, so this flag has no effect.

Not all display cards and drivers support screen changing without restarting.

The force option is not officially supported by Microsoft. It forces the display to change without restarting. This may work correctly with some video cards and drivers, but can cause palette problems on others, and crash the system on some. You are advised to only use this option on known hardware and after extensive testing.

If you use the "temp" mode, then the user's preferred screen display will be returned when the system is restarted. You can not set a "temp" mode unless it can be changed without restarting Windows.

The "temp" mode should only be used if you do not intend the user to be able to access the task bar or desktop while your program is running. When using the "temp" mode, Windows may not position the desktop icons and task bar in usable positions. You should use the "perm" option if you intend to allow the user access to the desktop.

Use can use the refresh option in baMultiDisplayInfo to get the current refresh frequency. It is possible to set a frequency that the display card is capable of using but that the monitor can not handle.

On Macintosh, not all screens support user selected refresh rates. In these cases, use a refresh rate of 0.

See also:

baMultiDisplayInfo
baSetDisplay
baSetDisplayEx


baExitWindows

ExitWindows

Description:

baExitWindows exits or restarts Windows.

Platforms:

Windows

Usage:

baExitWindows( Option )

Arguments:

String.
Option is the type of exit. Can be:
"reboot" | reboots the system
"restart" | restarts Windows
"logoff" | logs off Windows
"shutdown" | shuts down the system
"poweroff" | powers off the system

Returns:

Void.

Examples:

Director:
baExitWindows( "reboot" )

Authorware:
baExitWindows( "reboot" )

Notes:

Not all versions of Windows support all the restarting options. If a particular function is not available, then another mode will be substituted according to the following table.

The system security settings may prohibit some of these options from operating.

 | 95/98/ME | NT/2000/XP/Vista
"reboot" | reboot | reboot
"restart" | restart | reboot
"shutdown" | shutdown | shutdown
"logoff" | logoff | logoff
"poweroff" | poweroff | poweroff


baRunProgram

RunProgram

Description:

baRunProgram runs an external application and can optionally wait until the other program quits before continuing.

Platforms:

Windows and Macintosh

Usage:

Result = baRunProgram( Program , State, Wait )

Arguments:

String, string, integer.
Program is the name of the program to run.
On Windows, can be one of these:
"Normal"shows in its usual state.
"Hidden"is not visible.
"Maximised"shows as a maximised window.
"Minimised"shows as an minimised icon.
On Macintosh, State is ignored.
Wait determines whether the Authorware program continues, or if it waits for the external program to finish before continuing. Can be either true or false.

Returns:

Integer.
Returns a meaningless number greater than 31.
If the return is less than 32, then an error occurred. Some possible Windows error numbers are:
0 | System was out of memory, executable file was corrupt, or relocations were invalid.
1 | Unspecified error.
2 | File was not found.
3 | Path was not found.
5 | Attempt was made to dynamically link to a task, or there was a sharing or network-protection error.
6 | Library required separate data segments for each task.
8 | There was insufficient memory to start the application.
10 | Windows version was incorrect.
11 | Executable file was invalid. Either it was not a Windows application or there was an error in the .EXE image.
12 | Application was designed for a different operating system.
13 | Application was designed for MS-DOS 4.0.
14 | Type of executable file was unknown.
15 | Attempt was made to load a real-mode application (developed for an earlier version of Windows).
16 | Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.
19 | Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded.
20 | Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this application was corrupt.
21 | Application requires 32-bit extensions.

On Macintosh, an error always returns 0.

Examples:

Director:
OK = baRunProgram( "Notepad.exe", "maximised", false )

Authorware:
OK := baRunProgram( "Notepad.exe", "maximised", false )

Notes:

On Windows, where possible, the complete path to the program should be specified. If a path is not provided, then Windows searches for the file in the following order: the current directory, the Windows directory, the Windows system directory, the directory containing the executable file for the current task, the directories listed in the PATH environment variable, the directories mapped in a network.

You are not limited to supplying just an executable file name; you can add any other command line parameters that the executable supports. For example, to load the Adobe Acrobat Reader with mydoc.pdf, use the following call:

baRunProgram( "acroread.exe mydoc.pdf", "maximised", false )

To print an Acrobat file, you can use

baRunProgram( "c:\acrobat\acroread.exe /p mydoc.pdf", "Hidden", true )

On Macintosh, you must supply the full path to the file. Command line arguments are not supported.

If used with the Wait option, this function will not return control to Authorware/Director until the jumped to program has quit. If your user switches back to the Authorware program, it will appear to have frozen. You may choose to display an on-screen message to inform your user of this. You can also use the baWaitTillActive function to pause execution until the Authorware/Director window becomes active again.

See also:

baWaitTillActive
baWaitForWindow
baNextActiveWindow
baOpenFile
baShell


baWinHelp

WinHelp

Description:

baWinHelp displays a windows Help file.

Platforms:

Windows

Usage:

Result = baWinHelp(Cmd, HelpFile, Data )

Arguments:

String, string, string.
Cmd is the help file command. Can be one of the following:
"Contents" | shows the Contents page.
"Context" | shows the page with the "Data" context number.
"PopUp" | shows the page with the "Data" context number in a pop-up window.
"Show" | shows the topic found that matches "Data" if there is one exact match. If there is more than one match, then the Search dialog box is displayed. If there is no exact match, then an error message will appear.
"Search" | shows the topic found that matches "Data" if there is one exact match. If there is more than one match, then the Search dialog box is displayed. If there is no match, then the Search dialog box appears.
"Quit" | closes the Help file.
"Help" | shows the Help-On-Help page.
"Macro" | executes the Help macro named in "Data".
HelpFile is the name of the Help file to display. This should include the complete path to the help file.
Data is a string containing extra information. This will vary according to the Cmd used. Note that even if a number is required, this must be passed as a string.
"Contents" | Data should be "".
"Context" | Data is the context number, eg "4".
"PopUp" | Data is the context number, eg "4".
"Show" | Data is the topic string to show, eg "About BudAPI".
"Search" | Data is the topic string to search for, eg "About BudAPI".
"Quit" | Data should be "".
"Help" | Data should be "".
"Macro" | Data should be the name of the macro to execute, eg "PlayMovie".

Returns:

Integer.
Returns 1 if successful, else 0. Not finding the Help file is not considered a failure.

Examples:

Director:
OK = WinHelp( "Show", the pathName & "myhelp.hlp", "Flowers" )
OK = WinHelp( "Quit", the pathName & "myhelp.hlp", "" )

Authorware:
OK := WinHelp( "Show", FileLocation ^ "myhelp.hlp", "Flowers" )
OK := WinHelp( "Quit", FileLocation ^ "myhelp.hlp", "" )

Notes:

This function only works with .hlp files. Note that support for .hlp files is not standard in Vista.


baMsgBox

MsgBox

Description:

baMsgBox displays a system MessageBox.

Platforms:

Windows and Macintosh

Usage:

Result = baMsgBox( Message, Caption, Buttons, Icon, DefaultButton )

Arguments:

String, string, string, string, integer.
Message is the message to display. This can contain more than one line.
Caption is the caption to show in the Title bar.
Buttons is the type of buttons to display. This can be one of the following:
"OK"
"OKCancel"
"RetryCancel"
"AbortRetryIgnore"
"YesNo"
"YesNoCancel"
Icon is the type of icon to display. This can be one of the following:
"Stop"
"Information"
"Question"
"Exclamation"
"NoIcon"
DefaultButton is the number of the default (selected) button. Can be 1, 2, or 3 depending on the number of buttons. The button on the left hand side is 1.

Returns:

String.
Returns the name of the button clicked eg "OK" or "Ignore".

Examples:

Director:
Answer = baMsgBox( "Is this is a test message?", "A question" , "YesNo", "Question" , 1 )
if Answer = "Yes" then baMsgBox("Correct!" , "The answer", "OK", "Information", 1)

Authorware:
Answer := baMsgBox( "Is this is a test message?", "A question" , "YesNo", "Question" , 1 )
if Answer = "Yes" then baMsgBox("Correct!" , "The answer", "OK", "Information", 1)

Notes:

On Macintosh, you can use alternative icon names "Note" instead of "Information"; "Caution" instead of "Exclamation".

On Macintosh, if the Caption argument is empty, then a nonmovable message box will be used.

See also:

MsgBoxEx
baMsgBoxButtons
baTaskDialog


baMsgBoxEx

MsgBoxEx

Description:

baMsgBoxEx displays a custom MessageBox.

Platforms:

Windows and Macintosh

Usage:

Result = baMsgBoxEx( Message, Caption, Button1, Button2, Button3, Icon, DefButton, Alignment, FontName, FontSize, FontWeight, xPos, yPos )

Arguments:

String, string, string, string, string, string, integer, string, string, integer, integer, integer, integer.
Message is the message to display. This can contain more than one line
Caption is the caption to show in the Title bar
Button1 is the caption of the first button
Button2 is the caption of the second button
Button3 is the caption of the third button
Icon is the type of icon to display. This can be one of the following:
"Stop"
"Information"
"Question"
"Exclamation"
"NoIcon"
DefButton is the number of the default (selected) button. Can be 1, 2, or 3 depending on the number of buttons. The button on the left hand side is 1.
Alignment is the alignment of the message text. Can be:
"left"
"center"
"right"
FontName is the name of the font to use
FontSize is the size of the font
FontWeight is the weight of the font, from 1 - 9
xPos is the horizontal position of the dialog
yPos is the vertical position of the dialog

Returns:

String.
Returns the name of the button clicked eg "OK" or "Cancel"

Examples:

Director:
Answer = baMsgBoxEx( "How are you feeling?", "Online Doctor" , "Great", "Just OK", "Lousy", "Question" , 1 , "center", "Arial", 12, 4, 100, 100 )

Authorware:
Answer := baMsgBoxEx( "How are you feeling?", "Online Doctor" , "Great", "Just OK", "Lousy", "Question" , 1 , "center", "Arial", 12, 4, 100, 100 )

Notes:

If you do not want to show all buttons, then make the button text for the button you don't want to appear an empty string. On Windows, ff you want to add a keyboard shortcut to a button, then place a & in front of the letter you want it to use. eg "&Later". On Macintosh, you can not assign a keyboard shortcut. The size of the buttons does not change - you are limited to about 12 characters for the buttons.

The font weight is in a range from 1 - 9; 4 is normal, 7 is bold. Not all fonts have all weights. Use 0 if you want to use the standard weight of the font. Under Macintosh, any number greater than 5 will be bold.

The values of the xPos and yPos are relative to the screen. Use -1 to center the dialog on the screen, -2 to center on the Director/Authorware window.

See also:

MsgBox
baTaskDialog


baMsgBoxButtons

MsgBoxButttons

Description:

baMsgBoxButtons sets the text of the buttons for MessageBox.

Platforms:

Macintosh

Usage:

Result = baMsgBoxButtons( OK, Cancel, Yes, No, Retry, Ignore, Abort )

Arguments:

String, string, string, string, string, string, string.

Returns:

Void.

Examples:

Director:s
baMsgBoxButtons("","", "Ya", "Nein" , "", "" , "" )

Authorware:
baMsgBoxButtons("","", "Ya", "Nein" , "", "" , "" )

Notes:

This function allows you to localise/customise the text on the buttons of the baMsgBox function. Call this function before you call baMsgBox.
If you want to retain the default text, then pass in an empty string.

If you change the text of a button, baMsgBox will still return the default text of the button clicked.

See also:

baMsgBox


baPrompt

Prompt

Description:

baPrompt displays a prompt dialog box.

Platforms:

Windows and Macintosh

Usage:

Result = baPrompt( Caption, Instruction, DefaultText, Flags, X, Y )

Arguments:

String, string, string, integer, integer, integer.
Caption is the caption to show in the Title bar.
Instruction is the instruction to display to the user.
DefaultText is the text to display in the edit box.
Flags changes the behaviour of the dialog.
X is the horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

String.
Returns the text the user entered, or an empty string if cancelled

Examples:

Director:
pw = baPrompt( "", "Please enter your password:" , "", 2, -1, -1 )

Authorware:
pw := baPrompt( "", "Please enter your password:" , "", 2, -1, -1 )

Notes:

Two flags are currently defined:
1 | only allow numbers to be entered
2 | use ***** to mask the user input

The values of the X and Y are relative to the screen. Use -1 to center the dialog on the screen, -2 to center on the Director/Authorware window.

See also:

LogIn


baLogIn

LogIn

Description:

baLogIn displays a log in dialog box.

Platforms:

Windows and Macintosh

Usage:

Result = baLogIn( Caption, Instruction, UserName, Password, Flags, NameCaption, PasswordCaption, X, Y )

Arguments:

String, string, string, string, integer, string, string, integer, integer.
Caption is the caption to show in the Title bar.
Instruction is the instruction to display to the user.
UserName is the text to display in the user name edit box.
Password is the text to display in the password edit box.
Flags changes the behaviour of the dialog.
NameCaption is the text to display beside the user name edit box.
PasswordCaption is the text to display beside the password edit box.
X is the horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

List.
Returns a property list. See Notes for details.

Examples:

Director:
log = baLogIn( "", "Please log in:" , "", "", 2, "User:", "Password:", -1, -1 ))

Authorware:
log := baLogIn( "", "Please log in:" , "", "", 2, "User:", "Password:", -1, -1 ))

Notes:

The return will be a property list with 3 entries - #Name, #Password and #Ok. For example;

[#Name: "Fred", #Password: "casper", #Ok: 1]

If the user cancels, then #Ok will be equal to 0.

[#Name: "", #Password: "", #Ok: 0]

Five flags are currently defined:

1 | only allow numbers to be entered
2 | use ***** to mask the password input
4 | Don't allow spaces to be entered
8 | Do not allow blank user name
16 | Do not allow blank password

The values of the X and Y are relative to the screen. Use -1 to center the dialog on the screen, -2 to center on the Director/Authorware window.

See also:

baPrompt


baTaskDialog

TaskDialog

Description:

baTaskDialog shows a Vista style Task Dialog.

Platforms:

Windows

Usage:

Result = baTaskDialog( Options )

Arguments:

List.
Options is a property list with the dialog options. See Notes for details.

Returns:

List.
Returns a list with the result of the dialog. There will always be a #button entry in the list with the #button equal to the number of the button the user clicked, or 0 if the user cancelled. See Notes for more details.

Examples:

Director:
Options = [ #Message: "This is a task dialog. Do you like it?", #Button1: "Yes", #Button2: "No" ]
res = baTaskDialog( Options )
if res.button = 1 then -- user selected Yes.

Authorware:
This function is not available for Authorware.

Notes:

The Task Dialog has a large number of options. All are optional, but leaving out some will not make sense. At teh least, you should include a #Message and #Button1.

The options available are:

#Message | The main message.
#Title | The title of the dialog.
#Content | Smaller text under the main message.
#Footer | Small text at the bottom of the dialog.
#Button1, #Button2, etc | The text for the buttons. Up to 5 different buttons can be defined. You can place a RETURN in the text to make a second line with more information. For example: [ #Button1: "Yes" & RETURN & "I really do want to do this." ]
#DefaultButton: | Set to the number of the button to use as the default.
#StandardButtons | Set to 1 to use standard buttons instead of links.
#NoCommandIcon | Set to 1 to not show a icon beside the buttons.
#CloseButton | Set to 1 to include a close button in the title bar. If the user clicks this button, then the #button property in the return list will be 0.
#Icon | The icon to show. Can be "Error", "Information", "Warning", "Shield" or the full path to an .ico file.
#FooterIcon | The icon to show beside the Footer text. Can be "Error", "Information", "Warning", or the full path to an .ico file. Only available if #Footer is supplied.
#ExpandedInformation | Text to show when user clicks the "More details" button.
#CollapsedControlText | Text to use for the "More details" button.
#ExpandedControlText | Text to use for the "Fewer details" button.
#ExpandedInFooter | Set to 1 to show the #ExpandedInformation text in the footer instead of below the main message.
#OpenExpanded | Set to 1 to expand the #ExpandedInformation text when the dialog is opened.
#EnableHyperlinks | Set to 1 to enable the use of hyperlinks in the #Content, #Footer or #ExpandedInformation text. For example: [ #Content: "Visit the <A HREF=" & QUOTE & "http://www.mods.com.au" & QUOTE & ">Buddy API</A> web site." , #EnableHyperlinks: 1 ]
#VerificationText | Text to show with a check box beside it. If this option is included, then the return list will include an #checked entry set to 1 if the check box was checked when the dialog was closed or 0 if it wasn't.
#VerificationChecked | Set to 1 to check the verification box when the dialog is opened.
#Radio1, #Radio2, etc | The text for radio buttons. Up to 5 radio buttons can be defined. If this option is included, then the return list will include an #radio entry set to the number that was selected when the dialog was closed.
#DefaultRadioButton | Set the number of the radio button to be selected when the dialog is opened.
#CenterOnStage | Set to 1 to center the dialog on the Director/Authorware window, instead of the center of the screen.
#Emulated: | Set to 1 to use emulated mode on Vista. This function is only native on Vista, on earlier versions the dialog will be emulated. There will be visual differences between the emulated and the native dialogs. Use this option to have the dialog look the same on all Windows, although that will mean on Vista, the standard dialog will not be used and may not follow the user's interface preferences.

See also:

baMsgBox
baMsgBoxEx


baSleep

Sleep

Description:

baSleep pauses the calling Director/Authorware program.

Platforms:

Windows

Usage:

baSleep( milliSecs )

Arguments:

Integer.
milliSecs is the time to sleep for, in thousandths of a second.

Returns:

Void.

Examples:

Director:
baSleep( 200 )

Authorware:
baSleep( 200 )

Notes:

This function is most useful for 'lowering' the priority of Director to allow other programs a larger slice of available processing time - for example when playing a mpeg movie. Calling this function in a loop such as in a on exitFrame handler, will give other processes a chance to run while still allowing Director to process events such as mouse clicks. Larger numbers will give other programs more time, but slow down Director responses. Values between 50 and 200 would be a good starting point for experimentation.


baHideTaskBar

HideTaskBar

Description:

baHideTaskBar shows/hides the Windows Task Bar or Macintosh Dock.

Platforms:

Windows and Macintosh

Usage:

Result = baHideTaskBar( Hide )

Arguments:

Integer.
If Hide is true, the task bar is hidden, else it will be visible.

Returns:

Integer.
Returns the previous state of the task bar - 1 if it is visible, 0 if it isn't.

Examples:

Director:
showing = baHideTaskBar( true )

Authorware:
showing := baHideTaskBar( true )

Notes:

On Windows, this function will not change the user's task bar settings: the 'Always on top' and 'Auto hide' settings.

On Macintosh, this function works under OSX 10.2 and later. There are differences between the way the function works under 10.2 and 10.3 and 10.4, due to Apple bugs and differences in implementation between the two operating systems.

baHideTaskBar( 0 ) shows the dock and menubar
baHideTaskBar( 1 ) hides only the dock on 10.3 and 10.4; hides the dock and menu bar on 10.2
baHideTaskBar( 2 ) hides the dock and menu bar on both
baHideTaskBar( 3 ) sets the dock to autohide on 10.3 and 10.4; hides the dock and menu bar on 10.2

The dock and menu bar will be hidden only when the projector is the active application. On 10.2, when the projector is activated again, the dock will be hidden again; under 10.3 and 10.4 it won't be.

The function return on Macintosh will always be 0.


baSetCurrentDir

SetCurrentDir

Description:

baSetCurrentDir sets the current directory.

Platforms:

Windows

Usage:

Result = baSetCurrentDir( Dir )

Arguments:

String.
Dir is the full path name of the directory to make current.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baSetCurrentDir( "c:\temp" )

Authorware:
OK := baSetCurrentDir( "c:\\temp" )

Notes:

This function is useful when running external programs using the baRunProgram function. Some programs, particularly DOS ones, require the current directory to be set first. The current directory can be retrieved using the baSysFolder function.

See also:

SysFolder


baCopyText

CopyText

Description: | baCopyText copies text to the clipboard.
Platforms: | Windows and Macintosh
Usage: | Result = baCopyText( ClipText )
Arguments: | String. ClipText is the text to copy to the clipboard.
Returns: | Integer. Returns 1 if the function is successful, otherwise 0.
Examples: | Director: OK = baCopyText( UserName ) Authorware: OK := baCopyText( UserName )
See also: | baPasteText


baPasteText

PasteText

Description:

baPasteText copies text from the clipboard.

Platforms:

Windows and Macintosh

Usage:

Result = baPasteText()

Arguments:

None.

Returns:

String.

Examples:

Director:
ClipText = baPasteText()

Authorware:
ClipText := baPasteText()

See also:

baCopyText


baEncryptText

EncryptText

Description:

baEncryptText encrypts a text string.

Platforms:

Windows and Macintosh

Usage:

Result = baEncryptText( String , Key )

Arguments:

String, string.
String is the text to encrypt.
Key is the string to use as the encryption key.

Returns:

String.
Returns the encrypted string.

Examples:

Director:
text = baEncryptText( "MyPassword" , "This is my key" )

Authorware:
test := baEncryptText( "MyPassword" , "This is my key" )

Notes:

This function uses an xor routine to encrypt the text. To decrypt the text, use the baDecryptText function using the same key. This will return the original text.

As well as encrypting the text, this function also puts the text through a uuencode type function to ensure that the encrypted string contains only printable characters. This means that the encrypted string will not be the same length as the original string.

The maximum size of the string that can be encrypted is 24000 characters.

See also:

baDecryptText


baDecryptText

DecryptText

Description:

baDecryptText decrypts a string encrypted with baEncryptText.

Platforms:

Windows and Macintosh

Usage:

Result = baDecryptText( String , Key )

Arguments:

String, string.
String is the text to decrypt.
Key is the string that was used as the encryption key.

Returns:

String.
Returns the decrypted string.

Examples:

Director:
text = baDecryptText( "MyEncryptedPassword" , "This is my key" )

Authorware:
text := baDecryptText( "MyEncryptedPassword" , "This is my key" )

See also:

baEncryptText


baPlaceCursor

PlaceCursor

Description:

baPlaceCursor positions the cursor on the screen.

Platforms:

Windows and Macintosh

Usage:

baPlaceCursor( X, Y )

Arguments:

Integer, integer.
X an Y is the new position of the cursor, measured from the top left corner of the screen.

Returns:

Void.

Examples:

Director:
baPlaceCursor( 200 , 300 )

Authorware:
baPlaceCursor( 200 , 300 )

See also:

baRestrictCursor


baRestrictCursor

RestrictCursor

Description:

baRestrictCursor restricts the cursor to a specified part of the screen.

Platforms:

Windows

Usage:

baRestrictCursor( Left, Top, Right, Bottom )

Arguments:

Integer, integer, integer, integer.
Left, Top, Right, Bottom define the rectangle that the cursor will be restricted to. They are measured in pixels from the top left corner of the screen.

Returns:

Void.

Examples:

Director:
baRestrictCursor( 100, 100, 200, 200 )

Authorware:
baRestrictCursor( 100, 100, 200, 200 )

Notes:

Use the baFreeCursor function to return the cursor to its normal state.

See also:

baFreeCursor
baPlaceCursor


baFreeCursor

FreeCursor

Description:

baFreeCursor allows the cursor to move anywhere on the screen. It is used to free the cursor after using baRestrictCursor.

Platforms:

Windows

Usage:

baFreeCursor( )

Arguments:

None.

Returns:

Void.

Examples:

Director:
baFreeCursor( )

Authorware:
baFreeCursor( )

See also:

baRestrictCursor


baSetVolume

SetVolume

Description:

baSetVolume sets the volume level of the sound card for wave files and audio CD.

Platforms:

Windows and Macintosh

Usage:

Result = baSetVolume( Device, Volume )

Arguments:

String, integer.
Device is the device to get the volume of. Can be:
Windows 2000/XP
"master" | gets the master volume
"wave" | gets the volume of wave and video files
"cd" | gets the volume of audio CD playback
"midi" | gets the volume of an external midi device
"synth" | gets the volume of the internal FM synthesizer
"master mute" | gets the master mute state
"wave mute" | gets the wave mute state
"cd mute" | gets the CD mute state
"synth mute" | gets the built-in synthesizer mute state
Windows Vista
"master" | gets the master volume
"master mute" | gets the master mute state
"record" | gets the master recording volume
"record mute" | gets the master recording mute state
Macintosh
"speakers" | gets the volume of external speaker
"wave" | gets the volume of internal speaker

Volume is the volume level to set. The volume level can be between 0 (silence) and 100 (maximum). For the mute devices, Volume can be either 1 for mute on, or 0 for mute off.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baSetVolume( "cd" , 50 )

Authorware:
OK := baSetVolume( "cd" , 50 )

Notes:

Not all sound cards support this function. Some cards will only support some of the device types. They will return -1 if the function is not supported.

The function will set the volume from the first sound card found.

Some sound cards do not set the volume precisely. For example, if you set the volume to 50, then call the baGetVolume function, it may return 48 or 49.

On Windows Vista, Microsoft made some big changes to the way the sound API works, you can no longer set the level for individual device types.

On Macintosh, you can also use "master" for "speakers".

See also:

baGetVolume


baGetVolume

GetVolume

Description:

baGetVolume gets the current system volume level.

Platforms:

Windows and Macintosh

Usage:

Result = baGetVolume( Device )

Arguments:

String.
Device is the device to get the volume of. Can be:
Windows NT/2000/XP
"master" | gets the master volume
"wave" | gets the volume of wave and video files
"cd" | gets the volume of audio CD playback
"midi" | gets the volume of an external midi device
"synth" | gets the volume of the internal FM synthesizer
"master mute" | gets the master mute state
"wave mute" | gets the wave mute state
"cd mute" | gets the CD mute state
"synth mute" | gets the built-in synthesizer mute state
Windows Vista
"master" | gets the master volume
"master mute" | gets the master mute state
"record" | gets the master recording volume
"record mute" | gets the master recording mute state
Macintosh
"speakers" | gets the volume of external speaker
"wave" | gets the volume of internal speaker

Returns:

Integer.
Returns the volume of the requested device. The volume level can be between 0 (silence) and 100 (maximum). The mute options will return 1 if the mute is on, or 0 if it isn't.
Returns -1 if the function is not supported.

Examples:

Director:
Volume = baGetVolume( "wave" )

Authorware:
Volume := baGetVolume( "wave" )

Notes:

Not all sound cards support this function. Some cards will only support some of the device types. They will return -1 if the function is not supported.

The function will get the volume from the first sound card found.

If the left and right channels are at different levels, then the average of the two is returned.

Some sound cards do not set the volume precisely. For example, if you set the volume to 50 using the baSetVolume function, then call this function, it may return an 48 or 49.

On Windows Vista, Microsoft made some big changes to the way the sound API works, you can no longer set the level for individual device types.

On Macintosh, you can also use "master" for "speakers".

See also:

baSetVolume


baEnvironment

Environment

Description:

baEnvironment returns the value of an environment variable.

Platforms:

Windows

Usage:

Result = baEnvironment( Variable )

Arguments:

String.
Variable is the name of the variable to get.

Returns:

String.
Returns the value of the variable, or an empty string if the variable doesn't exist.

Examples:

Director:
path = baEnvironment( "PATH" )

Authorware:
user := baEnvironment( "USERNAME" )

Notes:

There are both system (available to all applications) and local (available only to the current application) variables, and they may have the same name. This function will work with both types of variables. It will first check if there is a local variable, if there isn’t then it will check for a system variable.

See also:

baSetEnvironment


baSetEnvironment

SetEnvironment

Description:

baSetEnvironment sets the value of an environment variable.

Platforms:

Windows

Usage:

Result = baSetEnvironment( Variable, Value )

Arguments:

String, string.
Variable is the name of the variable to get.
Value is the value to set the variable to.

Returns:

Integer.
Returns 1 if successful, otherwise 0.

Examples:

Director:
OK = baSetEnvironment( "UserResults", "pass" )

Authorware:
OK := baSetEnvironment( "UserResults", "pass" )

Notes:

There are both system (available to all applications) and local (available only to the current application) variables, and they may have the same name. This function will only work with local variables, and will not change system variables. For example, you can not change the system path variable using this functions.

See also:

baEnvironment


baAdministrator

Administrator

Description:

baAdministrator checks whether the current user has Administrator rights.

Platforms:

Windows

Usage:

Result = baAdministrator( )

Arguments:

None.

Returns:

Integer.
Returns 1 if the user has Administrator rights, otherwise 0.

Examples:

Director:
OK = baAdministrator( )

Authorware:
OK := baAdministrator( )

Notes:

This function does not work on 95, 98 or ME and it will always return 0.


baUserName

UserName

Description:

baUserName returns the log on name of the current user.

Platforms:

Windows and Macintosh

Usage:

Result = baUserName( )

Arguments:

None.

Returns:

String.

Examples:

Director:
name = baUserName( )

Authorware:
name := baUserName( )

See also:

baUserShortName
baComputerName


baUserShortName

UserShortName

Description:

baUserShortName returns the short name of the current user.

Platforms:

Macintosh

Usage:

Result = baUserShortName( )

Arguments:

None.

Returns:

String.

Examples:

Director:
name = baUserShortName( )

Authorware:
name := baUserShortName( )

See also:

baUserName
baComputerName


baComputerName

ComputerName

Description:

baComputerName returns the network name of the computer.

Platforms:

Windows and Macintosh

Usage:

Result = baComputerName( )

Arguments:

None.

Returns:

String.

Examples:

Director:
name = baComputerName( )

Authorware:
name := baComputerName( )

See also:

baUserName


baLanguage

Language

Description:

baLanguage returns the language currently in use.

Platforms:

Windows and Macintosh

Usage:

Result = baLanguage( )

Arguments:

None.

Returns:

Integer.

Examples:

Director:
set lang = baLanguage( )

Authorware:
lang := baLanguage( )

Notes:

On Macintosh, some possible returns are:

0 | English
1 | French
2 | German
3 | Italian
4 | Dutch
5 | Swedish
6 | Spanish
7 | Danish
8 | Portuguese
9 | Norwegian
10 | Hebrew
11 | Japanese
12 | Arabic
13 | Finnish
14 | Greek

A more complete list can be found at
http://www.mods.com.au/budapi/mac_language_codes.htm

On Windows, some possible returns are:

9 | English
12 | French
7 | German
16 | Italian
19 | Dutch
29 | Swedish
10 | Spanish
6 | Danish
22 | Portuguese
20 | Norwegian
13 | Hebrew
17 | Japanese
1 | Arabic
11 | Finnish
8 | Greek

A more complete list can be found at
http://www.mods.com.au/budapi/win_language_codes.htm


baIsLimited

IsLimited

Description:

baIsLimited checks if the program is being run as a Limited user under Vista.

Platforms:

Windows

Usage:

Result = baIsLimited( )

Arguments:

None.

Returns:

Integer.
Returns 1 if program is a Limited user, else 0.

Examples:

Director:
limited = baIsLimited( )

Authorware:
limited := baIsLimited( )

Notes:

This function only works on Vista, if used under earlier Windows it will always return 0.

Vista has a new User Account Control feature which provides security for Limited users.

baIsLimited checks if the program is being run as a Limited user. If UAC is disabled, then this function will return false. If your program is run as a standard user with UAC enabled, then it will return true. If your program is run as an Administrator and UAC is enabled, the user will be presented with a 'Allow this program to run' dialog. If the user allows the program to run, then this function will return false.

See also:

baIsVirtualized


baIsVirtualized

IsVirtualized

Description:

baIsVirtualized checks if program's file access is being virtualized under Vista.

Platforms:

Windows

Usage:

Result = baIsVirtualized( )

Arguments:

None.

Returns:

Integer.
Returns 1 if program is being virtualized, else 0.

Examples:

Director:
virt = baIsVirtualized( )

Authorware:
virt := baIsVirtualized( )

Notes:

This function only works on Vista, if used under earlier Windows it will always return 0.

If a program is run by a Limited user, then any attempts to write to either the Windows or Program Files will result in the files being saved in the <user>\AppData\Local\VirtualStore folder instead. Attempting to write to the LOCAL_MACHINE branch of the registry will result in the data being written to the CLASSES_ROOT\VirtualStore branch instead. This process is called virtualization. baIsVirtualized returns true if the current program's file access will be virtualized.

To find the VirtualStore folder, use :

baSysFolder( "28" ) & "VirtualStore"

The VirtualStore folder name is never localised.

See also:

baIsLimited


baInstallFont

InstallFont

Description:

baInstallFont installs a TrueType or Bitmap font.

Platforms:

Windows

Usage:

Result = baInstallFont( FontFile, FontName )

Arguments:

String, string.
FontFile is the .ttf or .fon file to install.
FontName is the name of the font.

Returns:

Integer.
Returns 0 if font installs OK. Otherwise returns one of
1 | A font file with that name already exists.
2 | The font file was not found.
3 | Error copying font file.
4 | Windows couldn't install the font.
5 | The font file is an invalid name.

Examples:

Director:
OK = baInstallFont( the moviePath & "arialb.ttf" , "Arial Bold" )

Authorware:
OK := baInstallFont( FileLocation ^ "arialb.ttf" , "Arial Bold" )

Notes:

Most fonts are copyrighted material. You should not install a font unless you are legally allowed to do so.

The name of the font should be taken from the Fonts Control Panel. The name that Windows identifies the font to applications is taken from information inside the font file, not the name you give it.

You should use the baFontInstalled command to check whether or not a particular font is already installed before you try to install a new copy.

Director does not rebuild it's font list after it has been started. This means that the font will not be available to the projector that installed it unless it is restarted. All versions of Authorware should be able to use the font immediately. There is usually no need to restart Windows.

See also:

baFontInstalled
baFontStyleList
baFontList


baKeyIsDown

KeyIsDown

Description:

baKeyIsDown checks whether a key is currently down.

Platforms:

Windows and Macintosh

Usage:

Result = baKeyIsDown( Key )

Arguments:

Integer.
Key is the virtual key code of the key to test.

Returns:

Integer.
Returns 1 if Key is being held down, else 0.

Examples:

Director:
KeyDown = baKeyIsDown( 65 ) -- check if the "a" key is down

Authorware:
KeyDown := baKeyIsDown( 65 ) -- check if the "a" key is down

Notes:

A list of Virtual Key Codes is supplied. Some of these keys are not available in different versions of Windows.

See also:

baKeyBeenPressed


baKeyBeenPressed

KeyBeenPressed

Description:

baKeyBeenPressed checks whether a key has been pressed since the last time the function was called.

Platforms:

Windows

Usage:

Result = baKeyBeenPressed( Key )

Arguments:

Integer.
Key is the virtual key code of the key to test.

Returns:

Integer.
Returns 1 if Key has been pressed since the last time the function was called, else 0.

Examples:

Director:
KeyBeenPressed = baKeyBeenPressed( 65 ) -- check if the "a" key has been pressed

Authorware:
KeyBeenPressed := baKeyBeenPressed( 65 ) -- check if the "a" key has been pressed

Notes:

A list of Virtual Key Codes is supplied. Some of these keys are not available in different versions of Windows.

This function tracks key presses in all applications, not just yours.

See also:

baKeyIsDown


Virtual Key Codes

vk_BackSpace = 8 | vk_Tab = 9 | vk_Return = 13
vk_Command = 15 M | vk_Shift = 16 | vk_Control = 17
vk_Alt = 18 | vk_Pause = 19 | vk_CapsLock = 20
vk_Escape = 27 | vk_Space = 32 | vk_PageUp = 33
vk_PageDown = 34 | vk_End = 35 | vk_Home = 36
vk_Left = 37 | vk_Up = 38 | vk_Right = 39
vk_Down = 40 | vk_PrintScreen = 44 | vk_Insert = 45
vk_Delete = 46 |  |
vk_0 = 48 | vk_1 = 49 | vk_2 = 50
vk_3 = 51 | vk_4 = 52 | vk_5 = 53
vk_6 = 54 | vk_7 = 55 | vk_8 = 56
vk_9 = 57 |  |
vk_A = 65 | vk_B = 66 | vk_C = 67
vk_D = 68 | vk_E = 69 | vk_F = 70
vk_G = 71 | vk_H = 72 | vk_I = 73
vk_J = 74 | vk_K = 75 | vk_L = 76
vk_M = 77 | vk_N = 78 | vk_O = 79
vk_P = 80 | vk_Q = 81 | vk_R = 82
vk_S = 83 | vk_T = 84 | vk_U = 85
vk_V = 86 | vk_W = 87 | vk_X = 88
vk_Y = 89 | vk_Z = 90 |
vk_LWin = 91 * | vk_RWin = 92 * | vk_Apps = 93 *
vk_NumPad0 = 96 | vk_NumPad1 = 97 | vk_NumPad2 = 98
vk_NumPad3 = 99 | vk_NumPad4 = 100 | vk_NumPad5 = 101
vk_NumPad6 = 102 | vk_NumPad7 = 103 | vk_NumPad8 = 104
vk_NumPad9 = 105 | vk_Multiply = 106 | vk_Add = 107
vk_Subtract = 109 | vk_Decimal = 110 | vk_Divide = 111
vk_F1 = 112 | vk_F2 = 113 | vk_F3 = 114
vk_F4 = 115 | vk_F5 = 116 | vk_F6 = 117
vk_F7 = 118 | vk_F8 = 119 | vk_F9 = 120
vk_F10 = 121 | vk_F11 = 122 | vk_F12 = 123
vk_F13 = 124 | vk_F14 = 125 | vk_F15 = 126
vk_F16 = 127 |  |
vk_NumLock = 144 | vk_ScrollLock = 145 | vk_LShift = 160 **
vk_RShift = 161 ** | vk_LControl = 162 ** | vk_RControl = 163 **
vk_LAlt = 164 ** | vk_RAlt = 165 ** | vk_SemiColon = 186
vk_Equals = 187 | vk_Comma = 188 | vk_UnderScore = 189
vk_Period = 190 | vk_Slash = 191 | vk_BackSlash = 220
vk_RightBrace = 221 | vk_LeftBrace = 219 | vk_Apostrophe = 222

* Available in 95/NT4 only
** Available in 2000/XP/Vista only
M Available in Macintosh only

See also:

baKeyIsDown
baKeyBeenPressed
baMakeShortcutEx


baCapsLockOn

CapsLockOn

Description:

baCapsLockOn determines the current state of the Caps Lock key.

Platforms:

Windows

Usage:

Result = baCapsLockOn( )

Arguments:

None.

Returns:

Returns 1 if the Caps Lock key is on, else 0.

Examples:

Director:
capsOn = baCapsLockOn( )

Authorware:
capsOn := baCapsLockOn( )

See also:

baSetCapsLockOn
baNumLockOn
baSetNumLockOn


baSetCapsLockOn

SetCapsLockOn

Description: | baSetCapsLockOn sets the state of the Caps Lock key.
Platforms: | Windows
Usage: | Result = baSetCapsLockOn( On )
Arguments: | Integer. If On is true, the Caps Lock key is turned on, otherwise it is turned off.
Returns: | Void.
Examples: | Director: baSetCapsLockOn( true ) Authorware: baCapsLockOn( false )
See also: | baCapsLockOn baNumLockOn baSetNumLockOn


baNumLockOn

NumLockOn

Description:

baNumLockOn determines the current state of the Num Lock key.

Platforms:

Windows

Usage:

Result = baNumLockOn( )

Arguments:

None.

Returns:

Integer.
Returns 1 if the Caps Lock key is on, else 0.

Examples:

Director:
numOn = baNumLockOn( )

Authorware:
numOn := baNumLockOn( )

See also:

baSetNumLockOn
baCapsLockOn
baSetCapsLockOn


baSetNumLockOn

SetNumLockOn

Description: | baSetNumLockOn sets the state of the Num Lock key.
Platforms: | Windows
Usage: | Result = baSetNumLockOn( On )
Arguments: | Integer. If On is true, the Num Lock key is turned on, otherwise it is turned off.
Returns: | Void.
Examples: | Director: baSetNumLockOn( true ) Authorware: baNumLockOn( false )
See also: | baNumLockOn baCapsLockOn baSetCapsLockOn


baEjectDisk

EjectDisk

Description:

baEjectDisk ejects a CD.

Platforms:

Windows and Macintosh

Usage:

Result = baEjectDisk( Drive )

Arguments:

String.
The drive to eject.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baEjectDisk( "e:\" ) -- eject E drive

Authorware:
OK := baEjectDisk( "e:\\" )

Notes:

On Windows, you can specify the drive as a drive letter - "e:\", or as the name of the CD - "magic:". If using the name of the CD, the name must end with a colon.

On Macintosh, you must use the name of the disk.


baCreatePMGroup

CreatePMGroup

Description:

baCreatePMGroup makes a Start Menu group.

Platforms:

Windows

Usage:

Result = baCreatePMGroup( Group )

Arguments:

String.
Group is the name of the group to create.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baCreatePMGroup( "Multimedia World" )

Authorware:
OK := baCreatePMGroup( "Multimedia World" )

Notes:

This function creates a Start Menu group for the current user. See baCreatePMCommonGroup to create a group for All Users.

See also:

baCreatePMCommonGroup
baDeletePMGroup
baPMGroupList
baCreatePMIcon
baDeletePMIcon
baPMIconList


baCreatePMCommonGroup

CreatePMCommonGroup

Description:

baCreatePMGroup makes a Common Start Menu group.

Platforms:

Windows

Usage:

Result = baCreatePMGroup( Group )

Arguments:

String.
Group is the name of the group to create.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baCreatePMGroup( "Multimedia World" )

Authorware:
OK := baCreatePMGroup( "Multimedia World" )

Notes:

This function creates a Start Menu group for All Users. See baCreatePMGroup to create a group for the current user.

See also:

baCreatePMGroup
baDeletePMGroup
baPMGroupList
baCreatePMIcon
baDeletePMIcon
baPMIconList


baDeletePMGroup

DeletePMGroup

Description:

baDeletePMGroup deletes a Start Menu group.

Platforms:

Windows

Usage:

Result = baDeletePMGroup( Group )

Arguments:

String.
Group is the name of the group to delete.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baDeletePMGroup( "Multimedia World" )

Authorware:
OK := baDeletePMGroup( "Multimedia World" )

Notes:

The group does not have to be empty for it to be deleted.

See also:

baCreatePMGroup
baPMGroupList
baCreatePMIcon
baDeletePMIcon
baPMIconList


baPMGroupList

PMGroupList

Description:

baPMGroupList returns a list of all Start Menu groups.

Platforms:

Windows

Usage:

Result = baPMGroupList( )

Arguments:

Void.

Returns:

List.
Returns a list or string containing all Start Menu groups.

Examples:

Director:
GroupList = baPMGroupList( )

Authorware:
GroupList := baPMGroupList( )

See also:

baPMSubGroupList
baCreatePMGroup
baDeletePMGroup
baCreatePMIcon
baDeletePMIcon
baPMIconList


baPMSubGroupList

PMSubGroupList

Description:

baPMSubGroupList returns a list of Start Menu groups inside another group.

Platforms:

Windows

Usage:

Result = baPMSubGroupList( GroupName )

Arguments:

String.
Group is the name of the group to get the list of.

Returns:

List
Returns a list or string containing the groups.

Examples:

Director:
GroupList = baPMSubGroupList( "Accessories" )

Authorware:
GroupList := baPMSubGroupList( "Accessories " )

Notes:

This function returns the groups inside a group. To get the contents of a group inside a group, place a "\" between the groups ("\\" in Authorware) eg

baPMSubGroupList( "Accessories\Multimedia" ).

See also:

baPMGroupList
baCreatePMGroup
baDeletePMGroup
baCreatePMIcon
baDeletePMIcon
baPMIconList


baCreatePMIcon

CreatePMIcon

Description:

baCreatePMIcon creates a Start Menu icon.

Platforms:

Windows

Usage:

Result = baCreatePMIcon( Command, Title, Icon, IconNumber )

Arguments:

String, string, string, integer.
Command is the command line to use in the icon.
Title is the name that appears under the icon.
Icon is the name of the icon to use.
IconNumber is the number of the icon to use.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baCreatePMIcon( "d:\mterms.exe", "Multimedia Terms" , "d:\mterms.ico" , 0 )

Authorware:
OK := baCreatePMIcon( "d:\\mterms.exe", "Multimedia Terms" , " d:\\mterms.ico" , 0 )

Notes:

The icon will be added to the active Start Menu group. To ensure that the group you want to add the icon to is active, you should always call baCreatePMGroup or baCreatePMCommonGroup before you use this function (even if the group already exists). This will make the group the active one. If you are adding multiple icons, you only need to make one call to baCreatePMGroup or baCreatePMCommonGroup before you start adding icons.

If you create a group, and want to add icons to it, you should allow enough time for Windows to create the group before you try to add an icon to it. A wait of one second should be enough, but slow machines running Win95 may take longer.

The Icon parameter can be either an .ico, .exe or .dll file. If the file is a .ico, then the IconNumber parameter is ignored. If it is a .exe or .dll file, then the IconNumber is the number of the icon in that file to use. If the Icon is an empty string (""), then the first icon in the Command .exe file will be used.

For example:

baCreatePMIcon( "d:\mterms.exe", "Multimedia Terms" , "" , 0 )

will use the default icon for d:\mterms.exe.

baCreatePMIcon( "d:\mterms.exe", "Multimedia Terms" , "d:\mterms.ico" , 0 )

will use the d:\mterms.ico icon.

baCreatePMIcon( "d:\mterms.exe", "Multimedia Terms" , "c:\windows\moreicons.dll" , 5 )

will use the fifth icon in moreicons.dll.

You need to ensure that the filenames you pass into the function do not contain a space – use the baShortFilename function to return the short version of a filename.

See also:

baCreatePMGroup
baDeletePMGroup
baPMGroupList
baPMSubGroupList
baDeletePMIcon
baPMIconList


baPMIconList

PMIconList

Description:

baPMIconList returns a list containing all the icons in a Start Menu group.

Platforms:

Windows

Usage:

Result = baPMIconList( Group )

Arguments:

String.
Group is the name of the group to get the icons of.

Returns:

List.
Returns a list or string containing all the icons in Group.
If Group does not exist or it empty, then an empty list or string will be returned.

Examples:

Director:
IconList = baPMIconList( "Macromedia" )

Authorware:
IconList := baPMIconList( "Macromedia" )

Notes:

You can also get the contents of a nested group, by placing a "\" ("\\" in Authorware) between the groups. eg baPMIconList( "Accessories\Multimedia" ) will get the contents of the Multimedia group, inside the Accessories group.

See also:

baCreatePMGroup
baDeletePMGroup
baPMGroupList
baPMSubGroupList
baCreatePMIcon
baDeletePMIcon


baSystemTime

SystemTime

Description:

baSystemTime returns the current time/date.

Platforms:

Windows and Macintosh

Usage:

Result = baSystemTime( Format )

Arguments:

String.
Format is the time/date format to return.

Returns:

String.
Returns the requested time/date.

Examples:

Director:
theTime = baSystemTime( "date" )

Authorware:
theTime := baSystemTime( "Today is %A" ) -- returns the day eg "Today is Tuesday"

Notes:

There are two predefined formats - "time" and "date"

"time" will return the current time in 24 hour format with leading zeros - hours, minutes and seconds eg "230412". It will always be 6 characters long.

"date" will return the date in year, month, day eg "19980321". It will always be 8 characters long,

Other formatting is available. Any of these constants will be replaced by the appropriate time/date - any other characters will be returned as is.

%a | Abbreviated weekday name
%A | Full weekday name
%b | Abbreviated month name
%B | Full month name
%d | Day of month as decimal number (1 - 31)
%0d | Day of month with leading 0
%H | Hour in 24-hour format (0 - 23)
%0H | Hour in 24-hour format with leading 0
%j | Day of year as decimal number (1 - 366)
%0j | Day of year as decimal number with leading 0
%m | Month as decimal number (1 - 12)
%0m | Month as decimal number with leading 0
%M | Minute as decimal number (0 - 59)
%0M | Minute as decimal number with leading 0
%S | Second as decimal number (0 - 59)
%0S | Second as decimal number with leading 0
%w | Weekday as decimal number (0 - 6; Sunday is 0)
%y | Year without century, as decimal number (00 - 99)
%Y | Year with century, as decimal number

Examples:

"%d %B, %Y" - "2 June, 1998"

"It is %M past %H on %A" - "It is 23 past 10 on Tuesday"

"The time is %H:%0M:%0S" - "The time is 14:25:04"

See also:

baSetSystemTime


baSetSystemTime

SetSystemTime

Description:

baSetSystemTime sets the current time/date.

Platforms:

Windows

Usage:

Result = baSetSystemTime( Format, NewTime )

Arguments:

String, string.
Format is the time/date format to set. Can be either "time" or "date".
NewTime is the time/date to set.

Returns:

Integer.
Returns 1 if successful, otherwise 0.

Examples:

Director:
ok = baSetSystemTime( "date", "19980523" ) - sets the date to 23 June 1998

Authorware:
ok := baSetSystemTime( "time", "102300" ) - sets the time to 23 past 10

Notes:

The format for the time or date must be as follows:

"time" is in 24 hour format with leading zeros - hours, minutes and seconds and must be 6 characters

"date" is in year, month, day with leading zeros and must be 8 characters long,

The "date" and "time" formats are the same as those returned by baSystemTime

See also:

baSystemTime


baPrinterInfo

PrinterInfo

Description:

baPrinterInfo returns information about the installed printers.

Platforms:

Windows

Usage:

Result = baPrinterInfo( Info )

Arguments:

String.
Info is the type of information required. Can be:
"installed" | returns full list of installed printers, drivers and ports
"list" | list of the names of installed printers
"default" | the current default printer
"orientation" | the orientation of the default printer
"paper" | the current paper size of the default printer
"papers" | the list of paper sizes supported by the default printer
"papername" | the name of the current paper of the default printer
"papernames" | the list of paper names of the default printer
"paperlength" | the length of the paper in the default printer in 1/1000 mm
"paperwidth" | the width of the paper in the default printer in 1/1000 mm
"copies" | the number of copies to print

Returns:

Depends on Info type.
"installed", "list", "papers", "papernames" return a list;
"default", "orientation", "paper", "papername" return a string;
"paperlength", "paperwidth" and "copies" return an integer.

Examples:

Director:
printer = baPrinterInfo( "default" )

Authorware:
printerList := baPrinterInfo( "list" )

Notes:

The "installed" info type returns a list - one list element for each printer. Each element will consist of the printer name, then the driver, then the port, all separated by commas. eg.

["EPSON Stylus COLOR 400,EPS400,LPT1:", "Acrobat PDFWriter,PDFWRITR,DISK:"]

The "list" Info type returns a list with just the printer names. eg

["EPSON Stylus COLOR 400", "Acrobat PDFWriter"]

The "orientation" Info type will return "Landscape", "Portrait" or "Unknown".

The "paper" Info type returns the size of the selected paper. It will be one of the following values:

"Letter", "LetterSmall", "Tabloid", "Ledger", "Legal", "Statement", "Executive", "A3", "A4", "A4Small", "A5", "B4", "B5", "Folio", "Quarto", "10x14", "11x17", "Note", "Envelope9", "Envelope10", "Envelope11", "Envelope12", "Envelope14", "CSheet", "DSheet", "ESheet", "EnvelopeDL", "EnvelopeC5", "EnvelopeC3", "EnvelopeC4", "EnvelopeC6", "EnvelopeC65", "EnvelopeB4", "EnvelopeB5", "EnvelopeB6", "EnvelopeItaly", "EnvelopeMonarch", "EnvelopePersonal", "FanFoldUS", "FanFoldStdGerman", "FanFoldLegalGermany", "User", "Unknown".

The "papers" info type returns a list of the paper sizes supported by the default printer.

The "papername" type returns the name of the selected paper as shown by the printer driver.

The "papernames" type returns a list of the papers supported by the default printer, as listed by the printer driver.

The "paper" option uses paper sizes pre-defined by Windows. Printer drivers may define their own page sizes and names - if the selected paper is a printer-defined size, the function will return "Unknown".

The "papername" will return the name of the paper as displayed by the printer driver - this will be the name the user sees in printer setup dialog boxes.

See also:

baSetPrinter
baPrintDlg


baSetPrinter

SetPrinter

Description:

baSetPrinter changes settings for the default printer.

Platforms:

Windows

Usage:

Result = baSetPrinter( Info, Data )

Arguments:

String, any.
Info is the type of information to set.
Can be:
"default" | set the current default printer (string)
"orientation" | the orientation of the default printer (string)
"paper" | the selected paper size of the default printer (string)
"papername" | the name of the selected paper of the default printer (string)
"copies" | the number of copies to print (integer
Data is the data to set - the format depends on the info type. can be either a string or a number.

Returns:

Integer
Returns 1 if successful, otherwise 0.

Examples:

Director:
ok = baSetPrinter( "default", "Epson 400 Stylus Color" )
ok = baSetPrinter( "copies", 2 )

Authorware:
ok := baSetPrinter( "orientation", "landscape" )
ok := baSetPrinter( "copies", 2 )

Notes:

The "default" option only requires the name of the printer, not the port or driver.

The "paper" option uses the same names as the baPrinterInfo "paper".

The "papername" option uses the same names as the baPrinterInfo "papername".

See also:

baPrinterInto
baPrinterDlg


baPrintDlg

PrintDlg

Description:

baPrintDlg shows the system printer dialog.

Platforms:

Windows

Usage:

Result = baPrintDlg( Flags )

Arguments:

Integer.
Flags alters the behaviour of the dialog. No Flags are presently defined, always use 0.

Returns:

Integer.
Returns 1 if user selects Print, otherwise 0.

Examples:

Director:
ok = baPrinterDlg( 0 )

Authorware:
ok := baPrintDlg( 0 )

Notes:

This function does not do any printing - it just shows the dialog box.

The return will be 1 if the user clicks the 'Print' button, or 0 if the user cancels. If the user clicks Print, then the selections the user has made in the dialog will be set as the default printer settings. You can retrieve these settings by using baPrinterInfo. For example, baPrinterInfo( "copies" ) will return the number of copies the user selected.

if baPrintDlg( 0 ) = 1 then -- user selected to print
copies = baPrinterInfo( "copies" ) -- get number of copies entered
doMyPrint( copies ) -- pass to your printing routine
end if

See also:

baPrinterInto
baSetPrinter


baPageSetupDlg

PageSetupDlg

Description:

baPageSetupDlg shows the system page setup dialog.

Platforms:

Windows

Usage:

Result = baPageSetupDlg( Flags )

Arguments:

Integer.
Flags alters the behaviour of the dialog. See Notes for details.

Returns:

Integer.
Returns 1 if user selects OK, otherwise 0.

Examples:

Director:
ok = baPageSetupDlg( 1 )

Authorware:
ok := baPageSetupDlg( 1 )

Notes:

This function does not do any printing - it just shows the dialog box.

The return will be 1 if the user clicks the 'OK' button, or 0 if the user cancels. If the user clicks OK, then the selections the user has made in the dialog will be set as the default printer settings. You can retrieve these settings by using baPrinterInto.

The following flags are defined.

1 | Disable the Printer button.
2 | Disable the Orientation settings
4 | Disable the Paper size selection
8 | Hides the Network button
16 | Disable the margin settings
32 | Disable the page drawing icon

These flags can be added together, eg baPageSetupDlg( 2 + 4 ) disables the orientation and paper size options.

See also:

baPrinterInto
baSetPrinter


baRefreshDesktop

RefreshDesktop

Description: | baRefreshDesktop refreshes the desktop icons.
Platforms: | Windows
Usage: | baRefreshDesktop( Wait )
Arguments: | Integer. If Wait is true, then the function will wait until the update is complete before returning.
Returns: | Void.
Examples: | Director: baRefreshDesktop( true ) Authorware: baRefreshDesktop( false )
Notes: | This function would typically be used after making registry changes that affect the icons displayed by files, such as changing a file association.
See also: | baRefreshFiles


baRefreshFiles

RefreshFiles

Description:

baRefreshFiles refreshes the desktop database.

Platforms:

Macintosh

Usage:

baRefreshFiles( )

Arguments:

None.

Returns:

Void.

Examples:

Director:
baRefreshFiles( )

Authorware:
baRefreshFiles( )

Notes:

This function would typically be used after writing or copying a large number of files.

See also:

baRefreshDesktop


baSetCursor

SetCursor

Description:

baSetCursor sets a system cursor.

Platforms:

Windows

Usage:

baSetCursor( Type. Filename )

Arguments:

String, string.
Type is the type of cursor to set. Can be:
"Normal"
"AppStarting"
"Cross"
"Hand"
"Help"
"iBeam"
"No"
"SizeAll"
"SizeNESW"
"SizeNS"
"SizeNWSE"
"SizeWE"
"Up"
"Wait"
Filename is the name of .ico file to use.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
ok = baSetcursor( "wait", the moviePath & "waitCursor.ico" )

Authorware:
ok := baSetcursor( "wait", FileLocation ^ "waitCursor.ico" )

Notes:

The cursor will remain in force until the computer is rebooted..

Use baLoadDefaultCursors to restore the user's default cursors.

See also:

baSetCursor


baLoadDefaultCursors

LoadDefaultCursors

Description: | baLoadDefaultCursors loads the user's default cursors.
Platforms: | Windows
Usage: | baLoadDefaultCursors ( )
Arguments: | None.
Returns: | Void.
Examples: | Director: baLoadDefaultCursors ( ) Authorware: baLoadDefaultCursors ( )
See also: | baSetCursor


baCreateGUID

CreateGUID

Description:

baCreateGUID creates a unique GUID.

Platforms:

Windows

Usage:

Result = baCreateGUID( )

Arguments:

None.

Returns:

String.
Returns a unique GUID.

Examples:

Director:
guid = baCreateGUID( )

Authorware:
guid := baCreateGUID( )

Notes:

A GUID is a Globally Unique Identifier. It is a unique 128-bit number produced by an application or operating system to identify a particular component, application, file, database entry or user. Each generated GUID will be unique every time it is run because it includes a time component. Running this function twice on the same computer will result in two different GUIDs being generated.


File functions

Specifying file names | how to specify file names
baFileAge | returns the age of a file
baFileExists | checks whether a file exists
baIsBundle | checks if a file is a bundle
baFolderExists | checks whether a folder exists
baCreateFolder | creates a new folder
baDeleteFolder | deletes an empty folder
baRenameFile | renames a file or folder
baDeleteFile | deletes a file
baDeleteXFiles | deletes files with wildcard matching
baXDelete | deletes files with wildcard matching, including sub-directories
baFileDate | returns the date of a file
baFileDateEx | returns the date of a file/folder
baSetFileDate | sets the date of a file
baFileSize | returns the size of a file
baFileSizeEx | returns the size of a folder
baFileAttributes | returns the attributes of a file
baSetFileAttributes | sets the attributes of a file
baFilePermissions | returns the Unix file permissions
baSetFilePermissions | set the Unix file permissions
baFileType | returns the four character type code of a file
baFileCreator | returns the four character creator code of a file
baSetFileInfo | sets the type or creator of a file
baRecycleFile | places a file in the recycle bin.
baCopyFile | copies a file
baCopyXFiles | copies multiple files with wildcard matching
baXCopy | copies multiple files with wildcard matching, including sub-directories
baCopyFileProgress | copies file while displaying progress bar
baCopyXFilesProgress | copies multiple files while displaying progress bar
baXCopyProgress | copies multiple files, including sub-folders, while displaying progress bar
baFileVersion | returns the version of a file
baFileList | returns a list of files in a folder
baFolderList | returns a list of folders in a folder
baGetFilename | displays a file selection dialog
baGetFilenameEx | displays a file selection dialog
baGetFolder | displays a folder selection dialog
baGetFiles | displays a file selection dialog
baGetDisk | displays a disk selection dialog
baFolderSize | returns the size of a folder
baMoveOnReboot | moves a file on system reboot
baFindFirstFile | searches for the first file matching a specification
baFindNextFile | searches for the next file matching a specification
baFindClose | finishes a search started with baFindFirstFile
baEncryptFile | encrypts/decrypts a file
baFindDrive | searches all drives for a specified file
baShell | executes a file
baOpenFile | opens a file using it's associated program
baOpenURL | opens a URL using the default browser
baPrintFile | prints a file using it's associated program
baShortFileName | returns the DOS version of a Win95 long file name
baLongFileName | returns the long version of a short file name
baTempFileName | returns a temporary file name guaranteed not to exist
baHfsName | returns the Hfs name of a file
baUnixName | returns the Unix name of a file
baReturnUnixNames | sets whether to return file names in Unix or Hfs format
baMakeShortcut | creates a shortcut
baMakeShortcutEx | creates a shortcut
baResolveShortcut | returns the file a shortcut points to
baBundleApp | returns the application file inside a bundle


Specifying file names

You should always pass in the full path name to the file you want to work with. For example, use

baOpenFile( "c:\data\myfile.pdf", "normal" ) or

baOpenFile( "Mac HD:Data:myfile.pdf", "normal" )

rather than

baOpenFile( "myFile.pdf", "normal" )

You should do this even when the file you are working with is in the same folder as your projector or application. If you want to work with a file that is relative to your projector or application, then you can use Lingo's the applicationPath or the moviePath variables; or Authorware's FileLocation variable. These variables return the path to the projector/application or the current .dir file. To open a file in the same folder as your projector, use:

baOpenFile( the applicationPath & "myFile.pdf", "normal" ) -- Director

baOpenFile( FileLocation ^ "myFile.pdf", "normal" ) -- Authorware

To open a file in a folder, add it to the path.

baOpenFile( the applicationPath & "data\\myFile.pdf", "normal" ) -- Director

baOpenFile( FileLocation ^ "data\myFile.pdf", :"normal" ) -- Authorware

In Director, you can also use Lingo's @ operator. This is the same as the moviePath, but can be used to specify cross-platform path names. Where a : / or \ character is included in your path name, it will be translated to the appropriate path separator.

baOpenFile( "@:Data:myFile.pdf", "normal" )

baOpenFile( "@/Data/myFile.pdf", "normal" )

baOpenFile( "@\Data\myFile.pdf", "normal" )

will all open the myfile.pdf in the Data subfolder on both platforms.

You must include a folder separator after the @.

On Macintosh, you can specify files using either Unix ( '/Volumes/Mac HD/data/myfile.pdf' ) or HFS ( 'Mac HD:Data:myfile.pdf' ) names. You can use baReturnUnixNames to specify whether Buddy functions return Unix or HFS names.


baFileAge

FileAge

Description:

baFileAge returns the date of a file in seconds.

Platforms:

Windows and Macintosh

Usage:

Result = baFileAge( FileName )

Arguments:

String.
FileName is the file to get the age of.

Returns:

Integer.
Returns the age of the file in seconds.

Examples:

Director:
Age = baFileAge( "c:\data\student.dat" )

Authorware:
Age := baFileAge( "c:\\data\\student.dat" )

Notes:

The number returned is the number of seconds since an arbitrary date. The number means little by itself, but can be used to compare the dates of two files. The file with higher number is the newer file. For example:

if baFileAge( "c:\\data\\student.dat"" ) > baFileAge( "a:\\student.dat" ) then
-- file on "C" drive is newer than the one on "A" drive.

See also:

baFileDate
baFileDateEx
baFileVersion


baFileExists

FileExists

Description:

baFileExists reports whether or not a specific file exists.

Platforms:

Windows and Macintosh

Usage:

Result = baFileExists( FileName )

Arguments:

String.
FileName is the name of the file. It should include the full path name.

Returns:

Integer.
Returns 1 if the file exists, otherwise 0.

Examples:

Director:
File = baFileExists( the pathName & "test.dat" )

Authorware:
File := baFileExists( FileLocation ^ "test.dat" )

See also:

baRenameFile
baFolderExists


baIsBundle

IsBundle

Description:

baIsBundle checks if a file is a bundle.

Platforms:

Macintosh

Usage:

Result = baIsBundle( FileName )

Arguments:

String.
FileName is the file to check.

Returns:

Integer.
Returns 1 if the file is a bundle, else 0.

Examples:

Director:
bundle = baIsBundle( "OSX:Applications:Internet Explorer.app" )

Authorware:
bundle := baIsBundle( "OSX:Applications:Internet Explorer.app" )

See also:

baBundleApp


baFolderExists

FolderExists

Description:

baFolderExists checks whether or not a folder exists.

Platforms:

Windows and Macintosh

Usage:

Result = baFolderExists( FolderName )

Arguments:

String.
FolderName is the folder to check for.

Returns:

Integer.
Returns 1 if the folder exists, else 0.

Examples:

Director:
OK = baFolderExists( "c:\data" )

Authorware:
OK := baFolderExists( "c:\\data" )

See also:

baCreateFolder


baCreateFolder

CreateFolder

Description:

baCreateFolder creates a new folder.

Platforms:

Windows and Macintosh

Usage:

Result = baCreateFolder( FolderName )

Arguments:

String.
FolderName is the folder to create.

Returns:

Integer.
Returns 1 if the folder was successfully created or already exists, else 0.

Examples:

Director:
OK = baCreateFolder( "c:\data\courses" )

Authorware:
OK := baCreateFolder( "c:\\data\\courses" )

Notes:

This function will create any intermediate folders that are needed. For example, baCreateFolder( "c:\data\courses\biology" ) will create "c:\data", then "c:\data\courses", then " c:\data\courses\biology".

See also:

baFolderExists
baDeleteFolder


baDeleteFolder

DeleteFolder

Description:

baDeleteFolder deletes an empty folder.

Platforms:

Windows and Macintosh

Usage:

Result = baDeleteFolder( FolderName )

Arguments:

String.
FolderName is the folder to delete.

Returns:

Integer.
Returns 1 if the folder was successfully deleted or doesn't exist, else 0.

Examples:

Director:
OK = baDeleteFolder( "c:\data" )

Authorware:
OK := baDeleteFolder( "c:\\data" )

Notes:

This function will only delete a folder that doesn't contain any files or sub-directories.

See also:

baFolderExists
baCreateFolder


baRenameFile

RenameFile

Description:

baRenameFile renames a file or folder.

Platforms:

Windows and Macintosh

Usage:

Result = baRenameFile( FileName , NewName )

Arguments:

String.
FileName is the file/folder to rename.
NewName is the new name for the file/folder.

Returns:

Integer.
Returns 1 if the file was successfully renamed, else 0.

Examples:

Director:
OK = baRenameFile( "c:\data\student.dat" , "c:\data\student.bak" )

Authorware:
OK := baRenameFile( "c:\\data\\student.dat" , "c:\\data\\student.bak" )

Notes:

This function will fail if a file called NewName already exists. The full path name to both the FileName and the NewName should be given.

You can also move a file or folder to a different folder if the destination file is on the same drive as the source file. eg: baRenameFile( "c:\data\student.dat", "c:\temp\student.dat" ) moves student.dat file from c:\data to c:\temp.

See also:

baFileExists
baDeleteFile


baDeleteFile

DeleteFile

Description:

baDeleteFile deletes a file.

Platforms:

Windows and Macintosh

Usage:

Result = baDeleteFile( FileName )

Arguments:

String.
FileName is the file to delete.

Returns:

Integer.
Returns 1 if the file was successfully deleted or doesn't exist, else 0.

Examples:

Director:
OK = baDeleteFile( "c:\data\student.bak" )

Authorware:
OK := baDeleteFile( "c:\\data\\student.bak" )

See also:

baDeleteXFiles
baRenameFile
baRecycleFile


baDeleteXFiles

DeleteXFiles

Description:

baDeleteXFiles deletes files with wildcard matching.

Platforms:

Windows

Usage:

Result = baDeleteXFiles( DirName, FileSpec )

Arguments:

String, string.
DirName is the folder to delete the files from.
FileSpec determines what files are deleted.

Returns:

Integer.
Returns 1 if all the matching files were successfully deleted or if DirName doesn't exist, else 0.

Examples:

Director:
OK = baDeleteXFiles( "c:\data" , "*.bak" )

Authorware:
OK := baDeleteXFiles( "c:\\data" , "*.bak" )

Notes:

On Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name. So *.* copies all files; *.bmp copies all files with a .bmp extension; T*.* copies all files starting with the letter T.

On Macintosh, the FileSpec is either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

See also:

baDeleteFile
baFileExists


baXDelete

XDelete

Description:

baXDelete deletes files with wildcard matching, including sub-directories.

Platforms:

Windows and Macintosh

Usage:

Result = baXDelete( DirName , FileSpec )

Arguments:

String, string.
DirName is the folder to delete the files from.
FileSpec determines what files are deleted.

Returns:

Integer.
Returns 1 if all the matching files were successfully deleted or if DirName doesn't exist, else 0.

Examples:

Director:
OK = baXDelete( "c:\data" , "*.bak" )

Authorware:
OK := baXDelete( "c:\\data , "*.bak" )

Notes:

Any empty directories that are left will also be deleted.

on Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name. So *.* deletes all files in the directory; *.bmp deletes all files with a .bmp extension; T*.* deletes all files starting with the letter T.

On Macintosh, the FileSpec argument can be either a file type, eg. "JPEG" or an extension .jpg.

See also:

baDeleteFile
baDeleteXFiles
baFileExists


baFileDate

FileDate

Description:

baFileDate returns the date of a file as a string.

Platforms:

Windows and Macintosh

Usage:

Result = baFileDate( FileName , DateFormat , TimeFormat )

Arguments:

String, string, string.
FileName is the file to get the date of.
DateFormat is the desired format of the date,
TimeFormat is the desired format of the time.

Returns:

String.
Returns the date of the file, or an empty string if the file doesn't exist.

Examples:

Director:
date = baFileDate( "c:\data\student.dat" , "dd-mm-yy" , "hh:nn:ss" )

Authorware:
date := baFileDate( "c:\\data\\student.dat" , "dd-mm-yy" , "hh:nn:ss" )

Notes:

The date format can consist of "d" for day, "m" for month, "y" for year.

The time format can consist of "h" for hours, "n" for minutes, "s" for seconds. (Note the "n" for minutes.)

A single letter ("d") returns the exact number eg "5".

A double letter ("dd") returns the number with a leading zero if required eg "05".

A triple letter ("ddd") returns the short name eg "Mon".

A quad letter ("dddd") returns the full name eg "Monday".

Any letters other than those listed above will returned as is - they can be used for separators eg "dd-mm-yy" returns "05-11-97"; "d mmmm, yyyy" returns "5 November, 1997"

If the format is an empty string, then the date or time will not be returned.

See also:

baFileDateEx
baSetFileDate
baFileAge
baFileVersion


baFileDateEx

FileDateEx

Description:

baFileDateEx returns the date of a file or folder as a string.

Platforms:

Windows

Usage:

Result = baFileDate( FileName , DateType , DateFormat , TimeFormat )

Arguments:

String, string, string, string.
FileName is the file to get the date of.
DateType is the data to return. Can be one of:
"created"
"modified"
"accessed"
DateFormat is the desired format of the date.
TimeFormat is the desired format of the time.

Returns:

String.
Returns the date of the file/folder, or an empty string if the file/folder doesn't exist.

Examples:

Director:
date = baFileDateEx( "c:\data\student.dat" , "created" , "dd-mm-yy" , "hh:nn:ss" )

Authorware:
date := baFileDateEx( "c:\\data\\student.dat" , "modified" ,"dd-mm-yy" , "hh:nn:ss" )

Notes:

The date format can consist of "d" for day, "m" for month, "y" for year.

The time format can consist of "h" for hours, "n" for minutes, "s" for seconds. (Note the "n" for minutes.)

A single letter ("d") returns the exact number eg "5".

A double letter ("dd") returns the number with a leading zero if required eg "05".

A triple letter ("ddd") returns the short name eg "Mon".

A quad letter ("dddd") returns the full name eg "Monday".

Any letters other than those listed above will returned as is - they can be used for separators eg "dd-mm-yy" returns "05-11-97"; "d mmmm, yyyy" returns "5 November, 1997"

If the format is an empty string, then the date or time will not be returned.

See also:

baFileDate
baSetFileDate
baFileAge
baFileVersion


baSetFileDate

SetFileDate

Description:

baSetFileDate sets the date of a file.

Platforms:

Windows

Usage:

Result = baSetFileDate( FileName, Year, Month, Day, Hour, Minute, Second )

Arguments:

String, integer, integer, integer, integer, integer, integer.
FileName is the file to set the date of.
Year is the year.
Month is the month, January = 1.
Day is the day of the month.
Hour is the hour in 24 hour format (0-23).
Minute is the minute.
Second is the number of seconds.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baSetFileDate( "c:\data\student.dat", 2001, 12, 5, 15, 23, 12 )

Authorware:
OK := baSetFileDate( "c:\\data\\student.dat", 2001, 12, 5, 15, 23, 12 )

Notes:

If an invalid date is entered then the function will fail.

See also:

baFileDate
baFileAge
baFileVersion


baFileSize

FileSize

Description:

baFileSize returns the size of a file.

Platforms:

Windows and Macintosh

Usage:

Result = baFileSize( FileName )

Arguments:

String.
FileName is the file to get the size of.

Returns:

Integer.
Returns the size of the file in bytes, or -1 if the file doesn't exist.

Examples:

Director:
size = baFileSize( "c:\data\student.dat" )

Authorware:
size := baFileSize( "c:\\data\\student.dat" )

Notes:

This function will only return correctly on files smaller than Director's MAXINTEGER - 2147483647 bytes. Use baFileSizeEx to get file sizes larger than this.

See also:

baFileSizeEx


baFileSizeEx

FileSizeEx

Description:

baFileSizeEx returns the size of a file.

Platforms:

Windows and Macintosh

Usage:

Result = baFileSizeEx( FileName )

Arguments:

String.
FileName is the file to get the size of.

Returns:

Float.
Returns the size of the file in bytes, or -1 if the file doesn't exist.

Examples:

Director:
size = baFileSize( "c:\data\student.dat" )

Authorware:
size := baFileSize( "c:\\data\\student.dat" )

Notes:

This function returns a float and can handle files larger than Director's MAXINTEGER - 2147483647 bytes.

See also:

baFileSize


baFileAttributes

FileAttributes

Description:

baFileAttributes returns the attributes of a file.

Platforms:

Windows and Macintosh

Usage:

Result = baFileAttributes( FileName )

Arguments:

String.
FileName is the file to get the attributes of.

Returns:

String.
Returns a string containing all the attributes that are set. Can be any combination of:
Windows
"r" | read-only
"a" | archive
"h" | hidden
"s" | system
Macintosh
"r" | locked
"h" | invisible
"s" | shared
"c" | custom icon
"t" | stationery pad
"l" | alias
"n" | name locked
"b" | has bundle
"i" | has been inited
Returns an empty string if FileName doesn't exist.

Examples:

Director:
att = baFileAttributes( "c:\data\student.dat" )

Authorware:
att := baFileAttributes( "c:\\data\\student.dat" )

Notes:

You can use the Director contains or Authorware Find function to test whether a particular attribute is set. eg.

if Find( "r" , baFileAttributes( FileName ) ) <> 0 then -- file is read only

if baFileAttributes( FileName ) contains "r" then -- file is read only

See also:

baSetFileAttributes


baSetFileAttributes

SetFileAttributes

Description:

baSetFileAttributes sets the attributes of a file.

Platforms:

Windows and Macintosh

Usage:

Result = baSetFileAttributes( FileName , Attributes )

Arguments:

String, string.
FileName is the file to get the attributes of.
Attributes are the attributes to set. Can be on of:
Windows
"r" | read-only
"a" | archive
"h" | hidden
"s" | system
Macintosh
"r" | locked
"h" | invisible
"s" | shared
"c" | custom icon
"t" | stationery pad
"l" | alias
"n" | name locked
"b" | has bundle
"i" | has been inited

An empty string removes all attributes.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baSetFileAttributes( "c:\data\student.dat" , "rh" ) -- make file hidden and read-only

Authorware:
OK := baSetFileAttributes( "c:\\data\\student.dat" , "" ) -- clear all attributes

See also:

baFileAttributes


baFilePermissions

FilePermissions

Description:

baFilePermissions returns the UNIX permissions of a file or folder.

Platforms:

Macintosh

Usage:

Result = baFilePermissions( FileName, User )

Arguments:

String, string.
FileName is the file to get the attribute of.
User is the user type to get. Can be one of:
"u" | the present user
"g" | the current group
"o" | all other users

Returns:

String.
Returns a string containing all the file permissions that are set.
Can be a combination of:
"r" | read access allowed
"w" | write access allowed
"x" | execute access allowed

Examples:

Director:
perm = baFilePermissions( "Mac HD:data:student.dat", "u" )

Authorware:
perm := baFilePermissions( "Mac HD:data:student.dat", "u" )

Notes:

You can use the Director contains or Authorware Find functions to test whether a
particular attribute is set. eg.

if Find( "r", baFilePermissions( File ) ) <> 0 then file has read access

if baFilePermissions( Filename ) contains "r" then file has read access
To get the permissions of a folder, you need to make sure that the folder name
ends with a folder separator ( : or / )


baSetFilePermissions

SetFilePermissions

Description:

baSetFilePermissions sets the UNIX permissions of a file.

Platforms:

Macintosh

Usage:

Result = baSetFilePermissions( FileName, User, Permissions )

Arguments:

String, string, string.
FileName is the file to set the attribute of.
User is the user type to set. Can be one of:
"u" | the present user
"g" | the current group
"o" | all other users
Permissions are the permissions to set. Can be a combination of:
"r" | read access allowed
"w" | write access allowed
"x" | execute access allowed

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
ok = baSetFilePermissions( "Mac HD:data:student.dat", "u", "rw" )

Authorware:
ok := baSetFilePermissions( "Mac HD:data:student.dat", "o", "x" )

Notes:

The file permissions will be set to what you pass in "rw" will set the read and write
access and remove the execute access, regardless of the present settings.

If you pass in a plus sign as the first character, then the permissions will be added
to the present permissions – "+r" will add read access without changing the present write and execute settings.

If you pass in a minus sign as the first character, then the permissions will be removed from the present permissions – "wx"
will remove the write and execute access without changing the present read setting.

To set the permissions of a folder, you need to make sure that the folder name ends with a folder separator ( : or / ).

See also:

baFilePermissions


baFileType

FileType

Description:

baFileType returns the type code of a file.

Platforms:

Macintosh

Usage:

Result = baFileType( FileName )

Arguments:

String.
FileName is the file to get the code of.

Returns:

String.
Returns the four character type code of the file.

Examples:

Director:
set type = baFileType( "HD:Data:data file" )

Authorware:
OK := baFileType( "HD:Data:data file" )

See also:

baFileCreator
baSetFileInfo


baFileCreator

FileCreator

Description:

baFileCreator returns the creator code of a file.

Platforms:

Macintosh

Usage:

Result = baFileCreator( FileName )

Arguments:

String.
FileName is the file to get the code of.

Returns:

String.
Returns the four character creator code of the file.

Examples:

Director:
set type = baFileType( "HD:Data:data file" )

Authorware:
OK := baFileType( "HD:Data:data file" )

See also:

baFileType
baSetFileInfo


baSetFileInfo

SetFileInfo

Description:

baSetFileInfo sets the type and creator of a file.

Platforms:

Macintosh

Usage:

Result = baSetFileInfo( FileName, Type, Creator )

Arguments:

String.
FileName is the file to set the information of.
Type is the four character Type code.
Creator is the four character Creator code.

Returns:

Integer.
Returns 1 if successful, otherwise 0.

Examples:

Director:
ok = baSetFileInfo( "HD:Data:myFile.pdf", " PDF", "CARO" )

Authorware:
OK := baFileType( "HD:Data:myFile.pdf", " PDF", "CARO" )

Notes:

You can pass in an empty string for either the Type or Creator and the files present Type or Creator will not be changed.

See also:

baFileCreator
baFileType


baRecycleFile

RecycleFile

Description:

baRecycleFile places a file in the recycle bin.

Platforms:

Windows

Usage:

Result = baRecycleFile( FileName )

Arguments:

String.
FileName is the file to recycle.

Returns:

Integer.
Returns 1 if the file was successfully recycled or doesn't exist, else 0.

Examples:

Director:
OK = baRecycleFile( "c:\data\student.bak" )

Authorware:
OK := baRecycleFile( "c:\\data\\student.bak" )

See also:

baDeleteFile


baCopyFile

CopyFile

Description:

baCopyFile copies a file.

Platforms:

Windows and Macintosh

Usage:

Result = baCopyFile( SourceFile , DestFile , Overwrite )

Arguments:

String, string, string.
SourceFile is the file to copy.
DestFile is the name to copy it to.
Overwrite determines how the copy is done. Can be:
"Always" | always copies the file
"IfNewer" | copies the file if SourceFile is newer than DestFile
"IfNotExist" | copies only if DestFile does not already exist

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:
1 | Invalid Source file name
2 | Invalid Dest file name
3 | Error reading the Source file
4 | Error writing the Dest file
5 | Couldn't create directory for Dest file
6 | Dest file exists
7 | Dest file is newer that Source file

Examples:

Director:
OK = baCopyFile( "c:\data\student.dat" , "c:\data\backup\student.dat" , "IfNewer" )

Authorware:
OK := baCopyFile( "c:\\data\\student.dat" , "c:\\data\\backup\\student.dat" , "IfNewer" )

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: on Windows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison. On Macintosh, only the file dates are used for comparison.

The DestFile must contain the full name of the file, not just the name of the folder it is being copied to.

The new file will be set to archive and not read-only.

See also:

baCopyXFiles
baXCopy
baCopyFileProgress
baCopyXFilesProgress
baXCopyProgress


baCopyXFiles

CopyXFiles

Description:

baCopyXFiles copies multiple files from one folder to another folder, with wildcard matching.

Platforms:

Windows and Macintosh

Usage:

Result = baCopyXFiles( SourceDir , DestDir , FileSpec , Overwrite )

Arguments:

String, string, string, string.
SourceDir is the folder to copy from.
DestDir is the folder to copy to.
FileSpec determines what files are copied.
Overwrite determines how the copy is done. Can be:
"Always" | always copies the file
"IfNewer" | copies the file if SourceFile is newer than DestFile
"IfNotExist" | copies only if DestFile does not already exist

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:
1 | Invalid Source file name
2 | Invalid Dest file name
3 | Error reading the Source file
4 | Error writing the Dest file
5 | Couldn't create directory for Dest file
6 | Dest file exists
7 | Dest file is newer that Source file
8 | No files matched the specified type

Examples:

Director:
OK = baCopyXFiles( "c:\data" , "d:\backup" , "*.dat " , "IfNewer" )

Authorware:
OK := baCopyXFiles( "c:\\data" , "d:\\backup" , "*.dat" , "IfNewer" )

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

The return value will not be 0 if any file is not copied. For example, if you specify
baCopyXFiles( "c:\data" , "d:\backup" , "*.*" , "IfNewer" )
and any of the files in c:\data are newer than the ones in d:\backup, the return result will be 7 (Dest file is newer than Source). A result of 0 will be returned only if none of the files in c:\data is newer than d:\backup.

On Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name. So *.* copies all files; *.bmp copies all files with a .bmp extension; T*.* copies all files starting with the letter T.

On Macintosh, the FileSpec is either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: on Windows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison. On Macintosh, only the file dates are used for comparison.

See also:

baCopyFile
baXCopy
baCopyFileProgress
baCopyXFilesProgress
baXCopyProgress


baXCopy

XCopy

Description:

baXCopy copies multiple files from one folder to another folder, with wildcard matching, including sub-directories.

Platforms:

Windows and Macintosh

Usage:

Result = baXCopy( SourceDir , DestDir , FileSpec , Overwrite, MakeDir )

Arguments:

String, string, string, string, integer.
SourceDir is the folder to copy from.
DestDir is the folder to copy to.
FileSpec determines what files are copied.
Overwrite determines how the copy is done. Can be:
"Always" | always copies the file
"IfNewer" | copies the file if SourceFile is newer than DestFile
"IfNotExist" | copies only if DestFile does not already exist

If MakeDir is true, any empty directories will be created.

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:
1 | Invalid Source file name
2 | Invalid Dest file name
3 | Error reading the Source file
4 | Error writing the Dest file
5 | Couldn't create directory for Dest file
6 | Dest file exists
7 | Dest file is newer that Source file
8 | No files matched the specified type

Examples:

Director:
OK = baXCopy( "c:\data" , "d:\backup" , "*.dat " , "IfNewer" , true )

Authorware:
OK := baXCopy( "c:\\data" , "d:\\backup" , "*.*" , "Always" , false )

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

The return value will not be 0 if any file is not copied. For example, if you specify

baXCopy( "c:\data" , "d:\backup" , "*.*" , "IfNewer" )

and any of the files in c:\data are newer than the ones in d:\backup, the return result will be 7 (Dest file is newer than Source). A result of 0 will be returned only if none of the files in c:\data is newer than d:\backup.

On Windows, the FileSpec argument follows normal DOS wildcard rules. Use "*.*" to copy all files.

On Macintosh, the FileSpec can be either a four character type code, eg “TEXT” or an extension, eg ".txt". You must include the . in the extension. Only one type or extension can be specified. Use an empty string or “*.*” to specify all files.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: on Windows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison. On Macintosh, only the file dates are used for comparison.

The new files will be set to archive and not read-only.

See also:

baCopyFile
baCopyXFiles
baCopyFileProgress
baCopyXFilesProgress
baXCopyProgress


baCopyFileProgress

CopyFileProgress

Description:

baCopyFileProgress copies a file, while displaying a progress dialog.

Platforms:

Windows and Macintosh

Usage:

Result = baCopyFileProgress( SourceFile , DestFile , Overwrite, Title, ButtonText, Flags )

Arguments:

String, string, string, string, string, integer.
SourceFile is the file to copy.
DestFile is the name to copy it to.
Overwrite determines how the copy is done. Can be:
"Always" | always copies the file
"IfNewer" | copies the file if SourceFile is newer than DestFile
"IfNotExist" | copies only if DestFile does not already exist
Title is the title of the dialog box.
ButtonText is the text to use in the Cancel button.
Flags changes the behaviour of the dialog, see notes for details.

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:
1 | Invalid Source file name
2 | Invalid Dest file name
3 | Error reading the Source file
4 | Error writing the Dest file
5 | Couldn't create directory for Dest file
6 | Dest file exists
7 | Dest file is newer that Source file
8 | No files matched the specified type
9 | User cancelled the copy

Examples:

Director:
OK = baCopyFileProgress( "c:\data\student.dat" , "c:\data\backup\student.dat" , "IfNewer", "Backing up files... ", "Cancel", 0 )

Authorware:
OK := baCopyFileProgress( "c:\\data\\student.dat" , "c:\\data\\backup\\student.dat" , "IfNewer" , "Backing up files... ", "Cancel", 0 )

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

The return value will not be 0 if any file is not copied. For example, if you specify
baCopyXFilesProgress( "c:\data" , "d:\backup" , "*.*" , "IfNewer", ....... )
and any of the files in c:\data are newer than the ones in d:\backup, the return result will be 7 (Dest file is newer than Source). A result of 0 will be returned only if none of the files in c:\data is newer than d:\backup.

On Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name. So *.* copies all files; *.bmp copies all files with a .bmp extension; T*.* copies all files starting with the letter T.

On Macintosh, the FileSpec is either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison.

Seven Flags are defined:
CP_NOCANCEL | 1 | does not show the Cancel button
CP_NOFILENAME | 2 | does not display the file names while copying
CP_STOPONERROR | 4 | stop copying if an error occurs
CP_NODIALOG | 8 | does not show the dialog box
CP_CALLBACK | 16 | nable the copy callback handler
CP_ANIMATE | 32 | shows system file copying animation
CP_SIZEUPDATE | 64 | updates the callback handler by size

You can add any of these flags together to customize the dialog box.

To implement the callback handler, use the CP_CALLBACK flag. Typically you would also use the CP_NODIALOG flag and implement your own dialog box. If you use this flag then you need to add a handler called 'baCopyProgressUpdate'. This handler needs to be a movie script.

This handler will have two arguments passed into it - the percentage copied so far and the current file being copied. The handler will be called whenever the percentage copied has increased by one, or a new file is being copied. If you specify the CP_SIZEUPDATE, then your handler will be called whenever approximately 64k of data has been copied, rather than by percentage.

To stop copying, you can return 1 in your handler; return 0 or no return to continue copying. An example handler is listed below - the update functions would be used to update your own progress dialog.

on baCopyProgressUpdate percentage, filename
updateProgressBar percentage
updateStatus fileName
if keyPressed( " " ) then -- if user presses space bar, stop copying
return 1
end if
end

The callback handler is only available on Director.

See also:

baCopyFile
baCopyXFiles
baXCopy
baCopyXFilesProgress
baXCopyProgress


baCopyXFilesProgress

CopyXFilesProgress

Description:

baCopyXFilesProgress copies multiple files, while displaying a progress dialog.

Platforms:

Windows and Macintosh

Usage:

Result = baCopyXFilesProgress( SourceDir , DestDir , FileSpec, Overwrite, Title, ButtonText, Flags )

Arguments:

String, string, string, string, string, string, integer.
SourceDir is the folder to copy from.
DestDir is the folder to copy to.
FileSpec determines what files are copied.
Overwrite determines how the copy is done. Can be:
"Always" | always copies the file
"IfNewer" | copies the file if SourceFile is newer than DestFile
"IfNotExist" | copies only if DestFile does not already exist
Title is the title of the dialog box.
ButtonText is the text to use in the Cancel button.
Flags changes the behaviour of the dialog, see Notes for details.

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:
1 | Invalid Source file name
2 | Invalid Dest file name
3 | Error reading the Source file
4 | Error writing the Dest file
5 | Couldn't create directory for Dest file
6 | Dest file exists
7 | Dest file is newer that Source file
8 | No files matched the specified type
9 | User cancelled the copy

Examples:

Director:
OK = baCopyXFilesProgress( "c:\data" , "d:\backup" , "*.dat", "IfNewer", "Backing up files... ", "Cancel", 0 )

Authorware:
OK := baCopyXFilesProgress( "c:\\data" , "d:\\backup" , "*.dat", "IfNewer" , "Backing up files... ", "Cancel", 0 )

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

The return value will not be 0 if any file is not copied. For example, if you specify
baCopyXFilesProgress( "c:\data" , "d:\backup" , "*.*" , "IfNewer", ....... )
and any of the files in c:\data are newer than the ones in d:\backup, the return result will be 7 (Dest file is newer than Source). A result of 0 will be returned only if none of the files in c:\data is newer than d:\backup.

On Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name. So *.* copies all files; *.bmp copies all files with a .bmp extension; T*.* copies all files starting with the letter T.

On Macintosh, the FileSpec is either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison.

Seven Flags are defined:
CP_NOCANCEL | 1 | does not show the Cancel button
CP_NOFILENAME | 2 | does not display the file names while copying
CP_STOPONERROR | 4 | stop copying if an error occurs
CP_NODIALOG | 8 | does not show the dialog box
CP_CALLBACK | 16 | nable the copy callback handler
CP_ANIMATE | 32 | shows system file copying animation
CP_SIZEUPDATE | 64 | updates the callback handler by size

You can add any of these flags together to customize the dialog box.

To implement the callback handler, use the CP_CALLBACK flag. Typically you would also use the CP_NODIALOG flag and implement your own dialog box. If you use this flag then you need to add a handler called 'baCopyProgressUpdate'. This handler needs to be a movie script.

This handler will have two arguments passed into it - the percentage copied so far and the current file being copied. The handler will be called whenever the percentage copied has increased by one, or a new file is being copied. If you specify the CP_SIZEUPDATE, then your handler will be called whenever approximately 64k of data has been copied, rather than by percentage.

To stop copying, you can return 1 in your handler; return 0 or no return to continue copying. An example handler is listed below - the update functions would be used to update your own progress dialog.

on baCopyProgressUpdate percentage, filename
updateProgressBar percentage
updateStatus fileName
if keyPressed( " " ) then -- if user presses space bar, stop copying
return 1
end if
end

The callback handler is only available on Director.

See also:

baCopyFile
baCopyXFiles
baXCopy
baCopyFileProgress
baXCopyProgress


baXCopyProgress

XCopyProgress

Description:

baXCopyProgress copies multiple files, including sub-folders, while displaying a progress dialog.

Platforms:

Windows and Macintosh

Usage:

Result = baXCopyProgress( SourceDir, DestDir, FileSpec, Overwrite, MakeDir, Title, ButtonText, Flags )

Arguments:

String, string, string, string, integer, string, string, integer.
SourceDir is the folder to copy from.
DestDir is the folder to copy to.
FileSpec determines what files are copied.
Overwrite determines how the copy is done. Can be:
"Always" | always copies the file
"IfNewer" | copies the file if SourceFile is newer than DestFile
"IfNotExist" | copies only if DestFile does not already exist
If MakeDir is true, any empty directories will be created.
Title is the title of the dialog box.
ButtonText is the text to use in the Cancel button.
Flags changes the behaviour of the dialog, see Notes for details.

Returns:

Integer.
Returns 0 if the file was copied successfully, otherwise one of these:
1 | Invalid Source file name
2 | Invalid Dest file name
3 | Error reading the Source file
4 | Error writing the Dest file
5 | Couldn't create directory for Dest file
6 | Dest file exists
7 | Dest file is newer that Source file
8 | No files matched the specified type
9 | User cancelled the copy

Examples:

Director:
OK = baXCopyProgress( "c:\data" , "d:\backup" , "*.dat", "IfNewer", true, "Backing up files... ", "Cancel", 0 )

Authorware:
OK := baXCopyProgress( "c:\\data" , "d:\\backup" , "*.dat", "IfNewer" , true, "Backing up files... ", "Cancel", 0 )

Notes:

By default, this function will not overwrite an existing file if that file is marked as read-only. However, by adding "+" to the "Always" and "IfNewer" options (eg "Always+" or "IfNewer+"), the files will be overwritten if they are read-only.

The return value will not be 0 if any file is not copied. For example, if you specify
baCopyXFilesProgress( "c:\data" , "d:\backup" , "*.*" , "IfNewer", ....... )
and any of the files in c:\data are newer than the ones in d:\backup, the return result will be 7 (Dest file is newer than Source). A result of 0 will be returned only if none of the files in c:\data is newer than d:\backup.

On Windows, the FileSpec argument follows normal DOS wildcard rules. A * means match any character in the file name. So *.* copies all files; *.bmp copies all files with a .bmp extension; T*.* copies all files starting with the letter T.

On Macintosh, the FileSpec is either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

A return value of 6 (Dest file exists) can only be returned when Overwrite is "IfNotExist".

A return value of 7 (Dest file is newer than Source file) can only be returned when Overwrite is "IfNewer". The other return values can be returned for all Overwrite options.

The "IfNewer" option operates as follows: if both files have internal version numbers, then these numbers are used for comparison, otherwise the dates of the two files are used for comparison.

Seven Flags are defined:
CP_NOCANCEL | 1 | does not show the Cancel button
CP_NOFILENAME | 2 | does not display the file names while copying
CP_STOPONERROR | 4 | stop copying if an error occurs
CP_NODIALOG | 8 | does not show the dialog box
CP_CALLBACK | 16 | nable the copy callback handler
CP_ANIMATE | 32 | shows system file copying animation
CP_SIZEUPDATE | 64 | updates the callback handler by size

You can add any of these flags together to customize the dialog box.

To implement the callback handler, use the CP_CALLBACK flag. Typically you would also use the CP_NODIALOG flag and implement your own dialog box. If you use this flag then you need to add a handler called 'baCopyProgressUpdate'. This handler needs to be a movie script.

This handler will have two arguments passed into it - the percentage copied so far and the current file being copied. The handler will be called whenever the percentage copied has increased by one, or a new file is being copied. If you specify the CP_SIZEUPDATE, then your handler will be called whenever approximately 64k of data has been copied, rather than by percentage.

To stop copying, you can return 1 in your handler; return 0 or no return to continue copying. An example handler is listed below - the update functions would be used to update your own progress dialog.

on baCopyProgressUpdate percentage, filename
updateProgressBar percentage
updateStatus fileName
if keyPressed( " " ) then -- if user presses space bar, stop copying
return 1
end if
end

The callback handler is only available on Director.

See also:

baCopyFile
baCopyXFiles
baXCopy
baCopyFileProgress
baCopyXFilesProgress


baFileVersion

FileVersion

Description:

baFileVersion returns a string containing the version of a file.

Platforms:

Windows and Macintosh

Usage:

Result = baFileVersion( FileName )

Arguments:

String.
FileName is the name of the file to obtain version information of.

Returns:

String.
Returns the version of the file. If the file doesn't contain version information or doesn't exist, then an empty string is returned.

Examples:

Director:
AcroVer = baFileVersion( "c:\acroread\acroread.exe" )

Authorware:
AcroVer := baFileVersion( "c:\\acroread\\acroread.exe" )

See also:

baFileDate
baFileAge


baFileList

FileList

Description:

baFileList returns a list of files in a folder.

Platforms:

Windows and Macintosh

Usage:

Result = baFileList( Folder, FileSpec )

Arguments:

String, string.
Folder is the name of the folder to list.
FileSpec is the pattern of files to match.

Returns:

List.
Returns the list of matching files. If Folder doesn't exist, then an empty list/string is returned.

Examples:

Director:
Files = baFileList( "c:\windows", "*.*" )

Authorware:
Files := baFileList( "c:\\temp", "*.bmp" )

Notes:

On Windows, the FileSpec is a DOS wildcard, eg "*.bmp". Only one type can be specified. Use an empty string or "*.*" to match all files.

On Macintosh, the FileSpec can be either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.

See also:

baFolderList


baFolderList

FolderList

Description:

baFolderList returns a list of folders in a folder.

Platforms:

Windows and Macintosh

Usage:

Result = baFolderList( Folder )

Arguments:

String.
Folder is the name of the folder to list.

Returns:

List.
Returns the list of folders. If Folder doesn't exist, then an empty list is returned.

Examples:

Director:
Folders = baFolderList( "c:\windows" )

Authorware:
Files := baFolderList( "c:\\temp" )

See also:

baFileList


baGetFolder

GetFolder

Description:

baGetFolder displays a directory dialog box and returns the folder selected.

Platforms:

Windows and Macintosh

Usage:

Result = baGetFolder( StartDir, Instruction, Flags, Caption, X, Y )

Arguments:

String, string, integer, string, integer, integer.
StartDir is the initial directory. Use "" for the current directory.
Instruction is the instruction to display to the user.
Flags modifies the behaviour of the dialog.
Caption is the caption of the dialog.
X is the horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

String.
Returns the folder selected, or "" if the user cancelled.

Examples:

Director:
folder = baGetFolder( "c:\temp", "Please select a folder to install into:", 1, "Select a folder", -1, 0 )

Authorware:
folder := baGetFolder( "c:\\temp", "Select installation directory", 0, "", 200, 200 )

Notes:

The flags argument allows you to change the way the dialog box looks and behaves. The following flags are defined.

1 | On Windows, makes the dialog box a 32 bit Explorer style.
2 | Displays a ‘New’ button to allow the user to create a new folder. On Macintosh, the New button will always be shown.

On Windows, the Caption argument is only used if a 32 bit dialog box is used. If it is an empty string, then the default "Browse for Folder" will be displayed.

On Macintosh, if Caption is not supplied, the default "Choose a Folder" will be used.

The X and Y values are the number of pixels from the top left corner of the screen. Set X to -1 to position the dialog in the center of the calling Director/Authorware window. Set X to -2 to position the dialog in the center of the screen.

See also:

baGetFilename
baGetDisk
baGetFiles


baGetFilename

GetFilename

Description:

baGetFilename displays a file dialog box and returns the filename selected.

Platforms:

Windows and Macintosh

Usage:

Result = baGetFilename( Operation, StartDir, Filename, Filter, Flags, Instruction, NoFolders, X, Y )

Arguments:

String, string, string, string, integer, string, integer, integer, integer.
Operation is the type of dialog to show. Can be "open" or "save".
StartDir is the initial directory. Use "" for the current directory.
Filename is the initial file name to display.
Filter is the type of files to display. Use "" to show all files.
Flags modifies the behaviour of the dialog.
Instruction is the instruction to display to the user.
If NoFolders is true, the folder selection controls will not be shown.
X is horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

String.
Returns the file name selected, or "" if the user cancelled.

Examples:

Director:
filename = baGetFilename( "save", "c:\temp", "newfile.txt", "Text files|*.txt", 0, "Save new file", false, 100, 100 )

Authorware:
file := baGetFilename( "open", "c:\\temp", "", "", 0, "Select data file to open", true, -1, 0 )

Notes:

On Windows, the filter argument consists of a series of strings separated by "|" characters. The strings are divided into pairs, the first half of a pair is the description that appears in the drop down box, the second half is the wildcard for the files. Separate multiple wildcards with semi-colons.
"Text files|*.txt" -- shows only text files
"Text files|*.txt|All files|*.*" -- allows the user to display either text files or all files
"Images|*.bmp;*.tif;*.jpg" -- shows different image files

On Macintosh, the filter can be a four character code of the file type eg “TEXT”. Up to 4 types can be specified, eg “TEXT|PICT”. Alternatively, you can specify an extension to filter on. You can specify up to 10 extensions, separated by commas, eg".bmp,.jpg,.jpeg"

Setting the NoFolders option to true will mean that the user will not be able to change the initial directory, and folders will not be shown. This flag is only available on Windows, and if you do not include the OFN_EXPLORER flag.

The X and Y values are the number of pixels from the top left corner of the screen. Set X to -1 to position the dialog in the center of the calling Director/Authorware window. Set X to -2 to position the dialog in the center of the screen. On Macintosh, –3 will position the dialog where the user left it.

The flags argument allows you to change the way the dialog box looks and behaves. On Windows, it can be the combination of any of these values:

1 | OFN_READONLY Causes the Read Only check box to be checked initially when the dialog box is created.
2 | OFN_OVERWRITEPROMPT Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
4 | OFN_HIDEREADONLY Hides the Read Only check box.
8 | OFN_NOCHANGEDIR Restores the current directory to its original value if the user changed the directory while selecting a file.
32 | OFN_ADDEXTENSION If the user enters a name without an extension, the first extension listed in the Filter argument will be added to the end of the returned filename.
256 | OFN_RETURNASLIST If OFN_ALLOWMULTISELECT is specified returns the file names as a list.
512 | OFN_ALLOWMULTISELECT Specifies that the File Name list box allows multiple selections.
2048 | OFN_PATHMUSTEXIST Specifies that the user can type only valid paths and filenames. If this flag is used and the user types an invalid path and filename in the File Name entry field, the dialog box function displays a warning in a message box.
4096 | OFN_FILEMUSTEXIST Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box.
8192 | OFN_CREATEPROMPT Specifies that the dialog box function should ask whether the user wants to create a file that does not currently exist.
32768 | OFN_NOREADONLYRETURN Specifies that the returned file does not have the Read Only check box checked and is not in a write-protected directory.
131072 | OFN_NONETWORKBUTTON Hides and disables the Network button.
262144 | OFN_NOLONGNAMES Specifies that long filenames are not displayed in the File Name list box. This value is ignored if OFN_EXPLORER is set.
524288 | OFN_EXPLORER Creates an Open or Save As dialog box that uses user-interface features similar to the Windows Explorer.
1048576 | OFN_NODEREFERENCELINKS Directs the dialog box to return the path and filename of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut.
2097152 | OFN_LONGNAMES Causes the Open or Save As dialog box to display long filenames. If this flag is not specified, the dialog box displays filenames in 8.3 format. This value is ignored if OFN_EXPLORER is set.
4194304 | OFN_SHOWPLACESBAR Shows the Places bar. Only available on ME/2000/XP. Has no effect unless OFN_EXPLORER is also specified. Note that if this flag is specified then the Position arguments are ignored - Windows will place the dialog in the last place left by the user.

On Macintosh, they can be:

1 | OFN_HIDEBUNDLES Do not allow bundles to be selected.
2 | OFN_OPENBUNDLES Treat bundles as folders and allow the contents to be displayed and selected.
512 | OFN_ALLOWMULTISELECT Specifies that the File Name list box allows multiple selections. The files are always returned as a list.
1048576 | OFN_NODEREFERENCELINKS Directs the dialog box to return the path and filename of the selected shortcut file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut.

Using a flag of -1 gives a standard dilaog box with the most common options.

To use these values, add the appropriate values together eg

OFN_CREATEPROMPT + OFN_HIDEREADONLY + OFN_NONETWORKBUTTON

If OFN_ALLOWMULTISELECT is specified and OFN_RETURNASLIST is not specified, and the user selects more than one file, the return will be a series of strings, separated by returns. The first line will be the directory selected, the remaining lines will be the selected filenames. In Director, use "the line of" function to retrieve each line. In Authorware, use the "GetLine" function. Note that on Macintosh, it is possible to select files that are not in the same folder, so the return is always a list.

If OFN_RETURNASLIST is specified then the return will be a list with each filename as a separate entry. Each entry will be the full filename, including the path.

The OFN_EXPLORER flag can not be used with the NoFolders option. The NoFolders option is not available on Macintosh. You can use the baGetFiles function to display a files only dialog box.

To make it easier to enter the constants, here are some scripts:

Director:

set OFN_READONLY = 1
set OFN_OVERWRITEPROMPT = 2
set OFN_HIDEREADONLY = 4
set OFN_NOCHANGEDIR = 8
set OFN_ALLOWMULTISELECT = 512
set OFN_PATHMUSTEXIST = 2048
set OFN_FILEMUSTEXIST = 4096
set OFN_CREATEPROMPT = 8192
set OFN_NOREADONLYRETURN = 32768
set OFN_NONETWORKBUTTON = 131072
set OFN_NOLONGNAMES = 262144
set OFN_EXPLORER = 524288
set OFN_NODEREFERENCELINKS = 1048576
set OFN_LONGNAMES = 2097152
set OFN_SHOWPLACESBAR = 4194304

Authorware:

OFN_READONLY := 1
OFN_OVERWRITEPROMPT := 2
OFN_HIDEREADONLY := 4
OFN_NOCHANGEDIR := 8
OFN_ALLOWMULTISELECT := 512
OFN_PATHMUSTEXIST := 2048
OFN_FILEMUSTEXIST := 4096
OFN_CREATEPROMPT := 8192
OFN_NOREADONLYRETURN := 32768
OFN_NONETWORKBUTTON := 131072
OFN_NOLONGNAMES := 262144
OFN_EXPLORER := 524288
OFN_NODEREFERENCELINKS := 1048576
OFN_LONGNAMES := 2097152
OFN_SHOWPLACESBAR := 4194304

See also:

baGetFilenameEx
baGetFolder
baGetDisk
baGetFiles


baGetFilenameEx

GetFilenameEx

Description:

baGetFilenameEx displays a file dialog box and returns the filename selected.

Platforms:

Windows

Usage:

Result = baGetFilename( Operation, StartDir, Filename, Filter, Flags, Instruction, View, NoFolders, X, Y )

Arguments:

String, string, string, string, integer, string, integer, integer, integer.
Operation is the type of dialog to show. Can be "open" or "save".
StartDir is the initial directory. Use "" for the current directory.
Filename is the initial file name to display.
Filter is the type of files to display. Use "" to show all files.
Flags modifies the behaviour of the dialog.
View specifies the initial view of the dialog.
Instruction is the instruction to display to the user.
If NoFolders is true, the folder selection controls will not be shown.
X is horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

String.
Returns the file name selected, or "" if the user cancelled.

Examples:

Director:
filename = baGetFilenameEx( "save", "c:\temp", "newfile.txt", "Text files|*.txt", 0, "Save new file", 3, false, 100, 100 )

Authorware:
file := baGetFilename( "open", "c:\\temp", "", "", 0, "Select data file to open", 1, true, -1, 0 )

Notes:

This function is an extension of the baGetFilename function. You can specify the View that the dialog box opens in. Can be one of

1 | Icon
2 | List
3 | Report
4 | Thumbnail
5 | Tile

The other arguments are the same as baGetFilename, except that you can not use a Flags of -1.

See also:

baGetFilename
baGetFolder
baGetDisk
baGetFiles


baGetDisk

GetDisk

Description:

baGetDisk displays a directory dialog box and returns the folder selected.

Platforms:

Windows and Macintosh

Usage:

Result = baGetDisk( Disk, Instruction, Flags, X, Y )

Arguments:

String, string, integer, integer, integer.
Disk is the initial disk to be selected in the dialog.
Instruction is the instruction to display to the user.
Flags modifies the behaviour of the dialog.
X and Y are the position of the dialog.

Returns:

String.
Returns the name of the disk selected, or an empty string if the user cancels the dialog.

Examples:

Director:
disk = baGetDisk( "c:\", "Select a disk", 0, 50, 50 )

Authorware:
disk := baGetDisk( "c:\\", "Select a disk", 0, 50, 50 )

Notes:

No flags are currently defined.

The X and Y arguments specify the position of the dialog in screen pixels. Set X to -2 to center the dialog on the screen. Centering the dialog on the stage is not implemented. Using -3 will position the dialog at the position it was last displayed.

See also:

baGetFolder
baGetFilename


baGetFiles

GetFiles

Description:

baGetFiles displays a files dialog box and returns the files selected.

Platforms:

Windows and Macintosh

Usage:

Result = baGetFiles( StartDir, FileSpec, SelectedFile, Title, Instruction, Flags, X, Y )

Arguments:

String, string, string, string, integer, integer, integer.
StartDir is the folder containing the files.
Filespec is the type of files to display. Use "" or "*.*" to show all files.
Filename is the name of the file to be selected when the dialog opens.
Title is the tile of the dialog.
Instruction is an instruction text to display.
Flags modifies the behaviour of the dialog.
X is horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

String or List.
Returns the file name selected, or "" if the user cancelled.
If the Multiselect option is used, the return will be a list of the file selected.

Examples:

Director:
files = baGetFiles( the moviePath & "images", "*.jpg", "", "My program", "Select pictures to import", 3, 100, 100 )

Authorware:
files := baGetFiles( FileLocation ^ "images", "*.jpg", "", "My program", "Select pictures to import", 3, 100, 100 )

Notes:

On Windows, The FileSpec is a standard DOS wildcard string. Use an empty string to show all files.

The X and Y values are the number of pixels from the top left corner of the screen. Set X to -1 to position the dialog in the center of the calling Director/Authorware window. Set X to -2 to position the dialog in the center of the screen.

The flags argument allows you to change the way the dialog box looks and behaves. It can be the combination of any of these values:

1 | GF_MULTISELECT The dialog box allows multiple selections. The return will always be a list.
2 | GF_SIMPLESELECT Windows only Allows the user to select multiple files without needing to use the Shift and Control keys. The return will always be a list.
4 | GF_RETURNASLIST Returns the files selected as a list.
8 | GF_SHOWHIDDEN Shows hidden files in the dialog list. By default, hidden files are not displayed.
16 | GF_SHOWBUNDLES Macintosh only Include bundles in the list.
32 | GF_HIDEEXTENSIONS Do not show the file extensions of the files in the list.

See also:

baGetFilename
baGetFolder
baGetDisk


baFolderSize

FolderSize

Description:

baFolderSize returns the size of a folder.

Platforms:

Windows and Macintosh

Usage:

Result = baFolderSize( Folder, FileSpec, SubFolders )

Arguments:

String, string, integer.
Folder is the folder to get the size of.
FileSpec determines what files are included.
If SubFolders is true, the size of subfolders is also included.

Returns:

Integer.
Returns the size of the folder in kilobytes (1k = 1000 bytes).

Examples:

Director:
size = baFolderSize( "c:\Data", "*.*", 1 )

Authorware:
folder := baFolderSize( "c:\\Data", "*.*", 1 )

Notes:

On Windows, the FileSpec is a DOS wildcard, eg "*.bmp". Only one type can be specified. Use "*.*" to match all files.

On Macintosh, the FileSpec can be either a four character type code eg "TEXT" or an extension eg ".txt". Only one type or extension can be specified. Use an empty string or "*.*" to match all files.


baMoveOnReboot

MoveOnReboot

Description:

baMoveOnReboot moves a file on system reboot.

Platforms:

Windows

Usage:

Result = baMoveOnReboot( SourceFile, DestFile )

Arguments:

String, string.
SourceFile is the file to move.
DestFile is the new name of the file.

Returns:

Integer.
The function returns 1 if successful, otherwise 0. Note that the function can not check if the file will actually be moved/deleted, only that Windows will attempt to do it when the system next reboots.

Examples:

Director:
OK = baMoveOnReboot( "c:\Data\student.log", "c:\Backup\student.log" )

Authorware:
OK := baMoveOnReboot( "c:\\Data\\student.log", "c:\\Backup\\student.log" )

Notes:

This function allows you to move or delete a file that is currently in use by Windows and can't be moved or deleted until Windows restarts.

Passing in an empty string as the DestFile will mean that the file will be deleted on reboot.

This function will work on folders as well as files.


baFindFirstFile

`

Description:

baFindFirstFile searches for the first file matching a specification.

Platforms:

Windows and Macintosh

Usage:

Result = baFindFirstFile( StartDir, FileSpec )

Arguments:

String, string.
StartDir is the directory to start searching in.
FileSpec is the pattern to search for.

Returns:

String.
Returns the full path to the first file found

Examples:

Director:
file = baFindFirstFile( "c:\", "netscape.exe" ) -- searches drive c for netscape.exe

Authorware:
file := baFindFirstFile( "c:\\windows", "*.ttf" ) -- searches for fonts

Notes:

All sub-directories of the starting directory will be included in the search. This function can be used with baFindNextFile to find all files.

On Windows, you can use standard DOS wildcard searching.

On Macintosh, if the FileSpec starts with *, then all files with FileSpec in the name will be found, otherwise only exact matches will be returned.

Here are examples of searching the C drive for all copies of "netscape.exe"

Director:

fileList = [] -- a list to contain the found files
file = baFindFirstFile( "c:\", "netscape.exe" )
-- loop through all found files and add to the list
repeat while file <> ""
append( fileList, file )
file = baFindNextFile()
end repeat
baFindClose()

Authorware:

fileList := [] -- a list to contain the found files
file := baFindFirstFile( "c:\\", "netscape.exe" )
repeat while file <> ""
AddLinear( fileList, file )
file := baFindNextFile()
end repeat
baFindClose()

See also:

baFindNextFile
baFindClose


baFindNextFile

FindNextFile

Description:

baFindNextFile continues a search started with baFindFirstFile.

Platforms:

Windows and Macintosh

Usage:

Result = baFindNextFile( )

Arguments:

None.

Returns:

String.
Returns the full path to the next file found

Examples:

Director:
file = baFindNextFile( )

Authorware:
file := baFindNextFile( )

Notes:

You must call baFindFirstFile before calling this function. baFindFirstFile sets up the search criteria, and allocates the required memory. When you are finished finding all the files you are interested in, you should call baFindClose to free memory allocated by baFindFirstFile.

See also:

baFindFirstFile
baFindClose


baFindClose

FindClose

Description:

baFindClose finishes a search started with baFindFirstFile.

Platforms:

Windows and Macintosh

Usage:

baFindClose( )

Arguments:

None.

Returns:

Void.

Examples:

Director:
baFindClose( )

Authorware:
baFindClose( )

Notes:

This function frees memory allocated by baFindFirstFile. After calling this function, you must call baFindFirstFile to start a new search.

See also:

baFindFirstFile
baFindNextFile


baEncryptFile

EncryptFile

Description:

baEncryptFile encrypts/decrypts a file.

Platforms:

Windows and Macintosh

Usage:

Result = baEncryptFile( FileName, Key )

Arguments:

String, string.
FileName is the file to encrypt/decrypt.
Key is the string to use as the encryption key.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baEncryptFile( "d:\results.dat" , "This is my key" )

Authorware:
OK := baEncryptFile( "d:\results.dat" , "This is my key" )

Notes:

This function uses an xor routine to encrypt a file. To decrypt the file, run the function again using the same key. This will return it to it's original state.


baFindDrive

FindDrive

Description:

baFindDrive searches all drives looking for a specified file.

Platforms:

Windows

Usage:

Result = baFindDrive( StartDrive, FileName )

Arguments:

String, string.
StartDrive is the letter of the drive to start searching on.
FileName is the name of the file to search for.

Returns:

String.
Returns the letter of the Drive where the file was found. If the file is not found, returns an empty string.

Examples:

Director:
Drive = baFindDrive( "c", "myfile.id" )

Authorware:
Drive := baFindDrive( "c", "myfile.id" )

Notes:

The StartDrive option can be used to avoid searching floppy disks.

The FileName can consist of a path name as well as the filename. For example, FindDrive( "c", "data\avi\cn232.avi" ) will search for "c:\data\avi\cn232.avi", "d:\data\avi\cn232.avi", "e:\data\avi\cn232.avi", etc. If a path is not included, then the root directory of the drive will be used in the search. The search is done in alphabetical order.

This function can be used to search for content that is stored separately from the main packaged file eg on a CD or network drive.

See also:

baDiskInfo


baShell

Shell

Description:

baShell executes a file.

Platforms:

Windows and Macintosh

Usage:

Result = baShell( Operation, Filename, Args, WorkDir, State )

Arguments:

String, string, string, string, string.
Operation is the action to perform on the file.
Filename is the name of the file the shortcut will point to.
Args is any command line arguments to use.
WorkDir is the working directory to set. Ignored on Macintosh.
State is the state to start the program in. Ignored on Macintosh.

Returns:

Integer.
Returns a number larger than 32 if successful.
Returns an error code. If the return is less than 32 than an error occurred. On Windows, possible return values are:
0 | System was out of memory.
2 | File was not found.
3 | Path was not found.
5 | Sharing or network-protection error.
6 | Library required separate data segments for each task.
8 | There was insufficient memory to start the application.
10 | Windows version was incorrect.
11 | Executable file was invalid. Either it was not a Windows application or there was an error in the .EXE image.
12 | Application was designed for a different operating system.
13 | Application was designed for MS-DOS 4.0.
14 | Type of executable file was unknown.
15 | Attempt was made to load a real-mode application (developed for an earlier version of Windows).
16 | Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.
19 | Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded.
20 | Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this application was corrupt.
21 | Application requires 32-bit extensions.
26 | A sharing violation occurred.
27 | The filename association is incomplete or invalid.
29 | The DDE transaction failed.
30 | The DDE transaction could not be completed because other DDE transactions were being processed.
31 | There is no application associated with the given filename

Examples:

Director:
ok = baShell( "open", "c:\windows\notepad.exe", "myfile.txt" , "", "normal" )
ok = baShell( "edit", "myfile.htm" , "", "", "normal" )

Authorware:
ok := baShell( "open", "myfile.doc", "" , "", "normal" )

Notes:

On Windows, this function can execute either a document or a program file. If it opens a document file, the Args parameter is ignored. The Operation can be any action that is registered with the document type, most commonly 'open' and 'print'. If the specified action is not registered to the document, the function will return 31. Only the 'open' action works on program files.

On Macintosh, this function can be used to open a document in a specified program, rather than in the default program as baOpenFile does. The Filename must be supplied in Unix format. If there is a space in the file name, then the entire name must be surrounded by single quotation marks. The Args is the document to open and must be a valid existing file name, be in Unix format and use single quotation marks if the name contains a space. You can supply more than one document name, in this case each file name must be surrounded by single quotation marks and separated by a space.

On Macintosh, you can use "system" as an Operation to execute a system function, in which case the Filename is used for the command passed to the system, e.g. baShell( "system", "killall TextEdit", "", "", "" ).

See also:

baOpenFile
baPrintFile
baRunProgram


baOpenFile

OpenFile

Description:

baOpenFile opens a document, using the program that the file is associated with.

Platforms:

Windows and Macintosh

Usage:

Result = baOpenFile( FileName , State )

Arguments:

String, string.
FileName is the name of the file to open. The full path name should be supplied.
State is the window state to open the file with.
On Windows, can be one of these:
"Normal"shows in its usual state.
"Hidden"is not visible.
"Maximised"shows as a maximised window.
"Minimised"shows as an minimised icon.
On Macintosh, State is ignored.

Returns:

Integer.
Returns an error code. If the return is less than 32 then an error occurred.
See Notes for details.

Examples:

Director:
OK = baOpenFile( the moviePath & "test.txt" , "maximised" )

Authorware:
OK := baOpenFile( FileLocation ^ "test.txt" , "maximised" )

Notes:

You should always use the full path to the file being opened. Windows will search for the file in limited specific places such as the current directory and the PATH variable, but Macintosh won't.

On Windows, possible errors include:

0 | System was out of memory.
2 | File was not found.
3 | Path was not found.
5 | Sharing or network-protection error.
6 | Library required separate data segments for each task.
8 | There was insufficient memory to start the application.
10 | Windows version was incorrect.
11 | Executable file was invalid. Either it was not a Windows application or there was an error in the .EXE image.
12 | Application was designed for a different operating system.
13 | Application was designed for MS-DOS 4.0.
14 | Type of executable file was unknown.
15 | Attempt was made to load a real-mode application (developed for an earlier version of Windows).
16 | Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.
19 | Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded.
20 | Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this application was corrupt.
21 | Application requires 32-bit extensions.
26 | A sharing violation occurred.
27 | The filename association is incomplete or invalid.
29 | The DDE transaction failed.
30 | The DDE transaction could not be completed because other DDE transactions were being processed.
31 | There is no application associated with the given filename.

On Macintosh, an error will result in a return of 0.

To open a file in a program other than the default one, use baShell.

See also:

baPrintFile
baShell


baOpenURL

OpenURL

Description:

baOpenURL opens an internet document, using the default browser.

Platforms:

Windows and Macintosh

Usage:

Result = baOpenURL( URL , State )

Arguments:

String, string.
URL is the name of the document to open.
State is the window state to open the browser with.
On Windows, can be one of these:
"Normal"shows in its usual state.
"Hidden"is not visible.
"Maximised"shows as a maximised window.
"Minimised"shows as an minimised icon.
On Macintosh, State is ignored.

Returns:

Integer.
Returns 1 if successful, else 0. Success means that there is a browser associated with .htm files, and it can be started. If opening a local file, the function will return 0 if the file does not exist.

Examples:

Director:
OK = baOpenURL( "http://www.macromedia.com" , "maximised" )

Authorware:
OK := baOpenURL( "http://www.macromedia.com" , "maximised" )

Notes:

The URL can be any valid internet URL or a local HTML file.

On Macintosh, Internet Config will be used to determine the default browser.


baPrintFile

PrintFile

Description:

baPrintFile prints a document, using the program that the file is associated with.

Platforms:

Windows and Macintosh

Usage:

Result = baPrintFile( FileName )

Arguments:

String.
FileName is the name of the file to print. The full path name should be supplied.

Returns:

Integer.
Returns an error code. If the return is less than 32 than an error occurred.
On Windows, some return values are:
0 | System was out of memory.
2 | File was not found.
31 | There is no application registered to print the given filename extension.

On Macintosh, an error will always return 0.

Examples:

Director:
OK = baPrintFile( the moviePath & "test.txt" )

Authorware:
OK := baPrintFile( FileLocation ^ "test.txt" )

See also:

baOpenFile
baShell


baShortFileName

ShortFileName

Description:

baShortFileName returns the short name of a long filename.

Platforms:

Windows and Macintosh

Usage:

Result = baShortFileName( LongFileName )

Arguments:

String.
LongFileName is the name of the file. You must supply the full path name to the file.

Returns:

String.
Returns the file name in DOS format. If the file doesn't exist, then the return will be an empty string.

Examples:

Director:
ShortName = baShortFileName( "c:\Program Files\Accessories\Wordpad.exe" )

Authorware:
ShortName := baShortFileName( "c:\\Program Files\\Accessories\\Wordpad.exe" )

Notes:

On Macintosh, this function will only work with and return HFS names.

See also:

baLongFileName


baLongFileName

LongFileName

Description:

baLongFileName returns the long version of a short filename.

Platforms:

Windows and Macintosh

Usage:

Result = baLongFileName( ShortFileName )

Arguments:

String.
ShortFileName is the name of the file. You must supply the full path name to the file.

Returns:

String.
Returns the file name in long format. If the file doesn't exist, then the return will be an empty string.

Examples:

Director:
LongName = baLongFileName( "c:\Progra~1\Access~1\wordpad.exe " )

Authorware:
LongName := baLongFileName("c:\Progra~1\Access~1\wordpad.exe " )

Notes:

On Macintosh, this function will only work with and return HFS names.

See also:

baShortFileName


baTempFileName

TempFileName

Description:

baTempFileName returns a temporary file name that is guaranteed not to exist.

Platforms:

Windows

Usage:

Result = baTempFileName( Prefix )

Arguments:

String.
Prefix is a string of up to 3 characters that is used to generate the filename.

Returns:

String.
Returns the file name, including the path.

Examples:

Director:
FileName = TempFileName( "gaz" )

Authorware:
FileName := TempFileName( "gaz" )

Notes:

The file name will consist of the path name, followed by the prefix, then a number, with a ".tmp" extension; eg "c:\temp\gaz12453.tmp"
An empty file with that name will be created.

The baTempFileName function gets the temporary file path as follows:
1.The path specified by the TMP environment variable.
2.The path specified by the TEMP environment variable, if TMP is not defined.
3.The current directory, if both TMP and TEMP are not defined.

Files created using file names returned by this function are not automatically deleted when Windows shuts down.


baHfsName

HfsName

Description:

baHfsName returns a file name in HFS format.

Platforms:

Macintosh

Usage:

Result = baHfsName( File )

Arguments:

String.
The file name to convert in Unix format.

Returns:

String.
The converted name, or an empty string if the file doesn’t exist.

Examples:

Director:
hfs = baHfsName( “/Volumes/Mac HD/Data/products.pdf” )

Authorware:
hfs := baHfsName( “/Volumes/Mac HD/Data/products.pdf” )

Notes:

The file does not have to exist for this function to work. The name returned may not be a valid HFS name - it may contain Unicode characters or be longer than 31 characters. To ensure a valid HFS name, use baShortFilename.

See also:

baUnixName
baReturnUnixNames
Specifying file names


baUnixName

UnixName

Description:

baUnixName returns a file name in Unix format.

Platforms:

Macintosh

Usage:

Result = baUnixName( File )

Arguments:

String.
The file name to convert in Hfs format.

Returns:

String.
The converted name, or an empty string if the file doesn’t exist.

Examples:

Director:
hfs = baUnixName( “Mac HD:Data:products.pdf” )

Authorware:
hfs := baUnixName( “Mac HD:Data:products.pdf” )

Notes:

The file does not have to exist for this function to work.

See also:

baReturnUnixNames
baHfsName
Specifying file names


baReturnUnixNames

ReturnUnixNames

Description:

baReturnUnixNames specifies whether to return file names in Unix format.

Platforms:

Macintosh

Usage:

baReturnUnixNames( On )

Arguments:

Integer.
If On is true, file functions will return names in Unix format.

Returns:

Void.

Examples:

Director:
baReturnUnixNames( true )

Authorware:
baReturnUnixNames( true )

Notes:

By default, file functions return names in HFS format Mac HD:Data:products.pdf . In this format, file and folder names are limited to 31 characters in length, and can not contain Unicode characters.

You can choose to return the names in Unix format /Volumes/Mac HD/Data/products.pdf In this format, file and folder names can be up to 256 characters long, and can contain Unicode characters. The system generates short names for files with names longer than 31 characters, and HFS format uses these names. Buddy functions can use either format, but the function will work in the format passed in. For example, if you pass in a HFS name to baXCopy, then all files will be copied in HFS format, so long file names and Unicode characters will be lost.

You can convert between HFS and Unix names using the baUnixName and baHfsName functions.

To utilise Unicode support in Director 11, you must use Unix file names.

See also:

Specifying file names
baHfsName
baUnixName


baMakeShortcut

MakeShortcut

Description:

baMakeShortcut creates a shortcut to a file.

Platforms:

Windows and Macintosh

Usage:

Result = baMakeShortcut( FileName , Path , Title )

Arguments:

String, string, string.
FileName is the file that the shortcut will point to.
Path is the folder that the shortcut will be created in.
Title is the name of the shortcut.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baMakeShortcut( "d:\mworld.exe" , "c:\windows\desktop" , "Multimedia World" )

Authorware:
OK := baMakeShortcut( "d:\\mworld.exe" , "c:\\windows\\desktop" , "Multimedia World" )

Notes:

On Macintosh, if the file the alias points to contains a custom icon, it will not be copied to the alias file. The Finder will update the alias when the file is run.

See also:

baMakeShortcutEx
baResolveShortcut


baMakeShortcutEx

MakeShortcutEx

Description:

baMakeShortcutEx creates a shortcut.

Platforms:

Windows

Usage:

Result = baMakeShortcutEx( FileName, Path, Title, Args, WorkDir, Icon, IconNumber, Hotkey, State )

Arguments:

String, string, string, string, string, string, integer, integer, string.
Filename is the name of the file the shortcut will point to.
Path is the folder to create the shortcut in.
Title is the name of the shortcut.
Args is any command line arguments to use.
WorkDir is the working directory to set.
Icon is the name of the icon file.
IconNumber is the number of the icon in Icon to use.
Hokey is the virtual key code of the hotkey to assign to the shortcut.
State is the state to start the program in. Can be "normal", "min", "max"

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
ok = baMakeShortcutEx( "c:\windows\notepad.exe", "c:\temp", "My Notepad", "", "c:\windows", "c:\windows\system32\shell32.dll", 12, 65, "normal" )

Authorware:
ok := baMakeShortcutEx( "c:\\window\\notepad.exe", baSysFolder( "desktop" ), "My Document", docpath ^ "theFile.txt", "", "", 0, 65, "max" )

Notes:

This function is an extended version of baMakeShortcut. Only the first three arguments are required - if any of the others are an empty string or 0, they will be ignored.

The Icon parameter can be either an .ico, .exe or .dll file. If the file is a .ico, then the IconNumber parameter is ignored. If it is a .exe or .dll file, then the IconNumber is the number of the icon in that file to use. If the Icon is an empty string (""), then the first icon in the Command .exe file will be used.

The Hotkey is a number that represents the virtual key code to use as the hotkey. The actual hotkey will be Ctrl + Alt + the key. eg a value of 65 will produce a hotkey of Ctrl+Alt+A. If the value is negative then Shift will also be used. eg -66 will produce Ctrl+Alt+Shift+B. A list of Virtual Key Codes is supplied.

See also:

baMakeShortcut
baResolveShortcut


baResolveShortcut

ResolveShortcut

Description:

baResolveShortcut returns the file a shortcut. points to.

Platforms:

Windows

Usage:

Result = baResolveShortcut( Shortcut )

Arguments:

String.
Shortcut is the name of the shortcut.

Returns:

String.
Returns the file name, or an empty string if the shortcut doesn't exist or isn't a shortcut.

Examples:

Director:
filename = baResolveShortcut( "c:\temp\My Shortcut" )

Authorware:
filename := baResolveShortcut( "c:\\temp\\My Shortcut" )

Notes:

The file extension for shortcuts is .lnk, which Windows does not display. If does not matter whether or not you include this extension in your shortcut name.

See also:

baMakeShortcut
baMakeShortcutEx


baBundleApp

BundleApp

Description:

baBundleApp returns the application file inside a bundle.

Platforms:

Macintosh

Usage:

Result = baBundleApp( BundleName )

Arguments:

String.
BundleName is the bundle to get the application of.

Returns:

String.
Returns the full path to the application file, or an empty string if an error occurred.

Examples:

Director:
bundle = baBundleApp( "OSX:Applications:Internet Explorer.app:" )

Authorware:
bundle := baBundleApp( "OSX:Applications:Internet Explorer.app:" )

See also:

baIsBundle


Window functions

baWindowInfo | returns info (state, size, position, title, class) of a window
baFindWindow | finds a window with given title or class
baWindowList | returns a list of all windows with given title or class
baChildWindowList | returns a list a window's child windows
baActiveWindow | returns the active window
baCloseWindow | closes a window
baCloseApp | closes the application owning a window
baSetWindowState | minimises, maximises, hides a window
baActivateWindow | activates the specified window
baSetWindowTitle | set the caption of a window
baMoveWindow | moves/resizes a window
baWindowToFront | brings a window to the front of other windows
baWindowToBack | sends a window to the back of other windows
baWindowDepth | gets the z-order depth of a window
baSetWindowDepth | sets the z-order depth of a window
baWaitForWindow | waits until a specified window is in a specified state
baWaitTillActive | waits until a specified window becomes the active one
baNextActiveWindow | returns the next window to become active
baWindowExists | checks that a window handle is valid
baGetWindow | returns a window related to another window
baSendKeys | sends simulated key presses to the active window
baMouseClick | simulates a mouse click
baSendMsg | sends a windows message to a window
baAddSysItems | adds System menu, min and max boxes
baRemoveSysItems | removes System menu, min and max boxes
baClipWindow | removes edges from window
baSetParent | makes a window a child of another window
baWinHandle | returns the main Director or Authorware presentation window
baStageHandle | returns the Director stage window


baWindowInfo

WindowInfo

Description:

baWindowInfo returns information about a window.

Platforms:

Windows and Macintosh

Usage:

Result = baWindowInfo( WindowHandle , InfoType )

Arguments:

Integer, string
WindowHandle is the handle of the window.
InfoType is the type of information required. Can be one of the following:

"title"

the caption of the window Windows Macintosh

"class"

the class name of the window Windows Macintosh

"state"

the present state of the window. Windows
Return can be:
"hidden" | the window is hidden
"min" | minimised
"max" | maximised
"normal" | normal state

"text"

the window's text Windows

"left"

the left edge of the window in pixels Windows

"right"

the right edge Windows

"top"

the top edge of the window in pixels Windows

"bottom"

the bottom edge Windows

"height"

the height of the window Windows

"width"

the width of the window Windows

"rel left"

the left edge of the window in relation to it's parent Windows

"rel top"

the top edge of the window in relation to it's parent Windows

"client height"

the height of the client area of the window Windows

"client width"

the width of the client area of the window Windows

"app"

the path to the application that owns the window Windows Macintosh

Returns:

String.
Returns the information requested, or "Invalid" if the window doesn't exist

Examples:

Director:
State = baWindowInfo( Window, "state" )

Authorware:
State := baWindowInfo( Window, "state" )

Notes:

The "text" option can be used to retrieve the text in an edit control window.

When using the "rel left" and "rel top" options, if the window is a child of another window, then the values returned will be relative to the parent window. If the window does not have a parent window, then the returns will be relative to the screen.

See also:

baSetWindowTitle
baMoveWindow
baSetWindowState
baFindWindow


baFindWindow

FindWindow

Description:

baFindWindow returns the handle of a window. This handle can then be used in other window management functions.

Platforms:

Windows and Macintosh

Usage:

Result = baFindWindow( Class/Creator, Title )

Arguments:

String, string.
On Windows, Class is the class name of the window.
On Macintosh, Creator it is the creator type of the application.
Title is the text in the window's caption.
The function can use either or both arguments. If one of the arguments is blank, then only the other argument will be used in searching for the window.

Returns:

Integer.
Returns the window handle. If the window isn't found, then returns 0.

Examples:

Director:
WinHandle = baFindWindow( "" , "Calculator" )

Authorware:
WinHandle := baFindWindow( "" , "Calculator" )

Notes:

On Windows, a window handle is an number that Windows uses to identify windows. Every window has a unique handle. You can use this handle to manipulate the window; bring it to the front, close it, etc. Every window also has a class name. This is assigned by the programmer, and can be used to find a specific window. For example, the Class window for the main MS Word window is "OpusApp". To find the handle for the Word window, you could use FindWindow( "OpusApp", "" ).

If you know the text in the window's caption, you can use this to find the window. For example, FindWindow( "" , "Notepad mydoc.txt" ).

On Macintosh, the window handle returned is the identifier for the application rather than an individual window. The title of the window will be the name that appears in the Application menu.

See also:

baWindowList
baGetWindow


baWindowList

WindowList

Description:

baWindowList returns a list of the handles of open windows. These handles can then be used in other window management functions.

Platforms:

Windows and Macintosh

Usage:

Result = baWindowList( Class/Creator, Caption, MatchCaption )

Arguments:

String, string, integer.
On Windows, Class is the Class name of the windows to find.
On Macintosh, Creator is the four character creator code of the application.
Caption is the Caption of the windows to find.
If MatchCaption is true, then Caption must match the window caption exactly (apart from case). If it is false, then any window which contains Caption will be returned. If Caption is an empty string, then MatchCaption is ignored.
The function can use either or both Class and Caption arguments. If one of the arguments is empty, then only the other argument will be used in searching for the windows.

Returns:

List
Returns a list or string of all matching window handles.

Examples:

Director:
WndList = baWindowList( "" , "Netscape" , false ) -- return list of all windows with a caption containing "Netscape"

Authorware:
WndList := baWindowList( "Notepad" , "" , false ) -- return list of all Notepad windows

Notes:

The windows will be listed in front-to-back order - the first window in the list will be the one at the front, while the last one in the list will be behind all other windows in the list.

See also:

baFindWindow
baChildWindowList
baGetWindow


baChildWindowList

ChildWindowList

Description:

baChildWindowList returns a list of a window's child windows.

Platforms:

Windows

Usage:

Result = baChildWindowList( ParentWnd, Class, Caption, MatchCaption )

Arguments:

Integer, string, string, integer.
ParentWnd is the window to get the children of.
Class is the class of child windows to include.
Caption is the window title of child windows to include.
If MatchCaption is true, then Caption must match the window caption exactly (apart from case). If it is false, then any window which contains Caption will be returned. If Caption is an empty string, then MatchCaption is ignored.
The function can use either or both Class and Caption arguments. If one of the arguments is empty, then only the other argument will be used in searching for the windows.

Returns:

List.
Returns a list or string of all found window handles.

Examples:

Director:
wndList = baChildWindowList( 1234, "", "", 0 ) -- return list of all child windows of window 1234

Authorware:
wndList := baChildWindowList( 1234, "Edit", "", 0 ) -- return list of all edit controls of window 1234

Notes:

This function will return all child windows of the parent window and all its' children.

See also:

baFindWindow
baWindowList
baGetWindow


baActiveWindow

ActiveWindow

Description:

baActiveWindow returns the handle of the currently active window.

Platforms:

Windows and Macintosh

Usage:

Result = baActiveWindow( )

Arguments:

None.

Returns:

Integer.
Returns the handle of the active window.

Examples:

Director:
WinHandle = baActiveWindow( )

Authorware:
WinHandle := baActiveWindow( )

Notes:

On Windows, under some conditions, this function can return 0. This would typically happen during the time an application starts up - the app may have control, but not yet opened its main window. Do not use a loop such as this:

wnd = 0
baRunProgram( "other.exe" , "normal" , false )
repeat while wnd <> baWinHandle()
wnd = baActiveWindow() -- ActiveWindow could return 0
end repeat

In the case above, it is possible that wnd will equal 0, not the window handle of the new application. A better way to achieve this is to use the baNextActiveWindow function.

See also:

baNextActiveWindow
baWaitForWindow


baCloseWindow

CloseWindow

Description: | baCloseWindow closes the specified window.
Platforms: | Windows and Macintosh
Usage: | Result = baCloseWindow( WinHandle )
Arguments: | Integer. WinHandle is the handle of the window to close.
Returns: | Integer. Returns 1 if successful, otherwise 0.
Examples: | Director: OK = baCloseWindow( WinHandle ) Authorware: OK := baCloseWindow( WinHandle )
Notes: | On Macintosh, this function sends a Quit AppleEvent to the application. Some programs need to be made active before they will quit - you may need to do a baActiveWindow before using this function.
See also: | baCloseApp


baCloseApp

CloseApp

Description: | baCloseApp closes the application owning a specified window.
Platforms: | Windows
Usage: | Result = baCloseApp( WinHandle )
Arguments: | Integer. WinHandle is the handle of the window to close.
Returns: | Void.
Examples: | Director: baCloseApp( WinHandle ) Authorware: baCloseApp( WinHandle )
Notes: | Not all applications react kindly to being closed by other applications, and may leave the system unstable. If you use this function, be sure to test thoroughly. If possible, use the baCloseWindow function instead.
See also: | baCloseWindow


baSetWindowState

SetWindowState

Description:

baSetWindowState allows you to manipulate the specified window.

Platforms:

Windows

Usage:

baSetWindowState( WinHandle, State )

Arguments:

Integer, string.
WinHandle is the handle of the window to change. To change the Director or Authorware window, use the baWinHandle() function.
State is the window's new state. Can be one of the following:
"Hidden" | Hides the window and passes activation to another window.
"Restored" | Activates and displays a window. If the window is minimized or maximized, it is restored to its original size and position.
"Normal" | Activates a window and displays it in its current size and position.
"Maximised" | Activates a window and displays it as a maximized window.
"Minimised" | Activates a window and displays it as an icon.
"MinNotActive" | Displays a window as an icon. The window that is currently active remains active.
"NotActive" | Displays a window in its current state. The window that is currently active remains active.
"ShowNotActive" | Displays a window in its most recent size and position. The window that is currently active remains active.
"StayOnTop" | Makes the window stay on top of all other windows.
"DontStayOnTop" | Allows the window to go behind other windows.

Returns:

Void.

Examples:

Director:
baSetWindowState( baWinHandle(), "StayOnTop" )

Authorware:
baSetWindowState( baWinHandle(), "StayOnTop" )

Notes:

If the WinHandle is 0, or is not the valid handle of a window, then the function will act on the active window.

See also:

baWindowInfo
baActivateWindow
baFindWindow


baActivateWindow

ActivateWindow

Description:

baActivateWindow activates the specified window.

Platforms:

Windows and Macintosh

Usage:

Result = baActivateWindow( WinHandle )

Arguments:

Integer.
WinHandle is the handle of the window to activate. To activate the Director or Authorware window, use the baWinHandle() function.

Returns:

Integer.
Returns 1 if successful, otherwise 0.

Examples:

Director:
OK = baActivateWindow( baWinHandle() )

Authorware:
OK := baActivateWindow( baWinHandle() )

Notes:

Microsoft has introduced a change to the way this function operates under Win 98 and NT 4. If your user is presently typing in a window, then you can not force another window to become the active one. Instead, the button for that window will flash on the Taskbar to alert the user that a program needs attention.

See also:

baFindWindow


baSetWindowTitle

SetWindowTitle

Description:

baSetWindowTitle sets the title of a specified window.

Platforms:

Windows

Usage:

baSetWindowTitle( WinHandle, Title )

Arguments:

Integer, string.
WinHandle is the handle of the window to change the title of.
Title is the string to change the window title to.

Returns:

Void.

Examples:

Director:
baSetWindowTitle( Window, "Module 1" )

Authorware:
baSetWindowTitle( Window, "Module 1" )

Notes:

If the WinHandle is 0, or is not the valid handle of a window, then the function will act on the active window.

See also:

baWindowInfo
baFindWindow


baMoveWindow

MoveWindow

Description:

baMoveWindow moves or resizes the specified window.

Platforms:

Windows

Usage:

baMoveWindow( WinHandle, Left , Top , Width , Height , Activate )

Arguments:

Integer, integer, integer, integer, integer, integer.
WinHandle is the handle of the window to move.
Left is the new left position of the window.
Top is the new top position of the window.
Width is the new width of the window.
Height is the new height of the window.
If Activate is true then the window will be activated.

Returns:

Void.

Examples:

Director:
baMoveWindow( Wnd, 20 , 20 , 400 , 400 , true )

Authorware:
baMoveWindow( Wnd, 20 , 20 , 400 , 400 , true )

Notes:

If both Left and Top arguments are -1, then the windows current position will not be changed.

If both Width and Height are -1, then the windows current size will not be changed.

See also:

baWindowInfo


baWindowtoFront

WindowToFront

Description:

baWindowToFront brings the specified window to the front of all other windows.

Platforms:

Windows

Usage:

Result = baWindowToFront( WinHandle )

Arguments:

Integer.
WinHandle is the handle of the window to bring to the front. To bring the Director or Authorware window to the front, use the baWinHandle() function.

Returns:

Integer.
Returns 1 if successful, otherwise 0.

Examples:

Director:
OK = baWindowToFront( baWinHandle() )

Authorware:
OK := baWindowToFront( baWinHandle() )

See also:

baWindowToBack
baWindowDepth
baSetWindowDepth


baWindowToBack

WindowToBack

Description:

baWindowToBack sends the specified window to the back of all other windows.

Platforms:

Windows

Usage:

Result = baWindowToBack( WinHandle )

Arguments:

Integer.
WinHandle is the handle of the window to send to the back. To send the Director or Authorware window to the back, use the baWinHandle() function.

Returns:

Integer.
Returns 1 if successful, otherwise 0.

Examples:

Director:
OK = baWindowToBack( baWinHandle() )

Authorware:
OK := baWindowToBack( baWinHandle() )

See also:

baWindowToFront
baWindowDepth
baSetWindowDepth


baWindowDepth

WindowDepth

Description:

baWindowDepth gets the z-order depth of the specified window.

Platforms:

Windows

Usage:

Result = baWindowDepth( WinHandle )

Arguments:

Integer.
WinHandle is the handle to get the depth of.

Returns:

Integer.
Returns the depth, or 0 if WinHandle doesn't exist.

Examples:

Director:
depth = baWindowDepth( baWinHandle() )

Authorware:
depth := baWindowDepth( baWinHandle() )

Notes:

Only windows that are visible are counted in the depth. If a window's state is hidden, then it will be ignored by this function. Windows that are set as topmost or stay-on-top will be counted before normal windows - even if they are minimised.

See also:

baSetWindowDepth
baWindowToFront
baWindowToBack


baSetWindowDepth

SetWindowDepth

Description:

baSetWindowDepth sets the z-order depth of the specified window.

Platforms:

Windows

Usage:

baSetWindowDepth( WinHandle , Depth )

Arguments:

Integer, integer.
WinHandle is the handle to set the depth of.
Depth is the new depth to set the window to.

Returns:

Void.

Examples:

Director:
baSetWindowDepth( baWinHandle() , 2 ) -- sets the Director window to below the top window, but in front of all other windows

Authorware:
baSetWindowDepth( 3124 , 5 )

Notes:

Setting a depth greater than the number of visible windows is allowed - the window will be sent to the back of all other windows.

See also:

baWindowDepth
baWindowToFront
baWindowToBack


baWaitForWindow

WaitForWindow

Description:

baWaitForWindow waits until a window is in a specified state, with an optional timeout.

Platforms:

Windows and Macintosh

Usage:

Result = baWaitForWindow( WinHandle , State , TimeOut )

Arguments:

Integer, string, integer.
WinHandle is the handle of the window to wait for.
State is the state to wait for. Can be:
"inactive" | waits until the window is inactive
"active" | waits until the window is active
"closed" | waits until the window is closed
TimeOut is the maximum amount of time to wait in ticks. A tick is equal to 1/60th of a second. If TimeOut is 0, the function will wait indefinitely.

Returns:

Integer.
Returns 0 if the window doesn't exist, or the timeout occurs before the window reaches the specified state.
Returns 1 if the window reached the specified state.

Examples:

Director:
OK = baWaitForWindow( baWinHandle() , "active" , 300 ) -- waits for the Director window to become active, for a maximum of 5 seconds

Authorware:
OK := baWaitForWindow( 3248, "closed" , 600 ) -- waits for the window 3248 to be closed, for a maximum of 10 seconds

Notes:

The "inactive" option is useful for waiting until the Director/Authorware window is inactive after starting another program. When the Director/Authorware window is no longer active, then the other program has opened and has focus.

For example, here is some code to open a readme file in Authorware, and wait until the user has finished with it.

if baOpenFile( "readme.txt" , "normal" ) > 32 then -- open readme file
wnd := baNextActiveWindow( 0 ) -- get handle of Notepad window
baWaitForWindow( baWinHandle() , "active" , 0 ) -- wait till the Authorware window is active i.e. Notepad has been closed or user switched back to Authorware
if baWindowExists( wnd )
then baCloseWindow( wnd ) -- close Notepad
end if
end if

See also:

baWaitTillActive
baNextActiveWindow
baActiveWindow


baWaitTillActive

WaitTillActive

Description:

baWaitTillActive pauses execution until a specified window becomes the active one.

Platforms:

Windows

Usage:

baWaitTillActive( WindowHandle )

Arguments:

Integer.
WindowHandle is the handle of the window to wait for.

Returns:

Void.

Examples:

Director:
baWaitTillActive( baWinHandle() ) -- wait till Director window becomes the active one

Authorware:
baWaitTillActive( baWinHandle() ) -- wait till Authorware window becomes the active one

Notes:

This function is mainly intended to be used with the baRunProgram function. The RunProgram function can pause execution until the jumped to program quits. This may cause a problem if the user switches back to the Authorware program without quitting the jumped to program. If you use the baRunProgram without the pause option, you can use this function (after a short wait) to resume the program if the user switches back to it.

This function is provided for compatibility with older versions. New applications should use the baWaitForWindow function.

See also:

baWaitForWindow
baNextActiveWindow
baActiveWindow


baNextActiveWindow

NextActiveWindow

Description:

baNextActiveWindow returns the next window to become active.

Platforms:

Windows and Macintosh

Usage:

Result = baNextActiveWindow( TimeOut )

Arguments:

Integer.
TimeOut is the maximum amount of time to wait in ticks. A tick is equal to 1/60th of a second. If TimeOut is 0, the function will wait indefinitely.

Returns:

Integer.
Returns the handle of the next active window.
Returns 0 if the timeout occurs before another window becomes active.

Examples:

Director:
wnd = baNextActiveWindow( 300 ) -- waits for the next window to become active, for a maximum of 5 seconds

Authorware:
wnd := baNextActiveWindow( 600 )

Notes:

The next active window is defined as the next window that isn't the window of the Director/Authorware calling program, or a dialog box or a splash screen. It would be typically used after a baRunProgram or baOpenFile call to get the handle of the window the program opens, and is particularly useful for applications such as Netscape and Acrobat that open splash screens.

Here is an example of opening an Acrobat file in Director, and closing it when the user is finished with it.

if baOpenFile( "readme.pdf" , "normal" ) > 32 then -- open acrobat file
wnd = baNextActiveWindow( 0 ) -- get handle of Acrobat window
baWaitForWindow( baWinHandle() , "active" , 0 ) -- wait till the Director window is active i.e. Acrobat has been closed or user switched back to Director
if baWindowExists( wnd ) then
baCloseWindow( wnd ) -- close Acrobat
end if
end if

See also:

baWaitTillActive
baWaitForWindow
baActiveWindow


baWindowExists

WindowExists

Description:

baWindowExists checks if a window handle is valid.

Platforms:

Windows and Macintosh

Usage:

Result = baWindowExists( WinHandle )

Arguments:

Integer.
WindowHandle is the handle of the window to check for.

Returns:

Integer.
Returns 1 if the window exists, else 0.

Examples:

Director:
OK = baWindowExists( 3248 )

Authorware:
OK := baWindowExists( 3248 )

See also:

baFindWindow


baGetWindow

GetWindow

Description:

baGetWindow gets a window that is related to another window.

Platforms:

Windows

Usage:

Result = baGetWindow( WindowHandle , Relation )

Arguments:

Integer, string.
WindowHandle is the handle of the window.
Relation is the type of relationship to look for. Can be one of the following:
"child" | gets the first child window
"first" | gets the first window
"last" | gets the last window
"next" | gets the next window
"previous" | gets the previous window
"owner" | gets the window's owner
"parent" | gets the window's parent

Returns:

Integer.
Returns the handle of the found window, or 0 if the requested window could not be found.

Examples:

Director:
wnd = baGetWindow( 2349 , "parent" )

Authorware:
wnd := baGetWindow( 2349 , "parent" )


baSendKeys

SendKeys

Description:

baSendKeys sends a series of keystrokes to the active window.

Platforms:

Windows and Macintosh

Usage:

Result = baSendKeys( Keys )

Arguments:

String.
Keys is the string of keys to send. See the notes section for a full description.

Returns:

Integer.
Returns an error code.
0 | success
1 | invalid character in string
2 | window unavailable
3 | unknown error
4 | another SendKeys function is still under way

Examples:

Director:
OK = baSendKeys( "hello" ) -- sends "hello"
OK = baSendKeys( "^C" ) -- sends Control C
OK = baSendKeys( "{F1}" ) -- sends the F1 key
OK = baSendKeys( "fname.txt{ENTER}" ) -- sends "fname.txt" then Enter

Authorware:
OK := baSendKeys( "hello" ) -- sends "hello"
OK := baSendKeys( "^C" ) -- sends Control C
OK := baSendKeys( "{F1}" ) -- sends the F1 key
OK := baSendKeys( "fname.txt{ENTER}" ) -- sends "fname.txt" then Enter

Notes:

The string sent can contain any alphanumeric character.

The keys sent will be case sensitive, and this may affect some programs. For example, sending "^C" may be interpreted by some programs as sending Control+Shift+c, others may treat it the same as "^c".

Use "@" for the Alt key, "~" for the Shift key, "^" for the Control key, and “#” for the Macintosh Command key

If you need to send these actual keys, use a combination of Shift and the required letter eg to send "@" use "~2".

Other special keys can be sent as follows: (include the curly brackets)

{F1}, {F2}, etc to {F12} | {ENTER}
{INSERT} | {BKSP}
{DELETE} | {PRTSC}
{HOME} | {ESCAPE}
{END} | {LEFT}
{PGUP} | {RIGHT}
{PGDN} | {UP}
{TAB} | {DOWN}

Sending function keys is not supported on Macintosh.


baMouseClick

MouseClick

Description:

baMouseClick simulates a mouse click.

Platforms:

Windows and Macintosh

Usage:

baMouseClick( Type )

Arguments:

String.
Type is the type of click to generate.
On Windows, can be:
"left"
"middle"
"right"
"left down"
"left up"
"right down"
"right up"
"middle up"
"middle down"
On Macintosh, can be:
"left"
"middle"
"right"

Returns:

Void.

Examples:

Director:
baMouseClick( "left" )

Authorware:
baMouseClick( "right down" )

Notes:

The mouse click is generated at the present cursor position.

See also:

baPlaceCursor


baSendMsg

SendMsg

Description:

baSendMsg sends a Windows message to a window.

Platforms:

Windows

Usage:

Result = baSendMsg( WindowHandle , Message , wParam , lParam , Wait )

Arguments:

Integer, integer, integer, integer, integer.
WindowHandle is the handle of the window to send the message to.
Message is the message to send.
wParam is additional message information.
lParam is additional message information.
If Wait is true, execution is paused until the window processes the message.

Returns:

Integer.
If Wait is true, the return value specifies the result of the message processing and depends on the message sent.
If Wait is false, returns 1 is the message was successfully posted to the window, else 0.

Examples:

Director:
Result = baSendMsg( 65535, 26 , 0, 0, true ) -- send a WM_WININCHANGE message to all windows.

Authorware:
Result := baSendMsg( 65535, 26, 0, 0, true )

Notes:

To use this function, you will need access to Windows API information about messages.


baAddSysItems

AddSysItems

Description:

baAddSysItems is a function which adds the system menu, minimise and maximise buttons to a window.

Platforms:

Windows

Usage:

baAddSysItems( WindowHandle, SystemMenu, MinBox, MaxBox )

Arguments:

Integer, integer, integer, integer.
WindowHandle is the handle of the window to change.
If SystemMenu is true, the system menu is added.
If MinBox is true, the minimize button is added.
If MaxBox is true, the maximize button is added.

Returns:

void.

Examples:

Director:
baAddSysItems(baWinHandle() , false , true , false )

Authorware:
baAddSysItems(baWinHandle() , false , true , false )

Notes:

Use this function with care. Some windows do not react kindly to having their window style changed. Some windows will ignore this call.

This function is limited in 32 bit Windows - only the Director/Authorware window can be changed, and you can only have all the items or none of the items.

See also:

baRemoveSysItems


baRemoveSysItems

RemoveSysItems

Description:

baRemoveSysItems is a function which removes the system menu, minimise and maximise buttons from a window.

Platforms:

Windows

Usage:

baRemoveSysItems( WindowHandle, SystemMenu, MinBox, MaxBox )

Arguments:

Integer, integer, integer, integer.
WindowHandle is the handle of the window to change.
If SystemMenu is true, the system menu is removed.
If MinBox is true, the minimize button is removed.
If MaxBox is true, the maximize button is removed.

Returns:

Void.

Examples:

Director:
baRemoveSysItems(1356 , true , false , false ) -- remove the system menu from window 1356

Authorware:
baRemoveSysItems(1356 , true , false , false ) -- remove the system menu from window 1356

Notes:

Use this function with care. Some windows do not react kindly to having their window style changed. Some windows will ignore this call.

This function is limited in 32 bit Windows - only the Director/Authorware window can be changed, and you can only have all the items or none of the items.

See also:

baAddSysItems


baClipWindow

ClipWindow

Description:

baClipWindow removes the edges from a window.

Platforms:

Windows

Usage:

baClipWindow( WindowHandle, Left, Top, Right, Bottom, Border, Remove )

Arguments:

Integer, integer, integer, integer, integer, integer, integer.
WindowHandle is the handle of the window to change
Left is the amount of the window to remove from the left edge
Top is the amount of the window to remove from the top edge
Right is the amount of the window to remove from the right edge
Bottom is the amount of the window to remove from the bottom edge
If Border is true, then the window border is removed first
If Remove is true, then the window is clipped; if false then any previous clipping is removed and the window is restored to it's normal state.

Returns:

Void.

Examples:

Director:
baClipWindow( 2459 , 10 , 20 , 10 , 10 , true, true )

Authorware:
baClipWindow( 2459 , 10 , 20 , 10 , 10 , true, true )

Notes:

If you specify to remove the border first, then the window's menu bar and borders are removed first, then the window is clipped by the amount specified


baSetParent

SetParent

Description:

baSetParent makes a window a child of another window.

Platforms:

Windows

Usage:

baSetParent( WindowHandle, NewParent )

Arguments:

Integer, integer.
WindowHandle is the handle of the window to change.
NewParent is the handle of the window to make the parent

Returns:

Void.

Examples:

Director:
baSetParent( 2459 , baStageHandle() ) -- make a window a child of the stage

Authorware:
baSetParent( 2459 , 5623 )

Notes:

Not all programs like having their windows made a child of another program.


baWinHandle

WinHandle

Description:

baWinHandle returns the main Director window or the Authorware presentation window.

Platforms:

Windows and Macintosh

Usage:

Result = baWinHandle()

Arguments:

None.

Returns:

Integer.
Returns the handle of the window.

Examples:

Director:
Win = baWinHandle()

Authorware:
Win := baWinHandle()

Notes:

Use this function to get the Director window for use with the other window manipulation functions.

See also:

baStageHandle


baStageHandle

StageHandle

Description:

baStageHandle returns the Director stage window.

Platforms:

Windows

Usage:

Result = baStageHandle( )

Arguments:

None.

Returns:

Integer.

Examples:

Director:
Win = baStageHandle( )

Authorware:
Win := baStageHandle( )

Notes:

Use this function to get the Director stage window. You should use baWinHandle if you want to use the other Buddy window manipulation functions on the Director window.

If used in Authorware, this function will return the main presentation window.

See also:

baWinHandle


Registration functions

baAbout | shows information about Buddy API
baRegister | registers Buddy API
baSaveRegistration | saves your registration information
baGetRegistration | retrieves your registration information
baFunctions | retrieves the number of functions you are licenced to use
baUsedFunctions | returns a list of all the functions you have called


baAbout

About

Description:

baAbout shows information about Buddy API.

Platforms:

Windows and Macintosh

Usage:

baAbout()

Arguments:

None.

Returns:

Void.

Examples:

Director:
baAbout()

Authorware:
baAbout()

Notes:

This function displays a message box showing the version of Buddy API, who the version is registered to, and the number of functions licenced for use.


baRegister

Register

Description:

baRegister registers Buddy API.

Platforms:

Windows and Macintosh

Usage:

Result = baRegister( UserName, RegNumber )

Arguments:

String, integer.
UserName is the user name you received when you registered.
RegNumber is your registration number.

Returns:

Integer.
Returns the number of functions licenced for use.

Examples:

Director:
funcs = baRegister( "My name" , 111111 )

Authorware:
funcs := baRegister( "My name" , 111111 )

Notes:

You need to use this function before you call any other Buddy functions. For Director, the best place to do this is in your startMovie handler. In Authorware, place this into a calculation icon near the start of the flowline.


baSaveRegistration

SaveRegistration

Description:

baSaveRegistration saves your Buddy API registration information.

Platforms:

Windows and Macintosh

Usage:

Result = baSaveRegistration( UserName , RegNumber )

Arguments:

String, integer.
UserName is the user name you received when you registered.
RegNumber is your registration number.

Returns:

Integer.
Returns 1 if successfully saved, else 0.

Examples:

Director:
OK = baSaveRegistration( "My name" , 111111 )

Authorware:
OK := baSaveRegistration( "My name" , 111111 )

Notes:

This function is designed to be used with the baGetRegistration function to make it easier for you to enter your registration code. In Director, you can use the Message window to save the information.

The function is only available in authoring mode.

See also:

baGetRegistration


baGetRegistration

GetRegistration

Description:

baGetRegistration retrieves your Buddy API registration information.

Platforms:

Windows and Macintosh

Usage:

Result = baGetRegistration( )

Arguments:

None.

Returns:

String.
Returns your registration information.

Examples:

Director:
regstring = baGetRegistration( )

Authorware:
regstring := baGetRegistration( )

Notes:

This function is designed to be used with the baSaveRegistration function to make it easier for you to enter your registration code. In Director, you can use the Message window to get the information.

The function is only available in authoring mode.

See also:

baSaveRegistration


baFunctions

Functions

Description:

baFunctions returns the number of functions you are licenced to use.

Platforms:

Windows and Macintosh

Usage:

Result = baFunctions( )

Arguments:

None.

Returns:

Integer.
Returns the number of licenced functions.

Examples:

Director:
number = baFunctions( )

Authorware:
number := baFunctions( )

See also:

baRegister


baUsedFunctions

UsedFunctions

Description:

baUsedFunctions returns a list of the Buddy functions you have used.

Platforms:

Windows and Macintosh

Usage:

Result = baUsedFunctions( )

Arguments:

None.

Returns:

List.

Examples:

Director:
used = baUsedFunctions( )

Authorware:
used := baUsedFunctions( )

Notes:

Only the functions that you have actually called in the application will be returned.


baDeletePMIcon

DeletePMIcon

Description:

baDeletePMIcon deletes a Program Manager or Start Menu icon.

Platforms:

Windows

Usage:

Result = baDeletePMIcon( Icon )

Arguments:

String.
Icon is the name of the icon to delete.

Returns:

Integer.
Returns 1 if successful, else 0.

Examples:

Director:
OK = baDeletePMIcon( "Multimedia Terms" )

Authorware:
OK := baDeletePMIcon( "Multimedia Terms" )

Notes:

The icon will be deleted from the active Program Manager group. To ensure that the group you want to delete the icon from is active, you should always call baCreatePMGroup before you use this function (even if the group already exists). This will make the group the active one. If you are deleting multiple icons, you only need to make one call to baCreatePMGroup before you start deleting.

See also:

baCreatePMGroup
baDeletePMGroup
baPMGroupList
baPMSubGroupList
baCreatePMIcon
baPMIconList


baWriteRegString

WriteRegString

Description:

baWriteRegString writes a string into the Windows Registry.

Platforms:

Windows

Usage:

Result = baWriteRegString( KeyName, ValueName, Data, Branch )

Arguments:

String, string, string, string.
KeyName is the name of the key.
ValueName is the name of the value.
Data is the string to write into the registry.
Branch is the branch of the registry to use. Can be one of the following:
"HKEY_CLASSES_ROOT"
"HKEY_CURRENT_USER"
"HKEY_LOCAL_MACHINE"
"HKEY_USERS"
"HKEY_CURRENT_USER"
"HKEY_DYN_DATA"

Returns:

Integer.
Returns 1 if the function is successful, otherwise 0.

Examples:

Director:
OK = baWriteRegString( "Courses\Computers\101", "CurrentUser", "Gary Smith" , "HKEY_CLASSES_ROOT" )

Authorware:
OK := baWriteRegString( "Courses\\Computers\\101", "CurrentUser", "Gary Smith" , "HKEY_CLASSES_ROOT" )

Notes:

A Registry entry consists of keys and sub-keys, similar to the directories and sub-directories in the Windows file system. 32 bit Windows adds Values to the registry. These can be thought of as files within the key. These Values are not available under 16 bit - the ValueName argument is ignored.

To set the (Default) value of a key use an empty string for the ValueName argument.

See also:

baReadRegString
baReadRegNumber
baWriteRegNumber
baReadRegBinary
baWriteRegBinary
baReadRegMulti
baWriteRegMulti
baDeleteReg
baRegKeyList
baRegValueList