Option Statement

Home • Gallery • Tutorials • Download • Purchase • Site Map
 

Option Statement Syntax

The Fractal Science Kit fractal generator option statement is 1 of the statements used in the properties section of the program instructions to define the program's Properties.

The option statement is the most common statement found in the properties section. Each option statement defines a property that can be modified by the user. The type of the associated control used to modify the property value depends on the type of the option. We have seen examples of enum options, function proxy options, and option map options in previous sections. Here we provide the complete description of the option statement.

The syntax of the option statement is:

option <OptionName> {
  type = <Type>
  caption = <CaptionString>
  details = <DetailsString>
  default = <DefaultValue>
  range = <RangeSpecification>
  hint = <HintString>
  size = <Tiny|Small|Medium|Large>
  enabled = <Expression>
  visible = <Expression>
}

The <OptionName> must be a valid identifier. The type field assignment is required, and for some types, the default field assignment is also required. Typically, most option specifications will set the type, caption, and default, and many will also set the details, range, and/or hint. The size field controls the option size for some of the types. The enabled field is used to enable/disable the option based on the value of other options. The visible field is used to show/hide the option based on the value of other options. The order of the option field assignments above is not important except that the type assignment must be given first.

When you run a program, the compiler creates a constant for each option with the same name as the option. The value of the constant is taken from the control associated with the option. Your program instructions can reference these constants to control program flow and/or set default values.

Example:

iterate:
 
  z = z^K + c
 
properties:
 
  option K {
    type = Integer
    caption = "Power"
    default = 4
    range = [2,]
  }

These instructions define a single option named K which is an Integer. The range statement restricts the value such that K is greater than or equal to 2. The default field sets the initial value for the option to 4. The caption of the control displayed on the associated Properties Page is "Power". Within the iterate section, K is used as the power to which z is raised in the fractal iteration.

Here is the resulting properties page:

Program Properties

Type

The type field determines what type of value the option will hold and the type of the control that is created on the associated properties page to allow the user to modify the option value. The type field assignment is required and must be the 1st assignment in the option statement block.

The type can be set to Complex, Integer, Float, Boolean, Color, ColorSet, SamplePointValue, GradientIndex, an OptionMap name, an Enum name, IndexedEnum, IntegerEnum, or a FunctionSet name. See below for a discussion of each of these types.

Caption

The caption is a quoted string used for the label to the left of the control on the properties page. There is limited space to the left of the control allocated for the caption, so try to choose short names. Spaces are allowed. A colon (:) is appended to the end of the caption before it is displayed.

Details

The details field is a quoted string used for a short description to the right of the control on the properties page. The different option types have differing space available for details so you may need to reduce the size of the string if it does not fit in the available space.

Default

The default is the initial value assigned to the option when it is presented to the user for the first time. The format of the default value depends on the option's type. If default is not specified, the value 0 is used. The default value must be a valid value for the option. This is true even if default is not specified. For example, enum options expect the default to be given as the enum name followed by a period (.) and the enum item name. In this case, if the default is not specified, an error will result since 0 is not a valid enum item specification.

Range

The range is appropriate only for Integer and Float options. The format for the range is:

range = [<Minimum>,<Maximum>]

The <Minimum> and <Maximum> give the minimum/maximum acceptable value for the option. If instead of brackets you use parentheses, the interval is open and the limiting values are excluded from the range. Either or both of the range limits can be open if required. Either or both values may be omitted but the comma is required. If either value is omitted, the associated minimum/maximum is not defined and the value is unrestricted. The default value for the option must fall within the given range.

Example:

properties:
  '
  ' 1 <= Count <= 8
  '
  option Count {
    type = Integer
    caption = "Count"
    default = 1
    range = [1,8]
  }
  '
  ' 1 <= Iterations
  '
  option Iterations {
    type = Integer
    caption = "Iterations"
    default = 4
    range = [1,]
  }
  '
  ' 0 < ScaleFactor
  '
  option ScaleFactor {
    type = Float
    caption = "Scale Factor"
    default = 1
    range = (0,)
  }

These options illustrate different ways the range specification can be used to restrict user input. The comments above each option give the range of acceptable values. When the user enters a value outside the acceptable range, the option is simply reset to the default value; i.e., no error message is displayed. The range is displayed in the tooltip of the control on the properties page.

Here is the resulting properties page:

Range Field Example

Hint

The option hint is a quoted string used in the tooltip of the control on the properties page.

Size

The size field is applicable only to options represented by a combobox control (i.e., SamplePointValue options, option map options, enum options, or function proxy options). It represents the size of the combobox control. The size field must be one of the identifiers Tiny, Small, Medium, or Large. By using a smaller size, the space available for the details string is increased. If size = Large, the details string will not be displayed. If size is not specified, size = Medium is assumed.

Example:

properties:
 
  enum InnerCircleTypes {
    Tangent, "Tangent"
    Rosette, "Rosette"
  }
  option InnerCircles {
    type = InnerCircleTypes
    caption = "Inner Circles"
    details = "Pattern used to generate N inner circles"
    default = InnerCircleTypes.Tangent
    size = Small
  }

This example sets the InnerCircles option's size=Small so that a smaller combobox control is created allowing for a larger details string as shown below:

Size Field Example

Enabled

The enabled field is a Boolean expression using other program properties (those that result in constants), which determines the enabled state of the control. Function proxies cannot be used in the enabled expression.

Example:

properties:
 
  enum SpiralTypes {
    Archimedean, "Archimedean"
    Logarithmic, "Logarithmic"
  }
  option SpiralType {
    type = SpiralTypes
    caption = "Type"
    default = SpiralTypes.Archimedean
  }
  option Center {
    type = Complex
    caption = "Center"
    details = "Center point of spiral"
    default = 0
  }
  option Scale {
    type = Float
    caption = "Scale"
    details = "Scale factor applied to spiral"
    range = (0,)
    default = 1
  }
  option Power {
    type = Float
    caption = "Power"
    details = "Power applied to Archimedean spirals"
    default = 1
    enabled = SpiralType = SpiralTypes.Archimedean
  }
  option Angle {
    type = Float
    caption = "Angle"
    details = "Angle applied to Logarithmic spirals"
    range = (-360,360)
    default = 135
    enabled = SpiralType = SpiralTypes.Logarithmic
  }

This example uses the current state of the SpiralType option to enable/disable the Power and Angle options. The following properties page illustrates the fact that when SpiralType option is set to the value SpiralTypes.Archimedean, the Angle field is disabled:

Visible

The visible field is a Boolean expression using other program properties (those that result in constants), which determines the visible state of the control. Function proxies cannot be used in the visible expression.

Complex Options

A Complex option is used when a complex value is required. The default value is given as a complex value or a complex expression. A textbox control is created to allow the user to enter a complex expression which is evaluated and assigned to the associated constant. The expression is usually in the form:

<Float> +/- <Float>i

However, any expression that results in a complex number is acceptable (e.g., Sqrt(-1/2)).

Example:

option Center {
  type = Complex
  caption = "Center"
  details = "Center of equilateral triangle"
  default = 0
}

This example defines a Complex option named Center with default 0. The example is displayed below:

Complex Option Example

In this example the user has set the value of Center to 0.5+0.5i.

Integer Options

An Integer option is used for integral data. Integer options support the range field to restrict the acceptable range of the user input. The default value is given as an integer number and must fall within the specified range, if any. A numeric textbox control is created for user input.

Example:

option Sides {
  type = Integer
  caption = "Sides"
  details = "Number of sides of the polygon"
  default = 3
  range = [3,16]
}

This example defines an Integer option named Sides with default 3. The valid range is given as: 3 <= Sides <= 16. The example is displayed below:

Integer Option Example

Float Options

A Float option is used for floating point data. Float options support the range field to restrict the acceptable range of the user input. The default value is given as a floating point number and must fall within the specified range, if any. A numeric textbox control is created for user input.

Example:

option Radius {
  type = Float
  caption = "Radius"
  details = "Radius of triangle circumcircle"
  default = 1
  range = (0,)
}

This example defines a Float option named Radius with default 1. The valid range is given as: 0 < Radius. The example is displayed below:

Float Option Example

Boolean Options

A Boolean option is used for Boolean data (True or False). The default assignment is required and is given as either True or False. A checkbox control is provided for user input.

Example:

option Dihedral {
  type = Boolean
  caption = "Dihedral"
  details = "Check to apply dihedral symmetry"
  default = False
}

This example defines a Boolean option named Dihedral with default False. The example is displayed below:

Boolean Option Example

Color Options

A Color option is used for color data. The default value is given as a hex number, composed of 3 pairs of hex digits (for a total of 6 hex digits), corresponding to the red, green, and blue components of the color, in that order (i.e., RRGGBB). A color preview control is provided for user input. The color preview is a small box that displays the currently selected color. Clicking on the box displays the Color Selection Dialog to allow the user to change the color.

Example:

option Background {
  type = Color
  caption = "Background"
  default = 0000FF
}

This example defines a Color option named Background with default 0000FF (blue). The example is displayed below:

Color Option Example

ColorSet Options

A ColorSet option is used for entering a small set of colors. The default value is given as a list of N hex numbers, each composed of 3 pairs of hex digits (for a total of 6 hex digits), corresponding to the red, green, and blue components of the color, in that order (i.e., RRGGBB). The number N is called the dimension of the ColorSet option and is described in the following example. A color set preview control is provided for user input. The color set preview is a set of small boxes that display the set of colors. Clicking on any of the boxes displays the Color Selection Dialog to allow the user to change the colors.

Example:

option Count {
  type = IntegerEnum(1,8)
  caption = "Count"
  details = "Number of colors to use"
  default = 8
}
option Colors {
  type = ColorSet[Count]
  caption = "Colors"
  default = FF00AE, FF2020, FF8200, FFFF00, 00FF6C, 00FFFF, 4040FF, AE60FF
}

This example defines a ColorSet option named Colors with 8 colors by default. Each of the 8 default colors is composed of 3 pairs of hex digits (for a total of 6 hex digits) corresponding to the red, green, and blue components of the color, in that order (i.e., RRGGBB). The type is given as ColorSet[Count]. This identifies the option used to control the number of colors in the set; Count in this example. The named option, called the dimension, must be an Integer or IntegerEnum option on the same page as the ColorSet option, with its range restricted to values between 1 and 200. The dimension's default must match the number of default colors given in the ColorSet option; 8 in this example. You can also define a fixed size array by using an integer between 1 and 200 in place of the dimension (e.g., ColorsSet[4]). In that case, the number of default colors given in the ColorSet option must match the given integer. The example is displayed below:

ColorSet Option Example

An array named Colors[] can be used by the program instructions to access the colors as shown below:

color = Colors[WrapIndex(Sample.TrapDwellRaw, Count)]

Here we index into the Colors[] array using the trap's (raw) dwell value. We use the function WrapIndex to ensure that the index is valid; i.e., between 0 and Count-1. See General Functions for a description of WrapIndex.

ColorSet options cannot be part of an OptionMap Statement.

SamplePointValue Options

A SamplePointValue option is used by Color Controllers to select a field from the sample data. Controllers are responsible for mapping a sample to a color. The properties section can define 1 or more SamplePointValue options to allow the user to choose which components of the sample data should be used to resolve the color. The option's default field should be set to one of the sample values associated with the controller.

Example:

comment:
 
  Maps a sample point value to a gradient index.
 
color:
 
  color = Gradient.Color(0, Value)
 
properties:
 
  option Value {
    type = SamplePointValue
    caption = "Value"
    default = Sample.Magnitude
  }

In this example, the controller maps a user selected SamplePointValue to a gradient index thereby obtaining a color. Unlike the other option types, Value does not define a constant, but instead, uses the SamplePointValue setting to access the corresponding component of the current sample which is returned by Value. The controller calls the function Gradient.Color(0,Value) to map the sample data to a color using the 1st gradient in the controller's list of gradients (i.e., gradient 0). The SamplePointValue cannot be used in enabled or visible expressions for other options, or as part of an OptionMap Statement. The example is displayed below:

SamplePointValue Option Example

The SamplePointValue option is supported only for Color Controllers.

GradientIndex Options

A GradientIndex option is used by Classic Controllers, Orbit Trap Controllers, or Orbital Controllers, to select a gradient from the controller's list of gradients. Controllers are responsible for mapping a sample to a color. The properties section can define 1 or more GradientIndex options to allow the user to choose which of the controller's gradients should be used to resolve the color. The default value is given as a positive integer number that gives the 0-based index into the list of gradients associated with the controller. A combobox is created for user input, and a gradient preview control is placed just below it on the page. See the example below.

Example:

comment:
 
  Maps a sample point value to a gradient index.
 
color:
 
  color = Gradient.Color(ColorScheme, Value)
 
properties:
 
 option ColorScheme {
    type = GradientIndex
    caption = "Color Scheme"
    default = 0
    size = Large
  }
  option Value {
    type = SamplePointValue
    caption = "Value"
    default = Sample.Magnitude
  }

In this example, the controller maps a user selected SamplePointValue to a gradient index thereby obtaining a color. The controller calls the function Gradient.Color(ColorScheme,Value) to map the sample data to a color using the gradient in the controller's list of gradients indexed by ColorScheme. The example is displayed below:

GradientIndex Option Example

Option Map Options

An option map option is used to create named sets of related options that can be set by selecting the name from a combobox. When an item is selected, all the component options are updated with the values specified in the associated OptionMap Statement. The user can accept the set of values as is, or change one or more of the component values. This provides the user with a set of example parameter sets while still allowing the user to try new parameter sets not specified in the OptionMap Statement. You need to define an optionMap (using an OptionMap Statement) before you define the option map option. Then you set the option's type field to the optionMap name. The option's default field should be set to one of the values associated with the named optionMap. The default is given as the optionMap name followed by a period (.) and the optionMap item name. All of the values associated with the the option map option's default override the default values for the associated options. See OptionMap Statement for details and examples. An option map option cannot be part of an OptionMap Statement.

Enum Options

An enum option is used when the data represents a single value from a set of choices. You need to define an enum using an Enum Statement before you define an enum option. Then you set the option's type field to the enum name. The option's default field should be set to one of the values associated with the named enum. The default is given as the enum name followed by a period (.) and the enum item name. The enum option is typically used with a switch statement in the program instructions. A combobox is provided for user input. See Enum Statement for details and examples.

IndexedEnum Options

An IndexedEnum option is used when you have a situation where changing the value of an enum option causes a 2nd option to be associated with a different enum. The 2nd option is defined as an IndexedEnum as illustrated in the following example.

Example:

properties:

  enum ColorModels {
    RGB, "RGB"
    HSL, "HSL"
  }
  option ColorModel {
    type = ColorModels
    caption = "Color Model"
    default = ColorModels.RGB
  }
  enum RGB {
    R, "Red"
    G, "Green"
    B, "Blue"
  }
  enum HSL {
    H, "Hue"
    S, "Saturation"
    L, "Lightness"
  }
  option ColorComponent {
    type = IndexedEnum(ColorModel, RGB, HSL)
    caption = "Color Component"
    default = RGB.R
  }

This example defines 2 options: ColorModel and ColorComponent. ColorModel is either RGB or HSL. When ColorModel changes, we require that ColorComponent be updated with a different set of items appropriate for the selected ColorModel. For example, if ColorModel is set to RGB, ColorComponent should be loaded with the RGB enum but when ColorModel is changed to HSL, ColorComponent should be reloaded with the HSL enum. This is accomplished using the IndexedEnum specification to define the option type as in the example above.

Here is the ColorComponent menu when ColorModel is RGB:

IndexedEnum Option Example

Here is the ColorComponent menu when ColorModel is HSL:

The IndexedEnum specification takes a variable number of arguments:

type = IndexedEnum(<Option>, <Enum>, <Enum>, ...)

<Option> is an enum option and the remaining arguments are enums. The number of items in the enum associated with <Option> must match the number of <Enum> arguments in the IndexedEnum specification. The value of <Option> is used as an index into the array of <Enum> arguments and when <Option> changes, the IndexedEnum is reloaded with the items in the <Enum> associated with the new value. <Option> and each of the <Enum> arguments must exist or an error will result. The default should be taken from the <Enum> associated with <Options>'s default.

The following example shows how you would access the IndexedEnum value:

switch (ColorModel) {
  case ColorModels.RGB
    switch (ColorComponent) {
      case RGB.R: debug.print("R")
      case RGB.G: debug.print("G")
      case RGB.B: debug.print("B")
    }
     
  case ColorModels.HSL
    switch (ColorComponent) {
      case HSL.H: debug.print("H")
      case HSL.S: debug.print("S")
      case HSL.L: debug.print("L")
    }
}

Both options must be on the same page and neither option can be part of an OptionMap Statement.

IntegerEnum Options

An IntegerEnum option is used for integral data. An IntegerEnum option is identical to an Integer option except that it creates a small combobox with a list of integers from which to choose instead of a numeric textbox control. An IntegerEnum option can be used when the range of integers associated with an option is small.

The IntegerEnum specification takes 2 arguments:

type = IntegerEnum(<Min>, <Max>)

<Min> and <Max> specify the set of values added to the combobox. <Min> must be less than <Max> and both values must be between -999 and 999. Typically, the number of values in the range should be less than 50 or the value of using the IntegerEnum option rather than an Integer option is questionable.

The following example illustrates these concepts:

properties:
 
  option K {
    type = Integer
    caption = "K"
    details = "Example Integer option"
    default = 1
    range = [1,8]
  }
  option L {
    type = IntegerEnum(1,8)
    caption = "L"
    details = "Example IntegerEnum option"
    default = 1
  }

Both of these options allow an integer between 1 and 8 to be specified by the user but option K requires the user to type in the number, while option L allows the user to select the number from the associated list. The example is displayed below:

IntegerEnum Option Example

Function Proxy Options

A function proxy option is used to allow the user to select a function from a set of functions. You need to define the set of functions using a FunctionSet Statement before you define the function proxy option and you set the option's type field to the name given to the set of functions. The option's default field should be set to one of the functions associated with the function proxy. In the program instructions you can invoke the function proxy just as you would a function. A combobox is provided for user input. See FunctionSet Statement for details and examples.

 

Copyright © 2004-2017 Hilbert, LLC
All rights reserved