Help File/Documentation Issues. (Discussion Only)

[pixelsearch]

@argumentum your suggestion "main window" or "main form" is a good idea, descriptive and correct, the word "main" makes all the difference. I wish you entered this thread earlier

3 hours ago, argumentum said:

We call it a GUI but is a form and inside that form we do what we do. Am not familiar enough to make a writeup about it nor can find a reference link with an explanation of how M$ windows calls each component 🤷‍♂️If any of you find such reference, please post it here.

This link :

Remarks
A top-level form is a window that has no parent form, or whose parent form is the desktop window.
Top-level windows are typically used as the main form in an application.

See how MS wrote "main form" in the remarks above ?

This link :

The great Raymond Chen on explanations :

A window can be created as a child window (WS_CHILD set) or a top-level window (WS_CHILD not set).
A child window has a parent, which you specify when you call CreateWindowEx, and which you can change by calling SetParent.
A top-level window, on the other hand, has no parent. Its parent is NULL.

 

3 hours ago, argumentum said:

calling the main window "the parent" is going to be brought up in the future, since there can be many child windows that each have it's own parent.

I second this.

Have a great evening both of you

[jpm]

@argumentum the intent is really to have ControlGetPos returning info about the parent window

THat what the proposal I will send to Jon

Cheers

[pixelsearch]

Hello  Concerning an example found in the help file, topic _WinAPI_GetAncestor

Local $hWnd, $hParent
$hWnd = GUICreate("test")
ConsoleWrite("Main GUI : $hWnd = " & $hWnd & @crlf) ; added this line for info
$hParent = _WinAPI_GetAncestor($hWnd, $GA_PARENT) ; $hParent is the desktop (as $hWnd is a top-level window)

MsgBox($MB_SYSTEMMODAL, "Parent", "Get Ancestor of " & $hWnd & ": " & $hParent)
MsgBox($MB_SYSTEMMODAL, "Root", "Get Ancestor of " & $hParent & ": " & _WinAPI_GetAncestor($hWnd, $GA_ROOT))
MsgBox($MB_SYSTEMMODAL, "Root Owner", "Get Ancestor of " & $hParent & ": " & _WinAPI_GetAncestor($hWnd, $GA_ROOTOWNER))

If not mistaken, the correct display should be :

...
MsgBox($MB_SYSTEMMODAL, "Parent", "Get Ancestor of " & $hWnd & ...) ; no change
MsgBox($MB_SYSTEMMODAL, "Root", "Get Ancestor of " & $hWnd & ...) ; change
MsgBox($MB_SYSTEMMODAL, "Root Owner", "Get Ancestor of " & $hWnd & ...) ; change

[jpm]

It was created by Gary in 2008

So I will update with

#include <MsgBoxConstants.au3>
#include <WinAPISysWin.au3>

Example()

Func Example()
    GUICreate("test")
    Local $idLabel = GUICtrlCreateLabel("label", 0, 0)
    Local $hLabel = GuiCtrlGetHandle($idLabel)
    MsgBox($MB_SYSTEMMODAL, "Parent", "Get Parent Ancestor of " & $hLabel & ": " & _WinAPI_GetAncestor($hLabel, $GA_PARENT))
    MsgBox($MB_SYSTEMMODAL, "Root", "Get Root Ancestor of " & $hLabel & ": " & _WinAPI_GetAncestor($hLabel, $GA_ROOT))
    MsgBox($MB_SYSTEMMODAL, "Root Owner", "Get Root Owner Ancestor of " & $hLabel & ": " & _WinAPI_GetAncestor($hLabel, $GA_ROOTOWNER))
EndFunc   ;==>Example

 

[mLipok]

haha.. something new that I notice first time

Did you ever notice that some examples have additional note ?

 

https://www.autoitscript.com/autoit3/docs/functions/HotKeySet.htm

Quote

Example 2, @HotKeyPressed usage

 

[pixelsearch]

Hello, just wondering about what follows. Help file, topic _WinAPI_EnumChildWindows

AutoIt help file, topic _WinAPI_EnumChildWindows

Parameters
$hWnd : Handle to the parent window whose child windows are to be enumerated.
If this parameter is 0, this function is equivalent to _WinAPI_EnumWindows().
...

But how could this parameter be 0, when the function returns an immediate @error = 2 in this case !

Func _WinAPI_EnumChildWindows($hWnd, $bVisible = True)
    If Not _WinAPI_GetWindow($hWnd, 5) Then Return SetError(2, 0, 0) ; $GW_CHILD
    ...
EndFunc   ;==>_WinAPI_EnumChildWindows

To be consistent, it should be stipulated like this :

If this parameter is the desktop handle, then this function is equivalent to _WinAPI_EnumWindows().

Actually it seems to be a can of worms, because everything is strange in these functions : AutoIt _WinAPI_EnumWindows() retrieves ALL windows, but msdn EnumWindows function retrieves ONLY top-level windows :

msdn
EnumWindows function (winuser.h)

Enumerates all top-level windows on the screen by passing the handle to each window, in turn, to an application-defined callback function. EnumWindows continues until the last top-level window is enumerated or the callback function returns FALSE.

Now this sentence in AutoIt help file...

If this parameter is 0, this function is equivalent to _WinAPI_EnumWindows().

...is found even in Yashied's original function, and it has been copied from msdn :

msdn EnumChildWindows()

Parameters
[in, optional] hWndParent
Type: HWND
A handle to the parent window whose child windows are to be enumerated. If this parameter is NULL, this function is equivalent to EnumWindows.

As AutoIt decided to take a different way, then this sentence shouldn't be found in AutoIt.

By the way, if you comment out this line :

; If Not _WinAPI_GetWindow($hWnd, 5) Then Return SetError(2, 0, 0) ; $GW_CHILD

...now _WinAPI_EnumChildWindows will return ONLY top-level windows when you pass 0 as parameter, just like msdn stipulates :

If this parameter is NULL, this function is equivalent to EnumWindows.

I doubt these functions will ever be reworked in AutoIt to match msdn (especially we have _WinAPI_EnumWindowsPopup, _WinAPI_EnumWindowsTop etc...) but please, just remove this line from the help file as it's confusing :

If this parameter is 0, this function is equivalent to _WinAPI_EnumWindows().

Thanks

[mLipok]

Please check out the _WinAPI_Print_Window() function example in Windows 11.
It doesn't work well for me.

[argumentum]

_WinAPI_PrintWindow()
Works well with the old "CLASS:CalcFrame" but not with the newer "CLASS:ApplicationFrameWindow"
It would work better with:
Local $hWnd = WinWaitActive("[REGEXPCLASS:CalcFrame|ApplicationFrameWindow]", '', 3)
and WinClose($hWnd, "")  at the end

If the newer calculator has a "don't screen record me" setting ( and that would make sense ) it would fail to screen capture it.
_ScreenCapture_Capture() does capture it so, that's no it.

..well, that as my investigating  

[argumentum]

...digging deeper. https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-printwindow

Local $aCall = DllCall('user32.dll', 'bool', 'PrintWindow', 'hwnd', $hWnd, 'handle', $hDC, 'uint', $bClient)

PrintWindow often fails on modern UWP (Universal Windows Platform) apps like the Windows Calculator because they use hardware acceleration (DirectComposition) instead of standard GDI rendering. PrintWindow only captures the visible GDI content, not the accelerated content. To capture it, you must use Desktop Duplication APIs or ensure the window is not minimized or obscured, though these may still fail on UWP apps

So, we'll need to either come up with another example or a disclaimer of the technologies involved 🤷‍♂️

Edit: _ScreenCapture_CaptureWnd() works well with the newer calculator.

Edited 16 hours ago by argumentum

[Nine]

There is an undocumented flag that can be used for those newer "CLASS:ApplicationFrameWindow" like Calculator.  Use flag 2 and it works like a charm. 

Documentation should be modified accordingly.

[argumentum]

3 hours ago, Nine said:

Use flag 2

where ? how ?

[Nine]

4 minutes ago, argumentum said:

where ? how ?

#include <WinAPI.au3>

Local $hWnd = WinGetHandle("Calculat")
PrintWindow($hWnd, 2)

Func PrintWindow($hWnd, $iFlag = 0)
  Local $aPos = WinGetPos($hWnd)
  Local $hDC_Capture = _WinAPI_GetDC($hWnd)
  Local $hMemDC = _WinAPI_CreateCompatibleDC($hDC_Capture)
  Local $hHBitmap = _WinAPI_CreateCompatibleBitmap($hDC_Capture, $aPos[2], $aPos[3])
  Local $hObject = _WinAPI_SelectObject($hMemDC, $hHBitmap)
  _WinAPI_PrintWindow($hWnd, $hMemDC, $iFlag)
  _WinAPI_SaveHBITMAPToFile("Test.bmp", $hHBitmap)
  _WinAPI_SelectObject($hMemDC, $hObject)
  _WinAPI_DeleteDC($hMemDC)
  _WinAPI_ReleaseDC($hWnd, $hDC_Capture)
  _WinAPI_DeleteObject($hHBitmap)
EndFunc

 

[argumentum]

ok, lets replace the example with this:

expandcollapse popup

#include <GUIConstantsEx.au3>
#include <SendMessage.au3>
#include <StaticConstants.au3>
#include <WinAPIGdi.au3>
#include <WinAPIGdiDC.au3>
#include <WinAPIHObj.au3>
#include <WindowsConstants.au3>

ShellExecute(@SystemDir & '\calc.exe')
Local $hWnd = WinWaitActive("[REGEXPCLASS:CalcFrame|ApplicationFrameWindow]", '', 3)
If Not $hWnd Then
    Exit
EndIf
Sleep(300) ; give it time to draw

; Create GUI
Local $iSize = WinGetPos($hWnd)
Local $hForm = GUICreate('Test ' & StringReplace(@ScriptName, '.au3', '()'), $iSize[2] + 80, $iSize[3] + 80)
Local $idPic = GUICtrlCreatePic('', 40, 40, $iSize[2], $iSize[3])
Local $hPic = GUICtrlGetHandle($idPic)

; Create bitmap
Local $hDC = _WinAPI_GetDC($hPic)
Local $hDestDC = _WinAPI_CreateCompatibleDC($hDC)
Local $hBitmap = _WinAPI_CreateCompatibleBitmap($hDC, $iSize[2], $iSize[3])
Local $hDestSv = _WinAPI_SelectObject($hDestDC, $hBitmap)
Local $hSrcDC = _WinAPI_CreateCompatibleDC($hDC)
Local $hBmp = _WinAPI_CreateCompatibleBitmap($hDC, $iSize[2], $iSize[3])
Local $hSrcSv = _WinAPI_SelectObject($hSrcDC, $hBmp)
Local Const $PW_RENDERFULLCONTENT = 0x2 ; this will go to where it should  =)
_WinAPI_PrintWindow($hWnd, $hSrcDC, $PW_RENDERFULLCONTENT)
_WinAPI_BitBlt($hDestDC, 0, 0, $iSize[2], $iSize[3], $hSrcDC, 0, 0, $MERGECOPY)

_WinAPI_ReleaseDC($hPic, $hDC)
_WinAPI_SelectObject($hDestDC, $hDestSv)
_WinAPI_SelectObject($hSrcDC, $hSrcSv)
_WinAPI_DeleteDC($hDestDC)
_WinAPI_DeleteDC($hSrcDC)
_WinAPI_DeleteObject($hBmp)

; Set bitmap to control
_SendMessage($hPic, $STM_SETIMAGE, 0, $hBitmap)
Local $hObj = _SendMessage($hPic, $STM_GETIMAGE)
If $hObj <> $hBitmap Then
    _WinAPI_DeleteObject($hBitmap)
EndIf

GUISetState(@SW_SHOW)

Do
Until GUIGetMsg() = $GUI_EVENT_CLOSE

WinClose($hWnd, "")

and @Nine, can you find a reference to that "2" flag to document it ? Or the info that should go there if there is no reference to be found ?

Edited 1 hour ago by argumentum
updated

[Nine]

Just now, argumentum said:

can you find a reference to that "2" flag to document it ?

I can't remember where I have found it.  It was a long time ago in the course of developing my Screen Scraper UDF.  

[argumentum]

0x1 PW_CLIENTONLY Captures only the client area. 
0x2 PW_RENDERFULLCONTENT Used to capture the full content, which is useful for modern applications. 

...After some digging I found the following in the chromium source: "The PW_RENDERFULLCONTENT flag is undocumented, but works starting in Windows 8.1. It allows for capturing the contents of the window that are drawn using DirectComposition." UINT flags = PW_CLIENTONLY | PW_RENDERFULLCONTENT; ...

maybe that's enough info for the help file ? 

Edit: updated the example I proposed.

Spoiler

referance of PW_RENDERFULLCONTENT ?

 

 

The term

PW_RENDERFULLCONTENT is a flag used with the Windows API function PrintWindow. It is a constant with a value of 0x00000002 (or simply 2) and is used to control how a window's content is rendered during the capturing process. 

 

Purpose and Usage

The primary purpose of the PW_RENDERFULLCONTENT flag is to assist in capturing the complete visual representation of a window, particularly those that use modern rendering tehniques like hardware acceleration or desktop composition (Aero in older Windows versions). 

• Hardware Acceleration: Many modern applications (e.g., web browsers like Chrome, or applications built with certain frameworks) use hardware acceleration for rendering their content. Standard GDI (Graphics Device Interface) methods like BitBlt sometimes only capture a black area or an incomplete image from such windows.
• Full Content Rendering: When PW_RENDERFULLCONTENT is specified in the call to PrintWindow, it tells the system to try and render the window's full content to the provided device context (DC), effectively bypassing some of the limitations of older capture methods. This can include rendering the window with its correct frame and visual styles, rather than a "classic" or basic frame.
• System Requirements: This flag is only available and functional on Windows 8.1 (Windows NT 6.3) and later versions. 

 

Key Points

• API Function: It is used as a parameter for the Windows API function PrintWindow, which is used to copy the content of a specified window into a device context.
• Compatibility: While very useful, the flag is not officially documented by Microsoft in all public references and is considered an internal flag by some developers, meaning its behavior could theoretically change in future Windows updates.
• Alternative: When this flag is not used (or on older Windows versions), developers often must use alternative methods, such as the newer Windows.Graphics.Capture API for Windows 10/11, to reliably capture hardware-accelerated content. 

Do you need to use this flag for a specific programming task, or are you troubleshooting a window capture issue with the PrintWindow API?

 

AI can make mistakes, so double-check responses

 

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

 

 

While the main documentation for the

PrintWindow function is available on the official Microsoft Learn website, the PW_RENDERFULLCONTENT flag itself is not explicitly listed in the public documentation. It is considered an internal, undocumented flag by Microsoft. 

 

Official Documentation

You can refer to the main, public documentation for the function to understand its documented usage and the officially supported flags (currently only PW_PRINTCLIENT😞

• PrintWindow function (winuser.h) - Win32 apps | Microsoft Learn 

 

Unofficial References and Context

The existence and functionality of PW_RENDERFULLCONTENT are widely discussed in developer forums and Q&A sites, where engineers have discovered it in header files or through reverse engineering.

• Stack Overflow Discussion: This discussion provides insight into where the flag appears in header files and its availability from Windows 8.1 onwards: The third parameter of PrintWindow API - Stack Overflow.
• AutoHotkey Community Forum: This forum details how the flag helps capture GDI+ content that would otherwise appear as a black screen, showing real-world application of the flag. 

The flag's value of 0x00000002 (or 2) is only recognized by the compiler if the target Windows version is set to Windows 8.1 (0x0603) or higher in your project. 

 

...some extra info via AI

Edited 55 minutes ago by argumentum
updated

[mLipok]

16 minutes ago, argumentum said:

0x1 PW_CLIENTONLY Captures only the client area. 
0x2 PW_RENDERFULLCONTENT Used to capture the full content, which is useful for modern applications. 

https://learn.microsoft.com/en-us/answers/questions/1611498/clarification-on-the-nflags-parameter-default-valu

https://learn.microsoft.com/en-us/answers/questions/801244/capturing-a-window

 

minior fixes proposal:

expandcollapse popup

#include <GUIConstantsEx.au3>
#include <SendMessage.au3>
#include <StaticConstants.au3>
#include <WinAPIGdi.au3>
#include <WinAPIGdiDC.au3>
#include <WinAPIHObj.au3>
#include <WindowsConstants.au3>

_Example()

Func _Example()
    ShellExecute(@SystemDir & '\calc.exe')
    Local $hWnd = WinWaitActive("[REGEXPCLASS:CalcFrame|ApplicationFrameWindow]", '', 3)
    If Not $hWnd Then
        Exit
    EndIf
    Sleep(300) ; give it time to draw

    ; Create GUI
    Local $iSize = WinGetPos($hWnd)
    GUICreate('Test ' & StringReplace(@ScriptName, '.au3', '()'), $iSize[2] + 80, $iSize[3] + 80)
    Local $idPic = GUICtrlCreatePic('', 40, 40, $iSize[2], $iSize[3])
    Local $hPic = GUICtrlGetHandle($idPic)

    ; Create bitmap
    Local $hDC = _WinAPI_GetDC($hPic)
    Local $hDestDC = _WinAPI_CreateCompatibleDC($hDC)
    Local $hBitmap = _WinAPI_CreateCompatibleBitmap($hDC, $iSize[2], $iSize[3])
    Local $hDestSv = _WinAPI_SelectObject($hDestDC, $hBitmap)
    Local $hSrcDC = _WinAPI_CreateCompatibleDC($hDC)
    Local $hBmp = _WinAPI_CreateCompatibleBitmap($hDC, $iSize[2], $iSize[3])
    Local $hSrcSv = _WinAPI_SelectObject($hSrcDC, $hBmp)
    Local Const $PW_RENDERFULLCONTENT = 0x2 ; this will go to where it should  =)
    _WinAPI_PrintWindow($hWnd, $hSrcDC, $PW_RENDERFULLCONTENT)
    _WinAPI_BitBlt($hDestDC, 0, 0, $iSize[2], $iSize[3], $hSrcDC, 0, 0, $MERGECOPY)

    _WinAPI_ReleaseDC($hPic, $hDC)
    _WinAPI_SelectObject($hDestDC, $hDestSv)
    _WinAPI_SelectObject($hSrcDC, $hSrcSv)
    _WinAPI_DeleteDC($hDestDC)
    _WinAPI_DeleteDC($hSrcDC)
    _WinAPI_DeleteObject($hBmp)

    ; Set bitmap to control
    _SendMessage($hPic, $STM_SETIMAGE, 0, $hBitmap)
    Local $hObj = _SendMessage($hPic, $STM_GETIMAGE)
    If $hObj <> $hBitmap Then
        _WinAPI_DeleteObject($hBitmap)
    EndIf

    GUISetState(@SW_SHOW)

    Do
    Until GUIGetMsg() = $GUI_EVENT_CLOSE

    WinClose($hWnd, "")
EndFunc   ;==>_Example

 

[argumentum]

...always disliked with a passion those inline examples with "Local" where "Global" goes. Encapsulating all that in an Example() is the way it should be. Looks good, thanks.

[Nine]

$iSize should be renamed $aSize