Columns UI SDK  6.5
Public Member Functions | List of all members
ui_extension::window_host Class Referenceabstract

Interface for window_host service. More...

#include <window_host.h>

Inheritance diagram for ui_extension::window_host:
ui_extension::window_host_ex ui_extension::window_host_with_control

Public Member Functions

virtual const GUID & get_host_guid () const =0
 Get the unique ID of the host. More...
 
virtual void on_size_limit_change (HWND wnd, unsigned flags)=0
 Notify host about changed size limits of a hosted extension. More...
 
virtual unsigned is_resize_supported (HWND wnd) const =0
 Called by panels hosted by this host to find out whether the host supports resizing. More...
 
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. More...
 
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. More...
 
virtual bool get_keyboard_shortcuts_enabled () const
 Query if keyboard shortcuts should be processed. More...
 
virtual bool is_visible (HWND wnd) const =0
 Query if extension window is visible. More...
 
virtual bool is_visibility_modifiable (HWND wnd, bool desired_visibility) const =0
 Query if extension window can be hidden or shown. More...
 
virtual bool set_window_visibility (HWND wnd, bool visibility)=0
 Hides or shows extension window. More...
 
virtual void relinquish_ownership (HWND wnd)=0
 Relinquish ownership of a UI extension instance. More...
 
 FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT (window_host)
 

Detailed Description

Interface for window_host service.

This interface is to be implemented by panel hosts.

Remarks
The host may not be dialog managed.
Hosts must forward the following messages to hosted windows:
  • WM_SETTINGCHANGE
  • WM_SYSCOLORCHANGE

Member Function Documentation

ui_extension::window_host::FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT ( window_host  )
virtual const GUID& ui_extension::window_host::get_host_guid ( ) const
pure virtual

Get the unique ID of the host.

This GUID is used to identify a specific host.

Returns
host GUID
virtual bool ui_extension::window_host::get_keyboard_shortcuts_enabled ( ) const
inlinevirtual

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;
Precondition
May only be called by a hosted UI extension.
Returns
whether keyboard shortcuts should be processed
virtual unsigned ui_extension::window_host::is_resize_supported ( HWND  wnd) const
pure virtual

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

Parameters
[in]wndhandle 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
Precondition
May only be called by a hosted UI extension.
See also
ui_extension::resize_flag_t
virtual bool ui_extension::window_host::is_visibility_modifiable ( HWND  wnd,
bool  desired_visibility 
) const
pure virtual

Query if extension window can be hidden or shown.

Parameters
[in]wndhandle to the window to test
[in]desired_visibilitywhether you want the window to be visible
Precondition
May only be called by a hosted UI extension.
Returns
whether the required visiblility can be set.
virtual bool ui_extension::window_host::is_visible ( HWND  wnd) const
pure virtual

Query if extension window is visible.

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

Parameters
[in]wndhandle to the window to test
Precondition
May only be called by a hosted UI extension.
Returns
whether window is visible.
virtual void ui_extension::window_host::on_size_limit_change ( HWND  wnd,
unsigned  flags 
)
pure virtual

Notify host about changed size limits of a hosted extension.

Precondition
May only be called by a hosted UI extension.
Parameters
[in]wndwindow handle of the extension's window
[in]flagsa combination of SLC_* flags indicating which size limits changed
See also
ui_extension::size_limit_flag_t
virtual bool ui_extension::window_host::override_status_text_create ( service_ptr_t< ui_status_text_override > &  p_out)
pure virtual

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.
Precondition
May only be called by a hosted UI extension.
Parameters
[out]p_outreceives new ui_status_text_override instance.
Returns
true on success, false on failure (out of memory / no GUI loaded / etc)
virtual void ui_extension::window_host::relinquish_ownership ( HWND  wnd)
pure virtual

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.

Precondition
May only be called by a hosted UI extension.
Parameters
[in]wndwindow handle of the extension's window
See also
window::create_or_transfer_window
virtual bool ui_extension::window_host::request_resize ( HWND  wnd,
unsigned  flags,
unsigned  width,
unsigned  height 
)
pure virtual

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.

Parameters
[in]wndhandle 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
See also
ui_extension::resize_flag_t
virtual bool ui_extension::window_host::set_window_visibility ( HWND  wnd,
bool  visibility 
)
pure virtual

Hides or shows extension window.

Parameters
[in]wndhandle to the window to test
[in]visibilitywhether you want the window to be visible
Precondition
May only be called by a hosted UI extension.
Returns
whether the required visiblility was be set.

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