Directives 

Formats

Where:

Description

The DEF OBJECT directive is used to create a new instance of a specified external control. It can be used to create a COM, .NET or *Browser control.

Upon successful execution of DEF OBJECT, a reference to the object objDef$ will be placed into the supplied numeric variable ext_id.

Note:
WindX in PxPlus supports the use of this directive via the [WDX] or [LCL] tags; e.g. DEF OBJECT "[WDX]somefile.ext". Non-PxPlus versions require you to encapsulate the command in an EXECUTE directive with a [WDX] tag (i.e. EXECUTE "[WDX]..."). See [WDX] Direct Action to Client Machine or [LCL] Access to Users Local Machine.

For COM objects, this is done through the PxPlus Event Handling interface and Component Object Model (COM), an industry-standard technology used by applications to expose methods, properties and events to development tools, macro languages and other applications. See Automation in PxPlus.

Using .NET Objects

Once you define a .NET object, you can use it like any PxPlus object through properties, methods and events.

Important Note:
All formats are Windows only, and you must have installed Windows Desktop Runtime 8.

If using 64-bit PxPlus, you must have the x64 Runtime installed. If using 32-bit PxPlus, you must have the x86 Runtime installed.

The .NET interface can be used when running under WindX, in which case, Windows Desktop Runtime 8 must be installed on client machines.

The following How To Tutorials provide detailed steps on how to create .NET Button and Calendar objects:

How to Create a .NET Button (Program)
How to Create a .NET Calendar Control (Program)

(.NET support was added in PxPlus 2025.)

You can list the properties and methods via:

print ext_id'*

You can access the properties and methods of the object using the ' (apostrophe operator):

ext_id'prop$="foxtrot"
ext_id'doMethod$()

Note:
Attempting to access properties and methods that have the same name as one of the PxPlus system variables or functions, such as DAY or LOG(), will result in a syntax error.

To avoid this syntax error and access these properties and methods, prefix the property or method name with NotPvx_.

Examples:

ext_id'NotPvx_Day=12

ext_id'NotPvx_Log("foxtrot")

The .NET objects also define several extended properties:

You can/should drop/delete any .NET objects once they are no longer needed to free up resources (ctls/memory):

drop object ext_id
delete object ext_id

Note:
If returning a .NET object via a property or method, you should save the handle/ctl so you can drop/delete it when it is no longer needed.

This is true even if creating the .NET object just to pass it in as an argument to another object.

Events can be subscribed to and unsubscribed to via ON EVENT, just like COM and *Browser. All .NET events have two arguments, sender and evtArgs, where sender is the .NET object that triggered the event while evtArgs is a .NET object that contains additional event arguments, if needed. What these are exactly will depend on the .NET object, and you can use the .NET objects documentation to find out details about specific events, evtArgs. Event arguments are supported only when handling events via a class.

Everything in .NET is an object, even numbers and strings. When passing in arguments to create an object or to call a method, and when setting properties, PxPlus will automatically convert a PxPlus number to a .NET Int16, UInt16, Int32, UInt32, Int64, UInt64, or Double object, and a PxPlus string to a .NET String, Char, Char[], Byte, Bye[], SByte, or SByte[] object, and a PxPlus 0 or 1 to a .NET Boolean object. What the PxPlus number or string gets converted to depends on the .NET property or argument type. Other .NET property or argument types are not converted, and you need to use a .NET object handle. When setting a property of a non-converted type or when passing in an argument via DEF OBJECT or a method call, use the PvxHandle $ property of a PxPlus .NET object. See PvxHandle$ for examples.

The return value of a property or method is also automatically converted where .NET Int16, UInt16, Int32, UInt32, Int64, UInt64, or Double objects are converted to PxPlus numbers, .NET String, Char, Char[], Byte, Bye[], SByte, or SByte[] objects are converted to PxPlus strings, and a .NET Boolean object is converted to a 0 or 1. Other types are not converted and are returned to PxPlus as a handle/ctl to the.NET object, which can then be used the same as the originally created .NET object.

In .NET, enumerator objects are common. Enumerators allow you to have a pre-set list of named values that a property can be set to. PxPlus treats the enumerator as a .NET object. The enumerator object will have properties for each of the named values. These properties return their own enumerator object set to that named value. The enumerator object is set to a specific named value via the value_ property with a numeric representation of which named enumerator it is. If you know the numeric value for the named enumerator type you want, you can set the value_ property directly.

Note:
Care should be taken to give returned enumerator objects handles so you can drop/delete them when done.

     def object fontStyle,"[.NET]System.Drawing,System.Drawing.FontStyle"
     bold=fontStyle'Bold
     drop object fontStyle
     def object font,"[.NET]System.Drawing,System.Drawing.Font","Verdana",12,bold'PvxHandle$
     drop object bold
     …
     drop object font

In .NET, some objects are value type objects where each time you return the object, it will be a unique object. In this case, you cannot just access that value type object's properties or methods to change it and have the parent object changed. You must get a handle to a value type object, modify it, and then set the parent object property to the modified value type object. For example, enumerators are value type objects. You want to drop/delete these objects when finished with them.

In .NET, non-value type objects will return the same object each time they are accessed. You can access a non-value type object's properties and methods to change the behavior of the parent object. PxPlus will use the same ctl value each time you access these types of objects. You generally do not drop/delete these objects, as they are part of the parent object.

Static .NET classes are supported as well. A static class is a class with only static members, such as System.Math, which can be used to get constant values and perform operations on passed-in values but does not store any data. You do a DEF OBJECT on it the same as you would a .NET object and work with it in the same way.

Error messages are returned via MSG(-1).

Format 1

Define Invisible External Object

DEF OBJECT ext_id,objDef$[,arg_1[$],arg_2[$],…,arg_n[$]][,ERR=stmtref]

Use this format to create a link to an invisible external object (COM, .NET or *Browser). This format associates the object with the current window, yet it is hidden from view.

COM Example:

def object this_com_id,"Mabry.SoundX"

.NET Example:

def object this_ext_id,"[.NET]Newtonsoft.Json.dll,Newtonsoft.Json.JsonConvert"

Once the definition is complete, this_ext_id will contain a handle to the object. This handle will be used to get and set properties and methods and service events. Note that since the value returned in this_ext_id is a handle (memory pointer) to the object, it should not be changed by the application.

Format 2

Define Visible External Object

DEF OBJECT ext_id,@(col,ln,wth,ht ){,|=} objDef$[,arg_1[$],arg_2[$],…,arg_n[$]] [,ERR=stmtref]

This format defines a visible object and associates it with a location in the current window:

def object numvar,@(col,row,wide,high),"object_name",err=2000
def object numvar,@(col,row,wide,high)="object_name",err=2000

def object numvar,@(col,row,wide,high),"[.NET]dll_path,object_name",err=2000
def object numvar,@(col,row,wide,high)="[.NET]dll_path,object_name",err=2000

For graphical .NET controls, a .NET form is created, and the .NET control requested is added to it. The form is then embedded at the coordinates given in the DEF OBJECT directive. The .NET control is positioned at the top left of the .NET form and given the same width and height as the form. The end result is that you see only your .NET control embedded in the PxPlus screen. You can, however, change the position and size of the control within a .NET frame, if needed. You may want to do this if the form supports menus, for example, where you can position the control lower in the frame and shorten the height to make room for the menu.

The position and size of the .NET frame is controlled via the following properties: PvxCol, PvxCols, PvxLine, PvxLines, PvxLeft, PvxTop, PvxHeight and PvxWidth. The position and size of the .NET control within the .NET form is controlled via the .NET object properties Left, Top, Height, Width, Bottom and Right.

When moving and/or resizing the .NET container form control via the Pvxnnnnn properties, the size of the .NET control will be moved and/or resized as well. If the position/size of the .NET control was modified to be different from the form, then that difference will be maintained when moving/resizing. For example, if you moved the .NET control lower and made it shorter than the form to fit a menu, and then you move and/or resize the form, the space created at the top for the menu will be kept intact.

Example:

def object pdf,@(80,2,100,65),"[.NET]C:\Program Files\DevExpress 24.2\Components\Bin\NetCore\DevExpress.XtraPdfViewer.v24.2.dll,DevExpress.XtraPdfViewer.PdfViewer"
pdf'Top=150
pdf'Height=pdf'Height-150
pdf'CreateRibbon()
pdf'LoadDocument(path_to_pdf$)

Note:
Only WinForms graphical .NET controls are supported.

Format 3

List Available COM Objects

DEF OBJECT ext_id, "*" [,ERR=stmtref]

Use this format to display a pop-up window listing the COM controls currently installed on the system.

Examples

COM Examples:

def object X,"*"

def object X,"Word.Application",err=*next

def object X,@(1,1,70,20)="Word.Document"

def object X,"[dcom]MyServer;Shell.Explorer"

def object X,@(10,2,20,10)="[file]c:\y documents\test.doc"

def object X,"VCF1.VCF1Ctrl.1;License=8041207972768742028669631967"

def object X,"[running or new]Excel.Application"

.NET Examples:

def object mathDotNet,"[.NET]mscorlib,System.Math"

def object devExpressGrid,@(80,1,50,20),"[.NET]C:\Program Files\DevExpress 24.2\Components\Bin\NetCore\DevExpress.XtraGrid.v24.2.dll,DevExpress.XtraGrid.GridControl"

def object font,"[.NET]System.Drawing,System.Drawing.Font","Verdana",12,fontStyle'PvxHandle$,err=bad_font

def object calendarDotNet,@(100,10,30,20),"[.NET]System.Windows.Forms,System.Windows.Forms.MonthCalendar"

See Also

DELETE OBJECT Remove Object
ON EVENT Event Processing
Apostrophe Operator
Automation in PxPlus
External Controls - *Browser, ActiveX (COM), PVX Plus, .NET
How To Tutorials (for .NET Interface)