Archive for category The Documentation Sucks
A reader commented on my ScrollPane article, saying “why wouldn’t they just say that?”
I’ve found myself asking this question more and more as I’ve been diving into Flex and ActionScript 3.
For example, here is how to get the name of the root node of an XML object:
nodeName has mysteriously disappeared, and the Migration Guide makes no mention of
name() as its new equivalent.
In fact, the XML Class Definition for ActionScript 3 describes
name() as “Gives the qualified name for the XML object.”, which led me to believe it was relevant only namespace-qualified XML tags and not useful for getting a root node’s name.
Splitting hairs, perhaps, but a good little tip nonetheless.
It seems that documentation and clear examples for how to customize Flash 8’s ScrollPane component are somewhat scarce. In fact, just a quick Google search yields many messageboard postings bemoaning the difficulty of using ScrollPane, with little to nothing in response.
It’s important to note that the old methods of UI Component customization – setting values for “face”, “arrow,” “scrollTrack,” and the like, seem to have fallen by the wayside.
The recommended method these days is something much more in-depth and complicated, with poor documentation thrown in just to make sure you don’t get it right the first time. For example, the documentation on LiveDocs provides the following table of applicable styles for ScrollPane:
||Halo||The base color scheme of a component. Possible values are
||Both||The ScrollPane component uses a RectBorder instance as its border and responds to the styles defined on that class. See RectBorder class.The default border style is
||Sample||The background color for the scroll track. The default value is 0xCCCCCC (light gray).|
||Sample||The color of the arrows on the scrollbar buttons. The default value is 0x000000 (black).|
||Sample||The color of disabled arrows on the scrollbar buttons. The default value is 0x848384 (dark gray).|
Great! Looks like we can change the arrow or track color of the scrollbar on a ScrollPain instance. All you need to do is set
Try it. Put a ScrollPane on the stage and set that scrollTrackColor. Set it all day long until you’re 0x0000FF in the face. You won’t see any changes to the scrollbar’s appearance.
Pay close attention to that “theme” column. It provides the key to why your customization isn’t going as planned. If you want to customize the scroll track or arrow color, those properties are available but what isn’t mentioned here is that you must first install the “Sample” theme from Macromedia’s libraries. A detailed description of how to do this is available in “About Themes” on LiveDocs.
So, we’ve dragged the Library over, installed the sample theme, and Presto! We now have a customized scrollbar color. We can also set
symbolColor to change the color of the arrows.
It’s only a slight improvement. The problem is, we’ve now been left with chunky, gray, Windows 3.1-style scrollbars, and the only ActionScript customization options are for the arrows and the track.
You can improve the look and feel of the arrows manually, by editing the symbols in the Scrollbar Assets folder we dragged over during the Sample theme install. But who has the time or energy for that?
A little bit of digging around in the symbols that the Sample theme carried over reveals some hidden, undocumented goodness: there is also a
shadowColor property available to these scrollbars.
highlightColor applies to the “main” color of the arrow buttons and “thumb” element, while
shadowColor is the small shadow to the bottom right of each piece.
(To see this for yourself, have a look at the “BrdrHilght,” “BrdrFace”, “BrdrBlk”, and “BrdrShdw” symbols.)
Here’s a diagram of the different parts of the scrollbar and where the different colors apply. Note: Please, never, under any circumstances, for any reason, use a color scheme like this. I only did it so I can show where the different parts are.
Sometime’s, it’s really amazing what you can find just by poking around in Macromedia’s samples.