Version 1.5.0.0 Changes

InputOptions.md

@@ -0,0 +1,55 @@
+## Input Simulation Options
+
+![Input Options UI](images/StayAwakeInputOptions.png)
+
+StayAwake can randomly pick any of the 26 inputs (24 key codes & 2 mouse moves) during each simulation. In this popup, users can specify _at least_ one OR a select few OR all of the 26 inputs to be included in the simulation roster.
+
+StayAwake simulates events using the `SendInput` API instead of the deprecated `keybd_event` API. `SendInput` API allows batching of multiple key or mouse events in a single atomic call to the Windows OS, thus yielding jitter-free key or mouse simulations.
+
+As can be noted from the screenshot, [Zero-pixel Mouse Move](#zero-pixel-mouse-move) and [One-pixel Mouse Jiggle](#one-pixel-mouse-jiggle) are my two preferred input options.
+
+#### Scroll Lock cycling
+Scroll Lock toggling will work just fine for most users. However, some users using Remote Desktop alongside have reported spurious keystrokes being transmitted between the connected Windows devices. Users in such situations should explore other key simulation options.
+
+#### Volume Up & Down
+With this option, StayAwake will simulate a _Volume Down_ key press, immediately followed by a _Volume Up_ key press, thereby resulting in no net change in volume level.
+
+Volume Up & Down simulation will preserve the muted sound state. Prior to each Volume Up & Down simulation event, StayAwake will detect if the sound is in a muted state or not. If the sound is found muted, Volume Mute key will also be added after the Volume Down & Up keys in the `SendInput` API call. Since all these key events are sent in a single atomic API call, any sound jitter that may still occur will be the briefest possible.
+
+A minor benefit with this option is the visual feedback. Each StayAwake key simulation event will cause the Windows Volume Slider flyout/toast OSD (on-screen display) to show for a few seconds. While this input option is useful for debugging or verification of StayAwake functionality, it will get too distracting over long term.
+
+**Tip**: You can verify StayAwake in action by *temporarily* enabling only the *Volume Up & Down* key code and setting both *Minimum Awake Seconds* and *Maximum Awake Seconds* fields to 10.
+
+#### Unassigned Key (1 to 10)
+With these options, StayWake will simulate key press of an unassigned keycode.
+
+These unassigned keycodes have been obtained from this Microsoft article on [Virtual-Key Codes](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes).
+
+Microsoft may start utilizing any of these unassigned codes in the future -- but not all of them in one go. Hence all 10 of the currently unassigned codes have been included in the [Input Simulation Options](#input-simulation-options) popup so that users can select other still available unassigned keycodes.
+
+See also: [Google Sheets clears active cell content on unassigned Windows virtual-key events](https://github.com/shriprem/StayAwake/discussions/21)
+
+#### Extended Function Keys (F13 to F24)
+These 12 options are safe to use since most applications do not bind F13�F24 keys to any action. However, there are some rare exceptions such as:
+* Some DAWs (digital audio workstations)
+* Some macro software
+* Some enterprise kiosk systems
+* Some accessibility tools
+
+See also: [Google Sheets clears active cell content on unassigned Windows virtual-key events](https://github.com/shriprem/StayAwake/discussions/21)
+
+#### One-pixel Mouse Jiggle
+With this option, StayAwake will simulate a one-pixel mouse jiggle. The mouse pointer will move one pixel diagonally right & down, and then back to its original position. This one-pixel jiggle is jitter-free since the two mouse moves are batched into a single atomic `SendInput` API call. So, the mouse pointer will not seem to move at all with this option.
+
+#### Zero-pixel Mouse Move
+With this option, StayAwake will simulate a zero-pixel mouse move. The mouse pointer will not move at all. At least on the few Windows 11 devices that I have tested, this option was found to be remarkably effective. If this option does not work on your Windows device, use the [One-pixel Mouse Jiggle](#one-pixel-mouse-jiggle) option instead.
+
+
+#### Buttons
+* _Select None_ button will deselect all 26 input options.
+* _Select All Unassigned_ button will select all 10 Unassigned Key options.
+* _Select All Ext. FN Keys_ button will select all 12 Extended Function Key options.
+* _Select All_ button will select all 26 input options.
+* _Apply_ will save the selected input options and close the popup.
+* _Cancel_ will close the popup without saving any changes.
+

README.md

@@ -10,37 +10,52 @@
       
 <a title="OSSign - Code Signing for Open Source" href="https://www.ossign.org"><img style="width:100px; height:86px;" src="images/OSSign.png"/></a>
 
+![StayAwake UI](images/StayAwakeApp.png) &nbsp; ![Input Options UI](images/StayAwakeInputOptions.png)
 
-[Current Version: 1.3.0.0](https://github.com/shriprem/StayAwake/blob/main/VersionHistory.md)
+[Current Version: 1.5.0.0](VersionHistory.md)
 
 StayAwake is a simple utility that enables you to maintain an _Active_ status on Microsoft Teams (and perhaps other messaging applications such as Slack and Zoom). StayAwake also prevents screen saver activation, screen blanking, and Windows session lockouts.
 
+## Features at a glance
+* Randomized simulation with mouse or key inputs. Roster with a choice of 24 no/low side-effect keys and 2 invisible mouse moves.
+* Random interval simulation. Intervals within a specified range of seconds.
+* Helpful status information with timestamps of Last and Next simulations.
+* Minimization to System Tray.
+* Start Minimized option.
+* Manual Pause feature when needed.
+* Automatic Pause while Windows in locked state. Reduces disk activity and CPU usage. Conserves battery power.
+* Small, portable application. Runs with no installation or administrator privileges.
+* Digitally signed application executable file.
+* Update Check feature - Manual or automatic (opt-in).
+
 If you are using Microsoft Teams, you may have noticed that Teams automatically sets your status to _Away_ after a certain period of inactivity. This can be frustrating if you are still at your desk but perhaps on a business phone call _OR_ outlining a plan on paper _OR_ consulting some reference material.
 
-StayAwake can be minimized to the Windows System Tray, and will continue to run in the background until you click the _Exit_ button. StayAwake also has the option to automatically minimize to Windows System Tray upon launch. See: [Start Minimized](#start-minimized)
+StayAwake simulates a randomly selected input from a specified roster of jitter-free mouse moves and no/low side-effect keys. Additionally, these simulations are done at random intervals within a specified range of seconds. This is a safe and non-intrusive way to keep your Microsoft Teams status _Active_. The combined randomness of inputs and time intervals eliminates predictable patterns, making StayAwake simulations seem organic.
 
-StayAwake does its job by simulating key presses of unused or low side-effect buttons at specified time intervals. This is a safe and non-intrusive way to keep your Microsoft Teams status _Active_.
+StayAwake can be minimized to the Windows System Tray, and will continue to run in the background until you click the _Exit_ button. StayAwake also has the option to automatically minimize to Windows System Tray upon launch. See: [Start Minimized](#start-minimized)
 
 StayAwake executable is now digitally signed by the kind folks at [OSSign](https://www.ossign.org). Thanks to the code signing, there is *NO* need for users to override the Windows Defender Smartscreen or [unblock the executable file](https://stackoverflow.com/questions/48946680/how-to-avoid-the-windows-defender-smartscreen-prevented-an-unrecognized-app-fro) to launch StayAwake.
 
 ## User Interface
 ![StayAwake UI](images/StayAwakeApp.png)
 
-#### Select multiple Key Codes for random simulation
-StayAwake can randomly pick any of the 12 key codes during each simulation. Users can specify _at least_ one OR a select few OR all of the 12 key codes to be included in the simulation roster. See the [Select multiple Key Codes](#select-multiple-key-codes) section below for more info.
+#### Select multiple options for random simulation
+StayAwake can randomly pick any of the 26 inputs (24 key codes & 2 mouse moves) during each simulation. Users can specify _at least_ one OR a select few OR all of the 26 inputs to be included in the simulation roster. See [Input Simulation Options](InputOptions.md) for more info.
 
 #### Minimum Awake Seconds
 This field allows you to specify the minimum interval between key simulations. The initial default value for this is 240 seconds (_i.e._, 4 minutes). However, you can change this to any value between 10 and 9990 seconds. Your new value will be saved and used the next time you run StayAwake.
 
 #### Maximum Awake Seconds
 This field allows you to specify the maximum interval between key simulations. The initial default value for this is 240 seconds (_i.e._, 4 minutes). However, you can change this to any value between 10 and 9990 seconds. Your new value will be saved and used the next time you run StayAwake.
 
+**Tip**: If Microsoft Teams is changing your status to _Away_ after 5 minutes (i.e., 300 seconds) of inactivity, consider setting the *Minimum Awake Seconds* to around 200 and the *Maximum Awake Seconds* to 310 or 320 or even 330 (i.e., a little over 300). This weighted range will cause your Teams status to briefly drift out of _Active_ status once in a while -- a more normal user behavior from your coworkers' perspective than a solid green status through an entire work day.
+
 #### Set Timer button
 After changing the value for either *Minimum Awake Seconds* or *Maximum Awake Seconds*, click this button to apply the new setting. Clicking this button will also immediately invoke an Awake event.
 
 After every Awake event, a random number of seconds (between the specified minimum and maximum seconds) will be picked to run the next Awake event.
 
-The clock times of the last and next Awake events will be displayed and continually refreshed on the StayAwake window. The randomly picked key code used for the last Awake will also be displayed below the last Awake time.
+The clock times of the last and next Awake events will be displayed and continually refreshed on the StayAwake window. The randomly picked input option used for the last Awake will also be displayed below the last Awake time.
 
 #### Pause button
 Click this button to pause StayAwake Key simulations.
@@ -55,43 +70,30 @@ As seen in the clip above, clicking the *Pause* button will also have these effe
    ![StayAwake UI](images/StayAwakePausedLaunch.png)
 
 
+4. On a related note, if the Windows system has been manually locked, StayAwake will pause key and mouse simulations until the system gets unlocked again. This will help reduce disk activity and CPU usage (thus conserving battery power on laptops) while the system is in locked state.
+
 #### Minimize button
 Click this button to minimize StayAwake to the Windows System Tray. See the [SystemTray Icon](#system-tray-icon) section below for more info.
 
 #### Exit button
 Click this button to exit StayAwake.
 
 #### Start Minimized
-Check the _Launch application in minimized state_ box to have StayAwake automatically minimize to System Tray upon launch.
+Check the _Start minimized_ box to have StayAwake automatically minimize to System Tray upon launch.
 
 When the _Start Minimized_ option is enabled, StayAwake will launch and minimize immediately only on the first launch attempt. If StayAwake is still running in a minimized state, trying to launch the application again will restore the StayAwake dialog from the minimized state. This is by design when `MultipleInstancesAllowed=N`. See under: [Configuration File Details](#configuration-file-details)
 
+#### Update Check button
+Click this button to manually check if a newer version of StayAwake is available. When clicked, the _Check for Updates_ dialog will popup.
 
-### Select multiple Key Codes
-
-![StayAwake UI](images/StayAwakeKeySelections.png)
-
-StayAwake can randomly pick any of the 12 key codes during each simulation. In this popup, users can specify _at least_ one OR a select few OR all of the 12 key codes to be included in the simulation roster.
-
-#### Scroll Lock cycling
-Scroll Lock toggling will work just fine for most users. However, some users using Remote Desktop alongside have reported spurious keystrokes being transmitted between the connected Windows devices. Users in such situations should explore other key simulation options.
 
-#### Volume Up & Down
-With this option, StayAwake will simulate a _Volume Down_ key press, immediately followed by a _Volume Up_ key press, thereby resulting in no net change in volume level.
+![StayAwake UI](images/CheckForUpdates.png)
 
-A minor benefit with this option is the visual feedback. Each StayAwake key simulation event will cause the Windows Volume Slider bar to display for a few seconds above the Windows Taskbar.
+The _Check for Updates_ popup will display the Installed and Latest Version numbers.
 
-However, if a user has muted the audio, then this option will unmute it. Users wishing to avoid this side effect should explore other key simulation options.
+If a newer version is available, the popup will display a clickable link that redirects to the [StayAwake - Latest Release](https://github.com/shriprem/StayAwake/releases/latest) page.
 
-#### Unassigned Key (1 to 10)
-With these options, StayWake will simulate key press of an unassigned keycode.
-
-These unassigned keycodes have been obtained from this Microsoft article on [Virtual-Key Codes](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes).
-
-Microsoft may start utilizing any of these unassigned codes in the future -- but not all of them in one go. Hence all 10 of the currently unassigned codes have been included in the [Select multiple Key Codes](#select-multiple-key-codes) popup so that users can select other still available unassigned keycodes.
-
-#### Optional Tip
- You can verify StayAwake in action by *temporarily* enabling only the [Volume Up & Down](#volume-up--down) key code and setting both *Minimum Awake Seconds* and *Maximum Awake Seconds* fields to 10 seconds.
+In this popup, you can also enable the _Check for updates when StayAwake starts_ option to have StayAwake automatically check for a newer version every time it is launched. This is an opt-in feature that is unchecked by default.
 
 
 ### System Tray Icon
@@ -107,7 +109,9 @@ When you minimize StayAwake, it will be represented by the System Tray icon show
 ## Configuration File Details
 StayAwake saves its configuration in a file named `StayAwake.ini`. This file is co-located in the `StayAwake.exe` application file folder. These key-value pairs are stored in this file:
 
-1. `SelectedKeyCodes`: This key stores a string of 12 characters -- each character indicating if a key code in the [Select multiple Key Codes](#select-multiple-key-codes) popup is selected or not with either a `1` or `0`, respectively.
+1. `SelectedKeyCodes`: This key stores a string of 26 characters -- each character indicating if a key code or mouse move in the [Input Simulation Options](InputOptions.md) popup is enabled or not with either a `1` or `0`, respectively.
+
+   If an invalid value is detected for this key, the default value of `00111111111111111111111111` (i.e., enabling of all inputs except *Scroll Lock cycle* and *Volume Down & Up*) will be used instead.
 
 2. `MinimumIntervalInSeconds`: This key stores the minimum number of seconds between each StayAwake Key simulation as specified in the [Minimum Awake Seconds](#minimum-awake-seconds) field.
 
@@ -119,9 +123,11 @@ StayAwake saves its configuration in a file named `StayAwake.ini`. This file is
 
 4. `AwakePaused`: This key stores a flag value (_Y_ or _N_) to indicate if StayAwake is in paused state.
 
-5.  `StartMinimized`: This key stores a flag value (_Y_ or _N_) to indicate if StayAwake will automatically minimize to System Tray upon launch. See: [Start Minimized](#start-minimized)
+5. `StartMinimized`: This key stores a flag value (_Y_ or _N_) to indicate if StayAwake will automatically minimize to System Tray upon launch. See: [Start Minimized](#start-minimized)
 
-6. `MultipleInstancesAllowed`: This key stores a flag value (_Y_ or _N_) to indicate whether multiple instances of StayAwake are allowed to run simultaneously. The default value is _N_ (i.e., multiple instances are not allowed). Any value that is not _Y_ will be interpreted as _N_.
+6. `StartCheckUpdates`: This key stores a flag value (_Y_ or _N_) to indicate if StayAwake will automatically check for a newer version every time it is launched. See: [Update Check button](#update-check-button)
+
+7. `MultipleInstancesAllowed`: This key stores a flag value (_Y_ or _N_) to indicate whether multiple instances of StayAwake are allowed to run simultaneously. The default value is _N_ (i.e., multiple instances are not allowed). Any value that is not _Y_ will be interpreted as _N_.
 
 
 ## Alternatives
@@ -143,5 +149,9 @@ However, if you are looking for a way to keep your Microsoft Teams status _Activ
 
 StayAwake is a portable application and does NOT require installation with administrator privileges. Simply download the latest release from the [Releases](https://github.com/shriprem/StayAwake/releases) page and unzip the contents to a folder of your choice. Run the `StayAwake.exe` application file to start the utility.
 
+If you like StayAwake, please star this repo. Thank you for your appreciation.
+
+If you would like to support its development, you can buy me a coffee by clicking the button below. Thank you for your support!
+
 
 <a href='https://ko-fi.com/S6S417WICS' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi5.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>