Main Content

align

Align UIControl components and Axes objects

collapse all in page

    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.

    example

    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.

    example

    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.

    example

    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.

    example

    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.

    example

    Examples

    collapse all

    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");

    Figure window with three unaligned buttons

    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");

    Figure window with three buttons in a column with equal vertical distance between each button

    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");

    Figure window with three unaligned buttons

    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");

    Figure window with three buttons in a row, with a distance of 10 pixels between each button

    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");

    Figure window with an axes object and a button in the lower-left corner

    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");

    Figure window with an axes object and button in the center of the axes

    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");

    Figure window with three unaligned buttons

    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)

    Figure window with three unaligned buttons

    Input Arguments

    collapse all

    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.

    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.

    Two rectangles with left edges aligned in a column

    "center"

    Align the horizontal centers of the objects.

    Two rectangles with horizontal centers aligned in a column

    "right"

    Align the right edges of the objects.

    Two rectangles with right edges aligned in a column

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

    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.

    Two rectangles with top edges aligned in a row

    "middle"

    Align the vertical centers of the objects.

    Two rectangles with horizontal middles aligned in a row

    "bottom"

    Align the bottom edges of the objects.

    Two rectangles with bottom edges aligned in a row

    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.

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

    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;

    Figure window with three buttons stacked vertically in the upper-left corner

    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

    See Also

    | |