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 
00726   void setFormerBrotherDockWidget(KDockWidget *);
00727 
00728 signals:
00733    void widgetSet(QWidget*);
00734 
00741   void docking( KDockWidget* dw, KDockWidget::DockPosition dp);
00742 
00746   void setDockDefaultPos();
00747 
00751   void headerCloseButtonClicked();
00752 
00756   void headerDockbackButtonClicked();
00757 
00761   void iMBeingClosed();
00765   void hasUndocked();
00766 
00767 protected slots:
00768 
00773   void loseFormerBrotherDockWidget();
00774 
00775   virtual void paintEvent(QPaintEvent*);
00776 
00777   virtual void mousePressEvent(QMouseEvent*);
00778   virtual void mouseReleaseEvent(QMouseEvent*);
00779   virtual void mouseMoveEvent(QMouseEvent*);
00780   virtual void leaveEvent(QEvent*);
00781 protected:
00782   friend class KDockWidgetHeader;
00786   KDockWidget* formerBrotherDockWidget;
00790   DockPosition currentDockPos;
00794   DockPosition formerDockPos;
00798   QString toolTipStr;
00802   QString tabPageTitle;
00803 
00804 private:
00810   void setDockTabName( KDockTabGroup* g);
00811 
00819   void applyToWidget( QWidget* s, const QPoint& p  = QPoint(0,0) );
00820 
00824   KDockWidgetAbstractHeader* header;
00825 
00829   QWidget* widget;
00830 
00834   QVBoxLayout* layout;
00835 
00839   KDockManager* manager;
00840 
00844   QPixmap* pix;
00845 
00849   int eDocking;
00850 
00854   int sDocking;
00855 
00859   KDockWidget::DockPosition prevSideDockPosBeforeDrag;
00860 
00861   // GROUP data
00862   QString firstName;
00863   QString lastName;
00864   Orientation splitterOrientation;
00865   bool isGroup;
00866   bool isTabGroup;
00867 protected:
00868   virtual void virtual_hook( int id, void* data );
00869 private:
00870   KDockWidgetPrivate *d;
00871 };
00872 
00885 class EXPORT_DOCKCLASS KDockManager: public QObject
00886 {
00887   Q_OBJECT
00888 friend class KDockWidget;
00889 friend class KDockMainWindow;
00890 
00891 public:
00892     enum EnReadDockConfigMode {
00893         Unknown,
00894         WrapExistingWidgetsOnly,
00895         RestoreAllDockwidgets
00896     };
00897 
00898 public:
00909   KDockManager( QWidget* mainWindow, const char* name = 0L );
00910 
00914   virtual ~KDockManager();
00915 
00916   void dumpDockWidgets();
00917 
00918 #ifndef NO_KDE2
00919 
00928   void writeConfig( KConfig* c = 0L, QString group = QString::null );
00929 
00946   void readConfig ( KConfig* c = 0L, QString group = QString::null );
00947 #endif
00948 
00950   void setMainDockWidget2(KDockWidget *);
00951 
00955   void writeConfig(QDomElement &base);
00959   void readConfig(QDomElement &base);
00960 
00965   void activate();
00966 
00975   virtual bool eventFilter( QObject * object, QEvent * event );
00976 
00984   KDockWidget* findWidgetParentDock( QWidget* w) const;
00985 
00991   void makeWidgetDockVisible( QWidget* w ){ findWidgetParentDock(w)->makeDockVisible(); }
00992 
00996   QPopupMenu* dockHideShowMenu() const { return menu; }
00997 
01002   KDockWidget* getDockWidgetFromName( const QString& dockName );
01003 
01008   void setSplitterOpaqueResize(bool b=true);
01009 
01013   bool splitterOpaqueResize() const;
01014 
01020   void setSplitterKeepSize(bool b=true);
01021 
01025   bool splitterKeepSize() const;
01026 
01033   void setSplitterHighResolution(bool b=true);
01034 
01038   bool splitterHighResolution() const;
01039 
01043   void setSpecialLeftDockContainer(KDockWidget* container);  
01044   void setSpecialTopDockContainer(KDockWidget* container);  
01045   void setSpecialRightDockContainer(KDockWidget* container);  
01046   void setSpecialBottomDockContainer(KDockWidget* container);  
01047 
01048   void removeFromAutoCreateList(KDockWidget* pDockWidget);
01049   void finishReadDockConfig();
01050   void setReadDockConfigMode(int mode);
01051 
01052 signals:
01053 
01057   void change();
01058 
01062   void replaceDock( KDockWidget* oldDock, KDockWidget* newDock );
01063 
01067   void setDockDefaultPos( KDockWidget* );
01068 
01069 private slots:
01070 
01074   void slotMenuPopup();
01075 
01081   void slotMenuActivated( int id);
01082 
01083   /* clears the old drawn drag rectangle (oldDragRect) from screen and
01084    * draws the new current drag rectangle (dragRect) depending on the current mouse position.
01085    * This highlights the dockwidget which is the currently chosen target during a dock action.
01086    */
01087   void drawDragRectangle();
01088 
01089 private:
01090 
01094   struct MenuDockData
01095   {
01096     MenuDockData( KDockWidget* _dock, bool _hide )
01097     {
01098       dock = _dock;
01099       hide = _hide;
01100     };
01101     ~MenuDockData(){};
01102 
01103     KDockWidget* dock;
01104     bool hide;
01105   };
01106 
01113   KDockWidget* findDockWidgetAt( const QPoint& pos );
01114 
01122   void findChildDockWidget( QWidget*& w, const QWidget* p, const QPoint& pos );
01123 
01130   void findChildDockWidget( const QWidget* p, QWidgetList*& l);
01131 
01135   void startDrag( KDockWidget* );
01136 
01143   void dragMove( KDockWidget* d, QPoint pos );
01144 
01148   void cancelDrop();
01149 
01154   void drop();
01155 
01156 // class members
01157 
01161   QWidget* main;
01162 
01166   KDockWidget* currentDragWidget;
01167 
01171   KDockWidget* currentMoveWidget; // widget where mouse moving
01172 
01176   QWidgetList* childDockWidgetList;
01177 
01181   KDockWidget::DockPosition curPos;
01182 
01187   QObjectList* childDock;
01188 
01192   QObjectList* autoCreateDock;
01193 
01197   int storeW;
01198 
01202   int storeH;
01203 
01207   bool dragging;
01208 
01212   bool undockProcess;
01213 
01218   bool dropCancel;
01219 
01224   QPopupMenu* menu;
01225 
01229   QPtrList<MenuDockData> *menuData;
01230 
01231 protected:
01232   virtual void virtual_hook( int id, void* data );
01233 private:
01234   class KDockManagerPrivate;
01235   KDockManagerPrivate *d;
01236 };
01237 
01281 class EXPORT_DOCKCLASS KDockMainWindow : public KMainWindow
01282 {
01283   Q_OBJECT
01284 
01285 friend class KDockManager;
01286 
01287 public:
01288 
01301   KDockMainWindow( QWidget* parent = 0L, const char *name = 0L, WFlags f = WType_TopLevel | WDestructiveClose );
01302 
01306   virtual ~KDockMainWindow();
01307 
01312   KDockManager* manager() const { return dockManager; }
01313 
01320   void setMainDockWidget( KDockWidget* dockwidget);
01321 
01327   KDockWidget* getMainDockWidget() const { return mainDockWidget; }
01328 
01341   KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L,
01342     const QString& strCaption = QString::null, const QString& strTabPageLabel = QString::fromLatin1( " " ) );
01343 
01347   void writeDockConfig(QDomElement &base);
01351   void readDockConfig(QDomElement &base);
01352 
01353 #ifndef NO_KDE2
01354 
01360   void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
01361 
01368   void readDockConfig ( KConfig* c = 0L, QString group = QString::null );
01369 #endif
01370 
01376   void activateDock(){ dockManager->activate(); }
01377 
01384   QPopupMenu* dockHideShowMenu() const { return dockManager->dockHideShowMenu(); }
01385 
01393   void makeDockVisible( KDockWidget* dock );
01394 
01400   void makeDockInvisible( KDockWidget* dock );
01401 
01406   void makeWidgetDockVisible( QWidget* widget );
01407 
01414   void setView( QWidget * widget );
01415 
01416 signals:
01420   void dockWidgetHasUndocked(KDockWidget*);
01421 
01422 protected:
01423 
01427   KDockWidget* mainDockWidget;
01428 
01432   KDockManager* dockManager;
01433 
01434 protected slots:
01438   void slotDockWidgetUndocked();
01439 
01440 protected:
01441   virtual void virtual_hook( int id, void* data );
01442 private:
01443   class KDockMainWindowPrivate;
01444   KDockMainWindowPrivate *d;
01445 };
01446 
01447 
01448 
01449 
01450 
01451 
01452 
01453 
01454 
01455 
01456 
01457 
01458 
01459 
01460 
01461 
01462 class EXPORT_DOCKCLASS KDockArea : public QWidget
01463 {
01464   Q_OBJECT
01465 
01466 friend class KDockManager;
01467 
01468 public:
01469 
01470 
01471   KDockArea( QWidget* parent = 0L, const char *name = 0L);
01472 
01473   virtual ~KDockArea();
01474 
01475   KDockManager* manager(){ return dockManager; }
01476 
01477 
01478   void setMainDockWidget( KDockWidget* );
01479   KDockWidget* getMainDockWidget(){ return mainDockWidget; }
01480 
01481   KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L,
01482     const QString& strCaption = QString::null, const QString& strTabPageLabel = QString::fromLatin1( " " ) );
01483 
01484   void writeDockConfig(QDomElement &base);
01485   void readDockConfig(QDomElement &base);
01486 
01487 #ifndef NO_KDE2
01488   void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
01489   void readDockConfig ( KConfig* c = 0L, QString group = QString::null );
01490 #endif
01491 
01492 
01493 
01494   void activateDock(){ dockManager->activate(); }
01495   QPopupMenu* dockHideShowMenu(){ return dockManager->dockHideShowMenu(); }
01496   void makeDockVisible( KDockWidget* dock );
01497   void makeDockInvisible( KDockWidget* dock );
01498   void makeWidgetDockVisible( QWidget* widget );
01499   //void setView( QWidget* );
01500 
01501 signals:
01505   void dockWidgetHasUndocked(KDockWidget*);
01506 
01507 protected:
01508 
01509   KDockWidget* mainDockWidget;
01510   KDockManager* dockManager;
01511 
01512 protected slots:
01513   void slotDockWidgetUndocked();
01514 
01515 public:
01516     virtual void resizeEvent(QResizeEvent *);
01517 
01518 protected:
01519   virtual void virtual_hook( int id, void* data );
01520 private:
01521   class KDockMainWindowPrivate;
01522   KDockMainWindowPrivate *d;
01523 };
01524 
01525 
01526 #endif
01527 
01528 
KDE Logo
This file is part of the documentation for kdeui Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Apr 21 18:43:15 2004 by doxygen 1.3.6-20040222 written by Dimitri van Heesch, © 1997-2003