carbon-components-angular
Version:
Next generation components
715 lines (594 loc) • 24.5 kB
HTML
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>carbon-components-angular documentation</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/x-icon" href="../images/favicon.ico">
<link rel="stylesheet" href="../styles/style.css">
<link rel="stylesheet" href="../styles/dark.css">
<style>
footer.carbon {
position: absolute;
bottom: 0;
width: 100%;
z-index: 9999;
}
#root > div {
/*
* Subtracting the height of the footer to prevent
* overlaying the footer ontop of content
*/
height: calc(100vh - 48px);
}
</style>
</head>
<body>
<script>
// Blocking script to avoid flickering dark mode
// Dark mode toggle button
var useDark = window.matchMedia('(prefers-color-scheme: dark)');
var darkModeState = useDark.matches;
var $darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input');
var $darkModeToggles = document.querySelectorAll('.dark-mode-switch');
var darkModeStateLocal = localStorage.getItem('compodoc_darkmode-state');
function checkToggle(check) {
for (var i = 0; i < $darkModeToggleSwitchers.length; i++) {
$darkModeToggleSwitchers[i].checked = check;
}
}
function toggleDarkMode(state) {
if (window.localStorage) {
localStorage.setItem('compodoc_darkmode-state', state);
}
checkToggle(state);
const hasClass = document.body.classList.contains('dark');
if (state) {
for (var i = 0; i < $darkModeToggles.length; i++) {
$darkModeToggles[i].classList.add('dark');
}
if (!hasClass) {
document.body.classList.add('dark');
}
} else {
for (var i = 0; i < $darkModeToggles.length; i++) {
$darkModeToggles[i].classList.remove('dark');
}
if (hasClass) {
document.body.classList.remove('dark');
}
}
}
useDark.addEventListener('change', function (evt) {
toggleDarkMode(evt.matches);
});
if (darkModeStateLocal) {
darkModeState = darkModeStateLocal === 'true';
}
toggleDarkMode(darkModeState);
</script>
<div class="navbar navbar-default navbar-fixed-top d-md-none p-0">
<div class="d-flex">
<a href="../" class="navbar-brand">carbon-components-angular documentation</a>
<button type="button" class="btn btn-default btn-menu ion-ios-menu" id="btn-menu"></button>
</div>
</div>
<div class="xs-menu menu" id="mobile-menu">
<div id="book-search-input" role="search"><input type="text" placeholder="Type to search"></div> <compodoc-menu></compodoc-menu>
</div>
<div class="container-fluid main">
<div class="row main">
<div class="d-none d-md-block menu">
<compodoc-menu mode="normal"></compodoc-menu>
</div>
<!-- START CONTENT -->
<div class="content class">
<div class="content-data">
<ol class="breadcrumb">
<li class="breadcrumb-item">Classes</li>
<li class="breadcrumb-item" >IconCache</li>
</ol>
<ul class="nav nav-tabs" role="tablist">
<li class="nav-item">
<a href="#info"
class="nav-link"
class="nav-link active"
role="tab" id="info-tab" data-bs-toggle="tab" data-link="info">Info</a>
</li>
<li class="nav-item">
<a href="#source"
class="nav-link"
role="tab" id="source-tab" data-bs-toggle="tab" data-link="source">Source</a>
</li>
</ul>
<div class="tab-content">
<div class="tab-pane fade active in" id="info">
<p class="comment">
<h3>File</h3>
</p>
<p class="comment">
<code>src/icon/icon.service.ts</code>
</p>
<p class="comment">
<h3>Description</h3>
</p>
<p class="comment">
<p>Abstract class that represent a cache of icons.</p>
<p>The actual caching mechanism will be implementation specific,
but it's likely a good idea to key by the icons name and/or size.
Icon name and size will always be strings, and they will be the two consistent
identifiers of an icon. For the purposes of storage additonal descriptor properties may
be used, but the name and size are the only ones guarenteed to be passed for lookup purposes.</p>
</p>
<section data-compodoc="block-index">
<h3 id="index">Index</h3>
<table class="table table-sm table-bordered index-table">
<tbody>
<tr>
<td class="col-md-4">
<h6><b>Methods</b></h6>
</td>
</tr>
<tr>
<td class="col-md-4">
<ul class="index-list">
<li>
<span class="modifier">Abstract</span>
<a href="#get" >get</a>
</li>
<li>
<span class="modifier">Abstract</span>
<a href="#set" >set</a>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-methods">
<h3 id="methods">
Methods
</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="get"></a>
<span class="name">
<span class="modifier">Abstract</span>
<span ><b>get</b></span>
<a href="#get"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>get(name: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>, size: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="92"
class="link-to-prism">src/icon/icon.service.ts:92</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Finds and returns an icon based on it's name and size</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
</tr>
<tr>
<td>size</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/object" target="_blank" >object</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="set"></a>
<span class="name">
<span class="modifier">Abstract</span>
<span ><b>set</b></span>
<a href="#set"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>set(name: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>, size: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>, descriptor: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/object" target="_blank">object</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="96"
class="link-to-prism">src/icon/icon.service.ts:96</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>stores an icon descriptor to the cache</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
</tr>
<tr>
<td>size</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
</tr>
<tr>
<td>descriptor</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/object" target="_blank" >object</a></code>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
</section>
</div>
<div class="tab-pane fade tab-source-code" id="source">
<pre class="line-numbers compodoc-sourcecode"><code class="language-typescript">import { Injectable } from "@angular/core";
import { toString } from "@carbon/icon-helpers";
// icon imports
import {
Add16,
Calendar16,
CaretDown16,
CaretLeft16,
CaretRight16,
CaretUp16,
Checkmark16,
CheckmarkFilled16,
CheckmarkOutline16,
ChevronDown16,
ChevronRight16,
Close16,
Copy16,
Download16,
ErrorFilled16,
InformationFilled16,
Menu16,
OverflowMenuVertical16,
Save16,
Settings16,
TrashCan16,
Warning16,
WarningFilled16
} from "@carbon/icons";
/**
* An object that represents a parsed icon
*/
export interface IconDescriptor {
/**
* The element to render. For the root this is `svg`
*/
elem: string;
/**
* An object of attributes to apply to the element.
*
* The type here is non-exhaustive.
*/
attrs: {
xmlns: string,
// needed by the icon directive to determine other attributes
viewBox: string,
fill: string,
// needed by the icon directive to determine other attributes
width: string,
// needed by the icon directive to determine other attributes
height: string,
[x: string]: string
};
/**
* The content (children) of the element as an array of `IconDescriptor`s
* (usually without a few fields, namely `name` and `size`)
*/
content: IconDescriptor[];
/**
* The name of the icon.
*
* Needed by the icon service.
*/
name: string;
/**
* The size of the icon in pixels.
*
* Needed by the icon service.
*/
size: number;
/**
* Optional. A string representation of the compiled svg.
* If missing the icon service will add this.
*/
svg?: string;
}
/**
* Abstract class that represent a cache of icons.
*
* The actual caching mechanism will be implementation specific,
* but it's likely a good idea to key by the icons name and/or size.
* Icon name and size will always be strings, and they will be the two consistent
* identifiers of an icon. For the purposes of storage additonal descriptor properties may
* be used, but the name and size are the only ones guarenteed to be passed for lookup purposes.
*/
export abstract class IconCache {
/**
* Finds and returns an icon based on it's name and size
*/
abstract get(name: string, size: string): object;
/**
* stores an icon descriptor to the cache
*/
abstract set(name: string, size: string, descriptor: object): void;
}
/**
* Custom error for when a name can't be found
*/
export class IconNameNotFoundError extends Error {
constructor(name: string) {
super(`Icon ${name} not found`);
}
}
/**
* Custom error for when a specific size can't be found
*/
export class IconSizeNotFoundError extends Error {
constructor(size: string, name: string) {
super("Size ${size} for ${name} not found");
}
}
/**
* Concrete implementation of `IconCache` as a simple in memory cache
*/
export class IconMemoryCache extends IconCache {
private iconMap = new Map<string, Map<string, object>>();
get(name: string, size: string) {
if (!this.iconMap.has(name)) {
throw new IconNameNotFoundError(name);
}
const sizeMap = this.iconMap.get(name);
if (!sizeMap.has(size)) {
throw new IconSizeNotFoundError(size, name);
}
return sizeMap.get(size);
}
set(name: string, size: string, descriptor: object) {
if (!this.iconMap.has(name)) {
this.iconMap.set(name, new Map());
}
const sizeMap = this.iconMap.get(name);
sizeMap.set(size, descriptor);
}
}
/**
* The icon service is a singleton service responsible for registering and retriving icons from `@carbon/icons`.
*
* It's important to register icons before use. It's reccommended to register your icons early, likely in your app.component.
*
* To allow for improved tree shaking _do not_ import all the icons from `@carbon/icons` and register them.
* Instead register only the icons in use by your application. If your application makes use of lazy loaded
* modules you may also lazy load the icons used in that module by registering them early on in that module.
*
* `ngOnInit` should be sufficiantly early to register icons.
*
* Example:
* ```
* import { Accessibility16 } from "@carbon/icons";
*
* // ...
*
* class MyComponent implements OnInit {
* constructor(protected iconService: IconService) {}
*
* // ...
*
* ngOnInit() {
* this.iconService.register(Accessibility16);
* }
*
* // ...
* }
* ```
*
* If needed it is possible to register an icon under a different name, via `registerAs`.
*/
@Injectable()
export class IconService {
private iconCache: IconCache = new IconMemoryCache();
/**
* Registers an array of icons based on the metadata provided by `@carbon/icons`
*/
public registerAll(descriptors: object[]) {
descriptors.forEach(icon => this.register(icon));
}
/**
* Registers an icon based on the metadata provided by `@carbon/icons`
*/
public register(descriptor: object) {
const { name } = descriptor as IconDescriptor;
this.registerAs(name, descriptor);
}
/**
* Registers an icon based on a uniqe name and metadata provided by `@carbon/icons`
*/
public registerAs(name: string, descriptor: object) {
const { size } = descriptor as IconDescriptor;
this.iconCache.set(name, size.toString(), descriptor);
}
/**
* Gets an icon, converts it to a string, and caches the result
*/
public get(name: string, size: string): IconDescriptor {
try {
const icon = this.iconCache.get(name, size.toString()) as IconDescriptor;
if (!icon.svg) {
icon.svg = toString(icon);
}
return icon;
} catch (e) {
throw e;
}
}
/**
* Configure various service settings (caching strategy ...)
*/
public configure(options: { cache: IconCache }) {
this.iconCache = options.cache;
}
}
</code></pre>
</div>
</div>
</div><div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
<!-- END CONTENT -->
</div>
</div>
<label class="dark-mode-switch">
<input type="checkbox">
<span class="slider">
<svg class="slider-icon" viewBox="0 0 24 24" fill="none" height="20" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" width="20" xmlns="http://www.w3.org/2000/svg">
<path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"></path>
</svg>
</span>
</label>
<script>
var COMPODOC_CURRENT_PAGE_DEPTH = 1;
var COMPODOC_CURRENT_PAGE_CONTEXT = 'class';
var COMPODOC_CURRENT_PAGE_URL = 'IconCache.html';
var MAX_SEARCH_RESULTS = 15;
</script>
<script>
$darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input');
checkToggle(darkModeState);
if ($darkModeToggleSwitchers.length > 0) {
for (var i = 0; i < $darkModeToggleSwitchers.length; i++) {
$darkModeToggleSwitchers[i].addEventListener('change', function (event) {
darkModeState = !darkModeState;
toggleDarkMode(darkModeState);
});
}
}
</script>
<script src="../js/libs/custom-elements.min.js"></script>
<script src="../js/libs/lit-html.js"></script>
<script src="../js/menu-wc.js" defer></script>
<script nomodule src="../js/menu-wc_es5.js" defer></script>
<script src="../js/libs/bootstrap-native.js"></script>
<script src="../js/libs/es6-shim.min.js"></script>
<script src="../js/libs/EventDispatcher.js"></script>
<script src="../js/libs/promise.min.js"></script>
<script src="../js/libs/zepto.min.js"></script>
<script src="../js/compodoc.js"></script>
<script src="../js/tabs.js"></script>
<script src="../js/menu.js"></script>
<script src="../js/libs/clipboard.min.js"></script>
<script src="../js/libs/prism.js"></script>
<script src="../js/sourceCode.js"></script>
<script src="../js/search/search.js"></script>
<script src="../js/search/lunr.min.js"></script>
<script src="../js/search/search-lunr.js"></script>
<script src="../js/search/search_index.js"></script>
<script src="../js/lazy-load-graphs.js"></script>
<footer class="carbon">
<dds-footer-container key="footer" disable-locale-button="true" size="micro" />
</footer>
<script
key="8"
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v1/latest/footer.min.js">
</script>
<!-- Storybook override -->
<script>
document.title = "Carbon Components Angular";
</script>
<script
src="//1.www.s81c.com/common/stats/ibm-common.js"
type="text/javascript"
async="async">
</script>
</body>
</html>