From 7cb31ff224857dd5b6a7ffc177bd7c77c098a8bb Mon Sep 17 00:00:00 2001
From: Emil Kosz <ekosz@int.pl>
Date: Fri, 22 Nov 2024 18:50:28 +0100
Subject: [PATCH] Add preference categories, update the manual

---
 app/src/main/res/layout/activity_manual.xml | 15 +++--
 app/src/main/res/values/strings.xml         | 60 ++++++++++++-----
 app/src/main/res/xml/preferences.xml        | 72 ++++++++++++---------
 3 files changed, 94 insertions(+), 53 deletions(-)

diff --git a/app/src/main/res/layout/activity_manual.xml b/app/src/main/res/layout/activity_manual.xml
index e975ad0..10122da 100644
--- a/app/src/main/res/layout/activity_manual.xml
+++ b/app/src/main/res/layout/activity_manual.xml
@@ -16,10 +16,15 @@
   ~ along with this program.  If not, see <https://www.gnu.org/licenses/>.
   -->
 
-<TextView xmlns:android="http://schemas.android.com/apk/res/android"
-    android:id="@+id/manual_text"
+<ScrollView xmlns:android="http://schemas.android.com/apk/res/android"
     android:layout_width="match_parent"
-    android:layout_height="match_parent"
-    android:padding="@dimen/default_space">
+    android:layout_height="match_parent">
 
-</TextView>
\ No newline at end of file
+    <TextView
+        android:id="@+id/manual_text"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:padding="@dimen/default_space"
+        android:text="@string/app_name"
+        android:textSize="@dimen/default_text_size" />
+</ScrollView>
\ No newline at end of file
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index bd944f8..9c2e964 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -35,6 +35,10 @@
     </string>
     <string name="clip_default_text">Clip</string>
 
+    <string name="preferences_category_keyboard">Keyboard</string>
+    <string name="preferences_category_functionality">Functionality</string>
+    <string name="preferences_category_other">Other</string>
+
     <string name="preferences_label_cycle_manual">
         Cycle symbols by consecutively pressing a key
     </string>
@@ -57,24 +61,48 @@
 
     <string name="user_manual_html">
         <![CDATA[
-        <h1>Titanboard manual</h1>
-        <h2>First steps</h2>
+        <h1>Introduction</h1>
         <p>
-            Thank you for trying out Titanboard! There are a few things in this program that can
-            make your typing experience better. First, set up your settings to fit what you want:
+            Thank you for trying out Titanboard! This keyboard program is designed to make your
+            experience with physical keyboards as pleasant and powerful as possible. It was designed
+            to be intuitive, and work exactly as you would expect it to. This means that pressing
+            any key, with or without modifiers like Alt or Shift, will show the corresponding
+            character on the screen. For example, on the Unihertz Titan, pressing R will input
+            &quot;r&quot;, pressing Alt+R will input &quot;-&quot;, Shift+R will input
+            &quot;R&quot;. Whatever you see on your physical keyboard will show up on the screen.
+        </p>
+        <p>
+            However, on most physical keyboard devices, this makes it very hard to input characters
+            which aren&apos;t on it. For example, on the Unihertz Titan, it isn&apos;t possible to
+            input the &quot;&amp;&quot; symbol. The stock keyboard application solves this by using
+            an additional visual keyboard interface, but I think that misses the point. Instead,
+            Titanboard allows every symbol on the physical keyboard, even those with modifiers, to
+            have extra symbols. These are accessed by <i>cycling</i>.
+        </p>
+        <p>
+            <i>Cycling</i> is basically a method for accessing the extra symbols under a given key. By
+            default, this method is long pressing a key. For example, on the Unihertz Titan, the
+            ) key (Alt+Y) has four symbols: &quot;)&quot;, &quot;&gt;&quot;, &quot;]&quot;,
+            &quot;}&quot;. The first is inputted by simply pressing Alt, then Y (or Alt and Y). The
+            rest can be accessed by pressing Alt (or holding), then pressing and holding Y. This
+            will start switching through the aforementioned characters at the rate specified in the
+            preferences (by default 500 ms).
+        </p>
+        <p>
+            There is an alternate cycling method which can be enabled under the &quot;Cycle symbols
+            by consecutively pressing a key&quot; setting in the preferences. This is
+            self-explanatory. Instead of long pressing like in the aforementioned example, you
+            instead quickly press the key several times. So, if I want to input &quot;]&quot;, I
+            press Alt, then I press Y three times. This is very good for fast typing.
+        </p>
+        <p>
+            If you tried the above, you might have noticed that the Alt or Shift keys can be
+            &quot;locked&quot; (or latched). This is the same behaviour like in regular visual
+            keyboards Android. Simply put, pressing a modifier key once puts it into a latched
+            state, which means the next key pressed will be uppercased or be the alternative symbol.
+            You can also lock a modifier key by pressing it twice in a quick fashion. Otherwise,
+            modifier keys work as expected.
         </p>
-        <ol>
-            <li>
-                Pick your device from the device list. This will make sure that all characters on
-                the physical keyboard can be used, such as alt symbols.
-            </li>
-            <li>Pick the languages you use from the language list</li>
-            <li>
-                Choose your symbol inputting method. This applies to alphabetic and twelve key
-                keyboards only, as full keyboards use the shift and alt keys to access alternate
-                symbols.
-            </li>
-        </ol>
         ]]>
     </string>
 </resources>
\ No newline at end of file
diff --git a/app/src/main/res/xml/preferences.xml b/app/src/main/res/xml/preferences.xml
index f3ae1d7..4c27d55 100644
--- a/app/src/main/res/xml/preferences.xml
+++ b/app/src/main/res/xml/preferences.xml
@@ -19,36 +19,44 @@
 
 <!--suppress DeprecatedClassUsageInspection -->
 <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">
-    <SwitchPreference
-        android:defaultValue="@bool/cycle_manual_default"
-        android:key="@string/preferences_key_cycle_manual"
-        android:summary="@string/preferences_summary_cycle_manual"
-        android:title="@string/preferences_label_cycle_manual" />
-    <ListPreference
-        android:defaultValue="@string/cycle_speed_default"
-        android:disableDependentsState="true"
-        android:entries="@array/preferences_cycle_speed_labels"
-        android:entryValues="@array/preferences_cycle_speeds"
-        android:key="@string/preferences_key_cycle_speed"
-        android:title="@string/preferences_label_cycle_speed" />
-    <ListPreference
-        android:defaultValue="@string/clipboard_size_default"
-        android:entries="@array/preferences_clipboard_size_labels"
-        android:entryValues="@array/preferences_clipboard_sizes"
-        android:key="@string/preferences_key_clipboard_size"
-        android:title="@string/preferences_label_clipboard_size" />
-    <MultiSelectListPreference
-        android:defaultValue="@array/preferences_keymap_defaults"
-        android:entries="@array/preferences_keymap_labels"
-        android:entryValues="@array/preferences_keymaps"
-        android:key="@string/preferences_key_keymaps"
-        android:title="@string/preferences_label_keymaps" />
-    <Preference android:title="@string/preferences_label_user_manual">
-        <intent
-            android:action="eur.cfpifpsi.titanboard.intent.SHOW_MANUAL"
-            android:targetClass="eur.cfpifpsi.titanboard.activities.ManualActivity" />
-    </Preference>
-    <Preference
-        android:selectable="false"
-        android:summary="@string/preferences_summary_copyright_info" />
+    <PreferenceCategory android:title="@string/preferences_category_keyboard">
+
+        <MultiSelectListPreference
+            android:defaultValue="@array/preferences_keymap_defaults"
+            android:entries="@array/preferences_keymap_labels"
+            android:entryValues="@array/preferences_keymaps"
+            android:key="@string/preferences_key_keymaps"
+            android:title="@string/preferences_label_keymaps" />
+    </PreferenceCategory>
+    <PreferenceCategory android:title="@string/preferences_category_functionality">
+
+        <SwitchPreference
+            android:defaultValue="@bool/cycle_manual_default"
+            android:key="@string/preferences_key_cycle_manual"
+            android:summary="@string/preferences_summary_cycle_manual"
+            android:title="@string/preferences_label_cycle_manual" />
+        <ListPreference
+            android:defaultValue="@string/cycle_speed_default"
+            android:disableDependentsState="true"
+            android:entries="@array/preferences_cycle_speed_labels"
+            android:entryValues="@array/preferences_cycle_speeds"
+            android:key="@string/preferences_key_cycle_speed"
+            android:title="@string/preferences_label_cycle_speed" />
+        <ListPreference
+            android:defaultValue="@string/clipboard_size_default"
+            android:entries="@array/preferences_clipboard_size_labels"
+            android:entryValues="@array/preferences_clipboard_sizes"
+            android:key="@string/preferences_key_clipboard_size"
+            android:title="@string/preferences_label_clipboard_size" />
+    </PreferenceCategory>
+    <PreferenceCategory android:title="@string/preferences_category_other">
+        <Preference android:title="@string/preferences_label_user_manual">
+            <intent
+                android:action="eur.cfpifpsi.titanboard.intent.SHOW_MANUAL"
+                android:targetClass="eur.cfpifpsi.titanboard.activities.ManualActivity" />
+        </Preference>
+        <Preference
+            android:selectable="false"
+            android:summary="@string/preferences_summary_copyright_info" />
+    </PreferenceCategory>
 </PreferenceScreen>
\ No newline at end of file