kdeui Library API Documentation

kdockwidget.h

00001 /* This file is part of the KDE libraries
00002    Copyright (C) 2000 Max Judin <novaprint@mtu-net.ru>
00003    Copyright (C) 2000 Falk Brettschneider <falk@kdevelop.org>
00004    Copyright (C) 2002,2003 Joseph Wenninger <jowenn@kde.org>
00005 
00006    This library is free software; you can redistribute it and/or
00007    modify it under the terms of the GNU Library General Public
00008    License version 2 as published by the Free Software Foundation.
00009 
00010    This library is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY; without even the implied warranty of
00012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013    Library General Public License for more details.
00014 
00015    You should have received a copy of the GNU Library General Public License
00016    along with this library; see the file COPYING.LIB.  If not, write to
00017    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018    Boston, MA 02111-1307, USA.
00019 */
00020 
00021 /*
00022    activities:
00023    -----------
00024    05/2001 -               : useful patches, bugfixes by Christoph Cullmann <crossfire@babylon2k.de>,
00025                              Joseph Wenninger <jowenn@bigfoot.com> and  Falk Brettschneider
00026    03/2001 - 05/2001       : maintained and enhanced by Falk Brettschneider <falk@kdevelop.org>
00027    03/2000                 : class documentation added by Falk Brettschneider <gigafalk@yahoo.com>
00028    10/1999 - 03/2000       : programmed by Max Judin <novaprint@mtu-net.ru>
00029 
00030    C++ classes in this file:
00031    -------------------------
00032    - KDockWidgetAbstractHeader     - minor helper class
00033    - KDockWidgetAbstractHeaderDrag - minor helper class
00034    - KDockWidgetHeaderDrag         - drag panel in a dockwidget title bar
00035    - KDockWidgetHeader             - dockwidget title bar containing the drag panel
00036    - KDockTabGroup                 - minor helper class
00037    - KDockWidget                   - IMPORTANT CLASS: the one and only dockwidget class
00038    - KDockManager                  - helper class
00039    - KDockMainWindow               - IMPORTANT CLASS: a special KMainWindow that can have dockwidgets
00040    - KDockArea                     - like KDockMainWindow but inherits just QWidget
00041 
00042    IMPORTANT Note: This file compiles also in Qt-only mode by using the NO_KDE2 precompiler definition!
00043 */
00044 
00045 
00046 #ifndef KDOCKWIDGET_H
00047 #define KDOCKWIDGET_H
00048 
00049 #define _KDOCKWIDGET_2_2_
00050 
00051 #include <qpoint.h>
00052 #include <qptrlist.h>
00053 #include <qframe.h>
00054 #include <qdom.h>
00055 #include <qtabwidget.h>
00056 
00057 #ifndef NO_KDE2
00058 #include <kmainwindow.h>
00059 #include <netwm_def.h>
00060 #undef  EXPORT_DOCKCLASS
00061 #define EXPORT_DOCKCLASS
00062 #else
00063 #include <qmainwindow.h>
00064 #include "exportdockclass.h"
00065 #include "dummykmainwindow.h"
00066 #endif
00067 
00068 class KDockSplitter;
00069 class KDockManager;
00070 class KDockMoveManager;
00071 class KDockWidget;
00072 class KDockButton_Private;
00073 class KDockWidgetPrivate;
00074 class KDockWidgetHeaderPrivate;
00075 class KDockArea;
00076 
00077 class QObjectList;
00078 class QPopupMenu;
00079 class QVBoxLayout;
00080 class QHBoxLayout;
00081 class QPixmap;
00082 
00083 #ifndef NO_KDE2
00084 class KToolBar;
00085 class KConfig;
00086 #else
00087 class QToolBar;
00088 #endif
00089 
00090 class KDockContainer;
00091 
00099 class KDEUI_EXPORT KDockWidgetAbstractHeader : public QFrame
00100 {
00101   Q_OBJECT
00102 public:
00103 
00110   KDockWidgetAbstractHeader( KDockWidget* parent, const char* name = 0L );
00111 
00115   virtual ~KDockWidgetAbstractHeader(){};
00116 
00120   virtual void setTopLevel( bool ){};
00121 
00122 #ifndef NO_KDE2
00123 
00126   virtual void saveConfig( KConfig* ){};
00127 
00131   virtual void loadConfig( KConfig* ){};
00132 #endif
00133 
00134 protected:
00135   virtual void virtual_hook( int id, void* data );
00136 private:
00137   class KDockWidgetAbstractHeaderPrivate;
00138   KDockWidgetAbstractHeaderPrivate *d;
00139 };
00140 
00148 class KDEUI_EXPORT KDockWidgetAbstractHeaderDrag : public QFrame
00149 {
00150   Q_OBJECT
00151 public:
00152 
00160   KDockWidgetAbstractHeaderDrag( KDockWidgetAbstractHeader* parent,
00161                                  KDockWidget* dock, const char* name = 0L );
00162 
00166   virtual ~KDockWidgetAbstractHeaderDrag(){};
00167 
00171   KDockWidget* dockWidget() const { return dw; }
00172 
00173 private:
00177   KDockWidget* dw;
00178 protected:
00179   virtual void virtual_hook( int id, void* data );
00180 private:
00181   class KDockWidgetAbstractHeaderDragPrivate;
00182   KDockWidgetAbstractHeaderDragPrivate *d;
00183 };
00184 
00193 class KDEUI_EXPORT KDockWidgetHeaderDrag : public KDockWidgetAbstractHeaderDrag
00194 {
00195   Q_OBJECT
00196 public:
00197 
00205   KDockWidgetHeaderDrag( KDockWidgetAbstractHeader* parent, KDockWidget* dock,
00206                          const char* name = 0L );
00207 
00211   virtual ~KDockWidgetHeaderDrag(){};
00212 
00213 protected:
00214 
00218   virtual void paintEvent( QPaintEvent* );
00219 
00220 protected:
00221   virtual void virtual_hook( int id, void* data );
00222 private:
00223   class KDockWidgetHeaderDragPrivate;
00224   KDockWidgetHeaderDragPrivate *d;
00225 };
00226 
00234 class KDEUI_EXPORT KDockWidgetHeader : public KDockWidgetAbstractHeader
00235 {
00236   Q_OBJECT
00237 public:
00238 
00245   KDockWidgetHeader( KDockWidget* parent, const char* name = 0L );
00246 
00250   virtual ~KDockWidgetHeader(){};
00251 
00257   virtual void setTopLevel( bool t);
00258 
00264   void setDragPanel( KDockWidgetHeaderDrag* nd );
00265 
00266   bool dragEnabled() const;
00267   void setDragEnabled(bool b);
00269   void showUndockButton(bool show);
00270 
00272   void forceCloseButtonHidden(bool enable=true);
00273 #ifndef NO_KDE2
00274 
00279   virtual void saveConfig( KConfig* c);
00280 
00286   virtual void loadConfig( KConfig* c);
00287 #endif
00288 
00289    /*@since 3.2
00290     * add an arbitrary button to the dockwidget header
00291     * NOT PART OF THE PUBLIC API (you don't have access the class defintion anyways, without special
00292     * header file copying. (don't do it))
00293     */
00294     void addButton(KDockButton_Private*);
00295 
00296    /*@since 3.2
00297     * remove an arbtrary button from the dockwidget header
00298     * NOT PART OF THE PUBLIC API (you don't have access the class defintion anyways, without special
00299     * header file copying. (don't do it))
00300     */
00301     void removeButton(KDockButton_Private*);
00302 
00303 
00304 
00305 protected slots:
00309   void slotStayClicked();
00310 
00311 protected:
00312 
00316   QHBoxLayout* layout;
00317 
00321   KDockButton_Private* closeButton;
00322 
00326   KDockButton_Private* stayButton;
00327 
00331   KDockButton_Private* dockbackButton;
00332 
00336   KDockWidgetHeaderDrag* drag;
00337 
00338 protected:
00339   virtual void virtual_hook( int id, void* data );
00340 private:
00341   KDockWidgetHeaderPrivate *d;
00342 };
00343 
00352 class KDEUI_EXPORT KDockTabGroup : public QTabWidget
00353 {
00354   Q_OBJECT
00355 public:
00359   KDockTabGroup( QWidget *parent = 0, const char *name = 0 )
00360   :QTabWidget( parent, name ){};
00361 
00365   virtual ~KDockTabGroup(){};
00366 
00367   QWidget *transientTo();
00368 protected:
00369   virtual void virtual_hook( int id, void* data );
00370 private:
00371   class KDockTabGroupPrivate;
00372   KDockTabGroupPrivate *d;
00373 };
00374 
00375 
00412 class KDEUI_EXPORT KDockWidget: public QWidget
00413 {
00414   Q_OBJECT
00415 friend class KDockManager;
00416 friend class KDockSplitter;
00417 friend class KDockMainWindow;
00418 friend class KDockArea;
00419 
00420 public:
00436   KDockWidget( KDockManager* dockManager, const char* name,
00437                const QPixmap &pixmap, QWidget* parent = 0L, const QString& strCaption = QString::null,
00438                const QString& strTabPageLabel = QString::fromLatin1( " " ), WFlags f = 0);
00439 
00443   virtual ~KDockWidget();
00444 
00448   enum DockPosition
00449   {
00450     DockNone   = 0,
00451     DockTop    = 0x0001,
00452     DockLeft   = 0x0002,
00453     DockRight  = 0x0004,
00454     DockBottom = 0x0008,
00455     DockCenter = 0x0010,
00456     DockDesktop= 0x0020,
00457     DockToSpecialSites=0x0040, 
00458     DockCorner = DockTop | DockLeft | DockRight | DockBottom,
00459     DockFullSite = DockCorner | DockCenter,
00460     DockFullDocking = DockFullSite | DockDesktop
00461   };
00462 
00482   KDockWidget* manualDock( KDockWidget* target, DockPosition dockPos, int spliPos = 50, QPoint pos = QPoint(0,0), bool check = false, int tabIndex = -1);
00483 
00489   void setEnableDocking( int pos );
00490 
00494   int enableDocking() const { return eDocking; }
00495 
00501   void setDockSite( int pos ){ sDocking = pos;}
00502 
00506   int dockSite() const { return sDocking; }
00507 
00515   void setWidget( QWidget* w);
00516 
00522   QWidget* getWidget() const { return widget; };
00523 
00532   void setHeader( KDockWidgetAbstractHeader* ah);
00533 
00537   KDockWidgetAbstractHeader *getHeader();
00538 
00544   void makeDockVisible();
00545 
00555   bool mayBeHide() const;
00556 
00564   bool mayBeShow() const;
00565 
00569   KDockManager* dockManager() const { return manager; }
00570 
00581   void setToolTipString(const QString& ttStr) { toolTipStr = ttStr; };
00582 
00586   const QString& toolTipString() const { return toolTipStr; };
00587 
00591   bool isDockBackPossible() const;
00592 
00597   void setTabPageLabel( const QString& label) { tabPageTitle = label; };
00598 
00602   const QString& tabPageLabel() const { return tabPageTitle; };
00603 
00607   virtual bool event( QEvent * );
00608 
00612   virtual void show();
00616   KDockTabGroup* parentDockTabGroup() const;
00617 
00619   QWidget *parentDockContainer() const;
00620 
00621 #ifndef NO_KDE2
00622 
00628   void setDockWindowType (NET::WindowType windowType);
00629 
00630 #endif
00631 
00632   void setDockWindowTransient (QWidget *parent, bool transientEnabled);
00633 
00638    QWidget *transientTo();
00639 
00646   KDockWidget *findNearestDockWidget(DockPosition pos);
00647 
00654    void setPixmap(const QPixmap& pixmap=QPixmap());
00655 
00661    const QPixmap& pixmap() const;
00662 
00667   KDockWidget::DockPosition currentDockPosition() const;
00668 
00669 public slots:
00676   void setForcedFixedWidth(int);
00683   void setForcedFixedHeight(int);
00685   void restoreFromForcedFixedSize();
00686 
00688   int forcedFixedWidth();
00690   int forcedFixedHeight();
00691 
00696   void dockBack();
00697 
00701   void changeHideShowState();
00702 
00708   void undock();
00709 
00714   void toDesktop( );
00715 
00716 protected:
00717   friend class KMdiMainFrm;
00725   void updateHeader();
00726 
00728   void setLatestKDockContainer(QWidget *);
00730   QWidget *latestKDockContainer();
00731 
00733   void setFormerBrotherDockWidget(KDockWidget *);
00734 
00735 signals:
00740    void widgetSet(QWidget*);
00741 
00748   void docking( KDockWidget* dw, KDockWidget::DockPosition dp);
00749 
00753   void setDockDefaultPos();
00754 
00758   void headerCloseButtonClicked();
00759 
00763   void headerDockbackButtonClicked();
00764 
00768   void iMBeingClosed();
00772   void hasUndocked();
00773 
00774 protected slots:
00775 
00780   void loseFormerBrotherDockWidget();
00781 
00782   virtual void paintEvent(QPaintEvent*);
00783 
00784   virtual void mousePressEvent(QMouseEvent*);
00785   virtual void mouseReleaseEvent(QMouseEvent*);
00786   virtual void mouseMoveEvent(QMouseEvent*);
00787   virtual void leaveEvent(QEvent*);
00788 protected:
00789   friend class KDockWidgetHeader;
00793   KDockWidget* formerBrotherDockWidget;
00797   DockPosition currentDockPos;
00801   DockPosition formerDockPos;
00805   QString toolTipStr;
00809   QString tabPageTitle;
00810 
00811 private:
00817   void setDockTabName( KDockTabGroup* g);
00818 
00826   void applyToWidget( QWidget* s, const QPoint& p  = QPoint(0,0) );
00827 
00831   KDockWidgetAbstractHeader* header;
00832 
00836   QWidget* widget;
00837 
00841   QVBoxLayout* layout;
00842 
00846   KDockManager* manager;
00847 
00851   QPixmap* pix;
00852 
00856   int eDocking;
00857 
00861   int sDocking;
00862 
00866   KDockWidget::DockPosition prevSideDockPosBeforeDrag;
00867 
00868   // GROUP data
00869   QString firstName;
00870   QString lastName;
00871   Orientation splitterOrientation;
00872   bool isGroup;
00873   bool isTabGroup;
00874 protected:
00875   virtual void virtual_hook( int id, void* data );
00876 private:
00877   KDockWidgetPrivate *d;
00878 };
00879 
00892 class KDEUI_EXPORT KDockManager: public QObject
00893 {
00894   Q_OBJECT
00895 friend class KDockWidget;
00896 friend class KDockMainWindow;
00897 
00898 public:
00899     enum EnReadDockConfigMode {
00900         Unknown,
00901         WrapExistingWidgetsOnly,
00902         RestoreAllDockwidgets
00903     };
00904 
00905 public:
00916   KDockManager( QWidget* mainWindow, const char* name = 0L );
00917 
00921   virtual ~KDockManager();
00922 
00923   void dumpDockWidgets();
00924 
00925 #ifndef NO_KDE2
00926 
00935   void writeConfig( KConfig* c = 0L, QString group = QString::null );
00936 
00953   void readConfig ( KConfig* c = 0L, QString group = QString::null );
00954 #endif
00955 
00957   void setMainDockWidget2(KDockWidget *);
00958 
00962   void writeConfig(QDomElement &base);
00966   void readConfig(QDomElement &base);
00967 
00972   void activate();
00973 
00982   virtual bool eventFilter( QObject * object, QEvent * event );
00983 
00991   KDockWidget* findWidgetParentDock( QWidget* w) const;
00992 
00998   void makeWidgetDockVisible( QWidget* w ){ findWidgetParentDock(w)->makeDockVisible(); }
00999 
01003   QPopupMenu* dockHideShowMenu() const { return menu; }
01004 
01009   KDockWidget* getDockWidgetFromName( const QString& dockName );
01010 
01015   void setSplitterOpaqueResize(bool b=true);
01016 
01020   bool splitterOpaqueResize() const;
01021 
01027   void setSplitterKeepSize(bool b=true);
01028 
01032   bool splitterKeepSize() const;
01033 
01040   void setSplitterHighResolution(bool b=true);
01041 
01045   bool splitterHighResolution() const;
01046 
01050   void setSpecialLeftDockContainer(KDockWidget* container);  
01051   void setSpecialTopDockContainer(KDockWidget* container);  
01052   void setSpecialRightDockContainer(KDockWidget* container);  
01053   void setSpecialBottomDockContainer(KDockWidget* container);  
01054 
01055   void removeFromAutoCreateList(KDockWidget* pDockWidget);
01056   void finishReadDockConfig();
01057   void setReadDockConfigMode(int mode);
01058 
01059 signals:
01060 
01064   void change();
01065 
01069   void replaceDock( KDockWidget* oldDock, KDockWidget* newDock );
01070 
01074   void setDockDefaultPos( KDockWidget* );
01075 
01076 private slots:
01077 
01081   void slotMenuPopup();
01082 
01088   void slotMenuActivated( int id);
01089 
01090   /* clears the old drawn drag rectangle (oldDragRect) from screen and
01091    * draws the new current drag rectangle (dragRect) depending on the current mouse position.
01092    * This highlights the dockwidget which is the currently chosen target during a dock action.
01093    */
01094   void drawDragRectangle();
01095 
01096 private:
01097 
01101   struct MenuDockData
01102   {
01103     MenuDockData( KDockWidget* _dock, bool _hide )
01104     {
01105       dock = _dock;
01106       hide = _hide;
01107     };
01108     ~MenuDockData(){};
01109 
01110     KDockWidget* dock;
01111     bool hide;
01112   };
01113 
01120   KDockWidget* findDockWidgetAt( const QPoint& pos );
01121 
01129   void findChildDockWidget( QWidget*& w, const QWidget* p, const QPoint& pos );
01130 
01137   void findChildDockWidget( const QWidget* p, QWidgetList*& l);
01138 
01142   void startDrag( KDockWidget* );
01143 
01150   void dragMove( KDockWidget* d, QPoint pos );
01151 
01155   void cancelDrop();
01156 
01161   void drop();
01162 
01163 // class members
01164 
01168   QWidget* main;
01169 
01173   KDockWidget* currentDragWidget;
01174 
01178   KDockWidget* currentMoveWidget; // widget where mouse moving
01179 
01183   QWidgetList* childDockWidgetList;
01184 
01188   KDockWidget::DockPosition curPos;
01189 
01194   QObjectList* childDock;
01195 
01199   QObjectList* autoCreateDock;
01200 
01204   int storeW;
01205 
01209   int storeH;
01210 
01214   bool dragging;
01215 
01219   bool undockProcess;
01220 
01225   bool dropCancel;
01226 
01231   QPopupMenu* menu;
01232 
01236   QPtrList<MenuDockData> *menuData;
01237 
01238 protected:
01239   virtual void virtual_hook( int id, void* data );
01240 private:
01241   class KDockManagerPrivate;
01242   KDockManagerPrivate *d;
01243 };
01244 
01288 class KDEUI_EXPORT KDockMainWindow : public KMainWindow
01289 {
01290   Q_OBJECT
01291 
01292 friend class KDockManager;
01293 
01294 public:
01295 
01308   KDockMainWindow( QWidget* parent = 0L, const char *name = 0L, WFlags f = WType_TopLevel | WDestructiveClose );
01309 
01313   virtual ~KDockMainWindow();
01314 
01319   KDockManager* manager() const { return dockManager; }
01320 
01327   void setMainDockWidget( KDockWidget* dockwidget);
01328 
01334   KDockWidget* getMainDockWidget() const { return mainDockWidget; }
01335 
01348   KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L,
01349     const QString& strCaption = QString::null, const QString& strTabPageLabel = QString::fromLatin1( " " ) );
01350 
01354   void writeDockConfig(QDomElement &base);
01358   void readDockConfig(QDomElement &base);
01359 
01360 #ifndef NO_KDE2
01361 
01367   void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
01368 
01375   void readDockConfig ( KConfig* c = 0L, QString group = QString::null );
01376 #endif
01377 
01383   void activateDock(){ dockManager->activate(); }
01384 
01391   QPopupMenu* dockHideShowMenu() const { return dockManager->dockHideShowMenu(); }
01392 
01400   void makeDockVisible( KDockWidget* dock );
01401 
01407   void makeDockInvisible( KDockWidget* dock );
01408 
01413   void makeWidgetDockVisible( QWidget* widget );
01414 
01421   void setView( QWidget * widget );
01422 
01423 signals:
01427   void dockWidgetHasUndocked(KDockWidget*);
01428 
01429 protected:
01430 
01434   KDockWidget* mainDockWidget;
01435 
01439   KDockManager* dockManager;
01440 
01441 protected slots:
01445   void slotDockWidgetUndocked();
01446 
01447 protected:
01448   virtual void virtual_hook( int id, void* data );
01449 private:
01450   class KDockMainWindowPrivate;
01451   KDockMainWindowPrivate *d;
01452 };
01453 
01454 
01455 
01456 
01457 
01458 
01459 
01460 
01461 
01462 
01463 
01464 
01465 
01466 
01467 
01468 
01469 class KDEUI_EXPORT KDockArea : public QWidget
01470 {
01471   Q_OBJECT
01472 
01473 friend class KDockManager;
01474 
01475 public:
01476 
01477 
01478   KDockArea( QWidget* parent = 0L, const char *name = 0L);
01479 
01480   virtual ~KDockArea();
01481 
01482   KDockManager* manager(){ return dockManager; }
01483 
01484 
01485   void setMainDockWidget( KDockWidget* );
01486   KDockWidget* getMainDockWidget(){ return mainDockWidget; }
01487 
01488   KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L,
01489     const QString& strCaption = QString::null, const QString& strTabPageLabel = QString::fromLatin1( " " ) );
01490 
01491   void writeDockConfig(QDomElement &base);
01492   void readDockConfig(QDomElement &base);
01493 
01494 #ifndef NO_KDE2
01495   void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
01496   void readDockConfig ( KConfig* c = 0L, QString group = QString::null );
01497 #endif
01498 
01499 
01500 
01501   void activateDock(){ dockManager->activate(); }
01502   QPopupMenu* dockHideShowMenu(){ return dockManager->dockHideShowMenu(); }
01503   void makeDockVisible( KDockWidget* dock );
01504   void makeDockInvisible( KDockWidget* dock );
01505   void makeWidgetDockVisible( QWidget* widget );
01506   //void setView( QWidget* );
01507 
01508 signals:
01512   void dockWidgetHasUndocked(KDockWidget*);
01513 
01514 protected:
01515 
01516   KDockWidget* mainDockWidget;
01517   KDockManager* dockManager;
01518 
01519 protected slots:
01520   void slotDockWidgetUndocked();
01521 
01522 public:
01523     virtual void resizeEvent(QResizeEvent *);
01524 
01525 protected:
01526   virtual void virtual_hook( int id, void* data );
01527 private:
01528   class KDockMainWindowPrivate;
01529   KDockMainWindowPrivate *d;
01530 };
01531 
01532 
01533 #endif
01534 
01535 
KDE Logo
This file is part of the documentation for kdeui Library Version 3.3.90.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Mar 30 10:12:00 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003