IApplicationDesignModeSettings interface (shobjidl_core.h)

Article
03/09/2022

Enables development tool applications to dynamically spoof system and user states, such as native display resolution, device scale factor, and application view state, for the purpose of testing Windows Store apps running in design mode for a wide range of form factors without the need for the actual hardware. Also enables testing of changes in normally user-controlled state to test Windows Store apps under a variety of scenarios.

Inheritance

The IApplicationDesignModeSettings interface inherits from the IUnknown interface. IApplicationDesignModeSettings also has these types of members:

Methods

The IApplicationDesignModeSettings interface has these methods.


IApplicationDesignModeSettings::ComputeApplicationSize Gets the size of the Windows Store app, based on the current set of spoofed settings.
IApplicationDesignModeSettings::IsApplicationViewStateSupported Determines whether a particular application view state is supported for specific spoofed display size and scale factor settings.
IApplicationDesignModeSettings::SetApplicationViewState Sets a spoofed application view state (full-screen landscape, full-screen portrait, filled, or snapped) to be used for a Windows Store app running in design mode.
IApplicationDesignModeSettings::SetNativeDisplaySize Sets a spoofed native display size to be used for a Windows Store app running in design mode.
IApplicationDesignModeSettings::SetScaleFactor Sets a spoofed device scale factor to be used for a Windows Store app running in design mode.
IApplicationDesignModeSettings::TriggerEdgeGesture Sends a spoofed edge gesture event to the proxy core window on the caller's thread. This gesture toggles the app's app bar, if the app supports one. The caller can specify the type of input that triggered the edge gesture.

Remarks

This interface is acquired by cocreating CLSID_ApplicationDesignModeSettings.

Users will normally follow a usage pattern similar to the following:

Call CoCreateInstance with CLSID_ApplicationDesignModeSettings to create the application design mode settings object on a thread in the Windows Store app process.
Call QueryInterface on the application design mode settings object to obtain an IInitializeWithWindow object.
Call the Initialize method of the IInitializeWithWindow object, passing in the HWND for the proxy core window. This must be done before any "set" methods are called, and will succeed only once per process. For a code example, see [Display WinRT UI objects that depend on CoreWindow](/windows/apps/develop/ui-input/display-ui-objects#winui-3-with-c).
Call QueryInterface for IApplicationDesignModeSettings and spoof the necessary test state by calling its appropriate methods (SetNativeDisplaySize, SetScaleFactor, etc.). These methods will trigger the appropriate Windows Runtime events to fire for the Windows Store app.
Call the ComputeApplicationSize method to determine the proper size for the app, based on the currently spoofed state. All layout "set" methods must have already been called or this call will fail. The developer tool application is responsible for positioning and sizing the app windows, when appropriate.

When to implement

Do not implement this interface; the implementation is supplied with Windows.

When to use

Use the methods of this interface to test your Windows Store app under various spoofed configurations and scenarios.

Examples

This example shows the methods of this interface in use.


IApplicationDesignModeSettings *pDesignModeSettings;

// CoCreate the design mode settings object
HRESULT hr = CoCreateInstance(CLSID_ApplicationDesignModeSettings, nullptr, CLSCTX_INPROC, IID_PPV_ARGS(&pDesignModeSettings));
if (SUCCEEDED(hr))
{
    IInitializeWithWindow *pInitializeWithWindow;
    hr = pDesignModeSettings->QueryInterface(IID_PPV_ARGS(&pInitializeWithWindow);
    if (SUCCEEDED(hr))
    {
        // Before we spoof any state, we must first initialize the design
        // mode settings object with a proxy core window. Since apps
        // running in design mode don't have an actual core window, we must
        // supply an HWND that can be used as a proxy.
        hr = pInitializeWithWindow->Initialize(hwndProxyCoreWindow);
        pInitializeWithWindow->Release();
    }

    if (SUCCEEDED(hr))
    {
        // Verify that our desired spoofed settings are supported.
        SIZE sizeNativeDisplay = {1366, 768};
        SCALE_FACTOR scaleFactor = SCALE_100_PERCENT;
        APPLICATION_VIEW_STATE viewState = AVS_FULLSCREEN_LANDSCAPE;
        BOOL fSupported;
        hr = pDesignModeSettings->IsApplicationViewStateSupported(viewState,
                                                                  sizeNativeDisplay,
                                                                  scaleFactor,
                                                                  &fSupported);
    }

    if (SUCCEEDED(hr) && fSupported))
    {
        // Set the spoofed native display size.
        hr = pDesignModeSettings->SetNativeDisplaySize(sizeNativeDisplay);

        if (SUCCEEDED(hr))
        {
            // Set the spoofed scale factor to 100%.
            hr = pDesignModeSettings->SetScaleFactor(SCALE_100_PERCENT);
        }

        if (SUCCEEDED(hr))
        {
            // Set the spoofed application view state to full-screen landscape.
            hr = pDesignModeSettings->SetApplicationViewState(AVS_FULLSCREEN_LANDSCAPE);
        }

        if (SUCCEEDED(hr))
        {
            // Now that all the necessary state has been spoofed, calculate
            // the size that the app should occupy.
            SIZE sizeApplication;
            hr = pDesignModeSettings->ComputeApplicationSize(&sizeApplication);
        }
    }

    pDesignModeSettings->Release();
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)

Share via