StartAnimation - ProGUI Reference Manual

Syntax

AnimationID = StartAnimation(Object, ID=#PG_Any, Duration=0, FPS=#Null, Flags=#Null, *UserData=#Null)

Description

Starts or continues an animation loop associated with a specific ProGUI object (Window or Widget). This triggers a sequence of events (#PG_Event_Animate or #PG_Event_AnimateSkin) allowing for time-based changes to the object's properties or appearance.

Parameters

Object
The handle of the ProGUI Window or Widget to which this animation should be attached.

ID (optional)
An integer identifier for this specific animation on the object. If #PG_Any is used, ProGUI generates a unique negative ID. Using a specific ID allows multiple animations to run concurrently on the same object or allows restarting/modifying an existing animation by using the same ID with the #PG_Animation_IsContinue flag. Default is #PG_Any.

Duration (optional)
The total duration of the animation in milliseconds (ms). If 0, the animation runs indefinitely until stopped by StopAnimation(). Default is 0.

FPS (optional)
The target frames per second for the animation's update events. If #Null or invalid, it defaults to the system's target FPS (#_AnimationTargetFPS, typically 60). The actual event rate may vary. Default is #Null.

Flags (optional)
Flags modifying the behavior. Default is #Null.

#PG_Animation_IsContinue : If an animation with the same `Object` and `ID` is already running, this flag causes the new `Duration` to be added to the existing animation's remaining duration instead of replacing it. If no animation is running with that ID, it starts a new one normally.

*UserData (optional)
A pointer to custom data that will be passed within the *UserData field of the PG_EventAnimate event structure dispatched by this animation. Default is #Null.

Return Value

Returns the integer ID of the animation (either the one provided or the one generated by ProGUI if #PG_Any was used). Returns #False (0) if the `Object` handle is invalid.

Remarks

Starting an animation initiates a sequence of events:

One #PG_Event_Animate event with State = #PG_Event_Animate_Start.
Multiple #PG_Event_Animate events with State = #PG_Event_Animate_Update, dispatched approximately according to the specified `FPS`. The event data includes `currentTime` (elapsed ms since start) and `deltaTime` (ms since last update).
If `Duration` > 0, one final #PG_Event_Animate event with State = #PG_Event_Animate_End when the duration is reached.

If the internal flag #_Animation_IsSkin is used (intended for skin transitions), the event type dispatched is #PG_Event_AnimateSkin instead.

Use AddEventHandler() with #PG_Event_Animate (or #PG_Event_AnimateSkin) to process these events and perform the actual animation logic, often using AnimationGetCurrentTime() and Transition_* functions.

The animation timing is managed by ProGUI's internal animation thread, which aims to sync with the display refresh rate using OS-specific mechanisms (like DirectComposition on Windows).

Example

IncludeFile "ProGUI_PB.pbi"

Structure MyAnimData
  TargetValue.d
  StartValue.d
  Widget.i
EndStructure

Procedure AnimateHandler(Object, EventType, *EventData.PG_EventAnimate, *UserData)
  Protected CurrentValue.d

  *animUserData.MyAnimData = *EventData\userData ; the userData passed to the StartAnimation() command not *UserData that could be passed to this event handler
  
  Select *EventData\state

    Case #PG_Event_Animate_Start

      Debug "Animation " + *EventData\id + " started for Widget " + *animUserData\Widget
      ; Optional: Initialize start value here if needed
      ; *animUserData\StartValue = WidgetGetSomeProperty(*animUserData\Widget) 
      
    Case #PG_Event_Animate_Update

      ; Calculate intermediate value using a transition function
      CurrentValue = Transition_EaseInOut(*EventData\currentTime, *animUserData\StartValue, *animUserData\TargetValue - *animUserData\StartValue, *EventData\duration)
      
      ; Apply the value (e.g., change widget position, opacity, etc.)
      WidgetSetOpacity(*animUserData\Widget, CurrentValue)
      ; WidgetRedraw(*animUserData\Widget) ; Redraw might be needed depending on what's animated

      Debug "Animation " + *EventData\id + " Update: Time=" + *EventData\currentTime + "ms, Value=" + StrD(CurrentValue)
      
    Case #PG_Event_Animate_End

      Debug "Animation " + *EventData\id + " ended"
      ; Ensure final value is set exactly
      WidgetSetOpacity(*animUserData\Widget, *animUserData\TargetValue)
      ; WidgetRedraw(*UserData\Widget) 
      FreeStructure(*animUserData) ; Free data allocated for this animation

  EndSelect

EndProcedure

StartProGUI()

MyWindow = CreateWindow(0, 0, 300, 200, "StartAnimation Example")
MyWidget = CreateWidget(100, 80, 100, 30) ; Let layout handle position
WidgetSetClass(MyWidget, "button") ; Assume skin exists

If MyWindow And MyWidget
  AddEventHandler(MyWidget, #PG_Event_Animate, @AnimateHandler())

  ; Setup data for animation
  *AnimData.MyAnimData = AllocateStructure(MyAnimData)
  If *AnimData
    *AnimData\Widget = MyWidget
    *AnimData\StartValue = WidgetGetOpacity(MyWidget) ; Get current opacity (e.g., 1.0)
    *AnimData\TargetValue = 0.2 ; Target opacity
    
    ; Start a 2-second animation to fade the widget
    AnimID = StartAnimation(MyWidget, #PG_Any, 2000, #Null, #Null, *AnimData) 
    Debug "Started animation with ID: " + AnimID
  EndIf

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)
  Repeat : Event = WaitWindowEvent() : Until Event = #PB_Event_CloseWindow
EndIf 

StopProGUI()

Supported OS

Windows, Linux