| Customize Help

Creating a MILweb client application with JavaScript


The JavaScript MILweb API is suitable for writing a client application that can run in a compatible web browser on a wide variety of platforms.

This section only discusses information specific to the MILweb JavaScript API. For general information about creating a MILweb client application, see the Fundamentals for creating your MILweb client application section earlier in this chapter. For details about the JavaScript versions of specific MILweb functions see the JavaScript MILweb function reference section later in this chapter.

JavaScript primer for C/C++ MIL developers

Since JavaScript shares much of its syntax with C/C++, in general you should find it easy to write a simple JavaScript application that uses MILweb. It is useful to bear in mind the following differences between C/C++ and JavaScript:

  • JavaScript is an interpreted language. You do not need to compile JavaScript code, nor do you need any kind of linking mechanism to access mil.js (except for putting it in the folder with your application). You can create and modify your JavaScript application using any text editor. You can run your application in a compatible web browser by calling your main JavaScript function from within an HTML file (so long as the HTML file, your application source code, and mil.js are in the same folder). For more information, see the Running your JavaScript MILweb client application subsection of this section.

  • JavaScript is a dynamically-typed language. You do not assign a data type to variables; the type of data in a variable is determined automatically each time you assign a value to it. In general, casting is done automatically when required (and possible). For example, in the following code, multiplicationResult is set to the number 30 (someVariable is automatically cast as a number), and printableOutput is set to the string "That other variable is the number 30" (multiplicationResult is automatically cast as a string):

    var someVariable = "5";
    var multiplicationResult = someVariable * 6;
    var printableOutput= "That other variable is the number " + multiplicationResult;

    This can lead to ambiguous situations, in which the JavaScript interpreter must decide how to cast a variable. For example in the following code, the JavaScript interpreter must decide whether to cast firstVariable and secondVariable as strings or numbers for the purposes of addition. In this case, firstAddition is set to the number 8, while secondAddition is set to the string "26":

    var firstVariable = 2;
    var firstAddition= firstVariable + 6;
    var secondVariable = "2";
    var secondAddition= secondVariable + 6;

    You can determine what data type is currently stored in a variable using the built-in function typeof. For example, typeof(2) returns "number", while typeof("2") returns "string". Note that this does not work for arrays; typeof(anArray) returns "object".

    The MILweb JavaScript function reference lists the expected data type for each parameter. If you set a parameter to a variable that stores a different type of data, the JavaScript interpreter will attempt to cast the data to the correct data type. If a cast is not possible, either an error is generated or the value "undefined" is used. You should be aware of this when debugging your MILweb client application.

  • JavaScript does not distinguish between integers and decimal values. All types of numbers have the data type number, unless they were declared within quotation marks in which case they have the data type string.

  • An array is a type of JavaScript object. Arrays in JavaScript are similar to vectors in C++. You can increase or decrease the size of an array after it has been defined. You do not need to declare that a variable is an array object before assigning values to it, nor do you need to explicitly specify the size of an array.

  • JavaScript objects are similar to C++ objects, but the terminology is different. Member variables in C++ are referred to as properties in JavaScript, member functions in C++ are referred to as methods in JavaScript.

  • Web browsers typically execute JavaScript in a single thread. However, some procedures (such as establishing a connection to a MILweb server) are completed asynchronously.

To learn more about using JavaScript, refer to third-party resources such as the Mozilla JavaScript documentation at https://developer.mozilla.org/en-US/docs/Web/JavaScript.

MIL primer for JavaScript developers

The MILweb JavaScript library is closely modeled on the C MIL library. Unlike JavaScript, C is not an object-oriented programming language. However, MIL implements an object-oriented model within the framework of C. The following information will help you to understand the model for accessing MIL objects.

  • Each MIL object has a client-side MIL identifier. Instead of accessing the MIL object directly, you store the client-side identifier of the MIL object in a variable and pass that variable to a function.

    For example, you can zoom a MIL display using the function MilWeb.MdispZoom. This function is not a method of the display; it is a global function you call with the client-side identifier of the display, as shown below:

    var displayIdentifier = MilWeb.MappInquireConnection(MilWebApp, MilWeb.M_WEB_PUBLISHED_NAME, "Display", MilWeb.M_DEFAULT);
    MilWeb.MdispZoom(displayIdentifier, 2, 2);

    The first line inquires the identifier of the display. The second line zooms the display by calling MilWeb.MdispZoom with that identifier.

    For clarity, this example assumes that a connection has already been established to the MIL display by a previous call to MilWeb.MappInquireConnection. Normally, you cannot access a MIL object immediately after inquiring its client-side MIL identifier. For more information, see the Accessing MILweb server applications and published MIL objects subsection of this section.

  • You do not access the properties of a MIL object directly. Instead you use a control or inquire function with the setting that specifies the property you want to access. You can think of control and inquire functions as getter and setter functions for the MIL object that you specify (using its client-side MIL identifier).

Writing a MILweb client application in JavaScript

Your Javascript web client application must use the mil.js library (located by default in C:\Program Files\Matrox Imaging\tools\milweb). This library provides functions to access MIL objects, hook onto updates, present a display in an HTML5 canvas, and send input data to your MIL application. The MILweb JavaScript API is closely modeled on the standard MIL API.

Differences between MIL and MILweb

You should be aware of the following differences between MIL and the JavaScript MILweb API:

  • Client-side MIL identifiers are not valid until MILweb has asynchronously completed the connection to the MILweb server application or MIL object. For more information, see the Accessing MILweb server applications and published MIL objects subsection of this section.

  • MIL identifiers have the data type number.

  • JavaScript does not have a pass-by-pointer or pass-by-reference mechanism for number and string data types. MILweb functions that return data in a parameter instead write the data to the data property of a JavaScript object that you specify. For more information, see the Returned values in MILweb subsection of this section. Typically this is optional, since most MILweb functions also return their result.

  • Hook-handler functions must be declared as: function hookHandler(hookType, eventId, UserVar).

  • MilWeb.MdispSelect does not select an image to a display; it presents a display in an HTML5 canvas.

Accessing MILweb server applications and published MIL objects

Before you pass the identifier of a MILweb server application or published MIL object to a MILweb function, you must first establish a connection between your MILweb client application and the server application or MIL object. You do this using MilWeb.MappOpenConnection (for the MILweb server application) or using MilWeb.MappInquireConnection with MILweb.M_WEB_PUBLISHED_NAME (for published MIL objects).

Each published MIL object occupies one WebSocket in the user's web browser. If the web browser limits the number of open WebSockets per connection, this also limits the number of published MIL objects the MILweb client application can access.

Both MilWeb.MappOpenConnection and MilWeb.MappInquireConnection are executed asynchronously. Your program will continue to execute after calling these functions, but before they have finished establishing a connection. To ensure that code is executed after a connection event has finished, you must put that code in a hook-handler function. You can hook to connection events using MilWeb.MappHookFunction or MilWeb.MobjHookFunction with MilWeb.M_CONNECT.

This does not apply to the MILweb C/C++ API. For C/C++, these functions are executed synchronously. Therefore, you do not need to hook to connection events, or be aware of connections to individual objects.

To hook a function to the connection event (for example, using MilWeb.MappHookFunction or MilWeb.MdispHookFunction), you need to specify the client-side MIL identifier used to identify the MILweb server or object. Therefore, you must obtain this identifier by initiating the connection prior to hooking a function to the MilWeb.M_CONNECT event (the identifier is returned by the function that makes the connection). You should hook to the connection event immediately after calling MilWeb.MappHookFunction to ensure that the hook-handler function is executed when the connection is established. For example:

var UserVar = {};
MilWeb.MappOpenConnection(URL, MilWeb.M_DEFAULT, MilWeb.M_DEFAULT, UserVar);
AppId = UserVar.data;
MilWeb.MappHookFunction(AppId, MilWeb.M_CONNECT, ConnectHandler);

When the connection is established, the ConnectHandler callback function will be executed, even though MilWeb.MappHookFunction was called after MilWeb.MappOpenConnection.

MilWeb.MappCloseConnection is also executed asynchronously. You can hook to the disconnection event using MilWeb.M_DISCONNECT.

Returned values in MILweb

To maintain similarity with the MIL API, many functions in MILweb can both return their result (such as an inquired value) and/or store it in an object that you specify. However, unlike C and C++, JavaScript does not have a pass-by-pointer or pass-by-reference mechanism for number and string data types (numbers and strings are always passed to functions by value; they cannot be used as "out" parameters). Conversely, JavaScript objects are always passed by sharing, which is functionally equivalent to pass-by-reference. Therefore, to mirror MIL, functions in the MILweb API write their result to the data property of the specified JavaScript object.

For example, the following code creates a JavaScript object stored in the variable AppId, then uses it to store the result of a MILweb function:

var appId = {};
MilWeb.MappOpenConnection("ws://localhost:7861", MilWeb.M_DEFAULT, MilWeb.M_DEFAULT, appId);

After this code is executed, appId.data stores the MIL application identifier of the MILweb server application.

You do not need to declare a data property for the object beforehand; MILweb does this automatically. Any existing properties of the object are removed.

Running your JavaScript MILweb client application

To test your MILweb client application, you must create a simple HTML page and access that page from an HTML5-compatible web browser.

  1. Create the application folder (for example, C:\working\YourMILwebClientApplication).

  2. Copy the MILweb JavaScript library (mil.js) to the application folder. By default, this file is located in C:\Program Files\Matrox Imaging\tools\milweb.

  3. Save the source code for your Javascript application as a file with the js file extension (for example, YourMILwebClientApplication.js) and copy this file to the application folder.

  4. Create an HTML page that loads the mil.js and your JavaScript application. For example:

    <script type="text/javascript" src="mil.js"></script>
    <script type="text/javascript" src="YourMILwebClientApplication.js"></script>

    Save this page with the HTML file extension, in the application folder.

  5. Open the HTML file with an HTML5-compatible web browser.

Deploying your MILweb client application

Once you have finished developing your MILweb client application and embedding it in a web page, typically you will want to make it available for access by one or more remote computers. In most cases, you should use one of the following methods to make the web page available:

This animation shows the relationship between a web-enabled device, the MIL HTTP server object, and the MILweb server application.

  • 1 of 7

Browser compatibility

The MILweb client JavaScript library requires a web browser that supports both JavaScript and the HTML5 WebSocket protocol. MILweb client applications have been tested successfully with the desktop versions of the following third-party web browsers:

  • Google Chrome (version 16 and higher).

  • Microsoft Edge (all versions).

  • Microsoft Edge Legacy (all versions).

    This browser is limited to accessing 5 published MIL objects (such as displays) at a time.

  • Microsoft Internet Explorer (version 11 and higher).

  • Mozilla Firefox (version 11 and higher).

The MILweb JavaScript library adheres to industry-standard JavaScript development practices, including standards-compliant use of the HTML5 WebSocket protocol. However, third-party web browsers are frequently updated. Matrox can only guarantee compatibility with the versions of these third-party browsers that were current when the most recent MILweb driver update was released.