Object

class Object extends Any

Object is the basic class from which other AutoHotkey object classes derive. Each instance of Object consists of a set of "own properties" and a base object, from which more properties are inherited. Objects also have methods, but these are just properties which can be called.

There are value properties and dynamic properties. Value properties simply contain a value. Dynamic properties do not contain a value, but instead call an accessor function depending on how they are accessed (get, set or call).

"Obj" is used below as a placeholder for any instance of the Object class.

All instances of Object are based on Object.Prototype, which is based on Any.Prototype. In addition to the methods and property inherited from Any, Objects have the following predefined methods and properties.

Table of Contents

Static Methods

Call

Creates a new Object.

Obj := Object()

Methods

Clone

Returns a shallow copy of an object.

Clone := Obj.Clone()

Each property or method owned by the object is copied into the clone. Object references are copied (like with a normal assignment), not the objects themselves; in other words, if a property contains a reference to an object, the clone will contain a reference to the same object.

Dynamic properties are copied, not invoked.

The clone has the same base object as the original object.

DefineProp

Defines a new own property.

Obj.DefineProp(Name, Desc)
Name

Type: String

The name of the property.

Desc

Type: Object

An object with one of the following own properties, or both Get and Set:

Get: The function object to call when the property's value is retrieved.

Set: The function object to call when the property is assigned a value. Its second parameter is the value being assigned.

Call: The function object to call when the property is called.

Value: Any value to assign to the property.

Returns the target object (Obj).

This method can be used to convert a value property to a dynamic property or vice versa, but it is not possible to specify both a value and accessor functions.

If any one of the accessor functions is omitted, behavior is inherited from a base object.

As with methods, the first parameter of Get, Set or Call is this (the target object). For Set, the second parameter is value (the value being assigned). These parameters are defined automatically by method and property definitions within a class, but must be defined explicitly if using normal functions. Any other parameters passed by the caller are appended to the parameter list.

The MaxParams and IsVariadic properties of the function objects are evaluated to determine whether the property may accept parameters. If MaxParams is 1 for get or 2 for set and IsVariadic is false or undefined, the property cannot accept parameters; they are instead forwarded to the __Item property of the object returned by get.

DeleteProp

Removes an own property from an object.

Obj.DeleteProp(Name)
Name

Type: String

A property name.

Returns the value of the removed property (blank if none).

GetOwnPropDesc

Returns a descriptor for a given own property, compatible with DefineProp.

Obj.GetOwnPropDesc(Name)
Name

Type: String

A property name.

For a dynamic property, the return value is a new object with an own property for each accessor function: Get, Set, Call. Each property is present only if the corresponding accessor function is defined in Obj itself. For a value property, the return value is a new object with a property named Value. In such cases, Obj.GetOwnPropDesc(Name).Value == Obj.%Name%.

Modifying the returned object has no effect on Obj unless DefineProp is called.

A PropertyError is thrown if Obj does not own a property by that name. The script can determine whether a property is dynamic by checking not desc.HasProp("Value"), where desc is the return value of GetOwnPropDesc.

HasOwnProp

Returns true if an object owns a property by the specified name, otherwise false.

Obj.HasOwnProp(Name)

The default implementation of this method is also defined as a function: ObjHasOwnProp(Obj, Name).

OwnProps

Enumerates an object's own properties.

For Name , Value in Obj.OwnProps()

Returns a new enumerator. The enumerator is typically passed directly to a for-loop, which calls the enumerator once for each iteration of the loop. Each call to the enumerator returns the next property name and/or value. The for-loop's variables correspond to the enumerator's parameters, which are:

Name

Type: String

The property's name.

Value

The property's value.

If the property has a getter method, it is called to obtain the value (unless Value is omitted).

Dynamic properties are included in the enumeration. However:

To enumerate own properties without calling property getters, or to enumerate all properties regardless of type, pass only a single variable to the for-loop or enumerator. GetOwnPropDesc can be used to differentiate value properties from dynamic properties, while also retrieving the value or getter/setter/method.

Methods are typically excluded from enumeration in the two-parameter mode, because evaluation of the property normally depends on whether the object has a corresponding getter or value, either in the same object or a base object. To avoid inconsistency when two variables are specified, OwnProps skips over own properties that have only a Call accessor function. For example:

The default implementation of this method is also defined as a function: ObjOwnProps(Obj).

Properties

Base

Retrieves or sets an object's base object.

BaseObj := Obj.Base
Obj.Base := BaseObj

BaseObj must be an Object.

If assigning the new base would change the native type of the object, an exception is thrown. An object's native type is decided by the nearest prototype object belonging to a built-in class, such as Object.Prototype or Array.Prototype. For example, an instance of Array must always derive from Array.Prototype, either directly or indirectly.

Properties and methods are inherited from the base object dynamically, so changing an object's base also changes which inherited properties and methods are available.

This property is inherited from Any; however, it can be set only for instances of Object.

See also: ObjGetBase, ObjSetBase

Functions

ObjSetBase

Sets an object's base object.

ObjSetBase(Obj, BaseObj)

No meta-functions or property functions are called. Overriding the Base property does not affect the behaviour of this function.

An exception is thrown if Obj or BaseObj is of an incorrect type.

See also: ObjGetBase, Base property

ObjOwnPropCount

Returns the number of properties owned by an object.

Count := ObjOwnPropCount(Obj)

ObjSetCapacity

Sets the current capacity of the object's internal array of own properties.

ObjSetCapacity(Obj, MaxProps)
MaxProps

Type: Integer

The new capacity. If less than the current number of own properties, that number is used instead, and any unused space is freed.

Returns the new capacity.

An exception is thrown if Obj is of an incorrect type.

ObjGetCapacity

MaxItems := ObjGetCapacity(Obj)

Returns the current capacity of the object's internal array of properties.

An exception is thrown if Obj is of an incorrect type.