1 /*
2   ==============================================================================
3 
4    This file is part of the JUCE library.
5    Copyright (c) 2020 - 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 6 End-User License
11    Agreement and JUCE Privacy Policy (both effective as of the 16th June 2020).
12 
13    End User License Agreement: www.juce.com/juce-6-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     void displayTip (Point<int> screenPosition, const String& text);
89 
90     /** Can be called to manually hide the tip if it's showing. */
91     void hideTip();
92 
93     /** Asks a component for its tooltip.
94         This can be overridden if you need custom lookup behaviour or to modify the strings.
95     */
96     virtual String getTipFor (Component&);
97 
98     //==============================================================================
99     /** A set of colour IDs to use to change the colour of various aspects of the tooltip.
100 
101         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
102         methods.
103 
104         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
105     */
106     enum ColourIds
107     {
108         backgroundColourId      = 0x1001b00,    /**< The colour to fill the background with. */
109         textColourId            = 0x1001c00,    /**< The colour to use for the text. */
110         outlineColourId         = 0x1001c10     /**< The colour to use to draw an outline around the tooltip. */
111     };
112 
113     //==============================================================================
114     /** This abstract base class is implemented by LookAndFeel classes to provide
115         window drawing functionality.
116     */
117     struct JUCE_API  LookAndFeelMethods
118     {
119         virtual ~LookAndFeelMethods() = default;
120 
121         /** returns the bounds for a tooltip at the given screen coordinate, constrained within the given desktop area. */
122         virtual Rectangle<int> getTooltipBounds (const String& tipText, Point<int> screenPos, Rectangle<int> parentArea) = 0;
123         virtual void drawTooltip (Graphics&, const String& text, int width, int height) = 0;
124 
125        #if JUCE_CATCH_DEPRECATED_CODE_MISUSE
126         // This method has been replaced by getTooltipBounds()
getTooltipSizeLookAndFeelMethods127         virtual int getTooltipSize (const String&, int&, int&) { return 0; }
128        #endif
129     };
130 
131 private:
132     //==============================================================================
133     Point<float> lastMousePos;
134     Component* lastComponentUnderMouse = nullptr;
135     String tipShowing, lastTipUnderMouse;
136     int millisecondsBeforeTipAppears;
137     int mouseClicks = 0, mouseWheelMoves = 0;
138     unsigned int lastCompChangeTime = 0, lastHideTime = 0;
139     bool reentrant = false;
140 
141     void paint (Graphics&) override;
142     void mouseEnter (const MouseEvent&) override;
143     void timerCallback() override;
144     void updatePosition (const String&, Point<int>, Rectangle<int>);
145 
146     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TooltipWindow)
147 };
148 
149 } // namespace juce
150