DurationRuler - Control axis with duration values - MATLAB (original) (raw)

DurationRuler Properties

Control axis with duration values

DurationRuler properties control the appearance and behavior of an _x_-axis, _y_-axis, or _z_-axis that shows duration values. Each individual axis has its own ruler object. By changing property values of the ruler, you can modify certain aspects of a specific axis.

Use dot notation to refer to a particular ruler and property. Access the ruler objects through the XAxis, YAxis, andZAxis properties of the Axes object.

ax = gca; co = ax.XAxis.Color; ax.XAxis.Color = 'blue';

Appearance

expand all

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

LabelHorizontalAlignment Value	Description	Appearance
'center'	For a horizontal axis, the label is centered between the left and right edges of the plot box.For a vertical axis, the label is centered between the top and bottom edges of the plot box.
'left'	For a horizontal axis, the label is aligned with the left edge of the plot box.For a vertical axis, the label is aligned with the bottom edge of the plot box.
'right'	For a horizontal axis, the label is aligned with the right edge of the plot box.For a vertical axis, the label is aligned with the top edge of the plot box.

Scale and Direction

expand all

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

d = duration(1,40:45,0); y = rand(6,1); plot(d,y) ax = gca; ax.XAxis.Limits = [d(2) d(5)];

You can specify both limits, or specify one limit and let the ruler automatically calculate the other using an Inf or-Inf duration value, such asdays(Inf).

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'.

Note

The Limits property for the ruler and the associated XLim, YLim, orZLim property for the parent axes always have the same value. Setting one also sets the other.

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

Tick Values and Labels

expand all

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

d = duration(1,40:45,0); y = rand(6,1); plot(d,y) ax = gca; ax.XAxis.TickValues = [d(1) d(3) d(5)];

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

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

Note

The TickValues property for the ruler and the associated XTick, YTick, orZTick property for the parent axes always have the same value. Setting one also sets the other.

Exponential notation common to all tick values, specified as an integer value. The Exponent property applies only to tick labels that show a single unit of time, such as seconds, minutes, or hours. It does not apply to tick labels that show mixed units of time. When applicable, the ruler displays an exponent label showing the base and exponent value.

The base value is always 10. You can change the exponent value by setting the Exponent property. If the exponent value is0, then the exponent label is not displayed.

For example, this code changes the exponent value to 8.

x = hours((1:10)*1e10); plot(x,1:10) ax = gca; ax.XAxis.Exponent = 8;

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

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

• 'auto' — Automatically select the exponent value based on the axis limits.
• 'manual' — Use an exponent value that you specify. To specify the value, set theExponent property.

Data Types: char | string | categorical

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.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].
• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes"#FF8800","#ff8800","#F80", and"#f80" are equivalent.

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

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Note

Setting the ruler’s Color property also sets theTickLabelColor property to the same value. However, setting the TickLabelColor property does not change theColor property. To prevent the Color property value from overriding the TickLabelColor property value, set the Color property first, and then set theTickLabelColor property.

Tick label format, specified as a character vector or string scalar.

To display a duration as a single number that includes a fractional part (for example, 1.234 hours), specify one of the following formats.

To display a duration in the form of a digital timer, specify one of these formats:

• 'dd:hh:mm:ss'
• 'hh:mm:ss'
• 'mm:ss'
• 'hh:mm'

In addition, you can display up to nine fractional second digits by appending up to nine S characters. For example,'hh:mm:ss.SSS' displays the milliseconds of a duration value to three digits.

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

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

Font

Callbacks

expand all

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

• A function handle.
• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

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 calledevent. You can query the object properties using dot notation. For example, event.NewLimits returns the new axis limits. TheLimitsChanged 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.

Parent/Child

expand all

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

Version History

Introduced in R2016b

expand all

The FontSmoothing property has no effect and will be removed in a future release. You can set or get the value of this property without warning, but all text is smooth regardless of the property value. This property removal was announced in R2022a.