uitextarea
Create text area component
Description
creates a text area in
a new figure window and returns the txa
= uitextareaTextArea
object. MATLAB® calls the uifigure
function to create the
figure.
specifies txa
= uitextarea(___,Name,Value
)TextArea
properties using one or more
name-value arguments. For example,
uitextarea("Value","Comments")
creates a text area that shows
the text Comments
. Use this option with any of the input argument
combinations in the previous syntaxes.
Examples
Create Text Area
Create Text Area with Placeholder Text
Create a text area in a UI figure. Specify placeholder text to describe the expected input. The placeholder text shows only when the text area is empty.
fig = uifigure; txa = uitextarea(fig,"Placeholder","Enter feedback");
Set and Access Text Area Properties
Create a populated text area in a UI figure.
fig = uifigure; txa = uitextarea(fig, ... "Value",["First Name Last Name"; "Address 1"; ... "Address 2"; "City, State"; "Postal Code"]);
Notice that the text area includes a scroll bar so that the app user can view the postal code.
Determine the current width and height of the text area by querying the third and fourth values of the Position
property.
size = txa.Position(3:4)
size = 1×2
150 60
Increase the text area size so that all of the content is visible without the use of a scroll bar.
txa.Position(3:4) = [155 80];
Scroll Text Area Programmatically
Scroll to the bottom of a text area programmatically.
Create a text area. Specify a size and long text for it.
fig = uifigure;
txa = uitextarea(fig);
txa.Position = [100 100 80 80];
txa.Value = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.";
Scroll to the bottom of the text area.
scroll(txa,"bottom")
Code Response to Changed Text Area Value
Create an app that enables a button when an app user enters text in a text area.
In a file named textAreaApp.m
, write a function that implements the app:
Create a UI figure and a grid layout manager to lay out the app.
Create a label, text area, and button in the grid layout manager.
Write a callback function named
textEntered
that enables a button when there is text in the text area, and assign the function to theValueChangedFcn
callback property of the text area. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.
function textAreaApp fig = uifigure; g = uigridlayout(fig,[3 3]); g.RowHeight = {'fit','fit','fit'}; g.ColumnWidth = {'1x','fit','1x'}; lbl = uilabel(g,"Text","Enter Comments:"); lbl.Layout.Row = 1; lbl.Layout.Column = 2; txa = uitextarea(g); txa.Layout.Row = 2; txa.Layout.Column = 2; btn = uibutton(g,"Text","Submit","Enable","off"); btn.Layout.Row = 3; btn.Layout.Column = 2; txa.ValueChangedFcn = @(src,event) textEntered(src,event,btn); end function textEntered(src,event,btn) val = src.Value; btn.Enable = "off"; % Check each element of text area cell array for text for k = 1:length(val) if ~isempty(val{k}) btn.Enable = "on"; break end end end
Run the textAreaApp
function. Enter some text in the text area, then click outside the text area to enable the Submit button.
Input Arguments
parent
— Parent container
Figure
object (default) | Tab
object | Panel
object | ButtonGroup
object | GridLayout
object
Parent container, specified as a Figure
object created using the uifigure
function or one of its child
containers: Tab
, Panel
, ButtonGroup
, or GridLayout
. If you do not specify a parent container, MATLAB calls the uifigure
function to create a new Figure
object that serves as the parent container.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: uitextarea(Editable="off")
specifies that the app user
cannot change the text area text.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: uitextarea("Editable","off")
specifies that the app
user cannot change the text area text.
Note
The properties listed here are a subset of the available properties. For the
full list, see TextArea
.
Value
— Value
{''}
(default) | character vector | string scalar | cell array of character vectors | string array | 1-D categorical array
Value, specified as a character vector, string scalar, cell array of character
vectors, string array, or 1-D categorical array. To display multiple lines of text,
specify Value
as an array. Each element in the array represents a
separate line of
text.
txt = ["Line 1"; "Line 2"; "Line 3"; "Line 4"]; textarea = uitextarea("Value",txt);
If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.
If the text does not fit into the width of the text area, MATLAB wraps the text.
If there are too many rows to display in the text area, MATLAB adds a scroll bar.
Example: ["Joseph Welford"; "Mary Reilly"; "Roberta
Silberlicht"]
ValueChangedFcn
— Value changed callback
''
(default) | function handle | cell array | character vector
Value 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.
The callback executes when the user changes the text and either presses
Tab or clicks outside the text area. It does not execute if the
Value
property changes programmatically.
This callback function can access specific information about the user’s interaction
with the text area. MATLAB passes this information in a ValueChangedData
object as the second argument to your callback function.
In App Designer, the argument is called event
. You can query the
object properties using dot notation. For example,
event.PreviousValue
returns the previous value of the text area.
The ValueChangedData
object is not available to
callback functions specified as character vectors.
The following table lists the properties of the ValueChangedData
object.
Property | Value |
---|---|
Value | Value of text area after app user’s most recent interaction with it |
PreviousValue | Value of text area before app user’s most recent interaction with it |
Source | Component that executes the callback |
EventName | 'ValueChanged' |
For more information about writing callbacks, see Callbacks in App Designer.
ValueChangingFcn
— Value changing callback
''
(default) | function handle | cell array | character vector
Value changing 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 as follows:
As the user types in the text area, the callback executes repeatedly.
When the user presses Tab or clicks outside the text area, the callback executes.
If the text area value changes programmatically, then the callback does not execute.
This callback function can access specific information about the user’s interaction with the text area. MATLAB passes this information in a ValueChangingData
object as the second argument to your callback function. In App Designer, the argument is called event
. You can query the object properties using dot notation. For example, event.Value
is the value in the text area that triggered the execution of the callback. The ValueChangingData
object is not available to callback functions specified as character vectors.
Here are the properties of the ValueChangingData
object:
Property | Description |
---|---|
Value | Value that triggered the execution of the callback |
Source | Component that executes the callback |
EventName | 'ValueChanging' |
The Value
property of the TextArea
object is not updated until the user either presses Tab or clicks outside the text area. However, you can get the text while the user is still typing by querying the Value
property of the ValueChangingData
object.
Note
Avoid updating the Value
property of the
TextArea
object from within its own
ValueChangingFcn
callback, as this might result in unexpected
behavior. To update the text area value in response to user input, use a
ValueChangedFcn
callback instead.
For more information about writing callbacks, see Callbacks in App Designer.
Position
— Location and size of text area
[100 100 150 60]
(default) | [left bottom width height]
Location and size of the text area relative to the parent, specified
as the vector [left bottom width height]
. This
table describes each element in the vector.
Element | Description |
---|---|
left | Distance from the inner left edge of the parent container to the outer left edge of the text area |
bottom | Distance from the inner bottom edge of the parent container to the outer bottom edge of the text area |
width | Distance between the right and left outer edges of the text area |
height | Distance between the top and bottom outer edges of the text area |
All measurements are in pixel units.
The Position
values are relative to the
drawable area of the parent container. The drawable area is the area
inside the borders of the container and does not include the area occupied by decorations such
as a menu bar or title.
Example: [100 100 100 90]
Version History
Introduced in R2016aR2021b: Program response while a user is typing
Create a ValueChangingFcn
callback to program your app to
respond when a user is typing in a text area. The callback function executes
repeatedly while the user types.
R2021a: Specify placeholder text
Provide a short hint that describes the expected text area input by using the
Placeholder
property.
For more information, see TextArea
.
R2020b: Toggle text wrapping
Use the WordWrap
property to toggle text wrapping. When the
WordWrap
property is 'on'
(the
default), the UI component breaks the text into new lines so that each line fits
horizontally within the component. When the property is set to
'off'
, the text does not wrap.
For more information, see TextArea
.
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)