The following table lists methods that must be implemented in the PowerBuilder extension module when the conditions shown in the table apply. The methods are described after the table. The PBX_GetVersion method is used by PowerBuilder to determine whether the compiler macro UNICODE or _UNICODE has been set. It is for internal use only.
Method |
Required |
|---|---|
When the extension contains nonvisual native classes |
|
When the extension contains visual native classes |
|
When you want to be able to draw a visual representation of the visual object in the PowerBuilder development environment |
|
In all extensions |
|
When the extension contains global functions |
|
When you need to initialize and uninitialize a session |
Creates a new instance of a nonvisual PowerBuilder extension object.
PBX_CreateNonVisualObject(IPB_Session* pbsession, pbobject pbobj, LPCTSTR xtraName, IPBX_NonVisualObject **obj)·
Argument |
Description |
|---|---|
pbsession |
This IPB session |
pbobj |
The name of a pbobject corresponding to the PowerBuilder extension object to be created |
xtraname |
The name of the PowerBuilder native class in lowercase |
obj |
The PowerBuilder extension object to be created |
PBXRESULT. PBX_OK for success.
In this example, the extension contains several classes. The object created depends on the string value of the class name passed in.
PBXEXPORT PBXRESULT PBXCALL PBX_CreateNonVisualObject
(
IPB_Session* pbsession,
pbobject pbobj,
LPCTSTR xtraName,
IPBX_NonVisualObject **obj
)
{
PBXRESULT result = PBX_OK;
string cn(className);
if (cn.compare("class_a") == 0)
{
*obj = new class_a(pbobj);
}
else if (cn.compare("class_b") == 0)
{
*obj = new class_b(pbobj);
}
else if (cn.compare("class_c") == 0)
{
*obj = new class_b(pbobj);
else
{
*obj = NULL;
result = PBX_E_NO_SUCH_CLASS;
}
return PBX_OK;
};
You must implement this method in every PowerBuilder extension module that contains nonvisual classes. When you use the CREATE statement in PowerScript to create a new PowerBuilder extension object, the PBVM calls this method.
Creates a new instance of a visual PowerBuilder extension object.
PBX_CreateVisualObject(IPB_Session* pbsession, pbobject pbobj, LPCTSTR xtraName, IPBX_NonVisualObject **obj)·
Argument |
Description |
|---|---|
pbsession |
This IPB session |
pbobj |
The name of a pbobject corresponding to the PowerBuilder extension object to be created |
xtraname |
The name of the PowerBuilder native class in lowercase |
obj |
The PowerBuilder extension object to be created |
PBXRESULT. PBX_OK for success.
In this example the extension contains several classes. The object created depends on the string value of the class name passed in.
PBXEXPORT PBXRESULT PBXCALL PBX_CreateVisualObject
(
IPB_Session* pbsession,
pbobject pbobj,
LPCTSTR className,
IPBX_VisualObject **obj
)
{
PBXRESULT result = PBX_OK;
string cn(className);
if (cn.compare("visualext") == 0)
{
*obj = new CVisualExt(pbsession, pbobj);
}
else
{
*obj = NULL;
result = PBX_FAIL;
}
return PBX_OK;
};
You must implement this method in every PowerBuilder extension module that contains visual classes. When you use a visual extension in a PowerBuilder application, the PBVM calls this method.
Draws a visual object in the PowerBuilder development environment.
PBX_DrawVisualObject(HDC hDC, LPCTSTR className, const PBX_DrawItemStruct& property)·
Argument |
Description |
|---|---|
hDC |
A handle to the device context of the object |
classname |
The name of the visual extension object to be drawn |
property |
A PBX_DrawItemStruct structure specifying the display properties of the object |
PBXRESULT. The return value of this function is currently ignored.
This is an extension of a sample that is available on the PowerBuilder CodeXchange Web site. It draws a representation of a light-emitting diode (LED) and uses Microsoft Foundation Classes (MFC):
PBXEXPORT PBXRESULT PBXCALL PBX_DrawVisualObject
(
HDC hDC,
LPCTSTR xtraName,
const PBX_DrawItemStruct& property
)
{
// If this PBX is dynamically linked against the MFC
// DLLs, any functions exported from this PBX that
// call into MFC must have the AFX_MANAGE_STATE macro
// added at the very beginning of the function.
AFX_MANAGE_STATE( AfxGetStaticModuleState() );
// Variables to hold the Led control and a pointer
// to Device Context
CLed *myLed;
CDC* pDC;
// The name must not contain uppercase letters
if ( strcmp( xtraName, "u_cpp_led" ) == 0 )
{
CRect rc( property.x, property.y, property.x +
property.width, property.y + property.height );
//Create a new LED
myLed = new CLed();
// Get the handle from the hDC
pDC = CDC::FromHandle(hDC);
CWnd* pWnd = pDC->GetWindow();
// Create the window
myLed->Create(NULL, WS_CHILD | WS_VISIBLE |
SS_BITMAP, rc, pWnd);
// Function that handles the background
// rendering of the control
myLed->OnEraseBkgndIDE(pDC);
// Draw the LED in default mode (red, on, round)
myLed->DrawLed(pDC,0,0,0);
myLed->SetLed(0,0,0);
//done
delete myLed;
}
return PBX_OK;
}
In a visual extension, export this function if you want the visual control to be drawn in the development environment. If you do not export the function, you need to run the application to see the appearance of the visual control.
Passes a description of all the classes and methods in the PowerBuilder extension module to PowerBuilder.
PBX_GetDescription ( )
LPCTSTR containing the description of the module.
The following extension module contains three classes:
PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
{
static const TCHAR desc[] = {
"class class_a from nonvisualobject\n"
"function long meth1(string classpath)\n"
"function string meth2()\n"
"end class\n"
"class class_b from nonvisualobject\n"
"subroutine sbrt1()\n"
"subroutine sbrt2()\n"
"function long func1()\n"
"end class\n"
"class class_c from nonvisualobject\n"
"end class\n"
};
return desc;
}
The following module contains a visual class that has two subroutines (functions that do not return values), two events that require that Windows messages be captured in the extension (onclick and ondoubleclick), and one event that maps a Windows message directly to a PowerBuilder event (testmouse). The module also contains two global functions, funca and funcb.
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"
"event testmouse pbm_mousemove \n"
"end class\n"
"globalfunctions\n"
"function int funca(int a, int b)\n"
"function int funcb(int a, int b)\n"
"end globalfunctions\n"
};
return desc;
}
You must implement this method in every PowerBuilder extension module. The method is exported from the PowerBuilder extension module and is used by PowerBuilder to display the prototype of each class, function, and event in the module.
The syntax of the description follows:
Multiple instances
A syntax element with an asterisk indicates that multiple
instances of that element can appear in a description. For example, [Desc]* indicates
that one description can contain multiple classes, global functions,
and forward declarations.
Desc ::= class_desc | globalfunc_desc | forward_desc | [Desc]*
class_desc ::= class className from parentClass newline [methods_desc]* end class newline
globalfunc_desc := globalfunctions newLine [func_desc]* end globalfunctions
forward_desc := forward newLine [forwardtype_desc]* end forward
forwardtype_desc := class className from parentClass newline
className ::= a PowerBuilder token (cannot duplicate an existing group name)
parentClass ::= any class inherited from NonVisualObject or UserObject
newline ::= a newline character
methods_desc ::= method_desc [methods_desc]*
method_desc ::= func_desc | sub_desc | event_desc
func_desc ::= function returnType funcName(args_desc) newline
returnType :: = pbType
pbType ::= any PowerBuilder type | previous declared PBNI class
funcName ::= a PowerBuilder token
args_desc ::= None | arg_desc, [args_desc]*
arg_desc ::= [ ref | readonly ] pbType argName [array_desc]
argName ::= a PowerBuilder token
array_desc ::= array declaration of PowerBuilder
sub_desc ::= subroutine subName(args_desc) newline
event_desc ::= event returnType eventName(args_desc) newline | event eventName pbevent_token newline
pbevent_token :: = string
This syntax for event_desc allows you to map a Windows message directly to a PowerBuilder event:
event eventName pbevent_token newline
For more information, see “Event processing in visual extensions”.
Contains the implementation of one or more global functions used in the PowerBuilder extension module.
PBX_InvokeGlobalFunction(IPB_Session* pbsession, LPCTSTR functionname, PBCallinfo* ci);
Argument |
Description |
|---|---|
pbsession |
This IPB session |
functionname |
The name of the global function |
ci |
A pointer to a preallocated PBCallInfo structure containing the parameters and return value setting for the function |
PBXRESULT. PBX_OK for success.
This 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 PBX_InvokeGlobalFunction call contains the implementation of the 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;
}
Use this function in a PowerBuilder native class that uses global functions. The function is exported from the PowerBuilder extension module and is used to identify global functions included in the module. Like global functions in PowerScript, global functions in PowerBuilder extensions cannot be overloaded.
Used to initialize and uninitialize a session.
PBXEXPORT PBXRESULT PBXCALL PBX_Notify(IPB_Session* pbsession, pbint reasonForCall)
PBXRESULT
This sample shows code that exports PBX_Notify and displays a message box after the PBX is loaded and before it is unloaded:
PBXEXPORT PBXRESULT PBXCALL PBX_Notify
(
IPB_Session* pbsession,
pbint reasonForCall
)
{
switch(reasonForCall)
{
case kAfterDllLoaded:
MessageBox(NULL, "After PBX loading", "",
MB_OK);
break;
case kBeforeDllUnloaded:
MessageBox(NULL, "Before PBX unloading", "",
MB_OK);
break;
}
return PBX_OK;
}
If PBX_NOTIFY is exported, the PBVM calls PBX_Notify immediately after an extension PBX is loaded and just before the PBX is unloaded. You can use this function to initialize and uninitialize a session. For example, you could create a session manager object, and store it in the IPB session using the SetProp function. Later, you could use GetProp to obtain the session object.
