Jump to content
N7XSQ

Embedded Documentation Extractor?

Recommended Posts

N7XSQ

There appears to be comments that are embedded documentation in the user defined function .au3s that are distributed with AutoIt. Is there a documentation generator available anywhere that will generate documentation from this, or any other, style of embedded documentation? I have tried searching the forum, and if it is here, I don't seem to be able to find the right combination of keywords to find it.

Steve

Edited by N7XSQ

Share this post


Link to post
Share on other sites
numdig

Is this what you are talking about? Building Templates

HI I tried to use you program on my include file

and I get the following error :

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

Error

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

ScreenCaptureBIS.au3 - ###User Defined Function###

_ScreenCaptureBIS_CaptureV2

: (37): FuncModify

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

OK

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

The file is tidy and functional.. And I followed that basic tokenization principles... The template generator configuration file seems OK as well. I've even put my include in the standard AUtoIT directory so as not to do anything funky ... So I don't understand the error.

#include-once
#include <WindowsConstants.au3>
#include <WinAPI.au3>
#include <ScreenCapture.au3>

; #INDEX# =======================================================================================================================
; Title .........: ScreenCaptureBIS
; Description ...: ScreenCapture
; Description ...: Tries to fix ScreenCapture's behavior regarding layered windows capture.
; Author(s) .....: Patryk Szczepankiewicz (pszczepa at gmail dot com)
; ===============================================================================================================================

; #CONSTANTS# ===================================================================================================================
Global Const $__SCREENCAPTURECONSTANT_DEFAULT_BITBLT_FLAG = BitOR($SRCCOPY, $CAPTUREBLT)
; ===============================================================================================================================

; #CURRENT# =====================================================================================================================
;_ScreenCaptureBIS_CaptureV2
;_ScreenCaptureBIS_CaptureWndV2
; ===============================================================================================================================

; #FUNCTION# ====================================================================================================================
; Name...........: _ScreenCaptureBIS_CaptureV2
; Description ...: Captures a region of the screen
; Syntax.........: _ScreenCaptureBIS_CaptureV2([$sFileName = ""[, $iLeft = 0[, $iTop = 0[, $iRight = -1[, $iBottom = -1[, $fCursor = True[, $iBitBltFlag = Default]]]]]]])
; Parameters ....: $sFileName   - Full path and extension of the image file
;                 $iLeft       - X coordinate of the upper left corner of the rectangle
;                 $iTop     - Y coordinate of the upper left corner of the rectangle
;                 $iRight     - X coordinate of the lower right corner of the rectangle.  If this is  -1,  the  current  screen
;                 +width will be used.
;                 $iBottom   - Y coordinate of the lower right corner of the rectangle.  If this is  -1,  the  current  screen
;                 +height will be used.
;                 $fCursor   - If True the cursor will be captured with the image
;                 $iBitBltFlag - Flag to pass to the _WinAPI_BitBlt operation (default it BitOR($SRCCOPY, $CAPTUREBLT))
; Return values .: See remarks
; Author ........: Paul Campbell (PaulIA)
; History .......: OCT 25, 2011 - Added $iBitBltFlag parameter. It uses $CAPTUREBLT by default in order to capture layered windows
; Remarks .......: If FileName is not blank this function will capture the screen and save it to file. If FileName is blank, this
;                 function will capture the screen and return a HBITMAP handle to the bitmap image.  In this case, after you are
;                 finished with the bitmap you must call _WinAPI_DeleteObject to delete the bitmap handle.
;+
;                 Requires GDI+: GDI+ requires a redistributable for applications  that
;                 run on the Microsoft Windows NT 4.0 SP6, Windows 2000, Windows 98, and Windows Me operating systems.
; Related .......: _WinAPI_DeleteObject, _ScreenCapture_SaveImage
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _ScreenCaptureBIS_CaptureV2($sFileName = "", $iLeft = 0, $iTop = 0, $iRight = -1, $iBottom = -1, $fCursor = True, $iBitBltFlag = Default)
If $iRight = -1 Then $iRight = _WinAPI_GetSystemMetrics($SM_CXSCREEN)
If $iBottom = -1 Then $iBottom = _WinAPI_GetSystemMetrics($SM_CYSCREEN)
If $iRight < $iLeft Then Return SetError(-1, 0, 0)
If $iBottom < $iTop Then Return SetError(-2, 0, 0)
If $iBitBltFlag = Default Then $iBitBltFlag = $__SCREENCAPTURECONSTANT_DEFAULT_BITBLT_FLAG

Local $iW = ($iRight - $iLeft) + 1
Local $iH = ($iBottom - $iTop) + 1
Local $hWnd = _WinAPI_GetDesktopWindow()
Local $hDDC = _WinAPI_GetDC($hWnd)
Local $hCDC = _WinAPI_CreateCompatibleDC($hDDC)
Local $hBMP = _WinAPI_CreateCompatibleBitmap($hDDC, $iW, $iH)
_WinAPI_SelectObject($hCDC, $hBMP)
_WinAPI_BitBlt($hCDC, 0, 0, $iW, $iH, $hDDC, $iLeft, $iTop, $iBitBltFlag)

If $fCursor Then
Local $aCursor = _WinAPI_GetCursorInfo()
If $aCursor[1] Then
Local $hIcon = _WinAPI_CopyIcon($aCursor[2])
Local $aIcon = _WinAPI_GetIconInfo($hIcon)
_WinAPI_DeleteObject($aIcon[4]) ; delete bitmap mask return by _WinAPI_GetIconInfo()
_WinAPI_DrawIcon($hCDC, $aCursor[3] - $aIcon[2] - $iLeft, $aCursor[4] - $aIcon[3] - $iTop, $hIcon)
_WinAPI_DestroyIcon($hIcon)
EndIf
EndIf

_WinAPI_ReleaseDC($hWnd, $hDDC)
_WinAPI_DeleteDC($hCDC)
If $sFileName = "" Then Return $hBMP

_ScreenCapture_SaveImage($sFileName, $hBMP)
_WinAPI_DeleteObject($hBMP)
EndFunc   ;==>_ScreenCaptureBIS_CaptureV2

; #FUNCTION# ====================================================================================================================
; Name...........: _ScreenCaptureBIS_CaptureWndV2
; Description ...: Captures a screen shot of a specified window. This function is an alternative to '_ScreenCapture_CaptureWnd'.
;                 It is able to take screenshots of layered windows (drawn by the graphic card). See 'remarks' below.
; Syntax.........: _ScreenCaptureBIS_CaptureWndV2($sFileName, $hWnd[, $iLeft = 0[, $iTop = 0[, $iRight = -1[, $iBottom = -1[, $fCursor = True[, $iBitBltFlag = Default]]]]]])
; Parameters ....: $sFileName   - Full path and extension of the image file
;                 $hWnd     - Handle to the window to be captured
;                 $iLeft       - X coordinate of the upper left corner of the client rectangle
;                 $iTop     - Y coordinate of the upper left corner of the client rectangle
;                 $iRight     - X coordinate of the lower right corner of the rectangle
;                 $iBottom   - Y coordinate of the lower right corner of the rectangle
;                 $fCursor   - If True the cursor will be captured with the image
;                 $iBitBltFlag - Flag to pass to the _WinAPI_BitBlt operation (default it BitOR($SRCCOPY, $CAPTUREBLT))
; Return values .: See remarks
; Remarks .......: 1/ If FileName is not blank this function will capture the screen and save it to file. If FileName is blank, this
;                 function will capture the screen and return a HBITMAP handle to the bitmap image.  In this case, after you are
;                 finished with the bitmap you must call _WinAPI_DeleteObject to delete the bitmap handle.  All coordinates are  in
;                 client coordinate mode.
;
;                 2.1/ Layered windows do not appear on screenshots taken by '_ScreenCapture_Capture' because it uses the desktop's
;                 handle whereas the layered windows are drawn directly by the graphic card. 2.2/ '_ScreenCapture_CaptureWnd'
;                 is a wrapper of '_ScreenCapture_Capture' and, therefore, has the same limitations. 2.3/ Instead,
;                 '_ScreenCapture_CaptureWndV2', THIS FUNCTION, is using the handle of the targetted window to perfom its task
;                 (in a similar way than '_ScreenCapture_Capture'uses the Desktop's handle).
;
; Author ........: Patryk Szczepankiewicz (pszczepa at gmail dot com)
; History .......: JAN 21, 2009 - Created
;                 OCT 18, 2010 - First release on the AutoIT forum
;                 OCT 28, 2010 - Cleaned the border code and fixed the capture of the cursor.
;                 APR 06, 2011 - Updated for AutoIT 3.3.6.1
;                 OCT 25, 2011 - Added $iBitBltFlag parameter. It uses $CAPTUREBLT by default in order to capture layered windows
; Related .......: _WinAPI_DeleteObject
; Link ..........; http://www.autoitscript.com/forum/index.php?showtopic=65008
; Example .......; No
; Credits .......: Based on Paul Campbell's '_ScreenCapture_Capture' function and inspired by Jennico's '_WinGetBorderSize'.
; ===============================================================================================================================
Func _ScreenCaptureBIS_CaptureWndV2($sFileName, $hWnd, $iLeft = 0, $iTop = 0, $iRight = -1, $iBottom = -1, $fCursor = True, $iBitBltFlag = Default)

Local $tRect
Local $iWndX, $iWndY, $iWndW, $iWndH

Local $tClient
Local $iBorderV, $iBorderT
Local $iPicHeight, $iPicWidth
Local $iPicCursorX, $iPicCursorY


Local $hDDC, $hCDC, $hBMP, $aCursor, $aIcon, $hIcon

; Default parameters
If $iBitBltFlag = Default Then $iBitBltFlag = $__SCREENCAPTURECONSTANT_DEFAULT_BITBLT_FLAG

; Get the absolute coordinates of the window
$tRect = _WinAPI_GetWindowRect($hWnd)

; Get useful variables
$iWndX = DllStructGetData($tRect, "Left")
$iWndY = DllStructGetData($tRect, "Top")
$iWndW = DllStructGetData($tRect, "Right")
$iWndH = DllStructGetData($tRect, "Bottom")

; Assign automatic values: the right and bottom are computed as
; the width and height of the absolute coordinates of the window.
If $iRight = -1 Then $iRight = $iWndW - $iWndX
If $iBottom = -1 Then $iBottom = $iWndH - $iWndY

; Check user values: check that caller is not putting the top-left
; corner out of the window.
If $iLeft > $iWndW Then $iLeft = $iWndX
If $iTop > $iWndH Then $iTop = $iWndY

; Check user values: check that caller is not asking for a
; screenshot bigger than the window itelf.
If $iRight > $iWndW Then $iRight = $iWndW
If $iBottom > $iWndH Then $iBottom = $iWndH

; Compute the size of the final picture.
$iPicWidth = $iRight - $iLeft
$iPicHeight = $iBottom - $iTop

; Compute the borders sizes
$tClient = _WinAPI_GetClientRect($hWnd)
$iBorderV = (($iWndW - $iWndX) - DllStructGetData($tClient, "Right")) / 2
$iBorderT = ($iWndH - $iWndY) - DllStructGetData($tClient, "Bottom") - $iBorderV

; Transfert color data
$hDDC = _WinAPI_GetDC($hWnd)
$hCDC = _WinAPI_CreateCompatibleDC($hDDC)
$hBMP = _WinAPI_CreateCompatibleBitmap($hDDC, $iPicWidth, $iPicHeight)
_WinAPI_SelectObject($hCDC, $hBMP)
_WinAPI_BitBlt($hCDC, 0, 0, $iPicWidth, $iPicHeight, $hDDC, $iLeft - $iBorderV, $iTop - $iBorderT, $iBitBltFlag)

; Add the cursor on the screenshot
If $fCursor Then
$aCursor = _WinAPI_GetCursorInfo()
If $aCursor[1] Then
$hIcon = _WinAPI_CopyIcon($aCursor[2])
$aIcon = _WinAPI_GetIconInfo($hIcon)
$iPicCursorX = $aCursor[3] - $aIcon[2] - $iWndX - $iLeft
$iPicCursorY = $aCursor[4] - $aIcon[3] - $iWndY - $iTop
_WinAPI_DrawIcon($hCDC, $iPicCursorX, $iPicCursorY, $hIcon)
EndIf
EndIf

; Clean and save data
_WinAPI_ReleaseDC($hWnd, $hDDC)
_WinAPI_DeleteDC($hCDC)
If $sFileName = "" Then Return $hBMP
_ScreenCapture_SaveImage($sFileName, $hBMP)

EndFunc   ;==>_ScreenCaptureBIS_CaptureWndV2
Edited by Chess

Share this post


Link to post
Share on other sites
BrewManNH

After the Author information in the header, you have to have a line with "; Modified.......:" in it, even if it's blank, it has to be there. Your history line should be in the remarks section I believe.


If I posted any code, assume that code was written using the latest release version unless stated otherwise. Also, if it doesn't work on XP I can't help with that because I don't have access to XP, and I'm not going to.
Give a programmer the correct code and he can do his work for a day. Teach a programmer to debug and he can do his work for a lifetime - by Chirag Gude
How to ask questions the smart way!

I hereby grant any person the right to use any code I post, that I am the original author of, on the autoitscript.com forums, unless I've specifically stated otherwise in the code or the thread post. If you do use my code all I ask, as a courtesy, is to make note of where you got it from.

Back up and restore Windows user files _Array.au3 - Modified array functions that include support for 2D arrays.  -  ColorChooser - An add-on for SciTE that pops up a color dialog so you can select and paste a color code into a script.  -  Customizable Splashscreen GUI w/Progress Bar - Create a custom "splash screen" GUI with a progress bar and custom label.  -  _FileGetProperty - Retrieve the properties of a file  -  SciTE Toolbar - A toolbar demo for use with the SciTE editor  -  GUIRegisterMsg demo - Demo script to show how to use the Windows messages to interact with controls and your GUI.  -   Latin Square password generator

Share this post


Link to post
Share on other sites
ProgAndy

After the Author information in the header, you have to have a line with "; Modified.......:" in it, even if it's blank, it has to be there. Your history line should be in the remarks section I believe.

It doesn't have to be I think, but I would put it after the Remarks section

There appears to be comments that are embedded documentation in the user defined function .au3s that are distributed with AutoIt.

That is long waiting for removal. Valik wants to remove all documentation from the source files (maybe except licence, contributors, and a reference to the helpfiles) Edited by ProgAndy

*GERMAN* [note: you are not allowed to remove author / modified info from my UDFs]My UDFs:[_SetImageBinaryToCtrl] [_TaskDialog] [AutoItObject] [Animated GIF (GDI+)] [ClipPut for Image] [FreeImage] [GDI32 UDFs] [GDIPlus Progressbar] [Hotkey-Selector] [Multiline Inputbox] [MySQL without ODBC] [RichEdit UDFs] [SpeechAPI Example] [WinHTTP]UDFs included in AutoIt: FTP_Ex (as FTPEx), _WinAPI_SetLayeredWindowAttributes

Share this post


Link to post
Share on other sites
BrewManNH

It doesn't have to be I think, but I would put it after the Remarks section

That is long waiting for removal. Valik wants to remove all documentation from the source files (maybe except licence, contributors, and a reference to the helpfiles)

I just tested it with his header info, it would have to go after the line "; Example .......: No" because that template builder seems to look for the header information in a non-changing way, one section HAS to follow the previous one or you get an error with the line number.

If I posted any code, assume that code was written using the latest release version unless stated otherwise. Also, if it doesn't work on XP I can't help with that because I don't have access to XP, and I'm not going to.
Give a programmer the correct code and he can do his work for a day. Teach a programmer to debug and he can do his work for a lifetime - by Chirag Gude
How to ask questions the smart way!

I hereby grant any person the right to use any code I post, that I am the original author of, on the autoitscript.com forums, unless I've specifically stated otherwise in the code or the thread post. If you do use my code all I ask, as a courtesy, is to make note of where you got it from.

Back up and restore Windows user files _Array.au3 - Modified array functions that include support for 2D arrays.  -  ColorChooser - An add-on for SciTE that pops up a color dialog so you can select and paste a color code into a script.  -  Customizable Splashscreen GUI w/Progress Bar - Create a custom "splash screen" GUI with a progress bar and custom label.  -  _FileGetProperty - Retrieve the properties of a file  -  SciTE Toolbar - A toolbar demo for use with the SciTE editor  -  GUIRegisterMsg demo - Demo script to show how to use the Windows messages to interact with controls and your GUI.  -   Latin Square password generator

Share this post


Link to post
Share on other sites
numdig

Roger that, loud and clear. So the message is really an indication of the error:

eg. "(90): FuncDesc" idicates an error with the "Description" section at (or expected at) line 90,

and "FuncModif" is about the "Modified" section, etc. OK I think I've got it.

Btw, keep the good work. and thanks for everything you've done so far guys.

Take care.

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

×

Important Information

We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.