Help File/Documentation Issues. (Discussion Only)

[mLipok]

In the following topic:

 

is discusion about using:

_WinAPI_SetThreadExecutionState()

 

I want to focus on HelpFile Remarks for this function:

 

On 11.10.2018 at 4:11 PM, Danyfirex said:

Remarks say: This function does not stop the screen saver from executing.

Microsoft Docs  say:

Quote

The SetThreadExecutionState function cannot be used to prevent the user from putting the computer to sleep. Applications should respect that the user expects a certain behavior when they close the lid on their laptop or press the power button.

On my understanging this shoud be stated like this:

Quote

The SetThreadExecutionState function should not be used by developer to intentionally prevent the windows end user from putting the computer to sleep. Applications should respect that the user expects a certain behavior when they close the lid on their laptop or press the power button.

I think the same about change in AutoIt HelpFile :
This function should not does be used by AutoIt user, to prevent windows end user from putting the computer to sleep.
instead:
The _WinAPI_SetThreadExecutionState() function cannot be used to prevent the user from putting the computer to sleep.

And: "This function does not stop the screen saver from executing." should be removed from HelpFile as this is not true on my Win10Pro ( btw. could somebody test and confirm the same behavior on another windows version ? )

What is your's opinion ?

Edited October 12, 2018 by mLipok

[czardas]

On 10/12/2018 at 8:42 PM, mLipok said:

The _WinAPI_SetThreadExecutionState() function cannot be used to prevent the user from putting the computer to sleep

Using _WinAPI_SetThreadExecutionState() does not prevent the user from putting the computer to sleep.

Edited October 14, 2018 by czardas

[mLipok]

Look in Microsoft Docs  for ES_AWAYMODE_REQUIRED remarks .

I thought that this function very well preventing, but should not be used to prevent - is't she ?

Edited October 15, 2018 by mLipok

[czardas]

Sorry mLipok, I have no time to check what these things do. I was simply trying to interpret, and correct, your English.

Using [funcName] does not prevent the user from putting the computer to sleep.
[funcName] should not be used to put the computer to sleep.

These have two very different meanings. Short and easy to understand sentences are best IMHO.

Edited October 16, 2018 by czardas

[czardas]

Just had a quick look at the link, and what is written makes sense in context. I would add a link to this page in the help file. I don't see any reason to alter the text for the help file.

Edited October 16, 2018 by czardas

[mLipok]

ok.

 

[mLipok]

3 minutes ago, czardas said:

I would add a link to this page in the help file.

like this one:

Quote

According to <a href="https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-setthreadexecutionstate">Microsoft Docs</a> $ES_USER_PRESENT should not be used, and $ES_AWAYMODE_REQUIRED should be used only when absolutely necessary.

 

[czardas]

I don't know if copying the text constitutes infringement of copyright - probably.

[czardas]

Something like your example above is possible - or you could simply list the constants and add a single link for the description: See Microsoft Documentation about <a href="https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-setthreadexecutionstate"> SetThreadExecutionState</a>.

[czardas]

To rewrite the description is risky.

[Danyfirex]

@mLipok I think ES_AWAYMODE_REQUIRED prevent a true sleep. So It means it prevents it. I think.

The ES_AWAYMODE_REQUIRED value should be used only when absolutely necessary by media applications that require the system to perform background tasks such as recording television content or streaming media to other devices while the system appears to be sleeping. Applications that do not require critical background processing or that run on portable computers should not enable away mode because it prevents the system from conserving power by entering true sleep.

 

About help file I think is enough to remove "This function does not stop the screen saver from executing." and let the developer deal with the msdn link.

 

Saludos

 

 

[mLipok]

currently in helpfile (not published yet) this look like this:

Quote

 

###Remarks###
The <a href="_WinAPI_SetThreadExecutionState.htm">_WinAPI_SetThreadExecutionState()</a> function cannot be used to prevent the user from putting the computer to sleep.
Applications should respect that the user expects a certain behavior when they close the lid on their laptop or press the power button.

This function does not stop the screen saver from executing.
According to <a href="https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-setthreadexecutionstate">Microsoft Docs</a> $ES_USER_PRESENT should not be used, and $ES_AWAYMODE_REQUIRED should be used only when absolutely necessary.

 

This BOLD text is from the begining (documentation for this function was added in 2013).

Maybe just remove them all, and put this short description:

Quote

[MS DOC] says to use this function with special attention. Read the remarks from [MS DOC] carefully.

 

[czardas]

I agree with @Danyfirex about this.

[mLipok]

3 minutes ago, Danyfirex said:

About help file I think is enough to remove "This function does not stop the screen saver from executing." and let the developer deal with the msdn link.

current helpFile which you can read , have this description:
 

Quote

Remarks

The _WinAPI_SetThreadExecutionState() function cannot be used to prevent the user from putting the computer to
sleep. Applications should respect that the user expects a certain behavior when they close the lid on their
laptop or press the power button.

This function does not stop the screen saver from executing.

As I understand @czardas meant that the literal quote from "MS DOC" is not good idea.
So the conclusion to me is that we should remove them all and only say somethink like this:

Quote

[MS DOC] says to use this function with special attention. Read the remarks from [MS DOC] carefully.

unless I've got lost in it a bit.

[Danyfirex]

I think your suggestion is  fine too.

 

Saludos

[czardas]

I mean that it's difficult to rewrite all the detail without making it harder to understand or overly verbose. Anyone using such advanced functions should be able to interpret the description on MSDN. I do believe the constant names ought to be listed, but rewording MSDN descriptions seems like a huge effort.

[seadoggie01]

The -WinAPI-MoveWindow documentation doesn't mention that it can also be used to resize a control / multiple controls inside of a window as well as resizing a window. Like this

This was incredibly helpful, but also incredibly hard to find. I want a status bar at the bottom of my GUI that is toggle-able, but that would leave a white space without this function.

Edit: Underlined underscores  = space

Edited November 14, 2018 by seadoggie01

[mLipok]

Example for TimerInit:
 

#include <MsgBoxConstants.au3>

Local $hTimer = TimerInit() ; Begin the timer and store the handle in a variable.
Sleep(3000) ; Sleep for 3 seconds.
Local $fDiff = TimerDiff($hTimer) ; Find the difference in time from the previous call of TimerInit. The variable we stored the TimerInit handlem is passed as the "handle" to TimerDiff.
MsgBox($MB_SYSTEMMODAL, "Time Difference", $fDiff)

Is there typo in:

Quote

The variable we stored the TimerInit handlem is passed as the "handle" to TimerDiff.

?

[mLipok]

Anyone (native english speeker) who would explain this form of this word to me ?

Is this just a typo ?

Edited December 20, 2018 by mLipok

[BrewManNH]

Typo, unnecessary m at the end.