Describes and controls aspects of the computer's desktop. More...

#include "juce_Desktop.h"

Inheritance diagram for juce::Desktop:

Classes
class	NativeDarkModeChangeDetectorImpl

Public Types
enum	DisplayOrientation { upright , upsideDown , rotatedClockwise , rotatedAntiClockwise , allOrientations }
	In a tablet/mobile device which can be turned around, this is used to indicate the orientation. More...

Public Member Functions
int	getMouseButtonClickCounter () const noexcept
	Returns the number of times the mouse button has been clicked since the app started.

int	getMouseWheelMoveCounter () const noexcept
	Returns the number of times the mouse wheel has been moved since the app started.

void	addGlobalMouseListener (MouseListener *listener)
	Registers a MouseListener that will receive all mouse events that occur on any component.

void	removeGlobalMouseListener (MouseListener *listener)
	Unregisters a MouseListener that was added with addGlobalMouseListener().

void	addFocusChangeListener (FocusChangeListener *listener)
	Registers a FocusChangeListener that will receive a callback whenever the focused component changes.

void	removeFocusChangeListener (FocusChangeListener *listener)
	Unregisters a FocusChangeListener that was added with addFocusChangeListener().

void	addDarkModeSettingListener (DarkModeSettingListener *listener)
	Registers a DarkModeSettingListener that will receive a callback when the operating system dark mode setting changes.

void	removeDarkModeSettingListener (DarkModeSettingListener *listener)
	Unregisters a DarkModeSettingListener that was added with addDarkModeSettingListener().

bool	isDarkModeActive () const
	True if the operating system "dark mode" is active.

void	setKioskModeComponent (Component *componentToUse, bool allowMenusAndBars=true)
	Takes a component and makes it full-screen, removing the taskbar, dock, etc.

Component *	getKioskModeComponent () const noexcept
	Returns the component that is currently being used in kiosk-mode.

int	getNumComponents () const noexcept
	Returns the number of components that are currently active as top-level desktop windows.

Component *	getComponent (int index) const noexcept
	Returns one of the top-level desktop window components.

Component *	findComponentAt (Point< int > screenPosition) const
	Finds the component at a given screen location.

ComponentAnimator &	getAnimator () noexcept
	The Desktop object has a ComponentAnimator instance which can be used for performing your animations.

LookAndFeel &	getDefaultLookAndFeel () noexcept
	Returns the current default look-and-feel for components which don't have one explicitly set.

void	setDefaultLookAndFeel (LookAndFeel *newDefaultLookAndFeel)
	Changes the default look-and-feel.

const Array< MouseInputSource > &	getMouseSources () const noexcept
	Provides access to the array of mouse sources, for iteration.

int	getNumMouseSources () const noexcept
	Returns the number of MouseInputSource objects the system has at its disposal.

MouseInputSource *	getMouseSource (int index) const noexcept
	Returns one of the system's MouseInputSource objects.

MouseInputSource	getMainMouseSource () const noexcept
	Returns the main mouse input device that the system is using.

int	getNumDraggingMouseSources () const noexcept
	Returns the number of mouse-sources that are currently being dragged.

MouseInputSource *	getDraggingMouseSource (int index) const noexcept
	Returns one of the mouse sources that's currently being dragged.

void	beginDragAutoRepeat (int millisecondsBetweenCallbacks)
	Ensures that a non-stop stream of mouse-drag events will be sent during the current mouse-drag operation.

DisplayOrientation	getCurrentOrientation () const
	In a tablet device which can be turned around, this returns the current orientation.

void	setOrientationsEnabled (int allowedOrientations)
	Sets which orientations the display is allowed to auto-rotate to.

int	getOrientationsEnabled () const noexcept
	Returns the set of orientations the display is allowed to rotate to.

bool	isOrientationEnabled (DisplayOrientation orientation) const noexcept
	Returns whether the display is allowed to auto-rotate to the given orientation.

const Displays &	getDisplays () const noexcept
	Returns the Displays object representing the connected displays.

void	setGlobalScaleFactor (float newScaleFactor) noexcept
	Sets a global scale factor to be used for all desktop windows.

float	getGlobalScaleFactor () const noexcept
	Returns the current global scale factor, as set by setGlobalScaleFactor().

bool	isHeadless () const noexcept
	Returns true on a headless system where there are no connected displays.

Static Public Member Functions
static Desktop &JUCE_CALLTYPE	getInstance ()
	There's only one desktop object, and this method will return it.

static Point< int >	getMousePosition ()
	Returns the mouse position.

static void	setMousePosition (Point< int > newPosition)
	Makes the mouse pointer jump to a given location.

static Point< int >	getLastMouseDownPosition ()
	Returns the last position at which a mouse button was pressed.

static void	setScreenSaverEnabled (bool isEnabled)
	This lets you prevent the screensaver from becoming active.

static bool	isScreenSaverEnabled ()
	Returns true if the screensaver has not been turned off.

static bool	canUseSemiTransparentWindows () noexcept
	True if the OS supports semitransparent windows.

Friends
class	Component

class	ComponentPeer

class	detail::MouseInputSourceImpl

class	DeletedAtShutdown

class	detail::TopLevelWindowManager

class	Displays

Detailed Description

Describes and controls aspects of the computer's desktop.

@tags{GUI}

Definition at line 75 of file juce_Desktop.h.

Member Enumeration Documentation

◆ DisplayOrientation

enum juce::Desktop::DisplayOrientation

In a tablet/mobile device which can be turned around, this is used to indicate the orientation.

Enumerator
upright	Indicates that the device is the normal way up.
upsideDown	Indicates that the device is upside-down.
rotatedClockwise	Indicates that the device is turned 90 degrees clockwise from its upright position.
rotatedAntiClockwise	Indicates that the device is turned 90 degrees anti-clockwise from its upright position.
allOrientations	A combination of all the orientation values.

Definition at line 343 of file juce_Desktop.h.

Member Function Documentation

◆ addDarkModeSettingListener()

void juce::Desktop::addDarkModeSettingListener ( DarkModeSettingListener * listener )

Registers a DarkModeSettingListener that will receive a callback when the operating system dark mode setting changes.

To query whether dark mode is on use the isDarkModeActive() method.

See also: isDarkModeActive, removeDarkModeSettingListener

Definition at line 223 of file juce_Desktop.cpp.

◆ addFocusChangeListener()

void juce::Desktop::addFocusChangeListener ( FocusChangeListener * listener )

Registers a FocusChangeListener that will receive a callback whenever the focused component changes.

See also: removeFocusChangeListener

Definition at line 188 of file juce_Desktop.cpp.

◆ addGlobalMouseListener()

void juce::Desktop::addGlobalMouseListener ( MouseListener * listener )

Registers a MouseListener that will receive all mouse events that occur on any component.

See also: removeGlobalMouseListener

Definition at line 245 of file juce_Desktop.cpp.

◆ beginDragAutoRepeat()

void juce::Desktop::beginDragAutoRepeat ( int millisecondsBetweenCallbacks )

Ensures that a non-stop stream of mouse-drag events will be sent during the current mouse-drag operation.

This allows you to make sure that mouseDrag() events are sent continuously, even when the mouse isn't moving. This can be useful for things like auto-scrolling components when the mouse is near an edge.

Call this method during a mouseDown() or mouseDrag() callback, specifying the minimum interval between consecutive mouse drag callbacks. The callbacks will continue until the mouse is released, and then the interval will be reset, so you need to make sure it's called every time you begin a drag event. Passing an interval of 0 or less will cancel the auto-repeat.

See also: mouseDrag

Definition at line 185 of file juce_Desktop.cpp.

◆ canUseSemiTransparentWindows()

bool juce::Desktop::canUseSemiTransparentWindows ( )

staticnoexcept

True if the OS supports semitransparent windows.

Definition at line 623 of file juce_Windowing_linux.cpp.

◆ findComponentAt()

Component * juce::Desktop::findComponentAt ( Point< int > screenPosition ) const

Finds the component at a given screen location.

This will drill down into top-level windows to find the child component at the given position.

Returns nullptr if the coordinates are inside a non-JUCE window.

Definition at line 71 of file juce_Desktop.cpp.

◆ getAnimator()

ComponentAnimator & juce::Desktop::getAnimator ( )

noexcept

The Desktop object has a ComponentAnimator instance which can be used for performing your animations.

Having a single shared ComponentAnimator object makes it more efficient when multiple components are being moved around simultaneously. It's also more convenient than having to manage your own instance of one.

See also: ComponentAnimator

Definition at line 262 of file juce_Desktop.h.

◆ getComponent()

Component * juce::Desktop::getComponent ( int index ) const

noexcept

Returns one of the top-level desktop window components.

The index is from 0 to getNumComponents() - 1. This could return 0 if the index is out-of-range.

See also: getNumComponents, Component::addToDesktop

Definition at line 66 of file juce_Desktop.cpp.

◆ getCurrentOrientation()

Desktop::DisplayOrientation juce::Desktop::getCurrentOrientation ( ) const

In a tablet device which can be turned around, this returns the current orientation.

Definition at line 695 of file juce_Windowing_linux.cpp.

◆ getDefaultLookAndFeel()

LookAndFeel & juce::Desktop::getDefaultLookAndFeel ( )

noexcept

Returns the current default look-and-feel for components which don't have one explicitly set.

See also: setDefaultLookAndFeel

Definition at line 92 of file juce_Desktop.cpp.

◆ getDisplays()

const Displays & juce::Desktop::getDisplays ( ) const

noexcept

Returns the Displays object representing the connected displays.

See also: Displays

Definition at line 380 of file juce_Desktop.h.

◆ getDraggingMouseSource()

MouseInputSource * juce::Desktop::getDraggingMouseSource ( int index ) const

noexcept

Returns one of the mouse sources that's currently being dragged.

The index should be between 0 and getNumDraggingMouseSources() - 1. If the index is out of range, or if no mice or fingers are down, this will return a null pointer.

Definition at line 183 of file juce_Desktop.cpp.

◆ getGlobalScaleFactor()

float juce::Desktop::getGlobalScaleFactor ( ) const

noexcept

Returns the current global scale factor, as set by setGlobalScaleFactor().

See also: setGlobalScaleFactor

Definition at line 391 of file juce_Desktop.h.

◆ getInstance()

Desktop &JUCE_CALLTYPE juce::Desktop::getInstance ( )

static

There's only one desktop object, and this method will return it.

Definition at line 50 of file juce_Desktop.cpp.

◆ getKioskModeComponent()

Component * juce::Desktop::getKioskModeComponent ( ) const

noexcept

Returns the component that is currently being used in kiosk-mode.

This is the component that was last set by setKioskModeComponent(). If none has been set, this returns nullptr.

Definition at line 225 of file juce_Desktop.h.

◆ getLastMouseDownPosition()

Point< int > juce::Desktop::getLastMouseDownPosition ( )

static

Returns the last position at which a mouse button was pressed.

Note that this is just a shortcut for calling getMainMouseSource().getLastMouseDownPosition(), and in a multi-touch environment, it doesn't make much sense. ALWAYS prefer to get this information via other means, such as MouseEvent::getMouseDownScreenPosition() if possible, and only ever call this as a last resort.

Definition at line 168 of file juce_Desktop.cpp.

◆ getMainMouseSource()

MouseInputSource juce::Desktop::getMainMouseSource ( ) const

noexcept

Returns the main mouse input device that the system is using.

See also: getNumMouseSources()

Definition at line 184 of file juce_Desktop.cpp.

◆ getMouseButtonClickCounter()

int juce::Desktop::getMouseButtonClickCounter ( ) const

noexcept

Returns the number of times the mouse button has been clicked since the app started.

Each mouse-down event increments this number by 1.

See also: getMouseWheelMoveCounter

Definition at line 173 of file juce_Desktop.cpp.

◆ getMousePosition()

Point< int > juce::Desktop::getMousePosition ( )

static

Returns the mouse position.

The coordinates are relative to the top-left of the main monitor.

Note that this is just a shortcut for calling getMainMouseSource().getScreenPosition(), and you should only resort to grabbing the global mouse position if there's really no way to get the coordinates via a mouse event callback instead.

Definition at line 153 of file juce_Desktop.cpp.

◆ getMouseSource()

MouseInputSource * juce::Desktop::getMouseSource ( int index ) const

noexcept

Returns one of the system's MouseInputSource objects.

The index should be from 0 to getNumMouseSources() - 1. Out-of-range indexes will return a null pointer. In a traditional single-mouse system, there might be only one object. On a multi-touch system, there could be one input source per potential finger.

Definition at line 182 of file juce_Desktop.cpp.

◆ getMouseSources()

const Array< MouseInputSource > & juce::Desktop::getMouseSources ( ) const

noexcept

Provides access to the array of mouse sources, for iteration.

In a traditional single-mouse system, there might be only one MouseInputSource. On a multi-touch system, there could be one input source per potential finger. The number of mouse sources returned here may increase dynamically as the program runs. To find out how many mouse events are currently happening, use getNumDraggingMouseSources().

Definition at line 179 of file juce_Desktop.cpp.

◆ getMouseWheelMoveCounter()

int juce::Desktop::getMouseWheelMoveCounter ( ) const

noexcept

Returns the number of times the mouse wheel has been moved since the app started.

Each mouse-wheel event increments this number by 1.

See also: getMouseButtonClickCounter

Definition at line 174 of file juce_Desktop.cpp.

◆ getNumComponents()

int juce::Desktop::getNumComponents ( ) const

noexcept

Returns the number of components that are currently active as top-level desktop windows.

See also: getComponent, Component::addToDesktop

Definition at line 61 of file juce_Desktop.cpp.

◆ getNumDraggingMouseSources()

int juce::Desktop::getNumDraggingMouseSources ( ) const

noexcept

Returns the number of mouse-sources that are currently being dragged.

In a traditional single-mouse system, this will be 0 or 1, depending on whether a JUCE component has the button down on it. In a multi-touch system, this could be any number from 0 to the number of simultaneous touches that can be detected.

Definition at line 181 of file juce_Desktop.cpp.

◆ getNumMouseSources()

int juce::Desktop::getNumMouseSources ( ) const

noexcept

Returns the number of MouseInputSource objects the system has at its disposal.

In a traditional single-mouse system, there might be only one MouseInputSource. On a multi-touch system, there could be one input source per potential finger. The number of mouse sources returned here may increase dynamically as the program runs. To find out how many mouse events are currently happening, use getNumDraggingMouseSources().

See also: getMouseSource

Definition at line 180 of file juce_Desktop.cpp.

◆ getOrientationsEnabled()

int juce::Desktop::getOrientationsEnabled ( ) const

noexcept

Returns the set of orientations the display is allowed to rotate to.

See also: setOrientationsEnabled

Definition at line 338 of file juce_Desktop.cpp.

◆ isDarkModeActive()

bool juce::Desktop::isDarkModeActive ( ) const

True if the operating system "dark mode" is active.

To receive a callback when this setting changes implement the DarkModeSettingListener interface and use the addDarkModeSettingListener() to register a listener.

See also: addDarkModeSettingListener, removeDarkModeSettingListener

Definition at line 672 of file juce_Windowing_linux.cpp.

◆ isHeadless()

bool juce::Desktop::isHeadless ( ) const

noexcept

Returns true on a headless system where there are no connected displays.

Definition at line 363 of file juce_Desktop.cpp.

◆ isOrientationEnabled()

bool juce::Desktop::isOrientationEnabled ( DisplayOrientation orientation ) const

noexcept

Returns whether the display is allowed to auto-rotate to the given orientation.

Each orientation can be enabled using setOrientationEnabled(). By default, all orientations are allowed.

Definition at line 343 of file juce_Desktop.cpp.

◆ isScreenSaverEnabled()

bool juce::Desktop::isScreenSaverEnabled ( )

static

Returns true if the screensaver has not been turned off.

This will return the last value passed into setScreenSaverEnabled(). Note that it won't tell you whether the user is actually using a screen saver, just whether this app is deliberately preventing one from running.

See also: setScreenSaverEnabled

Definition at line 688 of file juce_Windowing_linux.cpp.

◆ removeDarkModeSettingListener()

void juce::Desktop::removeDarkModeSettingListener ( DarkModeSettingListener * listener )

Unregisters a DarkModeSettingListener that was added with addDarkModeSettingListener().

See also: addDarkModeSettingListener

Definition at line 224 of file juce_Desktop.cpp.

◆ removeFocusChangeListener()

void juce::Desktop::removeFocusChangeListener ( FocusChangeListener * listener )

Unregisters a FocusChangeListener that was added with addFocusChangeListener().

See also: addFocusChangeListener

Definition at line 189 of file juce_Desktop.cpp.

◆ removeGlobalMouseListener()

void juce::Desktop::removeGlobalMouseListener ( MouseListener * listener )

Unregisters a MouseListener that was added with addGlobalMouseListener().

See also: addGlobalMouseListener

Definition at line 252 of file juce_Desktop.cpp.

◆ setDefaultLookAndFeel()

void juce::Desktop::setDefaultLookAndFeel ( LookAndFeel * newDefaultLookAndFeel )

Changes the default look-and-feel.

Parameters

newDefaultLookAndFeel the new look-and-feel object to use - if this is set to nullptr, it will revert to using the system's default one. The object passed-in must be deleted by the caller when it's no longer needed.

See also: getDefaultLookAndFeel

Definition at line 106 of file juce_Desktop.cpp.

◆ setGlobalScaleFactor()

void juce::Desktop::setGlobalScaleFactor ( float newScaleFactor )

noexcept

Sets a global scale factor to be used for all desktop windows.

Setting this will also scale the monitor sizes that are returned by getDisplays().

Definition at line 352 of file juce_Desktop.cpp.

◆ setKioskModeComponent()

void juce::Desktop::setKioskModeComponent	(	Component *	componentToUse,
		bool	allowMenusAndBars = `true`
	)

Takes a component and makes it full-screen, removing the taskbar, dock, etc.

The component must already be on the desktop for this method to work. It will be resized to completely fill the screen and any extraneous taskbars, menu bars, etc will be hidden.

To exit kiosk mode, just call setKioskModeComponent (nullptr). When this is called, the component that's currently being used will be resized back to the size and position it was in before being put into this mode.

If allowMenusAndBars is true, things like the menu and dock (on mac) are still allowed to pop up when the mouse moves onto them. If this is false, it'll try to hide as much on-screen paraphernalia as possible.

Definition at line 293 of file juce_Desktop.cpp.

◆ setMousePosition()

void juce::Desktop::setMousePosition ( Point< int > newPosition )

static

Makes the mouse pointer jump to a given location.

The coordinates are relative to the top-left of the main monitor. Note that this is a pretty old method, kept around mainly for backwards-compatibility, and you should use the MouseInputSource class directly in new code.

Definition at line 163 of file juce_Desktop.cpp.

◆ setOrientationsEnabled()

void juce::Desktop::setOrientationsEnabled ( int allowedOrientations )

Sets which orientations the display is allowed to auto-rotate to.

For devices that support rotating desktops, this lets you specify which of the orientations your app can use.

The parameter is a bitwise or-ed combination of the values in DisplayOrientation, and must contain at least one set bit.

Definition at line 326 of file juce_Desktop.cpp.

◆ setScreenSaverEnabled()

void juce::Desktop::setScreenSaverEnabled ( bool isEnabled )

static

This lets you prevent the screensaver from becoming active.

Handy if you're running some sort of presentation app where having a screensaver appear would be annoying.

Pass false to disable the screensaver, and true to re-enable it. (Note that this won't enable a screensaver unless the user has actually set one up).

The disablement will only happen while the JUCE application is the foreground process - if another task is running in front of it, then the screensaver will be unaffected.

See also: isScreenSaverEnabled

Definition at line 679 of file juce_Windowing_linux.cpp.

Friends And Related Symbol Documentation

◆ Component

friend class Component

friend

Definition at line 411 of file juce_Desktop.h.

◆ ComponentPeer

friend class ComponentPeer

friend

Definition at line 412 of file juce_Desktop.h.

◆ DeletedAtShutdown

friend class DeletedAtShutdown

friend

Definition at line 414 of file juce_Desktop.h.

◆ detail::MouseInputSourceImpl

friend class detail::MouseInputSourceImpl

friend

Definition at line 413 of file juce_Desktop.h.

◆ detail::TopLevelWindowManager

friend class detail::TopLevelWindowManager

friend

Definition at line 415 of file juce_Desktop.h.

◆ Displays

friend class Displays

friend

Definition at line 416 of file juce_Desktop.h.

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

juce_gui_basics/desktop/juce_Desktop.h
juce_gui_basics/desktop/juce_Desktop.cpp
juce_gui_basics/native/juce_Windowing_linux.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ DisplayOrientation

Member Function Documentation

◆ addDarkModeSettingListener()

◆ addFocusChangeListener()

◆ addGlobalMouseListener()

◆ beginDragAutoRepeat()

◆ canUseSemiTransparentWindows()

◆ findComponentAt()

◆ getAnimator()

◆ getComponent()

◆ getCurrentOrientation()

◆ getDefaultLookAndFeel()

◆ getDisplays()

◆ getDraggingMouseSource()

◆ getGlobalScaleFactor()

◆ getInstance()

◆ getKioskModeComponent()

◆ getLastMouseDownPosition()

◆ getMainMouseSource()

◆ getMouseButtonClickCounter()

◆ getMousePosition()

◆ getMouseSource()

◆ getMouseSources()

◆ getMouseWheelMoveCounter()

◆ getNumComponents()

◆ getNumDraggingMouseSources()

◆ getNumMouseSources()

◆ getOrientationsEnabled()

◆ isDarkModeActive()

◆ isHeadless()

◆ isOrientationEnabled()

◆ isScreenSaverEnabled()

◆ removeDarkModeSettingListener()

◆ removeFocusChangeListener()

◆ removeGlobalMouseListener()

◆ setDefaultLookAndFeel()

◆ setGlobalScaleFactor()

◆ setKioskModeComponent()

◆ setMousePosition()

◆ setOrientationsEnabled()

◆ setScreenSaverEnabled()

Friends And Related Symbol Documentation

◆ Component

◆ ComponentPeer

◆ DeletedAtShutdown

◆ detail::MouseInputSourceImpl

◆ detail::TopLevelWindowManager

◆ Displays