Mastering PowerBuilder

Color CommandButton Object in the DataWindow Object

With version 6.0, PowerBuilder allows you to place a CommandButton in the DataWindow object and has added couple of events ButtonClicking and ButtonClicked to program the CommandButton. When you place the button in the DW object, you can select one of the two pre-defined actions and you don't have to write any code for it. The following lists the pre-defined actions.

Value	Action	Description	Value returned to ButtonClicked event
0	UserDefined	(Default) Allows for programming of the ButtonClicked and ButtonClicking events with no intervening action occurring.	Return code from the user's coded event script
1	Retrieve (Yield)	Retrieves rows from the database. Before retrieval actually occurs, option to yield is turned on. This allows the Cancel action to take effect during a long retrieve	Number of rows retrieved
2	Retrieve	Retrieves rows from the database. The option to yield is not automatically turned on	Number of rows retrieved
3	Cancel	Cancels a retrieval that has been started with the option to yield	0
4	PageNext	Scrolls to the next page	The row displayed at the top of the DataWindow control when the scrolling is complete or attempts to go past the first row-1 is an error occurs
5	PagePrior	Scrolls to the prior page	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
6	PageFirst	Scrolls to the first page	1 if successful-1 if an error occurs
7	PageLast	Scrolls to the last page	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
8	Sort	Displays Sort dialog box and sorts as specified	1 if successful-1 if an error occurs
9	Filter	Displays Filter dialog box and filters as specified	Number of rows filteredNumber < 0 if an error occurs
10	DeleteRow	If button is in detail band, deletes row associated with button; otherwise, deletes the current row	1 if successful-1 if an error occurs
11	AppendRow	Inserts row at the end	Row number of newly inserted row
12	InsertRow	If button is in detail band, inserts row using row number associated with the button; otherwise, inserts row using the current row	Row number of newly inserted row
13	Update	Saves changes to the database. If the update is successful, a COMMIT is issued. If the update fails, a ROLLBACK is issued	1 if successful-1 if an error occurs
14	SaveRowsAs	Displays Save As dialog box and saves rows in the format specified	Number of rows filtered
15	Print	Prints one copy of the DataWindow object	0
16	Preview	Toggles between preview and print preview	0
17	PreviewWithRulers	Toggles between rulers on and off	0
18	QueryMode	Toggles between query mode on and off	0
19	QuerySort	Specifies sorting criteria (forces query mode on)	0
20	QueryClear	Removes the WHERE clause from a query (if one was defined)	0

To see how this works, place a button object in the footer band in d_products_maint DataWindow object and select SaveRowsAs pre-defined action from the properties sheet and run the application, retrieve data and click on that button.

Placing the button object is also useful when you generate updatable HTML forms from the DataWindow. This feature is explored in 'WWW-PB' session in detail.

Unlike the CommandButton Window control, you can specify background and foreground colors to the button object.

ButtonClicking and ButtonClicked events work similar to Window CloseQuery and Close events, meaning, ButtonClicking event fires just before ButtonClicked event. If the former event returns zero, then the later event is fired, otherwise, PowerBuilder doesn't execute the later event. The row number parameter to both of these events is the row number on which the button is placed. If you click on a button placed in the Footer area passes the bottom most visible row on the DataWindow and button in the Summary band passes the last row in the DataWindow (same as the one returned by the RowCount() function).

Home	Previous Lesson: Print Preview - Zoom Utility Next Lesson: Drag And Drop