Differences

This shows you the differences between two versions of the page.

--- guides:objects [2025-03-31 14:44] – [Fundamentals of Class Objects] geek
+++ guides:objects [2025-03-31 17:28] (current) – Move classes header to separate page geek
@@ Line 328: / Line 328: @@
 ===== Classes =====
-In AutoHotkey, classes are a way to design a template for new objects to create. Each object created from the class, called an instance, have a similar set of properties to each other. This is how the name, "class", was chosen to represent the concept.
+See: [[guides:objects:classes|]]
-Imagine you're writing a script where you're working extensively with X/Y coordinates. All over, you may have object definitions like ''{ x: 123, y: 456 }''. Conceptually, all of these objects could be said to be the same. While we can see that as readers browsing through a script, it is somewhat more difficult for AHK itself (and the tools for writing scripts) to come to that conclusion. Instead of defining the object structure every time we want a coordinate pair, we can instead define the structure once and re-use that template all over the script.
-<runner ahk2>
-/**
- * Define a class object: a template for instance objects to be made from.
- * Represents an X/Y coordinate pair.
- */
-class Coord {
-    x := 0
-    y := 0
-}
-/**
- * Gets the cursor position
- *
- * @return {Coord} The coordinate pair corresponding to the cursor
- */
-MyMousePosGetter() {
-    MouseGetPos &x, &y
-    ; Create an instance object, modeled after the class object.
-    ; Like AHK's built-in `Object()`.
-    pair := Coord()
-    pair.x := x
-    pair.y := y
-    return pair
-}
-pos := MyMousePosGetter()
-MsgBox pos.x "," pos.y
-</runner>
-With this new Coord class, functions which return a coordinate pair can be more useful to work with than ones returning a basic object. If you're using a supported editor like Visual Studio Code, when typing code such as that last line ''MsgBox pos.x "," pos.y'', once you get through the ''pos.'' bit the editor will display an Intellisense tool-tip with all the properties known to the Coord class (here, ''x'' or ''y''). That tool-tip will filter to show potential matches as you're typing out the property name.
-Now, you might notice that we've gone from a simple one line definition of returning a basic object to now four full lines of creating the object from the template, filling its properties, and returning the object. This explosion of size can be managed handily through a concept known as //constructors//. A constructor is a routine that takes in some arguments and uses them to populate the properties of an object. In AutoHotkey, the default constructor can be specified by defining a specially named function inside the class called ''%%__New%%''.
-<runner ahk2>
-/**
- * Define a class object: a template for instance objects to be made from.
- * Represents an X/Y coordinate pair.
- */
-class Coord {
-    x := 0
-    y := 0
-    /**
-     * Constructor for the Coord object, takes arguments x and y
-     * and populates the x and y properties of the object.
-     */
-    __New(x, y) {
-        this.x := x
-        this.y := y
-    }
-}
-/**
- * Gets the cursor position
- *
- * @return {Coord} The coordinate pair corresponding to the cursor
- */
-MyMousePosGetter() {
-    MouseGetPos &x, &y
-    return Coord(x, y)
-}
-pos := MyMousePosGetter()
-MsgBox pos.x "," pos.y
-</runner>
-This simple addition, a function inside the class definition, exposes the second great strength of classes. Instead of just containing data, they can also specify the functions that pertain to that data. For example, we could add a function like ''RelativeTo'' which gives us our coordinate as relative to another coordinate. When a function is kept as part of an object, such as defining it in a class so it may be copied to an object by template, it is called a //method//.
-<runner ahk2>
-/**
- * Define a class object: a template for instance objects to be made from.
- * Represents an X/Y coordinate pair.
- */
-class Coord {
-    x := 0
-    y := 0
-    /**
-     * Constructor for the Coord object, takes arguments x and y
-     * and populates the x and y properties of the object.
-     */
-    __New(x, y) {
-        this.x := x
-        this.y := y
-    }
-    /**
-     * Returns a new coordinate with its positions holding the relative
-     * values between this coordinate and the target coordinate.
-     */
-    RelativeTo(targetCoord) {
-        return Coord(this.x - targetCoord.x, this.y - targetCoord.y)
-    }
-}
-/**
- * Gets the cursor position
- *
- * @return {Coord} The coordinate pair corresponding to the cursor
- */
-MyMousePosGetter() {
-    MouseGetPos &x, &y
-    return Coord(x, y)
-}
-/**
- * Gets the position of the given window
- * @return {Coord} The coordinate pair corresponding to the window position
- */
-MyWinPosGetter(title) {
-    WinGetPos &x, &y, &w, &h, title
-    return Coord(x, y)
-}
-; Get the active window's position
-WinMove 30, 40, 50, 60, "Notepad"
-winPos := MyWinPosGetter("Notepad")
-; Get the mouse position
-MouseMove 123, 456
-mousePos := MyMousePosGetter()
-MsgBox "Cursor position: " mousePos.x ", " mousePos.y
-MsgBox "Window position: " winPos.x ", " winPos.y
-relativePos := mousePos.RelativeTo(winPos)
-MsgBox "Relative position: " relativePos.x ", " relativePos.y
-</runner>
-Alongside methods that can be called to manipulate the object's data, we can add "static" methods. Static methods are methods that don't operate on the data of a populated instance, but instead are standalone functions that merely relate to the concept of the class. For example, we have written these two independent "getter" functions that create Coord instance objects. These getters don't rely on the properties of an already existing Coord instance object, but they do relate to the Coord objects conceptually. If we wanted, we could turn them into static methods so they may be grouped together logically:
-<runner ahk2>
-/**
- * Define a class object: a template for instance objects to be made from.
- * Represents an X/Y coordinate pair.
- */
-class Coord {
-    x := 0
-    y := 0
-    /**
-     * Constructor for the Coord object, takes arguments x and y
-     * and populates the x and y properties of the object.
-     */
-    __New(x, y) {
-        this.x := x
-        this.y := y
-    }
-    /**
-     * Returns a new coordinate with its positions holding the relative
-     * values between this coordinate and the target coordinate.
-     */
-    RelativeTo(targetCoord) {
-        return Coord(this.x - targetCoord.x, this.y - targetCoord.y)
-    }
-/**
- * Gets the cursor position
- *
- * @return {Coord} The coordinate pair corresponding to the cursor
- */
-MyMousePosGetter() {
-    MouseGetPos &x, &y
-    return Coord(x, y)
-}
-/**
- * Gets the position of the given window
- * @return {Coord} The coordinate pair corresponding to the window position
- */
-MyWinPosGetter(title) {
-    WinGetPos &x, &y, &w, &h, title
-    return Coord(x, y)
-}
-}
-; Get the active window's position
-WinMove 30, 40, 50, 60, "Notepad"
-winPos := MyWinPosGetter("Notepad")
-; Get the mouse position
-MouseMove 123, 456
-mousePos := MyMousePosGetter()
-MsgBox "Cursor position: " mousePos.x ", " mousePos.y
-MsgBox "Window position: " winPos.x ", " winPos.y
-relativePos := mousePos.RelativeTo(winPos)
-MsgBox "Relative position: " relativePos.x ", " relativePos.y
-</runner>
-==== Function Objects ====
-In AutoHotkey v1, there were several global collections of names that were kept separate. There was a collection of command names, a collection of label names, a collection of function names, and a collection of variable names. AutoHotkey v2 has mostly merged these collections, folding them all into the //just// variable name collection. Label-based subroutines have been replaced in favor of functions. Commands have been replaced in favor of functions. And, critically, functions have been redesigned to all be stored //inside// global variables.
-Allowing functions to be saved inside variables and passed around like data is known as having [[https://en.wikipedia.org/wiki/First-class_function|first-class functions]]. In AutoHotkey, it is achieved by using [[https://www.autohotkey.com/docs/v2/misc/Functor.htm|function objects]], which are objects that can run code when you use the call syntax: ''name()''. Both user-defined functions and built-in functions are implemented this way, with function definition syntax creating a global variable by the function's name to hold the function object.
-<runner ahk2>
-MyFunction() {
-    ; No matter how this function is called, the message box
-    ; will say "You called MyFunction".
-    MsgBox "You called " A_ThisFunc
-}
-MsgBox IsObject(MsgBox) ", " Type(MsgBox)
-MsgBox IsObject(MyFunction) ", " Type(MyFunction)
-MyVar := MyFunction ; Put MyFunction into a different variable
-MyVar() ; Call the function object stored inside MyVar
-</runner>
-Function objects come inside global read-only variables by default, but can be passed around just like any other object. As shown above, it's easy to put the function object into a different variable even if the new variable has a different name. Additionally, AutoHotkey allows you to //skip// defining the global read-only variable by defining some functions directly inside an expression:
-<runner ahk2>
-MyVar := () => MsgBox("You called '" A_ThisFunc "' (the arrow function)")
-MyVar()
-; In AHKv2.1 this is allowed as well:
-;MyVar2 := () {
-;    MsgBox "You called '" A_ThisFunc "' (the function expression)"
-;}
-;MyVar2()
-</runner>
-By itself, this syntax is usually seen when defining OnEvent type callbacks. It allows you to skip defining a function that might only be called in one place:
-<code autohotkey>
-CloseCallback() {
-    MsgBox "You tried to close the GUI"
-}
-g := Gui()
-g.OnEvent("Close", CloseCallback)
-; Can be rewritten as:
-g := Gui()
-g.OnEvent("Close", () => MsgBox("You tried to close the GUI"))
-; Or in v2.1:
-g := Gui()
-g.OnEvent("Close", () {
-    MsgBox "You tried to close the GUI"
-})
-</code>
-However, where things start to get really interesting is when you put function objects into //other objects//. Just like a function object can be stored inside a regular variable and then that variable becomes callable, a function object can be stored as an object property and then that property becomes callable. A callable property on an object is called a //method//.
-When you call a function stored as an object property, AutoHotkey does a little trick with the parameter list. If you have ''MyObject'' with a property ''FunctionProperty'' that contains a function object, calling ''MyObject.FunctionProperty(1, 2, 3)'' will automatically translate into (roughly) ''Temp := MyObject.FunctionProperty'' then ''Temp(MyObject, 1, 2, 3)'', where ''Temp(...)'' behaves as a regular call to the function. You see, the object that contains the property is passed as a first parameter to the function.
-<runner ahk2>
-MyFunction(this, a, b, c) {
-  MsgBox 'a: ' a '`nb: ' b '`nc: ' c
-}
-MyObject := {
-  FunctionProperty: MyFunction
-}
-; These following 4 lines are all equivalent
-MyObject.FunctionProperty(1, 2, 3)
-Temp := MyObject.FunctionProperty, Temp(MyObject, 1, 2, 3)
-(MyObject.FunctionProperty)(MyObject, 1, 2, 3)
-MyObject.FunctionProperty.Call(MyObject, 1, 2, 3)
-</runner>
-==== Prototyping ====
-AutoHotkey objects are *prototype* based, but AutoHotkey's docs don't really do a proper job of explaining what that means or how it works. Prototype-based Object-Oriented-Programming (OOP) is a way of arranging objects containing function objects so that the emergent behavior is similar to non-prototype OOP languages (think C++ or Java).
-The first part of this arrangement was //function objects// being nested inside regular objects. The second part is //prototyping//. Prototyping is the generic term for allowing one object to borrow the properties of another object (the //prototype// object). In AutoHotkey, this is achieved using the "base" mechanism. By adding a base to your object, whenever you try to access a property on your object that does not exist AutoHotkey will then check the base object to see if it exists there instead.
-<runner ahk2>
-baseObject := {
-    someProperty: "alpha"
-}
-testObject := {
-    base: baseObject
-}
-MsgBox testObject.someProperty ; Will show "alpha"
-</runner>
-==== Class Syntax ====
-AutoHotkey's ''class'' syntax is so-called [[https://en.wikipedia.org/wiki/Syntactic_sugar|sugar syntax]]. Sugar syntax is an easier to read and write shorthand for code that is too verbose to work with directly. The implication of calling class syntax as sugar syntax is that you can do almost everything that the ''class'' keyword does entirely without using it. There are a few minor exceptions that we will go over later.
-Class syntax is used to simultaneously define two things: a "prototype object" and a "class object". A prototype object is used the *base* object for class instances. When you create an object like ''myObject := MyClass()'', the value of ''myObject'' ends up looking something like ''myObject := {base: MyClass.Prototype}''. The prototype object is the object that holds all the method functions that you can call on the class instance.
-Remembering the fundamental of how functions stored in objects are called, it would mean that in this following example, when ''testMethod'' is called the value of ''this'' will be equal to ''myObject'' //not// ''MyClass.Prototype''.
-<runner ahk2>
-testMethod(this, a, b, c) {
-    MsgBox "this Ptr: " ObjPtr(this)
-    MsgBox 'a: ' a '`nb: ' b '`nc: ' c
-}
-MyClass := {
-    Prototype: {
-       functionProperty: testMethod
-    }
-}
-myObject := {base: MyClass.Prototype}
-MsgBox "Prototype Ptr: " ObjPtr(MyClass.Prototype)
-MsgBox "myObject Ptr: " ObjPtr(myObject)
-myObject.functionProperty(1, 2, 3)
-</runner>
-The "class object" created by class syntax starts pretty simple: an object with a ''Prototype'' field. But then AHK adds onto that with an "instance factory". Instance factory is a term that I don't think the AHK docs ever uses, but it really should because that's what it would be called in any sane language.
-An instance factory is a function that creates instances of a class. An instance factory for an AHK class works something like this:
-<code autohotkey>
-classFactory(someClass) {
-    instance := {base: someClass.Prototype}
-    instance.__Init()
-    if HasMethod(instance, "__New") {
-        instance.__New()
-    }
-    return instance
-}
-</code>
-The instance factory gets put onto the class object as its "Call" method. With the class factory put onto the class object like this, you can create instances by calling the class object directly:
-<runner ahk2>
-testMethod(this, a, b, c) {
-    MsgBox 'a: ' a '`nb: ' b '`nc: ' c
-}
-classFactory(someClass) {
-    instance := {base: someClass.Prototype}
-    instance.__Init()
-    if HasMethod(instance, "__New") {
-        instance.__New()
-    }
-    return instance
-}
-MyClass := {
-    Prototype: {
-       functionProperty: testMethod
-    },
-    Call: classFactory
-}
-myInstance := MyClass()
-myInstance.functionProperty("alpha", "bravo", "charlie")
-</runner>
-This code invokes "Call" automatically, like ''(MyClass.Call)(MyClass)'', which invokes ''classFactory'' and returns the instance object.
-That's the vast majority of what class syntax does. In that last example, we manually created this class:
-<runner ahk2>
-class MyClass {
-  functionProperty(a, b, c) {
-    MsgBox 'a: ' a '`nb: ' b '`nc: ' c
-  }
-}
-myInstance := MyClass()
-myInstance.functionProperty("alpha", "bravo", "charlie")
-</runner>
-When defining a class, it allows you to specify static and non-static properties. You can do exactly the same with the manually written code. Static properties get added to the class object. Non-static properties get added to the instance by the ''%%__Init%%'' method called by the instance factory:
-<runner ahk2>
-class MyClass1 {
-    static someProp := 123
-    someProp := 456
-}
-myInstance1 := MyClass1()
-MsgBox "Static " MyClass1.someProp " | Non-Static: " myInstance1.someProp
-; Equivalent to
-classFactory(someClass) {
-    instance := {base: someClass.Prototype}
-    instance.__Init()
-    if HasMethod(instance, "__New") {
-        instance.__New()
-    }
-    return instance
-}
-MyClass2 := {
-    Prototype: {
-       __Init: (this) => (this.someProp := 456)
-    },
-    Call: classFactory,
-    someProp: 123
-}
-myInstance2 := MyClass2()
-MsgBox "Static " MyClass2.someProp " | Non-Static: " myInstance2.someProp
-</runner>
-=== Unique behavior ===
-As mentioned previously, there are a few unique features of the ''class'' syntax that are not easily replicated.
-The first is //definition hoisting//. Definition hoisting is the ability to define a class (or other construct) //below// the point where it will be referenced. This allows you to write a class definition at the bottom of your script, but still use it in the auto-execution section. Function definitions are also hoisted in this way.
-The second difference is that the variable defined using ''class'' syntax to hold the class object is made read-only. If you define a class manually like any other object, that class name can be overwritten later. But if you define it with ''class'' syntax, trying to overwrite the global variable that holds the class object will result in the exception "This Class cannot be used as an output variable."