Action Command Reference

This section contains descriptions of each of the action commands found in NeoDX. After installing NeoDX, the actions below should automatically appear in VisualNEO for Windows’s Select an Action list in the NeoDX section. If you’re not familiar with the basic concept of using actions in VisualNEO for Windows, please read "Understanding Actions and Variables" in your VisualNEO for Windows User Guide or Help file.

Basic

dxPlaySoundFile

dxPlayVideoFile

dxPauseMedia

dxStopMedia

Basic actions are intended as drop-in replacements for VisualNEO for Windows's built-in multimedia actions.

Media Player

Mixer

Misc.

dxAddMarker

Purpose:

Add a new position marker to the media player. The marker is assigned a specific time index and associated with a script from your publication's Subroutine Action. The subroutine will automatically execute when the marker is reached during playback.

Markers can be used to synchronize playback with other actions for slide shows, presentations, etc. For example, you could set markers to changes pages at specific points during the narration of a story.

Category:

DirectX > Media Player

Syntax:

dxAddMarker "player id" "marker pos" "time format" "subroutine" "marker data"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

marker pos

A position from the beginning of the file. The position may be formatted in milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format for marker pos. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

subroutine

The name of a subroutine from your publication's Subroutine Action. The subroutine specified here will be automatically executed when the marker position is reached during playback. Subroutines are entered from the Actions page of VisualNEO for Windows's Book Properties screen.

marker data

Optional data to be associated with this marker. Data can be a string, number or variable. When this marker is triggered during playback, the contents of data will be copied to the [PlayerID.MarkerData] variable. You can access the contents of this variable and [PlayerID.MarkerPosition] from within the marker's subroutine. See Understanding NeoDX Variables for more information about player variables.

Example:

Set a marker to execute a subroutine called "SubOne" exactly 30 seconds into the file:

dxCreate "Rectangle1" "[Player1]" ""

dxOpenFile "[Player1]" "c:\multimedia\Beethoven.wma"

dxAddMarker "[Player1]" "30000" "Milliseconds" "SubOne" ""

dxPlay "[Player1]" "1"

You can use the marker data parameter to display messages or song lyrics during playback. Just insert [PlayerID.MarkerData] into a Text object and execute the following actions:

dxCreate "Rectangle1" "[Player1]" ""

dxOpenFile "[Player1]" "c:\multimedia\Happy Brithday.wma"

dxAddMarker "[Player1]" "1000" "Milliseconds" "" "Happy Birthday to you"

dxAddMarker "[Player1]" "3000" "Milliseconds" "" "Happy Birthday to you"

dxAddMarker "[Player1]" "5000" "Milliseconds" "" "Happy Birthday dear Sally"

dxAddMarker "[Player1]" "7000" "Milliseconds" "" "Happy Birthday to you..."

dxPlay "[Player1]" "1"

dxClearMarkers

Purpose:	Remove all position markers assigned to the media player. Individual markers can be removed using dxRemoveMarker.
Category:	DirectX > Media Player
Syntax:	dxClearMarkers "player id" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.
Example:	dxClearMarkers "[Player1]"

dxCloseFile

Purpose:	Close a media file previously opened with dxOpenFile. Calling dxCloseFile is optional since any files that are open when a publication is shutdown will be closed automatically.
Category:	DirectX > Media Player
Syntax:	dxCloseFile “player id” player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.
Example:	dxCloseFile "[Player1]"

dxCreate

Purpose:	Create a new DirectX media player and optionally specify a script from VisualNEO for Windows's Subroutine Action that you want executed if the current media file plays all the way to the end. You can leave the Rectangle Object field blank to create a non-visible media player. A unique identification number for the player will be returned in the Player ID Variable. Use this ID to identify the media player for other DirectX actions. See the NeoDX Tutorial topic for more information on dxCreate.
Category:	DirectX > Media Player
Syntax:	dxCreate "rectangle" "player id variable" " rectangle The name of an existing VisualNEO for Windows Rectangle object {bmc \NeoSoft Products\VisualNEO for Windows v4\Help NeoDX\RECTANGLE TOOL.BMP}. The Rectangle will serve as a host for the DirectX media player. Use VisualNEO for Windows's Tool Palette to create a Rectangle object on the page in your publication where you want the media player to appear. After executing dxCreate, the media player will appear within the boundaries of the Rectangle object. The background of the media player will be the same as the Rectangle object's fill color, so it may not be immediately apparent that anything has changed until you load a media file with dxOpenFile. The media player is only visible when running the publication. You can leave the Rectangle Object field blank to create a non-visible media player. This can be handy if you only want to play audio or music files that do not need to display anything on the screen. player id variable The name of the variable where this media player's unique identification number will be stored. This ID will be used to identify this media player for all other DirectX actions. See Understanding NeoDX Variables for more information about the significance of the player ID variable. subroutine (optional) The name of a subroutine from your publication's Subroutine Action. The subroutine specified here will be automatically executed if the media player plays all the way to the end of a file. Subroutines are entered from the Actions page of VisualNEO for Windows's Book Properties screen. Leave this parameter blank if you do not wish to use a subroutine.
Example:	dxCreate "Rectangle1" "[Player1]" "" You can omit the rectangle name to create an invisible media player which can be useful when you only need to play audio files. For example: dxCreate "" "[Player1]" "" A media player created in this manner won't be visible on-screen, but you can still access it using the player ID variable. For example: dxOpenFile "[Player1]" "c:\multimedia\Beethoven.wma"

dxDestroy

Purpose:	Destroys the media player object. Calling dxDestroy is optional since all media player objects will be destroyed automatically when the publication terminates.
Category:	DirectX > Media Player
Syntax:	dxDestroy “player id” player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.
Example:	dxDestroy "[Player1]"

dxFadeAndStop

Purpose:

Stop the currently playing media file after fading the volume.

Category:

DirectX > Media Player

Syntax:

dxFadeAndStop "player id" "duration" "time format" "target volume"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

duration

The approximate length of time it should take to perform the fade. The duration may be formatted as either milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format of duration. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

target volume

The target volume. When the target volume is reached, the player will stop. Specify the volume as a number between the current volume level and 0 (silence).

Example:

dxFadeAndStop "[Player1]" "3000" "Milliseconds" "0"

dxFadeIn

Purpose:

Slowly increase the media player's volume from the current level up to a specified volume setting.

Category:

DirectX > Media Player

Syntax:

dxFadeIn "player id" "duration" "time format" "target volume"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

duration

The approximate length of time it should take to perform the fade. The duration may be formatted as either milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format of duration. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

target volume

The target volume. Specify the volume as a number between the current volume level and 1000 (full volume).

Example:

dxFadeIn "[Player1]" "3000" "Milliseconds" "1000"

dxFadeOut

Purpose:

Slowly reduce the media player's volume from the current level until a specified target volume is reached.

Category:

DirectX > Media Player

Syntax:

dxFadeOut "player id" "duration" "time format" "target volume"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

duration

The approximate length of time it should take to perform the fade. The duration may be formatted as either milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format of duration. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

target volume

The target volume. Specify the volume as a number between the current volume level and 0 (silence).

Example:

dxFadeOut "[Player1]" "3000" "Milliseconds" "0"

dxFullScreenMode

Purpose:	Toggle the current video file between full screen and normal/windowed mode. This action only affects video files. If the media player does not contain a video file, the action will be ignored.
Category:	DirectX > Media Player
Syntax:	dxFullScreenMode "player id" "state" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur. state Use "True" to switch to full screen mode or "False" to return to normal/windowed mode.
Example:	dxFullScreenMode "[Player1]" "True" When the video is in full screen mode, you will not be able to access other parts of the publication or Windows. It's recommended that you assign a short cut key like Esc to a push button that sets the full screen mode to False.

dxGetMasterVol

Purpose:	Get the current master volume level and store the result in a variable.
Category:	DirectX > Mixer
Syntax:	dxGetMasterVol "variable" variable The name of the variable to store the volume level. The returned value will be a number between 0 and 1000. Full volume is 1000, and 0 is silence.
Example:	dxGetMasterVol "[vol]"

dxGetMute

Purpose:	Get the master volume mute state. Returns True if volume is muted.
Category:	DirectX > Mixer
Syntax:	dxSetMute "variable" variable The name of the variable to store the mute state. Returns "True" if sound is muted or "False" if not.
Example:	dxGetMute "[MuteState]"

dxGetVersion

Purpose:	Obtain the version number of the installed copy of DirectX. The version number is placed in a variable.
Category:	DirectX > Misc.
Syntax:	dxGetVersion “variable" variable The name of the variable where the version number will be stored. If DirectX is not installed the variable will contain a zero.
Example:	dxGetVersion "[DXVer]" If "[DXVer]" ">" "0" AlertBox "Success" "DirectX is installed!" Else AlertBox "Sorry" "DirectX is NOT installed!" EndIf

dxOpenFile

Purpose:	Load a media file into the media player. See NeoDX Tutorial for additional information on using this Action.
Category:	DirectX > Media Player
Syntax:	dxOpenFile "player id" “file name” player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur. file name The name of the media file to open.
Example:	dxOpenFile "[Player1]" "c:\multimedia\frogs.mpg" You can also combine dxOpenFile with VisualNEO for Windows's FileOpenBox action to select and open a file while your publication is running. For example: FileOpenBox "Open" "Any File\|." "c:\Multimedia" "[FileName]" "" If "[FileName]" "<>" "" dxOpenFile "[Player1]" "[FileName]" EndIf

dxPause

Purpose:	Pause the media player.
Category:	DirectX > Media Player
Syntax:	dxPause "player id" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.
Example:	dxPause "[Player1]"

dxPauseMedia

Purpose:	Pause an individual or all currently playing video or audio files started with dxPlaySoundFile or dxPlayVideoFile. This action is self-contained and does not require a media player object.
Category:	DirectX > Basic
Syntax:	dxPauseMedia "file name" file name Enter the file name of the media file to pause. Leave the file name blank to pause all playing media. Use "Sound" instead of a file name to pause all audio playback or "Video" to pause all video playback. This action only affects media files started with dxPlaySoundFile or dxPlayVideoFile.
Example:	dxPauseMedia "c:\multimedia\frogs.wav"

dxPlay

Purpose:	Play the current media file.
Category:	DirectX > Media Player
Syntax:	dxPlay "player id" "loop count" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur. loop count Number of times to repeat the playback of the file. You can specify a number from 1 to whatever, or enter the word "LOOP" to repeat the file continuously. You can interrupt a looping file by calling dxStop or dxPause.
Example:	dxPlay "[Player1]" "1"

dxPlayFromTo

Purpose:

Play the current media file starting and ending at specific points.

Category:

DirectX > Media Player

Syntax:

dxPlayFromTo "player id" "start pos" "stop pos" "time format" "loop count"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

start pos

The position in the file where the playback should begin. The position may be formatted as either milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

stop pos

The position in the file where the playback should end. The position may be formatted as either milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format for marker pos. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

loop count

Number of times to repeat the playback of the file. You can specify a number from 1 to whatever or enter the word "LOOP" to repeat the file continuously. You can interrupt a looping file by calling dxStop or dxPause.

Example:

Start playback eight seconds into the file and stop at 15 seconds:

dxPlayFromTo "[Player1]" "0:0:8:00" "0:0:15:00" "HMS" "1"

dxPlaySoundFile

Purpose:

Play an audio file. This is a DirectX version of VisualNEO for Windows's built-in PlaySoundFile action. This action is self-contained and does not require a media player object. You can use dxStopMedia to halt a sound started with this action.

Category:

DirectX > Basic

Syntax:

PlaySoundFile "file name" "mode"

file name

The name of the audio file you want to play.

mode

This is the method to use when playing the file. Mode may be one of the following:

Normal	Play the sound and continue with the next Action in the script.
Wait	Play the sound and suspend VisualNEO for Windows until the sound finishes.
Loop	Play the sound continuously in the background.

Example:

dxPlaySoundFile "c:\multimedia\crickets.wav" "Loop"

dxPlayVideoFile

Purpose:

Play a video file. This is a DirectX version of VisualNEO for Windows's built-in PlayVideoFile action. This action is self-contained and does not require a media player object. You can use dxStopMedia to halt a sound started with this action.

Category:

DirectX > Basic

Syntax:

dxPlayVideoFile "left" "top""width" "height" "filename" "mode"

left, top, width, height

The coordinates for the video’s left, top corner, width and height relative to the upper left corner of the publication. Use "-1" in left and top values to center on page. Use "-1" for width and height to use the video’s original size.

file name

The name of the audio file you want to play.

mode

This is the method to use when playing the file. Mode may be one of the following:

Normal	Play the sound and continue with the next Action in the script.
Wait	Play the sound and suspend VisualNEO for Windows until the sound finishes.
Loop	Play the sound continuously in the background.

Example:

dxPlayVideoFile "-1" "-1" "-1" "-1" "c:\samples\sales.avi" "Wait"

dxRemoveMarker

Purpose:

Remove a specific position marker assigned to the media player. The marker must have previously been created using dxAddMarker.

Category:

DirectX > Media Player

Syntax:

dxRemoveMarker "player id" "marker pos" "time format"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

marker pos

A position from the beginning of the file. The position may be formatted in milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format for marker pos. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

Example:

dxRemoveMarker "[Player1]" "30000" "Milliseconds"

dxRewind

Purpose:	Rewind the media player. The media player will automatically rewind when the end of the file is reached unless dxSetAutoRewind is set to False.
Category:	DirectX > Media Player
Syntax:	dxRewind "player id" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.
Example:	dxRewind "[Player1]"

dxSetAutoRewind

Purpose:	Enable or disable the media player's Auto-Rewind feature. Use True to enable or False to disable. When False, the media player must be rewound manually using dxSetPosition or dxRewind.
Category:	DirectX > Media Player
Syntax:	dxSetAutoRewind "player id" "status" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur. status The status of the Auto Rewind feature. Use "True" to turn Auto Rewind on or "False" to turn it off.
Example:	dxSetAutoRewind "[Player1]" "False"

dxSetBalance

Purpose:	Set the audio signal balance between the left and right channels/speakers.
Category:	DirectX > Media Player
Syntax:	dxSetBalance "player id" "balance" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur. balance This value can range from -1000 to 1000. Negative numbers shift the balance toward the left speaker and positive numbers shift the balance toward the right speaker. The value -1000 means the right speaker is effectively silent. The value 1000 means the left speaker is silent. A setting of 0 (zero) means that both channels are at full volume. This is the default setting.
Example:	dxSetBalance "[Player1]" "1000"

dxSetMasterVol

Purpose:	Set the master volume level. This is the same as setting the master volume in the Windows Control Panel.
Category:	DirectX > Mixer
Syntax:	dxSetMasterVol "volume" volume Specifies the volume, as a number between 0 and 1000. Full volume is 1000, and 0 is silence.
Example:	dxSetMasterVol "100"

dxSetMute

Purpose:	Mute the master volume.
Category:	DirectX > Mixer
Syntax:	dxSetMute "state" state Use "True" to disable all sound or "False" to enable.
Example:	dxSetMute "True"

dxSetPosition

Purpose:

Set the media player's playback position.

Category:

DirectX > Media Player

Syntax:

dxSetPosition "player id" "position" "time format"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

position

A position from the beginning of the file. The position may be formatted as either milliseconds or hours:minutes:seconds:ms depending on the time format specified below.

time format

The format of position. This may be one of the following:

Milliseconds	Indicates that marker pos is in milliseconds. There are 1000 milliseconds in a second.
HMS	Indicates that the marker pos is formatted as hours:minutes:seconds:ms. For example, zero hours, one minute and 10 seconds would look like: "00:01:10:00".

Example:

dxSetPosition "[Player1]" "00:01:00:00" "HMS"

dxSetRate

Purpose:	Set the media player's playback rate/speed. Some media formats do not support this option.
Category:	DirectX > Media Player
Syntax:	dxSetRate "player id" "rate" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player id is not valid, an error will occur. rate The playback speed as a fraction of the file's normal speed. Setting the rate to a number greater than 1.0 will result in faster playback. Rates between zero and 1.0 will play the file slower than normal. For example, to play at twice-normal speed, use the following: 2.0 Set the rate to 1.0 to play the file at normal speed.
Example:	dxSetRate "[Player1]" "1.5"

dxSetVideoMode

Purpose:

Set the mode used by the media player when displaying videos. This setting determines how videos are sized to fit within the media player window.

Category:

DirectX > Media Player

Syntax:

dxSetVideoMode "player id" "mode"

player id

A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.

mode

This may be one of the following options:

Normal	Display the video in its actual size regardless of the dimensions of the media player window. Portions of the video that fall outside the window will be clipped.
Stretch	Stretch or shrink the video image to fit within the media player window. The video will be distorted if its dimensions are significantly different from the media player window.
Aspect	Stretch or shrink the video image to fit within the media player window but maintain its original aspect ratio. The video will not be distorted.
Optimize	Display the video in its actual size if it will fit within the bounds of the media player window. Otherwise stretch the video and keep its aspect ratio intact. A combination of the Normal and Aspect modes. This is the default setting.

Example:

dxSetVideoMode "[Player1]" "Optimize"

dxSetVolume

Purpose:	Set the volume (amplitude) of the media player's audio signal. You can use the dxSetVolumeScale action to control how volume settings are applied.
Category:	DirectX > Media Player
Syntax:	dxSetVolume "player id" "volume" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur. volume Specifies the volume as a number between 0 and 1000. Full volume is 1000, and 0 is silence. When using the default Linear volume scale (see dxSetVolumeScale), settings are made in decibels, which can be calculated by multiplying the desired decibel level by 10. For example, a setting of 1000 would roughly equal 100 dB. When using the Logarithmic volume scale, settings represent a percentage of full volume. For example, a setting of 500 would be approximately 50% of full volume. A setting of 1000 (Full volume) reflects the user's default master volume setting as specified in the Windows Control Panel. You can use VisualNEO for Windows's SetVolume action to override the user's master volume if needed, but the media player's volume cannot exceed that specified in the Control Panel.
Example:	dxSetVolume "[Player1]" "1000"

dxSetVolumeScale

Purpose:

Use this action to select between Logarithmic and Linear volume scales. This action is typically executed at the beginning of a publication to change the volume scale from the default Linear setting to Logarithmic. This setting is global and affects all DX media players.

Category:

DirectX > Misc.

Syntax:

dxSetVolumeScale "mode"

mode

This may be one of the following options:

Logarithmic	Use a logarithmic formula to insure that adjustments made with dxSetVolume are constant across the entire output range. For example, using the logarithmic scale, a volume setting of 500 would be approximately 50% of full volume (1000).
Linear	Use the default DirectX volume scale (decibels). This mode simply passes volume settings to the DirectX API without making any adjustments. This is the default mode.

Example:

dxSetVolumeScale "Logarithmic"

dxShowErrors

Purpose:	When True, any problems that occur while processing DirectX commands will be displayed to the user in the form of error messages. When False no messages are displayed. When this feature is turned off, you can obtain the most recent error is by examining the global [dxError] variable. ShowErrors is set to True automatically when NeoDX is initialized.
Category:	DirectX > Misc.
Syntax:	dxShowErrors "status" status The status of the ShowErrors feature. Use "True" to turn ShowErrors on or "False" to turn it off.
Example:	dxShowErrors "False" When ShowErrors is turned off you can still check [dxError] to detect important errors and respond if needed. For example: dxOpenFile "[Player1]" "[PubDir]sample.mpg" If "[dxError]" ">" "" AlertBox "Sorry" "Unable to open that file." EndIf

dxStop

Purpose:	Stop the media player.
Category:	DirectX > Media Player
Syntax:	dxStop "player id" player id A variable containing the unique identifier for the media player obtained from dxCreate. If the player ID is not valid, an error will occur.
Example:	dxStop "[Player1]"

dxStopMedia

Purpose:	Stop an individual or all currently playing video or audio files started with dxPlaySoundFile or dxPlayVideoFile. This is a DirectX version of VisualNEO for Windows's built-in StopMedia action. This action is self-contained and does not require a media player object.
Category:	DirectX > Basic
Syntax:	dxStopMedia "file name" file name Enter the file name of the media file to stop. Leave the file name blank to stop all playing media. Use "Sound" instead of a file name to stop all audio playback or "Video" to halt all video playback. This action only affects media files started with dxPlaySoundFile or dxPlayVideoFile.
Example:	dxStopMedia "c:\multimedia\frogs.wav"