QStateMachine Class
QStateMachineクラスは階層型有限状態機械を提供する。詳細...
Header: | #include <QStateMachine> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS StateMachine) target_link_libraries(mytarget PRIVATE Qt6::StateMachine) |
qmake: | QT += statemachine |
Inherits: | QState |
メモ:このクラスの関数はすべてリエントラントです。
注意:これらの関数もスレッドセーフです:
- postEvent(QEvent *event, QStateMachine::EventPriority priority)
- postDelayedEvent(QEvent *event, int delay)
- cancelDelayedEvent(int id)
- postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)
パブリック・タイプ
class | SignalEvent |
class | WrappedEvent |
enum | Error { NoError, NoInitialStateError, NoDefaultStateInHistoryStateError, NoCommonAncestorForTransitionError, StateMachineChildModeSetToParallelError } |
enum | EventPriority { NormalPriority, HighPriority } |
プロパティ
- animated : bool
- errorString : QString
- globalRestorePolicy : QState::RestorePolicy
- running : bool
パブリック関数
QStateMachine(QObject *parent = nullptr) | |
virtual | ~QStateMachine() |
void | addDefaultAnimation(QAbstractAnimation *animation) |
void | addState(QAbstractState *state) |
QBindable<bool> | bindableAnimated() |
QBindable<QString> | bindableErrorString() const |
QBindable<QState::RestorePolicy> | bindableGlobalRestorePolicy() |
bool | cancelDelayedEvent(int id) |
void | clearError() |
QSet<QAbstractState *> | configuration() const |
QList<QAbstractAnimation *> | defaultAnimations() const |
QStateMachine::Error | error() const |
QString | errorString() const |
QState::RestorePolicy | globalRestorePolicy() const |
bool | isAnimated() const |
bool | isRunning() const |
int | postDelayedEvent(QEvent *event, int delay) |
int | postDelayedEvent(QEvent *event, std::chrono::milliseconds delay) |
void | postEvent(QEvent *event, QStateMachine::EventPriority priority = NormalPriority) |
void | removeDefaultAnimation(QAbstractAnimation *animation) |
void | removeState(QAbstractState *state) |
void | setAnimated(bool enabled) |
void | setGlobalRestorePolicy(QState::RestorePolicy restorePolicy) |
再実装パブリック関数
virtual bool | eventFilter(QObject *watched, QEvent *event) override |
パブリックスロット
void | setRunning(bool running) |
void | start() |
void | stop() |
シグナル
void | runningChanged(bool running) |
void | started() |
void | stopped() |
再実装された保護された関数
virtual bool | event(QEvent *e) override |
virtual void | onEntry(QEvent *event) override |
virtual void | onExit(QEvent *event) override |
詳細説明
QStateMachineは、ステートチャートの概念と表記法に基づいています。QStateMachine はQt State Machine Framework の一部です。
ステートマシンは、状態(QAbstractState を継承するクラス)と、それらの状態間の遷移(QAbstractTransition の子孫)のセットを管理します。これらの状態と遷移は、ステートグラフを定義します。これらの状態と遷移は、状態グラフを定義します。状態グラフが構築されると、ステートマシンはそれを実行できます。QStateMachineの実行アルゴリズムは、State Chart XML(SCXML)アルゴリズムに基づいている。フレームワークの概要には、いくつかのステート・グラフと、それらを構築するためのコードが記載されています。
ステート・マシンにトップ・レベルのステートを追加するには、addState ()関数を使用します。状態を削除するには、removeState ()関数を使用する。マシンの実行中に状態を削除することは推奨されない。
マシンを起動する前に、initial state を設定しなければならない。初期状態は、マシンが起動したときに入る状態である。その後、ステート・マシンをstart() することができる。started() シグナルは、初期状態に入ったときに発せられる。
マシンはイベント駆動で、独自のイベント・ループを保持する。イベントは、postEvent ()を介してマシンにポストされる。これは非同期に実行されることを意味し、実行中のイベントループがなければ進行しないことに注意してください。Qtのトランジション、例えばQEventTransition とそのサブクラスがこれを処理するので、通常はイベントを直接マシンにポストする必要はありません。しかし、イベントによってトリガーされるカスタムトランジションには、postEvent() が便利です。
ステートマシンはイベントを処理し、トップレベルの最終状態に入るまで遷移を行います。その後、ステートマシンはfinished() シグナルを発信します。ステートマシンを明示的にstop() することもできる。この場合、stopped() シグナルが出力される。
次のスニペットは、ボタンがクリックされると終了するステートマシンを示しています:
QPushButton button; QStateMachine machine; QState *s1 = new QState(); s1->assignProperty(&button, "text", "Click me"); QFinalState *s2 = new QFinalState(); s1->addTransition(&button, &QPushButton::clicked, s2); machine.addState(s1); machine.addState(s2); machine.setInitialState(s1); machine.start();
このコード例では、QAbstractState を継承したQState を使用しています。QState クラスは、QObjectのプロパティ設定やメソッド呼び出しに使用できるステートを提供します。また、この例のようにQSignalTransitions などの遷移を追加するための便利な関数も含まれています。詳細はQState クラスの説明を参照。
エラーが発生した場合、マシンはerror state を探し、利用可能なものがあれば、この状態に入る。利用可能なエラーのタイプは、Error enumで記述されている。エラー状態に入った後、エラーの種類はerror() で取得できる。エラー状態に入っても、ステートグラフの実行は停止しない。エラー状態に該当するものがない場合、マシンの実行は停止し、エラー・メッセージがコンソールに出力される。
注: 重要: ステートマシンのChildMode をパラレル (ParallelStates) に設定すると、無効なステートマシンになります。これは、ExclusiveStates にのみ設定できる(またはそのままにしておける)。
QAbstractState,QAbstractTransition,QState,Qt ステートマシンの概要も参照してください 。
メンバ型のドキュメント
enum QStateMachine::Error
この列挙型は、実行時にステートマシンで発生する可能性のあるエラーを定義する。ステートマシンは、実行時に回復不可能なエラーに遭遇すると、error() によって返されるエラーコード、errorString() によって返されるエラーメッセージを設定し、エラーのコンテキストに基づいてエラー状態に入ります。
定数 | 値 | 説明 |
---|---|---|
QStateMachine::NoError | 0 | エラーは発生していない。 |
QStateMachine::NoInitialStateError | 1 | マシンは、初期状態が設定されていない子機を持つQState に入った。このエラーのコンテキストは、初期状態がない状態である。 |
QStateMachine::NoDefaultStateInHistoryStateError | 2 | マシンが、初期状態が設定されていないQHistoryState 。このエラーのコンテキストは、デフォルト状態がないQHistoryState 。 |
QStateMachine::NoCommonAncestorForTransitionError | 3 | マシンが、ソースとターゲットが同じ状態ツリーに含まれない遷移を選択した。一般的に、これはステートの1つに親が与えられていないか、どのマシンにも追加されていないことを意味します。このエラーのコンテキストは遷移元の状態です。 |
QStateMachine::StateMachineChildModeSetToParallelError | 4 | マシンのchildMode プロパティがQState::ParallelStates に設定されました。 これは不正です。並列として宣言できるのはステートだけであり、ステートマシン自体は宣言できません。この列挙値は Qt 5.14 で追加されました。 |
setErrorState()も参照してください 。
enum QStateMachine::EventPriority
この列挙型は、postEvent ()を使用してステートマシンにポストされるイベントの優先度を指定します。
高い優先順位のイベントは、通常の優先順位のイベントよりも先に処理されます。
定数 | 値 | 説明 |
---|---|---|
QStateMachine::NormalPriority | 0 | イベントは通常の優先度を持つ。 |
QStateMachine::HighPriority | 1 | イベントは高い優先度を持つ。 |
プロパティの説明
[bindable]
animated : bool
注意: このプロパティは、QProperty バインディングをサポートします。
このプロパティは、アニメーションが有効かどうかを保持します。
このプロパティのデフォルト値はtrue
です。
QAbstractTransition::addAnimation()も参照してください。
[bindable read-only]
errorString : QString
注 : このプロパティは、QProperty バインディングに対応しています。
このプロパティは、このステートマシンのエラー文字列を保持します。
[bindable]
globalRestorePolicy : QState::RestorePolicy
注: このプロパティは、QProperty バインディングをサポートしています。
このプロパティは、このステートマシンの状態のリストアポリシーを保持する。
このプロパティのデフォルト値はQState::DontRestoreProperties です。
running : bool
このプロパティは、このステートマシンの実行状態を保持する。
アクセス関数:
bool | isRunning() const |
void | setRunning(bool running) |
Notifier シグナル:
void | runningChanged(bool running) |
start ()、stop ()、started ()、stopped ()、runningChanged ()も参照のこと 。
メンバ関数 ドキュメント
[explicit]
QStateMachine::QStateMachine(QObject *parent = nullptr)
与えられたparent で新しいステートマシンを構築する。
[virtual noexcept]
QStateMachine::~QStateMachine()
このステートマシンを破棄します。
void QStateMachine::addDefaultAnimation(QAbstractAnimation *animation)
すべての遷移で考慮されるデフォルトのanimation を追加します。
void QStateMachine::addState(QAbstractState *state)
与えられたstate をこのステートマシンに追加する。その状態はトップレベル状態になり、ステートマシンはその状態の所有権を持つ。
状態がすでに別のマシンにある場合、まずその古いマシンから削除され、次にこのマシンに追加されます。
removeState() およびsetInitialState()も参照 。
bool QStateMachine::cancelDelayedEvent(int id)
与えられたid で識別される遅延イベントをキャンセルする。id は、postDelayedEvent() のコールによって返された値でなければならない。イベントが正常にキャンセルされた場合はtrue
を返し、そうでない場合はfalse
を返す。
注意:この関数はスレッドセーフである。
postDelayedEvent()も参照 。
void QStateMachine::clearError()
ステート・マシンのエラー文字列とエラー・コードをクリアします。
QSet<QAbstractState *> QStateMachine::configuration() const
このステート・マシンが現在保持している状態(並列状態と最終状態を含む)の最大整合性セットを返します。状態s
がコンフィギュレーションにある場合、s
の親も c にあることが常にあります。ただし、マシン自体はコンフィギュレーションの明示的なメンバーではないことに注意してください。
QList<QAbstractAnimation *> QStateMachine::defaultAnimations() const
トランジションで考慮されるデフォルトアニメーションのリストを返します。
QStateMachine::Error QStateMachine::error() const
ステートマシンで発生した最後のエラーのエラーコードを返します。
QString QStateMachine::errorString() const
ステートマシンで発生した最後のエラーのエラー文字列を返します。
注: プロパティ errorString のゲッター関数です。
[override virtual protected]
bool QStateMachine::event(QEvent *e)
再インプリメント:QState::event(QEvent *e)。
[override virtual]
bool QStateMachine::eventFilter(QObject *watched, QEvent *event)
再リンプルメント:QObject::eventFilter(QObject *watched, QEvent *event)。
QState::RestorePolicy QStateMachine::globalRestorePolicy() const
ステートマシンのリストア・ポリシーを返します。
注: プロパティ globalRestorePolicy のゲッター関数です。
setGlobalRestorePolicy()も参照してください 。
bool QStateMachine::isAnimated() const
このステートマシンでアニメーションが有効になっているかどうかを返します。
注: プロパティanimated のゲッター関数。
[override virtual protected]
void QStateMachine::onEntry(QEvent *event)
再インプリメント:QState::onEntry(QEvent *event)。
この関数は、start ()を呼び出してステートマシンを開始します。
[override virtual protected]
void QStateMachine::onExit(QEvent *event)
再インプリメント:QState::onExit(QEvent *event)。
この関数はstop() を呼び出してステートマシンを停止し、その後stopped() シグナルを発信します。
int QStateMachine::postDelayedEvent(QEvent *event, int delay)
このステートマシンが処理するために、ミリ秒単位で指定されたdelay で、指定されたevent をポストする。遅延イベントに関連付けられた識別子を返すか、イベントをポストできなかった場合は -1 を返す。
この関数はすぐに戻ります。遅延時間が経過すると、イベントは、処理のためにステートマシンのイベントキューに追加されます。ステートマシンはイベントの所有権を取得し、処理が完了すると削除します。
イベントをポストできるのは、ステートマシンが動作しているときだけです。
注:この関数はスレッドセーフです。
cancelDelayedEvent() およびpostEvent()も参照してください 。
int QStateMachine::postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)
これはオーバーロードされた関数です。
このステートマシンが処理するために、ミリ秒単位で指定されたdelay で、指定されたevent をポストします。遅延イベントに関連付けられた識別子を返すか、イベントをポストできなかった場合は -1 を返します。
この関数はすぐに戻ります。遅延時間が経過すると、イベントは、処理のためにステートマシンのイベントキューに追加されます。ステートマシンはイベントの所有権を取得し、処理が完了すると削除します。
イベントをポストできるのは、ステートマシンが動作しているときだけです。
注:この関数はスレッドセーフです。
cancelDelayedEvent() およびpostEvent()も参照のこと 。
void QStateMachine::postEvent(QEvent *event, QStateMachine::EventPriority priority = NormalPriority)
このステートマシンで処理するために、指定されたpriority の指定されたevent をポストする。
この関数は即座に戻ります。イベントはステートマシンのイベントキューに追加される。イベントは、ポストされた順に処理される。ステートマシンはイベントの所有権を持ち、処理されると削除します。
イベントをポストできるのは、ステートマシンの実行中または起動中のみです。
注:この関数はスレッドセーフです。
postDelayedEvent()も参照 。
void QStateMachine::removeDefaultAnimation(QAbstractAnimation *animation)
デフォルトアニメーションのリストからanimation を削除します。
void QStateMachine::removeState(QAbstractState *state)
指定されたstate をこのステートマシンから削除します。ステートマシンは状態の所有権を解放します。
addState()も参照して ください。
[signal]
void QStateMachine::runningChanged(bool running)
このシグナルは、実行中のプロパティがrunning を引数として変更されたときに発行されます。
注: プロパティrunning に対するノーティファイア・シグナル。
QStateMachine::runningも参照して ください。
void QStateMachine::setAnimated(bool enabled)
このステートマシンのアニメーションがenabled であるかどうかを設定する。
注: プロパティのセッター関数animated 。
isAnimated()も参照 。
void QStateMachine::setGlobalRestorePolicy(QState::RestorePolicy restorePolicy)
ステートマシンのリストアポリシーをrestorePolicy に設定します。 デフォルトのリストアポリシーはQState::DontRestoreProperties です。
注: プロパティglobalRestorePolicy のセッター関数。
globalRestorePolicy()も参照して ください。
[slot]
void QStateMachine::start()
このステートマシンを起動します。マシンは構成をリセットし、初期状態に遷移します。最終的なトップレベル状態(QFinalState)に入ると、マシンはfinished() シグナルを発する。
注: QCoreApplication::exec() やQApplication::exec() で開始されるメイン・アプリケーション・イベント・ループなど、実行中のイベント・ループがないと、ステート・マシンは実行されません。
started()、finished()、stop()、initialState()、setRunning()も参照してください 。
[private signal]
void QStateMachine::started()
このシグナルは、ステートマシンが初期状態(QStateMachine::initialState)に入ったときに発せられる。
注意: これはプライベート・シグナルです。シグナル接続で使用することはできますが、ユーザーが発することはできません。
QStateMachine::finished() およびQStateMachine::start()も参照してください 。
[slot]
void QStateMachine::stop()
このステートマシンを停止します。ステートマシンはイベント処理を停止し、stopped() シグナルを発信します。
stopped ()、start ()、setRunning ()も参照 。
[private signal]
void QStateMachine::stopped()
このシグナルは、ステートマシンが停止したときに発行されます。
注意: これはプライベート・シグナルです。シグナル接続で使用することはできますが、ユーザーが発することはできません。
QStateMachine::stop() およびQStateMachine::finished()も参照してください 。
本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。