Using the MSHTML Editor's Extra Features
This article explains how to activate the extra features of the MSHTML Editor, such as multiple selection and 2-D positioning. To demonstrate these features, a sample application and its source code are included.
This article is divided into the following topics:
- Prerequisites and Requirements
- Overview of Editing Commands
- The Sample Specifications
- Issuing Editing Commands
- Document Level Editing Commands
- Related topics
Prerequisites and Requirements
In order to understand and use this tutorial, you will need:
- A good understanding of C++, the Component Object Model (COM), and the Active Template Library (ATL).
- Microsoft Internet Explorer 5.5 or later installed on your computer.
- Header files and libraries for Internet Explorer 5.5 or later for use in your development environment; in particular, you'll need Mshtml.h and Mshtmcid.h.
Overview of Editing Commands
You can activate a number of optional features to enhance the MSHTML Editor's default behavior. For a list of these features, see the section Document Level Editing Commands at the end of this article. The commands used to modify the Editor's behavior can be used from C++. Most work only when the browser is in design mode. They are turned off when the Editor is deactivated or the WebBrowser navigates to a new page.
The Sample Specifications
The sample for this tutorial provides a demonstration of the editing features controlled through IOleCommandTarget::Exec. The sample shows:
- How each of the features behaves.
- How to use IOleCommandTarget::Exec to turn editing features on and off.
The specifications of this sample are as follows:
- This sample is a simple browser implementation with an address bar and ten buttons.
- The first button turns the MSHTML Editor on and off.
- Each of the rest of the buttons executes one of the editing feature commands, turning it on or off.
Note You must download the sample to your own computer to run it.
The source code for this sample is included in a Microsoft Visual C++ 6.0 workspace. It uses ATL to provide COM support, standard implementations of some of the standard interfaces, and "smart" interface pointers that handle their own reference counting. The project source code can be downloaded at the Editing Features Sample Source Page.
Many of the interface pointers in the sample are wrapped by the CComQIPtr class. CComQIPtr is a "smart" pointer class. Besides automatic reference counting, it provides overloaded operators to make working with COM easier. CComQIPtr includes an overloaded assignment operator (operator=) which performs an automatic QueryInterface during assignment. For instance, the sample's QueryInterface call to initialize its IOleCommandTarget pointer looks like this:
// m_spWebBrowser is an already initialized pointer to an IWebBrowser2 interface.
// m_spOleCmdTarg is a declared but uninitialized CComQIPtr for an IOleCommandTarget interface.
m_spOleCmdTarg = m_spWebBrowser;
Issuing Editing Commands
The editing commands can be executed using the IOleCommandTarget::Exec method with command identifiers taken from the CGID_MSHTML command group. These commands are defined in Mshtmcid.h. You can obtain an IOleCommandTarget interface by calling QueryInterface on either the IWebBrowser2 or IHTMLDocument2 interface.
// Assume pWebBrowser is a valid pointer to the IWebBrowser2 interface
IOleCommandTarget* pCmdTarg;
pWebBrowser->QueryInterface(IID_IOleCommandTarget, (void**)&pCmdTarg);
Here is how you can turn on 2-D positioning using IOleCommandTarget::Exec:
// Declare a VARIANT data type and initialize it
VARIANT var;
V_VT(&var) = VT_BOOL; // Set the type to BOOL
V_BOOL(&var) = VARIANT_TRUE;
// Turn on 2-D positioning for absolutely positioned elements
hr = pCmdTarg->Exec(&CGID_MSHTML, IDM_2D_POSITION, MSOCMDEXECOPT_DODEFAULT, &var, NULL);
V_VT(X) and V_BOOL(X) are macros defined in Oleauto.h. They take a VARIANT pointer for their argument. The sample file BrowserHost.cpp includes Oleauto.h indirectly by way of Mshtmhst.h. Mshtmhst.h includes Ole2.h, which includes Oleauto.h. These macros assign a value to the appropriate member of a VARIANT structure. For instance, V_BOOL(&var) = VARIANT_TRUE is equivalent to var.bVal = VARIANT_TRUE.
Document Level Editing Commands
The following commands affect the behavior of the MSHTML Editor as a whole:
- IDM_MULTIPLESELECTION: Takes a VT_BOOL. Allows for the selection of more than one site selectable element at a time when the user holds down the SHIFT or CTRL keys. If multiple items are selected when this command is turned off, items remain selected.
- IDM_2D_POSITION: Takes a VT_BOOL. Allows absolutely positioned elements to be moved by dragging.
- IDM_LIVERESIZE: Takes a VT_BOOL. The Editor updates the screen at every mouse move, rather than at the end of a mouse move.
- IDM_ATOMICSELECTION: Takes a VT_BOOL. By default, the browser allows you to locate the insertion point in the text of any element. When the IDM_ATOMICSELECTION command is issued, any element that has its ATOMICSELECTION attribute set to true will be selectable only as a unit. This command applies to both design mode and browse mode.
- IDM_DISABLE_EDITFOCUS_UI: Takes a VT_BOOL. Turns off the hatched border and handles around a site selectable element when the element has "edit focus" in design mode; that is, when the text or contents of the element can be edited.
- IDM_RESPECTVISIBILITY_INDESIGN: Takes a VT_BOOL. When this feature is activated, any element that has a IHTMLCurrentStyle::visibility property set to "hidden," or a IHTMLCurrentStyle::display property set to "none," will not display in design mode, just as it would not display in browse mode.
- IDM_AUTOURLDETECT_MODE: Takes a VT_BOOL. By default, the Editor will automatically create a hyperlink for any text that is formatted as a URL. Use this command to turn automatic URL detection on and off.
- IDM_OVERRIDE_CURSOR: Takes a VT_BOOL. Commands the MSHTML Editor never to change the mouse cursor. The mouse cursor will remain fixed as the last cursor icon before the IDM_OVERRIDE_CURSOR command was issued.
- IDM_CSSEDITING_LEVEL: Takes a VT_I4. Allows you to choose which Cascading Style Sheets (CSS) level (CSS1 or CSS2) the Editor will support, if any. If you do not wish CSS support at all, set the VARIANT argument to zero. With no CSS support, elements can't be resized or moved. Note Level 2 support is not currently implemented.
- IDM_IE50_PASTE_MODE: Takes a VT_BOOL. Sets the MSHTML Editor paste operation to be compatible with Microsoft Internet Explorer 5. If set to VARIANT_TRUE, all UI paste operations are compatible with Internet Explorer 5. Otherwise, if set to VARIANT_FALSE, all UI operations are compatible with Internet Explorer 5.5.
- IDM_IE50_PASTE): Takes a VT_BSTR. Performs a single paste operation compatible with Internet Explorer 5.
Related topics
Conceptual
Introduction to MSHTML Editing