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

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.

Action

Valid?

New State/View

Transition Operation

SAVE

Yes

New/Form

Yes

DISCARD

Yes

New/Form

No

QUERY

Yes

Edit/Form

PromptYes

BROWSE

Yes

Browse/Table

PromptYes

HELP

Yes

New/Form

 

EXIT

Yes

 

PromptYes

 

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.