From 916241e6aa2058363c5f67c6ab781530f5d3ec9f Mon Sep 17 00:00:00 2001 From: Luke Campagnola <> Date: Thu, 25 Oct 2012 00:15:11 -0400 Subject: [PATCH] documentation updates for DockArea --- dockarea/Dock.py | 99 +++++++++++--------------------------------- dockarea/DockArea.py | 40 ++++++++++++++---- 2 files changed, 56 insertions(+), 83 deletions(-) diff --git a/dockarea/Dock.py b/dockarea/Dock.py index 63fafca8..35781535 100644 --- a/dockarea/Dock.py +++ b/dockarea/Dock.py @@ -77,6 +77,11 @@ class Dock(QtGui.QWidget, DockDrop): return name == 'dock' def setStretch(self, x=None, y=None): + """ + Set the 'target' size for this Dock. + The actual size will be determined by comparing this Dock's + stretch value to the rest of the docks it shares space with. + """ #print "setStretch", self, x, y #self._stretch = (x, y) if x is None: @@ -100,6 +105,10 @@ class Dock(QtGui.QWidget, DockDrop): #return self._stretch def hideTitleBar(self): + """ + Hide the title bar for this Dock. + This will prevent the Dock being moved by the user. + """ self.label.hide() self.labelHidden = True if 'center' in self.allowedAreas: @@ -107,12 +116,21 @@ class Dock(QtGui.QWidget, DockDrop): self.updateStyle() def showTitleBar(self): + """ + Show the title bar for this Dock. + """ self.label.show() self.labelHidden = False self.allowedAreas.add('center') self.updateStyle() def setOrientation(self, o='auto', force=False): + """ + Sets the orientation of the title bar for this Dock. + Must be one of 'auto', 'horizontal', or 'vertical'. + By default ('auto'), the orientation is determined + based on the aspect ratio of the Dock. + """ #print self.name(), "setOrientation", o, force if o == 'auto' and self.autoOrient: if self.container().type() == 'tab': @@ -127,6 +145,7 @@ class Dock(QtGui.QWidget, DockDrop): self.updateStyle() def updateStyle(self): + ## updates orientation and appearance of title bar #print self.name(), "update style:", self.orientation, self.moveLabel, self.label.isVisible() if self.labelHidden: self.widgetArea.setStyleSheet(self.nStyle) @@ -154,6 +173,10 @@ class Dock(QtGui.QWidget, DockDrop): return self._container def addWidget(self, widget, row=None, col=0, rowspan=1, colspan=1): + """ + Add a new widget to the interior of this Dock. + Each Dock uses a QGridLayout to arrange widgets within. + """ if row is None: row = self.currentRow self.currentRow = max(row+1, self.currentRow) @@ -188,7 +211,8 @@ class Dock(QtGui.QWidget, DockDrop): def __repr__(self): return "" % (self.name(), self.stretch()) - + + class DockLabel(VerticalLabel): sigClicked = QtCore.Signal(object, object) @@ -287,76 +311,3 @@ class DockLabel(VerticalLabel): -#class DockLabel(QtGui.QWidget): - #def __init__(self, text, dock): - #QtGui.QWidget.__init__(self) - #self._text = text - #self.dock = dock - #self.orientation = None - #self.setOrientation('horizontal') - - #def text(self): - #return self._text - - #def mousePressEvent(self, ev): - #if ev.button() == QtCore.Qt.LeftButton: - #self.pressPos = ev.pos() - #self.startedDrag = False - #ev.accept() - - #def mouseMoveEvent(self, ev): - #if not self.startedDrag and (ev.pos() - self.pressPos).manhattanLength() > QtGui.QApplication.startDragDistance(): - #self.dock.startDrag() - #ev.accept() - ##print ev.pos() - - #def mouseReleaseEvent(self, ev): - #ev.accept() - - #def mouseDoubleClickEvent(self, ev): - #if ev.button() == QtCore.Qt.LeftButton: - #self.dock.float() - - #def setOrientation(self, o): - #if self.orientation == o: - #return - #self.orientation = o - #self.update() - #self.updateGeometry() - - #def paintEvent(self, ev): - #p = QtGui.QPainter(self) - #p.setBrush(QtGui.QBrush(QtGui.QColor(100, 100, 200))) - #p.setPen(QtGui.QPen(QtGui.QColor(50, 50, 100))) - #p.drawRect(self.rect().adjusted(0, 0, -1, -1)) - - #p.setPen(QtGui.QPen(QtGui.QColor(255, 255, 255))) - - #if self.orientation == 'vertical': - #p.rotate(-90) - #rgn = QtCore.QRect(-self.height(), 0, self.height(), self.width()) - #else: - #rgn = self.rect() - #align = QtCore.Qt.AlignTop|QtCore.Qt.AlignHCenter - - #self.hint = p.drawText(rgn, align, self.text()) - #p.end() - - #if self.orientation == 'vertical': - #self.setMaximumWidth(self.hint.height()) - #self.setMaximumHeight(16777215) - #else: - #self.setMaximumHeight(self.hint.height()) - #self.setMaximumWidth(16777215) - - #def sizeHint(self): - #if self.orientation == 'vertical': - #if hasattr(self, 'hint'): - #return QtCore.QSize(self.hint.height(), self.hint.width()) - #else: - #return QtCore.QSize(19, 50) - #else: - #if hasattr(self, 'hint'): - #return QtCore.QSize(self.hint.width(), self.hint.height()) - #else: - #return QtCore.QSize(50, 19) diff --git a/dockarea/DockArea.py b/dockarea/DockArea.py index 49dd95ff..d49f02ad 100644 --- a/dockarea/DockArea.py +++ b/dockarea/DockArea.py @@ -35,8 +35,18 @@ class DockArea(Container, QtGui.QWidget, DockDrop): def addDock(self, dock, position='bottom', relativeTo=None): """Adds a dock to this area. - position may be: bottom, top, left, right, over, under - If relativeTo specifies an existing dock, the new dock is added adjacent to it""" + + =========== ================================================================= + Arguments: + dock The new Dock object to add. + position 'bottom', 'top', 'left', 'right', 'over', or 'under' + relativeTo If relativeTo is None, then the new Dock is added to fill an + entire edge of the window. If relativeTo is another Dock, then + the new Dock is placed adjacent to it (or in a tabbed + configuration for 'over' and 'under'). + =========== ================================================================= + + """ ## Determine the container to insert this dock into. ## If there is no neighbor, then the container is the top. @@ -90,6 +100,17 @@ class DockArea(Container, QtGui.QWidget, DockDrop): dock.area = self self.docks[dock.name()] = dock + def moveDock(self, dock, position, neighbor): + """ + Move an existing Dock to a new location. + """ + old = dock.container() + ## Moving to the edge of a tabbed dock causes a drop outside the tab box + if position in ['left', 'right', 'top', 'bottom'] and neighbor is not None and neighbor.container() is not None and neighbor.container().type() == 'tab': + neighbor = neighbor.container() + self.addDock(dock, position, neighbor) + old.apoptose() + def getContainer(self, obj): if obj is None: return self @@ -131,13 +152,6 @@ class DockArea(Container, QtGui.QWidget, DockDrop): return 0 return 1 - def moveDock(self, dock, position, neighbor): - old = dock.container() - ## Moving to the edge of a tabbed dock causes a drop outside the tab box - if position in ['left', 'right', 'top', 'bottom'] and neighbor is not None and neighbor.container() is not None and neighbor.container().type() == 'tab': - neighbor = neighbor.container() - self.addDock(dock, position, neighbor) - old.apoptose() #def paintEvent(self, ev): #self.drawDockOverlay() @@ -159,6 +173,7 @@ class DockArea(Container, QtGui.QWidget, DockDrop): return area def floatDock(self, dock): + """Removes *dock* from this DockArea and places it in a new window.""" area = self.addTempArea() area.win.resize(dock.size()) area.moveDock(dock, 'top', None) @@ -170,6 +185,9 @@ class DockArea(Container, QtGui.QWidget, DockDrop): area.window().close() def saveState(self): + """ + Return a serialized (storable) representation of the state of + all Docks in this DockArea.""" state = {'main': self.childState(self.topContainer), 'float': []} for a in self.tempAreas: geo = a.win.geometry() @@ -188,6 +206,10 @@ class DockArea(Container, QtGui.QWidget, DockDrop): def restoreState(self, state): + """ + Restore Dock configuration as generated by saveState. + """ + ## 1) make dict of all docks and list of existing containers containers, docks = self.findAll() oldTemps = self.tempAreas[:]