This is a full update for the definition file ahk2.d.ahk
and the directive/flow control/variable file ahk2.json
for THQBY's AHKv2 support addon.
- Why use this update
- Installation
- Auto-Updater
- Change Log
- In-depth Showcase
- Different Widget Types
- Will THQBY Implement This?
This is a full rewrite from the ground up.
It adds many things to the definition that it's currently missing.
All parameters are included, all functions and methods have return values, the text of the calltips are now formatted and more aesthetically pleasing, hyperlinks are added, all options are accounted for, the structure of the definition file has been expanded and updated, autocomplete features have been added for directives and flow control, and much more.
To put things in perspective, the current definition file is ~4,200 lines long and ~185,000 characters.
The updated definition file is ~24,000 lines long and ~1,510,000 characters.
The information difference is substantial and borderline palpable.
In all fairness, a chunk of this character increase comes from the numerous hyperlinks, markdown formatting, and individual GUI controls added coupled with them now having individualized methods and properties.
Please see the In-depth Showcase section to see a large listing of the numerous changes I've implemented to these files.
There are pictures and videos for almost every topic covered.
There are multiple ways to update the definition file.
To do it automatically, use the provided Auto Updater file.
definition_updater.v2.ahk
To do it manually, start by optionally backing up your original files.
ahk2.d.ahk
and ahk2.json
If you delete them and decide you want to go back to the standard definition files, they can always be redownloaded from THQBY's GitHub for the addon.
Now download the ahk2.d.ahk
and ahk2.json
files.
Copy them into the addon's syntaxes
folder.
The default location for this folder is:
C:\Users\<YourUsername>\.vscode\extensions\thqby.vscode-autohotkey2-lsp-<HighestVersionNumber>\syntaxes
Alternatively, you can always copy and paste the text from here to the installed ones on your computer.
I've written an auto-updater so you don't have to keep updating the file.
It can be ran as its own script or can be copy and pasted into a main script, as the updater is self-contained and will auto-run.
Properties and methods of the updater:
-
Methods:
Start()
= Starts/enables update checkingStop()
= Stops/disables update checking
-
Properties:
frequency
= How often to check for updates, in hours.
This can be a fractional number: 1.5 = 1 hr 30 min
Default value is 4.notify
= If set to true, TrayTips will pop up to notify of updates or errors.
Setting this to false will suspend all TrayTip popups.update_updater
= Set to false if you don't want the auto-updater updating itself.
- Updated JSON file to include new version.
-
Did a full rewrite of the updater to fix some bugs and an error in the code.
-
Reduced code size and streamlined things. (The code looks way better now.)
-
Pushed a second update because I got confirmation that encoding must be UTF-8-RAW as the file expected to be without BOM.
- Fixed some bugs in the auto-updater.
- Added a property to enable/disable auto-updating the auto-updater.
-
This is one of a few big updates that will be coming to fix lots of things, continuously adding example code, and doing other improvements.
-
Added an auto-updater to the repository that should automatically keep the defintion files up-to-date.
-
ahk2.json updates:
- Added a version key to the main json file for anyone who wants to use an auto-updater
- Format:
"version": 1.1
- Format:
- Core revisions based on updates made by THQBY.
- ahk_criteria, such as ahk_exe, ahk_class, etc., are now recognized in any field that expects a WinTitle.
- This includes functions like WinActivate(), WinExist(), ControlClick(), ControlGetPos(), etc.
- THQBY has moved most built-in var descriptions to the ahk2.d.ahk file.
- I've applied standardized tags to all of them including hyperlinks to their docs pages, formatted text, improved descriptions, and many examples of how to utilize them.
- Hotstring options have been added to the json file but I haven't figured out exactly what they do. HotString() seems to perform the same with and without them.
- The keyword Static now has an autocomplete for creating variables and methods
- Per /u/Laser-Made's request, each loop type's definition includes a list of A_LoopVARTYPE variables available to that specific loop.
- Examples:
- Parse-loop's definition now shows it has access to A_Index and A_LoopField.
- Registry-Loops have access to A_Index, A_LoopRegName, A_LoopRegType, A_LoopRegKey, and A_LoopRegTimeModified.
- Examples:
- Added a version key to the main json file for anyone who wants to use an auto-updater
-
ahk2.d.ahk updates:
- Added a version tag to the top of the file for anyone who wants to use an auto-updater
- Format:
;@region v1.1
- Format:
- Per THQBY's update, most built-in variables are now included in the ahk2.d.ahk file instead of the JSON file.
- Lots of small changes throughout the file. Grammar/captializations/corrected errors/etc.
- The @see tags are now separated by pipes to make them more distinguishable from each other.
- They're also stored on one line intstead of individual lines.
- Added many more examples.
- Started adding comments to some of the example code to assist with learning and understanding.
- I've made it a point to not write everything the same way in an attempt to expose people to the many ways things can be structured and written.
- Examples: Using both traditional and fat arrow functions
- Parsing text by using both parse-loops and StrSplit()
- Writing if-statements with curly braces (code blocks) and without by utilizing commas (multi-statement operator)
- Putting commands on the same line as Else or Try to illustrate the different ways to use them
- Most examples are written in a way that they can be copy+pasted into a blank file and ran.
- Some examples are not meant to be ran, but instead illustrate the the multiple ways of using them, such as Click().
- Added a version tag to the top of the file for anyone who wants to use an auto-updater
-
ahk2.d.ahk specifics:
-
Any class:
- Improved description.
-
Any.GetMethod():
- Updated return value.
-
Any.HasBas():
- Updated description and corrected return type from bool to integer.
-
Any.HasMethod():
- Rewrote to be more understandable and clearly worded.
- Added new examples.
-
Any.HasProp():
- Updated description.
- Added example.
-
__Init():
- Added a description as it lacked one.
-
__Delete():
- Added to the definition file and should appear in autocomplete now.
- Given a description.
-
Object class:
- Updated description.
- Added examples.
-
Object.Clone():
- Updated description.
- Improved example code.
-
Object.DefineProp():
- Updated description.
- Added more example code.
-
Object.DeleteProp():
- Updated description.
- Added better example code.
-
Object.GetOwnPropDesc():
- Updated description.
- Added better example code.
-
Object.OwnProps():
- Updated description.
- Added better example code.
-
Array class:
- Updated description.
-
Array.__Item:
- Updated description.
- Corrected an error.
- Updated and improved examples.
-
Array.Default:
-
Array.__Item:
- Uprdated definition to be more clear and inclusive.
-
Array.Clone():
- Updated definition to be more clear about shallow copies.
- Improved example code.
-
Array.Delete():
- Corrected an error in its description.
- Added error.
- Improved example.
-
Array.Get():
- Clarified return value.
- Updated example to show more variation and usage.
-
Array.Has():
- Clarified when it returns true.
- Improved example.
-
Array.InsertAt():
- Rewrote definition to clarify multiple things.
- Corrected an error in the description.
- Improved existing code and added more examples for clairfication.
- Updated AdditionalValues parameter to be variadic.
-
Array.Pop():
- Improved definition.
-
Array.Push():
- Rewrote definiton to be more accurate and informative.
- Added more examples.
-
Array.RemoveAt():
- Corrected erroneous information in the description.
- Improved overall description.
- Improved example code.
-
Array.__New():
- Updated definition to clarify __New() should not be called directly
-
Array.__Enum():
- Updated enumerator's definition.
- Updated and added to examples.
-
Buffer class:
- Updated definition.
- Corrected default values from Unset to 0.
-
Buffer.__New():
- Updated definition.
- Included default values.
-
ClipboardAll class:
- Updated definition.
- Added example code.
-
ClipboardAll.Ptr:
- Updated definition.
- Added @throw error
- Updated definition.
-
ClipboardAll.Call():
- Updated definition to be more clear.
- Included information I missed before.
-
Class():
- Improved and expanded the definition.
-
Class.Prototype:
- Improved definition
- Changed return type from Prototype to Object, as this is how the addon needs to see it
- There is no "prototype object" in AHK. Just an object we refer to as the "prototype".
-
Error class:
- Did a full update to all error sub-types and descriptions
-
Error.Stack:
- Rewrote definition to be easier to understand.
- Improved what the output structure looks like.
-
Error():
- Example code was improved.
-
All the error subtypes:
- Updated definitions to be more clear.
- Provided type-specific properties and parameters.
- Such as Message and Extra info for TypeError and ValueError
-
OSError Class:
- Added missing number property and definition (Thanks THQBY)
- Updated definition.
- Changed the first parameter to ErrorNumber and assigned the correct default value to it.
-
File class:
- Updated definitions for almost all properties and methods.
- Included number range and byte sizes with each type of Read()/Write() method.
- Ensured each method now has some form of example.
-
Func.Bind():
- Improved description.
- Added more examples.
-
Func.IsByRef():
- Improved description.
- Added more examples.
-
Func.IsOptional():
- Improved description.
- Added more examples.
-
BoundFunc Class:
- Updated description.
- Added examples for both types of boundfuncs.
-
Enumerator Class:
- Added new examples to show enumerator structure and use.
- Included examples for making any object enumerable with a custom enumerator.
-
Closure Class:
- Updated definition and added better example code that differntiates between closures and static nested functions.
-
Gui Class:
- New example code showing the many fascets of making a GUI.
-
Gui.Control Class:
- Added a description and properties to class definition.
- Updated the description of almost all properties and methods belonging to this class.
- Added example code to all properties and methods of this class.
-
ComCall():
- Made function call variadic as multiple type/args can be passed. (Thanks /u/bleurgh96230)
- Changed return type form an
String | Integer
toPrimitive
.
-
DateDiff():
- Updated description to state required format.
-
Exp():
- Fixed return value type from String to Number.
-
NumGet():
- Completely overhauled this function.
- Corrected a syntax error.
- Made things more understandable
- Created a new "data type" table, including byte/bit information.
- Added multiple examples.
-
NumPut():
- Completely overhauled this function.
- Corrected a syntax error.
- Made things more understandable
- Created a new "data type" table, including byte/bit information.
- Added multiple examples.
- Made function variadic as to not cause an error when setting multiple numbers.
- Due to limitations, the variadic parameter is the offset, which is incorrect.
- Currently, there is no way to tell the addon that the first 2 parameters can be repeated any number of times.
- It's a bandaid until THQBY comes up with a more elegant solution to this.
-
ObjBindMethod():
- Made function variadic to pre
-
PixelGetColor:
- Added example code.
-
SendMessage():
- Fixed doc URL.
-
SendMode():
- Fixed doc URL.
-
WinGetTransparent():
- Fixed @see links
-
- Updated a lot of the verbiage in the
Format()
tag to make it more understandable. - Removed unused tags left over from template pasting.
- Adjusted formatting of
@throw
tags. - Added missing "Related" links to the
@see
tag forOnError()
.
- Rewrote and restructured the entire ReadMe file for this GitHub page.
- Added a plethora of pictures and videos to the showcase section.
- Fixed InputBox()
Result
andValue
information, as they were accidentally swapped. - Added more examples to the code.
- Multiple formatting fixes.
- Fixed
ObjRelease()
not having thePtr
param in the function definition. (Thanks camkidd) - Fixed a description error in Array's
Get()
andHas()
methods.
- Fixed a typo in the autocomplete for
Loop Count
that included an invalid comma between the two. (Thanks /u/Hukepi)- This shows how ingrained some v1 syntax is in me.
- Fixed
FileSelect()
root directory and title parameter default.
- Fixed a bunch of typos and errors.
- Fixed functions/methods that should have had variadic parameters.
- Added String, Integer, Number, and Float class
Call()
functions and calltips. - Added ComObjArray, ComObject, and ComValue class
Call()
functions and calltips. - Cleaned up a lot of tags to try and make them more compact.
- Updated
ahk2.json
with new version for #Requires.
- All functions, classes, methods, and properties are done.
- Added
ahk2.json
file. This includes many updates to directives and flow control statements. - Some examples can be seen here.
-
All classes, functions, methods, and properties now have complete information provided for them.
-
I've applied a set standard of JSDoc tags to all these items.
- Examples:
- EVERYTHING starts with an
@description
tag and provides a hyperlink (mentioned below) to that item's official online doc pages. - A function will always list all parameters and their types, return values and types, and any listed throw errors.
- This is everything you need to utilize a function or method.
- Properties will always list the value type.
- EVERYTHING starts with an
- Examples:
-
I've applied Markdown formatting to each item so the displayed popup (called a widget) has formatted text.
- A Gui control's
Opt()
method is a great example. (Please note that this is one of the largest calltips)
- A Gui control's
-
ALL methods and functions now have a return value.
- If a function or method has no actual defined return value and uses the default "empty string", it's explicitly marked as
EmptyString
.
- If a function or method has no actual defined return value and uses the default "empty string", it's explicitly marked as
-
I've updated and rewritten some of the descriptions, parameters, etc. to be more clear and understandable.
- This is a big one for me. It's important that people understand exactly how something works.
- I strive to use proper terminology, but I also choose my words carefully, trying to never be ambiguous.
-
Added my own custom "things" to the script
- Examples:
- My own personal RegEx cheat sheets that I created for this file.
- Custom
@example
tags (mentioned below). - Other stuff.
- Examples:
-
Hyperlinks (everything in blue text) have been added. Plenty of them.
- As mentioned above, every class, function, method, and property now starts with an
@description
tag that starts with the name of the item and that name is always a hyperlink to the respective online docs page. - There are multiple other links throughout the calltips.
- All "Related" items from the docs are now included in the calltip's
@see
tag.- The links are not limited to the ones listed. I've included other links that I thought would be beneficial, such as linking to regex101.com and an online regex cheat sheet in the RegExMatch() and RegExReplace() functions.
- As mentioned above, every class, function, method, and property now starts with an
-
The
ahk2.json
file has also been updated with a lot of new menus and auto-complete features.- Directives with a set amount of options now show those options in a popup instead of expecting you to type them.
#MaxThreadsBuffer
#UseHook
#Warn
has two different menus.
- Directives where you're expected to type one or more fields prepopulate those fields and describe what each field expects.
#ClipboardTimeout
shows it expects milliseconds.#MaxThreads
shows the value must be between 1 and 255.#Include
tells you it expects a file, directory, or .
#Requires
got an overhaul and now provides multiple menus to generate the requirement. It also respects Semantic Versioning.- Version operator (less than, greater than, etc...)
- Minor revision. 1 or 2.
- Patch revision. 0 through 11 at the time of me writing this.
- And finally bit requirement
- All loops have a pre-defined setup, so each one is setup with some form of auto-complete.
- Directives with a set amount of options now show those options in a popup instead of expecting you to type them.
-
Custom examples galore.
- I've written an
@example
tag for many of the functions and methods (though only about 1/2 of them are done)- Doing this exposes people to the different ways something can be used or even different ways to write code in general.
- I'll be continuing to add more over time.
- Some examples show the different configurations or ways to use a command.
Click()
would be a good example of this.
- A lot of examples show a functioning piece of code that demonstrates how to use one or more items.
- The
AddSlider()
example creates a GUI with a slider to control system volume.
- The
- Code in the @example tag is properly syntax highlighted. How very meta!
- Text from the calltips can be copied and pasted directly into the editor.
- This can eliminate a lot of typing, especially when working with GUIs.
- I've written an
-
All GUI controls are now defined as their own class.
- Blanket methods and properties for GUI Controls have been removed and replaced with individual classes.
- This ensures each control object now registers as its own control type.
- Before, a button, checkbox, and edit field would all show as a
Gui.Control
whereas now they show asGui.Button
,Gui.Checkbox
, andGui.Edit
respectively.
- Before, a button, checkbox, and edit field would all show as a
- Each control now only contains information pertaining to that specific control.
OnEvent()
for example:- Before,
OnEvent()
listed all possible event types for all control types, regardless if they can be used by the control type. - Now, each method and property that contains unique information has its own calltip.
- A Button control's
OnEvent()
includes "Click" but not "Change" because buttons don't have change events. - Conversley, an Edit control's
OnEvent()
includes "Change" but not "Click", making writing code easier.
- Before,
Value
for example:- A Checkbox control's value explains it stores the state of the checkbox and can be a
1
,0
, or-1
- A DateTime control's value sets/gets the current date-time stamp in YYYYMMDDHH24MISS format.
- Don't know what that format means? Good thing it's a hyperlink to the docs page explaining it!
- A Checkbox control's value explains it stores the state of the checkbox and can be a
-
@throw
tags have been included to show what causes certain errors.- This should help when troubleshooting or writing your own error handling.
-
An
InputBox object class
has been added to the definition file and associated with the return value of InputBox(). -
I've tried to ensure every possible option available for each parameter and property (within reason) is included.
- For some functions and methods, this can cause some calltips to be long. For example:
- Note that cards with elongated parameters aren't too much of a problem b/c when typing out parameters, the addon puts the current param up top.
- This prevents a huge parameter section from eclipsing another one while you're typing out each param.
-
There are other things I'm sure I'm forgetting.
It should pointed out that there are multiple types of widgets that popup.
- If you hover a function/method/class/property, the hover widget shows up.
- It's resizeable, has the best header syntax highlighting out of all the widgets, and shows all calltip information, in order
- If you start typing a new name, the autocomplete widget shows up.
- This window is also resizeable.
- This view can be expanded or hidden
- Pressing
Ctrl+Space
brings up autocomplete as well as toggles the widget window.
- Pressing
- If you start typing the parameters of a method of function, the parameter widget shows up.
- This widget is unique in the fact that it can't be resized (and I don't know why b/c all the other ones are resizeable).
- It also puts the current parameter at the top of the card, preventing the need to scroll to get to the info.
- Pressing
Ctrl+Shift+Space
brings up the parmeter widget whenever you're between the parentheses of a function or method.
It seems unlikely.
I showed the updated files to him and he immediately pass on them.
I'm not sure he even tried them...
I cannot convey how disappointed I am thinking about the hours I invested into this thinking it'd be picked up immediately.
Especially considering the current incomplete and lacking state the definition file is in.
I don't know. Maybe he'll get curious about it later, try it, and change his mind.
Until then, I fully intend on maintaining these files and keeping them up to date.