Do not directly instantiate a VkMenuUndoManager object in your program. If you provide an undo callback to any menu item or if you use a subclass of VkAction or VkMenuActionObject in your program, ViewKit automatically creates an instance of VkMenuUndoManager named “Undo”. (“Command Classes” describes the VkAction and VkMenuActionObject classes.) The <Vk/VkMenuItem.h> header file provides theUndoManager, a global pointer to this instance. To access the ViewKit undo manager, simply use this global pointer.^[6]

You add the undo manager to a menu just as you would any other menu item: using the VkMenu::add() function of the menu object to which you want to add the undo manager. For example, the following line adds the undo manager to a menu pane specified by the variable edit:

edit->add(theUndoManager);

You cannot include the undo manager in a static menu description; however, you can add the undo manager to a statically-defined menu after creating the menu. To specify the position of the undo manager within the menu, include a position parameter when you add the undo manager. For example, the following line adds the undo manager to the top of a menu pane specified by the variable edit:

edit->add(theUndoManager, 0);

To add undo support for an undoable menu item (VkMenuAction and VkMenuToggle items), simply provide an undo callback function when you define the menu item. The undo callback function should reverse the effects of the item's action.

For example, the following static description describes a Cut menu item that executes the callback function cutCallback() when the user chooses the item and undoCutCallback() when the user undoes the command:

class EditWindow: public VkWindow {
  private:
    static VkMenuDesc editPane[];
    static void cutCallback(Widget, XtPointer, XtPointer);
    static void undoCutCallback(Widget, XtPointer, XtPointer);
    // ...
};
 
VkMenuDesc EditWindow::editPane[] = {
  { ACTION,   "Cut",   &EditWindow::cutCallback,
                               NULL,   NULL,   &EditWindow::undoCutCallback },
  { END }
};

You could do the same thing by adding the menu item dynamically:

class EditWindow: public VkWindow {
  private:
    static VkSubMenu *editMenu;
    static void cutCallback(Widget, XtPointer, XtPointer);
    static void undoCutCallback(Widget, XtPointer, XtPointer);
    // ...
};
 
EditWindow::EditWindow(char *name) : VkWindow(name)
{
  // ...
  editMenu->addAction("Cut", &EditWindow::cutCallback,
                      &EditWindow::undoCutCallback, this);
}

Sometimes you might want to provide undo support for an action not implemented as a menu item (for example, an action invoked by a pushbutton). ViewKit allows you to do this by adding the action directly to the undo stack using VkMenuUndoManager::add():

void add(const char *name,
         XtCallbackProc undoCallback,
         XtPointer clientData)

The name argument provides a name for the action to appear in the undo manager's menu item. The undoCallback argument must be an Xt-style callback function that the undo manager can call to undo the action. The undo manager passes the clientData argument to the undo callback function as client data when it invokes the callback. Following ViewKit conventions as described in “Using Xt Callbacks With Components”, you should pass the this pointer as client data so that the callback function can retrieve the pointer, cast it to the expected component type, and call a corresponding member function.

---

Note: add() simply adds an action to the undo stack; it does not “register” a permanent undo callback for an action. Once the undo stack is cleared, the undo information for that action is deleted. If you later perform the action again and you want to provide undo support for that action, you must use add() again to add the action to the undo stack.

---

Example 6-1 shows a simple example of adding an action to the undo stack. The MyComponent constructor creates a pushbutton as part of its widget hierarchy and registers actionCallback() as the button's activation callback function. actionCallback(), in addition to performing an action, adds undoActionCallback() to the undo stack.

MyComponent: public VkComponent {
 
  public:
    MyComponent(const char *, Widget);
    void actionCallback(Widget, XtPointer, XtPointer);
    void undoActionCallback(Widget, XtPointer, XtPointer);
    // ...
};
 
MyComponent::MyComponent(const char *, Widget parent)
{
  // ...
  Widget button = XmCreatePushButton(viewWidget, "button", NULL, 0);
  XtAddCallback(button, XmNactivateCallback,
                &MyWindow::actionCallback, (XtPointer) this);
  // ...
}
void MyComponent::actionCallback(Widget w, XtPointer clientData,
                                     XtPointer callData)
{
  // Perform action...
 
  theUndoManager->add("Action", &MyComponent::undoActionCallback, this);
}

The ViewKit classes that support command classes, VkAction and VkMenuActionObject, both require you to override the pure virtual function undoit(), which the undo manager calls to undo an action implemented as a command class. “Command Classes” describes how to use VkAction and VkMenuActionObject to implement command classes.

By default, VkMenuUndoManager provides multi-level undo support. The undo manager keeps commands on a stack. When the user undoes a command, the undo manager pops it from the stack, revealing the previously executed command. Once a user has undone at least one command, executing any new command clears the undo stack. Also, executing any undoable command clears the undo stack.

Supporting multi-level undo in your application can be difficult. If you prefer to support undoing only the last command executed, you can change the behavior of the undo manager with the VkMenuUndoManager::multiLevel() function:

void multiLevel(Boolean flag)

If flag is FALSE, the undo manager remembers only the last command executed.

You can force the undo manager to clear its command stack with the VkMenuUndoManager::reset() function:

void reset()

You can examine the contents of the undo manager's command stack using VkMenuUndoManager::historyList():

VkComponentList *historyList()

historyList() returns a list of objects representing commands that have been executed and are available to be undone. Commands are listed in order of execution; the last command executed is the last item in the list. All of the objects in the list are subclasses of VkMenuItem. Commands added directly to the undo stack (as described in “Providing Undo Support for Actions That Are Not Menu Items”) or commands implemented as VkAction objects (as described in “Command Classes”) appear as VkMenuActionStub objects. VkMenuActionStub is an empty subclass of VkMenuAction.

The label that the undo manager menu item displays is of the form Undo_label:Command_label. Undo_label is the value of the labelXmNlabelString resource of the undo manager. By default, this value is “Undo”. You can change this string (for example, for a German-language app-defaults file) by providing a different value for the XmNlabelString resource. For example, you could set the resource as follows:

*Undo.labelString:    Annul

Command_label is the label for the last executed command registered with the undo manager, determined as follows:

The syntax of the VkAction constructor is as follows:

VkAction(const char *name)

Each class derived from VkAction should provide a constructor that takes at least one argument: the object's name. All derived class constructors should pass the name to the VkAction constructor to initialize the basic class data members, and then initialize any subclass-specific data members.

The syntax of the VkMenuActionObject constructor is as follows:

VkMenuActionObject(const char *name, XtPointer clientData = NULL)

Each class derived from VkMenuActionObject should provide a constructor that takes two arguments: the object's name and optional client data. All derived class constructors should pass the name and the client data to the VkMenuActionObject constructor to initialize the basic class data members, and then initialize any subclass-specific data members.

The VkMenuActionObject constructor stores the client data in the protected data member _clientData:

void *_clientData

VkMenuActionObject objects do not use the _clientData data member for callback functions. Instead it is simply an untyped pointer that you can use to pass any information your command object might need. For example, you could pass a pointer to another object, a value, a string, or any other value. You can access and manipulate _clientData from member functions of your command subclass.

Both VkAction and VkMenuActionObject have two protected pure virtual functions that you must override—doit() and undoit():

virtual void doit()
virtual void undoit()

doit() performs the command class's action; undoit() undoes the action.

You can use command classes derived only from VkMenuActionObject in a ViewKit menu. Because VkAction is not derived from VkMenuItem, it does not provide the services required of a menu item.

You cannot specify VkMenuActionObject objects in a static menu description; you must add them dynamically using VkMenu::add(), which is described in “Functions for Dynamically Creating Menus”.

When a user chooses a VkMenuActionObject command object from a menu, ViewKit executes the command by calling the object's doit() function. ViewKit also automatically registers the command with the undo manager.

To activate a command object that is a subclass of VkAction, call that action's execute() member function:

void execute()

execute() calls the object's doit() function. execute() also registers the command with the undo manager.

---

Note: Do not call a command object's doit() function directly. If you do, ViewKit cannot register the command with the undo manager.

---

You can set the label of a VkMenuActionObject command object as you would any other VkMenuItem item: by setting the object's XmNlabelString resource or by calling the object's setLabel() function. “Setting Menu Item Labels” describes how to set the label for a menu item.

Because VkAction objects are command classes and not interface classes, they technically do not have labels; however, the undo manager requires a label that it can display after you have executed a VkAction command. Therefore, ViewKit allows you to set the value of a labelString resource for VkAction objects, qualified by the object's name. For example, if you have an instance of a VkAction named “formatPara,” you can set the label for this object by providing a value for the formatPara.labelString resource:

*formatPara:    Format Paragraph

If you do not provide a value for a VkAction object's labelString resource, the undo manager uses the object's name as the label.

---

Note: The VkAction labelString resource is a “synthetic” resource, not a widget resource. The only way that you can set the value of this resource is through a resource file. You can't use XtSetValues() because the object contains no widgets, and you can't use setDefaultResources() because VkAction is not a subclass of VkComponent.

---