Compound Variables
Compound variables are special objects in the Caliper Script language that make it easy to program certain functions. You create compound variables using the following functions:
| Type | Creation Function | Definition |
|---|---|---|
| Circle | Circle() | A circular area on the world |
| Color | ColorRGB() | A color (red, green, blue, and alpha) |
| Coord | Coord() | A location on the world (coordinate) |
| Data Cursor | CreateDataCursor() | A GISDK object for navigating and reading tabular data; for more information, see Data Cursors |
| DateTime | CreateDateTime() | A date and/or a time |
| DLL Handle | CallDllFunction() | A DLL handle |
| File Handle | OpenFile() | A reference to an open file |
| Fillstyle | FillStyle() | A pattern used to fill the interior of areas on a map |
| Linestyle | LineStyle() | A style for drawing lines on a map |
| Managed Object | CreateManagedObject() | A .NET object |
| Sample Area | SampleArea() | An example of how an area on a map is displayed |
| Sample Line | SampleLine() | An example of how a line on a map is displayed |
| Sample Point | SamplePoint() | An example of how a point on a map is displayed |
| Sample Text | SampleText() | An example of how text is displayed |
| Scope | Scope() | A portion of the world covered by a layer or feature |
| TIN | CreateTriangulation() | A Triangulated Irregular Network (TIN) |
| Vector | Vector() | An array with any number of elements of the same type |
Many functions return compound variables, or require compound variables as arguments, or both. This GISDK macro, for example, sets the color of the County layer to match the color of the State layer:
clr = GetBorderColor("State")
// clr is a compound variable containing the color
SetBorderColor("County", clr)You can retrieve and modify individual components of some compound variables using selectors. A selector is a keyword following a variable name and period:
x = Coord(-91250000, 45500000)
lonvalue = x.lon
latvalue = x.lat
x.lon = -916500000| Type | Valid Selectors |
|---|---|
| Circle | radius, center (cannot be set) |
| Color | red, green, blue, rgb, alpha (opacity) |
| Coord | lon, lat |
| Data Cursor | record, id |
| DateTime | day, month, year, hour, minute, second, millisecond |
| DLL Handle | filename |
| Scope | center, width, height, angle |
The rgb selector for a color handles the standard RGB representation of a color in a 4-byte integer. The red value is in the least significant byte, green in the second byte and blue in the third byte. The rgb selector can be used to both get and set the color value, and it can be especially useful when dealing with color attributes in COM objects. For example:
red_color = ColorRGB(65535, 0, 0)
obj.FillColor = red_color.rgb // value will be 0x000000ffThe alpha selector for a color sets the opacity of the color, from 0 (clear) to 65535 (completely opaque).
red_color = ColorRGB(65535, 0, 0)
red_color.alpha = 32767 // color will be 50% opaqueYou can also use the following methods on a DateTime compound variable to add time to a date or compute the time difference between dates:
datetime.AddYears(int years)
datetime.AddMonths(int months)
datetime.AddDays(int days)
datetime.AddHours(int hours)
datetime.AddMinutes(int minutes)
datetime.AddSeconds(int seconds)
datetime.AddMilliseconds(int milliseconds)
In each case, the method adds to the compound variable an integer value for the component of the date or time, and returns a new DateTime value.
dt = CreateDateTime(13, 8, 2014, 10, 46, 31, 0)
// Aug 13 2014, 10:46:31 AM
new_dt = dt.AddHours(2).AddMinutes(10)
// Aug 13 2014, 12:56:31 PMdatetime.DaysSince(date a_date)
datetime.MinutesSince(date a_date)
datetime.SecondsSince(date a_date)
datetime.MillisecondsSince(date a_date)
In each case, the method computes the time difference between the two dates and returns a real that represents the time delta in the desired time units.
dt = CreateDateTime(13, 8, 2014, 10, 46, 31, 0)
new_dt = dt.AddMinutes(10)
days = new_dt.DaysSince(dt)