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        
    };

    virtual void focusGained (FocusChangeType cause);

    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);

    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();
 
    //==============================================================================
   #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:
    //==============================================================================
    virtual std::unique_ptr<AccessibilityHandler> createAccessibilityHandler();
 
    //==============================================================================
    friend class ComponentPeer;
    friend class MouseInputSourceInternal;
 
   #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 PointerState&, Time);
    void internalMouseUp    (MouseInputSource, const PointerState&, Time, const ModifierKeys oldModifiers);
    void internalMouseDrag  (MouseInputSource, const 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>&);
    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);
    void grabKeyboardFocusInternal (FocusChangeType, bool canTryParent);
    void giveAwayKeyboardFocusInternal (bool sendFocusLossEvent);
    void sendEnablementChangeMessage();
    void sendVisibilityChangeMessage();
 
    struct ComponentHelpers;
    friend struct 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