align

Align UIControl components and Axes objects

Syntax

align(components,hloc,spacing)

align(components,hloc,"fixed",distance)

align(components,spacing,vloc)

align(components,"fixed",distance,vloc)

align(components,hloc,vloc)

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 in Column

align(components,hloc,spacing) aligns the specified components in a column. The function aligns the left sides, centers, or right sides of the objects depending on the value of hloc, 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,hloc,"fixed",distance) adjusts the vertical spacing to be a fixed distance in points.

Align Objects in Row

align(components,spacing,vloc) aligns the specified components in a row. The function aligns the top sides, middles, or bottom sides of the objects depending on the value of vloc, 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,vloc) adjusts the horizontal spacing to be a fixed distance in points.

Align Overlapping Objects

align(components,hloc,vloc) aligns the specified objects overlapping one another. This is equivalent to aligning the objects in a column according to hloc and in a row according to vloc. 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 in Column

Create a figure containing three buttons that are not quite 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 in a column and equalize the vertical spacing between the buttons. When aligning objects in a column, specify the alignment argument before the object spacing.

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

Align Bottom Edges in Row

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

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

Align the bottom edges of the buttons in a row, and set the horizontal spacing between the buttons to 10 points. When aligning objects in a row, specify the object spacing before the 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(f);
btn = uicontrol(f,"String","Click");

Align the center of the button with the center of the axes. The second argument, "center", specifies which parts of the components to align in a column and the third argument, "middle", specifies which parts of the components to align in a row.

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(f,"Position",[130 25 75 30],"String","Yes");
u2 = uicontrol(f,"Position",[35 60 75 30],"String","No");
u3 = uicontrol(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 sizes.

hloc — Horizontal locations of objects to align in a column

"left" | "center" | "right"

Horizontal locations of objects in components to align in a column, specified as "left", "center", or "right". This table describes each of the options.

hloc	Result
"left"	Align the left edges of the objects.
"center"	Align the horizontal centers of the objects.
"right"	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 in a column, do not move them vertically. When aligning objects in a row, do not move them horizontally.

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

vloc — Vertical locations of objects to align in a row

"top" | "middle" | "bottom"

Vertical locations of objects in components to align in a row, specified as "top", "middle", or "bottom".

halign	Result
"top"	Align the top edges of the objects.
"middle"	Align the vertical centers of the objects.
"bottom"	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 in a column 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