Options (object)

From GCAWiki

The Options object is primarily used in the Options variable. It is used to access the sheet profile options.

Contents 1 Option type constants 2 Properties & functions 2.1 AddOption() 2.2 Value() 3 Styling 4 Font control 4.1 ReturnFontName() 4.2 ReturnFontSize() 4.3 ReturnFontBold() 4.4 ReturnFontItalic()

Option type constants

GCA defines some constants for the various types of options and their associated interfaces. The options type constants are:

Common name		Constant		Interface		Use/return value
optVar		-99		none		Used for internal variables only and has no associated interface element
optHeader		-1		Section header & spacer		Used to separate options into sections and as a general spacer
optYesNo		0		Yes/No radio button		Returns a boolean
optTrueFalse		1		True/False radio button		Returns a boolean
optList		2		Drop-down list		Returns the value of the selected item
optListNumber		3		Drop-down list		Returns the index of the selected item
optListFlag		4		Checkbox list		Returns a long integer bit-field
optColor		5		Color picker		Returns the color as an long integer
optFont		6		Font settings		Returns the font properties as a pipe-delimited string
optText		7		Text box		Returns a string
optListOrdered		8		Orderable list		Returns the user ordered list
optCaption		9		Caption		Used to add captions
optListArray		10		Checkbox list		Returns a 1-base-index array of true/false values

Properties & functions

AddOption()

Description: Creates a new interface element in the Character Sheet Options window. The values of data control elements can be accessed via the Value method.

Prototype: AddOption(Name [, Type [, List [, Default [, Prompt [, Style]]]]])

Parameters:

Name 

[String] The unique name by which the option will be referenced.

Type 

[Integer] Optional: The type of the control. Default: 0.

List 

[String] Optional: The pipe-delimited list of items, for use with the list controls. Default: none.

Default 

[String] Optional: The default value/selection; see Font control below for more information on fonts. Default: True. [tmedwards: Should be by type? CHECK THIS!]

Prompt 

[String] Optional: The text explaining the option. Default: "Select an option".

Style 

[String] Optional: The style to be applied to the control; see Styling below for more information. Default: none.

Returns: no return value

Notes: A blank space/line can be obtained by adding a header type control with an empty string for the prompt.

Example:

'header
Options.AddOption "HeaderDefenses", -1, , , "Defenses Options"

'spacer
Options.AddOption "Spacer23", -1, , , ""

'list with a light blue background and red prompt text
Options.AddOption "DRDisplayType", 3, "Single DR value|Expanded DR table", 1, "Print damage resistances as:", &HFFEEEE& & "|" & &H0000FF&

Value()

Description: Accessor method for the values of the options.

Prototype: Value(OptionName)

Parameters:

OptionName 

[String] The name of the option whose value should be returned.

Returns: [Variant] The value of the selected option.

Example:

Options.Value("DRDisplayType")

Styling

A style consists of a pipe-delimited list of elements which correspond to the parts of a control which can be styled. All style elements are optional and may be left empty, in which case the associated part of the control will retain its default styling. Empty elements which appear to the right of the last non-empty element may be omitted (e.g. these are equivalent: "|0|True" and "|0|True||||").

All controls, except captions, have the same basic style elements, while captions have several additional elements available to them.

Basic format: [ BackColor [| ForeColor ]]

BackColor 

[Long] Optional: The background color of the control, includes margins. Default: none.

ForeColor 

[Long] Optional: The prompt text color. Default: 0 (i.e. black).

Caption format: [ BackColor [| ForeColor [| Bold [| Italic [| TopMargin [| BottomMargin [| InnerBackColor ]]]]]]]

BackColor & ForeColor 

(identical to those the basic format)

Bold 

[Boolean|String] Optional: Whether the prompt text will be bold. Default: False.

Italic 

[Boolean|String] Optional: Whether the prompt text will be italic. Default: False.

TopMargin 

[Long] Optional: The top margin of the control (in twips). Default: 60.

BottomMargin 

[Long] Optional: The bottom margin of the control (in twips). Default: 60.

InnerBackColor 

[Long] Optional: The background color of the control, excludes margins. Think of this as another background layer on top of BackColor, but that stops at the inner-border of the control.

The True/False boolean for Bold & Italic may either be the actual boolean value or simply the word itself.

Font control

The font control takes and returns a pipe-delimited list of a font's properties. Optional elements may be left empty, in which case the associated font property will retain its default setting. Empty elements which appear to the right of the last non-empty element may be omitted (e.g. these are equivalent: "Arial|10" and "Arial|10||").

Font properties: Name [| Size [| Bold [| Italic ]]]

Name 

[String] The background color of the control, includes margins. Default: none.

Size 

[Double] Optional: The size of the font (in points). Default: 8.

Bold 

[Boolean|String] Optional: Whether the font is a bold variant. Default: False.

Italic 

[Boolean|String] Optional: Whether the font is an italic/oblique variant. Default: False.

When used as a default value for AddOption, the True/False boolean for Bold & Italic may either be the actual boolean value or simply the word itself. When storing or returning font properties, GCA uses the words themselves (e.g. "Arial|8|False|False").

To make it easy for sheets to access returned font properties, GCA has built-in functions that take a font properties list and return an individual element.

ReturnFontName()

Description: Takes a font properties list and returns the font's name.

Prototype: ReturnFontName(FontPropList)

Parameters:

FontPropList 

[String] A font properties list.

Returns: [String] The name of the font.

Example:

ReturnFontName("Arial|8|False|False")

ReturnFontSize()

Description: Takes a font properties list and returns the font's size.

Prototype: ReturnFontSize(FontPropertiesList)

Parameters:

FontPropList 

[String] A font properties list.

Returns: [Double] The size of the font (in points).

Example:

ReturnFontSize("Arial|8|False|False")

ReturnFontBold()

Description: Takes a font properties list and returns whether the font is a bold variant.

Prototype: ReturnFontBold(FontPropertiesList)

Parameters:

FontPropList 

[String] A font properties list.

Returns: [Boolean] Whether the font is a bold variant.

Example:

ReturnFontBold("Arial|8|False|False")

ReturnFontItalic()

Description: Takes a font properties list and returns whether the font is an italic/oblique variant.

Prototype: ReturnFontItalic(FontPropertiesList)

Parameters:

FontPropList 

[String] A font properties list.

Returns: [Boolean] Whether the font is a italic/oblique variant.

Example:

ReturnFontItalic("Arial|8|False|False")