PowerBuilder Native Interface Programmers Guide and Reference
Programmers Guide

In this example, the C++ code is in three files:

To use the PowerBuilder native class in a PowerBuilder application, import the object descriptions in the PBX file into a library in your application.

The application runs just as it would if you had created a custom class user object in PowerBuilder with an f_add function. If PowerBuilder cannot find pbadd.pbx, the runtime error in the Clicked event script will be triggered and caught. Put pbadd.pbx in the same directory as the executable or the PowerBuilder runtime DLLs to make sure it can be found.

The first step in building a PowerBuilder extension is to identify a problem that an extension can solve. This might be a feature that can be coded more efficiently and easily in C++ than in PowerScript, or that requires the use of callback functions or nonstandard datatypes. You might also have access to existing C++ classes that perform the tasks you want to add to a PowerBuilder application, or you might want to create a wrapper for existing standard utilities written in C++.

For possible uses of PowerBuilder extensions, see Understanding PowerBuilder extensions.

For examples of PowerBuilder extensions, see the PowerBuilder Code Samples website at https://www.appeon.com/developers/library/code-samples-for-pb.

Your C++ code must expose two standard methods that enable PowerBuilder to recognize each native class and create instances of the class. One of these methods is PBX_GetDescription.

Use PBX_GetDescription to pass the descriptions of classes and global functions in the PowerBuilder extension to PowerBuilder. Every extension must export this method. Importing the PBX or DLL file into a PBL converts the description of the extension into PowerScript and adds it to the PBL as source code. The keyword native in the source code indicates that the PowerBuilder type was defined in an extension.

All the classes or global functions in an extension module are passed in a single description. The examples that follow illustrate how you define classes and functions in a description. For the full syntax, see PBX_GetDescription.

Describing nonvisual classes

Nonvisual classes can inherit from the NonVisualObject PowerBuilder system class or any of its descendants. While a native class can inherit from a user-defined user object, Appeon recommends that you use only system classes. Each native class can provide several functions, subroutines, and events.

The following example shows how you use the PBX_GetDescription method in the C++ code for an extension that includes three nonvisual classes. ClassName1 inherits from NonVisualObject, ClassName2 inherits from Exception, and ClassName3 inherits from Transaction. All three classes must be in a single description passed by PBX_GetDescription:

PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
{
  static const TCHAR desc[] = {
   // Description begins here
   "class ClassName1 from NonVisualObject\n"
    "function integer objectFunction(integer a[])\n"
    "subroutine objectSubroutine(integer ai_ref)\n"
    "event integer eventName(integer b)\n"
    "end class\n"

    "class ClassName2 from Exception\n"
    "function integer objectFunction(readonly 
       integer ai)\n"
    "subroutine objectSubroutine(integer arg)\n"
    "event integer eventName(integer arg)\n"
    "end class\n"

    "class ClassName3 from Transaction\n"
    "function integer objectFunction(integer arg)\n"
    "subroutine objectSubroutine(integer arg)\n"
    "event integer eventName(integer arg)\n"
    "end class\n"
    // Description ends here
  };
  return desc;
}

Describing visual classes

Visual native classes can inherit only from the UserObject PowerBuilder system class. The PowerBuilder VM considers any class that inherits from UserObject to be a visual class. All other native classes are considered to be nonvisual classes. For more information about how to describe visual classes, see Creating and using a visual extension.

Describing global functions

An extension can include global functions as well as classes. This example shows a description for two global functions:

"globalfunctions \n" \
"function int g_1(int a, int b)\n" \
"function long g_2(long a, long b)\n" \
"end globalfunctions\n"

The syntax and usage of global functions defined in an extension are the same as for global functions defined in the Function painter in PowerBuilder.

Using forward declarations

PowerBuilder extensions can provide multiple classes. A class can reference any class that is defined earlier in the description, but if it references a class defined later in the description, you must provide a forward declaration. This example shows a description that includes forward declarations for two classes, nativeclass_1 and nativeclass_2, that reference each other. This example also demonstrates that a single description can include global functions as well as classes:

"forward\n" \
"class nativeclass_1 from nonvisualobject\n"\
"class nativeclass_2 from nonvisualobject\n"\
"end forward\n" \

"class nativeclass_1 from nonvisualobject \n" \
"function int add(nativeclass_2 a, int b)\n" \
"function int sub(int a, int b)\n" \
"end class \n" \

"class nativeclass_2 from nonvisualobject \n" \
"function int add(nativeclass_1 a, int b)\n" \
"function int sub(int a, int b)\n" \
"end class \n"

"globalfunctions \n" \
"function int g_1(int a, int b)\n" \
"function long g_2(long a, long b)\n" \
"end globalfunctions\n"

For each native class that the nonvisual extension supports, declare an ANSI C++ class that inherits from IPBX_NonVisualObject, which is the ancestor class for all nonvisual PowerBuilder native classes.

The declaration of the class can be placed in a header file, and it must include Invoke and Destroy methods. This is a simple prototype for a nonvisual class:

#include "pbext.h"

class CMyClass : public IPBX_NonVisualObject
{
enum MethodIDs
{
   mFunca = 0,
   mFuncb = 1
};
public:
   // constructor, destructor
   CMyClass()
   virtual ~CMyClass()
   // member methods   PBXRESULT Invoke(
      IPB_Session   *session, 
      pbobject   obj, 
      pbmethodID   mid,
      PBCallInfo   *ci
   );
   void Destroy();

private:
   void funcA(IPB_Session* session, pbobject obj,
       PBCallInfo* ci);
   void funcB(IPB_Session* session, pbobject obj,
       PBCallInfo* ci);
};

If you declare global functions in your extension, the extension must export the PBX_InvokeGlobalFunction method. The following PBX_GetDescription call declares three global functions: bitAnd, bitOr, and bitXor:

PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
{
   static const TCHAR desc[] = {
      "globalfunctions\n"
      "function int bitAnd(int a, int b)\n"
      "function int bitOr(int a, int b)\n"
      "function int bitXor(int a, int b)\n"
      "end globalfunctions\n"
   };

  return desc;
}

The implementation of each class must include the implementation of the Invoke and Destroy methods, as well as all the methods declared for the class. Invoke and Destroy are methods of the IPBX_UserObject interface.

When the PowerBuilder application calls a method on the native class, the PBVM calls the Invoke method, which dispatches the call based on the method ID or method name. The method name is used when the method is called dynamically.

The Invoke method must be coded to invoke each method in the class. The example that follows shows a switch-case statement that invokes either funcA or funcB, depending on the value of the method ID. When the PowerBuilder application has finished using an instance of a native class, the PBVM calls the Destroy method.

This example does not show the implementation of the methods of the class itself:

PBXRESULT MyClass::Invoke(IPB_Session *session, pbobject obj, pbmethodID mid, PBCallInfo *ci)
{
   PBXRESULT result = PBX_OK;

   switch (mid)
   {
   case mFunca:
      result = funcA(session, obj, ci);
      break;

   case mFuncb:
      result = funcB(session, obj, ci);
      break;

   default:
      result = PBX_E_INVOKE_FAILURE;
      break;
   }

   return result;
}
// Implementation of funcA and funcB not shown
void Destroy()
   {
      delete this;
}

The following PBX_InvokeGlobalFunction contains the implementation of the three global functions included in the description shown in Step 3: Declare native classes and global functions:

PBXEXPORT PBXRESULT PBXCALL PBX_InvokeGlobalFunction
(
   IPB_Session*   pbsession,
   LPCTSTR        functionName,
   PBCallInfo*    ci   )
{

  PBXRESULT pbrResult = PBX_OK;

  int arg1 = ci->pArgs->GetAt(0)->GetInt();
  int arg2 = ci->pArgs->GetAt(1)->GetInt();

  if (stricmp(functionName, "bitand") == 0)
  {
     ci->returnValue->SetInt(arg1 & arg2);
  }else if (strcmp(functionName, "bitor") == 0)
  {
     ci->returnValue->SetInt(arg1 | arg2);
  }else if (strcmp(functionName, "bitxor") == 0)
  {
     ci->returnValue->SetInt(arg1 ^ arg2);
  }else
  {
     return PBX_FAIL;
  }

  return pbrResult;
}

PowerBuilder creates nonvisual and visual class instances differently:

When the PowerBuilder application creates an instance of a nonvisual class using the PowerScript CREATE statement, the PBVM calls the PBX_CreateNonVisualObject method in the extension. Every extension that contains nonvisual native classes must export this method.

In the same way that multiple classes are included in a single description passed by PBX_GetDescription, PBX_CreateNonVisualObject can be used to create multiple classes.

In this example, the extension has three classes. An IF statement compares the name of the class passed in from the PowerBuilder CREATE statement to the name of each of the classes in the extension in turn and creates an instance of the first class with a matching name. You could also use a CASE statement. The class name in the string comparison must be all lowercase:

PBXEXPORT PBXRESULT PBXCALL PBX_CreateNonVisualObject(
   IPB_Session * session, 
   pbobject obj, 
   LPCSTR className, 
   IPBX_NonVisualObject **nvobj
)
{
   PBXRESULT result = PBX_OK;
   // The class name must not contain uppercase
   if ( strcmp( className, "classone" ) == 0 )
      *nvobj = new ClassOne;
   else if ( strcmp( className, "classtwo" ) == 0 )
      *nvobj = new ClassTwo( session );
   else if ( strcmp( className, "classthree" ) == 0 )
      *nvobj = new ClassThree;
   else   {
      *nvobj = NULL;
      result = PBX_E_NO_SUCH_CLASS;
   }
   return PBX_OK;
};

Using your C++ development tool or the command line, build a PBX from your C++ classes.

When you compile and link the C++ code, verify the following:

Now you are ready to use the extension in a PowerBuilder application.

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 website at https://www.appeon.com/developers/library/code-samples-for-pb.

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.

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.

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.

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

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.

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.

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.

The following description uses the first syntax. The class has two events, onclick and ondoubleclick:

PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
{
   static const TCHAR desc[] = {
      "class visualext from userobject\n"
      "event int onclick()\n"
      "event int ondoubleclick()\n"
      "subroutine setcolor(int r, int g, int b)\n"
      "subroutine settext(string txt)\n"
      "end class\n" 
   };
return desc;
}

Capturing messages and mouse clicks

The code in the extension captures the Windows messages that cause the window to be drawn, as well as mouse clicks and double clicks:

LRESULT CALLBACK CVisualExt::WindowProc(
                                   HWND hwnd,
                                   UINT uMsg,
                                   WPARAM wParam,
                                   LPARAM lParam
                                   )
{
   CVisualExt* ext = (CVisualExt*)::GetWindowLong(hwnd,
      GWL_USERDATA);
   switch(uMsg) {

   case WM_CREATE:
      return 0;

   case WM_SIZE:
      return 0;

   case WM_COMMAND:
      return 0;

   case WM_PAINT: {
      PAINTSTRUCT ps;
      HDC hdc = BeginPaint(hwnd, &ps);
      RECT rc;
      GetClientRect(hwnd, &rc);
      LOGBRUSH lb;
      lb.lbStyle = BS_SOLID;
 
// Get color using the visual class's GetColor method
      lb.lbColor = ext->GetColor();
      HBRUSH hbrush = CreateBrushIndirect(&lb);
      HBRUSH hbrOld = (HBRUSH)SelectObject(hdc,
         hbrush);
      Rectangle(hdc, rc.left, rc.top, rc.right-rc.left,
         rc.bottom-rc.top);
      SelectObject(hdc, hbrOld);
      DeleteObject(hbrush);


// Get text using the visual class's GetText method
      DrawText(hdc, ext->GetText(), 
         ext->GetTextLength(), &rc, 
      DT_CENTER|DT_VCENTER|DT_SINGLELINE);
      EndPaint(hwnd, &ps);
      }
      return 0;

// Trigger event scripts in the PowerBuilder application
   case WM_LBUTTONUP:
      ext->TriggerEvent("onclick");
      break;

   case WM_LBUTTONDBLCLK:
      ext->TriggerEvent("ondoubleclick");
      break;
   }
   return DefWindowProc(hwnd, uMsg, wParam, lParam);
}

Triggering click events

The following is the TriggerEvent method that triggers the Onclick and Ondoubleclick events:

void CVisualExt::TriggerEvent(LPCTSTR eventName)
{
   pbclass clz = d_session->GetClass(d_pbobj);
   pbmethodID mid = d_session->GetMethodID(clz,
      eventName, PBRT_EVENT, "I");

   PBCallInfo ci;
   d_session->InitCallInfo(clz, mid, &ci);
   d_session->TriggerEvent(d_pbobj, mid, &ci);
   d_session->FreeCallInfo(&ci);
}

A simpler way to trigger events in a visual extension uses direct mapping of Windows messages to PowerBuilder events. The following class description contains the same two events, but in this case they use the alternative syntax that maps the event name to a PowerBuilder token name:

PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
{
   static const TCHAR desc[] = {
      "class visualext from userobject\n"
      "event onclick pbm_lbuttonup\n"
      "event ondoubleclick pbm_lbuttondblclk\n"
      "subroutine setcolor(int r, int g, int b)\n"
      "subroutine settext(string txt)\n"
      "end class\n" 
   };
return desc;
}

Generating event syntax automatically

Importing the extension generates the Onclick and Ondoubleclick events with the appropriate arguments automatically, and at runtime, the PBVM fires the events. You do not need to capture the Windows messages WM_LBUTTONUP and WM_LBUTTONDBLCLK in the extension.

In the following description, onclick is the event name and pbm_lbuttonup is the event token name. Notice that the event name is not followed by empty parentheses as it is when you use the return type and arguments technique for describing the event:

 "event onclick pbm_lbuttonup\n"

About the token name

The token name is a string that maps to an internal PowerBuilder event ID defined in the header file pbevtid.h. The first ID in this file is PB_NULL. For all other IDs in the file, there is a fixed relationship between the name that you use in the description and the event ID in pbevtid.h. The name is the same as the ID with the letter m appended to the pb prefix. You must use lowercase in the description.

For example, the event ID PB_ACTIVATE in pbevtid.h maps to the token name pbm_activate. In the description provided with PBX_GetDescription, you must use the name pbm_activate. If the event name you provide does not exist, importing the extension generates an error message. See the pbevtid.h file for a complete list of mapped IDs.

Some Windows messages, such as WM_COMMAND and WM_NOTIFY, are sent to the parent of an object and not to the object itself. Such messages cannot be caught in the visual extension's window procedure. The PBVM calls the GetEventID method to process these messages, as follows:

In the following example, the GetEventID function returns the identifier PB_BNCLICKED if a WM_COMMAND message with the notification code BN_CLICKED was sent. It returns the identifier PB_ENCHANGE if a WM_NOTIFY message was sent. Otherwise, it returns PB_NULL.

TCHAR CVisualExt::s_className[] = "PBVisualExt";

LPCTSTR CVisualExt::GetWindowClassName()
{
  return s_className;
}

HWND CVisualExt::CreateControl
(
  DWORD dwExStyle,      // extended window style
  LPCTSTR lpWindowName, // window name
  DWORD dwStyle,        // window style
  int x,               // horizontal position of window
  int y,            // vertical position of window
  int nWidth,       // window width
  int nHeight,      // window height
  HWND hWndParent,  // handle of parent or owner window
  HINSTANCE hInstance // handle of application instance
)
{
  d_hwnd = CreateWindowEx(dwExStyle, s_className,
    lpWindowName, dwStyle, x, y, nWidth, nHeight,
    hWndParent, NULL, hInstance, NULL);

  ::SetWindowLong(d_hwnd, GWL_USERDATA, (LONG)this);

  return d_hwnd;
}

int CVisualExt::GetEventID(
   HWND    hWnd,     /* Handle of parent window */
   UINT    iMsg,     /* Message sent to parent window*/
   WPARAM  wParam,   /* Word parameter of message*/
   LPARAM  lParam    /* Long parameter of message*/
  )
{
  if (iMsg == WM_COMMAND)
  {
    if ((HWND)lParam == d_hwnd)
    {
      switch(HIWORD(wParam))
      {
      case BN_CLICKED:
        return PB_BNCLICKED;
        break;
      }
    }
  }

  if (iMsg == WM_NOTIFY)
  {
    return PB_ENCHANGE;
  }
  return PB_NULL;
}

In this code fragment, the class and method ID returned by calls to the IPB_Session GetClass and GetMethodID methods are used to initialize a PBCallInfo structure, called ci, using the IPB_Session InitCallInfo method.

After a new pbstring variable is created, the value of that string is set to the value of the first argument in the PBCallInfo structure.

BOOL CALLBACK CFontEnumerator::EnumFontProc
(
   LPLOGFONT lplf, 
   LPNEWTEXTMETRIC lpntm, 
   DWORD FontType, 
   LPVOID userData
)
{
   UserData* ud = (UserData*)userData;
   pbclass clz = ud->session->GetClass(ud->object);
   pbmethodID mid = ud->session->GetMethodID
      (clz, "onnewfont", PBRT_EVENT, "IS");

   PBCallInfo ci;
   ud->session->InitCallInfo(clz, mid, &ci);

// create a new string variable and set its value
// to the value in the first argument in the 
// PBCallInfo structure
   pbstring str = ud->session->NewString
      (lplf->lfFaceName);
   ci.pArgs->GetAt(0)->SetString(str);

   ud->session->TriggerEvent(ud->object, mid, &ci);
   pbint ret = ci.returnValue->GetInt();

   ud->session->FreeCallInfo(&ci);
   return ret == 1 ? TRUE : FALSE;
}