juce_Component.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2015 - ROLI Ltd.
 
   Permission is granted to use this software under the terms of either:
   a) the GPL v2 (or any later version)
   b) the Affero GPL v3
 
   Details of these licenses can be found at: www.gnu.org/licenses
 
   JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 
   ------------------------------------------------------------------------------
 
   To release a closed-source product which uses JUCE, commercial licenses are
   available: visit www.juce.com for more information.
 
  ==============================================================================
*/
 
#ifndef JUCE_COMPONENT_H_INCLUDED
#define JUCE_COMPONENT_H_INCLUDED
 
 
//==============================================================================
class JUCE_API  Component  : public MouseListener
{
public:
    //==============================================================================
    Component() noexcept;
 
    virtual ~Component();
 
    //==============================================================================
    explicit Component (const String& componentName) noexcept;
 
    const String& getName() const noexcept                  { return componentName; }
 
    virtual void setName (const String& newName);
 
    const 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 shouldAlsoGainFocus);
 
    void toBack();
 
    void toBehind (Component* other);
 
    void setAlwaysOnTop (bool shouldStayOnTop);
 
    bool isAlwaysOnTop() const noexcept;
 
    //==============================================================================
    int getX() const noexcept                               { return bounds.getX(); }
 
    int getY() const noexcept                               { return bounds.getY(); }
 
    int getWidth() const noexcept                           { return bounds.getWidth(); }
 
    int getHeight() const noexcept                          { return bounds.getHeight(); }
 
    int getRight() const noexcept                           { return bounds.getRight(); }
 
    Point<int> getPosition() const noexcept                 { return bounds.getPosition(); }
 
    int getBottom() const noexcept                          { return bounds.getBottom(); }
 
    const Rectangle<int>& getBounds() const noexcept        { return bounds; }
 
    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,
                                 const Rectangle<int>& areaRelativeToSourceComponent) const;
 
    Point<int> localPointToGlobal (Point<int> localPoint) const;
 
    Point<float> localPointToGlobal (Point<float> localPoint) const;
 
    Rectangle<int> localAreaToGlobal (const Rectangle<int>& 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 (const Rectangle<int>& newBounds);
 
    void setBounds (const RelativeRectangle& newBounds);
 
    void setBounds (const String& newBoundsExpression);
 
    void setBoundsRelative (float proportionalX, float proportionalY,
                            float proportionalWidth, float proportionalHeight);
 
    void setBoundsInset (const BorderSize<int>& borders);
 
    void setBoundsToFit (int x, int y, int width, int height,
                         Justification justification,
                         bool onlyReduceInSize);
 
    void setCentrePosition (int x, int y);
 
    void setCentreRelative (float x, float y);
 
    void centreWithSize (int width, int height);
 
    //==============================================================================
    void setTransform (const AffineTransform& transform);
 
    AffineTransform getTransform() const;
 
    bool isTransformed() const noexcept;
 
    //==============================================================================
    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;
 
    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 (Component* p = parentComponent; p != nullptr; p = p->parentComponent)
            if (TargetClass* const 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 reallyContains (Point<int> localPoint, bool returnTrueIfWithinAChild);
 
    Component* getComponentAt (int x, int y);
 
    Component* getComponentAt (Point<int> position);
 
    //==============================================================================
    void repaint();
 
    void repaint (int x, int y, int width, int height);
 
    void repaint (const Rectangle<int>& area);
 
    //==============================================================================
    void setBufferedToImage (bool shouldBeBuffered);
 
    Image createComponentSnapshot (const Rectangle<int>& areaToGrab,
                                   bool clipImageToComponentBounds = true,
                                   float scaleFactor = 1.0f);
 
    void paintEntireComponent (Graphics& context, bool ignoreAlphaLevel);
 
    void setPaintingIsUnclipped (bool shouldPaintWithoutClipping) 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;
 
    //==============================================================================
    // Keyboard focus methods
 
    void setWantsKeyboardFocus (bool wantsFocus) noexcept;
 
    bool getWantsKeyboardFocus() const noexcept;
 
    //==============================================================================
    void setMouseClickGrabsKeyboardFocus (bool shouldGrabFocus);
 
    bool getMouseClickGrabsKeyboardFocus() const noexcept;
 
    //==============================================================================
    void grabKeyboardFocus();
 
    bool hasKeyboardFocus (bool trueIfChildIsFocused) const;
 
    static Component* JUCE_CALLTYPE getCurrentlyFocusedComponent() noexcept;
 
    static void JUCE_CALLTYPE unfocusAllComponents();
 
    //==============================================================================
    void moveKeyboardFocusToSibling (bool moveToNext);
 
    virtual KeyboardFocusTraverser* createFocusTraverser();
 
    int getExplicitFocusOrder() const;
 
    void setExplicitFocusOrder (int newFocusOrderIndex);
 
    void setFocusContainer (bool shouldBeFocusContainer) noexcept;
 
    bool isFocusContainer() const noexcept;
 
    //==============================================================================
    bool isEnabled() const noexcept;
 
    void setEnabled (bool shouldBeEnabled);
 
    virtual void enablementChanged();
 
    void setAlpha (float newAlpha);
 
    float getAlpha() const;
 
    //==============================================================================
    void setMouseCursor (const MouseCursor& cursorType);
 
    virtual MouseCursor getMouseCursor();
 
    void updateMouseCursor() const;
 
    //==============================================================================
    virtual void paint (Graphics& g);
 
    virtual void paintOverChildren (Graphics& g);
 
 
    //==============================================================================
    virtual void mouseMove (const MouseEvent& event) override;
 
    virtual void mouseEnter (const MouseEvent& event) override;
 
    virtual void mouseExit (const MouseEvent& event) override;
 
    virtual void mouseDown (const MouseEvent& event) override;
 
    virtual void mouseDrag (const MouseEvent& event) override;
 
    virtual void mouseUp (const MouseEvent& event) override;
 
    virtual void mouseDoubleClick (const MouseEvent& event) override;
 
    virtual void mouseWheelMove (const MouseEvent& event,
                                 const MouseWheelDetails& wheel) override;
 
    virtual void mouseMagnify (const MouseEvent& event, float scaleFactor);
 
    //==============================================================================
    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() const;
 
    bool isMouseOverOrDragging() 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() 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();
 
    //==============================================================================
    virtual MarkerList* getMarkers (bool xAxis);
 
    //==============================================================================
    void* getWindowHandle() const;
 
    //==============================================================================
    template <class ComponentType>
    class SafePointer
    {
    public:
        SafePointer() noexcept {}
 
        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->() noexcept                  { return getComponent(); }
 
        const 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() {}
 
        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; }
 
    //==============================================================================
    // These methods are deprecated - use localPointToGlobal, getLocalPoint, getLocalPoint, etc instead.
    JUCE_DEPRECATED (Point<int> relativePositionToGlobal (Point<int>) const);
    JUCE_DEPRECATED (Point<int> globalPositionToRelative (Point<int>) const);
    JUCE_DEPRECATED (Point<int> relativePositionToOtherComponent (const Component*, Point<int>) const);
 
private:
    //==============================================================================
    friend class ComponentPeer;
    friend class MouseInputSource;
    friend class MouseInputSourceInternal;
 
   #ifndef DOXYGEN
    static Component* currentlyFocusedComponent;
 
    //==============================================================================
    String componentName, componentID;
    Component* parentComponent;
    Rectangle<int> bounds;
    ScopedPointer<Positioner> positioner;
    ScopedPointer<AffineTransform> affineTransform;
    Array<Component*> childComponentList;
    LookAndFeel* lookAndFeel;
    MouseCursor cursor;
    ImageEffectFilter* effect;
    ScopedPointer<CachedComponentImage> cachedImage;
 
    class MouseListenerList;
    friend class MouseListenerList;
    friend struct ContainerDeletePolicy<MouseListenerList>;
    ScopedPointer<MouseListenerList> mouseListeners;
    ScopedPointer<Array<KeyListener*> > keyListeners;
    ListenerList<ComponentListener> componentListeners;
    NamedValueSet properties;
 
    friend class WeakReference<Component>;
    WeakReference<Component>::Master masterReference;
 
    struct ComponentFlags
    {
        bool hasHeavyweightPeerFlag     : 1;
        bool visibleFlag                : 1;
        bool opaqueFlag                 : 1;
        bool ignoresMouseClicksFlag     : 1;
        bool allowChildMouseClicksFlag  : 1;
        bool wantsFocusFlag             : 1;
        bool isFocusContainerFlag       : 1;
        bool dontFocusOnMouseClickFlag  : 1;
        bool alwaysOnTopFlag            : 1;
        bool bufferToImageFlag          : 1;
        bool bringToFrontOnClickFlag    : 1;
        bool repaintOnMouseActivityFlag : 1;
        bool currentlyModalFlag         : 1;
        bool isDisabledFlag             : 1;
        bool childCompFocusedFlag       : 1;
        bool dontClipGraphicsFlag       : 1;
        bool mouseDownWasBlocked        : 1;
        bool isMoveCallbackPending      : 1;
        bool isResizeCallbackPending    : 1;
       #if JUCE_DEBUG
        bool isInsidePaintCall          : 1;
       #endif
    };
 
    union
    {
        uint32 componentFlags;
        ComponentFlags flags;
    };
 
    uint8 componentTransparency;
 
    //==============================================================================
    void internalMouseEnter (MouseInputSource, Point<float>, Time);
    void internalMouseExit  (MouseInputSource, Point<float>, Time);
    void internalMouseDown  (MouseInputSource, Point<float>, Time);
    void internalMouseUp    (MouseInputSource, Point<float>, Time, const ModifierKeys oldModifiers);
    void internalMouseDrag  (MouseInputSource, Point<float>, 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 internalFocusGain (FocusChangeType, const WeakReference<Component>&);
    void internalFocusGain (FocusChangeType);
    void internalFocusLoss (FocusChangeType);
    void internalChildFocusChange (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 (const FocusChangeType);
    void grabFocusInternal (const FocusChangeType, bool canTryParent);
    static void giveAwayFocus (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)
 
    //==============================================================================
   #if JUCE_CATCH_DEPRECATED_CODE_MISUSE
    // This is included here just to cause a compile error if your code is still handling
    // drag-and-drop with this method. If so, just update it to use the new FileDragAndDropTarget
    // class, which is easy (just make your class inherit from FileDragAndDropTarget, and
    // implement its methods instead of this Component method).
    virtual void filesDropped (const StringArray&, int, int) {}
 
    // This is included here to cause an error if you use or overload it - it has been deprecated in
    // favour of contains (Point<int>)
    void contains (int, int) JUCE_DELETED_FUNCTION;
   #endif
 
protected:
    //==============================================================================
    virtual ComponentPeer* createNewPeer (int styleFlags, void* nativeWindowToAttachTo);
   #endif
};
 
 
#endif   // JUCE_COMPONENT_H_INCLUDED