ホーム › UI.Animation › IUIAnimationStoryboard

IUIAnimationStoryboard

COM

📘 Microsoft Learn (日本語) · English

IIDa8ff128f-9bf9-4af1-9e67-e5e410defb84継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ストーリーボードを定義します。ストーリーボードは、相互に同期される遷移(トランジション)のグループを保持します。

解説(Remarks)

IUIAnimationStoryboard は、 IUIAnimationVariable および IUIAnimationTransition とともに、アニメーションを構築するための主要なコンポーネントです。

メソッド 17

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

vtbl 3 HRESULT AddTransition(IUIAnimationVariable* variable, IUIAnimationTransition* transition)

ストーリーボードに遷移を追加します。(IUIAnimationStoryboard.AddTransition)

variable	IUIAnimationVariable*	in	遷移を追加する対象のアニメーション変数。
transition	IUIAnimationTransition*	in	追加する遷移。

戻り値

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

戻り値	説明
UI_E_TRANSITION_ALREADY_USED	この遷移は既にストーリーボードに追加されています。

解説(Remarks)

AddTransition メソッドは、指定された遷移をストーリーボード内の指定されたアニメーション変数に適用します。この変数に対してこのストーリーボードで最初に適用される遷移である場合、その遷移はストーリーボードの開始時点から始まります。それ以外の場合、その遷移は、その変数に最後に追加された遷移の後に追加されます。

例

例については、Create a Storyboard and Add Transitions を参照してください。

vtbl 4 HRESULT AddKeyframeAtOffset(UI_ANIMATION_KEYFRAME existingKeyframe, DOUBLE offset, UI_ANIMATION_KEYFRAME* keyframe)

既存のキーフレームから指定したオフセットの位置にキーフレームを追加します。(IUIAnimationStoryboard.AddKeyframeAtOffset)

existingKeyframe	UI_ANIMATION_KEYFRAME	in	既存のキーフレーム。ストーリーボードの開始位置からのオフセットにキーフレームを追加するには、特別なキーフレーム UI_ANIMATION_KEYFRAME_STORYBOARD_START を使用します。
offset	DOUBLE	in	新しいキーフレームを追加する、既存のキーフレームからのオフセット。
keyframe	UI_ANIMATION_KEYFRAME*	out	追加されるキーフレーム。

戻り値

解説(Remarks)

キーフレームはストーリーボード内のある時点を表し、遷移の開始時刻と終了時刻の指定に使用できます。キーフレームは遷移の終端にも追加できるため、ストーリーボードの開始位置からのオフセットは、ストーリーボードが再生されるまで確定しないことがあります。

例

次のコードは、ストーリーボードの開始位置にあるキーフレームから 0.3 秒の固定オフセットの位置にキーフレームを追加します。

const UI_ANIMATION_SECONDS offset = 0.3;

UI_ANIMATION_KEYFRAME keyframe1;
hr = pStoryboard->AddKeyframeAtOffset(
       UI_ANIMATION_KEYFRAME_STORYBOARD_START,
       offset,
       &keyframe1
);

vtbl 5 HRESULT AddKeyframeAfterTransition(IUIAnimationTransition* transition, UI_ANIMATION_KEYFRAME* keyframe)

指定した遷移の終端にキーフレームを追加します。(IUIAnimationStoryboard.AddKeyframeAfterTransition)

transition	IUIAnimationTransition*	in	キーフレームを追加する位置の直前となる遷移。
keyframe	UI_ANIMATION_KEYFRAME*	out	追加されるキーフレーム。

戻り値

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

戻り値	説明
UI_E_TRANSITION_NOT_IN_STORYBOARD	その遷移はストーリーボードに追加されていません。

解説(Remarks)

vtbl 6 HRESULT AddTransitionAtKeyframe(IUIAnimationVariable* variable, IUIAnimationTransition* transition, UI_ANIMATION_KEYFRAME startKeyframe)

指定したキーフレームから開始する遷移を追加します。(IUIAnimationStoryboard.AddTransitionAtKeyframe)

variable	IUIAnimationVariable*	in	遷移を追加する対象のアニメーション変数。
transition	IUIAnimationTransition*	in	追加する遷移。
startKeyframe	UI_ANIMATION_KEYFRAME	in	新しい遷移の開始位置を指定するキーフレーム。

戻り値

戻り値	説明
UI_E_TRANSITION_ALREADY_USED	この遷移は既にストーリーボードに追加されているか、再生が終了して解放されたストーリーボードに追加されています。
UI_E_TRANSITION_ECLIPSED	この遷移が、ストーリーボード内の別の遷移の開始を覆い隠す可能性があります。

解説(Remarks)

遷移は再生される順序で追加する必要があります。ストーリーボード内の直前の遷移が終了する前に、次の遷移の再生が始まることがあります。その場合、新しい遷移が参照する初期値と速度は、直前の遷移の状態によって決まります。遷移が直前の遷移の開始より前に始まってはなりません。

vtbl 7 HRESULT AddTransitionBetweenKeyframes(IUIAnimationVariable* variable, IUIAnimationTransition* transition, UI_ANIMATION_KEYFRAME startKeyframe, UI_ANIMATION_KEYFRAME endKeyframe)

2 つのキーフレームの間に遷移を追加します。(IUIAnimationStoryboard.AddTransitionBetweenKeyframes)

variable	IUIAnimationVariable*	in	遷移を追加する対象のアニメーション変数。
transition	IUIAnimationTransition*	in	追加する遷移。
startKeyframe	UI_ANIMATION_KEYFRAME	in	新しい遷移の開始位置を指定するキーフレーム。
endKeyframe	UI_ANIMATION_KEYFRAME	in	新しい遷移の終了位置を指定するキーフレーム。endKeyframe が、ストーリーボード内で startKeyframe より前に現れる可能性があってはなりません。

戻り値

戻り値	説明
UI_E_TRANSITION_ALREADY_USED	この遷移は既にストーリーボードに追加されているか、再生が終了して解放されたストーリーボードに追加されています。
UI_E_TRANSITION_ECLIPSED	この遷移が、ストーリーボード内の別の遷移の開始を覆い隠す可能性があります。
UI_E_START_KEYFRAME_AFTER_END	開始キーフレームが終了キーフレームより後に発生する可能性があります。

解説(Remarks)

このメソッドは、指定された遷移をストーリーボード内の指定されたアニメーション変数に適用し、その遷移を指定されたキーフレームで開始および終了させます。遷移の作成時に継続時間パラメーターが指定されていた場合、その値は開始キーフレームと終了キーフレームの間の時間で上書きされます。それ以外の場合、Windows Animation は必要に応じて遷移を加速または減速します。

遷移は再生される順序で追加する必要があります。ストーリーボード内の直前の遷移が終了する前に、次の遷移の再生が始まることがあります。その場合、新しい遷移が参照する初期値と速度は、直前の遷移の状態によって決まります。遷移が直前の遷移の開始より前に始まる可能性があってはなりません。

vtbl 8 HRESULT RepeatBetweenKeyframes(UI_ANIMATION_KEYFRAME startKeyframe, UI_ANIMATION_KEYFRAME endKeyframe, INT repetitionCount)

指定した 2 つのキーフレームの間にループを作成します。

startKeyframe	UI_ANIMATION_KEYFRAME	in	ループを開始するキーフレーム。
endKeyframe	UI_ANIMATION_KEYFRAME	in	ループを終了するキーフレーム。endKeyframe が、ストーリーボード内で startKeyframe より前に発生する可能性があってはなりません。
repetitionCount	INT	in	ループを繰り返す回数。このパラメーターは 0 または正の数でなければなりません。ストーリーボードが切り詰められる(trim)か終結(conclude)されるまでループを無限に繰り返すには、UI_ANIMATION_REPEAT_INDEFINITELY (-1) を使用します。

戻り値

戻り値	説明
UI_E_START_KEYFRAME_AFTER_END	開始キーフレームが終了キーフレームより後に発生する可能性があります。
UI_E_END_KEYFRAME_NOT_DETERMINED	開始キーフレームに到達した時点で、終了キーフレームの時刻を決定できない可能性があります。
UI_E_LOOPS_OVERLAP	ストーリーボードの 2 つの繰り返し部分が重なり合う可能性があります。

解説(Remarks)

このメソッドは、ストーリーボードの残りの部分を再生する前に、指定されたキーフレーム間の区間を繰り返し再生するようストーリーボードに指示します。有限の繰り返し回数が指定された場合、ループは常にその回数だけ再生されます。UI_ANIMATION_REPEAT_INDEFINITELY (-1) が指定された場合、ループはストーリーボードが終結されるまで繰り返されます。終結された場合は、現在のループの反復が完了してから、ストーリーボードの残りの部分が再生されます。無限に繰り返すストーリーボードは、切り詰められた場合にも終了します。

ループの入れ子および重なり合うループはサポートされません。

キーフレームはストーリーボード内のある時点を表し、遷移の開始時刻または終了時刻の指定に使用できます。キーフレームは遷移の終端にも追加できるため、ストーリーボードの開始位置からのオフセットは、ストーリーボードが再生されるまで確定しないことがあります。

vtbl 9 HRESULT HoldVariable(IUIAnimationVariable* variable)

ストーリーボードが終了するまで、指定したアニメーション変数を最終値に保持するようストーリーボードに指示します。(IUIAnimationStoryboard.HoldVariable)

variable

IUIAnimationVariable*

アニメーション変数。

戻り値

解説(Remarks)

ストーリーボードが再生されている間、より優先度の高いストーリーボードによって切り詰められない限り、そのストーリーボードはアニメーション対象の変数への排他的アクセス権を持ちます。通常、この排他的アクセス権は、その変数に対するストーリーボード内の最後の遷移の再生が終了した時点で解放されます。アプリケーションはこのメソッドを呼び出すことで、アニメーション変数への排他的アクセス権を維持し、ストーリーボードが終了するまで、その変数を最後の遷移の最終値に保持できます。

vtbl 10 HRESULT SetLongestAcceptableDelay(DOUBLE delay)

スケジュールされたストーリーボードが開始されるまでに許容できる最長の遅延時間を設定します。(IUIAnimationStoryboard.SetLongestAcceptableDelay)

delay

DOUBLE

許容できる最長の遅延時間。このパラメーターには正の値を指定できます。また、有限の遅延であればいずれも許容されることを示すには UI_ANIMATION_SECONDS_EVENTUALLY (-1) を指定します。

戻り値

解説(Remarks)

ストーリーボードが正常にスケジュールされるためには、許容できる最長の遅延時間が経過する前に開始される必要があります。この遅延時間は次の順序で決定されます。このメソッドの呼び出しで設定された遅延値、IUIAnimationManager::SetDefaultLongestAcceptableDelay メソッドの呼び出しで設定された遅延値、いずれのメソッドも呼び出されていない場合は 0.0。

vtbl 11 HRESULT Schedule(DOUBLE timeNow, UI_ANIMATION_SCHEDULING_RESULT* schedulingResult)

ストーリーボード自身を再生のためにスケジュールするよう指示します。(IUIAnimationStoryboard.Schedule)

timeNow	DOUBLE	in	現在の時刻。
schedulingResult	UI_ANIMATION_SCHEDULING_RESULT*	outoptional	スケジュール要求の結果。このパラメーターは、このメソッドの呼び出し時に省略できます。

戻り値

解説(Remarks)

このメソッドは、再生中のストーリーボードのスケジュールに自身を追加するよう、ストーリーボードに指示します。規則は次のとおりです。

同じアニメーション変数をアニメーションしている再生中のストーリーボードが存在しない場合、この試行は成功し、ストーリーボードはただちに再生を開始します。
競合するストーリーボードをキャンセル、切り詰め、終結、または圧縮する優先度をそのストーリーボードが持つ場合、スケジュールの試行は成功し、ストーリーボードは可能な限り早く再生を開始します。
ストーリーボードが優先度を持たない場合、試行は失敗し、schedulingResult パラメーターには UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY が設定されます。

このメソッドが OnStoryboardStatusChanged イベントのハンドラーから呼び出された場合、schedulingResult パラメーターには UI_ANIMATION_SCHEDULING_DEFERRED が設定されます。この場合、ストーリーボードが正常にスケジュールされたかどうかを判断する唯一の方法は、ストーリーボードイベントハンドラーを設定し、ストーリーボードの状態が UI_ANIMATION_STORYBOARD_INSUFFICIENT_PRIORITY になるかどうかを確認することです。

ストーリーボードの状態が UI_ANIMATION_STORYBOARD_READY に達した後に Schedule を再度呼び出すことで、ストーリーボードを再利用できます。ストーリーボードが UI_ANIMATION_STORYBOARD_BUILDING または UI_ANIMATION_STORYBOARD_READY 以外の状態にあるときにスケジュールを試みると失敗し、schedulingResult には UI_ANIMATION_SCHEDULING_ALREADY_SCHEDULED が設定されます。

例

次の例は、現在の時刻を取得してストーリーボードをスケジュールします。その他の例については、Schedule a Storyboard を参照してください。

// Get the current time and schedule the storyboard
UI_ANIMATION_SECONDS secondsNow;
hr = m_pAnimationTimer->GetTime(
    &secondsNow
    );
if (SUCCEEDED(hr))
{
    UI_ANIMATION_SCHEDULING_RESULT schedulingResult;
    hr = pStoryboard->Schedule(
        secondsNow,
        &schedulingResult
        );
    if (SUCCEEDED(hr))
    {
        if (schedulingResult == UI_ANIMATION_SCHEDULING_SUCCEEDED)
        {
            ...
        }
        else
        {
            ...
        }
    }
}

vtbl 12 HRESULT Conclude()

進行中のキーフレームループ(UI_ANIMATION_REPEAT_INDEFINITELY が設定されたループ)の現在の反復を完了させ、ループを終了して、ストーリーボードの残りの部分を続行します。(IUIAnimationStoryboard.Conclude)

戻り値

解説(Remarks)

このメソッドは、繰り返し回数が UI_ANIMATION_REPEAT_INDEFINITELY (-1) である以降のキーフレームループをスキップし、ストーリーボードの残りの部分を再生することを指定します。

進行中のキーフレームループの反復は、ストーリーボードの残りの部分が再生される前に完了します。

このメソッドがキーフレームループの反復の終了時に呼び出された場合、ループは終了し、ループの値はループ開始時の値に設定されます。

vtbl 13 HRESULT Finish(DOUBLE completionDeadline)

必要に応じてストーリーボードを圧縮しながら、指定した時間内にストーリーボードを終了させます。(IUIAnimationStoryboard.Finish)

completionDeadline

DOUBLE

ストーリーボードが再生を完了するために使用できる最大の時間。

戻り値

解説(Remarks)

このメソッドはストーリーボードイベントに影響しません。ストーリーボードの再生中、イベントは想定どおりに発生し続けます。

vtbl 14 HRESULT Abandon()

ストーリーボードを終了し、関連するすべてのアニメーション変数を解放して、ストーリーボードをスケジュールから削除します。(IUIAnimationStoryboard.Abandon)

戻り値

解説(Remarks)

このメソッドは、ストーリーボードの再生開始前でも開始後でも呼び出せます。

このメソッドはストーリーボードイベントを発生させません。

vtbl 15 HRESULT SetTag(IUnknown* object, DWORD id)

ストーリーボードのタグを設定します。(IUIAnimationStoryboard.SetTag)

object	IUnknown*	inoptional	タグのオブジェクト部分。このパラメーターには NULL を指定できます。
id	DWORD	in	タグの識別子部分。

戻り値

戻り値	説明
UI_E_STORYBOARD_ACTIVE	そのストーリーボードは現在スケジュールに登録されています。

解説(Remarks)

タグは、整数の識別子 (id) と COM オブジェクト (object) の組み合わせです。アプリケーションはこれをストーリーボードの識別に使用できます。

vtbl 16 HRESULT GetTag(IUnknown** object, DWORD* id)

ストーリーボードのタグを取得します。(IUIAnimationStoryboard.GetTag)

object	IUnknown**	outoptional	タグのオブジェクト部分。
id	DWORD*	outoptional	タグの識別子部分。

戻り値

戻り値	説明
UI_E_VALUE_NOT_SET	ストーリーボードのタグが設定されていません。

解説(Remarks)

タグは、整数の識別子 (id) と COM オブジェクト (object) の組み合わせです。アプリケーションはこれをストーリーボードの識別に使用できます。

これらのパラメーターは省略可能であり、タグの両方の部分を返すことも、識別子部分またはオブジェクト部分のみを返すこともできます。

vtbl 17 HRESULT GetStatus(UI_ANIMATION_STORYBOARD_STATUS* status)

ストーリーボードの状態を取得します。(IUIAnimationStoryboard.GetStatus)

status

UI_ANIMATION_STORYBOARD_STATUS*

out

ストーリーボードの状態。

戻り値

解説(Remarks)

このメソッドが OnStoryboardStatusChanged イベントのハンドラーから呼び出される場合を除き、返される値は UI_ANIMATION_STORYBOARD_BUILDING、UI_ANIMATION_STORYBOARD_SCHEDULED、 UI_ANIMATION_STORYBOARD_PLAYING、UI_ANIMATION_STORYBOARD_READY のみです。

vtbl 18 HRESULT GetElapsedTime(DOUBLE* elapsedTime)

ストーリーボードの再生開始からの経過時間を取得します。(IUIAnimationStoryboard.GetElapsedTime)

elapsedTime

DOUBLE*

out

経過時間。

戻り値

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

戻り値	説明
UI_E_STORYBOARD_NOT_PLAYING	ストーリーボードは再生されていません。

vtbl 19 HRESULT SetStoryboardEventHandler(IUIAnimationStoryboardEventHandler* handler)

ストーリーボードイベントのハンドラーを指定します。(IUIAnimationStoryboard.SetStoryboardEventHandler)

handler

IUIAnimationStoryboardEventHandler*

inoptional

ストーリーボードの状態イベントおよび更新イベントが発生するたびに呼び出されるハンドラー。

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

戻り値

解説(Remarks)

handler パラメーターに NULL を渡すと、Windows Animation は以前に渡されたハンドラーオブジェクトへの参照を解放します。この手法は、IUIAnimationManager::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_IUIAnimationStoryboard "{A8FF128F-9BF9-4AF1-9E67-E5E410DEFB84}"
#usecom global IUIAnimationStoryboard IID_IUIAnimationStoryboard "{}"
#comfunc global IUIAnimationStoryboard_AddTransition                  3 sptr,sptr
#comfunc global IUIAnimationStoryboard_AddKeyframeAtOffset            4 sptr,double,var
#comfunc global IUIAnimationStoryboard_AddKeyframeAfterTransition     5 sptr,var
#comfunc global IUIAnimationStoryboard_AddTransitionAtKeyframe        6 sptr,sptr,sptr
#comfunc global IUIAnimationStoryboard_AddTransitionBetweenKeyframes  7 sptr,sptr,sptr,sptr
#comfunc global IUIAnimationStoryboard_RepeatBetweenKeyframes         8 sptr,sptr,int
#comfunc global IUIAnimationStoryboard_HoldVariable                   9 sptr
#comfunc global IUIAnimationStoryboard_SetLongestAcceptableDelay      10 double
#comfunc global IUIAnimationStoryboard_Schedule                       11 double,var
#comfunc global IUIAnimationStoryboard_Conclude                       12
#comfunc global IUIAnimationStoryboard_Finish                         13 double
#comfunc global IUIAnimationStoryboard_Abandon                        14
#comfunc global IUIAnimationStoryboard_SetTag                         15 sptr,int
#comfunc global IUIAnimationStoryboard_GetTag                         16 sptr,var
#comfunc global IUIAnimationStoryboard_GetStatus                      17 var
#comfunc global IUIAnimationStoryboard_GetElapsedTime                 18 var
#comfunc global IUIAnimationStoryboard_SetStoryboardEventHandler      19 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IUIAnimationStoryboard "{A8FF128F-9BF9-4AF1-9E67-E5E410DEFB84}"
#usecom global IUIAnimationStoryboard IID_IUIAnimationStoryboard "{}"
#comfunc global IUIAnimationStoryboard_AddTransition                  3 sptr,sptr
#comfunc global IUIAnimationStoryboard_AddKeyframeAtOffset            4 sptr,double,sptr
#comfunc global IUIAnimationStoryboard_AddKeyframeAfterTransition     5 sptr,sptr
#comfunc global IUIAnimationStoryboard_AddTransitionAtKeyframe        6 sptr,sptr,sptr
#comfunc global IUIAnimationStoryboard_AddTransitionBetweenKeyframes  7 sptr,sptr,sptr,sptr
#comfunc global IUIAnimationStoryboard_RepeatBetweenKeyframes         8 sptr,sptr,int
#comfunc global IUIAnimationStoryboard_HoldVariable                   9 sptr
#comfunc global IUIAnimationStoryboard_SetLongestAcceptableDelay      10 double
#comfunc global IUIAnimationStoryboard_Schedule                       11 double,sptr
#comfunc global IUIAnimationStoryboard_Conclude                       12
#comfunc global IUIAnimationStoryboard_Finish                         13 double
#comfunc global IUIAnimationStoryboard_Abandon                        14
#comfunc global IUIAnimationStoryboard_SetTag                         15 sptr,int
#comfunc global IUIAnimationStoryboard_GetTag                         16 sptr,sptr
#comfunc global IUIAnimationStoryboard_GetStatus                      17 sptr
#comfunc global IUIAnimationStoryboard_GetElapsedTime                 18 sptr
#comfunc global IUIAnimationStoryboard_SetStoryboardEventHandler      19 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。