NumericAxis-of

{NumericAxis-of t:NumericType} (class)

            public NumericAxis-of
            {inherits {NumericAxisMixin-of t}, ChartAxis}

Package: CURL.GUI.CHARTS

A numeric implementation of ChartAxis that is based on an explicit range.

Description

In contrast to most axis types, this class does not use data as its basis. Instead, it uses the Type specified by t and the range explicitly specified when it is constructed (or via NumericAxis-of.set-range).

Notes

Unlike NumericDataSeriesAxis-of, the force-zero? parameter to the NumericAxis-of.default constructor is false by default. This is because it is usually not necessary, since the range is already explicitly specified.

Example

Example: Using NumericAxis-of to specify a fixed-range axis

{import * from CURL.GUI.CHARTS}
{import * from CHARTS-DOC,
    location = "../docstring-support/gui/charts-doc.scurl"
}

{LayeredChart
    width = 15cm,
    height = 6cm,
    left-axis = {new {NumericAxis-of double}, 0, 70},
    {BarLayer
        {ChartDataSeries sample-records, "Age"},
        {ChartDataSeries sample-records, "Points"},
        {ChartDataSeries sample-records, "Wins"},
        x-axis-data = {ChartDataSeries sample-records, "Name"}
    }
}

Constructors

default:

Create a new NumericAxis-of.

constructor public

{NumericAxis-of.default
    minimum:t,
    maximum:t,
    force-zero?:bool = false,
    force-range?:bool = false,
    force-range-strict?:bool = false,
    forced-min:t = {unit-value-for-type t},
    forced-max:t = {unit-value-for-type t},
    visible-values:{Array-of t} = {new {Array-of t}},
    label-group:ChartLabelGroup = {ChartLabelGroup},
    axis-group:Shape = {ShapeGroup},
    axis-line-group:Shape = {ShapeGroup},
    major-tick-group:Shape = {ShapeGroup},
    minor-tick-group:Shape = {ShapeGroup},
    ...
}

Properties

maximum:

The maximum value for this axis.

field public-get private-set NumericAxis-of.maximum:t

maximum-displayed-t:

The actual maximum displayed value on this axis.

field public-get private-set NumericAxis-of.maximum-displayed-t:t

minimum:

The minimum value for this axis.

field public-get private-set NumericAxis-of.minimum:t

minimum-displayed-t:

The actual minimum displayed value on this axis.

field public-get private-set NumericAxis-of.minimum-displayed-t:t

tick-count:

The actual number of ticks displayed on this axis.

field public-get private-set NumericAxis-of.tick-count:int

Properties inherited from NumericAxisMixin-of: force-range-strict?, force-range?, forced-max, forced-min, tick-spacing-proc, visible-values

Properties inherited from ChartAxis: axis-group, axis-label, axis-line-group, chart, label-group, length, major-tick-factory, major-tick-group, minor-tick-factory, minor-tick-group, position, style-element, tick-label-factory, x-axis?, y-axis?

Properties inherited from DataBindingTarget: data-binding-context, data-bindings

Properties inherited from Shape: as-Shape, border-color, color, draw-operation, option-parent, selection-context, shape-parent, shape-selectable, stroke-thickness, transformation, visible?

Properties inherited from OptionListInterface: option-register-proc, registered-option-keys

Properties inherited from ShapeContainerBase: as-ShapeRoot, shape-children

Properties inherited from EventTarget: event-handlers

Methods

generate-axis-label:

Generate an axis label appropriate for this ChartAxis.

public

{NumericAxis-of.generate-axis-label}:#Shape

generate-major-ticks:

Generate all Shapes required to represent the major ticks along this axis.

protected

{NumericAxis-of.generate-major-ticks}:void

generate-minor-ticks:

Generate all Shapes required to represent the minor ticks along this axis.

protected

{NumericAxis-of.generate-minor-ticks}:void

get-data-type:

Describes the way in which a ChartAxis is defined.

public

{NumericAxis-of.get-data-type}:(type:AxisDataType, value:any)

get-position-at-zero:

Get the spatial position along this axis corresponding with zero.

public

{NumericAxis-of.get-position-at-zero}:Distance

get-relative-position:

Calculate the spatial position corresponding to a data value.

public

{NumericAxis-of.get-relative-position val:any}:Fraction

get-value-relative:

Calculate the data value that corresponds with a position along this axis.

public

{NumericAxis-of.get-value-relative position:Fraction}:any

note-visible-values-changed:

Notify this axis that the contents of NumericAxisMixin-of.visible-values have changed.

public

{NumericAxis-of.note-visible-values-changed}:void

set-forced-range:

Apply (or remove) a constraint to the bounds used by this axis in NumericAxisMixin-of.calculate-tick-spacing.

public

{NumericAxis-of.set-forced-range
    force-range?:bool,
    force-range-strict?:bool = false,
    forced-min:t = {unit-value-for-type t},
    forced-max:t = {unit-value-for-type t}
}:void

set-range:

Set the range of this axis.

public

{NumericAxis-of.set-range minimum:t, maximum:t}:void

Methods inherited from NumericAxisMixin-of: calculate-tick-spacing, generate-numeric-ticks

Methods inherited from ChartAxis: clear-shapes, detach, generate-axis-line, generate-major-tick, generate-minor-tick, generate-tick-label, get-axis-label, get-major-ticks-Iterator, get-minor-ticks-Iterator, get-position, get-tick-label, get-tick-label-alignment, get-value, note-min-max-computation-changed, regenerate-shapes, transform-from-chart, transform-to-chart, update-layout

Methods inherited from GraphicOptions: any-to-Distance

Methods inherited from ShapeGroup: draw, get-own-bounds, get-own-bounds-in-shape-root, self-contains-point?, self-intersects-polygon?

Methods inherited from DataBindingTarget: add-data-binding, get-data-binding, refresh-data-binding, remove-data-binding, unset-property, update-data-binding, validate-data-binding

Methods inherited from Shape: apply-rotation, apply-scale, apply-transformation, apply-translation, apply-translation-in-parent, constrain-own-layout-bounds, constrain-shape-layout-bounds, contains-point?, find-graphical-ancestor, fire-crossing-event, fire-in-child, get-display-context, get-down-orientation-in-shape-parent, get-graphical-root, get-local-device-pixel-size, get-origin-in-graphical-ancestor, get-origin-in-root, get-origin-in-shape-parent, get-origin-in-shape-root, get-own-layout-bounds, get-right-orientation-in-shape-parent, get-shape-bounds, get-shape-bounds-in-shape-root, get-shape-layout-bounds, get-top-left-in-ancestor, get-transformation-to-shape-root, keyword-init-arg, option-change-notify, overdraw-for-selection, quantize-line-thickness, request-draw, request-draw-self, reset-transformation, set-rotation, set-scale, set-transformation, set-translation-in-parent, to-Graphic, transform-from-display-coordinates, transform-from-graphical-root-coordinates, transform-point-from-shape-root, transform-point-to-shape-root, transform-to-display-coordinates, transform-to-graphical-root-coordinates, transform-vector-from-shape-root, transform-vector-to-shape-root, transformation-changed, transformation-changing

Methods inherited from InitRestArgParser: process-rest-args

Methods inherited from GuiEventTarget: handle-event, on-action, on-cancel-mode, on-command-changed, on-commit, on-composition-change-event, on-composition-result-event, on-context-menu-event, on-current-record-change-request, on-current-record-changed, on-destroy-notify, on-destroy-requested, on-drag-over, on-drag-pointer, on-drag-started, on-drop, on-end-composition-event, on-focus-event, on-focus-in, on-focus-out, on-grab-release, on-gui-event, on-input-method-event, on-inspection, on-key-event, on-key-press, on-pointer-button, on-pointer-crossing, on-pointer-event, on-pointer-motion, on-pointer-press, on-pointer-release, on-pointer-scroll, on-raw-key-event, on-raw-key-press, on-raw-key-release, on-reset, on-selectable-added, on-selectable-removed, on-selection-changed, on-selection-context-activated, on-selection-context-deactivated, on-selection-event, on-start-composition-event, on-start-event, on-stop-event, on-view-activate, on-view-deactivate, on-window-close, remove-event-handlers-for-event-class

Methods inherited from EventTarget: accepts-event-class?, add-event-handler, event-handler-present?, remove-event-handler, verify-event

Methods inherited from BasicEventTarget: enqueue-event

Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize

Constructor Details

default (constructor)

public

Create a new NumericAxis-of.

minimum: The initial minimum value for this chart. See NumericAxis-of.minimum.

maximum: The initial maximum value for this chart. See NumericAxis-of.maximum.

force-zero?: If true, the minimum and maximum of this axis will be adjusted as needed to ensure that zero is represented. (This feature is implemented by adding a zero to visible-values.)

force-range?: If true, then forced-min and forced-max are used to set the bounds of this axis.

force-range-strict?: If true, then forced-min and forced-max become the bounds of this axis without modification, otherwise they are adjusted to the nearest round number.

forced-min: A value to be used as the minimum of this axis if force-range? is true.

forced-max: A value to be used as the maximum of this axis if force-range? is true.

visible-values: An array of values that will always be included within the bounds of this axis. See NumericAxisMixin-of.visible-values.

label-group: The initial value for ChartAxis.label-group.

axis-group: The initial value for ChartAxis.axis-group.

axis-line-group: The initial value for ChartAxis.axis-line-group.

major-tick-group: The initial value for ChartAxis.major-tick-group.

minor-tick-group: The initial value for ChartAxis.minor-tick-group.

...: Any of the arguments that Shape accepts. These are primarily keyword arguments representing option initializations.

Example

See NumericAxis-of.

Property Details

maximum (field)

public-get private-set NumericAxis-of.maximum:t

The maximum value for this axis.

Description

This value can be set by the NumericAxis-of.default constructor or by the NumericAxis-of.set-range method.

Notes

Unless NumericAxisMixin-of.force-range-strict? is true, then there is no guarantee that this value will directly become the displayed maximum. Normally, a round number greater than or equal to this value will be used. See NumericAxisMixin-of.calculate-tick-spacing for an explanation of the algorithm that governs this process.

maximum-displayed-t (field)

public-get private-set NumericAxis-of.maximum-displayed-t:t

The actual maximum displayed value on this axis.

Description

This value is calculated during the layout process, in NumericAxis-of.generate-major-ticks. Thus, it is only valid and meaningful if this axis is contained within a chart whose layout process has completed. (See Chart.ensure-layout-valid.)

minimum (field)

public-get private-set NumericAxis-of.minimum:t

The minimum value for this axis.

Description

This value can be set by the NumericAxis-of.default constructor or by the NumericAxis-of.set-range method.

Notes

Unless NumericAxisMixin-of.force-range-strict? is true, then there is no guarantee that this value will directly become the displayed minimum. Normally, a round number less than or equal to this value will be used. See NumericAxisMixin-of.calculate-tick-spacing for an explanation of the algorithm that governs this process.

minimum-displayed-t (field)

public-get private-set NumericAxis-of.minimum-displayed-t:t

The actual minimum displayed value on this axis.

Description

tick-count (field)

public-get private-set NumericAxis-of.tick-count:int

The actual number of ticks displayed on this axis.

Description

Method Details

generate-axis-label (method)

public

{NumericAxis-of.generate-axis-label}:#Shape

Generate an axis label appropriate for this ChartAxis.

Returns

A Shape representing the label, or null if no label should be displayed.

Description

ChartAxis subclasses must define this method. You may also wish to override this method if you are subclassing an existing ChartAxis class. See ChartAxis.get-axis-label for a more complete discussion of controlling the appearance of the axis label.

The Shape created need not be rotated or positioned, as ChartLabelGroup will set its position and rotation directly as appropriate to the axis' position. If you wish to specify an offset with respect to that position, you can apply the desired transformation to the label shape and then embed it within a ShapeGroup. The ShapeGroup will be the object that is positioned by ChartLabelGroup, and the child Shape you embedded will be brought along with it. See axis-label for an example that demonstrates this using scaling.

You must take care that the object generated is positioned well with respect to its origin. The origin will be placed in alignment with the center of the axis, close to the axis itself, and the rotation of the object will be 0 degrees or -90 degrees for the horizontal and vertical axes, respectively. For these reasons, you will need to position the shape you generate carefully to ensure it is where you want it to be (rather than, for instance, overlapping the axis and ticks).

See axis-label for a discussion of how to ensure this using options like halign or horigin on objects like TextShape.

Notes

This is usually implemented to depend on the data controlling the axis. For instance, DataSeriesAxis and subclasses return a TextShape containing the RecordField.caption value for all RecordFields they contain.

generate-major-ticks (method)

protected

{NumericAxis-of.generate-major-ticks}:void

Generate all Shapes required to represent the major ticks along this axis.

Description

This is the method in which ChartAxis implementations actually do the work of figuring out how many ticks to generate, where to place them, and actually doing so. This method is intended to be called from ChartAxis.update-layout.

If you are implementing this method, you may find it useful to use ChartAxis.generate-major-tick to create a standard tick shape. Generated Shapes should be added to ChartAxis.major-tick-group.

generate-minor-ticks (method)

protected

{NumericAxis-of.generate-minor-ticks}:void

Generate all Shapes required to represent the minor ticks along this axis.

Description

This is the minor tick counterpart to ChartAxis.generate-major-ticks. None of the standard axis implementations generate any minor ticks, and so ChartAxis.generate-minor-ticks does nothing. This method is intended to be called from ChartAxis.update-layout.

If you are implementing this method, you may find it useful to use ChartAxis.generate-minor-tick to create a standard tick shape. Generated Shapes should be added to ChartAxis.minor-tick-group.

get-data-type (method)

public

{NumericAxis-of.get-data-type}:(type:AxisDataType, value:any)

Describes the way in which a ChartAxis is defined.

Returns

An AxisDataType describing the data or metric associated with this axis and a value describing that metric.

Description

This method is used by the LayeredChart system that matches axes with data. For instance, if this axis is directly associated with a ChartDataSeries, then it is appropriate to associate it with plots of that data series. So, this method would return AxisDataType.data-series, along with the data series used within the axis.

The table below explains the type of value expected to be returned for each possible AxisDataType.

AxisDataType	Type of value	Description
AxisDataType.data-series	{Array-of ChartDataSeries}	This axis is directly associated with one or more ChartDataSeries, and those series are contained in the array returned. All data series must share the same Domain object. (This is the most commonly used type of axis by far.)
AxisDataType.record-field	{Array-of RecordField}	This axis is directly associated with one or more RecordFields. All fields must share the same Domain. Data will be matched to the axis if it uses the same field. The RecordFields used are returned in an array.
AxisDataType.field-name	{Array-of String}	In a manner very similar to AxisDataType.record-field, this axis is associated with one or more record fields by name. Data will be matched to this axis if it uses a field of the same name. The field names used are returned in an array.
AxisDataType.type	Type	The axis defines itself only as measuring a certain Type. NumericAxis-of is an example of this axis type. Failing a better match, any data that uses the same type will be matched to this axis.
AxisDataType.record-index	none (null)	This axis simply puts one Record after another, with no regard to the data. This axis type is only useful for X axes. It will match any data, but is the lowest priority kind of match. DefaultChartAxis and DefaultBarChartAxis are examples of this kind of axis.

get-position-at-zero (method)

public

{NumericAxis-of.get-position-at-zero}:Distance

Get the spatial position along this axis corresponding with zero.

Description

This returns a value along this axis' length with the same behavior as ChartAxis.get-position; see that method for details.

Notes

The concept of zero may not make sense for all axes. In particular, GenericDataSeriesAxis and EnumeratedBarChartAxis are ordinal axes, not continuous value-based axes, and so the concept of zero does not apply. Such axes always return 0m.

get-relative-position (method)

public

{NumericAxis-of.get-relative-position val:any}:Fraction

Calculate the spatial position corresponding to a data value.

value: A value whose expected type varies depending on the axis type. See ChartAxis.get-position. Passing an incompatible type will result in an error.

Returns

A Fraction indicating the position of the data value along the axis, ranging from 0 at the origin of the axis to 1 at the end of the axis.

Description

This is essentially the same as ChartAxis.get-position without any notion of the direction or length of the axis. In fact, that method is implemented in terms of this one. See ChartAxis.get-position for more information.

get-value-relative (method)

public

{NumericAxis-of.get-value-relative position:Fraction}:any

Calculate the data value that corresponds with a position along this axis.

position: The position along this axis as a fraction. This should be between 0 and 1, inclusive.

Returns

A value of the appropriate type for this axis. See ChartAxis.get-position for a discussion of the appropriate Types of values for different axes.

Description

This is essentially the same as ChartAxis.get-value without any notion of the direction or length of the axis. In fact, that method is implemented in terms of this one. See ChartAxis.get-value for more information.

note-visible-values-changed (method)

public

{NumericAxis-of.note-visible-values-changed}:void

Notify this axis that the contents of NumericAxisMixin-of.visible-values have changed.

Description

You must call this method whenever you modify the contents of NumericAxisMixin-of.visible-values in order to give the axis a chance to perform the necessary layout operations.

set-forced-range (method)

public

{NumericAxis-of.set-forced-range
    force-range?:bool,
    force-range-strict?:bool = false,
    forced-min:t = {unit-value-for-type t},
    forced-max:t = {unit-value-for-type t}
}:void

Apply (or remove) a constraint to the bounds used by this axis in NumericAxisMixin-of.calculate-tick-spacing.

force-range?: If true, then the range displayed on this axis is determined by the other parameters of this method. Otherwise, it is based on the minimum and maximum values from the data, and the other parameters to this method are ignored.

force-range-strict?: If true, then forced-min and forced-max become the bounds of this axis without modification, otherwise they are adjusted to the nearest round number.

forced-min: A value to be used as the minimum of this axis if force-range? is true.

forced-max: A value to be used as the maximum of this axis if force-range? is true.

Description

You can use this method to control the data bounds displayed by this axis. Normally, NumericAxisMixin-of.calculate-tick-spacing starts out with bounds determined using the minimum and maximum values present in the data. However, if you specify force-range? as true, then forced-min and forced-max are used instead of the data minimum and maximum.

Normally, regardless of the source of this minimum and maximum, NumericAxisMixin-of.calculate-tick-spacing then determines the optimal tick spacing and expands the bounds to the nearest round multiple of this spacing. If force-range-strict? is true, however, forced-min and forced-max will always be used as-is, without expansion.

Note that NumericAxisMixin-of.visible-values still applies, regardless of any forced range in effect.

Notes

These values can also be initialized from the NumericAxisMixin-of.default constructor or the NumericDataSeriesAxis-of.default and NumericAxis-of.default constructors.

Example

Example: Using NumericAxisMixin-of.set-forced-range

{import * from CURL.GUI.CHARTS}
{import * from CHARTS-DOC,
    location = "../docstring-support/gui/charts-doc.scurl"
}

{let constant axis:{NumericDataSeriesAxis-of double} =
    {new {NumericDataSeriesAxis-of double},
        {ChartDataSeries sample-records, "Age"},
        {ChartDataSeries sample-records, "Points"},
        force-zero? = false,
        force-range? = true,
        force-range-strict? = false,
        forced-min = 1.5,
        forced-max = 7.5
    }
}

{LayeredChart
    width = 15cm,
    height = 7cm,
    left-axis = axis,
    {LineLayer
        sample-records,
        "Age",
        "Points",
        x-axis-data =
            {ChartDataSeries sample-records, "Name"}
    }
}

{Table
    columns = 2,
    {text forced-min:},
    {TextField
        value = "" & axis.forced-min,
        {on ValueFinished at tf:TextField do
            {axis.set-forced-range
                axis.force-range?,
                force-range-strict? = axis.force-range-strict?,
                forced-min = {tf.value.to-double},
                forced-max = axis.forced-max
            }
        }
    },
    {text forced-max:},
    {TextField
        value = "" & axis.forced-max,
        {on ValueFinished at tf:TextField do
            {axis.set-forced-range
                axis.force-range?,
                force-range-strict? = axis.force-range-strict?,
                forced-min = axis.forced-min,
                forced-max = {tf.value.to-double}
            }
        }
    }
}

{CheckButton
    label = "force-range?",
    value = axis.force-range?,
    {on ValueFinished at cb:CheckButton do
        {axis.set-forced-range
            cb.value,
            force-range-strict? = axis.force-range-strict?,
            forced-min = axis.forced-min,
            forced-max = axis.forced-max
        }
    }
}

{CheckButton
    label = "force-range-strict?",
    value = axis.force-range-strict?,
    {on ValueFinished at cb:CheckButton do
        {axis.set-forced-range
            axis.force-range?,
            force-range-strict? = cb.value,
            forced-min = axis.forced-min,
            forced-max = axis.forced-max
        }
    }
}

set-range (method)

public

{NumericAxis-of.set-range minimum:t, maximum:t}:void

Set the range of this axis.

minimum: The minimum value for this axis.

maximum: The maximum value for this axis.

Description

This method sets NumericAxis-of.minimum and NumericAxis-of.maximum. Unless NumericAxisMixin-of.force-range-strict? is true, then there is no guarantee that these values will directly become the displayed minimum and maximum. Normally, they are enlarged to the nearest round numbers. See NumericAxisMixin-of.calculate-tick-spacing for an explanation of the algorithm that governs this process.