All Purpose ComboBox 2.0 Documentation
Ryan Sadwick - rsadwick@gmail.com
http://ootie.blogspot.com
Intro - XML Properties - Skin Attributes - Item Attributes - FAQ
Changes from 1.0 to 2.0
I created APC due to the demand of the development of user interactions that I've worked on over the years. I always squirmed at the thought of finding, typing, proof-reading all 50 states and abbreviations or all known countries or all the states in India. I also always need to change skins on-the-fly. So I created APC. I went ahead and created all the raw data one time and it's perfect to reuse in this comboBox.
Features:
Getting Started
Unzip the files into a folder, you should have a directory structure setup like so:
assets: Contains the skins + XML data.
assets/raw_data: Contains the XML data. If you need this data, open the file, go down to the <items> tag and copy/paste.
com.rsadwick.skins: Contains all the custom skin classes
com.rsadwick.motion: Contains tweening classes.
com.rsadwick.utils: Contains a class that opens URLs.
docs: All the documentation for this ComboBox.
Let's get started.
1. Start a new Flash File (ActionScript 3.0). Save the FLA in the main directory. (Where combo.fla is also located, see image above).
2. Create two layers. Call one layer UI, the other Actions. Go into the components library and drag a standard ComboBox unto the stage, then delete the ComboBox (the ComboBox will still retain in the library.
3. Go into your actions layer and we'll use the class:
First, we'll import the CustomComboBox class
import com.rsadwick.skins.CustomComboBox;
Now we'll make a reference to the class and instantiate the class:
var newCombo:CustomComboBox = new CustomComboBox();
Now, let's set the path to the XML file we'll be using:
newCombo.pathToUrl = "assets/iconExample.xml";
Call the setupXml function to load in the XML
newCombo.setupXml();
Finally, we'll add the newCombo to the display list:
addChild(newCombo);
4. Run your movie.
5. To customize the comboBox, open up the XML file and change it to your specifications. For more on the XML properties and what they do, the next section explains them all! For more examples on loading XML files and getting information from the ComboBox, check out the combo.fla file.
You're code should look similar to:
x: X position of the comboBox
y: Y position of the comboBox
width: Width of the comboBox
height: Height of the comboBox
dropdownWidth: sets the maximum width of the drop-down list, in pixels
displayOptions: Allows to display the label and data within the combo textField. Available options are 1, 2, 3
| 1: Normal Display of the label. |  |
| 2. Displays the label, dash, and the data. |  |
| 3. Displays the data, dash, and the label. |  |
prompt: sets the prompt for the ComboBox. For example, if your combobox is a list of states, this can be set to "Select a State" to give the user direction.
rowCount: sets the maximum number of rows that can appear in a drop-down list that does not have a scroll bar.
fontSize: font size of the entire combobox
fontColor: font color of the entire combobox
align: Align the text in the combobox: left, right, center
blockIndent: Indicates the block indentation in pixels
bold: sets the text face to bold. Boolean value only: use 0 or 1
italic: sets the text face to italic. Boolean value only: use 0 or 1
underline: sets the text face to underline. Boolean value only: use 0 or 1
font: the font that will be used in the combobox. Note: this attribute will not embed the font you choose here. If the font name isn't available on a machine, flash will do its best to select a similar font. If you wish to embed a specific font, please see Embedding fonts for more details.
embedFonts: sets the fonts to be embedded. Boolean value only: use 0 or 1. This attribute will NOT automatically embed your font, see Embedding fonts for more details.
fontClass: The name of the font class that is linked in the library. Embed fonts must be turned true(1) in order for the class to be used. See Embedding fonts for more details.
indent: Indicates the indentation from the left margin to the first character in the paragraph.
leading: An integer representing the amount of vertical space (called leading) between lines.
leftMargin: The left margin of the paragraph, in pixels.
letterSpacing: number representing the amount of space that is uniformly distributed between all characters.
rightMargin: The right margin of the paragraph, in pixels.
bullet: Indicates that the text is part of a bulleted list: Boolean value only: use 0 or 1
kerning: A Boolean value that indicates whether kerning is enabled (true) or disabled (false). Boolean value only: use 0 or 1
textPadding: The space that separates the border from the text representing the selected item, in pixels.
disabledAlpha: The alpha value to set the list to when the enabled property is false.
contentPadding: Padding between the content (the component and scroll bar), and the outside edge of the background, in pixels.
buttonWidth: The space that separates the right edge of the component from the text representing the selected item, in pixels. The button is part of the background skin.
editable: sets a Boolean value that indicates whether the ComboBox component is editable or read-only: Boolean value only: use 0 or 1. Enabling the combobox to be editable will listen for the ENTER key to be pressed to add the item to the combobox.
urlTarget: Defines the target of all url attributes. Options:
| _self | Specifies the current frame in the current window. |
| _blank | Specifies a new window. This new window acts as a pop-up window in the client's browser, so you must be aware that a pop-up blocker could prevent it from loading. |
| _parent | Specifies the parent of the current frame. |
| _top | Specifies the top-level frame in the current window. |
useSkin: sets a Boolean value tht indicates whether to use the custom created skins OR simply use the default Flash skins for the ComboBox. Note: If you've designed your own skins in Flash and want to use them, turn this option to "0" (false). Boolean value only: use 0 or 1.
Left: Custom Skin, created from the XML file. - Right: Flash designed skin from the library.
Tweening. APC provides a simple tweening class that applies to the ComboBox's dropdown menu:
tweenType: Sets the direction behavior for the tween: only available modes are x or y. If you do not want tweening, simply leave this blank.
tweenDuration: Sets the time (in seconds) of how long the tween will last.
tweenLooping : Sets a Boolean value tht indicates whether to loop the tween or not. Boolean value only: use 0 or 1.
tweenFPS: Defined the Frames-Per-Second the tween will run at. This FPS value will NOT effect your Flash movie's FPS value. This value is independantly set for the tween.
You can either use these skin attributes that are created programmically OR use the normal Flash skinning by double-clicking on the ComboBox component and editing the skins graphically.
To disable the programmically created skins, you'll need to comment out specific code in the CustomComboBox class file. You'll find specific instructions around line 150. This functionality will be smoother in a later version.
Skinning Programmically: The XML file contains all these attributes for customizing each skin.
XML Attributes
Important note about Alphas. Alpha values can only be 0.0 - 1.0. 0.0 being totally transparent and 1.0 being visible.
We'll use upSkin as an example. All other attributes in the XML behave the exact same way.
upSkinColor: Determines the colors to use in a gradient. If you do not want a gradient, simply use one color. For example:
upSkinColor="0xFF2222,0xCCFFAA" would create a gradient like so:
upSkinGradientAlphas: Specifies two alphas for the gradient. For example:
upSkinGradientAlphas="0.3,1 " would change the alpha on the left side to 0.3. The right side of the gradient remains at 1.0:
upSkinGradientAlign: Specifies the align of the gradient. There are only two options available: vertical and horizontal. For example:
upSkinGradientAlign="horizontal" OR upSkinGradientAlign="vertical" yield these type of results:
You can also use a single color and still change the alpha on each side if needed:
upSkinBorderSize: Changes the size of the border around a single skin.
upSkinBorderColor: Changes the color of the border.
upSkinShapes: Draws certain shapes inside the gradient. Available shapes are:
Important: The order you list the shapes as, is the order the shapes appear on the display list. For example, if you create a rectangle, box, and arrow:
upSkinShapes="rectangle,box,arrow" The rectangle will be behind everything else, whereas the arrow will be on top.
For example, on the UpSkin, we want a rectangle, box, and an arrow. We can specify these multiple shapes by using commas:
upSkinShapes="rectangle,box,arrow"
Of course, we need to specify the colors, alphas, and position such as X and Y for the above result, such are explained below:
upSkinShapeColors: Specifies the colors that each shape will use. This attribute can accept an array of colors. These must coorispond to the upSkinShapes:
We have a rectangle, box, and an arrow that need colors.
upSkinShapes="rectangle,box,arrow"
For our colors, rectangle will be white (0xFFFFFF), box will be light blue (0xAACCFC), and finally, arrow will be a red color (0xDE2222). So the upSkinShapeColors will look like this:
upSkinShapeColors="0xFFFFFF,0xAACCFC,0xDE2222"
upSkinShapeAlphas: Sets the alpha for each shape created. Works exactly like the example above with colors, however this attribute controls the alphas:
upSkinShapeAlphas="0.8,0.4,1"
The rectangle's alpha will be 0.8. The box's alpha value will be 0.4, and the arrow will be 1.
upSkinShapesPosition: Sets the X and Y positions of each shape. This works similar tothe above attributes, however the shape's X and Y a seperated by a space:
upSkinShapesPosition="1 13,90 1,93 28"
In this example, the rectangle will be assigned to 1, 13. The box is assigned to 90, 1. Finally, the arrow is assigned the to 93, 28 corrdinate.
alternateColorsEnabled: Determines whether to use Alternative Row Colors. Boolean value only: use 0 or 1.
alternateColors work the same as any other skin attribute. These attributes can have custom shapes, gradients, etc.
Important note: If alternateColorsEnabled is 0, the color that will be displayed in the ComboBox's textField background is defaulted to: alternateColor1SkinColor
The item node has three attributes:
label: The text label of the item.
data: Optional data. This can be used to store an abbreviation, a description, etc. (Optional)
iconSource: Used to display an icon. The icon must be in the Flash Library with Linkage. Use the class name. (Optional)
url: Have a link stored in this attribute. When the item is clicked, a URL is loaded. (Optional)
NOTE: You do not need to include any of these attributes with the exception of the label (you can not include it if you'd like, however the combo will be blank). This way, you can have icons displayed only on certain items or URLs assigned to certain items as well.
Example: This XML will display an icon every other line:
<item label="Square" iconSource="RedBox"/>
<item label="Triangle"/>
<item label="Animated Circle" iconSource="CircleIcon"/>
<item label="Square" />
1. How come my icon doesn't show up in the comboBox itself, it only shows in the drop down list?
2. How do I use my own AlternateColors that I've drawn in Flash?
3. How do I skin the ComboBox without using the programmically created skins?
5. I'm getting dashes in my data and there isn't dashes in my data!
How come my icon doesn't show up in the comboBox itself, it only shows in the drop down list?
I haven't found a clean way to initialize the comboBox to add in the custom icons. HOWEVER, I have manage to do this in Flex with the ClassFactory... which isn't available to use in Flash :( If anyone knows of a way to initialize the component before it's loaded, I could easily add in the icons. If you're interested in the Flex version of this component (same functionality but customized faster with CSS), drop me a line.
How do I use my own AlternateColors that I've drawn in Flash?
1. Open your library, double-click on the comboBox component.
2. Navigate to the CellRendererSkins folder.
3. Select the CellRenderer_upSkin, right-click and DUPLICATE the movieclip. Call the movieclip something like CellRenderer_alt1.
4. Repeat this step for CellRenderer_alt2.
5. Draw your two alternating color graphics. Once completed, right-click on CellRenderer_alt1 and click on Linkage:
6. Enable Export for ActionScript and press Ok. A warning box will appear, simply hit Ok on that one too.
7. Do the same to CellRenderer_alt2 movieclip.
8. Open the AlternatingRowColors class (com.rsadwick.skins.AlternatingRowColors). This is the custom item renderer class. Make these modifications:
9. Around line 80, find the above code. Comment out the setStyle("upSkin", AlternatingColor1); Under that line, add this:
setStyle("upSkin", CellRenderer_alt1); Do the same for CellRenderer_alt2. Also, do the same for the defaulted state in case you disable Alt row coloring.
10. Save the file, your results should be similar to:
How do I skin the ComboBox without using the programmically created skins?
1. Double-click on the comboBox component. You'll get something like this:
2. Jump into the library and we'll pick the ComboBox_upSkin. Duplicate this movieClip and name it ComboBox_upSkin_new
3. Right-click on ComboBox_upSkin_new and select Linkage:
4. Edit the skin the way you want.
5. If you're happy with your skin, replace ComboBox_upSkin with your new skin. (note: it's always safe to keep a backup just in case you need to revert back. Also, if you want the default Flash skin back, simply open a new file and drag a new comboBox to your stage.)
6. Open the XML file you wish to use and change the value of useSkins to "0"
7. Save the file and you should see a different result with the upSkin of the comboBox:
8. Do these same steps for each skin you would like to design.
You can't simply embed the fonts by setting the embed flag in the XML file to true. Although it's not as easy as that, embedding fonts is very easy. We need decide on a font to embed and create that font in the library:
1. Go into your library and create a new font by clicking on the top right menu:
Pick the font you want and any properties:
NOTE: The fontSize, bold, and italics attributes in the XML file override these settings.
2. Next, let's setup the linkage for the font. Go into your library, select the font, and define the linkage:
3. Now, enable embedFonts and type in the name of the font class in the fontClass attribute, in this case, we're using DigitalFont in the XML file:
Note: If embedFonts is not enabled or you do not specify the class name within the fontClass attribute, no font will be embedded and the comboBox will default to the font name in the XML file.
If you wish to make sure that your font was embedded, go into the CustomComboBox class. Around line 404, uncomment the rotation line: cb.rotation = 5;
4. Save the file and run your FLA. You should see results such as:
I'm getting dashes in my data and there isn't dashes in my data!
If you're getting dashes in your data, it is because of the displayOptions attribute in the XML file. Set the attribute to "1". The display options is a special attribute that allows you to change the display of the label and add dashes if needed.
To find out more about the displayOptions attribute, take a look at the XML listing.
Intro - XML Properties - Skin Attributes - Item Attributes - FAQ