[plasma/bluedevil] /: Add basic documentation
Nicolas Fella
null at kde.org
Mon Jun 6 14:37:39 BST 2022
Git commit 84c3bbe4d4bf913f7d0da3a925d997df111603d2 by Nicolas Fella, on behalf of Yuri Chornoivan.
Committed on 06/06/2022 at 13:37.
Pushed by nicolasfella into branch 'master'.
Add basic documentation
BUGS: 454602
M +1 -0 .kde-ci.yml
M +3 -0 CMakeLists.txt
A +3 -0 doc/CMakeLists.txt
A +- -- doc/bluetooth-add.png
A +- -- doc/bluetooth-configure.png
A +- -- doc/bluetooth-kcm.png
A +- -- doc/bluetooth-phone.png
A +- -- doc/bluetooth-tray.png
A +239 -0 doc/index.docbook
A +- -- doc/list-remove.png
A +- -- doc/network-connect.png
A +- -- doc/network-disconnect.png
M +1 -1 src/kcm/bluetooth.cpp
https://invent.kde.org/plasma/bluedevil/commit/84c3bbe4d4bf913f7d0da3a925d997df111603d2
diff --git a/.kde-ci.yml b/.kde-ci.yml
index fcf1ede7..ab70b8da 100644
--- a/.kde-ci.yml
+++ b/.kde-ci.yml
@@ -15,6 +15,7 @@ Dependencies:
'frameworks/kcoreaddons': '@latest'
'frameworks/kdbusaddons': '@latest'
'frameworks/kdeclarative': '@latest'
+ 'frameworks/kdoctools': '@latest'
'frameworks/ki18n': '@latest'
'frameworks/kio': '@latest'
'frameworks/kitemviews': '@latest'
diff --git a/CMakeLists.txt b/CMakeLists.txt
index f9b5104a..fc175d8b 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -25,6 +25,7 @@ find_package(KF5 ${KF5_MIN_VERSION} REQUIRED COMPONENTS
CoreAddons
WidgetsAddons
DBusAddons
+ DocTools
Notifications
WindowSystem
Plasma
@@ -74,3 +75,5 @@ ecm_qt_install_logging_categories(
FILE bluedevil.categories
DESTINATION ${KDE_INSTALL_LOGGINGCATEGORIESDIR}
)
+
+add_subdirectory(doc)
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
new file mode 100644
index 00000000..a2e2126f
--- /dev/null
+++ b/doc/CMakeLists.txt
@@ -0,0 +1,3 @@
+kdoctools_create_handbook(index.docbook
+ INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en
+ SUBDIR kcontrol/bluedevil)
diff --git a/doc/bluetooth-add.png b/doc/bluetooth-add.png
new file mode 100644
index 00000000..58ccaab9
Binary files /dev/null and b/doc/bluetooth-add.png differ
diff --git a/doc/bluetooth-configure.png b/doc/bluetooth-configure.png
new file mode 100644
index 00000000..595a87ff
Binary files /dev/null and b/doc/bluetooth-configure.png differ
diff --git a/doc/bluetooth-kcm.png b/doc/bluetooth-kcm.png
new file mode 100644
index 00000000..eb8b8e93
Binary files /dev/null and b/doc/bluetooth-kcm.png differ
diff --git a/doc/bluetooth-phone.png b/doc/bluetooth-phone.png
new file mode 100644
index 00000000..14bcf5a6
Binary files /dev/null and b/doc/bluetooth-phone.png differ
diff --git a/doc/bluetooth-tray.png b/doc/bluetooth-tray.png
new file mode 100644
index 00000000..8991126e
Binary files /dev/null and b/doc/bluetooth-tray.png differ
diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 00000000..fea6db25
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,239 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY bluetooth "<application>Bluetooth</application>">
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article id="bluedevil" lang="&language;">
+ <articleinfo>
+ <title>Bluedevil</title>
+ <authorgroup>
+ <author><firstname>Yuri</firstname><surname>Chornoivan</surname>
+ <email>yurchor at ukr.net</email></author>
+ <!-- TRANS:ROLES_OF_TRANSLATORS -->
+ </authorgroup>
+
+ <date>2022-06-05</date>
+ <releaseinfo>Plasma 5.25</releaseinfo>
+
+ <keywordset>
+ <keyword>KDE</keyword>
+ <keyword>Systemsettings</keyword>
+ <keyword>bluetooth</keyword>
+ <keyword>phone</keyword>
+ <keyword>headphones</keyword>
+ <keyword>earphones</keyword>
+ <keyword>modem</keyword>
+ <keyword>computer</keyword>
+ <keyword>headset</keyword>
+ <keyword>multimedia</keyword>
+ <keyword>device</keyword>
+ <keyword>keyboard</keyword>
+ <keyword>mouse</keyword>
+ <keyword>joypad</keyword>
+ <keyword>tablet</keyword>
+ <keyword>camera</keyword>
+ <keyword>printer</keyword>
+ <keyword>imaging</keyword>
+ <keyword>wearable</keyword>
+ <keyword>toy</keyword>
+ <keyword>health</keyword>
+ <keyword>peripheral</keyword>
+ <keyword>network</keyword>
+ </keywordset>
+ </articleinfo>
+
+ <sect1 id="kcmbluetooth">
+ <title>Bluetooth</title>
+
+ <para>
+ On this page you can configure your Bluetooth devices for the &plasma; Workspace.
+ </para>
+
+ <note>
+ <para>
+ Please press the <guibutton>Enable</guibutton> button to enable the &bluetooth; subsystem in your operating system.
+ </para>
+ </note>
+ <screenshot>
+ <screeninfo>&bluetooth; &systemsettings; module</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bluetooth-kcm.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>&bluetooth; &systemsettings; module</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ Press the <guibutton>Configure...</guibutton> button to change the general &bluetooth; settings for your &plasma; Workspace.
+ </para>
+
+ <screenshot>
+ <screeninfo>Configuring the general module settings</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bluetooth-configure.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>Configuring the general module settings</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ You can make your &bluetooth; device <guilabel>Enabled</guilabel> and <guilabel>Visible</guilabel> for other &bluetooth; devices with the corresponding items.
+ </para>
+
+ <para>
+ It is possible to change the &bluetooth; subsystem behavior on receiving file. Your &plasma; Workspace can <guilabel>Ask for confirmation</guilabel>, <guilabel>Accept for trusted devices</guilabel> (see the <guilabel>Trusted</guilabel> in the device settings below) and <guilabel>Always accept</guilabel> the sent files. You can also configure the folder to store the received files.
+ </para>
+
+ <para>
+ Please press the back button at the top of the page to return to the main page of the configuration module.
+ </para>
+
+ <para id="adddevice">
+ You can add a &bluetooth; device to the main list by clicking the <guibutton>Add...</guibutton>
+ button. Your neighborhood will be scanned for available devices. If the device you want to use is
+ not shown in the scanning list then you will need to consult its manual for the instructions on how to set it up.
+ </para>
+
+ <para>
+ Configure the <guilabel>Manual PIN</guilabel> if needed and <mousebutton>left</mousebutton>-click on the detected device to pair it with your computer. See the device manual on the procedure of pairing, the mileadge may vary but usually, it is very straightforward.
+ </para>
+
+ <screenshot>
+ <screeninfo>Adding &bluetooth; device</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bluetooth-add.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>Adding &bluetooth; device</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ <mousebutton>Left</mousebutton>-click on the list item to configure its name in the devices list and make it <guilabel>Trusted</guilabel> and <guilabel>Blocked</guilabel>.
+ </para>
+
+ <screenshot>
+ <screeninfo>Device settings</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bluetooth-phone.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>Device settings</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ Please press the back button at the top of the page to return to the main page of the configuration module.
+ </para>
+
+ <para>
+ When hovering with the mouse cursor, every &bluetooth; device in the main list shows two buttons on the right.
+ </para>
+
+ <para>
+ Use <guiicon><inlinemediaobject><imageobject><imagedata fileref="network-connect.png" format="PNG"/></imageobject></inlinemediaobject></guiicon> or <guiicon><inlinemediaobject><imageobject><imagedata fileref="network-disconnect.png" format="PNG"/></imageobject></inlinemediaobject></guiicon> to connect or disconnect a device.
+ </para>
+
+ <para>
+ You can remove a device from the main list by selecting it and then clicking on the <inlinemediaobject><imageobject><imagedata fileref="list-remove.png" format="PNG"/></imageobject></inlinemediaobject> icon.
+ </para>
+
+ <para>
+ If you need to switch &bluetooth; off for some reason press the <guibutton>Disable &bluetooth;</guibutton> button.
+ </para>
+
+ </sect1>
+
+ <sect1 id="system-tray">
+ <title>System Tray Operation</title>
+
+ <note>
+ <para>
+ You must be running the &plasma; desktop or another suitable window manager in order to display &bluetooth; in the system tray.
+ </para>
+ </note>
+
+ <para>The &bluetooth; module by default displays an icon in the system tray. The icon
+ provides both control and monitoring status indications. A
+ normal &bluetooth; icon indicates that all devices are disconnected,
+ while the icon with the horizontal dotted line indicates that
+ some devices are connected to your computer.
+ </para>
+
+ <para>
+ If you hover the mouse cursor over the system tray icon, a
+ summary of the connected device list is displayed as a tooltip.
+ </para>
+
+ <para>
+ <mousebutton>Left</mousebutton>-click on the system tray icon to
+ toggle between displaying and hiding the <link linkend="controlpanel">&bluetooth; main control panel</link>.
+ </para>
+
+ <para>
+ <mousebutton>Right</mousebutton>-click on the system tray icon to
+ display its context menu with just one item:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><menuchoice><guimenuitem>Configure &bluetooth;</guimenuitem></menuchoice></term>
+ <listitem><para><action>Starts the <link linkend="kcmbluetooth">&plasma; &bluetooth; configuration module</link>.</action></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect2 id="controlpanel">
+ <title>The &bluetooth; main control panel</title>
+
+ <para>
+ The &bluetooth; main control panel can be used to control your computer's &bluetooth; subsystem.
+ </para>
+
+ <screenshot>
+ <screeninfo>&bluetooth; tray control panel</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bluetooth-tray.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>&bluetooth; tray control panel</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ The top row of the panel contains the &bluetooth; switcher to enable or disable the &bluetooth; module, the <quote>plus</quote> button to <link linkend="adddevice">add &bluetooth; devices</link>, and the <quote>configure</quote> button to start the <link linkend="kcmbluetooth">&plasma; &bluetooth; configuration module</link>.
+ </para>
+
+ <para>
+ The main space of the panel is devoted to the paired devices.
+ </para>
+ <para>
+ Use <guiicon><inlinemediaobject><imageobject><imagedata fileref="network-connect.png" format="PNG"/></imageobject></inlinemediaobject></guiicon> or <guiicon><inlinemediaobject><imageobject><imagedata fileref="network-disconnect.png" format="PNG"/></imageobject></inlinemediaobject></guiicon> to connect or disconnect a device.
+ </para>
+
+ <para>
+ Click on the <guilabel>v</guilabel> button at the right of the device item to expand its properties.
+ </para>
+
+ <para>
+ The <guibutton>Send file...</guibutton> button will be shown only if the corresponding device is connected and ready to receive files. This feature may need some additional software to be installed. If needed, please follow the instructions and consult your distribution documentation.
+ </para>
+
+ </sect2>
+ </sect1>
+
+</article>
diff --git a/doc/list-remove.png b/doc/list-remove.png
new file mode 100644
index 00000000..873b2071
Binary files /dev/null and b/doc/list-remove.png differ
diff --git a/doc/network-connect.png b/doc/network-connect.png
new file mode 100644
index 00000000..7e26137d
Binary files /dev/null and b/doc/network-connect.png differ
diff --git a/doc/network-disconnect.png b/doc/network-disconnect.png
new file mode 100644
index 00000000..962ab2af
Binary files /dev/null and b/doc/network-disconnect.png differ
diff --git a/src/kcm/bluetooth.cpp b/src/kcm/bluetooth.cpp
index d1d5aef9..30062ca6 100644
--- a/src/kcm/bluetooth.cpp
+++ b/src/kcm/bluetooth.cpp
@@ -28,7 +28,7 @@ K_PLUGIN_CLASS_WITH_JSON(Bluetooth, "bluetooth.json")
Bluetooth::Bluetooth(QObject *parent, const KPluginMetaData &data, const QVariantList &args)
: KQuickAddons::ConfigModule(parent, data, args)
{
- setButtons(KQuickAddons::ConfigModule::NoAdditionalButton);
+ setButtons(Help);
qmlRegisterAnonymousType<QAbstractItemModel>("org.kde.bluedevil.kcm", 1);
qmlRegisterSingletonInstance("org.kde.bluedevil.kcm", 1, 0, "FileReceiverSettings", FileReceiverSettings::self());
More information about the kde-doc-english
mailing list