From 76e0437984a0a708ba544ede15eec26f0d925c9d Mon Sep 17 00:00:00 2001 From: ishmal Date: Fri, 25 Apr 2008 15:30:50 +0000 Subject: [PATCH] More documentation --- src/dom/stylesheets.h | 172 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 149 insertions(+), 23 deletions(-) diff --git a/src/dom/stylesheets.h b/src/dom/stylesheets.h index e41b6775d..5fdc44f64 100644 --- a/src/dom/stylesheets.h +++ b/src/dom/stylesheets.h @@ -28,6 +28,14 @@ * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + * + * ========================================================================= + * NOTES + * + * Views, Stylesheets and CSS are DOM Level 2 for the purposes of supporting + * SVG. Be prepared in the future when they make Level 3 and SVG is likewise + * updated. The API here and many of the comments come from this document: + * http://www.w3.org/TR/DOM-Level-2-Style/stylesheets.html */ @@ -58,14 +66,20 @@ typedef dom::Node Node; #########################################################################*/ /** - * + * The MediaList interface provides the abstraction of an ordered collection of + * media, without defining or constraining how this collection is implemented. An + * empty list is the same as a list that contains the medium "all". + * + * The items in the MediaList are accessible via an integral index, starting from + * 0. */ class MediaList { public: /** - * + * The parsable textual representation of the media list. This is a + * comma-separated list of media. */ virtual DOMString getMediaText() { @@ -73,7 +87,8 @@ public: } /** - * + * The parsable textual representation of the media list. This is a + * comma-separated list of media. */ virtual void setMediaText(const DOMString &val) throw (dom::DOMException) { @@ -81,7 +96,8 @@ public: } /** - * + * The number of media in the list. The range of valid media is 0 to + * length-1 inclusive. */ virtual unsigned long getLength() { @@ -89,7 +105,8 @@ public: } /** - * + * Returns the indexth in the list. If index is greater than or equal to + * the number of media in the list, this returns null. */ virtual DOMString item(unsigned long index) { @@ -99,7 +116,7 @@ public: } /** - * + * Deletes the medium indicated by oldMedium from the list. */ virtual void deleteMedium(const DOMString& oldMedium) throw (dom::DOMException) @@ -113,7 +130,8 @@ public: } /** - * + * Adds the medium newMedium to the end of the list. If the newMedium + * is already used, it is first removed. */ virtual void appendMedium(const DOMString& newMedium) throw (dom::DOMException) @@ -121,6 +139,7 @@ public: items.push_back(newMedium); } + //################## //# Non-API methods //################## @@ -135,6 +154,23 @@ public: * */ MediaList(const MediaList &other) + { + assign(other); + } + + /** + * + */ + MediaList &operator=(const MediaList &other) + { + assign(other); + return *this; + } + + /** + * + */ + void assign(const MediaList &other) { mediaText = other.mediaText; items = other.items; @@ -159,14 +195,23 @@ protected: #########################################################################*/ /** - * + * The StyleSheet interface is the abstract base interface for any type of style + * sheet. It represents a single style sheet associated with a structured + * document. In HTML, the StyleSheet interface represents either an external + * style sheet, included via the HTML LINK element, or an inline STYLE element. + * In XML, this interface represents an external style sheet, included via a + * style sheet processing instruction. */ class StyleSheet { public: /** - * + * This specifies the style sheet language for this style sheet. The style sheet + * language is specified as a content type (e.g. "text/css"). The content type is + * often specified in the ownerNode. Also see the type attribute definition for + * the LINK element in HTML 4.0, and the type pseudo-attribute for the XML style + * sheet processing instruction. */ virtual DOMString getType() { @@ -174,7 +219,11 @@ public: } /** - * + * false if the style sheet is applied to the document. true if it is not. + * Modifying this attribute may cause a new resolution of style for the document. + * A stylesheet only applies if both an appropriate medium definition is present + * and the disabled attribute is false. So, if the media doesn't apply to the + * current user agent, the disabled attribute is ignored. */ virtual bool getDisabled() { @@ -182,7 +231,7 @@ public: } /** - * + * Sets the value above. */ virtual void setDisabled(bool val) { @@ -190,7 +239,10 @@ public: } /** - * + * The node that associates this style sheet with the document. For HTML, this + * may be the corresponding LINK or STYLE element. For XML, it may be the linking + * processing instruction. For style sheets that are included by other style + * sheets, the value of this attribute is null. */ virtual NodePtr getOwnerNode() { @@ -198,7 +250,10 @@ public: } /** - * + * For style sheet languages that support the concept of style sheet inclusion, + * this attribute represents the including style sheet, if one exists. If the + * style sheet is a top-level style sheet, or the style sheet language does not + * support inclusion, the value of this attribute is null. */ virtual StyleSheet *getParentStyleSheet() { @@ -206,7 +261,10 @@ public: } /** - * + * If the style sheet is a linked style sheet, the value of its attribute is its + * location. For inline style sheets, the value of this attribute is null. See + * the href attribute definition for the LINK element in HTML 4.0, and the href + * pseudo-attribute for the XML style sheet processing instruction. */ virtual DOMString getHref() { @@ -214,7 +272,9 @@ public: } /** - * + * The advisory title. The title is often specified in the ownerNode. See the + * title attribute definition for the LINK element in HTML 4.0, and the title + * pseudo-attribute for the XML style sheet processing instruction. */ virtual DOMString getTitle() { @@ -222,7 +282,12 @@ public: } /** - * + * The intended destination media for style information. The media is often + * specified in the ownerNode. If no media has been specified, the MediaList will + * be empty. See the media attribute definition for the LINK element in HTML 4.0, + * and the media pseudo-attribute for the XML style sheet processing + * instruction . Modifying the media list may cause a change to the attribute + * disabled. */ virtual MediaList &getMedia() { @@ -252,6 +317,23 @@ public: * */ StyleSheet(const StyleSheet &other) + { + assign(other); + } + + /** + * + */ + StyleSheet &operator=(const StyleSheet &other) + { + assign(other); + return *this; + } + + /** + * + */ + void assign(const StyleSheet &other) { type = other.type; disabled = other.disabled; @@ -292,14 +374,19 @@ protected: #########################################################################*/ /** - * + * The StyleSheetList interface provides the abstraction of an ordered collection + * of style sheets. + * + * The items in the StyleSheetList are accessible via an integral index, starting + * from 0. */ class StyleSheetList { public: /** - * + * The number of StyleSheets in the list. The range of valid child stylesheet + * indices is 0 to length-1 inclusive. */ virtual unsigned long getLength() { @@ -307,7 +394,8 @@ public: } /** - * + * Used to retrieve a style sheet by ordinal index. If index is greater than or + * equal to the number of style sheets in the list, this returns null. */ virtual StyleSheet *item(unsigned long index) { @@ -333,6 +421,15 @@ public: sheets = other.sheets; } + /** + * + */ + StyleSheetList &operator=(const StyleSheetList &other) + { + sheets = other.sheets; + return *this; + } + /** * */ @@ -353,14 +450,18 @@ protected: #########################################################################*/ /** - * + * The LinkStyle interface provides a mechanism by which a style sheet can be + * retrieved from the node responsible for linking it into a document. An + * instance of the LinkStyle interface can be obtained using binding-specific + * casting methods on an instance of a linking node (HTMLLinkElement, + * HTMLStyleElement or ProcessingInstruction in DOM Level 2). */ class LinkStyle { public: /** - * + * The style sheet. */ virtual StyleSheet &getSheet() { @@ -387,6 +488,15 @@ public: sheet = other.sheet; } + /** + * + */ + LinkStyle &operator=(const LinkStyle &other) + { + sheet = other.sheet; + return *this; + } + /** * */ @@ -406,14 +516,21 @@ protected: #########################################################################*/ /** - * + * The DocumentStyle interface provides a mechanism by which the style sheets + * embedded in a document can be retrieved. The expectation is that an instance + * of the DocumentStyle interface can be obtained by using binding-specific + * casting methods on an instance of the Document interface. */ class DocumentStyle { public: /** - * + * A list containing all the style sheets explicitly linked into or embedded in a + * document. For HTML documents, this includes external style sheets, included + * via the HTML LINK element, and inline STYLE elements. In XML, this includes + * external style sheets, included via style sheet processing instructions (see + * [XML-StyleSheet]). */ virtual StyleSheetList &getStyleSheets() { @@ -438,6 +555,15 @@ public: styleSheets = other.styleSheets; } + /** + * + */ + DocumentStyle &operator=(const DocumentStyle &other) + { + styleSheets = other.styleSheets; + return *this; + } + /** * */ -- 2.30.2