Frames and manager — qtaui 1.0.2 documentation

# Frames and manager

The basic building blocks of a qtaui based UI are frames, which are instances of `QAUILeafFrame` (a QWidget really). The application must also hold an instance of `QAUIManager`, which acts as a common ancestor and repository for frames. So the skeleton of a qtaui based application would be:

    from PySide import QtGui
    from qtaui import QAUIManager, QAUILeafFrame

    class MainWindow(QtGui.QMainWindow):
        def __init__(self):
            super(MainWindow, self).__init__()
            self.manager = QAUIManager()
            self.setCentralWidget(self.manager)

            # Let's add a simple empty frame
            self.manager.addFrame(QAUILeafFrame(self.manager, title='I am a frame'))

    if __name__ == '__main__':
        app = QtGui.QApplication([])
        win = MainWindow()
        win.show()
        win.raise_()
        app.exec_()

Which will look pretty uninteresting:

## Frame position

the `QAUIManager.addFrame()` method takes an optional position argument, which value must be one of the constants defined in the `QAUIPos` class. The default value is `QAUIPos.CENTER`, which means to add the frame as a new tab. Other values are:

`QAUIPos.LEFT`
  Add the frame as a new column in an horizontal splitter, to the left.
`QAUIPos.RIGHT`
  Add the frame as a new column in an horizontal splitter, to the right.
`QAUIPos.TOP`
  Add the frame as a new row in a vertical splitter, to the top.
`QAUIPos.BOTTOM`
  Add the frame as a new row in a vertical splitter, to the bottom.
`QAUIPos.FLOATING`
  Add the frame as a top-level widget.

The frame that will be replaced in the hierarchy by a splitter/tabbed interface is the one the `QAUILeafFrame.addFrame()` method is called on. So we can already build a not so simple interface:

> - Tab #1
>   - Vertical splitter with frames 1 and 2
> - Tab #2
>   - Horizontal splitter with frames 3 and 4

With the following code:

    from PySide import QtGui
    from qtaui import QAUIManager, QAUILeafFrame, QAUIPos

    class MainWindow(QtGui.QMainWindow):
        def __init__(self):
            super(MainWindow, self).__init__()
            self.manager = QAUIManager()
            self.setCentralWidget(self.manager)

            tab1 = self.manager.addFrame(QAUILeafFrame(self.manager, title='Frame #1'))
            tab1.addFrame(QAUILeafFrame(self.manager, title='Frame #2'), QAUIPos.BOTTOM)
            tab2 = self.manager.addFrame(QAUILeafFrame(self.manager, title='Frame #3'))
            tab2.addFrame(QAUILeafFrame(self.manager, title='Frame #4'), QAUIPos.LEFT)

            self.resize(600, 300)

    if __name__ == '__main__':
        app = QtGui.QApplication([])
        win = MainWindow()
        win.show()
        win.raise_()
        app.exec_()

## Undocking a frame

Leaf frames and tabs have a title bar. The user can drag the frame from this titlebar in order to undock it, i.e. to make it into a top-level widget. The parent container of the undocked widget will be replaced by the appropriate one if this leads to it containing only one or zero frames; for instance a tabbed container will be replaced by a plain one, thus removing the tabs. Undocking the frame #4 in the previous example will lead to this:

When a frame is undocked, the frame itself emits a `QAUILeafFrame.undocked()` signal and the manager emits a `QAUIManager.frameUndocked()` signal. There are also `QAUILeafFrame.docked()` and `QAUIManager.frameDocked()` signals. See the Class reference for more information.

Note

Since Qt does not exit the main event loop as long as there are visible top-level widgets, a convenience method of the `QAUIManager` class allows you to hide all undocked frames at once; this must typically be called on program termination, from your main window:

    def closeEvent(self, event):
        self.manager.shutdown()
        event.accept()

## Docking a frame

When the user is dragging an undocked frame around, the `QAUIManager` goes into “drop” mode, which is a graphical representation of the UI hierarchy, with hints as to where the frame can be dropped in order to dock it:

Each part of the hierarchy has five drop targets, each mapping to one of the positions defined in `QAUIPos`.