jeeswg's functions tutorial (initial content)

Helpful script writing tricks and HowTo's
User avatar
jeeswg
Posts: 4509
Joined: 19 Dec 2016, 01:58
Location: UK

jeeswg's functions tutorial (initial content)

24 Dec 2017, 11:58

[I intend to return to add some further content, as described in the Outline section.]

==================================================

JEESWG'S FUNCTIONS TUTORIAL

==================================================

CONTENTS

> BUILT-IN / CUSTOM FUNCTIONS
> OUTLINE
> LOCAL / GLOBAL / SUPER-GLOBAL VARIABLES
> STATIC VARIABLES
> BYREF VARIABLES
> VARIADIC FUNCTIONS
> OMIT PARAMETERS: CUSTOM FUNCTIONS / COM OBJECTS

==================================================

> BUILT-IN / CUSTOM FUNCTIONS

In AutoHotkey you can use built-in functions.

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



In AutoHotkey, you can also create custom functions.

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



Ultimately you can create functions to do virtually anything. And the vast majority of AutoHotkey's built-in functions can be recreated as custom functions.

Examples of functions:
Explorer window interaction (folder windows/Desktop, file/folder enumeration/selection/navigation/creation) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=6&t=35041
GUIs via DllCall: get/set internal/external control text - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=6&t=40514
commands as functions (AHK v2 functions for AHK v1) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=29689
AutoHotkey via DllCall: AutoHotkey functions as custom functions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=37871

==================================================

> OUTLINE

Here is a guide to the sections that will follow:

Key terms (which will be explained further):
- scope: local/global/super-global variables - a variable has a local version (inside a function), and a global version (outside a function), sometimes these are the same
- static variables - the content of static variables is remembered after a function is executed, normally variables are cleared
- ByRef variables - an input parameter that can also be used as an output parameter
- variadic functions - functions with a variable number of parameters, normally functions have a fixed number of parameters

Ways to increase the number of input variables:
- lots of variables as input parameters
- variables containing comma(/delimiter)-separated lists
- use global variables
- use arrays as input parameters
- variadic functions

Ways to increase the number of output variables:
- note: return is limited to one output parameter
- variables containing comma(/delimiter)-separated lists
- use global variables
- return an array
- use multiple ByRef variables as input/output parameters

Also:
- how many parameters were passed to the function
- omitting parameters / default values
- can an input variable also be an output variable (ByRef, objects)
- are variables inside functions cleared when the function ends (and: handling binary data)
- are variables inside functions local or global (and: parameter variables versus variables inside the function)
- creating variables dynamically within functions
- referring to functions dynamically
- built-in/custom functions with the same name
- including scripts (and functions) using #Include
- what happens when a function isn't found

==================================================

> LOCAL / GLOBAL / SUPER-GLOBAL VARIABLES

- Defining a variable as global within the main body of a script (outside a function), makes it super-global. All functions will use the global version of that variable, apart from any functions that specify to use the local(/static) version of that variable.
- Defining a variable as global within a function, means that the global version of the variable is used.
- Static variables are local variables, their content is remembered between calls to the function.

- If one or more variables are defined as local, all other (non-parameter) variables in the function are defined as global.
- If one or more variables are defined as global, this does not affect any other variables in the function.
- If one or more variables are defined as static (static variables are local) this does not affect any other variables in the function.

- The word 'global' on its own, can be used to make every variable in a function global.
- The word 'static' on its own, can be used to make every variable in a function static (and local).
- The word 'local' on its own, cannot be used to make every variable in a function local, it triggers an error message.
- From AHK v1.1.27 onwards. The word 'local' on its own, can be used to make every variable in a function local.

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus


- Further examples which work on AHK v1.1.27 onwards.

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



==================================================

> STATIC VARIABLES

- Static variables: the content of static variables is remembered between function calls.
- With a static variable, the only thing that is 'static', is that the variable continues to exist, the variable's address, size, and content can be changed at any time.
- If you use a line such as this: static var := 123, var is only set to the value once (when the script loads), the value is not reset each time you use the function. Static lines can be described as 'ghost lines', they are only executed once, after that, they are invisible to the script.

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



==================================================

> BYREF VARIABLES

- ByRef variables provide an input parameter that can also be used as an output parameter.
- Note: if you pass something that isn't a variable/object name, into a ByRef parameter, then the parameter acts as normal, and not as a ByRef parameter.
- Parameters that are not ByRef (by reference), are ByVal (by value).

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



==================================================

> VARIADIC FUNCTIONS

- Variadic functions can have a variable number of parameters.
- They have 0 or more normal parameters, and then a 'variadic parameter'.
- All of the items in the 'variadic parameter' are retrieved as keys in an array by the function.
- ByRef variables cannot be used with the 'variadic parameter'.

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus



==================================================

> OMIT PARAMETERS: CUSTOM FUNCTIONS / COM OBJECTS

- From v1.1.12 onwards, optional parameters can be omitted in functions. This also made the ComObjMissing function unnecessary.
- However, if you wanted a parameter, used with a COM object, to sometimes be omitted, and to sometimes be used, you could use the alternative mentioned below:
jeeswg's objects tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=29232

Code: [Select all] [Download] GeSHi © Codebox Plus

m := ComObjMissing() ;AHK v1
m := ComObject(0xA, 0x80020004) ;AHK v1/v2

Changes & New Features
https://autohotkey.com/docs/AHKL_ChangeLog.htm#v1.1.12.00
1.1.12.00 - August 14, 2013
Optional parameters can be omitted by writing two consecutive commas, as in InStr(a, b,, 2). Unlike previous versions, this now works for objects (including COM objects) and built-in functions. [a,,b] can be used to create a sparse array.

ComObjActive()
https://autohotkey.com/docs/commands/ComObjActive.htm
Creates an object which may be used in place of an optional parameter's default value when calling a method of a COM object. [v1.1.12+]: This function is obsolete. Instead, simply write two consecutive commas, as in Obj.Method(1,,3)
ParamObj := ComObjMissing()

==================================================

Return to “Tutorials”

Who is online

Users browsing this forum: No registered users and 3 guests