Axes: Elements

• Aug 27, 2019
• 7 minutes to read

The Titles, Labels, Constant Lines and Strips are an axis’s structural elements and can supplement the axis.

Note

Tickmarks and Grid Lines are visual elements and the Axis Style configures them. Refer to the Axes guide to learn more about styling.

How to: Manage an axis’ labels

Axis Labels are an axis’ main structural elements. The axis labels show textual representations of axis values at major tick marks.

How to: configure labels’ text

Labels’ main function is to display an axis value’s textual representation. The axis label converts an axis value to a string using one of the following approaches:

• Using Text Pattern

  The following code shows how to format label text if the label text does not require conditional formatting and all label texts use the same text format:

  Objective C

  DXAxisLabel *axisLabel = [[DXAxisLabel alloc] init];
  axisLabel.format = @"$#tn";
  axisX.label = axisLabel;
  

  Swift

  let axisLabel = DXAxisLabel()
  axisLabel.format = "$ #tn"
  axisX.label = axisLabel
  

  C#

  axisX.label = new DXAxisLabel {
      Format = "$ #tn"
  };
  

  The code above uses the following classes and class members:

  Symbol	Description
  DXAxisBase.label	Gets or sets axis labels’ settings.
  DXAxisLabel	Axis labels settings storage.
  DXAxisLabel.format	Gets or sets axis labels’ text format pattern.

• Using Axis’ Label Text Formatter

  The code snippet below demonstrates how to configure labels’ text if it requires more detailed customization (for example, conditional prefix):

  Objective C

  @interface LabelFormatter <DXNumericAxisLabelTextFormatter>
  @end
  // ...
  
  @implementation
  -(NSString *)format : (double) value {
      if (value > 0) {
          return String.stringWithFormat("$ %.1fM", value)
      }
      return "0";
  }
  @end
  // ...
  
  axisY.labelTextFormatter = [[LabelFormatter alloc] init]
  

  Swift

  class LabelFormatter: NSObject, DXNumericAxisLabelTextFormatter {
      func format(_ value: Double) -> String {
          if (value > 0) {
              return String(format: "$ %.1fM", value)
          }
          return "0"
      }
  }
  
  // ...
  axisY.labelTextFormatter = LabelFormatter()
  

  C#

  class LabelFormatter: DXNumericAxisLabelTextFormatter {
      public String format(double value) {
          if (value > 0) {
              return String("$ {0:F1}M", value)
          }
          return "0";
      }
  }
  
  // ...
  axisY.labelTextFormatter = LabelFormatter()
  

  This approach can use the following symbols:

  Symbol	Description
  DXQualitativeAxisX.labelTextFormatter	Gets or sets a formatter that provides qualitative X-axis labels’ text.
  DXQualitativeAxisLabelTextFormatter	The protocol which a class that provides qualitative X-axis‘s label text should implement.
  DXDateTimeAxisX.labelTextFormatter	Gets or sets a formatter that provides date-time X-axis labels’ text.
  DXDateTimeAxisLabelTextFormatter	The protocol which a class that provides a date-time X-axis‘s label text should implement.
  DXNumericAxisX.labelTextFormatter	Gets or sets a formatter that provides numeric X-axis labels’ text.
  DXNumericAxisY.labelTextFormatter	Gets or sets a formatter that provides numeric Y-axis labels’ text.
  DXNumericAxisLabelTextFormatter	The protocol which a class that provides numeric X-axis‘s or numeric Y-axis‘s label text should implement.

How to: change labels’ position

Axis labels can be inside or outside the drawing area. The following image demonstrates labels that are inside the area:

The following code snippet demonstrates how to change labels’ position:

Objective C

DXAxisLabel *axisLabel = [[DXAxisLabel alloc] init];
axisLabel.position = DXAxisLabelPositionInside;
axisX.label = axisLabel;

Swift

let axisLabel = DXAxisLabel()
axisLabel.position = .inside
axisX.label = axisLabel

C#

axisX.label = new DXAxisLabel {
    Position = DXAxisLabelPosition.Inside
};

The code above uses the following classes and methods:

Symbol	Description
DXAxisBase.label	Gets or sets axis labels’ settings.
DXAxisLabel	Axis labels settings storage.
DXAxisLabel.position	Gets or sets axis labels’ position.
DXAxisLabelPosition	Lists possible label positions.

How to: configure labels’ appearance

The style configures the following axis labels’ appearance settings:

The table below demonstrates the symbols that allow you to customize axis labels’ appearance:

Symbols	Description
DXAxisLabelBase.style	Gets or sets the axis labels’ appearance settings.
DXAxisLabelStyle	The axis labels’ appearance settings storage.

How to: Customize the axis title

The Axis Title allows you to display additional text that explains the axis values.

The following code demonstrates how to specify an axis’ title:

Objective C

DXAxisTitle *axisYTitle = [[DXAxisTitle alloc] init];
axisYTitle.text = @"Population, millions";
axisYTitle.alignment = DXAxisTitleAlignmentFar;
axisY.title = axisYTitle;

Swift

let axisYTitle = DXAxisTitle()
axisYTitle.text = "Population, millions"
axisYTitle.alignment = .far
axisY.title = axisYTitle

C#

axisY.Title = new DXAxisTitle() {
    Text = "Population, millions",
    Alignment = DXAxisTitleAlignment.Far
};

The code above uses the following classes and members:

Symbol	Description
DXAxisBase.title	Gets or sets the axis title settings.
DXAxisTitle	The axis title.
DXTitle.text	Gets or sets the title’s text.
DXAxisTitle.alignment	Gets or sets the title’s position.
DXAxisTitleAlignment	Lists the values that specify the available title alignments.

The style also configures the next axis title’s appearance settings:

The table below demonstrates the symbols that allow you to customize axis labels’ appearance.

Symbols	Description
DXTitle.style	Gets or sets the title’s appearance settings.
DXTitleStyle	The title appearance settings storage.

How to: Add a constant line

Constant lines provide a capability to mark required axis values.

Note that each axis type uses a specific constant line type. The table below shows axis types and their corresponding constant line types:

Axis Type	Constant Line Type
DXQualitativeAxisX	DXQualitativeConstantLine
DXNumericAxisX	DXNumericConstantLine
DXDateTimeAxisX	DXDateTimeConstantLine
DXNumericAxisY	DXNumericConstantLine

The following example demonstrates how to configure a constant line:

Objective C

DXNumericConstantLine *constantLine = [[DXNumericConstantLine alloc] init];
constantLine.axisValue = 100;
constantLine.titleText = @"Sample Constant Line";
constantLine.legendText = @"Sample Constant Line";
constantLine.showInLegend = YES;
constantLine.titleAlignment = DXConstantLineTitleAlignmentFar;
constantLine.showTitleBelowLine = YES;
[axisY addConstantLine:constantLine];

Swift

let constantLine = DXNumericConstantLine()
constantLine.axisValue = 100
constantLine.titleText = "Sample Constant Line"
constantLine.legendText = "Sample Constant Line"
constantLine.titleAlignment = .far
constantLine.showInLegend = true
constantLine.showTitleBelowLine = true
axisY.add(constantLine)

C#

axisY.AddConstantLine(new DXNumericConstantLine() {
    AxisValue = 100,
    TitleText = "Sample Constant Line",
    LegendText = "Sample Constant Line",
    ShowInLegend = true,
    TitleAlignment = DXConstantLineTitleAlignment.Far,
    ShowTitleBelowLine = true
});

The following classes and members allow you to configure a constant line:

Symbol	Description
DXQualitativeAxisX::addConstantLine:	Adds the specified constant line to the qualitative X-axis.
DXNumericAxisX::addConstantLine:	Adds the specified constant line to the numeric X-axis.
DXDateTimeAxisX::addConstantLine:	Adds the specified constant line to the date-time X-axis.
DXNumericAxisY::addConstantLine:	Adds the specified constant line to the numeric Y-axis.

The style also configures the following constant line’s appearance settings:

The table below provides the symbols that allow you to customize axis labels’ appearance.

Symbols	Description
DXConstantLineBase.style	Gets or sets the constant line’s appearance settings.
DXConstantLineStyle	The constant line’s appearance settings storage.

How to: Add a strip

Strips provide the capability to highlight axis ranges.

Note that each axis type uses a specific strip type. The table below shows axis types and their corresponding constant line types.

Axis Type	Constant Line Type
DXQualitativeAxisX	DXQualitativeStrip
DXNumericAxisX	DXNumericStrip
DXDateTimeAxisX	DXDateTimeStrip
DXNumericAxisY	DXNumericStrip

The following example demonstrates how to configure a strip:

Objective C

DXNumericStrip *yStrip = [[DXNumericStrip alloc] init];
yStrip.maxLimit = 40;
yStrip.minLimitEnabled = NO;
yStrip.axisLabelText = @"Low population";
yStrip.axisLabelHidden = NO;
yStrip.showInLegend = NO;
[axisY addStrip:yStrip];

Swift

let yStrip = DXNumericStrip()
yStrip.maxLimit = 40
yStrip.minLimitEnabled = false
yStrip.axisLabelText = "Low population"
yStrip.axisLabelHidden = false
yStrip.showInLegend = false
axisY.add(yStrip)

C#

axisY.AddStrip(new DXNumericStrip() {
    MaxLimit = 40,
    MinLimitEnabled = false,
    AxisLabelText = "Low population",
    AxisLabelHidden = false,
    ShowInLegend = false
});

The following classes and members allow you to configure a constant line:

Symbol	Description
DXQualitativeAxisX::addStrip:	Adds the specified strip to the qualitative X-axis.
DXNumericAxisX::addStrip:	Adds the specified strip to the numeric X-axis.
DXDateTimeAxisX::addStrip:	Adds the specified strip to the date-time X-axis.
DXNumericAxisY::addStrip:	Adds the specified strip to the numeric Y-axis.

The style also configures the following constant line’s appearance settings:

The table below provides the symbols that allow you to customize axis labels’ appearance.

Symbols	Description
DXStripBase.style	Gets or sets the strip’s appearance settings.
DXStripStyle	The strip appearance settings storage.