Updated Branches:
  refs/heads/mobileexperimental b68e18285 -> 37832b98d


https://issues.apache.org/jira/browse/FLEX-33777 Dagrid for mobile
- fixed ASDOC


Project: http://git-wip-us.apache.org/repos/asf/flex-sdk/repo
Commit: http://git-wip-us.apache.org/repos/asf/flex-sdk/commit/37832b98
Tree: http://git-wip-us.apache.org/repos/asf/flex-sdk/tree/37832b98
Diff: http://git-wip-us.apache.org/repos/asf/flex-sdk/diff/37832b98

Branch: refs/heads/mobileexperimental
Commit: 37832b98d62a63315488133959d722027deadb0c
Parents: b68e182
Author: mamsellem <[email protected]>
Authored: Thu Oct 3 23:04:11 2013 +0200
Committer: mamsellem <[email protected]>
Committed: Thu Oct 3 23:04:11 2013 +0200

----------------------------------------------------------------------
 .../src/spark/components/MobileGrid.as          | 28 +++++++++---------
 .../itemRenderers/IMobileGridCellRenderer.as    | 16 +++++++----
 .../IMobileGridTextCellRenderer.as              | 19 ++++++++++---
 .../MobileGridBitmapCellRenderer.as             | 26 ++++++++++++++---
 .../itemRenderers/MobileGridTextCellRenderer.as | 27 ++++++++++++++++++
 .../supportClasses/MobileGridColumn.as          | 30 ++++++++++----------
 .../supportClasses/MobileGridRowRenderer.as     |  4 +++
 7 files changed, 109 insertions(+), 41 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/MobileGrid.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/MobileGrid.as 
b/frameworks/projects/experimental_mobile/src/spark/components/MobileGrid.as
index 39977d7..ce76f6f 100644
--- a/frameworks/projects/experimental_mobile/src/spark/components/MobileGrid.as
+++ b/frameworks/projects/experimental_mobile/src/spark/components/MobileGrid.as
@@ -49,36 +49,38 @@ use namespace  mx_internal;
 [Event(name="sortChange", type="spark.events.MobileGridHeaderEvent")]
 
 /**
- *  The MobileGrid displays a collection of items in a grid of rows and 
columns, with column headers, optimized for mobile devices.
- *  The MobileGrid component provides the following features:
- *  <ul>
+ * The MobileGrid displays a collection of items in a grid of rows and columns 
and column headers and is optimized for speed on mobile devices.
+ * <p> The MobileGrid component provides the following features:
+ * <ul>
  *      <li> user can swipe through the rows in the datagrid. </li>
  *      <li> supports single selection of a row. </li>
  *      <li> rows can be sorted according to a given column by clicking on the 
column's header. </li>
  *      <li> cells can be displayed as text in different fonts and formats, as 
images, or using a custom renderer. </li>
  *      <li> default  skin uses dark shades of gray, and is available in 
different screen densities.</li>
  *  </ul>
- *
+ * </p>
  * <p> It's important to understand that MobileGrid does not have all the 
capabilities and flexibility of it's desktop equivalent,
  * in order to ensure optimal display and scrolling performance on mobile 
devices. </p>
  * <p>Typically, the following features are not available in MobileGrid:
- * <ul>
- *     <li>the list of columns is static and cannot be changed at runtime</li>
+ *  <ul>
  *     <li>multiple selection is not supported </li>
  *     <li>it's not possible to interactively reorder columns </li>
+ *     <li> MobileGrid does  not scroll horizontally, even when the column 
widths exceeds the component's width.</li>
  *     <li>custom cell renderers must be designed with care, preferably in 
ActionScript, to ensure good display performance </li>
- *   </ul>
- *  </p>
+ *  </ul>
+ * </p>
  * <p>Internally,  MobileGrid inherits for Mobile spark.List component rather 
than any Grid or DataGrid, which means that all cell renderers
  * in a single row are managed   by one single MobileGridRowRenderer that  
delegates the individual  cell renderers to light-weight sub-renderers. </p>
  * <p> You usually don't access this internal row renderer yourself, and will 
rather define the individual cell renderers.</p>
- * <p> This technique ensures optimal display and memory performance, which is 
critical for mobile devices,, at the price of less flexibility for cell 
renderers. </p>
- *
- *  @see spark.components.supportClasses.MobileGridColumn
+ * <p> This technique ensures optimal display and memory performance, which is 
critical for mobile devices, at the price of less flexibility for cell 
renderers. </p>
+ * <p>Click the link below to view examples of MobileGrid usage on the 
ApacheFlex github repository.</p>
  *
+ *    @see spark.components.supportClasses.MobileGridColumn
+ *    @see 
https://github.com/apache/flex-examples/tree/develop/showcase/4.11/components/mobilegrid/index.html
 Examples of MobileGrid usage on ApacheFlex github
  *  @langversion 3.0
  *  @playerversion AIR 3.8
  *  @productversion Flex 4.11
+ *
  */
 public class MobileGrid extends List
 {
@@ -103,9 +105,9 @@ public class MobileGrid extends List
     }
 
     /**
-     *  An array of MobileGridColumn objects, one for each column that  can be 
displayed.
+     *  An array of MobileGridColumn objects, one for each column to display.
      *  <p>Contrary to desktop DataGrid, this property must be set explicitly 
, or no columns will be displayed.</p>
-     *  <p>If you want to change the set of columns,you need to re-assign the 
new array to the columns property.
+     *  <p>If you want to change the set of columns, you need to re-assign the 
new array to the columns property.
      *  Changes to the original array without assigning the property will have 
no effect.</p>
      *
      *  @see   spark.components.supportClasses.MobileGridColumn

http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridCellRenderer.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridCellRenderer.as
 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridCellRenderer.as
index eb5ddc7..abac1db 100644
--- 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridCellRenderer.as
+++ 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridCellRenderer.as
@@ -23,9 +23,9 @@ import mx.core.IDataRenderer;
 import mx.styles.IStyleClient;
 
 /**
- * This is the base interface that all mobile cell or other mobile item part 
renderers must implement.
- * Contrary to desktop DataGrid control, there is no default base renderer,
- * because mobile renderers must be lightweight, and derive directly for the 
existing component, (ie. s:Button or s:CheckBox ).
+ * This is the base interface that all mobile grid cell renderers must 
implement.
+ * <p>Contrary to desktop DataGrid control, there is no default implementation 
for this interface,
+ * because mobile renderers must be lightweight, and derive directly for an 
existing component, (eg.. s:Button or s:CheckBox ).</p>
  *
  *  @langversion 3.0
  *  @playerversion AIR 3.8
@@ -40,12 +40,18 @@ public interface IMobileGridCellRenderer extends 
IDataRenderer
      */
     function set styleProvider(value:IStyleClient):void ;
 
+    /** Flag indicating whether the layout manager can stretch the width of 
this renderer to match the column's width.
+     <p> default value is false.  Override the getter to return a difference 
value </p>
+     */
     function get canSetContentWidth():Boolean;
 
+    /** Flag indicating whether the layout manager can stretch the height of 
this renderer to match the column's height.
+     <p> default value is false.  Override the getter to return a difference 
value </p>
+     */
     function get canSetContentHeight():Boolean;
 
-    /**
-     * @private
+    /** this property is set with the GridColumn's styleName property.
+     <p> you can override it to extract information from the style and pass 
them to this renderer.</p>
      */
     function set cssStyleName(value:String):void;
 

http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridTextCellRenderer.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridTextCellRenderer.as
 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridTextCellRenderer.as
index d26c312..694ed1c 100644
--- 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridTextCellRenderer.as
+++ 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/IMobileGridTextCellRenderer.as
@@ -19,7 +19,10 @@
 package spark.components.itemRenderers
 {
 
-/**  Extended interface for renderer that include text
+/**  Extends IMobileGridCellRenderers with APIs for rendering text in 
MobileGrid cells.
+ *  <p>Typically , implementors will set the text to render using labelField 
and/or labelFunction this way:      </p>
+ *  <code> text = UIComponentUtils.itemToLabel(value, _labelField, 
_labelFunction); </code>
+ *
  *  @langversion 3.0
  *  @playerversion AIR 3.8
  *  @productversion Flex 4.11
@@ -27,13 +30,21 @@ package spark.components.itemRenderers
 
 public interface IMobileGridTextCellRenderer extends IMobileGridCellRenderer
 {
-    /* implement this property so that the renderer can receive the dataField 
from the renderer's MobileGridColumn*/
+    /**
+     *  Implement this property so that the renderer can receive the dataField 
from its MobileGridColumn.
+     * @see spark.components.supportClasses.MobileGridColumn#labelField
+     *  */
     function set labelField(value:String):void;
 
-    /* implement this property so that the renderer can receive the 
labelFunction from the renderers' MobileGridColumn*/
+    /**
+     *  Implement this property so that the renderer can receive the 
labelFunction its MobileGridColumn
+     *  @see spark.components.supportClasses.MobileGridColumn#labelFunction */
     function set labelFunction(value:Function):void;
 
-    /* implement this property so that the renderer can receive the textAlign 
property from the renderers' MobileGridColumn*/
+    /**
+     *  Implement this property so that the renderer can receive the textAlign 
property from the renderers' MobileGridColumn
+     *  @see spark.components.supportClasses.MobileGridColumn#textAlign
+     *  */
     function set textAlign(textAlign:String):void;
 }
 }

http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridBitmapCellRenderer.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridBitmapCellRenderer.as
 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridBitmapCellRenderer.as
index 1eed532..8ed04c4 100644
--- 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridBitmapCellRenderer.as
+++ 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridBitmapCellRenderer.as
@@ -50,7 +50,7 @@ public class MobileGridBitmapCellRenderer extends BitmapImage 
implements IMobile
 
     /**
      *  The name of the field or property in the DataGrid's dataProvider item 
that defines the icon to display for this renderer's column.
-     *  <p> The field value must be either an embedded bitmap's class, or or 
MultiBitmapSource object.   </p>
+     *  <p> The field value must be either an embedded bitmap's class, or a 
MultiBitmapSource object.   </p>
      *   <p> If not set, then iconFunction will be used.  </p>
      *  @default null
      *
@@ -82,7 +82,7 @@ public class MobileGridBitmapCellRenderer extends BitmapImage 
implements IMobile
      *
      *  @default null
      *
-     *  @see #iconLabel
+     *  @see #iconField
      *  @see  spark.utils.MultiDPIBitmapSource
      *
      */
@@ -96,6 +96,9 @@ public class MobileGridBitmapCellRenderer extends BitmapImage 
implements IMobile
         _iconFunction = value;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set data(value:Object):void
     {
         _data = value;
@@ -103,28 +106,43 @@ public class MobileGridBitmapCellRenderer extends 
BitmapImage implements IMobile
         this.source = iconSource;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function get data():Object
     {
         return _data;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set styleProvider(value:IStyleClient):void
     {
         // do nothing, this renderer does not manages styles for now.
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set cssStyleName(value:String):void
     {
 
     }
 
-    /* to avoid any scaling artifacts, we do not allow bitmap to be stretcghed 
*/
-
+    /**
+     *  Returns false to avoid any density scaling artifacts.
+     *   @inheritDoc
+     *  */
     public function get canSetContentWidth():Boolean
     {
         return false;
     }
 
+    /**
+     *  Returns false to avoid any density scaling artifacts.
+     *   @inheritDoc
+     *  */
     public function get canSetContentHeight():Boolean
     {
         return false;

http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridTextCellRenderer.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridTextCellRenderer.as
 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridTextCellRenderer.as
index 139d9a3..8a74e88 100644
--- 
a/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridTextCellRenderer.as
+++ 
b/frameworks/projects/experimental_mobile/src/spark/components/itemRenderers/MobileGridTextCellRenderer.as
@@ -52,17 +52,26 @@ public class MobileGridTextCellRenderer extends 
StyleableTextField implements IM
         multiline = true;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set styleProvider(value:IStyleClient):void
     {
         styleName = value;
         commitStyles();
     }
 
+    /**
+   *  @inheritDoc
+     */
     public function set textAlign(value:String):void
     {
         setStyle("textAlign", value);
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set cssStyleName(pstyleName:String):void
     {
         var css:CSSStyleDeclaration = pstyleName ? 
StyleManager.getStyleManager(null).getStyleDeclaration("." + pstyleName) : null;
@@ -76,32 +85,50 @@ public class MobileGridTextCellRenderer extends 
StyleableTextField implements IM
         }
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set data(value:Object):void
     {
         _data = value;
         text = UIComponentUtils.itemToLabel(value, _labelField, 
_labelFunction);
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function get data():Object
     {
         return _data;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set labelField(value:String):void
     {
         _labelField = value;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function set labelFunction(value:Function):void
     {
         _labelFunction = value;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function get canSetContentWidth():Boolean
     {
         return true;
     }
 
+    /**
+     *  @inheritDoc
+     */
     public function get canSetContentHeight():Boolean
     {
         return false;

http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridColumn.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridColumn.as
 
b/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridColumn.as
index 95d2d85..23b9f87 100644
--- 
a/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridColumn.as
+++ 
b/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridColumn.as
@@ -38,8 +38,8 @@ import 
spark.components.itemRenderers.MobileGridTextCellRenderer;
  * such as the field of the data provider item whose value is to be displayed 
in the column.
  * MobileGridColumn takes most of its properties  from its parent class and 
adds the following Grid-specific options:</p>
  * <ul>
- *     <li>headerText and headerStyleName: optional label and style to display 
in the header for this column </li>
- *     <li>sortable, sortDescending and sortField: sorting options for this 
column </li>
+ *     <li>headerText and headerStyleName: optional label and style to display 
in the header for this column.</li>
+ *     <li>sortable, sortDescending and sortField: sorting options for this 
column.</li>
  *  </ul>
  *
  *  @see spark.components.MobileGrid
@@ -97,8 +97,7 @@ public class MobileGridColumn extends EventDispatcher
 
 
     /** Set the desired width for this column.
-     * <p> Width value is expressed in current applicationDPI, or at 160 DPI  
if applicationDPI is not set.
-     * The default value is 100.
+     * <p> Width value is expressed in current applicationDPI, or at 160 DPI  
if applicationDPI is not set. </p>
      *
      *  <p>Note: You can specify a percentage value in the MXML
      *  <code>width</code> attribute, such as <code>width="50%"</code>,
@@ -132,7 +131,7 @@ public class MobileGridColumn extends EventDispatcher
      *      <li> First, honor all columns with fixed widths.  Columns with no 
width or percentWidth receive a width of 100.</li>
      *      <li> Then distribute the remainder of width between all the 
columns with percentage widths.
      *      If the total of percentages is greater that 100%, it's will be 
normalized first..</li>
-     *   <ul>
+     *   </ul>
      *  </p>
      *
      * @default NaN
@@ -155,9 +154,11 @@ public class MobileGridColumn extends EventDispatcher
      *
      *  <p>The default item renderer is the ItemTextPartRenderer class,
      *  which displays the data item as text, optimized for mobile.  </p>
-     *  <p>You can use also ItemBitmapPartRenderer to display embedded 
bitmaps, in which case you need to define the iconField or iconFunction </p>
-     *  <p>You can also  create custom item renderers by deriving any subclass 
of UIComponent (eg. s:Button) and implementing IMobileGridCellRenderer.
-     *  for performance reasons  it's preferable that your renderer be written 
in ActionScript
+     *  <p>You can use also ItemBitmapPartRenderer to display embedded bitmaps,
+     *  in which case you need to define the iconField or iconFunction </p>
+     *  <p>You can also  create custom item renderers by deriving any subclass 
of UIComponent (eg. s:Button)
+     *  and implementing IMobileGridCellRenderer.</p>
+     *  <p>For performance reasons  it's preferable that your renderer be 
written in ActionScript and be as light as possible.</p>
      *
      *  @see #dataField
      *  @see spark.components.itemRenderers.MobileGridTextCellRenderer
@@ -179,7 +180,7 @@ public class MobileGridColumn extends EventDispatcher
 
 
     /**
-     *  An idempotent function that converts a data provider item into a 
column-specific string
+     *  An user-defined function that converts a data provider item into a 
column-specific string
      *  that's used to initialize the item renderer's <code>label</code> 
property.
      *
      *  <p>You can use a label function to combine the values of several data 
provider items
@@ -193,8 +194,7 @@ public class MobileGridColumn extends EventDispatcher
      *
      *  <pre>labelFunction(item:Object):String</pre>
      *
-     *  <p>The <code>item</code> parameter is the data provider item for an 
entire row.
-     *  The second parameter is this column object.</p>
+     *  <p>The <code>item</code> parameter is the data provider item for an 
entire row.</p>
      *
      *  <p>A typical label function could concatenate the firstName and
      *  lastName properties of the data provider item ,
@@ -212,8 +212,8 @@ public class MobileGridColumn extends EventDispatcher
 
     private var _styleName:String;
 
-    /** The css style name to apply to the renderer
-     *  the style items in the css will depend on the renderer. For example, 
text renderers will accept fontSize, color, fontWeight, etc.
+    /** The css style name to apply to the renderer.
+     * <p>The style items in the css entry will depend on the renderer. For 
example, text renderers will accept fontSize, color, fontWeight, etc.  </p>
      */
     public function get styleName():String
     {
@@ -282,7 +282,7 @@ public class MobileGridColumn extends EventDispatcher
     private var _sortable:Boolean = true;
 
     /** Flag indicating whether a column can be sorted by clicking on its 
header.
-     *  <p>This flag is effective only if the MobileGrid </p>
+     *  <p>This flag is effective only if the MobileGrid sortableColumn is not 
set or set to true.</p>
      */
     public function get sortable():Boolean
     {
@@ -325,7 +325,7 @@ public class MobileGridColumn extends EventDispatcher
         return sortField;
     }
 
-    public function createPartRenderer():IMobileGridCellRenderer
+    mx_internal function createPartRenderer():IMobileGridCellRenderer
     {
         var pr:IMobileGridCellRenderer = _itemRenderer.newInstance() as 
IMobileGridCellRenderer;
         if (pr)

http://git-wip-us.apache.org/repos/asf/flex-sdk/blob/37832b98/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridRowRenderer.as
----------------------------------------------------------------------
diff --git 
a/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridRowRenderer.as
 
b/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridRowRenderer.as
index 832997d..61aea73 100644
--- 
a/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridRowRenderer.as
+++ 
b/frameworks/projects/experimental_mobile/src/spark/components/supportClasses/MobileGridRowRenderer.as
@@ -20,12 +20,16 @@ package spark.components.supportClasses
 {
 import flash.display.DisplayObject;
 
+import mx.core.mx_internal;
+
 import spark.components.itemRenderers.IMobileGridCellRenderer;
 import spark.core.DisplayObjectSharingMode;
 import spark.core.IGraphicElement;
 import spark.core.IGraphicElementContainer;
 import spark.core.ISharedDisplayObject;
 
+use namespace mx_internal;
+
 /**  @private
  *  This is the base class for multi-part renderers that manages a vector of 
part renderers.
  *  This class is responsible for creating and storing  the actual renderers 
from their descriptors

Reply via email to