Creating Panel Controls

COM Control

The PxPlus COM Control Properties dialogue allows you to integrate external components produced by third-party vendors into your MS Windows-based PxPlus application (e.g. progress bar, spreadsheet, browser or calendar). This dialogue is used to obtain information about, as well as access to, the internal properties and methods of the Component Object Model (COM) control being used. These types of controls are now typically based on Windows ActiveX vs. the older OLE control technology (OCX).

Note:
A new Chromium Browser Object has been added that allows you to embed a Chromium Browser into PxPlus windows. This object can be used to display a Web page, execute JavaScript, and subscribe to browser events. The Chromium Browser was developed as an alternative to the Microsoft Web Browser (Shell Explorer).

(The Chromium Browser Object was added in PxPlus 2017.)

To add a COM control to a NOMADS panel, see Adding a COM Control.

To define a COM control once it has been added to a panel, see Defining a COM Control.

For information on handling events for a COM control, see Handling Events.

Adding a COM Control

To add a COM control to your panel, select the COM Control button from the Controls Toolbar in the Panel Designer. Hold down the left mouse button and drag the mouse to create a rectangle to the desired size. Release the mouse button to create the new object. Define the properties for the new COM control.

For making other adjustments, see Modifying Objects.

COM Control Properties

When creating or editing a COM Control, the COM Control Properties dialogue is displayed:

This dialogue is divided into the following tabbed panels for viewing and/or changing COM control properties: Display, Properties and Logic.

Object Name

Unique name of the control (NOMADS provides a default). Naming conventions for variables apply.

Note:
When a new control name is entered, it will be checked against the Reserved Words list to determine if it is restricted for use as a NOMADS control name. If it is found, a warning message will display.

(User Reserved Words Maintenance was added in PxPlus 2020.)

COM Control

Unique name of the COM control. Click the Query button for a list of available selections:

Chromium Browser	Adds a Chromium Browser control to the current NOMADS panel.
ActiveX Controls	Launches a separate ActiveX Controls dialogue with a list of ActiveX COM controls registered on the system. Highlighting an ActiveX control also displays the Programmatic ID for that control. If you already know the Programmatic ID of a control, you can enter it in the COM Control field instead of selecting from the list (some controls may not be listed). For a description of ActiveX controls, see Concepts and Terminology.
PVX Plus Controls	Launches a separate PVX Plus Controls dialogue. Select from the list of available PVX Plus COM controls: Ace Editor Control, Google Maps Control, Signature Capture Control and TinyMCE® Editor Control.

See Defining a COM Control.

(The Chromium Browser Object was added in PxPlus 2017.)

Alternate control names to load at runtime if primary not found

Assign alternate COM control names (separated by semi-colons) to be used at runtime if the generic name cannot be found.

Display

Position

Column	Starting column for the top left corner of the control - numeric expression. Format mask is #0.00. Valid entries are 0 to 620.
Line	Starting line for the top left corner of the control - numeric expression. Format mask is #0.00. Valid entries are 0 to 255.

(Support for increased Column and Line maximums was added in PxPlus 2021.)

Size

Width	Width of the control in number of columns - numeric expression. Format mask is #0.00. Valid entries are 0 to 620.
Height	Height of the control in number of lines - numeric expression. Format mask is #0.00. Valid entries are 0 to 255.

(Support for increased Width and Height maximums was added in PxPlus 2021.)

Properties

Objects

Assign property/method values (Fixed or Expression) and set up logic that will execute when a COM control event is triggered. See Defining a COM Control.

Logic

Default Program

Displays the name of the Default Program used in the Panel Header definition.

(The Default Program was added for display in PxPlus 2019.)

Post Create

Logic to be processed after the control is drawn. Click the drop-down arrow for a list of selections. See Events Logic.

Click the Program Logic button beside the Perform or Call action to launch the default program editor, which is typically the *IT - Integrated Toolkit. To make Ed+ the default program editor, change the setting for the %NOMADS'Program_Editor property to Ed+.

(The ability to set Ed+ as the default program editor was added in PxPlus 2023.)

Groups

Button used to assign the control to a group. See Group Assignment.

Notes

Add notes/comments for the control. Maximum 1024 characters. These notes also display in the Wiki Help documentation for the panel. See NOMADS Wiki Help.

(The Notes button was added in PxPlus 2023.)

Defining a COM Control

After a COM control is created on the panel (see Adding a COM Control), the control's properties need to be defined.

The steps to define a new COM control are listed below. (These steps are based on the Folder Style version of the NOMADS Panel Designer.)

Step

Description

1. Select a COM Control

In the COM Control Properties dialogue, click the Query button for the COM Control property. Available selections are Chromium Browser, ActiveX Controls, PVX Plus Controls.

2. Define Properties

Once the COM Control is selected, assign property/method values using the Properties tab.

The Item grid lists all the sub-objects, properties and methods for the COM control selected. This grid consists of the following:

Item

Contains the property or method name.

Type

Contains the details on each item; i.e. Num|Str, Num, Str, pNum|Str, pNum, Meth, Obj, pObj, pArray or Array (where "p" indicates a PxPlus property or object).

Current Value

Contains the current value for an item.

Value/Expression

If enabled, the Value/Expression column accepts either an expression or a value, depending on the Exp check box selection.

PxPlus properties are prefixed with Pvx. Both properties and methods are sorted in alphabetical order and will later be set in alphabetical order. If the assigned value for a property is an expression, place a check mark in the Exp column for that property. The default is no check mark, indicating a literal value.

Use the Value/Expression column to assign a value to the property. The value is assigned after the COM control is created. If the property is Read Only, this cell will be locked.

Methods are identified by "Meth" (in the Type column) and by empty brackets appended to their name; e.g. AboutBox( ). If the method accepts a string value as a single parameter, it may be defined in the Value/Expression column.

Example:

COM Control: *browser

Item
Navigate2( )

Value/Expression
www.pvxplus.com

Both properties and methods may also be defined in the Post Create logic (on the Logic tab). If an application needs access to methods that take no parameters, numeric parameters or more than one parameter, then it must be defined either in the Post Create logic or within the application itself.

Example:

COM Control: *browser

Post Create Logic: Execute COM_1.CTL'Navigate2("www.pvxplus.com")

3. Define Events

The Events grid contains all the events available for the COM control. This grid consists of the following:

Event

Event names are obtained from the 'PVXEVENTS$ property (see Extended Properties and Methods) and are loaded into the Event column in alphabetical order.

Function

Describes how the event (if any) will execute. The following preset values are available in the drop-down list:

Ignore	No event occurs.
Link	Invoke a panel. Syntax: "object name","[ library ]"[, arg_1$ , arg_2$ ... arg_20$ ]
Perform	Perform a program with optional label entry point. (For proper syntax, see PERFORM directive.)
Call	Call a sub-program with optional label entry point. (For proper syntax, see CALL directive.)
Execute	Run a series of PxPlus commands separated by semi-colons.

Logic

Contains associated logic that will execute when an event signal is triggered.

If the Function is a Perform or Call, you can click the magnifying glass button in the Logic cell to launch the Program Editor.

If the program and label already exist for the event, then the Editor will be positioned to that label automatically.

If the program label on an event does not exist, then NOMADS will generate a label automatically (eventname+"_"+control) and insert it in the program. The program will be created if it does not exist. See Events Logic.

4. Assign Post Create Logic

Add/edit Post Create logic using the Logic tab. Enter the program/entry point to be performed, called or executed after the COM control is created. See Events Logic.

Handling Events

It is strongly recommended that event functions be kept relatively short and simple. One reason for this is that normal code execution will be suspended when an event is handled and will not resume until the event function is finished. It is also possible to introduce code (or use commands, such as MSGBOX) to create a re-entrance issue in the event function.

How NOMADS Handles the Events

COM controls generate a unique CTL value for each event defined in NOMADS. NOMADS reserves CTL values between 22001 and 22999. These are loaded into a table at run time after the COM is created using:

ON EVENT "event_name" FROM COM_id PREINPUT CTL_value

Note:
COM_id is stored in control_name.ctl. When an event occurs, NOMADS will scan the event CTL table. If a match is found, then the logic for that event is executed.

Working with Events that Supply Parameters

Most of the time, it is sufficient to trap events through the COM interface. However, NOMADS does not normally receive the parameters that may be passed back (if the events are capable).

To receive event parameters from a COM control, a PxPlus class must first be designed. A class function must be written for each event to be handled.

Example:

If you were writing an event class for the COM object Shell.Explorer.2, you could receive parameters from the exposed event BEFORENAVIGATE2 (URL, [Flags], [TargetFrameName], [PostData], [Headers]) by defining a class as follows:

def class "menuevent"
property TXID$
function BEFORENAVIGATE2(*)BEFORE for event "BeforeNavigate2"
end def

BEFORE:
enter *,U$,*,*,*,*,C
if mid(lcs(U$),1,3)="tx:" \
     then C=1;
             TXID$=U$(4) \
       else TXID$=""
return 1

The function and label name are not required to match the name of the event. It is the string after the FOR EVENT portion of the statement that determines the event name that will be handled. The event name is not case sensitive, and argument names are not required to match the COM control's event declaration. When the OOP method name matches the COM event name, then SAME can be used to describe the name of the event.

Once the class is complete, an instance of the class must be instantiated to bind the COM object to the event handler. In NOMADS, this code should be invoked by the COM Post Create logic:

create_object:
EVNTOBJ=new("menuevent",EXPLORER.CTL,100)
return

Once bound, the PxPlus event class function will be called when the corresponding event occurs.

TinyMCE® is a registered trademark of Tiny Technologies Inc.

Creating Panel Controls

Adding a COM Control

COM Control Properties

Note: When a new control name is entered, it will be checked against the Reserved Words list to determine if it is restricted for use as a NOMADS control name. If it is found, a warning message will display.(User Reserved Words Maintenance was added in PxPlus 2020.)

Defining a COM Control

Handling Events

Note:COM_id is stored in control_name.ctl. When an event occurs, NOMADS will scan the event CTL table. If a match is found, then the logic for that event is executed.

Note:
When a new control name is entered, it will be checked against the Reserved Words list to determine if it is restricted for use as a NOMADS control name. If it is found, a warning message will display.

(User Reserved Words Maintenance was added in PxPlus 2020.)

Note:
COM_id is stored in control_name.ctl. When an event occurs, NOMADS will scan the event CTL table. If a match is found, then the logic for that event is executed.