Using Options Arrays

Many GISDK functions take an array of options as a parameter. Each element in an options array is an array of two (or more) elements. The first element (the option key) in each sub-array is a string specifying the name of the option. The option keys are case insensitive.  The second and subsequent  elements  (the option values) of a sub-array give the values for the option. For example, the following options array contains two options (Layer Name and Label) and their associated values:

 

options_array = {

     {"Layer Name", "Counties"}

     {"Label", "Counties of the Northeast"}

     {"Font Size", 16}

     }

 

Options arrays can be expressed using a syntax shortcut.  The following expression is equivalent to the example above:

 

options_array = { "Layer Name": "Counties" ,  "Label" : "Counties of the Northeast", "Font Size":16}

 

In Maptitude 2021 and subsequent versions the option keys are space-insensitive:  Therefore, the example above can also be expressed as:

 

options_array = { "LayerName" : "Counties", "Label" : "Counties of the Northeast" , "FontSize": 16}

 

Furthermore, quotes can be omitted, when using the syntax short-cut,  as long as the option key includes no spaces

 

options_array = { LayerName : "Counties", Label : "Counties of the Northeast", FontSize: 16}

 

Please note that the option key should be a string, numeric values are not permitted.  The following expression would result in an error:

 

options_array = { 1: "Counties" ,  2:  "Counties of the Northeast"}

 

You can use a dot notation to get, set, add, and remove options in options arrays. For more information, see "Options Arrays and Dot Notation" in Arrays.

 

If you don't need to pass any options to a GISDK function, you can pass null for the options array.

 

Some GISDK functions also return options arrays. In general, you should not rely on the order in which options appear in a returned options array. Instead, to locate specific options within an options array, use the GISDK functions:

 

GISDK Function	Summary
FindOption()	Finds a particular option and its setting in an array of name-value pairs
FindOptionValue()	Finds the value of a particular option in an options array

 

In addition, some GISDK functions, like AddAnnotation() and GetAnnotation() accept or return information in the same format as an options array. You can use these same GISDK functions to manipulate these arrays.