Often you need to exchange information between a window and a visual user object in the window. Consider these situations:
-
You have a set of buttons in a custom user object. Each of the buttons acts upon a file that is listed in a SingleLineEdit control in the window (but not in the user object).
-
You need to pass the contents of the SingleLineEdit control from the window to the user object.
-
You have a user object color toolbar. When the user clicks one of the colors in the user object, a control in the window changes to that color.
-
You need to pass the color from the user object to the window control.
This section discusses two techniques for handling this communication and presents a simple example.
|
Technique |
Advantages |
Disadvantages |
|---|---|---|
|
Functions |
Easy to use Supports parameters and return types, so is not prone to errors Supports data encapsulation and information hiding Best for complex operations |
Creates overhead, might be unnecessary for simple operations |
|
User events |
Very flexible and powerful |
Uses no type checking, so is prone to error |
Communication with both techniques can be either synchronous (using Send for functions and the EVENT keyword for events) or asynchronous (using Post for functions and the POST keyword for events).
Directly referencing properties
Instead of using functions or user events, it is possible to reference properties of a user object directly. If you have a user object control, uo_1, associated with a custom user object that has a SingleLineEdit, sle_1, you can use the following in a script for the window:
uo_1.sle_1.Text = "new text"
However, it is better to communicate with user objects through functions and user events, as described below, in order to maintain a clean interface between your user object and the rest of your application.
The functions technique
Exchanging information using functions is straightforward. After a user object calls a function, any return value is available to any control within that object.
For how to use this technique, see Example 1: using functions.
To pass information from a window to a user object:
-
Define a public, user object-level function that takes as arguments the information needed from the window.
-
Place the user object in the window.
-
When appropriate, call the function from a script in the window, passing the needed information as arguments.
To pass information from a user object to a window:
-
Define a public, window-level function that takes as parameters the information needed from the user object.
-
Place the user object in the window.
-
When appropriate, call the function from a script in the user object, passing the needed information as parameters.
The user events technique
You can define user-defined events, also called user events, to communicate between a window and a user object. You can declare user events for any PowerBuilder object or control.
A custom visual user object often requires a user event. After you place a custom visual user object in a window or in another custom user object, you can write scripts only for events that occur in the user object itself. You cannot write scripts for events in the controls in the user object.
You can, however, define user events for the user object, and trigger those events in scripts for the controls contained in that user object. In the Window painter, you write scripts for the user events, referencing components of the window as needed.
For more information about user events, see Working with User Events, and Application Techniques. For instructions for using this technique, see Example 2: using user events.
To define and trigger a user event in a visual user object:
-
In the User Object painter, select the user object.
-
Make sure no control in the user object is selected.
-
In the Event List view, select Add from the pop-up menu.
-
In the Prototype window that displays, define the user event.
For how to do so, see Defining user events.
-
Use the Event keyword in scripts for a control to trigger the user event in the user object:
userobject.Event eventname ( )
For example, the following statement in the Clicked event of a CommandButton contained in a custom visual user object triggers the Max_requested event in the user object:
Parent.Event Max_requested()
This statement uses the pronoun Parent, referring to the custom visual user object itself, to trigger the Max_requested event in that user object.
-
Implement these user events in the Window painter.
To implement the user event in the window:
-
Open the window.
In the Window painter, select Insert>Control from the menu bar and place the custom visual user object in the window.
-
Double-click the user object and then in the Script view, write scripts for the user events you defined in the User Object painter.
To illustrate these techniques, consider a simple custom visual user object, uo_minmax, that contains two buttons, Maximize and Minimize.
If the user clicks the Maximize button in an application window containing this user object, the current window becomes maximized. If the user clicks Minimize, the window closes to an icon.
Because the user object can be associated with any window, the scripts for the buttons cannot reference the window that has the user object. The user object must get the name of the window so that the buttons can reference the window.
Example 1: using functions shows how PowerBuilder uses functions to pass a window name to a user object, allowing controls in the user object to affect the window the user object is in.
Example 2: using user events shows how PowerBuilder uses unmapped user events to allow controls in a user object to affect the window the user object is in.
-
In the Script view in the User Object painter, define an instance variable, mywin, of type window.
window mywin
This variable will hold the name of the window that has the user object.
-
Define a user object-level function, f_setwin, with:
-
Public access
-
No return value
-
One argument, win_param, of type window and passed by value
-
-
Type the following script for the function:
mywin = win_param
When f_setwin is called, the window name passed in win_param will be assigned to mywin, where user object controls can reference the window that has the user object.
-
Write scripts for the two buttons:
cb_max: mywin.WindowState = Maximized!
cb_min: mywin.WindowState = Minimized!
-
Save the user object as uo_minmax and close the User Object painter.
-
Open the window, drag uo_minmax onto the window in the Layout view, and name it uo_func in the Properties view.
-
In the Open event for the window, call the user object-level function, passing the name of the window:
uo_func.f_setwin(This)
The pronoun This refers to the window's name, which will be passed to the user object's f_setwin function.
What happens. When the window opens, it calls the user object-level function f_setwin, which passes the window name to the user object. The user object stores the name in its instance variable mywin. When the user clicks a button control in the user object, the control references the window through mywin.
In the Script view in the User Object painter, define two unmapped user events for the user object: Max_requested and Min_requested.
Leave the Event ID fields blank to define them as unmapped.
Trigger user events of the user object in the scripts for the Clicked event of each CommandButton:
-
cb_max: Parent.Event Max_requested()
-
cb_min: Parent.Event Min_requested()
Save the user object and name it uo_event and close the User Object painter.
Open the window and in the Window painter, select Insert>Object from the menu bar and then place uo_event in the window.
Double-click uo_event to display its Script view.
The two new user events display in the second drop-down list in the Script view.
Write scripts for the two user events:
max_requested: Parent.WindowState = Maximized!
min_requested: Parent.WindowState = Minimized!
These scripts reference the window containing the user object with the pronoun Parent.
What happens
When a user clicks a button, the Clicked event script for that button triggers a user event in its parent, the user object. The user object script for that event modifies its parent, the window.
