Firefly skinning documentation

[aaronmielke]

from the Firefly beta boards. Hope this helps:

Here's the first tutorial of the two I said I'd post. It's not really going to be a step by step thing, but more of a "Hey look at this" and "Don't do this" thing. That just said, here's the steps I would go through in making a new skin.

1) Copy Default.xml and name it something significant.
2) Create a new (empty)folder to hold all your kickin' new graphics.
3) Edit your new skin file, replacing any Default/foo.png paths with NewSkin/newfoo.png paths, along with any bounds, colors, fonts, alignments that you see fit.

Now for the faq part. These are all questions pulled from my own...head.

Q. Give me the lingo.
A. A tag is anything of the form ‘<foo attribute=�bar�\>’. This would be a foo tag. An attribute is inside a tag and has the form ‘bar=�10�’. That would be a bar attribute. Any item on the application (from graphics to text) is a control.

Q. Can I put images in multiple/nested directories?
A. You certainly can, and are highly encouraged to. If you want to use images in the default directory, say the firefly logo, you'd leave this tag the same:
Images Id="MainLogoFirefly" Path="Default\Logo.png"
However, if you want to change the Separator image you can follow that with:
Images Id="MainSeparator" Path="NewSkin\Separator.png"
and everything should work great.
Basically, Path is a relative path to the Skin directory. You are free to go wherever you want, but are encouraged to stay one level deep in the skins directory. For instance this:
Images Id="MainSeparator" Path="NewSkin\Separator.png"
and this:
Images Id="MainSeparator" Path="..\Skins\NewSkin\Separator.png"
and this
Images Id="MainSeparator" Path="NewSkin\..\..\Skins\..\Skins\NewSkin\Separat or.png"
are the same, but fairly silly.
Here's another scenario, say you were testing something you could have this
Images Id="MainSeparator" Path="NewSkin\Test\Separator.png"
As long as everything existed in the right place it should work beautifully.

Q. I notice you use mostly pngs but one jpg, why?
A. You see, pngs are great, they use lossless compression and have an alpha channel, making them great for skinning. However, that alpha channel incurs a performance hit, thus we use jpgs when we don't want any transparency (like the background) to make ff perform better.

Q. I used a big png for the background and now the main menu is sluggish, what gives?
A. We had the same problem. Use a smaller jpg. Basically, the main menu's performance is inversely proportional to the size of the image that is it's background.

Q. Are there any tags not in the default skin that are available?
A. Two: “MainButtonNormalBackground� and “BrowserButtonNormalBackground�. They are blank for us, but you are certainly able to put whatever you want.

Q. The bounds tag is confusing me.
A. The Bounds tag positions the control inside its parent. The decimals equate to percent height of the parent for the top/bottom attribute and percent width of the parent for the left/right attribute. There are two special values for the Bottom/Top/Left/Right attribute. One is “Auto� and the other is of the form foo~Bottom+0.1.
“Auto� means to auto-compute that side based on the image of that control in order to maintain the correct image aspect ratio. This works for almost every control, except for button lists, and the scroll-bar. For buttons, the normal image is used for these calculations. Only one side can be “Auto� at a time inside a Bounds tag.
“foo~Bottom+0.1� is a little more complicated. It’s basically a relative positioning indicator. For instance, Top= foo~Bottom+0.1 means that I want the top of this tag to be the bottom of the foo tag plus ten percent of their parent. This is really useful for lining up or justifying tags. In that case you put +0.0 or -0.0 for the offset.

Q. What are the limitations of the bounds tag?
A. There are several limitations, but all of them make sense. You can only use Top/Bottom as relative tags for Top/Bottom tags and Left/Right relative tags for Left/Right tags. You must always include an offset, even if that offset is 0.0. If you use decimals, Left must be < Right and Top < Bottom. Only one Auto at a time in a Bounds tag.

Q. It seems like it would’ve been simpler to use Left/Top and Width/Height instead of Left/Right/Top/Bottom.
A. Yes it would’ve, but then I couldn’t have right justified anything with the Auto attribute (How would I have calculated Left with just a Width, Height, and Top?)

Q. Things don’t look positioned right; did I mess up? How do I know?
A. Yes you did. Check the log. It should at least tell you that it couldn't position everything correctly. Try removing stuff until what you have in looks correct.

Q. Can I have control A refer to control B for a reference tag and then have Control B refer to control A for a reference tag?
A. No, that’s an infinite loop. Another infinite loop would be A -> B -> C -> A. Be careful of that. Also, make sure you refer to controls that are inside the same parent for reference tags.

Q. OK, then which controls are not on the same parent, or nested inside other controls?
A. The Control Box is by itself and not available as a reference control. It’s Buttons (Maximize/Minimize/Close) are inside of it and their Bounds refer to the size of the control box. For example:
Bounds Id="ControlBoxMinimize" Left="0.228237885462555" Top="0.19298245614" Right="Auto" Bottom="0.8421"
The Top attribute refers to about 20 percent the height of the Control Box, not of the application.
Also, ChildFireflyLogo, BrowserTitle, and SettingsLogo are inside of ChildTop, the BrowserTitle and all the BrowserDetails tags are inside of ChildBottom, and MainTime and MainDate are inside the MainDateTimeContainer. I should note that although the bounds refer to their respective parents for placement their fonts still refer to the height of the application.

Q. Please explain fonts.
A. Fonts have three attributes. Family, Size, and Style. Family can be any font currently installed on your computer. Size is the percent height of the current application. Thus .1 is 10 percent. Style can be any of the following: Bold, Italic, Regular, Strikeout, Underline.

Q. I’ve noticed different types of tags have the same ID, like font and bounds. Is that significant?
A. Very. All tags with the same ID refer to the same control.

Q. What are the possible values for alignment tag?
A. BottomCenter, BottomLeft, BottomRight, MiddleCenter, MiddleLeft, MiddleRight, TopCenter, TopLeft, TopRight.

Q. Explain Color.
A. Pretty simple. R is red, g is green, and b is blue. Together they describe all possible display colors. A is the alpha value. That determines the opacity of the color. If you want text where the background bleeds through, then decrease the A attribute. All attributes have the value 0 to 255. For A 0 is completely translucent (read invisible) and 255 is completely opaque. For colors 0 is none of that color and 255 is the most of that color. Thus, if you want totally opaque red you would put
A=�255� R=�255� G=�0� B=�0�
If you need more explanation than that then maybe skinning isn’t the thing for you.

Q. Do the organization tags “Settings, AllChildren�, etc. mean anything?
A. No, absolutely nothing. It’s purely for my organization and you can change, then, remove them, whatever. Just remember to remove the open and close tag to keep your xml well formed.

Q. Does the order of the attributes in a tag matter?
A. No.

Q. This is hard, got any tips?
A. Indeed I so. First of all, occasionally open your skin in Internet Explorer. That will find any malformed xml you may’ve introduced. Second, make a screen shot of what you want it to look like and use that as a reference. That’s how I did it. I had Joel make a screen shot of how he wanted it to look like at 1280x1024. I then whipped out my trusty calculator and did stuff like: “OK, it’s 350 pixels down at 1280x1024 so that mean it’s at 350/1024 which is 0.341796875.� The same goes for fonts. “Size 52 font at 1280x1024 is 52/1024 which is 0.05078125.� I used standard calc and Microsoft Photo Editor which come standard with XP.

[tahalouzi]

thank you