Source: kdockwidget.h


Annotated List
Files
Globals
Hierarchy
Index
/* This file is part of the KDE libraries
   Copyright (C) 2000 Max Judin <novaprint@mtu-net.ru>
   Copyright (C) 2000 Falk Brettschneider <gigafalk@yahoo.com>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307, USA.
*/

/*
   activities:
   -----------
   03/2000                 : class documentation added by Falk Brettschneider
   10/1999 - 03/2000       : programmed by Max Judin
*/

#ifndef KDOCKWIDGET_H
#define KDOCKWIDGET_H

#include <qpoint.h>
#include <qlist.h>
#include <qframe.h>
#include <ktmainwindow.h>

#include "kdocktabctl.h"

class KDockSplitter;
class KDockMoveManager;
class KDockWidget;
class KDockButton_Private;

class QObjectList;
class QPopupMenu;
class QVBoxLayout;
class QHBoxLayout;
class QPixmap;

class KToolBar;
class KConfig;

typedef QList<QWidget> WidgetList;

/**
 * An abstract base clase for all dockwidget headers. See the class description of KDockWidgetHeader!
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
 */
class KDockWidgetAbstractHeader : public QFrame
{
  Q_OBJECT
public:

  /** 
   * Constructs this.
   * 
   * @param parent the parent widget (usually a dockwidget)
   * @param name   the object instance name
   */
  KDockWidgetAbstractHeader( KDockWidget* parent, const char* name = 0L );
  
  /**
   * Destructs this.
   */
  virtual ~KDockWidgetAbstractHeader(){};
  
  /** Provides things concerning to switching to toplevel mode. Must be overridden by an inheriting class. */
  virtual void setTopLevel( bool ){};

  /** Provides saving the current configuration. Must be overridden by an inheriting class. */
  virtual void saveConfig( KConfig* ){};

  /** Provides loading the current configuration.  Must be overridden by an inheriting class */
  virtual void loadConfig( KConfig* ){};
};

/**
 * An abstract class for all dockwidget header drags. See the class description of KDockWidgetHeaderDrag!
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
 */
class KDockWidgetAbstractHeaderDrag : public QFrame
{
  Q_OBJECT
public:

  /** 
   * Constructs this.
   * 
   * @param parent the parent widget (usually a dockwidget header)
   * @param dock   the dockwidget where it belongs to
   * @param name   the object instance name
   */
  KDockWidgetAbstractHeaderDrag( KDockWidgetAbstractHeader* parent,
                                 KDockWidget* dock, const char* name = 0L );

  /**
   * Destructs this.
   */
  virtual ~KDockWidgetAbstractHeaderDrag(){};

  /** @return the dockwidget where this belongs to */
  KDockWidget* dockWidget(){ return d; }

private:
  /** the dockwidget where this belongs to */
  KDockWidget* d;
};

/**
 * This special widget is the panel one can grip with the mouse. The widget for dragging, so to speak.
 * Usually it is located in the KDockWidgetHeader. 
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
 */
class KDockWidgetHeaderDrag : public KDockWidgetAbstractHeaderDrag
{
  Q_OBJECT
public:

  /** 
   * Constructs this.
   * 
   * @param parent the parent widget (usually a dockwidget header)
   * @param dock   the dockwidget where it belongs to
   * @param name   the object instance name
   */
  KDockWidgetHeaderDrag( KDockWidgetAbstractHeader* parent, KDockWidget* dock,
                         const char* name = 0L );

  /**
   * Destructs this.
   */
  virtual ~KDockWidgetHeaderDrag(){};

protected:

  /**
   * Draws the drag panel (a double line)
   */
  virtual void paintEvent( QPaintEvent* );
};

/**
 * The header (additional bar) for a KDockWidget.
 * It have got the buttons located there. And it is for recording and reading the button states.
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
 */
class KDockWidgetHeader : public KDockWidgetAbstractHeader
{
  Q_OBJECT
public:

  /** 
   * Constructs this.
   * 
   * @param parent the parent widget (usually a dockwidget)
   * @param name   the object instance name
   */
  KDockWidgetHeader( KDockWidget* parent, const char* name = 0L );

  /**
   * Destructs this.
   */
  virtual ~KDockWidgetHeader(){};

  /**
   * Hides the close button and stay button when switching to toplevel or vice versa shows them.
   *
   * @param t toplevel or not
   */
  virtual void setTopLevel( bool t);

  /**
   * Saves the current button state to a KDE config container object.
   *
   * @param c the configuration safe
   */
  virtual void saveConfig( KConfig* c);

  /**
   * Loads the current button state from a KDE config container object.
   *
   * @param c the configuration safe
   */
  virtual void loadConfig( KConfig* );

protected slots:
  /**
   * Set dragging the dockwidget off when the stay button is pressed down and vice versa.
   */
  void slotStayClicked();

protected:

  /** A layout manager for placing the embedded buttons (close and stay) */
  QHBoxLayout* layout;
  
  /** a little button for closing (undocking and hiding) the dockwidget */
  KDockButton_Private* closeButton;
  
  /** a little button for enabling/disabling dragging the dockwidget with the mouse */
  KDockButton_Private* stayButton;
  
  /** the drag panel (double line) */
  KDockWidgetHeaderDrag* drag;
};

/**
 *
 */
class KDockTabGroup : public KDockTabCtl
{
  Q_OBJECT
public:
  KDockTabGroup( QWidget *parent = 0, const char *name = 0 )
  :KDockTabCtl( parent, name ){};
  virtual ~KDockTabGroup(){};
};

/**
 * Floatable widget that can be dragged around with the mouse und encapsulate the actual widget.
 *
 * 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: KDockWidget can only be dock to KDockWidget.
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
*/
class KDockWidget: public QWidget
{
  Q_OBJECT
friend class KDockManager;
friend class KDockSplitter;
friend class KDockMainWindow;

public:
  /**
   * Constructs 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.
   *
   * @param dockManager the responsible manager (dock helper)
   * @param name        object instance name
   * @param pixmap      an icon (for instance shown when docked centered)
   * @param parent      parent widget
   */
  KDockWidget( KDockManager* dockManager, const char* name,
               const QPixmap &pixmap, QWidget* parent = 0L );

  /**
   * Destructs a dockwidget.
   */
  virtual ~KDockWidget();

  /**
   * The possible positions where a dockwidget can dock to another dockwidget
   */
  enum DockPosition
  {
    DockNone   = 0,
    DockTop    = 0x0001,
    DockLeft   = 0x0002,
    DockRight  = 0x0004,
    DockBottom = 0x0008,
    DockCenter = 0x0010,
    DockDesktop= 0x0020,

    DockCorner = DockTop | DockLeft | DockRight | DockBottom,
    DockFullSite = DockCorner | DockCenter,
    DockFullDocking = DockFullSite | DockDesktop
  }; 

  /* if target is null  - dock move to desktop at position pos;
   * check - only for internal uses;
   * return result GroupDockWidget
   */
  KDockWidget* manualDock( KDockWidget* target, DockPosition dockPos, int spliPos = 50, QPoint pos = QPoint(0,0), bool check = false );

  /**
   * Specify where it is either possible or impossible for this to dock to another dockwidget.
   *
   * @param pos an OR'ed set of DockPositions
   */
  void setEnableDocking( int pos );

  /**
   * @return where it is either possible or impossible for this to dock to another dockwidget (an OR'ed set of DockPositions)
   */
  int enableDocking(){ return eDocking; }

  /**
   * Specify where it is either possible or impossible for another dockwidget to dock to this.
   *
   * @param pos an OR'ed set of DockPositions
   */
  void setDockSite( int pos ){ sDocking = pos;}

  /**
   * @return where it is either possible or impossible for another dockwidget to dock to this (an OR'ed set of DockPositions)
   */
  int dockSite(){ return sDocking; }

  /**
   * Set the embedded widget. A QLayout takes care about proper resizing, automatically.
   *
   * @param w the pointer to the dockwidget's child widget
   */
  void setWidget( QWidget* w);

  /**
   * Set 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.
   *
   * @param ah a base class pointer to the dockwidget header
   */
  void setHeader( KDockWidgetAbstractHeader* ah);

  /**
   * 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.
   */
  void makeDockVisible();
  
  /** 
   * @return if it may be possible to hide this.  
   * There are reasons that it's impossible:
   * <UL><LI>it is a (tab) group</LI>
   * <LI>it is invisible, already ;-)</LI>
   * <LI>the parent of this is the KDockMainWindow</LI>
   * <LI>it isn't able to dock to another widget</LI></UL>
   */
  bool mayBeHide();
  
  /** 
   * @return if it may be possible to show this
   * There are reasons that it's impossible:
   * <UL><LI>it is a (tab) group</LI>
   * <LI>it is visible, already ;-)</LI>
   * <LI>the parent of this is the KDockMainWindow</LI></UL>
   */
  bool mayBeShow();

  /**
   * @return the dockmanager that is responsible for this.
   */
  KDockManager* dockManager(){ return manager; }

  /**
   * Catches and processes some QWidget events that are interesting for dockwidgets.
   */
  virtual bool event( QEvent * );
  
  /**
   * Add dockwidget management actions to QWidget::show. 
   */
  virtual void show();

public slots:
  /**
   * Toggles the visibility state of the dockwidget if it is able to be shown or to be hidden. 
   *
   */
  void changeHideShowState();

protected:
  
  /**
   * @return the parent widget of this if it inherits class KDockTabGroup
   */
  KDockTabGroup* parentTabGroup();
  
  /**
   * Check some conditions and show or hide the dockwidget header (drag panel).
   * The header is hidden if:
   * <LU><LI>the parent widget is the KDockMainWindow</LI>
   * <LI>this is a (tab) group dockwidget</LI>
   * <LI>it is not able to dock to another dockwidgets</LI>
   */
  void updateHeader();

signals:
  /**
   * Emits that another dockwidget is docking to this.
   *
   * @param dw the dockwidget that is docking to this
   * @param the DockPosition where it wants to dock to
   */
  void docking( KDockWidget* dw, KDockWidget::DockPosition );
  
  /**
   * Signals that the dock default position is set.
   */
  void setDockDefaultPos();

public slots:

  /**
   * 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).
   */
  void undock();

private:
  /** 
   * Sets the caption (window title) of the given tab widget.
   *
   * @param g the group (tab) widget
   */
  void setDockTabName( KDockTabGroup* g);
  
  /**
   * Reparent to s or set this to the KDockMainWindow's view if s is that dockmainwindow.
   * If s is O, simply move the widget.
   *
   * @param s the target widget to reparent to
   * @param p the point to move to (if it doesn't reparent)
   */
  void applyToWidget( QWidget* s, const QPoint& p  = QPoint(0,0) );

  /** A base class pointer to the header of this dockwidget */
  KDockWidgetAbstractHeader* header;
  
  /** the embedded widget */
  QWidget* widget;
  
  /** the layout manager that takes care about proper resizing and moving the embedded widget and the header */
  QVBoxLayout* layout;
  
  /** the responsible dockmanager */
  KDockManager* manager;
  
  /** an icon for the tab widget header */
  QPixmap* pix;

  /**
   * Information about the ability for docking to another dockwidget.
   */
  int eDocking;

  /**
   * Information which site of this dockwidget is free for docking of other dockwidgets.
   */
  int sDocking;

  // GROUP data
  QString firstName;
  QString lastName;
  Orientation splitterOrientation;
  bool isGroup;
  bool isTabGroup;

  class KDockWidgetData;
  KDockWidgetData *d;
};

/**
 * The manager that knows all dockwidgets and handles the dock process.
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
*/
class KDockManager: public QObject
{
  Q_OBJECT
friend class KDockWidget;
friend class KDockMainWindow;

public:
  KDockManager( QWidget* mainWindow, const char* name = 0L );

  /**
   * Destructs a dockmanager.
   */
  virtual ~KDockManager();

  void writeConfig( KConfig* c = 0L, QString group = QString::null );
  void readConfig ( KConfig* c = 0L, QString group = QString::null );
  void activate();

  virtual bool eventFilter( QObject *, QEvent * );

  KDockWidget* findWidgetParentDock( QWidget* );
  void makeWidgetDockVisible( QWidget* w ){ findWidgetParentDock(w)->makeDockVisible(); }

  QPopupMenu* dockHideShowMenu(){ return menu; }

  KDockWidget* getDockWidgetFromName( const QString& dockName );

signals:
  void change();
  void replaceDock( KDockWidget* oldDock, KDockWidget* newDock );
  void setDockDefaultPos( KDockWidget* );

private slots:
  void slotMenuPopup();
  void slotMenuActivated( int );

private:
  struct MenuDockData
  {
    MenuDockData( KDockWidget* _dock, bool _hide )
    {
      dock = _dock;
      hide = _hide;
    };
    ~MenuDockData(){};

    KDockWidget* dock;
    bool hide;
  };

  KDockWidget* findDockWidgetAt( const QPoint& pos );
  void findChildDockWidget( QWidget*&, const QWidget* p, const QPoint& pos );
  void findChildDockWidget( const QWidget* p, WidgetList*& );

  void startDrag( KDockWidget* );
  void dragMove( KDockWidget*, QPoint pos );
  void drop();

  QWidget* main;
  KDockMoveManager* mg;
  KDockWidget* currentDragWidget;
  KDockWidget* currentMoveWidget; // widget where mouse moving
  WidgetList* childDockWidgetList;
  KDockWidget::DockPosition curPos;
  QObjectList* childDock;
  QObjectList* autoCreateDock;
  int storeW;
  int storeH;
  bool draging;
  bool undockProcess;
  bool dropCancel;

  QPopupMenu* menu;
  QList<MenuDockData> *menuData;
};

/**
 * A special kind of KTMainWindow that is able to have dockwidget child widgets.
 *
 * The main widget should be a dockwidget where other dockwidgets can be docked to
 * the left, right, top, bottom or to the middle.
 * Furthermore, the KDockMainWindow has got the KDocManager and some data about the dock states.
 *
 * @author Max Judin.
 * @version $Id: kdockwidget.h,v 1.3 2000/03/23 22:19:50 falkbr Exp $
*/
class KDockMainWindow : public KTMainWindow
{
  Q_OBJECT
public:

  /**
   * Constructs a dockmainwindow. It calls it base class constructor and does additional things concerning
   * to the dock stuff:
   * <UL><LI>information about the dock state of this' children gets initialized</LI>
   * <LI>a dockmanager is created...</LI>
   * <LI>...and gets initialized</LI>
   * <LI>the main dockwidget is set to 0L</LI></UL>
   *
   * @param name object name
   */
  KDockMainWindow( const char *name = 0L );

  /**
   * Destructs a dockmainwindow.
   */
  virtual ~KDockMainWindow();

  /**
   * Returns the dockmanager of this. (@see KDockManager)
   * @return pointer to the wanted dockmanager
   */
  KDockManager* manager(){ return dockManager; }

  /**
   * Sets a new main dockwidget.
   * Additionally, the toolbar is re-initialized.
   *
   * @param _ dockwidget that become the new main dockwidget
   */
  void setMainDockWidget( KDockWidget* );

  /**
   * Returns the main dockwidget.
   *
   * @return pointer to the main dockwidget
   */
  KDockWidget* getMainDockWidget(){ return mainDockWidget; }

  /** 
   * This is one of the most important methods! 
   * The KDockMainWindow creates a new dockwidget object here that usually should encapsulate the user's widget.
   * The new dockwidget is automatically taken under control by the dockmanager of the dockmainwindow.
   *
   * @param name   dockwidget caption (window title)
   * @param pixmap window icon (for instance shown when docked as tabwidget entry)
   * @param parent parent widget for the new dockwidget
   * @return    a pointer to the new created dockwidget
   */
  KDockWidget* createDockWidget( const QString& name, const QPixmap &pixmap, QWidget* parent = 0L );

  /** 
   * It writes the current dock state in the given section of KConfig.
   * 
   * @param c     KDE class for saving configurations
   * @param group name of section to write to
   */
  void writeDockConfig( KConfig* c = 0L, QString group = QString::null );
  
  /** 
   * It reads the current dock state from the given section of KConfig.
   * 
   * @param c     KDE class for saving configurations
   * @param group name of section to read from
   */
  void readDockConfig ( KConfig* c = 0L, QString group = QString::null );

  /**
   * It runs through all dockwidgets which are under control of the dockmanager and calls show() for every
   * encapsulated widget and show() for the dockwidget itself if it is not in tab mode.
   * Additionally, if the main dockwidget is not a QDialog, it will be shown.
   */
  void activateDock(){ dockManager->activate(); }

  /**
   * Returns a popup menu that contains entries for all controlled dockwidgets making hiding and showing
   * them possible.
   *
   * @return the wanted popup menu
   */
  QPopupMenu* dockHideShowMenu(){ return dockManager->dockHideShowMenu(); }

  /**
   * This method shows the given dockwidget.
   * The clue is that it also considers the dockwidget could be a tab page 
   * and must set to be the activate one.
   *
   * @param dock the dockwidget that is to be shown
   */
  void makeDockVisible( KDockWidget* dock );

  /**
   * This is an overloaded member function, provided for convenience.
   * It differs from the above function only in what argument(s) it accepts. 
   */
  void makeWidgetDockVisible( QWidget* widget );

  /**
   * This method calls the base class method. 
   * If the given widget inherits KDockWidget, applyToWidget(this) is called.
   * 
   * @param - any widget that should become the main view
   */
  void setView( QWidget* );

protected slots:

  /**
   * Updates the dock-toolbar buttons and the internal information about the 4 dockwidgets 
   * that are directly docked to the main widget.
   */
  void slotDockChange();

  /**
   * Inverts the state of the appropriate toggle-toolbutton of the dock-toolbar.
   *
   * @param _ index of the toolbutton
   */
  void slotToggled( int );

  /**
   * Using the given parameters it updates the information about the 4 dockwidgets
   * that are directly docked to the main widget.
   *
   * @param oldDock new main dockwidget
   * @param newDock old main dockwidget
   */
  void slotReplaceDock( KDockWidget* oldDock, KDockWidget* newDock );

protected:

  /**
   * Used as container for information about one of the 4 dockwidgets that are
   * directly docked to the main dockwidget.
   */
  struct DockPosData
  {
    /** A Pointer to the dockwidget at this position */
    KDockWidget* dock;
    KDockWidget* dropDock;
    KDockWidget::DockPosition pos;
    int sepPos;
  };

  /**
   * This method docks as given in the position data, if toggled is true.
   * Otherwise the dockwidget given with the position data will be undocked.
   *
   * @param toggled specifies if the dockwidget gets docked or undocked
   * @param data    reference to the struct containing information about the appropriate dockwidget
   */ 
  void toolBarManager( bool toggled, DockPosData &data );

  /** A pointer to the main dockwidget (where one can manualDock() to */
  KDockWidget* mainDockWidget;

  /** A pointer to the manager for the dock process */
  KDockManager* dockManager;

  /** Contains information about which dockwidget is docked on the left. */
  DockPosData DockL;

  /** Contains information about which dockwidget is docked on the right. */
  DockPosData DockR;

  /** Contains information about which dockwidget is docked at the top. */
  DockPosData DockT;

  /** Contains information about which dockwidget is docked at the bottom. */
  DockPosData DockB;

  /** A pointer to the dock toolbar
   * (for showing or hiding the 4 docked dockwidgets that are docked to the main dockwidget).
   */
  KToolBar* toolbar;
};

#endif



Generated by: dfaure@faure on Sun Mar 26 14:24:24 2000, using kdoc 2.0a35.