1/*
2 Copyright (c) 2009 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_ENTITYTREEVIEWSTATESAVER_H
21#define AKONADI_ENTITYTREEVIEWSTATESAVER_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QObject>
26
27class QTreeView;
28class KConfigGroup;
29
30namespace Akonadi {
31
32class EntityTreeViewStateSaverPrivate;
33
34/**
35 * @short A helper class that saves and restores state of an EntityTreeView
36 *
37 * This class saves and restores the state of a QTreeView showing an EntityTreeModel,
38 * or whatever proxies are stacked on top of one. State so far means the current selection
39 * and expansion of the items and collections.
40 *
41 * The EntityTreeViewStateSaver is needed because populating the EntityTreeModel
42 * is asynchronous and finding the right point in time to restore the state is a
43 * difficult task that is hidden inside this class.
44 *
45 * Example:
46 *
47 * @code
48 *
49 * class MyWidget : public QWidget
50 * {
51 * public:
52 * MyWidget( QWidget* parent );
53 * ~MyWidget();
54 *
55 * ...
56 *
57 * private:
58 * KConfig *mGlobalConfig;
59 * QTreeView *mTreeView;
60 * Akonadi::EntityTreeViewStateSaver *mStateSaver;
61 * };
62 *
63 * MyWidget::MyWidget( QWidget *parent )
64 * : QWidget( parent )
65 * {
66 * mGlobalConfig = ...
67 * mTreeView = new QTreeView( this );
68 * ...
69 *
70 * mStateSaver = new Akonadi::EntityTreeViewStateSaver( mTreeView );
71 *
72 * KConfigGroup group( mGlobalConfig, "treeViewState" );
73 * mStateSaver->restoreState( group );
74 * }
75 *
76 * MyWidget::~MyWidget()
77 * {
78 * KConfigGroup group( mGlobalConfig, "treeViewState" );
79 * mStateSaver->saveState( group );
80 * }
81 *
82 * @endcode
83 *
84 * @author Volker Krause <vkrause@kde.org>
85 * @since 4.4
86 *
87 * @deprecated This class is deprecated. Use ETMViewStateSaver instead.
88 */
89class AKONADI_DEPRECATED_EXPORT EntityTreeViewStateSaver : public QObject
90{
91 Q_OBJECT
92
93public:
94 /**
95 * Creates a new state saver, for saving or restoring.
96 *
97 * @param view The QTreeView which state should be saved/restored.
98 */
99 explicit EntityTreeViewStateSaver(QTreeView *view);
100
101 /**
102 * Destroys this state saver.
103 */
104 ~EntityTreeViewStateSaver();
105
106 /**
107 * Stores the current state in the given config group.
108 *
109 * @param configGroup Config file group into which the state is supposed to be stored.
110 */
111 void saveState(KConfigGroup &configGroup) const;
112
113 /**
114 * Restore the state stored in @p configGroup as soon as the corresponding entities
115 * become available in the model (the model is populated asynchronously, which is the
116 * main reason why you want to use this class).
117 *
118 * @param configGroup Config file group containing a previously stored EntityTreeView state.
119 */
120 void restoreState(const KConfigGroup &configGroup) const;
121
122private:
123 //@cond PRIVATE
124 EntityTreeViewStateSaverPrivate *const d;
125 Q_PRIVATE_SLOT(d, void rowsInserted(const QModelIndex &, int, int))
126 Q_PRIVATE_SLOT(d, void restoreScrollBarState())
127 //@endcond
128};
129
130}
131
132#endif
133