External Event (Magic xpa 2.x)

« Go Back


Created ByKnowledge Migration User
Approval Process StatusPublished

External Event (Magic xpa 2.x)

This event is raised from external 3rd party software. The event enables easier integration between Magic xpa and external programs running on the same computer, by enabling Magic xpa to receive and process events and data from external programs.

Browser Client

This event is triggered upon receiving a Windows message or upon activating the JavaScript function of the MGExternal event in a Browser client task.

From inside your HTML, you can use the special script called MGExternalEvent. Calling this script will activate Magic xpa's event called External Event, and pass the parameters you specified.

The MGExternalEvent function provided by the Browser Client JS module enables Magic xpa to invoke the Magic xpa External Event from an external JS module that is executed from a Browser Client page. When the MGExternalEvent function is executed, the External Event is added to the Magic xpa event queue and is recognized as a regular Magic xpa event.


MGExternalEvent(parameter 1, parameter 2)


parameter: A string value passed as a parameter. The passed values will be received by the Handler’s virtual variables according to their order. There is no limit to the number of parameters allowed.


The function returns a True value if the Browser Client is loaded or a False value if the Browser Client cannot be loaded.

Rich Client

This event is an alternative to the Browser Status Text Change event, which is blocked by default in Internet Explorer 7.

This event can be raised from within a script in the Browser control's HTML page by using the following syntax:


As opposed to Browser Client tasks, in Rich Client tasks, only one BLOB Unicode parameter can be sent.

Since version: 1.8

See also: the RRC07 sample program in the RIA samples

Platform Specific

This event is not supported in Window Mobile devices.

On iOS devices, this event can be raised from a Browser control using the following syntax



In the example below, a VBScript script calls the MGExternalEvent script, passing three parameters, the Day, Month, and Year. The event handler catches those three parameters, and responds by updating a field and refreshing the screen.

Note that in Rich Client, only one parameter can be sent, so you should concatenate those values into one string.

Using Windows API

Raising an external event in Magic xpa is done using a SendMessage window API command with the WM_COPYDATA message type. This message contains a pointer to a COPYDATASTRUCT structure. Magic xpa places these parameters into the event queue, and the handler receiving the event receives its parameters.

COPYDATASTRUCT Format – This structure contains the three members listed below:

  • dwData – number indicating the number of parameters sent

  • lpData – pointer to a buffer containing the parameters

  • cbData – length of data in lpData.

Parameters – The parameters placed in the cbData member are placed as null terminated strings in the buffer. Magic xpa accepts four types of parameters:

  • -A – Alpha parameter

  • -N – Whole numeric parameter

  • -F – Floating point parameter

  • -L – Logical parameter (T or F values)

Example: Suppose we are to send 4 parameters containing “XXX”, 17, True, 643.23. The created buffer should be in the following form:


Where the ? sign, represents a null character.

Defining the handler

To handle the external event, you need to create a handler on the ‘External event’ part of the Internal type of events. In this handler you can create the virtual variables that will receive the passed arguments.

Demo executable and CPP code

The Magic xpa installation provides an executable file, Msg2mgic.exe, that demonstrates the invocation of the external event in Magic xpa. For more information, see MSG2MGIC Utility.

The External Event has no default Keyboard Mapping.

Related Topics