Editing Dialog Elements |
Top Previous Next |
The Edit Dialog Element dialog is shown when adding or editing elements from the Edit Dialog Definition function.
Here you edit all of the components of a Dialog Element. This one dialog is used for all types of elements, even though different information is needed for each type. To help avoid confusion, it will only show the fields that apply to the element type that's currently chosen. Choosing a different Element Type will completely change most of the fields available on the dialog.
The common fields available to all elements are described first, followed by the type-specific fields for each element.
Element Type
Select the type of element you want to add. The dialog elements fall into several different categories:
Add a New Control -- This adds a new "control" to the dialog, such as an entry field, text, checkbox, selection list, etc. Naturally the control is only added once, when the dialog is created, but any Action expressions in the elements are still active as long as the dialog is open.
Modify a control -- Elements can be used to rename, move, re-size or hide an existing control. These can only be done for standard controls on the dialog, not new controls that you add. Multiple elements can act on the same control, e.g. you can rename, move, and re-size the same control using 3 different elements. These elements are executed only once, when the dialog is created.
Action on input -- Data-entry types of controls can trigger an action when something is changed (when the text is changed, a box checked, etc). You can define an expression to be executed when the action is triggered, e.g. to do something when a button is clicked, or auto-format text as it's entered. This element can only be added for standard controls, since the Add New Control element already contains an Action expression for new controls. Any action elements stay active for the duration of the dialog.
Action on focus change -- This can be used to trigger an expression when a control gains or loses input focus (e.g. due to a mouse click or Tab to the next control). These elements can be defined for either standard controls or for new controls you add.
Action on data saved -- This element is triggered when data is saved to the record being edited. This is usually done when "Save" is clicked on the dialog, but other things can trigger it too. This element can be used to do special validation of the data, for instance.
Action on dialog initialization -- This element is triggered when the dialog is being initialized. You can use this element to perform any other actions you want to when opening the dialog. Note that this is only executed once, not for each record change (e.g. if changing records in Reservation Details), so the record context is not necessarily useful. For instance It could be used to do initial validations, modify controls, or show messages.
Condition
This optional expression determines whether or not the element is used, and must return a True or False boolean value. To edit the condition expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression.
If the condition returns False, then the element is considered non-existent -- if it's for a New Control element, then the control won't be added. If it's for an element that modifies other controls, the modification won't take place. And if it's for an action type of element, then the action will not take place.
Note that for action elements, this condition is checked only when the dialog is first created, not each time there's a possible trigger, so a condition based on changes in the dialog cannot be checked here. If you want the element to only execute an action if certain changeable conditions are satisfied at the time of the input or focus trigger, then you need to check these conditions within the Action expression.
Notes
These notes are for your reference, and will also appear in the list of elements. We recommend putting notes in especially for action type elements if the expression isn't obvious, but it's a good idea for any element that's not obvious so you can tell what's going on if you need to edit the Dialog later.
Context Available in Dialogs
There are some special considerations for the expression context in dialog definitions.
In most cases, the ThisRecord( ) context is obvious, e.g. it's the Site for a Site Details add-on, the Customer for Customer Details, etc. Likewise, in Reservation Details, you have the obvious ThisResv( ) context and also a corresponding ThisSite( ) and ThisCust( ) available.
For dialogs that aren't add-ons, the This( ) record is defined when you call DlgOpenUserDialog( ) to open it. In addition, any existing context would be inherited from the expression or script that it's being called from -- for instance, if you create a custom dialog that's called from a right-click menu function on a query or tab view, you have access to all of the query's context such as ThisListCount( ) and ThisListRec( ) for the list of records in the query, as well as ThisFromDate( ) and ThisToDate( ) for the dates selected in the query.
Note that in the case of Site Details, Customer Details, etc., while you do have the record context available, it's not guaranteed to be a real record in the database. For instance, when editing a customer, it will just be a temporary record except during the Action on Data Saved expression. So be careful not to assume that setting values in the record will stick (other than in the Action on Data Saved), or that the record itself will be saved (e.g. if they click Cancel when adding a new customer).
Additional context is available for add-on definitions for New Reservation / Assign Site. The context list accessed by ThisListRec( ) and ThisListCount( ) will have the list of sites currently selected. Also in New Reservation / Assign Site, when saving data (BeforeSaveAction), This( ) will be the Customer if creating a New Reservation, or it will be the Reservation if Assigning a Site. There is also a special function ThisTempRec( ), which will be a temporary reservation record with the current preferences selected, so you can act on the current selections before the reservation is saved.
In a New Reservation dialog add-on, if multiple reservations are created (multiple sites selected), then the OK/Save Expression for any controls will be executed for each reservation created, with the appropriate Resv(), Site() and Cust() context of the real, created reservation. This allows any fields to be saved to each reservation. (If they are Customer fields, it will probably set the value to the same customer multiple times but that should have no adverse effects.) Just be careful about doing things in the expression that should not happen more than once. However, if you added an "Action on data saved" element, that element's Action expression will still only be executed once. The context Resv() for that expression will be the "primary" reservation (the first site added).
In the Point of Sale Entry dialog, the Resv( ) and Cust( ) context may be available if a reservation or customer have been selected.
"Add New Control" Elements
New control elements are used to add new data to a dialog, either to show the value or to allow the user to change a value. You can also add your own buttons to the dialogs, perhaps to perform special functions or to open a new dialog for entering a lot more information.
Control Name
This is a name to be used for the control internally, but is not the text shown for the control. A control name should be unique within the dialog definition, so that it can be referenced in expressions (e.g. to set or save the field's value) and referenced in other dialog elements. It may also help to indicate the type of control in the name for easy reference. Typical control names might be "EmailButton", "LastNameEntry", "LastNameLabel", "SiteDirtyCheckbox", etc. Using multiple words without spaces like this also serves as a reminder that the Control Name is not the text that gets displayed, but if you prefer to use spaces then you may do so.
Note that the names may be case sensitive when referenced (e.g. "ButtonA" is not the same as "buttona"), though this is not guaranteed. It's good practice to always assume the case must match.
Control Type
Select the type of control from the list. Naturally the type of control determines what's shown on the dialog as well as what it can do, how it acts, what kind of action it triggers, etc., so familiarity with Windows controls is helpful. A brief description of each is given below.
•Static text - Simple text (not editable), which will wrap as needed within the control's size
•Edit text - A single line text input field
•Edit text multi-line - A multi-line text input field (but the Tab key goes to the next control)
•Edit text multi-line w/Tab key - A multi-line text input field, with Tab key support
•Edit text, Read-only - Similar to static, but has a box around it like an edit field
•Edit text multi-line, Read-only - Same as above, for multiple lines.
•Button - A clickable button with text in it.
•Check box - A square checkbox input field for yes/no or true/false values
•Radio button - A round check-button field for multiple-choice input values
•Date selection - A date input field with a drop-down calendar selection
•Date selection with checkbox - A date field that has a checkbox (unchecked = no date selected)
•Time selection - A time entry field, with up/down buttons
•List box - A multi-line list of items to choose from
•Drop-down list box - A list of items to choose from, in drop-down form
•Combo list box - Similar to a drop-down list, but any text can also be entered
Start of a group
This is generally only important when Radio button controls are added, since a set of radio buttons must be in a "group" to act properly. In particular, when one radio button of a group is checked, it will automatically uncheck any others in the group. Also, it allows the arrow keys to be used to select which item in the group is checked, and the Tab key will move on to the next control outside the group.
Every new control has this option checked by default. When adding radio buttons for a multiple-choice option, you should uncheck this for each button except for the first one. It's also important that the next control in the dialog element list does have this option checked, so that it knows a new group (not part of the radio group) is starting.
Left & Top position
Specify the upper left corner position of the control, in pixel units. The position 0,0 is in the upper left corner of the dialog. It's usually desirable to leave a margin of about 10 pixels, so the default starting position is 10,10.
Width & Height
Specify the size of the control, in pixel units. Note that for drop-down list boxes and combo boxes, the height specified is the maximum height after it's dropped down -- the control height when it's not dropped down cannot be changed.
Control Text
This is the text that will appear in the control by default for text controls, buttons, check & radio boxes, and edit controls. It's not applicable to date or time controls, or list & combo boxes. These types need to be "filled in" from an Initialization expression, for instance.
Initialize Expression
This expression is executed for each control, after the control is created and shown on the dialog. This is where you should "populate" the value of the field if it's a data field. You can also use this to set static text fields to a value that depends on the context record, for instance. To edit the expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression.
There are DlgSetUserCtrl...( ) functions for each type of control, so you should use the appropriate expression to set the value of the control. Here's an example, setting an Edit control to the current value of the "# Adults" reservation field:
DlgSetUserCtrlText("# Adults Input", FieldText(ThisResv(),"Resv_Adult"))
For list and combo box fields, you'll also need to populate the list of selections, using DlgAddUser...( ) function calls. Here's part of an example for a Site Type list, including a blank entry at the top (assuming you want the option to leave it blank). Here the Eval( ) function is used so that many expressions can be executed in sequence, in order to add all of the necessary options:
Eval( DlgAddUserDropListText("Type Input"," "), DlgAddUserDropListText("Type Input","Normal RV"), ....
If you're not sure how to handle a particular type of input, use the Quick-Add Fields function in Edit Dialog Definition to add a similar type of field. It will fill in an appropriate expression for you.
OK/Save Expression
This expression is executed for each control when the "Save" function is done for the dialog (e.g. when DlgClickSave( ) is called in a new dialog, usually done when the "Save" button is clicked). This is where you would get the final value of the control and put it into the data field of the appropriate record. To edit the expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression.
It may be tempting to do validation here, but there's no way to abort the saving here if the value isn't valid. See the other element type, "Action on data Saved", for a good place to do validation. Of course if you just need to modify the value, e.g. convert the typed text to upper case, then you can do that here.
You should use appropriate expression functions to get the value of the control. There are DlgGetUserCtrl...( ) functions for each type of control. Here's an example, getting an Edit field for the "# Adults" reservation field and setting the data value:
SetFieldText( ThisResv(), "Resv_Adult", DlgGetUserCtrlText("# Adults Input"))
If you're not sure how to handle a particular type of input, use the Quick-Add Fields function in Edit Dialog Definition to add a similar type of field. It will fill in an appropriate expression for you.
There is a subtle but important issue when changing database field values -- the "Save" function is done only when it detects changes, e.g. when a change to an entry field is noticed. If you change database field values through scripting or any change to a record's value besides what's manually changed by the operator on the dialog entry field, you need to make sure you use DlgSetChangedFlag(.T.), in case no other changes are made on the dialog entry fields themselves that would normally trigger a flush.
Action Expression
This is optional expression which will be executed when the control's value is changed by the user (e.g. a button or checkbox clicked, text edited, or a list selection changed. As with any expression, appropriate context will be available. To edit the action expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression.
Control is NOT a data field
Usually when you add a control such as Edit Text, Check box, Drop-down List box, etc, it will be used for a database field. Thus any change to the field needs to be recognized as a "Data changed". However there are some cases where you use a field for some other function (e.g. a List Box used to just show a list of options to choose from). To avoid making the dialog think the database should be updated when the control is clicked on, set this option. Technically it wouldn't hurt anything if you never check this option, but using this option can help avoid extra "Save changes?" prompts when nothing has really changed.
"Modify Control" Elements
These element types, Rename, Move, Resize and Hide, allow you to change the standard controls of an existing dialog. These cannot be used with new controls you add, since all of this can be specified in the new control's element definition already.
Control ID
This specifies which dialog control will be modified. It must be entered as the internal ID of the control. Refer to the Dialog Control ID Reference for the ID's of each control.
Position, Size, or Control Text
Depending on the type of element, fill in the appropriate information -- the new Left and Top position for moving a control, or the new Width and Height for resizing a control, or the new Control Text for renaming a control.
"Action on Input" Elements
These element types allow you to perform some action when the standard controls of an existing dialog are clicked or the values changed (depending on the control type). These types of elements cannot be used with new controls you add, since the action expression is specified in the new control's element definition already.
Note that "Action on button click" is used not only for button controls, but also for checkbox controls and radio buttons. If the wrong type of action element is used for a control (e.g. a "button click" action for an Edit control), the results are unpredictable.
Any number of Action elements for a given control can be defined, and will be executed based on the order in the Dialog Elements list. However, note that any "Execute action before..." elements will be processed first, then the normal action of the control will be done, and finally any "after" elements will be executed (elements that do not have "Execute action before..." checked). If at any time one of the elements aborts the processing for that control (through the Abort option below), then it will also skip all remaining Action elements defined for that control.
Control ID
This specifies which dialog control will be modified. (See "Modify Control" Elements above for details.)
Action Expression
This is the expression which will be executed when the appropriate control change is triggered. As with any expression, appropriate context will be available. To edit the action expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression.
Execute action before normal processing
If this option is checked (and an Action expression entered), the Action expression will be executed before any normal processing that might happen for the action. This may or may not be important, depending on what you want to do.
The "normal processing" refers to the internal processing that the program normally does when this action is triggered. In many cases it's nothing, e.g. when entering text for most fields. However in many cases there is something done such as validation of the value, or changing what other fields are visible. And of course any buttons clicked will do something important.
As an example, you might define an element to execute an action when the "+1M" button is clicked in Reservation Details. If you need to make sure it's OK to do this before allowing it, then you would check this "Execute action before..." option so you can do your check and keep the function from happening if needed). However if you want the normal action to take place first (updating the date) before executing your expression, then don't select this option.
Abort the operation which triggered this action
If this is checked, then the Action Expression should return a True or False (boolean) value. If the value is False, then any normal processing is aborted. Obviously this is only useful if you also check the option to execute your action before normal processing, since there's nothing to abort after the normal processing.
As an example, you can do some validation or prompt the user when a button is clicked (e.g. to Check In a reservation), which would naturally need to be done before the normal processing, and return False in your Action expression to abort the operation if you don't want it to continue.
"Action on Focus Change" Elements
These elements can be used to trigger an expression when a control gains or loses input focus (e.g. due to a mouse click on the control, or the Tab key pressed to get to the next control). These elements can be defined for either standard controls or for new controls you add.
As described for "Action on Input" elements, only the first applicable focus change element will be used for a given dialog control.
Control ID or Control Name
This specifies which control will be modified. If it's for a standard (existing) control, fill in the Control ID (see "Modify Control" elements above for details.) If it's for a new control, fill in the Control Name of the new control (which must match the Control Name in the new control element definition).
Action Expression
This is the expression which will be executed when the control loses or gains focus. To edit the action expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression. The expression is always executed after the focus change actually happens (so for instance you can set focus somewhere else).
The focus change cannot be aborted, so the return value of this expression is not used.
"Action on Data Saved" Elements
For add-on Dialog Definitions, this element is triggered when data is saved to the record being edited.
For new dialogs, this is triggered when the DlgClickSave( ) function is executed. This is usually done in the Action expression for the "Save" button, so it will happen when "Save" is clicked on the dialog.
Action Expression
This is the expression which will be executed when the data is saved to the record being edited. Note that for add-on dialogs this isn't necessarily just when the dialog is closed -- for instance when used in the Customer Details dialog (Edit Customer), this is done whenever the customer being viewed is changed also, e.g. through the Next and Prev buttons.
To edit the action expression, click on the text box or click the Edit button next to it. The Expression Creator dialog will be used to enter the expression.
Execute action before normal processing
If this option is checked, the Action expression will be executed before any normal processing that the dialog does for saving -- generally this means before the data is actually saved into the record. Thus you can do any validation of your own before anything is saved (e.g. validate the fields in the dialog), with the option to abort the changes before actually saving them.
Note that if this option is used in the New Reservation dialog, then the Site for the reservation (or possibly multiple sites) will not yet be known when the Action is executed, so there is no Site context. You can access the Attributes selected through the ThisTempRec() context function, but it will not have a Site.
If this option is not checked, then the Action expression is not executed until all of the normal "Save" processing is performed by the dialog, e.g. the data validated and saved.
Note that it is possible to have more than one "Action on Data Save" elements to make multiple validations, and some can be executed before and some executed after the normal processing.
Abort the operation which triggered this action
If this is checked, then the Action Expression should return a True or False (boolean) value. If the value is False, then any normal processing (validation and saving data) is aborted. Obviously this is only useful if you also check the option to execute your action before normal processing.
Additional Topics:
Advanced Customizations Overview & other topics