Creating and using a visual extension

In general, you follow the same steps to create and use a visual extension that you do to create a nonvisual extension:

Step 1: Decide on a feature to implement.

Step 2: Define the classes and functions in the extension.

Step 3: Declare visual classes and global functions.

Step 4: Implement native classes.

Step 5: Export methods to create class instances.

Step 6: Build and use a PBX.

Step 7: Use the visual extension in an application.

Using PowerBuilder visual objects in C++

For information about using PowerBuilder visual objects from a C++ application, see Processing PowerBuilder messages in C++.

Step 1: Decide on a feature to implement

You can choose to use visual extensions to implement controls with a specific purpose or that use a custom look and feel. For some examples of visual extensions, see the PowerBuilder Code Samples Web site at https://www.appeon.com/developers/library/code-samples-for-pb.

Step 2: Define the classes and functions in the extension

The description for a visual class follows the same rules as for a nonvisual class, but it must inherit from the UserObject system class:

PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
{
   static const TCHAR desc[] = {
      "class myvisualext from userobject\n"
      "subroutine func_1(int arg1, int arg2)\n"
      "subroutine func_2(string arga)\n"
      "end class\n" 
   };
return desc;
}

There are no events in the preceding example, but a typical visual extension makes use of events such as mouse clicks. There are two ways to declare and handle events. See Event processing in visual extensions.

Step 3: Declare visual classes and global functions

You declare native visual classes in the same way as nonvisual classes, except that you declare an ANSI C++ class that inherits from IPBX_VisualObject, which is the ancestor class for all nonvisual PowerBuilder native classes, instead of from IPBX_NonVisualObject. You can also declare global functions in a visual extension. See Step 3: Declare native classes and global functions in the section on nonvisual extensions.

Step 4: Implement native classes

You implement Invoke and Destroy methods and any class or global functions the same way for visual extensions as for nonvisual extensions. See Step 4: Implement native classes and global functions.

Step 5: Export methods to create class instances

The major difference between visual and nonvisual extensions is in how instances of the class are created. See Creating visual class instances.

Step 6: Build and use a PBX

As for nonvisual extensions, you must build a PBX, import it into the application, and put the PBX in the execution path. See Step 6: Build a PBX  and Adding an extension to a PowerBuilder target in the section on nonvisual extensions.

Step 7: Use the visual extension in an application

You do not need to declare an instance of a visual class or use the CREATE statement to create an instance. The PBVM creates an instance when the window or visual control in which the visual class resides is opened, as described in Creating visual class instances. You can invoke the object's functions the same way that you invoke a nonvisual object's functions.

To use a visual extension:

  1. Select File>Inherit from the PowerBuilder menu and select the PBD in the Libraries list in the Inherit from Object dialog box.

  2. Select the visual class and click OK.

  3. In the User Object painter, size the visual object and make any other changes you need.

  4. Save the object.

You can now drag the new user object from the System Tree directly onto a window or onto another visual control, such as a tab control, and use it like any other visual user object.

Code samples

The code fragments in the rest of this section are based on complete sample applications that you can find on the PowerBuilder Code Samples Web site at https://www.appeon.com/developers/library/code-samples-for-pb.