Help File/Documentation Issues. (Discussion Only)

[Danp2]

@mLipok Following the "See Also" links will lead you to here.

[jpm]

no idea how to use it but the name is a MSDN one just look at _WinAPI_CreateWindowStation()

[pixelsearch]

Hi everybody

autoit-v3.3.16.1-rc2
There's something I don't understand in the help file, concerning a change made to the last parameter of _ArrayDisplay, which now accepts negative values :

$iDesired_Colwidth [optional]
If positive : Max width to which a ListView column will expand to show content. Default = 350 pixels.
If negative : All columns, except the first one set to 55, will be set to Abs($iDesired_Colwidth). 

When you read this, you may think that indicating a negative value (-70 for example) will force all columns (except the 1st one set to 55) to have exactly a width of 70, no matter the headers length or the items length.

But it's not the case (at least in my quick test). For example, with this script based on the help file's _ArrayDisplay script (reworked) :

; autoit-v3.3.16.1-rc2 (or autoit-v3.3.16.1-rc1 which got same ArrayDisplayInternals.au3)

#include <Array.au3>

Example()

Func Example()

        ; Create 2D array to display
        Local $aArray_2D[20][4]
        For $i = 0 To UBound($aArray_2D) - 1
                For $j = 0 To UBound($aArray_2D, 2) - 1
                        $aArray_2D[$i][$j] = "aaaaaaaaaaaItem " & StringFormat("%02i", $i) & StringFormat("%02i", $j)
                Next
        Next

        _ArrayDisplay($aArray_2D, "2D display", Default, Default, Default, _
            "PersonalHeader0|PersonalHeader1", -70)

EndFunc    ;==>Example

1st column got exactly a width of 55 (ok) then all other columns got a width of 135 each (instead of 70).
If this behavior is intentional, then shouldn't it be explained differently in the help file ?

[jpm]

the column size is always addapted to the length of the element displayed to show the entry data's

I don't know if it is needed to add more explanation in the help

Cheers

[pixelsearch]

Hi Jpm,
imho it would be great to add the explanation you just indicated, to warn users so they won't ask themselves why the result isn't what they expected :

If Negative : all columns, except the first one set to 55, will be set to Abs($iDesired_Colwidth). But remember, the column size is always adapted to the length of the element displayed to show the entry data's.

Thanks.

[jpm]

in fact it is true  for positive or negative

[pixelsearch]

Gladly I never used this 7th parameter before. Personal tests just done now don't make it clearer (at least for me).
Please have a look at these 4 tests (autoit-v3.3.16.1-rc2) :

#include <Array.au3>

Example()

Func Example()

        ; Create 2D array to display
        Local $aArray_2D[20][4]
        For $i = 0 To UBound($aArray_2D) - 1
                For $j = 0 To UBound($aArray_2D, 2) - 1
                        $aArray_2D[$i][$j] = "" & "aaaaaaaaaaaaaaaaaaaaaaItem " & _  ; <==== "" or "b" in 4 examples below
                            StringFormat("%02i", $i) & StringFormat("%02i", $j)
                Next
        Next

        _ArrayDisplay($aArray_2D, "2D display", Default, Default, Default, _
            "PersonalHeader0|PersonalHeader1", 50) ; <==== 50 or -50 in 4 examples below

EndFunc    ;==>Example

1) Last parameter is 50, Data is "" & "aaa..."

Each column got a width of 200 pixels (on my computer, not sure it will appear same on yours)

2) Last parameter is 50, Data is "b" & "aaa..."

Each column got a width of 50 pixels because width of data > 200 pixels. Where does this 200 constant come from ?

3) Last parameter is -50, Data is "" & "aaa..."

Each column got a width of 200 pixels (same display as example 1)

4) Last parameter is -50, Data is "b" & "aaa..."

Each column got a width of 210 pixels when initially displayed (initial "b" making it larger > 200 pixels)

Is there a logic in these 4 examples ?

Help file (reminder) :

$iDesired_Colwidth : [optional]
If positive : max width to which a ListView column will expand to show content. Default = 350 pixels.
If negative : all columns, except the first one set to 55, will be set to Abs($iDesired_Colwidth).

Thanks for reading

[argumentum]

I was wandering about the FileGetTime. It now has UTC support but FileSetTime not ?!. So I tested and it does but there is no telling in the help file.
So on type,  "$FT_UTC (4) = UTC time instead of Local time" need to be added.

Edit: No such thing. Was in a hurry this morning. Brain fart !.

Edited June 28, 2022 by argumentum
oops

[argumentum]

hmmm, do test them ( Get/Set time ) in UTC and Local:

..same brain fart from above. Sorry about it  

Edited June 28, 2022 by argumentum
oops

[argumentum]

The prior 2 posts are wrong. 

[mLipok]

Documentation regarding: Language Reference - Datatypes states that:

Quote

Keyword

AutoIt uses 4 Keywords as datatypes

True        Boolean True - e.g. 7 = 7
False       Boolean False - e.g. 5 >= 14
Default   Only used for assigning a default value to optional arguments of a function.
Null        An unknown value. (Note this keyword is NOT part of a 3-valued logic as in other languages such as SQL).

 

but maybe it should be suplemented by adding there  ByDefault ?

[argumentum]

..it' be redundantly redundant. Default is by default. Where would you place the ByDefault ?

[mLipok]

I'm not sure if you notice but now in 3.3.16.x versions we have new keyword ByDefault which is not the same as Default.

Even IsKeyword have new return value:

Quote

Return Value

Success:

$KEYWORD_DEFAULT (1) the Default keyword.     $KEYWORD_NULL (2) the Null keyword.     $KEYWORD_BYDEFAULT (3) the ByDefault keyword.

 

Thus my kindly asked question:

  

46 minutes ago, mLipok said:

but maybe it should be suplemented by adding there  ByDefault ?

 

Edited July 11, 2022 by mLipok

[argumentum]

...you've got me there !. I thought it was a linguistic interpretation.
If is a new concept then an example of use should be given, as to know how to implement the concept. 

I looked at the 3.3.6.1 chm and can not find the ByDefault keyword. And my AutoItConstants.au3 don't have it.

; Keywords (returned from the IsKeyword() function)
Global Const $KEYWORD_DEFAULT = 1
Global Const $KEYWORD_NULL = 2

I'd guess it would return ByDefault (3), if not only is Default but also not changed, and in fact the ByDefault value.
I'd also guess that is a script braking change ( but I've been having some brain farts above ), so without a use case example, I have no idea.

Edit: downloaded and installed RC2 and is not there, so, this is not out yet. MVP stuff

Edited July 11, 2022 by argumentum

[Melba23]

mLipok,

You asked for such a Keyword here: https://www.autoitscript.com/trac/autoit/ticket/3892. But it is as yet only in the latest Alpha release from jpm. Please do not spreadi rumours about this limited-release version beyond its intended scope.

M23

[pixelsearch]

Hi everybody 
Help file, topic _WinAPI_AddFontResourceEx . Here is what we read in the Remarks section :

Remarks
This function installs the font only for the current session. When the system restarts, the font will not be present.
To have the font installed even after restarting the system, the font must be listed in the registry.

Why isn't it mentioned also what we read on msdn :

Remarks
...
When an application no longer needs a font resource it loaded by calling the AddFontResourceEx function, it must remove the resource by calling the RemoveFontResourceEx function.

imho it should be mentioned and the corresponding example in the help file should end with :

; Clean up resources (important flag $FR_PRIVATE, as found in _WinAPI_AddFontResourceEx just above)
_WinAPI_RemoveFontResourceEx(@ScriptDir & '\Extras\SF Square Head Bold.ttf', $FR_PRIVATE)

Please note the correct comment in AutoIt help file, topic _WinAPI_RemoveFontResourceEx :

$iFlag  [optional] ... In order for the font to be removed, the flags used must be the same as when the font was added with the _WinAPI_AddFontResourceEx() function.

This discussion has started in this link, after @funkey solved nicely OP's issue

[argumentum]

so use:

#include <ButtonConstants.au3>
#include <GUIConstantsEx.au3>
#include <WinAPIGdi.au3>

Example()

Func Example()
    Local $sFontFile = StringLeft(@AutoItExe, StringInStr(@AutoItExe, '\', 0, -1) -1) & '\Examples\Helpfile\Extras\SF Square Head Bold.ttf'
    Local $hGUI = GUICreate("GDI", 720, 235)
    Local $idButton = GUICtrlCreateButton("AutoIt" & @CRLF & "forever", 100, 32, 520, 170, $BS_MULTILINE)

    _WinAPI_AddFontResourceEx($sFontFile, $FR_PRIVATE)
    GUICtrlSetFont($idButton, 28, 0, 0, "SF Square Head Bold")

    GUISetState()

    ; Loop until user exits
    Do
    Until GUIGetMsg() = $GUI_EVENT_CLOSE

    ; Clean up resources
    ; If not removed font is installed until system restart
    _WinAPI_RemoveFontResourceEx($sFontFile, $FR_PRIVATE)

    GUIDelete($hGUI)
EndFunc   ;==>Example

for _WinAPI_AddFontResourceEx() and _WinAPI_RemoveFontResourceEx() and amend the remarks.
Ok, sounds good

[pixelsearch]

@argumentum concerning the 2nd parameter of _WinAPI_AddFontResourceEx ($iFlag) , here are a few thoughts & personal tries I'd like to share with you :

AutoIt Help file :

$iFlag [optional] The characteristics of the font to be added to the system. This parameter can be one of the following values :
$FR_PRIVATE
$FR_NOT_ENUM 

We could add some explanations in the help file, like :

$iFlag [optional] The characteristics of the font to be added to the system. This parameter can be one of the following values :
* Default value (0)    : the font can subsequently be used for text output by any application.
* $FR_PRIVATE   (0x10) : only the process that called the AddFontResourceEx function can use this font.
* $FR_NOT_ENUM  (0x20) : no process, including the process that called the AddFontResourceEx function, can enumerate this font. 

I tried the 0 value (blank 2nd parameter) in your script, like this :

_WinAPI_AddFontResourceEx($sFontFile)

Then, while the GUI is active, we can see this new font "SF Square Head Bold" listed in NotePad (or Word etc...) and use it directly in any other application that output text. Of course, as soon as we close the GUI and this line is executed...

_WinAPI_RemoveFontResourceEx($sFontFile)

...then the font is not listed and not usable any more in NotePad, everything is correct.

A user should never be "scared" if he forgot to remove the font at the end of his script because the registry hasn't been touched and the font will disappear after the next reboot. If we want to remove it without a reboot, then a simple script like this one will remove it (tested) :

#include <WinAPIGdi.au3>

Local $sFontFile = StringLeft(@AutoItExe, StringInStr(@AutoItExe, '\', 0, -1) -1) & '\Examples\Helpfile\Extras\SF Square Head Bold.ttf'

_WinAPI_RemoveFontResourceEx($sFontFile)

In fact the number of times we call _WinAPI_RemoveFontResourceEx() should always be equal to the number of times we called _WinAPI_AddFontResourceEx(), only then the font will be removed without a reboot.

I also tested successfully $FR_NOT_ENUM (by using _WinAPI_EnumFontFamilies to display all fonts) but it seems less important, compared to the default value flag (0) or $FR_PRIVATE (0x10)

[argumentum]

...I guess FR_PRIVATE should be the default but, It would not kill anyone if not private.
The additional explanation I'd like to see in a next version.
An _WinAPI_AddFontResource() as a dumb down function would be handy to have. So the function itself keeps track of what's added, avoid calling the loading of a font more than once ( by hashing the file ), and an OnExit to remove the added fonts. 

[pixelsearch]

14 hours ago, argumentum said:

An _WinAPI_AddFontResource() as a dumb down function would be handy to have

This function exists in Windows but not in AutoIt. Let's have a look at these 4 msdn web pages :

Private fonts :
AddFontResourceExW  (this function allows a process to use fonts without allowing other processes access to the fonts)
RemoveFontResourceExW

Public fonts :
AddFontResourceW (the fonts can subsequently be used for text output by any application)
RemoveFontResourceW

Following msdn recommandations, here is a quick script showing how these 4 functions (4, not 2 as in actual AutoIt) could have been scripted. Actually the 2 functions found in AutoIt ( _WinAPI_AddFontResourceEx  and  _WinAPI_RemoveFontResourceEx  ) come directly from Yashied's code (written in 2012) where he mixed the 4 msdn functions to create only 2 AutoIt functions.

expandcollapse popup

; no include files in this script (+++)

Global Const $GUI_EVENT_CLOSE = -3, $BS_MULTILINE = 0x2000, $FR_PRIVATE = 0x10, $FR_NOT_ENUM = 0x20

Example()

Func Example()
    Local $sFontFile = StringLeft(@AutoItExe, StringInStr(@AutoItExe, '\', 0, -1) -1) & '\Examples\Helpfile\Extras\SF Square Head Bold.ttf'

    ; >>>>>>>> Add a private font (not usable by other applications)
    Local $hGUI = GUICreate("PRIVATE font (not listed in NotePad)", 720, 235)
    Local $idButton = GUICtrlCreateButton("AutoIt" & @CRLF & "forever", 100, 32, 520, 170, $BS_MULTILINE)
    _WinAPI_AddFontResourceEx($sFontFile)
    If @error Then ConsoleWrite("@error 1 = " & @error & @crlf)
    GUICtrlSetFont($idButton, 28, 0, 0, "SF Square Head Bold")
    GUISetState()

    Do
    Until GUIGetMsg() = $GUI_EVENT_CLOSE

    ; Clean up resources
    _WinAPI_RemoveFontResourceEx($sFontFile)
    If @error Then ConsoleWrite("@error 2 = " & @error & @crlf)
    GUIDelete($hGUI)


    ; >>>>>>>> Add a public font (usable by other applications)
    Local $hGUI = GUICreate("PUBLIC font (listed in NotePad)", 720, 235)
    Local $idButton = GUICtrlCreateButton("AutoIt" & @CRLF & "forever", 100, 32, 520, 170, $BS_MULTILINE)
    _WinAPI_AddFontResource($sFontFile)
    If @error Then ConsoleWrite("@error 3 = " & @error & @crlf)
    GUICtrlSetFont($idButton, 28, 0, 0, "SF Square Head Bold")
    GUISetState()

    Do
    Until GUIGetMsg() = $GUI_EVENT_CLOSE

    ; Clean up resources
    _WinAPI_RemoveFontResource($sFontFile)
    If @error Then ConsoleWrite("@error 4 = " & @error & @crlf)
    GUIDelete($hGUI)

EndFunc   ;==>Example

;----------------------------------------------------------
Func _WinAPI_AddFontResourceEx($sFont, $iFlag = $FR_PRIVATE) ; add private font
    Local $aRet = DllCall('gdi32.dll', 'int', 'AddFontResourceExW', 'wstr', $sFont, 'dword', $iFlag, 'ptr', 0)
    If @error Or Not $aRet[0] Then Return SetError(@error, @extended, 0)
    Return $aRet[0]
EndFunc   ;==>_WinAPI_AddFontResourceEx

;----------------------------------------------------------
Func _WinAPI_RemoveFontResourceEx($sFont, $iFlag = $FR_PRIVATE) ; remove private font
    Local $aRet = DllCall('gdi32.dll', 'bool', 'RemoveFontResourceExW', 'wstr', $sFont, 'dword', $iFlag, 'ptr', 0)
    If @error Or Not $aRet[0] Then Return SetError(@error, @extended, False)
    Return $aRet[0]
EndFunc   ;==>_WinAPI_RemoveFontResourceEx

;===========================================================
Func _WinAPI_AddFontResource($sFont) ; add public font
    Local $aRet = DllCall('gdi32.dll', 'int', 'AddFontResourceW', 'wstr', $sFont)
    If @error Or Not $aRet[0] Then Return SetError(@error, @extended, 0)

    Local Const $WM_FONTCHANGE = 0x001D
    Local Const $HWND_BROADCAST = 0xFFFF
    DllCall('user32.dll', 'none', 'SendMessage', 'hwnd', $HWND_BROADCAST, 'uint', $WM_FONTCHANGE, 'wparam', 0, 'lparam', 0)

    Return $aRet[0]
EndFunc   ;==>_WinAPI_AddFontResource

;===========================================================
Func _WinAPI_RemoveFontResource($sFont) ; remove public font
    Local $aRet = DllCall('gdi32.dll', 'bool', 'RemoveFontResourceW', 'wstr', $sFont)
    If @error Or Not $aRet[0] Then Return SetError(@error, @extended, False)

    Local Const $WM_FONTCHANGE = 0x001D
    Local Const $HWND_BROADCAST = 0xFFFF
    DllCall('user32.dll', 'none', 'SendMessage', 'hwnd', $HWND_BROADCAST, 'uint', $WM_FONTCHANGE, 'wparam', 0, 'lparam', 0)

    Return $aRet[0]
EndFunc   ;==>_WinAPI_RemoveFontResource