ActiveX Control Methods

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 DHTML Editing control makes available a number of methods that you can call to manage the document displayed in the control. Most of the methods provide the equivalent to commands typically found on a File menu in a Windows application. A few, FilterSourceCode and SetContextMenu, provide utility functions.

Two important methods provide the means for manipulating the document itself. The ExecCommand method allows you to execute commands to format the document's text; cut and paste; manage tables, links, and graphics; and more. The QueryStatus method allows you to determine whether a given command is valid for the selection or document state.

The methods exposed by the control are: ExecCommand, FilterSourceCode, LoadDocument, LoadURL, NewDocument, PrintDocument, QueryStatus, Refresh, SaveDocument, SetContextMenu

See Also

ActiveX Control Properties, ActiveX Control Events

ExecCommand Method

Description

Performs a formatting or other commands against the selection or at the current insertion point in the document.

Syntax

object. ExecCommand cmdID [, cmdExecOpt] [, pInVar]

Part	Description
object	The DHTML Editing control
cmdID	Numeric value indicating the command to execute. Commands are typically passed as constant values. For a list of the constant values for the commands you can execute using this method, see ActiveX Control Command IDs. Note Command IDs are defined as constants in include files. For details about getting the correct include file for the language you are using, see Requirements.
cmdExecOpt	Numeric value indicating whether the command should display a dialog box, if supported by that command. This parameter is typically passed as a constant. Note This parameter is optional if the command does not support a dialog box and if you are not passing a value in the pInVar parameter. Most commands do not support a dialog box. Some, such as DEC MD_HYPERLINK, can optionally display a dialog box. Choices for this parameter are enum values of type OLECMDEXECOPT. The values are: OLECMDEXECOPT_DODEFAULT Let the command determine the user interface. If there is a choice, this is typically determined by the presence of the pInVar parameter. OLECMDEXECOPT_DONTPROMPTUSER Never display a user interface. OLECMDEXECOPT_PROMPTUSER Always display the user interface. Note Because the DHTML Editing control is an OCX control, some host environments will report a standard OLE option called OLECMDEXECOPT_SHOWHELP for this parameter. (For example, statement completion in Visual Basic will list this option.) This option is currently unsupported for the DHTML Editing control, and will result in an error if passed to the ExecCommand method. For details about what options you can pass, see the topics for individual commands.
pInVar	Input parameter for the command, if any. This parameter is not required for all commands. If it is included, the cmdExecOpt parameter must be included as well.

Error Codes

The ExecCommand method returns the following error codes.

Error Return Value	Description
S_OK	Success
DE_E_NOTSUPPORTED	The command passed in cmdID is not a valid command.
DE_E_INVALIDARG	Invalid argument (invalid parameter, missing parameter, or incorrect type)
DE_E_OUTOFMEMORY	Out of memory
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Return values

Most commands do not return a value. The following do:

DECMD_GETBACKCOLOR

D ECMD_GETBLOCKFMT

D ECMD_GETFONTNAME

D ECMD_GETFONTSIZE

DECMD_GETFORECOLOR

Remarks

The ExecCommand method is used to manipulate the contents of the current document. Most commands perform an action on the selection in the document. Others perform an action at the current insertion point. Available commands include those that allow you to:

Change formatting for characters and paragraphs.

Cut and paste elements.

Find text.

Insert links and images.

Add, delete, and change tables and cells.

Change positioning of absolutely positioned elements. For details about absolutely positioned elements, see Working with Absolutely Positioned Elements.

Call the QueryStatus method before executing a command to determine whether a specific command is supported for the selection. Based on the results returned by the QueryStatus method, you can update your application's user interface, such as enabling or disabling menu commands or toolbar buttons.
Some commands, such as those to insert links and images, include an option to display a dialog box. For example, to insert a link, you execute the DECMD_HYPERLINK command. You can either pass the link information using the pInVar parameter, or you can pass an option in cmdExecOpt to display the Hyperlink dialog box, which inserts the appropriate information based on user choices.

FilterSourceCode Method

Description

Removes attributes from HTML text that were introduced during document parsing.

Syntax

object. FilterSourceCode sourceCodeIn

Part	Description
object	The DHTML Editing control
sourceCodeIn	A string containing the source code to filter.

Return value

A string containing the filtered text.

Remarks

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.

LoadDocument Method

Description

Opens a DHTML file from disk for editing.

Syntax

object. LoadDocument pathIn, promptUser

Part	Description
object	The DHTML Editing control
pathIn	String containing the path and name of the file to open. If promptUser is True, then any value you pass in this parameter is used as the default in the Open dialog box. If you are including a drive letter, you must include a backslash with the path, as in the following: c:\sample.htm. Note Some languages, such as JavaScript, treat the "\" character as an escape character. If you are including a full path such as c:\mydocs\sample.htm, make sure you treat the backslash character properly. For example, in JavaScript, you should indicate the path using this string: C:\\mydocs\\sample.htm.
promptUser	Boolean value specifying whether the Open dialog box should be displayed. If promptUser is True then the Windows Open dialog box is displayed to allow the user to choose the file to open. Any value passed in pathIn is used as the default in the dialog box. The default is False.

Error Codes

The LoadDocument method returns the following error codes.

Error Return Value	Description
S_OK	Success
DE_E_INVALIDARG	Invalid argument (invalid parameter, missing parameter, or incorrect type)
DE_E_PATH_NOT_FOUND	The path is not valid. Also occurs if you specify drive letter but no backslash, such as c:sample.htm instead of c:\sample.htm or file://c:sample.htm instead of file://c:\sample.htm. Note This error will also be returned if you pass a path such as c:\sample.htm but are working with a language (such as JavaScript) that treats the "\" character as an escape character. If you are coding in such a language, use the proper method for indicating the backslash. Frequently this means doubling it: c:\\sample.htm
DE_E_FILE_NOT_FOUND	The specified file does not exist
DE_E_ACCESS_DENIED	Insufficient access privileges for this file, or for a directory in the path
DE_E_OUTOFMEMORY	Out of memory
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.
E_FILTER_FRAMESET	Returned if the caller attempts to load a frameset
E_FILTER_SERVERSCRIPT	Returned if the page is primarily server script

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

This method can be called at any time to reload the file being edited or to load a new document.

Note This method does not include a test to determine whether the current document should be saved. To create such a test, test the IsDirty property, and if necessary, call the SaveDocument method.

The LoadDocument method respects the SourceCodePreservation property. The LoadDocument method sets the following properties:

BaseURL is set to the path of the directory containing the opened file.

CurrentDocumentPath is set to the path and name of the document.

DocumentTitle is set to the contents of the document's <TITLE> element, if any.

DOM is set if this is the first time a document has been loaded for this instance of the control. If the DOM property was previously set, it is not reset.

DocumentHTML is loaded with the contents of the current document.

IsDirty is set to False after the document is loaded.

The LoadDocument method is asynchronous. The process of loading the document from disk is synchronous; control does not return to the statement following the LoadDocument method until the document has been fetched from disk. After that point, the method yields. However, the document has not yet been parsed and the document's object model is not yet available. While the parsing process takes place, the Busy property is set to True. When the control has finished parsing the document, the DocumentComplete event is fired and the Busy property is set to False. You must wait until the document is done loading before attempting to manipulate the document or get its current properties.

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

See Also

The DHTML Editing Component and Browser Security, Loading and Saving Documents

LoadURL Method

Description

Loads a document into the DHTML Editing control from an arbitrary URL.

Syntax

object. LoadURL url

Part	Description
object	The DHTML Editing control
url	URL to load. It can be any valid URL. The version not marked safe for scripting supports all URL protocols, including the File protocol and standard file system paths such as c:\mydoc.htm. The version of the control that is marked safe for scripting only accepts URLs specified with the HTTP or FTP protocol. Documents cannot be loaded from a local disk. In addition, the safe for scripting control will load documents only if they are in the same domain as the hosting application. For example, if the host is a Web page, the LoadURL method will accept only URLs in the same domain. Finally, the safe-for-scripting version of the control does not support server redirection of the value specified in url.

Error Codes

The LoadURL method returns the following error codes.

Error Return Value	Description
DE_E_INVALIDARG	Invalid argument (invalid parameter, missing parameter, or incorrect type)
DE_E_URL_NOT_FOUND	The URL was not found.
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.
DE_E_ACCESS_DENIED	Insufficient access privileges for this file, or for a directory in the path. This error can occur when an attempt is made to load into the control marked as safe for scripting a document that is not in the current domain or is on a local drive.
DE_E_PATH_NOT_FOUND	Some directory in the specified path does not exist. Also occurs if you specify drive letter, colon, no backslash, such as c:text.txt instead of c:\text.txt or file://c:text.txt instead of file://c\:text.txt.
DE_E_INVALID_URL	The URL is invalid.
DE_E_URL_SYNTAX	The URL in url malformed, such as http:/abc.com instead of http://abc.com.
DE_E_NO_SESSION	No Internet session was established.
DE_E_CANNOT_CONNECT	The attempt to connect to the server failed.
DE_E_RESOURCE_NOT_FOUND	The server or proxy was not found.
DE_E_OBJECT_NOT_FOUND	The object was not found.
DE_E_DATA_NOT_AVAILABLE	An Internet connection was established, but the data could not be retrieved.
DE_E_DOWNLOAD_FAILURE	The download failed; for example, the connection was interrupted.
DE_E_AUTHENTICATION_REQUIRED	Authentication is needed to access the object.
DE_E_NO_VALID_MEDIA	The object is not one of the required types.
DE_E_CONNECTION_TIMEOUT	The Internet connection timed out.
DE_E_INVALID_REQUEST	The request was invalid.
DE_E_UNKNOWN_PROTOCOL	In the safe for scripting control, the protocol was not HTTP or FTP. In the unmarked control, indicates that the protocol could not be identified.
DE_E_SECURITY_PROBLEM	An unspecified security problem was encountered.
DE_E_CANNOT_LOAD_DATA	The object could not be loaded.
DE_E_CANNOT_INSTANTIATE_OBJECT	The control was unable to create an instance of a control.
DE_E_REDIRECT_FAILED	The redirection failed because either the protocol changed (for example, from HTTP to FTP) or all attempts made to redirect to a new URL failed (the default is 5).
DE_E_CANNOT_LOCK_REQUEST	The requested resource could not be locked.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

This method can be called at any time to reload the file being edited or to load a new document. LoadURL can load a file from a server (using Internet protocols such as HTTP, FTP, and so on) or directly from disk.

The LoadURL method attempts to load a document directly from its source; it does not reload the document from the Internet Explorer cache. However, if the URL specified in the url parameter loads a page that results in redirection, the LoadURL method cannot guarantee that the most recent version of the target page will be loaded.
The version of the control that is marked safe for scripting supports only the HTTP and FTP protocols for this method.

Note This method does not include a test to determine whether the current document should be saved. To create such a test, test the IsDirty property, and if necessary, call the SaveDocument method.

The LoadURL method respects the SourceCodePreservation property. This method sets the following properties:

BaseURL is set to the URL of the document (if the document was opened with the HTTP protocol) or to the path of the directory containing the opened file if opened from disk.

CurrentDocumentPath is set to the URL of the current document.

DocumentTitle is set to the contents of the document's <TITLE> element, if any.

DocumentHTML is loaded with the contents of the current document.

DOM is set if this is the first time a document has been loaded for this instance of the control. If the DOM property was previously set, it is not reset.

IsDirty is set to False after the document is loaded.

The LoadURL method is asynchronous. The process of loading the document from a server is synchronous; control does not return to the statement following the LoadURL method until the document has been fetched. (This process can involve some delay, depending on the server speed and load, size of the document, and connection bandwidth.) After the document has been fetched, the method yields. However, the document has not yet been parsed and the document's object model is not yet available. While the parsing process takes place, the Busy property is set to True. When the control has finished parsing the document, the DocumentComplete event is fired and the Busy property is set to False. You must wait until the document is done loading before attempting to manipulate the document or get its current properties.

See Also

Loading and Saving Documents

NewDocument Method

Description

Creates a new document.

Syntax

object. NewDocument

Part	Description
object	The DHTML Editing control

Error Codes

The NewDocument method returns the following error codes.

Error Return Value	Description
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

This method can be called at any time to clear the existing document and create a new document. The template for the document is determined by the value of the UseDivOnCarriageReturn property.

Note This method does not test whether the current document should be saved. To create such a test, test the IsDirty property and, if necessary, call the SaveDocument method.

The NewDocument method sets the following properties:

BaseURL is set to "".

CurrentDocumentPath is set to "".

DocumentTitle is set to "".

DOM is set if this is the first time the NewDocument method has been loaded for this instance of the control. If the DOM property was previously set, it is not reset.

IsDirty is set to False.

The default text of the new document depends on the value of the UseDivOnCarriageReturn property. If that property is True, 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>

The NewDocument method is asynchronous. While a new document is being created, the Busy property is set to True. When the new document is complete and has been loaded into the control, the DocumentComplete event is fired and the Busy property is set to False. You must wait until the document is done loading before attempting to manipulate the document or get its current properties.

Note Because the process of creating a new document is relatively simple, the delay between the time the new document is created and the time its document object is available can be very short. In some instances, the delay might be so short that the document can be manipulated in the same function that contains the call to the NewDocument method. Although this practice might appear to work in some circumstances, it is strongly recommended that you do not rely on it, and instead, create a handler for the DocumentComplete event to alert you when it is safe to manipulate the document.

PrintDocument Method

Description

Prints the current document.
Note The PrintDocument method is the only way to print the contents of the control. If the control is hosted inside a container such as a form or Web page and you call the container's Print command, the contents of the DHTML Editing control will appear as a blank rectangle.

Syntax

object. PrintDocument [bfWithUI]

Part	Description
object	The DHTML Editing control
bfWithUI	Optional. VARIANT value of type VT_BOOL that specifies whether the method displays the Windows Print dialog box. If the value is set to True, the dialog box is displayed. If the value is set to False, or if the parameter is omitted, the current document is printed silently.

Error Codes

The PrintDocument method returns the following error codes.

Error Return Value	Description
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

This method is not supported by the version of the control marked as safe for scripting.

See Also

The DHTML Editing Component and Browser Security

QueryStatus Method

Description

Determines whether a formatting or other command is valid for the selection or insertion point.

Syntax

object. QueryStatus cmdID

Part	Description
object	The DHTML Editing control
cmdID	Numeric value indicating command to query status against. Commands are typically passed as constant values. For a list of the commands you can execute using this method, see ActiveX Control Command IDs.

Error Codes

The QueryStatus method returns the following error codes.

Error Return Value	Description
S_OK	Success
DE_E_NOTSUPPORTED	The command passed in cmdID is not a valid command.
DE_E_INVALIDARG	Invalid argument (invalid parameter, missing parameter, or incorrect type)
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Return value

An enum value of type DHTMLEDITCMDF indicates the return value for the query. Possible values for this enum are:

DECMDF_DISABLED (1) Command is not valid for the selection. For example, DECMD_GETFONTNAME will return this value if you attempt to get the font name of an ActiveX® control. In general, this status indicates that if the command being tested is visible in the user interface, the interface element (button or command) should be disabled.

DECMDF_ENABLED (3) Command is available for use with the selection. For example, DECMD_INSERTROW will return this value when the selection is within a table. DECMD_BOLD will return this value when the selection contains non-bold text.

DECMDF_LATCHED (7) Command is available for use with the selection and the command should be displayed latched (for example, a toolbar button should be depressed or a menu item should be checked). DECMD_BOLD will return this value when the selection contains bold text.

DECMDF_NINCHED (11) Command is available for use with the selection, but the selection contains mixed data. For example, DECMD_BOLD will return this value when the selection contains both bold and non-bold text.

Remarks

Call this method before calling the ExecCommand method in order to determine whether a specific command is supported for the current state of the control.

The QueryStatus method is frequently called in a handler for the DisplayChanged event to test whether you should enable or disable user interface elements such as menu commands and toolbar buttons. For example, the following Visual Basic handler tests whether the selection supports the DECMD_BOLD command, and if not, disables a command button called btnBold:

Private Sub DHTMLEdit1_DisplayChanged()
 retVal = DHTMLEdit1.QueryStatus(DECMD_BOLD)
 Select Case retVal
  Case DECMDF_ENABLED, DECMD_LATCHED
   btnBold.Enabled = True
  Case DECMDF_DISABLED
   btnBold.Enabled = False
 End Select
End Sub

Refresh Method

Description

Redraws the current document.

Syntax

object. Refresh

Part	Description
object	The DHTML Editing control

Error Codes

The Refresh method returns the following error codes.

Error Return Value	Description
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

The Refresh method redraws the current document, including the latest changes. You can use this method to redisplay a document if a series of edits have left the document in a state that is hard to read. If you are hosting a DHTML Editing control on a Web page, and if the control is hidden, you can also use this method to load a document into a DHTML Editing control. By default, the window object's onload event does not load documents into hidden controls.

The Refresh method does not reread information from a file, it merely updates the display of the current document. The value of the IsDirty property is not changed as a result of calling the Refresh method. If the current document references an external file, such as an applet or an image, and that file has changed, the change is not displayed by the Refresh method. To see changes in external files, use the LoadURL or LoadDocument method.

SaveDocument Method

Description

Saves the current document to the file system.

Syntax

object. SaveDocument pathIn, promptUser

Part	Description
object	The DHTML Editing control
pathIn	String containing the path and name of the file to save to. If promptUser is True, then any value you pass in this parameter is used as the default in the Save As dialog box. If you are including a drive letter, you must include a backslash with the path, as in the following: c:\sample.htm. Note Some languages, such as JavaScript, treat the "\" character as an escape character. If you are including a full path such as c:\mydocs\sample.htm, make sure you treat the backslash character properly. For example, in JavaScript, you should indicate the path using this string: C:\\mydocs\\sample.htm.
promptUser	Boolean value indicating whether the Save As dialog box should be displayed to allow the user to specify a path and file name. If True, the dialog box is displayed. If False or missing, the document is saved to the value specified in pathIn. Caution If the Save As dialog box is not displayed, the SaveDocument method does not prompt before overwriting existing files.

Error Codes

The SaveDocument method returns the following error codes.

Error Return Value	Description
S_OK	Success
DE_E_INVALIDARG	Invalid argument (invalid parameter, missing parameter, or incorrect type)
DE_E_PATH_NOT_FOUND	The path is not valid. Also occurs if you specify drive letter but no backslash (c:sample.htm instead of c:\sample.htm). Note This error will also be returned if you pass a path such as c:\sample.htm but are working with a language (such as JavaScript) that treats the "\" character as an escape character. If you are coding in such a language, use the proper method for indicating the backslash. Frequently this means doubling it: c:\\sample.htm.
DE_E_DISK_FULL	Not enough disk space to write the file
DE_E_ACCESS_DENIED	Insufficient access privileges for this file, or for a directory in the path
DE_E_OUTOFMEMORY	Out of memory
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

The SaveDocument method sets the following properties:

CurrentDocumentPath is set to the path and name of the document.

IsDirty is set to False after the document is saved.

The SaveDocument method is synchronous. The method does not yield until the control has finished saving the document. Because the method is synchronous, the Busy property is not set, and the DocumentComplete event does not fire.

This method is not supported by the version of the control marked as safe for scripting.

See Also

The DHTML Editing Component and Browser Security, Loading and Saving Documents

SetContextMenu Method

Description

Sets the menu items for the current document's right-click context menu.

Syntax

object. SetContextMenu menuStrings, menuState

Part	Description
object	The DHTML Editing control
menuStrings	SafeArray containing VARIANTs of type VT_BSTR, one for each of the context menu items to show. An empty string indicates a separator line. An ampersand (&) in an element of menuString indicates that the character after the ampersand is an access (mnemonic) key. To clear the context menu, pass an array dimensioned to zero in this parameter.
menuState	SafeArray of VARIANTs of type OLE_TRISTATE (long). Each element corresponds to an element in menuStrings. Possible values are: OLE_TRISTATE_UNCHECKED (0) Displays the menu item unchecked. OLE_TRISTATE_CHECKED (1) Displays a check mark next to the menu item. OLE_TRISTATE_GRAY (2) Makes the menu item appear unavailable. To clear the context menu, pass an array dimensioned to zero in this parameter.

Error Codes

The SetContextMenu method returns the following error codes.

Error Return Value	Description
DE_E_INVALIDARG	Invalid argument (invalid parameter, missing parameter, or incorrect type)
DE_E_UNEXPECTED	Control is in an unexpected state. This error can occur if this method is invoked prior to the DocumentComplete event occurring.

Note Error constants are defined in include files. For details about getting the correct include file for the language you are using, see Requirements. For details about trapping errors, see Handling Errors in the DHTML Editing Control.

Remarks

This method can be called just once for a static context menu, or called in response to the ShowContextMenu event in order to build a dynamic context menu. To determine what item a user has selected from the context menu, create a handler for the ContextMenuAction event.

The following Visual Basic example shows how to build a context menu of three items for a DHTML Editing control called DE1:

Private Sub CreateContextMenu()
    Dim MenuText(3)
    Dim MenuState(3) As OLE_TRISTATE
    MenuText(0) = "Choice 1 (Unchecked)"
    MenuText(1) = "Choice 2 (Checked)"
    MenuText(2) = ""    ' Line
    MenuText(3) = "Choice 3 (Gray)"
    MenuState(0) = Unchecked
    MenuState(1) = Checked
    MenuState(3) = Gray
    DE1.SetContextMenu MenuText, MenuState
End Sub

To clear the menu, use a call such as the following:

dim MenuText(0)
dim MenuState(0)
DE1.SetContextMenu MenuText, MenuState