sublime/controller.h

   1 /***************************************************************************
   2  *   Copyright 2006-2007 Alexander Dymo  <adymo@kdevelop.org>       *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU Library General Public License as       *
   6  *   published by the Free Software Foundation; either version 2 of the    *
   7  *   License, or (at your option) any later version.                       *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU Library General Public     *
  15  *   License along with this program; if not, write to the                 *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.         *
  18  ***************************************************************************/
  19 #ifndef SUBLIMECONTROLLER_H
  20 #define SUBLIMECONTROLLER_H
  21
  22 #include <QtCore/QObject>
  23
  24 #include "sublimedefs.h"
  25 #include "sublimeexport.h"
  26
  27 #include "mainwindowoperator.h"
  28
  29
  30 namespace Sublime {
  31
  32 class Area;
  33 class AreaIndex;
  34 class Document;
  35 class MainWindow;
  36
  37 /**
  38 @short Handles association of areas to main windows.
  39
  40 Whereas the MainWindow class can be told to show arbitrary Area
  41 instance, this class establishes more high-level rules based
  42 on the following assumptions:
  43
  44 1. It's desirable to have a list of "area types" -- basically string,
  45 and be able to switch each main window between those "area types". For
  46 example, to switch main window between "Code" and "Debug"
  47
  48 2. It's also desirable to save the state of area -- like the set of toolviews,
  49 position of toolviews, etc. This need to be done per-main window, so that
  50 "code" area of one window is allowed to be different from "code" area
  51 of another window.
  52
  53 3. Is it desirable to be able to reset an area of given type in a given
  54 main window to a default state.
  55
  56 The current implementation achieves those goals as follows.
  57
  58 1. Controller keeps a list of default areas. Those areas are not shown by any
  59 main window, and never modified as result of user actions. They are directly
  60 constructed by kdevelop core. Those areas are returned by the ::defaultAreas
  61 method. Each Area instance in the list provides area type id, and human name
  62 of the area -- via Area::objectName and Area::title methods respectively.
  63 All methods in this class accept area id, and human name of the area is only
  64 used to present the area type to the user, for selection.
  65
  66 2. Controller also keeps a list of MainWindow instances that it manages. For
  67 each instance, it keeps a list of areas private to the MainWindow instance.
  68 There's one area for each area in defaultAreas. That is, for each area type,
  69 there's one area in defaultAreas, and one area per each main window
  70
  71 3. It's possible to switch a given main window to display an area of the
  72 given type -- which finds the area with the given id in the list of area
  73 private to that main window, and switches the main window to the found area.
  74
  75 When we create a new main window, we create fresh set of private areas by
  76 cloning the default areas. An alternative approach would be to create a clone
  77 only when we try to show a specific area type in a main window. However,
  78 I think that knowing that each main window has its Area instance for each
  79 area type simplifies the code. For example, most of the time, during
  80 restoring areas we'd need per-window area instances anyway. Of course, we
  81 can introduce a method demand_area_type(MainWindow*, QString) that
  82 clones the default area of the necessary type, but I don't see what that will
  83 buy us.
  84
  85 Controller has to exist before any area, document or mainwindow can be created.
  86 There's no point in having two controllers for one application unless they
  87 need to show completely different sets of areas.
  88 */
  89 class SUBLIME_EXPORT Controller: public QObject, public MainWindowOperator {
  90     Q_OBJECT
  91 public:
  92     Controller(QObject *parent = 0);
  93     ~Controller();
  94
  95     /** Add the area to the set of default areas in this controller. */
  96     void addDefaultArea(Area *area);
  97
  98     /** Return the list of default areas.  */
  99     const QList<Area*> &defaultAreas() const;
 100
 101     /** Return the default area with given @p id.*/
 102     Area *defaultArea(const QString &id);
 103
 104     /** Add a main window to the set of of windows managed by this
 105         controller.  The ownership of the window is passed to the
 106         controller.  The window will be associated with a set of
 107         areas created by cloning the current defaultAreas.  */
 108     void addMainWindow(MainWindow* mainWindow);
 109
 110     /** Return the set of MainWindow instances managed by
 111         *this. */
 112     const QList<MainWindow*> &mainWindows() const;
 113
 114     /** Return all areas associated with the main window with the specified
 115         index. */
 116    const QList<Area*> &areas(int mainWindow) const;
 117
 118     /** Return the area with the given in main window specified
 119         by its index, @p mainWindow.  */
 120     Area *area(int mainWindow, const QString& id);
 121
 122     /**Shows an @p area in @p mainWindow. @todo Remove this method */
 123     void showArea(Area *area, MainWindow *mainWindow);
 124
 125     /** Show area with the id of @p areaTypeId in @p mainWindow. */
 126     void showArea(const QString& areaTypeId, MainWindow *mainWindow);
 127
 128     /** Make the tool configuration of the area currently shown
 129         in @p mainWindow match those of default area with the same
 130         area type. */
 131     void resetCurrentArea(MainWindow *mainWindow);
 132
 133     /** Return the list of all areas, including default area and
 134         area private to each main window.  */
 135     const QList<Area*> &allAreas() const;
 136
 137     /**@return the list of documents created in this controller.*/
 138     const QList<Document*> &documents() const;
 139
 140     void setStatusIcon(Document* document, const QIcon& icon);
 141
 142 public Q_SLOTS:
 143     //@todo adymo: this should not be a part of public API
 144     /**Area can connect to this slot to release itself from its mainwindow.*/
 145     void areaReleased();
 146     /**Releases @p area from its mainwindow.*/
 147     void areaReleased(Sublime::Area *area);
 148
 149 protected:
 150     bool eventFilter(QObject *obj, QEvent *ev);
 151     void showAreaInternal(Area* area, MainWindow *mainWindow);
 152
 153 private Q_SLOTS:
 154     void notifyToolViewRemoved(Sublime::View *view, Sublime::Position);
 155     void notifyToolViewAdded(Sublime::View *view, Sublime::Position);
 156     void notifyViewRemoved(Sublime::AreaIndex*, Sublime::View *view);
 157     void notifyViewAdded(Sublime::AreaIndex*, Sublime::View *view);
 158
 159 Q_SIGNALS:
 160     void aboutToRemoveToolView(Sublime::View*);
 161     void toolViewAdded(Sublime::View*);
 162     void aboutToRemoveView(Sublime::View*);
 163     void viewAdded(Sublime::View*);
 164     void toolViewMoved(Sublime::View*);
 165
 166 private:
 167     void init();
 168     Q_PRIVATE_SLOT(d, void removeArea(QObject*))
 169     Q_PRIVATE_SLOT(d, void removeDocument(QObject*))
 170
 171     /**Adds the document to the controller, used by Document class.
 172     @todo adymo: refactor*/
 173     void addDocument(Document *document);
 174
 175     struct ControllerPrivate *const d;
 176
 177     friend class Area;
 178     friend class Document;
 179
 180 };
 181
 182 }
 183
 184 #endif
 185