hyprctl: improve help pages (#5385)

hyprctl/Strings.hpp

@@ -0,0 +1,158 @@
+#pragma once
+
+const std::string_view USAGE = R"#(usage: hyprctl [flags] <command> [args...|--help]
+
+commands:
+    activewindow        → Gets the active window name and its properties
+    activeworkspace     → Gets the active workspace and its properties
+    animations          → Gets the current config'd info about animations
+                          and beziers
+    binds               → Lists all registered binds
+    clients             → Lists all windows with their properties
+    configerrors        → Lists all current config parsing errors
+    cursorpos           → Gets the current cursor position in global layout
+                          coordinates
+    decorations <window_regex> → Lists all decorations and their info
+    devices             → Lists all connected keyboards and mice
+    dismissnotify [amount] → Dismisses all or up to AMOUNT notifications
+    dispatch <dispatcher> [args] → Issue a dispatch to call a keybind
+                          dispatcher with arguments
+    getoption <option>  → Gets the config option status (values)
+    globalshortcuts     → Lists all global shortcuts
+    hyprpaper ...       → Issue a hyprpaper request
+    instances           → Lists all running instances of Hyprland with
+                          their info
+    keyword <name> <value> → Issue a keyword to call a config keyword
+                          dynamically
+    kill                → Issue a kill to get into a kill mode, where you can
+                          kill an app by clicking on it. You can exit it
+                          with ESCAPE
+    layers              → Lists all the surface layers
+    layouts             → Lists all layouts available (including plugin'd ones)
+    monitors            → Lists active outputs with their properties,
+                          'monitors all' lists active and inactive outputs
+    notify ...          → Sends a notification using the built-in Hyprland
+                          notification system
+    output ...          → Allows you to add and remove fake outputs to your
+                          preferred backend
+    plugin ...          → Issue a plugin request
+    reload [config-only] → Issue a reload to force reload the config. Pass
+                          'config-only' to disable monitor reload
+    rollinglog          → Prints tail of the log
+    setcursor <theme> <size> → Sets the cursor theme and reloads the cursor
+                          manager
+    seterror <color> <message...> → Sets the hyprctl error string. Color has
+                          the same format as in colors in config. Will reset
+                          when Hyprland's config is reloaded
+    setprop ...         → Sets a window property
+    splash              → Get the current splash
+    switchxkblayout ... → Sets the xkb layout index for a keyboard
+    systeminfo          → Get system info
+    version             → Prints the hyprland version, meaning flags, commit
+                          and branch of build.
+    workspacerules      → Lists all workspace rules
+    workspaces          → Lists all workspaces with their properties
+
+flags:
+    -j                  → Output in JSON
+    -r                  → Refresh state after issuing command (e.g. for
+                          updating variables)
+    --batch             → Execute a batch of commands, separated by ';'
+    --instance (-i)     → use a specific instance. Can be either signature or
+                          index in hyprctl instances (0, 1, etc)
+
+--help:
+    Can be used to print command's arguments that did not fit into this page
+    (three dots))#";
+
+const std::string_view HYPRPAPER_HELP = R"#(usage: hyprctl [flags] hyprpaper <request>
+
+requests:
+    listactive      → Lists all active images
+    listloaded      → Lists all loaded images
+    preload <path>  → Preloads image
+    unload <path>   → Unloads image. Pass 'all' as path to unload all images
+    wallpaper       → Issue a wallpaper to call a config wallpaper dynamically
+
+flags:
+    See 'hyprctl --help')#";
+
+const std::string_view NOTIFY_HELP = R"#(usage: hyprctl [flags] notify <icon> <time_ms> <color> <message...>
+
+icon:
+    Integer of value:
+        0       → Warning
+        1       → Info
+        2       → Hint
+        3       → Error
+        4       → Confused
+        5       → Ok
+        6 or -1 → No icon
+
+time_ms:
+    Time to display notification in milliseconds
+
+color:
+    Notification color. Format is the same as for colors in hyprland.conf. Use
+    0 for default color for icon
+
+message:
+    Notification message
+
+flags:
+    See 'hyprctl --help')#";
+
+const std::string_view OUTPUT_HELP = R"#(usage: hyprctl [flags] output <create <backend> | remove <name>>
+
+create <backend>:
+    Creates new virtual output. Possible values for backend: wayland, x11,
+    headless or auto.
+
+remove <name>:
+    Removes virtual output. Pass the output's name, as found in
+    'hyprctl monitors'
+    
+flags:
+    See 'hyprctl --help')#";
+
+const std::string_view PLUGIN_HELP = R"#(usage: hyprctl [flags] plugin <request>
+
+requests:
+    load <path>     → Loads a plugin. Path must be absolute
+    unload <path>   → Unloads a plugin. Path must be absolute
+    list            → Lists all loaded plugins
+
+flags:
+    See 'hyprctl --help')#";
+
+const std::string_view SETPROP_HELP = R"#(usage: hyprctl [flags] setprop <regex> <property> <value> [lock]
+
+regex:
+    Regular expression by which a window will be searched
+
+property:
+    See https://wiki.hyprland.org/Configuring/Using-hyprctl/#setprop for list
+    of properties
+
+value:
+    Property value
+
+lock:
+    Optional argument. If lock is not added, will be unlocked. Locking means a
+    dynamic windowrule cannot override this setting.
+
+flags:
+    See 'hyprctl --help')#";
+
+const std::string_view SWITCHXKBLAYOUT_HELP = R"#(usage: [flags] switchxkblayout <device> <cmd>
+
+device:
+    You can find the device using 'hyprctl devices' command
+
+cmd:
+    'next' for next, 'prev' for previous, or ID for a specific one. IDs are
+    assigned based on their order in config file (keyboard_layout),
+    starting from 0
+
+flags:
+    See 'hyprctl --help')#";

hyprctl/main.cpp

@@ -24,49 +24,7 @@
 #include <stdarg.h>
 #include <regex>
 
-const std::string USAGE = R"#(usage: hyprctl [(opt)flags] [command] [(opt)args]
+#include "Strings.hpp"
-
-commands:
-    activewindow
-    activeworkspace
-    binds
-    clients
-    configerrors
-    cursorpos
-    decorations
-    devices
-    dismissnotify
-    dispatch
-    getoption
-    globalshortcuts
-    hyprpaper
-    instances
-    keyword
-    kill
-    layers
-    layouts
-    monitors
-    notify
-    output
-    plugin
-    reload
-    rollinglog
-    setcursor
-    seterror
-    setprop
-    splash
-    switchxkblayout
-    systeminfo
-    version
-    workspacerules
-    workspaces
-
-flags:
-    -j -> output in JSON
-    -r -> refresh state after issuing command (e.g. for updating variables)
-    --batch -> execute a batch of commands, separated by ';'
-    --instance (-i) -> use a specific instance. Can be either signature or index in hyprctl instances (0, 1, etc)
-)#";
 
 #define PAD
 
@@ -295,7 +253,7 @@ int main(int argc, char** argv) {
     bool parseArgs = true;
 
     if (argc < 2) {
-        printf("%s\n", USAGE.c_str());
+        std::cout << USAGE << std::endl;
         return 1;
     }
 
@@ -326,13 +284,33 @@ int main(int argc, char** argv) {
                 ++i;
 
                 if (i >= ARGS.size()) {
-                    printf("%s\n", USAGE.c_str());
+                    std::cout << USAGE << std::endl;
                     return 1;
                 }
 
                 overrideInstance = ARGS[i];
+            } else if (ARGS[i] == "--help") {
+                const std::string& cmd = ARGS[0];
+
+                if (cmd == "hyprpaper") {
+                    std::cout << HYPRPAPER_HELP << std::endl;
+                } else if (cmd == "notify") {
+                    std::cout << NOTIFY_HELP << std::endl;
+                } else if (cmd == "output") {
+                    std::cout << OUTPUT_HELP << std::endl;
+                } else if (cmd == "plugin") {
+                    std::cout << PLUGIN_HELP << std::endl;
+                } else if (cmd == "setprop") {
+                    std::cout << SETPROP_HELP << std::endl;
+                } else if (cmd == "switchxkblayout") {
+                    std::cout << SWITCHXKBLAYOUT_HELP << std::endl;
+                } else {
+                    std::cout << USAGE << std::endl;
+                }
+
+                return 1;
             } else {
-                printf("%s\n", USAGE.c_str());
+                std::cout << USAGE << std::endl;
                 return 1;
             }
 
@@ -343,7 +321,7 @@ int main(int argc, char** argv) {
     }
 
     if (fullRequest.empty()) {
-        printf("%s\n", USAGE.c_str());
+        std::cout << USAGE << std::endl;
         return 1;
     }
 
@@ -415,11 +393,11 @@ int main(int argc, char** argv) {
     else if (fullRequest.contains("/decorations"))
         request(fullRequest, 1);
     else if (fullRequest.contains("/--help"))
-        printf("%s", USAGE.c_str());
+        std::cout << USAGE << std::endl;
     else {
         request(fullRequest);
     }
 
-    printf("\n");
+    std::cout << std::endl;
     return exitStatus;
 }