Feb 20, 2018 - In your script, you copy a folder to another folder that you have created. Since you use 'FileCopyDir' there is no intermediate results.
A curated list of awesome AutoHotkey libraries, library distributions, scripts, tools and resources. Inspired by the other awesome lists. Please read CONTRIBUTING.md before contributing.
Out-of-date or discontinued, but nonetheless historically relevant items can be found on Historical.md
Development state:
- Awesome AutoHotkey
- Libraries
- Scripts
- Tools
- Tutorials
- Resources
- Forks
Libraries
List of useful AutoHotkey libraries. Library is code that has some reusable functionality that can be combined with your own code in order to create new functionality.
Clipboard
- WinClip - by Deo - WinClip is a clipboard manipulation class extending AutoHotkey's clipboard capabilities including support for RTF, HTML and images. Forum thread: link.
Console
- AHKonsole - by G33kdude - Class based AutoHotkey library for console support. This library enables you to create an object representing a console to interact with, as well as multiple console buffer objects to facilitate in double buffering. Forum thread: link.
- LibCon - by joedf - AutoHotkey Library For Console Support. This library enables you to write console applications and interact with other console instances. Basically, this library facilitates anything that has to do with writing and interacting with consoles. Forum thread: link.
Data format
- AHK_ctable - by hoppfrosch - Library to handle strings in tabular format - Forum thread: link.
- AutoHotkey-JSON - by cocobelgica - JSON lib for AutoHotkey. Forum thread: link.
- CSV - by trueski/kdoske - Library to work with CSV files and Listview functions. Forum thread: link.
- List manipulation functions - by Laszlo - Function library to manipulate comma delimited lists. Forum thread: link.
- ObjCSV - by JnLlnd - Library to load/save CSV files to Objects and and Listview functions. Forum thread: link.
- ObjDump/ObjLoad - by HotKeyIt - Serialize/deserialize object to/from variable/memory.
- SerDes - by cocobelgica - Serialize / de-serialize an AutoHotkey object structure. Forum thread: link.
- Table - by VxE - Library to manipulate strings in tabular (TSV) format and Listview functions. Forum thread: link.
- XA - by trueski/hi5 - Serialize/deserialize array to/from XML. Forum thread: link.
Data Structures and Algorithms
- Facade - by Shambles - A Set of Functional Programming Libraries. - Forum thread: link
- HashTable - by Shambles - A Hash Table Implementation for AutoHotkey.
- LibCrypt - by different authors - A collection of crypting and encoding functions.
- Type_Checking - by Shambles - Type Checking for AutoHotkey - Forum thread: link
Database
- ahkDBA - by IsNull - An OOP-SQL database access framework. Forum thread: link.
- Class_SQLiteDB - by just Me - AHK SQLite API wrapper class. Forum thread: link.
Filesystem
- FileGetProperties - by kon - Functions for retrieving extended file properties.
Graphics
- GDIp - by tic - Full featured library that helps in interaction with Microsoft's gdiplus.dll - Forum thread: link.
- AHKv2-GDIP - Update of the above GDI+ library compatiable with both AHK v1.1 and AHK v2 - Forum thread: link.
- GDIp_ImageSearch - by tic - Library using gdiplus.dll for searching image instances on the screen. See the end of that thread for MasterFocus' improved version, or see his GitHub repo here
- Simple GDI class - by GeekDude - A class aiming to make using low-level GDI functions simple.
- Particle System - by tidbit - A simple class to add particles to your GUI or onto your screen, using GDI+. Forum thread: link.
GUI
Combobox
- CbAutoComplete - by Pulover - Auto-completes typed values in an AHK ComboBox. Forum thread: link
Custom Controls
- Rebar - by Pulover - AHK class for AutoHotkey Rebar custom controls. Forum thread: link
- Toolbar - by Pulover - AHK Class for AutoHotkey Toolbar custom controls. Forum thread: link
Edit
- Edit v2.0 - by jballi - Library for the lightweight and surprisingly powerful default Edit control for displaying and editing text. Forum thread: link
General
- AutoXYWH - by tmplinshi - Move and resize controls automatically when a GUI is resized.
- TaskDialog - by just Me - enhanced MsgBox for Win Vista+ - link
- OnWin - by cocobelgica - Call function on window event (WinWaitXXX async). Forum thread: link
- CGUI - by ChrisS85 - An object-oriented GUI library for AutoHotkey. Forum thread: link
- Class_ScrollGUI - by just me - Creates a scrollable GUI as a parent for AHK GUI windows. Forum thread: link
ListBox
- LBEX - by just me - a collection of utility functions for ListBoxes.. Forum thread: link
- TransparentListBox - by just Me - Provides transparent listbox controls for AHK GUIs.. Forum thread: link
ListView
- LV_Colors - by just Me - Individual background and/or text colours for a GUI ListView's cells or rows. Forum thread: link
- LV_EX - by just me - Some additional functions for AHK GUI ListView controls. Forum thread: link
- LV_InCellEdit - by just Me - In-cell editing for ListView controls. Forum thread: link
- LV_Rows - by Pulover - Additional functions for AHK ListView controls. Forum thread: link
Menu
- [Lib] Menu - by just me - Some functions related to AHK menus. Forum thread: link
Hotkeys
- CHotkeyControl - by evilC - Replacement for AHK hotkey GuiControl that supports mouse buttons etc (Partially mature).
- HParse - by Avi - Function to convert meaningful shortcuts (Ctrl+X) to AutoHotkey syntax (^x).
Joystick
- CvJoyInterface - by evilC - Control a vJoy virtual joystick using AHK.
- JoystickWrapper - by evilC - Full event-based, 8 axis, 128 button, 4 POV joystick reading (C# DLL, Uses Lexikos' CLR).
- XInput - by Lexikos - Read XBOX gamepads using XInput (Only way to independently read L/R triggers), control rumble motors.
Maths
- calc() - math expression evaluation incl brackets.
- Eval - by Pulover - Evaluate expressions in strings. Forum thread: link
- Scientific Maths - by Avi - Library facilitating high precision mathematics.
- Time() - by HotkeyIt - Count Days, hours, minutes, seconds between dates. Forum thread: link
Memory
- classMemory - by RHCP (Kalamity) - An AHK memory reading/writing class with pattern scans. Forum thread: link
Networking
- AHKhttp - Basic HTTP Server. Forum link
- AHKsock - by TheGood - Function based sockets library. Supports TCP. Forum link
- Socket Class (überarbeitet) - by Bentschi - Class based sockets library. Supports TCP and UDP.
- Socket.ahk - by GeekDude - Socket library based on Bentschi's - Forum link
- WebSocket.ahk - by GeekDude - Class based WebSocket library - Forum link
- WinSCP.ahk - by Lipkau - Lib allows the use of WinSCP in AHK
Plotting (graphs, bars, charts and etc)
- BarChart - by Learning One - Library for making bar charts. Download link.
- Excel Charts - by Xx7 - Library for creating a graph in Excel, save the graph as an image and display it in a GUI.
- XGraph - by SKAN - Function library for graphically plotting real time data.
- SVGraph - by CapnOdin - SVGraph bringing graphing and charting to AutoHotkey. Forum link
- gdiChartLib - by nnnik - a gdip chart lib for autohotkey. Forum link
System
- RunAsTask - by SKAN - Auto-elevates script without UAC prompt.
- Vista Audio Control Functions - by Lexikos - Provides alternatives to some SoundSet/SoundGet subcommands, as well as some additional features that SoundSet/SoundGet do not support. Forum thread: Link
Text manipulation
- String Things - by tidbit - Stand-alone string manipulation functions.
- TF - by hi5 - Functions for manipulation of text files such as .txt, .ahk, .html, .css etc and Strings (or variables). Forum thread: link.
Library Distributions
List of useful AutoHotkey library distributions. Library Distribution is a system that is made for distributing libraries.
- ahk-libs - Ryan Shipp's collection of libraries.
- ASPDM - package/stdlib distribution and management from the ahkscript folks. Trello link.
- pAHKlight - Your Lightweight Guide to AutoHotkey libraries, classes, functions and tools.
Scripts
List of useful AutoHotkey scripts. Script is code that is intended to be used as standalone programs, and is not meant to be integrated with other code.
Clipboard
- CL3 - A clipboard manager (text only) with plugins (Search, predefined Slots, ClipChain, FIFO, Editor and more). Forum thread link.
- ClipBoardMonitor - Monitor clipboard changes, showing a tooltip of word counting for text or a temporary GUI for pictures.
- Clipjump - is a Multiple-Clipboard management utility for Windows. Source code: GitHub. Forum threads: link 1, link 2.
Filesystem
- Belvedere - sets up rules for taking actions on files (move, copy, delete, etc) based on the name of a file, its extension, size, age, and more. More info link.
Graphics
- Fun with GDIPlus - Interesting GDI+ examples.
GUI
- Examples of Non-Standard GUIs (ActiveX, GDI, etc.) - Examples of GUIs using non-standard methods to produce beautiful user interfaces.
Maths
- Monster - evaluate math expressions in strings (calculator).
- Unit Converter - unit converter that has most common English and scientific units and most common quantities from length to density to thermal conductivity. Also includes a section for physical and mathematic constants.
Mouse
- EitherMouse - Multiple mice, individual settings, auto swap mouse buttons on second mouse. Forum thread: link.
- MouseGestureL - Control applications by mouse gestures. Gestures and actions can be defined via customizable interface. Documentation in English and Japanese - Japanese Homepage link
- Radial Menu - Powerful hotkey, launcher, mouse gestures system, and much more (skinable) - Forum thread: link
Typing
- AutoComplete - Suggests and completes words as you type. Forum thread: link.
- Half-QWERTY - One-handed Typing. Using the space bar as a modifier, the user can generate the characters of either side of a full-sized keyboard using only one hand. More information via Forum thread: link
- KeyPress OSD - On-Screen Display which displays every key or mouse button press at a clearly visible text size. Forum thread: link
- Lintalist - Searchable interactive lists to copy & paste text with plugins. Forum thread: link.
- Portable Keyboard Layout - helps people to learn better, more efficient keyboard layouts such as Dvorak, Colemak or Asset. Forum thread: link.
- Thumbscript - Allows you to type using the number pad, with only 2 number presses for every letter. Documentation: link
- TypingAid - Suggests and completes words as you type. Forum thread: link GitHub link.
Window Management
- Automatic Window Manager - Save and restore last window position for each process. Forum thread: link
- bug.n - Tiling Window Manager. Forum thread: link
- Min2Tray - Minimize window to tray & more. Forum thread: link
- NiftyWindows - control of all basic window interactions such as dragging, resizing, maximizing, minimizing, closing, snap-to-grid, 'keep window aspect ratio', rolling up a window to its title bar, transparency control.
- SnapX - Enhances Windows/Aero Snap by taking over its hotkeys (Win+Left/Right, etc) and providing more fine-grained control over snap location and size. Works with multiple monitors, resolutions, and DPI levels.
- WindowPadX - tool which provides some useful functionality within multi monitor environments. WindowPadX is an enhancement of WindowPad, originally released by Lexikos, see original forum thread: link
- WindowSaver - Save and restore window layouts in Windows10 with support for virtual desktops and changing monitor setups. WindowSaver is an enhancement of DockWin v0.3 by Paul Troiano
Games
- Achromatic - ProgressPlatformer - Platform game. Forum thread: link, GitHub: link
- AHK Mahjong Solitaire - Mahjong game. Forum thread: link
- F1 Racer - 2 or 4 player racing game. Forum thread: link
- Infection - Board game. Also known as Ataxx. Forum thread: link
- Ishido - Retro puzzle game. Forum thread: link, GitHub: link
- ManyTetris - Multiple Tetris variants. Forum thread: link
- Out of the Sea - Try to avoid being fished by evolving. GitHub: link
- PABI Logical - Remake of the amiga game Logical. Forum thread: link, GitHub: link
- Sudoku - Sudoku game and solver. Forum thread: link
Tools
List of useful AutoHotkey tools. Tools made for AutoHotkey
Interpreter
- AutoHotkey - AutoHotkey interpreter installer and binaries.
- AutoHotkey DLL - AutoHotkey.dll opens the world of AutoHotkey to other programming and scripting languages. Forum thread: link. Documentation link.
- AutoHotkey build for CE - AutoHotkey for Pocket PCs / WinCE / Smartphones. Forum thread: link. Documentation link.
- IronAHK - Cross platform .NET rewrite - unfinished.
Debugging
- [Class] Console - This class is meant to simplify debugging for scripts from simple text handling, to outputting and logging data & arrays. GitHub link.
- Print Array - Function that prints array content in GUI.
- Yunit - by Uberi and infogulch - Simple unit testing framework for AutoHotkey.
Decompilers
- AutoHotkey decompiler - for AHK 1.1+ Forum thread: link.
- AutoHotkey decompiler - classic - for AHK 1.0 does not work with password or /nodecompile protected files.
Integrated Development Environment
- AHK Studio - SciLexer.dll based IDE for AutoHotkey.
- AutoGUI - AHK IDE with useful built-in plugins and GUI designer.
- AutoHotFlow - Draw your applications. Forum thread: link. GitHub link.
- DRAKON Editor - Visual programming (with DRAKON diagrams) for AutoHotkey.
- Notepad++ for AutoHotkey - Setup for popular code editor Notepad++ for AutoHotkey.
- SciTE4AutoHotkey - SciTE-based IDE for AutoHotkey.
- SublimeAutoHotkey - AutoHotkey AHK language package for SublimeText including syntax highlighting, comments toggling, auto-completions, build system definitions, commands for ahkrun, ahkcompile, ahkrunpiped.
- Sublime 4 AutoHotkey - Sublime 4 AutoHotkey is a patch for Sublime Text text editor which adds support for AutoHotkey. - (discontinued)
- vim-AHKcomplete - Vim plugin to add auto-completion. (omni-completion)
- Vim autohotkey-ahk - Vim plugin to add syntax highlighting for AutoHotkey.
- VSCode extension - Visual Studio Code (VSCode) plugin to add syntax highlighting for AutoHotkey.
GUI WYSIWYG Builders
- AutoGUI - by alguimist - WYSIWIG GUI Designer and Script Editor
- GUI Creator (formerly Basic GUI Creator) - WYSIWYG GUI Creator for AutoHotkey.
- MagicBox - by Alguimist - MagicBox is a development tool to assist in the creation of message boxes. Forum thread: link.
Script Recorders and Writers
- Pulover’s Macro Creator - a Free Automation Tool and Script Generator. Recommended for beginners. Forum thread: link. GitHub link.
Web Syntax Highlighters
- highlight.js - A syntax highlighter written in JavaScript supporting more than 130 languages (including AutoHotkey).
- PrismJs - Lightweight minimal AutoHotkey syntax highlighting.
- Syntax Highlighter - Legacy syntax highlighter for AutoHotkey with default support for line numbers.
Others
- GoTo - Addon for any text editor that helps you jump to labels, hotkeys, hotstrings and functions in the active file.
- GoToTilla - Addon which allows jumping to tokens within AHK source code.
- Context sensitive help in any editor - Addon for any text editor that provides context sensitive help by pressing F1.
- CodeQuickTester - by GeekDude - A lightweight dynamic code tester.
- iWB2 Learner - by jethrow - iWB2 Learner is a tool for gathering information about Internet Explorer webpages. Forum thread: link
- AHK-EXE-Swapper - by evilC - Swap AHK version quickly! Forum thread: link.
- AEI - by joedf - Displays AutoHotkey Environment Information and AHK support relevant System Information with a fancy update checker that auto-downloads with a progress bar. Forum thread: link.
- WinSpy - by Alguimist - Useful window spy / information tool written in AHK.
(Use in) other programming languages
- AutoHotkey.dll - Part of the AutoHotkey_H distribution. Load the autohotkey.dll from your other language, and pass normal AHK code to the dll file for execution. See here for a list of the exported functions. Some older links: python example, c/c++ example, forum link
- .NET Framework Interop (CLR, C#, VB) - Forum thread: link.
- ActiveScript - Host VBScript and JScript in-process - Provides an interface to Active Scripting languages like VBScript and JScript, without relying on Microsoft's ScriptControl, which is not available to 64-bit programs.
- Exo-Javascript - Write AHK with JavaScript - Forum thread: link, Exo-CLI (Interactive Command-line) link.
- LibLua - Note: lua.ahk and lua_ahkfunctions.ahk can be found here.
- Machine code functions: Bit Wizardry - Tutorial link, C/C++ to MCode Generator forum link.
- Embed Perl - Forum thread: link.
- PAHK - Forum thread: link.
- PYAHK - Documentation link.
- ahk - A Python wrapper for AutoHotkey - Forum thread: link
Tutorials
List of useful AutoHotkey tutorials.
Classes
- Classes in AHK, Basic tutorial - AutoHotkey classes basic tutorial.
- Classes in AHK, a Dissection (Advanced) - AutoHotkey classes advanced tutorial.
COM
- MS Office COM Basics - Using AutoHotkey with MS Office.
GUI
- Use HTML and CSS for your GUIs! - Using HTML and CSS for creating GUIs.
MCode (machine code)
- MCode Tutorial - MCode (machine code) tutorial.
Resources
List of useful AutoHotkey resources. Various websites, documentation, guides, videos and articles related to AutoHotkey.
Documentation
- Official documentation - Official uptodate AutoHotkey documentation. GitHub link.
Books
- ahkbook - a book on AutoHotkey (not completed yet). Forum thread: link.
Quick-start guides
- Official quick start tutorial - Official quick start tutorial - originally written by tidbit. Forum thread: link.
Websites
- ahkscript.org - Official website of AutoHotkey Foundation LLC, a non-profit LLC (Limited Liability Company) founded for this software. Certificate of Organization (pdf) link.
- autohotkey.com - Official website of the AutoHotkey scripting language (downloads, forum, documentation).
- ahkscript GitHub organization - Official ahkscript GitHub organization.
Forks
Forks of AHK which add new features to the core language
AutoHotkey_H
- AutoHotkey_H - AHK_H adds functionality to original AutoHotkey and offers true multi-threading using NewThread() function or AutoHotkey.dll. Full list of changes
License
This work is licensed under a Creative Commons Attribution 4.0 International License.
Table of Contents
- Text, Edit, UpDown, Picture
- Button, Checkbox, Radio
- DropDownList, ComboBox
- ListBox, ListView, TreeView
- Link, Hotkey, DateTime
- MonthCal, Slider, Progress
- GroupBox, Tab3, StatusBar
- ActiveX (e.g. Internet Explorer Control)
Text
Description: A region containing borderless text that the user cannot edit. Often used to label other controls.
For example:
Appearance:
In this case, the last parameter is the string to display. It may contain linefeeds (`n) to start new lines. In addition, a single long line can be broken up into several shorter ones by means of a continuation section.
If a width (W) is specified in Options but no rows (R) or height (H), the text will be word-wrapped as needed, and the control's height will be set automatically.
To detect when the user clicks the text, use the Click event. For example:
Text controls also support the DoubleClick event.
Only Text controls with the SS_NOTIFY (0x100) style send click and double-click notifications, so OnEvent automatically adds this style when a Click or DoubleClick callback is registered. On Windows Vista and later, the SS_NOTIFY style causes the OS to automatically copy the control's text to the clipboard when it is double-clicked.
An ampersand (&) may be used in the text to underline one of its letters. For example:
In the example above, the letter F will be underlined, which allows the user to press the shortcut keyAlt+F to set keyboard focus to the first input-capable control that was added after the text control. To instead display a literal ampersand, specify two consecutive ampersands (&&). To disable all special treatment of ampersands, include 0x80 in the control's options.
See general options for other options like Right, Center, and Hidden. See also: position and sizing of controls.
Edit
Description: An area where free-form text can be typed by the user.
For example:
Appearance:
The control will be multi-line if it has more than one row of text. For example, specifying
r3
in Options will create a 3-line edit control with the following default properties: a vertical scroll bar, word-wrapping enabled, and the Enter key captured as part of the input rather than triggering the window's default button.To start a new line in a multi-line edit control, the last parameter (contents) may contain either a solitary linefeed (`n) or a carriage return and linefeed (`r`n). Both methods produce literal `r`n pairs inside the Edit control. However, when the control's content is retrieved via Gui.Submit or GuiCtrl.Value, each `r`n in the text is always translated to a plain linefeed (`n). To bypass this End-of-Line translation, use GuiCtrl.Text. To write the text to a file, follow this example:
FileAppend(MyEdit.Text, 'C:Saved File.txt')
.If the control has word-wrapping enabled (which is the default for multi-line edit controls), any wrapping that occurs as the user types will not produce linefeed characters (only the Enter keystroke can do that).
Whenever the user changes the control's content, the Change event is raised.
TIP: To load a text file into an Edit control, use FileRead and GuiCtrl.Value. For example:
Edit Options
To remove an option rather than adding it, precede it with a minus sign:
Limit: Restricts the user's input to the visible width of the edit field. Alternatively, to limit input to a specific number of characters, include a number immediately afterward. For example,
Limit10
would allow no more than 10 characters to be entered.Lowercase: The characters typed by the user are automatically converted to lowercase.
Multi: Makes it possible to have more than one line of text. However, it is usually not necessary to specify this because it will be auto-detected based on height (H), rows (R), or contents (Text).
Number: Prevents the user from typing anything other than digits into the field (however, it is still possible to paste non-digits into it). An alternate way of forcing a numeric entry is to attach an UpDown control to the Edit.
Password: Hides the user's input (such as for password entry) by substituting masking characters for what the user types. If a non-default masking character is desired, include it immediately after the word Password. For example,
Password*
would make the masking character an asterisk rather than the black circle (bullet), which is the default on Windows XP. Note: This option has no effect for multi-line edit controls.ReadOnly: Prevents the user from changing the control's contents. However, the text can still be scrolled, selected and copied to the clipboard.
Tn: The letter T may be used to set tab stops inside a multi-line edit control (since tab stops determine the column positions to which literal TAB characters will jump, they can be used to format the text into columns). If the letter T is not used, tab stops are set at every 32 dialog units (the width of each 'dialog unit' is determined by the operating system). If the letter T is used only once, tab stops are set at every n units across the entire width of the control. For example,
Gui.Add('Edit', 'vMyEdit r16 t64')
would double the default distance between tab stops. To have custom tab stops, specify the letter T multiple times as in the following example: Gui.Add('Edit', 'vMyEdit r16 t8 t16 t32 t64 t128')
. One tab stop is set for each of the absolute column positions in the list, up to a maximum of 50 tab stops. Note: Tab stops require a multiline edit control.Uppercase: The characters typed by the user are automatically converted to uppercase.
WantCtrlA: Specify
-WantCtrlA
(minus WantCtrlA) to prevent the user's press of Control+A from selecting all text in the edit control.WantReturn: Specify
-WantReturn
(minus WantReturn) to prevent a multi-line edit control from capturing the Enter keystroke. Pressing Enter will then be the same as pressing the window's default button (if any). In this case, the user may press Control+Enter to start a new line.WantTab: Causes a Tab keystroke to produce a tab character rather than navigating to the next control. Without this option, the user may press Control+Tab to produce a tab character inside a multi-line edit control. Note: WantTab also works in a single-line edit control, but in Windows XP and lower each tab character is displayed as an empty-box character (though it is stored as a real tab).
Wrap: Specify
-Wrap
(minus Wrap) to turn off word-wrapping in a multi-line edit control. Since this style cannot be changed after the control has been created, use one of the following to change it: 1) Destroy then recreate the window and its control; or 2) Create two overlapping edit controls, one with wrapping enabled and the other without it. The one not currently in use can be kept empty and/or hidden.See general options for other options like Right, Center, and Hidden. See also: position and sizing of controls.
A more powerful edit control: HiEdit is a free, multitabbed, large-file edit control consuming very little memory. It can edit both text and binary files. For details and a demonstration, see HiEdit on GitHub.
UpDown
Description: A pair of arrow buttons that the user can click to increase or decrease a value. By default, an UpDown control automatically snaps onto the previously added control. This previous control is known as the UpDown's buddy control. The most common example is a 'spinner', which is an UpDown attached to an Edit control.
For example:
Appearance:
In the example above, the Edit control is the UpDown's buddy control. Whenever the user presses one of the arrow buttons, the number in the Edit control is automatically increased or decreased.
An UpDown's buddy control can also be a Text control or ListBox. However, due to OS limitations, controls other than these (such as ComboBox and DropDownList) might not work properly with the Change event and other features.
Specify the UpDown's starting position as the last parameter (if omitted, it starts off at 0 or the number in the allowable range that is closest to 0).
When Gui.Submit or GuiCtrl.Value is used, the return value is the current numeric position of the UpDown. If the UpDown is attached to an Edit control and you do not wish to validate the user's input, it is best to use the UpDown's value rather than the Edit's. This is because the UpDown will always yield an in-range number, even when the user has typed something non-numeric or out-of-range in the Edit control. On a related note, numbers with more than three digits get a thousands separator (such as comma) by default. These separators are returned by the Edit control but not by the UpDown control.
Whenever the user clicks one of the arrow buttons or presses an arrow key on the keyboard, the Change event is raised.
UpDown Options
Horz: Make's the control's buttons point left/right rather than up/down. By default, Horz also makes the control isolated (no buddy). This can be overridden by specifying
Horz 16
in the control's options.Left: Puts the UpDown on the left side of its buddy rather than the right.
Range: Sets the range to be something other than 0 to 100. After the word Range, specify the minimum, a dash, and maximum. For example,
Range1-1000
would allow a number between 1 and 1000 to be selected; Range-50-50
would allow a number between -50 and 50; and Range-10--5
would allow a number between -10 and -5. The minimum and maximum may be swapped to cause the arrows to move in the opposite of their normal direction. The broadest allowable range is -2147483648-2147483647. Finally, if the buddy control is a ListBox, the range defaults to 32767-0 for verticals and the inverse for horizontals (Horz).Wrap: Causes the control to wrap around to the other end of its range when the user attempts to go beyond the minimum or maximum. Without Wrap, the control stops when the minimum or maximum is reached.
16: Specify -16 (minus 16) to cause a vertical UpDown to be isolated; that is, it will have no buddy. This also causes the control to obey any specified width, height, and position rather than conforming to the size of its buddy control. In addition, an isolated UpDown tracks its own position internally. This position can be retrieved normally by means such as Gui.Submit.
0x80: Include
0x80
in Options to omit the thousands separator that is normally present between every three decimal digits in the buddy control. However, this style is normally not used because the separators are omitted from the number whenever the script retrieves it from the UpDown control itself (rather than its buddy control).Increments other than 1: In this script, NumEric demonstrates how to change an UpDown's increment to a value other than 1 (such as 5 or 0.1).
See also: position and sizing of controls.
Picture (or Pic)
Description: An area containing an image (see last two paragraphs for supported file types). The last parameter is the filename of the image, which is assumed to be in A_WorkingDir if an absolute path isn't specified.
For example:
To retain the image's actual width and/or height, omit the W and/or H options. Otherwise, the image is scaled to the specified width and/or height (this width and height also determines which icon to load from a multi-icon .ICO file). To shrink or enlarge the image while preserving its aspect ratio, specify -1 for one of the dimensions and a positive number for the other. For example, specifying
w200 h-1
would make the image 200 pixels wide and cause its height to be set automatically. If the picture cannot be loaded or displayed (e.g. file not found), the control is left empty and its width and height are set to zero.Picture controls support the Click and DoubleClick events, with the same caveat as Text controls.
To use a picture as a background for other controls, the picture should normally be added prior to those controls. However, if those controls are input-capable and the picture has the SS_NOTIFY style (which may be added automatically by OnEvent), create the picture after the other controls and include
0x4000000
(which is WS_CLIPSIBLINGS) in the picture's Options. This trick also allows a picture to be the background behind a Tab control or ListView.Icons, cursors, and animated cursors: Icons and cursors may be loaded from the following types of files: ICO, CUR, ANI, EXE, DLL, CPL, SCR, and other types that contain icon resources. To use an icon group other than the first one in the file, include in Options the word Icon followed by the number of the group. In the following example, the default icon from the second icon group would be used:
Gui.Add('Picture', 'Icon2', 'C:My Application.exe')
.Specifying the word AltSubmit in Options tells the program to use Microsoft's GDIPlus.dll to load the image, which might result in a different appearance for GIF, BMP, and icon images. For example, it would load a GIF that has a transparent background as a transparent bitmap, which allows the BackgroundTrans option to take effect (but icons support transparency without AltSubmit). If GDIPlus is not available (see next paragraph), AltSubmit is ignored and the image is loaded using the normal method.
All operating systems support GIF, JPG, BMP, ICO, CUR, and ANI images. On Windows XP or later, additional image formats such as PNG, TIF, Exif, WMF, and EMF are supported. Operating systems older than XP can be given support by copying Microsoft's free GDI+ DLL into the AutoHotkey.exe folder (but in the case of a compiled script, copy the DLL into the script's folder). To download the DLL, search for the following phrase at www.microsoft.com: gdi redistributable
Animated GIFs: Although animated GIF files can be displayed in a picture control, they will not actually be animated. To solve this, use the AniGIF DLL (which is free for non-commercial use) as demonstrated at the AutoHotkey Forums. Alternatively, the ActiveX control type can be used. For example:
A bitmap or icon handle can be used instead of a filename. For example,
'HBITMAP:' handle
.Button
Description: A pushbutton, which can be pressed to trigger an action. In this case, the last parameter is the name of the button (shown on the button itself), which may include linefeeds (`n) to start new lines.
For example:
Appearance:
The Click event is raised whenever the user clicks the button or presses Space or Enter while it has the focus.
The DoubleClick, Focus and LoseFocus events are also supported. As these events are only raised if the control has the BS_NOTIFY (0x4000) style, it is added automatically by OnEvent.
The example above includes the word Default in its Options to make 'OK' the default button. The default button's Click event is automatically triggered whenever the user presses Enter, except when the keyboard focus is on a different button or a multi-line edit control having the WantReturn style. To later change the default button to another button, follow this example, which makes the Cancel button become the default:
Gui['Cancel'].Opt('+Default')
. To later change the window to have no default button, follow this example: Gui['OK'].Opt('-Default')
.An ampersand (&) may be used in the button name to underline one of its letters. For example:
In the example above, the letter P will be underlined, which allows the user to press Alt+P as shortcut key. To display a literal ampersand, specify two consecutive ampersands (&&).
Known limitation: Certain desktop themes might not display a button's text properly. If this occurs, try including
-Wrap
(minus Wrap) in the control's options. However, this also prevents having more than one line of text.Checkbox
Description: A small box that can be checked or unchecked to represent On/Off, Yes/No, etc.
For example:
Appearance:
The last parameter is a label displayed next to the box, which is typically used as a prompt or description of what the checkbox does. It may include linefeeds (`n) to start new lines. If a width (W) is specified in Options but no rows (R) or height (H), the control's text will be word-wrapped as needed, and the control's height will be set automatically.
GuiCtrl.Value returns the number 1 for checked, 0 for unchecked, and -1 for gray/indeterminate.
Specify the word Check3 in Options to enable a third 'indeterminate' state that displays a gray checkmark or a square instead of a black checkmark (the indeterminate state indicates that the checkbox is neither checked nor unchecked). Specify the word Checked or CheckedGray in Options to have the checkbox start off checked or indeterminate, respectively. The word Checked may optionally be followed immediately by a 0, 1, or -1 to indicate the starting state. In other words,
'Checked'
and 'Checked' VarContainingOne
are the same.Whenever the checkbox is clicked, it automatically cycles between its two or three possible states, and then raises the Click event, allowing the script to immediately respond to the user's input.
The DoubleClick, Focus and LoseFocus events are also supported. As these events are only raised if the control has the BS_NOTIFY (0x4000) style, it is added automatically by OnEvent. This style is not applied by default as it prevents rapid clicks from changing the state of the checkmark (such as if the user clicks twice to toggle from unchecked to checked and then to indeterminate).
Known limitation: Certain desktop themes might not display a checkbox's text properly. If this occurs, try including
-Wrap
(minus Wrap) in the control's options. However, this also prevents having more than one line of text.Radio
Description: A radio button is a small empty circle that can be checked (on) or unchecked (off).
For example:
Appearance:
These controls usually appear in radio groups, each of which contains two or more radio buttons. When the user clicks a radio button to turn it on, any others in its radio group are turned off automatically (the user may also navigate inside a group with the arrow keys). A radio group is created automatically around all consecutively added radio buttons. To start a new group, specify the word Group in the Options of the first button of the new group -- or simply add a non-radio control in between, since that automatically starts a new group.
For the last parameter, specify the label to display to the right of the radio button. This label is typically used as a prompt or description, and it may include linefeeds (`n) to start new lines. If a width (W) is specified in Options but no rows (R) or height (H), the control's text will be word-wrapped as needed, and the control's height will be set automatically.
Specify the word Checked in Options to have the button start off in the 'on' state. The word Checked may optionally be followed immediately by a 0 or 1 to indicate the starting state: 0 for unchecked and 1 for checked. In other words,
'Checked'
and 'Checked' VarContainingOne
are the same.GuiCtrl.Value returns the number 1 for 'on' and 0 for 'off'. To instead retrieve the position number of the selected radio option within a radio group, name only one of the radio buttons and use Gui.Submit.
The Click event is raised whenever the user turns on the button. Unlike the single-variable mode in the previous paragraph, the event callback must be registered for each button in a radio group for which it should be called. This allows the flexibility to ignore the clicks of certain buttons.
The DoubleClick, Focus and LoseFocus events are also supported. As these events are only raised if the control has the BS_NOTIFY (0x4000) style, it is added automatically by OnEvent.
Known limitation: Certain desktop themes might not display a radio button's text properly. If this occurs, try including
-Wrap
(minus Wrap) in the control's options. However, this also prevents having more than one line of text.DropDownList (or DDL)
Description: A list of choices that is displayed in response to pressing a small button. In this case, the last parameter is a pipe-delimited list of choices such as
Choice1|Choice2|Choice3
or an array like ['Choice1', 'Choice2', 'Choice3']
.For example:
Appearance:
To have one of the items pre-selected when the window first appears, include two pipe characters after it (e.g.
Red|Green||Blue
). Alternatively, include in Options the word Choose followed immediately by the number of an item to be pre-selected. For example, Choose5
would pre-select the fifth item (as with other options, it can also be a variable such as 'Choose' Var
). After the control is created, use Value, Text or Choose to change the selection, and Add or Delete to add or remove entries from the list.Specify either the word Uppercase or Lowercase in Options to automatically convert all items in the list to uppercase or lowercase. Specify the word Sort to automatically sort the contents of the list alphabetically (this also affects any items added later via GuiCtrl.Add). The Sort option also enables incremental searching whenever the list is dropped down; this allows an item to be selected by typing the first few characters of its name.
When Gui.Submit or GuiCtrl.Value is used, the return value is the position number of the currently selected item (the first item is 1, the second is 2, etc.) or zero if none is selected. To get its text instead, use GuiCtrl.Text.
Whenever the user selects a new item, the Change event is raised. The Focus and LoseFocus events are also supported.
Use the R or H option to control the height of the popup list. For example, specifying
R5
would make the list 5 rows tall, while H400
would set the total height of the selection field and list to 400 pixels. If both R and H are omitted, the list will automatically expand to take advantage of the available height of the user's desktop (however, operating systems older than Windows XP will show 3 rows by default).To set the height of the selection field or list items, use the CB_SETITEMHEIGHT message as in the example below:
The separator between fields may be changed to something other than pipe (|). For example
Gui.Opt('+Delimiter`n')
would change it to linefeed and Gui.Opt('+DelimiterTab')
would change it to tab (`t).ComboBox
Description: Same as DropDownList but also permits free-form text to be entered as an alternative to picking an item from the list.
For example:
Appearance:
In addition to allowing all the same options as DropDownList above, the word Limit may be included in Options to restrict the user's input to the visible width of the ComboBox's edit field. Also, the word Simple may be specified to make the ComboBox behave as though it is an Edit field with a ListBox beneath it.
GuiCtrl.Value returns the position number of the currently selected item (the first item is 1, the second is 2, etc.) or 0 if the control contains text which does not match a list item. To get the contents of the ComboBox's edit field, use GuiCtrl.Text. Gui.Submit stores the text, unless the word AltSubmit is in the control's Options and the text matches a list item, in which case it stores the position number of the item.
Whenever the user selects a new item or changes the control's text, the Change event is raised. The Focus and LoseFocus events are also supported.
ListBox
Description: A relatively tall box containing a list of choices that can be selected. In this case, the last parameter is a pipe-delimited list of choices such as
Choice1|Choice2|Choice3
or an array like ['Choice1', 'Choice2', 'Choice3']
.For example:
Appearance:
To have list item(s) pre-selected when the window first appears, include two pipe characters after each (the Multi option is required if more than one item is to be pre-selected). Alternatively, include in Options the word Choose followed immediately by the number of an item to be pre-selected. For example,
Choose5
would pre-select the fifth item. After the control is created, use Value, Text or Choose to change the selection, and Add or Delete to add or remove entries from the list.If the Multi option is absent, GuiCtrl.Value returns the position number of the currently selected item (the first item is 1, the second is 2, etc.) or 0 if there is no item selected. To get the selected item's text instead, use GuiCtrl.Text. If the Multi option is used, Value and Text return an array of items instead of a single item.
Gui.Submit stores Text by default, but stores Value instead if the word AltSubmit is in the control's Options.
Whenever the user selects or deselects one or more items, the Change event is raised. The DoubleClick, Focus and LoseFocus events are also supported.
When adding a large number of items to a ListBox, performance may be improved by using
MyListBox.Opt('-Redraw')
prior to the operation, and MyListBox.Opt('+Redraw')
afterward.ListBox Options
Choose: See above.
Multi: Allows more than one item to be selected simultaneously via shift-click and control-click (to avoid the need for shift/control-click, specify the number 8 instead of the word Multi). In this case, Gui.Submit or GuiCtrl.Value returns an array of selected position numbers. For example,
[1, 2, 3]
would indicate that the first three items are selected. To get an array of selected texts instead, use GuiCtrl.Text. To extract the individual items from the array, use MyListBox.Text[1]
(1 would be the first item) or a For-loop such as this example:ReadOnly: Prevents items from being visibly highlighted when they are selected (but Gui.Submit, GuiCtrl.Value or GuiCtrl.Text will still return the selected item).
Sort: Automatically sorts the contents of the list alphabetically (this also affects any items added later via GuiCtrl.Add). The Sort option also enables incremental searching, which allows an item to be selected by typing the first few characters of its name.
Tn: The letter T may be used to set tab stops, which can be used to format the text into columns. If the letter T is not used, tab stops are set at every 32 dialog units (the width of each 'dialog unit' is determined by the operating system). If the letter T is used only once, tab stops are set at every n units across the entire width of the control. For example,
Gui.Add('ListBox', 'vMyListBox t64')
would double the default distance between tab stops. To have custom tab stops, specify the letter T multiple times as in the following example: Gui.Add('ListBox', 'vMyListBox t8 t16 t32 t64 t128')
. One tab stop is set for each of the absolute column positions in the list, up to a maximum of 50 tab stops.0x100: Include 0x100 in Options to turn on the LBS_NOINTEGRALHEIGHT style. This forces the ListBox to be exactly the height specified rather than a height that prevents a partial row from appearing at the bottom. This option also prevents the ListBox from shrinking when its font is changed.
To specify the number of rows of text (or the height and width), see position and sizing of controls.
ListView and TreeView
See separate pages ListView and TreeView.
Link
Description: A text control that can contain links similar to those found in a web browser. Within the control's text, enclose the link text within
<A>
and </A>
to create a clickable link. Although this looks like HTML, Link controls only support the opening <A>
tag (optionally with an ID and/or HREF attribute) and closing </A>
tag.For example:
Appearance:
Whenever the user clicks on a link, the Click event is raised. If the control has no Click callback (registered by calling OnEvent), the link's HREF is automatically executed as though passed to the Run function.
Hotkey
Description: A box that looks like a single-line edit control but instead accepts a keyboard combination pressed by the user. For example, if the user presses Control+Alt+C on an English keyboard layout, the box would display 'Ctrl + Alt + C'.
For example:
Appearance:
GuiCtrl.Value returns the control's hotkey modifiers and name, which are compatible with the Hotkey function. Examples:
^!C
, +!Home
, +^Down
, ^Numpad1
, !NumpadEnd
. If there is no hotkey in the control, the value is blank.Note: Some keys are displayed the same even though they are retrieved as different names. For example, both
^Numpad7
and ^NumpadHome
might be displayed as Ctrl + Num 7.By default, the control starts off with no hotkey specified. To instead have a default, specify its modifiers and name as the last parameter as in this example:
The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the key list for available key names.
Gui.Add('Hotkey', 'vChosenHotkey', '^!p')
The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the key list for available key names.
Whenever the user changes the control's content (by pressing a key), the Change event is raised.
Note: The event is raised even when an incomplete hotkey is present. For example, if the user holds down the Control key, the event is raised once and Value returns only a circumflex (^). When the user completes the hotkey, the event is raised again and Value returns the complete hotkey.
To restrict the types of hotkeys the user may enter, include the word Limit followed by the sum of one or more of the following numbers:
- 1: Prevent unmodified keys
- 2: Prevent Shift-only keys
- 4: Prevent Control-only keys
- 8: Prevent Alt-only keys
- 16: Prevent Shift+Control keys
- 32: Prevent Shift+Alt keys
- 64: This value is not supported (it will not behave correctly)
- 128: Prevent Shift+Control+Alt keys
For example,
Limit1
would prevent unmodified hotkeys such as letters and numbers from being entered, and Limit15
would require at least two modifier keys. If the user types a forbidden modifier combination, the Control+Alt combination is automatically and visibly substituted.The Hotkey control has limited capabilities. For example, it does not support mouse/joystick hotkeys or the Win key (LWin and RWin). One way to work around this is to provide one or more checkboxes as a means for the user to enable extra modifiers such as the Win key.
DateTime
Description: A box that looks like a single-line edit control but instead accepts a date and/or time. A drop-down calendar is also provided.
For example:
Appearance:
The last parameter is a format string, as described below.
SetFormat
Sets the display format of a DateTime control.
Type: String
One of the following:
ShortDate (or omitted/blank): Uses the locale's short date format. For example, in some locales it would look like: 6/1/2005
LongDate: Uses the locale's long date format. For example, in some locales it would look like: Wednesday, June 01, 2005
Time: Shows only the time using the locale's time format. Although the date is not shown, it is still present in the control and will be retrieved along with the time in the YYYYMMDDHH24MISS format. For example, in some locales it would look like: 9:37:45 PM
(custom format): Specify any combination of date and time formats. For example,
'M/d/yy HH:mm'
would look like 6/1/05 21:37. Similarly, 'dddd MMMM d, yyyy hh:mm:ss tt'
would look like Wednesday June 1, 2005 09:37:45 PM. Letters and numbers to be displayed literally should be enclosed in single quotes as in this example: 'Date:' MM/dd/yy 'Time:' hh:mm:ss tt'
. By contrast, non-alphanumeric characters such as spaces, tabs, slashes, colons, commas, and other punctuation do not need to be enclosed in single quotes. The exception to this is the single quote character itself: to produce it literally, use four consecutive single quotes (''), or just two if the quote is already inside an outer pair of quotes.DateTime Usage
To have a date other than today pre-selected, include in Options the word Choose followed immediately by a date in YYYYMMDD format. For example,
Choose20050531
would pre-select May 31, 2005 (as with other options, it can also be a variable such as 'Choose' Var
). To have no date/time selected, specify ChooseNone. ChooseNone also creates a checkbox inside the control that is unchecked whenever the control has no date. Whenever the control has no date, Gui.Submit or GuiCtrl.Value will retrieve a blank value (empty string).The time of day may optionally be present. However, it must always be preceded by a date when going into or coming out of the control. The format of the time portion is HH24MISS (hours, minutes, seconds), where HH24 is expressed in 24-hour format; for example, 09 is 9am and 21 is 9pm. Thus, a complete date-time string would have the format YYYYMMDDHH24MISS.
When specifying dates in the YYYYMMDDHH24MISS format, only the leading part needs to be present. Any remaining element that has been omitted will be supplied with the following default values: MM with month 01, DD with day 01, HH24 with hour 00, MI with minute 00 and SS with second 00.
Within the drop-down calendar, the today-string at the bottom can be clicked to select today's date. In addition, the year and month name are clickable and allow easy navigation to a new month or year.
Keyboard navigation: Use the ↑/↓ arrow keys, the +/- numpad keys, and Home/End to increase or decrease the control's values. Use ← and → to move from field to field inside the control. Within the drop-down calendar, use the arrow keys to move from day to day; use PageUp/PageDown to move backward/forward by one month; use Ctrl+PageUp/PageDown to move backward/forward by one year (only supported on Win XP and earlier); and use Home/End to select the first/last day of the month.
When Gui.Submit or GuiCtrl.Value is used, the return value is the selected date and time in YYYYMMDDHH24MISS format. Both the date and the time are present regardless of whether they were actually visible in the control.
Whenever the user changes the date or time, the Change event is raised. The Focus and LoseFocus events are also supported.
DateTime Options
Choose: See above.
Range: Restricts how far back or forward in time the selected date can be. After the word Range, specify the minimum and maximum dates in YYYYMMDD format (with a dash between them). For example,
Range20050101-20050615
would restrict the date to the first 5.5 months of 2005. Either the minimum or maximum may be omitted to leave the control unrestricted in that direction. For example, Range20010101
would prevent a date prior to 2001 from being selected and Range-20091231
(leading dash) would prevent a date later than 2009 from being selected. Without the Range option, any date between the years 1601 and 9999 can be selected. The time of day cannot be restricted.Right: Causes the drop-down calendar to drop down on the right side of the control instead of the left.
1: Specify the number 1 in Options to provide an up-down control to the right of the control to modify date-time values, which replaces the button of the drop-down month calendar that would otherwise be available. This does not work in conjunction with the format option LongDate described above.
2: Specify the number 2 in Options to provide a checkbox inside the control that the user may uncheck to indicate that no date/time is selected. Once the control is created, this option cannot be changed.
MonthCal
Description: A tall and wide control that displays all the days of the month in calendar format. The user may select a single date or a range of dates.
For example:
Appearance:
To have a date other than today pre-selected, specify it as the third parameter in YYYYMMDD format (e.g.
20050531
). A range of dates may also be pre-selected by including a dash between two dates (e.g. '20050525-20050531'
).It is usually best to omit width (W) and height (H) for a MonthCal because it automatically sizes itself to fit exactly one month. To display more than one month vertically, specify
R2
or higher in Options. To display more than one month horizontally, specify W-2
(W negative two) or higher. These options may both be present to expand in both directions.The today-string at the bottom of the control can be clicked to select today's date. In addition, the year and month name are clickable and allow easy selection of a new year or month.
Keyboard navigation: On Windows Vista and later, keyboard navigation is fully supported in MonthCal, but only if it has the keyboard focus. For supported keyboard shortcuts, see DateTime's keyboard navigation (within the drop-down calendar).
When Gui.Submit or GuiCtrl.Value is used, the return value is the selected date in YYYYMMDD format (without any time portion). However, when the multi-select option is in effect, the minimum and maximum dates are retrieved with a dash between them (e.g.
20050101-20050108
). If only a single date was selected in a multi-select calendar, the minimum and maximum are both present but identical. StrSplit can be used to separate the dates. For example, the following would put the minimum in Date[1] and the maximum in Date[2]: Date := StrSplit(MyMonthCal.Value, '-')
.The Change event is raised when the user changes the selection. On Windows XP and earlier, due to a quirk of the OS, the event is also raised every two minutes for the case a new day has arrived.
When specifying dates in the YYYYMMDD format, the MM and/or DD portions may be omitted, in which case they are assumed to be 1. For example,
200205
is seen as 20020501, and 2005
is seen as 20050101.MonthCal Options
Multi: Multi-select. Allows the user to shift-click or click-drag to select a range of adjacent dates (the user may still select a single date too). This option may be specified explicitly or put into effect automatically by means of specifying a selection range when the control is created. For example:
Gui.Add('MonthCal', 'vMyCal', '20050101-20050108')
. Once the control is created, this option cannot be changed.Range: Restricts how far back or forward in time the calendar can go. After the word Range, specify the minimum and maximum dates in YYYYMMDD format (with a dash between them). For example,
Range20050101-20050615
would restrict the selection to the first 5.5 months of 2005. Either the minimum or maximum may be omitted to leave the calendar unrestricted in that direction. For example, Range20010101
would prevent a date prior to 2001 from being selected and Range-20091231
(leading dash) would prevent a date later than 2009 from being selected. Without the Range option, any date between the years 1601 and 9999 can be selected.4: Specify the number 4 in Options to display week numbers (1-52) to the left of each row of days. Week 1 is defined as the first week that contains at least four days.
8: Specify the number 8 in Options to prevent the circling of today's date within the control.
16: Specify the number 16 in Options to prevent the display of today's date at the bottom of the control.
Slider
Description: A sliding bar that the user can move along a vertical or horizontal track. The standard volume control in the taskbar's tray is an example of a slider.
For example:
Appearance:
Specify the starting position of the slider as the last parameter. If the last parameter is omitted, the slider starts off at 0 or the number in the allowable range that is closest to 0.
The user may slide the control by the following means: 1) dragging the bar with the mouse; 2) clicking inside the bar's track area with the mouse; 3) turning the mouse wheel while the control has focus; or 4) pressing the following keys while the control has focus: ↑, →, ↓, ←, PageUp, PageDown, Home, and End.
GuiCtrl.Value and Gui.Submit return or store the current numeric position of the slider.
Detecting Changes
By default, the slider's Change event is raised when the user has stopped moving the slider, such as by releasing the mouse button after having dragging it. If the control has the AltSubmit option, the Change event is also raised (very frequently) after each visible movement of the bar while the user is dragging it with the mouse.
Type: Integer
A numeric value from the table below indicating how the slider was moved. These values and the corresponding names are defined in the Windows SDK.
Value | Name | Meaning |
---|---|---|
0 | TB_LINEUP | The user pressed the ← or ↑ key. |
1 | TB_LINEDOWN | The user pressed the → or ↓ key. |
2 | TB_PAGEUP | The user pressed the PageUp key. |
3 | TB_PAGEDOWN | The user pressed the PageDown key. |
4 | TB_THUMBPOSITION | The user moved the slider via the mouse wheel, or finished a drag-and-drop to a new position. |
6 | TB_TOP | The user pressed the Home key to send the slider to the left or top side. |
7 | TB_BOTTOM | The user pressed the End key to send the slider to the right or bottom side. |
Only if the AltSubmit option is used: | ||
5 | TB_THUMBTRACK | The user is currently dragging the slider via the mouse; that is, the mouse button is currently down. |
8 | TB_ENDTRACK | The user has finished moving the slider, either via the mouse or the keyboard. Note: With the exception of mouse wheel movement (#4), the Change event is raised again for #8 even though it was already raised with one of the digits above. |
Slider Options
Buddy1 and Buddy2: Specifies up to two existing controls to automatically reposition at the ends of the slider. Buddy1 is displayed at the left or top side (depending on whether the Vertical option is present). Buddy2 is displayed at the right or bottom side. After the word Buddy1 or Buddy2, specify the Name or HWND of an existing control. For example,
Buddy1MyTopText
would assign the control whose name is MyTopText. The text or ClassNN of a control can also be used, but only up to the first space or tab.Center: The thumb (the bar moved by the user) will be blunt on both ends rather than pointed at one end.
Invert: Reverses the control so that the lower value is considered to be on the right/bottom rather than the left/top. This is typically used to make a vertical slider move in the direction of a traditional volume control. Note: The ToolTip option described below will not obey the inversion and therefore should not be used in this case.
Left: The thumb (the bar moved by the user) will point to the top rather than the bottom. But if the Vertical option is in effect, the thumb will point to the left rather than the right.
Line: Specifies the number of positions to move when the user presses one of the arrow keys. After the word Line, specify number of positions to move. For example:
Line2
.NoTicks: Omits tickmarks alongside the track.
Page: Specifies the number of positions to move when the user presses the PageUp or PageDown key. After the word Page, specify number of positions to move. For example:
Page10
.Range: Sets the range to be something other than 0 to 100. After the word Range, specify the minimum, a dash, and maximum. For example,
Range1-1000
would allow a number between 1 and 1000 to be selected; Range-50-50
would allow a number between -50 and 50; and Range-10--5
would allow a number between -10 and -5.Thick: Specifies the length of the thumb (the bar moved by the user). After the word Thick, specify the thickness in pixels (e.g.
Thick30
). To go beyond a certain thickness on Windows XP or later, it is probably necessary to either specify the Center option or remove the theme from the control (which can be done by specifying -Theme
in the control's options).TickInterval: Provides tickmarks alongside the track at the specified interval. After the word TickInterval, specify the interval at which to display additional tickmarks (if the interval is never set, it defaults to 1). For example,
TickInterval10
would display a tickmark once every 10 positions.ToolTip: Creates a tooltip that reports the numeric position of the slider as the user is dragging it. To have the tooltip appear in a non-default position, specify one of the following instead:
ToolTipLeft
or ToolTipRight
(for vertical sliders); ToolTipTop
or ToolTipBottom
(for horizontal sliders).Vertical: Makes the control slide up and down rather than left and right.
The above options can be changed via GuiCtrl.Opt after the control is created.
Progress
Description: A dual-color bar typically used to indicate how much progress has been made toward the completion of an operation.
For example:
Appearance:
Specify the starting position of the bar as the third parameter (if omitted, the bar starts off at 0 or the number in the allowable range that is closest to 0). To later change the position of the bar, follow these examples, all of which operate upon a progress bar whose Name is MyProgress:
For horizontal Progress Bars, the thickness of the bar is equal to the control's height. For vertical Progress Bars it is equal to the control's width.
Progress Options
Cn: Changes the bar's color. Specify for n one of the 16 primary HTML color names or a 6-digit RGB color value. Examples:
cRed
, cFFFF33
, cDefault
. If the C option is never used (or cDefault
is specified), the system's default bar color will be used.BackgroundN: Changes the bar's background color. Specify for n one of the 16 primary HTML color names or a 6-digit RGB color value. Examples:
BackgroundGreen
, BackgroundFFFF33
, BackgroundDefault
. If the Background option is never used (or BackgroundDefault
is specified), the background color will be that of the window or tab control behind it.Range: Sets the range to be something other than 0 to 100. After the word Range, specify the minimum, a dash, and maximum. For example,
Range0-1000
would allow numbers between 0 and 1000; Range-50-50
would allow numbers between -50 and 50; and Range-10--5
would allow numbers between -10 and -5.Smooth: Displays a simple continuous bar. If this option is not used and the bar does not have any custom colors, the bar's appearance is defined by the current system theme. Otherwise, the bar appears as a length of segments.
Vertical: Makes the bar rise or fall vertically rather than move along horizontally.
The above options can be changed via GuiCtrl.Opt after the control is created.
GroupBox
Description: A rectangular border/frame, often used around other controls to indicate they are related. In this case, the last parameter is the title of the box, which if present is displayed at its upper-left edge.
For example:
Appearance:
By default, a GroupBox's title may have only one line of text. This can be overridden by specifying
Wrap
in Options.To specify the number of rows inside the control (or its height and width), see position and sizing of controls.
Tab3
Description: A large control containing multiple pages, each of which contains other controls. From this point forward, these pages are referred to as 'tabs'.
There are three types of Tab control:
- Tab3: Fixes some issues which affect Tab2 and Tab. Controls are placed within an invisible 'tab dialog' which moves and resizes with the tab control. The tab control is themed by default.
- Tab2: Fixes rare redrawing problems in the original 'Tab' control but introduces some other problems.
- Tab: Retained for backward compatibility because of differences in behavior between Tab2/Tab3 and Tab.
For example:
Appearance:
The last parameter above is a pipe-delimited list or an array of tab names. To have one of the tabs pre-selected when the window first appears, include two pipe characters after it (e.g.
'Red|Green||Blue'
). Alternatively, include in Options the word Choose followed immediately by the number of a tab to be pre-selected. For example, Choose5
would pre-select the fifth tab (as with other options, it can also be a variable such as 'Choose' Var
). After the control is created, use Value, Text or Choose to change the selected tab, and Add or Delete to add or remove tabs.After creating a Tab control, subsequently added controls automatically belong to its first tab. This can be changed at any time by following these examples (in this case, Tab is the GuiControl object of the first tab control and Tab2 of the second one):
![Autohotkey Autohotkey](https://a.fsdn.com/con/app/proj/autogui/screenshots/Menu%20Editor.png/1)
It is also possible to use any of the examples above to assign controls to a tab or tab-control that does not yet exist (except in the case of the Name method). But in that case, the relative positioning options described below are not supported.
Positioning: When each tab of a Tab control receives its first sub-control, that sub-control will have a special default position under the following conditions: 1) The X and Y coordinates are both omitted, in which case the first sub-control is positioned at the upper-left corner of the tab control's interior (with a standard margin), and sub-controls beyond the first are positioned beneath the previous control; 2) The X+n and/or Y+n positioning options are specified, in which case the sub-control is positioned relative to the upper-left corner of the tab control's interior. For example, specifying
x+10 y+10
would position the control 10 pixels right and 10 pixels down from the upper left corner.Current tab: GuiCtrl.Value returns the position number of the currently selected tab (the first tab is 1, the second is 2, etc.). To get its text instead, use GuiCtrl.Text. Gui.Submit stores Text by default, but stores Value instead if the word AltSubmit is in the control's Options.
Detecting tab selection: Whenever the user switches tabs, the Change event is raised.
Keyboard navigation: The user may press Control+PageDown/PageUp to navigate from page to page in a tab control; if the keyboard focus is on a control that does not belong to a Tab control, the window's first Tab control will be navigated. Control+Tab and Control+Shift+Tab may also be used except that they will not work if the currently focused control is a multi-line Edit control.
Limits: Each window may have no more than 255 tab controls. Each tab control may have no more than 256 tabs (pages). In addition, a tab control may not contain other tab controls.
Tab3 vs. Tab2 vs. Tab
Parent window: The parent window of a control affects the positioning and visibility of the control and tab-key navigation order. If a sub-control is added to an existing Tab3 control, its parent window is the 'tab dialog', which fills the tab control's display area. Most other controls, including sub-controls of Tab or Tab2 controls, have no parent other than the GUI window itself.
Positioning: For Tab and Tab2, sub-controls do not necessarily need to exist within their tab control's boundaries: they will still be hidden and shown whenever their tab is selected or de-selected. This behavior is especially appropriate for the 'buttons' style described below.
For Tab3, sub-controls assigned to a tab before the tab control is created behave as though added to a Tab or Tab2 control. All other sub-controls are visible only within the display area of the tab control.
If a Tab3 control is moved, its sub-controls are moved with it. Tab and Tab2 controls do not have this behavior.
In the rare case that WinMove (or an equivalent DllCall) is used to move a control, the coordinates must be relative to the parent window of the control, which might not be the GUI (see above). By contrast, GuiCtrl.Move takes GUI coordinates and ControlMove takes window coordinates, regardless of the control's parent window.
Autosizing: If not specified by the script, the width and/or height of the Tab3 control are automatically calculated at one of the following times (whichever comes first after the control is created):
- The first time the Tab3 control ceases to be the current tab control. This can occur as a result of calling GuiCtrl.UseTab (with or without parameters) or creating another tab control.
- The first time Gui.Show is called for that particular Gui.
The calculated size accounts for sub-controls which exist when autosizing occurs, plus the default margins. The size is calculated only once, and will not be recalculated even if controls are added later. If the Tab3 control is empty, it receives the same default size as a Tab or Tab2 control.
Tab and Tab2 controls are not autosized; they receive an arbitrary default size.
Tab-key navigation order: The navigation order via the Tab key usually depends on the order in which the controls are created. When tab controls are used, the order also depends on the type of tab control:
- Tab and Tab2 allow their sub-controls to be mixed with other controls within the tab-key order.
- Tab2 puts its tab buttons after its sub-controls in the tab-key order.
- Tab3 groups its sub-controls within the tab-key order and puts them after its tab buttons.
Notification messages (Tab3): Common and Custom controls typically send notification messages to their parent window. Any WM_COMMAND, WM_NOTIFY, WM_VSCROLL, WM_HSCROLL or WM_CTLCOLOR' messages received by a Tab3 control's tab dialog are forwarded to the GUI window and can be detected by using OnMessage. If the tab control is themed and the sub-control lacks the +BackgroundTrans option, WM_CTLCOLORSTATIC is fully handled by the tab dialog and not forwarded. Other notification messages (such as custom messages) are not supported.
Known issues with Tab2:
- BackgroundTrans has no effect inside a Tab2 control.
- WebBrowser controls do not redraw correctly.
- AnimateWindow and possibly other Win32 API calls can cause the tab's controls to disappear.
Known issues with Tab:
- Activating a GUI window by clicking certain parts of its controls, such as scrollbars, might redraw improperly.
- BackgroundTrans has no effect if the Tab control contains a ListView.
- WebBrowser controls are invisible.
Tab Options
Choose: See above.
Background: Specify
-Background
(minus Background) to override the window's custom background color and use the system's default Tab control color. Specify +Theme -Background
to make the Tab control conform to the current desktop theme. However, most control types will look strange inside such a Tab control because their backgrounds will not match that of the tab control. This can be fixed for some control types (such as Text) by adding BackgroundTrans to their options.Buttons: Creates a series of buttons at the top of the control rather than a series of tabs (in this case, there will be no border by default because the display area does not typically contain controls).
Left/Right/Bottom: Specify one of these words to have the tabs on the left, right, or bottom side instead of the top. See TCS_VERTICAL for limitations on Left and Right.
Wrap: Specify
-Wrap
(minus Wrap) to prevent the tabs from taking up more than a single row (in which case if there are too many tabs to fit, arrow buttons are displayed to allow the user to slide more tabs into view).To specify the number of rows of text inside the control (or its height and width), see position and sizing of controls.
Icons in Tabs: An icon may be displayed next to each tab's name/text via SendMessage. This is demonstrated in the forum topic Icons in tabs.
![Autohotkey copy paste examples Autohotkey copy paste examples](/uploads/1/2/5/6/125684191/361550519.png)
StatusBar
Description: A row of text and/or icons attached to the bottom of a window, which is typically used to report changing conditions.
For example:
Appearance:
The simplest use of a status bar is to call SB.SetText whenever something changes that should be reported to the user. To report more than one piece of information, divide the bar into sections via SB.SetParts. To display icon(s) in the bar, call SB.SetIcon.
StatusBar Methods
SetText
Displays NewText in the specified part of the status bar, and returns 1 upon success and 0 upon failure.
Type: String
Up to two tab characters (`t) may be present anywhere in NewText: anything to the right of the first tab is centered within the part, and anything to the right of the second tab is right-justified.
Type: Integer
If PartNumber is omitted, it defaults to 1. Otherwise, specify an integer between 1 and 256.
Type: Integer
If Style is omitted, it defaults to 0, which uses a traditional border that makes that part of the bar look sunken. Otherwise, specify 1 to have no border or 2 to have border that makes that part of the bar look raised.
SetParts
Divides the bar into multiple sections according to the specified widths (in pixels), and returns a non-zero value (the status bar's HWND).
Type: Integer
If all parameters are omitted, the bar is restored to having only a single, long part. Otherwise, specify the width of each part except the last (the last will fill the remaining width of the bar). For example,
SB.SetParts(50, 50)
would create three parts: the first two of width 50 and the last one of all the remaining width.Note: Any parts 'deleted' by
SB.SetParts()
will start off with no text the next time they are shown (furthermore, their icons are automatically destroyed).SetIcon
Displays a small icon to the left of the text in the specified part, and returns the icon's handle.
Type: String
The path of an icon or image file. For a list of supported formats, see the Picture control.
A bitmap or icon handle can be used instead of a filename. For example,
SB.SetIcon('HICON:' handle)
.Type: Integer
To use an icon group other than the first one in the file, specify its number for IconNumber. For example,
SB.SetIcon('Shell32.dll', 2)
would use the default icon from the second icon group. If IconNumber is negative, its absolute value is assumed to be the resource ID of an icon within an executable file.Type: Integer
If PartNumber is omitted, it defaults to 1. Otherwise, specify an integer between 1 and 256.
Note: The HICON is a system resource that can be safely ignored by most scripts because it is destroyed automatically when the status bar's window is destroyed. Similarly, any old icon is destroyed when
SB.SetIcon()
replaces it with a new one. This can be avoided via:SetProgress
Creates and controls a progress bar inside the status bar. This function is available at www.autohotkey.com/forum/topic37754.html
StatusBar Usage
Reacting to mouse clicks: Whenever the user clicks on the bar, the Click, DoubleClick or ContextMenu event is raised, and the Info or Item parameter contains the part number. However, the part number might be a very large integer if the user clicks near the sizing grip at the right side of the bar.
Font and color: Although the font size, face, and style can be set via Gui.SetFont (just like normal controls), the text color cannot be changed. The status bar's background color may be changed by specifying in Options the word Background followed immediately by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples:
BackgroundSilver
, BackgroundFFDD99
, BackgroundDefault
.Hiding the StatusBar: Upon creation, the bar can be hidden via
MyStatusBar := Gui.Add('StatusBar', 'Hidden')
. To hide it sometime after creation, use MyStatusBar.Visible := false
. To show it, use MyStatusBar.Visible := true
. Note: Hiding the bar does not reduce the height of the window. If that is desired, one easy way is Gui.Show('AutoSize')
.Styles (rarely used): See the StatusBar styles table.
Known limitations: 1) Any control that overlaps the status bar might sometimes get drawn on top of it. One way to avoid this is to dynamically shrink such controls via Size event. 2) There is a limit of one status bar per window.
Example: Example #1 at the bottom of the TreeView page demonstrates a multipart status bar.
ActiveX
ActiveX components such as the MSIE browser control can be embedded into a GUI window by following this example:
When the control is created, the ActiveX object can be retrieved via GuiCtrl.Value.
To handle events exposed by the object, use ComObjConnect as demonstrated below:
ComObjType can be used to determine the type of the retrieved object.
Custom
Other controls which are not directly supported by AutoHotkey can be also embedded into a GUI window. In order to do so, include in Options the word Class followed by the Win32 class name of the desired control. Examples:
AutoHotkey uses the standard Windows control text routines when text is to be retrieved/replaced in the control via
Gui.Add
or GuiCtrl.Value
.Events: Since the meaning of each notification code depends on the control which sent it, OnEvent is not supported for Custom controls. However, if the control sends notifications in the form of a WM_NOTIFY or WM_COMMAND message, the script can use OnNotify or OnCommand to detect them.
Here is an example that shows how to add and use an IP address control:
Related Pages
ListView, TreeView, GuiCreate, Gui object, GuiControl object, Menu object