void256/nifty-gui — pull request #275 by 3xp0n3nt (2014-08-25 13:03:04+00:00)
Title: Refactor element mouse interaction.

There is an ambiguously-named method in the Element class that spurred
on this refactoring: onClick.

Surely this method began long, long ago with good intentions...

But now that Nifty has separated the idea of a click from a release, now
that there exists multiclicks, primary clicks, secondary clicks,
tertiary clicks, and combinations of clicking and releasing, this method
is embarrassingly outdated.

What it actually does is simulate a click-release of the primary mouse
button. "Simulate" means that normally all mouse actions are handled via
events, but in this case, the event system is bypassed and the mouse
action is handled AS IF it received an event.

This simulation is useful when we want to cause mouse actions to occur
that are not originated by the user. The only actual INTERNAL use case
for this currently is handling NiftyStandardInputEvent.Activate events.

Not only is the Element.onClick method name ambiguous, but the method it
delegates to is also ambiguous; that is, ElementInteraction.activate,
and the method that that method delegates to is also ambiguous:
ElementInteractionClickHandler.activate, and finally this last method
also delegates to another ambiguously named method,
MouseClickMethods.activate.

Why are they ambiguous? Because these "activate" methods are really
simulating a primary mouse button click-release. This "activate" concept
is a bad abstraction because in all these classes it is surrounded by
other methods that very specifically refer to mouse related parts and
actions (wheels, buttons, clicks, etc).

It's very important to have a consistent level of abstraction here. So
the solution is to rename all these "activate" methods to what they are
so that they harmonize with the other methods there, which means using
the phrase "clickAndReleasePrimaryMouseButton" or similar wording as
appropriate.

This renaming revealed that there were some methods missing for
supporting simulating secondary and tertiary mouse button
click-releases, so add those methods as well (most of the framework was
already in place for secondary & tertiary mouse actions).

Now we have elegantly solved the ambiguity of Element.onClick while
simultaneously adding some interesting features:

Element.onClickAndReleasePrimaryMouseButton
Element.onClickAndReleaseSecondaryMouseButton
Element.onClickAndReleaseTertiaryMouseButton

Now we can directly cause a click-release for either of the three mouse
buttons supported by Nifty, without having to dig through the code to
interpret the meaning of bad abstractions (Element class already
contains much explicit mouse-related functionality, so the above three
methods are not out of place).

Because the Element.onClick method is public, deprecate it rather than
deleting it (in line with other past refactorings of public Element class
methods). Refer users via the onClick javadoc to
onClickAndReleasePrimaryMouseButton.

Make Element.onClick delegate to
Element.onClickAndReleasePrimaryMouseButton.

Add extensive javadoc to Element.onClickAndReleasePrimaryMouseButton,
Element.onClickAndReleaseSecondaryMouseButton, &
Element.onClickAndReleaseTertiaryMouseButton to explain what they do and
in what situations they won't work. (This information was missing on the
Element.onClick method, making it even worse).

Change all internal callers of Element.onClick to use
Element.onClickAndReleasePrimaryMouseButton. Now, Element.onClick has no
uses internally and is ready to be deleted after the next release of the
library.

Element.onClickAndReleasePrimaryMouseButton is used internally to handle
NiftyStandardInputEvent.Activate events. The name of the new method is
self-documenting and should eliminate confusion for users implementing
custom controls and/or custom input mapping. They also now have the
option of mapping to secondary and/or tertiary mouse button
click-releases.

When Element.clickAndReleasePrimaryMouseButton is called, now not only
will a NiftyMousePrimaryClickedEvent be generated as before, but ALSO a
NiftyMousePrimaryReleaseEvent. The same applies for secondary & tertiary
mouse button click-releases. This was actually a preexisting bug that
has been fixed.

Other changes:

Remove all other methods from the Element class that were deprecated in
the previous version of Nifty. It should be safe to remove them now that
they are deprecated in the current release version of Nifty. None of
these methods were in use internally.

The multiclick mouse code was poorly written, not conforming to the
library's code style, contained spelling errors and poorly written
comments. This has been improved although it is still far from complete.
The logic of the multiclick code has not been changed.

All unit tests are passing, and integration testing was successful.