Translation needed

The content of this page was copied from another page tree and needs to be translated or updated.

When you finish translation, make sure to

Replace the label NEEDS-TRANSLATING with TRANSLATED
Remove this macro from the page

Since 3.2.0

1 Introduction
2 Configuration
- 2.1 Options:
3 Menu - Callback Function
4 Events
5 Change Icon Location
6 Functions
- 6.1 HD.EmbededApi.getSymbols
7 Performance

Introduction

This functionality is part of HDC.EmbeddedAPI controller and allows an external application to place selected icons based on object ID.

For available system icons, please review this guide: (no) Ikoner

Sample icons with a context menu placed in individual rooms:

Since 4.6.0 The symbols will be placed on first visible global layer.

Configuration

Both internal and external IDs are supported. Icons are created based on configuration object with the following structure:

var symbols = {    
      //general call options
      options: {
            domain: "12",          
            objectClass: "HDV_H1_SPACE",
            iconId: "123",		
			sizePercentage: 50,
			alignTo:"C",
			fixedSize: false
      },

         
      menu: [{          
            name: 'My Menu Item',
            callback: this.myFunction,            
            context: this,           
            iconCls: 'far fa-address-card',
      }],  

      "objects": [{          
            id: "5105701/10/1",
            label: 'Room 01'
            iconId: "123",
			fixedSize: false,   
        
            position: {
                  x: 12.32,
                  y: 14.56
            }
      }, {
            id: "5105701/10/107",
            label: 'Room 02'
      }, {
            id: "5105701/10/106",
            label: "Room 03"
      }, {
            id: "5105701/10/7",
            label: "Room 03"
      }]
};

Options:

Parameter	Default Options	Object	Description

Parameter	Default Options	Object	Description
^domain	x		Applicable if IDs given are from external domain
^objectClass	x		External object class (only used with domain ID
^iconId	x	x	Common icon ID for all objects (check icon ID in system configuration) Can be used per object
^{sizePercentage}	x	x	If the real icon size is not adequate, it can be altered by changing this parameter accepted values are between 1 and 100. It will be applied evenly to width and height to maintain proper aspect ratio Can be used per icon.
^alignTo	x	x	Optional icon alignment parameter, can be used per object. Available options for optional alignTo parameter C - Center LT - Left Top RT - Right Top LB - Left Bottom RB - Right Bottom L - Left R - Right T - Top B - Bottom
^fixedSize Since v3.7	x	x	Indicate a default value for icon fixed size: true - icon will maintain its size independent from zoom level false - icon will be resized to match current zoom level
^position		x	Optional fixed position of the icon (can be saved and restored by an external system) `position: { x: 12.32, y: 14.56 }`
id		x	Internal or external domain ID (see domain config above)
^label		x	Optional object label for the context menu
^{allowChangeOwnerObject} Since v4.4			When set to TRUE, a user can drag and drop given symbol on any vector entity that has links to objects. The target object will be updated in symbol properties.
^{allowedOwnerClasses} Since v4.4			Can be set to an array of allowed object classes. Example: allowedOwnerClasses = [108] An internal class ID must be given. No conversion or class name is supported here. Note: for a drop to be successful a single object must be identified in given location. For example, if we have a kitchen cabinet inside of a room, and you want to allow drop of objects in that location (over a cabinet), please specify "Room class" as allowed owner. In such case a drop will be allowed all over the room, as only one object of class room will be identified in this location.

Menu - Callback Function

A function given as callback in configuration must be set before the configuration object is created and passed to HD.EmbeddedAPI.

Menu configuration parameters:

Parameter	Value	Description

Parameter	Value	Description
^name	String	Name of the menu item
^callback	Function	Callback function that should be called when menu item is selected
^context	Object	Context that should be set for callback
^iconCls	String	Icon class to be used, choose from any FontAwsome 5 icons Choose from gallery of icons in Regular type: https://fontawesome.com/icons?d=gallery&s=regular

A test function can look like this:

var myFunction = function(params){console.log(params)};

The function will be called with a proper context as set in configuration and with "parameters" argument containing the following information:

Events

Symbols are a special case of Spots, and support the following events:

*.*.user.spot.select
*.*.spot.update - warning - this event is fired continuously while updating spot
ui.drawing.entity.changed - fired once per entity when change is complete
ui.drawing.symbol.ownerchanged - fired when "owner object" for given element was changed successfully.

Note: the external ID of object is not updated when these events are fired. To obtain external IDs either convert these objects using eid2hdid function or call getSymbols() with "convert" parameter set to true.

Samples:

with payload:

Change Icon Location

A preset Icon position can be passed for each object in a configuration:

A position of an Icon can be changed by the user. Later on, the position can be recorded as a reaction to event or by using getSymbols() function.

Functions

Function	Description	Arguments

Function

Description

Arguments

HD.EmbededApi.clearSymbols()

Clear all symbols on the current drawing

N/A

HD.EmbededApi.setSymbols(symbols);

Set symbols according to passed configuration

Symbols definition object as described in this manual.

HD.EmbededApi.getSymbols(convert, callback, context)

Get current state of symbols, including their position

convert - true/false (convert to external ID)

callback - callback function only used when convert set to true;

context - context for callback function

HD.EmbededApi.getSymbols

Returned payload:

Please note that only internal objectId is always updated.

External object Id is converted only on request. If externalDataDirty flag is set to true, it means that this data was changed and not updated.

getSymbols with convert and callback

HD.EmbededApi.getSymbols(convert, callback, context)

callback function signature/arguments:

success - indicates if convert operation was successful
symbols - symbols are returned both with success and failure in convert. Note: unconverted symbols are marked as dirty.

Performance

If a high frequency refresh rate is needed for the same objects, it is advised to perform object conversion from external to internal domain once, and then use internal object class and ID to set symbols.

Otherwise, when objects are passed with external domain, conversion and server round-trip will be performed for every call. HD.EmbededApi.convertEid2hdid function can be used for this conversion.

HyperDoc (HDC) Manual

(no) Temporal Symbols (Icons)