Description
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_GetVersionmethod is used by PowerBuilder to determine whether the compiler macro UNICODE or _UNICODE has been set. It is for internal use only.
Methods
|
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 |
Description
Creates a new instance of a nonvisual PowerBuilder extension object.
Syntax
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 |
Return value
PBXRESULT. PBX_OK for success.
Examples
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;
};Usage
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.
See also
Description
Creates a new instance of a visual PowerBuilder extension object.
Syntax
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 |
Return value
PBXRESULT. PBX_OK for success.
Examples
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;
};Usage
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.
See also
Description
Draws a visual object in the PowerBuilder development environment.
Syntax
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 |
Return value
PBXRESULT. The return value of this function is currently ignored.
Examples
This is an extension of a sample that is available on the PowerBuilder Code Samples website at https://community.appeon.com/index.php/codeexchange/powerbuilder. 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;
}Usage
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.
See also
Description
Passes a description of all the classes and methods in the PowerBuilder extension module to PowerBuilder.
Syntax
PBX_GetDescription ( )
Return value
LPCTSTR containing the description of the module.
Examples
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;
}Usage
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_tokennewline
For more information, see Event processing in visual extensions.
See also
Description
Contains the implementation of one or more global functions used in the PowerBuilder extension module.
Syntax
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 |
Return value
PBXRESULT. PBX_OK for success.
Examples
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;
}Usage
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.
See also
Description
Used to initialize and uninitialize a session.
Syntax
PBXEXPORT PBXRESULT PBXCALL PBX_Notify(IPB_Session* pbsession,pbint reasonForCall)
Return value
PBXRESULT
Examples
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;
}Usage
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.
