Viewport Class Reference

A Viewport is used to contain a larger child component, and allows the child to be automatically scrolled around. More...

Inherits Component, ComponentListener, and ScrollBarListener.

List of all members.

Public Member Functions
	Viewport (const String &componentName=String::empty)
	Creates a Viewport.
	~Viewport ()
	Destructor.
void	setViewedComponent (Component *newViewedComponent)
	Sets the component that this viewport will contain and scroll around.
Component *	getViewedComponent () const throw ()
	Returns the component that's currently being used inside the Viewport.
void	setViewPosition (int xPixelsOffset, int yPixelsOffset)
	Changes the position of the viewed component.
void	setViewPositionProportionately (double proportionX, double proportionY)
	Changes the view position as a proportion of the distance it can move.
bool	autoScroll (int mouseX, int mouseY, int distanceFromEdge, int maximumSpeed)
	If the specified position is at the edges of the viewport, this method scrolls the viewport to bring that position nearer to the centre.
int	getViewPositionX () const throw ()
	Returns the position within the child component of the top-left of its visible area.
int	getViewPositionY () const throw ()
	Returns the position within the child component of the top-left of its visible area.
int	getViewWidth () const throw ()
	Returns the width of the visible area of the child component.
int	getViewHeight () const throw ()
	Returns the height of the visible area of the child component.
int	getMaximumVisibleWidth () const throw ()
	Returns the width available within this component for the contents.
int	getMaximumVisibleHeight () const throw ()
	Returns the height available within this component for the contents.
virtual void	visibleAreaChanged (int visibleX, int visibleY, int visibleW, int visibleH)
	Callback method that is called when the visible area changes.
void	setScrollBarsShown (bool showVerticalScrollbarIfNeeded, bool showHorizontalScrollbarIfNeeded)
	Turns scrollbars on or off.
bool	isVerticalScrollBarShown () const throw ()
	True if the vertical scrollbar is enabled.
bool	isHorizontalScrollBarShown () const throw ()
	True if the horizontal scrollbar is enabled.
void	setScrollBarThickness (int thickness)
	Changes the width of the scrollbars.
int	getScrollBarThickness () const throw ()
	Returns the thickness of the scrollbars.
void	setSingleStepSizes (int stepX, int stepY)
	Changes the distance that a single-step click on a scrollbar button will move the viewport.
void	setScrollBarButtonVisibility (bool buttonsVisible)
	Shows or hides the buttons on any scrollbars that are used.
ScrollBar *	getVerticalScrollBar () const throw ()
	Returns a pointer to the scrollbar component being used.
ScrollBar *	getHorizontalScrollBar () const throw ()
	Returns a pointer to the scrollbar component being used.
juce_UseDebuggingNewOperator void	resized ()
void	scrollBarMoved (ScrollBar *scrollBarThatHasMoved, double newRangeStart)
void	mouseWheelMove (const MouseEvent &e, float wheelIncrementX, float wheelIncrementY)
bool	keyPressed (const KeyPress &key)
void	componentMovedOrResized (Component &component, bool wasMoved, bool wasResized)
bool	useMouseWheelMoveIfNeeded (const MouseEvent &e, float wheelIncrementX, float wheelIncrementY)

---

Detailed Description

A Viewport is used to contain a larger child component, and allows the child to be automatically scrolled around.

To use a Viewport, just create one and set the component that goes inside it using the setViewedComponent() method. When the child component changes size, the Viewport will adjust its scrollbars accordingly.

A subclass of the viewport can be created which will receive calls to its visibleAreaChanged() method when the subcomponent changes position or size.

---

Constructor & Destructor Documentation

Viewport::Viewport

(

const String &

componentName = String::empty

)

[explicit]

Creates a Viewport.

The viewport is initially empty - use the setViewedComponent() method to add a child component for it to manage.

Viewport::~Viewport

(

)

Destructor.

---

Member Function Documentation

void Viewport::setViewedComponent

(

Component *

newViewedComponent

)

Sets the component that this viewport will contain and scroll around.

This will add the given component to this Viewport and position it at (0, 0).

(Don't add or remove any child components directly using the normal Component::addChildComponent() methods).

Parameters:

newViewedComponent

the component to add to this viewport (this pointer may be null). The component passed in will be deleted by the Viewport when it's no longer needed

See also:

getViewedComponent

Component* Viewport::getViewedComponent

(

)

const throw ()

Returns the component that's currently being used inside the Viewport.

See also:

setViewedComponent

void Viewport::setViewPosition	(	int	xPixelsOffset,
		int	yPixelsOffset
	)

Changes the position of the viewed component.

The inner component will be moved so that the pixel at the top left of the viewport will be the pixel at position (xPixelsOffset, yPixelsOffset) within the inner component.

This will update the scrollbars and might cause a call to visibleAreaChanged().

See also:

getViewPositionX, getViewPositionY, setViewPositionProportionately

void Viewport::setViewPositionProportionately	(	double	proportionX,
		double	proportionY
	)

Changes the view position as a proportion of the distance it can move.

The values here are from 0.0 to 1.0 - where (0, 0) would put the visible area in the top-left, and (1, 1) would put it as far down and to the right as it's possible to go whilst keeping the child component on-screen.

bool Viewport::autoScroll	(	int	mouseX,
		int	mouseY,
		int	distanceFromEdge,
		int	maximumSpeed
	)

If the specified position is at the edges of the viewport, this method scrolls the viewport to bring that position nearer to the centre.

Call this if you're dragging an object inside a viewport and want to make it scroll when the user approaches an edge. You might also find Component::beginDragAutoRepeat() useful when auto-scrolling.

Parameters:

	mouseX	the x position, relative to the Viewport's top-left
	mouseY	the y position, relative to the Viewport's top-left
	distanceFromEdge	specifies how close to an edge the position needs to be before the viewport should scroll in that direction
	maximumSpeed	the maximum number of pixels that the viewport is allowed to scroll by.

Returns:

true if the viewport was scrolled

int Viewport::getViewPositionX

(

)

const throw ()

Returns the position within the child component of the top-left of its visible area.

See also:

getViewWidth, setViewPosition

int Viewport::getViewPositionY

(

)

const throw ()

Returns the position within the child component of the top-left of its visible area.

See also:

getViewHeight, setViewPosition

int Viewport::getViewWidth

(

)

const throw ()

Returns the width of the visible area of the child component.

This may be less than the width of this Viewport if there's a vertical scrollbar or if the child component is itself smaller.

int Viewport::getViewHeight

(

)

const throw ()

Returns the height of the visible area of the child component.

This may be less than the height of this Viewport if there's a horizontal scrollbar or if the child component is itself smaller.

int Viewport::getMaximumVisibleWidth

(

)

const throw ()

Returns the width available within this component for the contents.

This will be the width of the viewport component minus the width of a vertical scrollbar (if visible).

int Viewport::getMaximumVisibleHeight

(

)

const throw ()

Returns the height available within this component for the contents.

This will be the height of the viewport component minus the space taken up by a horizontal scrollbar (if visible).

virtual void Viewport::visibleAreaChanged	(	int	visibleX,
		int	visibleY,
		int	visibleW,
		int	visibleH
	)			[virtual]

Callback method that is called when the visible area changes.

This will be called when the visible area is moved either be scrolling or by calls to setViewPosition(), etc.

void Viewport::setScrollBarsShown	(	bool	showVerticalScrollbarIfNeeded,
		bool	showHorizontalScrollbarIfNeeded
	)

Turns scrollbars on or off.

If set to false, the scrollbars won't ever appear. When true (the default) they will appear only when needed.

bool Viewport::isVerticalScrollBarShown

(

)

const throw ()

True if the vertical scrollbar is enabled.

See also:

setScrollBarsShown

bool Viewport::isHorizontalScrollBarShown

(

)

const throw ()

True if the horizontal scrollbar is enabled.

See also:

setScrollBarsShown

void Viewport::setScrollBarThickness

(

int

thickness

)

Changes the width of the scrollbars.

If this isn't specified, the default width from the LookAndFeel class will be used.

See also:

LookAndFeel::getDefaultScrollbarWidth

int Viewport::getScrollBarThickness

(

)

const throw ()

Returns the thickness of the scrollbars.

See also:

setScrollBarThickness

void Viewport::setSingleStepSizes	(	int	stepX,
		int	stepY
	)

Changes the distance that a single-step click on a scrollbar button will move the viewport.

void Viewport::setScrollBarButtonVisibility

(

bool

buttonsVisible

)

Shows or hides the buttons on any scrollbars that are used.

See also:

ScrollBar::setButtonVisibility

ScrollBar* Viewport::getVerticalScrollBar

(

)

const throw ()

Returns a pointer to the scrollbar component being used.

Handy if you need to customise the bar somehow.

ScrollBar* Viewport::getHorizontalScrollBar

(

)

const throw ()

Returns a pointer to the scrollbar component being used.

Handy if you need to customise the bar somehow.

juce_UseDebuggingNewOperator void Viewport::resized

(

)

[virtual]

For internal use only.

Reimplemented from Component.

void Viewport::scrollBarMoved	(	ScrollBar *	scrollBarThatHasMoved,
		double	newRangeStart
	)			[virtual]

For internal use only.

Implements ScrollBarListener.

void Viewport::mouseWheelMove	(	const MouseEvent &	e,
		float	wheelIncrementX,
		float	wheelIncrementY
	)			[virtual]

For internal use only.

Reimplemented from Component.

bool Viewport::keyPressed

(

const KeyPress &

key

)

[virtual]

For internal use only.

Reimplemented from Component.

void Viewport::componentMovedOrResized	(	Component &	component,
		bool	wasMoved,
		bool	wasResized
	)			[virtual]

For internal use only.

Reimplemented from ComponentListener.

bool Viewport::useMouseWheelMoveIfNeeded	(	const MouseEvent &	e,
		float	wheelIncrementX,
		float	wheelIncrementY
	)

For internal use only.

---

The documentation for this class was generated from the following file:

• juce_Viewport.h