This document covers the following topics:
This section describes the process of editing item labels for both tree view and list view controls. The word "item" is therefore used throughout, in place of "tree view item" and "list view item", respectively.
The editing of an item's label, unless prohibited (see below), may be initiated in one of three ways:
By the user, by clicking on the label of a selected item.
By the user, by pressing the F2 key (whereupon the item with the focus rectangle, if any, is edited).
By the program, by calling the
EDIT-LABEL
action.
Regardless of the means of initiation, the sequence of actions taken by Natural in response is identical:
The control's MODIFIABLE
attribute is examined. If this is FALSE (e.g., the
Modifiable option was not checked in the control's
attributes window), no further action occurs and label editing mode is not
entered.
The control's ITEM
attribute is set to the handle of the item for which label editing was
requested (the "target" item).
Unless suppressed, a
BEFORE-EDIT
event is raised for the control.
The target item's MODIFIABLE
attribute is examined. If this is FALSE, no further action occurs
and label editing mode is not entered.
Label editing mode is entered. The user may cancel any changes he has made via the ESC key. In this case, the original label is restored, edit mode exited, and no further action taken. Alternatively, the user can commit the changes (e.g. by pressing the ENTER key or setting the focus to another window or control).
The target item's STRING
attribute is updated with the new label text.
Unless suppressed, an
AFTER-EDIT
event is raised for the control.
If the item's label is no longer identical to the item's
STRING
attribute (i.e., the application modified the attribute during the
AFTER-EDIT
event), the item's label is updated accordingly.
The purpose of the
BEFORE-EDIT
event is twofold. Firstly, it allows the application to dynamically set the
item's MODIFIABLE
attribute (thus allowing or preventing label editing from taking place)
according to the particular context. Secondly, it gives the application a
chance to save the original label in case it wishes to restore it later in the
AFTER-EDIT
event.
The AFTER-EDIT
event has four options:
Do nothing, which case the new item label will be accepted.
Reject the new label, by restoring the previous value for the item's
STRING
attribute (as saved in the
BEFORE-EDIT
event).
Reject the new label, by setting the the item's
STRING
attribute to some other value that neither matches the new nor old label (e.g.
silently "correcting" the label entered by the user).
Re-enter edit mode for the item, forcing the user to modify the label again (possibly after displaying a message box to inform the user that the newly entered label is invalid).
As an example demonstrating some of the above topics, consider the following example. Firstly, we define some local data variables which we will need later:
01 #CONTROL HANDLE OF GUI 01 #ITEM HANDLE OF GUI 01 #LABEL (A) DYNAMIC 01 #POS (I4)
Having done this, we can can write a trivial
BEFORE-EDIT
event, where we simply save the existing label of the item about to be edited
in the dynamic variable #LABEL:
#CONTROL := *CONTROL #ITEM := #CONTROL.ITEM #LABEL := #ITEM.STRING
To illustrate a few of the above techniques, we use the following
AFTER-EDIT
handler:
#CONTROL := *CONTROL #ITEM := #CONTROL.ITEM IF #ITEM.STRING = ' ' #ITEM.STRING := #LABEL ELSE EXAMINE #ITEM.STRING TRANSLATE INTO LOWER EXAMINE #ITEM.STRING FOR ' ' GIVING POSITION #POS IF #POS > 0 PROCESS GUI ACTION CALL-DIALOG WITH #DLG$WINDOW #ITEM 'EDIT-LABEL' FALSE END-IF END-IF
The above code performs the following actions:
If the new item label consists only of blank, the old item label, as
saved in the BEFORE-EDIT
event is restored.
Otherwise, the new item label is converted into lower case (EXAMINE
TRANSLATE).
Then, if the new item label contains a blank, we treat the data as invalid and raise an asynchronous user-defined event for the item in order to request corrected data from the user (more later).
The asynchronous event allows an invalid item label to be provisionally
accepted. However, on receipt of the user-defined EDIT-LABEL
event, we display a message box to inform the user that the data is invalid and
in need of correction, then re-enter label editing mode. This is done via the
following code in the DEFAULT event
handler for the dialog:
IF *EVENT = 'EDIT-LABEL' #ITEM := *CONTROL OPEN DIALOG NGU-MESSAGEBOX USING #ITEM.PARENT WITH #BUTTON 'Invalid data - please re-enter' 'Label Edit' '!O' PROCESS GUI ACTION EDIT-LABEL WITH #ITEM GIVING *ERROR END-IF
If it is sufficient to set an edit mask and/or maximum label length in
characters, and/or specify that only upper case characters should be allowed,
this can be achieved without any coding by setting the
EDIT-MASK
attribute, LENGTH
attribute or "Upper case (U)"
STYLE flag
(respectively) for the appropriate item(s). If an edit mask is specified,
Natural automatically restores the old label, issuing a beep (if enabled), if
the entered label does not match the mask.
An item's label may be set directly via its
STRING
attribute. For example:
#ITEM.STRING := New label'
where #ITEM is the handle of the corresponding tree view or
list view item.
In this case, only the item's edit mask (if any) is used. All other aspects of label editing described above do not apply here. In particular:
The label is changed regardless of the value of the
MODIFIABLE
attribute for the control and the item.
No BEFORE-EDIT
or AFTER-EDIT
events are raised.
The control's ITEM
attribute is not set.
The text is not automatically translated to upper case if the item's
"Upper case (U)"
STYLE flag
is set.
The supplied label can exceed the limit (if any) imposed by the item's
LENGTH
attribute.
