Creating a Form

A form is an object you customize to create the user interface for your application. It contains a collection of controls, such as speech controls, power list boxes, audio controls, and tabber controls that display information on a screen. A form provides the following services to an Auto PC application:

• Acts as a collection of controls
• Dispatches messages to controls
• Manages input focus
• Provides methods for controls to invalidate and update themselves
• Provides access to a device context so that a form can draw to the screen

A form is used instead of a window manager to display information on a screen. A form performs the same type of standard Microsoft® Windows® messaging tasks typically performed by HWND and message loop procedures, including automatic invalidation and message posting.

When you add a control to a form, an application must create one or more form objects to become a container for a control. An application uses the IASForm interface to manage the controls on a form.

    To create a form

1. Create the form object with CoCreateInstance.
2. Call Init to initialize a form.
3. Call Start to start a form.
4. Call PutCaption to add a title to a form.
5. Call put_Visible to make a form visible.

The following code example shows how to create a form.

HRESULT CreateMainForm(void)
{
    HRESULT hr = NOERROR;

    // Create the form.
    hr = CoCreateInstance(CLSID_ASFORM, NULL, CLSCTX_INPROC_SERVER,
        IID_ASFORM, 
                            (PVOID *) &g_pForm);
    if (FAILED(hr)) return hr;

    hr = g_pForm->Init(ID_MAINFORM, NULL, g_pSink); // Initialize the
                                                    // form.
    if (FAILED(hr)) goto LReturn;
    
    hr = g_pManage->Start(g_pForm);                 // Start the form.
    if (FAILED(hr)) goto LReturn;

    IASControl* pControl;
    g_pForm->QueryInterface(IID_ASCONTROL,
        (PVOID*) & pControl);
    pControl->put_Caption(g_bstrAppName);          // Give the form
                                                   // a title.
    pControl->Release();

    hr = AddControls();                             // Add controls.
 if (FAILED(hr)) goto LReturn;

 // Make the form visible or there will be no display.
 hr = g_pForm->put_Visible(TRUE);
     
LReturn:
    if (FAILED(hr))             // There was an error. Cleanup.
        {
        g_pForm->Close();       // Close the form.
        g_pForm->Release();
        g_pForm = NULL;
        }

    return hr;
}