UDF-spec - Revision history

Mlipok: /* Headers */ header is 129 characters wide - requirement removal

2024-01-19T18:51:36Z

Headers: header is 129 characters wide - requirement removal

← Older revision		Revision as of 18:51, 19 January 2024
Line 117:		Line 117:
	; Author ........: Paul Campbell (PaulIA)		; Author ........: Paul Campbell (PaulIA)
	; Modified.......:		; Modified.......:
	; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position. It		; Remarks .......: This function takes into account the current MouseCoordMode setting when obtaining the mouse position.
	; will also convert screen to client coordinates based on the parameters passed.		; It will also convert screen to client coordinates based on the parameters passed.
	; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY		; Related .......: $tagPOINT, _WinAPI_GetMousePosX, _WinAPI_GetMousePosY
	; Link ..........:		; Link ..........:
	; Example .......: Yes		; Example .......: Yes
	; ===============================================================================================================================		; ===============================================================================================================================
	Func _WinAPI_GetMousePos($bToClient = False, $hWnd = 0)</syntaxhighlight>		Func _WinAPI_GetMousePos($bToClient = False, $hWnd = 0)
			</syntaxhighlight>

	The header is 129 characters wide, and any text within it should be wrapped to that length. For example the <code>Remarks</code> in the above header has been extended to cover two lines. The exception to that rule is the <code>Syntax</code> line, which should not be wrapped. Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.		Some of the parameters in the header are optional, in which case they should remain, but be left empty (for example the <code>Link</code> and <code>Modified</code> lines in the above header). In others, they are needed, but can be empty or not used such as <code>Parameters</code> or <code>Return Values</code>. In this case the value should be 'None', as they will still be present in the documentation.

	There are some flags that can be used within function headers:		There are some flags that can be used within function headers:

Mlazovjp: /* Structures */ Capitalized “Hungarian”

2019-10-16T21:04:04Z

Structures: Capitalized “Hungarian”

← Older revision		Revision as of 21:04, 16 October 2019
Line 192:		Line 192:

	== Structures ==		== Structures ==
	Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the ~~Hungarian~~ notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.		Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

	=== Headers ===		=== Headers ===

Mlazovjp: /* Structures */ Capitalized “Hungarian”

2019-10-16T21:03:49Z

Structures: Capitalized “Hungarian”

← Older revision		Revision as of 21:03, 16 October 2019
Line 192:		Line 192:

	== Structures ==		== Structures ==
	Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the ~~hungarian~~ notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.		Structures are defined as global constants, and follow the naming pattern <code>$tagSTRUCTNAME</code>. The struct name should be as it appears on MSDN if it's used in the windows API, or follow a similar pattern if not. It should go without saying that they must work for both 32 and 64 bit machines, including resolving any alignment issues. Elements should also be named as they appear on MSDN if they are taken from there, which includes the Hungarian notation prefix. Although many standard UDFs do not follow that rule, importantly <code>StructureConstants.au3</code>, the rule still stands.

	=== Headers ===		=== Headers ===

Mlazovjp: /* Headers */ Removed apostrophe from “it’s” in Modified subsection

2019-10-16T20:49:35Z

Headers: Removed apostrophe from “it’s” in Modified subsection

← Older revision		Revision as of 20:49, 16 October 2019
Line 146:		Line 146:
	:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.		:This is the original writer of the function. It should contain the username, so that any queries about the code can be made through the forum, but you can give as much or little information as you feel appropriate.
	Modified		Modified
	:This is a list of modifications made. At ~~it's~~ most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.		:This is a list of modifications made. At its most basic this is just a list of users who have made changes, but ideally it includes some information about what they did, in which cases it follows the same form as other multi-value lines, with the username and description of modifications seperated by a dash.
	Remarks		Remarks
	:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.		:This is anything the user should know about a function in order to use it. For example exceptional cases and recommended ways to handle the function should all be detailed here, as well as additional info about possible reasons for failure and how to deal with them.

Mlipok: /* Examples */ Au3Check flags

2018-10-16T08:56:26Z

Examples: Au3Check flags

← Older revision		Revision as of 08:56, 16 October 2018
Line 254:		Line 254:
	* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.		* Be simple. Ideally the only functions used are basic functions like ConsoleWrite and MsgBox and the function that the example is written for. Writing a single example that covers a wide range of functions is not nearly as easy to use as writing an example per function that clearly demonstrates its use.
	* Be readable. Everything should be explained step by step in comments.		* Be readable. Everything should be explained step by step in comments.
	* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.		* Be correct. In addition to passing the same Au3Check flags as the UDF itself (<code>-q -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7</code>) it should always be written with best practice being the main consideration. This takes preference over the first point, just because code is shorter and looks easier doesn't mean it's right.
	* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.		* Examples should represent all the functionality. If there is more than one way of using a function then include more than one example of how to use it.
	* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.		* Not make any permanent changes to the users computer. For example, if demonstrating a File function, be sure to delete the file after it has been used. The same applies for any function that makes a change to the environment: the changes MUST be undone.

Mlipok: /* Template UDF */ #AutoIt3Wrapper_Au3Check_Parameters fixed

2018-10-16T08:54:45Z

Template UDF: #AutoIt3Wrapper_Au3Check_Parameters fixed

← Older revision		Revision as of 08:54, 16 October 2018
Line 300:		Line 300:
	Here is an example of a UDF called <code>MyUDF.au3</code>:		Here is an example of a UDF called <code>MyUDF.au3</code>:

	<syntaxhighlight lang="autoit">#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7		<syntaxhighlight lang="autoit">
			; AU3Check settings
			#AutoIt3Wrapper_Run_AU3Check=Y
			#AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7
			#AutoIt3Wrapper_AU3Check_Stop_OnWarning=Y
	#include-once		#include-once

Mlipok: fixed Au3Check parameters

2018-10-16T00:23:09Z

fixed Au3Check parameters

← Older revision		Revision as of 00:23, 16 October 2018
Line 10:		Line 10:

	* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.		* Be tidied. Just hit <code>Ctrl+T</code> from SciTE or run Tidy manually. The only flag needed is <code>/sf</code>.
	* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7</code>		* Pass Au3Check with no errors using the strictest settings: <code>-q -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7</code>
	* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.		* Support everything AutoIt supports. In some cases features may not be able to support everything, in which case this should be checked for and return errors appropriately. This applies to: windows OS versions (AutoIt has support for all OS' from windows 2000), unicode and ansi strings, 64 and 32 bit machines.
	* Not use any magic numbers. Ever. None. At all. No excuses.		* Not use any magic numbers. Ever. None. At all. No excuses.

TheDcoder: /* Index */

2015-12-01T12:37:25Z

Index

← Older revision		Revision as of 12:37, 1 December 2015
Line 31:		Line 31:
	; ===============================================================================================================================</syntaxhighlight>		; ===============================================================================================================================</syntaxhighlight>

	The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference		The only required element in the index header is <code>Title</code>. All others are ignored by the processor, but should be included for reference, remember that you can add some custom fields like <code>Links</code> too.

	The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.		The <code>Dll</code> field can remain empty in many cases where no dlls are called directly. This header must be defined.

MLipok: /* Examples */ renamed $hGUI >> $hGUI_MyApp

2015-11-10T17:28:39Z

Examples: renamed $hGUI >> $hGUI_MyApp

← Older revision		Revision as of 17:28, 10 November 2015
Line 270:		Line 270:

	Func Example()		Func Example()
	Local $idButton_Run, $idButton_Test, $iMsg, $~~hGUI~~		Local $idButton_Run, $idButton_Test, $iMsg, $hGUI_MyApp

	$~~hGUI~~ = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered		$hGUI_MyApp = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

	$idButton_Run = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)		$idButton_Run = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
Line 291:		Line 291:
	EndSelect		EndSelect
	WEnd		WEnd
	GUIDelete($~~hGUI~~)		GUIDelete($hGUI_MyApp)
	EndFunc ;==>Example</syntaxhighlight>		EndFunc ;==>Example</syntaxhighlight>

MLipok: /* Examples */ $idButton_ renaming

2015-11-10T17:26:46Z

Examples: $idButton_ renaming

← Older revision		Revision as of 17:26, 10 November 2015
Line 270:		Line 270:

	Func Example()		Func Example()
	Local $~~idButton_1~~, $~~idButton_2~~, $iMsg, $hGUI		Local $idButton_Run, $idButton_Test, $iMsg, $hGUI

	$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered		$hGUI = GUICreate("My GUI Button") ; Will create a dialog box that when displayed is centered

	$~~idButton_1~~ = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)		$idButton_Run = GUICtrlCreateButton("Run Notepad", 4, 4, 80, 30)
	$~~idButton_2~~ = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)		$idButton_Test = GUICtrlCreateButton("Button Test", 4, 38, 80, 30)

	GUISetState() ; will display a dialog box with 2 button		GUISetState() ; will display a dialog box with 2 button
Line 285:		Line 285:
	Case $iMsg = $GUI_EVENT_CLOSE		Case $iMsg = $GUI_EVENT_CLOSE
	ExitLoop		ExitLoop
	Case $iMsg = $~~idButton_1~~		Case $iMsg = $idButton_Run
	Run("Notepad.exe") ; Will Run/Open Notepad		Run("Notepad.exe") ; Will Run/Open Notepad
	Case $iMsg = $~~idButton_2~~		Case $iMsg = $idButton_Test
	MsgBox($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed		MsgBox($MB_SYSTEMMODAL, "Testing", "Button 2 was pressed") ; Will demonstrate Button 2 being pressed
	EndSelect		EndSelect