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 and toolbar hosts.

Remark

The host must not be dialog managed.

Remark

Hosts must forward the following messages to hosted windows:

  • WM_SETTINGCHANGE

  • WM_SYSCOLORCHANGE

  • WM_TIMECHANGE

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 this host about changed size limits of a hosted window.

See also

uie::size_limit_flag_t

Parameters:

  • wnd – [in] window handle of the panel or toolbar

  • flags – [in] a combination of uie::size_limit_flag_t flags indicating which size limits changed

Pre:

May only be called by a hosted window.

virtual unsigned is_resize_supported(HWND wnd) const = 0

Get whether the host supports resizing hosted windows.

See also

uie::resize_flag_t

Parameters:

wnd – [in] handle to the window to test

Returns:

combination of uie::resize_flag_t flags to indicate whether the width or height can be modified

Pre:

May only be called by a hosted window.

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

Ask for your window to be resized.

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 of those, do not change the size at all.

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

Instantiate the 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 window.

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

Returns:

whether keyboard shortcuts should be processed

virtual bool is_visible(HWND wnd) const = 0

Query if a hosted window is visible.

Note

A hidden window may still have the WS_VISIBLE style if the host uses another mechanism to hide panels.

Parameters:

wnd – [in] handle to the window to test

Pre:

May only be called by a hosted window.

Returns:

whether window is visible.

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

Query if a hosted 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 window.

Returns:

whether the required visibility can be set.

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

Hide or show a hosted 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 window.

Returns:

whether the requested visibility was set

virtual void relinquish_ownership(HWND wnd) = 0

Relinquish ownership of a window instance.

See also

window::create_or_transfer_window

Note

This method mainly relates to legacy functionality. Do not call it outside an implementation of window::create_or_transfer_window().

Parameters:

wnd – [in] window handle of the panel or toolbar

Pre:

May only be called by a hosted window.

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(window_host)
class window_host_with_control : public uie::window_host

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

Note

This service relates to legacy functionality. It is only implemented by the host for the toolbars area.

Public Functions

virtual unsigned get_supported_types() const = 0

Get supported window types.

See also

uie::window_type_t

Returns:

a combination of uie::window_type_t 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 hosted window.

Creates an instance of the specified windows and inserts it into the host’s client area. Single-instance windows should remove themselves from the old host (if there is one).

See also

is_available, window::init_or_take_ownership

Parameters:

  • guid – [in] unique ID of the window 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 an existing instance of a hosted window.

Inserts the given window instance into the host’s client area.

See also

is_available, window::init_or_take_ownership

Parameters:

  • p_ext – [in] pointer to the window 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 window 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.

Constants

enum uie::size_limit_flag_t

Flags indicating a change of a size limit.

Combine multiple flags using bitwise or, if more than one size limit changed.

See also

window_host::on_size_limit_change()

Values:

enumerator size_limit_minimum_width

The minimum width changed.

enumerator size_limit_maximum_width

The maximum width changed.

enumerator size_limit_minimum_height

The minimum height changed.

enumerator size_limit_maximum_height

The maximum height changed.

enumerator size_limit_all

All size limits changed.

enum uie::resize_flag_t

Flags indicating whether the size and height parameters are valid.

Combine multiple flags using bitwise or.

See also

uie::window_host::is_resize_supported(), uie::window_host::request_resize()

Values:

enumerator size_width

The width parameter is valid.

enumerator size_height

The height parameter is valid.