[haiku-commits] Re: haiku: hrev48561 - docs/user/interface
- From: Adrien Destugues <pulkomandy@xxxxxxxxx>
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Wed, 24 Dec 2014 08:36:02 +0100
On Tue, Dec 23, 2014 at 11:32:49PM +0100, jscipione@xxxxxxxxx wrote:
> +/*!
> + \class BToolTip
> + \ingroup interface
> + \ingroup libbe
> + \brief Displays help text on hover.
> +
> + \attention Use at your own risk! This class is private and may change
> before release.
> +
This class is for advanced uses of tooltips with custom contents or
behavior. The simple way to use tooltips is through BView->SetToolTip,
probably it should be mentionned here.
> + \since Haiku R1A3
> +*/
> +/*!
> + \fn void BToolTip::SetSticky(bool enable)
> + \brief Turns sticky flag on and off.
> +
> + \since Haiku R1
> +*/
> +
> +
> +/*!
> + \fn bool BToolTip::IsSticky() const
> + \brief Returns whether or not the sticky flag is set.
> +
> + \since Haiku R1
> +*/
What is the behavior change when the tooltip is sticky? The fact that
these are setter and getter for the flag is obvious enough from the
method names and doesn't really need to be documented.
So the brief could be something like:
\brief Make the tooltip sticky or transient (?)
\brief Returns true if the tooltip is sticky
And the detailed description should explain how a sticky tooltip is
different from a non-sticky one (I guess it stays visible on mouse
moves?)
> +
> +
> +/*!
> + \fn void BToolTip::SetMouseRelativeLocation(BPoint location)
> + \brief Set the location of the tooltip relative to the current mouse
> position.
This sounds confusing to me. Maybe with more details it could be
clearer:
\brief Sets the tooltip position.
The position is relative to the mouse cursor location at the time the
mouse is shown. It should be as close as possible to the mouse cursor,
but without hiding important parts of the UI near the cursor so the
tooltip parent view is still visible and reachable.
> +/*!
> + \fn void BToolTip::SetAlignment(BAlignment alignment)
> + \brief Set the alignment of the tool tip.
Here as well we need to document what is the behavior of the tooltip
depending on this. Does it allow to select which part of the tooltip
(top-left corner, center, ...) is aligned on the MouseRelativeLocation,
or is it something else?
--
Adrien.
Other related posts:
