Main Content

align

Align UI control components and axes objects

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

    Description

    Align Objects Vertically

    example

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

    example

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

    Align Overlapping Objects

    example

    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

    example

    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.

    Examples

    collapse all

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

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

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

    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

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

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

    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.

    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.

    Introduced in R2012b