Window Class Reference

#include <Window.hpp>

Inheritance diagram for Window:

Classes
struct	FileBrowserOptions
class	ScopedGraphicsContext

Public Member Functions
	Window (Application &app)
	Window (Application &app, Window &parent)
	Window (Application &app, uintptr_t parentWindowHandle, double scaleFactor, bool resizable)
	Window (Application &app, uintptr_t parentWindowHandle, uint width, uint height, double scaleFactor, bool resizable)
virtual	~Window ()
bool	isEmbed () const noexcept
bool	isVisible () const noexcept
void	setVisible (bool visible)
void	show ()
void	hide ()
void	close ()
bool	isResizable () const noexcept
void	setResizable (bool resizable)
uint	getWidth () const noexcept
uint	getHeight () const noexcept
Size< uint >	getSize () const noexcept
void	setWidth (uint width)
void	setHeight (uint height)
void	setSize (uint width, uint height)
void	setSize (const Size< uint > &size)
const char *	getTitle () const noexcept
void	setTitle (const char *title)
bool	isIgnoringKeyRepeat () const noexcept
void	setIgnoringKeyRepeat (bool ignore) noexcept
bool	addIdleCallback (IdleCallback *callback, uint timerFrequencyInMs=0)
bool	removeIdleCallback (IdleCallback *callback)
Application &	getApp () const noexcept
const GraphicsContext &	getGraphicsContext () const noexcept
uintptr_t	getNativeWindowHandle () const noexcept
double	getScaleFactor () const noexcept
void	focus ()
bool	openFileBrowser (const FileBrowserOptions &options)
void	repaint () noexcept
void	repaint (const Rectangle< uint > &rect) noexcept
void	runAsModal (bool blockWait=false)
void	setGeometryConstraints (uint minimumWidth, uint minimumHeight, bool keepAspectRatio=false, bool automaticallyScale=false)
bool	getIgnoringKeyRepeat () const noexcept
double	getScaling () const noexcept
void	exec (bool blockWait=false)

Protected Member Functions
virtual bool	onClose ()
virtual void	onFocus (bool focus, CrossingMode mode)
virtual void	onReshape (uint width, uint height)
virtual void	onScaleFactorChanged (double scaleFactor)
virtual void	onFileSelected (const char *filename)
virtual void	fileBrowserSelected (const char *filename)

Friends
class	Application
class	PluginWindow
class	TopLevelWidget

Detailed Description

DGL Window class.

This is the where all OS-related events initially happen, before being propagated to any widgets.

A Window MUST have an Application instance tied to it. It is not possible to swap Application instances from within the lifetime of a Window. But it is possible to completely change the Widgets that a Window contains during its lifetime.

Typically the event handling functions as following: Application -> Window -> Top-Level-Widget -> SubWidgets

Please note that, unlike many other graphical toolkits out there, DGL makes a clear distinction between a Window and a Widget. You cannot directly draw in a Window, you need to create a Widget for that.

Also, a Window MUST have a single top-level Widget. The Window will take care of global screen positioning and resizing, everything else is sent for widgets to handle.

...

Constructor & Destructor Documentation

Window() [1/4]

Window::Window ( Application &  app )

explicit

Constructor for a regular, standalone window.

Window() [2/4]

Window::Window ( Application &  app, Window &  parent  )

explicit

Constructor for a modal window, by having another window as its parent. The Application instance must be the same between the 2 windows.

Window() [3/4]

Window::Window ( Application &  app, uintptr_t  parentWindowHandle, double  scaleFactor, bool  resizable  )

explicit

Constructor for an embed Window without known size, typically used in modules or plugins that run inside another host.

Window() [4/4]

Window::Window ( Application &  app, uintptr_t  parentWindowHandle, uint  width, uint  height, double  scaleFactor, bool  resizable  )

explicit

Constructor for an embed Window with known size, typically used in modules or plugins that run inside another host.

~Window()

virtual Window::~Window ( )

virtual

Destructor.

Member Function Documentation

isEmbed()

bool Window::isEmbed ( ) const

noexcept

Whether this Window is embed into another (usually not DGL-controlled) Window.

isVisible()

bool Window::isVisible ( ) const

noexcept

Check if this window is visible / mapped. Invisible windows do not receive events except resize.

See also

setVisible(bool)

setVisible()

void Window::setVisible

(

bool

visible

)

Set windows visible (or not) according to visible. Only valid for standalones, embed windows are always visible.

See also

isVisible(), hide(), show()

show()

void Window::show

(

)

Show window. This is the same as calling setVisible(true).

See also

isVisible(), setVisible(bool)

hide()

void Window::hide

(

)

Hide window. This is the same as calling setVisible(false).

See also

isVisible(), setVisible(bool)

close()

void Window::close

(

)

Hide window and notify application of a window close event. The application event-loop will stop when all windows have been closed. For standalone windows only, has no effect if window is embed.

See also

isEmbed()

Note

It is possible to hide the window while not stopping the event-loop. A closed window is always hidden, but the reverse is not always true.

isResizable()

bool Window::isResizable ( ) const

noexcept

Check if this window is resizable (by the user or window manager).

See also

setResizable

setResizable()

void Window::setResizable

(

bool

resizable

)

Set window as resizable (by the user or window manager). It is always possible to resize a window programmatically, which is not the same as the user being allowed to it.

Note

This function does nothing for plugins, where the resizable state is set via macro.

See also

DISTRHO_UI_USER_RESIZABLE

getWidth()

uint Window::getWidth ( ) const

noexcept

Get width.

getHeight()

uint Window::getHeight ( ) const

noexcept

Get height.

getSize()

Size<uint> Window::getSize ( ) const

noexcept

Get size.

setWidth()

void Window::setWidth

(

uint

width

)

Set width.

setHeight()

void Window::setHeight

(

uint

height

)

Set height.

setSize() [1/2]

void Window::setSize	(	uint	width,
		uint	height
	)

Set size using width and height values.

setSize() [2/2]

void Window::setSize

(

const Size< uint > &

size

)

Set size.

getTitle()

const char* Window::getTitle ( ) const

noexcept

Get the title of the window previously set with setTitle().

setTitle()

void Window::setTitle

(

const char *

title

)

Set the title of the window, typically displayed in the title bar or in window switchers.

This only makes sense for non-embedded windows.

isIgnoringKeyRepeat()

bool Window::isIgnoringKeyRepeat ( ) const

noexcept

Check if key repeat events are ignored.

setIgnoringKeyRepeat()

void Window::setIgnoringKeyRepeat ( bool  ignore )

noexcept

Set to ignore (or not) key repeat events according to ignore.

addIdleCallback()

bool Window::addIdleCallback	(	IdleCallback *	callback,
		uint	timerFrequencyInMs = 0
	)

Add a callback function to be triggered on every idle cycle or on a specific timer frequency. You can add more than one, and remove them at anytime with removeIdleCallback(). This can be used to perform some action at a regular interval with relatively low frequency.

If providing a timer frequency, there are a few things to note:

1. There is a platform-specific limit to the number of supported timers, and overhead associated with each, so you should create only a few timers and perform several tasks in one if necessary.
2. This timer frequency is not guaranteed to have a resolution better than 10ms (the maximum timer resolution on Windows) and may be rounded up if it is too short. On X11 and MacOS, a resolution of about 1ms can usually be relied on.

removeIdleCallback()

bool Window::removeIdleCallback

(

IdleCallback *

callback

)

Remove an idle callback previously added via addIdleCallback().

getApp()

Application& Window::getApp ( ) const

noexcept

Get the application associated with this window.

getGraphicsContext()

const GraphicsContext& Window::getGraphicsContext ( ) const

noexcept

Get the graphics context associated with this window. GraphicsContext is an empty struct and needs to be casted into a different type in order to be usable, for example GraphicsContext.

See also

CairoSubWidget, CairoTopLevelWidget

getNativeWindowHandle()

uintptr_t Window::getNativeWindowHandle ( ) const

noexcept

Get the "native" window handle. Returned value depends on the platform:

• HaikuOS: This is a pointer to a BView.
• MacOS: This is a pointer to an NSView*.
• Windows: This is a HWND.
• Everything else: This is an [X11] Window.

getScaleFactor()

double Window::getScaleFactor ( ) const

noexcept

Get the scale factor requested for this window. This is purely informational, and up to developers to choose what to do with it.

If you do not want to deal with this yourself, consider using setGeometryConstraints() where you can specify to automatically scale the window contents.

See also

setGeometryConstraints

focus()

void Window::focus

(

)

Grab the keyboard input focus.

openFileBrowser()

bool Window::openFileBrowser

(

const FileBrowserOptions &

options

)

Open a file browser dialog with this window as parent. A few options can be specified to setup the dialog.

If a path is selected, onFileSelected() will be called with the user chosen path. If the user cancels or does not pick a file, onFileSelected() will be called with nullptr as filename.

This function does not block the event loop.

repaint() [1/2]

void Window::repaint ( )

noexcept

Request repaint of this window, for the entire area.

repaint() [2/2]

void Window::repaint ( const Rectangle< uint > &  rect )

noexcept

Request partial repaint of this window, with bounds according to rect.

runAsModal()

void Window::runAsModal

(

bool

blockWait = false

)

Run this window as a modal, blocking input events from the parent. Only valid for windows that have been created with another window as parent (as passed in the constructor). Can optionally block-wait, but such option is only available if the application is running as standalone.

setGeometryConstraints()

void Window::setGeometryConstraints	(	uint	minimumWidth,
		uint	minimumHeight,
		bool	keepAspectRatio = false,
		bool	automaticallyScale = false
	)

Set geometry constraints for the Window when resized by the user, and optionally scale contents automatically.

getIgnoringKeyRepeat()

bool Window::getIgnoringKeyRepeat ( ) const

inlinenoexcept

DEPRECATED Use isIgnoringKeyRepeat().

getScaling()

double Window::getScaling ( ) const

inlinenoexcept

DEPRECATED Use getScaleFactor().

exec()

void Window::exec ( bool  blockWait = false )

inline

DEPRECATED Use runAsModal(bool).

onClose()

virtual bool Window::onClose ( )

protectedvirtual

A function called when the window is attempted to be closed. Returning true closes the window, which is the default behaviour. Override this method and return false to prevent the window from being closed by the user.

This method is not used for embed windows, and not even made available in DISTRHO_NAMESPACE::UI. For embed windows, closing is handled by the host/parent process and we have no control over it. As such, a close action on embed windows will always succeed and cannot be cancelled.

onFocus()

virtual void Window::onFocus ( bool  focus, CrossingMode  mode  )

protectedvirtual

A function called when the window gains or loses the keyboard focus. The default implementation does nothing.

onReshape()

virtual void Window::onReshape ( uint  width, uint  height  )

protectedvirtual

A function called when the window is resized. If there is a top-level widget associated with this window, its size will be set right after this function. The default implementation sets up drawing context where necessary.

onScaleFactorChanged()

virtual void Window::onScaleFactorChanged ( double  scaleFactor )

protectedvirtual

A function called when scale factor requested for this window changes. The default implementation does nothing. WARNING function needs a proper name

onFileSelected()

virtual void Window::onFileSelected ( const char *  filename )

protectedvirtual

A function called when a path is selected by the user, as triggered by openFileBrowser(). This action happens after the user confirms the action, so the file browser dialog will be closed at this point. The default implementation does nothing.

fileBrowserSelected()

virtual void Window::fileBrowserSelected ( const char *  filename )

inlineprotectedvirtual

DEPRECATED Use onFileSelected().

---

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

• dgl/Window.hpp