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
