#include <Window.hpp>

Inheritance diagram for Window:

Classes
struct	ScopedGraphicsContext
struct	FileDropEvent

Public Member Functions
	Window (Application &app)
	Window (Application &app, Window &transientParentWindow)
	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)
int	getOffsetX () const noexcept
int	getOffsetY () const noexcept
Point< int >	getOffset () const noexcept
void	setOffsetX (int x)
void	setOffsetY (int y)
void	setOffset (int x, int y)
void	setOffset (const Point< int > &offset)
bool	setEmbeddedOffset (int x, int y)
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
const void *	getClipboard (size_t &dataSize)
bool	setClipboard (const char mimeType, const void data, size_t dataSize)
bool	startFileDrag (const char *filename)
bool	isAcceptingFileDrops () const noexcept
bool	setAcceptingFileDrops (bool accept)
bool	setCursor (MouseCursor cursor)
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
const char *	getPortalParentHandle () const noexcept
double	getScaleFactor () const noexcept
void	focus ()
bool	anyWidgetWantsKeyboardFocus ()
void	repaint () noexcept
void	repaint (const Rectangle< uint > &rect) noexcept
void	renderToPicture (const char *filename)
void	runAsModal (bool blockWait=false)
Size< uint >	getGeometryConstraints (bool &keepAspectRatio)
void	setGeometryConstraints (uint minimumWidth, uint minimumHeight, bool keepAspectRatio=false, bool automaticallyScale=false, bool resizeNowIfAutoScaling=true)
void	setTransientParent (uintptr_t transientParentWindowHandle)
bool	getIgnoringKeyRepeat () const noexcept
double	getScaling () const noexcept
void	exec (bool blockWait=false)

Protected Member Functions
std::vector< ClipboardDataOffer >	getClipboardDataOfferTypes ()
virtual uint32_t	onClipboardDataOffer ()
virtual bool	onFileDragEnter (const FileDropEvent &ev)
virtual bool	onFileDragMove (const FileDropEvent &ev)
virtual void	onFileDragLeave ()
virtual bool	onFileDrop (const FileDropEvent &ev)
virtual bool	onClose ()
virtual void	onFocus (bool focus, CrossingMode mode)
virtual void	onReshape (uint width, uint height)
virtual void	onScaleFactorChanged (double scaleFactor)

Friends
class	Application
class	TopLevelWidget
class	DAF_NAMESPACE::PluginWindow

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 &	transientParentWindow )

explicit

Constructor for a modal window, by having another window as its transient 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 window 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: DAF_UI_USER_RESIZABLE

◆ getOffsetX()

int Window::getOffsetX ( ) const

noexcept

Get X offset, typically 0.

◆ getOffsetY()

int Window::getOffsetY ( ) const

noexcept

Get Y offset, typically 0.

◆ getOffset()

Point< int > Window::getOffset ( ) const

noexcept

Get offset.

◆ setOffsetX()

void Window::setOffsetX ( int x )

Set X offset.

◆ setOffsetY()

void Window::setOffsetY ( int y )

Set Y offset.

◆ setOffset() [1/2]

void Window::setOffset	(	int	x,
		int	y )

Set offset using x and y values.

◆ setOffset() [2/2]

void Window::setOffset ( const Point< int > & offset )

Set offset.

◆ setEmbeddedOffset()

bool Window::setEmbeddedOffset	(	int	x,
		int	y )

Set the offset of an embedded window relative to its parent.

Embedded windows are normally positioned by their host, so the regular setOffset methods intentionally ignore them. This explicit variant is for hosts that own both the parent and embedded child window.

Returns: Whether the platform accepted the position change.

See also: isEmbed()

◆ 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.

◆ getClipboard()

const void * Window::getClipboard ( size_t & dataSize )

Get the clipboard contents.

This gets the system clipboard contents, which may have been set with setClipboard() or copied from another application.

Returns the clipboard contents, or null.

Note: By default only "text/plain" mimetype is supported and returned. Override onClipboardDataOffer for supporting other types.

◆ setClipboard()

bool Window::setClipboard	(	const char *	mimeType,
		const void *	data,
		size_t	dataSize )

Set the clipboard contents.

This sets the system clipboard contents, which can be retrieved with getClipboard() or pasted into other applications.

If using a string, the use of a null terminator is required (and must be part of dataSize).
The MIME type of the data "text/plain" is assumed if null is used.

◆ startFileDrag()

bool Window::startFileDrag ( const char * filename )

Start an outgoing copy-only drag of one existing file, from a primary mouse gesture. The UTF-8 path must identify an absolute file path. Call on the UI thread. Native delivery starts outside drawing, on a subsequent idle call. A true result means the operation was accepted, not that a destination has accepted the file. Keep the file available for asynchronous destination reads, including after this Window closes. The Window cancels its drag on destruction. Supported on Windows, macOS and X11. Returns false for an invalid file/gesture, an active drag, or an unsupported backend.

◆ isAcceptingFileDrops()

bool Window::isAcceptingFileDrops ( ) const

noexcept

Whether this window receives files dragged onto it from other applications.

See also: setAcceptingFileDrops(bool)

◆ setAcceptingFileDrops()

bool Window::setAcceptingFileDrops ( bool accept )

Let this window receive files dragged onto it from other applications, such as a file manager. The window then gets onFileDragEnter(), onFileDragMove(), and onFileDragLeave() or onFileDrop().

Only a window of its own can take drops: this fails for an embedded window, and on platforms without support (for now everything but X11, Wayland, macOS and Windows). On Windows it also fails on a thread in COM's multi-threaded apartment, where OLE cannot deliver drops. Turning it off always succeeds, and ends a drag in progress with onFileDragLeave() when the window had the enter. A window that never asks behaves exactly as before.

See also: isAcceptingFileDrops()

◆ setCursor()

bool Window::setCursor ( MouseCursor cursor )

Set the mouse cursor.

This changes the system cursor that is displayed when the pointer is inside the window. May fail if setting the cursor is not supported on this system, for example if compiled on X11 without Xcursor support.

◆ 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:

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.
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.

The callback is not owned or tracked beyond this, so it MUST be removed with removeIdleCallback() before the callback object is destroyed, and while this window still exists. A callback without a timer frequency is registered on the Application rather than on this window, and destroying the window does not remove it, so a forgotten one is called through a dangling pointer.

◆ 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.

◆ getPortalParentHandle()

const char * Window::getPortalParentHandle ( ) const

noexcept

Get this window's handle in the form xdg-desktop-portal expects for a dialog's parent, so that a portal file chooser opens on top of it instead of floating free. On X11 that is "x11:" and the window id, on Wayland "wayland:" and an xdg-foreign handle.

Returns an empty string when there is nothing to give: on platforms with no portals, and on a Wayland compositor that has not answered with a handle (or does not implement xdg-foreign). The returned string belongs to the window and is valid until the next call.

◆ 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.

◆ anyWidgetWantsKeyboardFocus()

bool Window::anyWidgetWantsKeyboardFocus ( )

Whether any visible widget of this window wants the keyboard focus. This asks Widget::wantsKeyboardFocus() of every visible top-level widget and, recursively, of their visible subwidgets. A hidden widget hides its whole subtree.

◆ 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.

◆ renderToPicture()

void Window::renderToPicture ( const char * filename )

Render this window's content into a picture file, specified by filename. Window must be visible and on screen. Written picture format is PPM.

◆ 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.

◆ getGeometryConstraints()

Size< uint > Window::getGeometryConstraints ( bool & keepAspectRatio )

Get the geometry constraints set for the Window.

See also: setGeometryConstraints

◆ setGeometryConstraints()

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

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

The minimum size is given unscaled: with automaticallyScale the constraint handed to the windowing system is the minimum multiplied by the window scale factor.

resizeNowIfAutoScaling additionally resizes the window to that scaled minimum as auto-scaling is switched on. It is ignored once the Window is already auto-scaling, so a later call cannot pull a user-resized window back down to its minimum.

◆ setTransientParent()

void Window::setTransientParent ( uintptr_t transientParentWindowHandle )

Set the transient parent of the window.

Set this for transient children like dialogs, to have them properly associated with their parent window. This should be not be called for embed windows, or after making the window visible.

◆ 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).

◆ getClipboardDataOfferTypes()

std::vector< ClipboardDataOffer > Window::getClipboardDataOfferTypes ( )

protected

Get the types available for the data in a clipboard. Must only be called within the context of onClipboardDataOffer.

◆ onClipboardDataOffer()

virtual uint32_t Window::onClipboardDataOffer ( )

protectedvirtual

A function called when clipboard has data present, possibly with several datatypes. While handling this event, the data types can be investigated with getClipboardDataOfferTypes() to decide whether to accept the offer.

Reimplement and return a non-zero id to accept the clipboard data offer for a particular type. Applications must ignore any type they do not recognize.

The default implementation accepts the "text/plain" mimetype.

◆ onFileDragEnter()

virtual bool Window::onFileDragEnter ( const FileDropEvent & ev )

protectedvirtual

A function called when files dragged from another application first come over this window, once their list is known. Return whether the window would take them if dropped at ev.pos. The answer shows as the platform's drag feedback. The source is only ever told of a copy.

Called on the event thread, like every other window callback, and only for a window that accepts file drops. Keep it short: the window may be closed or deleted from here, but must not block. The default implementation refuses.

See also: setAcceptingFileDrops(bool)

◆ onFileDragMove()

virtual bool Window::onFileDragMove ( const FileDropEvent & ev )

protectedvirtual

A function called when the files dragged over this window move. Return whether they would be taken if dropped at ev.pos. The default implementation answers what onFileDragEnter() answered.

◆ onFileDragLeave()

virtual void Window::onFileDragLeave ( )

protectedvirtual

A function called when the drag left this window, or ended without a drop on it. Comes only after onFileDragEnter(), and never after onFileDrop(). The default implementation does nothing.

◆ onFileDrop()

virtual bool Window::onFileDrop ( const FileDropEvent & ev )

protectedvirtual

A function called when the files are dropped, at a position the last answer accepted. Return whether the files were taken. To act on them at length, remember the paths and do it on the next idle: on some platforms the source waits for this call to return. The default implementation refuses.

◆ 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 DAF_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.

NOTE: This currently does not work under macOS.

◆ 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. Called from the drawing path, with the graphics context current, before the first draw that follows the resize. If there is a top-level widget associated with this window, its size has already been set by the time this runs. 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

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

dgl/Window.hpp

Classes

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Window() [1/4]

◆ Window() [2/4]

◆ Window() [3/4]

◆ Window() [4/4]

◆ ~Window()

Member Function Documentation

◆ isEmbed()

◆ isVisible()

◆ setVisible()

◆ show()

◆ hide()

◆ close()

◆ isResizable()

◆ setResizable()

◆ getOffsetX()

◆ getOffsetY()

◆ getOffset()

◆ setOffsetX()

◆ setOffsetY()

◆ setOffset() [1/2]

◆ setOffset() [2/2]

◆ setEmbeddedOffset()

◆ getWidth()

◆ getHeight()

◆ getSize()

◆ setWidth()

◆ setHeight()

◆ setSize() [1/2]

◆ setSize() [2/2]

◆ getTitle()

◆ setTitle()

◆ isIgnoringKeyRepeat()

◆ setIgnoringKeyRepeat()

◆ getClipboard()

◆ setClipboard()

◆ startFileDrag()

◆ isAcceptingFileDrops()

◆ setAcceptingFileDrops()

◆ setCursor()

◆ addIdleCallback()

◆ removeIdleCallback()

◆ getApp()

◆ getGraphicsContext()

◆ getNativeWindowHandle()

◆ getPortalParentHandle()

◆ getScaleFactor()

◆ focus()

◆ anyWidgetWantsKeyboardFocus()

◆ repaint() [1/2]

◆ repaint() [2/2]

◆ renderToPicture()

◆ runAsModal()

◆ getGeometryConstraints()

◆ setGeometryConstraints()

◆ setTransientParent()

◆ getIgnoringKeyRepeat()

◆ getScaling()

◆ exec()

◆ getClipboardDataOfferTypes()

◆ onClipboardDataOffer()

◆ onFileDragEnter()

◆ onFileDragMove()

◆ onFileDragLeave()

◆ onFileDrop()

◆ onClose()

◆ onFocus()

◆ onReshape()

◆ onScaleFactorChanged()