juce_Component.h

Go to the documentation of this file.

 /*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  Component  : public MouseListener
{
public:
    //==============================================================================
    Component() noexcept;
 
    ~Component() override;
 
    //==============================================================================
    explicit Component (const String& componentName) noexcept;
 
    String getName() const noexcept                  { return componentName; }
 
    virtual void setName (const String& newName);
 
    String getComponentID() const noexcept           { return componentID; }
 
    void setComponentID (const String& newID);
 
    //==============================================================================
    virtual void setVisible (bool shouldBeVisible);
 
    bool isVisible() const noexcept                         { return flags.visibleFlag; }
 
    virtual void visibilityChanged();
 
    bool isShowing() const;
 
    //==============================================================================
    virtual void addToDesktop (int windowStyleFlags,
                               void* nativeWindowToAttachTo = nullptr);
 
    void removeFromDesktop();
 
    bool isOnDesktop() const noexcept;
 
    ComponentPeer* getPeer() const;
 
    virtual void userTriedToCloseWindow();
 
    virtual void minimisationStateChanged (bool isNowMinimised);
 
    virtual float getDesktopScaleFactor() const;
 
    //==============================================================================
    void toFront (bool shouldAlsoGainKeyboardFocus);
 
    void toBack();
 
    void toBehind (Component* other);
 
    void setAlwaysOnTop (bool shouldStayOnTop);
 
    bool isAlwaysOnTop() const noexcept;
 
    //==============================================================================
    int getX() const noexcept                               { return boundsRelativeToParent.getX(); }
 
    int getY() const noexcept                               { return boundsRelativeToParent.getY(); }
 
    int getWidth() const noexcept                           { return boundsRelativeToParent.getWidth(); }
 
    int getHeight() const noexcept                          { return boundsRelativeToParent.getHeight(); }
 
    int getRight() const noexcept                           { return boundsRelativeToParent.getRight(); }
 
    Point<int> getPosition() const noexcept                 { return boundsRelativeToParent.getPosition(); }
 
    int getBottom() const noexcept                          { return boundsRelativeToParent.getBottom(); }
 
    Rectangle<int> getBounds() const noexcept               { return boundsRelativeToParent; }
 
    Rectangle<int> getLocalBounds() const noexcept;
 
    Rectangle<int> getBoundsInParent() const noexcept;
 
    //==============================================================================
    int getScreenX() const;
 
    int getScreenY() const;
 
    Point<int> getScreenPosition() const;
 
    Rectangle<int> getScreenBounds() const;
 
    Point<int> getLocalPoint (const Component* sourceComponent,
                              Point<int> pointRelativeToSourceComponent) const;
 
    Point<float> getLocalPoint (const Component* sourceComponent,
                                Point<float> pointRelativeToSourceComponent) const;
 
    Rectangle<int> getLocalArea (const Component* sourceComponent,
                                 Rectangle<int> areaRelativeToSourceComponent) const;
 
    Rectangle<float> getLocalArea (const Component* sourceComponent,
                                   Rectangle<float> areaRelativeToSourceComponent) const;
 
    Point<int> localPointToGlobal (Point<int> localPoint) const;
 
    Point<float> localPointToGlobal (Point<float> localPoint) const;
 
    Rectangle<int> localAreaToGlobal (Rectangle<int> localArea) const;
 
    Rectangle<float> localAreaToGlobal (Rectangle<float> localArea) const;
 
    //==============================================================================
    void setTopLeftPosition (int x, int y);
 
    void setTopLeftPosition (Point<int> newTopLeftPosition);
 
    void setTopRightPosition (int x, int y);
 
    void setSize (int newWidth, int newHeight);
 
    void setBounds (int x, int y, int width, int height);
 
    void setBounds (Rectangle<int> newBounds);
 
    void setBoundsRelative (float proportionalX, float proportionalY,
                            float proportionalWidth, float proportionalHeight);
 
    void setBoundsRelative (Rectangle<float> proportionalArea);
 
    void setBoundsInset (BorderSize<int> borders);
 
    void setBoundsToFit (Rectangle<int> targetArea,
                         Justification justification,
                         bool onlyReduceInSize);
 
    void setCentrePosition (int x, int y);
 
    void setCentrePosition (Point<int> newCentrePosition);
 
    void setCentreRelative (float x, float y);
 
    void centreWithSize (int width, int height);
 
    //==============================================================================
    void setTransform (const AffineTransform& transform);
 
    AffineTransform getTransform() const;
 
    bool isTransformed() const noexcept;
 
    static float JUCE_CALLTYPE getApproximateScaleFactorForComponent (const Component* targetComponent);
 
    //==============================================================================
    int proportionOfWidth (float proportion) const noexcept;
 
    int proportionOfHeight (float proportion) const noexcept;
 
    int getParentWidth() const noexcept;
 
    int getParentHeight() const noexcept;
 
    Rectangle<int> getParentMonitorArea() const;
 
    //==============================================================================
    int getNumChildComponents() const noexcept;
 
    Component* getChildComponent (int index) const noexcept;
 
    int getIndexOfChildComponent (const Component* child) const noexcept;
 
    const Array<Component*>& getChildren() const noexcept          { return childComponentList; }
 
    Component* findChildWithID (StringRef componentID) const noexcept;
 
    void addChildComponent (Component* child, int zOrder = -1);
 
    void addChildComponent (Component& child, int zOrder = -1);
 
    void addAndMakeVisible (Component* child, int zOrder = -1);
 
    void addAndMakeVisible (Component& child, int zOrder = -1);
 
    void addChildAndSetID (Component* child, const String& componentID);
 
    void removeChildComponent (Component* childToRemove);
 
    Component* removeChildComponent (int childIndexToRemove);
 
    void removeAllChildren();
 
    void deleteAllChildren();
 
    Component* getParentComponent() const noexcept                  { return parentComponent; }
 
    template <class TargetClass>
    TargetClass* findParentComponentOfClass() const
    {
        for (auto* p = parentComponent; p != nullptr; p = p->parentComponent)
            if (auto* target = dynamic_cast<TargetClass*> (p))
                return target;
 
        return nullptr;
    }
 
    Component* getTopLevelComponent() const noexcept;
 
    bool isParentOf (const Component* possibleChild) const noexcept;
 
    //==============================================================================
    virtual void parentHierarchyChanged();
 
    virtual void childrenChanged();
 
    //==============================================================================
    virtual bool hitTest (int x, int y);
 
    void setInterceptsMouseClicks (bool allowClicksOnThisComponent,
                                   bool allowClicksOnChildComponents) noexcept;
 
    void getInterceptsMouseClicks (bool& allowsClicksOnThisComponent,
                                   bool& allowsClicksOnChildComponents) const noexcept;
 
 
    bool contains (Point<int> localPoint);
 
    bool contains (Point<float> localPoint);
 
    bool reallyContains (Point<int> localPoint, bool returnTrueIfWithinAChild);
 
    bool reallyContains (Point<float> localPoint, bool returnTrueIfWithinAChild);
 
    Component* getComponentAt (int x, int y);
 
    Component* getComponentAt (Point<int> position);
 
    Component* getComponentAt (Point<float> position);
 
    //==============================================================================
    void repaint();
 
    void repaint (int x, int y, int width, int height);
 
    void repaint (Rectangle<int> area);
 
    //==============================================================================
    void setBufferedToImage (bool shouldBeBuffered);
 
    Image createComponentSnapshot (Rectangle<int> areaToGrab,
                                   bool clipImageToComponentBounds = true,
                                   float scaleFactor = 1.0f);
 
    void paintEntireComponent (Graphics& context, bool ignoreAlphaLevel);
 
    void setPaintingIsUnclipped (bool shouldPaintWithoutClipping) noexcept;
 
    bool isPaintingUnclipped() const noexcept;
 
    //==============================================================================
    void setComponentEffect (ImageEffectFilter* newEffect);
 
    ImageEffectFilter* getComponentEffect() const noexcept              { return effect; }
 
    //==============================================================================
    LookAndFeel& getLookAndFeel() const noexcept;
 
    void setLookAndFeel (LookAndFeel* newLookAndFeel);
 
    virtual void lookAndFeelChanged();
 
    void sendLookAndFeelChange();
 
    //==============================================================================
    void setOpaque (bool shouldBeOpaque);
 
    bool isOpaque() const noexcept;
 
    //==============================================================================
    void setBroughtToFrontOnMouseClick (bool shouldBeBroughtToFront) noexcept;
 
    bool isBroughtToFrontOnMouseClick() const noexcept;
 
    //==============================================================================
    // Focus methods
 
    void setExplicitFocusOrder (int newFocusOrderIndex);
 
    int getExplicitFocusOrder() const;
 
    enum class FocusContainerType
    {
        none,
 
        focusContainer,
 
        keyboardFocusContainer
    };
 
    void setFocusContainerType (FocusContainerType containerType) noexcept;
 
    bool isFocusContainer() const noexcept;
 
    bool isKeyboardFocusContainer() const noexcept;
 
    Component* findFocusContainer() const;
 
    Component* findKeyboardFocusContainer() const;
 
    //==============================================================================
    void setWantsKeyboardFocus (bool wantsFocus) noexcept;
 
    bool getWantsKeyboardFocus() const noexcept;
 
    void setMouseClickGrabsKeyboardFocus (bool shouldGrabFocus);
 
    bool getMouseClickGrabsKeyboardFocus() const noexcept;
 
    void grabKeyboardFocus();
 
    void giveAwayKeyboardFocus();
 
    bool hasKeyboardFocus (bool trueIfChildIsFocused) const;
 
    void moveKeyboardFocusToSibling (bool moveToNext);
 
    static Component* JUCE_CALLTYPE getCurrentlyFocusedComponent() noexcept;
 
    static void JUCE_CALLTYPE unfocusAllComponents();
 
    //==============================================================================
    virtual std::unique_ptr<ComponentTraverser> createFocusTraverser();
 
    virtual std::unique_ptr<ComponentTraverser> createKeyboardFocusTraverser();
 
    void setHasFocusOutline (bool hasFocusOutline) noexcept  { flags.hasFocusOutlineFlag = hasFocusOutline; }
 
    bool hasFocusOutline() const noexcept                    { return flags.hasFocusOutlineFlag; }
 
    //==============================================================================
    bool isEnabled() const noexcept;
 
    void setEnabled (bool shouldBeEnabled);
 
    virtual void enablementChanged();
 
    //==============================================================================
    float getAlpha() const noexcept;
 
    void setAlpha (float newAlpha);
 
    virtual void alphaChanged();
 
    //==============================================================================
    void setMouseCursor (const MouseCursor& cursorType);
 
    virtual MouseCursor getMouseCursor();
 
    void updateMouseCursor() const;
 
    //==============================================================================
    virtual void paint (Graphics& g);
 
    virtual void paintOverChildren (Graphics& g);
 
 
    //==============================================================================
    void mouseMove (const MouseEvent& event) override;
 
    void mouseEnter (const MouseEvent& event) override;
 
    void mouseExit (const MouseEvent& event) override;
 
    void mouseDown (const MouseEvent& event) override;
 
    void mouseDrag (const MouseEvent& event) override;
 
    void mouseUp (const MouseEvent& event) override;
 
    void mouseDoubleClick (const MouseEvent& event) override;
 
    void mouseWheelMove (const MouseEvent& event,
                         const MouseWheelDetails& wheel) override;
 
    void mouseMagnify (const MouseEvent& event, float scaleFactor) override;
 
    //==============================================================================
    static void JUCE_CALLTYPE beginDragAutoRepeat (int millisecondsBetweenCallbacks);
 
    void setRepaintsOnMouseActivity (bool shouldRepaint) noexcept;
 
    void addMouseListener (MouseListener* newListener,
                           bool wantsEventsForAllNestedChildComponents);
 
    void removeMouseListener (MouseListener* listenerToRemove);
 
    //==============================================================================
    void addKeyListener (KeyListener* newListener);
 
    void removeKeyListener (KeyListener* listenerToRemove);
 
    virtual bool keyPressed (const KeyPress& key);
 
    virtual bool keyStateChanged (bool isKeyDown);
 
    virtual void modifierKeysChanged (const ModifierKeys& modifiers);
 
    //==============================================================================
    enum FocusChangeType
    {
        focusChangedByMouseClick,   
        focusChangedByTabKey,       
        focusChangedDirectly        
    };
 
    enum class FocusChangeDirection
    {
        unknown,
        forward,
        backward
    };
 
    virtual void focusGained (FocusChangeType cause);
 
    virtual void focusGainedWithDirection (FocusChangeType cause, FocusChangeDirection direction);
 
    virtual void focusLost (FocusChangeType cause);
 
    virtual void focusOfChildComponentChanged (FocusChangeType cause);
 
    //==============================================================================
    bool isMouseOver (bool includeChildren = false) const;
 
    bool isMouseButtonDown (bool includeChildren = false) const;
 
    bool isMouseOverOrDragging (bool includeChildren = false) const;
 
    static bool JUCE_CALLTYPE isMouseButtonDownAnywhere() noexcept;
 
    Point<int> getMouseXYRelative() const;
 
    //==============================================================================
    virtual void resized();
 
    virtual void moved();
 
    virtual void childBoundsChanged (Component* child);
 
    virtual void parentSizeChanged();
 
    virtual void broughtToFront();
 
    void addComponentListener (ComponentListener* newListener);
 
    void removeComponentListener (ComponentListener* listenerToRemove);
 
    //==============================================================================
    void postCommandMessage (int commandId);
 
    virtual void handleCommandMessage (int commandId);
 
    //==============================================================================
   #if JUCE_MODAL_LOOPS_PERMITTED
    int runModalLoop();
   #endif
 
    void enterModalState (bool takeKeyboardFocus = true,
                          ModalComponentManager::Callback* callback = nullptr,
                          bool deleteWhenDismissed = false);
 
    void exitModalState (int returnValue = 0);
 
    bool isCurrentlyModal (bool onlyConsiderForemostModalComponent = true) const noexcept;
 
    static int JUCE_CALLTYPE getNumCurrentlyModalComponents() noexcept;
 
    static Component* JUCE_CALLTYPE getCurrentlyModalComponent (int index = 0) noexcept;
 
    bool isCurrentlyBlockedByAnotherModalComponent() const;
 
    virtual bool canModalEventBeSentToComponent (const Component* targetComponent);
 
    virtual void inputAttemptWhenModal();
 
 
    //==============================================================================
    NamedValueSet& getProperties() noexcept                             { return properties; }
 
    const NamedValueSet& getProperties() const noexcept                 { return properties; }
 
    //==============================================================================
    Colour findColour (int colourID, bool inheritFromParent = false) const;
 
    void setColour (int colourID, Colour newColour);
 
    void removeColour (int colourID);
 
    bool isColourSpecified (int colourID) const;
 
    void copyAllExplicitColoursTo (Component& target) const;
 
    virtual void colourChanged();
 
    //==============================================================================
    void* getWindowHandle() const;
 
    //==============================================================================
    template <class ComponentType>
    class SafePointer
    {
    public:
        SafePointer() = default;
 
        SafePointer (ComponentType* component)                : weakRef (component) {}
 
        SafePointer (const SafePointer& other) noexcept       : weakRef (other.weakRef) {}
 
        SafePointer& operator= (const SafePointer& other)     { weakRef = other.weakRef; return *this; }
 
        SafePointer& operator= (ComponentType* newComponent)  { weakRef = newComponent; return *this; }
 
        ComponentType* getComponent() const noexcept          { return dynamic_cast<ComponentType*> (weakRef.get()); }
 
        operator ComponentType*() const noexcept              { return getComponent(); }
 
        ComponentType* operator->() const noexcept            { return getComponent(); }
 
        void deleteAndZero()                                  { delete getComponent(); }
 
        bool operator== (ComponentType* component) const noexcept   { return weakRef == component; }
        bool operator!= (ComponentType* component) const noexcept   { return weakRef != component; }
 
    private:
        WeakReference<Component> weakRef;
    };
 
    //==============================================================================
    class JUCE_API  BailOutChecker
    {
    public:
        BailOutChecker (Component* component);
 
        bool shouldBailOut() const noexcept;
 
    private:
        const WeakReference<Component> safePointer;
 
        JUCE_DECLARE_NON_COPYABLE (BailOutChecker)
    };
 
    //==============================================================================
    class JUCE_API  Positioner
    {
    public:
        explicit Positioner (Component& component) noexcept;
        virtual ~Positioner() = default;
 
        Component& getComponent() const noexcept    { return component; }
 
        virtual void applyNewBounds (const Rectangle<int>& newBounds) = 0;
 
    private:
        Component& component;
 
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Positioner)
    };
 
    Positioner* getPositioner() const noexcept;
 
    void setPositioner (Positioner* newPositioner);
 
    void setCachedComponentImage (CachedComponentImage* newCachedImage);
 
    CachedComponentImage* getCachedComponentImage() const noexcept      { return cachedImage.get(); }
 
    void setViewportIgnoreDragFlag (bool ignoreDrag) noexcept           { flags.viewportIgnoreDragFlag = ignoreDrag; }
 
    bool getViewportIgnoreDragFlag() const noexcept                     { return flags.viewportIgnoreDragFlag; }
 
    //==============================================================================
    String getTitle() const noexcept  { return componentTitle; }
 
    void setTitle (const String& newTitle);
 
    String getDescription() const noexcept  { return componentDescription; }
 
    void setDescription (const String& newDescription);
 
    String getHelpText() const noexcept    { return componentHelpText; }
 
    void setHelpText (const String& newHelpText);
 
    void setAccessible (bool shouldBeAccessible);
 
    bool isAccessible() const noexcept;
 
    AccessibilityHandler* getAccessibilityHandler();
 
    void invalidateAccessibilityHandler();
 
    //==============================================================================
    virtual std::unique_ptr<AccessibilityHandler> createAccessibilityHandler();
 
    //==============================================================================
   #ifndef DOXYGEN
    [[deprecated ("Use the setFocusContainerType that takes a more descriptive enum.")]]
    void setFocusContainer (bool shouldBeFocusContainer) noexcept
    {
        setFocusContainerType (shouldBeFocusContainer ? FocusContainerType::keyboardFocusContainer
                                                      : FocusContainerType::none);
    }
 
    [[deprecated ("Use the contains that takes a Point<int>.")]]
    void contains (int, int) = delete;
   #endif
 
private:
 
    //==============================================================================
    friend class ComponentPeer;
    friend class detail::MouseInputSourceImpl;
 
   #ifndef DOXYGEN
    static Component* currentlyFocusedComponent;
 
    //==============================================================================
    String componentName, componentID, componentTitle, componentDescription, componentHelpText;
    Component* parentComponent = nullptr;
    Rectangle<int> boundsRelativeToParent;
    std::unique_ptr<Positioner> positioner;
    std::unique_ptr<AffineTransform> affineTransform;
    Array<Component*> childComponentList;
    WeakReference<LookAndFeel> lookAndFeel;
    MouseCursor cursor;
    ImageEffectFilter* effect = nullptr;
    std::unique_ptr<CachedComponentImage> cachedImage;
 
    class MouseListenerList;
    std::unique_ptr<MouseListenerList> mouseListeners;
    std::unique_ptr<Array<KeyListener*>> keyListeners;
    ListenerList<ComponentListener> componentListeners;
    NamedValueSet properties;
 
    friend class WeakReference<Component>;
    WeakReference<Component>::Master masterReference;
 
    std::unique_ptr<AccessibilityHandler> accessibilityHandler;
 
    struct ComponentFlags
    {
        bool hasHeavyweightPeerFlag       : 1;
        bool visibleFlag                  : 1;
        bool opaqueFlag                   : 1;
        bool ignoresMouseClicksFlag       : 1;
        bool allowChildMouseClicksFlag    : 1;
        bool wantsKeyboardFocusFlag       : 1;
        bool isFocusContainerFlag         : 1;
        bool isKeyboardFocusContainerFlag : 1;
        bool childKeyboardFocusedFlag     : 1;
        bool dontFocusOnMouseClickFlag    : 1;
        bool hasFocusOutlineFlag          : 1;
        bool alwaysOnTopFlag              : 1;
        bool bufferToImageFlag            : 1;
        bool bringToFrontOnClickFlag      : 1;
        bool repaintOnMouseActivityFlag   : 1;
        bool isDisabledFlag               : 1;
        bool dontClipGraphicsFlag         : 1;
        bool mouseDownWasBlocked          : 1;
        bool isMoveCallbackPending        : 1;
        bool isResizeCallbackPending      : 1;
        bool viewportIgnoreDragFlag       : 1;
        bool accessibilityIgnoredFlag     : 1;
        bool cachedMouseInsideComponent   : 1;
       #if JUCE_DEBUG
        bool isInsidePaintCall            : 1;
       #endif
    };
 
    union
    {
        uint32 componentFlags;
        ComponentFlags flags;
    };
 
    uint8 componentTransparency = 0;
 
    //==============================================================================
    void internalMouseEnter (MouseInputSource, Point<float>, Time);
    void internalMouseExit  (MouseInputSource, Point<float>, Time);
    void internalMouseDown  (MouseInputSource, const detail::PointerState&, Time);
    void internalMouseUp    (MouseInputSource, const detail::PointerState&, Time, ModifierKeys oldModifiers);
    void internalMouseDrag  (MouseInputSource, const detail::PointerState&, Time);
    void internalMouseMove  (MouseInputSource, Point<float>, Time);
    void internalMouseWheel (MouseInputSource, Point<float>, Time, const MouseWheelDetails&);
    void internalMagnifyGesture (MouseInputSource, Point<float>, Time, float);
    void internalBroughtToFront();
    void internalKeyboardFocusGain (FocusChangeType, const WeakReference<Component>&, FocusChangeDirection);
    void internalKeyboardFocusGain (FocusChangeType);
    void internalKeyboardFocusLoss (FocusChangeType);
    void internalChildKeyboardFocusChange (FocusChangeType, const WeakReference<Component>&);
    void internalModalInputAttempt();
    void internalModifierKeysChanged();
    void internalChildrenChanged();
    void internalHierarchyChanged();
    void internalRepaint (Rectangle<int>);
    void internalRepaintUnchecked (Rectangle<int>, bool);
    Component* removeChildComponent (int index, bool sendParentEvents, bool sendChildEvents);
    void reorderChildInternal (int sourceIndex, int destIndex);
    void paintComponentAndChildren (Graphics&);
    void paintWithinParentContext (Graphics&);
    void sendMovedResizedMessages (bool wasMoved, bool wasResized);
    void sendMovedResizedMessagesIfPending();
    void repaintParent();
    void sendFakeMouseMove() const;
    void takeKeyboardFocus (FocusChangeType, FocusChangeDirection);
    void grabKeyboardFocusInternal (FocusChangeType, bool canTryParent, FocusChangeDirection);
    void giveAwayKeyboardFocusInternal (bool sendFocusLossEvent);
    void sendEnablementChangeMessage();
    void sendVisibilityChangeMessage();
 
    friend struct detail::ComponentHelpers;
 
    /* Components aren't allowed to have copy constructors, as this would mess up parent hierarchies.
       You might need to give your subclasses a private dummy constructor to avoid compiler warnings.
    */
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Component)
 
protected:
    //==============================================================================
    virtual ComponentPeer* createNewPeer (int styleFlags, void* nativeWindowToAttachTo);
    static std::unique_ptr<AccessibilityHandler> createIgnoredAccessibilityHandler (Component&);
   #endif
};
 
} // namespace juce