Beginning Tips for Writing AutoHotkey Scripts (Methods for Running Label Subroutines)

Last time I discussed the AutoHotkey building blocks called Labels which are the names assigned to subroutines. A Label subroutine can appear almost anywhere in an AutoHotkey script, calling it at a later time after the script is running. This is an important concept since a Label subroutine can be almost any type of snippet from a quick pop-up to a full-blown app. Once the script is loaded there are a number of ways to call up these subroutines through AutoHotkey commands. Last time I used the example of the Hotkey command and briefly discussed the GoTo and GoSub commands. However, depending on how you want your apps to work, there are a number of other commands for accessing your Label subroutines.

For demonstration purposes the following short script is offered as an example of an AutoHotkey Label subroutine:

Hotkey, ^!t, GetTime

GetTime:
  FormatTime, OutputVar
  MsgBox, The time is %OutputVar%
Return

This script could be almost any snippet you’ve written including much more complex applications. Plus, as previously mentioned, the Label subroutine can appear virtually anywhere in the AutoHotkey script as long as it doesn’t interfere with another building block or the auto-execute section in the beginning of the script.

Pop-up displaying the current time and date.

In the above script, the hotkey combination CTRL+ALT+T (^!t) is assigned to call the Label subroutine GetTime: (which must already exist within the script when it is first loaded). The GetTime: subroutine simply assigns the default value of the FormatTime command (the current time and date) to the variable OutputVar. Then, the MsgBox command is used to display the default formatted time and date (as shown at right).

The HotKey command must run in the auto-execute section at the beginning of the script. Note that there is no Return command after the HotKey command. This is deliberate since

rather than stopping the processing of the auto-execute section with the Return, AutoHotkey drops into the Label subroutine GetTime: displaying the time and date when the script is first loaded. The auto-execute processing stops after encountering the Return at the end of the GetTime: subroutine. If you don’t want this initial display upon opening, then place a Return command on the next line after the HotKey command.

Whenever the hotkey combination is used, the current time pops up.

Now that we have our app (CheckDate.ahk) loaded, let’s look for other ways to call the same Label subroutine, GetTime:.

The Menu Command

One easy way to reuse a Label subroutine is to add it to a pop-up menu with the Menu command. This can be done by merely adding one line to the auto-execute portion of the script:

Hotkey, ^!t, GetTime
Menu, Tray, Add, Show Time, GetTime

GetTime:
FormatTime, OutputVar
MsgBox, The time is %OutputVar%
Return

Right-click Menu — Right-click on icon in System Tray to view AutoHotkey menu.

Now whenever you right-click on the green AutoHotkey logo in the System Tray on the right side of the Windows Taskbar (as shown on right), the option to select “Show Time” will appear at the bottom of the list. When selected, the “Show Time” option runs the GetTime: subroutine.

Note: At this point, it’s necessary to keep the HotKey command in the script. While the HotKey setup will keep the process running after loading, the Menu command alone will not. Removing the HotKey command causes the process to end after the first run. However, if the Menu command (in the auto-execute section) and the GetTime: subroutine are added to another combined script with any hotkeys or hotstrings, there will be no early termination problem.

An alternative (and more useful) method for keeping any AutoHotkey script running is to add the #Persistent command to the script. Placing #Persistent anywhere in a script stops automatic termination when the script completes its initial loading.

SetTimer Command

Perhaps you would like to run the Label subroutine after a specific interval of time. Then, the SetTimer command can be used:

Hotkey, ^!t, GetTime
Menu, Tray, Add, Show Time, GetTime
SetTimer, GetTime, 15000

GetTime:
  FormatTime, OutputVar
  MsgBox, The time is %OutputVar%
Return

This particular setting for the SetTimer command may be a bit excessive since it will pop-up the time window every 15 seconds. If you are using SetTimer on its own, then use #Persistent to keep the script alive.

OnExit Command

Sometimes you may want a script to perform specific actions just before processing ends (or exiting) such as backing up your work or performing other checks. In that case, use the OnExit command. In our example, the GetTime: subroutine will run before the script actually ends:

Hotkey, ^!t, GetTime
Menu, Tray, Add, Show Time, GetTime
SetTimer, GetTime, 60000
OnExit, GetTimeEnd
GetTime:
  FormatTime, OutputVar
  MsgBox, The time is %OutputVar%
Return

GetTimeEnd:
  GoSub GetTime
  ExitApp
Return

The number one problem with OnExit is that it captures all attempts to end a process. That means you must use the ExitApp command in your exit subroutine or the script will be kept alive indefinitely. The only way to close (or reload) it will be to kill the process with Windows Task Manager (CTRL+SHIFT+ESC to open). For that reason the GetTime: subroutine cannot be called directly.

The GetTimeEnd: label is added to make if possible to check the time when an exit action occurs, then actually exit the script. This subroutine uses the GoSub command to call the GetTime: subroutine before closing the process (ExitApp). Select the “Exit” option from the right-click menu for the running System Tray AutoHotkey icon to test this subroutine.

Using GUI Labels (gLabel)

As you progress in AutoHotkey, you will eventually want to use the built-in AutoHotkey Graphic User Interface (GUI) windows to build scripts. These GUIs are a collection of powerful pop-up windows which help to build useful, intuitive apps. (See “The Use and Images of AutoHotkey GUI Control Popup Windows” to get a peek at how the various pop-ups look and work.) Label subroutines called gLabels are integral to making work for you GUI controls. While you can create many of your own gLabels, there are numerous built-in gLabels which are automatically invoked by specific user actions. A majority of the scripts found online (and certainly many of those in my books) make extensive use of GUI gLabels to call subroutines.

The most common way to call a Label subroutine in a GUI control is by adding the gLabel option to the Gui, Add command. Generally, the gLabel subroutine is activated by user action such as clicking a mouse button or initiating a keyboard action. In the example below, a simple GUI is created which calls the same GetTime: subroutine when the text in the GUI is clicked:

Hotkey, ^!t, GetTime
Menu, Tray, Add, Show Time, GetTime
SetTimer, GetTime, 60000
OnExit, GetTimeEnd
Gui, Add, Text, gGetTime, Click Here!
Gui, Show
Return

GetTime:
  FormatTime, OutputVar
  MsgBox, The time is %OutputVar%
Return

GetTimeEnd:
  GoSub GetTime
  ExitApp
Return

The Gui, Add command is used to create a GUI with the text “Click Here!” inside. In order to see the pop-up, the Gui, Show command must be used. With the gGetTime option included, each time the text is clicked with the left mouse button, the GetTime: subroutine runs.

This is a rudimentary example, but it illustrates the basic usage of the gLabel option. See the online line documentation to learn how each control type responds to a gLabel subroutine. Scripts using GUI controls and gLabel subroutines can get quite involved. Plus, the various GUI controls have a number of built-in Labels for special actions within the various pop-up controls (e.g. GuiClose, GuiEscape, GuiSize, GuiContextMenu, and GuiDropFiles). The proper use of these built-in GUI control Labels makes it possible to add many powerful features to your apps. The topic of using Label subroutines with GUI controls deserves much more time and is indeed a major part of some of my AutoHotkey books (especially AutoHotkey Applications).