Interface IOleUndoManager (ocidl.h)

L’interface IOleUndoManager permet aux conteneurs d’implémenter des opérations d’annulation et de restauration à plusieurs niveaux pour les actions qui se produisent dans des contrôles autonomes.

Héritage

L’interface IOleUndoManager hérite de l’interface IUnknown. IOleUndoManager a également les types de membres suivants :

Méthodes

L’interface IOleUndoManager contient ces méthodes.

Remarques

Le contrôle doit créer une unité d’annulation avec l’interface IOleUndoUnit ou une unité d’annulation parente avec l’interface IOleParentUndoUnit dérivée de IOleUndoUnit. Ces deux interfaces effectuent l’action d’annulation et l’unité d’annulation parente peut en outre contenir des unités d’annulation imbriquées.

Le gestionnaire d’annulation fournit un service d’annulation et de restauration centralisée. Il gère les unités d’annulation parentes et les unités d’annulation simples sur les piles d’annulation et de restauration. Qu’un objet soit actif ou non, il peut déposer des unités d’annulation sur ces piles en appelant des méthodes dans le gestionnaire d’annulation.

Le gestionnaire d’annulation centralisé dispose alors des données nécessaires pour prendre en charge l’interface utilisateur d’annulation et de restauration pour l’application hôte et peut ignorer progressivement les informations d’annulation à mesure que la pile devient pleine.

Le gestionnaire d’annulation est implémenté en tant que service et les objets obtiennent un pointeur vers IOleUndoManger à partir de l’interface IServiceProvider . Il est généralement implémenté par le conteneur. Le service gère deux piles, la pile d’annulation et la pile de restauration, chacune contenant des unités d’annulation générées par des objets incorporés ou par l’application conteneur elle-même.

Les unités d’annulation sont généralement générées en réponse aux actions effectuées par l’utilisateur final. Un objet ne génère pas d’actions d’annulation pour les événements programmatiques. En fait, les événements programmatiques doivent effacer la pile d’annulation, car l’événement programmatique peut éventuellement invalider les hypothèses faites par les unités d’annulation sur la pile.

Lorsque l’état de l’objet change, il crée une unité d’annulation encapsulant toutes les informations nécessaires pour annuler cette modification. L’objet appelle des méthodes dans le gestionnaire d’annulation pour placer ses unités d’annulation sur la pile. Ensuite, lorsque l’utilisateur final sélectionne une opération Annuler, le gestionnaire d’annulation retire l’unité d’annulation supérieure de la pile, appelle son action en appelant sa méthode IOleUndoUnit ::D o, puis la libère. Lorsqu’un utilisateur final sélectionne une opération Redo, le gestionnaire d’annulation retire l’unité de restauration en haut de la pile, appelle son action en appelant sa méthode IOleUndoUnit ::D o, puis la libère.

Le gestionnaire d’annulation a trois états : l’état de base, l’état d’annulation et l’état de rétablissement. Il commence à l’état de base. Pour effectuer une action à partir de la pile d’annulation, elle se met à l’état d’annulation, appelle IOleUndoUnit ::D o sur l’unité d’annulation et retourne à l’état de base. Pour effectuer une action à partir de la pile de restauration automatique, elle se met à l’état redo, appelle IOleUndoUnit ::D o sur l’unité d’annulation et retourne à l’état de base.

Si le gestionnaire d’annulation reçoit une nouvelle unité d’annulation alors qu’il est dans l’état de base, il place l’unité sur la pile d’annulation et ignore l’ensemble de la pile de rétablissement. Alors qu’il est à l’état d’annulation, il place les unités entrantes sur la pile de restauration. Alors qu’il est à l’état redo, il les place sur la pile d’annulation sans vider la pile de restauration.

Le gestionnaire d’annulation permet également aux objets d’ignorer la pile d’annulation ou de restauration à partir de n’importe quel objet de l’une ou l’autre pile.

L’application hôte détermine l’étendue d’un gestionnaire d’annulation. Par exemple, dans une application, l’étendue peut se trouver au niveau du document ; un gestionnaire d’annulation distinct est conservé pour chaque document ; et undo est géré indépendamment pour chaque document. Toutefois, une autre application conserve un gestionnaire d’annulation, et donc une étendue d’annulation, pour l’ensemble de l’application.

Gestion des erreurs

L’échec d’une opération d’annulation et le fait de laisser le document dans un état instable est quelque chose que le gestionnaire d’annulation, les unités d’annulation et l’application elle-même doivent tous travailler ensemble pour éviter. Par conséquent, il existe certaines exigences auxquelles les unités d’annulation, le gestionnaire d’annulation et l’application ou le composant utilisant undo doivent se conformer.

Pour effectuer une annulation, le gestionnaire d’annulation appelle IOleUndoUnit ::D o sur une ou plusieurs unités d’annulation qui peuvent, à leur tour, contenir plus d’unités. Si une unité quelque part dans la hiérarchie échoue, l’erreur finit par atteindre le gestionnaire d’annulation, qui est chargé d’effectuer une tentative de restauration de l’état du document par rapport à ce qu’il était avant l’appel à la dernière unité de niveau supérieur. Le gestionnaire d’annulation effectue la restauration en appelant IOleUndoUnit ::D o sur l’unité qui a été ajoutée à la pile de restauration lors de la tentative d’annulation. Si la restauration échoue également, le gestionnaire d’annulation est obligé de tout abandonner et de revenir à l’application. Le gestionnaire d’annulation indique si la restauration a réussi, et l’application peut effectuer différentes actions en fonction de cela, telles que la réinitialisation des composants afin qu’ils soient dans un état connu.

Toutes les étapes d’ajout d’une unité d’annulation à la pile doivent être effectuées de manière atomique. Autrement dit, toutes les étapes doivent réussir ou aucune d’entre elles ne doit réussir.

L’application hôte qui fournit le gestionnaire d’annulation décide de l’action à entreprendre en cas d’échec de l’annulation. À tout le moins, il doit informer l’utilisateur de la défaillance. Le gestionnaire d’annulation indique à l’application hôte si l’annulation a réussi et si la tentative de restauration a réussi. En cas d’échec de l’annulation et de la restauration, l’application hôte peut présenter à l’utilisateur plusieurs options, notamment l’arrêt immédiat de l’application.

Les unités d’annulation simples ne doivent pas modifier l’état d’un objet si elles retournent un échec. Cela inclut l’état de la pile de restauration ou de la pile d’annulation si vous effectuez un rétablissement. Ils doivent également placer une unité correspondante sur la pile de restauration ou d’annulation s’ils réussissent. L’application doit être stable avant et après l’appel de l’unité.

Les unités d’annulation parentes ont les mêmes exigences que les unités simples, à une exception près. Si un ou plusieurs enfants ont réussi avant la défaillance d’un autre enfant, l’unité parente doit valider son unité correspondante sur la pile de restauration et renvoyer l’échec à son parent. Si aucun enfant n’a réussi, l’unité parente doit valider son unité de restauration automatique uniquement si elle a apporté une modification d’état qui doit être restaurée. Par exemple, supposons qu’une unité parente contient trois unités simples. Les deux premiers réussissent et ont ajouté des unités à la pile de restauration automatique, mais la troisième a échoué. À ce stade, l’unité parente valide son unité de restauration et retourne l’échec.

Comme effet secondaire, l’unité parente ne doit jamais apporter de modifications d’état qui dépendent de la réussite de ses enfants. Cela entraîne l’interruption du comportement de restauration. Si une unité parente apporte des modifications d’état, elle doit les faire avant d’appeler des enfants. Ensuite, si le changement d’état échoue, il ne doit pas valider son unité de rétablissement, il ne doit pas appeler d’enfants et il doit renvoyer l’échec à son parent.

Le gestionnaire d’annulation a une exigence principale pour la gestion des erreurs : tenter de restaurer en cas d’échec d’une annulation ou d’une restauration.

Objets non conformes

Les objets qui ne prennent pas en charge l’annulation à plusieurs niveaux peuvent causer de graves problèmes pour un service d’annulation global. Étant donné que l’objet ne peut pas être utilisé pour mettre à jour correctement le gestionnaire d’annulation, toutes les unités soumises par d’autres objets sont également suspectes, car leurs unités peuvent s’appuyer sur l’état de l’objet non conforme. La tentative d’annulation des unités d’un objet conforme peut ne pas aboutir, car l’état de l’objet non conforme ne correspond pas.

Pour détecter les objets qui ne prennent pas en charge l’annulation à plusieurs niveaux, case activée pour la valeur OLEMISC_SUPPORTSMULTILEVELUNDO. Un objet qui peut participer au service d’annulation global définit cette valeur.

Lorsqu’un objet sans cette valeur est ajouté à un contexte d’annulation visible par l’utilisateur, la meilleure pratique consiste à désactiver l’interface utilisateur d’annulation pour ce contexte. Une boîte de dialogue peut également être présentée à l’utilisateur, lui demandant s’il faut tenter de fournir une prise en charge partielle de l’annulation, en contourne la non-conformité du nouvel objet.

En outre, des objets non conformes peuvent être ajoutés aux conteneurs imbriqués. Dans ce cas, le conteneur imbriqué doit informer le gestionnaire d’annulation que l’annulation ne peut plus être prise en charge en toute sécurité en appelant IOleUndoManager ::Enable with FALSE.

Configuration requise

Voir aussi

IOleParentUndoUnit

IOleUndoUnit