Support for Data Entry Windows

Support for Data Entry Windows

At any time, a window that is designed for data entry can be in one of several views (e.g. single record displayed, several records displayed), it can be in one of several processing modes (e.g. adding a new record, editing an existing record), the data in the window could have been modified, the data in the window might not satisfy data validation rules, and so on. Many such windows can be active at any time and, in a event driven interface where the user can move from one window to another at any time, the job of keeping track of what is happening within any specific window can be a big job. For example

1. the user could enter some new data in one window and then switch to another window. Then, the user could request that different data be displayed in the original window. The application must remember that the user was in the middle of entering a new record. It should immediately ask the user if the new data should be saved. If the user wants to save the data, the application must remember if any invalid data has been entered and if all required fields have been filled in.
2. in another situation, the user could be entering data for a new record and then request that the record be deleted. This must be detected as an invalid action (you cannot delete a record that has not been added).

These examples show that any window has a current “state”. Certain actions cause a change in the state. In some cases (situation 1 above), the transition from one state to another implies that other actions should be taken first (saving the data in our example). In other cases (such as 2), the transition is not valid.

Consider the Customers window in the example application (beginning with Simple Event Loop and Main Windows). In that implementation, the window state can be “Browse” (we are looking at data, can delete, but cannot update), “Edit” (we are looking at data, we can update the data, and we can delete records), and “New” (we are adding new records but cannot delete or change existing data). The window offers a “Form” view (only one database record is visible) and a “Table” view (many records are visible). The “Browse” state operates only in the “Table” view while the other two states operate only in “Form” view. The example application actually displays the state and view in the lower right corner of the window.

The choice of what states and views are possible and what names are used is entirely up to the application. However, the existence of these states is important because

• certain actions are not permitted in certain states and/or views. For example, we could decide that the “DELETE” action should not be permitted while in the “Browse” state.
  Note: In fact, DELETE is permitted in the Browse state in the Example Application, but this was an implementation choice.
• Some actions cause the state and/or view to change. In the Example Application, pressing the Browse button on the tool bar when the Customers window is in the “Edit” state causes the window to transform itself to the “Browse” state and the “Table” view.
• Certain operations can be associated with a change in state or view. Suppose that you are in the Customers window of the example application, that the window is in the “Edit” state, and that you have modified some data on the screen but have not saved it yet. If you were to click on the Browse button, you would want to be sure that the changes you made were saved first. Furthermore, you might want the saving to occur automatically. Or you might want the application to prompt you and give you a chance to either save the data, discard the changes, or cancel the operation (i.e. change your mind about going into the “Browse” state and stay in the “Edit” state).
• The Application Framework provides support for tracking the state of application windows and automating operations associated with state and view transitions through an entity set called ObjectAction in which valid states, views, and transitions are defined.
• The pValidateAction function, a Framework program, uses an application program’s current state and view, an action, and the ObjectAction EntitySet to determine if the action is valid and what the new state and view should be.
• Standard state/view entries to handle single table and header detail windows.

The Framework provides a mechanism for defining window states and valid transitions. It provides a program, pValidateAction, which determines if state transitions are valid and which can also invoke other actions (for example, the save action in our first example). This infrastructure greatly simplifies the code in programs that manage data entry windows.

These facilities provide a very general way to implement the specific rules of your application and are described in detail in the Reference Guide. However, before looking more closely at these facilities, let’s look at how they are used by the Example Application.

States and Views in the Example Application

All the data entry windows in the Example Application use the same states, views, and transitions. This is not surprising because if different windows used different state models, the application would be very difficult to use. The main application window does not use states and views at all since its only purpose is to enable the user to launch various windows.

The states and views used in the Example can be diagrammed as follows:

State/View Diagram for the Example Application

For each action that can occur in one of these states/views, ObjectAction defines if the action is valid, what the new state/view should be, and what operations should be done during the transitions. Let’s look at some examples for the “New” state.

• The SAVE action occurs when you click on the OK button. This, like all the other examples, is a valid action in the New state. The transition operation is Yes which indicates to the Framework that, if the on screen data has been modified, then the data should be saved automatically. The window re-enters the “new” state in the Form view.
• DISCARD occurs when you cancel changes using the Cancel button. Here, the transition operation is “No” meaning that the changes are discarded.
• The third entry is for the QUERY action which is generated when you select the Query button on the tool bar. The transition operation here is “PromptYes”. This indicates to the Framework that, if the on screen data has been modified, then the user should be prompted to see if he/she wants to save that data (the default button is Yes). If the user selects Yes, the data is added to the database. If the user selects No, the data is discarded, and if the user selects Cancel, the action is ignored. In the first cases (Yes or No), the window then enters the “Edit” state.
• BROWSE is similar except that the end state is “Browse”.
• The HELP action occurs when the user selects the Help button on the tool bar. This action is valid but leaves the user in the same state/view.
• Finally, EXIT occurs if the user closes the window, presses Ctrl+F4, etc. Like QUERY and BROWSE, this prompts the user if on screen data has been changed. There is no new state/view since the window is being closed.

In the above examples, there were several situations where modified data on the screen was to be saved or discarded. While the Framework determines if data should be saved or discarded, it cannot actually do the work (it has no idea what tables are being updated). Instead, pValidateAction (the program that interprets the ObjectAction EntitySet) pushes the action being validated onto the Message Queue and returns to the caller with the action name updated to either SAVE or DISCARD (unless a SAVE or DISCARD was being done anyway). The effect of this is that the process carries out the SAVE or DISCARD (instead of the original action), the next pGetAction finds the original action, and that is now passed to the process again. This time, however, the on screen data is saved or discarded and the action is acted on.

Validate Actions First

The above discussion shows that it is very important that programs using pValidateAction must call it immediately on entry before acting on the incoming action. This is required since the call to pValidateAction might actually change the action to SAVE or DISCARD.

ObjectAction Format

ObjectAction is an EntitySet defined in $DeployServices. Every Zim database has its own copy of ObjectAction. The main fields of ObjectAction are WindowTag, Action, State, View, ValidAction, NewState, NewView, SaveData, ValidCondition, Comment and ObjectActionOwner. ObjectAction is discussed in more detail in the Reference Guide.

Standard State/View Definitions

The Framework provides standard state and view definitions that are suitable for implementing many kinds of single table editing and header/detail type applications. In developing your own applications, you can choose to employ these state transitions or you can choose to implement your own. These standard entries are described in the Reference Guide.