DatetimeRuler Properties

Color of the axis line and labels, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^® uses in many types of plots.

Width of axis line and tick marks, specified as a positive value in point units. One point equals 1/72 inch.

Example: ax.XAxis.LineWidth = 2;

Axis label, which is a text object. To display text or change existing text, set the String property for the text object. Use other properties to change the text appearance, such as the font style or color.

ax = gca;
ax.XAxis.Label.String = 'X Axis';
ax.XAxis.Label.FontSize = 12;

For a full list of options, see Text Properties.

Alternatively, add or modify the axis labels using the xlabel, ylabel, and zlabel functions.

Axis label horizontal alignment, specified as one of the values from the table.

Axis visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Example: ax.XAxis.Visible = 'off';

Minimum and maximum axis limits, specified as a two-element vector of the form [min max], where min and max are datetime values. For example:

t = datetime(2014,6,28) + caldays(1:10);
y = rand(1,10);
plot(t,y);
ax = gca;
ax.XAxis.Limits = [t(2) t(8)];

Alternatively, set the limits using the xlim, ylim, and zlim functions.

If you assign a value to this property, then MATLAB sets the associated mode to 'manual'.

Selection mode for the Limits property, specified as one of these values:

Scale of values along axis, returned as 'linear'. DatetimeRuler objects do not support log scales.

Direction of increasing values, specified as one of these values:

Example: ax.XAxis.Direction = 'reverse';

Since R2023a

Reference date, specified as a datetime value. This property is useful for synchronizing tick placement across different axes and for plotting data from different time zones together.

MATLAB displays plots in the time zone of the first data set you plot into the axes. To change the time zone of the plot, set the ReferenceDate property to a datetime value that has the desired time zone.

Example

Plot the number of New Year's Day revelers in New York and London. The resulting plot is in the time zone of New York.

NY = datetime(2021,1,1,0:17,0,0,"TimeZone","America/New_York");
London = datetime(2021,1,1,0:17,0,0,"TimeZone","Europe/London");
ax = axes;
y = (1./(1:18).^2) * 100000;
semilogy(ax,NY,y,London,y)
grid on

Change the plot to use the time zone of London by setting the ReferenceDate property to a datetime value that has a time zone of "Europe/London". Then add a legend and a title.

ax.XAxis.ReferenceDate = datetime(2022,1,1,"TimeZone","Europe/London");
legend("New York","London")
title("New Year's Day Revelers")

Tick mark locations along the axis, specified as a vector of datetime values. For example:

t = datetime(2014,6,28) + caldays(1:10);
y = rand(1,10);
plot(t,y);
ax = gca;
ax.XAxis.TickValues = [t(1) t(3) t(5) t(10)];

If you assign a value to this property, then MATLAB sets the TickValuesMode property to 'manual'.

Alternatively, use the xticks, yticks, and zticks functions.

Selection mode for the TickValues property, specified as one of these values:

Tick mark labels, specified as a cell array of character vectors, string array, or categorical array. If you do not specify enough labels for all of the tick values, then the labels repeat. The labels support TeX and LaTeX markup. See the TickLabelInterpreter property for more information.

Example: ax.XAxis.TickLabels = {'January','February','March','April','May'}';

Example: ax.YAxis.TickLabels = {'\pi','2\pi','3\pi'}'

If you set this property, then MATLAB sets the TickLabelsMode property to 'manual'.

Alternatively, specify the tick labels using the xticklabels, yticklabels, and zticklabels functions.

Data Types: char | string | categorical

Selection mode for the TickLabels property, specified as one of these values:

Tick label color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

Tick label interpreter, specified as one of these values:

TeX Markup

By default, MATLAB supports a subset of TeX markup. Use TeX markup to add superscripts and subscripts, modify the text type and color, and include special characters in the text.

Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they modify only the next character or the characters within the curly braces. When you set the interpreter to 'tex', the supported modifiers are as follows.

This table lists the supported special characters for the 'tex' interpreter.

LaTeX Markup

To use LaTeX markup, set the TickLabelInterpreter property to 'latex'. Use dollar symbols around the labels, for example, use '$\int_1^{20} x^2 dx$' for inline mode or '$$\int_1^{20} x^2 dx$$' for display mode.

The displayed text uses the default LaTeX font style. The FontName, FontWeight, and FontAngle properties do not have an effect. To change the font style, use LaTeX markup within the text. The maximum size of the text that you can use with the LaTeX interpreter is 1200 characters. For multiline text, the maximum size of the text reduces by about 10 characters per line.

For examples that use TeX and LaTeX, see Greek Letters and Special Characters in Chart Text. For more information about the LaTeX system, see The LaTeX Project website at https://www.latex-project.org/.

Tick label format, specified as a string or character vector. The default format is based on the data.

Example: ax.XAxis.TickLabelFormat = "yyyy-MM-dd"; displays a date and time such as 2014-04-19.

Example: ax.XAxis.TickLabelFormat = "eeee, MMMM d, yyyy HH:mm:ss"; displays a date and time such as Saturday, April 19, 2014 21:41:06.

Example: ax.XAxis.TickLabelFormat = "MMMM d, yyyy HH:mm:ss Z"; displays a date and time such as April 19, 2014 21:41:06 -0400.

The following tables show the letter identifiers that you can use to construct the format. To separate the fields, use nonletter characters such as a hyphen, space, colon, or any non-ASCII character. The identifiers correspond to the Unicode^® Locale Data Markup Language (LDML) standard for dates.

Date and Time Formats

Use these identifiers to specify the display formats of the date and time fields.

Some tips and considerations:

Time Zone Offset Formats

Use these identifiers to specify the display format of the time zone offset. A time zone offset is the amount of time that a specific date and time is offset from UTC. This is different from a time zone, which comprises rules that determine the offsets for specific times of the year. Include a time zone offset identifier when you want to ensure that the time components are displayed unambiguously.

Selection mode for the TickLabelFormat property, specified as one of these values:

Since R2024a

Secondary label format, specified as a string scalar or character vector. The secondary label appears in the margin next to the tick labels. You can use this property to customize the format of the label. The default format is based on the data. To remove the secondary label, specify an empty string ("").

If you specify the secondary label format, the tick labels might update to avoid displaying redundant information. For example, if you plot several days and display the month in the secondary label, the tick labels update to show the day numbers without the month.

Example: ax.XAxis.SecondaryLabelFormat = "MMMM" displays the month name.

Example: ax.XAxis.SecondaryLabelFormat = "ZZZZ" displays a time zone offset.

The following tables show the letter identifiers that you can use to construct the format. To separate the fields, use nonletter characters such as a hyphen, space, colon, or any non-ASCII character. The identifiers correspond to the Unicode Locale Data Markup Language (LDML) standard for dates.

Date and Time Formats

Use these identifiers to specify the display formats of the date and time fields.

Some tips and considerations:

Time Zone Offset Formats

Use these identifiers to specify the display format of the time zone offset. A time zone offset is the amount of time that a specific date and time is offset from UTC. This is different from a time zone, which comprises rules that determine the offsets for specific times of the year. Include a time zone offset identifier when you want to ensure that the time components are displayed unambiguously.

Since R2024a

Selection mode for the SecondaryLabelFormat property, specified as one of these values:

Rotation of tick labels, specified as a scalar value in degrees. Positive values give counterclockwise rotation. Negative values give clockwise rotation.

Alternatively, you can rotate the tick labels using the xtickangle, ytickangle, and ztickangle functions.

Example: ax.XAxis.TickLabelRotation = 45;

Example: ax.YAxis.TickLabelRotation = -45;

Selection mode for the TickLabelRotation property, specified as one of these values:

Tick mark direction, specified as one of these values:

If you assign a value to this property, then MATLAB sets the TickDirectionMode property to 'manual'.

Selection mode for the TickDirection property, specified as one of these values:

Tick mark length, specified as a two-element vector of the form [2Dlength 3Dlength]. The first element is the tick mark length in 2-D views. The second element is the tick mark length in 3-D views. Specify the values in units normalized relative to the longest axes dimension.

Example: ax.YAxis.TickLength = [0.02 0.035];

Minor tick mark display, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Example: ax.XAxis.MinorTick = 'on';

Minor tick mark locations, specified as a vector of increasing datetime values.

If you assign values to this property, then MATLAB sets the MinorTickValuesMode property to 'manual'.

Selection mode for the MinorTickValues property, specified as one of these values:

Font name, specified as a system supported font name or 'FixedWidth'. The default font depends on the specific system and locale. To use a fixed-width font that renders well, specify 'FixedWidth'. The actual fixed-width font used depends on the FixedWidthFontName property of the root object.

Example: ax.XAxis.FontName = 'Cambria';

Font size, specified as a scalar numeric value. The default font size depends on the specific operating system and locale.

Example: ax.XAxis.FontSize = 12;

Thickness of the text characters, specified as one of these values:

MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold font weight. Therefore, specifying a bold font weight still can result in the normal font weight.

Example: ax.XAxis.FontWeight = 'bold';

Character slant, specified as 'normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font can look the same as the normal font.

Example: ax.XAxis.FontAngle = 'italic';

Text smoothing, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Example: ax.XAxis.FontSmoothing = 'off';

Axis limits changed callback, specified as one of these values:

This callback executes after the axis limits have changed, either programmatically or using an interaction such as panning within the axes. It can also execute if MATLAB changes the axis limits to encompass the range of your data when you call a plotting function.

This callback function can access specific information about the axis limits. MATLAB passes this information in a LimitsChanged object as the second argument to your callback function. If you are developing an app in App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.NewLimits returns the new axis limits. The LimitsChanged object is not available to callback functions specified as character vectors.

The following table lists the properties of the LimitsChanged object.

For more information about writing callbacks in apps, see Callbacks in App Designer.

Ruler parent, specified as an Axes object.

The ruler has no children. You cannot set this property.