textwrap

Wrap text for user interface control

collapse all in page

Syntax

wrappedtext = textwrap(c,txt)
wrappedtext = textwrap(c,txt,numchar)
wrappedtext = textwrap(txt,numchar)
[wrappedtext,position] = textwrap(___)

Description

Note

Using UI components such as Label or Button objects and wrapping text by setting the WordWrap property of the component to "on" is recommended over using the textwrap function with UIControl objects.

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

example

wrappedtext = textwrap(c,txt,numchar) returns text that wraps each line at the specified number of characters for the given UI control. 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.

example

wrappedtext = textwrap(txt,numchar) returns text that wraps each line at the specified number of characters.

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

example

Examples

collapse all

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

Figure window with text that is wrapped and cut off

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

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

Figure window with text that is wrapped and cut off

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

Preview the wrapped text and the recommended position of the UIControl object 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;

Figure window with the full text: "The data shown represents 18 months of observations."

Input Arguments

collapse all

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.

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"]

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

collapse all

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

Version History

Introduced before R2006a

See Also

|