Flash Drawing Control

API for Flash Drawing Control

Note: With the release of ARCHIBUS V.23.2, all ARCHIBUS views were converted to use the HTML drawing control instead of the Flash drawing control. If you have previously created views that use the Flash drawing control, the view's drawings will still work.

For new views that you create, ARCHIBUS, Inc. recommends using the HTML control, as the Flash control is slated for desupport in future versions of ARCHIBUS. For information on converting existing views with Flash drawings to HTML format, see Convert views with the Flash drawing control to the HTML drawing control.

The Flash Drawing Control has following list of exposed properties:

Property	Description
_delim	This determines the delimiter that is used when working with some data such as a concatenated string of primary keys such as: ‘HQ;17;101’. The default is ‘;’.
optionalPKFields	A list of optional fields that specifies other data values that should be returned in the ‘onclick’ handler other than the default primary key information of the selected asset.

The Flash Drawing Control supports the following events:

Event	Description
onclick	Is fired when an asset is selected with a mouse in the Drawing Control. This event will returns the following information: 1) The selected ids (with `optionalPKFields` as specified above) 2) `true` or `false`, indicating if the asset is selected or unselected. 3) And optionally a color, only when `assignMode` is > `0`.
onload	Is fired after the Flash Control has fully loaded. No information is returned with this event.
onresetassets	Is fired when the ‘Reset Rooms’ button is clicked. No information is returned with this event.
ondatasourcechanged	Is fired anytime a datasource used in the Drawing Control is applied. This event will return the following information: 1) The type: 1 = Labels, 2 = Highlights 2) The datasource name.
onselecteddatasourcechanged	Is fired when a datasource is changed from either of the Highlight or Labels drop down boxes. 1) The type: 1 = Labels, 2 = Highlights 2) The datasource name.
onhighlightschanged	Is fired after a highlight datasource has been applied and all assets in the drawing have been refreshed.

The Drawing Control has following list of exposed methods:

Method	Description
addDrawing(ob, options[optional])	Adds a drawing to the view. `ob`: An `Ab.drawing.DwgCtrlLoc`, `Ab.grid.Row` or an `Ab.view.Restriction` object. `options`: A `DwgOpts` object that provides greater control over initial display.
removeDrawing(ob)	Removes a drawing from the view. `ob`: An `Ab.drawing.DwgCtrlLoc`
clear()	Removes all drawings from the view.
clearHighlights(ob[optional])	Clears existing highlights from the specified drawing. If `ob` is not specified then all highlights are removed from all displayed drawings. `ob`: An `Ab.drawing.DwgCtrlLoc`
highlightAssets(options, row[optional])	Highlight the specific assets. `options`: A `DwgOpts` object. `row`: An `Ab.grid.Row` object.
findAsset(ob, opts, zoomTold, loadDwg, bSelected)	Finds an asset, will load the drawing if needed. `ob`: A `Ab.drawing.DwgCtrlLoc`, `Ab.grid.Row` or `Ab.view.Restriction` object. Required `opts`: A `DwgOpts` object for overriding fill defaults. Optional, defaults to null. `zoomToId`: Boolean to zoom in or not to the roomId. Optional, defaults to `false`. `loadDwg` : Force the drawing to load if not already loaded. Optional, defaults to `true`. `bSelected`: Forces The selection to be `true`/`false`. Optional
isometric (isometric, apply)	Depending on the provided Boolean, turns isometric project on/off. `isometric`: `true` to set to an ‘isometric’ view, `false` to set to a ‘tiled’ view. `apply`: Refresh the display with this setting, `true` or `false`.
getSelectedAssetIds()	Returns a list of currently selected assets in the loaded drawings.
setSelectColor(color)	Allows the app to override the default fill color from the drawing-control.xml file that is applied when assets are selected. This setting can be used in conjunction with the ‘assignMode’ attribute is set to a non-zero value.
setToAssign(field, value, color)	This is used in conjunction with the ‘assignMode’ attribute being set to `1` (One-to-One assign logic). This instructs the Drawing Control to apply the color for the specified field and value when an asset is selected in the Drawing Control.
appendNoFillValue(value, fill)	Allows the app to specify particular values that should not be filled. The specified fill will be used instead when highlighting is being applied to the drawing. `value`: Value that is to be overridden when highlighting. `fill`: A `DwgFill` object
appendRuleSet(name, ruleSet)	Appends a rule set. See the section on Rule Sets for more information. `name`: An identifier for the ruleset. `ruleSet`: A `DwgHighlightRuleSet` object
appendInstruction(ctrlId, eventName, msg, onlyIfDwgLoaded)	Appends an instruction that will be displayed in the Drawing Control title bar under certain conditions. `crtlId`: A Control Id that contains the event to be monitor. `eventName`: The name of the event to be monitored. `msg`: A message to be displayed when the specified event is fired. `onlyIfDwgLoaded`: Boolean that specifies if the message should only be displayed if a drawing is actually loaded.
setToolbar(action, option, names)	Shows/Hides or Enables/Disables toolbar buttons. `action`: ‘show’ or ‘hide’ `option`: `true` or `false` `names`: List of toolbar button names. See the ‘toolbarSettings’ in the Panel Attributes table for more information.
toolbarCmd(buttonName)	Executes the command associated with the specified `buttonName`. See the ‘toolbarSettings’ in the Panel Attributes table for a list of valid button names.
setSelectabilty(options, selectable)	Allows the application developer to manually set a group of specified assets to be selectable or not selectable. `options`: A `DwgOpts` object containing a list of assets. `selectable`: `true` or `false`
setLabels(loc, opts, mode)	Manually sets label text on specified assets. `loc`: An `Ab.drawing.DwgCtrlLoc` object. `opts`: A `DwgOpts` object. `mode`: Specifies how to apply the labels in the `opts` argument. Valid options are: `0`: Replace existing label `1`: Replace per Field, only specified fields will be replaced. `2`: Append to the end of the existing label. `3`: Remove per Field, only specified field/value pairs will be removed. `4`: Remove All, remove the entire contents of a label. `5`: Reset, restore to the original datasource generated label contents.
setDrawingTitle()	Sets the display text that is displayed below the drawing. By default this is the building/floor name.
clearAssignCache()	When the ‘assignMode’ attribute is set to something other than `0`, then this is typically called after a group of assignments have been committed to the database. When ‘assignMode’ is > `0`, it internally keeps track of assignments that have been temporarily made, which is independent of anything else that the application itself may be keeping track of. This method will clear the cached assignments.
clearPersistFills()	Clears any existing preset persistent fills. See the `DwgOpts.persistRecFills` for information on how to set.
print()	Returns an array of bytes containing a PNG image to be printed. (Not currently supported)

DwgOpts Object

The ‘options’ argument where used in the above methods is a DwgOpts object which provides a great deal of control over the Drawing Control for the application developer. In most common situations, the use of a DwgOpts object is not needed, but in instances where an application needs to externally manage the highlighting and labels, this is the object that is used to handle that.

The following table describes the available properties and methods on this object:

Properties
Name	Type	Purpose	Default Value
assetType	String	A list of asset file types to load, as a comma delimited string. The default is ‘rm’. This provides a mechanism for the application developer to load non-rm based asset files, such as ‘su’. Currently, only a single asset file can be loaded at a time.	‘rm’
assetSuffix	String	Used by default views (e.g. the hazmat plan). Loads highlights for assets whose names do not match their table names.	undefined	.
backgroundSuffix	String	Specifies an alternate background file to be loaded for situations where you want to have different versions of a drawing file. For example, you might want to have a drawing that shows only room boundaries, and another version that shows the departments and employees assigned to each room. For this property to work, you must have already saved the drawing file with a suffix, such as hq17-alternate. The suffix can be any string that you choose to identify the file. You can then use the background Suffix property to specify the additional version of the drawing.
highlightId	String	A single asset to apply the ‘assigned’ fill to
zoomToId	Bool	If the `highlightId` value is set, zoom into asset on load	false
multiple	Bool	Is loading of more than one drawing at a time supported	true
exclusive	Bool	Only the `highlightId` will have the ‘assigned’ fill applied to it. All others will have the ‘unassigned’ fill applied to them.	false
fill	DwgFill	Overrides the ‘assigned’ highlighting fill as specified in the drawing-control.xml file. This provides a way for application developers to manually control ‘assigned’ highlighting colors per their application’s needs. Setting the ‘mode’ property is a simpler way to control this in most circumstances, but using this ‘fill’ parameter will provide higher level of control of the highlighting.	undefined
mode	String	This specifies logically the type of highlighting that will be applied to the list of records associated with this `DwgOpts` object. Supported options are: ‘assigned’, ‘unassigned’, ‘selected’, ‘unselected’, ‘’ (an empty string)	‘’ (an empty string)
selectionMode	String	Determines which assets if any can be selected in the Drawing Control. Supported options are: ‘0’: Selection is disabled, ‘1’: Only ‘assigned’ assets, per the Drawing Control ‘highlightDataSource’ attribute, ‘2’: All assets are selectable	‘2’
assignMode	assignMode	This enables ‘assignment’ type of logic internal to the Drawing Control to graphically manage highlighting the type of assignment being done. Supported options are: ‘0’: Disabled, ‘1’: One to One, ‘2’: One to Many, ‘3’: Many to One, ‘4’: Many to Many	‘0’
multipleSelectionEnabled		Allow more than asset to be selected at a time. The ‘assignMode’ setting will override this if it is set to a non disabled mode.	true
forceload	Bool	Not currently supported	true
persistRecFills	Bool	If highlightAssets is called with this set true, the specified fills will override datasource changes.	false
folder		For internal use only, do not modify.
dwgName		For internal use only, do not modify.
recs		For internal use only, do not modify.

Methods

Name Arguments Purpose

setFillColor color: An RGB value in hex form.
e.g. ‘ff03e9’ In most cases, when applying highlighting, all that needs to be set is the color itself, not all of the other associated parameters. This method provides a simpler way of just specifying the color without the overhead of creating a DwgFill object.

appendRec

Methods
setFillColor	`color`: An RGB value in hex form. e.g. ‘ff03e9’	In most cases, when applying highlighting, all that needs to be set is the color itself, not all of the other associated parameters. This method provides a simpler way of just specifying the color without the overhead of creating a `DwgFill` object.
appendRec	`id`: The full id of a record to append (Required) e.g. ‘HQ-17’101’ `fill`: A `DwgFill` object. The fill to be applied specifically to this asset. (Optional) `label`: Not currently supported `asHighlight`: Use the specified id as the ‘highlightId’. `true` or `false` (Optional)	This allows application developers to manually control on a per asset basis the highlight and label applied to the specified ids.

id: The full id of a record to append (Required)
e.g. ‘HQ-17’101’

fill: A DwgFill object. The fill to be applied specifically to this asset. (Optional)

label: Not currently supported

asHighlight: Use the specified id as the ‘highlightId’. true or false (Optional)

This allows application developers to manually control on a per asset basis the highlight and label applied to the specified ids.

Rule Sets

The Rule Set functionality allows application developers to provide the following level control over highlighting:

Specify specific colors to be associated with specific values. This will override any default colors associated with that value per the database or the default color list.
Specify colors to be associated with a range of values, such as area values.

Unlike the DwgOpts object, which requires the application developer to specify specific assets to apply colors to after the drawing is displayed, the Rule Set logic allows the application developer to specify colors for particular values as the result of a query issue against the highlightDataSource. And those colors are applied as the drawing is loaded. A typical example of the types of cases that can take advantage of this functionality is as follows:

I have an application that is highlighting all rooms that are vacant, but what I want to see is that the colors that are applied are based on the area values. Meaning I want to be able to quickly differentiate between small, medium, and large rooms.

To use this functionality, the application developer would implement this by building a DwgHighlightRuleSet object and then appending it to the DrawingControl object with the appendRuleSet method which takes two arguments:

a name, which is an existing datasource name
the ruleset object itself

The Drawing Control supports multiple datasources for highlighting, and so rule sets can be applied to all data sources if desired.

Best Practice Tip

As best practice, when you set the drawing name, do not set it within the loop for each of the row, as they are the same. Instead, you can create a variable, such as currentDwgname in your controller, and set this value each time when user clicks on the tree node. You can pass this value into the HighlightAssets() function. This helps to avoid drawing load errors when the drawing name is different than bl_id+fl_id.