Messagelib

sortorder.h
1 /******************************************************************************
2  *
3  * SPDX-FileCopyrightText: 2009 Thomas McGuire <[email protected]>
4  *
5  * SPDX-License-Identifier: GPL-2.0-or-later
6  *
7  *******************************************************************************/
8 #pragma once
9 
10 #include <core/aggregation.h>
11 
12 #include <KConfigGroup>
13 
14 namespace MessageList
15 {
16 namespace Core
17 {
18 /**
19  * A class which holds information about sorting, e.g. the sorting and sort direction
20  * of messages and groups.
21  */
22 class SortOrder
23 {
24  Q_GADGET
25  Q_ENUMS(GroupSorting)
26  Q_ENUMS(SortDirection)
27  Q_ENUMS(MessageSorting)
28 
29 public:
30  /**
31  * How to sort the groups
32  * If you add values here please look at the implementations of the enumerate* functions
33  * and add appropriate descriptors.
34  */
35  enum GroupSorting {
36  NoGroupSorting, ///< Don't sort the groups at all, add them as they come in
37  SortGroupsByDateTime, ///< Sort groups by date/time of the group
38  SortGroupsByDateTimeOfMostRecent, ///< Sort groups by date/time of the most recent message
39  SortGroupsBySenderOrReceiver, ///< Sort groups by sender or receiver (makes sense only with GroupBySenderOrReceiver)
40  SortGroupsBySender, ///< Sort groups by sender (makes sense only with GroupBySender)
41  SortGroupsByReceiver ///< Sort groups by receiver (makes sense only with GroupByReceiver)
42  // Never add enum entries in the middle: always add them at the end (numeric values are stored in configuration)
43  };
44 
45  /**
46  * The "generic" sort direction: used for groups and for messages
47  * If you add values here please look at the implementations of the enumerate* functions
48  * and add appropriate descriptors.
49  */
50  enum SortDirection { Ascending, Descending };
51 
52  /**
53  * The available message sorting options.
54  * If you add values here please look at the implementations of the enumerate* functions
55  * and add appropriate descriptors.
56  */
58  NoMessageSorting, ///< Don't sort the messages at all
59  SortMessagesByDateTime, ///< Sort the messages by date and time
60  SortMessagesByDateTimeOfMostRecent, ///< Sort the messages by date and time of the most recent message in subtree
61  SortMessagesBySenderOrReceiver, ///< Sort the messages by sender or receiver
62  SortMessagesBySender, ///< Sort the messages by sender
63  SortMessagesByReceiver, ///< Sort the messages by receiver
64  SortMessagesBySubject, ///< Sort the messages by subject
65  SortMessagesBySize, ///< Sort the messages by size
66  SortMessagesByActionItemStatus, ///< Sort the messages by the "Action Item" flag of status
67  SortMessagesByUnreadStatus, ///< Sort the messages by the "Unread" flags of status
68  SortMessagesByImportantStatus, /// Sort the messages By "Important" flags of status
69  SortMessagesByAttachmentStatus /// Sort the messages By "Attachment" flags of status
70  // Warning: Never add enum entries in the middle: always add them at the end (numeric values are stored in configuration)
71  };
72 
73  SortOrder();
74 
75  /**
76  * Returns the GroupSorting
77  */
78  GroupSorting groupSorting() const;
79 
80  /**
81  * Sets the GroupSorting option.
82  * This may not have any effect, depending on the Aggregation this sort order
83  * is used in.
84  */
86 
87  /**
88  * Returns the current group SortDirection.
89  */
91 
92  /**
93  * Sets the SortDirection for the groups.
94  * Note that this option has no meaning if group sorting is set to NoGroupSorting.
95  */
97 
98  /**
99  * Returns the current message sorting option
100  */
102 
103  /**
104  * Sets the current message sorting option
105  */
107 
108  /**
109  * Returns the current message SortDirection.
110  */
112 
113  /**
114  * Sets the SortDirection for the message.
115  * Note that this option has no meaning if message sorting is set to NoMessageSorting.
116  */
118 
119  /**
120  * Enumerates the message sorting options compatible with the specified Threading setting.
121  * The returned descriptors are pairs in that the first item is the localized description
122  * of the option value and the second item is the integer option value itself.
123  */
125 
126  /**
127  * Enumerates the available message sorting directions for the specified MessageSorting option.
128  * The returned descriptors are pairs in that the first item is the localized description
129  * of the option value and the second item is the integer option value itself.
130  * If the returned list is empty then the value of the option is meaningless in the current context.
131  */
133 
134  /**
135  * Enumerates the group sorting options compatible with the specified Grouping.
136  * The returned descriptors are pairs in that the first item is the localized description
137  * of the option value and the second item is the integer option value itself.
138  * If the returned list is empty then the value of the option is meaningless in the current context.
139  */
141 
142  /**
143  * Enumerates the group sort direction options compatible with the specified Grouping and GroupSorting.
144  * The returned descriptors are pairs in that the first item is the localized description
145  * of the option value and the second item is the integer option value itself.
146  * If the returned list is empty then the value of the option is meaningless in the current context.
147  */
149 
150  /**
151  * Checks if this sort order can be used in combination with the given aggregation.
152  * Some combinations are not valid, for example the message sorting
153  * "most recent in subtree" with a non-threaded aggregation.
154  */
155  bool validForAggregation(const Aggregation *aggregation) const;
156 
157  /**
158  * Returns the default sort order for the given aggregation.
159  * @param aggregation the given aggregation.
160  * @param oldSortOrder the previously used sort order. If possible, the new sort order
161  * will be based on that old sort order, i.e. the message sorting and
162  * message sort direction is adopted.
163  */
164  static SortOrder defaultForAggregation(const Aggregation *aggregation, SortOrder oldSortOrder);
165 
166  /**
167  * Returns true if the ms parameter specifies a valid MessageSorting option.
168  */
170 
171  /**
172  * Reads the sort order from a config group.
173  * @param conf the config group.
174  * @param storageId the id of the folder, which is prepended to each key. This way,
175  * more than one sort order can be saved in the same config group
176  * @param storageUsesPrivateSortOrder this boolean will be true if the sort order
177  * is private for that folder, and false if the
178  * sort order is the global sort order.
179  */
180  void readConfig(KConfigGroup &conf, const QString &storageId, bool *storageUsesPrivateSortOrder);
181 
182  /**
183  * Writes the sort order to a config group.
184  * @param conf the config group.
185  * @param storageId the storage identifier.
186  * @param storageUsesPrivateSortOrder if false, this sort order will be saved as the
187  * global sort order.
188  * @sa readConfig
189  */
190  void writeConfig(KConfigGroup &conf, const QString &storageId, bool storageUsesPrivateSortOrder) const;
191 
192 private:
193  // Helper function to convert an enum value to a string and back
194  static const QString nameForSortDirection(SortDirection sortDirection);
195  static const QString nameForMessageSorting(MessageSorting messageSorting);
196  static const QString nameForGroupSorting(GroupSorting groupSorting);
197  static SortDirection sortDirectionForName(const QString &name);
198  static MessageSorting messageSortingForName(const QString &name);
199  static GroupSorting groupSortingForName(const QString &name);
200 
201  bool readConfigHelper(KConfigGroup &conf, const QString &id);
202 
203  MessageSorting mMessageSorting = SortMessagesByDateTime;
204  SortDirection mMessageSortDirection = Descending;
205  GroupSorting mGroupSorting = NoGroupSorting;
206  SortDirection mGroupSortDirection = Ascending;
207 };
208 } // namespace Core
209 } // namespace MessageList
210 
Sort the messages by date and time of the most recent message in subtree.
Definition: sortorder.h:60
A class which holds information about sorting, e.g.
Definition: sortorder.h:22
A set of aggregation options that can be applied to the MessageList::Model in a single shot...
Definition: aggregation.h:28
Sort groups by date/time of the group.
Definition: sortorder.h:37
SortDirection messageSortDirection() const
Returns the current message SortDirection.
Definition: sortorder.cpp:51
static bool isValidMessageSorting(SortOrder::MessageSorting ms)
Returns true if the ms parameter specifies a valid MessageSorting option.
Definition: sortorder.cpp:264
MessageSorting messageSorting() const
Returns the current message sorting option.
Definition: sortorder.cpp:41
static QVector< QPair< QString, int > > enumerateMessageSortDirectionOptions(MessageSorting ms)
Enumerates the available message sorting directions for the specified MessageSorting option...
Definition: sortorder.cpp:81
Threading
The available threading methods.
Definition: aggregation.h:65
Sort groups by receiver (makes sense only with GroupByReceiver)
Definition: sortorder.h:41
SortDirection groupSortDirection() const
Returns the current group SortDirection.
Definition: sortorder.cpp:31
static QVector< QPair< QString, int > > enumerateMessageSortingOptions(Aggregation::Threading t)
Enumerates the message sorting options compatible with the specified Threading setting.
Definition: sortorder.cpp:61
SortDirection
The "generic" sort direction: used for groups and for messages If you add values here please look at ...
Definition: sortorder.h:50
void writeConfig(KConfigGroup &conf, const QString &storageId, bool storageUsesPrivateSortOrder) const
Writes the sort order to a config group.
Definition: sortorder.cpp:247
Don&#39;t sort the groups at all, add them as they come in.
Definition: sortorder.h:36
void setGroupSorting(GroupSorting gs)
Sets the GroupSorting option.
Definition: sortorder.cpp:26
MessageSorting
The available message sorting options.
Definition: sortorder.h:57
void setMessageSortDirection(SortDirection messageSortDirection)
Sets the SortDirection for the message.
Definition: sortorder.cpp:56
static QVector< QPair< QString, int > > enumerateGroupSortingOptions(Aggregation::Grouping g)
Enumerates the group sorting options compatible with the specified Grouping.
Definition: sortorder.cpp:99
void setMessageSorting(MessageSorting ms)
Sets the current message sorting option.
Definition: sortorder.cpp:46
Sort groups by sender (makes sense only with GroupBySender)
Definition: sortorder.h:40
void readConfig(KConfigGroup &conf, const QString &storageId, bool *storageUsesPrivateSortOrder)
Reads the sort order from a config group.
Definition: sortorder.cpp:234
Grouping
Message grouping.
Definition: aggregation.h:36
Don&#39;t sort the messages at all.
Definition: sortorder.h:58
GroupSorting
How to sort the groups If you add values here please look at the implementations of the enumerate* fu...
Definition: sortorder.h:35
Sort the messages by sender or receiver.
Definition: sortorder.h:61
void setGroupSortDirection(SortDirection groupSortDirection)
Sets the SortDirection for the groups.
Definition: sortorder.cpp:36
GroupSorting groupSorting() const
Returns the GroupSorting.
Definition: sortorder.cpp:21
static SortOrder defaultForAggregation(const Aggregation *aggregation, SortOrder oldSortOrder)
Returns the default sort order for the given aggregation.
Definition: sortorder.cpp:170
Sort groups by sender or receiver (makes sense only with GroupBySenderOrReceiver) ...
Definition: sortorder.h:39
Sort the messages by the "Unread" flags of status.
Definition: sortorder.h:67
Sort the messages by date and time.
Definition: sortorder.h:59
Sort the messages by the "Action Item" flag of status.
Definition: sortorder.h:66
static QVector< QPair< QString, int > > enumerateGroupSortDirectionOptions(Aggregation::Grouping g, GroupSorting groupSorting)
Enumerates the group sort direction options compatible with the specified Grouping and GroupSorting...
Definition: sortorder.cpp:123
bool validForAggregation(const Aggregation *aggregation) const
Checks if this sort order can be used in combination with the given aggregation.
Definition: sortorder.cpp:155
Sort groups by date/time of the most recent message.
Definition: sortorder.h:38
Sort the messages By "Important" flags of status.
Definition: sortorder.h:69
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Dec 6 2021 23:04:58 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.