Communicating between a window and a user object
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:
|
1 |
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 Chapter 9, “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:1<i>userobject</i>.<b>Event</b> <i>eventname </i>( )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:1Parent.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.
Examples of user object controls affecting a window
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.
Example 1: using functions
- In the Script view
in the User Object painter, define an instance variable, mywin,
of type window.1window mywinThis 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:
1mywin = 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:1uo_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.
Example 2: using user events
- 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()
- cb_max: Parent.Event
- 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.