#include <ExternalWindow.hpp>

Public Member Functions
	ExternalWindow ()

	ExternalWindow (const PrivateData &data)

virtual	~ExternalWindow ()

virtual bool	isRunning () const

virtual bool	isQuitting () const

virtual uintptr_t	getNativeWindowHandle () const noexcept

virtual void	focus ()

bool	isEmbed () const noexcept

bool	isVisible () const noexcept

bool	isStandalone () const noexcept

uint	getWidth () const noexcept

uint	getHeight () const noexcept

double	getScaleFactor () const noexcept

const char *	getTitle () const noexcept

uintptr_t	getParentWindowHandle () const noexcept

uintptr_t	getTransientWindowId () const noexcept

void	hide ()

virtual void	close ()

void	setWidth (uint width)

void	setHeight (uint height)

void	setSize (uint width, uint height)

void	setTitle (const char *title)

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

void	show ()

void	setVisible (bool visible)

void	setTransientWindowId (uintptr_t winId)

Protected Member Functions
bool	startExternalProcess (const char *args[])

void	terminateAndWaitForExternalProcess ()

virtual void	sizeChanged (uint, uint)

virtual void	titleChanged (const char *)

virtual void	visibilityChanged (bool)

virtual void	transientParentWindowChanged (uintptr_t)

Friends
class	PluginWindow

class	UI

Detailed Description

External Window class.

This is a standalone TopLevelWidget/Window-compatible class, but without any real event handling. Being compatible with TopLevelWidget/Window, it allows to be used as DPF UI target.

It can be used to embed non-DPF things or to run a tool in a new process as the "UI". The uiIdle() function will be called at regular intervals to keep UI running. There are helper methods in place to launch external tools and keep track of its running state.

External windows can be setup to run in 3 different modes: Embed: Embed into the host UI, even-loop driven by the host. This is basically working as a regular plugin UI, as you typically expect them to. The plugin side does not get control over showing, hiding or closing the window (as usual for plugins). No restrictions on supported plugin format, everything should work. Requires DISTRHO_PLUGIN_HAS_EMBED_UI to be set to 1.

Semi-external: The UI is not embed into the host, but the even-loop is still driven by it. In this mode the host does not have control over the UI except for showing, hiding and setting transient parent. It is possible to close the window from the plugin, the host will be notified of such case. Host regularly calls isQuitting() to check if the UI got closed by the user or plugin side. This mode is only possible in LV2 plugin formats, using lv2ui:showInterface extension.

Standalone: The UI is not embed into the host or uses its event-loop, basically running as standalone. The host only has control over showing and hiding the window, nothing else. The UI is still free to close itself at any point. DPF will keep calling isRunning() to check if it should keep the event-loop running. Only possible in JACK and DSSI targets, as the UIs are literally standalone applications there.

Please note that for non-embed windows, you cannot show the window yourself. The plugin window is only allowed to hide or close itself, a "show" action needs to come from the host.

A few callbacks are provided so that implementations do not need to care about checking for state changes. They are not called on construction, but will be everytime something changes either by the host or the window itself.

Constructor & Destructor Documentation

◆ ExternalWindow() [1/2]

ExternalWindow::ExternalWindow ( )

inlineexplicit

Constructor.

◆ ExternalWindow() [2/2]

ExternalWindow::ExternalWindow ( const PrivateData & data )

inlineexplicit

Constructor for DPF internal use.

◆ ~ExternalWindow()

virtual ExternalWindow::~ExternalWindow ( )

inlinevirtual

Destructor.

Member Function Documentation

◆ isRunning()

virtual bool ExternalWindow::isRunning ( ) const

inlinevirtual

Check if main-loop is running. This is used under standalone mode to check whether to keep things running. Returning false from this function will stop the event-loop and close the window.

◆ isQuitting()

virtual bool ExternalWindow::isQuitting ( ) const

inlinevirtual

Check if we are about to close. This is used when the event-loop is provided by the host to check if it should close the window. It is also used in standalone mode right after isRunning() returns false to verify if window needs to be closed.

◆ getNativeWindowHandle()

virtual uintptr_t ExternalWindow::getNativeWindowHandle ( ) const

inlinevirtualnoexcept

Get the "native" window handle. This can be reimplemented in order to pass the native window to hosts that can use such informaton.

Returned value type 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.

Note: Only available to override if DISTRHO_PLUGIN_HAS_EMBED_UI is set to 1.

◆ focus()

virtual void ExternalWindow::focus ( )

inlinevirtual

Grab the keyboard input focus. Typically you would setup OS-native methods to bring the window to front and give it focus. Default implementation does nothing.

◆ isEmbed()

bool ExternalWindow::isEmbed ( ) const

inlinenoexcept

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

◆ isVisible()

bool ExternalWindow::isVisible ( ) const

inlinenoexcept

Check if this window is visible.

See also: setVisible(bool)

◆ isStandalone()

bool ExternalWindow::isStandalone ( ) const

inlinenoexcept

Whether this Window is running as standalone, that is, without being coupled to a host event-loop. When in standalone mode, isRunning() is called to check if the event-loop should keep running.

◆ getWidth()

uint ExternalWindow::getWidth ( ) const

inlinenoexcept

Get width of this window. Only relevant to hosts when the UI is embedded.

◆ getHeight()

uint ExternalWindow::getHeight ( ) const

inlinenoexcept

Get height of this window. Only relevant to hosts when the UI is embedded.

◆ getScaleFactor()

double ExternalWindow::getScaleFactor ( ) const

inlinenoexcept

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

◆ getTitle()

const char* ExternalWindow::getTitle ( ) const

inlinenoexcept

Get the title of the window previously set with setTitle(). This is typically displayed in the title bar or in window switchers.

◆ getParentWindowHandle()

uintptr_t ExternalWindow::getParentWindowHandle ( ) const

inlinenoexcept

Get the "native" window handle that this window should embed itself into. Returned value type 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.

◆ getTransientWindowId()

uintptr_t ExternalWindow::getTransientWindowId ( ) const

inlinenoexcept

Get the transient window that we should attach ourselves to. TODO what id? also NSView* on macOS, or NSWindow?

◆ hide()

void ExternalWindow::hide ( )

inline

Hide window. This is the same as calling setVisible(false). Embed windows should never call this!

See also: isVisible(), setVisible(bool)

◆ close()

virtual void ExternalWindow::close ( )

inlinevirtual

Hide the UI and gracefully terminate. Embed windows should never call this!

◆ setWidth()

void ExternalWindow::setWidth ( uint width )

inline

Set width of this window. Can trigger a sizeChanged callback. Only relevant to hosts when the UI is embedded.

◆ setHeight()

void ExternalWindow::setHeight ( uint height )

inline

Set height of this window. Can trigger a sizeChanged callback. Only relevant to hosts when the UI is embedded.

◆ setSize()

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

inline

Set size of this window using width and height values. Can trigger a sizeChanged callback. Only relevant to hosts when the UI is embedded.

◆ setTitle()

void ExternalWindow::setTitle ( const char * title )

inline

Set the title of the window, typically displayed in the title bar or in window switchers. Can trigger a titleChanged callback. Only relevant to hosts when the UI is not embedded.

◆ setGeometryConstraints()

void ExternalWindow::setGeometryConstraints	(	uint	minimumWidth,
		uint	minimumHeight,
		bool	keepAspectRatio = `false`
	)

inline

Set geometry constraints for the Window when resized by the user.

◆ show()

void ExternalWindow::show ( )

inline

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

See also: isVisible(), setVisible(bool)

◆ setVisible()

void ExternalWindow::setVisible ( bool visible )

inline

Set window visible (or not) according to visible.

See also: isVisible(), hide(), show()

◆ setTransientWindowId()

void ExternalWindow::setTransientWindowId ( uintptr_t winId )

inline

Called by the host to set the transient parent window that we should attach ourselves to. TODO what id? also NSView* on macOS, or NSWindow?

◆ sizeChanged()

virtual void ExternalWindow::sizeChanged	(	uint	,
		uint
	)

inlineprotectedvirtual

A callback for when the window size changes.

Note: WIP this might need to get fed back into the host somehow.

◆ titleChanged()

virtual void ExternalWindow::titleChanged ( const char * )

inlineprotectedvirtual

A callback for when the window title changes.

Note: WIP this might need to get fed back into the host somehow.

◆ visibilityChanged()

virtual void ExternalWindow::visibilityChanged ( bool )

inlineprotectedvirtual

A callback for when the window visibility changes.

Note: WIP this might need to get fed back into the host somehow.

◆ transientParentWindowChanged()

virtual void ExternalWindow::transientParentWindowChanged ( uintptr_t )

inlineprotectedvirtual

A callback for when the transient parent window changes.

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

distrho/extra/ExternalWindow.hpp

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ExternalWindow() [1/2]

◆ ExternalWindow() [2/2]

◆ ~ExternalWindow()

Member Function Documentation

◆ isRunning()

◆ isQuitting()

◆ getNativeWindowHandle()

◆ focus()

◆ isEmbed()

◆ isVisible()

◆ isStandalone()

◆ getWidth()

◆ getHeight()

◆ getScaleFactor()

◆ getTitle()

◆ getParentWindowHandle()

◆ getTransientWindowId()

◆ hide()

◆ close()

◆ setWidth()

◆ setHeight()

◆ setSize()

◆ setTitle()

◆ setGeometryConstraints()

◆ show()

◆ setVisible()

◆ setTransientWindowId()

◆ sizeChanged()

◆ titleChanged()

◆ visibilityChanged()

◆ transientParentWindowChanged()