QSplitterHandle Class

Detailed Description

The QSplitterHandle class provides handle functionality for the splitter.

QSplitterHandle is typically what people think about when they think about a splitter. It is the handle that is used to resize the widgets.

A typical developer using QSplitter will never have to worry about QSplitterHandle. It is provided for developers who want splitter handles that provide extra features, such as popup menus.

The typical way one would create splitter handles is to subclass QSplitter and then reimplement QSplitter::createHandle() to instantiate the custom splitter handle. For example, a minimum QSplitter subclass might look like this:

  class Splitter : public QSplitter
  {
  public:
      Splitter(Qt::Orientation orientation, QWidget *parent = 0);

  protected:
      QSplitterHandle *createHandle();
  };

The createHandle() implementation simply constructs a custom splitter handle, called Splitter in this example:

  QSplitterHandle *Splitter::createHandle()
  {
      return new SplitterHandle(orientation(), this);
  }

Information about a given handle can be obtained using functions like orientation() and opaqueResize(), and is retrieved from its parent splitter. Details like these can be used to give custom handles different appearances depending on the splitter's orientation.

The complexity of a custom handle subclass depends on the tasks that it needs to perform. A simple subclass might only provide a paintEvent() implementation:

  void SplitterHandle::paintEvent(QPaintEvent *event)
  {
      QPainter painter(this);
      if (orientation() == Qt::Horizontal) {
          gradient.setStart(rect().left(), rect().height()/2);
          gradient.setFinalStop(rect().right(), rect().height()/2);
      } else {
          gradient.setStart(rect().width()/2, rect().top());
          gradient.setFinalStop(rect().width()/2, rect().bottom());
      }
      painter.fillRect(event->rect(), QBrush(gradient));
  }

In this example, a predefined gradient is set up differently depending on the orientation of the handle. QSplitterHandle provides a reasonable size hint for the handle, so the subclass does not need to provide a reimplementation of sizeHint() unless the handle has special size requirements.