Condividi tramite

About Edit Designers

  • Articolo

This article provides a conceptual overview of edit designers, which are components that enable you to customize the MSHTML Editor. It explains what edit designers are and how they work, and offers some design suggestions to illustrate the possibilities for edit designer use and implementation.

The tutorials that accompany this overview describe how to implement the IHTMLEditDesigner interface and how to add and remove edit designers from the MSHTML Editor. The tutorials also provide more in-depth information about the MSHTML Editor's event model, and discuss how an edit designer controls the Editor. The first tutorial and sample present the basics of implementing edit designers. The second tutorial offers a more real-life application: an annotation system for Web pages.

This overview is divided into the following sections:

  • Prerequisites and Requirements
  • What Are Edit Designers?
  • Scenarios for Using Edit Designers
  • How Edit Designers Work
  • Implemention Models for Edit Designers
  • Third Party Designers
  • Combining Edit Designers with Other Editor Customization Options
  • The Edit Designer Tutorials
  • Related topics

Prerequisites and Requirements

To make best use of this overview, you need:

  • A good understanding of C++, and the Component Object Model (COM).

What Are Edit Designers?

Edit designers are COM components that you can implement to customize the MSHTML Editor. Edit designers work by intercepting events occurring in the MSHTML Editor. When an edit designer intercepts an Editor event, the edit designer can change how the Editor handles the event. You can write an edit designer to either supplement or override the Editor's behavior. You can attach an edit designer to the Editor at any time during a design mode session and deactivate it at any time. The MSHTML Editor allows you to attach several edit designers at once, enabling you to add multiple levels of custom functionality.

Since they are a COM component, edit designers are very portable. They can be used with any instance of Microsoft Internet Explorer 5.5, the WebBrowser control, or MSHTML that displays a document with editable content. Edit designers can be used in stand-alone applications hosting the WebBrowser control, and they can also be used on Web pages, hosted by an Microsoft ActiveX control or binary behavior, when the page has an editable region in it.

Scenarios for Using Edit Designers

Edit designers offer a very powerful tool for customizing the MSHTML Editor. You can change virtually any part of the Editor's behavior, as much or as little as you like. Because edit designers are so powerful, there are a host of scenarios where they can be invaluable, supporting the MSHTML Editor in handling HTML content as well as content that is not specifically HTML. Here are some ideas:

  • Add table editing or spell checking capability to the Editor.
  • Add annotation or revision-tracking capability.
  • Provide layout control in a variety of online or stand-alone applications, from custom greeting card design to drawing organizational charts to user interface layout in application development.
  • Customize the MSHTML Editor to build a code-editing environment for a programming language. You might, for instance, use the IHTMLElement::innerText property of a content-editable element on the page to extract and set the source code listed in a file. The edit designer could then use HTML markup for custom coloring and highlighting of language-specific keywords, comments, and code sections. You could also develop edit designer features that provide drop-down lists for code completion and lookup tools.

How Edit Designers Work

The IHTMLEditDesigner interface consists of four methods, which act as callback routines whenever an event occurs in the MSHTML editing environment. The methods are:

When an event comes into MSHTML, these four handlers enable you to intercept events at different points of MHSTML's event handling process. The following list and diagram present the sequence of stages that an event passes through.

  1. If an event is generated by keyboard input, it first passes through the IHTMLEditDesigner::TranslateAccelerator methods of each designer attached to the editor in the order in which the designers were added to the Editor.
  2. If the event was not generated by keyboard input, or once all the edit designer IHTMLEditDesigner::TranslateAccelerator methods have been called, the event passes to the object model (OM) event handlers, such as those scripted on a Web page. If an event is cancellable, the OM handlers have the opportunity to do so. In this case neither the Editor's handlers, the designers, nor the default MSHTML action for the event are ever invoked.
  3. Once the OM handlers are finished, and assuming they haven't "consumed" the event, the Editor calls the IHTMLEditDesigner::PreHandleEvent method of each designer attached to the Editor, again in the order in which the designers were added to the Editor.
  4. After the IHTMLEditDesigner::PreHandleEvent method calls, the Editor and MSHTML itself have a chance to perform their default processing for the event.
  5. Next the IHTMLEditDesigner::PostHandleEvent methods are called for each designer.
  6. Finally, the IHTMLEditDesigner::PostEditorEventNotify methods for the designers are called.

The return value from each of the IHTMLEditDesigner::PreHandleEvent, IHTMLEditDesigner::PostHandleEvent, and IHTMLEditDesigner::TranslateAccelerator methods controls further event processing. Returning S_OK indicates that a designer method has completely handled the event and that no further processing should occur for the event, either by other designers, the Editor, or MSHTML. Returning S_FALSE indicates that other designers, the Editor, and MSHTML should proceed with their normal processing.

IHTMLEditDesigner::PostEditorEventNotify functions differently. It fires after an event has been completely handled, either by passing through the Editor, MSHTML, and all designer methods or because of an S_OK return value from a designer method. IHTMLEditDesigner::PostEditorEventNotify is not cancellable, and its return value is ignored. IHTMLEditDesigner::PostEditorEventNotify is handy for ensuring that your designer completes its tasks. When other edit designers are attached to the Editor at the same time, they might interfere with your designer by returning S_OK from one of their IHTMLEditDesigner method calls. IHTMLEditDesigner::PostEditorEventNotify gives your designer a final chance to verify that its work has been completed before the event is over.

Each edit designer method has a DISPID and an IHTMLEventObj for its incoming parameters. The DISPID provides a very efficient mechanism for a designer method to determine the event type—its value will be one of the HTMLELEMENTEVENTS2 values defined in Mshtmdid.h. The IHTMLEventObj enables a designer to obtain more extended information about the event.

To use an IHTMLEditDesigner implementation with the MSHTML Editor, you must first register the edit designer with the Editor using IHTMLEditServices::AddDesigner. To unregister it, use IHTMLEditServices::RemoveDesigner.

You can add more than one designer at a time. During an event, each of a designer's IHTMLEditDesigner::PreHandleEvent, IHTMLEditDesigner::PostHandleEvent, IHTMLEditDesigner::TranslateAccelerator, and IHTMLEditDesigner::PostEditorEventNotify methods will be called in the order in which it was added.

Implemention Models for Edit Designers

Edit designers provide a flexible mechanism for extending the MSHTML Editor, and there are many implementation models to which they can apply. Edit designers can be used in a stand-alone application hosting the WebBrowser control, or in MSHTML in design mode. They can be used on a Web page as part of an ActiveX control or a binary behavior. On such a page, an edit designer can intercept events occurring in a content-editable region on the page, or on an entire page if the whole document is in design mode. You might, for instance, have a Web page composed of two frames, one frame being a control panel while the other frame holds an HTML document for editing. You could embed an editable iframe in a Web page. You could also create a frameless editing environment, since any element can be made editable with the IHTMLElement3::contentEditable attribute.

Multiple designers can be active at once. For instance, a table editing designer, a spell checking designer, and a revision tracking designer could be active at the same time.

Since edit designers are implemented as COM components, you have many options for providing services from them. An edit designer can be attached to any running instance of Internet Explorer 5.5, the WebBrowser control, or MSHTML and can affect the editable regions displayed in that instance. In many cases, edit designer components also need one or more supporting interfaces to help them with initialization, communication with the hosting application, control, or behavior, and other tasks. The Editor receives a pointer to the component's IHTMLEditDesigner using IHTMLEditServices::AddDesigner. The host receives a pointer to the supporting interface or interfaces.

One question to decide is where to implement an edit designer. It can be implemented in its own DLL or grouped with other designers and components in a DLL. It can also be implemented in a DLL or executable program for the hosting application, control, or behavior. In this case, you can choose to implement the designer as a separate object within the component or as another interface on the host's implementation.

In a complex application, multiple designers can be attached at once from many different sources, as shown in the following diagram.

These are only a few design ideas for using edit designers. There are many other possibilities, like using aggregation and containment or using connection points or event sinks to facilitate communication among the application-Editor-designer triad. Edit designers might connect to external databases, network connections, security systems, or other applications, such as Microsoft Visual SourceSafe (VSS), or be used with ViewLink.

Third Party Designers

Since edit designers can reside in their own separate DLL, and can attach to the MSHTML Editor in any instance of Internet Explorer 5.5, the WebBrowser control, or MSHTML, they provide independent software vendors an excellent opportunity to add value and functionality to the MSHTML Editor. Independent developers can create and market edit designers as add-ons to the MSHTML Editor. A customer (another developer) purchasing or licensing the DLL would need to perform only a few steps to incorporate a designer component in an application. After registering the components contained in the DLL (unless the DLL comes in a self-installing and self-registering package), the customer can instantiate the component and query for the IHTMLEditDesigner interface and other supporting interfaces as needed.

Combining Edit Designers with Other Editor Customization Options

Edit designers can be, and typically will be, combined with other customization techniques for the Editor. Among these other techniques are:

  • The IHTMLEditHost interface, which intercepts and controls the resizing and repositioning of absolutely-positioned elements.
  • MSHTML editing features and commands activated by MSHTML Command Identifiers. These features and commands include 2-D positioning, live resizing, multi-selection, toggling between bold and italic, changing font color, inserting images, creating hyperlinks, cut, copy, paste, font name, font size, and many more.
  • Custom editing glyphs, which provide a user with visual clues about the location of tags in a document.
  • Various markup, display, selection, and highlight interfaces. These interfaces provide very fine-grained control of the markup in a document and its on-screen rendering; they also offer control of the selection object and of the highlighting applied to a document.

The Edit Designer Tutorials

This article has given you a conceptual overview of edit designers, how they work, the possibilities for their use, and how they might be implemented. The articles following this overview present tutorials and corresponding samples that show you how to implement edit designers. The first tutorial reviews and expands on what the edit designer methods do and the Editor event model; it also presents useful tips and shows you how to compile .idl files with Mshtml.idl. The sample that accompanies this tutorial is an edit designer monitor, a very simple application hosting the WebBrowser control, that demonstrates basic edit designer implementation.

The second tutorial presents a more true-to-life application of edit designers. Its sample implements an annotation tool for use with the MSHTML Editor. This tool allows the user to insert, delete, and read comments embedded in a Web page. The sample is Web-based, implemented as an ActiveX control supplied in a separate cabinet file. It shows how edit designers can be packaged as separate components and how they can be used in an online environment.

Conceptual

Introduction to MSHTML Editing

Activating the MSHTML Editor

Modifying Documents in Edit Mode

Using the MSHTML Editor's Extra Features

Using Editing Glyphs

Implementing IHTMLEditHost

Implementing Edit Designers: The Basics

Implementing Edit Designers 2: The Annotator Sample