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

KDE's Doxygen guidelines are available online.