AnimManager 1.0
Copyright (c) 1991 INOVAtronics, Inc.
by James Nelson, INOVAtronics.

PURPOSE:

  The purpose of the AnimManager is to provide a means for CanDo
  application to play and control full screen animations.  The AnimManager
  runs as a separate module, which the CanDo application can control
  through the use of ARexx message passing, as will be described below.

  To give further control of the Animation, AnimManager allows for events
  to be associated with reaching particular frames.  If a FrameMark is
  attached to a frame, a message will be sent to your application, via an
  ARexx object.

  AnimManager also allows for Buttons areas to be specified on the
  Animation screen.  When these are hit, messages can will be sent to
  your Application in the same manner as in the FrameMarks.

LIMITS OF VERSION 1.0:

  The AnimManager 1.0 is only capable of playing and controlling full
  (non-overscan) screen animations created with or saved from Deluxe Paint
  III (tm).  Unfortunately, not all animation-creation programs interpret
  the ANIM5 IFF format in the same way.  Since CanDo's internal animation
  system only supports Deluxe Paint Brush Anims, I thought that the DPaint
  ANIM5 format would be the best of the many ANIM5 format variations to use
  in AnimManager.  With later revisions to the AnimManager, other ANIM5
  formats may be supported.  To ensure this, please write to us and let us
  know of any additional features which you would like AnimManager to have,
  and any other animation tools which you would like AnimManager to be
  compatible with.

RUNNING ANIMMANAGER:

  AnimManager can be run from a Shell with the following form:

    AnimManager -t{TalkTo} -l{ListenTo}

  where the TalkTo is the name of the port which AnimManager will send
  its messages to, and the ListenTo is the name of the port AnimManager
  will receive messages from.  The Listento defaults to "AnimRexxPort".

  If you want your CanDo Deck to run the AnimManager automatically, then
  you can place a script like the following into your Deck's OnStartUp
  (BeforeAttachment) Script:

    ListenTo "AnimEvent"
    SpeakTo "AnimRexxPort"
    IfError
       Dos "run >NIL: <NIL: YOURPATH:AnimManager -tAnimEvent"
       Let TimeOut = 50   ; MAX timeout
       Loop
          Delay 0,0,10
          SpeakTo "AnimRexxPort"
          IfError
             Let FoundAnimPort = FALSE
          Else
             Let FoundAnimPort = TRUE
          EndIf
          Let TimeOut = TimeOut - 1
       Until FoundAnimPort OR (TimeOut = 0)
    Else
       Let FoundAnimPort = TRUE
    EndIf
    If NOT FoundAnimPort
       Quit              ;Exit if we could not open the AnimManager
    EndIf

  The only part of the above script you will need to change is the word
  YOURPATH.  This must be changed to the actual path in which AnimManager
  is located on your system.

AREXX COMMANDS:

  All the controlling commands of AnimManager are accessible through ARexx
  communication using CanDo (ARexx not required).  Before using these
  commands, your CanDo Deck must first establish communication with the
  AnimManager.  It can do so by using the SpeakTo command as follows:

    SpeakTo "AnimManagerPort"

  The AnimManagerPort is AnimManager's ARexx port.  After the SpeakTo
  command has been performed (usually within your OnStartUp script), every
  command to the AnimManager can be sent with the SendMessage script (e.g.
  SendMessage "Version").

I.   COMMANDS OF INQUIRY:

     Help
     QueryLexicon

       Help and QueryLexicon are identical functions.  Each returns a list
       of all the commands supported by AnimManager.  This list can be
       typed into a document buffer as follows:

          SendMessage "Help"
          WorkWithDocument "AnimManagerCommands"
          Type MessageReturned,NewLine

       If "AnimManagerCommands" was the document used by a Memo Object,
       then you would see a list of these commands in your Memo Object display.

     Version

       This command returns a string containing the current version number
       of AnimManager.

     GetStatus

       This command returns a string containing information about the
       current state of the AnimManager in the following format:

         STATUS CURRENTFRAME THEDIRECTION NUMBEROFFRAMES JIFFIESPERUPDATE

       This information can be read as follows:

          SendMessage "GetStatus"
          Let Status             = GetWord(MessageReturned,1," ")
          Let CurrentFrame       = GetWord(MessageReturned,2," ")
          Let TheDirection       = GetWord(MessageReturned,3," ")
          Let NumberOfFrames     = GetWord(MessageReturned,4," ")
          Let JiffiesPerUpdate   = GetWord(MessageReturned,5," ")

       The values of Status can be either NotVisible, Paused, or Playing,
       and the values of TheDirection can be either Forward or Backward.
       The rest are integers.

       All of the following commands which change the state of the
       AnimManager will reply with this status string when they are used.

II.  FILE CONTROL

     LoadAnim {Anim File Name}

       This command loads an animation into the AnimManager, but does not
       begin to play the animation or show the animation.  This command can
       be used from within a CanDo deck as follows:

          SendMessage "LoadAnim Anim:MyAnimation.anim"

     Flush

       This command will completely remove a loaded animation from memory,
       causing the AnimManager to return to its original state.

     Quit

       This command shuts down the AnimManager, removing it from memory.

III. VIEWING CONTROL

     Play [Forward|Backward {numframes}]

       This command begins to play the Animation starting with its current
       frame (which is 1 when loaded).  If the Animation is not currently
       visible, then the screen will be opened before the animation begins
       to play.  Optionally, you can specify the direction which the
       Animation is to play, and also the number of frames to play can be
       specified.  In this manner, you can tell the Animation to play 5
       frames forward, then 4 frames backward as follows:

          SendMessage "Play Forward 5"
          SendMessage "Play Backward 4"

     Pause

       If the Animation is playing, this command will freeze the Animation
       at the frame it was showing when this command was used.  The current
       frame will remain visible.

     Step [Forward|Backward]

       When paused, you can step through the animation a frame at a time,
       either forward or backward, with this command.

     PlayTo {frame} [Forward|Backward]

       This command behaves similarly to the Play command, except it allows
       you to specify the exact frame number on which you want the
       Animation to pause.

     GotoFrame {framenum}

       This command moves to the specified frame and then will pause the
       Animation.  If the Animation was not currently visible, then this
       command will merely change the current frame number, leaving the
       animation invisible.

     SetUpdateSpeed {JiffiesPerUpdate}

       By default, the AnimManager will play the Animation at the speed in
       which it was designed to play when saved.  If you wish to change the
       speed which it plays, this command can be used.  The value of
       JiffiesPerUpdate specifies how many screen updates to keep each
       frame visible before moving to the next frame.  On NTSC machines,
       each jiffy lasts 1/60th of a second.  On PAL machines, a jiffy is
       1/50th of a second.

     Toggle

       This command changes the direction which the animation is playing.

     SetEndOfAnim Repeat|PingPong|Pause

       This command allows you to specify what should occur when your
       Animation reaches the last frame.  If Repeat is set, then the
       animation will continue to play in a loop.  If PingPong is set, then
       the animation will reverse directions at the first and last frame.
       If Pause is set, then the animation will stop playing when it
       reaches the last frame.  Each of these options is set in the
       following manner:

          SendMessage "SetEndOfAnim Repeat" ; I want the animation to loop
          SendMessage "SetEndOfAnim PingPong" ;Change directions
          SendMessage "SetEndOfAnim Pause" ; Stop playing at end of anim.


IV.  SCREEN CONTROL

     Screen ToFront|ToBack|On|Off

       AnimManager allows you to control the visibility of the Animation.
       The viewing screen can be turned on (if an animation is loaded), it
       can be turned off, it can be moved in front of all screens, or it
       can be moved behind all screens.  Each of these options is performed
       as follows:

          SendMessage "Screen ToFront"
          SendMessage "Screen ToBack"
          SendMessage "Screen On"
          SendMessage "Screen Off"

       If an animation is playing and the screen is turned off, then the
       animation will pause on that frame.  Turning the screen back on at
       this point would show the animation in paused mode.

     MoveScreen {dx},{dy}

       This command works just the like MoveScreen Command within CanDo.
       It allows you to move the Animation Screen up or down the the given
       increments.

V.   COMMUNICATION CONTROL

     SetTalkTo {ListenTo Port Name}

       This command allows you to tell the AnimManager the name of the
       Port you will be expecting to receive messages from FrameMarks and
       Button events.  This must correspond the the ListenTo command you
       use within your CanDo Application, (e.g AnimEvent in the example
       startup script above.)  If you do not use this command, then the
       FrameMark and Button events will not occur.

VI.  FRAME MARK EVENTS

     SetFrameMark {messagetosendback},{framenum}

       Use this to set up an event to occur on a given frame of the
       animation.  When the animation arrives at the specified frame, it
       will pass back the {messagetosendback} to the port you specified
       with the "SetTalkTo" command.  To receive the message, you will need
       an ARexx Object defined in your Card which will for the message (the
       first word of {messagetosendback}).  For example:

      Let Quote = """"  ; We need quotes around the messagetosendback
      Let MessageToSendBack = "Hello I've reached Frame Five!"
      SendMessage "SetFrameMark "||Quote||MessageToSendBack||Quote||",5"

       Given the above script, you will need an ARexx object which waits
       for the message "Hello".  Its Occurred script could look as follows:

         PrintText TheMessage,10,10

       The result of this script would be the words "I've reached Frame
       Five!" displayed on the card at location 10,10.

       The type of FrameMark which SetFrameMark sets up does not pause the
       the animation when it sends your animation a message.  While you are
       examining the message, the Animation will continue to play.  If
       you want the Animation to Pause while you are using its message,
       then use the SetInterruptFrameMark described below.

     ClearFrameMark {framenum}

       This command removes the FrameMark attacked to the given frame.

     SetInterruptFrameMark {messagetosendback},{framenum}

       This command is the same as SetFrameMark except that the Animation
       will pause while your ARexx Object's Occurred script is processing.

     ClearAllFrameMarks

       This command clears all FrameMarks from the Animation.

VII. THE BUTTON EVENTS

     AddButton {messagetosendback},{x},{y},{w},{h}

       This command places an invisible button on the Animation screen at
       the designated coordinates.  If the button is pressed, then it will
       send the {messagetosendback} to your application.  Please read the
       description and example for the command SetFrameMark above to
       understand how the message can be used.

     ClearButton {messagetosendback}

       Removes a button from the Animation screen.  The message must be
       exactly as defined by the AddButton routine.

     AddInterruptButton {messagetosendback},{x},{y},{w},{h}

       This is just like the AddButton command, except that the Animation
       will pause while the messagetosendback is being processed by you
       CanDo application.

     ClearAllButtons

       This removes all buttons from the Animation screen.