third_party/polymer/components/core-iconset/core-iconset.html

   1 <!--
   2 Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
   3 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
   4 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   5 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   6 Code distributed by Google as part of the polymer project is also
   7 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
   8 -->
   9
  10 <!--
  11 /**
  12  * @group Polymer Core Elements
  13  *
  14  * The `core-iconset` element allows users to define their own icon sets.
  15  * The `src` property specifies the url of the icon image. Multiple icons may
  16  * be included in this image and they may be organized into rows.
  17  * The `icons` property is a space separated list of names corresponding to the
  18  * icons. The names must be ordered as the icons are ordered in the icon image.
  19  * Icons are expected to be square and are the size specified by the `iconSize`
  20  * property. The `width` property corresponds to the width of the icon image
  21  * and must be specified if icons are arranged into multiple rows in the image.
  22  *
  23  * All `core-iconset` elements are available for use by other `core-iconset`
  24  * elements via a database keyed by id. Typically, an element author that wants
  25  * to support a set of custom icons uses a `core-iconset` to retrieve
  26  * and use another, user-defined iconset.
  27  *
  28  * Example:
  29  *
  30  *     <core-iconset id="my-icons" src="my-icons.png" width="96" iconSize="24"
  31  *         icons="location place starta stopb bus car train walk">
  32  *     </core-iconset>
  33  *
  34  * This will automatically register the icon set "my-icons" to the iconset
  35  * database.  To use these icons from within another element, make a
  36  * `core-iconset` element and call the `byId` method to retrieve a
  37  * given iconset. To apply a particular icon to an element, use the
  38  * `applyIcon` method. For example:
  39  *
  40  *     iconset.applyIcon(iconNode, 'car');
  41  *
  42  * Themed icon sets are also supported. The `core-iconset` can contain child
  43  * `property` elements that specify a theme with an offsetX and offsetY of the
  44  * theme within the icon resource. For example.
  45  *
  46  *     <core-iconset id="my-icons" src="my-icons.png" width="96" iconSize="24"
  47  *         icons="location place starta stopb bus car train walk">
  48  *       <property theme="special" offsetX="256" offsetY="24"></property>
  49  *     </core-iconset>
  50  *
  51  * Then a themed icon can be applied like this:
  52  *
  53  *     iconset.applyIcon(iconNode, 'car', 'special');
  54  *
  55  * @element core-iconset
  56  * @extends core-meta
  57  * @homepage github.io
  58  */
  59 -->
  60
  61 <link rel="import" href="../core-meta/core-meta.html">
  62
  63 <polymer-element name="core-iconset" extends="core-meta" attributes="src width icons iconSize">
  64
  65   <script>
  66
  67     Polymer('core-iconset', {
  68
  69       /**
  70        * The URL of the iconset image.
  71        *
  72        * @attribute src
  73        * @type string
  74        * @default ''
  75        */
  76       src: '',
  77
  78       /**
  79        * The width of the iconset image. This must only be specified if the
  80        * icons are arranged into separate rows inside the image.
  81        *
  82        * @attribute width
  83        * @type number
  84        * @default 0
  85        */
  86       width: 0,
  87
  88       /**
  89        * A space separated list of names corresponding to icons in the iconset
  90        * image file. This list must be ordered the same as the icon images
  91        * in the image file.
  92        *
  93        * @attribute icons
  94        * @type string
  95        * @default ''
  96        */
  97       icons: '',
  98
  99       /**
 100        * The size of an individual icon. Note that icons must be square.
 101        *
 102        * @attribute iconSize
 103        * @type number
 104        * @default 24
 105        */
 106       iconSize: 24,
 107
 108       /**
 109        * The horizontal offset of the icon images in the inconset src image.
 110        * This is typically used if the image resource contains additional images
 111        * beside those intended for the iconset.
 112        *
 113        * @attribute offsetX
 114        * @type number
 115        * @default 0
 116        */
 117       offsetX: 0,
 118       /**
 119        * The vertical offset of the icon images in the inconset src image.
 120        * This is typically used if the image resource contains additional images
 121        * beside those intended for the iconset.
 122        *
 123        * @attribute offsetY
 124        * @type number
 125        * @default 0
 126        */
 127       offsetY: 0,
 128       type: 'iconset',
 129
 130       created: function() {
 131         this.iconMap = {};
 132         this.iconNames = [];
 133         this.themes = {};
 134       },
 135
 136       ready: function() {
 137         // TODO(sorvell): ensure iconset's src is always relative to the main
 138         // document
 139         if (this.src && (this.ownerDocument !== document)) {
 140           this.src = this.resolvePath(this.src, this.ownerDocument.baseURI);
 141         }
 142         this.super();
 143         this.updateThemes();
 144       },
 145
 146       iconsChanged: function() {
 147         var ox = this.offsetX;
 148         var oy = this.offsetY;
 149         this.icons && this.icons.split(/\s+/g).forEach(function(name, i) {
 150           this.iconNames.push(name);
 151           this.iconMap[name] = {
 152             offsetX: ox,
 153             offsetY: oy
 154           }
 155           if (ox + this.iconSize < this.width) {
 156             ox += this.iconSize;
 157           } else {
 158             ox = this.offsetX;
 159             oy += this.iconSize;
 160           }
 161         }, this);
 162       },
 163
 164       updateThemes: function() {
 165         var ts = this.querySelectorAll('property[theme]');
 166         ts && ts.array().forEach(function(t) {
 167           this.themes[t.getAttribute('theme')] = {
 168             offsetX: parseInt(t.getAttribute('offsetX')) || 0,
 169             offsetY: parseInt(t.getAttribute('offsetY')) || 0
 170           };
 171         }, this);
 172       },
 173
 174       // TODO(ffu): support retrived by index e.g. getOffset(10);
 175       /**
 176        * Returns an object containing `offsetX` and `offsetY` properties which
 177        * specify the pixel locaion in the iconset's src file for the given
 178        * `icon` and `theme`. It's uncommon to call this method. It is useful,
 179        * for example, to manually position a css backgroundImage to the proper
 180        * offset. It's more common to use the `applyIcon` method.
 181        *
 182        * @method getOffset
 183        * @param {String|Number} icon The name of the icon or the index of the
 184        * icon within in the icon image.
 185        * @param {String} theme The name of the theme.
 186        * @returns {Object} An object specifying the offset of the given icon
 187        * within the icon resource file; `offsetX` is the horizontal offset and
 188        * `offsetY` is the vertical offset. Both values are in pixel units.
 189        */
 190       getOffset: function(icon, theme) {
 191         var i = this.iconMap[icon];
 192         if (!i) {
 193           var n = this.iconNames[Number(icon)];
 194           i = this.iconMap[n];
 195         }
 196         var t = this.themes[theme];
 197         if (i && t) {
 198           return {
 199             offsetX: i.offsetX + t.offsetX,
 200             offsetY: i.offsetY + t.offsetY
 201           }
 202         }
 203         return i;
 204       },
 205
 206       /**
 207        * Applies an icon to the given element as a css background image. This
 208        * method does not size the element, and it's often necessary to set
 209        * the element's height and width so that the background image is visible.
 210        *
 211        * @method applyIcon
 212        * @param {Element} element The element to which the background is
 213        * applied.
 214        * @param {String|Number} icon The name or index of the icon to apply.
 215        * @param {Number} scale (optional, defaults to 1) A scaling factor
 216        * with which the icon can be magnified.
 217        * @return {Element} The icon element.
 218        */
 219       applyIcon: function(element, icon, scale) {
 220         var offset = this.getOffset(icon);
 221         scale = scale || 1;
 222         if (element && offset) {
 223           var icon = element._icon || document.createElement('div');
 224           var style = icon.style;
 225           style.backgroundImage = 'url(' + this.src + ')';
 226           style.backgroundPosition = (-offset.offsetX * scale + 'px') +
 227              ' ' + (-offset.offsetY * scale + 'px');
 228           style.backgroundSize = scale === 1 ? 'auto' :
 229              this.width * scale + 'px';
 230           if (icon.parentNode !== element) {
 231             element.appendChild(icon);
 232           }
 233           return icon;
 234         }
 235       }
 236
 237     });
 238
 239   </script>
 240
 241 </polymer-element>