Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQSplitter class implements a splitter widget.

A splitter lets the user control the size of child widgets by dragging the boundary between the children. Any number of widgets may be controlled by a single splitter. The typical use of aQSplitter is to create several widgets and add them usinginsertWidget() oraddWidget().

The following example will show aQListView,QTreeView, andQTextEdit side by side, with two splitter handles:

QSplitter*splitter=newQSplitter(parent);QListView*listview=newQListView;QTreeView*treeview=newQTreeView;QTextEdit*textedit=newQTextEdit;    splitter->addWidget(listview);    splitter->addWidget(treeview);    splitter->addWidget(textedit);

If a widget is already inside aQSplitter wheninsertWidget() oraddWidget() is called, it will move to the new position. This can be used to reorder widgets in the splitter later. You can useindexOf(),widget(), andcount() to get access to the widgets inside the splitter.

A defaultQSplitter lays out its children horizontally (side by side); you can usesetOrientation(Qt::Vertical) to lay its children out vertically.

By default, all widgets can be as large or as small as the user wishes, between theminimumSizeHint() (orminimumSize()) andmaximumSize() of the widgets.

QSplitter resizes its children dynamically by default. If you would rather haveQSplitter resize the children only at the end of a resize operation, callsetOpaqueResize(false).

The initial distribution of size between the widgets is determined by multiplying the initial size with the stretch factor. You can also usesetSizes() to set the sizes of all the widgets. The functionsizes() returns the sizes set by the user. Alternatively, you can save and restore the sizes of the widgets from aQByteArray usingsaveState() andrestoreState() respectively.

When youhide() a child its space will be distributed among the other children. It will be reinstated when youshow() it again.

Property Documentation

childrenCollapsible :bool

This property holds whether child widgets can be resized down to size 0 by the user.

By default, children are collapsible. It is possible to enable and disable the collapsing of individual children usingsetCollapsible().

Access functions:

See alsosetCollapsible().

handleWidth :int

This property holds the width of the splitter handles.

By default, this property contains a value that depends on the user's platform and style preferences.

If you set handleWidth to 1, the actual grab area will grow to overlap a few pixels of it's respective widgets.

Access functions:

opaqueResize :bool

This property holds whether resizing is opaque.

Opaque resizing is on by default.

Access functions:

orientation :Qt::Orientation

This property holds the orientation of the splitter.

By default the orientation is horizontal (i.e., the widgets are laid out side by side). The possible orientations areQt::Horizontal andQt::Vertical.

Access functions:

See alsoQSplitterHandle::orientation().

Member Function Documentation

QSplitter::QSplitter(QWidget * parent = 0)

Constructs a horizontal splitter with theparent argument passed on to theQFrame constructor.

See alsosetOrientation().

QSplitter::QSplitter(Qt::Orientation orientation,QWidget * parent = 0)

Constructs a splitter with the givenorientation andparent.

See alsosetOrientation().

QSplitter::~QSplitter()

Destroys the splitter. All children are deleted.

void QSplitter::addWidget(QWidget * widget)

Adds the givenwidget to the splitter's layout after all the other items.

Ifwidget is already in the splitter, it will be moved to the new position.

See alsoinsertWidget(),widget(), andindexOf().

[virtual protected]void QSplitter::changeEvent(QEvent * ev)

Reimplemented fromQWidget::changeEvent().

[virtual protected]void QSplitter::childEvent(QChildEvent * c)

Reimplemented fromQObject::childEvent().

Tells the splitter that the child widget described byc has been inserted or removed.

This method is also used to handle the situation where a widget is created with the splitter as a parent but not explicitly added withinsertWidget() oraddWidget(). This is for compatibility and not the recommended way of putting widgets into a splitter in new code. Please useinsertWidget() oraddWidget() in new code.

See alsoaddWidget() andinsertWidget().

[protected]int QSplitter::closestLegalPosition(int pos,int index)

Returns the closest legal position topos of the widget with indexindex.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. Positions are then measured from the right edge of the widget.

See alsogetRange().

int QSplitter::count() const

Returns the number of widgets contained in the splitter's layout.

See alsowidget() andhandle().

[virtual protected]QSplitterHandle * QSplitter::createHandle()

Returns a new splitter handle as a child widget of this splitter. This function can be reimplemented in subclasses to provide support for custom handles.

See alsohandle() andindexOf().

[virtual protected]bool QSplitter::event(QEvent * e)

Reimplemented fromQObject::event().

void QSplitter::getRange(int index,int * min,int * max) const

Returns the valid range of the splitter with indexindex in *min and *max ifmin andmax are not 0.

QSplitterHandle * QSplitter::handle(int index) const

Returns the handle to the left (or above) for the item in the splitter's layout at the givenindex. The handle at index 0 is always hidden.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. The handle will be to the right of the widget atindex.

See alsocount(),widget(),indexOf(),createHandle(), andsetHandleWidth().

int QSplitter::indexOf(QWidget * widget) const

Returns the index in the splitter's layout of the specifiedwidget. This also works for handles.

Handles are numbered from 0. There are as many handles as there are child widgets, but the handle at position 0 is always hidden.

See alsocount() andwidget().

void QSplitter::insertWidget(int index,QWidget * widget)

Inserts thewidget specified into the splitter's layout at the givenindex.

Ifwidget is already in the splitter, it will be moved to the new position.

ifindex is an invalid index, then the widget will be inserted at the end.

See alsoaddWidget(),indexOf(), andwidget().

bool QSplitter::isCollapsible(int index) const

Returns true if the widget atindex is collapsible, otherwise returns false

[virtual]QSize QSplitter::minimumSizeHint() const

Reimplemented fromQWidget::minimumSizeHint().

[protected]void QSplitter::moveSplitter(int pos,int index)

Moves the left or top edge of the splitter handle atindex as close as possible to positionpos, which is the distance from the left or top edge of the widget.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed.pos is then the distance from the right edge of the widget.

See alsosplitterMoved(),closestLegalPosition(), andgetRange().

void QSplitter::refresh()

Updates the splitter's state. You should not need to call this function.

[virtual protected]void QSplitter::resizeEvent(QResizeEvent *)

Reimplemented fromQWidget::resizeEvent().

bool QSplitter::restoreState(constQByteArray & state)

Restores the splitter's layout to thestate specified. Returns true if the state is restored; otherwise returns false.

Typically this is used in conjunction withQSettings to restore the size from a past session. Here is an example:

Restore the splitters's state:

QSettings settings;    splitter->restoreState(settings.value("splitterSizes").toByteArray());

A failure to restore the splitter's layout may result from either invalid or out-of-date data in the supplied byte array.

See alsosaveState().

QByteArray QSplitter::saveState() const

Saves the state of the splitter's layout.

Typically this is used in conjunction withQSettings to remember the size for a future session. A version number is stored as part of the data. Here is an example:

QSettings settings;    settings.setValue("splitterSizes", splitter->saveState());

See alsorestoreState().

void QSplitter::setCollapsible(int index,bool collapse)

Sets whether the child widget at indexindex is collapsible tocollapse.

By default, children are collapsible, meaning that the user can resize them down to size 0, even if they have a non-zerominimumSize() orminimumSizeHint(). This behavior can be changed on a per-widget basis by calling this function, or globally for all the widgets in the splitter by setting thechildrenCollapsible property.

See alsoisCollapsible() andchildrenCollapsible.

[protected]void QSplitter::setRubberBand(int pos)

Displays a rubber band at positionpos. Ifpos is negative, the rubber band is removed.

void QSplitter::setSizes(constQList<int> & list)

Sets the child widgets respective sizes to the values given in thelist.

If the splitter is horizontal, the values set the widths of each widget in pixels, from left to right. If the splitter is vertical, the heights of each widget is set, from top to bottom.

Extra values in thelist are ignored. Iflist contains too few values, the result is undefined but the program will still be well-behaved.

The overall size of the splitter widget is not affected. Instead, any additional/missing space is distributed amongst the widgets according to the relative weight of the sizes.

If you specify a size of 0, the widget will be invisible. The size policies of the widgets are preserved. That is, a value smaller then the minimal size hint of the respective widget will be replaced by the value of the hint.

See alsosizes().

void QSplitter::setStretchFactor(int index,int stretch)

Updates the size policy of the widget at positionindex to have a stretch factor ofstretch.

stretch is not the effective stretch factor; the effective stretch factor is calculated by taking the initial size of the widget and multiplying it withstretch.

This function is provided for convenience. It is equivalent to

QWidget*widget= splitter->widget(index);QSizePolicy policy= widget->sizePolicy();policy.setHorizontalStretch(stretch);policy.setVerticalStretch(stretch);widget->setSizePolicy(policy);

See alsosetSizes() andwidget().

[virtual]QSize QSplitter::sizeHint() const

Reimplemented fromQWidget::sizeHint().

QList<int> QSplitter::sizes() const

Returns a list of the size parameters of all the widgets in this splitter.

If the splitter's orientation is horizontal, the list contains the widgets width in pixels, from left to right; if the orientation is vertical, the list contains the widgets height in pixels, from top to bottom.

Giving the values to another splitter'ssetSizes() function will produce a splitter with the same layout as this one.

Note that invisible widgets have a size of 0.

See alsosetSizes().

[signal]void QSplitter::splitterMoved(int pos,int index)

This signal is emitted when the splitter handle at a particularindex has been moved to positionpos.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed.pos is then the distance from the right edge of the widget.

See alsomoveSplitter().

QWidget * QSplitter::widget(int index) const

Returns the widget at the givenindex in the splitter's layout.

See alsocount(),handle(),indexOf(), andinsertWidget().