# Directives

ON EVENT | Event Processing

## Formats

1. External Control via OOP Object: | ON EVENT FROM ext_id PROCESS oop_id
2. External Control via CTL Event: | ON EVENT evtname$ FROM ext_id PREINPUT ctl_id
3. Remove CTL Event: | ON EVENT evtname$ FROM ext_id REMOVE

Where:

ext_id | Numeric CTL value of a Windows external object.
ctl_id | Numeric CTL signal to generate (pre-input) when a given event occurs.
evtname$ | Event name, maximum 255 characters.
oop_id | Numeric identifier of an OOP object. See Object Oriented Programming.

## Description

This directive is used to activate support for individual external control events for use in PxPlus applications. COM, .NET and *Browser controls are supported. See DEF OBJECT directive.

(.NET support was added in PxPlus 2025.)

The .NET Interface allows developers to leverage the power of .NET's robust libraries in PxPlus when using .NET applications.

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.

#### Note:
Only Format 1 supports event arguments. In Format 2, they are not supported.

## Format 1

External Control via OOP Object
ON EVENT FROM ext_id PROCESS oop_id

This format is used to register a numeric OOP object identifier (oop_id) to service a given external control (ext_id). The OOP object identifier is stored in a read-only property of the external object called 'PvxEvents. A comma-separated list of the events that are supported by the external object is available by querying 'PvxEvents$ via the Apostrophe Operator. Supported events are prefixed with a + (plus sign) while unmanaged events are prefixed with a leading - (minus sign). This format will not work across WindX.

#### Note:
The list of events reported in 'PvxEvents$ is only available after the ON EVENT FROM ext_id PROCESS oop_id has been executed. This behavior is intended to minimize communication with the interop layer when event support is not required.

An invalid ext_id generates an Error #65: Window element does not exist or already exists. An invalid oop_id generates an Error #95: Bad Object Identifier. Other errors, such as when an external object does not support events, will generate an Error #88: Invalid/unknown property name and, if available, place a description of what caused the error in the 'PvxError$ property for the external object, as well as in MSG(-1).

An oop_id of 0 (zero) deactivates event processing for the current external object. Dropping a PxPlus OOP object deactivates event processing for all external objects associated with the OOP object. Issuing a subsequent ON EVENT directive for an external control discontinues event processing for the first PxPlus OOP object and then activates it for the new OOP object (provided the new oop_id contains a non-zero value).

## Formats 2 and 3

COM Control via CTL Event
ON EVENT evtname$ FROM ext_id PREINPUT ctl_id
Generate Event

The PREINPUT option is used to generate a PxPlus CTL event whenever the identified external control event occurs. This format simplifies the event interface by eliminating the need to create an OOP object to manage events. This format will work across WindX. The event process does not have access to any event parameters, as it will not be running in-line when the event occurs.

ON EVENT evtname$ FROM ext_id REMOVE

Remove Event

The REMOVE option stops the process of generating a CTL signal for the specified event; however, the removal of an assigned event will have no effect on currently queued events.

## See Also

Object Oriented Programming
DEF OBJECT Define Windows Object
Apostrophe Operator
Automation in PxPlus