Messagelib

sortorder.h
1/******************************************************************************
2 *
3 * SPDX-FileCopyrightText: 2009 Thomas McGuire <mcguire@kde.org>
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
14namespace MessageList
15{
16namespace Core
17{
18/**
19 * A class which holds information about sorting, e.g. the sorting and sort direction
20 * of messages and groups.
21 */
23{
24 Q_GADGET
25 Q_ENUMS(GroupSorting)
26 Q_ENUMS(SortDirection)
27 Q_ENUMS(MessageSorting)
28
29public:
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 */
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 */
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 [[nodiscard]] 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 */
88 void setGroupSorting(GroupSorting gs);
89
90 /**
91 * Returns the current group SortDirection.
92 */
93 [[nodiscard]] 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 */
99 void setGroupSortDirection(SortDirection groupSortDirection);
100
101 /**
102 * Returns the current message sorting option
103 */
104 [[nodiscard]] MessageSorting messageSorting() const;
105
106 /**
107 * Sets the current message sorting option
108 */
109 void setMessageSorting(MessageSorting ms);
110
111 /**
112 * Returns the current message SortDirection.
113 */
114 [[nodiscard]] 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 */
135 [[nodiscard]] static QList<QPair<QString, int>> enumerateMessageSortDirectionOptions(MessageSorting ms);
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 [[nodiscard]] 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 [[nodiscard]] static SortOrder defaultForAggregation(const Aggregation *aggregation, SortOrder oldSortOrder);
168
169 /**
170 * Returns true if the ms parameter specifies a valid MessageSorting option.
171 */
172 [[nodiscard]] static bool isValidMessageSorting(SortOrder::MessageSorting ms);
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
195private:
196 // Helper function to convert an enum value to a string and back
197 [[nodiscard]] static const QString nameForSortDirection(SortDirection sortDirection);
198 [[nodiscard]] static const QString nameForMessageSorting(MessageSorting messageSorting);
199 [[nodiscard]] static const QString nameForGroupSorting(GroupSorting groupSorting);
200 [[nodiscard]] static SortDirection sortDirectionForName(const QString &name);
201 [[nodiscard]] static MessageSorting messageSortingForName(const QString &name);
202 [[nodiscard]] static GroupSorting groupSortingForName(const QString &name);
203
204 [[nodiscard]] 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
A set of aggregation options that can be applied to the MessageList::Model in a single shot.
Definition aggregation.h:29
Threading
The available threading methods.
Definition aggregation.h:65
A class which holds information about sorting, e.g.
Definition sortorder.h:23
SortDirection groupSortDirection() const
Returns the current group SortDirection.
Definition sortorder.cpp:30
void readConfig(KConfigGroup &conf, const QString &storageId, bool *storageUsesPrivateSortOrder)
Reads the sort order from a config group.
static bool isValidMessageSorting(SortOrder::MessageSorting ms)
Returns true if the ms parameter specifies a valid MessageSorting option.
void setMessageSorting(MessageSorting ms)
Sets the current message sorting option.
Definition sortorder.cpp:45
SortDirection
The "generic" sort direction: used for groups and for messages If you add values here please look at ...
Definition sortorder.h:50
static QList< QPair< QString, int > > enumerateGroupSortingOptions(Aggregation::Grouping g)
Enumerates the group sorting options compatible with the specified Grouping.
Definition sortorder.cpp:98
void setGroupSorting(GroupSorting gs)
Sets the GroupSorting option.
Definition sortorder.cpp:25
MessageSorting messageSorting() const
Returns the current message sorting option.
Definition sortorder.cpp:40
bool validForAggregation(const Aggregation *aggregation) const
Checks if this sort order can be used in combination with the given aggregation.
void writeConfig(KConfigGroup &conf, const QString &storageId, bool storageUsesPrivateSortOrder) const
Writes the sort order to a config group.
static QList< QPair< QString, int > > enumerateMessageSortDirectionOptions(MessageSorting ms)
Enumerates the available message sorting directions for the specified MessageSorting option.
Definition sortorder.cpp:80
void setGroupSortDirection(SortDirection groupSortDirection)
Sets the SortDirection for the groups.
Definition sortorder.cpp:35
GroupSorting groupSorting() const
Returns the GroupSorting.
Definition sortorder.cpp:20
MessageSorting
The available message sorting options.
Definition sortorder.h:60
@ SortMessagesBySize
Sort the messages by size.
Definition sortorder.h:68
@ SortMessagesByAttachmentStatus
Sort the messages By "Important" flags of status.
Definition sortorder.h:72
@ SortMessagesByDateTime
Sort the messages by date and time.
Definition sortorder.h:62
@ SortMessagesByActionItemStatus
Sort the messages by the "Action Item" flag of status.
Definition sortorder.h:69
@ NoMessageSorting
Don't sort the messages at all.
Definition sortorder.h:61
@ SortMessagesBySenderOrReceiver
Sort the messages by sender or receiver.
Definition sortorder.h:64
@ SortMessagesBySender
Sort the messages by sender.
Definition sortorder.h:65
@ SortMessagesByReceiver
Sort the messages by receiver.
Definition sortorder.h:66
@ SortMessagesByDateTimeOfMostRecent
Sort the messages by date and time of the most recent message in subtree.
Definition sortorder.h:63
@ SortMessagesByUnreadStatus
Sort the messages by the "Unread" flags of status.
Definition sortorder.h:70
@ SortMessagesBySubject
Sort the messages by subject.
Definition sortorder.h:67
static QList< QPair< QString, int > > enumerateMessageSortingOptions(Aggregation::Threading t)
Enumerates the message sorting options compatible with the specified Threading setting.
Definition sortorder.cpp:60
GroupSorting
How to sort the groups If you add values here please look at the implementations of the enumerate* fu...
Definition sortorder.h:35
@ SortGroupsBySenderOrReceiver
Sort groups by sender or receiver (makes sense only with GroupBySenderOrReceiver)
Definition sortorder.h:39
@ SortGroupsBySender
Sort groups by sender (makes sense only with GroupBySender)
Definition sortorder.h:40
@ SortGroupsByReceiver
Sort groups by receiver (makes sense only with GroupByReceiver)
Definition sortorder.h:41
@ SortGroupsByDateTimeOfMostRecent
Sort groups by date/time of the most recent message.
Definition sortorder.h:38
@ NoGroupSorting
Don't sort the groups at all, add them as they come in.
Definition sortorder.h:36
@ SortGroupsByDateTime
Sort groups by date/time of the group.
Definition sortorder.h:37
static SortOrder defaultForAggregation(const Aggregation *aggregation, SortOrder oldSortOrder)
Returns the default sort order for the given aggregation.
SortDirection messageSortDirection() const
Returns the current message SortDirection.
Definition sortorder.cpp:50
void setMessageSortDirection(SortDirection messageSortDirection)
Sets the SortDirection for the message.
Definition sortorder.cpp:55
static QList< QPair< QString, int > > enumerateGroupSortDirectionOptions(Aggregation::Grouping g, GroupSorting groupSorting)
Enumerates the group sort direction options compatible with the specified Grouping and GroupSorting.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:49:56 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.