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 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 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 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 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 EXPORT_DOCKCLASS 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 EXPORT_DOCKCLASS 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 public slots:
00669   void setForcedFixedWidth(int);
00676   void setForcedFixedHeight(int);
00678   void restoreFromForcedFixedSize();
00679 
00681   int forcedFixedWidth();
00683   int forcedFixedHeight();
00684 
00689   void dockBack();
00690 
00694   void changeHideShowState();
00695 
00701   void undock();
00702 
00707   void toDesktop( );
00708 
00709 protected:
00710   friend class KMdiMainFrm;
00718   void updateHeader();
00719 
00721   void setLatestKDockContainer(QWidget *);
00723   QWidget *latestKDockContainer();
00724 
00725 signals:
00730    void widgetSet(QWidget*);
00731 
00738   void docking( KDockWidget* dw, KDockWidget::DockPosition dp);
00739 
00743   void setDockDefaultPos();
00744 
00748   void headerCloseButtonClicked();
00749 
00753   void headerDockbackButtonClicked();
00754 
00758   void iMBeingClosed();
00762   void hasUndocked();
00763 
00764 protected slots:
00765 
00770   void loseFormerBrotherDockWidget();
00771 
00772   virtual void paintEvent(QPaintEvent*);
00773 
00774   virtual void mousePressEvent(QMouseEvent*);
00775   virtual void mouseReleaseEvent(QMouseEvent*);
00776   virtual void mouseMoveEvent(QMouseEvent*);
00777   virtual void leaveEvent(QEvent*);
00778 protected:
00779   friend class KDockWidgetHeader;
00783   KDockWidget* formerBrotherDockWidget;
00787   DockPosition currentDockPos;
00791   DockPosition formerDockPos;
00795   QString toolTipStr;
00799   QString tabPageTitle;
00800 
00801 private:
00807   void setDockTabName( KDockTabGroup* g);
00808 
00816   void applyToWidget( QWidget* s, const QPoint& p  = QPoint(0,0) );
00817 
00821   KDockWidgetAbstractHeader* header;
00822 
00826   QWidget* widget;
00827 
00831   QVBoxLayout* layout;
00832 
00836   KDockManager* manager;
00837 
00841   QPixmap* pix;
00842 
00846   int eDocking;
00847 
00851   int sDocking;
00852 
00856   KDockWidget::DockPosition prevSideDockPosBeforeDrag;
00857 
00858   // GROUP data
00859   QString firstName;
00860   QString lastName;
00861   Orientation splitterOrientation;
00862   bool isGroup;
00863   bool isTabGroup;
00864 protected:
00865   virtual void virtual_hook( int id, void* data );
00866 private:
00867   KDockWidgetPrivate *d;
00868 };
00869 
00882 class EXPORT_DOCKCLASS KDockManager: public QObject
00883 {
00884   Q_OBJECT
00885 friend class KDockWidget;
00886 friend class KDockMainWindow;
00887 
00888 public:
00889     enum EnReadDockConfigMode {
00890         Unknown,
00891         WrapExistingWidgetsOnly,
00892         RestoreAllDockwidgets
00893     };
00894 
00895 public:
00906   KDockManager( QWidget* mainWindow, const char* name = 0L );
00907 
00911   virtual ~KDockManager();
00912 
00913   void dumpDockWidgets();
00914 
00915 #ifndef NO_KDE2
00916 
00925   void writeConfig( KConfig* c = 0L, QString group = QString::null );
00926 
00943   void readConfig ( KConfig* c = 0L, QString group = QString::null );
00944 #endif
00945 
00947   void setMainDockWidget2(KDockWidget *);
00948 
00952   void writeConfig(QDomElement &base);
00956   void readConfig(QDomElement &base);
00957 
00962   void activate();
00963 
00972   virtual bool eventFilter( QObject * object, QEvent * event );
00973 
00981   KDockWidget* findWidgetParentDock( QWidget* w) const;
00982 
00988   void makeWidgetDockVisible( QWidget* w ){ findWidgetParentDock(w)->makeDockVisible(); }
00989 
00993   QPopupMenu* dockHideShowMenu() const { return menu; }
00994 
00999   KDockWidget* getDockWidgetFromName( const QString& dockName );
01000 
01005   void setSplitterOpaqueResize(bool b=true);
01006 
01010   bool splitterOpaqueResize() const;
01011 
01017   void setSplitterKeepSize(bool b=true);
01018 
01022   bool splitterKeepSize() const;
01023 
01030   void setSplitterHighResolution(bool b=true);
01031 
01035   bool splitterHighResolution() const;
01036 
01040   void setSpecialLeftDockContainer(KDockWidget* container);  
01041   void setSpecialTopDockContainer(KDockWidget* container);  
01042   void setSpecialRightDockContainer(KDockWidget* container);  
01043   void setSpecialBottomDockContainer(KDockWidget* container);  
01044 
01045   void removeFromAutoCreateList(KDockWidget* pDockWidget);
01046   void finishReadDockConfig();
01047   void setReadDockConfigMode(int mode);
01048 
01049 signals:
01050 
01054   void change();
01055 
01059   void replaceDock( KDockWidget* oldDock, KDockWidget* newDock );
01060 
01064   void setDockDefaultPos( KDockWidget* );
01065 
01066 private slots:
01067 
01071   void slotMenuPopup();
01072 
01078   void slotMenuActivated( int id);
01079 
01080   /* clears the old drawn drag rectangle (oldDragRect) from screen and
01081    * draws the new current drag rectangle (dragRect) depending on the current mouse position.
01082    * This highlights the dockwidget which is the currently chosen target during a dock action.
01083    */
01084   void drawDragRectangle();
01085 
01086 private:
01087 
01091   struct MenuDockData
01092   {
01093     MenuDockData( KDockWidget* _dock, bool _hide )
01094     {
01095       dock = _dock;
01096       hide = _hide;
01097     };
01098     ~MenuDockData(){};
01099 
01100     KDockWidget* dock;
01101     bool hide;
01102   };
01103 
01110   KDockWidget* findDockWidgetAt( const QPoint& pos );
01111 
01119   void findChildDockWidget( QWidget*& w, const QWidget* p, const QPoint& pos );
01120 
01127   void findChildDockWidget( const QWidget* p, QWidgetList*& l);
01128 
01132   void startDrag( KDockWidget* );
01133 
01140   void dragMove( KDockWidget* d, QPoint pos );
01141 
01145   void cancelDrop();
01146 
01151   void drop();
01152 
01153 // class members
01154 
01158   QWidget* main;
01159 
01163   KDockWidget* currentDragWidget;
01164 
01168   KDockWidget* currentMoveWidget; // widget where mouse moving
01169 
01173   QWidgetList* childDockWidgetList;
01174 
01178   KDockWidget::DockPosition curPos;
01179 
01184   QObjectList* childDock;
01185 
01189   QObjectList* autoCreateDock;
01190 
01194   int storeW;
01195 
01199   int storeH;
01200 
01204   bool dragging;
01205 
01209   bool undockProcess;
01210 
01215   bool dropCancel;
01216 
01221   QPopupMenu* menu;
01222 
01226   QPtrList<MenuDockData> *menuData;
01227 
01228 protected:
01229   virtual void virtual_hook( int id, void* data );
01230 private:
01231   class KDockManagerPrivate;
01232   KDockManagerPrivate *d;
01233 };
01234 
01278 class EXPORT_DOCKCLASS KDockMainWindow : public KMainWindow
01279 {
01280   Q_OBJECT
01281 
01282 friend class KDockManager;
01283 
01284 public:
01285 
01298   KDockMainWindow( QWidget* parent = 0L, const char *name = 0L, WFlags f = WType_TopLevel | WDestructiveClose );
01299 
01303   virtual ~KDockMainWindow();
01304 
01309   KDockManager* manager() const { return dockManager; }
01310 
01317   void setMainDockWidget( KDockWidget* dockwidget);
01318 
01324   KDockWidget* getMainDockWidget() const { return mainDockWidget; }
01325 
01338   KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L,
01339     const QString& strCaption = QString::null, const QString& strTabPageLabel = QString::fromLatin1( " " ) );
01340 
01344   void writeDockConfig(QDomElement &base);
01348   void readDockConfig(QDomElement &base);
01349 
01350 #ifndef NO_KDE2
01351 
01357   void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
01358 
01365   void readDockConfig ( KConfig* c = 0L, QString group = QString::null );
01366 #endif
01367 
01373   void activateDock(){ dockManager->activate(); }
01374 
01381   QPopupMenu* dockHideShowMenu() const { return dockManager->dockHideShowMenu(); }
01382 
01390   void makeDockVisible( KDockWidget* dock );
01391 
01397   void makeDockInvisible( KDockWidget* dock );
01398 
01403   void makeWidgetDockVisible( QWidget* widget );
01404 
01411   void setView( QWidget * widget );
01412 
01413 signals:
01417   void dockWidgetHasUndocked(KDockWidget*);
01418 
01419 protected:
01420 
01424   KDockWidget* mainDockWidget;
01425 
01429   KDockManager* dockManager;
01430 
01431 protected slots:
01435   void slotDockWidgetUndocked();
01436 
01437 protected:
01438   virtual void virtual_hook( int id, void* data );
01439 private:
01440   class KDockMainWindowPrivate;
01441   KDockMainWindowPrivate *d;
01442 };
01443 
01444 
01445 
01446 
01447 
01448 
01449 
01450 
01451 
01452 
01453 
01454 
01455 
01456 
01457 
01458 
01459 class EXPORT_DOCKCLASS KDockArea : public QWidget
01460 {
01461   Q_OBJECT
01462 
01463 friend class KDockManager;
01464 
01465 public:
01466 
01467 
01468   KDockArea( QWidget* parent = 0L, const char *name = 0L);
01469 
01470   virtual ~KDockArea();
01471 
01472   KDockManager* manager(){ return dockManager; }
01473 
01474 
01475   void setMainDockWidget( KDockWidget* );
01476   KDockWidget* getMainDockWidget(){ return mainDockWidget; }
01477 
01478   KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L,
01479     const QString& strCaption = QString::null, const QString& strTabPageLabel = QString::fromLatin1( " " ) );
01480 
01481   void writeDockConfig(QDomElement &base);
01482   void readDockConfig(QDomElement &base);
01483 
01484 #ifndef NO_KDE2
01485   void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
01486   void readDockConfig ( KConfig* c = 0L, QString group = QString::null );
01487 #endif
01488 
01489 
01490 
01491   void activateDock(){ dockManager->activate(); }
01492   QPopupMenu* dockHideShowMenu(){ return dockManager->dockHideShowMenu(); }
01493   void makeDockVisible( KDockWidget* dock );
01494   void makeDockInvisible( KDockWidget* dock );
01495   void makeWidgetDockVisible( QWidget* widget );
01496   //void setView( QWidget* );
01497 
01498 signals:
01502   void dockWidgetHasUndocked(KDockWidget*);
01503 
01504 protected:
01505 
01506   KDockWidget* mainDockWidget;
01507   KDockManager* dockManager;
01508 
01509 protected slots:
01510   void slotDockWidgetUndocked();
01511 
01512 public:
01513     virtual void resizeEvent(QResizeEvent *);
01514 
01515 protected:
01516   virtual void virtual_hook( int id, void* data );
01517 private:
01518   class KDockMainWindowPrivate;
01519   KDockMainWindowPrivate *d;
01520 };
01521 
01522 
01523 #endif
01524 
01525 
KDE Logo
This file is part of the documentation for kdeui Library Version 3.2.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Feb 4 12:34:16 2004 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2003