Merge pull request #5 from deadlydog/SeparateUserCommandsFromDefaultC…

…ommands

ReadMe.md

@@ -1,28 +1,45 @@
-# AHK Command Picker Description
+# AHK Command Picker description
 
-An AutoHotkey (AHK) script that allows you to easily call AHK functions and run other AHK scripts.
-(Requires [AutoHotkey_L][AutoHotkeyWebsiteUrl]).
+An [AutoHotkey][AutoHotkeyWebsiteUrl] (AHK) script that allows you to easily call AHK functions and run other AHK scripts.
+(Requires [AutoHotkey v1.1][AutoHotkeyDownloadPageUrl] to be installed).
 
 Instead of having to remember what hotkey maps to each of your AHK scripts (as you could have hundreds), this displays a list of Commands in a light-weight GUI that allows you to quickly and easily run your scripts.
 Simply type part of the command name and hit enter to run your script.
 You can also provide parameters to your commands, allowing you to change the functionality of a command with a few keystrokes.
 
 For more reasons to use this with your AHK scripts, see [Why Use AHK Command Picker][WhyUseAhkCommandPickerPage].
 
-## 🚀 How To Use AHK Command Picker
+## 🚀 How to use AHK Command Picker
 
 Start by [downloading the latest release][DownloadLatestReleaseUrl].
 To launch AHK Command Picker run the `AHKCommandPicker.ahk` script.
 
 Press the `Caps Lock` key to bring up the AHK Command Picker GUI.
-From there just type the name of the command that you want to run and hit enter to run it.
-You can still toggle Caps Lock on and off by pressing `Shift`+`Caps Lock`.
+From there, just type the name of the Command that you want to run and hit Enter to run it.
 
-To add your own commands to AHK Command Picker, see [the documentation][DocumentationPage].
+Note: You can still toggle Caps Lock on and off by pressing `Shift`+`Caps Lock`.
+
+### ✍ Adding your own Commands, hotkeys, and hotstrings
+
+AHK Command Picker comes with many Commands out of the box, but the real power comes from adding your own Commands, hotkeys, and hotstrings.
+
+- `UserCommands\MyCommands.ahk`: Add your own Commands here.
+- `UserCommands\MyHotkeys.ahk`: Add your own hotkeys and hotstrings here.
+
+You can use AHK Command Picker to open these files for editing by running the `EditMyCommands` and `EditMyHotkeys` Commands.
+After you have modified a file, run the `ReloadAHKScript` Command to apply your changes.
+
+For more information, see [the documentation][DocumentationPage].
+
+### Additional tidbits
 
 You will likely want to [have AHKCommandPicker start automatically when you log into Windows][AutomaticallyStartAtLogin].
 
-## 🖼 Screen Shots
+### Upgrading versions
+
+If you are upgrading from v1 to v2, see [the migration guide][MigrateFromV1ToV2Page].
+
+## 🖼 Screenshots
 
 All commands:
 
@@ -62,7 +79,7 @@ See [the Contributing page](docs/Contributing.md) for more details.
 
 ## 📃 Changelog
 
-See what's changed in the application over time by viewing [the changelog](docs/Changelog.md).
+See what's changed in the application over time by viewing [the Changelog](docs/Changelog.md).
 
 ## 💳 Donate
 
@@ -71,7 +88,8 @@ Buy me a pastry 🍰 for providing this script open source and for free 🙂
 [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=D7PW6YBWNDLXW)
 
 <!-- Links -->
-[AutoHotkeyWebsiteUrl]: http://www.autohotkey.com
+[AutoHotkeyWebsiteUrl]: https://www.autohotkey.com
+[AutoHotkeyDownloadPageUrl]: https://www.autohotkey.com/download/
 
 [AhkCommandPickerInUnder2MinutesYouTubeUrl]: https://www.youtube.com/watch?v=gevnQAwYLAg,type=youtube
 [AhkCommandPickerInUnder2MinutesYouTubeImageUrl]: https://img.youtube.com/vi/gevnQAwYLAg/0.jpg
@@ -87,6 +105,7 @@ Buy me a pastry 🍰 for providing this script open source and for free 🙂
 [WhyUseAhkCommandPickerPage]: docs/WhyUseAhkCommandPicker.md
 [DocumentationPage]: docs/DocumentationHomePage.md
 [AutomaticallyStartAtLogin]: docs/TipsAndTricks.md#have-ahk-command-picker-automatically-start-when-you-log-into-windows
+[MigrateFromV1ToV2Page]: docs/MigrateFromV1ToV2.md
 
 [AllCommandsImage]: docs/Images/AHKCommandPicker-AllCommands.png
 [FilteredCommandsImage]: docs/Images/AHKCommandPicker-FilteredCommands.png

docs/AddingMultipleCommandsAtOnce.md

@@ -2,7 +2,8 @@
 
 This is an alternative to [Using Preset Parameters][UsingCommandsWithParametersPage]
 
-So even though you can have your commands show a preset list of parameters, you may instead want each command-parameter combination show up as its own command. So essentially instead of getting this with using preset parameters:
+So even though you can have your commands show a preset list of parameters, you may instead want each command-parameter combination show up as its own command.
+So essentially instead of getting this with using preset parameters:
 
 ![Using Preset Parameters][UsingPresetParametersImage]
 
@@ -12,7 +13,8 @@ You would prefer to have this instead:
 
 Where each command-parameter combination shows up in the base list of commands; that is, the user does not have to type in some other command plus a comma to see the list of that command's preset parameters.
 
-Maybe you don't like having to press the comma (,) key after typing the command name, or maybe you just prefer to see ALL of your options without hiding any of them as parameters. Of course we could accomplish this by adding a command for each command-parameter combination one by one, like so:
+Maybe you don't like having to press the comma (`,`) key after typing the command name, or maybe you just prefer to see ALL of your options without hiding any of them as parameters.
+Of course we could accomplish this by adding a command for each command-parameter combination one by one, like so:
 
 ```AutoHotkey
 AddCommand("ExploreCDrive", "Explore C:\")
@@ -32,19 +34,23 @@ ExploreProgramFiles()
 
 But as you can see, even on this very basic and simple operation, there is a lot of very similar code and code duplication happening, and it would take a while to write all of it out.
 
-To help alleviate this tedious repetition you can use the `AddCommands()` or `AddCommandsWithPrePostfix()` functions. Here are their prototypes:
+To help alleviate this tedious repetition you can use the `AddCommands()` or `AddCommandsWithPrePostfix()` functions.
+Here are their prototypes:
 
 ```AutoHotkey
 AddCommands(functionName, descriptionOfWhatFunctionDoes = "", commandList = "")
 
 AddCommandsWithPrePostfix(functionName, descriptionOfWhatFunctionDoes = "", commandList = "", prefix = "", postfix = "")
 ```
 
-These both call the `AddNamedCommand()` function for each command in the commandList. Each command in the list will call the given functionName, supplying the command's specific value as a parameter to the function.
+These both call the `AddNamedCommand()` function for each command in the commandList.
+Each command in the list will call the given functionName, supplying the command's specific value as a parameter to the function.
 
-* `commandList` = The commands to show up in the picker that will call the function, separated with a comma. Separate the command name that appears in the picker and the value to pass to the function with a pipe character (|). If no pipe character is provided, the given value will be both shown in the picker and passed to the function.
-* `prefix` = The prefix to add to the beginning of all the command names in the commandList.
-* `postfix` = The postfix to add to the end of all the command names in the commandList.
+- `commandList`: The commands to show up in the picker that will call the function, separated with a comma.
+  Separate the command name that appears in the picker and the value to pass to the function with a pipe character (`|`).
+  If no pipe character is provided, the given value will be both shown in the picker and passed to the function.
+- `prefix`: The prefix to add to the beginning of all the command names in the commandList.
+- `postfix`: The postfix to add to the end of all the command names in the commandList.
 
 So to use the `AddCommands()` function to get the same type of look that you would get from manually adding each command individually you could do:
 
@@ -66,29 +72,41 @@ ExploreDirectory(directoriesToOpen = "")
 }
 ```
 
-Here we used the same technique as in the [Preset Parameters][UsingCommandsWithParametersPage] documentation to build a comma-separated list of directories to add. We also used the exact same `ExploreDirectory()` function. The only thing different here is that we used the `AddCommands()` function, which will essentially loop through each command in the commandList (i.e. the directories variable above) and call `AddCommand()` for you, passing in "ExploreDirectory" as the function to call and "Open directory" as the user-friendly description.
+Here we used the same technique as in the [Preset Parameters][UsingCommandsWithParametersPage] documentation to build a comma-separated list of directories to add.
+We also used the exact same _ExploreDirectory()_ function.
+The only thing different here is that we used the `AddCommands()` function, which will essentially loop through each command in the commandList (i.e. the _directories_ variable above) and call `AddCommand()` for you, passing in "ExploreDirectory" as the function to call and "Open directory" as the user-friendly description.
 
 One more time, this is what the result might look like if we added many more directories and had some other commands defined:
 
 ![Using Many Commands][UsingManyCommandsImage]
 
-Notice that you no longer need to type "ExploreDirectory," to see the list of directories to explore; they are listed along-side all of the other commands. For example, you could now just type "C Drive" to open `C:\`.
+Notice that you no longer need to type "ExploreDirectory," to see the list of directories to explore; they are listed along-side all of the other commands.
+For example, you could now just type "C Drive" to open _C:\\_.
 
 ## Prepend Command Names
 
-So that's nice, but what if you want to group all of these related commands that essentially do the same operation. That's what the `AddCommandsWithPrePostfix()` function is for. To prepend all of our "ExploreDirectory" commands with the letter "e", we could have used:
+So that's nice, but what if you want to group all of these related commands that essentially do the same operation.
+That's what the `AddCommandsWithPrePostfix()` function is for.
+To prepend all of our "ExploreDirectory" commands with the letter "e", we could have used:
 
 ```AutoHotkey
 AddCommandsWithPrePostfix("ExploreDirectory", "Open directory", directories, "e")
 ```
 
-Here we specified that all of these commands should have a prefix of "e" (and we omitted the postfix parameter, which is essentially the same as saying don't add a postfix). So in the GUI, this is what our list might now look like:
+Here we specified that all of these commands should have a prefix of "e" (and we omitted the postfix parameter, which is essentially the same as saying don't add a postfix).
+So in the GUI, this is what our list might now look like:
 
 ![Using many commands with prefix][UsingManyCommandsWithPrefixImage]
 
-Note the "e" at the beginning of our commands that call ExploreDirectory().
+Note the "e" at the beginning of our commands that call _ExploreDirectory()_.
+
+## Next Steps
+
+Proceed to the [Tips and Tricks][TipsAndTricksPage] page, or return to [the table of contents][DocumentationTableOfContents].
 
 <!-- Links -->
+[DocumentationTableOfContents]: DocumentationHomePage.md
+[TipsAndTricksPage]: TipsAndTricks.md
 [UsingCommandsWithParametersPage]: UsingCommandsWithParameters.md
 [UsingPresetParametersImage]: Images/UsingPresetParameters.png
 [UsingManyCommandsImage]: Images/UsingManyCommands.png

docs/BestPractices.md

@@ -1,7 +1,30 @@
 # Best Practices
 
-* Do not edit the `AhkCommandPicker.ahk`, `CommandScriptsToInclude.ahk`, `Commands\DefaultCommands.ahk`, and `Commands\DefaultHotkeys.ahk` files, as they may be updated when new versions of AHK Command Picker are released, so you may run into conflicts (or lose your customizations) when updating these files.
+## Use multiple files to organize your commands
 
-* While you could dump all of your commands into the `Commands\MyCommands.ahk` file, that file may soon become large and unwieldy. You will likely want to create some new .ahk files in the Commands folder and `#Include` the new files in the `MyCommands.ahk` file. Maybe try to keep them logically separated, such as putting commands you typically use at work in a `Commands\Work.ahk` file, and home ones in `Commands\Home.ahk`. However you want to organize them is up to you.
+While you could dump all of your commands into the `UserCommands\MyCommands.ahk` file, that file may soon become large and unwieldy.
+You may instead want to create new .ahk files in the `UserCommands` folder and `#Include` them from the `UserCommands\MyCommands.ahk` file.
+For example, put commands you typically use at work in a `UserCommands\Work.ahk` file, and home ones in `UserCommands\Home.ahk`.
+However you want to organize them is up to you, but new files should always be created in the `UserCommands` directory.
 
-* One important thing to note is that whenever a `hotkey` is encountered, any commands that may have been defined after it will not be processed and added to the AHK Command Picker's list of commands. So it is important that all hotkeys and hotstrings be declared **AFTER** all commands. This is why it is crucial that hotkeys and hotstrings are defined from the MyHotkeys.ahk file.
+## Do not add Hotkeys int the Command files
+
+One important thing to note is that whenever a `hotkey` (e.g. _^j::_) or `hotstring` (e.g. _::btw::by the way_) is encountered, any commands that may have been defined after it will not be processed and added to the AHK Command Picker's list of commands.
+So it is important that all hotkeys and hotstrings be declared **AFTER** all commands.
+**To do this, ensure that hotkeys and hotstrings are defined or `#Include`d in the `UserCommands\MyHotkeys.ahk` file.**
+
+## Do not edit the Default Commands
+
+Do not edit the `AhkCommandPicker.ahk` file or any files in the `DefaultCommands` directory, as they may be updated when new versions of AHK Command Picker are released, so you may run into conflicts (or lose your customizations) when updating these files.
+Only edit the `UserCommands\MyCommands.ahk` and `UserCommands\MyHotkeys.ahk` files, as well as any other files you create in the `UserCommands` directory.
+
+## Next Steps
+
+That's it.
+Congrats!
+You've read all of the documentation! 🎉👏
+
+Return to [the table of contents][DocumentationTableOfContents].
+
+<!-- Links -->
+[DocumentationTableOfContents]: DocumentationHomePage.md

docs/Changelog.md

@@ -2,24 +2,43 @@
 
 This page is a list of _notable_ changes made in each version.
 
-## vNext
+## v2.0.1 - February 28, 2023
+
+### App
 
 Features:
 
-- Updated file structure to make updating to new versions easier down the road.
-- Added support for Outlook 2016.
-- Add commands for creating an Outlook appointment and opening the Outlook calendar.
+- Updated file structure to separate User Commands from the built-in Default Commands to make updating to new versions easier in the future (BREAKING CHANGE).
+- Add examples to the `MyCommands.ahk` and `MyHotkeys.ahk` files to help new users get started faster.
 
 Fixes:
 
 - Fix issue where the wrong command is sometimes selected when typing quickly ([GitHub issue #3](https://github.com/deadlydog/AHKCommandPicker/issues/3)).
-- Make Outlook commands more resilient.
 
-Breaking changes:
+Breaking changes ([see the v1 to v2 migration guide](MigrateFromV1ToV2.md)):
 
 - Removed the `CommandScriptsToInclude.ahk` file.
   If you had added lines to that file to include other scripts, you will need to move those include statements to the `MyCommands.ahk` file.
-- Changed Default Hotkey for moving a window from Alt+MouseDrag to LeftWin+MouseDrag.
+- Moved the `MyCommands.ahk` and `MyHotkeys.ahk` files to the `UserCommands` directory.
+  If you had customized the `MyCommands.ahk` or `MyHotkeys.ahk` files, you will need to copy their contents into the new equivalent files in the `UserCommands` directory.
+  If you had added lines to include other scripts, you will need to update the include statement's directory path from `Commands` to `UserCommands`.
+
+### Default Commands
+
+Features:
+
+- Added support for Outlook 2016.
+- Added commands for creating an Outlook appointment and opening the Outlook calendar.
+- Added `ExploreMyDocuments` and `ExploreDesktop` Commands.
+
+Fixes:
+
+- Make Outlook commands more resilient.
+
+Breaking changes:
+
+- Renamed Commands `eMyComputer` to `ExploreMyComputer`, `eRecycleBin` to `ExploreRecycleBin`, and `eC` to `ExploreCDrive`.
+- Changed the Default Hotkey for moving a window with your mouse by grabbing it anywhere (not just the title bar) from `Alt`+`MouseDrag` to `LeftWin`+`MouseDrag`.
 
 ## v1.3.2 - May 4, 2016
 
@@ -34,6 +53,14 @@ Features:
 - Renamed General.ahk to DefaultCommands.ahk and GeneralHotKeys.ahk to DefaultHotkeys.ahk.
 - Added new MyCommands.ahk and MyHotkeys.ahk files, and associated EditMyCommands and EditMyHotkeys commands, to help new users get started faster.
 
+## v1.3.0 - November 24, 2013
+
+Features:
+
+- Added new setting to have Escape key kill all current Commands and reload script (i.e. panic kill).
+  Escape key only has an effect if a command is currently running.
+- Added Sleep timer to allow hotkeys and hotstrings to still be processed when in a long-running loop in a user's command.
+
 ## CodePlex to GitHub migration
 
 This project was originally created in January 2012 using TFVC (Team Foundation Version Control) and hosted on CodePlex, which is now defunct.

docs/Contributing.md

@@ -11,7 +11,3 @@ If you open an issue, please:
   - any error messages
   - log output or files
   - screenshots, gifs, or videos
-
-## Why is it like this?
-
-If you are curious why something is the way it is, it may be documented in the [Architecture Decision Records](/docs/ArchitectureDecisionRecords/ArchitectureDecisionRecords.md).

docs/DocumentationHomePage.md

@@ -1,21 +1,17 @@
 # Documentation Table Of Contents
 
-AHK Command Picker requires [AutoHotkey_L][AutoHotkeyWebsiteUrl] to be installed, as it uses features that are only available in this version of AutoHotkey.
+AHK Command Picker requires [AutoHotkey v1.1][AutoHotkeyDownloadPageUrl] (AutoHotkey_L) to be installed, as it uses features that are only available in this version of AutoHotkey.
 
 1. [Getting Started With AHK Command Picker][GettingStartedPage]
-
 1. [Using Commands With Parameters][UsingCommandsWithParametersPage]
-
 1. [Adding Multiple Commands At Once][AddingMultipleCommandsAtOncePage]
-
 1. [Tips and Tricks][TipsAndTricksPage]
-
 1. [Best Practices][BestPracticesPage]
 
 <!-- Links -->
-[AutoHotkeyWebsiteUrl]: http://www.autohotkey.com
-[GettingStartedPage]: GettingStarted.md
-[UsingCommandsWithParametersPage]: UsingCommandsWithParameters.md
 [AddingMultipleCommandsAtOncePage]: AddingMultipleCommandsAtOnce.md
+[AutoHotkeyDownloadPageUrl]: https://www.autohotkey.com/download/
 [BestPracticesPage]: BestPractices.md
+[GettingStartedPage]: GettingStarted.md
 [TipsAndTricksPage]: TipsAndTricks.md
+[UsingCommandsWithParametersPage]: UsingCommandsWithParameters.md