Interfaccia IOleUndoManager (ocidl.h)
L'interfaccia IOleUndoManager consente ai contenitori di implementare operazioni di annullamento e ripristino a più livelli per le azioni che si verificano all'interno di controlli contenuti.
Ereditarietà
L'interfaccia IOleUndoManager eredita dall'interfaccia IUnknown . IOleUndoManager include anche questi tipi di membri:
Metodi
L'interfaccia IOleUndoManager include questi metodi.
| IOleUndoManager::Add Aggiunge un'unità di annullamento semplice alla raccolta. Anche se un'unità padre di annullamento è aperta, la gestione annulla aggiunge unità di annullamento a questa unità chiamando IOleParentUndoUnit::Add. |
| IOleUndoManager::Close Chiude l'unità di annullamento padre specificata. (IOleUndoManager.Close) |
| IOleUndoManager::D iscardFrom Indica al manager di annullare l'eliminazione dell'unità di annullamento specificata e di tutte le unità di annullamento sotto di esso nello stack di annullamento o ripristino. |
| IOleUndoManager::Enable Abilita o disabilita la gestione annullamento. |
| IOleUndoManager::EnumRedoable Crea un oggetto enumeratore che il chiamante può usare per scorrere una serie di unità di annullamento di primo livello dallo stack di ripristino. |
| IOleUndoManager::EnumUndoable Crea un oggetto enumeratore che il chiamante può usare per eseguire l'iterazione tramite una serie di unità di annullamento di primo livello dallo stack di annullamento. |
| IOleUndoManager::GetLastRedoDescription Recupera la descrizione per l'unità di annullamento di primo livello che si trova nella parte superiore dello stack di ridistribuzione. |
| IOleUndoManager::GetLastUndoDescription Recupera la descrizione per l'unità di annullamento di primo livello che si trova nella parte superiore dello stack di annullamento. |
| IOleUndoManager::GetOpenParentState Recupera le informazioni sullo stato sull'unità padre più aperta all'interno. (IOleUndoManager.GetOpenParentState) |
| IOleUndoManager::Open Apre una nuova unità padre di annullamento, che diventa parte dello stack di annullamento dell'unità contenente. |
| IOleUndoManager::RedoTo Indica al gestore di annullamento di richiamare le azioni di annullamento tramite lo stack di ripristino, fino a e includere l'unità di annullamento specificata. |
| IOleUndoManager::UndoTo Indica al gestore di annullamento di richiamare le azioni di annullamento tramite lo stack di annullamento, fino a e includere l'unità di annullamento specificata. |
Commenti
Il controllo deve creare un'unità di annullamento con l'interfaccia IOleUndoUnit o un'unità padre di annullamento con l'interfaccia IOleParentUndoUnit derivata da IOleUndoUnit. Entrambe queste interfacce eseguono l'azione di annullamento e l'unità padre di annullamento possono inoltre contenere unità di annullamento annidate.
Il gestore di annullamento fornisce un servizio di annullamento e ripristino centralizzato. Gestisce unità di annullamento padre e unità di annullamento semplici negli stack di annullamento e ripristino. Indipendentemente dal fatto che un oggetto sia attivo dall'interfaccia utente o meno, può depositare unità di annullamento in questi stack chiamando i metodi nella gestione annullamento.
Il gestore di annullamento centralizzato dispone quindi dei dati necessari per supportare l'interfaccia utente di annullamento e ripristino per l'applicazione host e può eliminare le informazioni di annullamento gradualmente man mano che lo stack diventa pieno.
La gestione annullamento viene implementata come servizio e gli oggetti ottengono un puntatore a IOleUndoManger dall'interfaccia IServiceProvider . In genere viene implementato dal contenitore. Il servizio gestisce due stack, lo stack di annullamento e lo stack di ridistribuzione, ognuno dei quali contiene unità di annullamento generate da oggetti incorporati o dall'applicazione contenitore stessa.
Le unità di annullamento vengono in genere generate in risposta alle azioni eseguite dall'utente finale. Un oggetto non genera azioni di annullamento per gli eventi a livello di codice. In effetti, gli eventi a livello di codice devono cancellare lo stack di annullamento poiché l'evento programmatico può eventualmente invalidare le ipotesi effettuate dalle unità di annullamento nello stack.
Quando lo stato dell'oggetto cambia, crea un'unità di annullamento che incapsula tutte le informazioni necessarie per annullare tale modifica. L'oggetto chiama i metodi nella gestione annullamento per posizionare le unità di annullamento nello stack. Quando quindi l'utente finale seleziona un'operazione Annulla, il gestore annulla accetta l'unità di annullamento superiore dello stack, richiama l'azione chiamando il metodo IOleUndoUnit::D o e quindi lo rilascia. Quando un utente finale seleziona un'operazione Di ripristino, il gestore di annullamento accetta l'unità di ridistribuzione superiore dallo stack, richiama l'azione chiamando il relativo metodo IOleUndoUnit::D o e quindi rilasciarlo.
Il gestore annulla ha tre stati: lo stato di base, lo stato di annullamento e lo stato di ripristino. Inizia nello stato di base. Per eseguire un'azione dallo stack di annullamento, si inserisce nello stato di annullamento, chiama IOleUndoUnit::D o nell'unità di annullamento e torna allo stato di base. Per eseguire un'azione dallo stack di ripristino, si inserisce nello stato di ripristino, chiama IOleUndoUnit::D o nell'unità di annullamento e torna allo stato di base.
Se il gestore annulla riceve una nuova unità di annullamento durante lo stato di base, inserisce l'unità nello stack di annullamento e rimuove l'intero stack di ripristino. Mentre si trova nello stato di annullamento, inserisce le unità in ingresso nello stack di ridistribuimento. Mentre si trova nello stato di ripristino, li inserisce nello stack di annullamento senza scaricare lo stack di ripristino.
La gestione annullamento consente anche agli oggetti di eliminare lo stack di annullamento o ripristino a partire da qualsiasi oggetto in uno stack.
L'applicazione host determina l'ambito di un gestore di annullamento. Ad esempio, in un'applicazione, l'ambito potrebbe essere a livello di documento; un gestore di annullamento separato viene mantenuto per ogni documento; e annullare l'annullamento viene gestito in modo indipendente per ogni documento. Tuttavia, un'altra applicazione mantiene una gestione annulla e quindi un ambito annulla, per l'intera applicazione.
Gestione degli errori
L'esito negativo di un'operazione di annullamento e l'uscita del documento in uno stato instabile è qualcosa che il gestore di annullamento, l'annullamento delle unità e l'applicazione stessa devono collaborare per evitare. Di conseguenza, esistono determinati requisiti che annullano le unità, il gestore di annullamento e il componente o l'applicazione che usa annulla devono essere conformi.
Per eseguire un annullamento, il gestore annulla chiama IOleUndoUnit::D o su una o più unità che possono, a sua volta, contenere più unità. Se un'unità nella gerarchia ha esito negativo, l'errore raggiungerà infine il gestore di annullamento, responsabile del tentativo di eseguire il rollback dello stato del documento a quello che era prima della chiamata all'ultima unità di primo livello. Il gestore annulla esegue il rollback chiamando IOleUndoUnit::D o nell'unità aggiunta allo stack di ripristino durante il tentativo di annullamento. Se il rollback ha esito negativo, il gestore annulla viene costretto ad abbandonare tutto e tornare all'applicazione. Il gestore annulla indica se il rollback ha avuto esito positivo e l'applicazione può eseguire azioni diverse in base a questa operazione, ad esempio reinizializzare i componenti in modo che siano in uno stato noto.
Tutti i passaggi nell'aggiunta di un'unità di annullamento allo stack devono essere eseguiti atomicamente. Ecco, tutti i passaggi devono avere esito positivo o nessuno di loro dovrebbe avere esito positivo.
L'applicazione host che fornisce il gestore di annullamento decide l'azione da eseguire quando l'annullamento ha esito negativo. Almeno, deve informare l'utente dell'errore. L'applicazione host verrà comunicata dal gestore di annullamento se l'annullamento ha avuto esito positivo e se il rollback tentato ha avuto esito positivo. Nel caso in cui l'annullamento e il rollback non siano riusciti, l'applicazione host può presentare all'utente diverse opzioni, tra cui l'arresto immediato dell'applicazione.
Le unità di annullamento semplici non devono modificare lo stato di qualsiasi oggetto se restituiscono errori. Questo include lo stato dello stack di ridistribuzione o annulla se si esegue un ripristino. Sono inoltre necessari per inserire un'unità corrispondente nello stack di ripristino o annullamento se hanno esito positivo. L'applicazione deve essere stabile prima e dopo la chiamata dell'unità.
Le unità di annullamento padre hanno gli stessi requisiti delle unità semplici, con un'eccezione. Se uno o più elementi figlio hanno avuto esito positivo prima dell'errore di un altro figlio, l'unità padre deve eseguire il commit dell'unità corrispondente nello stack di ridistribuire e restituire l'errore al relativo padre. Se nessun elemento figlio ha esito positivo, l'unità padre deve eseguire il commit della relativa unità di ripristino solo se ha apportato una modifica dello stato che deve essere eseguito il rollback. Si supponga, ad esempio, che un'unità padre contenga tre unità semplici. I primi due hanno avuto esito positivo e aggiunto unità allo stack di ripristino, ma il terzo non è riuscito. A questo punto, l'unità padre esegue il commit della relativa unità di ripristino e restituisce l'errore.
Come effetto collaterale, l'unità padre non deve mai apportare modifiche allo stato che dipendono dal successo dei figli. In questo modo il comportamento di rollback verrà interrotto. Se un'unità padre apporta modifiche allo stato, deve eseguirle prima di chiamare qualsiasi elemento figlio. Se la modifica dello stato ha esito negativo, non deve eseguire il commit della relativa unità di ripristino, non deve chiamare elementi figlio e deve restituire l'errore al relativo padre.
Il gestore di annullamento ha un requisito primario per la gestione degli errori: per tentare il rollback quando un annullamento o un ripristino ha esito negativo.
Oggetti non conformi
Gli oggetti che non supportano l'annullamento a più livelli possono causare gravi problemi per un servizio di annullamento globale. Poiché l'oggetto non può essere basato su per aggiornare correttamente il gestore di annullamento, tutte le unità inviate da altri oggetti sono sospette, perché le unità possono basarsi sullo stato dell'oggetto non conforme. Il tentativo di annullare l'annullamento delle unità di un oggetto conforme potrebbe non essere riuscito, perché lo stato nell'oggetto non conforme non corrisponderà.
Per rilevare gli oggetti che non supportano l'annullamento a più livelli, verificare la presenza del valore di OLEMISC_SUPPORTSMULTILEVELUNDO. Un oggetto che può partecipare al servizio di annullamento globale imposta questo valore.
Quando un oggetto senza questo valore viene aggiunto a un contesto di annullamento visibile dall'utente, è consigliabile disabilitare l'interfaccia utente di annullamento per questo contesto. In alternativa, un dialogo potrebbe essere presentato all'utente, chiedendogli se tentare di fornire supporto parziale di annullamento, aggirare la mancata conformità del nuovo oggetto.
Inoltre, è possibile aggiungere oggetti non conformi ai contenitori annidati. In questo caso, il contenitore annidato deve notificare al gestore di annullamento che l'annullamento non può più essere supportato in modo sicuro chiamando IOleUndoManager::Enable con FALSE.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [app desktop | App UWP] |
| Server minimo supportato | Windows 2000 Server [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | ocidl.h |