[alpha] WinEvent - easily detect window open, close, move, and more

[Archimede]

Nice... I am waiting for it...

[Archimede]

Hallo Descolada.
I saw the WinEvent... detect any type of window, like system menu, window menu, standard window...
I suggest you, if possible, to add the possibility to set what type of window to detect.

[Descolada]

@Archimede what exactly is missing? Currently WinEvent supports the same window criteria as the native window functions (eg WinExist), so you can filter those windows out by using WinTitle criteria.

[Archimede]

Yes, but:
- to set the function call and, into the called function, filter the window name is simple, but requires many execution time;
- to set only window ( eg, no menu or other ) to call the function ( it save many time about many not desired window detection ) is no possible, because is no possible to define the search window by type ( with or without title, hidden or visible, menu or real window, and so on ).
I think the better solution is allow to define better the window detection, if is possible.
I appreciate ( I hope the word is right ) very much your work.

[Archimede]

I don't understand what is this function in the library:
WinEvent.IsEventTypeRegistered(EventType)
Please, can you explain me it? It seem like
WinEvent.IsRegistered(EventType)
without any other argument defined, or not?

[Descolada]

- to set the function call and, into the called function, filter the window name is simple, but requires many execution time;

I tried to write WinEvent to account for that and it shouldn't require more execution time than normal.

- to set only window ( eg, no menu or other ) to call the function ( it save many time about many not desired window detection ) is no possible, because is no possible to define the search window by type ( with or without title, hidden or visible, menu or real window, and so on ).
I think the better solution is allow to define better the window detection, if is possible.
I appreciate ( I hope the word is right ) very much your work.

It would not save execution time by a lot, because WinEvent is still internally called for the event type for every window. For example, if you use WinEvent.Show("ahk_exe notepad.exe"), the internal callback function is called once any window is showed and then WinEvent filters out the appropriate window using the WinTitle, WinText etc criteria. You can use whatever other criteria you want inside your callback, eg to return if the window is missing a title.
I will consider changing the behavior of DetectHiddenWindows though. Currently hidden windows are detected as well, because multiple WinEvent types require that (eg WinEvent.Exist). Though it does make sense to follow the DetectHiddenWindow setting at the time of registering the event for other types such as Move.

I don't understand what is this function in the library:
WinEvent.IsEventTypeRegistered(EventType)
Please, can you explain me it? It seem like
WinEvent.IsRegistered(EventType)
without any other argument defined, or not?

From WinEvent documentation:

Code: Select all

 * `WinEvent.IsRegistered(EventType, WinTitle:="", WinText:="", ExcludeTitle:="", ExcludeText:="")
 *      Checks whether an event with the specified type and criteria is registered.
 * `WinEvent.IsEventTypeRegistered(EventType)`
 *      Checks whether any events for a given event type are registered.

WinEvent.IsRegistered("Show", "ahk_exe notepad.exe") tells you that there is an event registered to track Notepad, whereas WinEvent.IsEventTypeRegistered("Show") tells you that at least one "Show" event is being tracked.

[Archimede]

@Descolada
I understood all you wrote, thank you very much.
I am an hardware developer and I am careful to the time execution for the hardware control.
I think your explanations are very interesting but, only about time execution, you must consider theAutoHotkey language is not compiled, is interpreted, then every program line requires many time only for to read by interpreter and the conversion; then the time required by the system for many calls is very smaller than the time required for AutoHotkey for the same calls.
I think your work is very interesting and very useful: I am building and searching many libraries for Event managing to save many execution time (I build a keyboard hook library based on InputHook( ... )).
All these considerations are secondary, because you have reason too.
The much important thing is the dependence on SetTitleMatchMode...

[Archimede]

@Descolada
Hallo.
I would like to understand what is the return value of
WinEvent.Stop(EventType?, WinTitle:="", WinText:="", ExcludeTitle:="", ExcludeText:="")
Thank you very much.

[Descolada]

@Archimede it has no return value, it just stops monitoring for the event. There are multiple ways of doing that:

Code: Select all

npHook := WinEvent.Show(NotepadCreated, "ahk_exe notepad.exe")
npHook.Stop() ; you can use the returned object
WinEvent.Stop("Show", "ahk_exe notepad.exe") ; or stop it using the WinTitle criteria
WinEvent.Stop() ; or stop all running events

NotepadCreated(hook, hWnd, dwmsEventTime) {
    hook.Stop() ; or stop it in the callback using the hook object that triggered the callback
}

[Archimede]

@Descolada
I found a small bug:

Code: Select all

SetTitleMatchMode "RegEx"
oEventHook := WinEvent.Show( FunctionTest, ".+" )
WinEvent.Pause( 1 )
iTest := HookWinPauseGet( oEventHook )

In this case the iTest value is 0 and not 1.
The Pause works well.

[Descolada]

@Archimede that behavior is actually by design, although I'm not 100% sure it should be. oHook.IsPaused tells you whether that event hook is paused or will still be paused if WinEvent itself is reactivated.

Lets say you have two event hooks Event1 and Event2, and Event2 is paused. You now call WinEvent.Pause(1), WinEvent.Pause(0). What would you expect: should both Event1 and Event2 be active now? Or should Event2 remain paused? If you call WinEvent.Pause(1) then how would you know which events will start running once you unpause it?

OK, lets say all hooks start running again after WinEvent.Pause(0). What if you want Event2 to remain paused? You would need to check all hooks you want to remain paused and save their states, to pause them again after you call WinEvent.Pause(0). I think that would be inconvenient.

Instead you could use iTest := WinEvent.IsPaused || oEventHook.IsPaused which will tell you the correct answer.

[Archimede]

@Descolada
Then you tell if I use
WinEvent.Pause(0)
that restart only the previous paused event by
WinEvent.Pause(1)
not ALL previous paused events by
oEventHook.Pause(1)
too?

[Descolada]

@Archimede no. If you use WinEvent.Pause(0) then only events that aren't paused will restart. If Event1 is active and Event2 is paused, then after using WinEvent.Pause(1) no events will be active, and after WinEvent.Pause(0) only Event1 will be active. If you also pause Event1 while WinEvent is paused then both Event1 and Event2 will be paused once you unpause WinEvent.

[Archimede]

@Descolada
Please, can you put here an Internet address where i can understand well all definitions like `Show`, `Create`, `Close`, `Exist`, `Active` and so on?
I searched, but I no found anything about it.
I know the definition are autoexplain, but I need to know the exact definitions and differences ( for example, what is the difference between "Show" and "Create" ).
Thank you very much.

[Archimede]

@Descolada
Hallo.
I am trying to understand well the meaning of any Event you defined.
In the library I see this line (values assignation to an associative array):
"Close", [this.EVENT_OBJECT_CREATE, this.EVENT_OBJECT_NAMECHANGE, this.EVENT_OBJECT_DESTROY]
the I would understand what is the *exact* meaning of the Close event? Is it activated by the object cration, too?
What are the exact definition of Active and NotActive? Is "Activation" and "UnActivation"?
I see all events can be sent from many object type: does your utility select only event sent from window object or not?
Thank you very much.

[Descolada]

@Archimede there is no such internet address which clearly and 100% describes them, as I would need to write all that myself.
1) "Create" means window creation, at which point the window might still be invisible. This means you can sometimes capture window events before the window is shown and do something. For example, if you want the window to appear at a certain location then if you move the window after "Create" then there might not be a visible flicker when you use WinMove, as opposed to using it after "Show". This is largely like an async version of WinWait with DetectHiddenWindows "On", but differs in the respect that it isn't triggered if the window title changes to match the WinTitle criteria.
2) "Show" means once a window becomes visible on the screen. This is largely like an async version of WinWait with DetectHiddenWindows "Off".
3) "Close" is triggered once a window which previously matched the WinTitle criteria is destroyed (EVENT_OBJECT_DESTROY). I might change this behavior to match WinWaitClose though, because WinWaitClose is also triggered once the window changes its title and no longer matches (which might not mean the window actually closed).
4) "Exist" is triggered once a window matching the WinTitle criteria exists (so like an async version of WinWait). This might happen after window creation or if a windows title changes.
5) "Active" is triggered once a window matching the WinTitle criteria becomes active (so an async version of WinWaitActive). "NotActive" is triggered once a window that matched WinTitle criteria no longer matches (eg on title change or the foreground window changes).

The exact behaviors are still under development and might change. For example I'm still thinking about how "Close" should work in the case of title change. I'm considering leaving the behavior unchanged and instead adding "NotExist" to differentiate between a window actually closing vs title changing.

[Archimede]

@Descolada
Thank you very much.
I have a problem with Create:
SetTitleMatchMode "RegEx"
oEventHook := WinEvent.Create( FunctionTest, ".+" )

FunctionTest( eventObj, hWnd, dwmsEventTime )
{
sTest4 := WinGetTitle( "ahk_id " . hWnd )
sTest5 := WinGetTitle( "ahk_id " . hWnd )
If( WinGetTitle( "ahk_id " . hWnd ) = "" )
Return
Critical( "On" )
sTest := eventObj
sTest := WinGetClass( "ahk_id " . hWnd )
sTest2 := WinGetProcessName( "ahk_id " . hWnd )
sTest3 := WinGetTitle( "ahk_id " . hWnd )
sTest := dwmsEventTime

}

when I start a new program with a new window ( e.g. Notepad ) it generates error in the function FunctionTest(...) everytime at the first try to read the window
sTest4 := WinGetTitle( "ahk_id " . hWnd )
but after that error it continue, with right read values... why?

[Descolada]

@Archimede WinGetTitle is most likely throwing an error because you haven't used DetectHiddenWindows "On". Remember, "Create" means the event is triggered once a window is created but isn't necessarily visible; "Show" would mean the window is visible and DetectHiddenWindows wouldn't need to be turned on. Also a small warning for you: a window might have an empty title if it hasn't been shown yet, so it might be hard to differentiate between multiple windows from the same process.

[Archimede]

@Descolada
Hallo.
I see
WinEvent.Restore(...)
detect the window normalization after iconization, but no detect window normalization after zooming.
I think the better thing is to detect window normalization after zooming too.

[Archimede]

I found these explanations about Event type:

• Show : When a Window / Menu is shown.
  A previously hidden or non-existent Window or menu appears on the screen.
  It is similar to an asynchronous version of WinWait with DetectHiddenWindows "Off".
  When a program starts, it usually creates a Window; although this Window usually has a name, it may initially be
  hidden and unnamed ( or have a different name than the one that is normally visible ).
  Create : When a Window / Menu was created even though it may be Hidden.
  This Event is generated at the creation of the Window, which may be Hidden at that time. This means that it is
  sometimes possible to detect the Window creation Event before the Window is displayed. This is an asynchronous
  version of WinWait( ... ) with DetectHiddenWindows( True ).
  When a program starts, it usually creates a Window; although this Window usually has a name, it may initially be
  Hidden and Unnamed ( or with a name different from the one normally visible ): since a Hidden Window is normally not
  detected by functions like WinExist( ... ), it is necessary to specify DetectHiddenWindows( True ).
  Close : When a Window / Menu is Destroyed / Closed.
  After this Event is detected, the Window or Menu no longer exists, so any reference to this object generates error.
  Exist : When a Window / Menu exists or begin to exists; renaming Window.
  The Event is generated when, at the time of the call, a Window exists or begins to exist that meets the criteria of
  WinTitle ( so like an asynchronous version of WinWait( ... )). This can happen after the Window is created or when
  the Window title is changed.
  Active : When a Window / menu is Activated / Focused / Renamed.
  The Event is generated when a Window matching the WinTitle criteria becomes active ( so it is like an asynchronous
  version of WinWaitActive( ... )).
  NotActive : When a Window is Unactivated / Unfocused / Renamed / Closed.
  The event is generated when a Window that matched WinTitle criteria no longer matches ( e.g. on title change ).
  After this Event is detected and the Event is Renamed or Closed, the Window or Menu no longer exists, so any
  reference to this object generates error.
  Move : When a window is Moved / Resized / Iconized / Zoomed / Normalized.
  If a window is in a resize or move situation, this Event is repeated continuously throughout that situation.
  MoveStart : When a Window is about to be moved or resized.
  The Event is generated when a window is about to be moved or resized ( even if it has not yet been physically moved
  or resized ).
  MoveEnd : When a Window has finished moving or resizing.
  The Event is generated when a window is finished moving or resizing.
  Minimize : When a window is Iconized.
  The Event is generated when a window is Iconized ( when created, from Zoomed Window or from Normal Window ).
  Restore : When a window is Normalized.
  The Event is generated when a window is Normalized ( from Iconized Window, NOT from Zoomed Window ).
  Maximize : When a window is Zoomed.
  The Event is generated when a window is Zoomed ( when created, from Iconized Window or from Normal Window ).