Jump to content

Sky Slate Blueberry Blackcurrant Watermelon Strawberry Orange Banana Apple Emerald Chocolate

[docs] AutoHotkey_L documentation rewriting project?

  • Please log in to reply
66 replies to this topic
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011

... we can show beginners why they should take a look at objects.

Should they? Arrays, sure - but IMO general objects (customized ones for sure) don't need to be promoted in the documentation or community. They are there if you want to use them - particularly for developing class libraries/modules - but the documentation should be focused on AHK as a procedural language/tool, IMO.

That's not to say, however, that we shouldn't have the best documentation/tutorial out there on the thought process behind & usage of objects ...

Okay, maybe I am bit biased because I have some knowledge of objects and how they work, but I obviously don't know as much as you guys. It's okay to focus on other things, but I just feel left in the dark in that case. How many other people out there, who also have intermediate knowledge, want to improve using the teaching materials available to them? I just think we should cover that kind of crowd as well, IMHO.

  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011

Perhaps something like this would help explain the purpose of the __New meta-function on more simple terms?

series :=	new Average(13,18,13,14,13,16,14,21,13)
For type, value in series
	MsgBox, , Average - %type%, %type%: %value%

class	Average {	[color=#40BF00]; input value must be a comma-delimited series of numbers[/color]
	__New(p*) {
		this.Mean :=	0
		[color=#40BF00]; determine the mean for the series[/color]
		For i, n in p
			t .=	(!t ? "" : ",") n
		Sort, t, N D`,
		list :=	t, p :=	[]
		Loop, parse, t, `,
			this.Mean +=	A_LoopField
		this.Mean :=	Round(this.Mean / p.MaxIndex(),3)
		[color=#40BF00]; determine the median for the series[/color]
		n :=	Round((Mod(p.MaxIndex(),2) ? p.MaxIndex() + 1 : p.MaxIndex()) / 2), this.Median :=	p[n]
		[color=#40BF00]; determine the mode for the series[/color]
		Sort, t, U
		Loop, parse, t, `,
			RegExReplace(list,"\b" A_LoopField "\b","$0",c)
			if	!current || c > current
				this.Mode :=	A_LoopField, current :=	c
		[color=#40BF00]; determine the range for the series[/color]
		this.Range :=	p[p.MaxIndex()] - p[1]

It's nice, but the other example is more accessible for me, I never cared too much for math :|

  • Moderators
  • 990 posts
  • Last active: May 15 2014 11:56 AM
  • Joined: 10 May 2007
The classes topic is nothing for complete beginners, but everyone who is interested in programming can come along.
Classes/Objects can help out in simple tasks, and they can be used to build complex things. You don't have to confront Newbies whit complex data structures, they are more interested in simple data Containers which makes scripting simpler/ reduces the required params in Methods.

Most important for those people are working Examples.
They wan't to know what are the benefits of doing it this way, and how have I to think over a problem to make it work with classes. Even more important is the idea behind all of this - thus Tutorials which cover the idea of a small project, the planing phase and the final implementation are required to gain enough understanding.

I've done some in the German Forum which can be easily translated: AHK OOP Tutorials TicTacToe, 4-Wins
It basically shows how to implement a TicTacToe, and introduce enough abstraction that it can be used as a base for a 4-Wins Game.

  • Members
  • 696 posts
  • Last active: May 08 2015 09:51 PM
  • Joined: 28 Jun 2007
As someone starting to learn this stuff, I would LOVE to see a translation of that IsNull!

  • Members
  • 2930 posts
  • Last active: Feb 05 2015 02:49 PM
  • Joined: 02 Nov 2008

Green-on-black = unreadable :p

I said it was a quick sketch! :p

Of course if it was going to be used, I'd make it look nice, and readable.
Request Video Tutorials Here or View Current Tutorials on YouTube
Any code ⇈ above ⇈ requires AutoHotkey_L to run

  • Moderators
  • 6367 posts
  • Last active: Nov 30 2018 08:50 PM
  • Joined: 18 Mar 2008
Another thought: a really obvious problem with teaching about objects is communicating the value of meaningfully naming variables so a natural dotted path syntax can come into play when using objects. Maybe that needs to be the model for how we teach about objects. Obviously that will also show the value of objects for organizing information in certain ways for ease of use. Here's a very rough demonstrative object that might be usable to help teach that:

body :=	{arms:{left:{hand:{fingers:5}},right:{hand:{fingers:5}}}
MsgBox, , Left Hand, %	"Method 1`n(body->arms->left->hand->fingers)`n" body.arms.left.hand.fingers
		 . "`n`nMethod 2`n(body->left->hand->fingers)`n" body.left.hand.fingers
		 . "`n`nMethod 3`n(body->hands->left->fingers)`n" body.hands.left.fingers
MsgBox, , Left Foot, %	"Method 1`n(body->legs->left->foot->toes)`n" body.legs.left.foot.toes
		 . "`n`nMethod 2`n(body->left->foot->toes)`n" body.left.foot.toes
		 . "`n`nMethod 3`n(body->feet->left->toes)`n" body.feet.left.toes

  • Members
  • 1591 posts
  • Last active: Nov 12 2012 08:51 PM
  • Joined: 13 Oct 2009
Your example appears very complex and unreadable to newbies I think. This syntax will surely confuse them. I agree that this is an important point though.

  • Members
  • 4368 posts
  • Last active: Aug 09 2015 02:36 AM
  • Joined: 26 Dec 2010

Your example appears very complex and unreadable to newbies I think.

It's unreadable (if not complex) to me. One thing I found intimidating when I was starting out is lots of ending braces (" }}} ") and I think they should be avoided, or at least cleared up with indentation.

I agree that this is an important point though.


  • Moderators
  • 6367 posts
  • Last active: Nov 30 2018 08:50 PM
  • Joined: 18 Mar 2008
I wasn't really talking about the readability of the object itself (that's where the obvious educational work comes in) so much as the readability of the resulting dotted path syntax. Is the final dotted path(s) unreadable?

The ultimate goal is to use objects to answer a question, in my particular rough case "From your body, how do you get to your fingers?"

  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011
Have you guys looked at a Head First book before? I think they are the best example to draw inspiration from when teaching programming to newbies. I just want to stress again the fact that I was able to make sense out of AHK_L objects after having finished the first lab in the Head First C# book.

  • Members
  • 100 posts
  • Last active: Apr 08 2015 10:07 AM
  • Joined: 16 Feb 2007
The main issue - at least for me - with _L's documentation is does not explain anything about objects or arrays. -Hey _L can support objects, and here, you can use them like this. That's it! With 0 programing background, this can be a problem.

So i found this course:
Introduction to Computer Science | Programming Methodology

The whole course starts from 0 and based on Java. The first few lectures can be a bit boring, but after that it's pretty cool. The instructor, is a super nice / funny guy. So if someone never really learned programming before, i highly recommend this course. Yes, it's a different language, but you will be surprised how much you can learn from it.


  • Members
  • 2558 posts
  • Last active: Nov 01 2014 03:23 PM
  • Joined: 29 Dec 2004
My suggestion for the documentation for objects would be to start extremely simple by explaining the concept with an example (not necessarily a working code example) and let users add complexity once they determine for themselves that it is necessary. The basic concept behind objects and their usage in general is really simple and not specific to programmers. In simple form it is just a collection of variables and actions for a set of data.

For an example, say you have a CD collection and want to store information about it. Each CD would have certain properties that you may want to note. You could create a variable for each property but it could get messy very quickly because you might have hundreds or thousands of CDs so you would need a way to reference each of them and to sort through the data once it is stored. Since there are a few sets of properties you may end up with several sets of data.

For each song you might have something like:


Then you might create another for each CD


Then you would want to place one inside the other


and then maybe add them to a larger list


Of course once we have the information stored we might want to do something with it like:


or maybe:


Once the basic structure has been assembled and the functionality for Playback, etc.. added you wouldn't want to duplicate the code for each set of information so would create one set then make copies and fill in the information for each copy. For example:

CD1 := new CD()

then add data and play

CD1.title := "Party Mix"
CD1.Song1.title := "my song"
CD1.Song1.audio := "D:\mysong.mp3"

Of course, some of the actual code to create and work with objects and classes in _L can seem a bit complicated but once someone has the basic concept of how things work they may have a better understanding of where to start and what to look for in the documentation.

  • Members
  • 251 posts
  • Last active: Dec 19 2012 03:54 PM
  • Joined: 04 Oct 2006
Very nice example... one everyone can understand and identify with. I suggest changing it slightly though. A CD will have a collection of tracks/songs... perfect array example along with some additional object attributes. And a Music Collection will be a collection of CDs leading to a good hash/associative array example.

  • Members
  • 1 posts
  • Last active: May 08 2012 02:28 PM
  • Joined: 08 May 2012
Will we finally understand how AHK_L's most advanced features work? That would be a best case scenario. Gamer's need and want this as they advance to speed up things.

nj contractors insurance

  • Members
  • 754 posts
  • Last active: Jan 17 2015 02:38 AM
  • Joined: 31 Oct 2008
Nice example corrupt but replace "CD" by "Album", noobs (new generation) will don't know what is a compact disk :D, like floppy disk icon for save a file, or an abacus for a calculator...
Abstract concept for variable and object is a "box" with things inside (method, interface, properties, data,... ) as "socket" for some programs... we need to do a general documentation about general programmation with ahk example, hard work...
"You annoy me, therefore I exist."