Buttons make it easy to provide command button actions in a DataWindow object. No coding is required. The use of Button controls in the DataWindow object, instead of CommandButton controls in a window, ensures that actions appropriate to the DataWindow object are included in the object itself.
The Button control is a command or picture button that can be placed in a DataWindow object. When clicked at runtime, the button activates either a built-in or user-supplied action.
For example, you can place a button in a report and specify that clicking it opens the Filter dialog box, where users can specify a filter to be applied to the currently retrieved data.
To add a button to a DataWindow object
-
Select Insert>Control>Button from the menu bar.
-
Click where you want the button to display.
You may find it useful to put a Delete button or an Insert button in the detail band. Clicking a Delete button in the detail band will delete the row next to the button clicked. Clicking an Insert button in the detail band will insert a row following the current row.
Be careful when putting buttons in the detail band
Buttons in the detail band repeat for every row of data, which is not always desirable. Buttons in the detail band are not visible during retrieval, so a Cancel button in the detail band would be unavailable when needed.
With the button still selected, type the text to display on the button in the PainterBar or on the General page of the Properties view.
-
Select the action you want to assign to the button from the Action drop-down list on the General page of the Properties view.
For information about actions, see Actions assignable to buttons in DataWindow objects.
If you want to add a picture to the button, select the Action Default Picture check box or enter the name of the Picture file to display on the button.
If you want to suppress event processing when the button is clicked at runtime, select the Suppress Event check box.
When this option has been selected for the button and the button is clicked at runtime, only the action assigned to the button and the Clicked event are executed. The ButtonClicking and the ButtonClicked events are not triggered.
What happens if Suppress Event is off
If Suppress Event is off and the button is clicked, the Clicked and ButtonClicking events are fired. Code in the ButtonClicking event (if any) is executed. Note that the Clicked event is executed before the ButtonClicking event.
If the return code from the ButtonClicking event is 0, the action assigned to the button is executed and then the ButtonClicked event is executed.
If the return code from the ButtonClicking event is 1, neither the action assigned to the button nor the ButtonClicked event are executed.
Do not use a message box in the Clicked event
If you call the MessageBox function in the Clicked event, the action assigned to the button is executed, but the ButtonClicking and ButtonClicked events are not executed.
Example
For an example of a DataWindow object that uses buttons, see the d_button_report object in the Code Examples application.
This DataWindow object has several buttons that have default actions, and two that have user-defined actions. In the Properties view in the DataWindow painter, these buttons are named cb_help and cb_exit. Suppress Event is off for all buttons.
In the Window painter, the Clicked and ButtonClicking events for the DataWindow control that contains d_button_report are not scripted. This is the ButtonClicked event script:
string ls_Object string ls_win ls_Object = String(dwo.name) If ls_Object = "cb_exit" Then Close(Parent) ElseIf ls_Object = "cb_help" Then ls_win = parent.ClassName() f_open_help(ls_win) End If
This script is triggered when any button in the DataWindow object is clicked.
You can choose whether to display buttons in print preview or in printed output. You control this in the Properties view for the DataWindow object (not the Properties view for the button).
To control the display of buttons in a DataWindow object in print preview and on printed output
-
Display the DataWindow object's Properties view with the Print Specification page on top.
-
Select the Display Buttons – Print check box.
The buttons are included in the printed output when the DataWindow object is printed.
-
Select the Display Buttons – Print Preview check box.
The buttons display on the screen when viewing the DataWindow object in print preview.
The following table shows the actions you can assign to a button in a DataWindow object. Each action is associated with a numeric value (the Action DataWindow object property) and a return code (the actionreturncode event argument).
The following code in the ButtonClicked event displays the value returned by the action:
MessageBox("Action return code", actionreturncode)
|
Action |
Effect |
Value |
Action return code |
|---|---|---|---|
|
User Defined (default) |
Allows the developer to program the ButtonClicked event with no intervening action occurring. |
0 |
The return code from the user's coded event script. |
|
Retrieve (Yield) |
Retrieves rows from the database. Before retrieval occurs, the option to yield is turned on; this will allow the Cancel action to take effect during a long retrieve. |
1 |
Number of rows retrieved. -1 if retrieve fails. |
|
Retrieve |
Retrieves rows from the database. The option to yield is not automatically turned on. |
2 |
Number of rows retrieved. -1 if retrieve fails. |
|
Cancel |
Cancels a retrieval that has been started with the option to yield. |
3 |
0 |
|
Page Next |
Scrolls to the next page. |
4 |
The row displayed at the top of the DataWindow control when the scrolling is complete or attempts to go past the first row. -1 if an error occurs. |
|
Page Prior |
Scrolls to the prior page. |
5 |
The row displayed at the top of the DataWindow control when the scrolling is complete or attempts to go past the first row. -1 if an error occurs. |
|
Page First |
Scrolls to the first page. |
6 |
1 if successful. -1 if an error occurs. |
|
Page Last |
Scrolls to the last page. |
7 |
The row displayed at the top of the DataWindow control when the scrolling is complete or attempts to go past the first row. -1 if an error occurs. |
|
Sort |
Displays Sort dialog box and sorts as specified. |
8 |
1 if successful. -1 if an error occurs. |
|
Filter |
Displays Filter dialog box and filters as specified. |
9 |
Number of rows filtered. Number < 0 if an error occurs. |
|
Delete Row |
If button is in detail band, deletes row associated with button; otherwise, deletes the current row. |
10 |
1 if successful. -1 if an error occurs. |
|
Append Row |
Inserts row at the end. |
11 |
Row number of newly inserted row. |
|
Insert Row |
If button is in detail band, inserts row using row number associated with the button; otherwise, inserts row using the current row. |
12 |
Row number of newly inserted row. |
|
Update |
Saves changes to the database. If the update is successful, a Commit will be issued; if the update fails, a Rollback will be issued. |
13 |
1 if successful. -1 if an error occurs. |
|
Save Rows As |
Displays Save As dialog box and saves rows in the format specified. |
14 |
Number of rows filtered. Number < 0 if an error occurs. |
|
|
Prints one copy of the DataWindow object. |
15 |
0 |
|
Preview |
Toggles between preview and print preview. |
16 |
0 |
|
Preview With Rulers |
Toggles between rulers on and off. |
17 |
0 |
|
Query Mode |
Toggles between query mode on and off. |
18 |
0 |
|
Query Sort |
Allows user to specify sorting criteria (forces query mode on). |
19 |
0 |
|
Query Clear |
Removes the WHERE clause from a query (if one was defined). |
20 |
0 |
