Working with User Objects

About this chapter

One of the features of object-oriented programming is reusability: you define a component once, then reuse it as many times as you need to without any additional work. User objects are one of the best ways to take advantage of reusability in PowerBuilder. This chapter describes how to define and use user objects.

About user objects

Applications often have features in common. For example, you might often reuse features like the following:

  • A processing package that calculates commissions or performs statistical analysis

  • A Close button that performs a certain set of operations and then closes the window

  • DataWindow controls that perform standard error checking

  • A list that includes all departments

  • A predefined file viewer that you plug into a window

If you find yourself using the same application feature repeatedly, you should define a user object: you define the user object once in the User Object painter and use it as many times as you need.

There are two main types of user objects: class and visual. Class user objects are also called nonvisual objects.

Examples of user objects

The PowerBuilder Code Examples contain many interesting user objects in PBEXAMUO.PBL. Take a look at them to get an appreciation for the power of user objects.

Class user objects

A class user object lets you reuse a set of business rules or other processing that acts as a unit but has no visual component. For example, you might define a class that calculates sales commissions or performs statistical analysis. Whenever you need to do this type of processing, you instantiate the user object in a script and call its functions.

You build class user objects in the User Object painter, specifying instance variables and object-level functions. Then you create an instance of the class user object in your application, thereby making its processing available.

There are two kinds of class user objects:

  • Custom class

  • Standard class

Custom class user objects

Custom class user objects are objects of your own design that encapsulate properties and functions not visible to the user. They are not derived from PowerBuilder objects. You define them to create units of processing that have no visual component.

For example, to calculate commissions in an application, you can define an n_CalculateCommission custom class user object that contains properties and user-defined functions that do the processing to calculate commissions.

Whenever you need to use this processing, you create an instance of the user object in a script, which then has access to the logic in the user object.

When you build components that you will deploy to a transaction server, you use custom class user objects. For more information, see the section called “Using Transaction Objects” in Application Techniques.

Standard class user objects

A standard class user object inherits its definition from one built-in, nonvisual PowerBuilder object, such as the Transaction object or Error object. You modify the definition to make the object specific to your application, and optionally add instance variables and functions to enhance the behavior of the built-in object. Once you define a standard class user object, you can go to the Application painter and specify that you want to use it instead of the corresponding built-in system object in your application.

One important use of a standard class user object is employing one inherited from the built-in Transaction object to do database remote procedure calls from within an application.

Visual user objects

A visual user object is a reusable control or set of controls that has a certain behavior. You define it in the User Object painter, where you place controls in the user object and write scripts for those controls. Then you can place the user object in windows you build in your applications as often as needed.

There are three types of visual user objects:

  • Custom visual

    Most useful if you frequently group controls together in a window and always use the controls to perform the same processing.

  • External visual

    Useful when you have a custom DLL.

  • Standard visual

    Most useful if you frequently use a PowerBuilder control to perform the same processing.

Custom visual user objects

Custom visual user objects are objects that have several controls that function as a unit. You can think of a custom visual user object as a window that is a single unit and is used as a control.

Assume you frequently use a group of buttons, each of which performs standard processing. If you build a custom user object that contains all the buttons, you can place the buttons in the window as a unit when you place the user object in a window.

External visual user objects

External visual user objects contain controls from objects in the underlying windowing system that were created outside PowerBuilder. You can use a custom DLL in PowerBuilder to create an external user object.

You must know what classes the DLL supports, the messages or events the DLL responds to, and the style bits that you can set in the DLL.

Standard visual user objects

A standard visual user object inherits its definition from one standard PowerBuilder control. You modify the definition to make the control specific to your applications.

Assume you frequently use a CommandButton named Close to display a message box and then close the parent window. If you build a standard visual user object that derives from a CommandButton to perform this processing, you can use the user object whenever you want to display a message box and then close a window.

Building user objects

You can build a user object from scratch, or you can create a user object that inherits its style, events, functions, structures, variables, and scripts from an existing user object.

For information on building a user object from scratch, see Building a new user object. To find out more about creating a user object based on an existing PowerBuilder object, see Using inheritance to build user objects.

About the User Object painter

The User Object painter has five implementations, depending on the type of user object you are working with. It has several views where you specify how the user object behaves and, for custom visual and standard visual user objects, how it looks. For details about the views, how you use them, and how they are related, see Views in painters that edit objects.

Views for visual user objects

In this User Object painter for a custom visual user object, the Layout view and Script view have been arranged to display at the same time:


Most of your work in the User Object painter for visual objects is done in three views:

  • The Layout view, where you design the appearance of the user object

  • The Properties view, where you set user object properties and control properties

  • The Script view, where you modify behavior by coding user object and control scripts

In the Layout view, you add controls to a visual user object in the same way you add controls to a window.

For information about specifying user object properties, see Building a new user object. For information about using the Script view, see Writing Scripts.

Views for nonvisual user objects

You do not need the Layout and Control List views for nonvisual user objects, but otherwise, you use all the views that you use for visual objects.

Nonvisual user objects require no layout design work, but working in the User Object painter on the behavior of a nonvisual object is otherwise similar to working on the behavior of a visual user object.

Building a new user object

This section describes how to build a user object from scratch. You use this technique to create user objects that are not based on existing user objects.

Creating a new user object

To create a new user object

  1. Open the New dialog box.

  2. On PB Object tab page, select the kind of user object you want to create.

    The five user object choices display at the top of the tab page:


  3. Click OK.

    What you do next depends on the type of user object you selected. For all user objects except Standard Class and Standard Visual, the User Object painter opens.

    The remainder of this section describes how to build each type of user object.

Building a custom class user object

On the PB Object tab page of the New dialog box, if you select Custom Class and click OK, the User Object painter for custom class user objects opens.

To build the custom class user object

  1. Declare functions, structures, or variables you need for the user object.

  2. Create and compile scripts for the user object.

    Custom class user objects have built-in constructor and destructor events.

  3. Save the user object.

    See Saving a user object.

Using AutoInstantiate

You can create custom class user objects that are autoinstantiated, which provides you with the ability to define methods.

Autoinstantiated user objects do not require explicit CREATE or DESTROY statements when you use them. They are instantiated when you call them in a script and destroyed automatically.

To define an autoinstantiated custom class user object

Building a standard class user object

On the PB Object tab page of the New dialog box, if you select Standard Class and click OK, the Select Standard Class Type dialog box displays.

To build the standard class user object

  1. In the Select Standard Class Type dialog box, select the built-in system object that you want your user object to inherit from and click OK.

  2. Declare functions, structures, or variables you need for the user object.

    For a list of properties and functions

    Use the Browser to list the built-in properties inherited from the selected system object. Use the Function List view or the Browser to list the functions inherited from the selected system object.

  3. Declare any user events needed for the user object.

    For information about user events, see Communicating between a window and a user object.

  4. In the Script view, create and compile scripts for the user object.

    Class user objects have built-in constructor and destructor events.

  5. Save the user object.

    See Saving a user object.

Building a custom visual user object

On the PB Object tab page of the New dialog box, if you select Custom Visual and click OK, the User Object painter for custom visual user objects opens. It looks like the Window painter, but the empty box that displays in the Layout view is the new custom visual user object.

Building a custom visual user object is similar to building a window, described in Working with Windows The views available in the Window painter and the User Object painter for custom visual user objects are the same.

To build the custom visual user object

  1. Place the controls you want in the custom visual user object.

  2. Work with the custom visual user object as you would with a window in the Window painter:

    • Define the properties of the controls

    • Declare functions, structures, or variables as necessary

    • Declare any events needed for the user object or its controls

      For information about user events, see Communicating between a window and a user object.

    • In the Script view, create and compile the scripts for the user object or its controls

      You can write scripts for each control in a custom visual user object.

      For more information on events associated with custom visual user objects, see Events in user objects.

  3. Save the user object.

    See Saving a user object.

Building an external visual user object

On the PB Object tab page of the New dialog box, if you select External Visual and click OK, the User Object painter for external visual user objects opens.

To build an external visual user object

  1. In the Properties view, click the Browse button next to the LibraryName box.

  2. In the Select Custom Control DLL dialog box, select the DLL that defines the user object and click OK.

  3. In the Properties view, enter the following information, as necessary, and click OK:

    • The class name registered in the DLL

      Information about the class name is usually provided by the vendor of the purchased DLL.

    • Text in the Text box

      This will be displayed only if the object has a text style property.

    • Display properties (border and scroll bars)

    • Decimal values for the style bits associated with the class

      Information about style bits is usually provided by the vendor of the purchased DLL. PowerBuilder will OR these values with the values selected in the display properties for the control.

  4. Declare any functions, structures, or variables you need to declare for the user object.

    You can declare functions, structures, and variables for the user object in the Script view. Information about functions is usually provided by the vendor of the purchased DLL.

  5. Declare any needed events for the user object.

    For information about user events, see Communicating between a window and a user object.

  6. In the Script view, create and compile the scripts for the user object.

    For more information on events associated with external visual user objects, see Events in user objects.

  7. Save the user object.

    See Saving a user object.

Building a standard visual user object

On the PB Object tab page of the New dialog box, if you select Standard Visual and click OK, the Select Standard Visual Type dialog box displays.

To build a standard visual user object

  1. In the Select Standard Visual Type dialog box, select the PowerBuilder control you want to use to build your standard visual user object and click OK.

    The selected control displays in the workspace. Your visual user object will have the properties and events associated with the PowerBuilder control you are modifying.

  2. Work with the control as you do in the Window painter:

    • Review the default properties and make any necessary changes

    • Declare functions, structures, or variables as necessary

      You can declare these in the Script view.

    • Declare any user events needed for the user object

      For information about user events, see Communicating between a window and a user object.

    • Create and compile the scripts for the user object

      Standard visual user objects have the same events as the PowerBuilder control you modified to create the object.

  3. Save the user object.

    See Saving a user object.

Events in user objects

When you build a user object, you can write scripts for any event associated with that user object.

Events in class user objects

Most custom class user objects have only constructor and destructor events.

Event

Occurs when

Constructor

The user object is created

Destructor

The user object is destroyed


Standard class user objects have the same events as the PowerBuilder system object from which they inherit.

Events in visual user objects

Standard visual user objects have the same events as the PowerBuilder control from which they inherit. Custom and external visual user objects have a common set of events.

Event

Occurs when

Constructor

Immediately before the Open event of the window and when the user object is dynamically placed in a window

Destructor

Immediately after the Close event of the window and when the user object is dynamically removed from a window

DragDrop

A dragged object is dropped on the user object

DragEnter

A dragged object enters the user object

DragLeave

A dragged object leaves the user object

DragWithin

A dragged object is moved within the user object

Help

A user presses the F1 key or clicks the context Help button [?] on the title bar of the window with which the menu is associated and then points and clicks on a menu item

Other

A Windows message occurs that is not a PowerBuilder event

RButtonDown

The right mouse button is pressed


For more about drag and drop, see Application Techniques.

Saving a user object

To save a user object

  1. In the User Object painter, select File>Save from the menu bar or click the Save button in the painter bar.

    If you have previously saved the user object, PowerBuilder saves the new version in the same library and returns you to the User Object painter.

    If you have not previously saved the user object, PowerBuilder displays the Save User Object dialog box.

  2. Enter a name in the User Objects box.

    For naming considerations, see Naming the user object.

  3. Enter comments to describe the user object.

    These display in the Select User Object dialog box and in the Library painter, and will document the purpose of the user object.

  4. Specify the library in which to save the user object.

    To make a user object available to all applications, save it in a common library and include the library in the library search path for each application.

  5. Click OK to save the user object.

Validation for .NET Web Service

In the User Object painter for a custom class user object, the Design menu has .NET Web Service Validation items. If you select a validation menu item for .NET Web Service to enable validation, a check displays next to the menu item. When you save the object, you might see some error messages.

Naming the user object

A user object name can be any valid PowerBuilder identifier up to 40 characters. For information about PowerBuilder identifiers, see the section called “Identifier names” in PowerScript Reference.

Naming conventions

You should adopt naming conventions to make it easy to understand a user object's type and purpose.

One convention you could follow is to use u_ as the prefix for visual user objects and n_ as the prefix for class (nonvisual) user objects. For standard classes, include the standard prefix for the object or control from which the class inherits in the name. For external user objects, include ex_ in the name, and for custom class user objects, include cst_ in the name.

The following table shows some examples of this convention.

Type of user object

Format

Example

Standard visual

u_control_purpose

u_cb_close, a CommandButton that closes a window

Custom visual

u_purpose

u_toolbar, a toolbar

External visual

u_ex_purpose

u_ex_sound, outputs sound

Standard class

n_systemobject_purpose

n_trans_test, derived from the Transaction object and used for testing

Custom class

n_cst_purpose

n_cst_commission, calculates commissions


For a list of naming conventions, see Naming conventions in Working with Targets.

Using inheritance to build user objects

When you build a user object that inherits its definition (properties, events, functions, structures, variables, controls, and scripts) from an existing user object, you save coding time. All you must do is modify the inherited definition to meet the requirements of the current application.

For example, suppose your application has a user object u_file_view that has three CommandButtons:

  • List—displays a list of files in a list

  • Open—opens the selected file and displays the file in a MultiLineEdit control

  • Close—displays a message box and then closes the window

If you want to build another user object that is exactly like the existing u_file_view except that it has a fourth CommandButton, you can use inheritance to build the new user object, and then all you need to do is add the fourth CommandButton.

To use inheritance to build a descendant user object:

  1. Click the Inherit button in the PowerBar, or select File>Inherit from the menu bar.

  2. In the Inherit From Object dialog box, select User Objects from the Objects of Type drop-down list.

  3. Select the target as well as the library or libraries you want to look in.

    Displaying user objects from many libraries

    To find a user object more easily, you can select more than one library in the Libraries list. Use Ctrl+click to toggle selected libraries and Shift+click to select a range.

  4. Select the user object you want to use to create the descendant, and click OK.

    The selected object displays in the User Object painter and the title bar indicates that the object is a descendant.

  5. Make any changes you want to the user object.

  6. Save the user object with a new name.

Using the inherited information

When you build and save a user object, PowerBuilder treats the object as a unit that includes:

  • The object (and any controls within the object if it is a custom visual user object)

  • The object's properties, events, and scripts

  • Any variables, functions, or structures declared for the object

When you use inheritance to build a new user object, everything in the ancestor user object is inherited in the direct descendant and in its descendants in turn.

Ancestor's instance variables display

If you create a user object by inheriting it from a custom class or standard class user object that has public or protected instance variables with simple datatypes, the instance variables display and can be modified in the descendant user object's Properties view.

All public instance variables with simple datatypes such as integer, boolean, character, date, string, and so on display in the descendant. Instance variables with the any or blob datatype or instance variables that are objects or arrays do not display.

What you can do in the descendant

You can do the following in a descendant user object:

  • Change the values of the properties and the variables

  • Build scripts for events that do not have scripts in the ancestor

  • Extend or override the inherited scripts

  • Add controls (in custom visual user objects)

  • Reference the ancestor's functions and events

  • Reference the ancestor's structures if the ancestor contains a public or protected instance variable of the structure datatype

  • Access ancestor properties, such as instance variables, if the scope of the property is public or protected

  • Declare variables, events, functions, and structures for the descendant

What you cannot do in the descendant

In a descendant user object, you cannot delete controls inherited from a custom visual user object. If you do not need a control in a descendant user object, you can make it invisible.

Understanding inheritance

The issues concerning inheritance with user objects are the same as the issues concerning inheritance with windows and menus. See Understanding Inheritance for more information.

Using user objects

Once you have built a user object, you are ready to use it in an application. This section describes how to use:

  • Visual user objects

  • Class user objects

Using visual user objects

You use visual user objects by placing them in a window or in a custom visual user object.The techniques are similar whether you are working in the Window painter or the User Object painter.

To place a user object

  1. Open the window or custom visual user object in which you want to place the visual user object.

  2. Click the User Object button in the PainterBar, or select Insert>Control from the menu bar and then select User Object.

  3. Select the user object you want to use and click the location where you want the user object to display.

    PowerBuilder creates a descendant user object that inherits its definition from the selected user object and places it in the window or user object.

Dragging the user object from the System Tree

You can drag a user object from the System Tree to the Layout view in the Window painter.

What you can do

After you place a user object in a window or a custom visual user object, you can name it, size it, position it, write scripts for it, and do anything else you can do with a control.

When you place the user object in a window, PowerBuilder assigns it a unique name, just as it does when you place a control. The name is a concatenation of the default prefix for a user object control (initially, uo_) and a default suffix, which is a number that makes the name unique.

You should change the default suffix to a suffix that has meaning for the user object in your application.

For more information about naming, see Naming controls.

Writing scripts

When you place a user object in a window or a custom user object, you are actually creating a descendant of the user object. All scripts defined for the ancestor user object are inherited. You can choose to override or extend those scripts.

For more information, see Using inherited scripts.

You place a user object as a unit in a window (or another user object). You cannot write scripts for individual controls in a custom user object after placing it in a window or custom user object; you do that only when you are defining the user object itself.

Placing a user object at runtime

You can add a user object to a window at runtime using the PowerScript functions OpenUserObject and OpenUserObjectWithParm in a script. You can remove a user object from a window using the CloseUserObject function.

Using class user objects

How you insert a nonvisual object

There are two ways to use a class user object when the user object is not autoinstantiating: you can create an instance of it in a script, or you can insert the user object in a window or user object using the Insert menu.

For more information on autoinstantiation, see Using AutoInstantiate.

The nonvisual object you insert can be a custom class user object or a standard class user object of most types.

To instantiate a class user object

  1. In the window or user object in which you want to use the class user object, declare a variable of the user object type and create an instance of it using the CREATE statement. For example:

    // declared instance variable: 
    // n_myobject invo_myobject
    invo_myobject = CREATE n_myobject
  2. Use the user object's properties and functions to do the required processing.

  3. When you have finished using the user object, destroy it using the DESTROY statement.

    If you select Autoinstantiate in the properties of the class user object, you cannot use the CREATE and DESTROY statements.

To insert a class user object

  1. Open the window or user object in which you want to insert the class user object.

  2. Select Insert>Object from the menu bar.

  3. Select User Object (at the bottom of the list) and then select the class user object you want to insert.

    PowerBuilder inserts the selected class user object.

  4. Modify the properties and code the events of the nonvisual object as needed.

    When the user object is created in an application, the nonvisual object it contains is created automatically. When the user object is destroyed, the nonvisual object is destroyed automatically.

Using the Non-Visual Object List view

You can use the same technique to insert standard class user objects. Since all class user objects are nonvisual, you cannot see them, but if you look at the Non-Visual Object List view, you see all the class user objects that exist in your user object.

Using the Non-Visual Object List view's pop-up menu, you can display a class user object's properties in the Properties view, display the Script view for the object to code its behavior, or delete the object.

Using global standard class user objects

Five of the standard class user object types are inherited from predefined global objects used in all PowerBuilder applications:

  • Transaction (SQLCA)

  • DynamicDescriptionArea (SQLDA)

  • DynamicStagingArea (SQLSA)

  • Error

  • Message

Replacing the built-in global object

If you want your standard class user object to replace the built-in global object, you tell PowerBuilder to use your user object instead of the built-in system object that it inherits from. You will probably use this technique if you have built a user object inheriting from the Error or Message object.

To replace the built-in global object with a standard class user object

  1. Open the Application object.

  2. In the Properties view, click the Additional Properties button on the General tab page.

  3. In the Application properties dialog box, select the Variable Types tab.

  4. Specify the standard class user object you defined in the corresponding field and click OK.


    After you have specified your user object as the default global object, it replaces the built-in object and is created automatically when the application starts up. You do not create it (or destroy it) yourself.

    The properties and functions defined in the user object are available anywhere in the application. Reference them using dot notation, just as you access those of other PowerBuilder objects such as windows.

Supplementing the built-in global object

You can use a user object inherited from one of these global objects by inserting one in your user object as described in Using class user objects. If you do, your user object is used in addition to the built-in global object variable. Typically you use this technique with user objects inherited from the Transaction object. You now have access to two Transaction objects: the built-in SQLCA and the one you defined.

For more information

For more information about using the Error object, see Using the Error object.

For information about using the Message object, and about creating your own Transaction object to support database remote procedure calls, see the section called “The Message object” in Application Techniques and the section called “Using Transaction objects to call stored procedures” in Application Techniques.

For more information about the DynamicDescriptionArea and DynamicStagingArea objects used in dynamic SQL, see the section called “Using dynamic SQL” in PowerScript Reference.

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:

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:

  1. Define a public, user object-level function that takes as arguments the information needed from the window.

  2. Place the user object in the window.

  3. 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:

  1. Define a public, window-level function that takes as parameters the information needed from the user object.

  2. Place the user object in the window.

  3. 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:

  1. In the User Object painter, select the user object.

  2. Make sure no control in the user object is selected.

  3. In the Event List view, select Add from the pop-up menu.

  4. In the Prototype window that displays, define the user event.

    For how to do so, see Defining user events.

  5. 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.

  6. Implement these user events in the Window painter.

To implement the user event in the window:

  1. Open the window.

    In the Window painter, select Insert>Control from the menu bar and place the custom visual user object in the window.

  2. 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

  1. 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.

  2. 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

  3. 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.

  4. Write scripts for the two buttons:

    cb_max: mywin.WindowState = Maximized!

    cb_min: mywin.WindowState = Minimized!

  5. Save the user object as uo_minmax and close the User Object painter.

  6. Open the window, drag uo_minmax onto the window in the Layout view, and name it uo_func in the Properties view.

  7. 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.

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()

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.