QUndoStack Class

メンバ関数のドキュメント

[explicit] QUndoStack::QUndoStack(QObject *parent = nullptr)

親のparent を持つ、空の取り消しスタックを作成します。スタックは初期状態ではクリーンな状態になります。parent がQUndoGroup オブジェクトである場合、スタックは自動的にそのグループに追加されます。

push()も参照してください 。

[virtual noexcept] QUndoStack::~QUndoStack()

元に戻すスタックを破棄し、そこに含まれているコマンドをすべて削除します。スタックが「QUndoGroup 」内にある場合、そのスタックは自動的にグループから削除されます。

「QUndoStack()」も参照してください 。

void QUndoStack::beginMacro(const QString &text)

指定されたtext 記述に基づくマクロコマンドの作成を開始します。

指定されたtext で記述された空のコマンドがスタックにプッシュされます。その後スタックにプッシュされるコマンドは、endMacro()が呼び出されるまで、その空のコマンドの子として追加されます。

beginMacro() およびendMacro() の呼び出しはネスト可能ですが、beginMacro() を呼び出すたびに、対応するendMacro() の呼び出しが必要です。

マクロの構成中は、スタックが無効化されます。つまり、

• indexChanged() およびcleanChanged() は発行されず、
• canUndo() およびcanRedo() は false を返します。
• undo() またはredo() を呼び出しても何の効果もありません。
• 元に戻す／やり直し操作が無効になります。

最外側のマクロに対してendMacro()が呼び出されると、スタックが有効になり、適切なシグナルが発行されます。

stack.beginMacro("insert red text");
stack.push(new InsertText(document, idx, text));
stack.push(new SetColor(document, idx, text.length(), Qt::red));
stack.endMacro(); // indexChanged() is emitted

このコードは以下と同等です:

QUndoCommand *insertRed = new QUndoCommand(); // an empty command
insertRed->setText("insert red text");

new InsertText(document, idx, text, insertRed); // becomes child of insertRed
new SetColor(document, idx, text.length(), Qt::red, insertRed);

stack.push(insertRed);

endMacro()も参照してください 。

bool QUndoStack::canRedo() const

やり直し可能なコマンドがある場合はtrue を返し、そうでない場合はfalse を返します。

この関数は、スタックが空の場合、またはスタックの先頭にあるコマンドがすでにやり直されている場合に、false を返します。

index() ==count() と同義です。

関連項目: ` index()` および `canUndo()`。

[signal] void QUndoStack::canRedoChanged(bool canRedo)

このシグナルは、canRedo() の値が変更されるたびに発火します。これは、createRedoAction() によって返されるリドゥ操作を有効または無効にするために使用されます。canRedo は新しい値を指定します。

bool QUndoStack::canUndo() const

元に戻せるコマンドが存在する場合は `true ` を返し、そうでない場合は `false` を返します。

この関数は、スタックが空の場合、またはスタックの最下位のコマンドがすでに取り消されている場合に、false を返します。

index() == 0 と同義です。

関連項目： index() およびcanRedo()。

[signal] void QUndoStack::canUndoChanged(bool canUndo)

このシグナルは、canUndo() の値が変化するたびに発火します。これは、createUndoAction() によって返される元に戻す操作を有効または無効にするために使用されます。canUndo は新しい値を指定します。

[signal] void QUndoStack::cleanChanged(bool clean)

このシグナルは、スタックがクリーン状態に入るか、またはクリーン状態を離れるたびに発せられます。clean がtrueの場合、スタックはクリーン状態にあります。そうでない場合、このシグナルはスタックがクリーン状態を離れたことを示します。

関連項目： isClean() およびsetClean()。

int QUndoStack::cleanIndex() const

クリーンインデックスを返します。これは、setClean() が呼び出されたインデックスです。

スタックにはクリーンインデックスが存在しない場合があります。これは、ドキュメントを保存した後、いくつかのコマンドを元に戻し、さらに新しいコマンドをスタックにプッシュした場合に発生します。push() は、新しいコマンドをプッシュする前に元に戻されたすべてのコマンドを削除するため、スタックは再びクリーンな状態に戻ることができません。 この場合、この関数は -1 を返します。また、resetClean() を明示的に呼び出した後にも -1 が返されることがあります。

isClean() およびsetClean()も参照してください 。

void QUndoStack::clear()

コマンドスタック上のすべてのコマンドを削除してスタックをクリアし、スタックを初期状態に戻します。

コマンドの取り消しややり直しは行われず、編集対象の状態は変更されません。

この関数は通常、ドキュメントの内容が破棄される場合に使用されます。

QUndoStack()も参照してください 。

const QUndoCommand *QUndoStack::command(int index) const

index にあるコマンドへの const ポインタを返します。

この関数が const ポインタを返すのは、コマンドがスタックにプッシュされて実行された後、そのコマンドを修正すると、後でそのコマンドを元に戻したりやり直したりした際に、ほぼ必ずドキュメントの状態が破損してしまうためです。

QUndoCommand::child()も参照してください 。

int QUndoStack::count() const

スタック上のコマンドの数を返します。マクロコマンドは1つのコマンドとしてカウントされます。

index()、setIndex()、およびcommand()も参照してください 。

QAction *QUndoStack::createRedoAction(QObject *parent, const QString &prefix = QString()) const

指定されたparent を持つ、再実行可能なQAction オブジェクトを作成します。

このアクションをトリガーすると、redo() が呼び出されます。このアクションのテキストは、次にredo() が呼び出された際にやり直されるコマンドのテキストであり、その先頭に指定されたprefix が付加されます。やり直し可能なコマンドがない場合、このアクションは無効になります。

prefix が空の場合、プレフィックスの代わりにデフォルトのテンプレート「Redo %1」が使用されます。Qt XML 4.8 以前では、デフォルトで「Redo」というプレフィックスが使用されていました。

createUndoAction()、canRedo()、およびQUndoCommand::text()も参照してください 。

QAction *QUndoStack::createUndoAction(QObject *parent, const QString &prefix = QString()) const

指定されたparent を持つ、QAction オブジェクトを作成します。

このアクションがトリガーされると、undo() が呼び出されます。このアクションのテキストは、次にundo() が呼び出された際に元に戻されるコマンドのテキストに、指定されたprefix が接頭辞として付加されたものです。元に戻す対象となるコマンドが存在しない場合、このアクションは無効になります。

prefix が空の場合、prefix の代わりにデフォルトのテンプレート「Undo %1」が使用されます。Qt XML 4.8 以前では、デフォルトで「Undo」という接頭辞が使用されていました。

createRedoAction()、canUndo()、およびQUndoCommand::text()も参照してください 。

void QUndoStack::endMacro()

マクロコマンドの構成を終了します。

ネストされたマクロ群の中でこれが最外側のマクロである場合、この関数はマクロコマンド全体に対して一度だけ `indexChanged()` を発行します。

beginMacro()も参照してください 。

int QUndoStack::index() const

現在のコマンドのインデックスを返します。これは、次にredo() が呼び出された際に実行されるコマンドです。いくつかのコマンドが取り消されている可能性があるため、必ずしもスタックの最上位にあるコマンドとは限りません。

setIndex()、undo()、redo()、およびcount()も参照してください 。

[signal] void QUndoStack::indexChanged(int idx)

このシグナルは、コマンドによってドキュメントの状態が変更されるたびに発火します。これは、コマンドの取り消しややり直しが行われた際に発生します。マクロコマンドの取り消しややり直しが行われた場合、あるいはsetIndex()が呼び出された場合、このシグナルは1回だけ発火します。

idx 現在のコマンド、すなわち次にredo() が呼び出された際に実行されるコマンドのインデックスを指定します。

index() およびsetIndex()も参照してください 。

bool QUndoStack::isClean() const

スタックがクリーンな状態の場合は `true` を返し、そうでない場合は `false` を返します。

関連項目： setClean() およびcleanIndex()。

void QUndoStack::push(QUndoCommand *cmd)

cmd をスタックにプッシュするか、直近で実行されたコマンドとマージします。いずれの場合も、cmd のredo()関数を呼び出して実行します。

cmd のidが-1ではなく、かつそのidが直近で実行されたコマンドのidと同一である場合、QUndoStack は、直近で実行されたコマンドに対してQUndoCommand::mergeWith()を呼び出すことで、2つのコマンドのマージを試みます。QUndoCommand::mergeWith()がtrue を返した場合、cmd は削除されます。

QUndoCommand::redo() および、該当する場合はQUndoCommand::mergeWith() を呼び出した後、cmd またはマージされたコマンドに対してQUndoCommand::isObsolete() が呼び出されます。QUndoCommand::isObsolete() がtrue を返した場合、cmd またはマージされたコマンドがスタックから削除されます。

それ以外の場合は、cmd が単にスタックにプッシュされます。

cmd がスタックにプッシュされる前にコマンドが取り消されていた場合、現在のコマンドおよびそれより上のすべてのコマンドが削除されます。したがって、cmd は常にスタックの最上位に配置されることになります。

コマンドがスタックにプッシュされると、そのコマンドはスタックが管理することになります。コマンドを返すゲッターは存在しません。これは、実行後のコマンドを変更すると、ほぼ確実にドキュメントの状態が破損してしまうためです。

QUndoCommand::id() およびQUndoCommand::mergeWith()も参照してください 。

[slot] void QUndoStack::redo()

QUndoCommand::redo() を呼び出して、現在のコマンドをやり直します。現在のコマンドインデックスをインクリメントします。

スタックが空の場合、またはスタックの先頭にあるコマンドがすでに再実行済みの場合は、この関数は何も行いません。

QUndoCommand::isObsolete() が現在のコマンドに対して true を返す場合、そのコマンドはスタックから削除されます。さらに、clean インデックスが現在のコマンドインデックス以上である場合、clean インデックスはリセットされます。

undo() およびindex()も参照してください 。

QString QUndoStack::redoText() const

redo() の次回の呼び出しで再実行されるコマンドのテキストを返します。

関連項目： QUndoCommand::actionText() およびundoText()。

[signal] void QUndoStack::redoTextChanged(const QString &redoText)

このシグナルは、redoText() の値が変更されるたびに発火します。これは、createRedoAction() によって返される「やり直し」アクションの text プロパティを更新するために使用されます。redoText は新しいテキストを指定します。

[slot] void QUndoStack::resetClean()

クリーン状態を解除し、スタックがクリーンだった場合はcleanChanged()を発行します。このメソッドは、クリーンインデックスを-1にリセットします。

これは通常、ドキュメントが以下の状態にある場合に呼び出されます。

• テンプレートに基づいて作成され、まだ保存されていないため、ドキュメントにファイル名が割り当てられていない場合。
• バックアップファイルから復元された場合。
• エディタ外で変更され、ユーザーが再読み込みを行っていない場合。

isClean()、setClean()、およびcleanIndex()も参照してください 。

[slot] void QUndoStack::setClean()

スタックがまだクリーンでない場合、スタックをクリーンとしてマークし、cleanChanged() を出力します。

これは通常、例えばドキュメントを保存する際に呼び出されます。

スタックが「undo」や「redo」コマンドの使用によってこの状態に戻るたびに、cleanChanged() シグナルを発生させます。このシグナルは、スタックがクリーン状態を離れたときにも発生します。

isClean()、resetClean()、およびcleanIndex()も参照してください 。

[slot] void QUndoStack::setIndex(int idx)

現在のコマンドインデックスが `idx` に達するまで、`undo()` または `redo()` を繰り返し呼び出します。この関数は、ドキュメントの状態を前方または後方に巻き戻すために使用できます。`indexChanged()` は 1 回のみ発行されます。

index()、count()、undo()、およびredo()も参照してください 。

QString QUndoStack::text(int idx) const

インデックスidx にあるコマンドのテキストを返します。

beginMacro()も参照してください 。

[slot] void QUndoStack::undo()

QUndoCommand::undo() を呼び出して、現在のコマンドの直下のコマンドを元に戻します。現在のコマンドインデックスを1減らします。

スタックが空の場合、またはスタックの最下位のコマンドがすでに元に戻されている場合、この関数は何も行いません。

コマンドの取り消し後、QUndoCommand::isObsolete()がtrue を返した場合、そのコマンドはスタックから削除されます。さらに、cleanインデックスが現在のコマンドインデックス以上である場合、cleanインデックスはリセットされます。

redo() およびindex()も参照してください 。

QString QUndoStack::undoText() const

undo() が次に呼び出された際に元に戻されるコマンドのテキストを返します。

関連項目： QUndoCommand::actionText() およびredoText()。

[signal] void QUndoStack::undoTextChanged(const QString &undoText)

このシグナルは、undoText() の値が変更されるたびに発火します。これは、createUndoAction() によって返される元に戻すアクションの text プロパティを更新するために使用されます。undoText は、新しいテキストを指定します。