Window host¶

These interfaces are used by components that can host other panels and toolbars.

Window host¶

class window_host : public service_base¶

Interface for window_host service.

This interface is to be implemented by panel hosts.

Remark

The host may not be dialog managed.

Remark

Hosts must forward the following messages to hosted windows:

WM_SETTINGCHANGE
WM_SYSCOLORCHANGE

Subclassed by uie::window_host_ex, uie::window_host_with_control

Public Functions

virtual const GUID &get_host_guid() const = 0¶

Get the unique ID of the host.

This GUID is used to identify a specific host.

Returns:: host GUID

virtual void on_size_limit_change(HWND wnd, unsigned flags) = 0¶

Notify host about changed size limits of a hosted extension.

See also

uie::size_limit_flag_t

Parameters:

wnd – [in] window handle of the extension’s window
flags – [in] a combination of SLC_* flags indicating which size limits changed

Pre:

May only be called by a hosted UI extension.

virtual unsigned is_resize_supported(HWND wnd) const = 0¶

Called by panels hosted by this host to find out whether the host supports resizing.

See also

uie::resize_flag_t

Parameters:: wnd – [in] handle to the window to test
Returns:: combination of uie::size_height and uie::size_width to indicate whether the width or height can be modified
Pre:: May only be called by a hosted UI extension.

virtual bool request_resize(HWND wnd, unsigned flags, unsigned width, unsigned height) = 0¶

Called by ui extension hosted by this host to resize your window.

Implementers: If you cannot fully meet the request, do not attempt to partially fulfil it. For example, if a request is made to modify both the width and height but you can only modify one if those.

See also

uie::resize_flag_t

Parameters:: wnd – [in] handle to the window to test
Returns:: combination of uie::size_height and uie::size_width to indicate whether the width or height is being modified

virtual bool override_status_text_create(service_ptr_t<ui_status_text_override> &p_out) = 0¶

Instantiates ui_status_text_override service, that can be used to display status messages.

Implementers: if you wish to display status bar text in the main window, simply use ui_control::override_status_text_create. Hybrid panel-hosts can forward the call to their host. If alternatively you wish to display the text in your own status area, you are responsible for implementing ui_status_text_override. Be sure to obey certain conventions:

Releasing the ui_status_text_override object should restore the text if revert_text has not been called.

Parameters:: p_out – [out] receives new ui_status_text_override instance.
Pre:: May only be called by a hosted UI extension.
Returns:: true on success, false on failure (out of memory / no GUI loaded / etc)

inline virtual bool get_keyboard_shortcuts_enabled() const¶

Query if keyboard shortcuts should be processed.

Use this to determine, if keyboard shortcuts should be processed. Do not process them, if this method returns false. Shortcuts can be processed using the keyboard_shortcut_manager service from the foobar2000 SDK.

Keyboard shortcuts would not be processed, for example, if the panel is hosted in a popup window. In this case the method returns false.

If the method does return true, whether you process keyboard shortcuts will depend on the type of functionality your control offers. For example, in a edit control you may wish not to process keyboard shortcuts.

The user must be able to navigate using the tab key. If VK_TAB is not processed by the keyboard_shortcut_manager and the TAB press is not being handled by the dialog manager, you should use g_on_tab() to change to the next control.

Usage example

case WM_KEYDOWN:
    if (p_host->get_keyboardshortcuts_enabled() &&
static_api_ptr_t<keyboard_shortcut_manager>()->on_keydown_xxxx(wp)) break; else if (wp == VK_TAB)
window::g_on_tab(wnd); break; 

Pre:: May only be called by a hosted UI extension.
Returns:: whether keyboard shortcuts should be processed

virtual bool is_visible(HWND wnd) const = 0¶

Query if extension window is visible.

An extension that is not visible does not imply that its window has been hidden using ShowWindow

Parameters:: wnd – [in] handle to the window to test
Pre:: May only be called by a hosted UI extension.
Returns:: whether window is visible.

virtual bool is_visibility_modifiable(HWND wnd, bool desired_visibility) const = 0¶

Query if extension window can be hidden or shown.

Parameters:

wnd – [in] handle to the window to test
desired_visibility – [in] whether you want the window to be visible

Pre:

May only be called by a hosted UI extension.

Returns:

whether the required visiblility can be set.

virtual bool set_window_visibility(HWND wnd, bool visibility) = 0¶

Hides or shows extension window.

Parameters:

wnd – [in] handle to the window to test
visibility – [in] whether you want the window to be visible

Pre:

May only be called by a hosted UI extension.

Returns:

whether the required visiblility was be set.

virtual void relinquish_ownership(HWND wnd) = 0¶

Relinquish ownership of a UI extension instance.

Call this to remove control of an extension window from the host. The host will not destroy the window as a result of this call. However, the window may be destroyed, if the host destroys the containing winow, so be sure to call SetParent first.

Reasons for calling this method include: another host tries to take ownership of an existing extension instance, the window should be destroyed/closed, or the window is to be turned into a popup dialog.

See also

window::create_or_transfer_window

Parameters:: wnd – [in] window handle of the extension’s window
Pre:: May only be called by a hosted UI extension.

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(window_host)¶

class window_host_with_control : public uie::window_host ¶

Sub-class of window_host, providing methods for external control.

In addition to the methods exposed through the window_host interface, this interface provides information about the host and its state as well as methods to manage hosted extensions.

Public Functions

virtual unsigned get_supported_types() const = 0¶

Get supported UI extension types.

See also

window_flag::window_type

Returns:: a combination of window_flag::TYPE_* flags to indicate recommended types for the host

virtual void insert_extension(const GUID &guid, unsigned height, unsigned width) = 0¶

Insert new instance of a UI extension.

Creates an instance of the specified extension and inserts it into the host’s client area. Single-instance extensions should removed themselves from the old host, if any.

See also

is_available, window::init_or_take_ownership

Parameters:

guid – [in] unique ID of the UI extension to be inserted
height – [in] desired height of the new panel
width – [in] desired width of the new panel

Pre:

May only be called, if is_available() returned true.

virtual void insert_extension(window_ptr &p_ext, unsigned height, unsigned width) = 0¶

Insert existing instance of a UI extension.

Inserts the given UI extension instance into the host’s client area.

See also

is_available, window::init_or_take_ownership

Parameters:

p_ext – [in] pointer to the UI extension instance to be inserted
height – [in] desired height of the new panel
width – [in] desired width of the new panel

Pre:

May only be called, if is_available() returned true.

virtual void get_name(pfc::string_base &out) const = 0¶

Get the name of the host.

Get a user-readable name of the host.

See also

get_host_guid

Warning

Do not use the name to identify hosts; use host GUIDs instead.

Parameters:: out – [out] receives the name of the host, e.g. “My UI/Sidebar”

virtual bool is_available() const = 0¶

Get availability of the host.

See also

insert_extension(const GUID &, unsigned, unsigned), insert_extension(window *, unsigned, unsigned)

Returns:: true if it is possible to insert a UI extension into the host.

FB2K_MAKE_SERVICE_INTERFACE(window_host_with_control, window_host)¶

Factories¶

template<class T> class window_host_factory : public service_factory_t<T>¶

Service factory for window hosts.

Usage example

static window_host_factory< my_window_host > foo_host;

template<class T> class window_host_factory_single : public service_factory_single_t<T>¶

Service factory for window hosts.

Usage example

static window_host_factory< my_window_host > foo_host;

The static instance of my_window_host can be accessed as foo_host.get_static_instance().

Public Functions

inline operator uie::window_host_ptr()¶

template<class T> class window_host_factory_transparent_single : public service_factory_single_transparent_t<T>¶

Service factory for window hosts.

Usage example

static window_host_factory_transparent< my_window_host > foo_host2;

The static instance of my_window_host can be accessed as foo_host2.