Methods and systems for objects supporting structured language persistent state6799301Abstract A converter converts between structured language elements and objects embeddable in the native format of a document editor. A data structure representing the embeddable object is created without instantiating an instance of the object and includes the associated structured language element. Subsequently, the structured language element is used to instantiate an object and set its properties. Any portion of the structured language element not recognized during the conversion process is retained by the embeddable object. If conversion back to a structured language element is subsequently required, the conversion process is facilitated by the presence of the original structured language element within the embeddable object as well as the retained portion of the structured language element not recognized. Claims We claim: Description COPYRIGHT AUTHORIZATION
<FORM ACTION="http://a.b.c/xyz.cgi" METHOD="post">
<P>
Please enter a choice:
<INPUT TYPE="TEXT" MAXLENGTH="25" NAME="CHOICE">
</P>
<INPUT TYPE="submit" NAME="OK">
<INPUT TYPE="reset">
</P>
</FORM>
Some of the form elements have an HTML element name of "INPUT" and an optional "TYPE" attribute keyword. If the "TYPE" attribute keyword is omitted, the form element defaults to a text box. If the "TYPE" attribute keyword specifies an attribute value of "radio," "checkbox," "submit," or "reset," the form element will appear as a graphical radio button, a check box, a submit push button, or a reset push button, respectively, when rendered. Some form elements, such as the "TEXTAREA" form element do not use the "TYPE" attribute keyword. The HTML language specification includes other form elements, and new ones may be added as HTML is extended or enhanced. Each of the form elements may have additional attributes which are indicated by an HTML attribute keyword and an HTML attribute value. For example, a text box may have the attribute of MAXLENGTH with an attribute value of "25". HTML elements with the name "FORM" ordinarily contain the HTML form elements known as the "reset" and "submit" elements which are HTML elements with the element name of "INPUT" and a TYPE of either "reset" or "submit." When rendered, these elements typically appear as graphical push buttons and may be used to clear the form or send its contents according to a predetermined protocol (e.g. "submit" or "post"), which is indicated in the "FORM" element with the keyword "METHOD." These elements need not be rendered as push buttons, and can be, for example, an image or some other item. When the HTML document is rendered for presentation to the user, the user can place information in the text boxes, select a radio button, or click on the "submit" graphical push button to submit the information placed in the form. The "submit" button can also be an image map. An image map is essentially a "submit" button in the form of an image. When the image map is clicked (i.e., the user clicks a mouse button or some other device while a pointer is positioned over the image map), the associated form is submitted along with additional information concerning where (i.e., the x-y coordinates) within the image map the click occurred. Numerous other HTML elements exist, such as the "MARQUEE" HTML element, which provides scrolling text, and the "VIDEO" HTML element which provides video. Some HTML elements may not require presentation in the document display area. For example, the "BGSOUND" HTML element provides a background sound (e.g., music that plays while the document is viewed) but need not be shown in the document display area. As discussed above, the number of HTML elements and their features continually grow as HTML is extended and enhanced. Storage and Stream Overview Data on a personal computer 20 may be arranged in many ways. One way of arranging data is by using a storage or stream. A storage is a data location that may itself contain data or refer to streams and/or other storages. Streams comprise data of any type and are not required to have a particular internal structure. Storages and streams are well known and may be arranged according to the OLE structured storage model. For a detailed description of storages and streams, see Inside OLE 2 by Kraig Brockschmidt, Microsoft Press, Redmond, Wash. 1994. ActiveX Controls Overview With reference to FIGS. 5, 11, 13, 15, and 18, the illustrated embodiment of the invention utilizes embeddable objects conforming to the ActiveX Controls specification of Microsoft Corporation. ActiveX controls conform with the component object model (COM) of Microsoft Corporation and are related to Microsoft's OLE standards. For a detailed discussion of COM, ActiveX and OLE, see Understanding ActiveX and OLE by David Chappell, Microsoft Press, Redmond, Wash. 1996. A brief overview of ActiveX controls and associated terminology is provided below before discussing the details of the illustrated embodiment. It will be appreciated that embeddable objects may follow other specifications such as the CORBA (Common Object Request Broker Architecture) specification of Object Management Group or be of other formats embeddable in a document editor's native document format. ActiveX controls are programming objects conforming to Microsoft's COM specification. An object is an instance of a programmer-defined type referred to as a class, which exhibits the characteristics of data encapsulation, polymorphism and inheritance. Data encapsulation refers to the combining of data (also referred to as properties of an object) with methods that operate on the data (also referred to as member functions of an object) into a unitary software component (i.e., the object), such that the object hides its internal composition, structure and operation and exposes its functionality to client programs that utilize the object only through one or more interfaces. An interface of the object is a group of semantically related member functions of the object. In other words, the client programs do not access the object's data directly, but must instead call functions on the object's interfaces to operate on the data. Polymorphism refers to the ability to view (i.e., interact with) two similar objects through a common interface, thereby eliminating the need to differentiate between two objects. Inheritance refers to the derivation of different classes of objects from a base class, where the derived classes inherit the properties and characteristics of the base class (such as the interfaces of the base class). The COM specification defines binary standards for objects and their interfaces which facilitate the integration of software components. At FIG. 5, a typical object 170 is represented in the computer system 20 (FIG. 1) by an instance data structure 172, a virtual function table 174, and member functions 176-78. The instance data structure 172 contains a pointer 180 to the virtual function table 174 and the data 182. A pointer is a data value that holds the address of an item in memory. The data 182 can include the properties (or data members) 183 and 184. The virtual function table 174 contains the entries 186-88 for the member functions 176-78. Each of the entries 186-88 contains a reference to the code 176-78 that implements the corresponding member function. The pointer 180, the virtual function table 174, and the member functions 176-78 implement an interface of the object 170. Client programs interact with the object 170 by obtaining a pointer (referred to as an interface pointer) to the pointer 180 of the virtual function table 174. The following code (in the C++ programming language) implements a call to member functions of an interface pointed to by pointer pinterface: pinterface->MemberFunction( . . . ) By convention, the interfaces of an object are illustrated graphically as a plug-in jack as shown for the IPersistHTML interface 406 at FIG. 11. Also, interfaces conventionally are given names beginning with a capital "I." Objects can include multiple interfaces which are implemented with one or more virtual function tables. The member function of an interface is denoted as "IInterfaceName::FunctionName." The object 170 conforming to the COM specification exhibits data encapsulation by exposing its interfaces (semantic groupings of its member functions) to client programs. The client programs interact with the object 170 by calling the member functions 176-78 on a particular interface of the object, but do not directly manipulate the object's data. The object 170 also exhibits polymorphism and inheritance in that the object 170 can provide interfaces in common with a base class and other similar objects, so that client programs can interact with each of the objects in the same manner by calling member functions of the interface that the objects have in common. ActiveX controls conform to the COM standard described above. The class of an ActiveX control is uniquely identified by a class identifier (CLSID). Certain interfaces to an ActiveX control, such as IPersistStreamInit are well known in the art and are described in more detail below. For a detailed discussion of various interfaces provided by various ActiveX controls, see Understanding ActiveX and OLE by David Chappell, Microsoft Press, Redmond, Wash. 1996. Part of the ActiveX Controls specification requires that the ActiveX control be able to associate a particular one of its properties with a dispatch identifier (DISPID). Thus, the DISPID can serve as a property identifier. The dispatch identifier is an integer value and can be used in conjunction with a particular interface called IDispatch to set or read the properties of an ActiveX control. One of the methods (or member functions) provided by IDispatch is called Invoke. The IDispatch::Invoke method itself includes methods arranged in a dispinterface. Given an integer value, the dispinterface invokes one of the methods of the dispinterface, and passes any provided parameters to the method. Commonly, these methods of the dispinterface are operable to set or read the properties of ActiveX control. Thus, the Invoke method can be used to set or read a property of an ActiveX control if provided with the following: the DISPID that identifies the particular property to be set or read (which is used to determine the associated property-setting or property-reading method), whether the property is to be set or read, and a value for setting or a location for reading the property. In this way, properties of an ActiveX control can be set or read with reference to the DISPID associated with a particular property. The IPersistStreamInit interface provides a means for an object to persist itself. An object may be in any number of possible states at a given time. For instance, the properties may be set to particular values (e.g., a graphical push button may have its "name" property set to "OK"). Persisting an object means producing and storing whatever state data is required for the object to restore its present state at some subsequent time. Later, the object "depersists" (e.g. acquires its state data) by accessing the state data to restore the previous state. The state data is typically of some format not compatible with HTML. Accordingly, the IPersistStreamInit interface provides two methods, IPersistStreamInit::Save and IPersistStreamInit::Load. IPersistStreamInit::Save generates a stream (the persisted state of the object). If this stream is provided to IPersistStreamInit::Load, the object is restored to its present state. Another interface, IPersistStorage, operates in a similar manner but uses a storage instead of a stream. Part of the ActiveX specification provides for embedding an ActiveX control within another object. The object in which the ActiveX control is embedded is called a control container. The application that can manipulate the ActiveX control embedded in a control container is sometimes called an ActiveX control host. Example ActiveX control hosts are Microsoft Visual Basic, the Internet Explorer, and Microsoft Word 97 of Microsoft Corporation. Applications typically implement their documents as objects, so in an arrangement in which an ActiveX control is embedded in a document editor's document involves an object (the ActiveX control) contained by another object (the control container or document), both of which can be manipulated by the host (the document editor). Embedding is achieved through a particular set of interfaces of the control container and the embedded object. These interfaces provide a way for the control container and the embedded object to communicate about such details as when the embedded object should display itself or be redrawn. For further details concerning embedding, see Understanding ActiveX and OLE by David Chappell, Microsoft Press, Redmond, Wash. 1996. It will be appreciated that a wide variety of embeddable ActiveX controls such as text boxes, graphical push buttons, background sounds and scrolling texts exist, and additional ones can be created. Microsoft Word 97 Overview Microsoft Word 97 is a document editor offering a word processing environment with a rich set of features including WYSIWYG editing, spell checking, and an extensive on-line help facility. Microsoft Word 97 can create, edit, and save documents as well as copy, cut, and paste items into and out of Microsoft Word 97. Microsoft Word 97 can host an ActiveX control and its native documents can serve as ActiveX control containers that support embedding of ActiveX controls. Further, an embedded ActiveX control and its properties can be manipulated within Microsoft Word 97. RTF Overview Rich Text Format (RTF) is one of the document formats Microsoft Word 97 can convert into its native format. RTF is a well-known format used to represent formatted text and includes mechanisms for marking text as bold and italic. RTF supports many features such as color tables, style sheets, hidden text, storage of document statistics, and others. RTF also has provisions for placing objects such as ActiveX controls into an RTF stream. RTF is a plain text format that is ordinarily presented to a user in rendered form. Certain HTML tags are readily translated into RTF. For example, the HTML tag "<B>" is associated with bold text, and the HTML tag "<BR>" indicates a line break. Each of these have a corresponding RTF translation. Since Word can convert RTF into its own internal format, Microsoft Word 97 can be used to convert an RTF document, view the document, and edit it in Microsoft Word 97's feature-rich environment, including WYSIWYG editing, spell checking, and an extensive on-line help facility. Overview of HTML Document to Microsoft Word 97 Native Format Document Conversion Process A flowchart illustrating an overview of the HTML document to Microsoft Word 97 native format conversion process is shown at FIG. 6. At step 192, the HTML document is converted to an RTF stream. Then, at step 194, the RTF stream is converted to a document (e.g., a document in Microsoft Word 97 native format). Finally, at step 196, the document is displayed. One of the features of the invention is that the logic pertaining to step 192 does not have to include logic to instantiate and set the properties of objects. In this way, the HTML to RTF converter logic can be smaller, and the same converter logic can be used to process HTML documents containing new extensions or enhancements. Although the illustrated embodiment first converts the document to RTF, conversion to some other intermediate format, directly to Microsoft Word 97's native format, or directly to any number of other formats could be achieved. An HTML to RTF converter is illustrated at FIG. 7. Converter controller 212 controls the conversion process. The HTML document 210 is a file comprising HTML tags. The HTML document 210 may reside as a file of a file system stored in the hard drive 27 (FIG. 1) or other secondary storage of a personal computer 20, or reside as resources at a remote computer 58 (FIG. 2) connected to the computer network 57, such as a world-wide web site on the Internet or an intranet. The flags 216, a CLSID 220, and an HTML stream 218 are shown as inside a storage 214; however, it will be appreciated that in FIG. 7 and the other figures, a storage may be internally represented as pointers to the items. The RTF stream 222 is a location into which text in Rich Text Format corresponding to the HTML document 210 is written. The Structured Language Element-to-Embeddable Object Class Association Table 224 associates an HTML tag component 226 with a particular class identifier 234. The Table 224 is described in more detail below. A temporary location 202 is used to temporarily store portions of the HTML document 210. One way to start the conversion process is to open the HTML Document 210 with the Microsoft Word 97 application. Microsoft Word 97 provides a familiar means of opening a document with the "File, Open . . . " command available from the Microsoft Word 97 menu bar. The user selects the HTML document 210, and Microsoft Word 97 proceeds according to the HTML to RTF conversion method illustrated at FIG. 8. At step 252, the HTML document 210 is examined to determine if it contains HTML. A common method for making such a determination is examining the HTML document 210 for the HTML indicator "<HTML>". If "<HTML>" is present, the conversion process continues by opening the Rich Text Format (RTF) stream 222. If there is no "<HTML>", the HTML document 210 is opened according to some non-HTML procedure. It will be recognized that other methods for determining if the HTML document 210 contains HTML may be used, such as detecting any HTML tag within the document or detecting a particular filename extension (e.g., ".html" or ".htm"). At step 254, the HTML document 210 is parsed according to familiar parsing procedures so that a next portion of the document is contained in the temporary location 202. For instance, if the next portion of the HTML document 210 contains an HTML tag, the tag is placed in the temporary location 202. If, instead, the next portion of the HTML document 210 contains plain text that is not an HTML tag, the plain text is placed into the temporary location 202. In special cases an entire HTML element is required for conversion. In such a case, if a particular HTML begin tag is detected, the HTML begin tag, the text following the tag (if any), and the HTML end tag are placed into the temporary location 202. For example, the HTML tag name "TEXTAREA" indicates the begin tag of an HTML "TEXTAREA" form element. If such an HTML tag is encountered, additional information is read from the HTML document 210 into the temporary location 202 until an HTML "</TEXTAREA>" end tag is encountered. The special cases are indicated within the parsing logic. It will be appreciated that the parsing process may take many forms, such as using index pointers to the document denoting the begin and end locations of the respective portion of the document instead of copying the next portion to a separate location. Next, the contents of the temporary location 202 are examined. First, at step 256, the temporary location 202 is examined to determine if it contains an HTML "FORM" tag (i.e., an HTML tag with a tag name of "FORM"). If so, the beginning of a form is indicated. At step 258, a top of form break is inserted into the RTF stream 222 as the text phrase "Top of FormF" (where F is the number of the current form in the document, starting with 1) formatted with a special paragraph style "z-Top of Form". Special allowance is made for storing information contained in the "FORM" tag relating to the submission of the form so that it can be retrieved later when creating an associated "INPUT" HTML element for submitting the form, as described below. Certain error checking is included at this point to detect if a Microsoft Word 97 form is begun while another Microsoft Word 97 form has already begun and not ended. Second, at step 260, the temporary location 202 is examined to determine if it contains an HTML "</FORM>" tag, which denotes the end of an HTML form. If the "</FORM>" tag is present, a bottom of form break is written into the RTF stream 222 at step 262. The bottom of form break is inserted into the RTF stream 222 as the text phrase "Bottom of Form F" (where F is the number of the current form in the document) formatted with a special paragraph style "z-Bottom of Form". Certain error checking is included at this point to detect if there is no Microsoft Word 97 form that has been begun and not ended. It will be appreciated that the top and bottom of form breaks could be denoted in any number of ways, such as by placing a set of special characters into the RTF stream 222. Third, at step 264, the method uses the Structured Language Element-Embeddable Object Class Association Table 224, described below, to determine an appropriate CLSID 220. If Table 224 indicates an appropriate class identifier 234 or 236, the temporary location 202 relates to an object (e.g., an ActiveX control for representing a text box, a graphical push button, or scrolling text). Then, a persisted state of an object is created in the storage 214 at step 266. The persisted state is created by creating a storage 214, placing the class identifier 234 or 236 indicated by the Table 224 into the CLSID 220, placing the text contained in the temporary location 202 in the HTML stream 218, and marking the storage as HTML by setting the flags 216. It will be appreciated that the determination of whether to convert the temporary location 202 to an object could alternatively be made by examining some other data structure such as a list of structured language tag components. Then, at step 270, the storage 214 is converted to a stream using the well known OleConvertIStorageToOLESTREAM function and passed to the RTF stream 222. Preferably, a special RTF tag is used to denote that the stream relates to HTML when it is passed to the RTF stream 222. If no class identifier 234 or 236 is determined at step 264, the temporary location 202 is converted to Rich Text Format (RTF) at step 268 according to familiar methods and placed into the RTF stream 222. If any additional information from the HTML document 210 is required to complete the conversion to RTF, it is read from the HTML document 210. If the conversion to RTF cannot be made, the HTML is ignored. At step 272, the method checks for an EOF condition to determine if the end of the HTML document 210 has been reached. If so, the HTML document 210 is closed, the RTF stream 222 is ended, and the method ends. Otherwise, the next portion of the HTML document 210 is parsed in a further iteration of steps 252-270. The conversion process also handles certain additional details of parsing HTML, such as the well known specialized "<HEAD>" and "<BODY>" tags. Additional details of the conversion process are described below. Structured Language Element-to-Embeddable Object Class Association Table In order to facilitate the HTML element to embeddable object conversion process, the converter uses a Structured Language Element-to-Embeddable Object Class Association Table 224 illustrated at FIG. 7. An entry 226 in the Table 224 associates an HTML tag component 226 with an object class identifier (CLSID) 234. For example, if the temporary location 202 comprises the tag component "MARQUEE", the Table 224 is consulted for the tag component "MARQUEE" and an entry 226 is found indicating a class identifier 234 of CLSID_ScrollingText. The class identifier 234 of an object providing marquee functionality (an ActiveX control providing scrolling text) is stored in the CLSID 220. The Structured Language Element-to-Embeddable Object Class Association Table 224 is implemented as two parallel arrays, one comprising HTML tag components, the other comprising class identifier information. When an index to the one array indicates a certain tag component, the same index to the other array indicates the associated class identifier. With respect to step 264, above, one of the HTML tag components 204, 206, or 208 is selected, then the Table 224 is searched for the selected tag component. In some cases, an HTML tag component 204, 206, or 208 may indicate a default value (e.g., the HTML tag component "INPUT" defaults to a TYPE of "TEXT."), in which case the table is searched for the default if no HTML tag component indicates otherwise. The Table 224 is searched by matching the selected tag component 204, 206, or 208 with the HTML tag components 230 or 232. If an entry 228 with a match 230 is found, the associated class identifier 236 indicates the class identifier to be stored in the CLSID 220. Converting an RTF Stream to a Microsoft Word 97 Document After the HTML document 210 has been converted to the RTF stream 222, the RTF stream 222 is converted to a document (e.g. a Microsoft Word 97 native format document). FIG. 9 is a block diagram showing a document editor controller 306 (e.g. Microsoft Word 97), an RTF stream 304, and a document 318. The document 318 may reside as a file of a file system stored in the hard drive 27 (FIG. 1) or other secondary storage of a personal computer 20, or it may be located in the RAM 25 of the system memory 22. A method for converting the RTF stream 304 to the document 318 is illustrated at FIG. 10. At step 352, the next portion of the RTF stream 304 is parsed according to familiar methods into the temporary location 302. At step 354, it is determined if the temporary location 302 is to be converted to a storage by detecting a special RTF tag in the temporary location 302. At step 356, a storage 308 is created, and the contents of the temporary location 302 are used to determine the flags 310, the CLSID 312, and the HTML stream 314. The CLSID 312 and the HTML stream 314 are related to the CLSID 220 and the HTML stream 218 of FIG. 7. A link 316 between the document 318 and the storage 308 is kept so that it can be determined where within the document 318 the storage 308 resides. If at step 354, it is determined that the temporary location 302 is not to be converted to a storage, at step 358, the temporary location 302 is converted to the format of document 318 (e.g. Microsoft Word 97 native format) according to familiar methods and passed to the document 318. At step 360, it is determined if the end of the RTF stream 304 has been reached. If so, the method ends, otherwise the RTF stream 304 is parsed in a further iteration of steps 352-358. After the RTF stream 304 is converted to the document 318, the document 318 is displayed as described below. Preparing the Document for Display At FIG. 11, a document 402 (e.g. a Microsoft Word 97 document) is displayed by a document editor controller 404 (e.g. Microsoft Word 97). The process for displaying the document 402 is well known. Commonly, the entire document 402 is not displayed at once. Instead, a certain portion of it is rendered for presentation to the user. As part of the display process, a facility is implemented to indicate when a particular item is to be presented to the user. When the facility indicates that an item relating to a storage 412 or 416 has come into view for presentation to the user, the following method for presenting the storage to the user is used if the flags 418 indicate that the storage 416 relates to HTML. The method is shown at FIG. 12. At step 454, an object 408 is instantiated using the CLSID 422. At step 456, a link 424 to the object 408 is placed in the document 402 to indicate where within the document 402 the object 408 resides. Then, at step 458, the HTML stream 420 is passed to the object 408 using the LoadHTML member function of the IPersistHTML interface 406 (IPersistHTML::LoadHTML) which stores the HTML stream 420 in the HTML stream 414. The details of IPersistHTML::LoadHTML are described below. Using the HTML Stream with IPersistHTML::LoadHTML With reference to FIG. 13, after the HTML stream 520 has been passed to the object 504 using the LoadHTML member function of the IPersistHTML interface 502, a property 506 of the object 504 may need to be set to a value such as 512. Although not required, preferably, the object 504 uses a software routine that can assist during the property setting process. The object 504 passes the HTML stream 520 and a Structured Language Attribute-to-Embeddable Object Association Table 530 to a property setting software routine 516 called LoadPropertiesFromHTMLStream. Preferably, the Structured Language Attribute-to-Embeddable Object Association Table is defined as part of the class of objects identified by the CLSID 422 (FIG. 11) used to instantiate the object 504. LoadPropertiesFromHTMLStream parses the HTML stream 520 and uses the Structured Language Attribute-to-Embeddable Object Property Association Table 530 to set the properties 508 and 506 of the object 504. The Structured Language Attribute-to-Embeddable Object Property Association Table 530 contains entries for use during the property setting process. Each entry 532 or 534 in Table 530 contains an HTML attribute keyword 536 and a corresponding object property identifier (e.g. an ActiveX control dispatch identifier or DISPID) 538. The Structured Language Attribute-to-Embeddable Object Property Association Table 530 is implemented as an array of HTML_ATTR_DESC structs.
struct HTML_ATTR_DESC
{
DISPID dispid; // dispid of corresponding property.
LPTSTR pszName; // Name of Attribute.
VARTYPE vt; // variant type of the property.
long lvalueImplied;
// If not null, the implied value if name but no
// value. So, if an attribute is present, but does not
// contain a declared value, this will be used.
BOOL fImpliedBool;
// Presence of this attribute implies True
// but the property does not have a value,
// e.g., the MULTIPLE property of the
// SELECT tag. Absence implies False.
};
The members of the struct can be used to track special cases, such as the "CHECKED" attribute which defaults to a value of "TRUE." Arrays and structs are well known data structures available in the C and C++ languages. An example table 530 for a text box (i.e., an HTML "INPUT" element with a type of "TEXT") follows:
// This is an example
// for a text box. It also works for a "password" HTML element.
HTML_ATTR_DESC s_TextHTMLProps[] =
{
{ DISPID_WHTMLType, TEXT("TYPE"), VT_BSTR, 0,
FALSE },
{ DISPID_WHTMLMaxLength, TEXT("MAXLENGTH"), VT_I4, 0,
FALSE },
{ DISPID_WHTMLWidth, TEXT("WIDTH"), VT_I4, 0,
FALSE },
{ DTSPID_GROUPNAME, TEXT("NAME"), VT_BSTR, 0,
FALSE },
{ DISPID_VALUE, TEXT("VALUE"), VT_BSTR, 0,
FALSE }
};
It is contemplated that as new objects are written by software developers, the new objects may use LoadPropertiesFromHTMLStream during the property setting process by providing a Structured Language Attribute-to-Embeddable Object Property Association Table 530 to facilitate conversion between HTML and a new object developed by the developer. In this way, the new object avoids having to duplicate the functionality of LoadPropertiesFromHTMLStream, and the logic in the control can be smaller. The object is not required to use LoadPropertiesFromHTMLStream. Also, it will be appreciated that the properties 506 and 508 of the object 504 may be set in any number of other ways such as by another program or another object. LoadPropertiesFromHTMLStream is defined as follows:
// Parse a string containing HTML attributes and set
// corresponding properties of punkObject.
// Attributes that are not recognized are returned, unmodified,
// in bstrNotRecognized.
HRESULT LoadPropertiesFromHTMLStream (
IUnknown * punkObject,
IStream * pstream,
LONG cAttributes,
HTML_ATTR_DESC * ahtmlattrAttribute,
BSTR * bstrNotRecognized );
LoadPropertiesFromHTMLStream operates according to the following method illustrated at FIG. 14 with reference to FIG. 13. The HTML stream 520 is the stream of HTML associated with the object 504 and is used to set the properties 506 and 508. Typically, only a certain portion of the HTML stream 520 is provided to LoadPropertiesFromHTMLStream. The HTML element name or other HTML tag components may be omitted. At 552, parsing is performed on the certain portion of the HTML stream 520 which results in an HTML attribute keyword 526 and HTML attribute value 528 stored in the temporary location 524. At step 554, the Table 530 is searched for the HTML attribute keyword 526. If there is an entry 534 in the Table 530 with an HTML attribute keyword 536 that matches the HTML attribute keyword 526, the table indicates how to process the temporary location 524. At step 560, the associated DISPID 538 of the entry 534 is used to set a property 506 of the object 504 to a value 512 by using the value 528. Preferably, the value 512 of the property 506 is set using a call to the Invoke member function of the interface IDispatch 514 (IDispatch::Invoke). The call to IDispatch::Invoke specifies the DISPID 538 relating to the property 506, the value 528, and that the value 512 is to be set. At step 562, a bit of the found bitmap 518 is set, indicating that the property 506 was set. If the Table 530 fails to indicate how to process the temporary location 524, the keyword 526 and the value 528 are preserved at step 558 in the HTML not recognized 522, which the object 504 preferably retains for later retrieval. LoadPropertiesFromHTMLStream operates to properly manipulate any necessary tag delimiters and associations between HTML attributes keywords and their corresponding HTML attribute values. For example, the HTML "INPUT" element of type "RADIO" relating to a radio button presents a special case because the HTML attribute keyword ("CHECKED") does not have a related HTML attribute value (it implicitly has an attribute value of "TRUE"). Also, an HTML "INPUT" element defaults to a type of "TEXT." Special provisions are made for setting the properties of an ActiveX control relating to an HTML "INPUT" element of type submit or image. Certain information related to the submission of the form is gathered from a location where it was stored previously during the processing of an HTML "FORM" element, as described above. At step 564, it is determined if the end of the HTML stream 520 has been reached. If so, the method ends. Otherwise, the next portion of the HTML stream 520 is parsed in a further iteration of steps 552-562. After the properties have been set, the flags 510 are set to indicate that the object 504 relates to HTML and that no changes have been made to it. Various other properties of the object 504 may be set as needed by the document editor. For example, the object may have a name assigned to it by the document editor. This name is assigned in addition to the HTML name as determined during the property setting process described above. The object 504 then has the information it needs to present itself to the user. Editing the Document When the document editor controller 404 (FIG. 11) displays the document 402, the user is presented with the option of toggling between a form edit mode and a run mode. During form edit mode, the user may make examine or alter the properties of objects embedded in the document. A change to an object may result in storing a value in its associated flags 510 and the found bitmap 518 to indicate that it has been changed. Similarly, a newly created object may have its flags 510 and found bitmap 518 set accordingly. During run mode, the objects may be operated by the user to perform their functions. For example, during form edit mode, the user may change the appearance or position of the reset push button. During run mode, the user may click on the reset push button to clear the values in the form associated with it. An object in a form may need to determine what other objects are located within the same form. For instance, when the user selects one of a set of related radio buttons or clicks on the submit or reset button, information relating to other objects in the form must be retrieved or altered. For example, when the user clicks on a "reset" button, the values in the objects associated within the same form breaks are cleared. Preferably, a function within the document editor searches the document to determine what other objects are located within the same form as a particular object. Finally, after the HTML document has been converted to the format of the document, the user may save the document (e.g., by using the "File, Save As . . . " command from the Microsoft Word 97 menu bar and specifying native format of Microsoft Word 97, also known as "normal" format). The document editor then writes the document to a location specified by the user using the document editor's native format. Microsoft Word 97 presents other ways for converting documents from HTML to the native format of Microsoft Word 97. For example, the user may create a new HTML document by using the "File, New . . . " command from the menu bar and specifying a document type of HTML. After entering HTML text into the document, the user may then save the document in Microsoft Word 97 format (i.e., by using the "File, Save As . . . " command of Microsoft Word 97). As another example, the user may choose "View, HTML Source" from the menu bar, and enter HTML text into the HTML source window. When the user switches from the HTML source, the HTML source is converted into Microsoft Word 97 native format. The user may subsequently save the document in Microsoft Word 97's native format. These methods use the above steps to convert the HTML source to an RTF stream and then to associated objects if required. If an object relates to a form, its class identifier (CLSID) preferably denotes one of the ActiveX controls that are part of Forms.sup.3, a set of ActiveX controls provided by Microsoft Corporation. However, HTML elements other than form elements may be converted to ActiveX controls. For instance, an HTML element indicating a background sound or scrolling text (i.e. "MARQUEE") may be converted to an equivalent ActiveX control. If the C++ programming language is used to represent an ActiveX control, it may be advantageous to use fewer C++ classes than ActiveX control classes. This arrangement avoids having a separate virtual function table for each ActiveX control and is accomplished by using a single C++ class to represent more than one object while changing a property of the class (e.g. a "style" property). This arrangement is also known as aggregating classes. Overview of Document Native Format to HTML Document Conversion Process Microsoft Word 97 can convert a Microsoft Word 97 document to an HTML document by performing the methods described below. For example, the user may select the "Save As HTML . . . " command from the menu bar, and the current document is saved as an HTML document. The current document may be a newly created document, a document that has converted according to the methods described above, or a document resulting from some other method. The document to HTML document conversion process is illustrated at FIGS. 15 and 16. A document 602 is converted into an HTML document 614. At step 652, an HTML indicator "<HTML>" is written to the HTML document 614. The conversion process then continues at 654 by parsing the next item in the document 602. At step 656, if the item is determined to be a top of form break, an HTML "FORM" tag is written to the HTML document 614 at step 658. Certain information concerning the "FORM" tag is gathered from the object corresponding to a submit button or image associated with the top of form break. At step 660, if the item is determined to be a bottom of form break, an HTML "/FORM" tag is written to the HTML document 614 at step 662. At step 664, if the item is an object 606, the flags 610 are examined to determine if it is to be converted to HTML. If so, the object 606 is converted to HTML and written to the HTML document 614 at step 666 using the SaveHTML member function of the IPersistHTML interface 608 (IPersistHTML::SaveHTML). Details concerning step 666 are described below. If the item is a storage representing an uninstantiated object, the HTML can be read out of the HTML stream in the storage and written to the HTML document 614 without instantiating an object. Otherwise, at step 668, the item is translated to HTML according to well known methods. For example, the Microsoft Word 97 representation of boldface text is converted to the associated HTML tags denoting boldface text ("<B>" and "</B>"). At step 670, it is determined if the end of the document 602 has been reached. If so, the end HTML indicator "<IHTML>" is written to the HTML document 614 and the method ends. Otherwise, the document 602 is parsed in a further iteration of steps 654-668. The conversion process also handles certain additional details of generating HTML, such as the well known specialized "<HEAD>" and "<BODY>" tags. Further, the conversion process writes certain identifying information to the HTML document 614. Many other types of information relating to a variety of HTML tags may be placed in the HTML document 614 as part of the conversion process. Microsoft Word 97 offers other methods for converting from Microsoft Word 97 native format to HTML. For instance, the user may select "View, HTML Source" from the menu bar to see the HTML source equivalent of the present document. This method uses the above steps, but presents the HTML to the user in a graphical window instead of writing it to an HTML document 614. Converting an Object into an HTML Element with IPersistHTML::SaveHTML Step 666 of the above method performs the following method illustrated by the flowchart at FIG. 17 to convert an object 606 (FIG. 15) to a stream of HTML which is written to the HTML document 614. The method is implemented as a member function SaveHTML of the IPersistHTML interface 608 (IPersistHTML::SaveHTML). At step 702, the HTML stream 612 is checked to see if it is empty, and the flags 610 are checked to see if they indicate that changes have been made to the object 606. If either condition is true, the method uses a stream of HTML generated from the object 606 at step 704. Otherwise, the method uses the HTML stream 612 from the object 606. Using the HTML stream 612 facilitates the conversion process because no additional conversion logic is required. Generating a Stream of HTML from the Object Step 704 includes logic further illustrated at FIGS. 18 and 19. The object 754 is converted to a stream of HTML which is then provided by the IPersistHTML interface 752. Although it is not required, the object 754 preferably uses a property reading software routine 778, SavePropertiesToHTMLStream, to assist in producing the stream of HTML. For example, an ActiveX control relating to scrolling text may first produce the initial part of the stream of HTML, (e.g., <MARQUEE), call SavePropertiesToHTMLStream to produce another part of the stream of HTML, (e.g., BEHAVIOR="ALTERNATE" WIDTH="764" HEIGHT="27" GIBBER="important"), and then produce the final part (e.g., >Sample Text</MARQUEE>), resulting in the following stream of HTML:
<MARQUEE BEHAVIOR="ALTERNATE" WIDTH="764"
HEIGHT="27" GIBBER="important">Sample Test</MARQUEE>
The property reading software routine 778 SavePropertiesToHTMLStream is defined as follows:
// Get properties of punkObject, convert to an HTML attribute format,
// save those properties plus bstrNotRecognized to the stream.
// Only properties whose corresponding bit is Set in dwFound are written.
// (if bit i is set, that means that the attribute described by
// ahtmlattrAttribute[ i ] is saved.)
HRESULT SavePropertiesToHTMLStream (
IUnknown * punkObject,
IStream * pStream,
LONG cAttributes,
HTML_ATTR_DESC * ahtmlattrAttribute,
DWORD * dwFound,
BSTR bstrNotRecognized );
SavePropertiesToHTMLStream uses a Structured Language Attribute-to-Embeddable Object Property Association Table 780. Preferably, this is the same Table 530 (FIG. 13) than can be used with the LoadPropertiesFromHTMLStream property setting software routine 516 described above. The method performed by SavePropertiesToHTMLStream is illustrated at FIG. 19. The method starts at the first entry 782 and proceeds to the last entry 784 in the Table 780. At step 804, if the found bitmap 764 indicates that the value of the object property identified by the DISPID 788 is to be written to the stream of HTML provided by IPersistHTML::SaveHTML, the method proceeds to step 806. At step 806, the HTML attribute keyword 786 and the value 762 of the property 756 identified by the DISPID 788 are written to the stream of HTML provided by the IPersistHTML interface 752. Preferably, the value 762 of the property 756 is read from the object 754 by using a call to the Invoke member function of the interface IDispatch 776 (IDispatch::Invoke) that specifies the DISPID 788 relating to the property 756, and that the value 762 is to be read. Ordinarily, the HTML attribute keyword 786 is followed by a "=" character, and then a text representation of the value 762 of the property 756 in quotations follows, for example: MAXLENGTH="25" If it is determined at step 808 that there are no more entries in the table, the HTML not recognized 768 is provided by IPersistHTML::SaveHTML (for the HTML document 614), and the method ends. Otherwise, the next entry in the Table 780 is considered in a further iteration of steps 804-806. The process operates to properly handle special cases such as the radio button, described above. The process also ensures that HTML tag delimiters are written into appropriate locations in the stream of HTML provided by the IPersistHTML interface 752. The details of writing the properties may be varied. For example, quotations around the text representation of the value 762 (e.g., "25") may be omitted. Microsoft Word 97 can convert ActiveX controls other than those corresponding to HTML form elements into HTML. For example, an ActiveX control representing scrolling text can be converted into an HTML "MARQUEE" element. Similarly, Microsoft Word 97 implements conversion of video and background sounds. The IPersistHTML Interface To load an HTML element from or save an HTML element to an ActiveX control, Microsoft Word 97 uses the IPersistHTML Interface. The IPersistHTML Interface is related to the well known IPersistStreamInit interface, except that the persisted state of the object is HTML. IPersistHTML provides IPersistHTML::SaveHTML, which generates a stream of HTML sufficient for the object to restore its present state and IPersistHTML::LoadHTML, which, given a stream of HTML, restores the object to a prior state. The streams written or read by these methods are streams comprising HTML. It should be noted that an exact equivalence between an HTML element and an ActiveX control may not be achieved, so some state information may be lost or slightly modified. The present invention addresses this problem by retaining the original HTML used to generate the ActiveX control and retaining any HTML not recognized by the ActiveX control. The HTML not recognized may be later retrieved when the ActiveX control produces a stream of HTML. The IPersistHTML interface uses Unicode, a well known format for representing characters. However, some other format for representing characters (e.g., ASCII) could be used. Having described and illustrated the principles of our invention with reference to an illustrated embodiment, it will be recognized that the illustrated embodiment can be modified in arrangement and detail without departing from such principles. It should be understood that the programs, processes, or methods described herein are not related or limited to any particular type of computer apparatus, unless indicated otherwise. Various types of general purpose or specialized computer apparatus may be used with or perform operations in accordance with the teachings described herein. Elements of the illustrated embodiment shown in software may be implemented in hardware and vice versa. In view of the many possible embodiments to which the principles of our invention may be applied, it should be recognized that the detailed embodiments are illustrative only and should not be taken as limiting the scope of our invention. Rather, we claim as our invention all such embodiments as may come within the scope and spirit of the following claims and equivalents thereto.
|
Same subclass Same class Consider this |
||||||||||