Report Help File Issues Here

[Bert]

This thread is for public posting and comment on the Help File audit project proposed changes being performed by myself and other forum members. We will be posting both proposed scripting examples for commands as well as proposed wording changes to the Help file. The following 6 post in this tread will be used to track proposed changes, changes approved by the group, rejected changes, and changes that may be deferred for various reasons.

We will be working through the Help File in order of page, so it may take a while to get to the section someone wishes to have audited.

We welcome your comments but we do ask that you not propose anything that calls for a feature request, bug fixing, or scripting questions.

If you have a bug you wish to report or feature request, please use Trac.

If you have a scripting question, Please post your question in the General Help and Support section of the forum.

Edit - last update 10/20/1020

Edited February 15, 2011 by MPH

[Bert]

reserved for scripting examples approved by the auditing group and that are closed from future public comment.

-----------------------------------------

ClipGet / ClipPut

; 1. Clear the clipboard
ClipPut("")
$bak = ClipGet()
MsgBox(262144, "Clipboard contains:", $bak)

; 2. Insert data into the clipboard then read
ClipPut("AutoIt ClipGet Example #2")
$bak = ClipGet()
MsgBox(262144, "Clipboard contains:", $bak)


; 3. Adding additional data to the clipboard
;    then reading the entire string.
ClipPut("AutoIt ClipGet Example #3")
$bak = ClipGet()
ClipPut($bak & " and some additional text")
MsgBox(262144, "Clipboard contains:", ClipGet())

-----------------------------------------------------------

MemGetStats

; 1. Example show entire array along with carrage returns in the msgbox.
$mem = MemGetStats()
MsgBox(0, "Your PC contains:", "Memory Load (Percentage of memory in use):" & $mem[0] & @CRLF _
                              &"Total physical RAM (KB): "& $mem[1]& @CRLF _
                              &"Available physical RAM: " & $mem[2]& @CRLF _
                              &"Total Pagefile: "         & $mem[3]& @CRLF _
                              &"Available Pagefile: "     & $mem[4]& @CRLF _
                              &"Total virtual: "          & $mem[5]& @CRLF _
                              &"Available virtual: "      & $mem[6])

------------------------------------------------------------

DirCreate and DirRemove

;1. Create C:\Test1 and all sub-directories. Show the directories in Explorer and then delete the directories.

$sFldr1 = "C:\Test1\" 
$sFldr2 = "C:\Test1\Folder1\" 
$sFldr3 = "C:\Test1\Folder1\Folder2\" 
If DirGetSize($sFldr1) = -1 Then
    DirCreate($sFldr3)
    $explorer = RunWait("explorer /root, C:\Test1\Folder1")
    $handle = WinGetHandle($explorer)
    MsgBox( 262144, "Message", "Explorer is opened with Folder2 displayed.")
    DirRemove($sFldr3, 1)
    MsgBox(262144, "Message", "The sub folder: Folder2 has been deleted.")
    WinClose($handle)
    DirRemove($sFldr1, 1) ;clean up test folders
Else
    MsgBox(48, $sFldr1, "Directory already exists!")
EndIf

Edited October 25, 2010 by MPH

[Bert]

reserved for text changes approved by the auditing group and closed from public comment.

Edited October 20, 2010 by MPH

[Bert]

Reserved for Proposed changes from members

[Bert]

Reserved for rejected changes

[Bert]

Reserved for examples that need public comment before final approval.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Edited October 25, 2010 by MPH

[Bert]

reserved for proposed wording changes that need public comment.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Edited October 20, 2010 by MPH

[GEOSoft]

New Example for _WinAPI_SetWindowsHookEx() and _WinAPI_UnhookWindowsHookEx()

expandcollapse popup

Opt("MustDeclareVars", 1)

#include <WinAPI.au3>
#include <WindowsConstants.au3>

; press ESC to exit this example
HotKeySet("{ESC}", "_Exit")

Global $dblClickTime, $mouseProc, $hHook, $lastX, $lastY, $iTime = 0

_Main()

Func _Main()
    OnAutoItExitRegister("_Cleanup")

    $dblClickTime = DllCall("user32.dll", "uint", "GetDoubleClickTime")
    $dblClickTime = $dblClickTime[0]
    $mouseProc = DllCallbackRegister("_LowLevelMouseProc", "lresult", "int;wparam;lparam")
    If $mouseProc = 0 Then Return SetError(1)
    $hHook = _WinAPI_SetWindowsHookEx($WH_MOUSE_LL, DllCallbackGetPtr($mouseProc), _WinAPI_GetModuleHandle(0))
    If @error Then Return SetError(2)

    While 1
        Sleep(1000)
    WEnd
EndFunc   ;==>_Main

Func _Exit()
    Exit
EndFunc   ;==>_Exit

; low level mouse hook callback function
Func _LowLevelMouseProc($nCode, $wParam, $lParam)
    ; nCode is a code to determine how to process this message.
    ; If nCode < 0, then return the value from CallNextHookEx.
    ; If nCode >= 0, then process the message.
    ;
    ; wParam identifies the mouse message, for example WM_LBUTTONDOWN.
    ; lParam is a pointer to a MSLLHOOKSTRUCT structure
    ;
    ; To block the mouse click, return a non-zero value.
    ;
    ; For this example, we will define a double click as two clicks less than the double click
    ; time and within a 4x4 pixel area.
    If $nCode >= 0 Then
        Switch $wParam
            Case $WM_LBUTTONDOWN
                Local $tMSLLHOOKSTRUCT = DllStructCreate("long x;long y;dword mouseData;dword flags;dword time;dword dwExtraInfo", $lParam)
                Local $iArea = 4
                ; 'time' member is the time stamp of the message
                Local $clickTime = DllStructGetData($tMSLLHOOKSTRUCT, "time")
                ; x and y coordinates of mouse click
                Local $thisX = DllStructGetData($tMSLLHOOKSTRUCT, "x")
                Local $thisY = DllStructGetData($tMSLLHOOKSTRUCT, "y")
                ; check click time and coordinates
                If ($clickTime - $iTime < $dblClickTime) And (Abs($thisX - $lastX) <= $iArea) And (Abs($thisY - $lastY) <= $iArea) Then
                    ; got a double click!
                    ConsoleWrite("- DOUBLE CLICK!! (" & $clickTime - $iTime & " ms => " & $thisX & ", " & $thisY & ")" & @CRLF)
                    ; reset last click time
                    $iTime = 0
                    ; block the double click
                    Return 1
                Else
                    ConsoleWrite("+ click (" & $thisX & ", " & $thisY & ")" & @CRLF)
                    ; record last click time and coordinates
                    $iTime = $clickTime
                    $lastX = $thisX
                    $lastY = $thisY
                EndIf
        EndSwitch
    EndIf
    Return _WinAPI_CallNextHookEx($hHook, $nCode, $wParam, $lParam)
EndFunc   ;==>_LowLevelMouseProc

; cleanup
Func _Cleanup()
    ConsoleWrite("Cleaning up..." & @CRLF)
    _WinAPI_UnhookWindowsHookEx($hHook)
    DllCallbackFree($mouseProc)
EndFunc   ;==>_Cleanup

[GEOSoft]

The Help File page for DllClose() says it has no return value; however, this is not true. Like a lot of native functions it returns 0 or 1. I think the help file should be changed to reflect this.

Return Value
None.

Return Value
Success: Returns 1.
Failure: Returns 0.

Thanks. We'll have a look at it.

[Ascend4nt]

Regarding Run() and RunWait():

Using Run*() on processes requiring elevation (via UAC prompts) on Vista+ will fail, as the CreateProcess API call will return an error message ERROR_ELEVATION_REQUIRED (provided that the current process isn't already elevated). There's a ticket open for this, but it would be nice to have it at least documented in the next release for those who are wondering why Run('regedit.exe') fails while ShellExecute('regedit.exe') works.

Ticket: #1771.

This article from Microsoft partially explains it: Using the ElevateCreateProcess Fix.

I understand Valik said he wants to look into a sensible solution - but I have looked myself and, other than modifying the registry, ShellExecute() is the only working alternative I can find. The problem with that is one cannot get a Process ID # using AutoIt's ShellExecute().

(Note that there are _ShellExecuteEx() UDF's where you can get the Process ID # however).

[Valik]

If a function is retardedly simple and does not have documented return values... there's a reason. It doesn't need them. DllClose() doesn't use a return value thus it's undocumented. The fact that it returns 1 is completely irrelevant. If DllClose() is ever modified to use a return value then that value will be documented and will be a value you can reasonably assume won't change. The value DllClose() returns now? If you're using that value for any reason then shame on you for using undocumented return values.

[GEOSoft]

I'm thinking that way myself Valik. It's fine the way it is.

Edited November 28, 2010 by GEOSoft

[SyDr]

1) Function MsgBox -> Section ###Remarks### -> <b>XXX flag</a>, but should be <b>XXX flag</b>

2) All_txt2htm.au3

Line 509:

; It can be better to launch an explorer web page
; seems pretty long to stay in .chm to browse pages
; an expert is needed for doing someting similar to the button "Open this script"

Return 'Search <a href="http://search.msdn.microsoft.com/search/Default.aspx?brand=msdn&query =' & _
$ Name & '">' & _
$ Name & '</a> in MSDN Library' & @ CRLF

Replace with

Return 'Search <a href="http://search.msdn.microsoft.com/search/Default.aspx?brand=msdn&query =' & _
$ Name & '" class ="ext" target=_blank">' & _
$ Name & '</a> in MSDN Library' & @ CRLF

Perhaps we should add "class="ext" target=_blank" to all links leading outside of the Help file.

[trancexx]

I'm thinking that way myself Valik. If all they need it for is some kind of error handling (also of no real value) then they could use something like

If NOT DllClose($hDll) Then
    ;; handle the error
EndIf

If you think the way Valik thinks you should have stopped at the first full stop.

This way you are only making a confusion.

[Richard Robertson]

I'm thinking that way myself Valik. If all they need it for is some kind of error handling (also of no real value) then they could use something like

If NOT DllClose($hDll) Then
    ;; handle the error
EndIf

And how do you intend to respond to a dll that either can't be released, or was never loaded in the first place?

[GEOSoft]

You're both right. It needs nothing there.

[Tlem]

Hello.

This is my contribution :

Files missings or path error like describe in this link :

The conditional statements With...Endwith disappeared from the file lang_loops.htm !!!

But steel used in AutoIt.

In documentation of function ChrW :

'Returns a blank string and sets @error to 1 if the UNICODEcode is greater than 65535'

should be

'Returns a blank string and sets @error to 1 if the UNICODE code is greater than 65535'

In Keyword.htm, for the #OnAutoItStartRegister description, you said :

Registers a function to be called when AutoIt starts

but isn't it more reliable to say :

Registers a function to be called when the script starts

Same remark in file functions.htm for OnAutoItExitRegister and OnAutoItExitUnRegister

I have noticed that Hour, Minute, Seconde are on two digits format because they do not have more digit.

Milliseconds can be tree digits, but it start to 00 instead of 000.

In ControlSend documentation, section Remark :

Opt("SendKeyDelay",...) alters the the length of the brief pause in between sent keystrokes.

should be

Opt("SendKeyDelay",...) alters the length of the brief pause in between sent keystrokes.

[GEOSoft]

Thanks Tlem.

I completed

#3 - ChrW()

#6 - ControlSend()

I'll look to see what happened with #2 - With/EndWith.

#4 and #5 are going to require input from the Dev Group.

[iamtheky]

To manage the link with the explorer you can use the shell extension NTFSLink

underlined is hyperlinked to the following URL - which is dead

http://forge.novell.com/modules/xfmod/project/?ntfslink

[GEOSoft]

underlined is hyperlinked to the following URL - which is dead

http://forge.novell.com/modules/xfmod/project/?ntfslink

what page is it on?

EDIT: I found the correct page in the files and that link has already been corrected by ??

Edited October 8, 2011 by GEOSoft