addSymbol()

Adds a panel reference in a panel or layout at a later time during run time. To suppress the Initialize scripts of the reference the function createSymbol() can be used instead.

Synopsis

int addSymbol(shape panel | (string moduleName, string panelName), string fileName, string refName, dyn_string subst, int x, int y, float angle, float scx, float scy[, string ewoName]);

Vertical or Horizontal Layout

int addSymbol(shape panel | (string moduleName, string panelName), string fileName, string refName, int index, string layout, dyn_string subst = makeDynString());

Grid Layout

int addSymbol(shape panel | (string moduleName, string panelName), string fileName, string refName, int row, int column, string layout, int rowspan = 1, int columnspan = 1, dyn_string subst = makeDynString());

Table Header - Vertical alignment

addSymbol(shape panel | (string moduleName, string panelName), string fileName, string symbolName, mapping options);

Parameter


Parameter	Meaning
panel	A shape variable pointing to a panel. Either this parameter or the combination of moduleName and panelName can be used to define the target.
moduleName, panelName	Module and panel name of the target as string. In order to add an object in a tab, both parameters have to be replaced by the functions myModuleName() and myPanelName(). If an empty string "" is used instead of myPanelName(), the tab is used as this panel.
fileName	File name under which the reference is stored.
refName	Name of the reference, that is unique (Module Name + Panel Name) with which the reference can be addressed, for example from a Control script.
symbolName	A symbol is shown in a shape that is specified via the mapping options - see below.
options	The mapping can optionally contain the following keys (string) (data type of the value in brackets): "dollars" (dyn_string) ... dollar parameter "targetShape" (string) ... name of the shape in which the symbol should be displayed (currently only a maps or table shape is possible). "columnHeader" (string) ... only if a table shape is used as targetShape, the name of the column is specified here, in whose header area the symbol will be displayed. For an example of table header - vertical alignment, see chapter addSymbol() - Example for vertical Alignment of a Table Column. Note: If an icon is used in a column header, the usual column name/icon is not displayed. If the column name is wrong, -1 is returned. In case of incorrect data (e.g. wrong column) the panel reference still exists in the panel, but its scripts may not be started and will not be displayed correctly in the targetShape.
subst	Definition of $ parameters (similar to opening a panel).
x, y	Are the coordinates at which the reference refName is displayed in the panel panelName.
angle	Relative rotation around the reference point of the panel reference to be displayed.
scx, scy	Scaling with center in the reference point of the panel reference to be displayed.
ewoName	Name of the EWO to which shapes should be added. Currently this is supported by the GisViewer.ewo only.
index	The position inside of the layout to which the symbol should be added. The index count is started at 0.
layout	Name of the layout object to which the object should be placed.
row	The horizontal position inside of the grid to which the symbol should be added. The row index count is started at 0.
column	The vertical position inside of the grid to which the symbol should be added. The column index count is started at 0.
rowspan	The number of horizontal grid areas the symbol should use. (optional)
columnspan	The number of vertical grid areas the symbol should use. (optional)

Return Value

Returns 0, in the event of a failure returns -1.

Errors

Missing arguments in the function.

Description

This function can be used to insert panel references in a panel or objects into a layout at a later date during run time. All symbols that are loaded later are removed when the panel is closed or with the function removeSymbol().

When using the function addSymbol(), the active element which starts the addSymbol() command, looses the focus. The focus switches to the last inserted element.

For example: a cursor moves up or down in a combo box, and each entry inserts an element using addSymbol(). This works only once, because the cursor switches to the inserted element.

For keeping the focus on the object, you set the focus by using setInputFocus() back to the object:

setInputFocus (myModuleName(), myPanelName(), this.name);

If an object is loaded into a reference via the addSymbol() function and an acknowledgement was configured for this object, the acknowledgement data point is not loaded into the panel when configuring sum alerts via the +panel button. The acknowledgement data point is not loaded since the addSymbol() is called first at runtime and the data point is not available yet.

When adding a reference into a horizontal or vertical layout the reference is appended after the stated position whereas for a grid layout the reference is added to the stated position. In either case the layout is extended with the stated position if the stated position did not exist before.

When adding a reference it is assigned to the panel and correspondingly functions called within the reference that affect a panel also are applied to the container panel, e.g. PanelOff() within the reference will close the whole panel.

There is no hierarchy of panel references that have been added using addSymbol().

Shapes inside panels loaded with addSymbol() can be addressed as panelName.shapeName. However, additional levels of nesting are not possible (e.g.: panelNameA.panelNameB.shapeName will not work). The shapes can be addressed directly, in which case shapes with the same name in different instances of a panel cannot be distinguished.

Inserts "pump" in the top left corner (0,0) of the "overview" panel in the "gedi" module.

main()
{
addSymbol("gedi","overview","pump","p1","",0,0,0,1,1);
}

Adds the reference "Reference1" containing two graphics elements to the panel "Ellipse" and passes the colors for the objects as dollar parameters "$p1:"+"blue","$p2:"+"green". In the first example the panel "Ellipse.pnl" is opened in the module "Ellipse". In the second example the reference is added to the panel "Ellipse.pnl" using addSymbol().

In the reference "Reference1", set the colors of the graphics objects using the dollar parameters <ShapeName>.backCol($p1); , for example, ELLIPSE1.backCol($p1);

main()
{
  ModuleOnWithPanel("Ellipse",50,50,70,70,2,2,"None","Ellipse.pnl",
    "Ellipse",makeDynString());
}

main()
{
  addSymbol("Ellipse", "Ellipse", "Referenz1.pnl", "Ref1",
    makeDynString("$p1:"+"blue","$p2:"+"green"), 50, 50, 0, 1, 1);
    }

Assignment

Graphics function