textwrap

Wrap text for user interface control

Use this function only with GUIDE, or with apps created using the figure function

Syntax

wrappedtext = textwrap(c,txt)

wrappedtext = textwrap(c,txt,numchar)

[wrappedtext,position] = textwrap(___)

Description

wrappedtext = textwrap(c,txt) returns text wrapped at a character width that fits within the specified UIControl object, c. The UI control object must be one created with the uicontrol function whose 'Style' property value is set to 'text' or 'edit'. For example, c = uicontrol('Style','text').

wrappedtext = textwrap(c,txt,numchar) returns text that wraps each line at the specified number of characters. Spaces are included in the character count. textwrap avoids splitting words when possible. If a word cannot be accommodated within the specified number of characters, then textwrap moves it to the start of the next line.

[wrappedtext,position] = textwrap(___) also returns the recommended position for the UI control based on the text to be wrapped. The returned position is one that allows the full text to display in the uicontrol without clipping. If a UI control is not specified, the position vector contains all zeros.

Examples

Preview Cell Array of Wrapped Text

Specify two lines of text for the String property of a static text field.

c = uicontrol('Style','text');
c.String = {'Extraordinarily long text will be wrapped', ...
'inside of a static text field.'};

The text is cut off and wraps across more than two lines because the default width and height of the text field are not large enough to accommodate the full length of the specified text. Notice how the word "Extraordinarily" is also split across two lines.

Preview the cell array of character vectors that is recommended for wrapping the text so that it fits inside the width of the UI control with the least amount of resizing.

wrappedtext = textwrap(c,c.String)

wrappedtext =

  7×1 cell array

    {'Extraordinarily'}
    {'long text'      }
    {'will be'        }
    {'wrapped'        }
    {'inside of a'    }
    {'static text'    }
    {'field.'         }

Display Wrapped Text in UI Control

Wrap text at a specified character width and display it in a static text field.

Create a static text field at the default position of [20 20 60 20]. Specify text to display in it.

c = uicontrol('Style','text');
c.String = {'The data shown represents 18 months of observations.'};

The text is cut off and displays on multiple lines because the default width and height values of the uicontrol are too small to accommodate the full text.

Preview the wrapped text and the recommended position of the uicontrol based on a maximum text width of 16 characters.

[wrappedtext,position] = textwrap(c,c.String,16)

wrappedtext =

  4×1 cell array

    {'The data shown '}
    {'represents 18 ' }
    {'months of '     }
    {'observations.'  }


position =

    20    20    86    64

Display the wrapped text in the text field and move it to the recommended position.

c.String = wrappedtext;
c.Position = position;

Input Arguments

c — UI control object

UIControl object (default)

UI control object, specified as a UIControl object. The UIControl object must support multiline text. For instance, its 'Style property can be 'text' or 'edit'. Use this argument to determine how text wraps in the specified UI control, or to determine the recommended size for the UI control based on the text to be wrapped.

txt — Text

cell array of character vectors | string array

Text to wrap, specified as a cell array of character vectors, a string array, or a string scalar.

Example: {'Please select an answer from the options below.'}

Example: ["Enter your name using","the format LastName, FirstName"]

numchar — Number of characters

positive integer

Number of characters in each line of text, specified as a positive integer. Use this argument to specify the maximum character width for each line. If numchar exceeds the number of characters in txt, then the text does not wrap.

Output Arguments

wrappedtext — Wrapped text

cell array of character vectors

Wrapped text, returned as a cell array of character vectors. To display the text on the specified UI control, you must assign wrappedtext to the String property of the UI control.

position — Position

[left bottom width height]

Position recommended for the UI control, returned as a four-element vector of the form [left bottom width height]. The units are the same as the units of the UI control. The returned position optimizes the width and height of the uicontrol so that the specified text can display across multiple lines, without clipping. If a UI control is not specified, then the position vector contains all zeros.