Window¶

These interfaces are used to implement panels and toolbars.

Window¶

class window : public uie::extension_base ¶

Base class for window (panel or toolbar) services (formerly known as UI extensions).

Subclassed by uie::container_ui_extension_t< W, T >, uie::container_uie_window_v3_t< Base >, uie::menu_window, uie::playlist_window, uie::splitter_window

Public Functions

virtual const bool get_is_single_instance() const = 0¶: Get whether is a single-instance window (as opposed to a multi-instance window).

Note

Do not explicitly override. The service factory implements this method.

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

Get the category of this window.

Pre-defined categories you can use are "Toolbars", "Panels", "Splitters", "Playlist views" and "Visualisations".

See also

uie::window_type_t

Returns:: one or more uie::window_type_t flags, combined using bitwise OR

inline virtual bool get_prefer_multiple_instances() const¶

Get whether the panel prefers to be created in multiple instances in the toolbars.

For example, this could be a spacer panel.

Returns:: true if the panel prefers to be created in multiple instances

virtual bool is_available(const window_host_ptr &p_host) const = 0¶

Get whether the window is available to be inserted in a particular host.

For multi-instance windows, you can always return true.

For single-instance windows, if an existing host has been assigned to the window, return false if its GUID is equal to the GUID of p_host. Otherwise, return `true.

Returns:: whether this instance can be created in or moved to the given host

virtual HWND create_or_transfer_window(HWND wnd_parent, const window_host_ptr &p_host, const ui_helpers::window_position_t &p_position = ui_helpers::window_position_null) = 0¶

Create the panel or toolbar window or transfer the window to a new host.

A canonical implementation of this method is similar to:

if (m_wnd) {
    ShowWindow(m_wnd, SW_HIDE);
    SetParent(m_wnd, parent);
    m_host->relinquish_ownership(get_wnd());
    m_host = host;
    SetWindowPos(get_wnd(), nullptr, position.x, position.y, position.cx, position.cy, SWP_NOZORDER);
} else {
    m_host = host;
    m_wnd = CreateWindowEx(ex_styles, class_name, window_name, styles,
        position.x, position.y, position.cx, position.cy, parent,
        reinterpret_cast<HMENU>(0), core_api::get_my_instance(), nullptr);
}

return m_wnd;

Note that the case where this method is called to transfer an already-created window to a new host is only relevant for single-instance windows. For multi-instance windows, you can instead call uBugCheck() or do something similar if that happens.

Remark

The window must have the WS_CHILD window style. It must not have the WS_POPUP, WS_CAPTION or WS_VISIBLE styles.
Do not make the window visible – the host will do this when ready.
Use the WS_EX_CONTROLPARENT extended style if the window has child windows that receive keyboard input, and you want them to be included in tab operations in the host window.
Do not directly create a common control as your window. You must create an intermediate window to contain any common controls (or other child windows) that communicate to the parent window via WM_COMMAND and WM_NOTIFY window messages.
If this window is not itself hosting another panel or toolbar, it can be dialog managed (i.e. using modeless_dialog_manager) if required.
The window must have a dialog item ID of 0.

Parameters:

wnd_parent – [in] Handle to the window to use as the parent for your window
p_host – [in] Pointer to the host that creates the extension. This parameter may not be NULL.
p_position – [in] Initial position of the window

Pre:

May only be called if is_available() returned true.

Returns:

Window handle of the panel or toolbar window, or nullptr on failure

virtual void destroy_window() = 0¶

Destroy the window.

Typically, you would call DestroyWindow() in this method, and clean up any resources that are no longer required.

In normal circumstances, the window will always be destroyed using this method.

virtual HWND get_wnd() const = 0¶

Get the extension window handle.

Pre:: May only be called on hosted extensions.
Returns:: Window handle of the extension window (or nullptr if the window has not been created)

inline virtual void get_size_limits(size_limit_t &p_out) const¶

This function is not used.

Note

Handle the WM_GETMINMAXINFO message to indicate size limits to the host.

Parameters:: p_out – [out] Not used.

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(window)¶

Public Static Functions

static inline bool create_by_guid(const GUID &guid, window_ptr &p_out)¶

Create an extension by ID.

Parameters:

guid – [in] GUID of a ui_extension
p_out – [out] Receives a pointer to the window.

Returns:

true if the window was found and instantiated. You may assume that if the method returns true, p_out is valid.

static HWND g_on_tab(HWND wnd_focus)¶

Helper function. Handle a press of the Tab key by focusing the next or previous tabbable window.

Parameters:: wnd_focus – [in] Handle to the currently focused window
Returns:: The handle to the window that was activated, or nullptr if the focus was not changed.

static bool g_process_keydown_keyboard_shortcuts(WPARAM wp)¶

Helper function. Process keyboard shortcuts using keyboard_shortcut_manager_v2::process_keydown_simple(). Requires foobar2000 >= 0.9.5.

Parameters:: wp – [in] Key down message WPARAM value.
Returns:: If a shortcut was executed.

Playlist view¶

class playlist_window : public uie::window ¶

Subclass of uie::window for playlist views.

Public Functions

virtual void set_focus() = 0¶

Focus the playlist window.

Pre:: May only be called on hosted extensions.

FB2K_MAKE_SERVICE_INTERFACE(playlist_window, window)¶

Menu¶

class menu_window : public uie::window ¶

Subclass of uie::window, specifically for menu bars.

Subclassed by uie::menu_window_v2

Public Functions

virtual bool on_menuchar(unsigned short chr) = 0¶

Handle menu accelerator key presses (e.g. Alt+F for the File menu).

Called by the host in its WM_MENUCHAR handler to notify extension that a menu was requested to be opened.

You should check whether the accelerator key pressed is one of yours.

Parameters:: chr – [in] character that was pressed
Pre:: May only be called on hosted extensions.
Returns:: whether you claimed the accelerator key, and showed/will show your menu

virtual void set_focus() = 0¶

Focus the menu window.

Pre:: May only be called on hosted extensions.

virtual bool is_menu_focused() const = 0¶

Retrieve whether the menu has the keyboard focus.

Pre:: May only be called on hosted extensions.
Returns:: whether your menu has keyboard focus

virtual void show_accelerators() = 0¶

Show underlines under characters indicating menu accelerators.

Remark

Relevant when SystemParametersInfo() returns FALSE for SPI_GETKEYBOARDCUES.

Remark

Do not change the state within this function call. Use PostMessage().

Implementation example

PostMessage(wnd_menu, WM_UPDATEUISTATE, MAKEWPARAM(UIS_CLEAR , UISF_HIDEACCEL), 0);

virtual void hide_accelerators() = 0¶

Indicates that you should stop underlining menu access keys in your menu.

Remark

Applicable only if your menu underlines menu access keys only when activated by the keyboard. This is typically determined by the SPI_GETKEYBOARDCUES system parameter.

Remark

Do not change the state within this function call. Use PostMessage().

Implementation example

 * if (GetFocus() == m_wnd)
    return;

BOOL show_keyboard_cues{TRUE};
SystemParametersInfo(SPI_GETKEYBOARDCUES, 0, &show_keyboard_cues, 0);
PostMessage(wnd_menu, WM_UPDATEUISTATE, MAKEWPARAM(show_keyboard_cues ? UIS_CLEAR : UIS_SET, UISF_HIDEACCEL), 0);

FB2K_MAKE_SERVICE_INTERFACE(menu_window, window)¶

class menu_window_v2 : public uie::menu_window ¶

Subclass of uie::menu_window, with additional functions.

Public Functions

virtual HWND get_previous_focus_window() const = 0¶

Retrieve the handle of the window that was focused before the menu was.

Implementations should track the previously focused window using the WM_SETFOCUS and WM_KILLFOCUS window messages.

Pre:: May only be called on hosted extensions.
Returns:: HWND of the previously focused window, or nullptr if no such window or the menu bar is not currently focused.

FB2K_MAKE_SERVICE_INTERFACE(menu_window_v2, menu_window)¶

Factories¶

template<class T> class window_factory : public service_factory_base_t<window>¶

Service factory for multiple instance windows.

Usage example

* static window_factory<my_uie> foo_extension;

Public Functions

inline window_factory()¶

inline ~window_factory()¶

inline void instance_create(service_ptr_t<service_base> &p_out) override¶

Constants¶

enum uie::window_type_t¶

Flags indicating the type of the UI extension.

Remark

Combine multiple flags using bitwise or, if an extension supports more than one type.