Jump to content
Sign in to follow this  
larryc

Found errors in _ClipBoard_SetData documentation

Recommended Posts

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

Share this post


Link to post
Share on other sites
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.

:)


Valuater's AutoIt 1-2-3, Class... Is now in Session!For those who want somebody to write the script for them: RentACoder"Any technology distinguishable from magic is insufficiently advanced." -- Geek's corollary to Clarke's law

Share this post


Link to post
Share on other sites
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.


SciTE for AutoItDirections for Submitting Standard UDFs

 

Don't argue with an idiot; people watching may not be able to tell the difference.

 

Share this post


Link to post
Share on other sites
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?

:)


Valuater's AutoIt 1-2-3, Class... Is now in Session!For those who want somebody to write the script for them: RentACoder"Any technology distinguishable from magic is insufficiently advanced." -- Geek's corollary to Clarke's law

Share this post


Link to post
Share on other sites
GaryFrost

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

:)

Only on my pc at the moment


SciTE for AutoItDirections for Submitting Standard UDFs

 

Don't argue with an idiot; people watching may not be able to tell the difference.

 

Share this post


Link to post
Share on other sites
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.

:)


Valuater's AutoIt 1-2-3, Class... Is now in Session!For those who want somebody to write the script for them: RentACoder"Any technology distinguishable from magic is insufficiently advanced." -- Geek's corollary to Clarke's law

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this  

×