In addition to HTML rendering and parsing capabilities, MSHTML also exposes WYSIWYG HTML editing functionality. Applications hosting MSHTML can exploit these editing features to enable editing of HTML content in a manner similar to text editing in word processors.
Applications that use HTML to render information or content can use MSHTML editing functionality to enable end users to alter that information. For example, an e-mail application that renders e-mail messages with HTML could use the MSHTML editing features to enable end users to alter messages in the content area. Instead of spending time developing editing features for message rendering, developers can use the MSHTML implementation of these capabilities. This frees up their time to concentrate on improving their e-mail communication functionality.
Applying WYSIWYG editing to HTML authoring not only improves control of format and appearance, but can also remove HTML knowledge requirements from the Web author. Currently, if someone wants to create a Web page, they have to take the time to learn HTML coding to some degree. This in itself is a stumbling block for nontechnical fans of the Internet who refrain from contributing due to the learning curve. By hosting MSHTML in an application, developers can provide users with a simple WYSIWYG Web authoring tool. Authors can simply click buttons to alter paragraph formats, font sizes, typefaces, font weights, colors, and so on. This is a far cry from going into the HTML code and inserting tags.
There are three levels of functionality available for implementing HTML editing in your application:
MSHTML Editing provides the following functionality:
Hosting applications can exploit MSHTML editing as a means to generate proper and consistent HTML and XML code. MSHTML editing generates standard HTML, allowing third-party applications to quickly adapt the latest Microsoft browser features.
The DHTML Editing Component DocObject provides all of the MSHTML DocObject functionality, plus:
The DHTML Editing Component ActiveX control provides all of the DocObject functionality implemented in an easy-to-use control. The control also adds:
For information on the DHTML Editing DocObject and ActiveX control, see the Microsoft DHTML Editing Component SDK.
To implement this editing functionality, an application must be hosting MSHTML. For information on how to host MSHTML in your application, see Reusing MSHTML.
MSHTML can be switched between two modes: browse mode and edit mode. In browse mode, MSHTML displays DHTML exactly as it would in Microsoft® Internet Explorer 5, including script execution. In edit mode, MSHTML is a WYSIWYG DHTML editor. A host can use editing commands to modify the DHTML document. A host can switch MSHTML between edit and browse modes to allow for editing and preview modes.
To switch to edit mode, a host should implement the necessary IDispatch interface for exposing its ambient properties to MSHTML. When a host sets its AMBIENT_USER_MODE property to FALSE, MSHTML switches into edit mode. Returning to browse mode is as easy as setting the AMBIENT_USER_MODE property to TRUE.
MSHTML communicates with its host using the Active Document interfaces. As part of the Active Document interfaces, both MSHTML and the host implement IOleCommandTarget. Through this interface MSHTML supports the standard Active Document command set and the CGID_MSHTML command group. Hosts use IOleCommandTarget::Exec to send a command, such as IDM_BOLD or IDM_MARQUEE, to MSHTML. Hosts use IOleCommandTarget::QueryStatus to determine if a given command is valid for the state of the current selection. For more information on the communication between the host and MSHTML, see Reusing MSHTML.
By calling IOleCommandTarget::Exec with one of the editing command identifiers, an application can alter the current selection. For example, to make the current selection bold, a host could implement the following:
{ HRESULT hr = S_OK; IUnknown* lpUnk = NULL; LPOLECOMMANDTARGET pCommandTarget = NULL; lpUnk = m_pSite->GetObjectUnknown(); hr = lpUnk->QueryInterface(IID_IOleCommandTarget,(void**) &pCommandTarget); if ( SUCCEEDED(hr) && pCommandTarget != NULL ) { HRESULT hr = S_OK; // Use the CGID_MSHTML command group with IDM_BOLD command ID hr = pCommandTarget->Exec(&CGID_MSHTML, IDM_BOLD, MSOCMDEXECOPT_DONTPROMPTUSER, NULL, NULL); } return hr; }
Some command identifiers require arguments as input to IOleCommandTarget::Exec, such as IDM_BACKCOLOR.
{ HRESULT hr = S_OK; IUnknown* lpUnk = NULL; LPOLECOMMANDTARGET pCommandTarget = NULL; lpUnk = m_pSite->GetObjectUnknown(); hr = lpUnk->QueryInterface(IID_IOleCommandTarget, (void**) &pCommandTarget); if ( SUCCEEDED(hr) && pCommandTarget != NULL ) { wchar_t wsz[] = "Blue"; BSTR bstrColor; bstrColor = SysAllocString(wsz); SysFreeString(wsz); Variant vInParam; VariantInit(&vInParam); vInParam.vt = VT_BSTR; vInParam.bstrVal = bstrColor; // Use the CGID_MSHTML command with IDM_FONTNAME hr = pCommandTarget->Exec(&CGID_MSHTML, IDM_FORECOLOR, MSCOMDEXECOPT_DONTPROMPTUSER, &vInParam, NULL); // deallocate the BSTR vInParam VariantClear(&vInParam); } return hr; }
Some command identifiers result in the out parameter for IOleCommandTarget::Exec returning a value. In this case, the out parameter represents some state of the current selection. For example, using the IDM_FONTNAME command identifier and preparing the out parameter provides the typeface of the current selection.
{ HRESULT hr = S_OK; IUnknown* lpUnk = NULL; LPOLECOMMANDTARGET pCommandTarget = NULL; lpUnk = m_pSite->GetObjectUnknown(); hr = lpUnk->QueryInterface(IID_IOleCommandTarget, (void**) &pCommandTarget); if ( SUCCEEDED(hr) && pCommandTarget != NULL ) { Variant vOutParam; VariantInit(&vOutParam); // Use the CGID_MSHTML command with IDM_FONTNAME hr = pCommandTarget->Exec(&CGID_MSHTML, IDM_FONTNAME, MSCOMDEXECOPT_DONTPROMPTUSER, NULL, &vOutParam); if (SUCCEEDED(hr)) { _bstr_t fontName; _ASSERTE(V_VT(&vOutParam) == VT_BSTR); fontName = V_BSTR(&vOutParam); } // deallocate the BSTR returned in vOutParam VariantClear(&vOutPara); } return hr; }
For more information, see the following topics: