Class library (OOP) - Help Thread

Welcome to the discussion half of the OOP library. Please post all requests and bugs on the Class library (OOP) - Wish list / Bug reports thread.

First, I want to give a BIG shout out to Lexikos for the ingenious template that spawned into this OOP library.

I split the theads, because I was told that 15+ pages is intimidating to noobs - sorry about that. So, this thread is strickly for questions and updates. I will no longer be posting detailed updates. Instead, I'll post an overview, and leave the specifics for display on the website. Note, it is not yet up-to-date, but it has a ton of updates, much cleaner and neater (than the old site), and will be updated (in my limited spare time).

Of course, any questions can be posted here. So PLEASE, don't hesitate to ask. I know this library can be overwhelming - I'M OVERWHELMED. However, that's what I'm here for - to assist.


The zip file contains Class.ahk, the wrapper classes, the Node Class, Array, Vector, and some example scripts (located in the "Class Examples" folder) which demonstrate some of the Class library's functionality. Also, there is a Rectangle Class to demonstate how to modify the Node class to be your own, personalized class.

The included Node class can be used as a template for almost any class you would need (except possibly container classes). Also, there are included wrapper classes to wrap the basic types (String, Int, UInt, Short, UShort, Char, UChar, Float, and Double). Int64 and UInt64 are now added. Additionally, there are some container classes: an Array class and a Vector class (dynamic array).

All classes use the Class library (Class.ahk) to provide their functionality, but the different Classes are optional and are only required if you wish to use them. Extact the zip to a library folder so that the classes are included automatically as needed.

My recommendation is to check out the included example scripts which demonstrate some of the class library's functionality. Also, the website has a TON of information to help you get started.

Download the Class library and
Check out the site
To easily navigate the class website, check out this addition - AccessClassLibrary.


Maintaining the class library requires a lot of time and effort. If you find the class library useful, please consider donating.

Ok, FYI, I LOVE WinSCP (edited). It's portable, it's free, and it's GREAT! I just uploaded the new site in seconds!!! I'm not a fan of FileZilla anymore. It saved my password (in text form) and didn't warn me. WinSCP warned me, and I said, don't save. It's very easy to use, just enter your password and you're in.

Anyway. I just wanted to say the site is up - check it out.

Note, there are some pages that go no wherere. I think only the Node and Rectangle stuff isn't up yet, but I could be wrong. If you find any, please just press the back button. If you want, you can report them on the Class library -> Bug reports thread. I'll be finishing updating the site in my limited spare time (so it might be a bit).

Please share any feedback. If there is something that could be explained better, please tell me. The site is to help; it's not any help if it doesn't make sense.

Again, ask questions if you have any - that's what I'm here for. Either I, or someone else will answer you question.

Update:
The "weird" question mark-like symbols have been fixed. Also, I fixed the the links for "homepage" - some of the links didn't link to the homepage.

FilleZilla is good. But I prefer FireFTP

Could you show some simple examples on how classes could be used?

An example... I'd say download the zip and there is the rectangle class - which is an example class of a Rectangle. I just relized that I forgot to post on the thread what is in the zip, sorry about that - I'll post that, thanks.

In the zip, there is a Rectangle class. It has built-in values (width and height) - like you'd expect. Additionally, Rectangle_test.ahk shows how to take a class and add user specified values. Since Rectangle is designed to allow user-specific values, you can expand on Rectangle for you project-specific needs. For example, the Rectangle_test has color, isStriped, hasDots, and some extra "values". The class is a "mock class" - not really meant to do much, but it shows what Classes can do.

FilleZilla is good. But I prefer FireFTP

So it's only a plugin for Firefox?

Cool. I'll look into the example later.
Yeah, FireFTP is only a plugin for Firefox. But since my FF is always open, it's convenient for me.

This will be a lot to chew on for me, but I'm getting an error in Array_Test.ahk:

Error: Too many parameters passed to function
Specifically: Node_new(0)

--> Node1 := Node_new(0)

This will be a lot to chew on for me, but I'm getting an error in Array_Test.ahk:

Error: Too many parameters passed to function
Specifically: Node_new(0)

--> Node1 := Node_new(0)

Thanks, I fixed it, just remove the 0 and it will work fine.

I wanted to share a script that I just finished - AccessClassLibrary. It allows accessing the pages on the site VERY EASILY.


It makes use of the Browser Class - The latest version is included in the zip.

Browser's main feature (I think only...) is the ability to open a list of web pages in a browser.
Supported Browsers:
[*:29025qc9]Internet Explorer
[*:29025qc9]Firefox (and its portable version)
[*:29025qc9]Opera
[*:29025qc9]Opera@USB (a portable Opera)
[*:29025qc9]Google Chrome (and its portable version).
This script makes use of a new Class function, Class_in - download the latest version of Class library, if you haven't already.

This function mixes the benefits of if var in/contains MatchList and a Parsing loop.
This addition is in response to this thread, "if Var in MatchList" is very slooooow. Also, the extra "tweaking" applied in Class_in allows AccessClassLibrary to do it's job.

The Node template has been updated to use this function (in the Node_constant function).


So, want to check out the latest additions? AccessClassLibrary is designed to help navigate the site.

Hotkeys (change them to fit your style)
[*:29025qc9]Win + c: Shows the gui to allow entering the desired page. Press enter to open the specified page or press escape to close the gui.

[*:29025qc9]Win + Alt + c: Same as above, but the URL will be opened in a new tab.

[*:29025qc9]Ctrl + Alt + c: If the specified browser is active, this hotkey minimizes it - to get back to programming. If the specified browser exists (but is not active), it activates the window - to allow going between programming and checking out the library.
How to use:

Download AccessClassLibrary.zip and extract its contents to a library folder.

Currently, firefox is set at the UsedBrowser (I'm guessing most of you use firefox). I use Opera@USB, so I use the Opera@USB browser. Set the browser as you wish. Both "InternetExplorer" and "IE" will make IE the used browser. The supported browsers are listed in the file. Specify the one you use. You only need to do this once.

1) Start AccessClassLibrary.ahk (located in the "Class Examples" folder)

2) Press the hotkey to show the gui
2a) Win + c to open the selected URL in the same tab
2b) Win + alt + c to open the selected URL in a new tab

3) Enter your selection. Ex. Class_in - let's check out the new function.

4) Press enter
4a) If the specified browser is already started, it will open the URL. It first activates the browser; then, goes to the page.
4b) If the specified browser is not already started, it will open the URL in the default browser.

5) Enjoy

6) To get rid of that pesky browser (and get back to work), press Ctrl + Alt + c. This will minimize the browser (if it is the active window). If the browser window exists (but is not active), it will be activated.


Any and all feedback is welcome. Hope you enjoy this addition.

Update:
"Containers" and "Wrappers" now function correctly - it considered them classes before.

Update2:
Added "home" as a synonym for Homepage and "basics" as a synonym for Class Basics.

Download AccessClassLibrary

I modified the Node_constant function so that you no longer have to specify the read-only variables in both lists. Now, there are two separate lists of variables - one for read/write values and one for read-only.

For complete details, check out this latest revision.

Download the updated Class library.

Edit:
Whenever appropriate, I will post a link to the latest version of AccessClassLibrary.

I added a new function to the Class Library - Class_setConstants(ClassNameOrObject, SetConstants, Mode = "")

This allow getting / setting multiple constants at a time - ex. storing and loading of settings. It dynamically calls the Class' "constant" function (if it exists), to set the settings.


Specify the constant to get or set on a line with a leading- "``" - a single accent character (after escaping). This allows support for values that have text on multiple lines. Any line that starts with an "accent" followed by a variable name is assumed to be the name of a constant. This only causes conflict if you have text that contains a line that starts with an "accent" followed by a "valid" variable name (see link for what constitutes a "valid" variable name) - this should be a rare occurence.

Getting and Setting values
To set a value, specify the variable name followed by a single space, followed by the value to set.

To get a value (instead of setting it), specify the variable name alone on the line. Any leading / trailing spaces will NOT be ignored. Update: A single trailing space is permitted. Ex. "``Variable ". This allows the following form (prevents needing two casses) - ``Variable [SetValue]. If SetValue is omitted, the value will be retrieved, and the previous value will remain unchanged.


The easiest way to build the "set constants" value is via a continuation section using LTrim as an option. You can optionally use the comments option like in the example below.

e.g.

#SingleInstance Force
;test of the SetConstants function (SetConstants_test.ahk located in the "Class examples" folder)

;includes the SetConstants class, since without it, the dynamic call fails
SetConstants_constant("")

MyValue := "Some Text"

Settings =
(LTrim Comments
    ;two "accent" marks are required to store a single "accent" mark
    ;   - due to character escaping
    ``Value1 5          ;stores for Value1 - 5
    ``Value2 6          ;stores for Value2 - 6
    ``Quote "           ;note, this will set a literal double quote into the constant
    ``Tab `tText        ;you can also use `t for tabs
    ;
    ;additionally, variable references can be used
    ;   this is a continuation section, after all
    ``Value %MyValue%
    ;
    ;You can format multi-line text as multi-line text or by using `n in the text (or a mixture of the two)
    ;For example, the below lines are stored as multi-line text - " Some text with a leading space`nSome more text`nYet another line"
    ;
    ;since the new lines in the set value don't start with an "accent" followed by a variable name,
    ;   they will be seen as part of the current set value.
    ;
    ``TextWithSpace
    ` Some text with a leading space    ;Since LTrim is used, the leading space needs to be escaped
    Some more text                      ;this line is part of <TextWithSpace> - since it doesn't have the form: ``Variable [SetValue]
    Yet another line                    ;this line is part of <TextWithSpace> - since it doesn't have the form: ``Variable [SetValue]
    ;
    ;another variable
    ``Value3            ;returns the current value - no value is set
)

MsgBox, % "Settings to store:`n`n" Settings

MsgBox, % "Previous settings (return from Class_setConstants):`n`n" . Class_setConstants("SetConstants", settings)

MsgBox, % "Current settings (return from Class_setConstants using mode = ""getOnly""):`n`n" . Class_setConstants("SetConstants", settings, "getOnly")
    . "`n`nNote: the value for <quote> and <tab> didn't change because they are both read-only."
    
MsgBox, % "The individual values..."

MsgBox, % "value: " SetConstants_constant("value")
MsgBox, % "value1: " SetConstants_constant("value1")
MsgBox, % "value2: " SetConstants_constant("value2")
MsgBox, % "value3: " SetConstants_constant("value3")
MsgBox, % "quote: " SetConstants_constant("quote")
MsgBox, % "tab (@ used solely to mark the end): " SetConstants_constant("tab") "@"
MsgBox, % "TextWithSpace:`n`n" SetConstants_constant("TextWithSpace")

Return value
The return value is in the above form, with the constant's "set value" being the value (before the change) for the respective constant. This allows the function's return to be used to easily store and load settings.

To store the settings:
Call the Class_setConstants function passing a list of variable names (in the above format) and specify "getOnly" (case-insensitive) as the Mode. This allows passing the same "set constants" list for both setting and getting constants. When Mode = "getOnly", no values are modified (even if there is a "set value" for the constant). However, the constant's current value will still be included in the return, as desired.

The return is formatted in the above form with the current values as the set value. This allows for easy loading of the settings by passing this return value as the parameter for Class_setConstants. For example, you can save the return to a file. Then, to load the settings, pass to Class_setConstants the contents of the file.

To load settings:
Call Class_setConstants with a list of settings - in the above form. Because the return from Class_setConstants is in the propper form, it can be used to restore a list of previous settings. This way, you can have multiple "profiles" - each in the propper from (e.g. the return from Class_setConstants). You can then load a "profile" by passing it to Class_setConstants.


Since the return from the Class' "constant" function is used, if the specified variable name isn't a "valid variable" (i.e. not in ReadOnlyVariables or ReadWriteVariables), then the empty string will be used for the constant's "set value".


Note: because the Class' "constant" function is called (and handles the getting and setting), the Class_setConstants function will work regardless of which "version" of Node_constant was implemented - whether the latest version or a previous one. This also means that read-only values won't be modified - the current value is still used in the return for Class_setConstants.


Additionally, because the return of this function has the variable name as part of the form, to retrieve a single value, it would be easier to continue using the Class' "constant" function or use Class_constant to dynamically call the Class' constant function.

I'm trying to start understanding your class library.
For a "newbie" it's quite difficult to find any starting point where he can hook in .... (I won't call myself a OOP programming newbie - but newbie in means of OOP within Autohotkey ...)

For example your Rectangle-class seems to be a quite straightforward class which should be easily understandable. But already in the class constructor some things are heavily unexplained - and (at least for me) it's not clear what the single steps are needed exactly for. For example:

;allocates memory for a new Rectangle object and returns it's address
Rectangle_new(Width, Height, UserDefinedSize = "")
{
    ;size of built-in values
    static BuiltInSize := 4

    ;Uses default user-defined size if none is specified
    if (UserDefinedSize = "")
        UserDefinedSize := Rectangle_setUserDefinedSize()

    ;Allocate Rectangle info structure
    if (RectangleObject := Class_Alloc(4 * UserDefinedSize + BuiltInSize))
    {
        ;Store "Class values" (must be present in ALL classes)
        Class_setClass(RectangleObject, Rectangle_initClass())
        Class_setBuiltInSize(RectangleObject, BuiltInSize)
        Class_setUserDefinedSize(RectangleObject, UserDefinedSize)

        ;Lock count is set to zero automatically

        ;Set Built-in values
        Rectangle_setWidth(RectangleObject, width)
        Rectangle_setHeight(RectangleObject, height)
    }

    return RectangleObject
}

What's UserDefinedSize needed for?
What'sBuiltInSize needed for?
What does the line if (RectangleObject := Class_Alloc(4 * UserDefinedSize + BuiltInSize)) allocate - is the factor 4 just fore fun or is it needed? What's the allocation needed for? (BTW: Class_Alloc() is not documented on your web site ...)

I think a more dummy introduction tutorial would help to overcome the main fears to work with your obviously great work ...

I think a more dummy introduction tutorial would help to overcome the main fears to work with your obviously great work ...

Thanks for bringing to my attention the need for a "getting started" tutorial / FAQ - I completely forgot to include something like that on the site. I'll upload a page with the below content, and add to it as more questions come in. Thanks for the idea.

What's UserDefinedSize needed for?

UserDefinedSize is to allow project-specific, user-defined values - this value is measured in words (4 byte "chunks").

UserDefinedSize allows adding to a class without needed to modify the original class. Additionally, each project can have different user-defined values. This means the same class can be used over and over, and modified without needing to modify the original class - kind of a "dynamic" extra. Although you can't change the class during run-time, you can change it for each project you use the class.

Of course, you can create a class that doesn't allow user-defined values. In this case, you can either, 1) remove all instances of user-defined size (which means the user-defined size would be zero), or 2) specify UserDefinedSize to be zero (via the static value). The latter allows you to easily add support for user-defined values add a later time.

What's BuiltInSize needed for?

BuiltInSize is the size of the built-in values. You specify this value in bytes.

Built-in values are values that are required for the class to function. These values, unlike user-defined values, are "hard-coded" into the class. Meaning, every instance of the class will have these values. For example, in the Rectangle class, width and height are built-in values. This is because every rectangle has a width and a height. It is up to the class' designer to decide which values need to be built-in.


On a side note, the built-in values and user-defined values are "partitioned" in the class. This means that even if the internals of the class change (even if it gets bigger or smaller), the user-defined values won't be affected. In OOP terminology, this concept is encapsulation or "data hiding". It means separating the internals of a Class from the externals (the interface). In this case, the user-defined values are unaffected by changes to the internals of the class.

What does the line if (RectangleObject := Class_Alloc(4 * UserDefinedSize + BuiltInSize)) allocate?

This line allocates memory for the Class object. Class_Alloc takes a single parameter - the size to allocate. If a number is specified, the parameter is the number of bytes to allocate.

Since UserDefinedSize is in words (4 byte chunks), we multiply the user-defined size by 4 to get the number of bytes. Add this to the built-in size and we get the total number of bytes that the class object requires.

(BTW: Class_Alloc() is not documented on your web site ...)

Correct, and it won't ever be. I, purposely, don't want to document internal functions that are never called by the creator of the class, or by the user of a class. Documenting internal functions, I think, would only cause confusion. For me, at least, documentation is something to tell people what they can do, and how to do it. Internal functions (which would be private in a "real" OOP setting) shouldn't be documented, because the user isn't supposed to use them.

In this case, Class_Alloc is only used in the constructor. However, it is not to be modified in any way. You can remove UserDefinedSize if you don't intend to allow user-defined values, or you can set the static value UserDefinedSize to zero. Other than that, there is no need to change the statement, nor will calling Class_Alloc anywhere else be required.

Thanks for bringing to my attention the need for a "getting started" tutorial / FAQ - I completely forgot to include something like that on the site. I'll upload a page with the below content, and add to it as more questions come in. Thanks for the idea.

Thanks back - for your kind response. By promising a beginners tutorial / FAQ (and hopefully providing it soon) most of my wishes are fulfilled...

Not documenting internal functions is OK, as long as they are not needed implementing a new class. As Class_Alloc() is used in most of your example class implementations (constructor) it looks like, its a function which is needed by user ...

BTW: Documentation of your dictionary/Sdictionary class is also missing on your current website ...

Not documenting internal functions is OK, as long as they are not needed implementing a new class. As Class_Alloc() is used in most of your example class implementations (constructor) it looks like, its a function which is needed by user ...

Sorry for the confusion. Yeah, I'm still catching up in terms of the site, and I'm working backwards (which is always bad). Lately, I've been focusing more on adding interfaces, then working on the site. Thanks for reminding me that a "sandwich" approach is a better method for updating. This ensures that the basics get added, and that devolopment of the Class doesn't slow down, too much, while updating the site with the basics.

When updating the site, I will try to remember to mention which functions are "private" (not to be used by the user or developer of a Class), and document the "public" functions. Feel free to remind me of what I have forgotten, as I rely on yal's feedback to "fill in the holes".