Introduction

 Top Next

Make your Flash™ animations stand alone! Convert your SWF files to projector executables or screen savers with SWiSH Studio in three easy steps, you can even burn them directly to an autorun CD. With SWiSH Studio you'll be producing dynamic standalone animations within minutes.

SWiSH Studio converts any animation in the .swf file format used by Macromedia Flash™. According to a recent survey by NPD Research, Flash is used by over 97% of web users!

With SWiSH Studio you can:

· Create projector executables
· Create screen savers
· Control the window style and behavior of your publication
· Use and create customizable skins for your exes
· Make transparent (windowless) publications
· Mouse event handling and customizable menus
· Publish animations to EXE or SCR files, or burn directly to autorun CD-ROM or DVD.
· FSCommand support

Minimum system requirements:

· Windows 98/ME/NT4/2000/XP
· Pentium 100
· 32Mb of RAM
· 800x600 pixels by 256 color display
· SWiSH Studio requires the Macromedia Flash™ player to be installed in your browser to preview the output.

Special thanks go to the SWiSHzone team for all their help.


Conventions

 Top Previous Next

Conventions used in this manual

Throughout this manual we refer to Menu selection options in the following format - Edit | Copy (Ctrl+C). This means to select the main title bar 'Edit' Menu and from within it, the 'Copy' option. An equivalent quick key sequence is performed by pressing the Control key (Ctrl) and the C key together.


Definitions

Definitions

General definitions are shown in the table below. More complex technical definitions are shown as child topics of this topic.

Image file | Imported .swi, .wmf, .emf, .gif, .jpg, .bmp, .png images or movies.
.html file | A HyperText Markup Language file. This file format is the most commonly used web page definition language
.swf file | SWF is a file format used by Macromedia to deliver graphics, animation and sound over the Internet. SWF files are much like .gif files in that they will play in most browsers without installing a plugin. SWF is pronounced "swiff".
.sws file | This is a SWiSH Studio native document file.
.sss file | This is a SWiSH Studio skin file.
FSCommand | An action called from within a Flash script that satisfies the Macromedia Flash FSCommand usage guidelines.
Projector | An executable file that runs one or more embedded source files. These source files are typically SWF files, but may be any of a variety of image or movie file types.
Sprite | A SWiSHscript sub movie or movie clip. Similar to a Flash Movie Clip. If you own SWiSH Max, see the SWiSH Max help file for more information.
Movie Clip | A sub movie. Similar to a SWiSH "Sprite".
Autorun CD | A CD that automatically launches a specific application when inserted in a machine's CD drive.


Database Field

This corresponds to a column in a database table. The FS Commands for ODBC Databases allow fields to be specified via name or number. If specified by number, the first field is 0.


Database Record

Each record corresponds to a row of the database table. A record may contain one or more fields.


Dependent Files

A Play List Item that makes reference to another file (possibly via a FS Command) must have that referenced file included as a dependent file via the Dependencies Palette (F9).

Studio packs all referenced files as well as required support files into the created projector or screen saver. When the projector or screen saver is run, the included Play List Items and dependent files are unpacked into the temporary sub folder then loaded by the projector as required.

Unlike the Play List Items, dependent files are not renamed when they are unpacked.


ODBC

Open Data Base Connectivity specification.

This specification allows database vendors to provide a consistant interface into their databases.

To configure a ODBC data source, you must be logged in as an administrator on NT, Win2000 and XP systems.

ODBC data sources are configured via Control Panel / Administrative Tools / Data Sources.

The Microsoft MSDN internet pages contain information about using the Microsoft ODBC Data Source Administrator.

ODBC databases can be accessed via the FS Comands defined here.


Play List Items

These are the files that have been added to your document using the Select tab. These items constitute the files that are played by the projector or screen saver.

SWiSH Studio packs all referenced files as well as required support files into the published projector or screen saver.

When the projector or screen saver is run, the included Play List items are unpacked into the temporary sub folder then loaded by the projector as required.

Should a Play List item require access to another file, then that file should be included with the Dependent Files via the Dependencies Palette.

Note: Play List items are renamed when unpacking to avoid possible conflicts with identically named files from different source folders. Consequently a Play List item cannot reference another Play List item, unless it is seperately included with the Dependent Files via the Dependencies Palette.


Play Time

This is the amount of time that SWiSH Studio will play the item before moving to the next item. If the Play Time is set too short, the full movie will not be displayed before moving to the next item in the play list.

When a .swf file is loaded into SWiSH Studio, its play time is based on the information contained in the header of the .swf file.

Unfortunately this information can be incorrect if the .swf file contains a number of sprites or other scripting that causes it to loop.

It is possible to override the default play time by clicking on the selected row's Play Time field and entering a new value.

Non .swf files (eg. .jpeg, .html) that are included in the play list, have initial Play Times set according to system defaults that can be altered via Tools Menu / Options.


Publication

A publication is a file produced in the Publish tab - it can either be a projector (.exe) file or a screen saver (.scr) file.


Recordset

The result of a database query.

A recordset contains one or more records.


SQL

Structured Query Language - a database query and manipulation language.

The Microsoft SQL server database is based on "Transact SQL". Reference documentation for that language can be found on the web at Transact -SQL overview.

The main SQL commands that a user should be familiar with are select, update, insert and delete.


Temporary Folder

This is a defined folder that the system uses to store temporary files.

For NT, Win2000 and XP this folder is typically:

C:\Documents and Settings\<user>\Local Settings\Temp

Where <user> is the current user account name.


Credits

The SWiSHzone Team

Many hours of labor and love have gone into bringing you SWiSH Studio. Thanks go to the following: Damien Skracic, Jon Herron, Hugh Boyd and the rest of the SWiSHzone team.

This Help File was made with EC Software Help & Manual.

The SWiSH Studio installer was created using MindVision Installer VISE.

© Copyright SWiSHzone.com Pty Ltd 2006.

Help Manual Release 1.00 (Tuesday, 22 August 2006).


Purchasing and Licensing

Most SWiSHzone.com products are protected from piracy by a software licensing system.

Depending on the product, a free trial period is normally allowed. The trial period (if enabled) will give you sufficient time to fully evaluate the terrific value of our products.

To activate your free trial, you will need to obtain a trial Site Key. See the Trial License section for more information.

You can purchase the product before or after the trial period has expired, but once the trial period has expired you will no longer be able to use this product on your computer on a trial basis.

To purchase the product, see the Registration section for more information.

SWiSHzone.com works hard to produce reasonably priced software. In addition to our reasonable prices, there are additional discount options for network-license versions and educational users. Look for details at www.swishzone.com or contact Sales and explain your requirements. There is sure to be a solution to suit your needs.

Please refer to the following sections for assistance:

· Register gives detailed instructions on how to access the Unlock web page. From that page it is possible to purchase and / or obtain Site Keys. An overview of the purchasing and licensing options is presented on our purchase pages.
· Licensing notice explains how to get information on your license and our licensing policy
· Network License can be used if you want to run your SWiSHzone.com product over a network (some products do not offer this facility).

Finally, we have a list of the most frequently asked questions on licensing and the protection system.


Frequently Asked Questions

How do I install on a NT / Windows 2000 or XP system so that the program is available to all users?

See the section Multi User use on XP / Win2000 / NT. Note some products may not support all these operating systems.

How do I update my software?

If an update for the program is available for download or on CD, follow the instructions supplied.

In all cases, please run the installer. Do not copy SZP .exe's directly between machines as this may cause incomplete copies or other errors.

I used to work on two computers (home and office). Can I install my software on both computers?

You are entitled to a License for home and office. Follow the instructions in the Register section to generate a second Site Key for your software. This policy does not apply when a multi user network license has been purchased.

Can I just copy my SWiSHzone program to another computer?

No. The copy protection software will prevent the second copy from working. You can however register two copies according to our home and office policy described above. Run the installation program on the second computer then follow the instructions in the Register section of this document.

Can I run my single user license copy on a network drive?

Yes. However each machine that references the installed program will require a local installation (possibly to the same network drive) and a local license.

What happens to the protection software when my computer HDD crashes and is replaced by a new one?

Follow the instructions in the Register section.

Is a Site key required during the free trial period?

Yes, Follow the instructions in the Trial License section.

What is my Site Code?

See Site Code.

What is my Site Key?

See Site Key.

How can I obtain a Site Key?

Go to the unlock page. This page can be accessed via the "Get Free Trial Key" or "Register" buttons of the 'Unlock' window.

I received the Site Key, but I can not see the difference between the number 0 and the letter O.

Because of the length of the Site Key, we recommend that cut and paste be used to transfer the site key.

Why can't I use the same Site Key multiple times?

The Site Code generated during the installation of the software depends on the computer. A new Site Code is generated if you install the software on another computer. Consequently, you cannot use the same Site Key for another computer. It is the Site Key that permits starting and using the application after the trial period.

For some reason I need to re-install my software. What happens with the Site Key?

If needed, go to the unlock page. This page can be accessed via the "Try" or "Unlock" buttons of the 'Unlock' window.

I want to license a machine that is not connected to the internet?

Paste the Site Code displayed in the 'Unlock' window to a text file and transfer that file to a computer that is connected to the internet. Access the Unlock web page and use the Site Code from the text file. Paste the resulting Site Key back into the text file and transfer back to the original computer.

I still need help...

If your questions are not answered here, contact your dealer or connect to the internet and use the "Try" or "Unlock" button to access the unlock page. From this web page, follow the Help link.

Please include the following information if available.

· The email address that you used to register your SWiSHzone.com product.
· World pay reciept ID number.
· Operating system e.g. 95 / 98 / ME / NT / Win2k / XP

Please also state:

· If you have previously un-installed your SWiSHzone.com product.
· Anything unusual about your system, huge disks, dual processors etc.


Trial License

A trial License allows the user to evaluate the SWiSHzone.com product for a limited time. Typically, the evaluation period will be for 15 days or 45 invocations (which ever occurs first).

Note: Some SWiSHzone products do not come with a Free Trial Period. See here for more information.

If you are already using a trial license and would like to find out about obtaining an unlimited license, see Registration for more information.

When first installed, the product will be unlicensed. (See No License).

To obtain a trial license, connect to the internet and press the "Try" button. This will activate a web page to obtain a trial Site Key that is matched to your Site Code.

Please read the Notes section for important information about when the trial commences, activation time and issues relating to multi user use on NT / Windows2000 / XP machines.

Pasting a valid Site Key into the edit box will cause the Site Key OK dialog to be displayed. Pressing Continue will activate the product.

While using a trial license, a 'Unlock' window will be displayed during startup. This window allows displays the current trial license status and gives opportunity to purchase and register the product. See Registration for more information.

Note: See the section Multi User use on XP / Win2000 / NT if you are installing on one of those operating systems and require multiple users to have access to the program. Although the trial can only be used by the person who installed it, it should be installed by an administrator account if you require multi user access in the future.


Notes

· Some SWiSHzone.com products are not available for trial use. See here for more information.
· Only 1 Trial Key will be issued to each computer. Support will NOT issue replacement trial keys.
· The trial period commences when the Site Key is first activated (pasted into the Site Key edit box).
· The available invocations will only decrement if the SZP is used. Pressing the cancel (x) button of the Unlock Window will allow viewing of license status without running the SZP and subsequent decrement of the available invocations.
· The Trial Site Key should be activated within 2 days. There is a timeout period, after which the site key will become invalid.
· Ensure that the date on your computer system is set to the correct date when activating the site key. Dates set in the future or in the past will invalidate the site key.
· When installed on a NT / Windows2000 / XP system, only the user that installs the SZP will be licensed to trial it. Other users attempting to run the installed product on the same computer using a different login will receive a status number 1011 indicating that the product is unlicensed. This WILL INVALIDATE the Trial Key for ALL users. (This limitation only applies to trial licenses, not Unlimited Site Keys.)
· See the first note above. Trial Keys will not be re-issued because of failure to follow the above suggestions.


Products Without Free Trial

Some SWiSHzone.com products do not come with a free trial period.

The Product Splash Image will indicate if a free trial period is available for the product you are using. If a trial is not available, the "Try" button will not be visible.

The following SWiSHzone products do not have a free trial period:

· SWiSHsites
· SWiSHlite (Discontinued Product)
· SWiSHv2 (Discontinued Product)
· SWiSHpowerFx (Discontinued Product)
· Non English versions of SWiSHmax.

Note that while discontinued products are still available for download to licensed customers, they are unavailable for purchase or trial.


No License

After installing the product, one of the following windows will be displayed if no previous license was found.

This window above indicates that a trial license is allowed for the product.

To obtain your trial license you will need to:

· Connect to the internet.
· Activate the unlock web page via the "Try" button.
· Paste the Site Key that was obtained from the web page into the Site Key Edit Box.

The window above indicates that a trial license is not available for the product.

If you have already purchased the product, you can unlock the product by pressing the "Unlock" button.

Once you have recieved your Site Key, use copy and paste commands to Paste it into the Site Key Edit Box.

If you have not purchased the product, you can access our web based purchase pages by pressing the "Buy" button.


Paste Unlock Key

Once a Site Key has been copied to the clipboard, Button B1 will change to a "Paste Key" button.

The Site Key can be pasted by pressing the "Paste Key" button or using standard paste procedure so that the Site Key is pasted into the "Site Key Edit Box".


Site Key OK

If the Site Key is valid, the following window will be displayed:

Press OK to remove the Congratulations dialog. The appliation will then start.

On subsequent invociations, press the Continue button to use the application.


Trial has ended

After the trial has ended the Unlock Window will appear as shown below.

Note that the Get Free Trial / Continue button is missing (no longer entitled to free trial).

To continue using the SZP, use the "Buy" button to purchase then obtain an Unlimited Site Key using the "Unlock" button.


Licensing Notice

Unless registered, the Product will cease to function after the trial period indicated on the start-up splash screen. No data is lost or destroyed when the trial period expires. Licensed (Registered) users can unlock their software on a permanent basis anytime during or after the trial period. Detailed information on unlocking the product can be found in this manual.

The 'Unlock' window CANNOT be accessed while the Product is in use. The 'Unlock' window will be displayed each time the product starts if using a Trial License. The 'Unlock' window will also be displayed if the license has expired or been made invalid for some reason.

The CD-ROM or download installers DO NOT self-destruct after the application is installed. They can be used to install the Product on an infinite number of PCs. However each PC will require either a trial or unlimited license to run. We encourage potential customers to install the product on multiple PCs for evaluation purposes. Keep in mind, however, that you must purchase a license for each PC you wish to run the Product on a permanent basis.

Variations from the aforementioned policy will be at the sole discretion of SWiSHzone.com Pty. Ltd.


Registration

To remove the time or runs limitation of the trial license, or to re-activate the product once the trial period has expired, it is necessary to purchase an unlimited license and install an Unlimited Site Key.

When the product runs using a trial license, the dialog in the Start up with trial license section is displayed. This dialog allows the user to see the current license status.

You can access the purchase pages using the "Buy" button. Once you have purchased a license, that license will be associated with your email address. Using your email address, you can then generate an Unlimited Site Key which will permanently enable the product.

To purchase the product, use the "Buy" button to access our web based shopping pages.

To Unlock the product, use the "Unlock" button to obtain an Unlimited Site Key. This can also be used to re-license the product after some error.

See the Register section for more information.

Note: See the section Multi User use on XP / Win2000 / NT if you are installing on one of those operating systems and require multiple users to have access to the program.


Start up with trial license

While running with a trial key, the following dialog will be displayed each time the product starts. Press the Continue button to use the application.

The dialog also shows the time and runs remaining on the trial license.

To purchase an unlimited license, connect to the web and press the Register button.


Unlock

Press the "Unlock" button of the 'Unlock' window to open a browser window that attempts to connect to the Unlock web page. This will also re-enable the Site Key Edit Box allowing a new site key to be pasted.

If connection is successful, the page will request the Site Code and the registered email address.

If you accessed the unlock page via the "Unlock" button, your current site code should have been automatically entered into the unlock page. This can be ammended if necessary.

If the registered user owns a valid license, a site key will be created and emailed to the registered email address.


Notes

When using NT / Windows2000 / XP, installation of the SZP and subsequent activation of the Unlimited Site Key by an administrator account will allow all uses of the system to use the SZP on that computer.

Installation and activation of the SZP by non adminsitrator accounts is possible. However, the license will only be useable by that user.

Upgrading the operating system, changing hardware or reformatting disk drives may cause a previously licensed system to become unlicensed. Follow the procedure in Register to obtain a new key.


Problems

If you encounter problems during the licensing / unlock process, connect to the web and press the "Try" or "Unlock" buttons to access the unlock page. From this web page, follow the Help link.

This is the preferred method of accessing the help page as it will transfer important information about your Site code and error number to our support staff.

Alternatively, you can contact our support staff via http://support.swishzone.com/support.asp


Network License

SWiSHloc supports network licenses.

This type of licensing requires a network server which should be running NT, Windows2000 or XP.

Client machines can run 95, 98, NT, Windows2000 or XP.

The network must support TCP/IP.

This type of setup is normally very attractive for large office or teaching institutions as the site key used by each of the client machines is identical.

The cost of a network license is identical to the equivalent number of single user licenses. Volume discounts still apply.

Detailed installation instructions and various network tools are included with the network installation package.

Because of the general complexity in setting up network solutions, the network installation package is not available automatically from our web site. Please contact Support with your requirements.

After analysing your requirements, If a network solution sounds like a useful solution, we will send you the network installation package.

Network licenses will not be supplied for sites with less than 5 seats (licensed users).


Multi User use on XP / Win2000 / NT

SWiSHzone.com products can be installed on a NT/Win2000/XP so that they are available to all logins. Note this only applies to full (non trial) unlock keys, and some products do not install on (some of) these operating systems. A trial key is only available to the user who first unlocked the program.

To allow all users access to the program, the following steps must be followed:

1. The original installation and unlock must be done by an administrator account.

2. The install directory must be shared so that other users can read the files. (Write permission is not required). Individual users must not refer to their own installed area as this will cause problems when installing updates.

If a user that did not have administrator privileges originally installed the application, please contact support for more information.


SWiSHloc

SWiSHloc is the copy protection system used to protect a number of SWiSHzone Products.


SWiSHzone Product

SWiSHzone.com produces a number of products.

For the purposes of this document, a SWiSHzone Product (sometimes referred to as SZP) is any product that uses the SWiSHloc method of copy protection.


Registered Email Address

The Registered Email Address is the email address that was used when a Registered User purchases the product.

The registered email address is used to track registered users on our database. The registered email address is also used to determine license ownership and consequently associated Site Key generation

permissions.


Registered User

A Registered User is a user that has a valid license for the SZP. Licenses can be obtained by purchasing the product.

A registered user with a valid license can visit the Unlock web page to obtain an Unlimited Site Key that will allow them to unlock their product on a permanent basis.


Site Code

A Site Code is used to identify a computer.

The Site Code is a 32 character string that is displayed in the 'Unlock' window.

An example site code is S18848NNK6189N93L22W86FTA8EJ4729

A corresponding Site Key available from our Unlock web page will unlock the application.


Site Key

A Site Key is an encrypted string that is created to match the Site Code.

The Site Key is often referred to as the "Unlock Key". It contains information about the particular type of license a user owns.

A Trial Site Key is a special key that allows timed use of the product.

Once license ownership has been verified, the program is unlocked according to the license constraints.

The Site Key is a long character string enclosed by {}.

An example Site key is

{SH44VGGR9R66TFK2WETCAWCSK7SBKZQTUS44UUWEYBNY7GK9MTMG6DJWHP

WCFF72BJMWBR3PZLMQ6C8KJ55UQN9B7A872WWS82WCMN4VJCBLBJNMTJ4X}

When pasting the Site key, include the opening and closing {}.


Site Key Activation

The process of pasting a valid Site Key into the Site Key Edit box that is displayed in the Unlock window.


Trial Site Key

A Trial Site Key is a key that is free issued to computers that are not shown as having previously been issued with a trial key.

The Trial Site Key limits program use according to both time period and invocations. (Typically 15 days / 45 invocations, which ever occurs first).

Otherwise, the program is fully functional.

See the notes section for other special requirements assocated with trial keys.


Try Button

This is button B1 of the Unlock Window. Note that this button is only visible after a fresh installation of the product.

Use this button to open the Unlock Web Page and obtain a Trial Site Key.

When this button is used to open the Unlock Web Page, your Site Code will be sent to the website eliminating the need to re-type the Site Code.

In some cases, the button may fail to function correctly because it is unable to determine the location of a default web browser.

The computer should be connected to the Web prior to pressing this button.

Note: Some SWiSHzone products do not come with a Free Trial Period. See here for more information.


Unlock Button

This is button B3 of the Unlock Window.

Use this button to open the Unlock Web Page and obtain a Unlimited Site Key.

When this button is used to open the Unlock Web Page, your Site Code will be sent to the website eliminating the need to re-type the Site Code.

In some cases, the button may fail to function correctly because it is unable to determine the location of a default web browser.

The computer should be connected to the Web prior to pressing this button.


Unlimited Site Key

An Unlimited Site Key is a Site Key that indicates that the user owns an unlimited license for the product. When this Key is entered, the trial key time / invocations limitations are removed.

Once an unlimited Site Key has been entered, the Unlock dialog will no longer appear unless some error or machine re-configuration invalidates the license.


Unlock web page

The web page http://support.swishzone.com/unlock.asp can be used to obtain Trial and Unlimited Site Keys.

This page can be accessed from the Unlock Window via the "Try" or "Unlock" buttons.

If possible, access the page using the "Try" or "Unlock" buttons as this will automatically transfer your site code to the web page.

Note that Unlimited Site Keys are only available to Registered Users and the Unlock web page will require your Registered Email Address to produce one of those Keys.


Unlock Window

This is the main SWiSHloc dialog window.

This window provides allows you to:

Unlock your SZP by pasting an appropriate Site Key into the Site Key Edit Box.

· View the current license status (If license is valid, press "Continue", button (B1) to start the SZP.)
· Obtain a Trial Site Key via the "Try" button, (B1).
· Purhcase the application via the "Buy" button, (B2).
· Obtain an Unlimited Site Key via the "Unlock" button, (B3).

If the product is using a trial license or is currently unlicensed, the Unlock window will appear each time the SZP is started.

Product Splash Image

This image identifies the product. The text indicates if a trial period is normally available for the product.

Site Key Edit Box

This Edit Box allows the pasting of Site Keys. After a valid site key has been entered, the edit box will become disabled.

Site Code

The site code for the product and your computer is displayed here.

Computers that are not connected to the internet can be licensed by transferring the Site Code (use cut and paste) to a text file which is then transferred to another computer that has internet access. From the internet connected computer, access the Unlock web page and obtain a Site Key using the Site Code from the text file. Paste that Site key to a text file and transfer back to the original comupter.

Status Description

The current license status:

Unlicensed, Trial License, Unlimited etc.

Status #

A code indicating the current license status. Support staff will find this number useful.

Status bar

A graphical bar that indicates the % of time / runs available with a trial license.

B1 (Try / Paste / Continue)

If the product is unlicensed and this is the first installation, the button will have the caption "Try". Press this button to access the Unlock web page to obtain your free trial key.

Note: Some SWiSHzone products do not come with a Free Trial Period. See here for more information. In this case the "Try" Button will not be visible.

If a Unlock Key has been pasted to the clipboard, the button will change to a "Paste" button, allowing the pasting of the Unlock key.

If the product is licensed, the button will have the caption "Continue". Pressing this button will start the SZP.

B2 (Buy)

Use this button to contact access our electronic store. The user should be connected to the Web before using this button.

B3 (Unlock)

Press this button to obtain an Unlimited Site Key.

Pressing this button will re-enable the Site Key Edit Box allowing a new key to be pasted.

B4 (x)

This button will allow exit without starting the SZP. If you are using a trial license, your invocation count will not be affected. Note that the time period limitation commences once you have obtained your trial site key.


Unlock Key

This is another name for Site Key.


Getting Started

SWiSH Studio allows you to convert your Flash animations into standalone projector executables or screen savers in three easy steps.

When you first launch SWiSH Studio you will see the Select page shown below.

This page lets you specify source files to be included in your presentation's play list, and is the first step of a simple three step process.

1. Select Play List Items.
2. Adjust Settings.
3. Publish your presentation.

Each step of the creation process corresponds to a tabbed page.

Each item in the play list will play in turn after it's Play Time has expired.

Once you are happy with your presentation and have published it, you can save your settings by saving the current document. The document is saved in the proprietary SWS format. You can start a new document or load a previously created document at any time.

If you wish your final publication to have the same name as the first imported play list file, simply check the Set document name based on first file loaded option and make sure that the play list is empty.

Audio playback

You may also choose to play an audio file throughout the final presentation. To do so check the Audio checkbox and click on the Select button. The following dialog will pop up.

You may choose files of type: .MP3, .MID, .AU, .WAV. Inside the dialog, you may choose to audition any audio file. This can be achieved in one of two ways. Either select a file and then hit the Audition button, or if you wish to audition many files, it's easier to check the Audition on selection check box. That way, every time you click on a new file, it will start playing automatically.

Once selected (and the dialog dismissed), the file may be played at any time by clicking the Test button (to stop play, uncheck the Audio checkbox).

If you check the Loop checkbox, then when the audio file has finished playing it will start playing again from the beginning.

Users familiar with SWiSH Studio can also take advantage of its single click operation.


Help Banner

First time users may wish to activate a help banner by pressing the Show/Hide help banner button on the toolbar.

This will bring up a window at the top of each tab which explains its basic purpose. For example:

Users familiar with SWiSH Studio will probably want to hide the help banner to put their screen space to better use.


Select Tab

The first step in the creation process is to select some Play List Items for your presentation.

The Select tab allows you to browse, load and view Play List items to be added to your document. Selected Play List items are shown in the list control, along with details such as their play time, size, dimension, location and number of frames. The last selected Play List item is automatically played in the preview window.

Multiple Play List items can be added to the project. If more than one Play List item is present, then the publication will play each item one after the other. Each play list item will play for the time displayed in the Play Time field.

Play List items can be added to the project by pressing the Select Play file(s) button, or by dragging them from other Windows applications such as Explorer and dropping them anywhere within the SWiSH Studio main window.

Play List items will typically be Macromedia Flash™ SWF files, but the following file types can all be included in your presentation:

· Flash files (.swf)
· Jpeg images (.jpg, .jpeg)
· Bitmap images (.bmp)
· PNG images (.png)
· TIFF images (.tif)
· WMF files (.wmf)
· EMF files (.emf)
· Icon files (.ico)
· HTML files (.htm, .html)

Note: Should a Play List item require access other files, then those files must be included as Dependent Files via the Dependencies Palette.

Dragging and dropping a file onto the SWiSH Studio desktop shortcut will launch SWiSH Studio using that file as the first imported Play List item. Play List items can also be passed as parameters when launching SWiSH Studio from the command line, or passed as arguments when SWiSH Studio is invoked by an external application.

The following operations are available on the main select page:

Set document name based on first file loaded

If this option is checked, then the document name will automatically be set based on the name of the first Play List item loaded. This can save you some typing if you wish that the publication has the same name as the first entered Play List item.

Select Play file(s)

Launch the Select Play List Items browser to add Play List items.

Remove selected play list item(s)

Remove selected items from the Play List. Multiple items can be selected at once by holding down the shift or control key while clicking.

Pressing the delete key has the same effect as pressing this button.

Move selected item up/down

Move a single highlighted item in the Play List up/down one position.

You can also use the mouse to drag a highlighted item to a new position in the list.

Play all items in the play list

Play all items in the Play List, one after the other, in the preview window.

Refresh play list files

Reload all files in the Play List from disk. This operation is useful if the files have been externally modified since they were loaded into SWiSH Studio.

Mute sound in preview

Check this box to remove sound from the file being played in the preview window. This option does not affect the final publication.

Audio

Check this option if you wish to add an external music file to your presentation.

Test

Plays the currently selected audio file.

Loop

Instructs the presentation to replay the music file after it has finished playing in the presentation.

Select

Allows you select a music file for play during a presentation. The following music file formats are supported:

.MP3, .AU, .WAV, .MIDI


File Browser

The graphical file browser allows you to select any supported graphics file to be added to your presentation's play list. The resizable browser supports a picture thumbnail view and a list view. There are also modes to sort files in alphabetical order, reverse alphabetical, from newest to oldest and from oldest to newest (based on file modification times).

When a thumbnail is selected, it will automatically appear in the preview window (if showing). The preview window may be detached from the main dialog by click-dragging on the ribbed upper section of the window. Once detached, it may be resized so that you can obtain a more detailed view of the selected image file.

The preview may be docked back into the main dialog by moving it over the top part of the folder tree window. When you're in the docking region, the title bar of the preview window will start flashing and the word "DOCK" will appear in the title bar. Simply release the mouse button and the window will attach itself to the main browser dialog.

Note: you can enlarge the size of the folder tree window by repositioning it's rightmost edge (and moving it to the right or left). Similarly, the top edge may be moved up or down.

Play List Items will typically be Macromedia Flash™ SWF files, but any of the following file types can be specified:

The files you select will typically be Macromedia Flash™ SWF files, however any of the following file types can be used (to create a slide-show type presentation):

· Flash files (.swf)
· Jpeg images (.jpg, .jpeg)
· Bitmap images (.bmp)
· PNG images (.png)
· TIFF images (.tif)
· WMF files (.wmf)
· EMF files (.emf)
· Icon files (.ico)
· HTML files (.htm, .html)
· All files (*.*)

Multiple items can be selected at once by holding down the shift or control key while clicking. Press the Select button to select the highlighted files and add them to the SWiSH Studio Play List.

select-browser-11 Recent Folders

This drop-down box contains the folder locations that you have visited and made selections from. They are listed in order of access, most recent first. This is a handy short-cut to navigate to commonly used folders.

select-browser-2 Up One Level

Press this button to move up one level in the folder tree.

select-browser-3 Create New Folder

Press this button to create a new sub-folder in the currently selected folder and edit it's name.

select-browser-4 Thumbnail View

Pressing this mode button will cause the dialog to display files as thumbnails.

select-browser-5 List View

Pressing this mode button will cause the dialog to display files as in list form.

select-browser-6 Delete File

Press this button to delete selected file(s). Holding the Shift key down and the same time will cause the file(s) to be deleted permanently.

select-browser-7 Sort A to Z

When pressed, the files will be displayed in alphabetical order.

select-browser-8 Sort Z to A

When pressed, the files will be displayed in reverse alphabetical order.

select-browser-9 Newest First

When pressed, the files will be displayed from newest to oldest (based on file modification times).

select-browser-10 Oldest First

When pressed, the files will be displayed from oldest to newest (based on file modification times).


Settings Tab

The second step in the creation process is to customize the look and feel of your presentation.

The user has control over most aspects of the resulting presentation through a number of settings. The Settings tab contains seven main categories of settings as described below.

Page

Category

Description
· Page 1

Window Style

Set the publication's window style.
· Page 2

Window Skin

Set the projector publication look from a skin file.
· Page 3

Size and Position

Set the size and position at which the publication launches.
· Page 4

Mouse and Keyboard

Set the behavior of mouse and keyboard interaction.
· Page 5

Playback Control

Set various aspects of playback control and expiry details.
· Page 6

Menus and About

Set contents of context menus and the About box.
· Page 7

Product Description

Set the product description details.
· Page 8

CD/DVD Preloader

Select an image or SWF file to be displayed while the main movie loads off CD/DVD.
· Page 9

Watermark

Set watermark logo and/or text.
· Page 10

Security

Apply Activation and Expiration options.


Window Style

This group of settings relates to the window style of your final publication.

Title Bar

Specify the Caption and optionally an Icon for your publication. These will not be visible on borderless publications (except when showing in taskbar).

Refresh

Reloads the selected icon image. Use this if the selected icon has changed.

Shape

Specify your publication's window shape. This may be:

Rectangle

A standard rectangular window.

Clip to shape

Choose the window shape from the following list of predefined shapes:

Bitmap

Specify the window shape based on an image.

Press the Browse button to load an image. Specify a Transparent color (by clicking on preview) and Tolerance range. This color (range) will be subtracted from the image, leaving what's left as a window mask. Press Build button to create the window mask. When published, content will be displayed in the masked region.

Background

Determines how the publication's background will be treated.

No Color

Window background color is not set. The color is determined by playing content.

Set Color

Window background color is set to the color showing in the color swatch (click on swatch to change).

Transparent

Produces a windowless publication. The background will be whatever the Desktop happens to be at any given time (see below).

Note: Transparent output can be compute intensive. For best performance, observe the following guidelines:

1) A fast machine always helps!

2) 32 bit system color mode is approx. 25% faster than non-32 bit color (8 bit color not supported).

3) The smaller the exe (movie) dimensions, the faster it will run with less CPU load.

4) The slower the SWF frame rate, the less the CPU burden.

Transparency is not supported under Win98/Me.

Trim outside

Select this option if you wish to trim the viewable area of the presentation. The effect is to clip all elements that lie outside the movie area. This can be useful when displaying publications in fullscreen mode and whose aspect ratio does not match your display monitor. The clipped region is painted with the selected color.

Note: This option does not work with the Transparent background option or with window skins.

Match bkgnd

Set this option to make the clipped region color the same as the color selected with the Set Color option. If checked, the two color swatches are linked and you can only make new color selections via the Set Color swatch.

Border

None

Removes the window border and titlebar from your publication, though it will still have a background.

Resizable

The publication will retain its border and titlebar. You can also choose various window titlebar options:

Maximize button

Disables the Maximize toolbar button.

Minimize button

Disables the Minimize toolbar button.

System menu

Removes all buttons and menus from the toolbar.

Disable resizing

Prevents the publication window from being resized.

General

General window attributes include:

Show in task bar

Publication will show in the task bar area.

Show in system tray

Publication will show in the system tray area. Right click in tray to display context menu to exit.

Close to system tray

When a publication is closed via the system Cancel toolbar button or via the system Close menu option, the publication will disappear from the task bar and will only be shown in the system tray (and will continue to execute). To reactivate the publication from the system tray simply left click on the icon. If you right click on the tray icon, a context menu will be displayed from which you can exit the application. The publication may also be exited if it is showing and you select Exit from the context menu defined in Menus and About.

Always on top

Publication will always be displayed on top of all other windows.

Minimize all windows on start

When the publication starts, all currently open windows will be minimized, exposing the desktop.

Restore min windows on exit

If the option to minimize all windows on startup was selected, then when the publication ends, all previously minimized windows will be restored to their original settings.


Window Skin

This group of settings are used to specify the look-and-feel of your projector publication.

Apply Skin

Check this option to apply the skin displayed in the preview. Note, this checkbox may not always be enabled, depending on your settings in the Window Style page, as some of those options may preclude the publication from displaying a window frame.

Skin

Browse

Select a new (.sss) skin file.

Refresh

Used to reload the selected skin file. You may need to do this if you made changes to the skin file definition.

Preview

Displays the currently selected skin file. You may click anywhere in the preview area to bring up the skin file browser (ie, same as hitting the Browse button).

See Also: Skin file definition


Size and Position

This group of settings controls the size and position at which your publication starts.

Note: Window size and position options are ignored when .scr is being created.

Window Size

Specifies the size of your publication when it first launches.

Same as first play list item

The same size as the first file in the play list. The size of this item (in pixels) is shown in the source file list in the Select tab.

Custom width x height pixels

Specify a size that suits you.

Desktop percent

Size is based as a percentage of total desktop size (which may include dual monitors).

Full screen

Set the publication size to match the full size of the desktop (which may include dual monitors).

Window Position

Specifies the position at which your publication will first launch.

Target monitor

Select which display(s) will be used as a reference for all alignments. Choices include:

Primary Monitor | - your primary display.
Secondary Monitor | - on dual monitor systems, this refers to your second display.
Dual Monitors | - on dual monitor systems, both displays will be used (ie, the sum area of both).

If a system only has a single monitor and you select Secondary Monitor or Dual Monitors, then all alignments will default to the primary monitor.

Align to desktop region

Check this option if you wish to align your projector executable to the target monitor using one of nine predefined regions. Choose the location by clicking on the desktop graphic.

If this option is unchecked, then you will be able to specify an exact horizontal and vertical position offset as follows:

Horizontal

Pixels from left

Number of pixels that the publication's left side should be from the left boundary of the target monitor.

Pixels from right

Number of pixels that the publication's right side should be from the right boundary of the target monitor.

Vertical

Pixels from top

Number of pixels that the publication's top side should be from the top boundary of the target monitor.

Pixels from bottom

Number of pixels that the publication's bottom side should be from the bottom boundary of the target monitor.

Window State

You can specify whether your publication will start either:

Normal

Window appears at its normal size and position as defined by size and position settings.

Maximized

Window appears in the maximized state.

Minimized

Window appears in the minimized state.

Maintain aspect ratio

Specifies whether the source file window's size should be adjusted to maintain their aspect ration. Check this item if you wish the component items to look the same in your final publication as they do in their source files.

Allow content scaling

When this option is checked then the publication's content will be scaled along with the window size. If it is unchecked, then the content will remain at its original size, regardless of window size. This also applies to Transparent (windowless) modes of operation.

This mode can also be set via scripting by issuing the fscommand allowscale:

* fscommad ("allowscale", "true"); // Turns on scaling.

* fscommad ("allowscale", "false"); // Turns off scaling.


Mouse and Keyboard

This group of settings specifies how your publication should handle mouse and keyboard input from the user.

Left Mouse Button

Specifies what to do if the user presses the left mouse button on the publication.

Send to Flash

Notify the playing Flash object of a left mouse click. If you have this option selected with a borderless window, then it will not be possible to move the window. You can however define arbitrary draggable hot-spot areas inside your presentation by using the following fscommands:

DragAddRect, DragAddPoly, DragAddEllipse, DragCancel.

Drag window

Allow the user to drag the publication, but do not pass mouse click to Flash.

Drag and send to Flash

Allow the user to drag the publication and to pass mouse click to Flash.

Ignore

Ignore left mouse presses.

Right Mouse Button

Specifies what to do if the user presses the right mouse button on the publication.

Send to Flash

Notify the underlying Flash object of a right mouse click.

Show context menu

Show the publication context menu specified by the menu settings.

Drag window

Allow the user to drag the publication.

Ignore

Ignore right mouse presses.

Key Press

Specifies what to do if the user presses a key on the keyboard while the publication is in focus.

Send to Flash

Notify the underlying Flash object of the key press.

Ignore

Ignore key presses.

Exit Key

Specifies which key closes the publication. If none of the following options are checked, then no single key press will close the publication.

ESC

Pressing the escape key will close the publication. This is the first key that most users will try when attempting to close an publication.

Any

Pressing any key will close the publication.


Playback Control

This group of settings specifies basic playback options for your publication.

Playback

Specifies the basic playback behavior of your publication.

Auto play

Automatically play the publication when run.

Loop playback

Loop the publication to play repeatedly.

Note: Leave this unchecked if your publication already loops.

Play once then quit

Check this option if you wish to publication to run through its presentation once and then automatically quit.

Minimum Flash required:

Select "Any version" if you do not care which version of Flash the user has loaded on his/her system. However, if your publication content requires a minimum version of Flash in order to display correctly, you can chose a version with this control. When the publication runs, the user's Flash level will be checked and if it does not match the minimum level that you have selected, they will be so warned.

Screen Saver Behavior

Screen saver behavior can be customised as follows:

Allow mouse movement

The screen saver will continue to run even if the mouse is moved.

Allow mouse click

The screen saver will continue to run even if a mouse button is clicked.

Disable Print Screen key

While the screen saver is running, the Prt Scr key will be disabled to prevent end users from capturing the screen content.

Note, if this is the intent, then it is advisable that "allow mouse movement" and "allow mouse click" options are not checked, as the print screen override only applies when the screen saver has focus. By not checking those options, you prevent other windows from gaining focus as the screen saver will terminate.


Menus and About

This group of settings determines the content of your publication's context menu and About dialog.

Context Menu Items

The publication's context menu may be shown in response to a right click, depending on the publication's mouse and keyboard settings. You can specify the following additional items to be included in the context menu:

Always on top

Zoom In

Zoom Out

Zoom 100%

Quality

Play

Loop

Rewind

Forward

Back

Maximize

Minimize

Restore

Exit

About Box

You can customise the following items to be included in your publication's About dialog:

None

Checkbox controls whether or not the About dialog box will appear in the menu.

Product Name

This is the same field as in setting "Product Description". It is duplicate here in order to show that it will appear in the About box.

Copyright

This is the same field as in setting "Product Description". It is duplicate here in order to show that it will appear in the About box.

URL label

The label for a related URL that is shown in the About box. This will appear as an active link.

URL label - Tip

Launches an edit dialog to customize the tooltip which will appear when the cursor hovers over the link.

URL address

The URL that is accessed when the user clicks on the above link.

Email label

The label for a related email contact that is shown in the About box. This will appear as an active link.

Email label - Tip

Launches an edit dialog to customize the tooltip which will appear when the cursor hovers over the link.

Email address

The address to which an email is sent when the user clicks on the above link.

Logo

A small logo image to be included in the About dialog. Check the Logo check box and Press the Browse button to locate and load a suitable image.

Refresh

Reloads the selected image. Use this if the selected image has changed.


Product Description

Use this group of settings to edit your publication's product description details.

These details can be viewed by right clicking on the publication file in Windows Explorer and selecting the appropriate entry in the Version tab.

Product Name

Your publication's full name.

Description

A brief description of this publication.

Company

Your company's name, or the name of the company to be associated with this publication.

Copyright

The name of this publication's copyright holder and the date of copyright.

Trademarks

The name of the owner of any trademarks associated with this publication and their date.

Comments

Any relevant comments you would like to add about your publication. For instance, the publication's intended purpose, details of source files, system requirements etc.

Version

The version of your publication.


CD/DVD Preloader

This setting allows you to define a custom preloader for use with CD based auto-run publications.

As loading of content off CD/DVD can be slow, it is considered good form for the user not to wonder if anything is going on after inserting an auto-run CD/DVD. Because a preloader is generally much smaller in size than the main executable, it will load much more quickly and inform the user that 'something is happening'.

Preloader files can have any popular image format, including animated GIFs, as well as SWF files.

Note: Some operating systems have a setting which enables/disables the auto-run functionality. If your CD/DVD isn't auto-running, make sure that you have this option enabled in your system settings.

Browse

Locate a file to be used as the preloader.

Preview

This option will display the selected preloader as it will appear when loading off disk. Clicking anywhere in the displayed window will close the preview window.

Refresh

Reloads the selected preloader file. Use this if the preloader file has changed.

Clear

Removes the preloader.


Watermark

Use this group of settings to brand your publication with a logo image and/or text. The watermark(s) will appear as the topmost element in your publication. The watermark position is set according to the selected alignment.

Alignment

The alignment control is enabled if either the Watermark Image or Watermark Text option is checked. Choose where you wish your watermark(s) to appear relative to the publication's display area. If both image and text watermarks are selected, they will always appear side by side as a unit (image to the left and text to the right).

Note: The watermark image and text are not translucent. Consequently, you may want to select a small image and / or font to prevent obscuring a large proportion of the projector window.

Watermark Image

Check this box if you wish to have an image appear in your publication.

Browse

Locate an image to be used as the watermark.

Refresh

Reloads the selected image. Use this if the selected watermark image has changed.

Watermark Text

Check this box if you wish to include a watermark text box in your publication. You may enter any text in the scrollable window immediately below this control.

Color Button

Click on this button to set the text box background color.

Set Font

Click this button to select a font face, style, size, color and effects.

Justify

Select from this drop-down box how you wish your text to be positioned inside the text box.


Security

This tab allows you to specify various Expiry and Activation options.

Secure access

Check this box to set an expire period for your publication. The controls are disabled unless this box is checked. If enabled, the content can be viewed without activation until the defined expiry date.

Expire

You can nominate your publication to expire:

After n days from install

The publication will stop running and display the expiry message (if any) n days after it is installed. Use 0 to force the requirement of activation before use. (ie. no trial period).

After n days from today

The publication will stop running and display the expiry message (if any) n days from today.

On date

The publication will stop running and display the expiry message (if any) on the specified date.

Activation

Cannot activate

Use this option when you want your presentation to timeout after a set period. This may be useful if you intend to supply updates on a regular basis and want the existing content to become unavailable after the next version is available.

Password only

This method of activation allows the presentation to be played once the correct password is entered. Although this method is easiest to administer, there is no protection against one of the users publishing or re-distributing the password.

User Messages

Different messages can be displayed during the trial or when Activation is required. These messages are enabled using the Show message during trial and Show message on expiration.

If messages contain http references. eg. "http://www.mywebsite.com" those references will be converted to hyperlinks. This is a convenient way of directing users to your website or "buy" pages.


Publish Tab

The third step in the creation process is to publish your results.

With SWiSH Studio you can export to any of the three output types shown in the Publish tab.

Simply press the desired output type to select it and bring up the appropriate export settings.

Option

Output Type

Description
· Option 1

Projector (.EXE)

Standalone projector executable file.
· Option 2

Screen Saver (.SCR)

Windows screen saver.
· Option 3

Burn to CD/DVD

Burn to an autorun CD/DVD in either EXE or SCR format.


Projector (.EXE)

Selecting the Projector EXE button in the Publish tab brings up the export options for creating a projector executable.

Projector Options

The following options are available:

Save In

Specifies the folder to which the resulting projector will be saved. Browse to select output folder:

Save As

The name of the projector file. The suffix ".exe" will be appended to this name.

Quality

The three quality options (Low, Medium or High) specify the visual quality of the resulting publication.

Mute sound in play list items

Select this option to remove all sound when the publication is played back.

Install Flash player (if required)

This option will include the Flash player installer which means that the publication will check the target system for an installed version of Flash before playing. If the target system does not have Flash installed, the publication will install it automatically. Enabling this feature will result in larger published file sizes.

Create AUTORUN.INF

Select this option to save an AUTORUN.INF file matching the current projector file. The AUTORUN.INF file can, for instance, be burnt to a CD along with the projector to create an auto playing CD. The AUTORUN.INF file is saved to the folder specified in the Save In folder. This can be useful if you want to use your own CD burning software.

Include FSCommand dlls

If your publication needs to process fscommands, then you need to select this option. However, if your publication doesn't need to use fscommands, you can uncheck this option and produce a smaller sized executable.

Compress

Select this option to produce a compacted executable. This option is generally useful for smaller publications where size is important for distribution reasons.

Publish

Press this button to create the final executable and save it to disk. This will fail if an instance of the executable is already running.

Test

Press this button to launch and test the exported executable.


Screen Saver (.SCR)

Selecting the Screensaver SCR button in the Publish tab brings up the publish options for creating a Windows screen saver.

Note: Window size and position options are ignored when .scr is being created.

Screen Saver Options

The following options are available:

Save In

Specifies the folder to which the resulting screen saver will be saved. Browse to select output folder:

Save As

The name of the screen saver file. The suffix ".scr" will be appended to this name.

Quality

The three quality options (Low, Medium or High) specify the visual quality of the resulting publication.

Mute sound in play list items

Select this option to remove all sound when the publication is played back. It's generally a good idea to use this option for screen savers.

Install Flash player (if required)

This option will include the Flash player installer which means that the publication will check the target system for an installed version of Flash before playing. If the target system does not have Flash installed, the publication will install it automatically. Enabling this feature will result in larger published file sizes.

Create AUTORUN.INF

Select this option to save an AUTORUN.INF file matching the current screen saver file. The AUTORUN.INF file can, for instance, be burnt to a CD along with the screen saver to create an auto playing CD. The AUTORUN.INF file is saved to the folder specified in the Save In folder. This can be useful if you want to use your own CD burning software.

Install Screensaver on Publish

Specifies whether the exported screen saver will be installed in the Windows system directory and set as the currently active screen saver when the Publish button is pressed.

Include FSCommand dlls

If your publication needs to process fscommands, then you need to select this option. However, if your publication doesn't need to use fscommands, you can uncheck this option and produce a smaller sized executable.

Compress

Select this option to produce a compacted executable. This option is generally useful for smaller publications where size is important for distribution reasons.

Publish

Press this button to create the final screen saver. Note, this will fail if an instance of the screen saver is already running.

Test

Press this button to launch and test the exported screen saver.

Note: It is also possible to create a Screen Saver Installer program that will install one or more screen savers. See the section SCR Installer Package for more information.


Burn to CD/DVD

Selecting the Burn to CD button in the Publish tab brings up the publish options for creating either a projector or a Windows screen saver.

CD/DVD Options

The following options are available:

Drive

Specifies the CD/DVD drive to write to. Only valid CD/DVD writers should appear in this list, which is prepared automatically.

Volume

The name that appears here will be the name of the CD/DVD (ie, volume label).

Save As

The name of the exported file. The suffix ".exe" or ".scr" will be appended to this name as appropriate.

Quality

The three quality options (Low, Medium or High) specify the visual quality of the resulting publication.

Other files...

This button will invoke a dialog which allows for the selection of additional files to be burned to CD/DVD. You can also define new folders and sub-folders containing files. The defined folder/file structure will be reproduced on the disk.

Note: the files and folders you setup here will not be stored in the Studio document, as they could be very large and need not be directly related to the presentation. Instead, they are stored as application wide preferences, which means that they can be used as common files in all CD/DVD burn sessions.

Mute sound in play list items

Select this option to remove all sound when the exported publication is played back.

Install Flash player (if required)

This option will include the Flash player installer which means that the publication will check the target system for an installed version of Flash before playing. If the target system does not have Flash installed, the publication will install it automatically. Enabling this feature will result in larger published file sizes.

Finalize disk (no more writes)

Tick this option if you wish to make the disk unwritable after burning your files by finalizing the disk. If this option is not checked, then only the disk write session will be finalized, leaving the remainder of the disk writable (by other CD/DVD burning software).

Make this an autorun disk

If this option is checked, then an AUTORUN.INF file matching the current export file will also be burnt to disk, resulting in an autorun disk.

Add Pre-loader

This option works in conjunction with the Autorun function. If checked, when an autorun disk starts up, a small default preloder will be run which will display a bitmap splash screen while the projector (or screen saver) is loading. If you have selected a custom preloader in the Settings Tab CD/DVD Preloader, then that preloader will be displayed instead of the default.

If the projector is many megabytes in size, it can take quite a while before anything obvious appears on-screen. Because the preloader is small, it loads immediately, offering the user feedback.

Write as Projector (.EXE)

Press this button if you wish the file to be burnt to disk to be a projector executable.

Write as Screen Saver (.SCR)

Press this button if you wish the file to be burnt to disk to be a screen saver.

Burn to CD/DVD

Press this button to build the export file and burn it to disk.

The progress control at the bottom of the main window will activate and notify you of progress during the build and burn operation. Press Cancel button (red X) to halt the CD burning process.

If the autorun option is checked, the disk will automatically launch the exported file when loaded onto any Windows machine.

Eject

Elect the drive tray of the specified drive.

Close

Closet the drive tray of the specified drive.

Default files written

The following files are automatically written when burning a CD/DVD:

· unicows.dll - Unicode support for Win98/Me systems.
· gdiplus.dll - Graphics support for non-XP systems. See GDIPlus.dll for more information.


Menu Items

The main menu items are:

· File
· Project
· Tools
· Help.


File Menu

The File menu manages the opening, saving and closing of SWiSH Studio documents. It also allows you to import source files.

New (Ctrl+N)

Create a new document.

Open (Ctr+O)

Open an existing document.

Close

Close the current document.

Select Playlist file(s) (Ctr+I)

Launch the Select Source Files browser and import source files.

Save (Ctrl+S)

Save the current document.

Save As

Save the current document under a different name.

Print (Ctrl+P)

Print the currently selected playlist item.

Recent

Load an existing document from a list of recently used documents.

Exit (Ctr+Q)

Exit SWiSH Studio.


Print

Print...

The print dialog enables you to print any frame or a series of frames from the selected playlist item.

Select

Allows you to select a different file for printing. The newly selected file will be displayed in the preview window.

Bg color

You can change the background color of the file you wish to print by checking this option. When checked, the color swatch will display the new background color along with its RGB values. Clicking on the swatch will bring up a color picker dialog from which you can select a different color. The background color will also be applied to the preview. In addition, you can set the background color by sampling the preview, by clicking on it with the eyedropper.

Begin

For multi-frame content only. Rewinds the movie back to the beginning, showing the first frame.

Back

For multi-frame content only. Rewinds the movie one frame back from the current frame. If you keep the button pressed, the frames will to reverse until you release the button.

Play

For multi-frame content only. Starts playing the movie from the current frame.

Stop

For multi-frame content only. Stops playing the movie.

Forward

For multi-frame content only. Forwards the movie frame by one. If you keep the button pressed, the frames will continue to advance until you release the button.

End

For multi-frame content only. Goes to the last frame of the movie.

Frame

Displays the current frame number. You may change the current frame by keying in a new frame number and pressing the Go button.

Go

Plays the frame displayed in the Frame edit box.

Frame range

Displays which movie frames are to be printed. You can enter a range of frames by using the following symbols: ',' and '-'. For example, to print frames 1, 5 to 10 and 20 to 30, you would enter: "1, 5-10, 20-30".

Format

Specifies how the frames are to be printed. This option is only enabled when the Frame range checkbox is ticked. The Single format simply means one frame per printer page. The other formats allow you to fit several frames per single printer page. For example, format 3x2 would print a total of six frames per page, arranged in two rows of three frames across the page.

Scale

The scale is relative to the printed page. So setting 50% would cause the printed frame to appear at half paper size (maximum horizontal size would be half the paper width and maximum vertical size would be half the paper height).

Setup

This brings up the standard printer settings dialog for your printer.

Print

Prints the selected frames.

Close

Dismisses the print dialog.


Project Menu

The Project menu gives access to most settings and actions available through the Select, Settings and Publish tabs. This means that the user can perform all steps of the publication creation process via menu selection.

These items correspond to the similar items in the Select, Settings and Publish tabs, with the exception of the following.

Remove All Files

Remove all files from the current play list. This is useful for clearing source items while retaining the current project settings and allows single click operation.


Tools Menu

The Tools menu gives you access to various useful options and tools.

Dependencies Palette F9

- specify externally dependent files to be included in published .exe

Options

- sets various configuration parameters.

SCR Installer Package

- creates a single exe that will install screensavers onto a target system.

SCR Preview/Install

- installs and previews the screensaver on the local system.

Convert to Image

- Converts the currently selected playlist item into one of many commonly used image formats.

Clean

- cleans the registry.

FS Command Log

- logs FSCommands for testing purposes.


Dependencies Palette F9

Dependencies Palette F9

This option gives access to the Dependencies Palette. This tool can also be accessed via the Toolbar.


Options

Options...

This option will display the Options dialog box.

Default play time for:

Image items

Sets the default play time in seconds when a play list item of type image is added.

HTML items

Sets the default play time in seconds when a play list item of type HTML is added.

Confirmation

Confirm removal of play list items

If this option is checked, the user will be asked for confirmation before removing items from the play list in the Select tab.

Confirm file overwrites on Publish

If this option is checked, the user will be asked for confirmation before overwriting existing published files in the Publish tab.

Default play time for Image/HTML items

Specify the default play time for which image/HTML items will be run in your publication.

General

Show Toolbar

Toggle this checkbox to make visible or hide the SWiSH Studio toolbar.

Automatically load last document

Check this option to make SWiSH Studio automatically load the last saved document upon startup.

Save file dependencies in document

When this is checked, all file dependencies defined in the Dependencies Palette will be saved in the document. This makes the document a wholly self-contained unit that can be shared between different users.

When this option is unchecked, the dependent files will not be saved into the document, only their names and locations, thus speeding up document save times and minimizing document size. However, be aware that the document will not be portable as there is a reliance on the user's machine to locate the files.

Save CD/DVD 'Other files' in document

Check this option if you wish to save the file paths of auxiliary files to be burned to CD/DVD within the SWiSH Studio document file. Note, only file paths will be stored, not the actual files themselves. This setting is useful if you have different files associated with each project.

If this option is unchecked, then the auxiliary files will be retained across different documents. This is the default setting and corresponds to version 1 functionality. This setting is useful if you always need to distribute the same files for all of your projects (such as company promotional material, utilities, etc).

Substitute with FSCommands

Due to the limitations of the flash ActiveX control, when loading local html files (getURL) with a relative pathname, the browser will assume that the filename specified is to be found on the Web and so adds "http://" to the pathname and, of course, fails to find it, giving the 'file not found' message. A similar situation occurs when using the mailto: command to invoke an email client - a browser window is also invoked with an error message.

There are two solutions to these problems. You can use the FSCommand Exec to load all local html files and the FSCommand mailto for invoking the email client.

Alternatively, you can check this option and SWiSH Studio will perform the substitution automatically whenever you publish your document. This way, you do not need to make any changes to the flash action script to use fscommands.

Command substitution will also take place when loading local image files. SWiSH Studio will translate these commands into a ShowImage fscommand. This also means that you can display images that normally would not display inside a browser window, such as TIF.

Sound

If you wish to know whether or not the above command substitution took place, you can check this box and SWiSH Studio will make a beeping sound when a substitution takes place - one per SWF file.


SCR Installer Package

SCR Installer package...

This command will open the Screensaver Installer Package dialog.

Through this dialog the user can create a single .exe installer that will install one or more selected screensavers into the appropriate system folder. On installation, the screensavers may be viewed/selected with the standard system Display Properties dialog, Screen Saver tab. Optionally, the Display Properties dialog, Screen Saver tab may be automatically shown on installation by checking the [x] Show screensaver tab option.

Select one or more screensaver files, specify a name to Save As and a folder to Save In, then press the Make button to create an EXE file that installs the selected screensavers when run on a target system.

After the screensaver installer is run, the last screen saver in the list, will be the default screensaver.

Include GdiPlus.dll

Check this option if the target system is not likely to be Windows XP, as other operating systems do not come standard with this dll, which is required for the screensavers to operate.

Show screensaver tab

Check this option if you wish that the system Display Properties dialog, Screen Saver tab, be automatically displayed upon successful installation:


SCR Preview/Install

SCR Preview/Install...

This option will open the Preview/Install Screensavers dialog.

Select a screensaver, then press the Preview button to test it. Press the Install button to install it in your Windows system directory and set it as the current screensaver.


Convert to Image

Convert to Image...

This tool allows you to convert one or more frames from a selected playlist item into any popular image format.

Select

Allows you to select a different file for conversion. The newly selected file will be displayed in the preview window.

Bg color

You can change the background color of the file you wish to convert by checking this option. When checked, the color swatch will display the new background color along with its RGB values. Clicking on the swatch will bring up a color picker dialog from which you can select a different color. The background color will also be applied to the preview. In addition, you can set the background color by sampling the preview, by clicking on it with the eyedropper.

Begin

For multi-frame content only. Rewinds the movie back to the beginning, showing the first frame.

Back

For multi-frame content only. Rewinds the movie one frame back from the current frame. If you keep the button pressed, the frames will to reverse until you release the button.

Play

For multi-frame content only. Starts playing the movie from the current frame.

Stop

For multi-frame content only. Stops playing the movie.

Forward

For multi-frame content only. Forwards the movie frame by one. If you keep the button pressed, the frames will continue to advance until you release the button.

End

For multi-frame content only. Goes to the last frame of the movie.

Frame

Displays the current frame number. You may change the current frame by keying in a new frame number and pressing the Go button.

Go

Plays the frame displayed in the Frame edit box.

Save In

The folder location of the converted image(s).

Browse

Select a new output folder location.

Save As

Filename of the converted image. If multiple frames are being converted, then the out filenames will have the frame number appended tot the filename. The image format may be one of JPEG, PNG, BMP, GIF, TIFF.

Type

The converted image may be saved either in full color or black and white (grayscale).

Quality

This only applies to JPEG format images. The higher the quality specified the better the image will look, but the higher the file size and vice-versa.

Pixel Width

Specifies the final horizontal image size. Changing this value will automatically change the Pixel Height value so that the original image aspect ratio is retained.

Pixel Height

Specifies the final vertical image size. Changing this value will automatically change the Pixel Width value so that the original image aspect ratio is retained.

Percentage of Original Size

The scale is relative to the printed page. So setting 50% would cause the printed frame to appear at half paper size (maximum horizontal size would be half the paper width and maximum vertical size would be half the paper height).

Frame range

Displays which movie frames are to be printed. You can enter a range of frames by using the following symbols: ',' and '-'. For example, to print frames 1, 5 to 10 and 20 to 30, you would enter: "1, 5-10, 20-30".

Convert

Performs the conversion of selected frames into images.

Close

Dismisses the print dialog.


Clean

Clean

Use this option to clean out the registry. Over time, you may build up numerous entries associated with old projectors and screen savers. When this option is activated, all such registry entries will be removed.


FS Command Log

FSCommand Log

This option will open an FSCommand log window, which will show FSCommands generated by your SWF files as they occur during testing.

Note: If this window is open when you publish a projector, the projector will also open a FSCommand log window. This can be useful in testing your final publication.


Help Menu

The Help menu item contains information about SWiSH Studio.

SWiSH Studio Help

Display this help manual.

About SWiSH Studio

Displays an About dialog containing version information, copyright details and credits.

Check for Update

Checks for newer versions of SWiSH Studio.

About UPX

Displays an UPX product About dialog.


Toolbar

The toolbar provides key functions that the user will most likely want at their fingertips.

The toolbar functions include:

Create a new project

Create a new document.

Open an existing project

Open an existing document file.

Save current project

Save the current document.

Print

Print the currently selected playlist item.

Show / Hide Dependencies Palette

Toggle to show/hide the floating Dependencies Palette. This allows the addition of Dependent Files.

Build projector executable

Build your publication as a projector executable using the current settings, and open up the Publish tab if not already open.

Make a screensaver

Build your publication as a screen saver using the current settings, and open up the Publish tab if not already open.

Burn to CD

Burn your publication to CD using the current settings, and open up the Publish tab if not already open.

Show/Hide help banner

Toggle this button to show/hide a help banner at the top of each tab which briefly describes its purpose.


Single Click Operation

SWiSH Studio is fully functional even if reduced to its smallest non-minimized size.

Playlist files can be added by dropping them anywhere with the SWiSH Studio window, then simply press the appropriate toolbar button to publish a projector executable, screen saver, or burn to CD.

There is no need to expand the window to change settings as most settings and actions are readily accessible through menu items, including the removal of current play list files or even totally resetting the current document by starting a new one.


Dependencies Palette

The palette may be activated via function key F9 or from the toolbar icon toolbar-dependent-1

This floating palette allows the user to add Dependent Files to the publication. It is a way of packaging and re-creating external files and folders required by the publication as it executes.

The Dependencies Palette is used to include all external files referenced by a playlist item. That is, the playlist item is dependent on these files in order to run correctly. The files might include other SWFs, EXEs, HTML files or any other files required by the main movie. The dependent files may be saved in their own sub-folders, if desired.

When SWiSH Studio publishes a projector exe or screen saver, it automatically packs all files in the Dependencies Palette into a single executable module that can be easily shared. Everything is self-contained so you need not worry about 'missing' files when distributing the publication.

When the exe or screen saver is run, the packed playlist items and dependent files are unpacked into a temporary folder then loaded by the publication as required.

When accessing files stored in the Dependencies Palette, you must use Relative folder paths, as the current working folder changes to the temp folder* (rather then remaining the folder from which the publication was executed). For example, to load a PDF file stored in the top Dependencies Palette folder:

fscommand ("Exec", "prices.pdf");

If the PDF was stored in a Dependencies Palette sub-folder called 'store', you would load it with:

fscommand ("Exec", "store\\prices.pdf");

NOTE: *If you do not include any files in the Dependencies Palette, then the current working folder remains the folder from which the publication was executed.


Skins

SWiSH Studio supports window skins for projector files. A Studio skin file (.sss) is a simple text file with declarations which define a unique look-and-feel to SWiSH Studio projector exes. You will find a default set of skins in the sub-folder (of the install folder) StudioSkins.

Skin file selection is performed in the Settings Tab Window Skin page.

Here is a sample skin called Techno.

See Also: Skin file definition


File Definition

Skin File

The .sss skin file is a text file that may be edited in any text editor. This allows for easy user customization.

The skin file format follows a simple section/attribute tag style. Some section names are mandatory, while others are optional. The same applies to attribute names. Let's examine the tags.

Skin File Conventions

Each section tag is enclosed in square brackets eg: [Version]. Everything that is defined after a section tag is related to that section (until another section is defined). These definitions are called attribute tags. Every attribute tag has the form:

attributeName = data

Section and attribute names are not case sensitive and my appear in any order inside the .sss file.

All reference point offsets and positions are measured in pixels. A bitmap's origin (0,0) point is always the top left position.

All color definitions are in RGB triples (0-255).

Pathnames may be enclosed in double quotes ("pathname").

Section Definitions:

The following sections are supported.

Version (required)

Every skin file must have a version section. The version identifies the skin file version which is required for future compatibility. If this section is not defined, the skin file will be deemed invalid.

Supported attribute tags include:

· Ver = versionNumber

- required
· Copyright = "string"

- optional

eg:

[Version]

Ver = 1.0

Copyright = "SWiSHzone.com"

Preview (optional)

This section is optional. However, if you do not define it, you will not be able to preview the skin file when browsing, though if the rest of the skin file is valid, it will display correctly in the final exe. It is recommended that the preview image be 350 x 230 pixels in size, for consistency with default skins. Also. it is a good idea to use a compact image format like PNG or JPEG for the preview (and other bitmaps) to keep the image size down.

Supported attribute tags include:

· Bitmap = pathname

- optional

eg:

[Preview]

Bitmap = Techno/Techno_Preview.png

ViewArea (optional)

This section is optional. If not specified, it is assumed that the view area is rectangular. The view area refers to the area that will display the window content, such as an SWF file or an image file, etc.

If you're defining a skin that does not have a rectangular view area (like the Techno skin), then you must define this section and set the Shape attribute to Irregular, otherwise the skinned exe will not display correctly.

Supported attribute tags include:

· Shape = Irregular

- required only if window content display area is non-rectangular.

eg:

[ViewArea]

Shape = Irregular

FrameTopLeft (required)

This section must be specified. It defines the top left corner of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap will usually need to have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

A reference point also needs to be specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the top left corner of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme

- required
· RefPoint = x,y

- required

eg:

[FrameTopLeft]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_TL.png

RefPoint = 59,36

FrameTopRight (required)

This section must be specified. It defines the top right corner of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap will usually need to have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

A reference point also needs to be specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the top right corner of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme

- required
· RefPoint = x,y

- required

eg:

[FrameTopRight]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_TR.png

RefPoint = 64,20

FrameBotLeft (required)

This section must be specified. It defines the bottom left corner of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap will usually need to have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

A reference point also needs to be specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the bottom left corner of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme

- required
· RefPoint = x,y

- required

eg:

[FrameBotLeft]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_BL.png

RefPoint = 47,19

FrameBotRight (required)

This section must be specified. It defines the bottom right corner of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap will usually need to have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

A reference point also needs to be specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the bottom right corner of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme

- required
· RefPoint = x,y

- required

eg:

[FrameBotRight]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_BR.png

RefPoint = 13,19

FrameMidTop (required)

This section must be specified. It defines the top middle section of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap may have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

The mid-section is the part of the window that will be extended when the window is resized in the horizontal direction. This bitmap can be only 1 pixel in width and will be repeated as many times as necessary between the top left and the top right corner sections.

The bitmap may also be more complex, defining wider sections with more detail. If this is the case, then you need to specify the suffix Complex after the bitmap definition: eg: Bitmap = Techno/Techno_MT.png, Complex. This tells the SWiSH Studio skinning engine to process this section differently compared to a simple rectangular bitmap section.

A reference point is optional. It only needs to be specified if the ViewArea Shape = Irregular. If so, then the point is specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the top horizontal edge of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme [, Complex]

- required, but suffix Complex is optional
· RefPoint = x,y

- required only if ViewArea Shape = Irregular

eg:

[FrameMidTop]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_MT.png

RefPoint = 0,21

FrameMidBot (required)

This section must be specified. It defines the bottom middle section of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap may have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

The mid-section is the part of the window that will be extended when the window is resized in the horizontal direction. This bitmap can be only 1 pixel in width and will be repeated as many times as necessary between the bottom left and the bottom right corner sections.

The bitmap may also be more complex, defining wider sections with more detail. If this is the case, then you need to specify the suffix Complex after the bitmap definition: eg: Bitmap = Techno/Techno_MB.png, Complex. This tells the SWiSH Studio skinning engine to process this section differently compared to a simple rectangular bitmap section.

A reference point is optional. It only needs to be specified if the ViewArea Shape = Irregular. If so, then the point is specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the bottom horizontal edge of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme [, Complex]

- required, but suffix Complex is optional.
· RefPoint = x,y

- required only if ViewArea Shape = Irregular

eg:

[FrameMidBot]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_MB.png, Complex

RefPoint = 0,19

FrameMidLeft (required)

This section must be specified. It defines the left middle section of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap may have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

The mid-section is the part of the window that will be extended when the window is resized in the vertical direction. This bitmap can be only 1 pixel in height and will be repeated as many times as necessary between the bottom left and the top left corner sections.

The bitmap may also be more complex, defining wider sections with more detail. If this is the case, then you need to specify the suffix Complex after the bitmap definition: eg: Bitmap = Techno/Techno_ML.png, Complex. This tells the SWiSH Studio skinning engine to process this section differently compared to a simple rectangular bitmap section.

A reference point is optional. It only needs to be specified if the ViewArea Shape = Irregular. If so, then the point is specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the left vertical edge of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme [, Complex]

- required, but suffix Complex is optional.
· RefPoint = x,y

- required only if ViewArea Shape = Irregular

eg:

[FrameMidLeft]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_ML.png, Complex

RefPoint = 45,0

FrameMidRight (required)

This section must be specified. It defines the right middle section of the skinned window by means of a bitmap. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap may have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

The mid-section is the part of the window that will be extended when the window is resized in the vertical direction. This bitmap can be only 1 pixel in height and will be repeated as many times as necessary between the bottom right and the top right corner sections.

The bitmap may also be more complex, defining wider sections with more detail. If this is the case, then you need to specify the suffix Complex after the bitmap definition: eg: Bitmap = Techno/Techno_ML.png, Complex. This tells the SWiSH Studio skinning engine to process this section differently compared to a simple rectangular bitmap section.

A reference point is optional. It only needs to be specified if the ViewArea Shape = Irregular. If so, then the point is specified relative to the top-left (0,0) point of the bitmap file. The reference point defines the location of the right vertical edge of the window content display area.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- required
· Bitmap = pathanme [, Complex]

- required, but suffix Complex is optional.
· RefPoint = x,y

- required only if ViewArea Shape = Irregular

eg:

[FrameMidRight]

Shape = ColorMask,255,255,0

Bitmap = Techno/Techno_MR.png

RefPoint = 3,0

Icon (optional)

This section is optional. It defines an icon bitmap to be used in the skinned window frame, usually next to the window title. This bitmap is identified with the Bitmap attribute and can be in any common image format. The bitmap may have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

Note: if you've specified an icon in the Settings Tab->Window Style->Title Bar->Icon control, then this icon will be used instead of the one specified in the skin file.

The FrameId attribute is optional. It specifies an anchor position of the icon which may be any one of the four corner sections identified as: FrameTopLeft, FrameTopRight, FrameBotLeft, FrameBotRight. If not specified, FrameTopLeft is assumed.

The RefPoint attribute is also optional. It specifies the position of the top left corner of the icon relative to the frame corner bitmap specified with FrameId. If not specified, the default reference point in 0,0.

The Shape attribute is optional. If not specified, the bitmap is assumed to be a simple rectangle and no transparency processing will take place.

Supported attribute tags include:

· Shape = ColorMask,r,g,b

- optional
· FrameId = FrameTopLeft

- optional
· Bitmap = pathanme

- required
· RefPoint = x,y

- optional

eg:

[Icon]

FrameId = FrameTopLeft

RefPoint = 6,6

Shape = ColorMask,255,0,0

Bitmap = Techno/Techno_icon.png

TitleBar (optional)

This section is optional. It is used to specify the font and text that will appear in a designated area of the skinned window, usually at the top.

The FontSpec attribute is optional, however, it should be defined if you wish to control how the text will appear. You can specify the typeface name, the font size, whether it should display bolded, italicised or plain. If the typeface name is left empty (""), a default font will be selected that is guaranteed to appear on any machine, including foreign language machines.

The Position attribute is optional. It defines the top left location of the text relative to the whole skinned dialog. If omitted, the default position is 0,0.

The Alignment attribute is optional. Currently, only one value is defined: Centered. If alignment is centered, the text will appear centered to the top mid-section of the window (ie, the section between the top left and top right corner sections).

The Color attribute is also optional. It defines the color of the text. The default text color is white (rgb: 255,255,255).

The ShadowColor attribute is optional. If defined, it signals that the text will be rendered with a drop shadow of the color specified. If omitted, but the ShadowOffs attribute is defined, the shadow color will default to black (rgb: 0,0,0).

The ShadowOffs attribute is optional. It defines the relative offset of the shadow text with respect to the title text. The offsets may be positive or negative. If this attribute is omitted, but the ShadowColor attribute is defined, then the shadow offset will default to 1,1.

The Text attribute is optional and should generally not be used as it can override your exe's title. If this attribute is defined AND nothing is entered in the Settings Tab->Window Style->Title Bar->Caption edit box, then this text string will be displayed. If a title is entered in the caption edit box, then that string will be displayed instead of the Text attribute string in the skin file.

If the Text attribute is omitted from the skin file and nothing is defined in the caption edit box, then the displayed title string will be the name of the exe itself.

· FontSpec = "faceName", size, bold, italic

- optional (as are all the items in the list)
· Position = x,y

- optional (defaults to 0,0)
· Alignment = Center

- optinal (defaults to none)
· Color = r,g,b

- optional (defaults to white)
· ShadowColor = r,g,b

- optional (defaults to black)
· ShadowOffs = x,y

- optional (defaults to 1,1).
· Text = "textString"

- optional

eg:

[TitleBar]

FontSpec = "Arial", 15, bold

Color = 244,241,254

Position = 26,6

ShadowOffs = 1,1

ShadowColor = 11,11,22

MinButton (optional)

This section is optional. It is used to define a button associated with minimizing the window. If it is omitted then no minimize button will be displayed.

The button is defined by up to three different bitmaps, one each for the button up, hover and pressed down states. Only the button up bitmap is required - if the others aren't defined, then the button will not show those states.

A bitmap state is defined by one of the following attributes: BitmapUp, BitmapDown, BitmapHover. The bitmaps may be in any common image format. The bitmaps may have a complex, non-rectangular shape. SWiSH Studio will automatically generate the required shape through a color masking process. By specifying a Shape = ColorMask,r,g,b attribute, SWiSH Studio will treat this color as transparent, leaving behind the desired shape.

The Shape attribute is optional. If not specified, it is assumed that the bitmap shapes are rectangular and will be used as is. If specified, the associated ColorMask color will be used for all button bitmap states.

The FrameId attribute is optional. It specifies an anchor position of the button which may be any one of the four corner sections identified as: FrameTopLeft, FrameTopRight, FrameBotLeft, FrameBotRight. If not specified, FrameTopRight is assumed.

The RefPoint attribute must be specified. It defines the position of the top left corner of the button relative to the frame corner bitmap specified with FrameId.

The BitmapUp attribute specifies the up-state bitmap for the button.

The BitmapDown attribute specifies the down-state bitmap for the button.

The BitmapHover attribute specifies the hover-state bitmap for the button. This is the condition when the cursor moves over the button, but is not pressed.

· FrameId = FrameTopRight

- optional
· RefPoint = x,y

- required
· Shape = ColorMask,r,g,b

- optional
· BitmapUp = pathanme

- required
· BitmapDown = pathanme

- optional
· BitmapHover = pathanme

- optional

eg:

[MinButton]

FrameId = FrameTopRight

RefPoint = 18,16

Shape = ColorMask,255,255,0

BitmapUp = Techno/Techno_btn_min_up.png

BitmapDown = Techno/Techno_btn_min_dn.png

BitmapHover = Techno/Techno_btn_min_hov.png

MaxButton (optional)

Same as the MinButton except the button function is to maximize/restore the window.

eg:

[MaxButton]

FrameId = FrameTopRight

RefPoint = 35,16

Shape = ColorMask,255,255,0

BitmapUp = Techno/Techno_btn_max_up.png

BitmapDown = Techno/Techno_btn_max_dn.png

BitmapHover = Techno/Techno_btn_max_hov.png

CancelButton (optional)

Same as the MinButton except the button function is to cancel or exit the application.

eg:

[CancelButton]

FrameId = FrameTopRight

RefPoint = 52,16

Shape = ColorMask,255,255,0

BitmapUp = Techno/Techno_btn_cancel_up.png

BitmapDown = Techno/Techno_btn_cancel_dn.png

BitmapHover = Techno/Techno_btn_cancel_hov.png


FSCommand Support

SWiSH Studio supports a basic set of FSCommand calls. This list will increase over time.

In addition, you can author your own FSCommand libraries.

The section FSCommand Return Values describes how FS Commands return status and other information.


FSCommand Return Values

After each fscommand is executed, the flash variable "fscmd_ret" will be set with a return value. It is up to the SWF author to check and/or respond to the return code after executing the command. A return code of –99 means that the executed command did not return a value. Other commonly used return codes are described in the section Generic Return Codes. Note that these return codes only apply if mentioned in the fscommand description.

Note: fscmd_ret is returned as a string. See fscmd_ret is returned as a string for more information.

Note: fscommands are executed as "non-blocking" commands. This means that your movie will continue even though the fscommand may not be complete. If you need to know when an fscommand has been executed, you can set the variable "fscmd_ret" to some special value and wait for it to change.

See FS Commands are Non Blocking in the notes section.

With many commands it is possible to quote a variable that the command is to return data into. In those instances the parameter is shown as [out]. When passing the name of such a variable, the variable is assumed to be at the top level of your movie. ie (_root.).

Note: When calling a fscommand from within a sprite or movie clip, any return variables MUST be declared with their full path.

eg. If your sprite / movie clip is mysprite, and your local variable is var, use _root.mysprite.var. var on its own will be treated as _root.var


Generic Return Codes

Error Code | Meaning
0 | Successful return (may be different as defined by commmand)
-99 | Generic return code when command returns no value
-101 | Insufficent arguments / Incorrect number of arguments
-102 | Argument out of range
-103 | File not open
-104 | File open failed. - File may not exist or opened for reading
-105 | Generic failure code. - No additional information.
-106 | End of file
-107 | Item not found
-108 | Future implementation
-109 | Memory error / limitation
-1000 to -1999 | System errors are subtracted from -1000 so a generic Permission error (EPERM 1) would be returned as -1001 Errors in this range are obtained from errno.
-2000 to -2999 | Extended System Errors, Errors returned from GetLastError() are subtracted from -2000 so an error (ERROR_FILE_EXISTS 80) would be returned as -2080

The above codes are returned in fscmd_ret.

Note: Apart from the -99 return code, the codes above will only be used if the command documentation states that it uses the Generic Return Codes.


System Errors

These errors are generally values that are placed into errno.

The values are contained in the header file errno.h

Note that the header file errno.h will only exist on systems that have a C++ development system installed.

Below are the system error codes:

#define EPERM              1

#define ENOENT             2

#define ESRCH             3

#define EINTR              4

#define EIO                5

#define ENXIO              6

#define E2BIG              7

#define ENOEXEC        8

#define EBADF              9

#define ECHILD             10

#define EAGAIN             11

#define ENOMEM          12

#define EACCES             13

#define EFAULT             14

#define EBUSY              16

#define EEXIST             17

#define EXDEV              18

#define ENODEV             19

#define ENOTDIR            20

#define EISDIR             21

#define EINVAL             22

#define ENFILE             23

#define EMFILE             24

#define ENOTTY             25

#define EFBIG              27

#define ENOSPC             28

#define ESPIPE             29

#define EROFS              30

#define EMLINK             31

#define EPIPE              32

#define EDOM               33

#define ERANGE             34

#define EDEADLK           36

#define ENAMETOOLONG        38

#define ENOLCK             39

#define ENOSYS             40

#define ENOTEMPTY          41

#define EILSEQ             42


Extended System Errors

These error numbers are returned by the SDK function GetLastError().

In some cases they have re-defind the error codes specified within errno.h. Consequently, fscommands return these error in a different number range (<2000)

The values are defined in the header file error.h

Note that the header file error.h will only exist on systems that have a C/C++ development system installed.

Below are the extended system error codes:

#define ERROR_INVALID_FUNCTION           1

#define ERROR_FILE_NOT_FOUND             2

#define ERROR_PATH_NOT_FOUND             3

#define ERROR_TOO_MANY_OPEN_FILES        4

#define ERROR_ACCESS_DENIED            5

#define ERROR_INVALID_HANDLE           6

#define ERROR_ARENA_TRASHED            7

#define ERROR_NOT_ENOUGH_MEMORY          8

#define ERROR_INVALID_BLOCK            9

#define ERROR_BAD_ENVIRONMENT            10

#define ERROR_BAD_FORMAT               11

#define ERROR_INVALID_ACCESS             12

#define ERROR_INVALID_DATA             13

/* **** reserved                                           14  ***** */

#define ERROR_INVALID_DRIVE            15

#define ERROR_CURRENT_DIRECTORY          16

#define ERROR_NOT_SAME_DEVICE            17

#define ERROR_NO_MORE_FILES            18

/* */

/* These are the universal int 24 mappings for the old INT 24 set of errors */

/* */

#define ERROR_WRITE_PROTECT            19

#define ERROR_BAD_UNIT                 20

#define ERROR_NOT_READY                21

#define ERROR_BAD_COMMAND              22

#define ERROR_CRC                  23

#define ERROR_BAD_LENGTH               24

#define ERROR_SEEK                 25

#define ERROR_NOT_DOS_DISK             26

#define ERROR_SECTOR_NOT_FOUND        27

#define ERROR_OUT_OF_PAPER             28

#define ERROR_WRITE_FAULT              29

#define ERROR_READ_FAULT               30

#define ERROR_GEN_FAILURE              31

/* */

/* These are the new 3.0 error codes reported through INT 24 */

/* */

#define ERROR_SHARING_VIOLATION                  32

#define ERROR_LOCK_VIOLATION                   33

#define ERROR_WRONG_DISK                       34

#define ERROR_FCB_UNAVAILABLE                    35

#define ERROR_SHARING_BUFFER_EXCEEDED        36

/* */

/* New OEM network-related errors are 50-79 */

/* */

#define ERROR_NOT_SUPPORTED 50

/* */

/* End of INT 24 reportable errors */

/* */

#define ERROR_FILE_EXISTS         80

#define ERROR_DUP_FCB             81

#define ERROR_CANNOT_MAKE        82

#define ERROR_FAIL_I24          83

/* */

/* New 3.0 network related error codes */

/* */

#define ERROR_OUT_OF_STRUCTURES        84

#define ERROR_ALREADY_ASSIGNED           85

#define ERROR_INVALID_PASSWORD           86

#define ERROR_INVALID_PARAMETER          87

#define ERROR_NET_WRITE_FAULT            88

/* */

/* New error codes for 4.0 */

/* */

#define ERROR_NO_PROC_SLOTS            89 /* no process slots available */

#define ERROR_NOT_FROZEN               90

#define ERR_TSTOVFL                91 /* timer service table overflow */

#define ERR_TSTDUP                 92 /* timer service table duplicate */

#define ERROR_NO_ITEMS                 93 /* There were no items to operate upon */

#define ERROR_INTERRUPT                95 /* interrupted system call */

#define ERROR_TOO_MANY_SEMAPHORES         100

#define ERROR_EXCL_SEM_ALREADY_OWNED        101

#define ERROR_SEM_IS_SET                       102

#define ERROR_TOO_MANY_SEM_REQUESTS        103

#define ERROR_INVALID_AT_INTERRUPT_TIME        104

#define ERROR_SEM_OWNER_DIED        105 /* waitsem found owner died */

#define ERROR_SEM_USER_LIMIT             106 /* too many procs have this sem */

#define ERROR_DISK_CHANGE              107 /* insert disk b into drive a */

#define ERROR_DRIVE_LOCKED             108 /* drive locked by another process */

#define ERROR_BROKEN_PIPE              109 /* write on pipe with no reader */

/* */

/* New error codes for OS/2 */

/* */

#define ERROR_OPEN_FAILED                      110 /* open/created failed due to */

                                                  /* explicit fail command */

#define ERROR_BUFFER_OVERFLOW              111 /* buffer passed to system call */

                                                  /* is too small to hold return */

                                                  /* data. */

#define ERROR_DISK_FULL                        112 /* not enough space on the disk */

                                                  /* (DOSNEWSIZE/w_NewSize) */

#define ERROR_NO_MORE_SEARCH_HANDLES        113 /* can't allocate another search */

                                                  /* structure and handle. */

                                                  /* (DOSFINDFIRST/w_FindFirst) */

#define ERROR_INVALID_TARGET_HANDLE        114 /* Target handle in DOSDUPHANDLE */

                                                  /* is invalid */

#define ERROR_PROTECTION_VIOLATION         115 /* Bad user virtual address */

#define ERROR_VIOKBD_REQUEST               116

#define ERROR_INVALID_CATEGORY             117 /* Category for DEVIOCTL in not */

                                                  /* defined */

#define ERROR_INVALID_VERIFY_SWITCH        118 /* invalid value passed for */

                                                  /* verify flag */

#define ERROR_BAD_DRIVER_LEVEL             119 /* DosDevIOCTL looks for a level */

                                                  /* four driver.   If the driver */

                                                   /* is not level four we return */

                                                  /* this code */

#define ERROR_CALL_NOT_IMPLEMENTED         120 /* returned from stub api calls. */

                                                  /* This call will disappear when */

                                                  /* all the api's are implemented. */

#define ERROR_SEM_TIMEOUT                      121 /* Time out happened from the */

                                                  /* semaphore api functions. */

#define ERROR_INSUFFICIENT_BUFFER          122 /* Some call require the  */

                                                  /* application to pass in a buffer */

                                                  /* filled with data.  This error is */

                                                  /* returned if the data buffer is too */

                                                  /* small.  For example: DosSetFileInfo */

                                                  /* requires 4 bytes of data.  If a */

                                                  /* two byte buffer is passed in then */

                                                  /* this error is returned.   */

                                                  /* error_buffer_overflow is used when */

                                                  /* the output buffer in not big enough. */

#define ERROR_INVALID_NAME                     123 /* illegal character or malformed */

                                                  /* file system name */

#define ERROR_INVALID_LEVEL                    124 /* unimplemented level for info */

                                                  /* retrieval or setting */

#define ERROR_NO_VOLUME_LABEL              125 /* no volume label found with */

                                                  /* DosQFSInfo command */

#define ERROR_MOD_NOT_FOUND                    126 /* w_getprocaddr,w_getmodhandle */

#define ERROR_PROC_NOT_FOUND               127 /* w_getprocaddr */

#define ERROR_WAIT_NO_CHILDREN                   128 /* CWait finds to children */

#define ERROR_CHILD_NOT_COMPLETE                 129 /* CWait children not dead yet */

/*This is a temporary fix for the 4-19-86 build this should be changed when */

/* we get the file from MS */

#define ERROR_DIRECT_ACCESS_HANDLE                130 /* handle operation is invalid */

                                                  /* for direct disk access */

                                                  /* handles */

#define ERROR_NEGATIVE_SEEK                131 /* application tried to seek  */

                                                     /* with negative offset */

#define ERROR_SEEK_ON_DEVICE               132 /* application tried to seek */

                                                  /* on device or pipe */

/* */

/* The following are errors generated by the join and subst workers */

/* */

#define ERROR_IS_JOIN_TARGET               133

#define ERROR_IS_JOINED                        134

#define ERROR_IS_SUBSTED                       135

#define ERROR_NOT_JOINED                       136

#define ERROR_NOT_SUBSTED                      137

#define ERROR_JOIN_TO_JOIN                     138

#define ERROR_SUBST_TO_SUBST               139

#define ERROR_JOIN_TO_SUBST                    140

#define ERROR_SUBST_TO_JOIN                    141

#define ERROR_BUSY_DRIVE                       142

#define ERROR_SAME_DRIVE                       143

#define ERROR_DIR_NOT_ROOT                     144

#define ERROR_DIR_NOT_EMPTY                    145

#define ERROR_IS_SUBST_PATH                    146

#define ERROR_IS_JOIN_PATH                     147

#define ERROR_PATH_BUSY                        148

#define ERROR_IS_SUBST_TARGET              149

#define ERROR_SYSTEM_TRACE                     150 /* system trace error */

#define ERROR_INVALID_EVENT_COUNT          151 /* DosMuxSemWait errors */

#define ERROR_TOO_MANY_MUXWAITERS          152

#define ERROR_INVALID_LIST_FORMAT          153

#define ERROR_LABEL_TOO_LONG               154

#define ERROR_TOO_MANY_TCBS                    155

#define ERROR_SIGNAL_REFUSED               156

#define ERROR_DISCARDED                        157

#define ERROR_NOT_LOCKED                       158

#define ERROR_BAD_THREADID_ADDR            159

#define ERROR_BAD_ARGUMENTS                    160

#define ERROR_BAD_PATHNAME                     161

#define ERROR_SIGNAL_PENDING               162

#define ERROR_UNCERTAIN_MEDIA              163

#define ERROR_MAX_THRDS_REACHED            164

#define ERROR_MONITORS_NOT_SUPPORTED        165

#define ERROR_INVALID_SEGMENT_NUMBER        180

#define ERROR_INVALID_CALLGATE             181

#define ERROR_INVALID_ORDINAL              182

#define ERROR_ALREADY_EXISTS               183

#define ERROR_NO_CHILD_PROCESS             184

#define ERROR_CHILD_ALIVE_NOWAIT           185

#define ERROR_INVALID_FLAG_NUMBER          186

#define ERROR_SEM_NOT_FOUND                    187

/*  following error codes have added to make the loader error

   messages distinct

*/

#define ERROR_INVALID_STARTING_CODESEG         188

#define ERROR_INVALID_STACKSEG             189

#define ERROR_INVALID_MODULETYPE           190

#define ERROR_INVALID_EXE_SIGNATURE        191

#define ERROR_EXE_MARKED_INVALID           192

#define ERROR_BAD_EXE_FORMAT               193

#define ERROR_ITERATED_DATA_EXCEEDS_64k        194

#define ERROR_INVALID_MINALLOCSIZE         195

#define ERROR_DYNLINK_FROM_INVALID_RING        196

#define ERROR_IOPL_NOT_ENABLED             197

#define ERROR_INVALID_SEGDPL               198

#define ERROR_AUTODATASEG_EXCEEDS_64k          199

#define ERROR_RING2SEG_MUST_BE_MOVABLE        200

#define ERROR_RELOC_CHAIN_XEEDS_SEGLIM         201

#define ERROR_INFLOOP_IN_RELOC_CHAIN        202

#define ERROR_ENVVAR_NOT_FOUND             203

#define ERROR_NOT_CURRENT_CTRY             204

#define ERROR_NO_SIGNAL_SENT               205

#define ERROR_FILENAME_EXCED_RANGE         206 /* if filename > 8.3 */

#define ERROR_RING2_STACK_IN_USE           207 /* for FAPI */

#define ERROR_META_EXPANSION_TOO_LONG        208 /* if "*a" > 8.3 */

#define ERROR_INVALID_SIGNAL_NUMBER        209

#define ERROR_THREAD_1_INACTIVE            210

#define ERROR_INFO_NOT_AVAIL                     211 /*@@ PTM 5550 */

#define ERROR_LOCKED                           212

#define ERROR_BAD_DYNALINK                     213 /*@@ PTM 5760 */

#define ERROR_TOO_MANY_MODULES                   214

#define ERROR_NESTING_NOT_ALLOWED                215


FSCommand List

The following functions are available with the 2005.05.03 (or later) version of the fscommand.dll

The section FSCommand Return Values describes how FS Commands return status and other information. This section should be consulted before using the commands as the non blocking nature of FS Commands, if not understood, can introduce strange or unexpected behavior.

The commands are described with the following Syntax

Command: | Example ("param1, <param2=100>, <[out] param3>")
Usage: | fscommand ("Example", "test1") fscommand ("Example", "test1,200") fscommand ("Example", "test1,,status") fscommand ("Example", "test1,200,status")
Return Code: | -99

The Command section defines the command name and the parameters it expects.

The command name is specified by the name before the brackets. In the example above, the command name is "Example".

Parameters surrounded with <> are optional. If the parameter includes a = character then the right hand value is the default value that is used if the parameter is omitted. In the example above, the default value for param2 is 100.

[out] indicates that a variable should be supplied and a value is returned in the supplied variable. (ie. it is an output parameter).

See the warning in FSCommand Return Values regarding how this variable should be specified.

Warning: If the parameter refers to a variable within a Sprite or Movie Clip, refer here for more information on correct calling procedure.

Note: if multiple parameters are optional and one of the right most parametes is specified, then commas must be used to show where the optional parameters would have been placed. eg. fscommand ("Example", "test1,,status")

Note: When Quoting file paths, \\ must be used in place of \ because of Escape Sequence Processing. Path macros have been provided to allow easy access to commonly used directories.

The Usage section demonstrates some example calls to the command. This can be used to emphasise the way in which the optional and default parameters can be used.

The Return Code section indicates the value that is returned in the variable fscmd_ret.

The available commands can be split up into the following groups:

Hardware Information

ODBC Database Commands

Registry Manipulation

ActiveX Commands

Desktop

AccessabilityOptDlg

ControlPanel

DateTimePropDlg

DisplayPropDlg

GetDesktopItemCount

GetDesktopItemIconRect

GetDesktopItemLabel

GetDesktopItemLabelRect

GetDesktopItemRect

VideoGetCurMode

VideoGetAllModes

VideoSetMode

Execute External Program

Exec

Execute

Quit

Run

File / Directory Operations

FileAccess

FileClose

FileCopy

FileDelete

FileOpen

FileRead

FileTempName

FileWrite

FileFindFirst

FileFindNext

FileIsDir

FontsFolder

WriteStr

GetExeDir

PrivateProfileStrings

System Values

SysDiskInfo

SysGetUserName

SysGetLocalTime

SysGetWinDir

SysOsVer

Window Dragging

DragCancel

DragAddEllipse

DragAddPoly

DragAddRect

Window Size and Position

WindowGetPos

WindowSetPos

WindowSetPosRel

WindowSetState

WindowShow

GetScreenSize

MinimizeAll

fullscreen

allowscale

Miscelaneous

Beep

HtmlSafe

mailto

MessageBox

DriveDoor

ShowImage

GetCursorPos


Active X Commands

These FS commands allow you to access various Active X controls.

Please read the Introduction section to see why you may want to use Active X.

For most access, 3 steps are required:

1. Open the connection to the control.

2. Perform operations on the control. This may include calling Methods, Putting or Getting Properties.

3. Close the connection.

Simpler commands (XSAMethod and XSAPropertyGet) requiring only 1 step are also provided for situations where continued connection to the object is not required. However, when using these commands, be aware that the object will normally not have any memory of previous calls that may have altered properties.

Many of the Active X commands provide additional error information. These error numbers are often describe in hexadecimal format. Common error numbers are shown in the table below:

Error number | Common cause
0x80020006 | Named method / property does not exist.
0x80020009 | Memory exception error in OCX. This can be caused by an unresolved internal function.
0x8002000E | Too many parameters.
0x8002000F | Not enough parameters.
0x800401F3 | Connection to OCX cannot be made.


Introduction

An Introduction to ActiveX.

What is it?

ActiveX was developed by Microsoft. Based on COM (Component Object Model) and OLE (Object Linking and Embedding), it defines a set of rules of how applications should share information.

Applications following these rules, can communicate with each other, generally without additional code. This encourages code re-use by allowing cross-platform, language-independent controls.

The defined interface allows most ActiveX applications to be accessed by:

· ASP (Active Server Page) Web pages
· Programming languages such as Visual Basic or Visual C++
· Other ActiveX clients such as some office components.

ActiveX and COM have now largely been superseeded by .NET technology. However ActiveX technology is still useful as:

· There is a large amount of ActiveX components available, some of this content has not been translated to .NET
· It is still a supported technology.
· It integrates will with VB6 and Visual C++ 6.0

What are some examples?

The flash player that is accessed by your browser, is an ActiveX component.

Most components accessed within an ASP page are ActiveX. These include Mailer applications, file upload applications and database interfaces.

What can I do with it?

If you have access to VB (Visual Basic) you can easily create your own ActiveX components to dramatically increase the power of the available FSCommands. See FSCommands ActiveX Tutorial for an example of this. Through this tutorial, (or via the supplied sample DLL), you can access MIDI tones from your sound card via FSCommands.

In most cases, if you have a specific programming task, you can often obtain or purchase an ActiveX control to simplify that task. For example, if you wanted to perform Serial I/O you may consider purchasing "PortController" from Scientific Component. And example of how to interface to their active X component is given in the tutorial FSCommand Active X Serial I/O.

Warning: It is possible that some components cannot work with SWiSH Studio as the interface is limited by the FSCommand format and return values. In addition, the published examples supplied with commercial products will not show you how to use the component from SWiSH Studio. You must read their documentation to determine the Methods and Properties that the component provides, then determine the appropriate ActiveX FSCommands that are necessary to access that component. Due to the large number of available components as well as the different interfaces, we are unable to provide any support on how to interface with a specific component. For more information see the Limitations section.


Limitations

Due to the nature of FSCommands, various ActiveX components cannot be supported. Below is a description of some component attributes that may cause problems. There may be other issues beyond the scope of this list.

1. The FSCommand interface is based on the ActiveX IDispatch interface. ActiveX Components that do not support this interface cannot be called by SWiSH Studio FSCommands.

2. The SWiSH Studio ActiveX interface does not support collections.

3. The SWiSH Studio ActiveX interface does not support methods where one of the parameters is a pointer to a buffer that is to hold return data.

eg. a Method defined as object.ReadBuffer(char * retbuff, int bufflen) is likely to cause problems.

4. As fscommands are sent as a comma separated list, it is difficult to send data that actually contains commas or quotes.

eg. A method that expects a comma separated string cannot be called.

5. Events and callback functions are not supported.

6. Properties must relate to simple items. A property item cannot be a class.


OLE/COM viewer

Many errors associated with ActiveX relate to the object not being registered or called by the correct name. Use the OLE / COM viewer (This is a free download from Microsoft, see oleview-o.) to view the installed components.

Looking up the Alphabetical list of All Objects, you will see all components that are registered on your computer.

Note to see the All Objects option, you must use the menu item "View / Expert".

The image below shows the reference for the PortController class. See the FSCommand ActiveX Serial I/O tutorial for more information on how to use that specific component.

Note that the class has the ProgID=PortControllerMod.PortController.1. Make a note of this name. It is needed for all of the Active X commands.


ActiveX Registration

To access an ActiveX component, it must be registered.

This can be done in two ways:

1. From a command prompt in the ActiveX components directory type "regsvr32 componentname". To unregister the component use the command "regsvr32 -u componentname". The component may have the extension .dll or .ocx

2. Include the DLL or OCX in the dependencies palette of your project, then use the fscommand XOpen to register the component and open the connection to the component within your project. The component will be unregistered when you use XClose, XCloseAll or exit the application.

For the sake of testing, it is probably easier to use approach 1.

However be aware that your project will not work correctly on other computers unless they install and register the ActiveX component. The second method is recommended when you intend to re-distribute your application with the activeX component.


Active X Definitions

Name | Definition
Active X | Subset of OLE. A better description is given in Introduction
Alias Name | An alternate shortened name of the OCX that is specified during the XOpen call. If specified, this shortened name must be used in all subsequent calls to the OCX.
COM | Stands for Component Object Model. This is the underlying technology that is used by Active X and OLE.
Interface | COM objects define various interfaces. The interfaces define how to communicate with an object. Some interfaces follow a standard definition. eg. IUnknown and IDispatch.
Method | A Method is analogous to a function that is contained within an object.
OcxName | This is the name of the ActiveX component. It will often be quoted in the suppliers literature. It can also be found using the oleview.exe see OLE/COM object viewer. For an VB active X dll, the name will be DName.CName where DName is the name of the DLL and CName is the name of the class that contains the functions being referenced.
OLE | OLE was originally an acronym for Object Linking and Embedding. However, it is now referred to simply as OLE. Parts of OLE not related to linking and embedding are now part of Active technology.
Property | A Property is a value that is held internally within the object. It can be used to hold global configuration settings for the object.


XOpen

Command: | XOpen ("OcxName <,AliasName <,DllName>>")
Usage: | fscommand ("XOpen", "xtest.itest, X1")
Return Code: | 0 on success One of the Generic Return Codes on failure A return code of -105 usually indicates that the OcxName is not found. Check that the OCX has been registered under the name you are using. See OLE/COM viewer for information on how to do this.

Parameter

Description

OcxName

Name of the Active X component that you wish to access.

AliasName

Optional alias name for the component that is used in subsequent calls.

DLLName

Name of the DLL to be registered.

This should not be used if the DLL is already loaded and registered on the system.

If used then AliasName must be supplied.

This should be used when the dll is included in the palette. It provides a way of autmatically registering, the unregistering and removing the ocx after the player terminates.

The dll is registered during the XOpen command and un registered during the XClose or XCloseAll commands.

Registration and Unregistering is analogous to using the regsvr32 and regsvr32 -u commands.

Note that XCloseAll is called automatically when the player terminates.

Opens a connection to the named Active X component. Currently there is a limit of 10 simultaneous connections.

This routine must be called before using XMethod, XPropertyGet or XPropertyPut.

On completion, call XClose to close the open connection.

Various reasons for failure include:

1. OcxName not found (Generic failure code. - No additional information.) In this case try the XSAMethod command as this gives additional error reporting.

2. More than 10 connections already open (File open failed.)

Examples

fscommand("XOpen", "mytest.if1, if1, mytest.dll");

Registers the dll mytest.dll and connects to the ActiveX item mytest.if1. The connection is referred to as "if1" in subsequent calls to XMethod, XPropertyGet, XPropertyPut and XClose. The dll mytest.dll is assumed to have been included in the root directory of the dependencies palette. The mytest.dll is un registered after a call to XClose("if1"), XCloseAll() or when the player terminates.

fscommand("XOpen", "mytest.if1, if1");

Assumes that the DLL defining the ActiveX item mytest.if1 has already been registered. The connection is referred to as "if1" in subsequent calls to XMethod, XPropertyGet, XPropertyPut and XClose.

fscommand("XOpen", "mytest.if1");

Assumes that the DLL defining the ActiveX item mytest.if1 has already been registered. The connection is referred to as "mytest.if1" in subsequent calls to XMethod, XPropertyGet, XPropertyPut and XClose.

See Also

XOpen, XMethod, XPropertyGet, XPropertyPut, XClose and XCloseAll


XClose

Command: | XClose ("OcxName")
Usage: | fscommand ("XClose", "xtest.itest")
Return Code: | 0 on success One of the Generic Return Codes on failure

Parameter | Description
OcxName | Name of the Active X component that you wish to access. If an alias name was specified during the XOpen command, then that name should be used here.

Closes an already open connection to the named Active X component.

Various reasons for failure include:

Connection was not previously opened.

In most instances, XCloseAll is easier to use as it closes all open connections with a single call.

See Also

XOpen, XMethod, XPropertyGet, XPropertyPut, XClose and XCloseAll


XCloseAll

Command: | XClose ("")
Usage: | fscommand ("XClose", "")
Return Code: | 0 on success One of the Generic Return Codes on failure

Closes any already open connections.

This can be used in place of multiple XClose calls.

This command is also called automatically when the player exits.

See Also

XOpen, XMethod, XPropertyGet, XPropertyPut and XClose


XMethod

Command: | XMethod ("[out] return, [in] OcxName, [in] MethodName, <[in] ParamN...>")
Usage: | fscommand ("XMethod", "ret.text, xtest.itest, Dist, 4, 5")
Return Code: | 0 on success One of the Generic Return Codes on failure Data from the Method if returned in the supplied return variable. On an error condition, this will contain additional error information.

Parameter | Description
[out] return | Name of the variable to hold the data returned by the method. This will contain additional error information if an error has occured.
[in] OcxName | Name of the Active X component that you wish to access. If an alias name was specified during the XOpen command, then that name should be used here.
[in] MethodName | Name of the Method being accessed.
<[in] ParamN> | Optional Parameters. Exact meaning and length depends on the requirements of the called Method.

Accesses the named Method with the supplied parameters. Connection the the Active X component must have been made previously via a XOpen command.

Various reasons for failure include:

1. Connection not previously opened. ("File not open" error.)

2. Method does not exist. ([0x80020006] in additional error information).

3. Incorrect number of Parameters ([0x8002000F] or [0x8002000E] in additional error information).

See Also

XOpen, XMethod, XSAMethod, XPropertyGet, XPropertyPut and XClose


XPropertyGet

Command: | XPropertyGet ("[out] return, [in] OcxName, [in] PropertyName")
Usage: | fscommand ("XPropertyGet", "ret.text, xtest.itest, Accel")
Return Code: | 0 on success One of the Generic Return Codes on failure Data from the Property is placed in the supplied return variable. On an error condition, this will contain additional error information.

Parameter | Description
[out] return | Name of the variable to hold the data returned by the method. This will contain additional error information if an error has occured.
[in] OcxName | Name of the Active X component that you wish to access. If an alias name was specified during the XOpen command, then that name should be used here.
[in] PropertyName | Name of the Property being accessed.

Returns the value of the named Property.Connection the the Active X component must have been made previously via a XOpen command.

Various reasons for failure include:

1. Connection not previously opened. ("File not open" error.)

2. Property does not exist. ([0x80020006] in additional error information).

See Also

XOpen, XMethod, XPropertyGet, XSAPropertyGet, XPropertyPut and XClose


XPropertyPut

Command: | XPropertyPut ("<[out] return>, [in] OcxName, [in] PropertyName, [in] Value")
Usage: | fscommand ("XPropertyPut", "ret.text, xtest.itest, Accel, 9.8")
Return Code: | 0 on success One of the Generic Return Codes on failure Data from the Property is placed in the supplied return variable. On an error condition, this will contain additional error information.

Parameter | Description
<[out] return> | Optional parameter. If supplied will hold additional error information if an error has occured.
[in] OcxName | Name of the Active X component that you wish to access. If an alias name was specified during the XOpen command, then that name should be used here.
[in] PropertyName | Name of the Property being accessed.
[in] Value | The value that the property is being set to.

Returns the value of the named Property.Connection the the Active X component must have been made previously via a XOpen command.

Various reasons for failure include:

1. Connection not previously opened. ("File not open" error.)

2. Property does not exist. ([0x80020006] in additional error information).

3. Incorrect number of parameters.

See Also

XOpen, XMethod, XPropertyGet, XSAPropertyGet, XPropertyPut and XClose


XSAMethod

Command: | XSAMethod ("[out] return, [in] OcxName, [in] MethodName, <[in] ParamN...>")
Usage: | fscommand ("XSAMethod", "ret.text, xtest.itest, Dist, 4, 5")
Return Code: | 0 on success One of the Generic Return Codes on failure Data from the Method if returned in the supplied return variable. On an error condition, this will contain additional error information.

Parameter | Description
[out] return | Name of the variable to hold the data returned by the method. This will contain additional error information if an error has occured.
[in] OcxName | Name of the Active X component that you wish to access.
[in] MethodName | Name of the Method being accessed.
<[in] ParamN> | Optional Parameters. Exact meaning and length depends on the requirements of the called Method.

Identical to XMethod except that the Connection to the Active X component is dynamically opened and closed within the single command.

Various reasons for failure include:

1. Connection cannot be made. ([0x800401F3] in additional error information indicates OCX does not exist or is not found based on the supplied name.)

2. Method does not exist. ([0x80020006] in additional error information).

3. Incorrect number of Parameters ([0x8002000F] or [0x8002000E] in additional error information).

See Also

XOpen, XMethod, XSAMethod, XPropertyGet, XPropertyPut and XClose


XSAPropertyGet

Command: | XSAPropertyGet ("[out] return, [in] OcxName, [in] PropertyName")
Usage: | fscommand ("XSAPropertyGet", "ret.text, xtest.itest, Accel")
Return Code: | 0 on success One of the Generic Return Codes on failure Data from the Property is placed in the supplied return variable. On an error condition, this will contain additional error information.

Parameter | Description
[out] return | Name of the variable to hold the data returned by the method. This will contain additional error information if an error has occured.
[in] OcxName | Name of the Active X component that you wish to access.
[in] PropertyName | Name of the Property being accessed.

Identical to XPropertyGet except that the Connection to the Active X component is dynamically opened and closed within the single command.

Note that there is no Single Action XSAPropertyPut, because the new property value would be lost as soon as the connection is broken.

Various reasons for failure include:

1. Connection cannot be made. ([0x800401F3] in additional error information indicates OCX does not exist or is not found based on the supplied name.)

2. Property does not exist. ([0x80020006] in additional error information).

See Also

XOpen, XMethod, XPropertyGet, XSAPropertyGet, XPropertyPut and XClose


AccessabilityOptDlg

Command: | AccessabilityOptDlg ([in] tabPage)
Usage: | fscommand("AccessabilityOptDlg", "1")
Return Code: | -99
Parameter | Description
[in] tabPage | 1 = show Keyboard tab 2 = show Sound tab 3 = show Display tab 4 = show Mouse tab 5 = show General tab

Show system Accessability Options dialog with specified tab showing.


AfxMessageBox

Command: | AfxMessageBox ("mssg, <style=0>")
Usage: | fscommand ("AfxMessageBox", "Hello World, 2"); Displays a abort, retry, ignore message box with the text Hello World.
Return Code: | 0 - Error insufficient memory (Error) Depending on the style selected, the return code will indicate the button that was pressed. 1 - IDOK (OK button pressed) 2 - IDCANCEL (Cancel button pressed) 3 - IDABORT (Abort button pressed) 4 - IDRETRY (Retry button pressed) 5 - IDIGNORE (Ignore button pressed) 6 - IDYES (Yes button pressed) 7 - IDNO (No button pressed) 8 - IDCLOSE (Close button pressed) 9 - IDHELP (Help button pressed) 10 - IDTRYAGAIN (Try Again button pressed) 11 - IDCONTINUE (Continue button pressed) 32000 - IDTIMEOUT

Displays a message box on the screen.

Parameter | Description
mssg | Message string to be displayed. If you need to display comma characters, precede the comma with a '\' eg: "Hello \, there".
<style> | Determines the look of the message box. It corresponds to Window's message-box style id codes (default = MB_OK). See styles below.

Other styles include:

Value | Style
0 | MB_OK
1 | MB_OKCANCEL
2 | MB_ABORTRETRYIGNORE
3 | MB_YESNOCANCEL
4 | MB_YESNO
5 | MB_RETRYCANCEL
6 | MB_CANCELTRYCONTINUE
16 | MB_ICONHAND, MB_ICONERROR, MB_ICONSTOP
32 | MB_ICONQUESTION
48 | MB_ICONEXCLAMATION, MB_ICONWARNING
64 | MB_ICONASTERISK, MB_ICONINFORMATION

Note: that the base window style can have the icon type specified by adding the appropriate icon value.

eg. for an OK, Cancel message box with an error icon use the style value (1 + 16 = 17).

See Also: MessageBox


allowscale

Command: | allowscale ("flag")
Usage: | fscommand ("allowscale", "true") fscommand ("allowscale", "false")
Return Code: | 1 on success 0 on failure

Enables or disables content scaling.

If flag = "true" content will scale to window size.

If flag = "false" content will always remain at it's original size.


Beep

Command: | Beep ("<freq = 1000>, <duration = 100>")
Usage: | fscommand ("Beep", "1200, 500")
Return Code: | -99

Generates simple tones on the speaker. First argument specifies the sound frequency, in hertz, while the second specifies the sound duration, in milliseconds.


ControlPanel

Command: | ControlPanel()
Usage: | fscommand ("ControlPanel")
Return Code: | -99

Displays control panel icons in folder view.


DateTimePropDlg

Command: | DateTimePropDlg ([in] tabPage)
Usage: | fscommand("DateTimePropDlg", "0")
Return Code: | -99
Parameter | Description
[in] tabPage | 0 = show Date/Time tab 1 = show Time Zone tab

Show system Date/Time Properties dialog with specified tab showing.


DisplayPropDlg

Command: | DisplayPropDlg ([in] tabPage)
Usage: | fscommand("DisplayPropDlg", "0")
Return Code: | -99
Parameter | Description
[in] tabPage | 0 = show Background tab 1 = show Screensaver tab 2 = show Appearance tab 3 = show Settings tab

Show system Display Properties dialog with specified tab showing.


DragCancel

Command: | DragCancel ("<freq = 1000>, <duration = 100>")
Usage: | fscommand ("DragCancel", "1200, 500")
Return Code: | -99

Removes all currently active dragable hot-spot areas.


DragAddEllipse

Command: | DragAddEllipse ([in] left, [in] top, [in] right, [in] bottom)
Usage: | fscommand("DragAddEllipse", "10,10,200,100")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
[in] left | Left pixel position of ellipse.
[in] top | Top pixel position of ellipse.
[in] right | Right pixel position of ellipse.
[in] bottom | Bottom pixel position of ellipse.

Adds an elliptical region to the current dragable hot-spot area.

See Also: DragAddRect, DragAddPoly, DragCancel


DragAddPoly

Command: | DragAddPoly ([in] x1, [in] y1, [in] x2, [in] y2, [in] x3, [in] y3 <,[in] x4, [in] y4>....<,[in] xn, [in] yn>)
Usage: | fscommand("DragAddPoly", "10,10,20,10,20,50,15,60,5,30")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
[in] x | X ordinate (must have x and y per coordinate).
[in] y | Y ordinate (must have x and y per coordinate).

Adds a polygonal region to the current dragable hot-spot area. There must be an even number of arguments, corresponding to x,y coordinate pairs. At least three coordinates must be present.

See Also: DragAddRect, DragAddEllipse, DragCancel


DragAddRect

Command: | DragAddRect ([in] left, [in] top, [in] right, [in] bottom)
Usage: | fscommand("DragAddRect", "10,10,200,100")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
[in] left | Left pixel position of rectangle.
[in] top | Top pixel position of rectangle.
[in] right | Right pixel position of rectangle.
[in] bottom | Bottom pixel position of rectangle.

Adds an rectangular region to the current dragable hot-spot area.

See Also: DragAddEllipse, DragAddPoly, DragCancel


DragSubEllipse

Command: | DragSubEllipse ([in] left, [in] top, [in] right, [in] bottom)
Usage: | fscommand("DragSubEllipse", "10,10,200,100")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
[in] left | Left pixel position of ellipse.
[in] top | Top pixel position of ellipse.
[in] right | Right pixel position of ellipse.
[in] bottom | Bottom pixel position of ellipse.

Subtracts an elliptical region from the current dragable hot-spot area.

See Also: DragSubRect, DragSubPoly, DragCancel


DragSubPoly

Command: | DragSubPoly ([in] x1, [in] y1, [in] x2, [in] y2, [in] x3, [in] y3 <,[in] x4, [in] y4>....<,[in] xn, [in] yn>)
Usage: | fscommand("DragSubPoly", "10,10,20,10,20,50,15,60,5,30")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
[in] x | X ordinate (must have x and y per coordinate).
[in] y | Y ordinate (must have x and y per coordinate).

Subtracts a polygonal region from the current dragable hot-spot area. There must be an even number of arguments, corresponding to x,y coordinate pairs. At least three coordinates must be present.

See Also: DragSubRect, DragSubEllipse, DragCancel


DragSubRect

Command: | DragSubRect ([in] left, [in] top, [in] right, [in] bottom)
Usage: | fscommand("DragSubRect", "10,10,200,100")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
[in] left | Left pixel position of rectangle.
[in] top | Top pixel position of rectangle.
[in] right | Right pixel position of rectangle.
[in] bottom | Bottom pixel position of rectangle.

Subtracts a rectangular region from the current dragable hot-spot area.

See Also: DragSubEllipse, DragSubPoly, DragCancel


DriveDoor

Command: | DriveDoor (<Drive=\001>, <status=o>)
Usage: | fscommand("DriveDoor", "") - open the default CD drive fscommand("DriveDoor", ",c") - close the default CD drive fscommand("DriveDoor", "z") - open CD drive Z fscommand("DriveDoor", "z,o") - open CD drive Z fscommand("DriveDoor", "z,c") - close CD drive Z
Return Code: | None. Returns -99
Parameter | Description
<Drive=\001> | Drive letter. If omitted, default drive is accessed. "\001" can also be used to define default drive.
<status=0> | Optional. If omitted, default action is to open. Other options are o or O for open, c or C for close.

Opens or closes the CD drive door.


Exec

Command: | Exec ("file")
Usage: | fscommand ("Exec", "SWiSHstudio.exe")
Return Code: | <= 32 indicates error, > 32 indicates success. The meaning of the error code is documented in Windows ShellExecute API documentation.

This is a shorthand version of the Execute command – it executes the file specified without any arguments being passed to it. The main application window will be used to display any messages.

Note that Path Macros can be quoted.


Execute

Command: | Execute ("hwnd, operation, file, params, <dir>, <show = 5>")
Usage: | fscommand ("Execute", "1202112, open, tutorial.exe, tutstudio.txt,,5")
Return Code: | <= 32 indicates error, > 32 indicates success. The meaning of the error code is documented in Windows ShellExecute API documentation.

Use this function to open or explore a folder, execute a file and pass arguments to file being executed. The show values correspond to Window's 'SW_' codes (SW_SHOW = 5).

Note: Path Macros can be quoted.


FileAccess

Command: | FileAccess (path, <mode=0>)
Usage: | fscommand("FileAccess", ".\\test.txt, 6") - see if file exists with R/W permissions. fscommand("FileAccess",".\\test.txt") - see if file exists (any permissions). fscommand("FileAccess","c:\\temp") - see if the directory temp exists.
Return Code: | Returns one of the generic error codes. 0 indicates exists with specified permissions -1002 indicates file / directory does not exist -1013 indicates file / directory exists but not with specified permissions

Parameter | Description
path | Name of the file or directory to be tested. Use .\\ if you wish to read a file in the current working directory. Path Macros can be quoted.
<mode=0> | Optional. If omitted, file is just tested for existance. The following values can also be used: 00 Existence only 02 Write permission 04 Read permission 06 Read and write permission

Determine file or directory-access permission.


FileClose

Command: | FileClose ("[in] id")
Usage: | fscommand ("FileClose", "2")
Return Code: | Returns one of the generic error codes.
Parameter | Description
[in] id | User supplied number that is used to identify the file from previous file operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous files.

Accessing a file via the FileOpen, FileClose, FileRead and FileWrite functions requires the functions to be called in a specific order. Failure to call the functions in the required order (or to failure to wait for their completion) can cause some unpredictable results. Please see section, FS Commands are Non Blocking for an example of how to call these functions in a sequenced manner.


FileCopy

Command: | FileCopy (path1, path2, <copyifexists=N>)
Usage: | fscommand("FileCopy", ".\\test.txt,.\\test2.txt,Y") - copy file even if .\test2.txt exists. fscommand("FileCopy", ".\\test.txt,.\\test2.txt) - copy file but fail if .\test2.txt already exists.
Return Code: | Returns one of the generic error codes.
Parameter | Description
path1 | Name of the file to be top be copied. Use .\\ if you wish to read a file in the current working directory. Path Macros can be quoted.
path2 | Name of the destination file. Use .\\ if you wish to read a file in the current working directory. Path Macros can be quoted.
<copyifexists=N> | Optional. If omitted, copy fails if destination file already exists. Specify Y to force copy to destination file irrespective of existance.

Copies file specified by path1 parameter into the file specified by path2.


FileDelete

Command: | FileDelete ([in] pathname)
Usage: | fscommand("FileDelete", "test.txt"); fscommand("FileDelete", "c:\\pictures\\myfolder");
Return Code: | Returns one of the generic error codes.
Parameter | Description
[in] pathname | Name of the file or folder to be deleted. If no path is specified, the current working directory is assumed. If pathname is a folder, then the folder and all it's contents (including files and other sub-folders) will be deleted. Path Macros can be quoted.

Deletes the named file or folder.


FileFindFirst

Command: | FileFindFirst ("[in] pathname, [out] filename <,[in] fileFilter> <,[in] sortOrder>")
Usage: | fscommand ("FileFindFirst", "c:\\myfolder, filename") fscommand ("FileFindFirst", "c:\\myfolder, filename, *.swf") fscommand ("FileFindFirst", "c:\\myfolder, filename, *.swf, A") fscommand ("FileFindFirst", "c:\\myfolder, filename,, Z")
Return Code: | 1 - if filename is returned in argument 'filename'. 0 - if no filename is returned (folder is empty or doesn't exist).

Parameter | Description
[in] pathname | Specifies the folder pathname from which filenames will be returned.
[out] filename | Returns the name of the first file in the specified folder.
<[in] fileFilter> | An optional wildcard mask, such as "*.swf". Used to limit the file search to a subset of files found in the folder. Default: *.*
<[in] sortOrder> | "A" specifies that the files will be returned in ascending alphabetical order. "Z" specifies that the files will be returned in reverse alphabetical order. Default: A

Gets the first filename from the specified folder, according to the the optional file filter mask and sort order.

Note that only the filenames are returned, ie, not including the folder path.


FileFindNext

Command: | FileFindNext ("[out] filename")
Usage: | fscommand ("FileFindNext", "filename")
Return Code: | 1 - if filename is returned in argument 'filename'. 0 - if no filename is returned (end of files).

Parameter | Description
[out] filename | Returns the name of the next file in the previously specified folder (see FileFindFirst).

Gets the next filename from a previosuly specified folder.

Note that only the filenames are returned, ie, not including the folder path.


FileIsDir

Command: | FileIsDir ("[in] pathname")
Usage: | fscommand ("FileIsDir", "pathname")
Return Code: | 1 - if pathanme is a folder. 0 - if pathname is not a folder.

Determines whether or not the specified pathname is a folder.


FileOpen

Command: | FileOpen ("id, path, <mode=r>")
Usage: | fscommand ("FileOpen", "2,.\\test.txt,r") open file for reading fscommand("FileOpen", "2,.\\test.txt,a") open file for appending
Return Code: | Returns one of the generic error codes.

Parameter

Description

id

User supplied number that is used to identify the file in subsequent file operations.

Numbers in the range 1..10 are permited. This allows up to 10 simultaneous files.

path

Name of the file to be opened. Use .\\ if you wish to read a file in the current working directory.

Path Macros can be quoted.

<mode=r>

Optional. If omitted, the mode is assumed to be read. (file must exist or error will be returned).

"r" - Opens for reading. If the file does not exist or cannot be found, the call fails.

"w" - Opens an empty file for writing. If the given file exists, its contents are destroyed.

"a" - Opens for writing at the end of the file (appending) without removing the EOF marker before writing new data to the file; creates the file first if it doesn't exist.

"a+" - Opens for reading and appending; the appending operation includes the removal of the EOF marker before new data is written to the file and the EOF marker is restored after writing is complete; creates the file first if it doesn't exist.

When a file is opened with the "a" or "a+" access type, all write operations occur at the end of the file.

The "a" mode does not remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. The "a+" mode does remove the EOF marker before appending to the file. After appending, the MS-DOS TYPE command shows all data in the file. The "a+" mode is required for appending to a stream file that is terminated with the CTRL+Z EOF marker.

In addition to the above values, the following characters can be included in mode to specify the translation mode for newline characters:

t - Open in text (translated) mode. In this mode, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading/writing with "a+", fopen checks for a CTRL+Z at the end of the file and removes it, if possible.

Also, in text mode, carriage return–linefeed combinations are translated into single linefeeds on input, and linefeed characters are translated to carriage return–linefeed combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the mbtowc function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the wctomb function).

b - Open in binary (untranslated) mode; translations involving carriage-return and linefeed characters are suppressed.

x - Allows file to be read and displayed as hex values (1 per byte). This mode is mainly used to support reading and writing of files that contain binary data.

eg. A file containing ascii "1234" when read will return "31 32 33 34" 31, being the hex ascii value for 1 etc. When data is written, the data is assumed to be in ascii byte format.

d - Allows file to be read and displayed as decimal values (1 per byte). This mode is mainly used to support reading and writing of files that contain binary data.

eg. A file containing "1234" when read will return "49 50 51 52" 49, being the decimal value for the ascii code for "1" etc. When data is written, the data is assumed to be in ascii byte format.

Note, your script must use FileClose to close the open file on completion.

Accessing a file via the FileOpen, FileClose, FileRead and FileWrite functions requires the functions to be called in a specific order. Failure to call the functions in the required order (or to failure to wait for their completion) can cause some unpredictable results. Please see section, FS Commands are Non Blocking for an example of how to call these functions in a sequenced manner.


AsciiByteFormat

This format expects the string to contain numbers which are converted to binary values before writing to the file.

This format can express both hexadecimal xHH (Note: no leading 0 as in 0xHH) as well as decimal NNN.

H represents a hex digit 0..9, a..f or A..F and N represents a decimal digit 0..9.

Each number must be separated by a non digit character. 'x' is an allowable separation character.

eg. "102 31 45" will write the byte codes 102, 31 and 45 to the file. Each number must be less than 256.

eg. "xFAx25x10" will write the hex byte codes 0xFA (250 decimal), 0x25 (37 decimal) and 0x10 (16 decimal) to the file.

Note that mixed decimal and hexadecimal representation is allowed.

eg. "102 xFA x25 31" will write decimal values 102, 250, 37 and 31 to the file.


FileMkDir

Command: | FileMkDir (path)
Usage: | fscommand("FileMkDir", "c:\\tmp\\test123")
Return Code: | None (-99)

Parameter | Description
path | Name of the directory to be opened. Use .\\ if you wish to open a path relative to the current working directory. Path Macros can be quoted.

Create the quoted directory path. Intermediate directories are created if needed.


FileMove

Command:

FileMove (path1, path2, <Options = 0>)

Usage:

fscommand("FileMove", ".\\test.txt,.\\test2.txt") - rename test1.txt test2.txt

fscommand("FileMove", ".\\test.txt,.\\test2.txt, 1") - rename test1.txt to test2.txt even if test2.txt already exists.

Return Code:

Returns one of the generic error codes.

Parameter

Description

path1

Name of the file to be top be copied. Use .\\ if you wish to read a file in the current working directory.

Path Macros can be quoted.

path2

Name of the destination file. Use .\\ if you wish to read a file in the current working directory.

Path Macros can be quoted.

<options=0>

Optional. Option codes.

Add the codes below to enable the named options.

eg. Option 3 means MOVEFILE_REPLACE_EXISTING and MOVEFILE_COPY_ALLOWED

MOVEFILE_REPLACE_EXISTING (1)

If a file named in path2 exists, the function replaces its contents with the contents of the path1 file.

This value cannot be used if path1 or path2 names a directory.

MOVEFILE_COPY_ALLOWED (2)

If the file is to be moved to a different volume, the function simulates the move by using the CopyFile and DeleteFile functions.

This value cannot be used with MOVEFILE_DELAY_UNTIL_REBOOT.

MOVEFILE_DELAY_UNTIL_REBOOT (4)

The system does not move the file until the operating system is restarted. The system moves the file immediately after AUTOCHK is executed, but before creating any paging files. Consequently, this parameter enables the function to delete paging files from previous startups.

This value can be used only if the process is in the context of a user who belongs to the administrator group or the LocalSystem account.

This value cannot be used with MOVEFILE_COPY_ALLOWED.

MOVEFILE_WRITE_THROUGH (8)

The function does not return until the file has actually been moved on the disk.

Setting this value guarantees that a move performed as a copy and delete operation is flushed to disk before the function returns. The flush occurs at the end of the copy operation.

This value has no effect if MOVEFILE_DELAY_UNTIL_REBOOT is set.

MOVEFILE_CREATE_HARDLINK (16)

Reserved for future use.

MOVEFILE_FAIL_IF_NOT_TRACKABLE (32)

Windows 2000 and later: The function fails if the source file is a link source, but the file cannot be tracked after the move. This situation can occur if the destination is a volume formatted with the FAT file system.

Moves / Renames the file specified by path1 parameter into the file specified by path2.

This function can be used to rename directories.

Depending on the chosen options, this may be achieved by renaming the file, or copying the file and deleting the original .


FileRead

Command: | FileRead ("[in] id, [out] data, <mode=L>")
Usage: | fscommand ("FileRead", "2, txt1, 10") read 10 characters from the current position. fscommand ("FileRead", "2, txt1") read a line from the current position.
Return Code: | Returns one of the generic error codes.

Parameter | Description
[in] id | User supplied number that is used to identify the file from previous file operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous files.
[out] data | Name of the variable that is to hold the returned data.
<mode=L> | Optional. If omitted, the next line of data is read. Alternative is to specify a number. If a number is specified, up to that many characters will be read. (Note that using very large numbers, may impact on system performance).

Note1: The file must have been previously opened via the FileOpen command. Your script must use FileClose to close the open file on completion.

Note2: If reading a binary file that was opened using the 'x' mode modifier, data will be returned as Hex Data in ascii format. eg. "31 32 33 34" if the file contains the data "1234".

Note3: If reading a binary file that was opened using the 'd' mode modifier, data will be returned as Decimal Data in ascii. eg. "49 50 51 52" if the file contains the data "1234".

Accessing a file via the FileOpen, FileClose, FileRead and FileWrite functions requires the functions to be called in a specific order. Failure to call the functions in the required order (or to failure to wait for their completion) can cause some unpredictable results. Please see section, FS Commands are Non Blocking for an example of how to call these functions in a sequenced manner.


FileSize

Command: | FileSize ("[in] path, [out] size")
Usage: | fscommand ("FileSize", ".\\test.txt,txt1")
Return Code: | Returns one of the generic error codes.

Name of the file to be opened. Use .\\ if you wish to read a file in the current working directory.

Parameter | Description
[in] path | Name of the file to be sized. Use .\\ if you wish to read a file in the current working directory. Path Macros can be quoted.
[out] size | The name of the variable that will hold the size information.

Returns the size (in bytes) of the file named by the path parameter.


FileTempName

Command: | FileTempName ([out] path)
Usage: | fscommand("FileTempName", "txt1")
Return Code: | Returns one of the generic error codes. Filename is returned in the variable specified by path.
Parameter | Description
path | Name of the variable that will contain the path and filename.

Returns the full path to a temporary filename.


FileWrite

Command: | FileWrite ("id, data")
Usage: | fscommand ("FileWrite", "2,hi this is a test\n2nd line\n")
Return Code: | Returns one of the generic error codes.

Parameter | Description
id | User supplied number that is used to identify the file from previous file operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous files.
data | The data to be written.

Note1: The newline character translation will depend on the mode in which the file is opened. See FileOpen for more information.

Note2: The file must have been previously opened via the FileOpen command. Your script must use FileClose to close the open file on completion.

Note3: If the file was opened with the 'x' or 'd' modifiers, data must be presented using the AsciiByteFormat.

Accessing a file via the FileOpen, FileClose, FileRead and FileWrite functions requires the functions to be called in a specific order. Failure to call the functions in the required order (or to failure to wait for their completion) can cause some unpredictable results. Please see section, FS Commands are Non Blocking for an example of how to call these functions in a sequenced manner.


FontsFolder

Command: | FontsFolder()
Usage: | fscommand ("FontsFolder")
Return Code: | -99

Displays the system fonts folder.


fullscreen

Command: | fullscreen ("flag")
Usage: | fscommand ("fullscreen", "true") fscommand ("fullscreen", "false")
Return Code: | 1 on success 0 on failure

Sets/resets fullscreen window mode.

If flag = "true" window will cover the whole screen.

If flag = "false" window will be restored to it's previous size and position.

This command will only work with non-Transparent windows.


GetCursorPos

Command: | GetCursorPos ([out] x, [out] y)
Usage: | fscommand("GetCursorPos", "x, y")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
x | Horizontal cursor position.
y | Vertical cursor position.

Retrieves the cursor's x,y position, in screen coordinates.


GetDesktopItemCount

Command: | GetDesktopItemCount (<[out] count>)
Usage: | fscommand("GetDesktopItemCount", "count") fscommand("GetDesktopItemCount", "")
Return Code: | Number of desktop items.
Parameter | Description
count | Number of desktop items.

Retrieves the total number of desktop items.


GetDesktopItemIconRect

Command: | GetDesktopItemIconRect ([in] index, <[out] left> <, [out] top> <, [out] right>, <[out] bottom>)
Usage: | fscommand("GetDesktopItemIconRect", "0, left, top, right, bottom") fscommand("GetDesktopItemIconRect", "1, left, top")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
index | Zero based index of desktop item.
left | Left screen position of desktop item.
top | Top screen position of desktop item.
right | Right screen position of desktop item.
bottom | Bottom screen position of desktop item.

Retrieves the bounding rectangle of the icon of desktop item 'index'.

See Also: GetDesktopItemLabelRect, GetDesktopItemRect


GetDesktopItemLabel

Command: | GetDesktopItemLabel ([in] index, [out] label)
Usage: | fscommand("GetDesktopItemLabel", "0, label")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
index | Zero based index of desktop item.
label | The text label associated with specified item.

Retrieves text label of desktop item 'index'.


GetDesktopItemLabelRect

Command: | GetDesktopItemLabelRect ([in] index, <[out] left> <, [out] top> <, [out] right>, <[out] bottom>)
Usage: | fscommand("GetDesktopItemLabelRect", "0, left, top, right, bottom") fscommand("GetDesktopItemLabelRect", "1, left, top")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
index | Zero based index of desktop item.
left | Left screen position of desktop item.
top | Top screen position of desktop item.
right | Right screen position of desktop item.
bottom | Bottom screen position of desktop item.

Retrieves the bounding rectangle of the label of desktop item 'index'.

See Also: GetDesktopItemIconRect, GetDesktopItemRect


GetDesktopItemRect

Command: | GetDesktopItemRect ([in] index, <[out] left> <, [out] top> <, [out] right>, <[out] bottom>)
Usage: | fscommand("GetDesktopItemRect", "0, left, top, right, bottom") fscommand("GetDesktopItemRect", "1, left,top")
Return Code: | 1 - if successful 0 - if unsuccessful

Parameter | Description
index | Zero based index of desktop item.
left | Left screen position of desktop item.
top | Top screen position of desktop item.
right | Right screen position of desktop item.
bottom | Bottom screen position of desktop item.

Retrieves the bounding rectangle of desktop item 'index' (including the label and icon area).

See Also: GetDesktopItemIconRect, GetDesktopItemLabelRect


GetExeDir

Command: | GetExeDir ("<[out] path>")
Usage: | fscommand ("GetExeDir", "") fscommand ("GetExeDir", "path")
Return Code: | current dir path of executing application with a trailing '\'.

Returns the executing application's current directory. If an argument is specified, the path will also be returned into the argument.


GetScreenSize

Command: | GetScreenSize ("<[out] wd>, <[out] ht>")
Usage: | fscommand ("GetScreenSize", "wd, ht") fscommand ("GetScreenSize", "wd") fscommand ("GetScreenSize", ",ht")
Return Code: | -99

Returns the current screen width and height in pixels. The width value is stored in variable 'wd' and the height in 'ht'. You may retrieve either both values at once, or either separately (see usage examples).


HardwareInformation

These commands provide hardware information about the system, hard disks and CPU.


GetCpuIdStr

Command: | GetCpuIdStr ("[out] idStr")
Usage: | fscommand ("GetCpuIdStr", "id")
Return Code: | 1 on success. 0 on error.
Parameter | Description
idStr | Returned string value containing the CPU id string.

Retrieves the CPU id string.


GetCpuManStr

Command: | GetCpuManStr ("[out] manStr")
Usage: | fscommand ("GetCpuManStr", "man")
Return Code: | 1 on success. 0 on error.
Parameter | Description
manStr | Returned string value containing the CPU manufacturer string.

Retrieves the CPU manufacturer string.


GetCpuTypeStr

Command: | GetCpuTypeStr ("[out] typeStr")
Usage: | fscommand ("GetCpuTypeStr", "type")
Return Code: | 1 on success. 0 on error.
Parameter | Description
typeStr | Returned string value containing the CPU type string.

Retrieves the CPU type string.


GetCpuVerStr

Command: | GetCpuVerStr ("[out] verStr")
Usage: | fscommand ("GetCpuVerStr", "ver")
Return Code: | 1 on success. 0 on error.
Parameter | Description
verStr | Returned string value containing the CPU version number string.

Retrieves the CPU version number string.


GetDiskCylinders

Command: | GetDiskCylinders ("[in] diskNumber, [out] cylinders")
Usage: | fscommand ("GetDiskCylinders", "0,cylinders")
Return Code: | 1 on success. 0 on error.
Parameter | Description
diskNumber | Zero based disk identifier (0 is the primary system disk).
cylinders | Returned int value containing the number of cylinders supported by the specified disk.

Retrieves the number of cylinders supported by the specified disk.


GetDiskHeads

Command: | GetDiskHeads ("[in] diskNumber, [out] heads")
Usage: | fscommand ("GetDiskHeads", "0,heads")
Return Code: | 1 on success. 0 on error.
Parameter | Description
diskNumber | Zero based disk identifier (0 is the primary system disk).
heads | Returned int value containing the number of read/write heads for specified disk.

Retrieves the number of read/write heads for specified disk.


GetDiskModelStr

Command: | GetDiskModelStr ("[in] diskNumber, [out] modelStr")
Usage: | fscommand ("GetDiskModelStr", "0,model")
Return Code: | 1 on success. 0 on error.
Parameter | Description
diskNumber | Zero based disk identifier (0 is the primary system disk).
modelStr | Returned string value containing the disk model string.

Retrieves the disk model string.


GetDiskSectorPerTrack

Command: | GetDiskSectorPerTrack ("[in] diskNumber, [out] sectors")
Usage: | fscommand ("GetDiskSectorPerTrack", "0,sectors")
Return Code: | 1 on success. 0 on error.
Parameter | Description
diskNumber | Zero based disk identifier (0 is the primary system disk).
cylinders | Returned int value containing the number of sectors per track for the specified disk.

Retrieves the number of sectors per track for the specified disk.


GetDiskSerialStr

Command: | GetDiskSerialStr ("[in] diskNumber, [out] serialStr")
Usage: | fscommand ("GetDiskSerialStr", "0,serial")
Return Code: | 1 on success. 0 on error.
Parameter | Description
diskNumber | Zero based disk identifier (0 is the primary system disk).
serialStr | Returned string value containing the disk serial number string.

Retrieves the serial number string belonging to the specified system hard disk.


GetSysManStr

Command: | GetSysManStr ("[out] verStr")
Usage: | fscommand ("GetSysManStr", "ver")
Return Code: | 1 on success. 0 on error.
Parameter | Description
verStr | Returned string value containing the system manufacturer string.

Retrieves the system manufacturer string.


GetSysProdNameStr

Command: | GetSysProdNameStr ("[out] prodStr")
Usage: | fscommand ("GetSysProdNameStr", "prod")
Return Code: | 1 on success. 0 on error.
Parameter | Description
prodStr | Returned string value containing the system product name string.

Retrieves the system product name string.


GetSysSerialStr

Command: | GetSysVerStr ("[out] serialStr")
Usage: | fscommand ("GetSysVerStr", "serial")
Return Code: | 1 on success. 0 on error.
Parameter | Description
serialStr | Returned string value containing the system serial number string.

Retrieves the system serial number string.


GetSysVerStr

Command: | GetSysVerStr ("[out] verStr")
Usage: | fscommand ("GetSysVerStr", "ver")
Return Code: | 1 on success. 0 on error.
Parameter | Description
verStr | Returned string value containing the system version number string.

Retrieves the system version number string.


HtmlSafe

Command: | HtmlSafe ("htmlstring")
Usage: | fscommand ("HtmlSafe", "test 1 2 3 \\") Note that \ must be entered as \\ because of FS Command Escape Sequences
Return Code: | Returns html safe string in fscmd_ret returns -101 on error (insufficient parametrs)

Character | Converted to:
space | %20
& | %26
' | removed from string
# | %22
/ | %2F
\ | %5C
carriage return (\r) | removed from string
line feed (\n) | %0A

Converts the following characters to in the input string into HTML safe versions.


mailto

Command: | mailto ("emailAddress")
Usage: | fscommand ("mailto", "fred@hotmail.com")
Return Code: | <= 32 indicates error, > 32 indicates success. The meaning of the error code is documented in Windows ShellExecute API documentation.

This command will automatically invoke the default email client, setting the 'To' email adress with that supplied by the command argument.


MessageBox

Command: | MessageBox ("mssg, title, <style=0>, <helpId=0>")
Usage: | fscommand ("MessageBox", "Hello World, MyTitle, 3"); displays a yes no cancel message box with title "MyTitle" and the message "Hello World"
Return Code: | 0 - Error insufficient memory (Error) Depending on the style selected, the return code will indicate the button that was pressed. 1 - IDOK (OK button pressed) 2 - IDCANCEL (Cancel button pressed) 3 - IDABORT (Abort button pressed) 4 - IDRETRY (Retry button pressed) 5 - IDIGNORE (Ignore button pressed) 6 - IDYES (Yes button pressed) 7 - IDNO (No button pressed) 8 - IDCLOSE (Close button pressed) 9 - IDHELP (Help button pressed) 10 - IDTRYAGAIN (Try Again button pressed) 11 - IDCONTINUE (Continue button pressed) 32000 - IDTIMEOUT

Displays a message box on the screen with a user defined title bar caption.

Parameter | Description
mssg | Message string to be displayed. If you need to display comma characters, precede the comma with a '\' eg: "Hello \, there".
title | String displayed in the title bar.
<style> | Determines the look of the message box. It corresponds to Window's message-box style id codes (default = MB_OK). See styles below.
<helpId> | Help-context ID for the message - default 0 indicates the application's default Help context will be used.

Other styles include:

Value | Style
0 | MB_OK
1 | MB_OKCANCEL
2 | MB_ABORTRETRYIGNORE
3 | MB_YESNOCANCEL
4 | MB_YESNO
5 | MB_RETRYCANCEL
6 | MB_CANCELTRYCONTINUE
16 | MB_ICONHAND, MB_ICONERROR, MB_ICONSTOP
32 | MB_ICONQUESTION
48 | MB_ICONEXCLAMATION, MB_ICONWARNING
64 | MB_ICONASTERISK, MB_ICONINFORMATION

Note: that the base window style can have the icon type specified by adding the appropriate icon value.

eg. for an OK, Cancel message box with an error icon use the style value (1 + 16 = 17).

See Also: AfxMessageBox


MinimizeAll

Command: | MinimizeAll (<[in] minimize=true>)
Usage: | fscommand("MinimizeAll", "false") fscommand("MinimizeAll", "")
Return Code: | -99
Parameter | Description
minimize | if true - minimizes all windows. if false - restores all previously minimized windows to original positions.

Minimize/restore all windows.


ODBC Database Commands

These FS commands allow access to any database that is configured as a ODBC data source.

The following are possible command sequences that can be used to access a database:

To execute a SQL command that manipulates the database but does not return any values.

eg. To delete a record from the database

1. DBOpen

2. DBExecSQL (eg. delete from mytab where id=100)

3. DBClose

To execute a SQL command that retrieves information from the database.

eg. To view all records with a score greater than 80

1. DBOpen

2. DBDoSQL (eg. select * from mytab where score > 80 order by score desc)

3. For each field of interest: DBGetFieldVal | DBGetFieldType | DBGetFieldName

4. DBMoveNext - Repeat step 3 if not last record to obtain data for all records.

5. DBClose

The ODBC Database Commands return Generic Error Codes on failure.

See the command description for the values that are returned on success.

The ODBC commands use a file id system similar to that used by the various file commands. The numbers 1..10 are available for use as a file id. This allows up to 10 simultaneous databases to be open.


ODBC Example Script

Badly constructed ODBC commands, appear to cause the driver to hang. Consequently it is useful to build a timeout facility into your scrips when they call the ODBC routines.

Below is a sample script that makes a number of ODBC calls and processes timeouts correctly.

The example opens a database and returns a count of the number of students who's score exceeded 50.

In the example below, both ret and txt1 are dynamic text objects that are used to display return values.

Note: There is a spare (empty) frame before each of the wait loops on frames 3, 5 and 7.

This frame based processing is necessary due to the Non Blocking nature of FS Commands.

onFrame (1) {

trycount = 0;

fscmd_ret = "";

fscommand("DBOpen","1,ODBC;DATABASE=students;UID=sa;PWD=mypassword;DSN=students_sql");

}

onFrame (3) {

if (("" == fscmd_ret) && (trycount++ < 10)) {

prevFrameAndPlay();

}

ret = (trycount >= 10) ? "timeout":fscmd_ret;

// expect 0 on success

if (0 != ret) {

gotoSceneAndPlay("Scene_Error",1);

}

// count number of students that passed.

trycount = 0;

fscmd_ret = "";

fscommand("DBDoSQL","1,select count (*) from students where score > 50");

}

onFrame (5) {

if (("" == fscmd_ret) && (trycount++ < 10)) {

prevFrameAndPlay();

}

ret = (trycount >= 10) ? "timeout":fscmd_ret;

// expect single field, the count from the database

if (ret != 1) {

gotoSceneAndPlay("Scene_Error",1);

}

// read the count into text variable txt1

trycount = 0;

fscmd_ret = "";

fscommand("DBGetFieldVal","1,0,txt1");

}

onFrame (7) {

if (("" == fscmd_ret) && (trycount++ < 10)) {

prevFrameAndPlay();

}

ret = (trycount >= 10) ? "timeout":fscmd_ret;

// expect a value >= 0

if (ret == "timeout" || ret < 0) {

gotoSceneAndPlay("Scene_Error",1);

}

// close the database (similar statement in Scene_Error)

fsCommand("DBClose","1");

}


DBClose

Command: | DBClose ("id")
Usage: | fscommand ("DBClose", "2") - close the previously opened database with the id 2
Return Code: | Returns one of the generic error codes on error. Returns 0 on success.

Parameter | Description
id | User supplied number that is used to identify the database from previous database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.

Closes a dabase that was previoiusly opened via a DBOpen command.


DBDoSQL

Command: | DBDoSQL ("id, sql")
Usage: | fscommand ("DBDoSQL", "2,select count (*) from mytable") - find number of records fscommand ("DBDoSQL", "2,select * from mytable") - fill record set with table
Return Code: | Returns one of the generic error codes on error. Returns number of fields contained in the returned record set on success. 0 is returned if record set contains no data.

Parameter | Description
id | User supplied number that is used to identify the database in subsequent database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.
sql | SQL string. This string must be a select type SQL statement as the intention of this command is to fill a recordset. For insert, update and delete type SQL strings, use DBExecSQL

This command fills a recordset according to the specified SQL select statement.

Once data has been retrieved via a DBDoSQL statement, the commands DBGetFieldVal, DBGetFieldName and DBGetFieldType can be used to read data or obtain information about a specific database field.

After a call to DBDoSQL, the recordset is positioned at the first record of the returned data. It is possible to move to subsequent records using the DBMoveNext command

Note, your script must use DBClose to close the open database on completion.


DBExecSQL

Command: | DBExecSQL ("id, sql")
Usage: | fscommand ("DBExecSQL", "2,delete from students where score=40") fscommand ("DBExecSQL", "2,update students set score=41 where studentid=20")
Return Code: | Returns one of the generic error codes on error. Returns 0 on completion, however failures of the command to execute due to syntax errors are not returned.

Parameter | Description
id | User supplied number that is used to identify the database in subsequent database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.
sql | SQL string. This string should be a command type SQL statement that does not return data. eg. insert, update and delete. To retrieve data from the database use DBDoSQL.

This command executes the specifid SQL string. Unlike DBDoSQL, this command does not return data.

Note: Your script must use DBClose to close the open database on completion.


DBGetFieldName

Command: | DBGetFieldName ("id, field, [out] data")
Usage: | fscommand ("DBGetFieldName", "2,5,txt1")
Return Code: | Returns one of the generic error codes on error. Returns the field number on success. The field name is returned in the data parameter.

Parameter | Description
id | User supplied number that is used to identify the database in subsequent database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.
field | The field number in the record set. This number should be less than the number of fields returned by DBDoSQL. Note that the first field in a record is numbered 0.
[out] data | The variable that is to hold the field name.

Returns the name of a numbered field. The name corresponds to the data obtained from the most recent DBDoSQL call.

This command can be used to obtain column headings for the database if they are unknown.

Note: This command can only be used if DBDoSQL has been called previously.

Note: Your script must use DBClose to close the open database on completion of all database access.


DBGetFieldType

Command: | DBGetFieldType ("id, field, [out] data")
Usage: | fscommand ("DBGetFieldType", "2,5,txt1") - get via field number fscommand ("DBGetFieldType", "2,student_name,txt1") - get via field name
Return Code: | Returns one of the generic error codes on error. Returns the field number on success. The field data type is returned in the data parameter.

Parameter | Description
id | User supplied number that is used to identify the database in subsequent database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.
field | The field number or name in the record. If a number is quoted it should be less than the number of fields returned by DBDoSQL. Note: The first field in a record is numbered 0. Note: Field names if quoted are case insensitive.
[out] data | The variable that is to hold the data.

Returns the data type of the named or numbered field.

The data type will be one of the following strings:

"UNKNOWN_TYPE"

"CHAR"

"NUMERIC"

"DECIMAL"

"INTEGER"

"SMALLINT"

"FLOAT"

"REAL"

"DOUBLE"

"DATETIME"

"TIME"

"TIMESTAMP"

"VARCHAR"

This command can be used to find out the characteristics of an unknown database who's scheme is not known.

Note: This command can only be used if DBDoSQL has been called previously.

Note: Your script must use DBClose to close the open database on completion of all database access.


DBGetFieldVal

Command: | DBGetFieldVal ("id, field, [out] data")
Usage: | fscommand ("DBGetFieldVal", "2,5,txt1") - get via field number fscommand ("DBGetFieldVal", "2,student_name,txt1") - get via field name
Return Code: | Returns one of the generic error codes on error. Returns the field number on success. The field's data is returned in the data parameter.

Parameter | Description
id | User supplied number that is used to identify the database in subsequent database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.
field | The field number or name in the record. If a number is quoted it should be less than the number of fields returned by DBDoSQL. Note: The first field in a record is numbered 0. Note: Field names if quoted are case insensitive.
[out] data | The variable that is to hold the data.

Returns the data from the named or numbered field in the current record. To move to the next record in the recordset use the command DBMoveNext

Note: This command can only be used if DBDoSQL has been called previously.

Note: Your script must use DBClose to close the open database on completion of all database access.


DBMoveNext

Command: | DBMoveNext ("id")
Usage: | fscommand ("DBMoveNext", "2")
Return Code: | Returns one of the generic error codes on error. Specifically End of File after last record. Returns 0 on success.

Parameter | Description
id | User supplied number that is used to identify the database in subsequent database operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.

Moves to the next record in the recordset. DBGetFieldVal can then be used to obtain information about that record.

Note: This command can only be used if DBDoSQL has been called previously.

Note: Your script must use DBClose to close the open database on completion of all database access.


DBOpen

Command: | DBOpen ("id, <connection>, <querytimeout=10>")
Usage: | fscommand ("DBOpen", "2") Open database. Prompt user to supply datasource. fscommand("DBOpen", "2,ODBC;DATABASE=test_db;UID=sa;PWD=password;DSN=mytestdb")
Return Code: | Returns one of the generic error codes. Returns 0 on success

Parameter | Description
id | User supplied number that is used to identify the database in subsequent file operations. Numbers in the range 1..10 are permited. This allows up to 10 simultaneous databases.
<connection=NULL> | Optional. If omitted, the user is prompted to enter the DSN name, database name and password via standard dialogs. The connection string can be fully specified in which case the following should be included ODBC; - Defines the connection as an ODBC connection. DATABASE=test_db; - Name of the database to be opened UID=sa; - user ID. Note for security reasons it is not good practice to use "sa". PWD=password; - The password for the UID DSN=mytestdb - The data source name as configured within the ODBC Data Source Administrator.
<querytimeout=10> | Optional. If omitted, the default query timeout is 10 seconds.

Allows user to open a database by specifying connection information. If the connection parameter is omitted, the user is prompted to supply the necessary information.

Once a database is opened, the commands DBExecSQL and DBDoSQL can be used to manipulate and read the database.

Note, your script must use DBClose to close the open database on completion.


PrivateProfileStrings

These commands provide similar functionality to the SDK functions GetPrivateProfileString (emulated by PrivateProfileStringGet) and WritePrivateProfileString (emulated by PrivateProfileStringSet).

Although these functions were originally provided by Microsoft to provide backward compatibility with 16-bit windows applications, they are very useful tools when used to define and look up text based databases.

The functions typically read and write a .ini file.

A typical ini file consists of multiple sections (or application names) each of which may contain multiple entries (or keynames).

eg.

[section1]

s1entry1=1.1

s1entry2=1.2

[section2]

s2entry1=2.1

s2entry2=2.2

For example, it is possible to use PrivateProfileStringGet to look up the value for section2, s2entry1. If the .ini file quoted was the one above, the function call would return 2.1

PrivateProfileStringSet is used to create a file such as the one above.


PrivateProfileStringGet

Command: | PrivateProfileStringGet ("inifilename, section, entry, <default value="">, <[out] value>")
Usage: | fscommand ("PrivateProfileStringGet", ".\\test.ini,debug,item1,,txt1.text")
Return Code: | On Success fscmd_ret returns the number of characters read. If the optional output parameter value is specified, the return value is placed into that variable. On Failure fscmd_ret returns one of the generic error codes.
Parameter | Description
inifilename | Name of the .ini file to be read. use .\\ if you wish to read a file in the current working directory. If path is not specified, file is searched for in the windows directory. Path Macros can be quoted.
section | The name of the section that contains the entry.
entry | The key name or entry.
<default> | Optional. This value is returned if named entry is not found. Defaults to "" if omitted.
<[out] value> | Optional. Defines the variable that will hold the returned value.

Gets the specified entry, from the named section of the quoted .ini file.


PrivateProfileStringSet

Command: | PrivateProfileStringSet ("inifilename, section, entry, value")
Usage: | fscommand ("PrivateProfileStringSet", ".\\test.ini,debug,item1,hi test 123")
Return Code: | On Success fscmd_ret returns 0. On Failure fscmd_ret returns one of the generic error codes.
Parameter | Description
inifilename | Name of the .ini file to be written. Use .\\ if you wish to write a file in the current working directory. If path is not specified, file is searched for in the windows directory. Path Macros can be quoted.
section | The name of the section that contains the entry.
entry | The key name or entry.
value | Defines the string that is to be written to the section / entry of inifilename

Writes the value defined by the value parameter to the specified .ini file under the specified section and entry.


Quit

Command: | Quit ("")
Usage: | fscommand ("Quit", "")
Return Code: | -99

Exits the application.


Registry Commands

The commands RegRead, RegWrite and RegDelete are provided to allow reading, writing and deletion of registry items.

The commands all use common Registry Key Abbreviations and allow operations on various registry data types.

WARNING: Manipulating your registry incorrectly can cause serious problems that may require you to reinstall your operating system. SWiSHzone.com cannot guarantee that problems resulting from incorrect registry manipulation can be solved. Use these commands at your own risk.


Registry Key Abbreviations

Abbreviation | Root Key
HKCR | HKEY_CLASSES_ROOT
HKCC | HKEY_CURRENT_CONFIG
HKCU | HKEY_CURRENT_USER
HKLM | HKEY_LOCAL_MACHINE
HKUSR | HKEY_USERS


Registry Data Types

Data Type | Description | Example Value
"REG_SZ" | String | "Hello world"
"REG_DWORD" | Integer | "123456"
"REG_BINARY" | Multiple Binary Hexadecimal Values | "1E, 2F, 3A, FC, 78"
"REG_EXPAND_SZ" | An expandable string (e.g., "%windir%\\calc.exe") The variable name %windir% is expanded on reading. | "%windir%\\calc.exe" on writing. "C:\WINDOWS\calc.exe" on reading.


RegDelete

Command: | RegDelete ("key, name, <[out] status>")
Usage: | fscommand ("RegDelete", "HKLM,SOFTWARE\\SWiSHzone.com\\testreg,txt4.text")
Return Code: | One of the generic error codes is returned in fscmd_ret Additional error information and success code is returned in the optional user supplied status variable. Possible values are: "Error:Insufficient arguments" "Error:UnknownKeyValue[ key name ]" or "OK" on success.

This command deletes the specified key and any subkeys.

Use with care, deleting registry areas can make your system unuseable.

Parameter | Description
key | One of the root key name abbreviations.
name | The remainder of the key name. Note that \ must be entered as \\
<[out] status> | Optional output parameter that shows text based result.

Requirements:

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 4.0 or later).

Windows 95/98/Me: Requires Windows 98 or later (or Windows 95 with Internet Explorer 4.0 or later).


RegRead

Command:

RegRead ("key, name, <[out] type>, <[out] data>")

Usage:

fscommand("RegRead",

"HKLM,SOFTWARE\\SWiSHzone.com\\SWiSH\\testreg\\expand,

txt1.text,txt2.text");

Return Code:

One of the generic error codes is returned in fscmd_ret

On error the type parameter will contain "Error" and the data variable will hold additional error information.

The parameter type is used to show the return data type. The parameter data will hold the returned data. The format of the data will depend on the data type.

This command reads the specified key and value.

Parameter | Description
key | One of the root key name abbreviations.
name | The remainder of the key name. Note that \ must be entered as \\
<[out] type> | A variable to hold the registry data type that was read.
<[out] data> | A variable to hold the registry data that is read. The data format will depend on the returned data type.


RegWrite

Command:

RegWrite ("key, name, type, data, <[out] status>")

Usage:

fscommand("RegWrite",

"HKLM,SOFTWARE\\SWiSHzone.com\\SWiSH\\testreg\\expand,

REG_EXPAND_SZ,%WINDIR%\\sys,txt4.text");

Return Code:

One of the generic error codes is returned in fscmd_ret

Additional error information and success code is returned in status parameter will The status parameter will contain one of the following error codes:

"Error:Insufficient arguments" - key, name, type and data must be specified.

"Error:UnknownDataType[ data type ]" - Not one of the defined data types

"Error:UnknownKeyValue[ key name ]" - Specified Key does not exist

"Error:Missing\\[ key name ]" - Specified key has missing \\

"Error:Open( key name )#=error_num - Cannot open key. error_num contains system error number.

"Error:SetValue( key name)#=error_num" - Cannot write value. error_num contains system error number. (Probably user has insufficient permissions).

"OK" - Success

This command reads the specified key and value.

Parameter | Description
key | One of the root key name abbreviations.
name | The remainder of the key name. Note that \ must be entered as \\
type | Defines the registry data type to be written.
data | Defines the registry data that is written. The data format will depend on the returned data type. If the type is REG_SZ then the supplied string will be interpreted according to the defined Path Macros. No interpretation occurs if the type is REG_EXPAND_SZ. In this case the interpretation is done when the registry value is read.
<[out] status> | Used to return any error codes and success condition.


Run

Command: | Run ("file, params")
Usage: | fscommand ("Run", "SWiSHstudio.exe, Document.sws")
Return Code: | <= 32 indicates error, > 32 indicates success. The meaning of the error code is documented in Windows ShellExecute API documentation.

This is a shorthand version of the Execute command – it executes the file specified, passing it the params argument. The main application window will be used to display any messages.


ShowImage

Command: | ShowImage ("[in] pathname <,[in] title> <,[in] realSize> <,[in] left> <,[in] top> <,[in] right> <,[in] bottom>")
Usage: | fscommand ("ShowImage", "c:\\mypic.jpg") fscommand ("ShowImage", "c:\\mypic.jpg,Holiday Pic,1") fscommand ("ShowImage", "c:\\mypic.jpg,,0,100,100,400,500") fscommand ("ShowImage", "c:\\mypic.jpg,,1,200,100")
Return Code: | 1 on success. 0 on failure.

Parameter

Description

pathname

Pathname to the image to be displayed.

title

Optional. Defines the label that will appear in the window titlebar. The default name is the filename component of the pathname.

realSize

Optional. Specifies whether or not the image will be displayed at its real (ie, 1:1) size.

1 - indicates display at real size.

0 - indicates image will be displayed in a window defined by the left, top, right, bottom rectangle. If a rectangle is not specified, it will default to: 100,100,500,400.

Note: If instructed to display at real size and the image is bigger than the available desktop area, then the image will be scaled down to fit the desktop area.

left

Optional. Left ordinate of window rectangle specification.

top

Optional. Top ordinate of window rectangle specification.

right

Optional. Right ordinate of window rectangle specification.

bottom

Optional. Bottom ordinate of window rectangle specification.

Displays an image inside a resizable window. The image can be made to display at 100% (ie, real size), providing it is not bigger than the desktop area (if so, it will be scaled to fit the desktop). The following image formats are supported: JPG, BMP, GIF, WMF, EMF, ICO, PNG, TIF.


SysDiskInfo

Command: | SysDiskInfo ("rootpath, <[out] name>, <[out] serial number>")
Usage: | fscommand ("SysDiskInfo", "c:\\,txt1,txt2")
Return Code: | On Success fscmd_ret returns 0. On Failure fscmd_ret returns one of the generic error codes.

Parameter

Description

rootpath

This can be a local drive such as c:\\ or a network drive such as \\\\myhost\\

Note that if the root path is a network drive, the serial number will not be reported correctly.

Note that '\\' must be used in place of '\' becuase of the FSCommand Escape sequence.

<[out] name>

Optional. Defines the variable that will hold the drive volume name.

<[out] serial number>

Optional. Defines the variable that will hold the driver serial number. This is a string representation of the number in decimal format.

eg. "-600820210" would represent the serial number DC30-360E

The serial number is the serial number assigned after a disk is formatted. This serial number is displayed via the dos command "dir". It is not the hardware serial number obtained from the drive firmware.

Returns the volume name and serial number of the specified drive.

Note that if the drive is removeable and is not present, a dialog will appear.


SysGetUserName

Command: | SysGetUserName ("[out] name")
Usage: | fscommand ("SysGetUserName", "txt1")
Return Code: | On Success fscmd_ret returns 0. On Failure fscmd_ret returns one of the generic error codes.

Parameter | Description
[out] name | Defines the variable that will hold the user name.

Returns the name of the user that is running the process.


SysGetLocalTime

Command: | SysGetLocalTime ("<[out] time>")
Usage: | fscommand ("SysGetLocalTime", "txt1")
Return Code: | On Success fscmd_ret returns the time_t value. The time_t value is the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time, according to the system clock. If the optional time parameter is specified, the local time in ascii text format is also returned. Note: fscmd_ret is returned as a string.

Parameter | Description
<[out] time> | If specified, holds the local time in ascii format. eg. "Thu Feb 12 15:47:21 2004"

Returns the local and system time.


SysGetWinDir

Command: | SysGetWinDir ("[out] path")
Usage: | fscommand ("SysGetWinDir", "txt1")
Return Code: | On Success fscmd_ret returns 0. On Failure fscmd_ret returns one of the generic error codes.

Parameter | Description
[out] name | Defines the variable that will hold the pathname.

Returns the path to the windows directory. eg. "c:\windows"


SysOsVer

Command: | SysOsVer ("<[out] Major, <[out] Minor>, <[out] Build>, <[out] ServPack>")
Usage: | fscommand ("SysOsVer", "txt1,txt2,txt3,txt4")
Return Code: | On Success fscmd_ret returns 0. On Failure fscmd_ret returns one of the generic error codes.

Parameter | Description
<[out] Major> | Optional. Defines the variable that is to hold the Major version number.
<[out] Minor> | Optional. Defines the variable that will hold the Minor version number.
<[out] Build> | Optional. Defines the variable that will hold the Build number.
<[out] ServPack> | Optional. Defines the variable that will hold the Service pack description string. eg. "Service Pack 1"

Get operating system information.

See Microsoft MSDN (OSVERSIONINFO) for more information.


VideoGetAllModes

Command: | VideoGetAllModes ([out] modesString)
Usage: | fscommand("VideoGetAllModes", "modesString")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
modesString | Retrieve a string of all possible video modes. Each video mode is represented by 4 comma separated values representing: width, height, bits-per-pixel, frequency.

Retrieve a string of all possible video modes.


VideoGetCurMode

Command: | VideoGetCurMode ([out] wd, [out] ht, <[out] bpp,> <[out] freq>)
Usage: | fscommand("VideoGetCurMode", "wd,ht,bpp,freq") fscommand("VideoGetCurMode", "wd,ht") fscommand("VideoGetCurMode", "wd,ht,,freq")
Return Code: | 1 - if successful 0 - if unsuccessful
Parameter | Description
wd | Screen pixel width
ht | Screen pixel height
bpp | Bits per pixel
freq | Monitor scan frequency (Hz)

Retrieve current video mode settings.


VideoSetMode

Command: | VideoSetMode ([out] wd, [out] ht, <[out] bpp,> <[out] freq>)
Usage: | fscommand("VideoSetMode", "1280,1024,32,85") fscommand("VideoSetMode", "800,600") fscommand("VideoSetMode", 1024,768,,75")
Return Code: | 1 - On success. -1 - Could not enumerate current video mode. -2 - Computer must be restarted in order for the graphics mode to work. -3 - The display driver failed the specified graphics mode. -4 - The graphics mode is not supported. -5 - Windows NT: Unable to write settings to the registry. -6 - An invalid set of flags was passed in. -7 - An invalid parameter was passed in. This can include an invalid flag or combination of flags. -8 - Unknown error.
Parameter | Description
wd | Screen pixel width
ht | Screen pixel height
bpp | Bits per pixel
freq | Monitor scan frequency (Hz)

Sets the specified video mode settings.

Note: All settings are temporary. When the executable terminates, the previous video mode will automatically be restored.


WindowGetPos

Command: | WindowGetPos("X,Y,CX,CY")
Usage: | fscommand ("WindowGetPos", "txt1,txt2,txt3,txt4")
Return Code: | -99

Parameter | Description
X | Name of the variable that is to hold the X position. X position is the X co-ordinate of the window top left hand corner.
Y | Name of the variable that is to hold the Y position. Y position is the Y co-ordinate of the window top left hand corner.
CX | Name of the variable that is to hold the CX size or Window Width.
CY | Name of the variable that is to hold the CY size or Window Height.

Gets the position and size of the currently running projector.

Position is the position of the top left hand corner. (0,0 is top left hand of screen)

See Also: WindowGetPos, WindowSetPos and WindowSetPosRel


WindowSetPos

Command: | WindowSetPos("<Level=0>, <x=-1>, <y=-1>, <cx=-1>, <cy=-1>, <option=0>)
Usage: | fscommand ("WindowSetPos", "1") - Set top fscommand ("WindowSetPos", "4") - Set bottom fscommand ("WindowSetPos", "0, 20, 40") - Move to 20, 40 fscommand ("WindowSetPos", "0,,,200,300") - Resize to 200 x 300
Return Code: | -99

Parameter | Description
<Level=0> | Optional parameter. Default is 0. Sets the level of the window. 0 = no change 1 = Top - becomes a topmost window 2 = TopMost - placed above non topmost windows, remains topmost even when deactivated. 3 = Top of non topmost, loses topmost position when deactivated 4 = Bottom - becomes bottom window.
<x=-1> | Optional parameter. Default is -1 X position of window top left hand corner. If X or Y is < 0, then window position is not altered.
<y=-1> | Optional parameter. Default is -1 Y position of window top left hand corner. If X or Y is < 0, then window position is not altered.
<cx=-1> | Optional parameter. Default is -1 Window Width. If cx or cy is < 0, then window size is not altered.
<cy=-1> | Optional parameter. Default is -1 Window Height. If cx or cy is < 0, then window size is not altered.
<option=0> | Optional parameter. Default is 0. Other optional settings. See the table below for the meaning of the values. Multiple options can be selected by adding the required values. eg. 6 (4+2) = SWP_NOORDER and SWP_NOMOVE.

Value | ID | Meaning
1 | SWP_NOSIZE | Retains current size, and ignores the cx and cy parameters.
2 | SWP_NOMOVE | Retains current position, it ignores the x and y parameters.
4 | SWP_NOZORDER | Retains current ordering, (same as Level = 0).
8 | SWP_NOREDRAW | Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area, including the title and scroll bars, and any part of the parent window uncovered as a result of the moved window. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that must be redrawn.
16 | SWP_NOACTIVATE | Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or the nontopmost group, depending on the setting of the pWndInsertAfter parameter.
32 | SWP_FRAMECHANGED SWP_DRAWFRAME | Draws a frame around the window, this is defined when the window is created. Sends a WM_NCCALCSIZE message to the window, even if the window size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window size is being changed.
64 | SWP_SHOWWINDOW | Displays the window.
128 | SWP_HIDEWINDOW | Hides the window.
256 | SWP_NOCOPYBITS | Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
512 | SWP_NOOWNERZORDER | Does not change the position in the Z-order of the owner window. (Does not really apply to studio .exe's)
1024 | SWP_NOSENDCHANGING | Prevents the window from receiving the WM_WINDOWPOSCHANGING message.
8192 | SWP_DEFERERASE |
16284 | SWP_ASYNCWINDOWPOS |

Sets the position, size and level of the running projector.

See Also: WindowGetPos, WindowSetPos and WindowSetPosRel


WindowSetState

Command: | WindowSetState("state = 3")
Usage: | fscommand ("WindowSetState", "1")
Return Code: | on success 1 on failure -1

Parameter | Description
state | = 1 Minimize window. = 2 Maximize window = 3 Restore window default is 3 (Restore).

Sets the window state to one of: minimized, maximized, restored.

See Also: WindowGetPos, WindowSetPos and WindowSetPosRel


WindowSetPosRel

Command: | WindowSetPosRel("<Level=0>, <x=0>, <y=0>, <cx=0>, <cy=0>, <option=0>)
Usage: | fscommand ("WindowSetPosRel", "1") - Set top fscommand ("WindowSetPosRel", "4") - Set bottom fscommand ("WindowSetPosRel", "0, 20, -40") - Move to +20, -40 from current fscommand ("WindowSetPosRel", "0,,,20,30") - Resize +20 x +30 from current size
Return Code: | -99

Parameter | Description
<Level=0> | Optional parameter. Default is 0. Sets the level of the window. 0 = no change 1 = Top - becomes a topmost window 2 = TopMost - placed above non topmost windows, remains topmost even when deactivated. 3 = Top of non topmost, loses topmost position when deactivated 4 = Bottom - becomes bottom window.
<x=0> | Optional parameter. Default is 0 position of window top left hand corner is moved by X pixels If resulting X or Y is < 0, then window position is not altered.
<y=0> | Optional parameter. Default is 0 position of window top left hand corner is moved down by Y pixels If resulting X or Y is < 0, then window position is not altered.
<cx=0> | Optional parameter. Default is 0 Window Width is increased by cx pixels. If resulting cx or cy is < 0, then window size is not altered.
<cy=0> | Optional parameter. Default is 0 Window Height is increased by cy pixels If resulting cx or cy is < 0, then window size is not altered.
<option=0> | Optional parameter. Default is 0. Other optional settings. See the table in WindowSetPos for a description of possible values.

Similar to WindowSetPos except that window position and size is specified relative to current window position and size.

See Also: WindowGetPos, WindowSetPos and WindowSetPosRel


WindowShow

Command: | WindowShow("show")
Usage: | fscommand ("WindowShow", "1")
Return Code: | on success 1 on failure -1

Parameter | Description
show | = 0 Hide window. = non-zero Show window

Shows or hides the main window.

See Also: WindowGetPos, WindowSetPos and WindowSetPosRel


WriteStr

Command: | WriteStr ("pathname, mode, text")
Usage: | fscommand ("WriteStr", "C:\\myfolder\\myfile.txt, W, Mary had a little lamb\r\n") fscommand ("WriteStr", "C:\\myfolder\\myfile.txt, A, Mary had a little lamb\r\n")
Return Code: | -99 No arguments specified. 0 Error opening file. 1 Error during write operation. 2 Write completed successfully.

WriteStr command accepts a full file pathname, mode flag and text argument. The specified file name is opened in the specified mode and text is written to it. There are two (case insensitive) modes:

1. W – means open file for writing, truncate contents for existing files or create new file if it doesn't exist.
2. A – means open file for appending. The text will be written from the end of the file. Note, if the file doesn't already exist, it will be automatically created.

Note, text formatting characters must be supplied by the caller (such cr/lf pairs).

Note: Path Macros can be quoted.

Note: This function is in no way related to the FileOpen, FileClose, FileRead and FileWrite functions. This funciton does not require a file to be opened or closed but may suffer a performace penalty when writing large amounts of data.


FSCommand Authoring

It is possible for third parties to make FSCommand DLLs. This feature allows you to expand the capabilities of your SWiSH Studio project to perform any task that is coded into the third party FSCommand DLL.

For SWiSH Studio to recognise the third party DLLs, they must reside in the SWiSH Studio program dir and they must match the following naming convention:

"*FSCmd*.dll"

For example, MyTestFSCmd.dll and FSCmdMacroMedia.dll are both valid FSCommand DLL names.

If this convention is followed, SWiSH Studio will recognise the DLLs and include them in compiled .exe files automatically.

The section Example Project demonstrates how to add functions to a user FSCommand DLL using a supplied Visual C++ project as a template.

Note: The Example Project must be compiled using UNICODE. If you create your own project instead of modifying the supplied project, you must undefine _MBCS and define _UNICODE in the project settings of your project. Versions of the Example Project distributed prior to Aug 22 2006 were not compiled as UNICODE. If your custom dll is based on one of these versions, please re-compile using UNICODE as described above.

Note: To compile the example project, it may be necessary to download and install the Microsoft Platform SDK. At time of publishing, this download is Windows Server 2003 R2 Platform SDK. The ISO image is available from here.

Once installed, you should change the Directory search order (Tools | Options | Directories) in your VC++ compiler to refer to the installed SDK directory.

For the above SDK installed to the default directory the first directory in the list should be:

"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include"


Example Project

An example Visual C++ 6.0 project has been included in the file: Studio_UserFSCmd.zip

This file is automatically installed in the SWiSH Studio program directory.

To modify the example project, unzip the entire contents of the zip file into a directory.

The DLL UserFSCmd.DLL contains a single FS Command, Beep2(freq, duration, [out] newvals);

To test this DLL, copy the DLL to the SWiSH Studio program directory and include the beep2.swf file in a SWiSH Studio project. The SWiSH Max souce for beep2.swf is included in the file beep2.swi

To modify the example project to add your own functions,

1. Open the StudioFSCmd.dsw workspace file using Visual Studio C++ 6.0

2. Add new functions to the UserFSCmd.cpp and include the new function names to StudioFSCmd.def.

Note: Functions must comply with the Function Calling Conventions.

3. Re-compile the project and copy the new UserFSCmd.DLL to the SWiSH Studio program directory.

The new functions including the example Beep2 will now be available to .swf files that are included in a SWiSH Studio project.


Function Calling Convention

The FSCommand functions must be defined according to the following format:

BSTR __declspec(dllexport)__stdcall FSName (const TCHAR *argStr)

Name is the name that is used when called via the fscommand() function from within the .swf file.

eg. fscommand("Name","arg1, arg2, ... argn");

Name should not be the same as any of the function names defined in FSCommand List

Note that the leading FS is omitted when the function is called from the fscommand() function, however the "FS" must be included in the function name definition and within the .def file.

The function parameters are passed in a single string, argStr. To simplify parsing of this string, the class ArgParse has been provided to simplify argument parsing. See UserFSCmd.cpp for an example of usage of this class.

Note that the ArgParse class with automatically expand path names as defined in FS Command Path Macros.

Return parameters can be returned using the RetCode class. See UserFSCmd.cpp for an example of usage of this class. The default parameter delimiter is a comma (,). The RetCode class allows the use of an alternate character if one of the return parameters will contain the default delimiter.

If it is not intended for the function to return any value, the function should return with the code number -99. This can be achieved with the following code:

RetCode ret;

return ret.GetRetCode(-99);

Note that -99 is the default return value for fscommands that do not return a value.


Notes

Some general notes pointing out some aspects that are not intuitive.

Also see information about fscmd_ret and the non blocking nature of fscommands.


FS Commands are Non Blocking

Note that fscommands are executed as "Non Blocking" commands.

This means that your movie will continue even though the fscommand may not be complete. If you need to know when an fscommand has been executed, you can set the variable "fscmd_ret" to some special value and wait for it to change.

In some instances, it is necessary to check that a previous command is complete before commencing the next command.

Consider the example below that demonstrates the opening, writing and subsequent closing of a file.

onFrame (1) {

fscmd_ret = "";

fscommand("FileOpen", "1,test123.txt,a");

}

onFrame (3) {

if ("" == fscmd_ret) {

prevFrameAndPlay();

} else {

ret = fscmd_ret; // display the return code

fscmd_ret = "";

fscommand("FileWrite", "1,hi this is a test2\n");

}

}

onFrame (5) {

if ("" == fscmd_ret) {

prevFrameAndPlay();

} else {

ret = fscmd_ret; // display the return code

fscmd_ret = "";

fscommand("FileClose", "1");

}

}

Note: that there is no script active in frames 2 and 4. Those frames are used as "wait" frames.

Note: As the filename is "test123.txt", its final location will depend on the Current Working Directory.

The onFrame(3) and onFrame(5) both wait for a non "" value to be placed into fscmd_ret before continuing.

Note that the use of:

while ("" == fscmd_ret)

{

// delay

}

This will place the flash player into a tight loop that will hog resources. This is not a satisfactory way to wait for a fscommand to complete.

See also ODBC Example Script which demonstrates a way of handling timeouts.


FS Command Path Macros

When paths or filenames are passed to the various FS Commands, the following macros can be used to reference commonly used directories.

Macro: | Description:
%Org% | .exe path name
%MyPictures% | Full Path to "My Documents\My Pictures\"
%MyDocuments% | Full Path to "My Documents\" On NT, Win2000 and XP systems this is typically: "C:\Documents and Settings\<user>\My Documents\" where <user> is the users log on id.
%WinDir% %Windows% | Returns the path to the windows directory. eg. c:\windows
%SysDir% %System% %System32% | Returns the defined system path. (Same irrespective of which macro name is used).
%TempDir% %Temp% | Returns the defined temporary directory
%Desktop% | The desktop path. On NT, Win2000 and XP systems this is typically: "C:\Documents and Settings\<user>\Desktop\" where <user> is the users log on id.
%StartMenu% | Returns the path to the start menu folder. On NT, Win2000 and XP systems this is typically: "C:\Documents and Settings\<user>\Start Menu\" where <user> is the users log on id.
%Programs% | Returns the path to the start \ programs menu folder. On NT, Win2000 and XP systems this is typically: "C:\Documents and Settings\<user>\Start Menu\Programs\" where <user> is the users log on id.
%StartUp% | Returns the path to the startup (auto start) menu folder. On NT, Win2000 and XP systems this is typically: "C:\Documents and Settings\<user>\Start Menu\Programs\Startup" where <user> is the users log on id.
%ProgramFilesDir% | Returns the path to the program files directory. On NT, Win2000 and XP systems this is typically: "C:\Program Files\"

eg. "%ProgramFilesDir%\\MyDir\\" is expanded to "C:\Program Files\MyDir\" before being processed by the FS command.

Note: When quoting paths to FS Commands, you must use \\ in place of \ because of the Escape Sequence Processing.


FS Command Escape Sequences

To allow the entry of various non printable characters, the backslash character (\) is used to denote the start of an escape sequence.

Sequence | Description | SWiSH Max Expert Mode
\n | Newline character. | \n
\r | Carriage return character. | \r
\\ | The backslash character | \\\\
\nnn | Any other non printable character where nnn is the octal ascii code for that character. | \nnn

This escape sequence exists for any quoted string. Consequently if you intend to enter a path as "c:\mydir\myfile.txt" you really need to enter "c:\\mydir\\myfile.txt"

SWiSH Max uses a similar escape sequence when entering and displaying non printable characters. Therefore you may have to use the Escape Sequence twice if entering values into SWiSH Max in its Expert Mode.

If entering script in SWiSH Max "expert mode", each \ character must also be escaped. (SWiSH Max uses the same escape sequence processing). Therefore if intended parameter is c:\ this must be presented to the fs command as c:\\. In SWiSH Max expert mode you must enter the same parameter as c:\\\\


UserFSCmd.cpp

/*

Copyright (C) 2003-2004 SWiSHzone.com PTY LTD

ABN 52 086 041 812, SYDNEY, AUSTRALIA

All rights reserved.

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY

KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR

PURPOSE.

You are allowed to modify this file to create your own fs command dll.

*/

#include "StdAfx.h"

#include "StudioFSCmd.h"

#include "ArgParse.h"

#include "PathMacro.h"

#include "ReturnCode.h"

/*

This file defines the user defined FSCommand functions

An example command Beep2 is provided below.

Chosen function names should not clash with those already defined distribution fscommands.dll

*/

BSTR __declspec(dllexport)__stdcall FSBeep2 (const TCHAR *argStr)

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

// Beep2 (dwFreq = 1000, dwDuration = 100, [out] newparam)

/*

This example function takes 3 parameters.

The first parameter arg[0] defines the frequency

The second parameter arg[1] defines the duration in milliseconds

The optional parameter defines the name of a variable that will hold a return string.

fscmd_ret is set to the value of frequency + duration (for the sake of example).

*/

{

ArgParse arg; // argument parsing class

arg.Parse (argStr); // initialise arguments

CString csNewParam; // used to hold hte newparm value

const int freq = (arg [0].IsEmpty()) ? 1000 : atoi (arg [0]); // set defaults

const int duration = (arg [1].IsEmpty()) ? 100 : atoi (arg [1]);

Beep (freq, duration); // make the noise

RetCode ret; // variable to hold return value. This class simplifies the passing of return parameters.

ret.SetDelimiter(_T('\t')); // need to change default delimiter as return string csNewParam contains ,

ret.Add(arg [0]); // place marker for 1st arg returned.

ret.Add(arg [1]); // place marker for 2nd arg returned

csNewParam.Format(_T("%d, %d"), freq * 110/100, duration * 110/100); // return newparam

ret.Add(csNewParam); // add the calculated values of newparam as the 3rd argument

return ret.GetRetCode(freq + duration); // return the values and set fscmd_ret to (freq + duration)

}


Current Working Directory

When you run the SWiSH Studio application, a projector or a screen saver created by SWiSH Studio, a temporary sub-folder will be created inside your temp folder location. The exact location of this folder will depend on your system configuration.

The temporary folder is used as a writeable location to unbundle any files that are required to play your presentation. Your projector exe may include any of the following bundled files:

· Your .swf movie(s) and other play list items.
· Any files that have been associated via the Dependencies Palette.
· The GDIPlus.dll (if selected via CD burning options).
· Flash installer (if selected).

The Current Working Directory (or CWD) is set to this temporary folder. References from within your movie to ".\" will refer to this folder, and not to the folder where the projector exe resides.

If you wish to find the path to the projector exe, you can use the GetExeDir fscommand, or use the path macro "%org%" in your fscommand path specification. For example:

fscommand ("Exec", "%org%/test.exe")

will execute the file "text.exe" from the same location that the projector exe resides.


fscmd_ret is returned as a string

fscmd_ret is returned as a string. This allows the return of both numeric and string values. If you wish to perform arithmetic calculations based on its numeric value you should convert to a numeric variable. The Number() function within SWiSH Max scripting language can be used to do this.


Parameters from within Sprites / Movie Clips

Variables can be defined locally within a Sprite or Movie Clip. When passing such variables to a FS Command, it is necessary to specify the full path.

eg. If your main movie contains a sprite "S1" and that Sprite contains a dynamic text variable "txt1", although you can refer to the variable as "txt1" from within the Sprite, when calling a FS Command from within the sprite, you must specify the full path to the variable.

eg. fscommand ("SysGetLocalTime", "_root.S1.txt1");

Note: The return value fscmd_ret should also be referenced via its full path. ie. _root.fscmd_ret


Frequently Asked Questions (FAQ)

Here you will find answers to many questions you may have about SWiSH Studio.

The General Questions area relates to licensing, unlocking and other things not related to SWiSH Studio use questions.

The Studio Use Questions section relates to specific issues with using SWiSH Studio.


General Questions

Do I need Macromedia Flash™ installed to use SWiSH Studio?

No. SWiSH Studio is a stand-alone application. It is not a plugin for Macromedia Flash™. SWiSH Studio can import .swf files and publish animations without Flash™ being installed.

What are Shockwave Flash™ (.swf ) files?

SWF is a file format used by Macromedia to deliver graphics, animation and sound over the Internet. SWF files are much like .gif files in that they will play in most browsers without installing a plugin. SWF is pronounced "swiff".

Is a Mac version of SWiSH Studio planned?

A Mac version of SWiSH Studio is currently not planned.

I have a question about purchasing, registration or the licensing of SWiSH Studio.

Look at some of the frequently asked questions in the Purchasing, Registration and Licensing section.

How do I remove the installed Screen Saver files ?

The screensaver files (.SCR) are saved in your WINDOWS directory (typically C:\WINDOWS). They should use the SWiSH Studio program icon. Simply delete the unwanted .SCR files to remove them from the list of available screensavers.


Studio Use Questions

· When I make a projector, only a small portion of the SWF will play before it starts replaying, why?

When you add a SWF file to the play list in the Select tab, its Play Time duration will be shown in that column of the list box. This figure is not always accurate as it does not take into account the possibility that the SWF file contains a number of sprites or other scripting that causes it to loop. Therefore, the time shown could be much shorter than the actual play time, so your projector will only play a portion of the SWF.

Furthermore, you have checked the option in the Settings tab --> Playback Control --> Loop Playback. This means that when all the items in the play list have finished playing, they will be replayed from the beginning. So, because you have a short play time and loopback set, SWiSH Studio will repeatedly play the same SWF for a fraction of its true playing time.

The solution is to uncheck Settings tab --> Playback Control --> Loop Playback. This way, the SWF will play indefinitely. However, you cannot do that if you have more than one item in the play list as each will be played in turn after it's Play Time expires. In this case, you need to edit the Play Time field to make the play duration as long as it needs to be.

· I have two SWFs, one loads the other on a button press. I have added both to the play list but when I click the button in the first SWF, nothing happens, why?

Remember that all items in the play list will play in turn and independently of any other item in the play list. If you have the situation where your second SWF is dependent on the first SWF for activation, you need to include the second SWF as a dependent file (of the first). This is achieved through the floating Dependencies Palette. You may add any support file(s) you wish, including sub-folder structures. These files will be packaged into the publication (projector or screen saver) and when the publication runs, the files (and sub-folders) will be expanded out and be available for reference by your main SWF.

· When I run the projector, I get an error message saying that GdiPlus.dll could not be found. What is wrong?

See the section GDIPlus.DLL

· I'm trying to access a HTML file on my hard disk with getURL("page1.htm") but when the browser pops up it is trying to load the file from the Web, ie "http://page1.htm" and it fails. What do I need to do to make this work?

The problem is that when the browser is told to load a file with a relative path, it assumes that it is to be found on the Web and so prepends "http://" to the filename. The solution is to use the FSCommand "Exec". For example:

on (press){

getURL("fscommand:Exec","page1.htm");

}

Alternatively, you can check the option in Tools --> Options --> Substitute with FSCommands, and SWiSH Studio will automatically do the substitution for you when you publish the document.

· I have just re-installed an old program on my system. Now when I start SWiSH Studio I see an error dialog. The error also appears when I try to run a projector or screen saver that I made recently.

It is possible that the program you re-installed has incorrectly installed a previous version of the flash player. This error can occur if you install Encarta 99, and possibly other Microsoft reference programs that use Macromedia Shockwave or Flash. Try installing the latest version of the flash player which is available from here and see if this fixes the problem.

The error occurs because the earler version of the flash player may not support some of the flash commands in the .swf file that you have most recently loaded in SWiSH Studio. Unfortunately, we cannot quote specific error messages as the message will depend on the contents of your .swf file and the specific version of the flash player that you have installed.

The error will occur when SWiSH Studio attempts to preview your .swf file (select tab) or when the player or screen saver attempts to play your .swf file.

Some possible error dialogs include:

"Member not found."

· How do I create an installer for my screen savers?

See the section SCR Installer Package


GDIPlus.dll

SWiSH Studio and its publications require that the gdiplus.dll is present in order to run.

Most newer machines (XP and above) will already have this dll, however, some of the older machines running 98, ME and NT may not.

In this case, you need to run (just once) the file called GdiPlusInstaller.exe which is supplied with SWiSH Studio. This will automatically install the correct dll on your machine. It is advisable that when running the installer, that you choose the 'system folder' option, as this will ensure that every publication will work from any folder on your machine.

Alternatively you can simply copy the gdiplus.dll to be in the same directory as your projector exe.

If you are making screen savers for distribution, you can bundle one or more screen savers into a single self-extracting exe file by selecting Tools --> SCR Installer Package. You should ensure that you check the Include GdiPlus.dll checkbox if you are unsure whether or not the target system will have gdiplus.dll on it.

If you use SWiSH Studio to create a CD, then gdiplus.dll will be automatically included on the CD.


Tutorials

Many of the Tutorials make use of sample files that are included in the Samples directory. Please follow the tutorials below to get a better understanding of how to use various features of SWiSH Studio.

The Tutorials are grouped according to your familiarity with SWiSH Studio.

Beginner:

Jelly Tutorial - A simple projector with a button.

Jelly Screen Saver Tutorial - A simple screen saver.

Advanced:

FSCommand Tutorial


Samples Directory

This directory contains tutorial examples and utility files that are used by the following tutorials.

This directory is installed as a sub directory of the SWiSH Studio install path.

Normally this will be C:\Program Files\SWiSHstudio\SampleFiles

File Name | Description | Associated Tutorials
Jelly-Button.swi | SWiSH Max .swi file that creates a "Jelly Button" | Jelly Tutorial
Jelly-Button.swf | The .swf version of Jelly-Button.swi | Jelly Tutorial
Jellyfish.swf | The ever popular SWiSH jellyfish.swf movie. | Jelly Tutorial
Jellyfishblack.swf | Black background version of Jellyfish.swf | Jelly Screen Saver Tutorial
fscommand.swi | SWiSH Max .swi file that contains a button and calls a fscommand when the button is pressed. | FSCommand Tutorial
fscommand.swf | The .swf version of the fscommand.swi file | FSCommand Tutorial
calc.exe | A simple command line calculator. Used to demonstrate the Exec fscommand. | FSCommand Tutorial


Jelly-Button.swi

This is a SWiSH Max .swi file.

This animated button wobbles in a "Jelly" like fashion when pressed.

When the amination concludes, it loads the movie "Jellyfish.swf" via the script command:

loadMovieNum("jellyfish.swf",0);

Jelly-Button.swf is the .swf export version of this file for use in SWiSH Studio.

If you have access to SWiSH Max, you can alter and re-export this file to .swf


Jelly-Button.swf

This is the .swf version of Jelly-Button.swi for use with SWiSH Studio.


Jellyfish.swf

This is the .swf movie of the SWiSHzone.com jellyfish demonstration.

It is used in the Jelly Tutorial to demonstrate how to load a second movie after a button press.

SWiSHmax users can download the effect from here although it is not needed for the tutorial.


Jellyfishblack.swf

This is similar to Jellyfish.swf except it has a black background and moves randomly around the screen area. This is intended for use with the screen saver tutorial


calc.exe

This is a simple dos based calculator program used to demonstrate the use of the "Exec" fscommand. This program is included in the samples directory.

When running it can perform simple calculator functions such as

a=3

b=4

c=a*b+5

This file is used by the FSCommand Tutorial


fscommand.swf

This is the file created from fscommand.swi

If you have SWiSH Max, you can re-create this file by loading fscommand.swi then re-exporting that file to .swf format.

This file is a .swf movie that allows the user to specify the fscommand name, the fscommand parameter then execute that fs command. This type of movie is very useful for evaluating and testing various fscommands.

Note: Only fscommands that return all of the results via the fscmd_ret variable can be tested fully with this movie.

This file is used by the FSCommand Tutorial


fscommand.swi

This is the SWiSH Max .swi file that is used to create the fscommand.swf file that is used with the FSCommand tutorial.

The .swi file contains the scripting as outlined below. The scripting along with an explaination is provided as an example to those people who do not have access to SWiSH Max to view the scripting directly.

A knowledge of SWiSH Max and SWiSH Max scripting is assumed.

If you are unsure about SWiSH Max or SWiSH Max scripting, please refer to the SWiSH Max help file.

Apart from static components, the fscommand movie contains the following objects and scripts:

Object | Description
btnRun | The "Run Command" button. This button actually executes the fs command. See the Scripting description section below for a description of the button script.
Command | Input text object. Holds the name of the fscommand to be executed.
Parameter | Input text object. Holds the name of the fscommand parameter.
Result | Dynamic text object to hold the result from the command.

Scripting is also used to update the Result Object based on the updated value of fscmd_ret.

The following onFrame events have been used:

onFrame (1) {

_root.fscmd_ret = "";

}

onFrame (3) {

if ("" eq fscmd_ret) {

prevFrameAndPlay();

}

Result.text = fscmd_ret;

}

onFrame (5) {

stop();

}

on (release) {

_root.fscmd_ret = "";

if (length(_root.Command.text) != 0) {

fscommand(_root.Command.text,_root.Parameter.text);

} else {

_root.fscmd_ret = "Enter a valid fs command";

}

gotoSceneAndPlay("<current scene>",2);

}

The onFrame(1) event is used to initialise _root.fscmd_ret

The onFrame(3) event is used to monitor the value of fscmd_ret. This is because of the Non Blocking nature of fs commands.

The onFrame(5) event simply stops the movie to display the result.

The on(release) event is the script for the button, "btnRun".

When the button is pressed, the movie is passed to frame 2 where it loops until a non "" value has been placed in fscmd_ret.

If you wish to re-use this .swi as a template, you can simply hard code in the fscommand and parameter instead of using _root.Command.text and _root.Parameter.text.


Jelly Tutorial

This step by step tutorial uses studio to make a projector based on some of the files supplied in the Samples Directory.

The tutorial demonstrates the following:

· The use of the Dependencies Palette
· How to overlay multiple movies via commands that may be associated with user input (eg. a button).
· How to create an autorun CD. This assumes your computer has a CD burner installed.

Create New .sws file

1. Use File | New to create a New Document and enter the name "Jelly"

Add the Jelly-Button.swf file

2. Use the select-button-add-1 button to add the Jelly-Button.swf file to the project.

3. After pressing Select you should see this:

Add Jellyfish.swf via the Dependencies Palette

4. The Jelly-Button.swf movie will attempt to load the Jellyfish.swf movie after the button has been pressed and the button animation is complete. As the Jellyfish.swf file is not included in the play file list, it must be explicitly added via the Dependencies Palette. This will cause the file to be included when the projector is built.

Note: Failure to include this step will cause a blank movie to be displayed after the button is pressed. This is because the movie referenced after the button is pressed (jellyfish.swf) cannot be found.

5. To open the dependencies palette, use Tools | Dependencies Palette or press F9

6. Add the Jellyfish.swf file which is in the Samples Directory

Publish and Test

7. Select the Publish Tab

8. Then press the Publish button. This will create a projector file, Jelly.exe in the directory specified by "Save In:".

9. Press the Test button to run the projector.

You should see the following:

When you press the SWiSH symbol, you should then see:

Save the .sws file

10. Use File | Save if you wish to save the Jelly.sws file for future use with SWiSH Studio

Notes:

If you gen an error about GDIPlus.DLL not found. See the section GDIPlus.DLL

Analysis

The Jelly-Button.swf movie attempts to load the Jellyfish.swf movie via a loadMovieNum("jellyfish.swf",0); command after the button animation is complete. If you have access to SWiSH Max, you can analyse the source file Jelly-Button.swi

As the Jellyfish.swf movie is not directly referenced in the play list, it must be explicitly defined via the Dependencies Palette so that it is included in the final projector. The projector .exe contains both the Jelly-Button.swf and Jellyfish.swf movies.

Make an Autorun CD

11. Place a new CD-R (no previous recordings) or a CD-RW CD into your CD burner.

12. Click on the Burn to CD button to display the additional Burn to CD options.

13. Check the following options:

· Include GDIPlus DLL (This will ensure that the CD will play on older systems such as win 98)
· Make this an autorun CD

14. Press the "Burn CD" button. This will cause the projector and associated files to be written to the CD.

Note: If you are using a CD-RW CD, and the CD is not empty, you will be prompted to erase the contents. You must erase the contents before burning a SWiSH Studio CD.

15. After the CD burn is complete, eject the CD, then re-insert into the CD drawer. After a short delay, the presentation should start automatically.

Analysis

The projector and associated support files have been burnt to the CD. Analysis of the CD will show the following files:

autorun.inf is a text file that indicates which file to run when the CD is inserted.

In this particular case, it contains the following lines:

[autorun]

open=Jelly.exe

gdiplus.dll is a support dll that is required to run SWiSH Studio projectors on some systems. See GDIplus.DLL for more information.

Jelly.exe is the SWiSH Studio projector that was created for this demonstration. It contains the Jelly-Button.swf and Jellyfish.swf movies.

unicows.dll is a support DLL that allows the SWiSH Studio projector to work on non Unicode systems such as 95, 98 and ME.


Jelly Screen Saver Tutorial

This step by step tutorial uses SWiSH Studio to make a screen saver based on some of the files supplied in the Samples Directory.

Create New .sws file

1. Use File | New to create a new .sws file.

2. Enter JellySS as the name of the file.

Load the Jellyfishblack.swf file

3. Use the select-button-add-1 button to select the Jellyfishblack.swf file from the Samples Directory

Set the appropriate Playback Control options

4. Select the Settings tab.

5. Select the Playback Control item.

6. Select Auto Play and Uncheck Loop Playback options in the Playback group.

Note: Loop playback should be unchecked as the Jellyfishblack.swf movie has been created to continue playing in a random fashion.

If the Jellyfish.swf was used in its place, then Loop playback would be necessary. Please experiment.

Publish as Screen Saver

7. Select the Publish tab and press the Screen Saver (.SCR) button.

8. Select the Install Screen Saver on Publish Option (Leave this unchecked if you are using NT, 2000 or XP and are not using an administrator account.)

9. Press Publish.

10. Press Test.

Note: If you are using NT, 2000 or XP and do not have admin permissions then the following error dialog will occur.

Note: You can still create the screen saver file by unchecking the Install Screen Saver on Publish option, but you will have to copy the .scr file manually into the screen saver area.


FSCommand Tutorial

This tutorial demonstrates the use of fscommands from within a projector created by SWiSH Studio.

The tutorial uses a sample .swf (fscommand.swf) file that was created by SWiSH Max. Both the .swf and the source .swi file are included in the Samples directory.

The fscommand.swf and .swi files are described in detail in the analysis section below.

1. Use File | New to create a New Document and enter the name "fscommand"

2. Using the Select Tab, and the select-button-add-1 button add the Sample file fscommand.swf to the play list.

3. Add the Sample file calc.exe to the Dependencies Palette. Although this is not used initially it is used later in the tutorial. This action, causes the calc.exe program to be included within the projector when the projector is built. This type of step should be used to include all external material when the location of that material cannot be guarenteed on the target computer.

4. Build the Projector. Call the Projector "FSCommands" by entering "FSCommands" into the Save As: box.

You should probably save this projector as it is a useful prototyping tool if you wish to develop your own projector to call various fscommands.

5. Test the projector.

6. Run the projector, FSCommand.exe.

You should see a dialog similar to the one shown below:

7. Use the projector with the following suggested command / parameter combinations. After you have entered the Command and Parameter. Press the Run Command button to execute the fs command.

Command | Parameter | Comments
Beep | 1000, 500 | 1000Hz tone for 500mSec
Exec | calc.exe | This will execute the sample calculator program in a dos window. Use q to exit the calculator program. Note: If you have not included calc.exe using the Dependencies palette, the standard windows calculator will probably be displayed.
FileAccess | calc.exe | Should return 0. This is because the file calc.exe was included with the dependencies palette.
FileAccess | calc1.exe | -1002, this file does not exist.
MessageBox | Hello World,My Caption,2 | Displays an abort, retry, ignore message box with the text "Hello World" and the caption "My Caption"
WindowSetPosRel | 0,20,-40 | Move projector window by x = +20, y = -40
WriteStr | c:\\temp\\test.txt, W, Line 1 of test file | Writes "Line 1 of test file" to the file c:\temp\test.txt
Quit |  | This will close the projector.

Analysis

Apart from the use of the Dependencies Palette to associate the calc.exe file with the projector .exe, much of the procedure to call a fscommand is contained in the fscommand.swi file. Please read the analysis of that file. Once understood, you should find it easy to apply to your own .swf files.


MidiExample

The source files can be found in the Samples\ActiveX directory.

A detailed description of the Active X interface can be found here.

If you have SWiSH Max, you can open the keyboard.swi file and look at the scripting. If you do not have SWiSH Max, the script can be viewed in the keyboard.swi script section.

To create the project do the following:

Open a new project in SWiSH Studio and select the keyboard.swf file.

Add the Active X dll to the Dependencies Palette

The SWiSHstudioXtest.dll is the ActiveX dll that interfaces with the winnm.dll to produce the midi sounds. The SWiSHstudioXtest.dll is described in more detail in the section FSCommand ActiveX Tutorial.

Then save the project, publish and test the player

Pressing the keyboard buttons should create noises.


keyboard.swi script

Script from the main movie

function midi(note,mode) {

// this function is called from each of the keyboard keys. Mode = 1 means play. Mode = 0 means stop.

note = note - 12;

// make middle C the second octave.

if (1 == mode) {

cmd = "cmdret.text, midi, NoteStart," add chan.text add ", " add note add ",127";

fscommand("XMethod",cmd);

} else {

if (!sustain._visible) {

cmd = "cmdret.text, midi, NoteStop," add chan.text add ", " add note;

fscommand("XMethod",cmd);

}

}

ret.text = cmd;

}

on (keyPress("<Space>")) {

if (sustain._visible) {

sustain._visible = false;

} else {

sustain._visible = true;

}

}

onFrame (1) {

// open the connection to the midi activeX component.

// dll is assumed to be in palette.

fscommand("XOpen","swishstudioxtest.midi, midi, swishstudioxtest.dll");

chan.text = 0;

sustain._visible = false;

currentbank = 0;

}

onFrame (2) {

// verify that midi card is installed.

fscommand("XPropertyGet","cmdret.text, midi, outnumdevs");

}

onFrame (3) {

// write error message if no card is installed.

if (0 == cmdret.text) {

cmdret.text = "No MIDI output devices";

} else {

// open the Microsoft MIDI Mapper

fscommand("XMethod","cmdret.text, midi, outopen, -1");

}

}

onFrame (4) {

// load bank 0, this assigns 1st 16 voices to the 16 available channels.

LoadBank(currentbank);

}

onFrame (5) {

stop();

}

function LoadBank(bank) {

// load the selected bank of voices into the 16 channels.

BankSel.text = bank;

cmd = "cmdret.text, midi, PatchBank, " add bank;

fscommand("XMethod",cmd);

}

Script from each of the keyboard keys. The MIDI note is hard coded.

on (press,dragOver) {

midi(96,1);

}

on (rollOut,release) {

midi(96,0);

}

Script from the Bank Selection keys.

on (release) {

currentbank=0;

LoadBank(currentbank);

}


FSCommand ActiveX Tutorial

Before continuing on the following sections, you should have a good grasp of fscommands and scripting.

Please see the tutorial FSCommand Tutorial if you do not currently have this knowledge.

The section Introduction (Active X) gives an overview of ActiveX, the way it works and the benefits it can provide.

Much of the following discussion involves an understanding of Visual Basic as the demonstration active X dll was created using that language.

A description of how to interface to a 3rd party Active X dll is given in the section FSCommand Active X Serial I/O (No knowledge of VB is required for this section.).

Consider the files in the Samples\ActiveX directory.

This directory contains tutorial examples and utility files that are used by the following Active X discussions.

This directory is installed as a sub directory of the SWiSH Studio\SampleFiles install path.

Normally this will be C:\Program Files\SWiSHstudio\SampleFiles\ActiveX

The following are not provided as detailed tutorials. They are example code and fscommand calls that demonstrate the use of Active X.

File Name | Description | Associated Tutorials
SWiSHstudioXtest.* | Demonstration VB project that demonstrates how to call functions defined in VB. | Newton, Quadratic and Midi
SWiSHstudioXtest.dll | This is the output from the SWiSHstudioXtest project. Use this DLL is used in a number of examples to demonstrate the ActiveX interface. | Newton, Quadratic and Midi
Newton.cls | Part of the source for the SWiSHstudioXtest.dll This VB class defines some simple functions that can be used to calculate some Newtonian physics. | Newton
Quadratic.cls | Part of the source for the SWiSHstudioXtest.dll This VB class calculates the points where a parabola crosses the X axis. | Quadratic
Midi.cls | Part of the source for the SWiSHstudioXtest.dll This VB class implements an interface to the microsoft winnm.dll. The winnm.dll allows users to control a midi interfaces that are installed on their system. see http://msdn.microsoft.com for more information on the winnm.dll | Midi
keyboard.* | demonstration .swi and .swf that calls the active x midi interface defined in Midi.cls | MidiExample and Midi
guitar.* | demonstration .swi and .swf that calls the active x midi interface defined in Midi.cls | Provided as an example only of the Midi component.

If you have Visual Basic 6.0 installed, you may want to view the section, Custom ActiveX Controls.

The file SWiSHstudioXtest.dll is an ActiveX DLL that supports the following controls:

Newton, Quadratic and Midi. The hyperlinks shown with each of those names, discusses the properties and methods that are available with each control.

To access the Active X dll, it is necessary to register it. See ActiveX registration for more information on how to register an Active X component.


Custom ActiveX Controls

The project can be found in the Samples/ActiveX directory.

Open the project by clicking on the SWiSHstudioXtest.vbp file. Note that the class files (*.cls) can also be viewed with a standard text editor if Visual Basic 6.0 is not available.

Note that each class, Newton.cls, Quadratic.cls and Midi.cls forms their own ActiveX component.

Note that registering the DLL causes each of the components to become defined. This can be verified through the use of the OLE/COM viewer (Look for SWiSHstudioXtest.Midi, SWiSHstudioXtest.Newton and SWiSHstudioXtest.Quadratic).

The Midi.cls file is probably the most interesting as it demonstrates how to interface with a system DLL. See MidiExample for a detailed description and example of how to create a Midi keyboard application using SWiSH Studio.


SWiSHStudioXtest.dll

This is a VB ActiveX dll. For additional information on how this DLL was created see the section Custom ActiveX Controls. The DLL demonstrates how Visual Basic can be used to create an ActiveX DLL that can then be accessed via the Active X fscommands.

The DLL supports 3 controls: Newton, Quadratic and Midi.

Examples on the use of each of those controls is given in the hyperlinked section.


Newton

This control implements some simple physics functions.

This control has the Prog ID of "SWiSHStudioXtest.Newton".

The control is defined in the Newton.cls class file. See Custom ActiveX Controls for more information.

Properties | Mode | Description
InitialVelocity | R/W | Sets or Gets the Initial Velocity
Accelleration | R/W | Sets or Gets accelleration.
Version | Read only | Displays the current version number
Methods |  | Description
Distance(t) |  | Given the time in seconds, calculates the distance based on the currently set initial velocity and accelleration.
Velocity(t) |  | Given the time in seconds, calculates the velocity based on the currently set initial velocity and accelleration.
Popup() |  | Displays a popup box.

To use this control (assuming the DLL is registered) you would use the following FSCommands:

The example assumes that ret.text is a dynamic text variable. This is used to show any return data.

fscommand("XOpen", "SWiSHstudioxtest.newton, nton"); // open connection, nton is alias name.

fscommand("XPropertyPut", "ret.text, nton, InitialVelocity, 1"); // initial velocity of 1m/s

fscommand("XPropertyPut", "ret.text, nton, Accelleration, -9.8"); // gravity in opposite direction to initial velocity.

fscommand("XMethod", "ret.text, nton, Distance, 2"); // find out how far in 2 seconds

// after this command, ret.text would show -17.6

fscommand("XCloseAll",""); // close all open ActiveX connections.


Quadratic

This control implements the Quadratic forumla:

x = -b +/- sqrt(b^2-4ac)/2a

to solve ax^2 + bx + c = 0

This control has the Prog ID of "SWiSHStudioXtest.Quadratic"

The control is defined in the Quadratic.cls class file. See Custom ActiveX Controls for more information.

Properties | Mode | Description
R1 | Read only | The first "root" or solution to the equation.
R2 | Read only | The second "root" or solution to the equation.
Methods |  | Description
Quadratic(a,b,c) |  | Calcualtes the values for the properties R1 and R2.

To use this control (assuming the DLL is registered) you would use the following FSCommands:

The example assumes that ret.text is a dynamic text variable. This is used to show any return data.

fscommand("XOpen", "SWiSHstudioxtest.quadratic, quad"); // open connection

fscommand("XMethod", "ret.text, quad, Quadratic, 1, -7, 12"); // calculate answer. ret.text shows 4:3

fscommand("XPropertyGet", "ret.text", quad, R1); // ret.text shows 4.000000

fscommand("XPropertyGet", "ret.text", quad, R2); // ret.text shows 3.000000

fscommand("XCloseAll",""); // close all open ActiveX connections.


Midi

This control implements Midi functions.

This control has the Prog ID of "SWiSHStudioXtest.Midi".

The control is defined in the Midi.cls class file. This class file is provided for your reference in the Samples\ActiveX directory.

See Custom ActiveX Controls for more information.

This control is an example of how existing system calls can be accessed via a small amount of additional Visual Basic "glue" code, thereby greatly expanding the capabilities of the fscommands.

In this case, the midi.cls file implements an interface to the Windows Multimedia SDK, winmm.dll which provides access to MIDI controllers.

A descrption of the system functions in the winmm.dll can be found at http://msdn.microsoft.com/ (search for winmm.lib and midi).

The files keyboard.swi and keyboard.swf in the Samples/ActiveX directory can be used to make a MIDI keyboard. See the section MidiExample for more information.

Properties | Mode | Description
OutNumDevs | Read Only | Returns the number of MIDI devices installed on the system. If this is 0, then none are installed.
ProdName | Read Only | Returns the Product Name. This is only valid after the LoadOutDevCaps(id) method has been called.
ManufId | Read Only | Manufacturer identifier of the device driver for the MIDI output device. For a list of identifiers, see the Manufacturer Indentifier topic in the Multimedia Reference of the Platform SDK. This is only valid after the LoadOutDevCaps(id) method has been called.
ProdId | Read Only | Product Identifier Product of the MIDI output device. For a list of product identifiers, see the Product Identifiers topic in the Multimedia Reference of the Platform SDK. This is only valid after the LoadOutDevCaps(id) method has been called.
DriverVers | Read Only | Version number of the device driver for the MIDI output device. The high-order byte is the major version number, and the low-order byte is the minor version number. This is only valid after the LoadOutDevCaps(id) method has been called.
Technology | Read Only | Returns one of the following numeric codes indicating the type of midi device. 1:MOD_MIDIPORT:output port 2:MOD_SYNTH:generic internal synth 3:MOD_SQSYNTH:square wave internal synth 4:MOD_FMSYNTH:FM internal synth 5:MOD_MAPPER:MIDI mapper 6:MOD_WAVETABLE:hardware wavetable synth 7:MOD_SWSYNTH:software synth This is only valid after the LoadOutDevCaps(id) method has been called.
Voices | Read Only | Number of voices supported by an internal synthesizer device. If the device is a port, this member is not meaningful and is set to 0. This is only valid after the LoadOutDevCaps(id) method has been called.
Notes | Read Only | Maximum number of simultaneous notes that can be played by an internal synthesizer device. If the device is a port, this member is not meaningful and is set to 0. This is only valid after the LoadOutDevCaps(id) method has been called.
ChannelMask | Read Only | Channels that an internal synthesizer device responds to, where the least significant bit refers to channel 0 and the most significant bit to channel 15. Port devices that transmit on all channels set this member to 0xFFFF. This is only valid after the LoadOutDevCaps(id) method has been called.
SupportMask | Read Only | Bitmap defining capabilities of the system. 1:MIDICAPS_VOLUME:supports volume control 2:MIDICAPS_LRVOLUME:separate left-right volume control 4:MIDICAPS_CACHE:supports patch caching 8:MIDICAPS_STREAM:driver supports midiStreamOut directly This is only valid after the LoadOutDevCaps(id) method has been called.
Methods |  | Description
LoadOutDevCaps(id) |  | Loads the Output Device Capabilities for the given ID. These can then be accessed via the Properties described above. Note: Device IDs seem to start from -1, so a system with 3 devices will have -1, 0 and 1.
OutOpen(id) |  | Opens the midi device according to the id. Returns one of the MIDI error codes below.
OutClose() |  | Closes the open midi device. Returns one of the MIDI error codes below.
OutShortMessage(Msg) |  | Outputs a short message to the midi device. Msg is a long integer. You are required to pack each of the bytes appropriately. The header (command) byte is actually the least significant byte in the integer (due to intel byte ordering).
NoteStart(channel, note, velocity) |  | Starts a note playing. channel: The midi channel to use (0..15) note: The midi note. 60=middle C, 61=C# etc. Highest note is 127. velocity: Simulates the loudness or the speed at which the key is struck. 0-127. A value of 0 will stop the note playing.
NoteStop(channel, note) |  | Stops a note playing. channel: The midi channel to use (0..15) note: The midi note. 60=middle C, 61=C# etc. Highest note is 127.
Patch(channel, voice) |  | Maps one of the 127 available voices onto one of the 16 channels. channel: The midi channel to use (0..15) voice: The voice id (0..127) eg. 0 = piano, 9 = precussion etc.
PatchBank(bank) |  | Maps a bank of 16 voices to the available channels. bank must be in the range 0..7 Bank 0 represents voices 0..15 Bank 1 represents voices 16..31 etc. eg. PatchBank(2) will map voice 32->channel 0, 33->channel 1 etc.

Standard MIDI errors: (Obtained from mmsystem.h Microsoft SDK header file)

Error Acronym | Code | Description
MMSYSERR_NOERROR | 0 | no error
MMSYSERR_ERROR | 1 | unspecified error
MMSYSERR_BADDEVICEID | 2 | device ID out of range
MMSYSERR_NOTENABLED | 3 | driver failed enable
MMSYSERR_ALLOCATED | 4 | device already allocated
MMSYSERR_INVALHANDLE | 5 | device handle is invalid
MMSYSERR_NODRIVER | 6 | no device driver present
MMSYSERR_NOMEM | 7 | memory allocation error
MMSYSERR_NOTSUPPORTED | 8 | function isn't supported
MMSYSERR_BADERRNUM | 9 | error value out of range
MMSYSERR_INVALFLAG | 10 | invalid flag passed
MMSYSERR_INVALPARAM | 11 | invalid parameter passed
MMSYSERR_HANDLEBUSY | 12 | handle being used simultaneously on another thread
MMSYSERR_INVALIDALIAS | 13 | specified alias not found
MMSYSERR_BADDB | 14 | bad registry database
MMSYSERR_KEYNOTFOUND | 15 | registry key not found
MMSYSERR_READERROR | 16 | registry read error
MMSYSERR_WRITEERROR | 17 | registry write error
MMSYSERR_DELETEERROR | 18 | registry delete error
MMSYSERR_VALNOTFOUND | 19 | registry value not found
MMSYSERR_NODRIVERCB | 20 | driver does not call DriverCallback
MMSYSERR_MOREDATA | 21 | more data to be returned
MMSYSERR_LASTERROR | 21 | last error in range

Here are the fscommands you would use to play some tones and examine properties of your midi devices.

You may get error returns if you have no sound cards installed on your system. The returned device names may be different on your system.

fscommand("XOpen", "swishstudioxtest.midi, midi"); // open the MIDI ActiveX interface

returns : -105

This is an error condition. It was caused by the fact that the active X component was not registered. To register the component, open a command prompt at the directory containing the dll then type the command

"regsvr32 swishstudioxtest.dll"

You should get a message that the registration worked. If you re-try the command you should get a return value of 0.

The error could also be caused by incorrect naming of the component. Use the OLE/COM viewer to check for correct naming and registration.

fscommand("XOpen", "swishstudioxtest.midi, midi"); // open the MIDI ActiveX interface

returns : 0

fscommand("XMethod", "ret.text, midi, loadoutdevcaps, 0"); // Loads the midi device properties for device 0

returns 0, ret.text = 0

fscommand("XPropertyGet", "ret.text, midi, ProdName"); // Gets the name of midi device 0

returns 0, ret.text = SoundMAX WDM MIDI

fscommand("XMethod", "ret.text, midi, loadoutdevcaps, -1"); // Loads the midi device properties for device -1

returns 0, ret.text = 0

fscommand("XPropertyGet", "ret.text, midi, ProdName"); // Gets the name of midi device -1

returns 0, ret.text = Microsoft MIDI Mapper

fscommand("XMethod", "ret.text, midi, loadoutdevcaps, 2"); // Loads the midi device properties for device 2

returns 0, ret.text = 2

the ret.text value of 2 means MMSYSERR_BADDEVICEID - This device does not exist on my system.

fscommand("XMethod", "ret.text, midi, OutOpen, -1"); // Open the Microsoft MIDI Mapper

returns 0, ret.text = 0

fscommand("XMethod", "ret.text, midi, PatchBank, 0"); // Patch voices 0..15 to channels 0..15

returns 0, ret.text = OK

fscommand("XMethod", "ret.text, midi, NoteStart, 0, 60, 127"); // Play middle C, piano

returns 0, ret.text = 0

fscommand("XMethod", "ret.text, midi, NoteStart, 9, 60, 127"); // Play precussion

returns 0, ret.text = 0

fscommand("XMethod", "ret.text, midi, NoteStart, 10, 60, 127"); // Play another instrument (middle C)

returns 0, ret.text = 0

fscommand("XMethod", "ret.text, midi, OutClose"); // Close the midi device.

returns 0, ret.text = 0

fscommand("XCloseAll", ""); // Close all ActiveX connections.

returns 0


FSCommand ActiveX Serial I/O

 Top Previous

This tutorial explains how to use the Serial Port Active X component (PortController) from Scientific Component.

After installing the component, you can use the OLE / COM viewer to view the installed components.

Note that the class has the ProgID=PortControllerMod.PortController.1. Make a note of this name. It is needed for all of the Active X commands.

Please read the help file that accompanies the Serial Port Active X component as it defines the Methods and Properties that are used to control the serial port. The following fscommands can then be used to configure and use the serial port:

fscommand("XOpen", "PortControllerMod.PortController.1, P1");

Return value should be 0. Connection now referred to as P1 in subsequent calls. Note that as the DLL was already installed and registered, there was no need to include the DLL name in the XOpen call.

fscommand("XMethod", "ret.text, P1, Open, com1");

Return value should be 0. The dynamic text string ret.text should contain "Empty". This command opens the serial port.

fscommand("XPropertyGet", "ret.text, P1, BaudRate");

Reads the current baud rate. Return value should be 0. Baud rate is placed into ret.text which is assumed to be a dynamic text variable. On test system it displayed "9600".

fscommand("XPropertyPut", "ret.text, P1, BaudRate, 2400");

Return value should be 0. The dynamic text string ret.text should contain "OK". This command configures the serial port. (Baud rate set to 2400).

fscommand("XPropertyPut", "ret.text, P1, Parity, 0");

Return value should be 0. The dynamic text string ret.text should contain "OK". This command configures the serial port. (Parity set to none).

fscommand("XPropertyPut", "ret.text, P1, StopBits, 1");

Return value should be 0. The dynamic text string ret.text should contain "OK". This command configures the serial port. (Stop bits = 1).

fscommand("XMethod", "ret.text, P1, Write, hi this is a test message");

Return value should be 0. The dynamic text string ret.text should contain "0". This command sends the text "hi this is a test message" down the serial line.

if response text is then typed on an attached terminal...

fscommand("XMethod", "ret.text, P1, Read");

Will read any buffered recieved characters. Return value should be 0. The dynamic text string ret.text should contain the recieved text.

fscommand("XMethod","ret.text, P1, Close");

Closes the open serial port. Return value should be 0. The dynamic text string ret.text should contain "Empty".

fscommand("XClose", "P1");

Closes the ActiveX session. Return value should be 0.

Notes:

As there is no way to pass binary values via fs commands, the ReadBinary and WriteBinary methods cannot be used.