Button::paintButton() documentation request

#1

can we get the documentation updated for paintButton()'s 3rd parameter to reflect the actual purpose? I just burned a couple hours trying to figure out why my button wasn’t painting correctly because of my misunderstanding of the function of that 3rd parameter.

suggested:

isButtonDown: true if the button should be drawn in the 'down' position.
 This parameter does not reflect the actual state of the button, just whether or not 
the button is currently being "pressed down" by the mouse cursor.  
use getToggleState() to get the state of the button

I’m sure there are a bunch of users over the years who naively wrote something like this:

void MyButton::paintButton(Graphics& g, bool isMouseOverButton, bool isButtonDown)
{
    if( isButtonDown )
    {
        //draw button in ON state
    }
    else
    {
        //draw button in OFF state
    }
}

when what they really want is:

void MyButton::paintButton(Graphics& g, bool isMouseOverButton, bool isButtonDown)
{
    if( getToggleState() )
    {
        //draw button in ON state
    }
    else
    {
        //draw button in OFF state
    }
}
#2

This gets me just about every time. It should be named isMouseButtonCurrentlyDown or just be removed in place of isMouseButtonDown()

#3

We pretty consistently use “up/down” to indicate mouse-press state, and “on/off” to indicate the toggle state, don’t we?

#4

ok, so since you used down in the 3rd param, shouldn’t it say isMouseDown, not isButtonDown ?

#5

No. The mouse can be down when the button itself isn’t. e.g. when you click and drag off the side of the button’s bounds, it pops up until you move back over it.

Maybe it’d be clearer to call them “shouldDrawButtonAsOver”, “shouldDrawButtonAsDown”?

#6

I think those variable names would help a lot of users. If long-time users like @Holy_City are saying it trips them up every time they need to write a customized paintButton(), that should say something about how the variable names and documentation could probably be improved to express the intent of those parameters.

shouldDrawButtonAsMousedOver maybe for the 2nd one?

#7

Yes, fair enough. I think the concept that’s unclear is that these are intended to be hints about how to draw the button, and the mouse is pretty much irrelevant.

TBH I think maybe “drawButtonAsHighlighted” might be better, avoiding mentioning the mouse.

#8