| Search Locate Previous Next | Contents |
Each object you add to your base form (except for trivial things like <OK> buttons) can watch and possibly update one or more APL variables. For example, a Text Edit object would normally watch a simple text vector. Any changes you made to the visible field on the screen would be reflected back into your variable as soon as the user left the field (with the Tab key or by pressing a button on the form).
Runtime and User Properties
Almost all objects make use of these property types, which are shown on the property browser as buttons with blue or green labels. The designer picks up the prompt from the object definition, so you usually have some idea what the object expects to see here! When the object can modify data in some way (e.g. a Scrolling List can change the selection) this is the variable that gets changed. Here is a simple example where a text field updates a value indexed from a vector of text vectors:
The expression may be a simple variable name, or any expression which is valid to the left of an assignment. You should imagine wrapping a pair of parentheses around the data expression and adding an assignment arrow like this:
(name)„
(inxœnames)„
(msk/names)„
(names[inx])„
('Your name is ',name)„... this is what Causeway will do to get the user’s changes reflected back to your data. Essentially anything involving indexing is fine, as are all valid selective specifications. The last example is fine for a label, but will fail on a SYNTAX ERROR if the user touches it in a text field. To help you see what is going on here, the lower field shows you the reversed expression that will be used. You can even modify this if you need to, using ¾ as illustrated to act as a placeholder for the data that will be read from the control.
Note that you may double-click on any variable (or function) name mentioned in this field to open an edit window on the object.
Dependencies (Refresh on a Change to) ...
The object must refresh its display when any variables named in this list change, or when the name is broadcast by an entry in the ‘Event-Action’ table following the execution of some APL code. The name is often just a repeat of the primary data, but remember that this can be any APL expression, so you always need to specify it explicitly. If you simply tab into this field, the Designer will take a reasonable guess and fill it in for you.
In our example, we could illustrate the effect by running up the finished form:
#.CPro.Make dbx.rec © Start the form running eyes„2 © Change some data #.CPro.Notify 'eyes' © Tell Causeway
Of course another way would be to make several copies of the form ...
#.CPro.Make ¨3½›dbx_rec © Start 3 copies
... change the data on any one and the other two should immediately change to match. Of course you will have to move the forms so that you can see them all at the same time.
Note that this need not be the name of a real variable. If you holler ‘hi’ from an action, all the fields which watch for a change to ‘hi’ get refreshed regardless of what they are displaying – this can be a useful shortcut to getting everything redone after a <Recalc> operation.
Forcing Causeway to Redraw the Control
To save time (and reduce screen flicker), Causeway will avoid redrawing controls if the data expression evaluates to exactly the same value as it did the last time the control was refreshed. This means that Causeway will buffer the old value and compare it with the new value every time a refresh is required – it may sometimes be better just to accept the redraw, thus saving on workspace. Also there are times when you want to force a redraw, for example if you are using unnamed graphic objects.
To prevent Causeway making the comparison with the previous value, check the ‘Always refresh ...’ box below the data expression.
Pre-Refresh, Validation and Post-Update Events
There are three places where your application code can step in during the automatic processing sequence which CPro runs for every control on a form.
Pre-Refresh Processing
This is most often used to run some application code which collects data into a format suitable for a specialised control. For example a Tree Control requires a two-column matrix of items and levels – you may store your data in a parent-child structure which requires reformatting before it is suitable. In this case you might set the watched variable as (say) datatree and your pre-refresh code would look like:
PR : : datatree„#.MakeTree ‘parent ‘child :
Note that CPro will always run the Pre-Refresh actions, but you can prevent the actual data-expression from executing by specifying ’Reject here. If the result of executing the data expression matches the previous field content, CPro will normally skip the redraw to save time and flicker. Very occasionally you need to force the refresh (typically for a chart where the PostScript definition may be unchanged but the window size may have changed) – you can over-ride the CPro caching by checking the ‘Forced refresh’ box under the expression definition.
Validating Data
This is catered for by a special Validate event which is triggered after your data has been read from the object, but before it is assigned back into the associated variable. The data is available for inspection as ¾ (omega), and there are two possibilities here. You can modify the data in passing:
VL: :¾„0—99˜¾ © Force range
... or you can check it and reject the event if it fails:
VL: ¾<100 : ’Reject © Bounce if >99
In the latter case, no assignment takes place, the variable name is not notified (so no other dependent controls will be updated), and the object is immediately refreshed with the original value.
Post-Update Processing
This may be used to trigger ‘knock-on’ processing, such as a background database update, or simply to reverse the effect of a pre-refresh by disassembling the data returned from the control into a more application-friendly format:
PU : : (‘parent ‘child)„#.ParseTree datatree :
N.B. The Post-Update only runs after the user has changed the data. When the control is updated by CPro, only the PreRefresh event will be fired. You can use ‘Refresh Completed’ in the main table of object behaviours if you need to do additional processing here.