diff options
Diffstat (limited to 'kmail/Mainpage.dox')
| -rw-r--r-- | kmail/Mainpage.dox | 104 |
1 files changed, 52 insertions, 52 deletions
diff --git a/kmail/Mainpage.dox b/kmail/Mainpage.dox index 0b15ebfbc..8f7a65037 100644 --- a/kmail/Mainpage.dox +++ b/kmail/Mainpage.dox @@ -71,7 +71,7 @@ is not modal and the user may hit apply/ok anytime between calls to function that want to use the identity reference. Store the UOID instead if you need to keep track of the identity. You may also want to connect to one of the KPIM::IdentityManager::changed() or ::deleted() -signals, if you want to do special processing in case the identity +Q_SIGNALS, if you want to do special processing in case the identity changes. Thus, in the ConfigureDialog, you will see non-const KPIM::Identity @@ -271,13 +271,13 @@ accessed via KMKernel ( the "kmkernel" construct ). Those methods are : folder manager. In dimap, both the headers and a copy of the full message are cached locally. 4) KMFolderMgr *searchFolderMgr() - which returns the folder manager - for search folders (folders created by using the "find + for search folders (folders created by using the "tqfind messages" tool). Other email clients call this type of folder "virtual folders". FolderJob classes - These classes allow asynchronous operations on KMFolder's. You create a Job on the heap, connect to one of its -signals and wait for the job to finish. Folders serve as FolderJob +Q_SIGNALS and wait for the job to finish. Folders serve as FolderJob factories. For example, to retrieve the full message from a folder you do : @@ -316,9 +316,9 @@ with questions... length := Q_UINT16 ; little endian (native?) - value := unicode-string-value / ulong-value + value := tqunicode-string-value / ulong-value - unicode-string-value := 0*256QChar ; network-byte-order + tqunicode-string-value := 0*256QChar ; network-byte-order ulong-value := unsigned_long ; little endian @@ -334,7 +334,7 @@ Currently defined tag values are: IdMD5 5 u msgIdMD5().stripWhiteSpace() XMark 6 u xmark().stripWhiteSpace() Offset 7 l folderOffset() (not only mbox!) - LegacyStatus 8 l mLegacyStatus + LegacytqStatus 8 l mLegacytqStatus Size 9 l msgSize() Date 10 l date() File 11 u fileName() (not only maildir!) @@ -342,9 +342,9 @@ Currently defined tag values are: MDNSent 13 l mdnSentState() ReplyToAuxIdMD5 14 u replyToAuxIdMD5() StrippedSubject 15 u strippedSubjectMD5().stripWhiteSpace() - Status 16 l status() + tqStatus 16 l status() - u: unicode-string-value; l: ulong-value + u: tqunicode-string-value; l: ulong-value Proposed new (KDE 3.2 / KMail 1.6) entry format: @@ -446,20 +446,20 @@ Currently defined tags are: MBoxOffset Offset(64) Offset in mbox file (pointing to From_) MBoxLength Size(64) Length of message in mbox file (incl. From_) Size Size(64) rfc2822-size of message (in mbox: excl. From_) - Status BitField (see below) + tqStatus BitField (see below) MessageIdMD5 MD5Hash MD5Hash of _normalized_ Message-Id: MDNLink SerialNumber SerNum of MDN received for this message DNSLink SerialNumber SerNUm of DSN received for this message ThreadHeads SerialNumberList MD5Hash's of all (so far discovered) - _top-level thread parents_ + _top-level thread tqparents_ ThreadParents SerialNumberList MD5Hash's of all (so far discovered) - thread parents + thread tqparents "String" is either Utf8String or (Utf16String or Latin1String), depending on content -Currently allocated bits for the Status BitField are: +Currently allocated bits for the tqStatus BitField are: Bit Value: on(/off) (\\imapflag) @@ -527,7 +527,7 @@ class SortCacheItem: folder) messages is cached on disk in a file named .$FOLDER.index.sorted so if, for example the name of a folder is foo, the associated sorting cache file would be called ".foo.index.sorted". - For each message, its serial number, that of its parent, the length of its + For each message, its serial number, that of its tqparent, the length of its sorting key, and the key itself are written to this file. At the start of the file several per folder counts and flags are cached additionally, immediately after a short file headers. The entries from the start of the @@ -544,13 +544,13 @@ class SortCacheItem: What is used for figuring out threading? - messages can have an In-Reply-To header that contains the message id of - another message. This is called a perfect parent. + another message. This is called a perfect tqparent. - additionally there is the References header which, if present, holds a list of message ids that the current message is a follow up to. We currently use the second to last entry in that list only. See further down for the reasoning behind that. - If the above two fail and the message is prefixed (Re: foo, Fwd: foo etc.) - an attempt is made to find a parent by looking for messages with the same + an attempt is made to find a tqparent by looking for messages with the same subject. How that is done is explained below as well. For all these comparisons of header contents, the md5 hashes of the headers @@ -578,27 +578,27 @@ Strategy: has been moved away in the meantime (possibly by outside forces such as other clients) and a deleted counter is incremented and all further processing stopped for this message. - The messages parent serial number, as read from the sorted file is then - used to look up the parent and reset it to -1 should it not be in the + The messages tqparent serial number, as read from the sorted file is then + used to look up the tqparent and reset it to -1 should it not be in the current folder anymore. -1 and -2 are special values that can show up - as parent serial numbers and are used to encode the following: - -1 means this message has no perfect parent, a parent for it needs to + as tqparent serial numbers and are used to encode the following: + -1 means this message has no perfect tqparent, a tqparent for it needs to be found from among the other messages, if there is a suitable one -2 means this message is top level and will forever stay so, no need - to even try to find a parent. This is also used for the non-threaded + to even try to find a tqparent. This is also used for the non-threaded case. These are messages that have neither an In-Reply-To header nor a References header and have a subject that is not prefixed. - In case there is a perfect parent, the current sort cache item is - appended to the parents list of unsorted children, or to that of + In case there is a perfect tqparent, the current sort cache item is + appended to the tqparents list of unsorted tqchildren, or to that of root, if there is not. A sort cache item is created in the mSortCache - for the parent, if it is not already there. Messages with a parent of - -1 are appended to the "unparented" list, which is later traversed and - its elements threaded. Messages with -2 as the parent are children of + for the tqparent, if it is not already there. Messages with a tqparent of + -1 are appended to the "untqparented" list, which is later traversed and + its elements threaded. Messages with -2 as the tqparent are tqchildren of root as well, as noted above, and will remain so. Once the end of the file is reached, we should have a nicely filled mSortCache, containing a sort cache item for each message that was in the - sorted file. Messages with perfect parents know about them, top level + sorted file. Messages with perfect tqparents know about them, top level messages know about that as well, all others are on a list and will be threaded later. @@ -608,16 +608,16 @@ Strategy: to mFolder->count() are looked at and a SortCacheItem is created for the ones that do not have one yet. This is where all sort cache items are created if there was no sorted file. The items created here are by definition un- - sorted as well as unparented. On creation their sort key is figured out as + sorted as well as untqparented. On creation their sort key is figured out as well. - The next step is finding parents for those messages that are either new, or - had a parent of -1 in the .sorted file. To that end, a dict of all sort + The next step is finding tqparents for those messages that are either new, or + had a tqparent of -1 in the .sorted file. To that end, a dict of all sort cache items indexed by the md5 hash of their messsage id headers is created, that will be used for looking up sort cache items by message id. The list of - yet unparented messages is then traversed and findParent() called for each + yet untqparented messages is then traversed and findParent() called for each element wihch checks In-Reply-To and References headers and looks up the - sort cache item of those parents in the above mentioned dict. Should none be + sort cache item of those tqparents in the above mentioned dict. Should none be found, the item is added to a second list the items of which will be subject threaded. @@ -638,7 +638,7 @@ Strategy: - since the above is a common special case, it is worth trying. I think. ;) - If the parent found is perfect (In-Reply-To), the sort cache items is marked + If the tqparent found is perfect (In-Reply-To), the sort cache items is marked as such. mIsImperfectlyThreaded is used for that purposer, we will soon see why that flag is needed. @@ -646,30 +646,30 @@ Strategy: the messages that are now top-level, the current thread heads, so to speak, are collected into a second dict ( QDict< QPtrList< SortCacheItem > > ) that contains for each different subject an entry holding a list of (so far - top level) messages with that subject, that are potential parents for - threading by subjects. These lists are sorted by date, so the parent closest + top level) messages with that subject, that are potential tqparents for + threading by subjects. These lists are sorted by date, so the tqparent closest by date can be chosen. Sorting of these lists happens via insertion sort while they are built because not only are they expected to be short (apart from hard corner cases such as cvs commit lists, for which subject threading makes little sense anyhow and where it should be turned off), but also since the messages should be roughly pre sorted by date in the store already. Some cursory benchmarking supports that assumption. - If now a parent is needed for a message with a certain subject, the list of + If now a tqparent is needed for a message with a certain subject, the list of top level messages with that subject is traversed and the first one that is - older than our message is chosen as it's parent. Parents more than six weeks + older than our message is chosen as it's tqparent. Parents more than six weeks older than the message are not accepted. The reasoning being that if a new message with the same subject turns up after such a long time, the chances that it is still part of the same thread are slim. The value of six weeks is chosen as a result of a poll conducted on #kde-devel, so it's probably bogus. :) All of this happens in the aptly named: findParentBySubject(). - Everthing that still has no parent after this ends up at toplevel, no further + Everthing that still has no tqparent after this ends up at toplevel, no further attemp is made at finding one. If you are reading this because you want to implement threading by body search or somesuch, please go away, I don't like you. :) Ok, so far we have only operated on sort cache items, nothing ui wise has - happened yet. Now that we have established the parent/child relations of all + happened yet. Now that we have established the tqparent/child relations of all messages, it's time to create HeaderItems for them for use in the header list. But wait, you say, what about sorting? Wouldn't it make sense to do that first? Exactly, you're a clever bugger, ey? Here, have a cookie. ;) @@ -677,13 +677,13 @@ Strategy: cache items happen at the same time. As previously mentioned (or not) each sort cache item holds a list of its - sorted and one of its unsorted children. Starting with the root node the + sorted and one of its unsorted tqchildren. Starting with the root node the unsorted list is first qsorted, and then merged with the list of already - sorted children. To achieve that, the heads of both lists are compared and + sorted tqchildren. To achieve that, the heads of both lists are compared and the one with the "better" key is added to the list view next by creating a KMHeaderListItem for it. That header item receives both its sort key as well as its id from the sort cache item. Should the current sort cache item have - children, it is added to the end of a queue of nodes to repeat these steps + tqchildren, it is added to the end of a queue of nodes to repeat these steps on after the current level is sorted. This way, a breadth first merge sort is performed on the sort cache items and header items are created at each node. @@ -706,16 +706,16 @@ What happens when a message arrives in the folder? structures described above are updated accordingly. If threading is enabled, the new message is threaded using the same findParent and findParentBySubject methods used on folder open. If the message ends up in a watched or ignored - thread, those status bits are inherited from the parent. The message is also + thread, those status bits are inherited from the tqparent. The message is also added to the dict of header items, the index of messages by message id and, if applicable and if the message is threaded at top level, to the list of - potential parents for subject threading. + potential tqparents for subject threading. After those house keeping tasks are performed, the list of as of yet imper- fectly threaded messages is traversed and our newly arrived message is - considered as a new parent for each item on it. This is especially important - to ensure that parents arriving out of order after their children still end - up as parents. If necessary, the entries in the .sorted file of rethreaded + considered as a new tqparent for each item on it. This is especially important + to ensure that tqparents arriving out of order after their tqchildren still end + up as tqparents. If necessary, the entries in the .sorted file of rethreaded messages are updated. An entry for the new message itself is appended to the .sorted file as well. @@ -732,10 +732,10 @@ What happens when a message is removed from the folder? In this case the msgRemoved slot kicks in and updates the headers list. First the sort cache item and header item representing our message are removed from the data structures and the ids of all items after it in the store decre- - mented. Then a list of children of the message is assembled containing those - children that have to be reparented now that our message has gone away. If - one of those children has been marked as toBeDeleted, it is simply added to - root at top level, because there is no need to find a parent for it if it is + mented. Then a list of tqchildren of the message is assembled containing those + tqchildren that have to be reparented now that our message has gone away. If + one of those tqchildren has been marked as toBeDeleted, it is simply added to + root at top level, because there is no need to find a tqparent for it if it is to go away as well. This is an optimization to avoid rethreading all messages in a thread when deleting several messages in a thread, or even the whole thread. The KMMoveCommand marks all messages that will be moved out of @@ -743,7 +743,7 @@ What happens when a message is removed from the folder? can be avoided. Note that that does not work when moving messages via filter action. - That list of children is then traversed and a new parent found for each one + That list of tqchildren is then traversed and a new tqparent found for each one using, again, findParent and findParentBySubject. When a message becomes imperfectly threaded in the process, it is added to the corresponding list. @@ -859,7 +859,7 @@ public: QTimer::singleShot( 10*1000, this, SLOT(slotTimeout()) ); } -private slots: +private Q_SLOTS: void slotTimeout() { notify(): } private: |