CopperSpice API  1.7.4
Using Layouts

Widgets and controls need to be placed into layouts. This process guarantees all of the objects will be displayed properly when the form is previewed in the Designer program or used in an application. Controls will be resized automatically by the CopperSpice GUI system as the window size is changed. During a resize the layout will use the hints provided by various controls, including horizontal or vertical spacers.

Top Level Layout

A layout attached to the first widget in the Object Inspector is called the top level layout. This will usually be a QMainWindow, QDialog, or QWidget control.

To check if a top level layout is present, preview your widget and attempt to resize the window by dragging the size grip. If the controls resize then you have a top level layout. Another way to check is by looking in the Object Inspector. If you see the the layout icon with a red circle and a line through it, then no top level layout was set.

To set a top level layout all widgets and controls in the window must be deselected. To clear all selections click the left mouse button on the form or unselect each control by hand. Then proceed with applying a top level layout.

Inserting Objects into a Layout

Objects can be inserted into an existing layout by dragging and dropping a control from the Widget Box or from another location on the form. A blue cursor is displayed in the layout as an object is dragged to indicate where the object will be added.

Applying and Breaking Layouts

To apply a layout to a group of existing objects, select the desired controls and apply one of the standard layouts using the main toolbar, Form menu, or the form's context menu.

Once a widget or control has been inserted into a layout you can not move and resize them individually because the layout controls the geometry of these widgets. To move or resize a widget you must first break the layout to adjust the object's geometry. To break a layout press Ctrl+0 or choose Break Layout from the main toolbar, the Form menu, or the form's context menu.

After the widgets have been adjusted then you will need to reapply the layout.

Another way to adjust spacing and improve the look and feel, is by using horizontal and vertical spacers to influence the geometries of the widgets.


These are the various types of layout formats.

  • Lay Out Horizontally
  • Lay Out Vertically
  • Lay Out in a Grid
  • Lay Out in a Form Layout
  • Lay Out Horizontally in Splitter
  • Lay Out Vertically in Splitter
  • Break Layout

Horizontal and Vertical Layouts

The simplest way to arrange objects on a form is to place them in a horizontal or vertical layout. Horizontal layouts ensure the widgets within it are aligned horizontally. A vertical layout ensure they are aligned vertically. Horizontal and vertical layouts can be combined and nested to any depth. If you find this is not providing enough control over the placement of objects, consider using the grid layout.

Grid Layout

Complex form layouts can be created by placing a group of controls in a grid layout. A grid arrangement is often much more suitable than a nested arrangement of horizontal and vertical layouts.

Splitter Layout

Another common way to manage the layout of objects to place them in a splitter. Splitters arrange the controls horizontally or vertically in the same way as normal layouts, while allowing the user to adjust the amount of space allocated to each object.

QSplitter is a container widget. The Designer program uses splitter objects as layouts. To place a group of controls into a splitter, select them as described here, then apply the splitter layout by using the main toolbar, Form menu, or the form's context menu.

Form Layout

The QFormLayout class manages widgets in a two-column form. The left column holds labels and the right column holds widgets such as line edits, spin boxes, etc. A form layout adheres to the various platform look and feel guidelines and supports wrapping for long rows.

Shortcut Keys

The following is a list of the keyboard shortcuts which can be used to apply a layout to a widget.

Break LayoutCtrl+0 Used to break a layout
HorizontalCtrl+1 Selected objects are arranged horizontally
VerticalCtrl+2 Selected objects are arranged vertically
GridCtrl+5 Selected objects are arranged in a grid
FormCtrl+6 Selected objects are arranged using a form layout
Horizontal splitterCtrl+3 Creates a horizontal splitter and puts the selected objects inside
Vertical splitterCtrl+4 Creates a vertical splitter and puts the selected objects inside
Adjust sizeCtrl+J Adjusts the size of the layout to ensure each child object has sufficient space to display their contents
See also