Referencing an Object Using a Name at Runtime
- Last UpdatedJul 18, 2023
- 3 minute read
Use the Cicode functions DspGetAnFromName, DspGetMetadataFromName, DspGetAnFromNameRelative and DspGetMetadataFromNameRelative to reference objects on a page, in a genie, group and symbol.
It is important to keep the following points in mind when referencing objects:
-
When referencing an object within a genie, group or symbol you need to use relative path syntax. This means you can search "up" or "down" the objects within the genie, symbol and/or group.
-
The name is always relative to the object you are referencing from.
-
If referencing an object within a group it will search only in the group the object belongs to.
-
If referencing an object at the group level it will search for the object across the defined paths.
Using the Syntax
-
"Name" – Used at page level. This is a fully qualified name.
-
".Name" - References itself, either in a group, genie or symbol.
-
"..\Name" – References objects within a group.
Examples
The diagram below includes objects and text on the page, and objects and text within groups A, B and C. A tree-view hierarchy has been used to illustrate how referencing can be applied.
|
Referenced Object |
Syntax |
Description |
|---|---|---|
|
To reference "Object1" from Object2 at the root or page level |
DspGetAnFromName("Object1") |
Object1 is a fully qualified name. Searches at page level for this object. |
|
To reference "Object1" from Object2 at the root or page level. |
DspGetMetadataFromName("Object1","Pump") |
Object1 is a fully qualified name. Pump is the name of the metadata defined in Object1. Searches the page level for Object1 and the metadata name. |
|
To reference "Object1" in GroupA from Object2 from the root level |
DspGetAnFromName("GroupA.Object1") |
"GroupA.Object2" is a fully qualified name. From the root (page) level search for Object1 within GroupA. |
|
To reference "Object5" in GroupC from Object2 at the root level |
DspGetAnFromName("GroupA.GroupC.Object5") |
"GroupA.GroupC.Object5" is a fully qualified name. From the root (page)level search for Object5 within GroupC and GroupA. |
|
To reference"Object1" in GroupA from Object4 |
DspGetAnFromName(".Object1") |
".Object1". This means search for Object1 in the current group. |
|
To reference"Object2" in GroupA from Object8 in Group B |
DspGetAnFromName("..\..\GroupA.Object2") |
"..\..\GroupA.Object2" Navigate two levels up the hierarchy, which will be root (page) level, and then search for GroupA and within Group A, Object2. |
|
To reference"Object2" in GroupA from Text8 in Group B |
DspGetAnFromNameRelative(639, "..\..\GroupA.Object2") |
From AN 639 and "..\..\GroupA.Object2" navigate two levels up the hierarchy and search for Group A and within Group A, Object2. Note: 639 is the animation number for Text8 once pasted on the graphics page within GroupB. |
|
To reference"Object2" in GroupA from Text8 in Group B |
DspGetMetadataFromName("..\..\GroupA.Object2", "Meter") |
"..\..\GroupA.Object2" Navigate two levels up the hierarchy which will be from the root (page)level, and then search for GroupA and within Group A, Object2, where the name of the metadata is "Meter". |
|
To reference "Object1" at the root level from Object5 in GroupC |
DspGetAnFromName("..\..\..\Object1") |
"..\..\..\Object1" Navigate three levels up the hierarchy which will be from the root (page)level, and then search for Object1. |
|
To reference "Object1" at the root level from Text5 in GroupC |
DspGetMetadataFromNameRelative(625, "..\..\..\Object1", "Pump") |
From AN 625 navigate three levels up and from the root level search for Object1 where the name of the metadata is Pump. Note: 625 is the animation number for Text6 once pasted on the page within GroupC. |
Note: When referencing from an object within a group, only those objects in the group the object belongs to will be searched. For example: If you reference Object1 in Group A from Object7 in GroupB using the syntax "..\Object1", an error will be returned, as no Object1 exists in GroupB. The correct syntax to use is "..\..\GroupA.Object1".