IOleUndoManager-Schnittstelle (ocidl.h)
Mit der IOleUndoManager-Schnittstelle können Container Vorgänge zum Rückgängigmachen und Wiederholen auf mehreren Ebenen für Aktionen implementieren, die in enthaltenen Steuerelementen auftreten.
Vererbung
Die IOleUndoManager-Schnittstelle erbt von der IUnknown-Schnittstelle . IOleUndoManager verfügt auch über folgende Membertypen:
Methoden
Die IOleUndoManager-Schnittstelle verfügt über diese Methoden.
| IOleUndoManager::Add Fügt der Auflistung eine einfache Rückgängig-Einheit hinzu. Während eine übergeordnete Undo-Einheit geöffnet ist, fügt der Rückgängig-Manager rückgängige Einheiten hinzu, indem er IOleParentUndoUnit::Add aufruft. |
| IOleUndoManager::Close Schließt die angegebene übergeordnete Rückgängig-Komponente. (IOleUndoManager.Close) |
| IOleUndoManager::D iscardFrom Weist den Rückgängig-Manager an, die angegebene Undo-Einheit und alle rückgängigen Einheiten darunter auf dem Stapel "Rückgängig" oder "Wiederholen" zu verwerfen. |
| IOleUndoManager::Enable Aktiviert oder deaktiviert den Rückgängig-Manager. |
| IOleUndoManager::EnumRedoable Erstellt ein Enumeratorobjekt, mit dem der Aufrufer eine Reihe von Rückgängigeinheiten der obersten Ebene aus dem Wiederholungsstapel durchlaufen kann. |
| IOleUndoManager::EnumUndoable Erstellt ein Enumeratorobjekt, mit dem der Aufrufer eine Reihe von Rückgängig-Einheiten der obersten Ebene aus dem Undo-Stapel durchlaufen kann. |
| IOleUndoManager::GetLastRedoDescription Ruft die Beschreibung für die Rückgängig-Einheit der obersten Ebene ab, die sich auf dem Wiederholungsstapel befindet. |
| IOleUndoManager::GetLastUndoDescription Ruft die Beschreibung für die Rückgängig-Einheit der obersten Ebene ab, die sich auf dem Rückgängigstapel befindet. |
| IOleUndoManager::GetOpenParentState Ruft Zustandsinformationen zur innersten geöffneten übergeordneten Undo-Einheit ab. (IOleUndoManager.GetOpenParentState) |
| IOleUndoManager::Open Öffnet eine neue übergeordnete Undo-Einheit, die Teil des Stapels zum Rückgängigmachen der enthaltenen Einheit wird. |
| IOleUndoManager::RedoTo Weist den Rückgängig-Manager an, Rückgängig-Aktionen zurück über den Wiederholungsstapel aufzurufen, bis hin zu und einschließlich der angegebenen Undo-Einheit. |
| IOleUndoManager::UndoTo Weist den Rückgängig-Manager an, Rückgängig-Aktionen zurück über den Rückgängigstapel aufzurufen, bis hin zu und einschließlich der angegebenen Undo-Einheit. |
Hinweise
Das Steuerelement muss eine Undo-Einheit mit der IOleUndoUnit-Schnittstelle oder eine übergeordnete undo-Einheit mit der von IOleUndoUnit abgeleiteten IOleParentUndoUnit-Schnittstelle erstellen. Beide Schnittstellen führen die Rückgängig-Aktion aus, und die übergeordnete Undo-Einheit kann zusätzlich geschachtelte Undo-Einheiten enthalten.
Der Rückgängig-Manager stellt einen zentralisierten Rückgängig- und Wiederholungsdienst bereit. Es verwaltet übergeordnete Rückgängig-Einheiten und einfache Rückgängig-Einheiten für die Stapel "Rückgängig" und "Wiederholen". Unabhängig davon, ob ein Objekt benutzeroberflächeaktiv ist oder nicht, kann es Rückgängigeinheiten auf diesen Stapeln ablegen, indem Methoden im Rückgängig-Manager aufgerufen werden.
Der zentralisierte Undo-Manager verfügt dann über die erforderlichen Daten, um die Benutzeroberfläche zum Rückgängigmachen und Wiederholen für die Hostanwendung zu unterstützen, und kann Rückgängiginformationen schrittweise verwerfen, wenn der Stapel voll wird.
Der Undo-Manager wird als Dienst implementiert, und Objekte erhalten von der IServiceProvider-Schnittstelle einen Zeiger auf IOleUndoManger. Sie wird in der Regel vom Container implementiert. Der Dienst verwaltet zwei Stapel, den Undo-Stapel und den Wiederholungsstapel, die jeweils Rückgängigeinheiten enthält, die von eingebetteten Objekten oder von der Containeranwendung selbst generiert wurden.
Rückgängig-Einheiten werden in der Regel als Reaktion auf Aktionen generiert, die vom Endbenutzer ausgeführt werden. Ein -Objekt generiert keine Rückgängig-Aktionen für programmgesteuerte Ereignisse. In der Tat sollten programmgesteuerte Ereignisse den Undo-Stapel löschen, da das programmgesteuerte Ereignis annahmen, die von den Rückgängigeinheiten auf dem Stapel vorgenommen wurden, möglicherweise ungültig machen kann.
Wenn sich der Zustand des Objekts ändert, wird eine Rückgängig-Einheit erstellt, die alle Informationen kapselt, die zum Rückgängigmachen dieser Änderung erforderlich sind. Das -Objekt ruft Methoden im Undo-Manager auf, um seine Rückgängig-Einheiten auf dem Stapel zu platzieren. Wenn der Endbenutzer dann einen Undo-Vorgang auswählt, nimmt der Rückgängig-Manager die oberste Rückgängig-Einheit vom Stapel, ruft ihre Aktion auf, indem er die IOleUndoUnit::D o-Methode aufruft, und gibt sie dann frei. Wenn ein Endbenutzer einen Redo-Vorgang auswählt, nimmt der Rückgängig-Manager die oberste Wiederholungseinheit aus dem Stapel, ruft ihre Aktion auf, indem er die IOleUndoUnit::D o-Methode aufruft, und gibt sie dann frei.
Der Rückgängig-Manager verfügt über drei Zustände: den Basiszustand, den Undo-Zustand und den Wiederholungszustand. Sie beginnt im Basiszustand. Um eine Aktion aus dem Undo-Stapel auszuführen, versetzt es sich in den Undo-Zustand, ruft IOleUndoUnit::D o für die Undo-Einheit auf und wechselt zum Basiszustand zurück. Um eine Aktion aus dem Wiederholungsstapel auszuführen, versetzt sie sich in den Wiederholungszustand, ruft IOleUndoUnit::D o für die Rückgängigeinheit auf und wechselt zum Basiszustand zurück.
Wenn der Rückgängig-Manager im Basiszustand eine neue Undo-Einheit empfängt, platziert er die Einheit auf dem Rückgängigstapel und verwirft den gesamten Wiederholungsstapel. Während es sich im Zustand "Rückgängig" befindet, werden eingehende Einheiten auf dem Wiederholungsstapel platziert. Während es sich im Wiederholungszustand befindet, platziert es sie auf dem Rückgängigstapel, ohne dass der Wiederholungsstapel geleert wird.
Der Rückgängig-Manager ermöglicht es Objekten auch, den Rückgängig- oder Wiederholungsstapel ab einem beliebigen Objekt in beiden Stapeln zu verwerfen.
Die Hostanwendung bestimmt den Bereich eines Rückgängig-Managers. In einer Anwendung kann sich der Bereich beispielsweise auf Dokumentebene befinden. Für jedes Dokument wird ein separater Rückgängig-Manager verwaltet. und rückgängig wird für jedes Dokument unabhängig verwaltet. Eine andere Anwendung verwaltet jedoch einen Undo-Manager und damit einen Rückgängigbereich für die gesamte Anwendung.
Fehlerbehandlung
Wenn ein Rückgängigvorgang fehlschlägt und das Dokument in einem instabilen Zustand bleibt, müssen der Rückgängig-Manager, die Rückgängig-Einheiten und die Anwendung selbst zusammenarbeiten, um zu vermeiden. Daher gibt es bestimmte Anforderungen, denen rückgängige Einheiten, der Undo-Manager und die Anwendung oder Komponente, die undo verwendet, entsprechen müssen.
Um ein Rückgängig auszuführen, ruft der Rückgängig-Manager IOleUndoUnit::D o für eine oder mehrere Rückgängig-Einheiten auf, die wiederum mehr Einheiten enthalten können. Wenn eine Einheit irgendwo in der Hierarchie fehlschlägt, erreicht der Fehler schließlich den Rückgängig-Manager, der für den Versuch verantwortlich ist, den Status des Dokuments auf den Zustand zurück zu setzen, der vor dem Aufruf der letzten Einheit der obersten Ebene war. Der Rückgängig-Manager führt das Rollback durch, indem er IOleUndoUnit::D o für die Einheit aufruft, die während des Rückgängigversuchs dem Wiederholungsstapel hinzugefügt wurde. Wenn das Rollback ebenfalls fehlschlägt, ist der Rückgängig-Manager gezwungen, alles abzubrechen und zur Anwendung zurückzukehren. Der Rückgängig-Manager gibt an, ob das Rollback erfolgreich war, und die Anwendung kann basierend darauf verschiedene Aktionen ausführen, z. B. das erneute Initialisieren von Komponenten, damit sie sich in einem bekannten Zustand befinden.
Alle Schritte zum Hinzufügen einer Rückgängig-Einheit zum Stapel sollten atomar ausgeführt werden. Das heißt, alle Schritte müssen erfolgreich sein, oder keiner davon sollte erfolgreich sein.
Die Hostanwendung, die den Undo-Manager bereitstellt, entscheidet, welche Aktion ausgeführt werden soll, wenn ein Rückgängigfehler auftritt. Zumindest sollte es den Benutzer über den Fehler informieren. Die Hostanwendung wird vom Rückgängig-Manager darüber benachrichtigt, ob der Rückgängigvorgang erfolgreich war und ob das versuchte Rollback erfolgreich war. Falls sowohl beim Rückgängigmachen als auch beim Rollback ein Fehler aufgetreten ist, kann die Hostanwendung dem Benutzer mehrere Optionen bereitstellen, einschließlich des sofortigen Herunterfahrens der Anwendung.
Einfache Rückgängigeinheiten dürfen den Zustand eines Objekts nicht ändern, wenn sie einen Fehler zurückgeben. Dies schließt den Zustand des Wiederholungsstapels oder des Rückgängigstapels ein, wenn ein Wiederholen ausgeführt wird. Sie sind auch erforderlich, um eine entsprechende Einheit im Wiederholungs- oder Rückgängigstapel zu platzieren, wenn sie erfolgreich sind. Die Anwendung sollte vor und nach dem Aufruf der Einheit stabil sein.
Übergeordnete Undo-Einheiten haben die gleichen Anforderungen wie einfache Einheiten, mit einer Ausnahme. Wenn mindestens ein untergeordnetes Element vor dem Fehler eines anderen untergeordneten Elements erfolgreich war, muss die übergeordnete Einheit ihre entsprechende Einheit auf dem Wiederholungsstapel committen und den Fehler an ihr übergeordnetes Element zurückgeben. Wenn keine untergeordneten Elemente erfolgreich waren, sollte die übergeordnete Einheit ihre Wiederholungseinheit nur dann committen, wenn sie eine Zustandsänderung vorgenommen hat, die zurückgesetzt werden muss. Angenommen, eine übergeordnete Einheit enthält drei einfache Einheiten. Die ersten beiden sind erfolgreich und haben dem Wiederholungsstapel Einheiten hinzugefügt, aber bei der dritten ist ein Fehler aufgetreten. An diesem Punkt committ die übergeordnete Einheit ihre Wiederholungseinheit und gibt den Fehler zurück.
Als Nebeneffekt sollte die übergeordnete Einheit niemals Zustandsänderungen vornehmen, die vom Erfolg ihrer untergeordneten Elemente abhängen. Dadurch wird das Rollbackverhalten unterbrochen. Wenn eine übergeordnete Einheit Zustandsänderungen vornimmt, sollte sie diese vor dem Aufrufen untergeordneter Elemente ausführen. Wenn die Zustandsänderung dann fehlschlägt, sollte sie die Wiederholungseinheit nicht committen, keine untergeordneten Elemente aufrufen und den Fehler an das übergeordnete Element zurückgeben.
Der Undo-Manager hat eine Hauptanforderung für die Fehlerbehandlung: das Versuchen eines Rollbacks, wenn ein Rückgängig- oder Wiederholungsfehler auftritt.
Nicht kompatible Objekte
Objekte, die nicht mehrstufiges Rückgängigmachen unterstützen, können schwerwiegende Probleme für einen globalen Rückgängigdienst verursachen. Da das -Objekt nicht für die ordnungsgemäße Aktualisierung des Undo-Managers verwendet werden kann, sind alle von anderen Objekten übermittelten Einheiten ebenfalls verdächtig, da ihre Einheiten möglicherweise auf dem Zustand des nicht konformen Objekts basieren. Der Versuch, die Einheiten eines konformen Objekts rückgängig zu machen, ist möglicherweise nicht erfolgreich, da der Zustand im nicht konformen Objekt nicht übereinstimmt.
Um Objekte zu erkennen, die nicht mehrstufiges Rückgängigmachen unterstützen, suchen Sie nach dem wert OLEMISC_SUPPORTSMULTILEVELUNDO. Ein Objekt, das am globalen Undo-Dienst teilnehmen kann, legt diesen Wert fest.
Wenn ein Objekt ohne diesen Wert einem benutzerseitig sichtbaren Rückgängig-Kontext hinzugefügt wird, besteht die bewährte Methode darin, die Rückgängig-Benutzeroberfläche für diesen Kontext zu deaktivieren. Alternativ kann dem Benutzer ein Dialogfeld angezeigt werden, in dem er gefragt wird, ob er versuchen soll, teilweise Rückgängig-Unterstützung bereitzustellen, um die Nichtkonformität des neuen Objekts zu umgehen.
Außerdem können nicht kompatible Objekte geschachtelten Containern hinzugefügt werden. In diesem Fall muss der geschachtelte Container den Rückgängig-Manager benachrichtigen, dass rückgängig gemacht werden kann, indem IOleUndoManager::Enable mit FALSE aufgerufen wird.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ocidl.h |