Documentation improvements. Small improvements to window flashing. Still issues with portal chrome not being cleaned up on layout change.

Author: groboclown

CHANGES.md

@@ -7,6 +7,8 @@
 * Added "resizable" flag for applications.
 * Added "snap" option to portals.
 * detect-monitors command now supports different output formats.
+* Added user extensions directory support.
+* Changed how you specify the layout argument at the command line.
 * Documentation improvements.
 * Bug fixes.
 
@@ -28,6 +30,18 @@
     * Run with "-f (format)" to output in a different format.
     * Supported formats are: `yaml`, `json`, and `py`.
     * Format now defaults to `yaml` instead of python.
+* Added user extensions directory support.
+    * You can either use the `%PETRONIA_USER_DIR%` environment variable, or
+        the `-e` command-line argument, to specify where Petronia should look
+        for user extensions.  This allows for adding in components to your
+        configuration.
+* Changed how you specify the layout argument at the command line.
+    * It used to be that the layout name was the optional second argument.  Now,
+        you must specify it with the `-l` or `--layout` argument.
+    * The check-layout command is unchanged.
+    * Command-line parsing for cmd and main now use argparse to grant the
+        ability to have more complex arguments.  Unfortunately, this lead to
+        the backwards incompatibility with the layout name.
 * Documentation improvements.
     * Cleaning up to better reflect the current version.
 * Bug fixes.

README.md

@@ -115,7 +115,7 @@ Once you have your configuration setup, you just run in a cmd prompt:
 ```cmd
 > set Path=(python 3.5.2 directory);%Path%
 > cd (petronia dir)\src
-> python -u -m petronia.cmd my_config_file.py
+> python -u -m petronia.cmd my_config_file.yaml
 ```
 
 Press <kbd>&crarr; Enter</kbd> in the command window to stop the program.

docs/README.md

@@ -1,6 +1,7 @@
 # Words for Users
 
 * [Getting Started](user-getting-started.md)
+* [Guide to Executables](user-execs.md)
 * Configuration:
     * [Configuration Guide](user-configuration.md)
     * [Configuration Through Python](user-configuration-py.md)

docs/dev-distribution.md

@@ -2,6 +2,13 @@
 
 Petronia has been designed to be a simple to distribute project.
 
+## Release Preparation
+
+1. Make sure `version.py` is set to the right version number.
+2. Make sure all commits are in github.
+3. CHANGES.md has the change notes for the version.
+
+
 ## Source Release
 
 Some users are okay with installing and running Python.  For those them, they
@@ -29,4 +36,5 @@ In a command prompt, you would run:
 ```
 
 This will create the `buildsrc\work\petronia-x86.zip` and
-`buildsrc\work\petronia-x64.zip` files.
+`buildsrc\work\petronia-x64.zip` files.  Rename these to include the
+version number (like `petronia-3.4-x64.zip`).

docs/user-custom-commands.md

@@ -1,5 +1,29 @@
 
-## Custom Commands
+# Custom Commands
+
+The hotkeys allow for running commands, but these commands are limited to
+the built-in set of commands provided by Petronia.  However, it is possible
+to write your own commands.
+
+Additional commands are added to the configuration, and can be referenced
+by the hotkey configuration like any other built-in command.
+
+
+## Adding Commands through Plugins
+
+If you're using the [components](user-components.md), you can add in a
+singleton component that registers new commands.
+
+The plugins themselves would add in the command to the configuration object
+passed to the `get_factory` function, as `config.commands.add_command(cmd)`.
+
+
+## Adding Commands through the Python Configuration
+
+*TODO* This is described below, but needs to be restructured.
+
+
+## Writing Commands
 
 The *command* configuration object (`CommandConfig`) allows for registering
 custom commands.  Each command must be a `petronia.script.command.Command`
@@ -24,10 +48,10 @@ base_config.add_command(Command('set-log-level', change_log_level))
 Then you can write a hotkey definition:
 
 ```
-alt + shift + f1 => set-log-level debug
+"alt + shift + f1": ['set-log-level', 'debug']
 ```
 
-If you're writing a command that interacts with the interworkings of Petronia,
+If you're writing a command that interacts with the inner workings of Petronia,
 then you'll have to send signals through the event bus.
 
 If you really want to get funky, you can reach into the bowels of the winapi

docs/user-execs.md

@@ -0,0 +1,73 @@
+# Guide to the Executables
+
+Petronia supplies several executable files.  This tells you what they do, and
+how to use them.
+
+
+## `petronia.exe` and `petronia-cli.exe`
+
+**Usage:** `petronia [-h] [-l LAYOUT] [-v] [-e EXTENSIONS] configfile`
+
+Window tiling manager for Windows.
+
+The `petronia-cli` is identical to `petronia`, but runs as a terminal program,
+for easier monitoring.  Additionally, you need to press <kbd>&crarrow; Enter</kbd> in
+the console window to end the program.
+
+**Positional arguments:**
+
+* `configfile` - Configuration file for setting up the display.
+    Supported formats are: yaml, json, and py.
+
+**Optional arguments:**
+
+* `-h`, `--help` - Show this help message and exit
+* `-l` LAYOUT, `--layout` LAYOUT - Initial layout. If not given, the layout
+    named `default` is used.
+* `-v`, `--version` - Show the version and quit.
+* `-e` EXTENSIONS, `--extensions` EXTENSIONS - Directory where the user
+    extensions are stored.  Defaults to environment variable `%PETRONIA_USER_DIR%`
+
+**Python Source**
+
+* `petronia.exe` == `python -m petronia.main`
+* `petronia-cli.exe` == `python -m petronia.cmd`
+
+
+## `detect-apps.exe`
+
+**Usage:** `detect-apps`
+
+A cli application.
+
+Displays the information that Petronia uses to match applications against the
+[application configuration](user-configuration.md#application-configuration).
+
+
+## `detect-monitors.exe`
+
+**Usage:** `detect-monitors [-f {yaml|json|py}]`
+
+A cli application.
+
+Displays information, in the given format (defaults to `yaml`), about the
+currently active monitors connected to your computer.  If you are running in
+a remote desktop environment, it will display information about the remote
+desktop display.
+
+**Optional arguments:**
+
+* `-f` - Set the output format, for easy cut-and-paste into your configuration
+    file.  Acceptable formats are `yaml`, `json`, and `py`.
+    
+
+## `detect-keys.exe`
+
+**Usage:** `detect-keys`
+
+A cli application.
+
+Reports the key names, as known by Petronia for use in the
+[hotkey configuration](user-configuration.md#hotkey-configuration).
+
+Press <kbd>&#x2732; Ctrl</kbd><kbd>C</kbd> to stop the application.

docs/user-extending.md

@@ -325,10 +325,14 @@ def window__wait_gui_thread_idle(hwnd):
 
 
 def window__send_message(hwnd, key, arg1, arg2):
+    if _attach_message_queue_to_thread(hwnd):
+        return True
     return windll.user32.SendMessageW(hwnd, key, arg1, arg2)
 
 
 def window__post_message(hwnd, key, arg1, arg2):
+    if _attach_message_queue_to_thread(hwnd):
+        return True
     res = windll.user32.PostMessageW(hwnd, key, arg1, arg2)
     return res != 0
 
@@ -540,8 +544,8 @@ def window__activate(hwnd):
     # if the results are non-zero.  Some of these will not succeed due to
     # attributes of the window, rather than the window not existing.
     windll.user32.SetWindowPos(hwnd, HWND_NOTOPMOST, 0, 0, 0, 0, SWP_NOSIZE | SWP_NOMOVE)
-    windll.user32.SetForegroundWindow(hwnd)
     windll.user32.AttachThreadInput(thread_process_id, current_thread_id, False)
+    windll.user32.SetForegroundWindow(hwnd)
     windll.user32.SetFocus(hwnd)
     windll.user32.SetActiveWindow(hwnd)
     return True
@@ -1406,3 +1410,17 @@ def process__get_window_state(thread_pid):
 
 def process__get_current_pid():
     return windll.kernel32.GetCurrentProcessId()
+
+
+def _attach_message_queue_to_thread(current_hwnd):
+    current_thread_id = windll.kernel32.GetCurrentThreadId()
+    thread_process_id = windll.user32.GetWindowThreadProcessId(current_hwnd, None)
+    if thread_process_id != current_thread_id:
+        res = windll.user32.AttachThreadInput(thread_process_id, current_thread_id, True)
+        # ERROR_INVALID_PARAMETER means that the two threads are already attached.
+        if res == 0 and GetLastError() != ERROR_INVALID_PARAMETER:
+            # TODO better logging
+            print("WARN: could not attach thread input to thread {0} ({1})".format(thread_process_id, GetLastError()))
+            return True
+    windll.user32.AttachThreadInput(thread_process_id, current_thread_id, False)
+    return False

src/petronia/arch/funcs_any_win.py

@@ -14,8 +14,11 @@
 from petronia.script.read_config import read_user_configuration
 from petronia.tests.bus_logger import log_events
 from petronia.script.script_logger import create_stdout_logger
+from petronia.version import VERSION
 
 import sys
+import os
+import argparse
 
 
 def setup(config_file, layout_name):
@@ -40,15 +43,51 @@ def setup(config_file, layout_name):
 
 
 def main_setup():
-    if len(sys.argv) <= 1:
-        print("Usage: arg 1: the user configuration file")
-        sys.exit(1)
-
-    layout_name = None
-    if len(sys.argv) >= 3:
-        layout_name = sys.argv[2]
-
-    setup(sys.argv[1], layout_name)
+    parser = argparse.ArgumentParser()
+    parser.description = "Window tiling manager for Windows."
+    parser.add_argument(
+        "configfile",
+        help="Configuration file for setting up the display.  Supported formats are: yaml, json, and py.")
+    parser.add_argument(
+        "-l", "--layout",
+        required=False,
+        help="Initial layout.  If not given, the layout named `default' is used.")
+    parser.add_argument(
+        "-v", "--version",
+        help="Show the version and quit.",
+        action="store_true"
+    )
+    parser.add_argument(
+        "-e", "--extensions",
+        help="Directory where the user extensions are stored.  Defaults to environment variable %%PETRONIA_USER_DIR%%"
+    )
+
+    # argparse doesn't allow for the "-v" by itself.
+    for arg in sys.argv[1:]:
+        if arg == '-v' or arg == '--version':
+            parser.exit(message="Petronia v{0}\nRunning Python {1}".format(VERSION, sys.version))
+
+    args = parser.parse_args()
+
+    if args.version:
+        parser.exit(message="Petronia v{0}\nRunning Python {1}".format(VERSION, sys.version))
+
+    if args.extensions:
+        if os.path.isdir(args.extensions):
+            sys.path.append(args.extensions)
+        else:
+            print("User extensions directory ({0}) does not exist. Skipping.".format(args.extensions))
+    elif 'PETRONIA_USER_DIR' in os.environ:
+        if os.path.isdir(os.environ['PETRONIA_USER_DIR']):
+            sys.path.append(os.environ['PETRONIA_USER_DIR'])
+        else:
+            print("User extensions directory from environment ({0}) does not exist.  Skipping.".format(
+                os.environ['PETRONIA_USER_DIR']))
+
+    if not args.configfile or not os.path.isfile(args.configfile):
+        parser.error("Missing configuration file.  Use `-h' to see the full usage.")
+
+    setup(args.configfile, args.layout)
 
 
 if __name__ == '__main__':

src/petronia/main.py

@@ -89,7 +89,7 @@ def _move_portal_window_to_other_portal(self, event_id, target_id, event_obj):
         active = self._find_active_portal_cid()
         if active is not None:
             # This is the temporary movement handler until navigation can handle it better.
-            self._log_verbose("Moving active window in {0} {1}".format(
+            self._log_debug("Moving active window in {0} {1}".format(
                 active, event_obj['direction']
             ))
             direction = event_obj['direction']

src/petronia/shell/control/active_portal_manager.py

@@ -107,7 +107,7 @@ def __direction_negotiate(self, event_obj, can_visit_parent):
         if direction == DIR_PARENT:
             if can_visit_parent:
                 # We're done.
-                self._log_verbose("Navigate to parent as final destination")
+                self._log_debug("Navigate to parent as final destination")
                 return self._fire_negotiation_target(self.parent_cid, event_obj)
 
             if dest_type == PORTAL_TYPE:
@@ -120,7 +120,7 @@ def __direction_negotiate(self, event_obj, can_visit_parent):
 
             # The parent can't be visited, and the destination isn't supposed to be a portal.
             # So we're the target.`
-            self._log_verbose("Navigate to self, as the parent, as the final destination")
+            self._log_debug("Navigate to self, as the parent, as the final destination")
             return self._fire_negotiation_target(self.cid, event_obj)
 
         if direction not in _ORIENT_DIRS[self.__layout_config.orientation]:
@@ -132,10 +132,10 @@ def __direction_negotiate(self, event_obj, can_visit_parent):
             # Just end it already
             if dest_type == PORTAL_TYPE:
                 # redirect to origin
-                self._log_verbose("Redirect to origin from the bad direction")
+                self._log_debug("Redirect to origin from the bad direction")
                 self._fire_negotiation_target(origin_cid, event_obj)
             # just use self
-            self._log_verbose("Redirect to self from the bad direction")
+            self._log_debug("Redirect to self from the bad direction")
             return self._fire_negotiation_target(self.cid, event_obj)
 
         index_change = _ORIENT_DIRS[self.__layout_config.orientation][direction]
@@ -145,7 +145,7 @@ def __direction_negotiate(self, event_obj, can_visit_parent):
         # Determine if we can handle this direction, based on our orientation.
         if _MOVE_PARENT_DIR == index_change:
             # move to the parent
-            self._log_verbose("Cannot move in direction for this split, telling parent to handle it")
+            self._log_debug("Cannot move in direction for this split, telling parent to handle it")
             return self._fire_negotiation_discover(event_obj)
 
         # We came from a child, so discover the child's index.
@@ -159,15 +159,15 @@ def __direction_negotiate(self, event_obj, can_visit_parent):
                 # Just end it already
                 if dest_type == PORTAL_TYPE:
                     # redirect to origin
-                    self._log_verbose("Split with no children cannot redirect to a child portal,"+
-                                      " so pushing back to origin")
+                    self._log_debug("Split with no children cannot redirect to a child portal," +
+                                    " so pushing back to origin")
                     self._fire_negotiation_target(origin_cid, event_obj)
                 # just use self
-                self._log_verbose("Split with no children cannot go deeper, so using self as target.")
+                self._log_debug("Split with no children cannot go deeper, so using self as target.")
                 return self._fire_negotiation_target(self.cid, event_obj)
 
             # just choose something
-            self._log_verbose("Split can't find previous child cid as a child, so just choosing one.")
+            self._log_debug("Split can't find previous child cid as a child, so just choosing one.")
             source_pos = 0
 
         # Rotate through the children indices.
@@ -182,7 +182,7 @@ def __direction_negotiate(self, event_obj, can_visit_parent):
             return self._fire_negotiation_discover(event_obj, False)
 
         # Go down into the children
-        self._log_verbose("Redirecting movement to the next child index {0}".format(next_pos))
+        self._log_debug("Redirecting movement to the next child index {0}".format(next_pos))
         self._fire_negotiation_descend(child_cids[next_pos], event_obj)
 
     def _fire_negotiation_target(self, target_cid, event_obj):

src/petronia/shell/control/split_layout.py

@@ -102,7 +102,7 @@ def message_pumper():
 
             shell__pump_messages(on_exit_callback)
 
-            print("window quit")
+            self._log_info("Window {0} quit".format(self.cid))
             self.__has_quit = True
 
         pump_thread = threading.Thread(
@@ -124,6 +124,7 @@ def close(self):
         try:
             self.__removing = True
             if not self.__has_quit:
+                self._log_verbose("Sending quit message to window {0} / {1}".format(self.cid, self.__hwnd))
                 window__send_message(self.__hwnd, windows_constants.WM_QUIT, 0, 0)
         finally:
             super().close()