QStateMachine Class

QStateMachine 클래스는 계층적 유한 상태 머신을 제공합니다. 더 보기...

Header: #include <QStateMachine>
CMake: find_package(Qt6 REQUIRED COMPONENTS StateMachine)
target_link_libraries(mytarget PRIVATE Qt6::StateMachine)
qmake: QT += statemachine
상속합니다: 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 프레임워크의 일부입니다.

상태 머신은 상태 집합( QAbstractState)을 상속하는 클래스와 이러한 상태 사이의 전환( QAbstractTransition)을 관리하며, 이러한 상태와 전환은 상태 그래프를 정의합니다. 상태 그래프가 구축되면 상태 머신은 이를 실행할 수 있습니다. QStateMachine의 실행 알고리즘은 상태 차트 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 열거형에 설명되어 있습니다. 오류 상태가 입력된 후 error()로 오류 유형을 검색할 수 있습니다. 오류 상태가 입력되어도 상태 그래프의 실행은 중지되지 않습니다. 오류 상태에 해당하는 오류 상태가 없으면 실행이 중지되고 콘솔에 오류 메시지가 인쇄됩니다.

참고 : 중요: 상태 머신의 ChildMode 을 병렬(ParallelStates)로 설정하면 잘못된 상태 머신이 생성됩니다. ExclusiveStates 로만 설정(또는 그대로 유지)할 수 있습니다.

QAbstractState, QAbstractTransition, QState, Qt State Machine 개요를참조하세요 .

멤버 유형 문서

enum QStateMachine::Error

이 열거형 타입은 런타임에 상태 머신에서 발생할 수 있는 오류를 정의합니다. 상태 머신이 런타임에 복구할 수 없는 오류가 발생하면 error()에서 반환하는 오류 코드와 errorString()에서 반환하는 오류 메시지를 설정하고 오류의 컨텍스트에 따라 오류 상태를 입력합니다.

상수설명
QStateMachine::NoError0오류가 발생하지 않았습니다.
QStateMachine::NoInitialStateError1머신이 초기 상태가 설정되지 않은 자식이 있는 QState 을 입력했습니다. 이 오류의 컨텍스트는 초기 상태가 누락된 상태입니다.
QStateMachine::NoDefaultStateInHistoryStateError2기본 상태가 설정되어 있지 않은 QHistoryState 을 입력했습니다. 이 오류의 컨텍스트는 기본 상태가 누락된 QHistoryState 입니다.
QStateMachine::NoCommonAncestorForTransitionError3머신이 소스 및 대상이 동일한 상태 트리에 속하지 않아 동일한 상태 머신의 일부가 아닌 전환을 선택했습니다. 일반적으로 이는 상태 중 하나에 부모가 지정되지 않았거나 머신에 추가되지 않았음을 의미할 수 있습니다. 이 오류의 컨텍스트는 전환의 소스 상태입니다.
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)

알림 신호:

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

상태 머신의 복원 정책을 반환합니다.

참고: 글로벌 복원 정책 속성에 대한 게터 함수입니다.

setGlobalRestorePolicy()도 참조하세요 .

bool QStateMachine::isAnimated() const

이 상태 머신에 애니메이션이 활성화되어 있는지 여부를 반환합니다.

참고: 프로퍼티에 대한 게터 함수 animated.

[override virtual protected] void QStateMachine::onEntry(QEvent *event)

다시 구현합니다: QState::onEntry(QEvent * 이벤트).

이 함수는 start()를 호출하여 상태 머신을 시작합니다.

[override virtual protected] void QStateMachine::onExit(QEvent *event)

다시 구현합니다: QState::onExit(QEvent *event).

이 함수는 stop()를 호출하여 상태 머신을 중지하고 이후 stopped() 신호를 내보냅니다.

int QStateMachine::postDelayedEvent(QEvent *event, int delay)

이 상태 머신에서 처리하도록 주어진 event 을 밀리초 단위로 delay 로 게시합니다. 지연된 이벤트와 연관된 식별자를 반환하거나 이벤트를 게시할 수 없는 경우 -1을 반환합니다.

이 함수는 즉시 반환됩니다. 지연 시간이 만료되면 이벤트는 처리를 위해 스테이트 머신의 이벤트 대기열에 추가됩니다. 스테이트 머신은 이벤트의 소유권을 가지며 이벤트가 처리되면 삭제합니다.

상태 머신이 실행 중일 때만 이벤트를 게시할 수 있습니다.

참고: 이 함수는 스레드에 안전합니다.

cancelDelayedEvent() 및 postEvent()도 참조하세요 .

int QStateMachine::postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)

이것은 오버로드된 함수입니다.

이 상태 머신에서 처리하도록 주어진 event 을 밀리초 단위로 delay 로 게시합니다. 지연된 이벤트와 관련된 식별자를 반환하거나 이벤트를 게시할 수 없는 경우 -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()도 참조하세요 .

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.