This is addressed to senior members of the Keyboard Maestro administration and support teams. Please escalate to your team leaders and managers.
A little warning here: This developed into a bit of a rant !
I write to express my utter frustration at the lack of available information on the "SCREEN" function and how it interacts with the action(s) "Move and Resize Window".
The Wiki instructions (function:SCREEN [Keyboard Maestro Wiki]) are abysmal - this is my third attempt to try and obtain a working knowledge of this function. I abandoned my last two attempts opting for reduced functionality "workarounds". Note that I am not a "newbie" - I am well versed in programming. The documentation on this and other like functions however is truly awful.
I have been forced into "trial and error" to try and understand this functionality. I have not fared well with this either.
I have accessed the Forums of course, and got some "snippets" of information, but they offer only generalised information (see forum excerpt below). I do not believe that users of your software want piecemeal instructions however. They want decent clear instructions with accompanying diagrams and (if possible) tutorials.
You can probably sense my rising level of frustration here.
As an example, in the forum post I reference below, I saw that somebody used a constant when using the "Left" parameter of the SCREEN function as in "SCREEN(Main,Top)+22". There is no mention in the Wiki that you can use constants.
So, I thought that maybe you can use constants when using the width parameter (even though there is no mention of it in the Wiki). This type of entry seemed to be accepted (no "red" warning text appears when using the following): SCREEN(Main,Width, 120).
This does change the screen size, but in a nonsensical way. If you use different width numbers, the window size stays the same! I am now forced to trawl through the forums to try and see how you can resize a window using this function. I am sure that those who already understand it find it "intuitive". For users coming to it "cold", I can assure you it is anything but.
I am sure you will write back giving me instructions on how I can resize a window using the function. However, this is no way to learn how to use something. Without understanding, I will be back in the same boat in the near future.
Another couple of examples:
-
The Wiki says: "SCREEN(Internal,Left,10%) would be the coordinate of left edge of the internal screen plus 10%" How can an edge be a coordinate? - An edge is defined "a line or border at which a surface terminates". A line cannot be a coordinate – Absurd and illogical. I have no idea what it means.
-
The Wiki refers to "internal screen of the Mac". What is the internal screen of the Mac?. I have no idea and no idea how to find out (there are no attached URL links to explain these types of terms); I know obviously what the main screen of a Mac is. I did try a Google search on this which returned nothing.... I assume therefore that it is a Keyboard Maestro proprietary term - Is it the innermost window on the main screen? How is anybody supposed to understand any of this?!
-
I am still trying to figure out how the function integrates with the "move/resize a window" action. The action has four boxes with images adjacent to each representing arrows: right-arrow, down-arrow and two double arrowed symbols (for width and height).
The Wiki does not state what the output of SCREEN function. I assume it is a single integer coordinate number. But are these absolute coordinates or offset coordinates from "your chosen screen"? But then you have window height and width parameters? So maybe, you just determine the coordinates of the left corner of the window and then set the height and width? But the Wiki mentions nothing about where you assign constant values for the width and the height of a window. Utterly confusing !
I hope this illustrates how this might drive somebody around and around in circles and eventually insane.
You would be better off dumping this Wiki page. It serves only to confuse. But then, it is the only documentation bar the Forums. I can find nothing in the User Manual referencing this (hardly any reference to any functions). I urge you to please provide some decent documentation. I can see from the forums that it is something that users want as user 'John_Cooper' below (and others) indicate.
As user 'peternlewis' says in the forum excerpt below, "Lots of possibilities (with the SCREEN function), so you can do pretty much anything you like....
You cannot do anything however if you cannot understand how it works.
PS. I started to write my own tutorial on this so that other users wouldn't go through the frustrations that I've gone through, but I gave up.
-- Forum excerpt --
March 2015: Best Way to Test for Screen Size?
User "peternlewis" advises:
The SCREEN function can give you the Left, Right, Top, Bottom coordinate (relative to the top left corner of the main screen), or the MidX or MidY (center), or the Width or the Height of the specified screen. And the screen choice can be the indexed screen (counting from the left), the Main screen (also the “0” screen), Second (left most screen that is not the Main screen), Third (leftmost screen that is not Main or Second), or the Internal or External screen (for MacBooks or iMacs), of the Front screen (screen with the frontmost window), or the Back screen (leftmost screen that is not the Front screen), or the Mouse screen (screen containing the mouse).
Lots of possibilities, so you can do pretty much anything you like.
Reply by "John_Cooper":
Thanks, Peter. What I’m missing is elementary help on how to use the SCREEN function in Keyboard Maestro. I mean, I know how I might use a simple function like SCREENCOUNT .....
-- End Forum excerpt --