66 replies to this topic

[fincs]

I have created this thread in action to my recent post. We need:
[*:13v52d7g]People willing to rewrite significant chunks of the documentation
[*:13v52d7g]Hints from non-programmers that have had major troubles understanding objects
[*:13v52d7g]Input from the community

[fragman]

I think there are three big points to be addressed when it comes to objects:
[*:nz6bsl90]Objects in general and their concepts
[*:nz6bsl90]Class syntax
[*:nz6bsl90]Meta functionsThese points need special care. All other things are minor compared to it IMO.

[IsNull]

I would suggest to split up the whole Object thing into:
- What are Objects in general
- Usage of existing Objects/classes
- Creating your own classes

Where as the last is definitely nothing for a Newbie not interested in learning a Language.

[jethrow]

I would cover:
1. Arrays in general. This would include Associative Arrays, and touch on how Arrays are an object.
2. Arrays & their usage in AHK(_L)
3. Customizing Arrays/Creating Custom objects (advanced training)
Also, I would create (possibly separately?) visuals to explain how simple objects are. As I've stated before, my opinion is that objects should reach the status (in the mind of a newbie anyways) of being a slighly more advanced variable.

[plastikglass]

I am willing to volunteer with this if it means that I will finally understand how AHK_L's most advanced features work. I can go so far as trying to create something with those features, and letting guys know where I get stuck. It's a shame that I switched jobs because that was the time when I really needed support on implementing OOP.

I still have some code, but obviously I won't be able to test anything out, although maybe some concepts can be reviewed and elaborated on.

Most importantly, I just think there needs to be better examples; the examples given were too technical and did not immediately show me how those features could be used right away. I found better examples from disparate videos and threads throughout the forum, in addition to examples provided by friendly people in the chatroom (whose scripts I have saved somewhere, thankfully).

[Frankie]

Along with what plastikglass was saying, I think the examples could be made more practical. I've done OOP with other languages, so I was able to translate it into those, and then understand it. Most users won't have that prior knowledge.

[plastikglass]

This is as far as I got with OOP in AHK_L with what was available in terms of teaching materials at the time, maybe since last winter:

<!-- l --><a class="postlink-local" href="http://www.autohotkey.com/community/viewtopic.php?f=2&t=84903">viewtopic.php?f=2&t=84903</a><!-- l -->

Hey Frankie, you were the one who gave me examples on meta-functions, thanks again!

[nioncode]

You need to find an easy way for people to contribute, that more or less excludes github

I think github should be used for keeping track of all the updates people contribute, but I agree with you that it might be not easy for users that don't even know git to use github to contribute any of their work.
So I would volunteer to accept contributions by any user (either per mail or per pm here in the forums) and push them to github for them, so everybody can access the current state of the documentation at a central place, which is the git repository.

Additionally, we should have a clear what-to-do list in this repository, where everybody can see which pages of the docs need to be updated and which are currently being updated by other people. Maybe we should even go further and add the names of the people currently working on an update for a page, so others can get in touch with them to provide any help (this would be best if done over irc or a separate thread or just through the pm system).

It would be great if some users who are currently learning how different things work with AutoHotkey's syntax (especially Objects as said previously) could ask their questions in a separate thread so that people working on the docs can see which parts need to be improved.

Of course, I will provide any help to improve the docs or write more examples, but I would like to first get a good plan of how to organize the process instead of people now starting to update the doc pages on their own and probably many doing the same work at the same time.

[Elesar]

Those of us on IRC likely have a collection of demo scripts on hand (I have a few), and we can keep an eye out for any common areas of confusion that people have...not just Objects, but all of AHK.

[sinkfaze]

Perhaps the easiest way to explain arrays them is to show comparisons to what's in the documentation for pseudo-arrays:

[color=#000000]; Write to the pseudo-array:[/color]
ArrayCount =	0
Loop, Read, C:\Guest List.txt
{
	ArrayCount += 1
	Array%ArrayCount% := A_LoopReadLine
}

[color=#000000]; Read from the pseudo-array:[/color]
Loop %ArrayCount%
{
    element := Array%A_Index%
    MsgBox % "Element number " . A_Index . " is " . Array%A_Index%
}

[color=#000000]; Write to the array:[/color]
Array :=	[]	[color=#00BF00]; creates an array and saves to the variable[/color]
Loop, Read, C:\Guest List.txt
	Array.Insert(A_LoopReadLine)

[color=#000000]; Read from the array:[/color]
For each, element in Array
	MsgBox % "Element number " . each . " is " . element	[color=#00BF00]; A_Index could also be used in place of 'each'[/color]

[plastikglass]

I never could fully understand how to use the meta-functions, and this example in the documentation did not help:

red  := new Color(0xff0000), red.R -= 5
cyan := new Color(0x00ffff)

MsgBox % "red: " red.R "," red.G "," red.B " = " red.RGB
MsgBox % "cyan: " cyan.R "," cyan.G "," cyan.B " = " cyan.RGB

class Color
{
    __New(aRGB)
    {
        this.RGB := aRGB
    }

    __Get(aName)
    {
        if (aName = "R")
            return (this.RGB >> 16) & 255
        if (aName = "G")
            return (this.RGB >> 8) & 255
        if (aName = "B")
            return this.RGB & 255
    }

    __Set(aName, aValue)
    {
        if aName in R,G,B
        {
            aValue &= 255

            if      (aName = "R")
                this.RGB := (aValue << 16) | (this.RGB & ~0xff0000)
            else if (aName = "G")
                this.RGB := (aValue << 8)  | (this.RGB & ~0x00ff00)
            else  ; (aName = "B")
                this.RGB :=  aValue        | (this.RGB & ~0x0000ff)

            ; 'Return' must be used to indicate a new key-value pair should not be created.
            ; This also defines what will be stored in the 'x' in 'x := clr[name] := val':
            return aValue
        }
    }
}

Take it any way you like, I am a newb, but I couldn't really make any sense out of that.

[fragman]

It's actually not that bad, however it gets complicated by some bit shifting operations which may be hard to understand for beginners. It basically shows how to implement properties that don't exist as keys in the object. In this example it gives you access to the separate color channels R,G,B as if they were defined as keys in the class.

[plastikglass]

It's actually not that bad, however it gets complicated by some bit shifting operations which may be hard to understand for beginners. It basically shows how to implement properties that don't exist as keys in the object. In this example it gives you access to the separate color channels R,G,B as if they were defined as keys in the class.

Maybe not for you, but it was hard to understand for me. We are already trying to learn something technical, so does it make sense to use a technical example? I don't imagine many newbies to understand it, unless that is not the goal, and you guys are trying to introduce AHK_L syntax to professional coders instead. (In contrast, my father was able to get it right away, but he is a programmer with over 20 years in C++)

Think of examples from the Head First series, they seem to have an idea on how to break down coding for newbies and beginning coders. If it is our goal to teach people, this is not the way to go about doing it. My theory on learning is that if you can make it as simple as can be without sacrificing core points, that is the stroke of genius.

[sinkfaze]

I don't think that classes are really something the documentation needs to focus on gearing to the beginner anyway. It could obviously use some revision but I think it should be much lower priority compared to demonstrating simple ways objects/arrays can be used that are pertinent to things beginners might do.

So the gamer wants to have several hotkeys that send a message to the chat. Normal documentation would lead them to do this, for example:

1::
Send Thanks!
return

2::
Send Sent.
return

3::
Send Oh noez!
return

Learning to use an array with A_ThisLabel can simplify it to this:

[color=#FF0000]messages :=	["Thanks!","Sent.","Oh noez!"][/color]

1::
2::
3::
Send [color=#FF0000]%	messages[A_ThisLabel][/color]
return