Lack of information

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:

  1. 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.

  2. 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?!

  3. 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 --

I’m going to start at the top and go through this until I get tired.

  1. You don’t think SCREEN(Main,Top)+22 is covered in the wiki. You don’t seem to realize that this is two terms added together. SCREEN(Main,Top) is a function that returns a number. The full expression adds 22 to the function result and returns the sum. The 22 is not a parameter passed to the SCREEN function.

  2. You then compare SCREEN(Main,Top)+22 to SCREEN(Main,Width, 120) as if the 22 in the first expression is comparable to the 120 in the second. They are not. You are passing 120 as the third parameter to SCREEN. Because you didn’t include a percent sign after the number, you’re not following the wiki.

    As it happens, you can pass a non-percentage numbers to SCREEN. They are converted to percentages (or perhaps percentages are converted to numbers—the effect is the same). So if your third parameter is .1, it’s the same as passing 10%. If your third parameter is 1, it’s the same as 100%. And if your third parameter is 120, it’s the same as 12000%. That’s going to return a very big number.

    Also, there’s nothing in the wiki about using a third parameter with Width, and the way the third parameter is described, it doesn’t make any sense to do so. A more appropriate second parameter would be Right, although I believe Keyboard Maestro is tolerant and will return the same value for Width as it does for Right.

  3. You then say SCREEN(Main,Width, 120) changes the size of the screen, “but in a nonsensical way.” It doesn’t change the screen size at all. Screens are not windows.

  4. You say an edge cannot be a coordinate because an edge is a line. True, but the edges of screens are either vertical or horizontal and such lines are expressed in analytic geometry with equations like x = 50 or y = 128. Clearly, the "coordinates" of these lines refer to the numbers in those equations.

OK, I'm done.

13 Likes

I had no idea that @peternlewis had senior members, an administration, and even support teams.

Wow ... I'm impressed ...

10 Likes

Then please, please, ask a specific question. You'll get specific information, and if you need more explanation just say -- it's a friendly bunch here, and everyone's been very helpful in the couple of months I've been here and learning about KM.

Functions don't really merit more than a mention in the manual -- seriously, what can you say? "A function accepts nought, one, or more parameters and returns a result -- anything else is specific to the function, please see the Wiki."

Unfortunately, you've picked one of the more complicated functions! It can take 2 or 3 parameters -- there must be a screen index (which can be either number or name, eg 0 or Main, which both refer to "the screen with your primary menu bar) and coordinate (eg Left or Height), plus an optional percentage.

SCREEN is a getter -- a term you'll know from your other programming -- and returns the position or coordinate of your coordinate parameter (which is a bit confusing...). So SCREEN(Main,Left) returns 0 (the x coordinate of the left edge of the main screen), SCREEN(Main,Width) returns 2560 on my iMac (the width of the main screen), and SCREEN(Main,Left,10%) returns 256 -- the coordinate of the left edge of the main screen plus 10% of the width of the main screen.

So you'd use it in eg a "Move and Resize" action, perhaps to make the front window of your target application 10% the width of the main screen, butted up to the left edge. If fact, we'll also use SCREENVISIBLE to make sure the window isn't covered by the menu bar or the dock:

(In order, that's "Set the left edge to:", "Set the top edge to:", "Set the width to:", and "Set the height to:".)

As to some of the language -- an edge being a coordinate, the "internal screen" (which is the one built in to your laptop or iMac), and so on -- these are the terms Apple use, and that they say developers should use. Some are a bit odd until you get used to them, but some are very useful -- for instance, you can always refer to the internal screen of your laptop with worrying whether you've plugged in an external display and made that the main.

Finally:

From that same Wiki page:

Coordinates are in absolute nominal resolution pixels relative to the top left corner of the main screen.

And yes, that means that if you have a screen to the left of your main, x coordinates on that screen will be negative -- and the same for y coordinates for a screen above main.

11 Likes

I do not wish to escalate this. Clearly, I have upset some people which which I can assure you was not my intention.

I wanted to engage in constructive criticism - if I have offended anyone, I regret it. That is why I explicitly started my forum post in a lighter tone with "A little warning here: This developed into a bit of a rant !". Perhaps, I should have suffixed this with a smiley.

However, having said that, I respectfully maintain my core argument... that the wiki page is deeply flawed. I respect that others will have their own opinions on that.

In defence of my argument, the fact that user "drdrang" had to explicitly lay out four separate explanations / examples to elucidate on the function should immediately raise red flags, I believe. I think this advances my argument, in fact.

I doubt (but I may be wrong here) that members of the forum /support people want to continually answer the same technical questions over and over again when, over a few hours (preparing good documentation) you could nullify many of those questions.

Perhaps this a generational thing. I am probably older than many of you. As I said in my post, I worked professionally in computing (support, development, and management) for over 30 years. One of the cornerstones of support management in that time was good documentation and good automation. This wasn't for the end users, you understand! It was for us (the IT support people) - it was for efficiency as we saved between 25 to 35% of our precious time. New users and old users could always go to the documentation first instead of us.

So in summary, I do not wish to denigrate the sterling work (no doubt much of it for free) that you (the members of the forum) are undertaking.

I do maintain my core point however – that it is counter-productive for both sides (the end users and support personnel) to have poor online documentation... And, I maintain my opinion that the Wiki in question (as a source of accurate and enlightening information) is very poor indeed.

Yours with respect...

Photoshop, Motion, After Effects, Excel, Numbers, Hazel, Handbrake, Oracle, Java, C, Swift, R Studio, Visual Studio etc. (I could keep going) don’t have everything I need to do extremely detailed either. Wikis and Documentation are living documents. We bring up the issue (like you did), discuss, add the suggestion and keep it moving. Ranting and proving we are right/correct is miscellaneous. The purpose is to get it right. My hope is that the miraculous @drdrang and the incredible “new guy” @Nige_S have outlined some great assistance for you. In an effort of politeness, I’ll thank them for you. Thanks Gents. I’m sure we can get the wiki modified, if we ask kindly.

Enjoy!

KC

1 Like

These different perspectives are interesting. I think the wiki is fantastic, but I admit it took me awhile to get the hang of it. I realize that may be interpreted as proving that it is "deeply flawed," but I feel that Keyboard Maestros learning curve is itself a matter of getting your hands dirty, learning as you go, and utilizing the two great resources that are this forum and the wiki. If I were to find something lacking or unclear in the wiki, I would ask in the forum and then suggest an improvement to wiki, as @kcwhat suggested.

FWIW, I don't know the details of Peter's operation, but I picture a one man show with very thoughtful priorities and I happily support his development of Keyboard Maestro as I wonder how he does it. I don't have expectations of support teams and admins.

As far as this forum, it's a super friendly and helpful community. Welcome @johnhamill.

8 Likes

Frustration is most easily resolved by asking questions.

Why would there be? Keyboard Maestro is designed so things work orthogonally. The Move and Resize a Window action contains numeric Text Fields, and like all numeric text fields, they can include Calculations user manual section, and all calculations can include Functions, and the SCREEN function is simply one of them.

The wiki page for the SCREEN function describes the SCREEN function, it doesn't reference the fact that it lives within a calculation, or that calculations live within numeric fields, or that numeric fields live within actions, or that actions live within macros, or that macros live within macro groups, because that is all external structural information unrelated to the function in question. Each of those topics are described in other locations, referenced from the home page. Most are covered in the Tutorial (in the Help menu), and the Quick Start, which is generally the first thing anyone using Keyboard Maestro should do and read.

This format is shown on about the fifth line of the SCREEN function:

SCREEN( index [number OR name], coordinate, percentage )

and described further down as:

The optional SCREEN percentage parameter specifies a percentage of the width or height to offset by.

Offsets are always to the right and down, but negative offsets are allowed.

For example SCREEN(Internal,Left,10%) would be the coordinate of left edge of the internal screen plus 10% of the width of the internal screen. SCREEN(Front,Right,-10%) would be the coordinate of the right edge of the external screen minus 10% of the width of the external screen.

Since it expects a percentage, 120 is effectively 12000%, which is not going to give a useful number.

I disagree. There are very few fundamental concepts in Keyboard Maestro, and they are listed in the Wiki page. One of the most fundamental, after the absolute basics of triggers and actions, is Text Fields, and understand the kinds of text fields, and how they operate expands your ability to use Keyboard Maestro dramatically. Once you know that numeric fields can have calculations in them, and those calculations can use functions, and that text fields can have Tokens, then you open up many possibilities.

From the page:

Coordinates are in absolute nominal resolution pixels relative to the top left corner of the main screen.

The entire desktop has a coordinate system from the top left corner of the main screen (which is the one with the menu bar on it in the Arrange section of the Displays system preference).

You omitted the last few words after 10%:

For example SCREEN(Internal,Left,10%) would be the coordinate of left edge of the internal screen plus 10% of the width of the internal screen.

That is, it is the coordinate of the left edge of the internal screen plus 10% of the width of the internal screen. If the internal screen is the main screen, then its left edge would be at coordinate 0. If the main screen is something else, then its left edge will be however far away it is from the left edge of the main screen. Then 10% of the width of the main screen is added. Exactly what you would want the position of a window to be if you wanted it on the internal screen with a 10% gap between the window edge and the screen edge.

The internal screen is the one built in to the Mac, be it an iMac or Laptop. A Studio Mac or a Mac Mini has no internal Mac. It is the “opposite” and “external display”, the one added to the iMac or Laptop. You're right that the wiki doesn't define this, but the wiki doesn't define every english term used. You'll find endless articles on the net on “hooking up an external display to a laptop”, none of which are going to define the term “external”.

Do you? This is much less commonly known that the difference between an internal and external Mac, and far appropriate to be explicitly specified on the wiki page.

What did you search for? A search for “internal display” finds endless articles with titles like “Laptop Internal Display not working”.

The SCREEN() and SCREENVISIBLE functions return the position or size of a screen.

Coordinates are in absolute nominal resolution pixels relative to the top left corner of the main screen.

I would be very interested to know what you would consider decent documentation. What exactly would have helped you understand the results of the SCREEN function, or how it is used, or how it interoperated with numeric fields or actions? If every single function included information about all of that, each function documentation would be filled with redundant information that would make it much less likely to be useful.

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.

Please do, because without some guidance on how to actually improve the page, all the information appears to be there, and to be in other appropriate places.

I wouldn't say upset, but it is less constructive than it could be. If you want it to be constructive, you need to offer an alternative. But also there are mistakes in what you have done and said in following and reading what is there that are exacerbating the issues with understanding.

OK, so offer something constructive as to how it should be changed that would more clearly elucidate the function.

If the same questions kept coming up, the answers would be on the wiki. Much of Keyboard Maestro’s design comes directly from minimising support. This is why almost everywhere in Keyboard Maestro you can hold the option key down and be taken straight to the wiki reference for that particular item (be it triggers, actions, functions, tokens, conditions, collections). This is why the Interactive Help exists for solving problems, and the Tutorial and Quick Start guides for getting started.

I did a quick search for “screen” on the forum, sorted by date, and there does not appear to be any appreciable number of SCREEN function related questions.

I expect I'm as old as you, or certainly close. And I agree. Most apps today have negligible documentation. But I don't think that is an accurate assessment of Keyboard Maestro. The User Manual, which does not even include the reference sections for trigger, actions, function, tokens, condition, collections, runs to 135 pages. Each and every component of Keyboard Maestro then also has reference documentation describing it, so every single function, including the SCREEN function, contains its own reference documentation. And all that reference material is linked directly from the program for easy accessibility.

And it is very effective, especially combined with an active forum to help people resolve real world issues and misunderstanding which are inevitable no matter how good the documentation is. My support email load is negligible, despite the large numbers of Keyboard Maestro users.

All of it free. No one, except me, receives any compensation for Keyboard Maestro. And I'm all there is of “senior [or otherwise] members of the Keyboard Maestro administration and support teams”.

OK, so add something constructive then. @drdrang and I have both gone through your misunderstandings and explained what the wiki actually says. So, with this new understanding, what exactly is missing from the page, or exactly how could it be rewritten so that you would have grasped the material that is there the first time you read the page?

Well said.

So, any constructive suggestions as to how the SCREEN function wiki page could better document the behaviour of the function?

16 Likes

Always bearing in mind, of course, that these things are often slowed by the:

XY problem - Wikipedia


As someone who still remembers Johannesburg in the 1950s, and provides computing support to someone who remembers it in the 1930s, I am only too well aware of how annoying it can be when things don't yield to understanding as fast as we would like.

Fortunately, (unlike the creator, who laboured for six days without a help-desk, and somehow still brought forth all these wonders, visible and unknown, without plotz or complaint), we can always ask.

4 Likes

@peternlewis The truth is, KM can be intimidating. KM is not a spare time software that you learn to master during your lunch break. KM can "construct" almost anything with modules. This is great, but not for beginners. Beginners need ready-made constructions. That's what you also get here. These are the macros provided by the community. These macros could be analyzed to learn from them. Yes, could…but beginners don’t do that. It is probably also a mistake to think that a good manual is needed. I promise you that most people between 15 and 40 don't read manuals.

I am not a coder and I have no idea about software, but I know how markets and customers work. This leads me to my question. Does the developer of KM know what the competition is doing? This question is meant seriously. I really don't know. Do you care what others do who develop similar software?

1 Like

Basically, nope.

I frankly don't really care much about the competition. I might occasionally glance at feature lists looking for inspiration, but that's about it.

I don't look at them for UI inspiration, because Keyboard Maestro has its own UI language - and you're right, it can be a bit intimidating, though I would contend that is largely a false impression. Keyboard Maestro, at its core, is really simple. Macros Groups and Macros, Triggers and Actions. If you understand the basics of that (which you can learn in a few minutes), you are 90% of the way to using Keyboard Maestro effectively. After that, everything else is incremental. Add Tokens and Functions and you can do pretty much anything.

At the end of the day, where I look for how to progress Keyboard Maestro is primarily:

  • Me and my use - doing things I want it to do that it can't (I'd like it to have inbuilt Translation capabilities for example since that is something I would use regularly).
  • Anything necessary for reducing support email (things like the Interactive Help, security warning system (most of my support burden is caused by Apple’s buggy security system), notes and warnings in the editor (eg the macro “Triggered by” checkbox gives hints as to when the macro might not be active).
  • User suggestions (via email or the forum or whatever).
  • Common questions or requests.

And all of that goes in to a long long todo list.

And then I pluck things out of the list, with higher priority for the support issues, and depending on how a new feature:

  • Integrates with other Keyboard Maestro features.
  • Fits within what Keyboard Maestro is and does.
  • How difficult it is to implement.
  • What kind of complexity it adds.
  • How many people it will benefit.
  • How much it will benefit those people.

But as for what other applications do, no, I have no real interest. Keyboard Maestro will either be useful to enough people that they will continue to purchase licenses to keep me gainfully employed building it (which it is), or it wont. If the latter ever happens, well, that will indicate that Keyboard Maestro has outlived its usefulness, and that's ok. But until then, I plan on continuing to build Keyboard Maestro, and there isn't any indication that is going to change any time soon.

21 Likes

Wait. I'm old. Does that make me a "senior member"? I'm not quite retirement age, though, so would I be a "junior member" or "middle aged member" instead? Searching the Wiki and the forums doesn't produce any guidance on this topic. @peternlewis ?

Hi @Frankb. I'm one of the several users that liked @peternlewis' two comments.

You and I have a different perspective. I can't speak for @peternlewis (PL), but I can share my interpretation of the statements in his second post:

I suspect that most indie developers start with a similar motivation and because such developers 'eat their own dog food' their software is not only functional, but more likely polished. As a user, both are big wins.

Keyboard Maestro is an application that is very unique, feature rich, and a great value. I find it amazing that a program with such depth is designed and programmed by one person. I'm clueless regarding the technical details, but I'm quite sure it would be impossible to support (technically and commercially), let along continue to improve, if there wasn't a high priority placed on minimizing support. This may seem "self-serving," but to me it's an obvious win-win for PL and the users.

There's much more that could be stated regarding this point, but I'll summarize by saying that I don't want to rely on software that has an unsustainable commercial model.

The regular and significant upgrades of Keyboard Maestro (including the free "point" releases), as well as PL's regular interaction in this forum, provides clear evidence that users' input is taken seriously. This forum is obviously a great vehicle for feedback but considering the above points, I, and I suspect many others, are careful not to pepper him with questions that can be addressed other ways.

7 Likes

@_jims I respect your interpretation. And I allow myself to have another one. In free societies, that's how you do it :slight_smile: It is the right of the developer to delete my post. And it is my right to state that this is a strange way of dealing with what he sees as criticism. As far as I'm concerned, the matter is closed.

2 Likes

Hi @johnhamill,
Your 2 posts have left me feeling frustrated by a lack of information!

Apart from your rant about the KM wiki you've said nothing at all about what it is that you're trying and failing to get KM to do for you. So why don't you tell us about that and maybe post your macro here for us to look at and maybe help you out?

If you're not sure about how to do that the wiki can help you out here: Forum [Keyboard Maestro Wiki]

4 Likes