Main Content

Root Properties

Graphics environment and state information

expand all in page

The Root object is the root of the graphics object tree. Root properties contain information about the graphics environment and the current state of the graphics system. Use dot notation to refer to a particular object and property.

r = groot;
fig = r.Children;

Display Information

expand all

This property is read-only.

Width and height of displays, returned as an n-by-4 matrix, where n is the number of displays. Each row corresponds to one display and is a four-element vector of the form [x y width height]. For example, if there are two displays, then the matrix has this form:

[x1 y1 width1 height1
 x2 y2 width2 height2]
The first two elements in each row indicate the display location with respect to the origin point. The last two elements in each row indicate the display size. The origin point is the lower-left corner of the primary display. If the units are pixels, then the origin point is (1,1). For all other units, the origin point is (0,0). The Units property determines the units of this measurement.

Note

MATLAB® sets the display information values for this property at startup. The values are static. If your system display settings change, for example, if you plug in a new monitor, then the values do not update. To refresh the values, restart MATLAB.

Current location of pointer, specified as a two-element vector of the form [x y]. The x and y values are the coordinates of the pointer position measured from the origin point. The origin point is the lower-left corner of the primary display. If the units are pixels, then the origin point is (1,1). For all other units, the origin point is (0,0). The Units property determines the units of this measurement.

This property contains the current pointer location, even if the pointer is outside a MATLAB window. Move the pointer by changing the values of this property. On Macintosh systems, you cannot change the pointer location by setting this property.

Querying the PointerLocation property in a callback routine might return a value that is different from the location of the pointer when the callback was triggered. This difference results from delays in callback execution caused by competition for system resources.

Example: [500 400]

Number of bits that define each pixel color, specified as a scalar. The default value depends on the computer. The maximum number of simultaneously displayed colors on the current graphics device equals 2 raised to the value of this property.

This property is read-only.

Display resolution, returned as a scalar in pixels per inch. The value depends on the system.

  • On Windows® systems, the value is 96 DPI.

  • On Macintosh systems, the value is 72 DPI.

  • On Linux® system, the value is determined by your system resolution.

Note

The ScreenPixelsPerInch property became a read-only property in R2015b. To change the size of text and other elements on the screen, adjust the display scaling for your operating system.

This property is read-only.

Size of primary display, returned as a four-element vector of the form [left bottom width height].

  • The left and bottom values are both 1 when the units are pixels, and 0 for all other units.

  • The width and height values are the width and height of the display, respectively.

Note

Starting in R2015b on Windows systems, if the Units property is set to 'pixels', then the width and height values might differ from the screen size reported by the operating system. The values MATLAB reports are based on a pixel size of 1/96th of an inch. On Macintosh and Linux systems, the values match the size reported by the operating system.

Some important information to consider when using this property:

  • The values might not represent the usable display size due to the presence of UIs, such as the Microsoft® Windows task bar.

  • MATLAB sets the display size values for this property at startup. The values are static. If your system display settings change, the display size values do not update. To refresh the values, restart MATLAB.

Font name for fixed-width font, specified as a character vector or string giving the name of a system supported font. This property determines the font for axes, text, and uicontrols that have a FontName property set to 'FixedWidth'. The default value depends on the system. 'Courier New' is the default in systems that use Latin-based characters.

Specifying the FixedWidthFontName property eliminates the need to hardcode font names in MATLAB applications. MATLAB attempts to set FixedWidthFontName property to the correct value for the system.

If you are a MATLAB application developer and want to use a fixed-width font, set the FontName property for axes, text, and uicontrol objects to 'FixedWidth' instead of setting this root property. Users of the application can set the root property if they do not want to use the preselected value.

Example: 'Courier New'

Units for the MonitorPositions, ScreenSize, and PointerLocation properties, specified as one of the values shown in this table.

UnitsDescription
'pixels' (default)

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

On Linux systems, the size of a pixel is determined by your system resolution.

'inches'Inches.
'centimeters'Centimeters.
'points'Points. One point equals 1/72 inch.
'normalized' Normalized with respect to the display. The lower left corner of the display maps to (0,0) and the upper right corner maps to (1,1).
'characters'

Based on the default system font character size.

  • Character width = width of letter x.

  • Character height = distance between the baselines of two lines of text.

All units are measured from the lower-left corner of the primary display. If the units are pixels, then the lower-left corner maps to (1,1). For all other units, the lower-left corner maps to (0,0).

If you change the units, it is good practice to return it to its default value after completing your operation to prevent affecting other functions that assume the Units property is set to the default value.

Identifiers

expand all

This property is read-only.

Object whose callback is executing, returned as a graphics object. For more information, see the gcbo command.

Current figure, specified as a figure object. The current figure is typically the one most recently created, clicked on, or made current by calling the figure function. Setting this property makes a figure the current figure without sorting it to the front of other figures on the display. However, using the figure function to make a figure the current figure sorts that figure to the front of the display. To become the current figure, the HandleVisibility property of the figure must be set to 'on'.

This property returns an empty GraphicsPlaceholder array if there are no figures. However, the gcf command always returns a figure object. If there are no figure objects, then gcf creates one.

This property is read-only.

Type of graphics object, returned as 'root'. The Root object handle is always visible using the groot function.

Tag to associate with root, specified as a character vector or string. There is only one Root object, which you can always access using the groot function.

User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell array, character array, table, or structure. Use this property to store arbitrary data on an object.

If you are working in App Designer, create public or private properties in the app to share data instead of using the UserData property. For more information, see Share Data Within App Designer Apps.

Parent/Child

expand all

The Root object has no parent. This property is always an empty GraphicsPlaceholder.

Children, specified as an array of figure objects that have visible handles. The HandleVisibility property of the figure determines if the handle is visible or hidden. This property does not contain figures with hidden handles.

Change the order of the children to change the sorting order of the figures on the display.

This property has no effect. The Root object handle is always visible using the groot function.

Hidden handle 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.

  • 'on' — Expose all object handles regardless of the HandleVisibility property.

  • 'off' — Do not display hidden object handles. The HandleVisibility property of the object determines if the handle is visible or hidden.

Version History

Introduced before R2006a

See Also

Topics