ActiveX Control Properties

This document describes technologies that are available in Internet Explorer 5. An earlier version of the DHTML Editing Component that is compatible with Internet Explorer 4.01 is available as an SDK that you can download from here.

Microsoft Corporation

Updated June 11, 1999

The following properties are exposed by the DHTML Editing control.

AbsoluteDropMode, ActivateActiveXControls, ActivateApplets, ActivateDTCs, Appearance, BaseURL, BrowseMode, Busy, CurrentDocumentPath, DocumentHTML, DocumentTitle, DOM, IsDirty, ScrollbarAppearance, ScrollBars, ShowBorders, ShowDetails, SnapToGrid, SnapToGridX, SnapToGridY, SourceCodePreservation, UseDivOnCarriageReturn

See Also

ActiveX Control Methods, ActiveX Control Events

AbsoluteDropMode Property

Description

Determines whether elements dragged onto the document will be absolutely positioned.

Syntax

object. AbsoluteDropMode [ = absoluteDropMode ]

Part	Description
object	The DHTML Editing control
absoluteDropMode	A Boolean value specifying the mode. If True, absolute drop mode is on. If False, it is not. The default is False.

Remarks

If absolute drop mode is on, all elements that can be absolutely positioned are automatically made absolute when they are dragged onto the document. Only elements coming from outside the document are affected by this mode. Repositioning existing items by dragging them within the document does not convert them to absolutely positioned, even if AbsoluteDropMode is set to True.

The value of this property is persisted at design time. Its value is available in both Edit mode and Browse mode and is retained when switching between modes. However, it does not apply in Browse mode.
This property is available in both the safe-for-scripting and unmarked versions of the control.

ActivateActiveXControls Property

Description

Enables or disables UI activation of ActiveX® controls.

Syntax

object. ActivateActiveXControls [ = activateActiveXControls ]

Part	Description
object	The DHTML Editing control
activateActiveXControls	A Boolean value indicating whether ActiveX controls are UI active. If True, they are. If False, they are not. The default is False.

Remarks

When an ActiveX control is UI activated, clicking it in Edit mode enables its text to be edited directly (rather than being edited by setting properties).

This property should be set at design time. For example, if the control is hosted in a Web page, the ActivateActiveXControls property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic® form, its value is set in the Properties window. The value of the ActivateActiveXControls property can be set at run time, but does not affect the current instance of the control.
The value of this property is persisted at design time. If set at run time, its value is retained when switching between Edit mode and Browse mode. In Browse mode, an ActiveX control is always activated.

This property is available in both the safe-for-scripting and unmarked versions of the control.

ActivateApplets Property

Description

Enables or disables UI activation of Java applets.

Syntax

object. ActivateApplets [ = activateApplets ]

Part	Description
object	The DHTML Editing control
activateApplets	A Boolean value indicating whether Java applets are UI active. If True, they are. If False, they are not. The default is False.

Remarks

When an applet is UI activated, clicking it in Edit mode enables its text to be edited directly (rather than being edited by setting properties). If ActivateApplets is False, then applets are treated like static elements.

This property should be set at design time. For example, if the control is hosted in a Web page, the ActivateApplets property should be set in a <PARAM> element enclosed in the control's <APPLET> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the ActivateApplets property can be set at run time, but does not affect the current instance of the control.
The value of this property is persisted at design time. If set at run time, its value is retained when switching between Edit mode and Browse mode. In Browse mode, an applet is always activated.

This property is available in both the safe-for-scripting and unmarked versions of the control.

ActivateDTCs Property

Description

Enables or disables UI activation of design-time controls (DTCs).

Syntax

object. ActivateDTCs [ = activateDTCs ]

Part	Description
object	The DHTML Editing control
activateDTCs	A Boolean value indicating whether design-time controls are UI active. If True, they are. If False, they are not. The default is True.

Remarks

When a design-time control is UI activated, clicking it in Edit mode enables its text to be edited directly (rather than being edited by setting properties).

This property should be set at design time. For example, if the control is hosted in a Web page, the ActivateDTCs property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the ActivateDTCs property can be set at run time, but does not affect the current instance of the control.
The value of this property is persisted at design time. If set at run time, its value is retained when switching between Edit mode and Browse mode. In Browse mode, a design-time control is always activated.

This property is available in both the safe-for-scripting and unmarked versions of the control.

Appearance Property

Description

Determines whether the bevel on the control's window is raised or flat.

Syntax

object. Appearance [ = appearance ]

Part

Description

object

The DHTML Editing control

appearance

Numeric value indicating whether the control's window is raised (3-D) or flat. The constant values and equivalent numeric values are:

DEAPPEARANCE_3D (1) The window is raised.

DEAPPEARANCE_FLAT (0) The window is flat.

The default is DEAPPEARANCE_3D.

Remarks

This property should be set at design time. For example, if the control is hosted in a Web page, the Appearance property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the Appearance property can be set at run time, but does not affect the current instance of the control.

The value of this property is persisted at design time. If set at run time, its value is retained when switching between Edit mode and Browse mode.
This property is available in both the safe-for-scripting and unmarked versions of the control.

BaseURL Property

Description

Specifies a base URL that is prepended to all relative URLs in the document.

Syntax

object. BaseURL [ = baseURL ]

Part	Description
object	The DHTML Editing control
baseURL	A string specifying the base URL.

Remarks

The property is set automatically under specific circumstances:

It is set to the empty string ("") when the control is first created.

The LoadDocument method sets BaseURL to the path of the document.

The LoadURL method sets BaseURL to the URL of the document if you load a URL, to the path of the document if you load a file using the File protocol, and to the empty string ("") if you load a document using a path (such as c:\test.htm).

The NewDocument method sets it to the empty string.

If the document includes a <BASE> element, the BaseURL property is set to the URL pointed to by the HREF attribute of that element.

Note If the HREF attribute of the document's <BASE> element is changed programmatically using the document object model (via the DOM property), the BaseURL property is not updated.

The host application can set this property to a new value at any time. If it does, when the control has finished resetting the BaseURL property, the document loaded in the control is reparsed. Images (<IMG> elements) and hyperlinks (<A> elements) are reevaluated based on the new BaseURL value and, if necessary, the files referenced by these elements are reloaded.
While the control is reparsing the document, the Busy property is set to True. When the document has been reparsed, the DocumentComplete event is fired and the Busy property is set to False. The DOM and DocumentHTML properties are invalid until the DocumentComplete event has been fired. You must wait until that event has fired before attempting to manipulate the document.

Note Changing the BaseURL property reloads the document without checking first whether the current document should be saved. To create such a test, test the IsDirty property and, if necessary, call the SaveDocument method.

For URL addresses, the baseURL value does not have to end in a forward slash; that is, it could be something like http://www.microsoft.com. However, for file paths, the trailing backslash is required; for example, \\fileserver\public\myfile\.
This property is read/write at run time. Its value is available in both Edit mode and Browse mode and is retained when switching between modes. Attempting to set this property at design time results in an error.

This property is available in both the safe-for-scripting and unmarked versions of the control.

BrowseMode Property

Description

Allows the host to switch the DHTML Editing control between Browse mode and Edit mode.

Note Browse mode is only available in the version of the control that is not marked as safe-for-scripting.

Syntax

object. BrowseMode [ = browseMode ]

Part	Description
object	The DHTML Editing control
browseMode	A Boolean value indicating what mode the control is in. If True, the control is in Browse mode. If False, it is in Edit mode.

Remarks

In the version of the control not marked safe for scripting, setting the value of this property switches between Edit mode and Browse mode. In Browse mode, the control displays the document in a manner similar to the way it is displayed in Microsoft® Internet Explorer. Mouse events are "live"--they invoke the same response that they would in the browser. Links, bookmarks, marquees, and client scripts are all live.

Note When the control is in Browse mode, clicking on a link will launch a new instance of Internet Explorer.

A switch between modes causes the document to be completely reparsed. While the document is being parsed, the Busy property is set to True. When the control has finished switching modes the DocumentComplete event is fired and the Busy property is set to False. The DOM and DocumentHTML properties are invalid until the DocumentComplete event has been fired. You must wait until that event has fired before attempting to manipulate the document.
In Browse mode, the IsDirty flag is always set to False, even if it was True in Edit mode. It remains set to False when you return to Edit mode.

This property is persisted at design time.

This property is available only in the version of the control that is not marked as safe for scripting.

See Also

Editing and Browsing Documents, ActiveX Control Methods, ActiveX Control Events, ActiveX Control Command IDs

Busy Property

Description

Indicates whether a document is currently being loaded, initialized, or parsed.

Syntax

object. Busy

Part	Description
object	The DHTML Editing control

Remarks

This property returns True while the control is loading a document, URL, or string, which occurs when the following are called or set:

LoadDocument method

LoadURL method

NewDocument method

BaseURL property

BrowseMode property

DocumentHTML property

After the control has finished parsing and displaying the document, it fires the DocumentComplete event and sets the Busy property to False.
Certain properties, such as DocumentHTML and DOM, are not valid while this property returns True. If you attempt to access these properties when Busy is True, a DE_E_UNEXPECTED error occurs.

This property is read-only at run time in both Edit mode and Browse mode.

This property is available in both the safe-for-scripting and unmarked versions of the control.

For an example of using the Busy property, see Working with HTML Source Code.

CurrentDocumentPath Property

Description

Returns the path and file name of the current document if it has been loaded from disk or saved to disk, or the full URL of the document if it was loaded using the LoadURL method.

Syntax

object. CurrentDocumentPath

Part	Description
object	The DHTML Editing control

Remarks

CurrentDocumentPath is set to the empty string ("") until the LoadDocument, LoadURL, or SaveDocument method is called.

This property is read-only at run time in both Edit mode and Browse mode. It is not available at design time.
This property is available in both the safe-for-scripting and unmarked versions of the control.

DocumentHTML Property

Description

Contains the raw HTML text, including the head, of the current document in the control.

Syntax

object. DocumentHTML [ = docHTML ]

Part	Description
object	The DHTML Editing control
docHTML	A string containing the contents of the document

Remarks

This property contains all of the HTML text in the DHTML Editing control, including the information preceding the <BODY> tag. You can read this property to get the entire document, and you can write HTML text to it to update the current document.

Note If you set the value of the DocumentHTML property to a string that includes illegal HTML, an error can result.

For example, you could use this property to display all the HTML text of the document being edited when the user pressed one tab, while another tab displayed the DHTML Editing control itself.
When you set this property, the control re-parses the document. While the control is re-parsing the document, the Busy property is set to True. When the document has been reparsed, the DocumentComplete event is fired and the Busy property is set to False. The DOM property is invalid until the DocumentComplete event has been fired. You must wait until that event has fired before attempting to manipulate the document.

This property is read/write at run time. Its value is available in both Edit mode and Browse mode. However, the contents of the property might be reconstructed during the switch between modes, depending on whether the SourceCodePreservation property is True and on whether the IsDirty flag has been set in Edit mode. The DocumentHTML property is not available at design time.

This property is available in both the safe-for-scripting and unmarked versions of the control.

For more details about using the DocumentHTML property, see Working with HTML Source Code.

DocumentTitle Property

Description

Returns the document's title.

Syntax

object. DocumentTitle

Part	Description
object	The DHTML Editing control

Remarks

This property is set to the empty string ("") when the control is first created. It is set to the current value of document's <TITLE> element, if any, when a document is loaded. If the current document does not have a <TITLE> element, the property remains set to the empty string.

This property is read-only at run time and is available in both Edit mode and Browse mode. It is not available at design time.
This property is available in both the safe-for-scripting and unmarked versions of the control.

DOM Property

Description

Provides a parent object that allows access to the document object model (DOM) of the page being edited.

Syntax

object. DOM

Part	Description
object	The DHTML Editing control

Remarks

The DOM property returns the document object (IHTMLDocument2). You can use the value of this property as the top-level object for access to the current document's DHTML document object model. In effect, the control's DOM property has the same role as the DHTML document object. For example, when scripting DHTML, you can access the window object using this syntax:

document.all.item("p1").innerHTML

When coding against the DHTML Editing control, you can access the same object using this syntax:

DOM.all.item("p1").innerHTML

Note You should not use the value of the DOM property when calling the control's methods or setting its properties. For example, you should not use a value returned via the DOM property as a parameter for the LoadURL method. Doing so can cause unexpected results.

If the value of the SourceCodePreservation property is True when a document is loaded, the control parses the document and adds control-specific attributes (such as DESIGNTIMESP and DESIGNTIMEURL) to the document to assist in preserving the document's original white spacing.
If you get the raw HTML of the document using the DocumentHTML property, these extra attributes are filtered out. However, if you get portions of the document using the document object model exposed in the DOM property, these attributes are returned as part of the object model. You can call the FilterSourceCode method to remove the extra attributes from document text extracted using the DOM property.

This property is read-only at run time and is available in both Edit mode and Browse mode. It is not available at design time.

This property is available in both the safe-for-scripting and unmarked versions of the control.

Note To use this property with Visual Basic early binding, add a reference in Visual Basic to MSHTML.DLL, which will make available the Microsoft HTML object library.

For general information about using the DHTML object model, see the Dynamic HTML Overview on the Microsoft Web site. For specific information about the document object, see the document reference topic in the online DHTML reference on the Microsoft Web site.
For details about using the DHTML object model in a DHTML Editing control, see Accessing the DHTML Document Object Model. For examples of how the DOM property is used, see the Visual Basic VBDom and Web DOMUsage samples. For more details about sample applications, see "Sample Applications" under Overview of the DHTML Editing Component.

IsDirty Property

Description

Indicates whether the document has been modified since it was loaded or saved.

Syntax

object. IsDirty

Part	Description
object	The DHTML Editing control

Remarks

This property is set to True automatically when the contents of the document are modified either by being edited directly or programmatically. The property remains set to True until one of the following occurs:

The LoadDocument method is called

The LoadURL method is called

The NewDocument method is called

The SaveDocument method is called

The DocumentHTML property is written

This property is read-only at run time in both Edit mode and Browse mode. However, at Browse mode this property always returns False. It is not available at design time.
This property is available in both the safe-for-scripting and unmarked versions of the control.

ScrollbarAppearance Property

Description

Determines whether the scrollbars for the control's window are raised or flat.

Syntax

object. ScrollbarAppearance [ = appearance ]

Part

Description

object

The DHTML Editing control

appearance

Numeric value indicating whether the scrollbars are raised (3-D) or flat. The constant values and equivalent numeric values are:

DEAPPEARANCE_3D (1) Scrollbars are raised.

DEAPPEARANCE_FLAT (0) Scrollbars are flat.

The default is DEAPPEARANCE_3D.

Remarks

This property should be set at design time. For example, if the control is hosted in a Web page, the ScrollbarAppearance property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the ScrollbarAppearance property can be set and read at run time, but setting it does not affect the current instance of the control.

The value of this property is persisted at design time. If set at run time, its value is retained when switching between Edit mode and Browse mode.
This property is available in both the safe-for-scripting and unmarked versions of the control.

ScrollBars Property

Description

Displays scrollbars in the control's window.

Syntax

object. ScrollBars [ = enableScrollbars ]

Part	Description
object	The DHTML Editing control
enableScrollbars	Boolean value indicating whether the control's window should display scrollbars. If True, scrollbars are displayed. If False, they are not. The default is True.

Remarks

If this property is True, the control's window initially displays a vertical scrollbar, even if no document is loaded. After a document is loaded, if the text in the window exceeds the height of the window, the scrollbar displays a slider to allow scrolling. A horizontal scrollbar is displayed only if you load a document in which the text exceeds the width of the control's window.

Note In Edit mode, text typed into the control wraps at the edge of the control's window.

This property should be set at design time. For example, if the control is hosted in a Web page, the ScrollBars property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the ScrollBars property can be set at run time, but does not affect the current instance of the control.

Note If the document being viewed has its SCROLL attribute set to NO (in the <BODY> tag), this setting will override the Scrollbars property and no scrollbars will appear for the control. However, the value of the Scrollbars property is unchanged, and when a new document is viewed without the SCROLL attribute set, the scrollbars will once again appear.

The value of this property is persisted at design time. If set at run time, its value is retained when switching between Edit mode and Browse mode.
This property is available in both the safe-for-scripting and unmarked versions of the control.

ShowBorders Property

Description

Displays a 1-pixel border around tables and <DIV> elements in Edit mode.

Syntax

object. ShowBorders [ = showBorders ]

Part	Description
object	The DHTML Editing control
showBorders	A Boolean value indicating whether borders are displayed. If True, borders are displayed. If False, they are not. The default is False.

Remarks

To make it easier to work with tables and with absolutely positioned <DIV> elements, the control can display a 1-pixel border around those controls in Edit mode if they don't already have a border. If a table or division has a border already, setting this property does not change that border.

The border controlled by the ShowBorders property is not displayed in Browse mode.
The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes.

This property is available in both the safe-for-scripting and unmarked versions of the control.

ShowDetails Property

Description

Shows hidden tags, anchors, and other elements as glyphs in Edit mode.

Syntax

object. ShowDetails [ = showDetails ]

Part	Description
object	The DHTML Editing control
showDetails	A Boolean value indicating whether glyphs are displayed. If True, glyphs are displayed. If False, they are not. The default is False.

Remarks

Certain HTML elements are normally invisible in a WYSIWYG rendering of the page in Edit mode. To mark these elements and therefore make them harder to change inadvertently, the control can display small glyphs to mark their position in the document.

You can see a table of the elements that can be represented by glyphs in the topic "Displaying Glyphs for Non-Visual Elements."

The glyphs controlled by the ShowDetails property are not displayed in Browse mode.
This property is read/write at run time.

The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes.

This property is available in both the safe-for-scripting and unmarked versions of the control.

SnapToGrid Property

Description

Turns snap-to-grid mode on or off.

Syntax

object. SnapToGrid [ = snapToGrid ]

Part	Description
object	The DHTML Editing control
snapToGrid	A Boolean value indicating whether elements are aligned according to an invisible grid. If True, snap mode is on. If False, snap mode is off. The default is False.

Remarks

Snap mode allows you to control the alignment of absolutely positioned elements. If snap mode is on, elements align to the nearest grid coordinates when they are moved or resized. Grid spacing is controlled by the SnapToGridX and SnapToGridY properties.

Note If snap mode is on and you nudge an absolutely positioned element using the keyboard, the element is snapped to the nearest grid coordinate.

Any absolutely positioned element that is contained within another absolutely positioned element will snap to grid relative to the left, top of its container.
The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes. However, it does not apply in Browse mode.

This property is available in both the safe-for-scripting and unmarked versions of the control.

SnapToGridX Property

Description

Sets the horizontal increment of the invisible snap-to grid.

Syntax

object. SnapToGridX [ = x ]

Part	Description
object	The DHTML Editing control
x	The horizontal grid snap increment value in pixels. The default is 50.

Remarks

If the SnapToGrid property is set to True, absolutely positioned elements are moved horizontally by the number of pixels represented by the SnapToGridX property.

The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes. However, it does not apply in Browse mode.
This property is available in both the safe-for-scripting and unmarked versions of the control.

See Also

SnapToGridY

SnapToGridY Property

Description

Sets the vertical increment of the invisible snap-to grid.

Syntax

object. SnapToGridY [ = y ]

Part	Description
object	The DHTML Editing control
y	The vertical grid snap value in pixels. The default is 50.

Remarks

If the SnapToGrid property is set to True, absolutely positioned elements are moved vertically by the number of pixels represented by the SnapToGridY property.

The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes. However, it does not apply in Browse mode.
This property is available in both the safe-for-scripting and unmarked versions of the control.

See Also

SnapToGridX

SourceCodePreservation Property

Description

Specifies whether white space and other formatting in source code should be preserved.

Syntax

object. SourceCodePreservation [ = enablePreservation ]

Part	Description
object	The DHTML Editing control
enablePreservation	A Boolean value indicating whether source code preservation is on. If True, formatting is preserved. If False, it is not. The default is True.

Remarks

If this property is True, the control maintains the original white space, attribute order, and so on, of the unchanged portions of the document as it is being loaded and edited. If this property is False, the control parses the document and reformats it in much the same way that Internet Explorer does when rendering a document.

Note Documents take longer to load and save if source code preservation is performed.

If the value of SourceCodePreservation is True, to maintain the original formatting, the control inserts temporary attributes (such as DESIGNTIMESP and DESIGNTIMEURL) into the document. If you get the raw HTML of the document using the DocumentHTML property, these extra attributes are filtered out. However, if you get portions of the document using the document object model exposed in the DOM property, these attributes are returned as part of the object model. You can call the FilterSourceCode method to remove the extra attributes from document text extracted using the DOM property.
This property should be set at design time. For example, if the control is hosted in a Web page, the SourceCodePreservation property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the SourceCodePreservation property can be set at run time, but does not affect the current instance of the control.

The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes. However, it does not apply in Browse mode.

This property is available in both the safe-for-scripting and unmarked versions of the control.

UseDivOnCarriageReturn Property

Description

Sets default paragraph spacing for an empty document.

Syntax

object. UseDivOnCarriageReturn [ = div ]

Part	Description
object	The DHTML Editing control
div	A Boolean value indicating whether carriage returns insert a single-spaced or double-spaced paragraph. If True, new paragraphs are single-spaced. If False, they are double-spaced. The default is True.

Remarks

This property establishes the contents of a new document. If UseDivOnCarriageReturn is True, when a new document is created with the NewDocument method, the body portion contains the following default text:

<DIV>&nbsp;</DIV>

If the UseDivOnCarriageReturn property is False, the body portion contains the following:

<P>&nbsp;</P>

Subsequent carriage returns split the existing element into two of the same. The result is that pressing the carriage return results in either single-spaced paragraphs (<DIV> elements) or double-spaced paragraphs (<P> elements).
This property should be set at design time. For example, if the control is hosted in a Web page, the UseDivOnCarriageReturn property should be set in a <PARAM> element enclosed in the control's <OBJECT> element. If hosted in a Visual Basic form, its value is set in the Properties window. The value of the UseDivOnCarriageReturn property can be set at run time, but does not affect the current instance of the control.

The value of this property is persisted at design time. At run time, its value is available in both Edit mode and Browse mode and is retained when switching between modes. However, it does not apply in Browse mode.

This property is available in both the safe-for-scripting and unmarked versions of the control.