1////////////////////////////////////////////////////////////////////////////////
2//
3//  ADOBE SYSTEMS INCORPORATED
4//  Copyright 2009 Adobe Systems Incorporated
5//  All Rights Reserved.
6//
7//  NOTICE: Adobe permits you to use, modify, and distribute this file
8//  in accordance with the terms of the license agreement accompanying it.
9//
10////////////////////////////////////////////////////////////////////////////////
11
12package spark.utils
13{
14
15import  mx.core.FlexVersion;
16
17/**
18 *  The LabelUtil class is used by components to determine the correct
19 *  text to display for their renderers or sub-parts.
20 *
21 *  @langversion 3.0
22 *  @playerversion Flash 10
23 *  @playerversion AIR 1.5
24 *  @productversion Flex 4
25 */
26public class LabelUtil
27{
28    include "../core/Version.as";
29
30    //--------------------------------------------------------------------------
31    //
32    //  Class methods
33    //
34    //--------------------------------------------------------------------------
35
36    /**
37     *  A function used by components that support item renderers
38     *  to determine the correct text an item renderer should display for a data item.
39     *  If no <code>labelField</code> or <code>labelFunction</code> parameter
40     *  is specified, the <code>toString()</code> method of the data item
41     *  is called to return a String representation of the data item.
42     *
43     *  <p>The <code>labelFunction</code> property takes a reference to a function.
44     *  The function takes a single argument which is the item in
45     *  the data provider and returns a String:</p>
46     *  <pre>
47     *  myLabelFunction(item:Object):String</pre>
48     *
49     *  @param item The data item. Null items return the empty string.
50     *
51     *  @param labelField The field in the data item to return. If labelField is set
52     *  to an empty string (""), no field will be considered on the data item
53     *  to represent label.
54     *
55     *  @param labelFunction A function that takes the data item
56     *  as a single parameter and returns a String.
57     *
58     *  @return A String representation for the data item
59     *
60     *  @langversion 3.0
61     *  @playerversion Flash 10
62     *  @playerversion AIR 1.5
63     *  @productversion Flex 4
64     */
65    public static function itemToLabel(item:Object, labelField:String=null,
66        labelFunction:Function=null):String
67    {
68        if (labelFunction != null)
69            return labelFunction(item);
70
71        // early check for Strings
72        if (item is String)
73            return String(item);
74
75        if (item is XML)
76        {
77            try
78            {
79                if (item[labelField].length() != 0)
80                    item = item[labelField];
81                //by popular demand, this is a default XML labelField
82                //else if (item.@label.length() != 0)
83                //  item = item.@label;
84            }
85            catch(e:Error)
86            {
87            }
88        }
89        else if (item is Object)
90        {
91            try
92            {
93                if (item[labelField] != null)
94                    item = item[labelField];
95            }
96            catch(e:Error)
97            {
98            }
99        }
100
101        // late check for strings if item[labelField] was valid
102        if (item is String)
103            return String(item);
104
105        // special case for empty labelField
106        if (labelField == "" && FlexVersion.compatibilityVersion >= FlexVersion.VERSION_4_5)
107            return "";
108
109        try
110        {
111            if (item !== null)
112                return item.toString();
113        }
114        catch(e:Error)
115        {
116        }
117
118        return " ";
119    }
120}
121
122}
123