Found errors in _ClipBoard_SetData documentation

[larryc]

I tried reporting this via the bug tracker, but it got rejected as spam. What's the best way to report it to the maintainer of the code?

Two bugs in the documentation for this function:

1. The function description shows the first parameter variable as $vData, but the parameter description refers to the variable $hMemory. This error exists both in the .chm Autoit help file as well as in the clipboard.au3 code itself.

CODE

; Name...........: _ClipBoard_SetData

; Description ...: Places data on the clipboard in a specified clipboard format

; Syntax.........: _ClipBoard_SetData($vData[, $iFormat = 1])

; Parameters ....: $hMemory - Handle to the data in the specified format. This parameter can be NULL, indicating that the ...

2. Second bug: The documentation implies that the first parameter should be a handle. However, upon reviewing the code itself, it is clear that the first parameter can be either a string or a handle (and this is dependent on the 2nd parameter.) The documentation should be fixed, as it is incorrect.

CODE

Func _ClipBoard_SetData($vData, $iFormat = 1)

Local $tData, $hLock, $hMemory, $iSize

Switch $iFormat

Case $CF_TEXT, $CF_OEMTEXT

$iSize = StringLen($vData) + 1

$hMemory = _MemGlobalAlloc($iSize, $GHND)

If $hMemory = 0 Then Return SetError(-1, 0, 0)

$hLock = _MemGlobalLock($hMemory)

If $hLock = 0 Then Return SetError(-2, 0, 0)

$tData = DllStructCreate("char Text[" & $iSize & "]", $hLock)

DllStructSetData($tData, "Text", $vData)

_MemGlobalUnlock($hMemory)

Case Else

; Assume all other formats are a pointer or a handle (until users tell me otherwise)

$hMemory = $vData

EndSwitch

[PsaltyDS]

I tried reporting this via the bug tracker, but it got rejected as spam. What's the best way to report it to the maintainer of the code?

Access to Trac is sometimes temporarily restricted for everyone when forum scripts detect inappropriate activity by the small number of bad actors out there. Those same scripts are likely to tag as SPAM any HTML links pointing outside of the AutoIt forums.

Two bugs in the documentation for this function:

1. The function description shows the first parameter variable as $vData, but the parameter description refers to the variable $hMemory. This error exists both in the .chm Autoit help file as well as in the clipboard.au3 code itself.

; Name...........: _ClipBoard_SetData
; Description ...: Places data on the clipboard in a specified clipboard format
; Syntax.........: _ClipBoard_SetData($vData[, $iFormat = 1])
; Parameters ....: $hMemory  - Handle to the data in the specified format.  This parameter can be NULL, indicating that the ...

It looks like the descriptions were copy/pasted between this function and _ClipBoard_SetDataEx(), where $hMemory is correct because it is always a handle. Then it was changed to $vData in _ClipBoard_SetData() so it could be used easily with plain text strings, where $hMemory is still used but is internally generated off the $vData input.

This is documentation errata and you might try to resubmit without any HTML references in your report. (Trac reports should be self-contained with all required info anyway.)

2. Second bug: The documentation implies that the first parameter should be a handle. However, upon reviewing the code itself, it is clear that the first parameter can be either a string or a handle (and this is dependent on the 2nd parameter.) The documentation should be fixed, as it is incorrect.

Func _ClipBoard_SetData($vData, $iFormat = 1)
    Local $tData, $hLock, $hMemory, $iSize

    Switch $iFormat
        Case $CF_TEXT, $CF_OEMTEXT
            $iSize = StringLen($vData) + 1
            $hMemory = _MemGlobalAlloc($iSize, $GHND)
            If $hMemory = 0 Then Return SetError(-1, 0, 0)
            $hLock = _MemGlobalLock($hMemory)
            If $hLock = 0 Then Return SetError(-2, 0, 0)
            $tData = DllStructCreate("char Text[" & $iSize & "]", $hLock)
            DllStructSetData($tData, "Text", $vData)
            _MemGlobalUnlock($hMemory)
        Case Else
        ; Assume all other formats are a pointer or a handle (until users tell me otherwise) :)
            $hMemory = $vData
    EndSwitch

As described above, in 20 out of 22 possible formats, it is a handle. In the two exceptions for $CF_TEXT and $CF_OEMTEXT the handle is internally generated as $hMemory. A tweak to the documentation is all that is required.

[GaryFrost]

; #FUNCTION# ====================================================================================================================
; Name...........: _ClipBoard_SetData
; Description ...: Places data on the clipboard in a specified clipboard format
; Syntax.........: _ClipBoard_SetData($vData[, $iFormat = 1])
; Parameters ....: $vData     - Handle to the data in the specified format.  This parameter can be NULL, indicating that the
;                  +window provides data in the specified clipboard format upon request.  If a window delays rendering, it must
;                  +process the $WM_RENDERFORMAT and $WM_RENDERALLFORMATS messages.  If this function succeeds, the system owns
;                  +the object identified by the $vData parameter.  The application may not write to or free the data once
;                  +ownership has been transferred to the system, but it can lock and read from the data until the _ClipBoard_Close
;                  +function is called.  The memory must be unlocked before the clipboard is closed.  If the $vData parameter
;                  +identifies a memory object, the object must have been allocated using the function with the $GMEM_MOVEABLE
;                  +flag.  If $iFormat is set to $CF_TEXT or $CF_OEMTEXT, then $vData will be treated as a string.

[PsaltyDS]

Where is that version? The ClipBoard.au3 that I have from 3.3.0.0 has:

; #FUNCTION# ====================================================================================================

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

; Name...........: _ClipBoard_SetData

; Description ...: Places data on the clipboard in a specified clipboard format

; Syntax.........: _ClipBoard_SetData($vData[, $iFormat = 1])

; Parameters ....: $hMemory - Handle to the data in the specified format. This...

Are you working on 3.3.1.1 Beta already?

[GaryFrost]

Where is that version? The ClipBoard.au3 that I have from 3.3.0.0 has:

Only on my pc at the moment

[PsaltyDS]

Only on my pc at the moment

Just an opinion: Since $CF_TEXT is the default, you might mention the option for $vData to be a string at the top of the description. As it is, the default use is only described after some pretty dense API talk.

[larryc]

OP's clarification: I am running AutoIT 3.3, but the clipboard library says it is version "; AutoIt Version: 3.2.8++"

I didn't want to mix in feature requests with bug reports, but as background, I came across the documentation errata while trying to put CF_HTML ("HTML Format") data on the clipboard. This is widely used, but custom, clipboard format. It is a text format, so I hacked up _clipboard_setdata to support it. (see my posting here: http://www.autoitscript.com/forum/index.ph...st&p=635804 ).

I can try to put together a UDF for this and share it, but if the clipboard library could be extended, it would be even better.