Creating a Forms Manager

A Forms Manager is an ActiveX® control container that provides speech and keyboard navigation, input to all controls, and common services such as visual Help and application menus. A Forms Manager passes messages from one form to another and from the OS to a form.

An Auto PC application uses a Forms Manager to handle its forms, even if it uses only one form. The device context handle is derived from the form. An Auto PC application is composed of at least three COM objects:

• A Forms Manager object controls application-wide functionality and its forms. You can only have one Forms Manager.
• A Form object holds the controls for a screen. You can have multiple forms.
• A Control object is placed on a form and displays information or receives user input. You can have multiple controls per form.

Create each object with CoCreateInstance and access its other interfaces through the IUnknown interface. A Forms Manager’s primary interface is IfmManage, which provides an application with methods and common services for an application and its forms. In addition, a Forms Manager exposes the following specialized interfaces:

• IASActiveForms, which manages form focus when an application has multiple forms
• IfmSystem, which contains system-level methods

The following illustration shows an Auto PC application architecture.

Because a Forms Manager consists of several interfaces, it performs the following tasks:

• Displays one or more active device contexts
• Creates and manages a single device context for all applications with activated faceplate forms
• Manages device contexts internally rather than externally
• Enables applications to specify the control layout for the information displayed on the faceplate while the faceplate has the input focus
• Enables applications to dynamically interact with a control to change its appearance and internal data
• Enables applications to receive events from active controls on a form
• Provides tab and focus management between the controls on an active form
• Enables you to add custom controls to an application
• Handles speech-to-text input for controls and for navigation between controls

    To create a Forms Manager

1. Call CoCreateInstance to create an instance of a Forms Manager.
2. Call RegisterStartedApplication to register your application with the Forms Manager.
3. Call MoveAppToForeground to move your application to the foreground.

The following code example shows how to create a Forms Manager.

HRESULT GetFormsManager()
{
    HRESULT         hr;
    
    hr = CoCreateInstance(CLSID_FMMANAGE, NULL, CLSCTX_INPROC_SERVER,
        IID_FMMANAGE, 
                            (PVOID *) &g_pManage);
    if (FAILED(hr)) goto LReturn;

 WCHAR wszAppName[ _MAX_PATH +1 ];

 //Use the name in the resource script with ID #1(STR_APP_SHELL_NAME)
    LoadString(g_hInst, STR_APP_SHELL_NAME, wszAppName,_MAX_PATH );

 g_bstrAppName = ::SysAllocString(wszAppName);

 if (g_bstrAppName){ 
 // Register the application as started with the Forms Manager.
 // Send the Forms Manager the name of the faceplate on
 // which to execute the application.
     g_pManage->RegisterStartedApplication(FC_MAINFACEPLATE,
            g_bstrAppName, 0, 0);
 } 
 else {
  hr = E_OUTOFMEMORY;
 }
 
 hr = g_pManage->MoveAppToForeground(GetCurrentProcessId(), 0, 0); 

LReturn:
 return hr;
}