From b3a4d3a564511b64cb90aecbe939a53aac1b8171 Mon Sep 17 00:00:00 2001 From: Wolfgang Müller Date: Fri, 18 Oct 2024 17:46:39 +0200 Subject: content: Add post: "Understanding recent files on KDE Plasma 6" --- content/25/index.md | 131 +++++++++++++++++++++++++++++++++++++++++++ content/25/recent-okular.png | Bin 0 -> 44030 bytes 2 files changed, 131 insertions(+) create mode 100644 content/25/index.md create mode 100644 content/25/recent-okular.png (limited to 'content/25') diff --git a/content/25/index.md b/content/25/index.md new file mode 100644 index 0000000..b17f3fe --- /dev/null +++ b/content/25/index.md @@ -0,0 +1,131 @@ ++++ +date = 2024-10-18T17:46:30+02:00 +title = "Understanding recent files on KDE Plasma 6" + +[taxonomies] +tags = ["TIL", "kde"] + +[extra] +related = [] ++++ + +Today, prompted by a question on the `#kde` channel on +[libera](https://libera.chat/), I looked into how Plasma handles its registry of +recently used folders and documents. Turns out it's way more complicated than I +first thought. + +The question specifically was whether there was a way to programmatically add +files to [Okular's](https://okular.kde.org/) recently opened documents, so +that's where I started looking. I was already aware that some apps like Okular +and [Gwenview](https://apps.kde.org/gwenview/) keep their own history +independently from the system, and I quickly found out that Okular simply keeps +a list of recently opened files in its configuration file `~/.config/okularrc` +of all places. + +{{ img(path="recent-okular.png", format="png", alt="A screenshot of Okular, +KDE's PDF document viewer. The application shows its welcome page, with a button +to open a new document beside a list of recently opened documents. The latter +contains an entry for a PDF of the POSIX Base Specifications.", +caption="Okular's welcome page, with recent documents listed.") }} + +This got me thinking. Maybe it would be a decent idea to instead have Okular +interact with the system history directly. For that I first had to understand +how exactly it worked. + +### The Standard + +The way that I *thought* Plasma's system history worked was through +freedesktop.org's [Desktop Bookmark +Specification](https://www.freedesktop.org/wiki/Specifications/desktop-bookmark-spec/) +. The gist of it is that applications read from and write to a well-known file +`$XDG_DATA_DIR/recently-used.xbel`. Indeed that file existed and it even +contained the relevant entry: + +```xml + + + + + + + + + + +``` + +Okular then seemed to write to both `recently-used.xbel` and `okularrc` when +instead it could simply access the former directly and keep all history entries +out of its configuration file. What's more, having Okular forget its history +would only clear the entry in `okularrc`. + +The most prominent place in which system history is displayed is in +[Dolphin's](https://apps.kde.org/dolphin/) "Recent Files" panel. After clearing +Okular's history entry I still found the document there, so it seemed obvious to +assume that it uses `recently-used.xbel`. Dolphin lets you forget specific +entries from history, so I confidently deleted the entry there and re-checked +the file. Weirdly, the entry was still there even though Dolphin didn't show it +anymore... + +It was time to delve into the code. Untangling all the interconnected parts took +a while, but after a good 10 minutes, I finally knew what was going on: **There +was another history provider.** + +### The Other "Standard" + +This is where I have to mention KDE's activities. Activities are a +[somewhat](https://pointieststick.com/2024/02/06/whats-going-on-with-activities-in-plasma-6/) +[ill-defined](https://invent.kde.org/plasma/kactivitymanagerd/-/issues/6) +concept but they basically boil down to the idea of providing a different +computing space depending on what you are doing at the moment. In reality the +most obvious user-facing activity feature in Plasma 6 is that you can customize +your task bar and wallpaper per activity so you could consider it an extension +of virtual desktops - applications open on one activity won't be shown once you +switch to another. + +Crucially, however, the activity subsystem +[`kactivitymanagerd`](https://invent.kde.org/plasma/kactivitymanagerd/) is +also used to manage recently opened files. I imagine the plan is (or was) to +enable tracking file history per activity, but in all my testing I could not get +this to work - history seems to be global. So what this essentially means is +that an application might, and most probably will: + +1) Keep its own history, most of the time through +[KRecentFilesAction](https://api.kde.org/frameworks/kconfigwidgets/html/classKRecentFilesAction.html) +and a simplistic history implementation. The data here is exclusively accessed +by the application itself. + +2) Keep its history in the desktop-agnostic `recently-used.xbel` file. In KDE's +case this usually does not happen in the application itself but instead through +its [KIO](https://invent.kde.org/frameworks/kio) framework. Other desktop +systems might read and display this data, but KDE seems to be write-only: +history is appended, but never shown to the user. + +3) Keep its history in an [SQLite](https://www.sqlite.org/) database under +`~/.local/share/kactivitymanagerd`, managed by a daemon. This is what you see in +Dolphin and what you can manage under "Recent Files" in the system settings. + +It also means that if you want to tweak history management, forget documents or +folders, or turn the thing(s) off, you have to look in a multitude of places: + +1) If the application provides a setting to manage or disable its own history, +use that. If that's not available (like in Okular) you're out of luck. Disabling +an application's own history will not impact the other two history providers - +you will still see recent files in Dolphin and elsewhere in the system. + +2) There's been +[ongoing](https://invent.kde.org/frameworks/kio/-/merge_requests/1670) +[work](https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/4560) to +streamline management of entries in `recently-used.xbel`, spurred by [this +bug](https://bugs.kde.org/show_bug.cgi?id=480276). You may also use the +undocumented `UseRecent`, `MaxEntries`, and `IgnoreHidden` +[options](https://invent.kde.org/frameworks/kio/-/blob/57342c46bf3789cd6f7b07ec33086a24f26223ad/src/core/krecentdocument.cpp#L512-515) +read from `~/.config/kdeglobals`. + +3) Tweak `kactivitymanagerd` history in system settings under "Recent Files". + +### Forgetting History + +With all this in mind my immediate reaction is to shy away from the whole +endeavour to have Okular interface with the system history - there's too many +moving parts, some of which aren't even yet well-defined on KDE's side. diff --git a/content/25/recent-okular.png b/content/25/recent-okular.png new file mode 100644 index 0000000..08dc0bb Binary files /dev/null and b/content/25/recent-okular.png differ -- cgit v1.2.3-2-gb3c3