Warning, /utilities/kio-stash/README.md is written in an unsupported language. File is not indexed.
0001 # File Stash KIO Worker 0002 0003 ## Introduction 0004 0005 *This is a GSoC 2016 project by Arnav Dhamija, mentored by Boudhayan Gupta and Pinak Ahuja.* 0006 0007 Selecting multiple files in any file manager for copying and pasting has never been a pleasant experience, especially if the files are in a non-continuous order. Often, when selecting files using Ctrl+A or the selection tool, we find that we need to select only a subset of the required files we have selected. This leads to the unwieldy operation of removing files from our selection. Of course, the common workaround is to create a new folder and to put all the items in this folder prior to copying, but this is a very inefficient and very slow process if large files need to be copied. Moreover Ctrl+Click requires fine motor skills to not lose the entire selection of files. 0008 0009 This is an original project with a novel solution to this problem. My solution is to add a virtual folder in all KIO applications, where the links to files and folders can be temporarily saved for a session. The files and folders are "staged" on this virtual folder. Files can be added to this by using all the regular file management operations such as Move, Copy and Paste, or by drag and drop. Hence, complex file operations such as moving files across many devices can be made easy by staging the operation before performing it. 0010 0011 ## Project Overview 0012 0013 This project consists of the following modules. As there is no existing implementation in KIO for managing virtual directories, all the following modules were written completely from scratch. 0014 0015 ### KIO Worker 0016 0017 The KIO worker is the backbone of the project. This KIO worker is responsible for interfacing with the GUI of a KDE application and provides the methods for various operations such as copying, deleting, and renaming files. All operations on the KIO worker are applied on a virtual stash filesystem (explained below). These operations are applied through inter process communication using the Qt's D-Bus API. 0018 0019 The advantage of the KIO worker is that it provides a consistent experience throughout the entire KDE suite of applications. Hence, this feature would work with all KIO compatible applications. 0020 0021 ### Stash File System 0022 0023 The Stash File System (SFS) is used for virtually staging all the files and directories added to the KIO worker. When a file is copied to the SFS, a new File Node is created to it under the folder to which it is copied. On copying a folder, a new Directory Node is created on the SFS with all the files and directories under it copied recursively as dictated by KIO. The SFS is a very important feature of the project as it allows the user to create folders and move items on the stash KIO worker without touching the physical file system at all. Once a selection is curated on the KIO worker, it can be seamlessly copied to the physical filesystem. 0024 0025 The SFS is implemented using a QHash pair of the URL as a key, containing the location of the file on the SFS and the value containing a StashNodeData object which contains all the properties (such as file name, source, children files for directories) of a given node in SFS. 0026 0027 Memory use of the SFS is nominal on a per file basis - each file staged on the SFS requires roughly 300 bytes of memory. 0028 0029 ### Stash Daemon 0030 0031 The Stash File System runs in the KDE Daemon (kded5) container process. An object of the SFS is created on startup when the daemon is initialized. The daemon responds to calls from the KIO worker communicated over the session bus and creates and removes nodes in the SFS. 0032 0033 ## Installation 0034 0035 Make sure you have KF5 backports with all the [KDE dependency libraries](https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Install_the_dependencies) installed before you build! 0036 0037 Clone master to your favorite folder and run: 0038 0039 ``` 0040 mkdir build 0041 cd build 0042 cmake -DCMAKE_INSTALL_PREFIX=/usr -DKDE_INSTALL_USE_QT_SYS_PATHS=TRUE .. 0043 make 0044 sudo make install 0045 kdeinit5 0046 ``` 0047 0048 Adaptor classes for D-Bus were generated using: 0049 0050 ``` 0051 qdbuscpp2xml -a stashnotifier.h -o ../../dbus/org.kde.kio.StashNotifier.xml 0052 qdbusxml2cpp -c StashNotifierAdaptor -a stash_adaptor.h:stash_adaptor.cpp ../../dbus/org.kde.kio.StashNotifier.xml 0053 ```