align

Align UIControl components and Axes objects

Syntax

align(components,valign,spacing)

align(components,valign,'fixed',distance)

align(components,spacing,halign)

align(components,'fixed',distance,halign)

align(components,valign,halign)

positions = align(___)

positions = align(cpositions,___)

Description

Note

The align function is not supported in App Designer or in apps created using the uifigure function. Instead, use a grid layout manager to align components in your app. For more information, see Alternative Functionality.

Align Objects Vertically

align(components,valign,spacing) vertically aligns the specified components. The function aligns the left sides, centers, or right sides of the objects depending on the value of valign, and adjusts the vertical spacing between the objects depending on the value of spacing. For instance, align(components,'left','none') aligns left edges and makes no spacing adjustments. The size of each object does not change.

align(components,valign,'fixed',distance) adjusts the vertical spacing to be a fixed distance in points.

Align Objects Horizontally

align(components,spacing,halign) horizontally aligns the specified components. The function aligns the top sides, middles, or bottom sides of the objects depending on the value of halign, and adjusts the horizontal spacing between the objects depending on the value of spacing. For instance, align(components,'none','top') aligns top edges and makes no spacing adjustments. The size of each object does not change.

align(components,'fixed',distance,halign) adjusts the horizontal spacing to be a fixed distance in points.

Align Overlapping Objects

align(components,valign,halign) aligns the specified objects overlapping one another. This is equivalent to aligning the objects vertically according to valign and horizontally according to halign. For example, align(components,'left','top') aligns the top left corners of the objects in components.

Return Calculated Positions

positions = align(___) returns the calculated positions for the specified objects as a matrix if they are aligned, but does not move the objects. Each row of the matrix output is a position vector. Use this option with any of the input argument combinations in the previous syntaxes.

positions = align(cpositions,___) returns the calculated positions for the objects whose positions are contained in cpositions if they are aligned, but the positions of the objects on the figure do not change. Use this option with any of the input combinations in the previous syntaxes, replacing components with cpositions.

Examples

Align Centers Vertically

Create a figure containing three buttons that are not quite vertically aligned.

f = figure('Position',[100 100 350 200]);
u1 = uicontrol(f,'Position',[10 80 60 30],'String','One');
u2 = uicontrol(f,'Position',[50 50 60 30],'String','Two');
u3 = uicontrol(f,'Position',[30 10 60 30],'String','Three');

Align the button centers vertically and equalize the vertical spacing between the buttons. When aligning objects vertically, specify the vertical alignment argument before the object spacing.

align([u1 u2 u3],'center','distribute');

Align Bottom Edges Horizontally

Create a figure containing three buttons that are not quite horizontally aligned.

f = figure('Position',[100 100 350 200]);
u1 = uicontrol('Parent',f,'Position',[43 50 75 30],'String','Yes');
u2 = uicontrol('Parent',f,'Position',[143 75 75 30],'String','No');
u3 = uicontrol('Parent',f,'Position',[233 40 75 30],'String','Cancel');

Align the bottom edges of the buttons, and set the horizontal spacing between the buttons to 10 points. When aligning objects horizontally, specify the object spacing before the horizontal alignment argument.

align([u1 u2 u3],'fixed',10,'bottom');

Center Button on Axes Object

Create a figure containing a button and an axes object.

f = figure('Position',[100 100 350 200]);
ax = axes('Parent',f);
btn = uicontrol('Parent',f,'String','Click');

Align the center of the button with the center of the axes. The second argument, 'center', specifies the vertical alignment and the third argument, 'middle', specifies the horizontal alignment.

align([ax btn],'center','middle');

Predict Aligned Object Positions

Calculate where objects would end up if you aligned them, but do not actually align them.

Create a figure containing three unaligned buttons.

f = figure('Position',[100 100 350 200]);
u1 = uicontrol('Parent',f,'Position',[130 25 75 30],'String','Yes');
u2 = uicontrol('Parent',f,'Position',[35 60 75 30],'String','No');
u3 = uicontrol('Parent',f,'Position',[200 160 75 30],'String','Cancel');

Predict the result of aligning the buttons by calling align with an output argument. The output is expressed as a matrix whose rows are the predicted position vectors of the buttons.

pos1 = align([u1 u2 u3],'right','fixed',3)

pos1 =

   200    25    75    30
   200    59    75    30
   200    93    75    30

Alternatively, pass align the position vectors of the buttons.

pos2 = align([u1.Position;u2.Position;u3.Position],'right','fixed',3)

pos2 =

   200    25    75    30
   200    58    75    30
   200    91    75    30

In either case, the resulting positions are the same. Neither function call changes the position of the buttons on the figure.

figure(f)

Input Arguments

components — Objects to align

vector

Objects to align, specified as a vector of UIControl or Axes objects. If the vector contains objects of types other than UIControl or Axes, the align function ignores them. Aligning objects does not change their absolute sizes.

valign — Vertical alignment of objects

'left' | 'center' | 'right'

How to vertically align the objects in components, specified as 'left', 'center', or 'right'

valign	Definition
'left'	Vertically align the left edges of the objects.
'center'	Vertically center the objects.
'right'	Vertically align the right edges of the objects.

All alignment options justify the objects within the bounding box that encloses the objects. The 'left' option aligns the left edges of the objects with the left edge of the bounding box that contains them, and likewise for 'right'. The 'center' option aligns the centers of the objects with the center of the bounding box.

spacing — Spacing adjustment between objects

'none' | 'distribute'

Spacing adjustment between objects, specified as 'none' or 'distribute'.

• 'none' — Do not change the spacing between objects. When aligning the objects vertically, do not move them horizontally. When aligning objects horizontally, do not move them vertically.

• 'distribute' — Evenly distribute the objects. When aligning objects vertically, evenly distribute the objects horizontally between the left and right edges of the bounding box that encloses them. When aligning objects horizontally, evenly distribute the objects vertically between the top and bottom edges of the bounding box that encloses them.

halign — Horizontal alignment of objects

'top' | 'middle' | 'bottom'

How to horizontally align the objects in components, specified as 'top', 'middle', or 'bottom'.

halign	Definition
'top'	Horizontally align the top edges of the objects.
'middle'	Horizontally center the objects.
'bottom'	Horizontally align the bottom edges of the objects.

All alignment options align the objects within the bounding box that encloses the objects. The 'top' option aligns the top edges of the objects with the top edge of the bounding box that contains them, and likewise for 'bottom'. The 'middle' option aligns the middles of the objects with the middle of the bounding box.

distance — Fixed distance between objects

0 (default) | scalar

Fixed distance between objects, specified as a scalar in points, where 72 points equals 1 inch.

cpositions — Current object positions

matrix whose rows are position vectors

Current object positions, specified as a matrix whose rows are position vectors. Each position vector is a four-element vector that specifies the location and size of the object in the form [left bottom width height]. All position vector measurements are in pixel units.

Alternative Functionality

In App Designer and in apps created using the uifigure function, use a grid layout manager to align components. Using grid layout managers, you can lay out UI components in a grid. Create a grid layout manager by calling the uigridlayout function or, in App Designer, dragging a Grid Layout component onto the canvas.

For example, to align three buttons vertically in the upper-left corner of a figure, create a grid layout manager containing four rows and two columns. Specify that the first column and the first three rows scale to fit the components they contain. Then, create the three buttons and add them to the first three rows of the first column.

fig = uifigure;
fig.Position = [100 100 200 200];
gl = uigridlayout(fig);
gl.RowHeight = {'fit','fit','fit','1x'};
gl.ColumnWidth = {'fit','1x'};

btn1 = uibutton(gl);
btn1.Layout.Row = 1;
btn1.Layout.Column = 1;
btn2 = uibutton(gl);
btn2.Layout.Row = 2;
btn2.Layout.Column = 1;
btn3 = uibutton(gl);
btn3.Layout.Row = 3;
btn3.Layout.Column = 1;

Alternatively, in App Designer, use the Space options in the Canvas tab to align components in Design View. For more information, see Lay Out Apps in App Designer Design View.

Version History

Introduced in R2012b