Class values |
Homepage |
This value contains The Class name as well as the class options.
You can retrieve the Class name (with options) by calling Class_getClass. Call Class_getClassName to retrieve the Class name (without the class options).
Class options are Class-specific options that allow adding extra functionality to a class.
They are defined in the YourClass_initClass function via the ClassName variable.
The ClassName variable has the following structure: ClassName(ClassOptions)
ClassName is the name of the class - any combination of upper / lower-case letters and digits (not case-sensitive). Do not make the Class name a number (e.g. Class 007 or Class 0x123 - hex), because such Class names may cause negative side-effects. You can, however, start a class with a digit, though.
ClassOptions is a comma-delimited list of class options (from the ones below)
This class option allows returning a value, instead of the object's address when using the getter function for an obj type (e.g. "Nodes" in a container class).
The returned value is the return from calling the Class' getValue function - YourClass_getValue(YourClassObject); therefore, this function must be defined . Note, even if YourClass_getValue is a function, the Class isn't considered a wrapper (and thus won't be "unwrapped") unless you specify "Wrapper" as a Class option.
Specify "uint" as the getter type to return the object's address (even for wrappers). See Obj vs UInt for details.
The cloneable option means that the class has a YourClass_clone(YourClassObject, DeepCopy = true) function defined.
This function will clone the specified object and return the address for a "clone" of the object.
If DeepCopy is true (1), then a deep (recursive) copy is done. This allows creating a copy an an object and any subobjects.
If DeepCopy is false (0), then a shallow copy is done. Note, this feature is not yet properly implemented
If DeepCopy is -1, then a "settings-only" copy is done. This copies all the values, but leaves obj type values unset, and instead leaves setting them up to the Class' clone function. This allows a custom behavior for deciding how to set the object values. For example, for a Vector object, you might want to create a deep clone, create an empty Vector, leave the obj unset, etc.
All V2 Class objects are cloneable by default.
Built-in values should be any value which is required by the class; these values will be stored in each of the Class' created objects.
For example, in the Rectangle class, width and height are both built-in values. Since every rectangle must have a width and a height, these values are built-in to ensure that every Rectangle object has them.
You can also include these built-in values as arguments to the
YourClass_New function to initialize them with the objects creation.
Note:Like all functions, you can specify default values to make a
parameter optional, or make
the parameter ByRef.
You can also, optionally, add built-in functions that reside within the Class' ahk file so that all objects can easily access them - Rectangle_area is an example of such a function.
Some notes:
Don't forget to set the static value BuiltInSize in YourClass_new to the total number of bytes for your built-in values.
See index value help for how to use index values.
Additionally, to meet the V2 design
standard, each class MUST have a getBuiltInValues() function which
contains a list of the built-in values used (their types, in ascending order
by index).
See V2 design ->
getBuiltInValues for details.
In addition to having built-in values, a class can have user-defined values (if the Class is designed to allow them).
User-defined values are added by the user of the Class (not it's creator) and allow adding project-specific values without modifying the Class' source.
The user-defined values can differ from script to script, so the user can reuse the same Class over and over in different scenarios by only changing the user-defined values.
In addition, you can, optionally, add project-specific, user-defined functions.
The lock count stores the number of times that a Class object is stored in a field of type obj.
A lock count of zero means that the object is not stored, and thus upon calling the object's destroy function, the object will be destroyed.
A lock count of one means that the object is stored once, and upon calling the object's destroy function, the object will be destroyed. This is commonly the case if the object is stored in a container object or associated with another object via an obj field.
If the lock count is more than one, this means the same object is stored in multiple locations. Upon calling the object's destroy function, the lock count will be reduced by one, but the object will not actually be destroyed. This allows the object's references in the other locations to remain valid until the last one is destroyed (lock count one), at which time the object will be destroyed.
Special care needs to be taken, however, if that the desired action is not to destroy an object, but to only remove it.
For example, if you create a String object, add it to an array, and then destroy that array, your String object is also destroyed.
If this was not the desired action, you can first remove the object. All container classes support object removal. See the respective class for more information.
When removing an object, the object's lock count is decreased by one (to reflect it's removal), but the object is not destroyed (even if the lock count is now zero).