(Engine-Level Function)
| Description: | Returns the current status of the locator (mouse) buttons in a certain window and its ancestors. |
| Returns: | Numeric |
Usage:  |
Script or steady state. |
| Function Groups: | Locator, Window |
| Related to: | Click | LocSwitch | SetXLoc | SetYLoc | Target | WinXLoc | WinYLoc | XLoc | YLoc |
| Format: |
WinLocSwitch(Object) |
| Parameters: |
| Object |
| Required. Any expression that returns the object value of any module instance drawn in the window. |
| Comments: | If the mouse isn't over the specified window or one of its ancestors, the function returns the mouse button status for the last time it was over the window (or ancestor). If the locator is not installed, the function returns 0. Otherwise, the return value has the following significance:
|
It cannot be over-emphasized that this function looks at the status of the mouse over not only the window indicated by Object, but all ancestral windows of Object as well. That is to say, any of its children, grandchildren, parents, grandparents, etc. For example, a WinLocSwitch statement in a certain module, we'll call it ModA, and a WinLocSwitch statement in a child module of ModA, call it ModB, will both return a value of 4 if the left mouse button is pressed over either one of them. If this action is not what is required for your application, the LocSwitch function may be more appropriate, since it will return a value of 4 only if the left mouse button is pressed while over the same window containing the module with the LocSwitch statement in it. From the previous example, this means that ModA's function will return the expected value only when over the window containing that module, not when the mouse is over ModB's window, and vice versa.
Example:
If WinLocSwitch(Cond(CurrentWindow() != secondaryWin,
CurrentWindow(),
Invalid())) == 4 TestDraw;
[
...
]
This statement will check the status of the left mouse button if its current window is not the one called secondaryWin. If there has been a change over any of the windows but secondary window, the script will execute and a change of state to TestDraw will occur. At some point prior to this, secondaryWin would have been set to a module instance inside the desired window.
