Talk:API Button Click

Please unrevert my last change.

"Pressed" is not the term Blizzard uses in any of their API documentation nor is it the verb used in the article title.

"Clicked" is.

The distinction, particularly in the discussion of the "down" parameter is not trivial. "Pressed" is down. "Released" is up. Clicked is whichever of those two means the signal is sent.

Clearly, "Pressed" is wrong here.

Additionally, the sentence structure of the reverted-to portion of the article is non-standard English.

I consider this unwarranted reversion to be vandalism, but I will give the offender a bit of time before I report it as such.Mltco78dhs (talk) 21:21, 20 August 2017 (UTC)

Foxlit is an admin, but hopefully he can explain the reasoning. --PcjWowpedia admin (TDrop me a line!•C207,729 contributions and counting) 21:26, 20 August 2017 (UTC)

I don't really care if he owns the moon. I've been working hard to fix the unprofessional and sloppy documentation on these pages, most of which fails to meet your own standards as published in your guidelines document. I spent more than 20 years as a tech writer. I know what I'm doing. Reverting a page to a clearly only semi-literate version with no explanation deserves more commentary that he provided. I'll give it another hour and then I'm ripping his reversion out. It's clearly wrong.Mltco78dhs (talk) 23:11, 20 August 2017 (UTC)

I reverted your changes to API Button Click because they were nonsensical. The original wording was:

true if the button should be considered pressed (but not yet released); otherwise, it'll be considered released.

The intent here is to communicate how the parameter will affect the parameters passed to the OnClick handler fired during the call, drawing parallels to the keybinding-based OnClick dispatch: passing true will make an OnClick call equivalent to one made when the user pressing down a binding clicking the button (a "click down" event of sorts), while passing a false value will make an OnClick call equivalent to one made when the user releases a binding clicking the button (a "click up" event). This matters if the button distinguishes between the two events, as some addons and actionbar-like buttons might do.

You changed this to:

true if the button should be considered clicked when pressed (but not yet released); otherwise, it'll be considered clicked when released.

This is problematic as "when pressed" doesn't make sense when discussing a widget API function: an addon can call :Click() at any time, even while the user is not pressing anything. You might've been trying to document the /click macro command, but that lives on a different page, and even then your interpretation of macro semantics seems rather dubious. — foxlit (talk) 16:56, 21 August 2017 (UTC)

My apologies for the delay. I just got back from a short hospital stay. Don't get old. My issue is more with the missing implied object of the word "considered" and the unnecessary use of a synonym for the word "down" in the original language. "Clicked" is the state that is being returned. "Down" is the parameter name. Arbitrarily swapping out a synonym (pressed) for down and omitting the proper object of the word "considered" is both ambiguous and imprecise. I limited the change to only correcting the grammar issue (in the interest of making minimal changes). The version you are trying to, apparently insisting on, reverting to is wrong on two levels. Grammar and content. If I need to, I'll diagram the sentence for you, but it's wrong, twice. Leave it alone. I ended up here, on this page, through clicking on the MACRO link. If there's a messed up link, we'll need to address that as well. The precise chain that brought me here isn't preserved in anything I have. If the incorrect language is repeated in the actual macro article, it needs to be changed there as well.Mltco78dhs (talk) 09:53, 23 August 2017 (UTC)

originally on User:Foxlit:

I'm not going to get into a protracted grammar-nazi discussion with you in the wiki pages themselves. I brought this here so as not to air "dirty laundry" in public. My problem with the reversion you're trying to do is that the resulting sentence is improperly formed.

I'll break this down for you into digestible pieces:

The original wording (from your comment): true if the button should be considered pressed (but not yet released); otherwise, it'll be considered released.

[This function returns] true if the button should be considered pressed (but not yet released); otherwise, it'll be considered released.

The "down" parameter tells the function to consider the button "clicked" when the button is pressed. The word "considered" is missing its proper object. That's not apparent because the original wording replaces the words "down" and "up" with the words "pressed" and "released". If you simplify it, the original sentence structure with the proper words in place looks wrong, on its face:

[This function returns] true if the button should be considered down (but not yet up); otherwise, it'll be considered up.

Clearly, there is a missing piece. "...should be considered <what, when the hardware button [actual or virtual] is> down...".

The original text conflates the hardware [actual or virtual] event state with the value to be returned. "Clicked" is the result. "Button" is an abstraction for the hardware [actual or virtual]. "Down" is one of two states that will determine precisely which part of the hardware event [actual or virtual] triggers the return.

There are two other errors in grammar in that sentence.

First, the semi-colon is incorrect. That is a conditional sentence (if-then-else or if-then-otherwise). What might be considered an independent clause at the end is, in fact, in integral part of the whole and should only have been set off by a comma in front of "otherwise."

Second, the first portion of the sentence and the last portion of the sentence use incompatible auxiliary verbs (should and will). "Should" is the past form of "shall" and according to https://wow.gamepedia.com/index.php?title=Wowpedia:Manual_of_Style&action=edit&section=21 we're supposed to use present or future tenses. "Will" denotes a future event.

Aside from that, using a passive verb form for a function return is just poor style. A function returns something. Should implies that a decision is to be made based on conditions that are preferable, but not necessarily proscriptive. "I should stop eating donuts because they make me fat." Nothing in there remotely equates to the algorithmic nature of how functions operate. There's no guarantee that the equation "If BMI > 35, return 'Go eat carrots. Leave the Krispy Kremes alone.' else return 'Go ahead. Eat the death-by-fat-and-sugar treat.'" function implied by that will result in the correct action. Functions are more Yodaish. They "do or do not". There is no "should" involved unless you are describing a function that you don't know the parameters of, in which case the "should" belongs in a caveat about the interface description, "These parameters should be correct. If they are, the function will...."

If I'd been writing this from scratch, not attempting to salvage any of the existing text, I'd have gone with this:

If the down parameter is true, this function returns true when the hardware event [actual or virtual] triggers the button down event, otherwise, it returns true when the hardware event [actual or virtual] triggers the button up event.

I hope this makes things clear. I have 30+ years doing this for a living. At one point I was the Senior Technical Editor for Thompson Publishing (Westlaw and every serious, professional-level IT book, ever). I've probably written 40 million words in technical manuals for more companies than I have fingers. This is a private chat, so this isn't a attempt at getting attention. I'm simply trying to explain that, while I am perfectly capable of making an error, I'm really not capable of making a deliberate one.

You may have a point about this not belonging on the Lua API page, but the existing language makes no reference to virtual hardware events at all. I didn't consider, in the scope of my changes, adding one as I was operating on a "least changes" model. I altered what was there to bring it into line with the rules of grammar for Standard American English making as small a change (at the expense of a little bit of absolute clarity) as I could. The MACRO click page is sloppy, unprofessional, and needs work as well. I may go back to look at it, but I'm still catching up from my little adventure in American Health Care (just got back from an emergency room visit that turned into a stay of I-still-don't-quite-know-how-many days).

Mltco78dhs (talk) 11:01, 23 August 2017 (UTC) (Sorry, still getting used to sticking this in the right place.)

To be clear, nobody is arguing with you about grammar. The underlying problem is that your understanding of what this function does is wrong. This appears in a few places: you're reading [This function returns ...] above where you should be reading [Pass ...] (it's an argument, not a return value), and your from-scratch wording, while nicely written, has very little in common with what this function actually does.

This is also the reason for reverting your change, and why the current wording cannot stay: it's a grammar fix based on a wrong interpretation of the content, and actively perpetuates that wrong interpretation. — foxlit (talk) 17:41, 23 August 2017 (UTC)

The grammar is still wrong with this portion of the entry: "Boolean - true if the button should be considered pressed (but not yet released); otherwise, it'll be considered released." The function is for activating the button in question. The button is processed as activated when pressed (if true) and processed as activated when released (if false). It is not "considered" at all. It's a misuse of the word and it's imprecise. This isn't "grammar nazi" stuff - this is fairly basic. There is a significant conflation of terms here. "Pressed" means down, not clicked. Given that the function is directly related to when the function is to send a "click" to a "button" widget with regards to the button being pressed or released, it's important not to do that. Better wording might be this: "Boolean - true if click is to occur when button is pressed, false (or omitted) if click is to occur when the button is released." Given my history with Foxlit, however, I'm loathe to make that change without moderator approval.Mltco78dhs (talk) 17:40, 14 May 2018 (UTC)

"considered" appears here because when you call button:Click("SomeButton", true), you will trigger the button's OnClick script handler (immediately), and its parameters will tell it that SomeButton is pressed (down), regardless of the actual state of SomeButton. This seems well within the "regard as" meaning of consider: the function instructs the script handler to treat SomeButton as pressed, regardless of its actual state.

I dislike the "X is to occur when Y" wording, because to me it sounds like "when Y happens, do X": i.e. calling button:Click("SomeButton", true) will cause the button to be clicked when SomeButton is pressed (later) by the user.

The easiest alternative is probably just to say that the down argument is converted to a boolean and passed as the down argument to the PreClick/OnClick/PostClick script handlers. — foxlit (talk) 20:19, 15 May 2018 (UTC)