AppBuilder Undo Mechanism
Beta Draft
Author: (Author's Name)
Date Last Updated: (Date)
Scheduled Release: (Release Number)


Revision History The following revisions have been made to this document:

Date: (date)
Revision: (rev-no)
Developer: (developer)
Summary of Changes: (summary)


Copyright © 2000 by Progress Software Corporation ("PSC"), 14 Oak Park, Bedford, MA 01730, and other contributors as listed below. All Rights Reserved.

The Initial Developer of the Original Code is PSC. The Original Code is Progress IDE code released to open source December 1, 2000.

The contents of this file are subject to the Possenet Public License Version 1.0 (the "License"); you may not use this file except in compliance with the License. A copy of the License is available as of the date of this notice at http://www.possenet.org/license.html

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. You should refer to the License for the specific language governing rights and limitations under the License.


Contributors
Jane Contributor, Joe Contributor


Contents

1. Overview
2. Architecture
3. Primary Data Structures
4. Primary Algorithms and Processes
5. Advanced Topics
6. Dependencies
7. Source Files
8. Build Process and Requirements
9. Execution Methods
10. Test Requirements and Strategies
11. Supplementary Information
12. Related Documentation

1 Overview

AppBuilder provides a mechanism to allow certain actions performed on a file to be undone, such as the deleting, moving, and resizing of objects. This document describes the undo mechanism and its implementation.

2 Architecture

The undo mechanism is achieved mainly through the ordered retrieval of “action” records. AppBuilder maintains an internal temp-table called _action that stores the sequences of actions that are performed on objects while working with them in AppBuilder. Whenever a recognized action occurs on an object, AppBuilder creates an _action record to denote the START of the action. This is followed by the addition of one or more _action records for each object to which the action is applicable. Finally, a new _action record that denotes the END of the action is created.

When the user performs an undo, the _action records between the START record and the END record are deleted from the _action temp-table after the action is undone. Relevant information is stored in the _data field in character form for use when the undo occurs. When the END action record is created, the _data field of this record contains the _seq-num of the START action record. This is maintained for performance reasons.

The following table lists the recognized actions:

Action

Description

Delete

A widget or group of widgets is selected and deleted using the DELETE key or the Edit>Delete menu item.

Move

A widget or group of widgets is selected and moved within the same window using the mouse.

Resize

A widget is selected and resized using the mouse.

Align

A widget or group of widgets is selected and aligned using one of the centering or spacing options on the Layout menu, or any of the options on the Layout>Align submenu.

TapIt

A widget or group of widgets is adjusted (moved) using the keyboard directional (arrow) keys. NOTE: Once a TapIt action is started for a particular widget or widget group, all adjustments that are made are grouped into a single action until a new action is started.

When an “undoable” action is started, the Edit>Undo menu item on AppBuilder’s main menu is enabled and the specified action name is appended to the menu item’s label. For example, if a widget is selected and then resized, the menu item would read “Edit>Undo Resize” and it would be enabled. Choosing Edit>Undo Resize would cause the most recent resizing of a widget to be undone using the mechanism described above.

3 Primary Data Structures

The main data structure used by the undo mechanism is the _action temp-table. The _action temp-table is used by the undo mechanism to implement a stack that records the sequence of events (of recognized actions) as they occur in an AppBuilder session. The _action temp-table consists of the following fields:

Field

Data Type

Description

_seq-num

Integer

Used to maintain the order in which the actions occur.

_u-recid

Recid

The recid of the primary object (_U) to which the action applies.

_window-handle

Widget-handle

The handle of the window to which the object is parented.

_operation

Character

Identifies the action (e.g., “StartMove, Align, EndDelete”).

_data

Character

Information that is needed in order to perform the associated action (e.g., an object’s coordinates before it was moved).

_other_Ls

Character

If there are Alternate Layouts defined for the object, this field will contain a comma-separated list of the recids for the associated layout records (_L) so that the other layouts will also reflect the change.

4 Primary Algorithms and Processes

See section 2 “Architecture” for a description of the primary functions of the undo mechanism.

5 Advanced Topics

Not applicable at this time.

6 Dependencies

AppBuilder uses the undo mechanism exclusively.

7 Source Files

The following table lists the primary source files used to implement this feature:

Source File

Description

adeuib/_undo.p

Locate the last undoable action in the _action temp-table and perform the associated undo operation.

adeuib/_undo.i

Definitions for _action temp-table and other shared variables used to manage the undo operations.

adeuib/_undmov.p

Undo a move or tapit action (called by _undo.p).

adeuib/_undsiz.p

Undo a resize action (called by _undo.p).

adeuib/_align.p

Performs widget alignment tasks and creates the _action records necessary to undo the operations.

adeuib/_uibmproa.i

Contains the code to perform widget deletion; creates the _action records necessary to undo the operation.

adeuib/_uibmproe.i

Contains the code to perform widget move, resize, and tapit tasks; creates the _action records necessary to undo the operations.

adeuib/_uibmundo.i

Contains the code to purge the _action records when AppBuilder is shut down or when there is an error.

adeuib/_undbutt.p

Undo the deletion of a button (called by _undo.p).

adeuib/_undcomb.p

Undo the deletion of a combo-box (called by _undo.p).

adeuib/_undedit.p

Undo the deletion of an editor widget (called by _undo.p).

adeuib/_undrect.p

Undo the deletion of a rectangle (called by _undo.p).

adeuib/_undimag.p

Undo the deletion of an image (called by _undo.p).

adeuib/_undqry.p

Undo the deletion of a query (called by _undo.p).

adeuib/_undslid.p

Undo the deletion of a slider (called by _undo.p).

adeuib/_undtext.p

Undo the deletion of a text widget (called by _undo.p).

adeuib/_undsele.p

Undo the deletion of a selection-list (called by _undo.p).

adeuib/_undfill.p

Undo the deletion of a fill-in (called by _undo.p).

adeuib/_undtogg.p

Undo the deletion of a toggle-box (called by _undo.p).

adeuib/_undradi.p

Undo the deletion of a radio-set (called by _undo.p).

adeuib/_undfram.p

Undo the deletion of a frame (called by _undo.p).

adeuib/_undbrow.p

Undo the deletion of a browse (called by _undo.p).

adeuib/_undcont.p

Undo the deletion of an OCX control (called by _undo.p).

adeuib/_undsmar.p

Undo the deletion of a SmartObject (called by _undo.p).

adeuib/_undmenu.p

Undo the deletion of a menu (called by _undo.p).

8 Build Process and Requirements

The undo mechanism is not a stand-alone module; it is an integral part of the AppBuilder tool.

9 Execution Methods

The undo mechanism is automatically invoked whenever the specific actions described above are performed.

10 Test Requirements and Strategies

Both individual widgets and groups of widgets should be tested to ensure that actions are undone accordingly on all selected widgets.

11 Supplementary Information

Not applicable at this time.

12 Related Documentation

Not applicable at this time.