Altair EEvision™

The GUI API

On Load – The eevinit Event

Running EEvision inside an iframe window is an easy way to (a) listen to the eevinit event that is sent from EEvision as soon as it finished its initialization and then (b) to call further API functions. Here is example code, that starts EEvision in an iframe and waits for its initialization and then calls the API function LoadAll:

<IFRAME width=700 height=500 id="iframe"
        src="main.html?edb=dir/file.edb">
</IFRAME>

<SCRIPT>
    var iframe = document.getElementById('iframe');
    var eev;
    document.addEventListener("eevinit", function(e) {
        eev = iframe.contentWindow.API;
        eev.LoadAll(function(result, errmsg) {
            if (errmsg) return console.error(errmsg);
            /* LoadAll done, continue with other work */
        });
    });
</SCRIPT>

Asynchronous API Functions

Those API functions that do asynchronous (AJAX) server communication need a doneFunc callback function that is called when (a) an error occurred or (b) after the request is finished. This callback function gets two arguments: the first argument is the response value from the API function and the second argument is normally undefined, but in case of an error, it stores the error message. This second argument must be checked for error cases, like in this example:

var doneFunc = function(value, errmsg) {
    if (errmsg) {
        // error handling
    } else {
        // normal end of request
    }
});

If an asynchronous API function is called without specifying a doneFunc, then the request is executed anyway, but the caller is not informed about the end of the request. In case of an error, the errmsg is sent to the internal error handling that will display the error message in the GUI, unless it is redefined by SetErrorMessageHandler().

function Load(id, doneFunc);

The Load function loads the object identified by the given id to the canvas. The id may refer to a Component, Connector, Cavity, Wire, Multicore, or Module object (see the Edb object model). The id refers to exactly one object; the same id always refers to the same object and different ids to different objects (object identity). The id can be received, e.g., from the QueryJson commands below. Depending on the object type, the Load function has different implementations:

Component

Loading a Component just adds the given object to the Schematic canvas and highlights it with the config.startColor.

Connector

Loading a Connector adds the Connector's parent Component to the Schematic canvas and highlights the Connector with the config.startColor. This is only supported for Connectors at ECU and INLINER Components.

Cavity

Loading a Cavity adds the Cavity's parent Component to the Schematic canvas and highlights the Cavity with the config.startColor.

Wire

Loading a Wire adds the Wire plus two connected Components to the Schematic canvas and highlights the Wire with the config.startColor.

However, if netMode is on, then loading a Wire implicitly adds all electrically interconnected Wires. Wires are electrically interconnected if they are joined by splices, eyelets, multi-term connections and partner Cavities at inliners. In this netMode, the interconnected splices, eyelets, inliners and all terminal components are implicitly added, but only the Wires are highlighted with the config.startColor.

Multicore

Loading a Multicore adds the Multicore object plus its grouped Wires with one connecting Component and highlights the Multicore with the config.startColor. The display of the Multicore object or the Multicore tree depends on the configuration in config.multicores. Each multicore indicator (e.g., oval) is displayed at each Connector where at least one (usually all) grouped Wires connect to Cavities. This also means: the Multicore object is usually displayed at two locations (or at even more locations, if the Wire actually represents a n-pin connection).

Module

Loading a Module adds all objects that are listed in the given Module and highlights them with a dimmed version of the config.startColor. Modules are multi-purpose lists that can be used to group objects, e.g., by their function or by other meaning.

null  (id=0)

Loads nothing – just clear the Schematic canvas.

The doneFunc is a callback function; if specified, it is called after loading is finished. The behavior of the Load function depends on some configure settings:

function LoadIncr(id, doneFunc);

The LoadIncr function loads the object identified by the given id and adds it to the current schematic (instead of replacing it). The doneFunc is a callback function; if specified, it is called after loading is finished.

function LoadAll(doneFunc);

The LoadAll function loads an arbitrary minimum spanning tree between all ECU & SVG Components. This means, all ECU & SVG Components will be loaded, but by far not all Wires. Splices, eyelets and inliners may (or may not) be included. The doneFunc is a callback function; if specified, it is called after loading is finished.

function ExtractOne(id, doneFunc, smart);

The ExtractOne function extracts the connectivity by one level up to the next connecting ECUs or SVGs and loads it to the canvas. The start object for this extraction is identified by the given id, that must be a Component, Connector or Cavity (that will be highlighted with config.startColor). The extraction can be limited by config.extractMax and/or reduced by the config.powerWireEx and config.groundWireEx. The doneFunc defines a callback function that is called after extraction and loading is finished.

The (optional) smart argument can be:

function ExtractPaths(  idList, doneFunc);
function ExtractSteiner(idList, doneFunc);

The ExtractPaths function extracts the connectivity between the start objects identified by the list of ids in idList - and loads them to the canvas. If an object's id appears multiple times in the same idList, then self-loops at that object are extracted too. The ExtractSteiner function extracts a Steiner tree between the start objects identified by the list of ids in idList - and loads them to the canvas. The start objects must be Component, Connector or Cavity objects. The doneFunc defines a callback function that is called after extraction and loading is finished.

function ShowToolbar(on, margin);

The ShowToolbar switches the EEvision toolbar on or off. The given boolean argument “on” must be true or false. Switching off the EEvision's toolbar can be useful if the customer wants to provide his own tool bar buttons and wants to drive the EEvision GUI solely through this GUI API. The optional margin defines the margin space around the EEvision window; if undefined, then the default margin is used.

function ChangeNetmode(on);

The ChangeNetmode switches EEvision's netMode on or off. The given boolean argument “on” must be true or false.

function QueryNetmode();

The QueryNetmode returns whether EEvision's netMode is on or off.

function QueryLogmode();

The QueryLogmode returns whether EEvision's logical mode is on or off.

function ChangeConfig(conf, doneFunc);

The ChangeConfig function changes the EEvision configuration. The given conf must be a Javascript object with some key-value pairs defining new configuration settings. All configuration key-value pairs in this document are referred to as config.key. The doneFunc defines a callback function that is called after the configuration is changed.

function SetSelectionNotify(func);

This function installs the func function (without any arguments) as a new selection callback. This callback is executed every time the user selects/deselects an object in the schematic (typically identified by using the GetSelection API function). If several selection callback functions are installed, they are called in the order of installation.

function RemoveSelectionNotify(func);

Calling this function removes the func function from the list of selection callbacks.

function SetErrorMessageHandler(func);

This function overwrites EEvision's internal error messages handler with the function func accepting two arguments msg (the error message) and cls (the message classification – 'error' or 'warn'). It is called for an error respectively warning which otherwise would be displayed in the EEvision standard GUI.

However, errors from API calls are usually returned to the caller directly. Here is an overview on different sources of errors:

synchronous API function

errors, that occur in a synchronous API function are directly thrown to the caller (normal JavaScript behavior)

asynchronous API function

errors, that occur in an asynchronous API function (with a doneFunc callback) are reported to the caller by passing the error message as second argument to doneFunc(). If the doneFunc is not specified to the asynchronous API function (undefined argument), then the error will be passed to the internal error messages handler that can be redirected by SetErrorMessageHandler.

asynchronous events

errors, that occur in an asynchronous GUI events, e.g mouse events, are passed to the internal error messages handler that can be redirected by SetErrorMessageHandler.

function QueryJsonList(flags, doneFunc);

The QueryJsonList requests a list of JSON objects. Each of those objects represents one EDB object. The given flags is expected to be a string (as a space-separated list) of items. The following flags are supported:

-component

-connector

-cavity

-wire

-multicore

-module

Limit the query request to the given object types. If, e.g., flags is set to “-component -wire”, then the result will include all component objects and all wire objects. See the JSON API.

-flat

Switch the query request into flat mode, so the resulting list contains only objects without nested objects. Without “-flat” each Component object will include all its Connectors in a nested way; and each Connector object will include all its Cavities in a nested way; and each Multicore object will include all its child Multicores in a nested way. See the JSON API.

The result is returned by asynchronously calling the given callback function doneFunc. That “doneFunc” will get the result in its first argument, and the user will most probably call JSON.parse() on it. Here is an example that queries for all wires:

QueryJsonList('-wire', function(response, errmsg) {
    if (errmsg) { /* error handling */ return; }
    var i;
    var list = JSON.parse(response);
    for(i=0; i<list.length; i++) {
        var obj = list[i];
        /* process object */
    }
});

function QueryJsonObj(flags, id, doneFunc);

The QueryJsonObj requests one JSON object, identified by the given id. The given flags supports only:

-flat

See description above.

See the JSON API for the object format. The result is returned by asynchronously calling the given callback function doneFunc. That “doneFunc” will get the result in its first argument, and the user will most probably call JSON.parse() on it. Here is an example that queries for object 12:

QueryJsonObj('-flat', 12, function(response, errmsg) {
    if (errmsg) { /* error handling */ return; }
    var obj = JSON.parse(response);
    /* process object */
});

function QueryJsonListByName(flags, name, doneFunc);

The QueryJsonListByName searches for object(s) with the given name (the name match may be limited by additional object types, if the flags is set accordingly). The given flags is the same as for QueryJsonList above. The result is returned asynchronously, also identical to QueryJsonList above. Here is an example that queries for a component named U42:

QueryJsonListByName('-component', 'U42', function(response, errmsg) {
    if (errmsg) { /* error handling */ return; }
    var obj = JSON.parse(response);
    /* process object */
});

function CurrentJsonList(flags, doneFunc);

The CurrentJsonList requests a JSON list of JSON objects, identical to QueryJsonList above, but instead of returning all EDB objects, it returns only those objects that are currently loaded to the Schematic canvas. The flags argument is probably not very useful here, but the same are supported as for QueryJsonList above. The result is returned asynchronously, also identical to QueryJsonList above. Here is an example that loops over all objects currently in the canvas:

CurrentJsonList('', function(response, errmsg) {
    if (errmsg) { /* error handling */ }
    var i;
    var list = JSON.parse(response);
    for(i=0; i<list.length; i++) {
        var obj = list[i];
    }
});

function PickObj(event, doneFunc);

The PickObj performs a “pick” in the canvas window at the coordinates given in the event (usually a mouse event). The result is the id of the object, closest to the given coordinates, or a “0” if nothing was picked. This id is returned by calling the doneFunc and passing the id as a field on the returned JavaScript object. That “doneFunc” may be called immediately or asynchronously depending on the internal caching situation. Here is an example that calls PickObj() followed by QueryJsonObj() to get the JSON information for the picked element:

function getjson(id) {
    QueryJsonObj('-flat', id, function(response, errmsg) {
        if (errmsg) { /* error handling */ }
        var obj = JSON.parse(response);
        /* process object obj */
    });
}
PickObj(event, function(id, errmsg) {
    if (errmsg) { /* error handling */ return; }
    if (id) {
        getjson(id);
    } else {
        /* nothing was picked */
    }
});

function CenterObj(id, doneFunc);

The CenterObj function centers the object specified by id in the schematic and calls the callback function doneFunc when done.

function CenterObjArray(ids, doneFunc);

The CenterObjArray function centers a collection of objects specified by an array ids in the schematic and calls the callback function doneFunc when done.

function SelectObj(id, doneFunc);

The SelectObj functions selects the object specified by id in the schematic and calls the callback function doneFunc when done.

function GetSelection(doneFunc)

This function generates an array with ids of all selected elements. On success the callback function doneFunc is executed with the array as first argument.

function ZoomTo(fac);

The ZoomTo changes the zoom factor of the current schematic in the canvas window (initial to 1). The given fac is an absolute floating number. If the function is called without parameter, it returns the current zoom factor without changing it.

function ScrollBy(relx, rely);

The ScrollBy changes the scroll-position of the current schematic in viewport defined by the canvas window. The given relx and rely are relative floating number in the range between -1.0 and 1.0. Negative relx shifts leftwards, negative rely shifts upwards. The ScrollBy functions applies limits to avoid scrolling the Schematic Diagram outside of the viewport. The following example will shift the current schematic towards right by 30% of the window width.

ScrollBy(0.3, 0);

function Fullfit(mode);

The Fullfit function changes the scroll position and zoom factor of the current schematic to fit the visible area. The optional parameter mode specifies whether the schematic is fit only to the canvas width preserving the y position (mode == 'x') or only to the canvas height preserving the x position (mode == 'y').

function RotateView(on);

If the parameter on is set to true, the RotateView function turns the canvas 90 degrees clockwise; if it is false, the canvas is rotated back into is normal orientation. If the parameter on is missing (or set to undefined), the function returns whether the canvas is currently rotated (return value = true) or not.

function Print();

Generates an SVG of the current schematic and opens the browsers print dialog.

function RestartFiltered(def);

The RestartFiltered performs a full restart of the EEvision session with a modified URL as computed by the function BuildURLParams(def) in “update mode”. There is no doneFunc callback function, but the eevinit event can/should be listened to, to get called when RestartFiltered has finished (see below). The full restart is done by internally assigning the new URL to the window.location.href. But this is done in “setTimeout(, 0)” to execute the full restart one event later, making sure, the caller of RestartFiltered() can still access all data structures in the old DOM without any memory issues.

Here is an example that queries for all Modules with matching names and then restarts filtered by those Modules:

function jdone(response, errmsg) {
    if (errmsg) { /* error handling */ }
    var i;
    var list = JSON.parse(response);
    var mlist = [];
    for(i=0; i<list.length; i++) {
        var obj = list[i];
        if (obj.name.match(/dist/)) {
            mlist.push(obj.id);
        }
    }
    var def = { f: mlist };
    RestartFiltered(def);
}
QueryJsonList('-module', jdone);

Using the eevinit event: The eevinit event is sent whenever EEvision has finished its initialization, e.g., after the Browser reload button but also in response to the RestartFiltered() call. An event listener for “eevinit” event must distinguish between these cases, if it is used for both waiting for the initial loading and waiting for RestartFiltered(). Here is a simple example that uses a “statefunc” variable to distinguish.

var iframe = document.getElementById('iframe');
var eev;
var statefunc = function(e) {
    /* initial loading is done */
}
document.addEventListener("eevinit", function(e) {
    eev = iframe.contentWindow.API;
    statefunc(e);
});

function ..... {
    statefunc = function(e) {
        /* RestartFiltered is done */
    }
    RestartFiltered(def);
}

function LiveSearch(otype, stype, str, mode, doneFunc);

Depending on mode, the LiveSearch searches either the complete EDB (mode = "edb") or the current schematic (mode = "scm") for objects matching the object type otype, the sub-type stype and the given str. An object is added to the result if str is a sub-string of the object name or of any of the object's attribute values (only attributes that are listed in config.searchAttr are considered). Each match adds one entry to the result list, which is returned as first argument to the doneFunc callback function.

Each entry in the result list is a 6-tuple (represented by a JavaScript array of length 6). Each entry is either a N-match (matching object name) or an A-match (matching any of the given object attribute values).

The otype is either 'any', or 'most' or null, or one of: 'component', 'connector', 'cavity', 'wire', 'multicore' or 'module'. If 'any' is specified, then search for all types (including cavities at ecu, svg, hier, inliner and undef components). If 'most' is specified, then search for all types, except for cavities. If 'null' is specified then it depends on config.searchAny.

The stype depends on the otype. For otype='component', the stype is either null or one of: 'ecu', 'inliner', 'hier', 'splice', or 'eyelet'. For otype='wire', the stype is either null or one of: 'power', 'ground', 'logical', 'bus' or 'hv'. For otype='module', the stype is either null or one of: 'config', 'signal', 'function', 'harness' or 'dbus'. For details see the Creator API.

The following example searches for all components in the EDB with A10 in their name or in any of the considered attributes (by searchAttr).

LiveSearch('component', null, 'A10', 'edb', function(result,errmsg) {
        if (errmsg) {
            console.error(errmsg);
            return;
        }

        var i;
        for (i=0; i < result.length; i++) {
            /* take 6-tuple from result list */
            var row       = result[i];
            var otype     = row[0];
            var name      = row[1];
            var id        = row[2];
            var attrmatch = row[3];
            var matchidx  = row[4];
            var matchlen  = row[5];
        }
    });

function SaveSVG(split, doneFunc);

Creates SVG format from the schematic that is currently loaded to the Schematic canvas. If split is true, then contents is split over some pages (with artificial off-page connectors). The doneFunc callback function is called with an array of strings, each string stores the SVG data of one page. This array of strings is provided as the “value” parameter to doneFunc(value,errmsg); If split is false, then the value's array length is always 1.

The following example creates SVG from the current contents and downloads it as one or multiple SVG files named page1.svg, page2.svg, etc.

API.SaveSVG(true, function(errmsg, svgList) {
    for (let i=0; i < svgList.length; i++) {
        var svg = svgList[i];
        var a   = document.createElement('a');
        a.setAttribute('href', 'data:image/svg+xml;charset=utf-8,'
            + encodeURIComponent(svg));
        a.setAttribute('download', 'page' + (i+1) + '.svg');

        a.style.display = 'none';
        document.body.appendChild(a);
        a.click();
        document.body.removeChild(a);
    }
});

function GetHistoryPosition();

Returns the position within the history stack of the current EEvision session (the empty canvas at the beginning of the session has position 0). This function can be used for example to check whether going back in the browsers history would leave the EEvision application.

function GetInternalState();

This function returns an object that represents the current state of the EEvision application. It can be used to restore the current schematics, selection, etc., by passing the object to RestoreInternalState(state, doneFunc).

function RestoreInternalState(state, doneFunc);

This function restores a previous state of EEvision. An EEvision state that needs to be restored later can be retrieved using GetInternalState(). RestoreInternalState is an asynchronous function; the callback function doneFunc is called when the restore operation has been finished.

Note: Restoring a previous state only works successfully if the same URL is loaded in EEvision from which the state was saved, i.e., both the same EDB file needs to be loaded and the same filters need to be applied in the same order. If state is the object obtained from GetInternalState(), then state.url is the URL that was loaded when the state was retrieved (not including the hash part after the “#”).

const eev_state = API.GetInternalState();

// ... further API calls, user interaction, ...

console.assert(eev_state.url === location.href.replace(location.hash, ""), 
    "Wrong URL.");
API.RestoreInternalState(eev_state, function () {
    console.log("State has been restored.");
});

Copyright © 2019–2024 by Altair Engineering Inc.
All rights reserved.