Wwise SDK 2021.1.14

This page will guide you through the different elements of a Windows graphical user interface (GUI) implementation.

Note: The Wwise Authoring application on macOS runs through Crossover, a bridge layer based on the open source project Wine. By creating a GUI implementation for Windows, this same implementation will run on macOS using this solution.

The base class AK::Wwise::Plugin::GUIWindows provides methods to implement that offer a way for Wwise to instantiate specific types of dialogs with controls bound to the plug-in's properties. A standard Win32 window procedure (a "WindowProc") is provided to allow your plug-in to act upon Windows events targeted at your plug-in view instance.

The Wwise Authoring application instantiates your plug-in GUI in the following way:

Wwise requests a type of dialog to be instantiated by your plug-in by calling AK::Wwise::Plugin::GUIWindows::GetDialog() (See Dialog Acquisition).
If the dialog type is supported by the plug-in's frontend, the plug-in returns the resource dialog ID corresponding to the type, along with an optional table of property bindings that tells Wwise which control ID corresponds to which property key in its property set (as defined in the plug-in XML, see Wwise Plug-in XML Description Files for more details).
The dialog is instantiated by Wwise using the resource handle provided by the plug-in (See Resource Handle).
Windows starts calling the WindowProc with events such as WM_INITDIALOG.

The following sections describe how to implement each method.

Using MFC

The Wwise Authoring GUI on Windows is built with the Microsoft Foundation Classes (MFC). While using MFC is optional for your plug-in, if you wish to do so you will need to initialize the library. This is provided through the service AK::Wwise::Plugin::PluginMFCWindows. Make sure to make it the first base class so that it is initialized before anything else.

class FrontendSourcePluginMFC
:   public AK::Wwise::Plugin::PluginMFCWindows<>
,   public AK::Wwise::Plugin::GUIWindows
{};

Note: Do not derive from this base class in the backend part of your plug-in, as it should not require MFC or any other GUI-related library.

Resource Handle

The resource handle is of type HINSTANCE and corresponds to your dynamic library holding the resource data compiled from a .rc file. It can be created using Microsoft Visual Studio and holds your custom dialogs and their content. For more information on resource files, consult the Microsoft documentation about how to create resource files.

The default implementation provides the module instance from a builtin injected by the MSVC linker.

// GUIWindows.h
// Acquire the module instance from the Microsoft linker

extern "C" IMAGE_DOS_HEADER __ImageBase;
 

virtual HINSTANCE GetResourceHandle() const

{
    return (HINSTANCE)&__ImageBase;
}

You don't need to implement this function unless a different module owns your dialog resources.

To create a resource file (.rc), refer to How to Create a Resource File For your Plug-in.

Dialog Acquisition

There exists two types of dialogs currently defined by Wwise in AK::Wwise::Plugin::eDialog :

SettingsDialog: Main plug-in dialog used for the Source or Effect Editor
ContentsEditorDialog: Small dialog used by Source plug-ins only in the Contents Editor

The dialog that is provided back to Wwise is then instantiated using the provided Resource Handle. To bind properties to the controls of your dialogs, a table that maps control IDs to the property names as found in the XML definition of your plug-in is used. This table is created using macros as follows:

constexpr auto propertyKey = u8"MyProperty";
 
AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE(PropertyTable)
    AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(IDC_MYPROPERTY_EDIT, propertyKey)

AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()

In this example, the table maps the control IDC_MYPROPERTY_EDIT (from the resource.h file accompanying the .rc file) to the property MyProperty, which must correspond to a property defined in the plug-in's XML definition.

This instantiates a variable PropertyTable that can then be forwarded to the Wwise Authoring application on GetDialog():

bool FrontendSourcePlugin::GetDialog(
    AK::Wwise::Plugin::eDialog in_eDialog,
    UINT& out_uiDialogID,
    AK::Wwise::Plugin::PopulateTableItem*& out_pTable) const

{
    switch (in_eDialog)
    {
    case SettingsDialog:
        out_uiDialogID = IDD_SOURCEPLUGIN_SETTINGS;
        out_pTable = ToneGenProp;
        return true;
 
    case ContentsEditorDialog:
        out_uiDialogID = IDD_SOURCEPLUGIN_CONTENTS;
        out_pTable = nullptr;
        return true;
    }
 
    return false;
}

Returning false in this function will simply not instantiate a dialog and a default one will be instantiated in its place.

Refer to Wwise Plug-in Dialog Reference for a complete description of the controls you can use in your dialog, how to bind them to properties, and so on.

Windows Events Handling through WindowProc

If UI changes require specific actions, such as enabling or disabling controls, you can carry these out by interpreting the window messages received in the AK::Wwise::Plugin::GUIWindows::WindowProc() function:

// Standard window function allowing the user to intercept whatever message is of interest when implementing UI behavior.

bool FrontendSourcePlugin::WindowProc(
    AK::Wwise::Plugin::eDialog in_eDialog,
    HWND in_hWnd,
    UINT in_message,
    WPARAM in_wParam,
    LPARAM in_lParam,
    LRESULT& out_lResult)
{
    if ( in_message == WM_INITDIALOG )
    {
        // Perform anything you need to do on dialog window initialization ...
    }
 
    // For example, catch window command actions (only for the main dialog) to enable/disable controls
    else if ( in_eDialog == SettingsDialog && in_message == WM_COMMAND )
    {
        // Notification code
        switch ( HIWORD( in_wParam ) )
        {
        case BN_CLICKED:
            // Check which button was clicked
            switch ( LOWORD( in_wParam ) )
            {
            case IDC_CHECK_SWEEPFREQ:
                // Verify if check box was enabled
                if ( IsDlgButtonChecked( in_hWnd, IDC_CHECK_SWEEPFREQ ) == BST_CHECKED )
                {
                    // Enable some controls ...
                }
                else if ( IsDlgButtonChecked( in_hWnd, IDC_CHECK_SWEEPFREQ ) == BST_UNCHECKED )
                {
                    // Disable some controls ...
                }
                break;
            }
        } // End switch hi word (notification code)
 
    } // End command window event
 
    // Return false to let the parent window deal with the message.
    // Return true for messages you don't want the parent window to handle.
 
    return false;
}

Displaying Help for a Plug-in

When a Wwise user clicks on the '?' icon in a plug-in's dialog title bar, AK::Wwise::Plugin::GUIWindows::Help() is called on that plug-in's frontend. You can implement Help with various tools, including HTMLHelp, WinHelp, or a third-party Help browser. The function receives a window handle that can be used as the parent for any window you want to display. The AK::Wwise::Plugin::eDialog parameter allows you to choose a specific Help topic to match the dialog the Wwise user currently has open. This function must return true if you handled the Help request, or false otherwise, in which case Wwise will display a Help topic related to the Plug-in Manager.

Note: As previously mentioned, source plug-ins have two dialogs. The AK::Wwise::Plugin::eDialog parameter should be used if your source plug-in has separate Help topics for its two dialogs.

Here is an example of a source plug-in that uses HTML help, with MFC providing the path to the file:

// Implement online help when the user clicks on the "?" icon

bool FrontendSourcePluginMFC::Help(HWND in_hWnd, AK::Wwise::Plugin::eDialog in_eDialog) const

{
    AFX_MANAGE_STATE( ::AfxGetStaticModuleState() );
 
    DWORD dwTopic = ONLINEHELP::Tone_Generator_Settings;
    if ( in_eDialog == AK::Wwise::Plugin::ContentsEditorDialog )
        dwTopic = ONLINEHELP::Tone_Generator_ContentsEditor;
 
    ::HtmlHelp(
        NULL, // <<< Must be NULL to launch on the correct parent window
        AfxGetApp()->m_pszHelpFilePath,
        HH_HELP_CONTEXT,
        dwTopic
    );
 
    return true;
}

Caution: The AK::Wwise::Plugin::GUIWindows::Help() method should NOT call AfxGetApp()->HtmlHelp(). It will launch the Help window from the wrong parent window which will make floating views behave unexpectedly. Instead, use HtmlHelp() with a NULL window handle, as shown the example above.