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

intaddSymbol(stringmoduleName,stringpanelName,stringfileName,stringrefName,dyn_stringsubst,intx,inty,floatangle,floatscx,floatscy[, string ewoName]);

Vertical or Horizontal Layout

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

Grid Layout

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

Parameter

Parameter Meaning
moduleName, panelName

Module and panel name of the target.

In order to add an object in a tab, the both parameters have to be replaced by the functions myModuleName() and myPanelName(). If an empty string "" is used instead of myPanelName(), so the tab is used as this panel.

fileName File name under which the reference was stored
refName Name of the reference name that is unique (Module Name + Panel Name) with which the reference can be addressed, for example from a Control script.
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().

Using the addSymbol(), the active element which is starting 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.

Example

Inserts "pump" later 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);
}
Example

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

Availability

UI