From 5f43d4a86ce0af441b9c9df40d37bf6efc89773c Mon Sep 17 00:00:00 2001 From: Ivailo Monev Date: Sun, 12 May 2024 05:50:54 +0300 Subject: [PATCH] kio: KRun documentation update other misc changes were made while at it, .gitexcludes had executable bit set.. Signed-off-by: Ivailo Monev --- .gitexcludes | 0 kinit/README.autostart | 39 --------------------------- kio/DESIGN.mimetypes | 37 ------------------------- kio/kio/krun.h | 61 +++++++++++++----------------------------- 4 files changed, 18 insertions(+), 119 deletions(-) mode change 100755 => 100644 .gitexcludes delete mode 100644 kinit/README.autostart delete mode 100644 kio/DESIGN.mimetypes diff --git a/.gitexcludes b/.gitexcludes old mode 100755 new mode 100644 diff --git a/kinit/README.autostart b/kinit/README.autostart deleted file mode 100644 index f0735368..00000000 --- a/kinit/README.autostart +++ /dev/null @@ -1,39 +0,0 @@ -KDE SESSION AUTOSTART -===================== - -KDE session startup occurs in the following sequence: - - Window manager startup - Autostart phase 1 - Session restoration - Autostart phase 2 - -Applications may be scheduled to be automatically run at KDE session startup -in either autostart phase 1 or phase 2. Autostart phase 1 is the original -autostart phase; phase 2 was introduced in KDE 3. To run in either phase, an -application's .desktop file must be located in a KDE autostart directory such -as $KDEDIR/share/autostart or $KDEHOME/share/autostart. The .desktop file can -contain the following optional entries to control its autostart: - - X-KDE-autostart-phase = phase - - phase = 1 or 2 - - Starts the application in the autostart phase specified by 'phase'. - If this entry is missing or 'phase' < 1, 'phase' defaults to 1. If - 'phase' > 2 the application will not be autostarted since the specified - autostart phase will never be reached. - - - Hidden = true - - Disables autostarting the application. - - -KUniqueApplication and session restoration ------------------------------------------- - -If KUniqueApplication applications are autostarted before they are restored -from the previous session, they will never see the session restoration command. -So if you need to autostart a KUniqueApplication which may also be restored -in session restoration, you should schedule it for autostart in phase 2. diff --git a/kio/DESIGN.mimetypes b/kio/DESIGN.mimetypes deleted file mode 100644 index 851fa319..00000000 --- a/kio/DESIGN.mimetypes +++ /dev/null @@ -1,37 +0,0 @@ -TODO: servicetypes -TODO: mimetypes - -Service type inheritance (X-KDE-Derived) -======================================== -X-KDE-Derived is for service types. ST1 derives from ST2 means ST1 is more specific than ST2. -If a service implements ST1, it also implements ST2, but not the other way round. - -For instance, KoDocument derives from KParts/ReadWritePart, which derives from KParts/ReadOnlyPart, -so KWord's part (which implements KoDocument) can be used as a readonly viewer for KWord files -in Konqueror (which looks for a KParts/ReadOnlyPart). - -Mimetype "inheritance" -====================== -We need a mechanism to also say that "text/xml is a special case of text/plain", -or "text/docbook is a kind of text/sgml", or "application/x-smb-workgroup is a kind -of inode/directory", etc. See below. - -Why mimetype "inheritance" doesn't use X-KDE-Derived -==================================================== -The confusing thing is that we said "a mimetype is a servicetype". But that's not exactly correct. -As Waldo noted, "the ability to open a mimetype" is what's a servicetype. -So if text/xml said X-KDE-Derived=text/plain (i.e. ST1=text/xml, ST2=text/plain), -then an application opening text/xml (ST1) would end up being associated with any text/plain (ST2) file, -which would be wrong. - -We want the other way round: to be able to open special kinds of text/plain in a plain text editor. -This is what X-KDE-IsAlso was introduced for. X-KDE-IsAlso kind of "works the other way" than X-KDE-Derived. -If M1 is a special kind of M2 (mimetypes), then "the ability to open M2" derives from "the ability to open M1" -The ability to open any text/plain file derives (is more specific than) the ability to open text/xml only. - -So we say in text/xml: X-KDE-IsAlso=text/plain, and applications that can open text/plain can also open text/xml. - -Pattern Accuracy -====================== -In some cases of inheritance several mimetypes shares the same extension (with the primary case being Ogg Multimedia files). -This has been solved sofar by matching the extension to most generic mimetype. To indicate that the mimetype can be refined further, the flag X-KDE-PatternsAccuracy can be set. The value to X-KDE-PatternsAccuracy is a number between 0-100, with 100 being the default if not set. Any values below 100 is interpreted as the possibility of further mimetype refinement. diff --git a/kio/kio/krun.h b/kio/kio/krun.h index 6a786fe8..79357228 100644 --- a/kio/kio/krun.h +++ b/kio/kio/krun.h @@ -29,72 +29,47 @@ class KRunPrivate; /** - * To open files with their associated applications in KDE, use KRun. - * - * It can execute any desktop entry, as well as any file, using - * the default application or another application "bound" to the file type - * (or URL protocol). - * - * In that example, the mimetype of the file is not known by the application, - * so a KRun instance must be created. It will determine the mimetype by itself. - * If the mimetype is known, or if you even know the service (application) to - * use for this file, use one of the static methods. - * - * By default KRun uses auto deletion. It causes the KRun instance to delete - * itself when the it finished its task. If you allocate the KRun - * object on the stack you must disable auto deletion, otherwise it will crash. - * - * @short Opens files with their associated applications in KDE + * KRun provides utility methods for running services and applications */ class KIO_EXPORT KRun { public: /** - * Display the Open-With dialog for those URLs, and run the chosen application. - * @param urls the list of applications to run - * @param window The top-level widget of the app that invoked this object. - * @param tempFiles if true and lst are local files, they will be deleted - * when the application exits. + * Display the Open-With dialog for URLs and run the chosen application + * + * @param urls the list of URLs to run + * @param window the top-level widget of the application, if any + * @param temp if true any local file URL will be deleted when the application exits * @return false if the dialog was canceled */ - static bool displayOpenWithDialog(const KUrl::List &urls, QWidget* window, - bool tempFiles = false); + static bool displayOpenWithDialog(const KUrl::List &urls, QWidget *window, bool temp = false); /** - * Processes a Exec= line as found in .desktop files. - * @param service the service to extract information from. - * @param urls The urls the service should open. + * Processes a Exec= line as found in .desktop files * - * @return a list of arguments suitable for KProcess::setProgram(). + * @param service the service to extract information from + * @param urls the urls the service should open + * @return a list of arguments suitable for KProcess::setProgram() */ static QStringList processDesktopExec(const KService &service, const KUrl::List &urls); /** - * Given a full command line (e.g. the Exec= line from a .desktop file), - * extract the name of the binary being run. + * Given a full command line (e.g. the Exec= line from a .desktop file), extracts the name of + * the binary being run. + * * @param execLine the full command line - * @param removePath if true, remove a (relative or absolute) path. E.g. /usr/bin/ls becomes ls. + * @param removePath if true, remove a (relative or absolute) path. e.g. /usr/bin/ls becomes ls * @return the name of the binary to run */ static QString binaryName(const QString &execLine, bool removePath); /** - * Returns whether @p serviceType refers to an executable program instead - * of a data file. + * Returns whether @p mimeType refers to an executable program */ - static bool isExecutable(const QString &serviceType); + static bool isExecutable(const QString &mimeType); /** - * Returns whether the @p url of @p mimetype is executable. - * To be executable the file must pass the following rules: - * -# Must reside on the local filesystem. - * -# Must be marked as executable for the user by the filesystem. - * -# The mime type must inherit application/x-executable or application/x-executable-script. - * To allow a script to run when the above rules are satisfied add the entry - * @code - * X-KDE-IsAlso=application/x-executable-script - * @endcode - * to the mimetype's desktop file. + * Returns whether the @p url of @p mimetype is executable */ static bool isExecutableFile(const KUrl &url, const QString &mimetype);