plugins/dali-script-v8/docs/content/item-factory.js

   1 /**
   2  *
   3 ## ItemFactory API
   4
   5  ItemFactory is for storing the data of {{#crossLink "ItemView"}}ItemView{{/crossLink}}
   6  and creating actors for ItemView on request. Each item in ItemView is identified by a
   7  unique ID, and has a linear order from 0.
   8
   9  A JSON file should be provided to ItemFactory which defines the templates of items
  10  to be used to create the actors. Multiple templates can be defined in the JSON file
  11  for different type of items.
  12
  13 ### Simple example of creating a JSON template for items
  14
  15 ```
  16   {
  17     "templates":
  18     {
  19       "template-item":
  20       {
  21         "name":"item",
  22         "type":"Actor",
  23         "position":[0,0,0],
  24         "anchorPoint":"TOP_LEFT",
  25         "parentOrigin":"TOP_LEFT",
  26         "actors":
  27          [
  28           {
  29             "name":"icon",
  30             "type":"ImageView",
  31             "image":
  32             {
  33               "rendererType" : "imageRenderer",
  34               "imageUrl": "{icon_path}"
  35             },
  36             "position":[20.0, 0.0, 0.0],
  37             "size":[70.0, 70.0, 0.0],
  38             "color":[1.0,1.0,1.0,1.0],
  39             "anchorPoint":"CENTER_LEFT",
  40             "parentOrigin":"CENTER_LEFT",
  41             "actors":
  42             [
  43               {
  44                 "name":"title",
  45                 "anchorPoint":"CENTER_LEFT",
  46                 "parentOrigin":"CENTER_RIGHT",
  47                 "type":"TextLabel",
  48                 "position": [30.0, 0.0, 0.0],
  49                 "size":[200.0, 70.0, 0.0],
  50                 "pointSize":30,
  51                 "fontFamily":"HelveticaNeue",
  52                 "fontStyle":"Bold",
  53                 "horizontalAlignment":"BEGIN",
  54                 "verticalAlignment":"CENTER",
  55                 "textColor": [1.0,0.0,1.0,1.0],
  56                 "text":"{title_text}"
  57               }
  58             ]
  59           }
  60         ]
  61       }
  62     }
  63   }
  64 ```
  65
  66  The data of items should be provided to ItemFactory as an array of property maps
  67  in which each map contains the data for each item, including the template to be used
  68  to build the actor and the pairs of key/value to be used to replace the constants
  69  defined in the template. The order of property maps in the array represents the actual
  70  order of items in ItemView.
  71
  72  ### Example of defining the data of an ItemView with two items
  73
  74 ```
  75   var itemViewData = [
  76                        { "template" : "template-item",
  77                          "icon_path" : "icon0.png",
  78                          "title_text" : "Item 0" },
  79                        { "template" : "template-item",
  80                          "icon_path" : "icon1.png",
  81                          "title_text" : "Item 1" }
  82                      ];
  83 ```
  84
  85  This means ItemFactory will use the template "template-item" defined in the JSON file
  86  to create the item for ItemView and replace the constants "icon_path" and "title_text"
  87  in the template with their actual values, e.g. "icon0.png" and "Item 0". Each item can
  88  have different template and different data.
  89
  90  ### Example of creating an ItemFactory with the above JSON template and link it with an ItemView
  91
  92 ![ ](../assets/img/item-view/list.png)
  93
  94 ```
  95   // Define the data of 100 items
  96   var itemViewData = [];
  97   for (var itemId = 0; itemId < 100; itemId++)
  98   {
  99     var itemData = {};
 100     itemData["template"] = "template-item";
 101     itemData["icon_path"] = "icon" + itemId + ".png";
 102     itemData["title_text"] = "Item " + itemId;
 103     itemViewData[itemId] = itemData;
 104   }
 105
 106   // Create the item factory and set the JSON template file and item view data
 107   var itemFactory = new dali.ItemFactory();
 108   itemFactory.jsonTemplateFile = "./item-template.json"; // Set the JSON template file
 109   itemFactory.data = itemViewData; // Set the ItemView data
 110
 111   // Create the item view with the given item factory
 112   var itemView = new dali.Control("ItemView", itemFactory);
 113   itemView.size = [stageSize.x, stageSize.y, 0.0];
 114   itemView.parentOrigin = dali.CENTER_LEFT;
 115   itemView.anchorPoint = dali.CENTER_LEFT;
 116   dali.stage.add( itemView );
 117
 118   // Add a list layout to ItemView (multiple layouts can be added to the same ItemView)
 119   itemView.addLayout(dali.ITEM_LAYOUT_LIST);
 120
 121   // Set custom item size for the list layout
 122   // If set, this will overide the predefined item size in the list layout
 123   itemView.setItemSize(0, [350, 100, 0]); // 0 means the first layout added to ItemView
 124
 125   // Acticate the list layout (which will layout the items as a list)
 126   itemView.activateLayout(0, itemView.size); // 0 means the first layout added to ItemView
 127 ```
 128
 129  ### Example of changing the data of items in ItemView dynamically
 130
 131 ```
 132   var data = itemFactory.data;
 133   data[itemId]["icon_path"] = "new-icon.png";
 134   data[itemId]["title_text"] = "New Item";
 135   itemFactory.data = data; // ItemView will update the changed items immediately
 136 ```
 137
 138  @class ItemFactory
 139
 140 */
 141
 142 /**
 143  * Sets the file name of JSON template that contains the templates for items.
 144  *
 145  * @example
 146  *    itemFactory.jsonTemplateFile = "item-template.json"; // ItemFactory will look for the template from this JSON file
 147  *
 148  * @type String
 149  * @property jsonTemplateFile
 150  */
 151 JSON_TEMPLATE_FILE
 152
 153 /**
 154  * Sets the data of ItemView
 155  *
 156  *  The data is an array of property maps in which each map contains the data
 157  *  for each item, including the template to be used to build the actor and
 158  *  the pairs of key/value to be used to replace the constants defined in the
 159  *  template. The order of property maps in the array represents the actual
 160  *  order of items in ItemView.
 161  *
 162  * @example
 163  *   var itemViewData = [
 164  *                        { "template" : "template-item",
 165  *                          "icon_path" : "icon0.png",
 166  *                          "title_text" : "Item 0" },
 167  *                        { "template" : "template-item",
 168  *                          "icon_path" : "icon1.png",
 169  *                          "title_text" : "Item 1" }
 170  *                     ];
 171  *
 172  *    itemFactory.data = itemViewData; // ItemFactory will look for the template from this JSON file
 173  *
 174  * @type Array
 175  * @property data
 176  */
 177 DATA