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