1 <!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
2 <meta http-equiv=
"content-type" content=
"text/html; charset=ISO-8859-1">
3 <meta name=
"author" content=
"Marc Attinasi"><title>Adding a new style property - layout cookbook
</title></head>
6 <h1>Adding a new style property
</h1>
8 <h4>Document history:
</h4>
10 <li>03/
21/
2002: Marc Attinasi (attinasi@netscape.com) created document
11 / implementing -moz-force-broken-image-icon for bug
<a href=
"http://bugzilla.mozilla.org/show_bug.cgi?id=58646">
14 6/
18/
2002: David Baron (dbaron@dbaron.org): corrected support
15 for 'inherit' and '-moz-initial' (didn't test with code, though),
16 and explained what the final boolean in CheckPropertyData is for.
19 11/
09/
2002: Christopher Aillon (caillon@returnzero.com): updated
20 nsCSSPropList.h macro description and added information about
21 nsIDOMCSS2Properties.idl.
25 <b>NOTE
</b>: This document is still missing a few pieces. I need to
26 add information on adding to
<code>nsComputedDOMStyle
</code>.
30 When a new style property is needed there are many places in the code that
31 need to be updated. This document outlines the procedure used to add a new
32 property, in this case the property is a proprietary one called '-moz-force-broken-image-icons'
33 and is used as a way for a stylesheet to force broken image icons to be displayed.
34 This is all being done in the context of
<a href=
"http://bugzilla.mozilla.org/show_bug.cgi?id=58646">
38 <p>Up front you have to decide some things about the new property:
</p>
40 <p><b>Questions:
</b></p>
42 <li>Is the property proprietary or specified by the CSS standard?
</li>
43 <li>Is the property inherited?
</li>
44 <li>What types of values can the property have?
</li>
45 <li>Does it logically fit with other existing properties?
</li>
46 <li>What is the impact to the layout of a page if that property changes?
</li>
47 <li>What do you want to name it?
</li>
49 <p><b>Answers:
</b></p>
51 <li>In our specific case, we want a property that is used internally,
52 so it is a proprietary property.
</li>
53 <li>The property is to be used for images, which are leaf elements, so
54 there is no need to inherit it.
</li>
55 <li>The property is used simply to force a broken image to be represented
56 by an icon, so it only supports the values '
0' and '
1' as numerics.
</li>
57 <li>It is hard to see how this property fits logically in with other
58 properties, but if we stretch our imaginations we could say that it is a
59 sort of UI property.
</li>
60 <li>If this property changes, the image frame has to be recreated. This
61 is because the decision about whether to display the icon or not will impact
62 the decision to replace the image frame with an inline text frame for the
63 ALT text, so if the ALT text inline is already made, there is no image frame
64 left around to reflow or otherwise modify.
</li>
65 <li>Finally, the name will be '-moz-force-broken-image-icons' - that
66 should be pretty self-describing (by convention we start proprietary property
67 names with '-moz-').
</li>
69 <h2>Implementation
</h2>
71 <p>There are several places that need to be educated about a new style property.
75 <li><a href=
"#CSSPropList">CSS Property Names and Hint Tables
</a>: the new
76 property name must be made formally know to the system
</li>
77 <li><a href=
"#CSSDeclaration">CSS Declaration
</a>: the declaration must be
78 able to hold the property and its value(s)
</li>
79 <li><a href=
"#Parser">CSS Parser
</a>: the parser must be able to parse the
80 property name, validate the values, and provide a declaration for the property
82 <li><a href=
"#StyleContext">Style Context
</a>: the StyleContext must be able
83 to hold the resolved value of the property, and provide a means to retrieve the
84 property value. Additionally, the StyleContext has to know what kind of impact a
85 change to this property causes.
</li>
86 <li><a href=
"#RuleNode">Rule Nodes
</a>: the RuleNodes need to know how the
87 property is inherited and how it is shared by other elements.
</li>
88 <li><a href=
"#DOM">DOM
</a>: Your style should be accessible from the DOM so
89 users may dynamically set/get its property value.
</li>
90 <li><a href=
"#Layout">Layout
</a>: layout has to know what to do with the
91 property, in other words, the meaning of the property.
</li>
93 <h3><a name=
"CSSPropList">CSS Property Name / Constants / Hints
</a></h3>
96 First, add the new name to the property list in
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/shared/public/nsCSSPropList.h">
98 Insert the property in the list alphabetically, using the existing
99 property names as a template. The format of the entry you will create is:
101 <pre>CSS_PROP(-moz-force-broken-image-icons, force_broken_image_icons, MozForceBrokenImageIcons, NS_STYLE_HINT_FRAMECHANGE) // bug
58646</pre>
103 <p>The first value is the formal property name, in other words the property
104 name as it is seen by the CSS parser.
<br>
105 The second value is the name of the property as it will appear internally.
<br>
106 The third value is the name of the DOM property used to access your style.
<br>
107 The last value indicates what must change when the value of the property
108 changes. It should be an
109 <a href=
"http://lxr.mozilla.org/seamonkey/source/content/shared/public/nsChangeHint.h">nsChangeHint
</a>.
</p>
111 <p>If you need to introduce new constants for the values of the property, they
112 must be added to
<a href=
"http://lxr.mozilla.org/seamonkey/source/layout/base/public/nsStyleConsts.h">
114 and to the appropriate keyword tables in
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/shared/src/nsCSSProps.cpp">
116 (note: this cookbook does not do this since the new property does not require
117 any new keywords for the property values).
118 <h3><a name=
"CSSDeclaration">CSS Declaration
</a></h3>
119 Changes will need to be made to the structs and classes defined in
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSDeclaration.h">
120 nsCSSDeclaration.h
</a>
121 and
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSDeclaration.cpp">
122 nsCSSDeclaration.cpp
</a>
125 First, find the declaration of the struct that will hold the new property
126 value (in the header file). For this example it is the struct
<b>nsCSSUserInterface
</b>
127 . Modify the struct declaration to include a new data member for the new
128 property, of the type CSSValue. Next, open the implementation file (the cpp)
129 and modify the struct's constructors.
<br>
131 Next, the
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSDeclaration.cpp#1410">
133 method must be updated to support your new property. The CSSParser will
134 call this to build up a declaration. Find the portion of that method that
135 deals with the other properties in the struct that you are adding your property
136 to (or create a new section if you are creating a new style struct). For
137 this example we will find the 'UserInterface' section and add our new property
138 <a href=
"#AppendValueCase">there
</a>
140 <pre> // nsCSSUserInterface
141 case eCSSProperty_user_input:
142 case eCSSProperty_user_modify:
143 case eCSSProperty_user_select:
144 case eCSSProperty_key_equivalent:
145 case eCSSProperty_user_focus:
146 case eCSSProperty_resizer:
147 case eCSSProperty_cursor:
148 case eCSSProperty_force_broken_image_icons: {
149 CSS_ENSURE(UserInterface) {
151 case eCSSProperty_user_input: theUserInterface-
>mUserInput = aValue; break;
152 case eCSSProperty_user_modify: theUserInterface-
>mUserModify = aValue; break;
153 case eCSSProperty_user_select: theUserInterface-
>mUserSelect = aValue; break;
154 case eCSSProperty_key_equivalent:
155 CSS_ENSURE_DATA(theUserInterface-
>mKeyEquivalent, nsCSSValueList) {
156 theUserInterface-
>mKeyEquivalent-
>mValue = aValue;
157 CSS_IF_DELETE(theUserInterface-
>mKeyEquivalent-
>mNext);
160 case eCSSProperty_user_focus: theUserInterface-
>mUserFocus = aValue; break;
161 case eCSSProperty_resizer: theUserInterface-
>mResizer = aValue; break;
162 case eCSSProperty_cursor:
163 CSS_ENSURE_DATA(theUserInterface-
>mCursor, nsCSSValueList) {
164 theUserInterface-
>mCursor-
>mValue = aValue;
165 CSS_IF_DELETE(theUserInterface-
>mCursor-
>mNext);
168 <b> <a name=
"AppendValueCase"></a>case eCSSProperty_force_broken_image_icons: theUserInterface-
>mForceBrokenImageIcon = aValue; break;
170 CSS_BOGUS_DEFAULT; // make compiler happy
177 The GetValue method must be similarly
<a href=
"#GetValueCase">modified
</a>
179 <pre> // nsCSSUserInterface
180 case eCSSProperty_user_input:
181 case eCSSProperty_user_modify:
182 case eCSSProperty_user_select:
183 case eCSSProperty_key_equivalent:
184 case eCSSProperty_user_focus:
185 case eCSSProperty_resizer:
186 case eCSSProperty_cursor:
187 case eCSSProperty_force_broken_image_icons: {
188 CSS_VARONSTACK_GET(UserInterface);
189 if (nsnull != theUserInterface) {
191 case eCSSProperty_user_input: aValue = theUserInterface-
>mUserInput; break;
192 case eCSSProperty_user_modify: aValue = theUserInterface-
>mUserModify; break;
193 case eCSSProperty_user_select: aValue = theUserInterface-
>mUserSelect; break;
194 case eCSSProperty_key_equivalent:
195 if (nsnull != theUserInterface-
>mKeyEquivalent) {
196 aValue = theUserInterface-
>mKeyEquivalent-
>mValue;
199 case eCSSProperty_user_focus: aValue = theUserInterface-
>mUserFocus; break;
200 case eCSSProperty_resizer: aValue = theUserInterface-
>mResizer; break;
201 case eCSSProperty_cursor:
202 if (nsnull != theUserInterface-
>mCursor) {
203 aValue = theUserInterface-
>mCursor-
>mValue;
206 <b> <a name=
"GetValueCase"></a>case eCSSProperty_force_broken_image_icons: aValue = theUserInterface-
>mForceBrokenImageIcons; break;
208 CSS_BOGUS_DEFAULT; // make compiler happy
218 Finally
<a href=
"#ListCase">modify
</a>
219 the 'List' method to output the property value.
<br>
220 <pre>void nsCSSUserInterface::List(FILE* out, PRInt32 aIndent) const
222 for (PRInt32 index = aIndent; --index
>=
0; ) fputs(
" ", out);
226 mUserInput.AppendToString(buffer, eCSSProperty_user_input);
227 mUserModify.AppendToString(buffer, eCSSProperty_user_modify);
228 mUserSelect.AppendToString(buffer, eCSSProperty_user_select);
229 nsCSSValueList* keyEquiv = mKeyEquivalent;
230 while (nsnull != keyEquiv) {
231 keyEquiv-
>mValue.AppendToString(buffer, eCSSProperty_key_equivalent);
232 keyEquiv= keyEquiv-
>mNext;
234 mUserFocus.AppendToString(buffer, eCSSProperty_user_focus);
235 mResizer.AppendToString(buffer, eCSSProperty_resizer);
237 nsCSSValueList* cursor = mCursor;
238 while (nsnull != cursor) {
239 cursor-
>mValue.AppendToString(buffer, eCSSProperty_cursor);
240 cursor = cursor-
>mNext;
243 <b> <a name=
"ListCase"></a>mForceBrokenImageIcon.AppendToString(buffer,eCSSProperty_force_broken_image_icons);
</b>
245 fputs(NS_LossyConvertUTF16toASCII(buffer).get(), out);
250 <h3><a name=
"Parser">CSS Parser
</a></h3>
251 Next, the CSSParser must be educated about this new property so that it can
252 read in the formal declarations and build up the internal declarations that
253 will be used to build the rules. If you are adding a simple property that
254 takes a single value, you simply add your new property to the ParseSingleProperty
255 method. If a more complex parsing is required you will have to write a new
256 method to handle it, modeling it off of one of the existing parsing helper
257 methods (see
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSParser.cpp#4151">
259 , for and example). We are just adding a simple single-value property here.
<br>
261 Open nsCSSParser.cpp and look for the method
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSParser.cpp#3580">
262 ParseSingleProperty
</a>
263 . This method is responsible for calling the relevant helper routine to parse
264 the value(s). Find an existing property that is similar to the property you
265 are adding. For our example we are adding a property that takes a numeric
266 value so we will model it after the 'height' property and call ParsePositiveVariant.
267 Add a new case for the new property and call the appropriate parser-helper
268 and make a call to ParseVariant passing the
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSParser.cpp#2754">
270 that makes sense for your property. In our case
<br>
272 <pre> case eCSSProperty_force_broken_image_icons:
</pre>
273 <pre> return ParsePositiveVariant(aErrorCode, aValue, VARIANT_INTEGER, nsnull);
</pre>
274 This will parse the value as a positive integer value, which is what we want.
<br>
276 <h3><a name=
"StyleContext">Style Context
</a></h3>
277 Having implemented support for the new property in the CSS Parser and CSS
278 Declaration classes in the content module, it is now time to provide support
279 for the new property in layout. The Style Context must be given a new data
280 member corresponding to the declaration's new data member, so the computed
281 value can be held for the layout objects to use.
<br>
283 First look into
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/shared/public/nsStyleStruct.h">
285 to see the existing style strucs. Find the one that you want to store the
286 data on. In this example, we want to put it on the nsStyleUserInterface struct,
287 however there is also a class nsStyleUIReset that holds the non-inherited
288 values, so we will use that one (remember, our property is not inherited).
289 Add a
<a href=
"#StyleContextMember">data member
</a>
291 <pre>struct nsStyleUIReset {
292 nsStyleUIReset(void);
293 nsStyleUIReset(const nsStyleUIReset
& aOther);
294 ~nsStyleUIReset(void);
296 NS_DEFINE_STATIC_STYLESTRUCTID_ACCESSOR(eStyleStruct_UIReset)
298 void* operator new(size_t sz, nsPresContext* aContext) {
299 return aContext-
>AllocateFromShell(sz);
301 void Destroy(nsPresContext* aContext) {
302 this-
>~nsStyleUIReset();
303 aContext-
>FreeToShell(sizeof(nsStyleUIReset), this);
306 PRInt32 CalcDifference(const nsStyleUIReset
& aOther) const;
308 PRUint8 mUserSelect; // [reset] (selection-style)
309 PRUnichar mKeyEquivalent; // [reset] XXX what type should this be?
310 PRUint8 mResizer; // [reset]
311 <b><a name=
"StyleContextMember"></a>PRUint8 mForceBrokenImageIcon; // [reset] (
0 if not forcing, otherwise forcing)
</b>
314 In the implementation file
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/shared/src/nsStyleStruct.cpp">
315 nsStyleContext.cpp
</a>
316 add the new data member to the constructors of the style struct and the CalcDifference
317 method, which must return the correct style-change hint when a change to
318 your new property is detected. The constructor changes are obvious, but here
319 is the CalcDifference change for our example:
<br>
320 <pre>PRInt32 nsStyleUIReset::CalcDifference(const nsStyleUIReset
& aOther) const
322 <b> if (mForceBrokenImageIcon == aOther.mForceBrokenImageIcon) {
</b>
323 if (mResizer == aOther.mResizer) {
324 if (mUserSelect == aOther.mUserSelect) {
325 if (mKeyEquivalent == aOther.mKeyEquivalent) {
326 return NS_STYLE_HINT_NONE;
328 return NS_STYLE_HINT_CONTENT;
330 return NS_STYLE_HINT_VISUAL;
332 return NS_STYLE_HINT_VISUAL;
334 <b>return NS_STYLE_HINT_FRAMECHANGE;
337 <h3>CSSStyleRule
</h3>
338 The nsCSSStyleRule must be updated to manage mapping the declaration to the
339 style struct. In the file
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/html/style/src/nsCSSStyleRule.cpp">
340 nsCSSStyleRule.cpp
</a>
341 , locate the Declaration mapping function corresponding to the style struct
342 you have added your property to. For example, we
<a href=
"http://bugzilla.mozilla.org/MapUIForDeclChange">
344 MapUIForDeclaration:
<br>
346 MapUIForDeclaration(nsCSSDeclaration* aDecl, const nsStyleStructID
& aID, nsCSSUserInterface
& aUI)
349 return NS_OK; // The rule must have a declaration.
351 nsCSSUserInterface* ourUI = (nsCSSUserInterface*)aDecl-
>GetData(kCSSUserInterfaceSID);
353 return NS_OK; // We don't have any rules for UI.
355 if (aID == eStyleStruct_UserInterface) {
356 if (aUI.mUserFocus.GetUnit() == eCSSUnit_Null
&& ourUI-
>mUserFocus.GetUnit() != eCSSUnit_Null)
357 aUI.mUserFocus = ourUI-
>mUserFocus;
359 if (aUI.mUserInput.GetUnit() == eCSSUnit_Null
&& ourUI-
>mUserInput.GetUnit() != eCSSUnit_Null)
360 aUI.mUserInput = ourUI-
>mUserInput;
362 if (aUI.mUserModify.GetUnit() == eCSSUnit_Null
&& ourUI-
>mUserModify.GetUnit() != eCSSUnit_Null)
363 aUI.mUserModify = ourUI-
>mUserModify;
365 if (!aUI.mCursor
&& ourUI-
>mCursor)
366 aUI.mCursor = ourUI-
>mCursor;
370 else if (aID == eStyleStruct_UIReset) {
371 if (aUI.mUserSelect.GetUnit() == eCSSUnit_Null
&& ourUI-
>mUserSelect.GetUnit() != eCSSUnit_Null)
372 aUI.mUserSelect = ourUI-
>mUserSelect;
374 if (!aUI.mKeyEquivalent
&& ourUI-
>mKeyEquivalent)
375 aUI.mKeyEquivalent = ourUI-
>mKeyEquivalent;
377 if (aUI.mResizer.GetUnit() == eCSSUnit_Null
&& ourUI-
>mResizer.GetUnit() != eCSSUnit_Null)
378 aUI.mResizer = ourUI-
>mResizer;
380 <a name=
"MapUIForDeclChange"></a>if (aUI.mForceBrokenImageIcon.GetUnit() == eCSSUnit_Null
&& ourUI-
>mForceBrokenImageIcon.GetUnit() == eCSSUnit_Integer)
381 aUI.mForceBrokenImageIcon = ourUI-
>mForceBrokenImageIcon;
</b>
388 <h3><a name=
"RuleNode">Rule Node
</a></h3>
389 Now we have to update the RuleNode code to know about the new property. First,
390 locate the PropertyCheckData array for the data that you added the new property
391 to. For this example, we add the following:
<br>
392 <pre>static const PropertyCheckData UIResetCheckProperties[] = {
393 CHECKDATA_PROP(nsCSSUserInterface, mUserSelect, CHECKDATA_VALUE, PR_FALSE),
394 CHECKDATA_PROP(nsCSSUserInterface, mResizer, CHECKDATA_VALUE, PR_FALSE),
395 CHECKDATA_PROP(nsCSSUserInterface, mKeyEquivalent, CHECKDATA_VALUELIST, PR_FALSE)
396 <b>CHECKDATA_PROP(nsCSSUserInterface, mForceBrokenImageIcon, CHECKDATA_VALUE, PR_FALSE)
</b>
399 The first two arguments correspond to the structure and data member from
400 the CSSDeclaration, the third is the data type, the fourth indicates
401 whether it is a coord value that uses an explicit inherit value on the
402 style data struct that must be computed by layout.
<br>
404 Next, we have to make sure the ComputeXXX method for the structure the property
405 was added to is updated to mange the new value. In this example we need to
406 modify the nsRuleNode::ComputeUIResetData method to handle the CSS Declaration
407 to the style struct:
<br>
409 // resizer: auto, none, enum, inherit
410 if (eCSSUnit_Enumerated == uiData.mResizer.GetUnit()) {
411 ui-
>mResizer = uiData.mResizer.GetIntValue();
413 else if (eCSSUnit_Auto == uiData.mResizer.GetUnit()) {
414 ui-
>mResizer = NS_STYLE_RESIZER_AUTO;
416 else if (eCSSUnit_None == uiData.mResizer.GetUnit()) {
417 ui-
>mResizer = NS_STYLE_RESIZER_NONE;
419 else if (eCSSUnit_Inherit == uiData.mResizer.GetUnit()) {
421 ui-
>mResizer = parentUI-
>mResizer;
424 <b>// force-broken-image-icons: integer, inherit, -moz-initial
425 if (eCSSUnit_Integer == uiData.mForceBrokenImageIcons.GetUnit()) {
426 ui-
>mForceBrokenImageIcons = uiData.mForceBrokenImageIcons.GetIntValue();
427 } else if (eCSSUnit_Inherit == uiData.mForceBrokenImageIcons.GetUnit()) {
429 ui-
>mForceBrokenImageIcons = parentUI-
>mForceBrokenImageIcons;
430 } else if (eCSSUnit_Initial == uiData.mForceBrokenImageIcons.GetUnit()) {
431 ui-
>mForceBrokenImageIcons =
0;
435 // We inherited, and therefore can't be cached in the rule node. We have to be put right on the
437 aContext-
>SetStyle(eStyleStruct_UIReset, *ui);
439 // We were fully specified and can therefore be cached right on the rule node.
440 if (!aHighestNode-
>mStyleData.mResetData)
441 aHighestNode-
>mStyleData.mResetData = new (mPresContext) nsResetStyleData;
442 aHighestNode-
>mStyleData.mResetData-
>mUIData = ui;
443 // Propagate the bit down.
444 PropagateDependentBit(NS_STYLE_INHERIT_UI_RESET, aHighestNode);
448 <h3><a name=
"DOM">DOM
</a></h3>
449 Users in scripts, or anywhere outside of layout/ or content/ may need to access
450 the new property. This is done using the CSS OM, specifically
451 <code>nsIDOMCSSStyleDeclaration
</code> and
<code>nsIDOMCSS2Properties
</code>.
452 By the magic of C++ pre-processing, the
453 CSS2Properties interfaces will be implemented automatically when you
454 <a href=
"#CSSPropList">add your property
</a> to
<a href=
"http://lxr.mozilla.org/seamonkey/source/content/shared/public/nsCSSPropList.h">
455 nsCSSPropList.h
</a>. Because of this, if you fail to add your property to the
456 DOM interface, you will be rewarded with compiler errors. All you have to do
457 is modify
<a href=
"http://lxr.mozilla.org/mozilla/source/dom/public/idl/css/nsIDOMCSS2Properties.idl">
458 nsIDOMCSS2Properties.idl
</a> and add the appropriate attribute to the
459 <code>nsIDOMNSCSS2Properties
</code> interface (lower in the file).
461 <pre> attribute DOMString MozForceBrokenImageIcon;
462 // raises(DOMException) on setting
465 <h3><a name=
"Layout">Layout
</a></h3>
466 OK, finally the style system is supporting the new property. It is time to
467 actually make use of it now.
<br>
469 In layout, retrieve the styleStruct that has the new property from the frame's
470 style context. Access the new property and get its value. It is that simple.
471 For this example, it looks like this, in nsImageFrame:
<br>
472 <pre> PRBool forceIcon = PR_FALSE;
474 if (GetStyleUIReset()-
>mForceBrokenImageIcon) {
479 Create some testcases with style rules that use the new property, make sure
480 it is being parsed correctly. Test it in an external stylesheet and in inline
481 style. Test that it is inherited correctly, or not inherited as appropriate
482 to your property. Update this document with any further details, or correcting