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

メモ:このクラスの関数はすべてリエントラントです。

注意:これらの関数もスレッドセーフです:

パブリック・タイプ

class SignalEvent
class WrappedEvent
enum Error { NoError, NoInitialStateError, NoDefaultStateInHistoryStateError, NoCommonAncestorForTransitionError, StateMachineChildModeSetToParallelError }
enum EventPriority { NormalPriority, HighPriority }

プロパティ

パブリック関数

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::NoError0エラーは発生していない。
QStateMachine::NoInitialStateError1マシンは、初期状態が設定されていない子機を持つQState に入った。このエラーのコンテキストは、初期状態がない状態である。
QStateMachine::NoDefaultStateInHistoryStateError2マシンが、初期状態が設定されていないQHistoryState 。このエラーのコンテキストは、デフォルト状態がないQHistoryState
QStateMachine::NoCommonAncestorForTransitionError3マシンが、ソースとターゲットが同じ状態ツリーに含まれない遷移を選択した。一般的に、これはステートの1つに親が与えられていないか、どのマシンにも追加されていないことを意味します。このエラーのコンテキストは遷移元の状態です。
QStateMachine::StateMachineChildModeSetToParallelError4マシンのchildMode プロパティがQState::ParallelStates に設定されました。 これは不正です。並列として宣言できるのはステートだけであり、ステートマシン自体は宣言できません。この列挙値は Qt 5.14 で追加されました。

setErrorState()も参照してください

enum QStateMachine::EventPriority

この列挙型は、postEvent ()を使用してステートマシンにポストされるイベントの優先度を指定します。

高い優先順位のイベントは、通常の優先順位のイベントよりも先に処理されます。

定数説明
QStateMachine::NormalPriority0イベントは通常の優先度を持つ。
QStateMachine::HighPriority1イベントは高い優先度を持つ。

プロパティの説明

[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.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。