Advanced PowerBuilder

Creating a Standard User Object

To create an user object, click on the user object icon and select the "New" button:

Note that the C++ option will only be available if you have the Enterprise version of PowerBuilder or if the Advanced Developer's Kit is installed.

In this dialog box, you need to specify which type of user object you want to create. Let's see how we created our example from Session 12, which displayed various quotes when different CommandButtons were clicked.

Select the "Standard" icon in the Visual group, click OK and select "CommandButton" from the list of standard visual objects.

A CommandButton should be ready and waiting for you. The user object development environment is similar to that found in the window painter.

If you remember back to our discussion of inheritance, we have just created our own class, crossing the boundary from PowerBuilder to user defined classes. After we add our functionality to this CommandButton, we will be able to create instances of it.

Creating a CommandButton User Object

Events available to the standard CommandButton control are available to this user object. In order to customize our user object, PowerBuilder offers us the chance to declare variables, structures, functions and our own user events.

To complete our CommandButton user object, we need to add the functionality that displays MircroHelp when the mouse moves over the CommandButton. Let's declare an user defined event, ue_mousemove. Select "Declare/User Events" from the menu and declare "ue_mousemove" event and map it to "pbm_mousemove" event id.

Now, go to the Script Painter and type the following script for the ue_mousemove event:

// Object: uo_CommandButton user object
// Event: ue_mousemove

w_mdi_frame.SetMicroHelp( This.Tag )

When creating an user object, try to avoid hard coding anything into the script. By hard coding the script, you are reducing the flexibility of the user object, the cornerstone of their usefulness. In this case, we've used the 'This' keyword, so that the displayed message depends on the underlying object.

Save the user object as "uo_commandbutton" and create a new window. Now, you may want to test this user object. Open the "w_about" window. Select "Controls/user object" from the menu. Select "uo_CommandButton". Click on the window workspace next to the "Done" CommandButton. We have script for the "Done" CommandButton's clicked event. Copy that script to the new CommandButton's clicked event, and delete the "Done" CommandButton. Change the new CommandButton's name to "cb_done" and the text to "&Done". Similarly, replace all other CommandButtons. Define the help for each CommandButton in its TAG property, by going into the properties dialog box for each CommandButton.

Confused about what's happening? What's happening is that, we replaced all the standard PowerBuilder CommandButtons in   "w_about" window with the user object of type CommandButton. That means, we are using our own CommandButton instead of PowerBuilder's.

Now, save the window and run the application. Select "Help/About" from the menu. Move the mouse over these CommandButtons and see if PowerBuilder displays help on the statusbar.

The code written for the user object class is available to each user object instance placed in the window and changes to the user object class will be reflected in each instance of the object. This provides you with a code which is reusable, easier to maintain and takes less time to develop.

Let's now create a more complex standard user object that we can be used in our Product Management application.

Creating a DataWindow user object

By default, you can't select multiple rows, either continuously or randomly, in a DataWindow; you are restricted to one row at a time. This can be restrictive, so let's create a DataWindow user object with this functionality.

Note that this kind of functionality is already supported by programs such as 'File Manager'/ 'Window Explorer'. It has been commonly accepted that the users need to use the Ctrl and Shift keys in conjunction with a mouse click to select random or continuous items respectively, and so it would make sense to use this standard.

Invoke the user object painter and this time create a Standard DataWindow object.

The logic for this user object is quite simple. We store the selected row in an instance variable and then if the user uses the Shift key while selecting a new row, we select all the rows in a loop between the previously selected row and the current row. If they use the Ctrl key, we simply add the current row to the list of selected rows.

We could write the entire code in the object's clicked event, but splitting the logic between two events, one standard and one custom, would be better. Therefore, let's create a user defined event called "ue_shiftclicked". DO NOT assign any event id to this event. Define arguments as shown below.

Next, we have to declare an instance variable to hold the selected rows, so select "Declare/Instance Variables..." and declare the following variable.

Long il_DWSelectedRow

Now write the following code in the clicked event for the user object:

// Object: uo_DataWindow control user object
// Event: Clicked

If Row > 0 Then
   If KeyDown(KeyControl!) Then
      This.selectrow(Row,true)
   Else
      This.selectrow(0,false)
      This.selectrow(Row,true)
   End If
   If KeyDown(KeyShift!) Then
      This.Event Trigger ue_ShiftClicked( Row )
      Return
   End If
End If

il_DWSelectedRow = Row
this.SetRow(Row)

The KeyDown()function is used to establish the key pressed by the user. If the user clicks the left mouse button without using any other key combination, we select the clicked row, deselecting others. If the Ctrl key combination is used, we add the highlighted row to our current selection and if the Shift key combination is used we trigger the user event.

The parameter for the KeyDown() is an enumerated data type. PowerBuilder's on-line help contains the list of all the keys that can be used as parameters for the KeyDown() function.

If you now look at the list of events that are possible for the user object, you'll find that our new user event "ue_shiftclicked" is available. We need to write the following code into this event:

// Object: uo_DataWindow Control user object
// Event: ue_shiftclicked

Long ll_OldRow, ll_StartRow, ll_EndRow, ll_RowCounter
ll_OldRow = il_DWSelectedRow

If ll_OldRow > ParamRow Then
   ll_StartRow = ParamRow
   ll_EndRow = ll_OldRow
Else
   ll_StartRow = ll_OldRow
   ll_EndRow = ParamRow
End If

For ll_RowCounter = ll_StartRow to ll_EndRow Step 1
   this.SelectRow( ll_RowCounter, true )
Next

this.SetRow( ParamRow )
this.SetColumn( 1 )

Return 0

You should be aware that the currently selected row may be either greater or lesser than the previously clicked row. For example, if you click on row 10 and click on row 16 with the Shift combination, the ll_StartRow will be10 and ll_EndRow will be16. In another case if you click on another row with the Shift combination that is less than 10, say 5, then in that case, ll_StartRow will be 5 and ll_EndRow will be 10. These endpoints are organized into sensible start and final variables by the if statement.

The FOR loop is used by the SelectRow() function to select all the rows from ll_StartRow to ll_EndRow. The second argument to the SelectRow() decides whether to select (true) or deselect (false) the specified row. After this, we store the currently selected row in the il_DWSelectedRow variable.

Save this user object as uo_DataWindow, and to use it:

1.	Open up the "w_product_master" window.
2.	Add the user object control "uo_DataWindow".
3.	Link "d_products_maint" DataWindow object to the new DataWindow control.
4.	Copy script from "dw_product" to the corresponding events in the new DataWindow control.
5.	Delete the "dw_product" DataWindow control.
6.	Rename the new DataWindow control as "dw_product".

We've effectively replaced dw_product with our user object of type DataWindow. If you run the window as it is, you be able to see the effect of our new functionality.

As you can see, we can now select multiple rows on the DataWindow.

Context Sensitive Help for DataWindow Controls

Like any other control in a window, you can specify tag values for the DataWindow control and then use them to display context sensitive help. However this is restricted to DataWindow as a whole. You encounter problems, if you want to display different textual help messages for each field within the DataWindow control.

To solve this problem, we need to find out the column in which the user is currently focused and then supply an appropriate message. For the first part of the problem, we can make use of the ItemFocusChanged event. When the user presses the Tab key or clicks on another column, ItemChanged, ItemError or ItemFocusChanged events will be triggered depending on whether or not the data has been changed, and if it has changed whether the new entry passes any predefined validation rules.

By using GetColumnName() function in the ItemChanged event, we can get the current column and by using the same command in the ItemFocusChanged event, we can get the next column name in the tab order.

For example, if the user presses Tab when the focus is on "product_no" in the "w_product_master" window, the GetColumnName() function in the ItemChanged event would return "product_no", while the same function in the ItemFocusChanged event would return "product_description".

The following code gets the column name, and sets the MircroHelp, by obtaining the tag values using the Describe() function. Put this script in the ItemFocusChanged event for the DataWindow Control user object ( uo_DataWindow ), that we just created .

// Object: uo_DataWindow Control user object
// Event: ItemFocusChanged

string ls_ColumnName, ls_TagValue, ls_Argument
ls_ColumnName = GetColumnName()
ls_Argument = trim( ls_ColumnName ) + ".Tag"
ls_TagValue = Describe( ls_Argument )

If ls_TagValue = "" OR &
   isnull( ls_TagValue ) OR &
   trim( ls_TagValue ) = "?" OR &
   trim( ls_TagValue ) = "!" Then
   ls_TagValue = "Ready"
End If

w_mdi_frame.SetMicroHelp( ls_TagValue )

The Describe() function returns an exclamation mark (!), when the argument is bad and returns a question mark (?), when the specified attribute has no value. We can use these returns in a test, setting ls_TagValue to 'Ready', the default value that appears on the status bar if anything goes wrong.

If you run the application, open the "w_product_master" by selecting "Module/Product Master Maint." option. Retrieve the data by selecting "File/Retrieve" from the menu. Now, keep on pressing the tab key and see the help on the status bar. If you see "Ready" for a column, it means that you didn't define a tag value for that column in the DataWindow. To define the TAG value, open "w_product_master" and click with the right mouse button on "dw_product" DataWindow. Select "Modify DataWindow" from the menu. Now you are in the DataWindow design mode. Select one column at a time and go to the properties for each column and define the TAG value.

You can now use uo_DataWindow, instead of the standard DataWindow control where ever you need multi row selection and microhelp display functionality, without writing a single line of new code.

Home	Previous Lesson: Introduction Next Lesson: Custom User Objects