Interface IOleUndoManager (ocidl.h)
A interface IOleUndoManager permite que os contêineres implementem operações de desfazer e refazer de vários níveis para ações que ocorrem dentro de controles independentes.
Herança
A interface IOleUndoManager herda da interface IUnknown . IOleUndoManager também tem estes tipos de membros:
Métodos
A interface IOleUndoManager tem esses métodos.
| IOleUndoManager::Add Adiciona uma unidade de desfazer simples à coleção. Enquanto uma unidade de desfazer pai está aberta, o gerenciador de desfazer adiciona unidades de desfazer a ela chamando IOleParentUndoUnit::Add. |
| IOleUndoManager::Close Fecha a unidade de desfazer pai especificada. (IOleUndoManager.Close) |
| IOleUndoManager::D iscardFrom Instrui o gerenciador de desfazer a descartar a unidade de desfazer especificada e todas as unidades de desfazer abaixo dela na pilha desfazer ou refazer. |
| IOleUndoManager::Enable Habilita ou desabilita o gerenciador de desfazer. |
| IOleUndoManager::EnumRedoable Cria um objeto enumerador que o chamador pode usar para iterar por meio de uma série de unidades de desfazer de nível superior da pilha de refazer. |
| IOleUndoManager::EnumUndoable Cria um objeto enumerador que o chamador pode usar para iterar por meio de uma série de unidades de desfazer de nível superior da pilha de desfazer. |
| IOleUndoManager::GetLastRedoDescription Recupera a descrição da unidade de desfazer de nível superior que está na parte superior da pilha de refazer. |
| IOleUndoManager::GetLastUndoDescription Recupera a descrição da unidade de desfazer de nível superior que está na parte superior da pilha de desfazer. |
| IOleUndoManager::GetOpenParentState Recupera informações de estado sobre a unidade de desfazer pai mais aberta interna. (IOleUndoManager.GetOpenParentState) |
| IOleUndoManager::Open Abre uma nova unidade de desfazer pai, que se torna parte da pilha de desfazer da unidade que contém. |
| IOleUndoManager::RedoTo Instrui o gerenciador de desfazer a invocar ações de desfazer novamente por meio da pilha de refazer, até e incluindo a unidade de desfazer especificada. |
| IOleUndoManager::UndoTo Instrui o gerenciador de desfazer a invocar ações de desfazer novamente por meio da pilha de desfazer, até e incluindo a unidade de desfazer especificada. |
Comentários
O controle deve criar uma unidade de desfazer com a interface IOleUndoUnit ou uma unidade de desfazer pai com a interface IOleParentUndoUnit derivada de IOleUndoUnit. Essas duas interfaces executam a ação desfazer e a unidade de desfazer pai também pode conter unidades de desfazer aninhadas.
O gerenciador de desfazer fornece um serviço de desfazer e refazer centralizado. Ele gerencia unidades de desfazer pai e unidades de desfazer simples nas pilhas desfazer e refazer. Se um objeto estiver ativo ou não na interface do usuário, ele poderá depositar unidades de desfazer nessas pilhas chamando métodos no gerenciador de desfazer.
Em seguida, o gerenciador de desfazer centralizado tem os dados necessários para dar suporte à interface do usuário desfazer e refazer para o aplicativo host e pode descartar informações de desfazer gradualmente à medida que a pilha fica cheia.
O gerenciador de desfazer é implementado como um serviço e os objetos obtêm um ponteiro para IOleUndoManger da interface IServiceProvider . Geralmente, ele é implementado pelo contêiner. O serviço gerencia duas pilhas, a pilha de desfazer e a pilha de refazer, cada uma contendo unidades de desfazer geradas por objetos inseridos ou pelo próprio aplicativo de contêiner.
Unidades de desfazer normalmente são geradas em resposta a ações executadas pelo usuário final. Um objeto não gera ações de desfazer para eventos programáticos. Na verdade, os eventos programáticos devem limpar a pilha de desfazer, pois o evento programático pode possivelmente invalidar suposições feitas pelas unidades de desfazer na pilha.
Quando o estado do objeto é alterado, ele cria uma unidade de desfazer encapsulando todas as informações necessárias para desfazer essa alteração. O objeto chama métodos no gerenciador de desfazer para colocar suas unidades de desfazer na pilha. Em seguida, quando o usuário final seleciona uma operação Desfazer, o gerenciador de desfazer tira a unidade de desfazer superior da pilha, invoca sua ação chamando seu método IOleUndoUnit::D o e o libera. Quando um usuário final seleciona uma operação Redo, o gerenciador de desfazer tira a unidade de restauração superior da pilha, invoca sua ação chamando seu método IOleUndoUnit::D o e o libera.
O gerenciador de desfazer tem três estados: o estado base, o estado de desfazer e o estado de refazer. Ele começa no estado base. Para executar uma ação da pilha de desfazer, ela se coloca no estado de desfazer, chama IOleUndoUnit::D o na unidade de desfazer e volta para o estado base. Para executar uma ação da pilha de refazer, ela se coloca no estado de refazer, chama IOleUndoUnit::D o na unidade de desfazer e volta para o estado base.
Se o gerenciador de desfazer receber uma nova unidade de desfazer enquanto estiver no estado base, ele colocará a unidade na pilha de desfazer e descartará toda a pilha de refazer. Embora esteja no estado de desfazer, ele coloca unidades de entrada na pilha de refazer. Embora esteja no estado de refazer, ele os coloca na pilha de desfazer sem liberar a pilha de refazer.
O gerenciador de desfazer também permite que os objetos descartem a pilha desfazer ou refazer a partir de qualquer objeto em qualquer pilha.
O aplicativo host determina o escopo de um gerenciador de desfazer. Por exemplo, em um aplicativo, o escopo pode estar no nível do documento; um gerenciador de desfazer separado é mantido para cada documento; e desfazer é gerenciado de forma independente para cada documento. No entanto, outro aplicativo mantém um gerenciador de desfazer e, portanto, um escopo de desfazer para todo o aplicativo.
Tratamento de erros
Ter uma operação de desfazer falha e deixar o documento em um estado instável é algo que o gerenciador de desfazer, desfazer unidades e o próprio aplicativo precisam trabalhar juntos para evitar. Como resultado, há determinados requisitos aos quais desfazer unidades, o gerenciador de desfazer e o aplicativo ou componente que usa desfazer devem estar em conformidade.
Para executar uma desfazer, o gerenciador de desfazer chama IOleUndoUnit::D o em uma ou mais unidades de desfazer que podem, por sua vez, conter mais unidades. Se uma unidade em algum lugar na hierarquia falhar, o erro atingirá o gerenciador de desfazer, que é responsável por fazer uma tentativa de reverter o estado do documento para o que era antes da chamada para a última unidade de nível superior. O gerenciador de desfazer executa a reversão chamando IOleUndoUnit::D o na unidade que foi adicionada à pilha de refazer durante a tentativa de desfazer. Se a reversão também falhar, o gerenciador de desfazer será forçado a abandonar tudo e retornar ao aplicativo. O gerenciador de desfazer indica se a reversão foi bem-sucedida e o aplicativo pode executar ações diferentes com base nisso, como reinicializar componentes para que eles estejam em um estado conhecido.
Todas as etapas na adição de uma unidade de desfazer à pilha devem ser executadas atomicamente. Ou seja, todas as etapas devem ter êxito ou nenhuma delas deve ter êxito.
O aplicativo host que fornece o gerenciador de desfazer decide qual ação tomar quando a desfaze falha. No mínimo, ele deve informar o usuário sobre a falha. O aplicativo host será informado pelo gerente de desfazer se o desfazer foi bem-sucedido e se a tentativa de reversão foi bem-sucedida. Caso o desfazer e a reversão falhem, o aplicativo host pode apresentar ao usuário várias opções, incluindo desligar imediatamente o aplicativo.
Unidades de desfazer simples não devem alterar o estado de nenhum objeto se retornarem falha. Isso inclui o estado da pilha de refazer ou desfazer pilha se estiver executando uma nova execução. Eles também são obrigados a colocar uma unidade correspondente na pilha de refazer ou desfazer se tiverem êxito. O aplicativo deve ser estável antes e depois que a unidade é chamada.
As unidades de desfazer pai têm os mesmos requisitos que unidades simples, com uma exceção. Se um ou mais filhos tiverem êxito antes da falha de outro filho, a unidade pai deverá confirmar sua unidade correspondente na pilha de refazer e retornar a falha ao pai. Se nenhum filho tiver êxito, a unidade pai deverá confirmar sua unidade de refazer somente se tiver feito uma alteração de estado que precise ser revertida. Por exemplo, suponha que uma unidade pai contenha três unidades simples. Os dois primeiros tiveram êxito e adicionaram unidades à pilha de refazer, mas a terceira falhou. Neste ponto, a unidade pai confirma sua unidade de refazer e retorna a falha.
Como efeito colateral, a unidade pai nunca deve fazer alterações de estado que dependam do sucesso de seus filhos. Isso fará com que o comportamento de reversão seja interrompido. Se uma unidade pai fizer alterações de estado, ela deverá fazê-las antes de chamar filhos. Em seguida, se a alteração de estado falhar, ela não deverá confirmar sua unidade de refazer, ela não deve chamar nenhum filho e deve retornar a falha para seu pai.
O gerenciador de desfazer tem um requisito principal para tratamento de erros: tentar reverter quando uma desfazer ou refazer falhar.
Objetos não compatíveis
Objetos que não dão suporte à desfaçamento de vários níveis podem causar sérios problemas para um serviço de desfazer global. Como o objeto não pode ser confiado para atualizar corretamente o gerenciador de desfazer, todas as unidades enviadas por outros objetos também são suspeitas, pois suas unidades podem depender do estado do objeto não compatível. A tentativa de desfazer as unidades de um objeto em conformidade pode não ser bem-sucedida, pois o estado no objeto não compatível não corresponderá.
Para detectar objetos que não dão suporte à desfazer de vários níveis, marcar para o valor OLEMISC_SUPPORTSMULTILEVELUNDO. Um objeto que pode participar do serviço de desfazer global define esse valor.
Quando um objeto sem esse valor é adicionado a um contexto de desfazer visível pelo usuário, a melhor prática é desabilitar a interface do usuário desfazer para esse contexto. Como alternativa, uma caixa de diálogo pode ser apresentada ao usuário, perguntando-lhe se deseja tentar fornecer suporte de desfazer parcialmente, trabalhando em torno da não conformidade do novo objeto.
Além disso, objetos não compatíveis podem ser adicionados a contêineres aninhados. Nesse caso, o contêiner aninhado precisa notificar o gerenciador de desfazer que não é mais possível desfazer com segurança chamando IOleUndoManager::Enable com FALSE.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | ocidl.h |