Win32 API 日本語リファレンス
ホーム › UI.Animation › IUIAnimationManager2

IUIAnimationManager2

COM
📘 Microsoft Learn (日本語) · English
IIDd8b6f7d4-4109-4d3f-acee-879926968cb1継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アニメーションマネージャーを定義します。アニメーションマネージャーは、多次元のアニメーションを作成および管理するための中心的なインターフェイスを提供します。

メソッド 21

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT CreateAnimationVectorVariable(DOUBLE* initialValue, DWORD cDimension, IUIAnimationVariable2** variable)

指定された次元ごとに新しいアニメーション変数を作成します。

initialValueDOUBLE*inアニメーション変数の初期値のベクター (サイズは cDimension)。
cDimensionDWORDinアニメーション化する値を必要とする次元数。このパラメーターは、initialValue に列挙される値の数を指定します。
variableIUIAnimationVariable2**out新しいアニメーション変数。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

アニメーション変数の初期値は、変数の作成時に指定します。アニメーション変数を作成した後は、その値を直接変更することはできません。値の更新はアニメーションマネージャーを通じて行う必要があります。

通常、アニメーション化する視覚的な特性ごとに 1 つのアニメーション変数を作成します。たとえば、3 次元空間内を自由に移動できるオブジェクトの X、Y、Z 座標に対して、アプリケーションが 3 つのアニメーション変数を作成する、といった具合です。

vtbl 4 HRESULT CreateAnimationVariable(DOUBLE initialValue, IUIAnimationVariable2** variable)

新しいアニメーション変数を作成します。(IUIAnimationManager2.CreateAnimationVariable)

initialValueDOUBLEinアニメーション変数の初期値。
variableIUIAnimationVariable2**out新しいアニメーション変数。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

アニメーション変数の初期値は、変数の作成時に指定します。アニメーション変数を作成した後は、その値を直接変更することはできません。値の更新はアニメーションマネージャーを通じて行う必要があります。

通常、アニメーション化する視覚的な特性ごとに 1 つのアニメーション変数を作成します。たとえば、ウィンドウ内を自由に移動できるオブジェクトの X 座標と Y 座標に対して、アプリケーションが 2 つのアニメーション変数を作成する、といった具合です。

vtbl 5 HRESULT ScheduleTransition(IUIAnimationVariable2* variable, IUIAnimationTransition2* transition, DOUBLE timeNow)

単一の遷移 (トランジション) から成るストーリーボードを作成してスケジュールします。(IUIAnimationManager2.ScheduleTransition)

variableIUIAnimationVariable2*inアニメーション変数。
transitionIUIAnimationTransition2*inアニメーション変数に適用する遷移 (トランジション)。
timeNowDOUBLEin現在のシステム時刻。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドは、ストーリーボードを作成し、指定された遷移 (トランジション) を指定されたアニメーション変数に適用したうえで、そのストーリーボードをスケジュールします。

vtbl 6 HRESULT CreateStoryboard(IUIAnimationStoryboard2** storyboard)

新しいストーリーボードを作成します。(IUIAnimationManager2.CreateStoryboard)

storyboardIUIAnimationStoryboard2**out新しいストーリーボード。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

vtbl 7 HRESULT FinishAllStoryboards(DOUBLE completionDeadline)

指定した時間内に、アクティブなすべてのストーリーボードを終了させます。(IUIAnimationManager2.FinishAllStoryboards)

completionDeadlineDOUBLEinすべてのストーリーボードが終了しなければならない最大の時間間隔。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

FinishAllStoryboards メソッドを呼び出すと、アクティブなすべてのストーリーボードが指定した完了期限内に確実に終了します。期限を超えて再生される予定のストーリーボードは圧縮されます。

ストーリーボードは、IUIAnimationStoryboard::GetStatus メソッドの呼び出しが UI_ANIMATION_STORYBOARD_PLAYING または UI_ANIMATION_STORYBOARD_SCHEDULED を返す場合にアクティブと見なされます。

vtbl 8 HRESULT AbandonAllStoryboards()

アクティブなすべてのストーリーボードを破棄します。(IUIAnimationManager2.AbandonAllStoryboards)

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドを呼び出すことは、アクティブな各ストーリーボードに対して IUIAnimationStoryboard::Abandon メソッドを呼び出すことと同じです。

ストーリーボードは、IUIAnimationStoryboard::GetStatus メソッドの呼び出しが UI_ANIMATION_STORYBOARD_PLAYING または UI_ANIMATION_STORYBOARD_SCHEDULED を返す場合にアクティブと見なされます。

vtbl 9 HRESULT Update(DOUBLE timeNow, UI_ANIMATION_UPDATE_RESULT* updateResult)

すべてのアニメーション変数の値を更新します。(IUIAnimationManager2.Update)

timeNowDOUBLEin現在のシステム時刻。このパラメーターは 0.0 以上でなければなりません。
updateResultUI_ANIMATION_UPDATE_RESULT*outoptional更新の結果。 このメソッドの呼び出しでは、このパラメーターを省略できます。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドを呼び出すと、アニメーションマネージャーが timeNow まで進み、必要に応じてすべてのストーリーボードの状態が変化し、各アニメーション変数が適切な補間値に更新されます。アニメーションマネージャーが一時停止している場合、ストーリーボードも変数も更新されません。アニメーションモードが UI_ANIMATION_MODE_DISABLED の場合、スケジュールされたすべてのストーリーボードは直ちに再生を終了します。この呼び出し中にいずれかの変数の値が変化した場合、updateResult の値は UI_ANIMATION_UPDATE_VARIABLES_CHANGED になります。それ以外の場合は UI_ANIMATION_UPDATE_NO_CHANGE になります。

vtbl 10 HRESULT GetVariableFromTag(IUnknown* object, DWORD id, IUIAnimationVariable2** variable)

指定したタグを持つアニメーション変数を取得します。(IUIAnimationManager2.GetVariableFromTag)

objectIUnknown*inoptionalタグのオブジェクト部分。 このパラメーターは NULL でもかまいません。
idDWORDinタグの識別子部分。
variableIUIAnimationVariable2**out指定したタグに一致するアニメーション変数。一致するものがない場合は NULL。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

タグとは、整数の識別子 (id) と COM オブジェクト (object) の組み合わせです。アプリケーションはタグを使用してアニメーション変数やストーリーボードを識別できます。タグのオブジェクト部分としては NULL も有効であるため、object パラメーターには NULL を指定できます。

タグは必ずしも一意ではありません。指定したタグを持つアニメーション変数が複数存在する場合、このメソッドは UI_E_AMBIGUOUS_MATCH を返します。

vtbl 11 HRESULT GetStoryboardFromTag(IUnknown* object, DWORD id, IUIAnimationStoryboard2** storyboard)

指定したタグを持つストーリーボードを取得します。(IUIAnimationManager2.GetStoryboardFromTag)

objectIUnknown*inoptionalタグのオブジェクト部分。 このパラメーターは NULL でもかまいません。
idDWORDinタグの識別子部分。
storyboardIUIAnimationStoryboard2**out指定したタグに一致するストーリーボード。一致するものがない場合は NULL。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

タグとは、整数の識別子 (id) と COM オブジェクト (object) の組み合わせです。アプリケーションはタグを使用してアニメーション変数やストーリーボードを識別できます。タグのオブジェクト部分としては NULL も有効であるため、object パラメーターには NULL を指定できます。

タグは必ずしも一意ではありません。指定したタグを持つストーリーボードが複数存在する場合、このメソッドは UI_E_AMBIGUOUS_MATCH を返します。

vtbl 12 HRESULT EstimateNextEventTime(DOUBLE* seconds)

次のアニメーションイベントまでの時間間隔の推定値を取得します。

secondsDOUBLE*out推定時間 (秒単位)。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

vtbl 13 HRESULT GetStatus(UI_ANIMATION_MANAGER_STATUS* status)

アニメーションマネージャーの状態を取得します。(IUIAnimationManager2.GetStatus)

statusUI_ANIMATION_MANAGER_STATUS*outアニメーションマネージャーの状態。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

vtbl 14 HRESULT SetAnimationMode(UI_ANIMATION_MODE mode)

アニメーションモードを設定します。(IUIAnimationManager2.SetAnimationMode)

modeUI_ANIMATION_MODEinアニメーションモード。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドを使用すると、アニメーションを全体として有効または無効にできます。アニメーションが無効になっている間は、すべてのストーリーボードがスケジュール時に直ちに終了します。既定のモードは UI_ANIMATION_MODE_SYSTEM_DEFAULT であり、この場合はアプリケーションでアニメーションを有効にするか無効にするかを Windows が判断します。

vtbl 15 HRESULT Pause()

すべてのアニメーションを一時停止します。(IUIAnimationManager2.Pause)

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

アニメーションマネージャーが一時停止されると、その状態は UI_ANIMATION_MANAGER_IDLE に設定されます。

vtbl 16 HRESULT Resume()

すべてのアニメーションを再開します。(IUIAnimationManager2.Resume)

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

アニメーションマネージャーが再開され、少なくとも 1 つのアニメーションがスケジュール済みまたは再生中である場合、その状態は UI_ANIMATION_MANAGER_BUSY に設定されます。

vtbl 17 HRESULT SetManagerEventHandler(IUIAnimationManagerEventHandler2* handler, BOOL fRegisterForNextAnimationEvent)

アニメーションマネージャーの状態更新に対するハンドラーを指定します。(IUIAnimationManager2.SetManagerEventHandler)

handlerIUIAnimationManagerEventHandler2*inoptional

アニメーションマネージャーの状態が変化したときに呼び出されるイベントハンドラー。

指定するオブジェクトは IUIAnimationManagerEventHandler インターフェイスを実装しているか、NULL である必要があります。詳細については「解説」を参照してください。

fRegisterForNextAnimationEventBOOLinTRUE の場合、IUIAnimationManager2::EstimateNextEventTime が次のアニメーションイベントまでの時間間隔を推定する際に handler を考慮に入れることを指定します。既定値はありません。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

handler パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この手法は、IUIAnimationManager2::Shutdown メソッドを呼び出さずに参照の循環を解消するうえで不可欠となる場合があります。

vtbl 18 HRESULT SetCancelPriorityComparison(IUIAnimationPriorityComparison2* comparison)

スケジュール済みのストーリーボードをキャンセルできるかどうかを判断する優先度比較ハンドラーを設定します。

comparisonIUIAnimationPriorityComparison2*inoptional

キャンセル用の優先度比較ハンドラー。

指定するオブジェクトは IUIAnimationPriorityComparison2 インターフェイスを実装しているか、NULL である必要があります。詳細については「解説」を参照してください。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドで優先度比較ハンドラーを設定すると、アプリケーションはストーリーボードのキャンセルによってスケジュールの競合を解決できる場合を示すことができます。

スケジュール済みのストーリーボードをキャンセルできるのは、そのストーリーボードがまだ再生を開始しておらず、かつこのメソッドで登録した優先度比較オブジェクトが S_OK を返す場合に限られます。キャンセルされたストーリーボードはスケジュールから完全に削除されます。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡された優先度比較ハンドラーオブジェクトへの参照を解放します。この手法は、IUIAnimationManager2::Shutdown メソッドを呼び出さずに参照の循環を解消するうえで不可欠となる場合があります。

vtbl 19 HRESULT SetTrimPriorityComparison(IUIAnimationPriorityComparison2* comparison)

スケジュール済みのストーリーボードをトリミングできるかどうかを判断する優先度比較ハンドラーを設定します。

comparisonIUIAnimationPriorityComparison2*inoptional

トリミング用の優先度比較ハンドラー。

指定するオブジェクトは IUIAnimationPriorityComparison インターフェイスを実装しているか、NULL である必要があります。

詳細については「解説」を参照してください。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドで優先度比較ハンドラーを設定すると、アプリケーションはスケジュール済みストーリーボードのトリミングによってスケジュールの競合を解決できる場合を示すことができます。

スケジュール済みのストーリーボードをトリミングできるのは、このメソッドで登録した優先度比較オブジェクトが S_OK を返す場合に限られます。新しいストーリーボードがスケジュール済みのストーリーボードをトリミングした場合、新しいストーリーボードがある変数のアニメーションを開始した後は、スケジュール済みのストーリーボードはその変数に影響を与えられなくなります。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この手法は、IUIAnimationManager2::Shutdown メソッドを呼び出さずに参照の循環を解消するうえで不可欠となる場合があります。

vtbl 20 HRESULT SetCompressPriorityComparison(IUIAnimationPriorityComparison2* comparison)

スケジュール済みのストーリーボードを圧縮できるかどうかを判断する優先度比較ハンドラーを設定します。

comparisonIUIAnimationPriorityComparison2*inoptional

圧縮用の優先度比較ハンドラー。

指定するオブジェクトは IUIAnimationPriorityComparison2 インターフェイスを実装しているか、NULL である必要があります。詳細については「解説」を参照してください。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドで優先度比較ハンドラーを設定すると、アプリケーションは、スケジュール済みのストーリーボードおよび同じ変数をアニメーション化する他のストーリーボードを圧縮することでスケジュールの競合を解決できる場合を示すことができます。

ストーリーボードを圧縮できるのは、圧縮の影響を受ける他のすべてのスケジュール済みストーリーボードに対して、このメソッドで登録した優先度比較オブジェクトが S_OK を返す場合に限られます。ストーリーボードが圧縮されると、影響を受けるストーリーボードの時間が一時的に加速され、再生が速くなります。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この手法は、IUIAnimationManager2::Shutdown メソッドを呼び出さずに参照の循環を解消するうえで不可欠となる場合があります。

vtbl 21 HRESULT SetConcludePriorityComparison(IUIAnimationPriorityComparison2* comparison)

スケジュール済みのストーリーボードを終結 (conclude) できるかどうかを判断する優先度比較ハンドラーを設定します。

comparisonIUIAnimationPriorityComparison2*inoptional終結用の優先度比較ハンドラー。指定するオブジェクトは IUIAnimationPriorityComparison2 インターフェイスを実装しているか、NULL である必要があります。 詳細については「解説」を参照してください。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドで優先度比較ハンドラーを設定すると、アプリケーションはスケジュール済みストーリーボードの終結によってスケジュールの競合を解決できる場合を示すことができます。

スケジュール済みのストーリーボードを終結できるのは、そのストーリーボードが繰り返し回数 UI_ANIMATION_REPEAT_INDEFINITELY のループを含んでおり、かつこのメソッドで登録した優先度比較オブジェクトが S_OK を返す場合に限られます。ストーリーボードが終結されると、現在のループの繰り返しが完了し、その後にストーリーボードの残りの部分が再生されます。

comparison パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この手法は、IUIAnimationManager2::Shutdown メソッドを呼び出さずに参照の循環を解消するうえで不可欠となる場合があります。

vtbl 22 HRESULT SetDefaultLongestAcceptableDelay(DOUBLE delay)

既定の許容アニメーション遅延を設定します。これは、ストーリーボードが開始されるまでに経過してもよい時間の長さです。(IUIAnimationManager2.SetDefaultLongestAcceptableDelay)

delayDOUBLEin既定の遅延。このパラメーターには正の値を指定できるほか、任意の有限の遅延を許容することを示す UI_ANIMATION_SECONDS_EVENTUALLY (-1) を指定できます。

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

Windows Animation がストーリーボードのスケジュールに成功するには、許容される最長の遅延が経過する前にストーリーボードが開始される必要があります。Windows Animation はこの遅延を次の順序で決定します。まず、対象のストーリーボードに対して IUIAnimationStoryboard::SetLongestAcceptableDelay を呼び出して設定された遅延値、次にこのメソッドを呼び出して設定された遅延値、いずれのメソッドも呼び出されていない場合は 0.0 です。

vtbl 23 HRESULT Shutdown()

アニメーションマネージャーと、それに関連付けられたすべてのオブジェクトをシャットダウンします。(IUIAnimationManager2.Shutdown)

戻り値

成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、Windows Animation Error Codes を参照してください。

解説(Remarks)

このメソッドを呼び出すと、アニメーションマネージャーおよびそれが作成したすべてのオブジェクトに対して、 他のオブジェクトへのポインターをすべて解放するよう指示されます。IUIAnimationManager2::Shutdown を呼び出した後は、アニメーションマネージャーおよびそれが作成したオブジェクトに対して他のメソッドを呼び出すことはできません。アプリケーションは、アニメーションオブジェクトを含む参照の循環を作り出している可能性がある場合に、このメソッドを呼び出してクリーンアップできます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IUIAnimationManager2 "{D8B6F7D4-4109-4D3F-ACEE-879926968CB1}"
#usecom global IUIAnimationManager2 IID_IUIAnimationManager2 "{D25D8842-8884-4A4A-B321-091314379BDD}"
#comfunc global IUIAnimationManager2_CreateAnimationVectorVariable     3 var,int,sptr
#comfunc global IUIAnimationManager2_CreateAnimationVariable           4 double,sptr
#comfunc global IUIAnimationManager2_ScheduleTransition                5 sptr,sptr,double
#comfunc global IUIAnimationManager2_CreateStoryboard                  6 sptr
#comfunc global IUIAnimationManager2_FinishAllStoryboards              7 double
#comfunc global IUIAnimationManager2_AbandonAllStoryboards             8
#comfunc global IUIAnimationManager2_Update                            9 double,var
#comfunc global IUIAnimationManager2_GetVariableFromTag                10 sptr,int,sptr
#comfunc global IUIAnimationManager2_GetStoryboardFromTag              11 sptr,int,sptr
#comfunc global IUIAnimationManager2_EstimateNextEventTime             12 var
#comfunc global IUIAnimationManager2_GetStatus                         13 var
#comfunc global IUIAnimationManager2_SetAnimationMode                  14 int
#comfunc global IUIAnimationManager2_Pause                             15
#comfunc global IUIAnimationManager2_Resume                            16
#comfunc global IUIAnimationManager2_SetManagerEventHandler            17 sptr,int
#comfunc global IUIAnimationManager2_SetCancelPriorityComparison       18 sptr
#comfunc global IUIAnimationManager2_SetTrimPriorityComparison         19 sptr
#comfunc global IUIAnimationManager2_SetCompressPriorityComparison     20 sptr
#comfunc global IUIAnimationManager2_SetConcludePriorityComparison     21 sptr
#comfunc global IUIAnimationManager2_SetDefaultLongestAcceptableDelay  22 double
#comfunc global IUIAnimationManager2_Shutdown                          23
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。