kdeui Library API Documentation

KDockWidget Class Reference

Floatable widget that can be dragged around with the mouse and encapsulate the actual widgets (and member of the dockwidget class set). More...

#include <kdockwidget.h>

Inheritance diagram for KDockWidget:

QWidget List of all members.

Public Types

enum  DockPosition {
  DockNone = 0, DockTop = 0x0001, DockLeft = 0x0002, DockRight = 0x0004,
  DockBottom = 0x0008, DockCenter = 0x0010, DockDesktop = 0x0020, DockToSpecialSites = 0x0040,
  DockCorner = DockTop | DockLeft | DockRight | DockBottom, DockFullSite = DockCorner | DockCenter, DockFullDocking = DockFullSite | DockDesktop
}

Public Slots

void setForcedFixedWidth (int)
void setForcedFixedHeight (int)
void restoreFromForcedFixedSize ()
int forcedFixedWidth ()
int forcedFixedHeight ()
void dockBack ()
void changeHideShowState ()
void undock ()
void toDesktop ()

Signals

void widgetSet (QWidget *)
void docking (KDockWidget *dw, KDockWidget::DockPosition dp)
void setDockDefaultPos ()
void headerCloseButtonClicked ()
void headerDockbackButtonClicked ()
void iMBeingClosed ()
void hasUndocked ()

Public Member Functions

 KDockWidget (KDockManager *dockManager, const char *name, const QPixmap &pixmap, QWidget *parent=0L, const QString &strCaption=QString::null, const QString &strTabPageLabel=QString::fromLatin1(" "), WFlags f=0)
virtual ~KDockWidget ()
KDockWidgetmanualDock (KDockWidget *target, DockPosition dockPos, int spliPos=50, QPoint pos=QPoint(0, 0), bool check=false, int tabIndex=-1)
void setEnableDocking (int pos)
int enableDocking () const
void setDockSite (int pos)
int dockSite () const
void setWidget (QWidget *w)
QWidgetgetWidget () const
void setHeader (KDockWidgetAbstractHeader *ah)
KDockWidgetAbstractHeadergetHeader ()
void makeDockVisible ()
bool mayBeHide () const
bool mayBeShow () const
KDockManagerdockManager () const
void setToolTipString (const QString &ttStr)
const QStringtoolTipString () const
bool isDockBackPossible () const
void setTabPageLabel (const QString &label)
const QStringtabPageLabel () const
virtual bool event (QEvent *)
virtual void show ()
KDockTabGroupparentDockTabGroup () const
QWidgetparentDockContainer () const
void setDockWindowType (NET::WindowType windowType)
void setDockWindowTransient (QWidget *parent, bool transientEnabled)
QWidgettransientTo ()
KDockWidgetfindNearestDockWidget (DockPosition pos)
void setPixmap (const QPixmap &pixmap=QPixmap())
const QPixmappixmap () const
KDockWidget::DockPosition currentDockPosition () const

Protected Slots

void loseFormerBrotherDockWidget ()
virtual void paintEvent (QPaintEvent *)
virtual void mousePressEvent (QMouseEvent *)
virtual void mouseReleaseEvent (QMouseEvent *)
virtual void mouseMoveEvent (QMouseEvent *)
virtual void leaveEvent (QEvent *)

Protected Member Functions

void updateHeader ()
void setLatestKDockContainer (QWidget *)
QWidgetlatestKDockContainer ()
void setFormerBrotherDockWidget (KDockWidget *)
virtual void virtual_hook (int id, void *data)

Protected Attributes

KDockWidgetformerBrotherDockWidget
DockPosition currentDockPos
DockPosition formerDockPos
QString toolTipStr
QString tabPageTitle

Friends

class KDockManager
class KDockSplitter
class KDockMainWindow
class KDockArea
class KMdiMainFrm
class KDockWidgetHeader

Detailed Description

Floatable widget that can be dragged around with the mouse and encapsulate the actual widgets (and member of the dockwidget class set).

You just grip the double-lined panel, tear it off its parent widget, drag it somewhere and let it loose. Depending on the position where you leave it, the dockwidget becomes a toplevel window on the desktop (floating mode) or docks to a new widget (dock mode). Note: A KDockWidget can only be docked to a KDockWidget.

If you want to use this kind of widget, your main application window has to be a KDockMainWindow. That is because it has got several additional dock management features, for instance a KDockManager that has an overview over all dockwidgets and and a dockmovemanager (internal class) that handles the dock process.

Usually you create an KDockWidget that covers the actual widget in this way:

 ...
 KDockMainWindow* mainWidget;
 ...
 KDockWidget* dock = 0L;
 dock = mainWidget->createDockWidget( "Any window caption", nicePixmap, 0L, i18n("window caption")); // 0L==no parent
 QWidget* actualWidget = new QWidget( dock);
 dock->setWidget( actualWidget); // embed it
 dock->setToolTipString(i18n("That's me")); // available when appearing as tab page
 ...

See KDockMainWindow how a dockwidget is docked in.

Author:
Max Judin (documentation: Falk Brettschneider).

Definition at line 412 of file kdockwidget.h.


Member Enumeration Documentation

enum KDockWidget::DockPosition
 

The possible positions where a dockwidget can dock to another dockwidget.

Enumeration values:
DockToSpecialSites 
Since:
3.1

Definition at line 448 of file kdockwidget.h.

Referenced by currentDockPosition(), manualDock(), and KDockManager::readConfig().


Constructor & Destructor Documentation

KDockWidget::KDockWidget KDockManager dockManager,
const char *  name,
const QPixmap pixmap,
QWidget parent = 0L,
const QString strCaption = QString::null,
const QString strTabPageLabel = QString::fromLatin1(" "),
WFlags  f = 0
 

Construct a dockwidget.

Initially, docking to another and docking to this is allowed for every DockPosition. It is supposed to be no (tab) group. It will taken under control of its dockmanager.

Parameters:
dockManager The responsible manager (dock helper)
name Object instance name
pixmap An icon (for instance shown when docked centered)
parent Parent widget
strCaption Title of the dockwidget window (shown when toplevel)
strTabPageLabel The title of the tab page (shown when in tab page mode), if it is "", only the icon will be shown, if it is 0L, the label is set to strCaption
f Qt::WidgetFlags widget flags

Definition at line 478 of file kdockwidget.cpp.

Referenced by manualDock().

KDockWidget::~KDockWidget  )  [virtual]
 

Destructs a dockwidget.

Definition at line 548 of file kdockwidget.cpp.

References KDockWidgetPrivate::blockHasUndockedSignal, KDockManager::childDock, KDockManager::d, iMBeingClosed(), latestKDockContainer(), KDockWidgetPrivate::pendingDtor, undock(), and KDockManager::undockProcess.


Member Function Documentation

KDockWidget * KDockWidget::manualDock KDockWidget target,
DockPosition  dockPos,
int  spliPos = 50,
QPoint  pos = QPoint(0, 0),
bool  check = false,
int  tabIndex = -1
 

This is a key method of this class! Use it to dock dockwidgets to another dockwidget at the right position within its KDockMainWindow or a toplevel dockwidget.

If the target is null, it will become a toplevel dockwidget at position pos; Note: Docking to another dockwidget means exactly: A new parent dockwidget will be created, that replaces the target dockwidget and contains another single helper widget (tab widget or panner) which contains both dockwidgets, this and the target dockwidget. So consider parent<->child relationships change completely during such actions.

Parameters:
target The dockwidget to dock to
dockPos One of the DockPositions this is going to dock to
spliPos The split relation (in percent, or percent*100 in high resolution) between both dockwidgets, target and this
pos The dock position, mainly of interest for docking to the desktop (as toplevel dockwidget)
check Only for internal use;
tabIndex The position index of the tab widget (when in tab page mode), -1 (default) means append
Returns:
result The group dockwidget that replaces the target dockwidget and will be grandparent of target and this.

Definition at line 944 of file kdockwidget.cpp.

References KDockSplitter::activate(), applyToWidget(), KDockWidgetPrivate::blockHasUndockedSignal, KDockManager::change(), currentDockPos, KDockManager::d, KDockSplitter::deactivate(), docking(), dockManager(), DockPosition, eDocking, formerBrotherDockWidget, formerDockPos, KDockSplitter::getFirst(), isGroup, isTabGroup, KDockWidget(), latestKDockContainer(), loseFormerBrotherDockWidget(), parentDockContainer(), parentDockTabGroup(), KDockManager::replaceDock(), sDocking, setDockWindowTransient(), setFormerBrotherDockWidget(), KDockSplitter::setKeepSize(), setLatestKDockContainer(), KDockSplitter::setOpaqueResize(), setWidget(), show(), KDockManager::splitterHighResolution(), KDockManager::splitterKeepSize(), KDockManager::splitterOpaqueResize(), tabPageLabel(), toolTipStr, toolTipString(), KDockTabGroup::transientTo(), undock(), and widget.

Referenced by dockBack(), KDockManager::readConfig(), and toDesktop().

void KDockWidget::setEnableDocking int  pos  ) 
 

Specify where it is either possible or impossible for this to dock to another dockwidget.

Parameters:
pos An OR'ed set of DockPositions

Definition at line 761 of file kdockwidget.cpp.

References updateHeader().

Referenced by setHeader().

int KDockWidget::enableDocking  )  const [inline]
 

Returns:
Where it is either possible or impossible for this to dock to another dockwidget (an OR'ed set of DockPositions).

Definition at line 494 of file kdockwidget.h.

void KDockWidget::setDockSite int  pos  )  [inline]
 

Specify where it is either possible or impossible for another dockwidget to dock to this.

Parameters:
pos An OR'ed set of DockPositions

Definition at line 501 of file kdockwidget.h.

int KDockWidget::dockSite  )  const [inline]
 

Returns:
There it is either possible or impossible for another dockwidget to dock to this (an OR'ed set of DockPositions).

Definition at line 506 of file kdockwidget.h.

Referenced by isDockBackPossible().

void KDockWidget::setWidget QWidget w  ) 
 

Sets the embedded widget.

A QLayout takes care about proper resizing, automatically.

Parameters:
w The pointer to the dockwidget's child widget.

Definition at line 1425 of file kdockwidget.cpp.

References KDockManager::d, KDockWidgetPrivate::isContainer, updateHeader(), and widgetSet().

Referenced by manualDock(), and setHeader().

QWidget* KDockWidget::getWidget  )  const [inline]
 

Get the embedded widget.

Returns:
The pointer to the dockwidget's child widget, 0L if there's no such child.

Definition at line 522 of file kdockwidget.h.

Referenced by findNearestDockWidget(), and KDockManager::readConfig().

void KDockWidget::setHeader KDockWidgetAbstractHeader ah  ) 
 

Sets the header of this dockwidget.

A QLayout takes care about proper resizing, automatically. The header contains the drag panel, the close button and the stay button.

Parameters:
ah A base class pointer to the dockwidget header

Definition at line 741 of file kdockwidget.cpp.

References kdDebug(), setEnableDocking(), and setWidget().

KDockWidgetAbstractHeader * KDockWidget::getHeader  ) 
 

Since:
3.2 get the pointer to the header widget

Definition at line 737 of file kdockwidget.cpp.

void KDockWidget::makeDockVisible  ) 
 

Normally it simply shows the dockwidget.

But additionally, if it is docked to a tab widget (DockCenter), it is set as the active (visible) tab page.

Definition at line 1511 of file kdockwidget.cpp.

References dockBack(), parentDockContainer(), parentDockTabGroup(), and show().

Referenced by changeHideShowState(), dockBack(), KDockMainWindow::makeDockVisible(), KDockManager::makeWidgetDockVisible(), and show().

bool KDockWidget::mayBeHide  )  const
 

Returns:
If it may be possible to hide this.
There are reasons that it's impossible:
  • It is a (tab) group.
  • It is already invisible ;-)
  • The parent of this is the KDockMainWindow.
  • It isn't able to dock to another widget.

Definition at line 1483 of file kdockwidget.cpp.

References KDockManager::main.

Referenced by changeHideShowState().

bool KDockWidget::mayBeShow  )  const
 

Returns:
If it may be possible to show this. There are reasons that it's impossible:
  • It is a (tab) group.
  • It is already visible ;-)
  • The parent of this is the KDockMainWindow.

Definition at line 1489 of file kdockwidget.cpp.

References KDockManager::main.

Referenced by changeHideShowState().

KDockManager* KDockWidget::dockManager  )  const [inline]
 

Returns:
The dockmanager that is responsible for this.

Definition at line 569 of file kdockwidget.h.

Referenced by KDockWidgetAbstractHeaderDrag::KDockWidgetAbstractHeaderDrag(), and manualDock().

void KDockWidget::setToolTipString const QString ttStr  )  [inline]
 

Stores a string for a tooltip.

That tooltip string has only a meaning when this dockwidget is shown as tab page. In this case the tooltip is shown when one holds the mouse cursor on the tab page header. Such tooltip will for instance be useful, if you use only icons there. Note: Setting an empty string switches the tooltip off.

Parameters:
ttStr A string for the tooltip on the tab.

Definition at line 581 of file kdockwidget.h.

Referenced by KDockManager::readConfig().

const QString& KDockWidget::toolTipString  )  const [inline]
 

Returns:
The tooltip string being shown on the appropriate tab page header when in dock-centered mode.

Definition at line 586 of file kdockwidget.h.

Referenced by manualDock(), and KDockManager::writeConfig().

bool KDockWidget::isDockBackPossible  )  const
 

Returns:
result true, if a dockback is possible, otherwise false.

Definition at line 1585 of file kdockwidget.cpp.

References dockSite(), and formerBrotherDockWidget.

Referenced by KDockWidgetHeader::setTopLevel().

void KDockWidget::setTabPageLabel const QString label  )  [inline]
 

Sets a string that is used for the label of the tab page when in tab page mode.

Parameters:
label The new tab page label.

Definition at line 597 of file kdockwidget.h.

Referenced by KDockManager::readConfig().

const QString& KDockWidget::tabPageLabel  )  const [inline]
 

Returns:
A string that is used for the label of the tab page when in tab page mode.

Definition at line 602 of file kdockwidget.h.

Referenced by event(), manualDock(), and KDockManager::writeConfig().

bool KDockWidget::event QEvent  )  [virtual]
 

Catches and processes some QWidget events that are interesting for dockwidgets.

Definition at line 874 of file kdockwidget.cpp.

References KDockManager::change(), iMBeingClosed(), parentDockTabGroup(), KDockWidgetPrivate::pendingFocusInEvent, and tabPageLabel().

void KDockWidget::show  )  [virtual]
 

Add dockwidget management actions to QWidget::show.

Definition at line 837 of file kdockwidget.cpp.

References KDockManager::main, makeDockVisible(), setDockDefaultPos(), and KDockManager::setDockDefaultPos().

Referenced by KDockManager::activate(), makeDockVisible(), manualDock(), KDockManager::readConfig(), and undock().

KDockTabGroup * KDockWidget::parentDockTabGroup  )  const
 

Returns:
the parent widget of this if it inherits class KDockTabGroup

Definition at line 1196 of file kdockwidget.cpp.

Referenced by KDockManager::activate(), event(), makeDockVisible(), manualDock(), setPixmap(), and undock().

QWidget * KDockWidget::parentDockContainer  )  const
 

Since:
3.1

Definition at line 1204 of file kdockwidget.cpp.

Referenced by makeDockVisible(), manualDock(), and setPixmap().

void KDockWidget::setDockWindowType NET::WindowType  windowType  ) 
 

Sets the type of the dock window.

Parameters:
windowType is type of dock window

Definition at line 855 of file kdockwidget.cpp.

References KDockWidgetPrivate::windowType.

QWidget * KDockWidget::transientTo  ) 
 

Returns the widget this dockwidget is set transient to, otherwise 0

Since:
3.2.

Definition at line 870 of file kdockwidget.cpp.

References KDockWidgetPrivate::_parent, and KDockWidgetPrivate::transient.

KDockWidget * KDockWidget::findNearestDockWidget DockPosition  pos  ) 
 

Lookup the nearest dockwidget docked left/right/top/bottom to this one or return 0.

Parameters:
pos is the position the wanted widget is docked to this one
Since:
3.1

Definition at line 917 of file kdockwidget.cpp.

References getWidget().

void KDockWidget::setPixmap const QPixmap pixmap = QPixmap()  ) 
 

Allows changing the pixmap which is used for the caption or dock tabs.

Parameters:
pixmap is the pixmap to set
Since:
3.2

Definition at line 528 of file kdockwidget.cpp.

References parentDockContainer(), and parentDockTabGroup().

const QPixmap & KDockWidget::pixmap  )  const
 

Returns the dockwidget's associated caption/dock tab pixmap.

Since:
3.2

Definition at line 544 of file kdockwidget.cpp.

KDockWidget::DockPosition KDockWidget::currentDockPosition  )  const
 

Returns:
the current dock position.
Since:
3.3

Definition at line 1263 of file kdockwidget.cpp.

References DockPosition.

void KDockWidget::setForcedFixedWidth int   )  [slot]
 

subject to changes.

It doesn't completely work yet without small hacks from within the calling application (Perhaps KDE 3.1.x oder 3.2 width is in pixel. It only affects a widget, which is placed directly into a horizontal KDockSplitter

Since:
3.1

Definition at line 1213 of file kdockwidget.cpp.

References KDockWidgetPrivate::forcedWidth.

void KDockWidget::setForcedFixedHeight int   )  [slot]
 

subject to changes.

It doesn't completely work yet without small hacks from within the calling application (Perhaps KDE 3.1.x oder 3.2 height is in pixel. It only affects a widget, which is placed directly into a vertical KDockSplitter

Since:
3.1

Definition at line 1222 of file kdockwidget.cpp.

References KDockWidgetPrivate::forcedHeight.

void KDockWidget::restoreFromForcedFixedSize  )  [slot]
 

Since:
3.1

Definition at line 1241 of file kdockwidget.cpp.

References KDockWidgetPrivate::forcedWidth.

int KDockWidget::forcedFixedWidth  )  [slot]
 

Since:
3.1

Definition at line 1231 of file kdockwidget.cpp.

References KDockWidgetPrivate::forcedWidth.

int KDockWidget::forcedFixedHeight  )  [slot]
 

Since:
3.1

Definition at line 1236 of file kdockwidget.cpp.

References KDockWidgetPrivate::forcedHeight.

void KDockWidget::dockBack  )  [slot]
 

Docks a dockwidget back to the dockwidget that was the neighbor widget before the current dock position.

Definition at line 1553 of file kdockwidget.cpp.

References formerBrotherDockWidget, formerDockPos, KDockWidgetPrivate::index, KDockManager::main, makeDockVisible(), manualDock(), and KDockWidgetPrivate::splitPosInPercent.

Referenced by KDockManager::eventFilter(), and makeDockVisible().

void KDockWidget::changeHideShowState  )  [slot]
 

Toggles the visibility state of the dockwidget if it is able to be shown or to be hidden.

Definition at line 1495 of file kdockwidget.cpp.

References KDockManager::main, makeDockVisible(), mayBeHide(), mayBeShow(), and undock().

void KDockWidget::undock  )  [slot]
 

Undocks this.

It means it becomes a toplevel widget framed by the system window manager. A small panel at the top of this undocked widget gives the possibility to drag it into another dockwidget by mouse (docking).

Definition at line 1268 of file kdockwidget.cpp.

References KDockSplitter::activate(), applyToWidget(), KDockWidgetPrivate::blockHasUndockedSignal, KDockManager::change(), KDockWidgetPrivate::container, currentDockPos, KDockManager::d, KDockSplitter::deactivate(), KDockManager::drawDragRectangle(), formerDockPos, KDockSplitter::getAnother(), KDockSplitter::getFirst(), hasUndocked(), iMBeingClosed(), KDockWidgetPrivate::index, parentDockTabGroup(), KDockWidgetPrivate::pendingDtor, KDockManager::replaceDock(), KDockSplitter::separatorPos(), setFormerBrotherDockWidget(), show(), KDockWidgetPrivate::splitPosInPercent, and KDockManager::undockProcess.

Referenced by changeHideShowState(), KDockMainWindow::makeDockInvisible(), manualDock(), KDockManager::readConfig(), and ~KDockWidget().

void KDockWidget::toDesktop  )  [slot]
 

Docks the widget to the desktop (as a toplevel widget)

Since:
3.1.

Definition at line 1253 of file kdockwidget.cpp.

References manualDock().

Referenced by KDockManager::eventFilter().

void KDockWidget::updateHeader  )  [protected]
 

Checks some conditions and shows or hides the dockwidget header (drag panel).

The header is hidden if:

  • the parent widget is the KDockMainWindow
  • this is a (tab) group dockwidget
  • it is not able to dock to another dockwidget

Definition at line 769 of file kdockwidget.cpp.

References KDockManager::main, and KDockWidgetAbstractHeader::setTopLevel().

Referenced by KDockManager::readConfig(), setEnableDocking(), and setWidget().

void KDockWidget::setLatestKDockContainer QWidget  )  [protected]
 

Since:
3.1

Definition at line 717 of file kdockwidget.cpp.

References KDockWidgetPrivate::container.

Referenced by manualDock().

QWidget * KDockWidget::latestKDockContainer  )  [protected]
 

Since:
3.1

Definition at line 728 of file kdockwidget.cpp.

References KDockWidgetPrivate::container.

Referenced by manualDock(), and ~KDockWidget().

void KDockWidget::setFormerBrotherDockWidget KDockWidget  )  [protected]
 

Since:
3.2

Definition at line 1536 of file kdockwidget.cpp.

References formerBrotherDockWidget, iMBeingClosed(), and loseFormerBrotherDockWidget().

Referenced by manualDock(), KDockManager::readConfig(), and undock().

void KDockWidget::widgetSet QWidget  )  [signal]
 

Since:
3.2 is emitted after the setWidget method has finished

Referenced by setWidget().

void KDockWidget::docking KDockWidget dw,
KDockWidget::DockPosition  dp
[signal]
 

Emitted when another dock widget is docking to this.

Parameters:
dw the dockwidget that is docking to this
dp the DockPosition where it wants to dock to

Referenced by manualDock().

void KDockWidget::setDockDefaultPos  )  [signal]
 

Signals that the dock default position is set.

Referenced by show().

void KDockWidget::headerCloseButtonClicked  )  [signal]
 

Emitted when the close button of the panel ( KDockWidgetHeader) has been clicked.

void KDockWidget::headerDockbackButtonClicked  )  [signal]
 

Emitted when the dockback button of the panel ( KDockWidgetHeader) has been clicked.

void KDockWidget::iMBeingClosed  )  [signal]
 

Emitted when the widget processes a close event.

Referenced by event(), loseFormerBrotherDockWidget(), setFormerBrotherDockWidget(), undock(), and ~KDockWidget().

void KDockWidget::hasUndocked  )  [signal]
 

Emitted when the widget has undocked.

Referenced by undock().

void KDockWidget::loseFormerBrotherDockWidget  )  [protected, slot]
 

Does several things here when it has noticed that the former brother widget (closest neighbor) gets lost.

The former brother widget is needed for a possible dockback action, to speak with the Beatles: "To get back to where you once belonged" ;-)

Definition at line 1544 of file kdockwidget.cpp.

References formerBrotherDockWidget, and iMBeingClosed().

Referenced by manualDock(), and setFormerBrotherDockWidget().


Member Data Documentation

KDockWidget* KDockWidget::formerBrotherDockWidget [protected]
 

earlier closest neighbor widget, so it's possible to dock back to it.

Definition at line 793 of file kdockwidget.h.

Referenced by dockBack(), isDockBackPossible(), loseFormerBrotherDockWidget(), manualDock(), setFormerBrotherDockWidget(), and KDockManager::writeConfig().

DockPosition KDockWidget::currentDockPos [protected]
 

the current dock position.

Definition at line 797 of file kdockwidget.h.

Referenced by KDockManager::eventFilter(), manualDock(), and undock().

DockPosition KDockWidget::formerDockPos [protected]
 

the former dock position when it really was at another position before.

Definition at line 801 of file kdockwidget.h.

Referenced by dockBack(), manualDock(), KDockManager::readConfig(), undock(), and KDockManager::writeConfig().

QString KDockWidget::toolTipStr [protected]
 

a string used as tooltip for the tab page header when in dock-centered mode.

Definition at line 805 of file kdockwidget.h.

Referenced by manualDock().

QString KDockWidget::tabPageTitle [protected]
 

a string used as title of the tab page when in tab page mode

Definition at line 809 of file kdockwidget.h.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdeui Library Version 3.3.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat Nov 27 13:43:28 2004 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003