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 aren’t 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.

   You can declare functions, structures, and variables for the
   user object in the Script view.

2. Create and compile scripts for the user object.

   Custom class user objects have 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:

1. In the Properties view, select the AutoInstantiate
   checkbox.

   

For more information about autoinstantiation,
see the PowerScript Reference.

Using the EAServer Project property

In the Properties view, if you specify an EAServer project
that will be used to generate an EAServer component (a custom class
user object with the characteristics needed for deployment to EAServer),
live editing is enabled. When live editing is enabled in the User
Object painter, PowerBuilder builds the project for an EAServer component
each time you save the user object.

For information about EAServer components and live editing,
see Application Techniques
.

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.

   You can declare these in the Script view.

   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 needed user events 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 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.

The procedure for building a custom visual user object is
similar to the process of building a window, described in Chapter 10, “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
     You can declare these in the Script view.
   • Declare any needed events 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 textbox.

   

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 only be displayed if the object has a text style
     property.
   • Display properties (border and scrollbars)
   • 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 needed user events 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

Custom class user objects have only constructor and destructor
events.

Event	Occurs
Constructor	When the user object is created
Destructor	When the user object is destroyed

Additional events are created for some of the specialized
custom class user objects that you create using the wizards at the
bottom of PB Object page in the New dialog box. For more information,
see Application Techniques
.

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

Saving a custom class or standard class user object In the User Object painter for a custom class user object,
the Design menu has Jaguar Validation and COM/MTS Validation
menu items. If you are saving a Jaguar component or a COM/MTS
component and you check the validation menu item for the component
to enable validation, a check displays next to the menu item. When
you save the object, you may see some error messages.

For information about Jaguar validation and
COM/MTS validation, see Application Techniques
.

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

Recommended naming convention

You should adopt naming conventions to make it easy to understand
a user object’s type and purpose. Here is a convention
you could follow.

Use u_ as the prefix for all user objects and apply
the prefix for the various types of user objects as follows:

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	u_systemobject_purpose	u_trans_test, derived from the Transaction object and used for testing
Custom class	u_cust_purpose	u_cust_commission, calculates commissions

---