Suggested edit for "Application Related Tokens" page

kevinb · June 17, 2024, 4:24pm

Page URL

https://wiki.keyboardmaestro.com/token/Application_Tokens

Section

The second table.

Current

Parameter	Meaning
0 or 1	the front application.
Positive Number	the indexed application from front to back.
Negative Number	the indexed application from back to front.
All	All of the applications, one per line, from front to back.
Foreground	All foreground of the applications, one per line, from front to back.
Background	All background of the applications, one per line, from front to back.

Proposed

Parameter	Meaning	Type of application included
0 or 1	The front application.	Foreground applications.
Positive Number	The application in that position, as numbered from the front.	Foreground applications.
Negative Number	The application in that position, as numbered from the back.	Foreground applications.
All	All applications, listed in front-to-back order.	Foreground and background applications.
Foreground	All foreground applications, listed in front-to-back order.	Foreground applications.
Background	All background applications, listed in front-to-back order.	Background applications.

PS

Strictly speaking, the page title should be "Application-Related Tokens".

cdthomer · November 4, 2024, 3:28pm

I like the proposal as it clarifies that the All parameter will return background applications as well, which can result in a very large list, including a lot of background-only application processes that I dare to say most users don’t care or need to know about.

Related post: Discrepancy Between Running Apps Token and for Each Action or User Error?

jonathonl · December 2, 2024, 1:07pm

Can we please clarify what is meant by foreground in this case?
Is it different to front window?
Is it affected if I have app running in a different space, desktop or screen? or minimised?

kevinb · December 2, 2024, 2:54pm

These and other questions can be tested by making a simple little macro that, say, displays the token values when you trigger it. See what happens in all the circumstances that you're curious about and I think it will all make sense in practice.

cdthomer · December 2, 2024, 3:06pm

Like @kevinb said, this is easily tested. Whenever I want to see what parameters are passed from the triggers, I made and use the following method. I attached the actions file if you want to import them and try it out.

Action Screenshot (click to expand/collapse)

Trigger tokens alert.kmactions (5.2 KB)

jonathonl · December 2, 2024, 10:55pm

Whilst I appreciate I could use trial and error to determine what happens, and use cdthomer's excellent snippet above, the point I was trying to make was that the wiki is not clear and that "foreground" is pretty generic and not precise enough in these circumstances.

Hence, my questions still stand.

kevinb · December 3, 2024, 12:18am

I see, well, yes, as the OP here I would have to agree! Speaking as someone who always likes to RTFM, I certainly like to have unfamiliar territory clearly mapped out. However, I suppose with any software documentation, some general terms won't be defined if it's assumed that the user will be familiar with them – and that assumption will be an expert's assumption, so might be optimistic! So we will always have to work some things out for ourselves, and that's probably for the best, too.

So… if we bring up a list of %Application%Foreground% versus %Application%Background%, what do we have… I would say we have first a list of what I would call "applications" (or "apps" if you prefer), these being programs that the user launches to do a job and interacts with before quitting them. And in the "background" list, we have what I might very sloppily think of as "other processes" (not good terminology!) – these being little apps? applets? that are usually not explicitly called by the user but by applications that might appear on the first list or by the OS or by other processes…

I did look for definitions outside the world of KM (since these are not, I think, KM-specific terms) but was unsuccessful (in the time I was willing to spend on the matter) and the above is simply how I see it for my own understanding.

Really, just trying out the tokens was enough for me, and I was satisfied by that, but if an expert could define "foreground" and "background" in a few words, that might prevent some readers from thinking it's all more complicated than it really is.

To continue that theme, I have found on rare occasions that an entry in the Wiki made my head spin until I experimented with a macro or two, got the idea and then reread the entry, and then found it, with the benefit of hindsight, clear! In some such instances I have sent suggestions – these being from my perspective as a reader and writer, and we all have our own style, haven't we? Sometimes suggestions prompt refinements to the documentation, sometimes not – as you might expect. Peter is open to feedback, and I couldn't ask for more than that.

To recap those:

So some quick experimenting will show that the answer is "no", but more generally, if you want to help improve the documentation, I reckon that the procedure that often works is:

Experiment with simple test macros to answer your own questions.
Suggest changes to the Wiki entry in the light of what you've learned.

For various reasons (I won't get into that since I've gone on long enough already!) I think that is a more effective approach than only suggesting matters that might be covered.