source/modules/juce_gui_basics/windows/juce_TooltipWindow.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     A window that displays a pop-up tooltip when the mouse hovers over another component.
  32
  33     To enable tooltips in your app, just create a single instance of a TooltipWindow
  34     object. Note that if you instantiate more than one instance of this class with the
  35     same parentComponent (even if both TooltipWindow's parentComponent is nil), you'll
  36     end up with multiple tooltips being shown! To avoid this use a SharedResourcePointer
  37     to instantiate the TooltipWindow only once.
  38
  39     For audio plug-ins (which should not be opening native windows) it is better
  40     to add a TooltipWindow as a member variable to the editor and ensure that the
  41     editor is the parentComponent of your TooltipWindow. This will ensure that your
  42     TooltipWindow is scaled according to your editor and the DAWs scaling setting.
  43
  44     The TooltipWindow object will then stay invisible, waiting until the mouse
  45     hovers for the specified length of time - it will then see if it's currently
  46     over a component which implements the TooltipClient interface, and if so,
  47     it will make itself visible to show the tooltip in the appropriate place.
  48
  49     @see TooltipClient, SettableTooltipClient, SharedResourcePointer
  50
  51     @tags{GUI}
  52 */
  53 class JUCE_API  TooltipWindow  : public Component,
  54                                  private Timer
  55 {
  56 public:
  57     //==============================================================================
  58     /** Creates a tooltip window.
  59
  60         Make sure your app only creates one instance of this class, otherwise you'll
  61         get multiple overlaid tooltips appearing. The window will initially be invisible
  62         and will make itself visible when it needs to display a tip.
  63
  64         To change the style of tooltips, see the LookAndFeel class for its tooltip
  65         methods.
  66
  67         @param parentComponent  if set to nullptr, the TooltipWindow will appear on the desktop,
  68                                 otherwise the tooltip will be added to the given parent
  69                                 component.
  70         @param millisecondsBeforeTipAppears     the time for which the mouse has to stay still
  71                                                 before a tooltip will be shown
  72
  73         @see TooltipClient, LookAndFeel::drawTooltip, LookAndFeel::getTooltipBounds
  74     */
  75     explicit TooltipWindow (Component* parentComponent = nullptr,
  76                             int millisecondsBeforeTipAppears = 700);
  77
  78     /** Destructor. */
  79     ~TooltipWindow() override;
  80
  81     //==============================================================================
  82     /** Changes the time before the tip appears.
  83         This lets you change the value that was set in the constructor.
  84     */
  85     void setMillisecondsBeforeTipAppears (int newTimeMs = 700) noexcept;
  86
  87     /** Can be called to manually force a tip to be shown at a particular location.
  88
  89         The tip will be shown until hideTip() is called, or a dismissal mouse event
  90         occurs.
  91
  92         @see hideTip
  93     */
  94     void displayTip (Point<int> screenPosition, const String& text);
  95
  96     /** Can be called to manually hide the tip if it's showing. */
  97     void hideTip();
  98
  99     /** Asks a component for its tooltip.
 100         This can be overridden if you need custom lookup behaviour or to modify the strings.
 101     */
 102     virtual String getTipFor (Component&);
 103
 104     //==============================================================================
 105     /** A set of colour IDs to use to change the colour of various aspects of the tooltip.
 106
 107         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 108         methods.
 109
 110         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 111     */
 112     enum ColourIds
 113     {
 114         backgroundColourId      = 0x1001b00,    /**< The colour to fill the background with. */
 115         textColourId            = 0x1001c00,    /**< The colour to use for the text. */
 116         outlineColourId         = 0x1001c10     /**< The colour to use to draw an outline around the tooltip. */
 117     };
 118
 119     //==============================================================================
 120     /** This abstract base class is implemented by LookAndFeel classes to provide
 121         window drawing functionality.
 122     */
 123     struct JUCE_API  LookAndFeelMethods
 124     {
 125         virtual ~LookAndFeelMethods() = default;
 126
 127         /** returns the bounds for a tooltip at the given screen coordinate, constrained within the given desktop area. */
 128         virtual Rectangle<int> getTooltipBounds (const String& tipText, Point<int> screenPos, Rectangle<int> parentArea) = 0;
 129         virtual void drawTooltip (Graphics&, const String& text, int width, int height) = 0;
 130     };
 131
 132     //==============================================================================
 133     /** @internal */
 134     float getDesktopScaleFactor() const override;
 135
 136 private:
 137     //==============================================================================
 138     Point<float> lastMousePos;
 139     SafePointer<Component> lastComponentUnderMouse;
 140     String tipShowing, lastTipUnderMouse, manuallyShownTip;
 141     int millisecondsBeforeTipAppears;
 142     unsigned int lastCompChangeTime = 0, lastHideTime = 0;
 143     bool reentrant = false, dismissalMouseEventOccurred = false;
 144
 145     enum ShownManually { yes, no };
 146     void displayTipInternal (Point<int>, const String&, ShownManually);
 147
 148     std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 149     void paint (Graphics&) override;
 150     void mouseEnter (const MouseEvent&) override;
 151     void mouseDown (const MouseEvent&) override;
 152     void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
 153     void timerCallback() override;
 154     void updatePosition (const String&, Point<int>, Rectangle<int>);
 155
 156     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TooltipWindow)
 157 };
 158
 159 } // namespace juce