TextScatter Properties
Control text scatter chart appearance and behavior
TextScatter
properties control the
appearance and behavior of TextScatter
object. By
changing property values, you can modify certain aspects of the text scatter
chart.
Text
TextData
— Text labels
string array | cell array of character vectors
Text labels, specified as a string array, or a cell array of character vectors.
Example: ["word1" "word2" "word3"]
Data Types: string
| cell
TextDensityPercentage
— Percentage of text data to show
60 (default) | scalar from 0 through 100
Percentage of text data to show, specified as a scalar from 0 through 100. To show all text,
set TextDensityPercentage
to 100. To show no text, set
TextDensityPercentage
to 0.
If you set TextDensityPercentage
to 100, then the software does not plot markers.
Example: 70
MaxTextLength
— Maximum length of text labels
40 (default) | positive integer
Maximum length of text labels, specified as a positive integer. The software truncates the text labels to this length and adds ellipses at the point of truncation.
Example: 10
Font Style
FontName
— Font name
system supported font name | 'FixedWidth'
Font name, specified as the name of the font to use or
'FixedWidth'
. To display and print properly, the font
name must be a font that your system supports. The default font depends on
the specific operating system and locale.
To use a fixed-width font that looks good in any locale, use
'FixedWidth'
. The 'FixedWidth'
value relies on the root FixedWidthFontName
property. Setting the root
FixedWidthFontName
property causes an immediate
update of the display to use the new font.
Example: 'Cambria'
FontSize
— Font size
10
(default) | scalar value greater than zero
Font size, specified as a scalar value greater than zero in point units.
One point equals 1/72
inch.
Example: 12
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
FontAngle
— Character slant
'normal'
(default) | 'italic'
Character slant, specified as 'normal'
or
'italic'
. Not all fonts have both font styles.
Therefore, the italic font might look the same as the normal font.
FontWeight
— Thickness of text characters
'normal'
(default) | 'bold'
Thickness of the text characters, specified as one of these values:
'normal'
— Default weight as defined by the particular font'bold'
— Thicker character outlines than normal
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.
FontSmoothing
— Smooth font character appearance
'on'
(default) | 'off'
Smooth font character appearance, specified as one of these values:
'on'
— Apply font smoothing. Reduce the appearance of jaggedness in the text characters to make the text easier to read.'off'
— Do not apply font smoothing.
Note
The FontSmoothing
property will have no effect in a
future release. Font smoothing will be enabled regardless of the value
of the property.
Text Box
EdgeColor
— Color of box outline
'none'
(default) | RGB triplet | character vector of color name
Color of box outline, specified as 'none'
, a
three-element RGB triplet, or a character vector of a color name. The
default edge color of 'none'
makes the box outline
invisible.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
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 character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, 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 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" |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
Example: 'blue'
Example: [0 0 1]
BackgroundColor
— Color of text box background
'none'
(default) | 'data'
| RGB triplet
Color of text box background, specified as one of these values:
'none'
— Make the text box background transparent.'data'
— Use background color specified byColorData
. The software automatically chooses a foreground to complement the background color.RGB triplet — Use the same color for all the markers in the plot. 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.5 0.6 0.7]
.
Example: [1 0 0]
Margin
— Space around text within text box
3
(default) | positive scalar
The space around the text within the text box, specified as a positive scalar in point units.
MATLAB uses the Extent
property value plus the
Margin
property value to determine the size of the
text box.
Example: 8
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Markers
MarkerColor
— Marker colors
'auto'
(default) | 'none'
| RGB triplet
Marker colors, specified as one of these values:
'auto'
— For each marker, use the same color as the corresponding text labels.'none'
— Do not show markers.RGB triplet — Use the same color for all the markers in the plot. 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.5 0.6 0.7]
.
Example: [1 0 0]
MarkerSize
— Marker size
6 (default) | positive scalar
Marker size, specified as a positive scalar.
Example: 10
Data
XData
— x values
[]
(default) | scalar | vector
x values, specified as a scalar or a vector. The text
scatter plot displays an individual marker for each value in
XData
.
The input argument X
to the
textscatter
and textscatter3
functions set the x values. XData
and YData
must have equal lengths.
Example: [1 2 4 2 6]
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| categorical
| datetime
| duration
XDataSource
— Variable linked to XData
''
(default) | character vector containing MATLAB workspace variable name
Variable linked to XData
, specified as a character
vector containing a MATLAB workspace variable name. MATLAB evaluates the variable in the base workspace to generate the
XData
.
By default, there is no linked variable so the value is an empty character
vector, ''
. If you link a variable, then MATLAB does not update the XData
values
immediately. To force an update of the data values, use the refreshdata
function.
Note
If you change one data source property to a variable that contains data of a different dimension, you might cause the function to generate a warning and not render the graph until you have changed all data source properties to appropriate values.
Example: 'x'
YData
— y values
[]
(default) | scalar | vector
y values, specified as a scalar or a vector. The text
scatter plot displays an individual marker for each value in
YData
.
The input argument Y
to the
textscatter
and textscatter3
functions set the y values. XData
and YData
must have equal lengths.
Example: [1 3 3 4 6]
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| categorical
| datetime
| duration
YDataSource
— Variable linked to YData
''
(default) | character vector containing MATLAB workspace variable name
Variable linked to YData
, specified as a character
vector containing a MATLAB workspace variable name. MATLAB evaluates the variable in the base workspace to
generate the YData
.
By default, there is no linked variable so the value is an empty character
vector, ''
. If you link a variable, then MATLAB does not update the YData
values
immediately. To force an update of the data values, use the refreshdata
function.
Note
If you change one data source property to a variable that contains data of a different dimension, you might cause the function to generate a warning and not render the graph until you have changed all data source properties to appropriate values.
Example: 'y'
ZData
— z values
[]
(default) | scalar | vector
z values, specified as a scalar or a vector.
For 2-D scatter plots,
ZData
is empty by default.For 3-D scatter plots, the input argument
Z
to thescatter3
function sets the z values.XData
,YData
, andZData
must have equal lengths.
Example: [1 2 2 1 0]
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| categorical
| datetime
| duration
ZDataSource
— Variable linked to ZData
''
(default) | character vector containing MATLAB workspace variable name
Variable linked to ZData
, specified as a character
vector containing a MATLAB workspace variable name. MATLAB evaluates the variable in the base workspace to
generate the ZData
.
By default, there is no linked variable so the value is an empty character
vector, ''
. If you link a variable, then MATLAB does not update the ZData
values
immediately. To force an update of the data values, use the refreshdata
function.
Note
If you change one data source property to a variable that contains data of a different dimension, you might cause the function to generate a warning and not render the graph until you have changed all data source properties to appropriate values.
Example: 'z'
ColorData
— Text colors
[]
(default) | RGB triplet | matrix of RGB triplets | categorical vector
Text colors, specified as one of these values:
RGB triplet — Use the same color for all the text in the plot. 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.5 0.6 0.7]
.Three-column matrix of RGB triplets — Use a different color for each text label in the plot. Each row of the matrix defines one color. The number of rows must equal the number of text labels.
Categorical vector — Use a different color for each category in the vector. Specify
ColorData
as a vector the same length asXData
. Specify the colors for each category using theColors
property
Example: [1 0 0; 0 1 0; 0 0 1]
Colors
— Category colors
matrix of RGB triplets
Category colors, specified as a matrix of RGB triplets. 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.5 0.6 0.7]
.
By default, Colors
is equal to the ColorOrder
property of the axes object.
Example: [1 0 0; 0 1 0; 0 0 1]
Visibility
Visible
— State of visibility
"on"
(default) | "off"
State of visibility, specified as one of these values:
"on"
— Display the object."off"
— Hide the object without deleting it. You still can access the properties of an invisible object.
Identifiers
Type
— Type of graphics object
'textscatter'
This property is read-only.
Type of graphics object, returned as 'textscatter'
. Use
this property to find all objects of a given type within a plotting
hierarchy; for example, searching for the type using findobj
.
Tag
— User-specified tag
''
(default) | character vector
This property is read-only.
User-specified tag to associate with the object, specified as a character
vector. Tags provide a way to identify graphics objects. Use this property
to find all objects with a specific tag within a plotting hierarchy; for
example, searching for the tag using findobj
.
Example: 'January Data'
UserData
— Data to associate with object
[]
(default) | any MATLAB data
This property is read-only.
Data to associate with the object, specified as any MATLAB data; for example, a scalar, vector, matrix, cell array, character array, table, or structure. MATLAB does not use this data.
To associate multiple sets of data or to attach a field name to the data,
use the getappdata
and setappdata
functions.
Example: 1:100
DisplayName
— Text used for legend label
''
(default) | character vector
This property is read-only.
Text used for the legend label, specified as a character vector. If you do
not specify the text, then the legend uses a label of the form
'dataN'
. The legend does not display until you call
the legend
command.
Example: 'Label Text'
Annotation
— Control for including or excluding object from legend
Annotation
object
Control for including or excluding the object from a legend, returned as
an Annotation
object. Set the underlying
IconDisplayStyle
property to one of these values:
'on'
— Include the object in the legend (default).'off'
— Do not include the object in the legend.
For example, exclude a stem chart from the legend.
p = plot(1:10,'DisplayName','Line Chart'); hold on s = stem(1:10,'DisplayName','Stem Chart'); hold off s.Annotation.LegendInformation.IconDisplayStyle = 'off'; legend('show')
Alternatively, you can control the items in a legend using the legend
function. Specify
the first input argument as a vector of the graphics objects to
include.
p = plot(1:10,'DisplayName','Line Chart'); hold on s = stem(1:10,'DisplayName','Stem Chart'); hold off legend(p)
Parent/Child
Parent
— Parent
Axes
object | PolarAxes
object | Group
object | Transform
object
Parent, specified as an Axes
, PolarAxes
, Group
, or Transform
object.
Children
— Children
empty GraphicsPlaceholder
array | DataTip
object array
Children, returned as an empty GraphicsPlaceholder
array or a DataTip
object array. Use this property to view
a list of data tips that are plotted on the chart.
You cannot add or remove children using the Children
property. To add a child to this list, set the Parent
property of the DataTip
object to the chart object.
HandleVisibility
— Visibility of object handle
"on"
(default) | "off"
| "callback"
Visibility of the object handle in the Children
property of the parent, specified as one of these values:
"on"
— Object handle is always visible."off"
— Object handle is invisible at all times. Use this option to prevent unintended changes to the UI by another function. SetHandleVisibility
to"off"
to temporarily hide the handle when you execute another function."callback"
— Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command-line, but allows callback functions to access it.
If the object is not listed in the Children
property of the parent, then
functions that obtain object handles by searching the object hierarchy or querying
handle properties cannot return it. These functions include get
, findobj
, gca
, gcf
, gco
, newplot
, cla
, clf
, and close
.
Hidden object handles are still valid. Set the root ShowHiddenHandles
property to "on"
to list all object handles regardless of their
HandleVisibility
property setting.
Interactive Control
ButtonDownFcn
— Mouse-click callback
''
(default) | function handle | cell array | character vector
Mouse-click callback, specified as one of these values:
Function handle
Cell array containing a function handle and additional arguments
Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)
Use this property to execute code when you click the object. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:
Clicked object — You can access properties of the clicked object from within the callback function.
Event data — This argument is empty for this property. Replace it with the tilde character (
~
) in the function definition to indicate that this argument is not used.
For more information on how to use function handles to define callback functions, see Create Callbacks for Graphics Objects.
Note
If the PickableParts
property is set to
'none'
or if the HitTest
property is set to 'off'
, then this callback does not
execute.
Example: @myCallback
Example: {@myCallback,arg3}
ContextMenu
— Context menu
empty GraphicsPlaceholder
array (default) | ContextMenu
object
Context menu, specified as a ContextMenu
object. Use
this property to display a context menu when you right-click the object.
Create the context menu using the uicontextmenu
function.
Note
If the PickableParts
property is set to
'none'
or if the HitTest
property is set to 'off'
, then the context menu does
not appear.
Selected
— Selection state
'off'
(default) | 'on'
Selection state, specified as one of these values:
'on'
— Selected. If you click the object when in plot edit mode, then MATLAB sets itsSelected
property to'on'
. If theSelectionHighlight
property also is set to'on'
, then MATLAB displays selection handles around the object.'off'
— Not selected.
SelectionHighlight
— Display of selection handles when selected
'on'
(default) | 'off'
Display of selection handles when selected, specified as one of these values:
'on'
— Display selection handles when theSelected
property is set to'on'
.'off'
— Never display selection handles, even when theSelected
property is set to'on'
.
DataTipTemplate
— Data tip content
DataTipTemplate
object
Data tip content, specified as a DataTipTemplate
object.
You can control the content that appears in a data tip by modifying the
properties of the underlying DataTipTemplate
object. For a
list of properties, see DataTipTemplate Properties.
For an example of modifying data tips, see Create Custom Data Tips.
Note
The DataTipTemplate
object is not returned by
findobj
or findall
, and it
is not copied by copyobj
.
Callback Execution Control
PickableParts
— Ability to capture mouse clicks
'visible'
(default) | 'none'
Ability to capture mouse clicks, specified as one of these values:
'visible'
— Can capture mouse clicks when visible. TheVisible
property must be set to'on'
and you must click a part of theTextScatter
object that has a defined color. You cannot click a part that has an associated color property set to'none'
. If the plot contains markers, then the entire marker is clickable if either the edge or the fill has a defined color. TheHitTest
property determines if theTextScatter
object responds to the click or if an ancestor does.'none'
— Cannot capture mouse clicks. Clicking theTextScatter
object passes the click to the object below it in the current view of the figure window. TheHitTest
property of theTextScatter
object has no effect.
HitTest
— Response to captured mouse clicks
'on'
(default) | 'off'
Response to captured mouse clicks, specified as one of these values:
'on'
— Trigger theButtonDownFcn
callback of theTextScatter
object. If you have defined theUIContextMenu
property, then invoke the context menu.'off'
— Trigger the callbacks for the nearest ancestor of theTextScatter
object that has aHitTest
property set to'on'
and aPickableParts
property value that enables the ancestor to capture mouse clicks.
Note
The PickableParts
property determines if the
TextScatter
object
can capture mouse clicks. If it cannot, then the
HitTest
property has no effect.
Interruptible
— Callback interruption
'on'
(default) | 'off'
Callback interruption, specified as 'on'
or
'off'
. The Interruptible
property
determines if a running callback can be interrupted.
Note
There are two callback states to consider:
The running callback is the currently executing callback.
The interrupting callback is a callback that tries to interrupt the running callback.
Whenever MATLAB invokes a callback, that callback attempts to
interrupt a running callback. The Interruptible
property of the object owning the running callback determines if
interruption is allowed. If interruption is not allowed, then the
BusyAction
property of the object owning the
interrupting callback determines if it is discarded or put in the
queue.
If the ButtonDownFcn
callback of the TextScatter
object is the
running callback, then the Interruptible
property
determines if it another callback can interrupt it:
'on'
— Interruptible. Interruption occurs at the next point where MATLAB processes the queue, such as when there is adrawnow
,figure
,getframe
,waitfor
, orpause
command.If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes. For more information, see Interrupt Callback Execution.
If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.
'off'
— Not interruptible. MATLAB finishes executing the running callback without any interruptions.
BusyAction
— Callback queuing
'queue'
(default) | 'cancel'
Callback queuing specified as 'queue'
or
'cancel'
. The BusyAction
property
determines how MATLAB handles the execution of interrupting
callbacks.
Note
There are two callback states to consider:
The running callback is the currently executing callback.
The interrupting callback is a callback that tries to interrupt the running callback.
Whenever MATLAB invokes a callback, that callback attempts to
interrupt a running callback. The Interruptible
property of the object owning the running callback determines if
interruption is allowed. If interruption is not allowed, then the
BusyAction
property of the object owning the
interrupting callback determines if it is discarded or put in the
queue.
If the ButtonDownFcn
callback of the TextScatter
object tries to
interrupt a running callback that cannot be interrupted, then the
BusyAction
property determines if it is discarded or
put in the queue. Specify the BusyAction
property as one
of these values:
'queue'
— Put the interrupting callback in a queue to be processed after the running callback finishes execution. This is the default behavior.'cancel'
— Discard the interrupting callback.
Creation and Deletion Control
CreateFcn
— Creation callback
''
(default) | function handle | cell array | character vector
Creation callback, specified as one of these values:
Function handle
Cell array containing a function handle and additional arguments
Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)
Use this property to execute code when you create the object. Setting the
CreateFcn
property on an existing object has no
effect. You must define a default value for this property, or define this
property using a Name,Value
pair during object creation.
MATLAB executes the callback after creating the object and
setting all of its properties.
If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:
Created object — You can access properties of the object from within the callback function. You also can access the object through the
CallbackObject
property of the root, which can be queried using thegcbo
function.Event data — This argument is empty for this property. Replace it with the tilde character (
~
) in the function definition to indicate that this argument is not used.
For more information on how to use function handles to define callback functions, see Create Callbacks for Graphics Objects.
Example: @myCallback
Example: {@myCallback,arg3}
DeleteFcn
— Deletion callback
''
(default) | function handle | cell array | character vector
Deletion callback, specified as one of these values:
Function handle
Cell array containing a function handle and additional arguments
Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)
Use this property to execute code when you delete the object MATLAB executes the callback before destroying the object so that the callback can access its property values.
If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:
Deleted object — You can access properties of the object from within the callback function. You also can access the object through the
CallbackObject
property of the root, which can be queried using thegcbo
function.Event data — This argument is empty for this property. Replace it with the tilde character (
~
) in the function definition to indicate that this argument is not used.
For more information on how to use function handles to define callback functions, see Create Callbacks for Graphics Objects.
Example: @myCallback
Example: {@myCallback,arg3}
BeingDeleted
— Deletion status
'off'
(default) | 'on'
Deletion status, returned as 'off'
or
'on'
. MATLAB sets the BeingDeleted
property
to 'on'
when the delete function of the object begins
execution (see the DeleteFcn
property). The
BeingDeleted
property remains set to
'on'
until the object no longer exists.
Check the value of the BeingDeleted
property to
verify that the object is not about to be deleted before querying or
modifying it.
Version History
Introduced in R2017bR2022a: FontSmoothing
will have no effect in a future release
The FontSmoothing
property will have no effect in a future
release. Font smoothing will be enabled regardless of the value of the
property.
R2020a: UIContextMenu
property is not recommended
Starting in R2020a, using the UIContextMenu
property to
assign a context menu to a graphics object or UI component is not recommended. Use
the ContextMenu
property instead. The property values are the
same.
There are no plans to remove support for the UIContextMenu
property at this time. However, the UIContextMenu
property no
longer appears in the list returned by calling the get
function
on a graphics object or UI component.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)