v2 Objects

In its simplest form, an object stores a collection of values that can be accessed by a key, like a name or a list index. You can think of an object like a box that groups a bunch of variables together, where the variable names are the keys and the variable contents are the values.

Most AutoHotkey v2 objects have two key value stores, which is an upgrade from v1 where all objects had a single store. These two stores are the property store and the item store.

The property store holds values that assist with you writing your code, called properties. For example, the Length will give you a value that shows how many items are in a list. The property store uses keys that you will hard-code in your script, like variable names. The property store is accessed by dot notation, for example: object.Key where Key is the literal text for the key name. The code MsgBox object.Length will check the property store of object for the Length property.

The item store holds keys and values, and is designed to hold data where the keys will supplied by a variable. For example, if you're accessing a items from the item store in a loop you might supply keys from a loop variable. The item store is accessed by bracket notation, for example: object["Key"] where "Key" is quoted text, a variable, or some other expression.

AutoHotkey v2 has many built-in object types. For now we'll focus on these three: Basic objects, Map objects, and Array objects.

It's important to know that AutoHotkey imagines an object as being separate from the variable(s) that hold it. Every object has a secret identifying label (known generally as a "reference" or "pointer"), like a label on a box, and a variable "holding" an object just keeps track of that label. This means that when you do something like b := a where a was "holding" an object, you don't copy the object, you copy the ID Label and now have two ways to reach (reference) the same object. If you give an object as a parameter when calling other code, the other code gets a copy of the ID Label not a copy of the object. Using dot notation and bracket notation on a variable tells AutoHotkey to check the ID, find the box with the corresponding label, and look inside it for the supplied key.

Basic objects are the foundation for all other types of objects in AutoHotkey. They have very few properties defined, and do not define an item store.

Basic objects are created using either curly braces ({}), or by creating a new instance of the Object class (Object()).

Basic objects should be used when you need to store a collection of keys and values, where the keys do not change and will be hard coded into the script.

Arrays are based on basic objects, and are used to store a list of items, numbered (indexed) starting at 1.

Arrays are created using either square brackets ([]), or by creating a new instance of the Array class (Array()). Between the brackets, or the parentheses of the call to Array(), you can put a comma delimited list of items to save to the array's item store.

Arrays have a variety of built-in properties / methods that can be used to interact with the list of items.

Unlike in AutoHotkey v1, arrays are not sparse. In v1, you could specify any new index for an array and assign a value into it. However, in v2 you cannot specify new indexes and all indexes are contiguous to existing indexes. So while in v1 you could take an array with three items and assign a new item at index 54, in v2 you can only assign indexes between 1 and array.Length. If you want to extend the array, you must use the Push method.