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