The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Win32-MSAgent-0.03
River stage zero No dependents
/ Win32::MSAgent

NAME

Win32::MSAgent - Interface module for the Microsoft Agent

SYNOPSIS

    use Win32::MSAgent;
    my $agent = Win32::MSAgent->new('Genie');

    my $char = $agent->Characters('Genie');
    $char->Voice('Dutch', 'Alexander');
    $char->SoundEffectsOn(1);
    $char->Show();

    $char->MoveTo(300,300);
    sleep(5);

    foreach my $animation ($char->AnimationNames)
    {
        my $request = $char->Play($animation);
        $char->Speak($animation);
        my $i = 0;
        while (($request->Status == 2) || ($request->Status == 4))
        { $char->Stop($request) if $i >10; sleep(1);  $i++}
    }

DESCRIPTION

Win32::MSAgent allows you to use the Microsoft Agent 2.0 OLE control in your perl scripts. From the Microsoft Website: "With the Microsoft Agent set of software services, developers can easily enhance the user interface of their applications and Web pages with interactive personalities in the form of animated characters. These characters can move freely within the computer display, speak aloud (and by displaying text onscreen), and even listen for spoken voice commands."

Since the MS Agent itself is only available on MS Windows platforms, this module will only work on those.

PREREQUISITES

In order to use the MSAgent in your scripts, you need to download and install some components. They can all be downloaded for free from http://www.microsoft.com/msagent/devdownloads.htm

1. Microsoft Agent Core Components
2. Localized Language Components
3. MS Agent Character files (.acs files)
4. Text To Speech engine for your language
5. SAPI 4.0 runtime

Optionally you can install the Speech Recognition Engines and the Speech Control Panel. The Speech Recognition part of MS Agent is not supported in this version of Win32::MSAgent

USAGE

The POD documentation here is not complete. I will continue to write more documentation in upcoming versions. In this version the Agent control and the Characters object are implemented. No events are implemented yet, nor any of the Speech Recognition stuff.

$agent = Win32::MSAgent->new([charactername])

The constructor optionally takes the name of the character to load. It loads the MS Agent OLE control, connects to it, and if the character name is supplied, it loads that character in the Characters object already. It returns the Win32::MSAgent object itself.

$agent->ShowDefaultCharacterProperties([X,Y])

Calling this method displays the default character properties window (not the Microsoft Agent property sheet). If you do not specify the X and Y coordinates, the window appears at the last location it was displayed

$agent->Connected(boolean)

Returns or sets whether the current object is connected to the Microsoft Agent server.

$agent->RaiseRequestErrors(boolean)

This method enables you to determine whether the server raises errors that occur with methods that support Request objects. For example, if you specify an animation name that does not exist in a Play method, the server raises an error (displaying the error message) unless you set this property to False.

$char = $agent->Characters(character)

This method returns the character object for the character you specify. If you don't specify a charactername, it returns the object for the character you previously 'Load'-ed.

$agent->Characters->ListVoices(languagename)

This method can be called on a Character object. It lists all possible voices for a certain language. It does not list voices nor languages that are installed on your system! Just the ones that you could install and use with MS Agent. You can query the correct id for a language from ListLanguages

$agent->Characters->ListLanguages

This method can be called on a Character object. It lists all possible languages you could use with MS Agent. Again, these are not the installed languages, just the ones MS Agent could recognize.

$agent->Characters->Load(id, acsfile)

You can load characters from the Agent subdirectory by specifying a relative path (one that does not include a colon or leading slash character). This prefixes the path with Agent's characters directory (located in the localized Windows\msagent directory). For example, specifying the following would load Genie.acs from Agent's Chars directory:

   $agent->Characters->Load("genie", "genie.acs")

You can also specify your own directory in Agent's Chars directory.

   $agent->Characters->Load("genie", "MyCharacters\\genie.acs")

$char->Show

This method shows the character on whose object it is called

$char->Hide

This method hides the character on whose object it is called

$char->Play(animation)

This method lets the character do the animation you tell it to. You can get a list of all animations that a certain character supports by calling AnimationNames

$char->Interrupt(request)

The Play, Speak, Move, and other 'animation' methods return request objects. If you want to interrupt the animation, call this method on the character with the returned request object from the action you want to interrupt.

$char->Stop(request)

Like the Interrupt method, this does not only interrupt the action, it completely stops it. The author of this module does not completely see the difference between the two, since there is no 'Resume' method to call on an interrupted action. With $request->Status however you can find out _why_ an action is stopped... See below for more info on the Request object.

$char->StopAll([type])

If you call this method without any parameters, it stops every action for this character. You can however supply a 'type' parameter, indicating which types of actions should be stopped:

(You can also specify multiple types by separating them with commas. )

"Get"

To stop all queued Get requests.

"NonQueuedGet"

To stop all non-queued Get requests (Get method with Queue parameter set to False).

"Move"

To stop all queued MoveTo requests.

"Play"

To stop all queued Play requests.

"Speak"

To stop all queued Speak requests.

Activate

GestureAt

Get

Listen

MoveTo

ShowPopupMenu

Wait

Think

Speak

@animations = $char->AnimationNames()

Voice

Active

AutoPopupMenu

Visible

Speed

Pitch

LanguageID

TTSModeID

Height

Width

HelpModeOn

SoundEffectsOn

Please take the MS Agent Platform SDK helpfile (download from http://www.microsoft.com/msagent/devdownloads.htm) for more documentation on the various methods and properties.

The Request object

yadayadayada

BUGS

Hey! Give me some slack! This is only version 0.02! Sure there are bugs!

SUPPORT

The MS Agent itself is supported on MS' public newsgroup news://microsoft.public.msagent You can email the author for support on this module.

AUTHOR

        Jouke Visser
        jouke@cpan.org
        http://jouke.pvoice.org

COPYRIGHT

Copyright (c) 2002 Jouke Visser. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).