Developer Notes [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
The ANIMATE object is a Windows GUI control that plays a very basic AVI (Audio-Video Interleaved) file.

It is normally used to indicate system activity during lengthy operations such as copying and searching for files, and prior to the release of Windows Vista it was a core part of the Windows Explorer shell. Since then it has been somewhat deprecated in that role, but the control is still part of Windows and available for use with OpenInsight.

{{100__animate_object_image_1.png?403x271}}

====== Developer Notes ======

  - Early versions of the control (prior to ComCtl32.dll v6) used a separate thread to play the animation, but this was removed from version 6 (i.e. from Windows XP onwards when using visual styles). In this case you //must// call the SYSTEM object PROCESSEVENTS or PROCESSMESSAGES methods frequently during any long running process to allow the Animation control to play the file as it now uses an internal TIMER event.
  - The control can display an AVI file originating from either an uncompressed AVI file or from an AVI file that was compressed using run-length (BI_RLE8) encoding. It must //not// contain a sound channel.
  - Several standard Windows AVI files are supplied with OpenInsight for common operations such a file copying, moving, deleting and so on.
  - Equated constants for the ANIMATE object can be found in the PS_ANIMATE_EQUATES insert record.
  - Equated constants the Windows API Animate messages and styles can be found in the MSWIN_ANIMATE_EQUATES insert record.



====== ANIMATE Properties ======

The ANIMATE object supports the following properties

^Name       ^Description                                                                     ^
|AUTOPLAY   |Specifies if the AVI file begins playing as soon as it is opened.               |
|CENTER     |Centers the AVI file in the ANIMATE control                                     |
|CLIPNAME   |Specifies the name of the AVI file to play.                                     |
|REPETITIONS|Specifies the number of times the animation should play.                        |
|STARTFRAME |Specifies the frame number where the animation should start playing from.       |
|STOPFRAME  |Specifies the frame number where the animation should stop playing.             |
|TRANSPARENT|Indicates that the animation should be displayed using a transparent background.|

The following Common GUI Object properties are not supported:

  * FOCUS
  * FONT
  * FORECOLOR
  * NEXT
  * PREVIOUS
  * TEXT

===== AUTOPLAY property =====

=== Description ===

Specifies if the AVI file beings playing as soon as it is opened.

=== Property Value ===

The AUTOPLAY property is a Boolean value of TRUE$ or FALSE$.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // immediately//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : ".\avi\filecopyxp.avi"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray )         
   

=== See Also ===

N/a.

===== CENTER property =====

=== Description ===

Centers the animation in the middle of the control when set, otherwise the animation is displayed in the top-left position.

=== Property Value ===

The CENTER property is a Boolean value of "0" (FALSE$) or "1" (TRUE$).

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // immediately in the centre of the control//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$

   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CENTER"
   DataArray := @Rm : TRUE$
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : ".\avi\filecopyxp.avi"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray )            
   

=== See Also ===

N/a.

===== CLIPNAME property =====

=== Description ===

Specifies the name of the AVI file to play.

=== Property Value ===

The CLIPNAME property can be the name of an actual file, or the name of a resource contained in an EXE or DLL. If the latter then it should be specified in the format:

<filename> '#' <resourceID>

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

The control can display an AVI file originating from either an uncompressed AVI file or from an AVI file that was compressed using run-length (BI_RLE8) encoding. It must not contain a sound channel.

=== Example ===

  
   // Example://
   ////
   // Open an AVI file contained in Shell32.dll with an ID of 43506//
   // and begin playing immediately in the centre of the control//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$

   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CENTER"
   DataArray := @Rm : TRUE$
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : "shell32.dll#43506"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray )            
   

=== See Also ===

N/a.

===== REPETITIONS property =====

=== Description ===

Specifies the number of times to play the animation.

=== Property Value ===

The REPETITIONS property is an integer value that specifies the number of times to play the animation. If set to -1 (the default) then the clip plays indefinitely.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

  
   // Example://
   ////
   // Open an AVI file contained in Shell32.dll with an ID of 43506//
   // and begin playing immediately for a total of 10 times.//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$

   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "REPETITIONS"
   DataArray := @Rm : 10
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : "shell32.dll#43506"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray )
      

=== See Also ===

N/a.

===== STARTFRAME property =====

=== Description ===

Specifies the frame number from which to begin playing.

=== Property Value ===

The STARTFRAME property is an integer value that specifies the frame number to start playing from. The value must be less than the STOPFRAME value and less than 65536. It defaults to 1.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

  
   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // immediately from frame 4.//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$

   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "STARTFRAME"
   DataArray := @Rm : 4
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : ".\avi\filecopyxp.avi"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray )
      

=== See Also ===

N/a.

===== STOPFRAME property =====

=== Description ===

Specifies the last frame number to display when playing a clip.

=== Property Value ===

The STOPFRAME property is an integer value that specifies the frame number to stop playing at. The value must be -1 (the default) to specify the last frame in the clip, or be greater than the STARTFRAME value and less than 65536.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

  
   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // immediately from frames 4 to 8//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$

   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "STARTFRAME"
   DataArray := @Rm : 4
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "STOPFRAME"
   DataArray := @Rm : 8
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : ".\avi\filecopyxp.avi"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray )   
      

=== See Also ===

N/a.

===== TRANSPARENT property =====

=== Description ===

Indicates that the animation should be displayed using a transparent background.

=== Property Value ===

The TRANSPARENT property is a Boolean value of "0" (FALSE$) or "1" (TRUE$). When set to TRUE$ the top-left pixel in the animation frame is assumed to be the AVI file background color – any pixels matching this color are instead painted the same color as the control's BACKCOLOR property.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

This control is sensitive to the order in which properties are set. To ensure that the transparency is implemented properly set the BACKCOLOR and the TRANSPARENT property before you set the CLIPNAME property.

=== Example ===

        
   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // immediately with a transparent background//
   
   $Insert Logical
   
   ObjxArray =        @Window : ".ANI_COPYING"
   PropArray =        "AUTOPLAY"
   DataArray =        TRUE$

   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "BACKCOLOR"
   DataArray := @Rm : -1 ; // transparent//
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "TRANSPARENT"
   DataArray := @Rm : TRUE$
   
   ObjxArray := @Rm : @Window : ".ANI_COPYING"
   PropArray := @Rm : "CLIPNAME"
   DataArray := @Rm : ".\avi\filecopyxp.avi"
   
   Call Set_Property_Only( ObjxArray, PropArray, DataArray ) 
      

=== See Also ===

N/a.

====== ANIMATE Methods ======

The ANIMATE object supports the following methods:

^Name^Description                       ^
|PLAY|Begins playing the animation file.|
|STOP|Stops playing the animation file. |

===== PLAY Method =====

=== Description ===

Begins the playback of an animation file.

=== Syntax ===

bSuccess = Exec_Method( CtrlEntID, |

"PLAY", |

Repetitions, |

StartFrame, |

StopFrame )

=== Parameters  ===

^Name      ^Required^Description                                                                                                      ^
|Repetitons|No      |Specifies the number of times to play the animation. Defaults to -1. See the REPETITIONS property above.         |
|StartFrame|No      |Specifies the frame number from which to begin playing. Defaults to 1. See the STARTFRAME property above.        |
|StopFrame |Yes     |Specifies the last frame number to display when playing a clip. Defaults to -1. See the STOPFRAME property above.|

=== Returns ===

"1" (TRUE$) if the clip was started successfully, "0" (FALSE$) otherwise.

=== Remarks ===

N/a.

=== Example ===

        
   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // from frames 4 to 8, with 10 repetitions//
   
   $Insert Logical
   
   Call Set_Property_Only( @Window : ".ANI_COPYING", |
                           "CLIPNAME",               |
                           ".\avi\filecopyxp.avi" )

   Call Exec_Method( @Window : ".ANI_COPYING", "PLAY", 10, 4, 8 )
        

=== See Also ===

N/a.

===== STOP Method =====

=== Description ===

Stops the playback of an animation file.

=== Syntax ===

bSuccess = Exec_Method( CtrlEntID, "STOP" )

=== Parameters  ===

N/a.

=== Returns ===

"1" (TRUE$) if the clip was stopped successfully, "0" (FALSE$) otherwise.

=== Remarks ===

N/a.

=== Example ===

     
   // Example://
   ////
   // Open an AVI file called "FileCopyXP.avi" and begin playing//
   // immediately, stopping after some process has finished//
   
   $Insert Logical
   
   Call Set_Property_Only( @Window : ".ANI_COPYING", |
                           "CLIPNAME",               |
                           ".\avi\filecopyxp.avi" )

   Call Exec_Method( @Window : ".ANI_COPYING", "PLAY" )
   
   // Do long running data process ....//
   
   Call Exec_Method( @Window : ".ANI_COPYING", "STOP" )   
   

=== See Also ===

N/a.