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, seeData 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 0x000000ff

 

The 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% opaque

 

You 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. You can pass a negative value to subtract the specified component. The methods can be chained together to modify multiple components. For example:

 

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 PM

 

datetime.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 represent the time delta in the desired time units.

 

dt = CreateDateAndTime(13, 8, 2014, 46, 31, 10)

//Aug 13 2014, 10:46:31 AM

new_dt = dt.AddMinutes(10)

//Aug 13 2014, 12:56:31 PM

 

days = new_dt.DaysSince(dt)

// 1.006944

negdays = dt.DaysSince(new_dt)

// -1.006944

 

 

You can apply selectors to array elements or other selectors:

 

lonvalue = x[1].lon

latvalue = circ.center.lat

 

You can use these functions for getting the definition of a fill style or a line style:

 

GISDK Function	Summary
GetFillStyleDefinition()	Returns an array defining the fill style
GetLineStyleDefinition()	Returns an array defining the line style

 

You can also use these functions with DateTime compound variables; for more information, see DateTime Functions:

 

GISDK Function	Summary
CreateDate()	Creates a DateTime compound variable with just a date
CreateTime()	Creates a DateTime compound variable with just a time
FormatDateTime()	Formats a DateTime compound variable
ParseDateTime()	Parses a string to create a DateTime compound variable