juce_Component.h

Go to the documentation of this file.

/*
  ==============================================================================

   This file is part of the JUCE library - "Jules' Utility Class Extensions"
   Copyright 2004-7 by Raw Material Software ltd.

  ------------------------------------------------------------------------------

   JUCE can be redistributed and/or modified under the terms of the
   GNU General Public License, as published by the Free Software Foundation;
   either version 2 of the License, or (at your option) any later version.

   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.

   You should have received a copy of the GNU General Public License
   along with JUCE; if not, visit www.gnu.org/licenses or write to the
   Free Software Foundation, Inc., 59 Temple Place, Suite 330,
   Boston, MA 02111-1307 USA

  ------------------------------------------------------------------------------

   If you'd like to release a closed-source product which uses JUCE, commercial
   licenses are also available: visit www.rawmaterialsoftware.com/juce for
   more information.

  ==============================================================================
*/

#ifndef __JUCE_COMPONENT_JUCEHEADER__
#define __JUCE_COMPONENT_JUCEHEADER__

#include "mouse/juce_MouseCursor.h"
#include "mouse/juce_MouseListener.h"
#include "juce_ComponentListener.h"
#include "keyboard/juce_KeyListener.h"
#include "keyboard/juce_KeyboardFocusTraverser.h"
#include "../graphics/effects/juce_ImageEffectFilter.h"
#include "../graphics/geometry/juce_RectangleList.h"
#include "../graphics/geometry/juce_BorderSize.h"
#include "windows/juce_ComponentPeer.h"
#include "../../events/juce_MessageListener.h"
#include "../../../juce_core/text/juce_StringArray.h"
#include "../../../juce_core/containers/juce_VoidArray.h"
#include "../../../juce_core/containers/juce_PropertySet.h"
class LookAndFeel;


//==============================================================================
class JUCE_API  Component  : public MouseListener,
                             protected MessageListener
{
public:
    //==============================================================================
    Component() throw();

    virtual ~Component();

    //==============================================================================
    Component (const String& componentName) throw();

    const String& getName() const throw()                   { return componentName_; }

    virtual void setName (const String& newName);

    //==============================================================================
    bool isValidComponent() const throw();

    //==============================================================================
    virtual void setVisible (bool shouldBeVisible);

    bool isVisible() const throw()                          { return flags.visibleFlag; }

    virtual void visibilityChanged();

    bool isShowing() const throw();

    void fadeOutComponent (const int lengthOfFadeOutInMilliseconds,
                           const int deltaXToMove = 0,
                           const int deltaYToMove = 0,
                           const float scaleFactorAtEnd = 1.0f);

    //==============================================================================
    virtual void addToDesktop (int windowStyleFlags,
                               void* nativeWindowToAttachTo = 0);

    void removeFromDesktop();

    bool isOnDesktop() const throw();

    ComponentPeer* getPeer() const throw();

    virtual void userTriedToCloseWindow();

    virtual void minimisationStateChanged (bool isNowMinimised);

    //==============================================================================
    void toFront (const bool shouldAlsoGainFocus);

    void toBack();

    void toBehind (Component* const other);

    void setAlwaysOnTop (const bool shouldStayOnTop);

    bool isAlwaysOnTop() const throw();

    //==============================================================================
    inline int getX() const throw()                         { return bounds_.getX(); }

    inline int getY() const throw()                         { return bounds_.getY(); }

    inline int getWidth() const throw()                     { return bounds_.getWidth(); }

    inline int getHeight() const throw()                    { return bounds_.getHeight(); }

    int getRight() const throw()                            { return bounds_.getRight(); }

    int getBottom() const throw()                           { return bounds_.getBottom(); }

    const Rectangle& getBounds() const throw()              { return bounds_; }

    void getVisibleArea (RectangleList& result,
                         const bool includeSiblings) const;

    //==============================================================================
    int getScreenX() const throw();

    int getScreenY() const throw();

    void relativePositionToGlobal (int& x, int& y) const throw();

    void globalPositionToRelative (int& x, int& y) const throw();

    void relativePositionToOtherComponent (const Component* const targetComponent,
                                           int& x, int& y) const throw();

    //==============================================================================
    void setTopLeftPosition (const int x, const int y);

    void setTopRightPosition (const int x, const int y);

    void setSize (const int newWidth, const int newHeight);

    void setBounds (int x, int y, int width, int height);

    void setBounds (const Rectangle& newBounds);

    void setBoundsRelative (const float proportionalX, const float proportionalY,
                            const float proportionalWidth, const float proportionalHeight);

    void setBoundsInset (const BorderSize& borders);

    void setBoundsToFit (int x, int y, int width, int height,
                         const Justification& justification,
                         const bool onlyReduceInSize);

    void setCentrePosition (const int x, const int y);

    void setCentreRelative (const float x, const float y);

    void centreWithSize (const int width, const int height);

    //==============================================================================
    int proportionOfWidth (const float proportion) const throw();

    int proportionOfHeight (const float proportion) const throw();

    int getParentWidth() const throw();

    int getParentHeight() const throw();

    const Rectangle getParentMonitorArea() const throw();

    //==============================================================================
    int getNumChildComponents() const throw();

    Component* getChildComponent (const int index) const throw();

    int getIndexOfChildComponent (const Component* const child) const throw();

    void addChildComponent (Component* const child,
                            int zOrder = -1);

    void addAndMakeVisible (Component* const child,
                            int zOrder = -1);

    void removeChildComponent (Component* const childToRemove);

    Component* removeChildComponent (const int childIndexToRemove);

    void removeAllChildren();

    void deleteAllChildren();

    Component* getParentComponent() const throw()                   { return parentComponent_; }

    template <class TargetClass>
    TargetClass* findParentComponentOfClass (TargetClass* const dummyParameter = 0) const
    {
        (void) dummyParameter;
        Component* p = parentComponent_;
        while (p != 0)
        {
            TargetClass* target = dynamic_cast <TargetClass*> (p);
            if (target != 0)
                return target;

            p = p->parentComponent_;
        }

        return 0;
    }

    Component* getTopLevelComponent() const throw();

    bool isParentOf (const Component* possibleChild) const throw();

    //==============================================================================
    virtual void parentHierarchyChanged();

    virtual void childrenChanged();

    //==============================================================================
    virtual bool hitTest (int x, int y);

    void setInterceptsMouseClicks (const bool allowClicksOnThisComponent,
                                   const bool allowClicksOnChildComponents) throw();

    void getInterceptsMouseClicks (bool& allowsClicksOnThisComponent,
                                   bool& allowsClicksOnChildComponents) const throw();


    virtual bool contains (int x, int y);

    bool reallyContains (int x, int y,
                         const bool returnTrueIfWithinAChild);

    Component* getComponentAt (const int x, const int y);

    //==============================================================================
    void repaint() throw();

    void repaint (const int x, const int y,
                  const int width, const int height) throw();

    //==============================================================================
    void setBufferedToImage (const bool shouldBeBuffered) throw();

    Image* createComponentSnapshot (const Rectangle& areaToGrab,
                                    const bool clipImageToComponentBounds = true);

    void paintEntireComponent (Graphics& context);


    //==============================================================================
    void setComponentEffect (ImageEffectFilter* const newEffect);

    ImageEffectFilter* getComponentEffect() const throw()               { return effect_; }

    //==============================================================================
    LookAndFeel& getLookAndFeel() const throw();

    void setLookAndFeel (LookAndFeel* const newLookAndFeel);

    virtual void lookAndFeelChanged();

    void sendLookAndFeelChange();

    //==============================================================================
    void setOpaque (const bool shouldBeOpaque) throw();

    bool isOpaque() const throw();

    //==============================================================================
    void setBroughtToFrontOnMouseClick (const bool shouldBeBroughtToFront) throw();

    bool isBroughtToFrontOnMouseClick() const throw();

    //==============================================================================
    // Keyboard focus methods

    void setWantsKeyboardFocus (const bool wantsFocus) throw();

    bool getWantsKeyboardFocus() const throw();

    //==============================================================================
    void setMouseClickGrabsKeyboardFocus (const bool shouldGrabFocus);

    bool getMouseClickGrabsKeyboardFocus() const throw();

    //==============================================================================
    void grabKeyboardFocus();

    bool hasKeyboardFocus (const bool trueIfChildIsFocused) const throw();

    static Component* JUCE_CALLTYPE getCurrentlyFocusedComponent() throw();

    //==============================================================================
    void moveKeyboardFocusToSibling (const bool moveToNext);

    virtual KeyboardFocusTraverser* createFocusTraverser();

    int getExplicitFocusOrder() const throw();

    void setExplicitFocusOrder (const int newFocusOrderIndex) throw();

    void setFocusContainer (const bool isFocusContainer) throw();

    bool isFocusContainer() const throw();

    //==============================================================================
    bool isEnabled() const throw();

    void setEnabled (const bool shouldBeEnabled);

    virtual void enablementChanged();

    //==============================================================================
    void setMouseCursor (const MouseCursor& cursorType) throw();

    virtual const MouseCursor getMouseCursor();

    void updateMouseCursor() const throw();

    //==============================================================================
    virtual void paint (Graphics& g);

    virtual void paintOverChildren (Graphics& g);


    //==============================================================================
    virtual void mouseMove         (const MouseEvent& e);

    virtual void mouseEnter        (const MouseEvent& e);

    virtual void mouseExit         (const MouseEvent& e);

    virtual void mouseDown         (const MouseEvent& e);

    virtual void mouseDrag         (const MouseEvent& e);

    virtual void mouseUp           (const MouseEvent& e);

    virtual void mouseDoubleClick  (const MouseEvent& e);

    virtual void mouseWheelMove    (const MouseEvent& e,
                                    float wheelIncrementX,
                                    float wheelIncrementY);

    //==============================================================================
    static void beginDragAutoRepeat (const int millisecondIntervalBetweenCallbacks);

    void setRepaintsOnMouseActivity (const bool shouldRepaint) throw();

    void addMouseListener (MouseListener* const newListener,
                           const bool wantsEventsForAllNestedChildComponents) throw();

    void removeMouseListener (MouseListener* const listenerToRemove) throw();

    //==============================================================================
    void addKeyListener (KeyListener* const newListener) throw();

    void removeKeyListener (KeyListener* const listenerToRemove) throw();

    virtual bool keyPressed (const KeyPress& key);

    virtual bool keyStateChanged();

    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() const throw();

    bool isMouseButtonDown() const throw();

    bool isMouseOverOrDragging() const throw();

    static bool JUCE_CALLTYPE isMouseButtonDownAnywhere() throw();

    void getMouseXYRelative (int& x, int& y) const throw();

    static Component* JUCE_CALLTYPE getComponentUnderMouse() throw();

    void enableUnboundedMouseMovement (bool shouldUnboundedMovementBeEnabled,
                                       bool keepCursorVisibleUntilOffscreen = false) throw();

    //==============================================================================
    virtual void resized();

    virtual void moved();

    virtual void childBoundsChanged (Component* child);

    virtual void parentSizeChanged();

    virtual void broughtToFront();

    void addComponentListener (ComponentListener* const newListener) throw();

    void removeComponentListener (ComponentListener* const listenerToRemove) throw();

    //==============================================================================
    void postCommandMessage (const int commandId) throw();

    virtual void handleCommandMessage (int commandId);

    //==============================================================================
    int runModalLoop();

    void enterModalState (const bool takeKeyboardFocus = true);

    void exitModalState (const int returnValue);

    bool isCurrentlyModal() const throw();

    static Component* JUCE_CALLTYPE getCurrentlyModalComponent() throw();

    bool isCurrentlyBlockedByAnotherModalComponent() const throw();

    virtual bool canModalEventBeSentToComponent (const Component* targetComponent);

    virtual void inputAttemptWhenModal();


    //==============================================================================
    const String getComponentProperty (const String& keyName,
                                       const bool useParentComponentIfNotFound,
                                       const String& defaultReturnValue = String::empty) const throw();

    int getComponentPropertyInt (const String& keyName,
                                 const bool useParentComponentIfNotFound,
                                 const int defaultReturnValue = 0) const throw();

    double getComponentPropertyDouble (const String& keyName,
                                       const bool useParentComponentIfNotFound,
                                       const double defaultReturnValue = 0.0) const throw();

    bool getComponentPropertyBool (const String& keyName,
                                   const bool useParentComponentIfNotFound,
                                   const bool defaultReturnValue = false) const throw();

    const Colour getComponentPropertyColour (const String& keyName,
                                             const bool useParentComponentIfNotFound,
                                             const Colour& defaultReturnValue = Colours::black) const throw();

    void setComponentProperty (const String& keyName, const String& value) throw();

    void setComponentProperty (const String& keyName, const int value) throw();

    void setComponentProperty (const String& keyName, const double value) throw();

    void setComponentProperty (const String& keyName, const bool value) throw();

    void setComponentProperty (const String& keyName, const Colour& newColour) throw();

    void removeComponentProperty (const String& keyName) throw();

    PropertySet* getComponentProperties() const throw()           { return propertySet_; }

    //==============================================================================
    const Colour findColour (const int colourId, const bool inheritFromParent = false) const throw();

    void setColour (const int colourId, const Colour& colour);

    void removeColour (const int colourId);

    bool isColourSpecified (const int colourId) const throw();

    void copyAllExplicitColoursTo (Component& target) const throw();

    virtual void colourChanged();

    //==============================================================================
    void* getWindowHandle() const throw();

    uint32 getComponentUID() const throw()                { return componentUID; }

    //==============================================================================
    juce_UseDebuggingNewOperator

private:
    //==============================================================================
    friend class ComponentPeer;
    friend class InternalDragRepeater;

    static Component* currentlyFocusedComponent;
    static Component* componentUnderMouse;

    //==============================================================================
    String componentName_;
    Component* parentComponent_;
    uint32 componentUID;
    Rectangle bounds_;
    unsigned short numDeepMouseListeners;
    Array <Component*> childComponentList_;
    LookAndFeel* lookAndFeel_;
    MouseCursor cursor_;
    ImageEffectFilter* effect_;
    Image* bufferedImage_;
    VoidArray* mouseListeners_;
    VoidArray* keyListeners_;
    VoidArray* componentListeners_;
    PropertySet* propertySet_;

    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 draggingFlag               : 1;
        bool mouseOverFlag              : 1;
        bool mouseInsideFlag            : 1;
        bool currentlyModalFlag         : 1;
        bool isDisabledFlag             : 1;
        bool childCompFocusedFlag       : 1;
#ifdef JUCE_DEBUG
        bool isInsidePaintCall          : 1;
#endif
    };

    union
    {
        uint32 componentFlags_;
        ComponentFlags flags;
    };

    //==============================================================================
    void internalMouseEnter (int x, int y, const int64 time);
    void internalMouseExit  (int x, int y, const int64 time);
    void internalMouseDown  (int x, int y);
    void internalMouseUp    (const int oldModifiers, int x, int y, const int64 time);
    void internalMouseDrag  (int x, int y, const int64 time);
    void internalMouseMove  (int x, int y, const int64 time);
    void internalMouseWheel (const int intAmountX, const int intAmountY, const int64 time);
    void internalBroughtToFront();
    void internalFocusGain (const FocusChangeType cause);
    void internalFocusLoss (const FocusChangeType cause);
    void internalChildFocusChange (FocusChangeType cause);
    void internalModalInputAttempt();
    void internalModifierKeysChanged();
    void internalChildrenChanged();
    void internalHierarchyChanged();
    void internalUpdateMouseCursor (const bool forcedUpdate) throw();
    void sendMovedResizedMessages (const bool wasMoved, const bool wasResized);
    void repaintParent() throw();
    void sendFakeMouseMove() const;
    void takeKeyboardFocus (const FocusChangeType cause);
    void grabFocusInternal (const FocusChangeType cause, const bool canTryParent = true);
    static void giveAwayFocus();
    void sendEnablementChangeMessage();
    static void* runModalLoopCallback (void*);
    void subtractObscuredRegions (RectangleList& result,
                                  const int deltaX, const int deltaY,
                                  const Rectangle& clipRect,
                                  const Component* const compToAvoid) const throw();
    void clipObscuredRegions (Graphics& g, const Rectangle& clipRect,
                              const int deltaX, const int deltaY) const throw();

    // how much of the component is not off the edges of its parents
    const Rectangle getUnclippedArea() const;
    void sendVisibilityChangeMessage();

    //==============================================================================
    // 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) {}

    // 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 like
    // this one to avoid compiler warnings.
    Component (const Component&);

    const Component& operator= (const Component&);

protected:
    virtual void internalRepaint (int x, int y, int w, int h);

    virtual ComponentPeer* createNewPeer (int styleFlags, void* nativeWindowToAttachTo);

    void handleMessage (const Message&);
};


#endif   // __JUCE_COMPONENT_JUCEHEADER__