View source for Cell Icon Set Library

'''Download Library:''' [[media:Cell Icon Set Library.ana|Cell_Icon_Set_Library.ana]]

<center>[[Image:CellIconSetExample1.png|800px]]</center>


The above screenshot shows [[CellIcon|cell icons in table cells]]. These icons can be used to convey information in various ways, but normally requires you to provide the icon images and to encode the logic to decide which icon to display.

This library provides pre-curated icon sets, so that you can select an icon set and let the library do the rest -- i.e., provide the icon images, use icons that go together as a set, impose a consistent color scheme, and decide which icon to show.  This is exposed through the two main functions:
* [[CellIconSetByLevel|CellIconSetByLevel( )]] : Select which icon based on an integer 1..n
* [[CellIconSetByValue|CellIconSetByValue( )]] : Partition an array of numbers into levels for you.

These two functions provide different options for how it should map your values to specific icons in each cell.   With either function, you can select from various icon sets and can also vary the color scheme among 5 pre-defined consistent color schemes. 

The library also exposes functions to draw all the icons (returning images), giving you total control over size, colors and percent progress (for indicator icons). These can be useful if you want icons with different colors, size or properties than those in the pre-curated icon sets.

== How to use ==

You use the two main functions of the library, [[CellIconSetByLevel]] and [[CellIconSetByValue]], in place of using the built-in [[CellIcon]] function. These are used from within the [[Computed cell formats|Computed Cell Formats attribute]].

=== The main functions ===
==== <div id="CellIconSetByLevel">CellIconSetByLevel( iconSetName, level'', numLevels, side, colorScheme'')</div>====
====<div id="CellIconSetByValue">CellIconSetByValue( iconSetName, level'', numLevels, side, colorScheme, thresholds'')====

where the parameters are:
* «iconSetName»: one of
** <code>'Arrows'</code>
** <code>'Triangles'</code>
** <code>'Circles'</code>
** <code>'Shapes'</code>
** <code>'Symbols'</code>
** <code>'Symbols in circles'</code>
** <code>'Indicator flags'</code>
** <code>'Star'</code>
** <code>'Bars'</code>
** <code>'Pie'</code>
** <code>'Grid'</code>
** <code>'Gauge'</code>
* «level»: a number in 1..«numLevels» that selects which icon in the icon set to show. This is usually an array that varies with the indexes of the result table.
* «numLevels»: (Optional) The number of levels in the cell icon set that you want to use.  Should be a number between 2 and 5. 
* «side»: Which side of the table cell should the icon appear on?  (see [[CellIcon]]) Possible values are
** <code>'Left'</code>
** <code>'Right'</code> (default)
** <code>'IconOnly'</code>
** <code>'ImageOnly'</code>:  Causes the function to return an image of the icon instead of acting as a replacement for [[CellIcon]]().
* «colorScheme»: (optional) One of
** <code>'Earthy'</code>
** <code>'Bright'</code>
** <code>'Pastel'</code>
** <code>'Neon'</code>
** <code>'Grayscale'</code>
* «thresholds»: (optional) Specify fixed values where it should transition from one icon to the next. When you use this, you don't have to specify «numLevels». These must be non-decreasing.  This is a repeated parameter, so you shouldn't pass a list, but rather just list the thresholds.


When using [[CellIconSetByValue]], you will usually specify either «numLevels» or «thresholds», but not both. If you do specify both, they need to be consistent (i.e., «numLevels» should be one greater than the number of thresholds listed). There is one special case where this isn't required -- when «numLevels» is 3 and a single threshold is specified.

=== Decide what information to depict ===
What do you wish to depict with the cell icons?  The functions expect this to be a numeric value.  It can be value that displays in the cell (Self), or a function of that value, or it can be a different variable that varies along the same indexes as your result.  The value depicted can be an expression, but since you'll be using this in a [[Computed cell format attribute]], it should be something that evaluates fairly quickly, since it may re-evaluate when the table redraws. If not, place the expression in its own variable so its result will be cached.

=== Select the icon set ===
When using either function, you'll select a cell icon set by specifying a ''set name'' and optionally the number of levels and color scheme.  The available set names and color schemes are shown here:
<center>[[image:CellIconSetAvailableSets.png|600px]]</center>

For example, if you select the icon set name <code>'Arrows'</code> with 4 levels using the <code>'Neon'</code> color scheme, the four icons [[image:FourNeonArrowIcons.png]] will be used, such as in this example:
:[[image:FourNeonArrowIconsInCells.png]]

=== Which icons to use ===

Each icon set has between 2 and 5 separate icons. Each cell will contain (at most) one of these icons, which will visually depict a value or other information at that cell coordinate. The icon might reflect the value that appears in that cell (such as whether it is large or small), or it might depict a different piece of information.  For example, in a result table showing a closing price on a given day, the icon might depict whether prices increased or decreased on that day, which is information that would be taken from a different variable.

There are three different ways you can have it map from your values to icon choice.
==== By Level ====
Your first option is to provide values that vary from 1 to the number of levels in your icon set.  A value of 1 would use the first icon in the set, 2 the second icon, etc.  This is a good option for discrete information such as "Pass", "Warn" and "Fail", for example. 

To use this method, use the [[CellIconSetByLevel]] function.

Example:
Index Status_idx := ["Pass","Warn","Fail"]

In the [[Computed cell format attribute]], the following would appear to depict <code>Status</code>:
:<code>[[CellIconSetByLevel]]( 'Symbols',  @[Status_idx=status], numLevels:3 )</code>

==== By Value / Rank ====

If you want to depict continuous information, [[CellIconSetByValue]] can partition the set of values that occur into levels that contain roughly the same number of cells.  All you have to do is specify «numLevels» and the function does the rest. For example, if you set <code>numLevels:5</code> to use an icon set with 5 levels, the largest 20% of the values will use the first icon, and the smallest 20% of the values will use the fifth icon. 

==== Using Thresholds ====
When you have important values that should serve as transition points from one icon to the next, use [[CellIconSetByValue]] with the «thresholds» parameter. The thresholds are the values where it transitions to the next icon. 

Example:
:<code>[[CellIconSetByValue]]( 'Arrows', change, thresholds: -10, 10)</code>
This could use an up arrow for values greater than 10, a right-arrow for values between -10 and 10, and a down arrow for values under -10.
:<code>[[CellIconSetByValue]]( 'Arrows', change, thresholds: -10, 0,0, 10)</code>
This would use 5 arrows -- North, NorthEast, East, SouthEast and South, where East would be used only value values exactly equal to 0.

Generally when using the «thresholds» parameter, you omit the «numLevels» parameter. If you also specify «numLevels», it needs to be consistent -- i.e., one greater than the number of «threshold» values. When using N threshold values, the icon set corresponding to N+1 levels much exist.  There is one special case where «numLevels» does not have to be one larger than the number of «thresholds», which is when numLevels=3 and only one threshold is specified, such as
:<code>[[CellIconSetByValue]]( 'Triangles', Trend, numLevels:3, thresholds:0 )</code>
In this case, the sole threshold is used only for exact matches to the threshold value, which is the same as specifying the same threshold twice.  More generally, when you want an icon to be used only for exact matches to a transition threshold, list the threshold value twice in a row, e.g.,
:<code>[[CellIconSetByValue]]( 'Arrows', Self, thresholds:-1,-1,1,1)</code>
which would use the first (up arrow) icon for values less that -1, the second icon for values exactly equal to 1, the third icon for values between -1 and 1, the fourth icon for values exactly equal to 1, and the fifth icon for values greater than 1.

=== Using the functions ===
When you use [[CellIconSetByLevel]] or [[CellIconSetByValue]], you place these functions in the [[Computed cell formats]] attribute, not in the definition.  The usage is the same as for the [[CellIcon]] function -- i.e., you don't wrap the result in [[CellIcon]].  If the icon is the only computed cell format, then the examples usages that appear on this page would be the full expression for the [[Computed cell formats]] attribute.

Within the library itself is a sub-module titled "Usage examples" that contains usage examples.  When viewing these, be sure to view the Computed cell formats attribute in the [[Object Window]]. 

==== Returning images ====
Although the normal use of [[CellIconSetByLevel]] and [[CellIconSetByValue]] is as a replacement for [[CellIcon]](), there is also a mode that causes the functions to just return the icon images. This is invoked by passing <code>side:'imageOnly'</code>.  

To compare how this differs from the other usage, note that the following are equivalent (and would appear in the [[Computed cell format attribute]]):
:<code>[[CellIconSetByLevel]]( 'Bars', level, 5, side:'Left' )</code>
:<code>[[CellIcon]]([[CellIconSetByLevel]]( 'Bars', level, 5, side:'imageOnly' ), 'Left')</code>

== Icon Drawing Functions ==
All icons in the pre-curated icon sets are generated from functions that draw the shapes using arbitrary fill, edge and background colors, arbitrary rotations where applicable, and arbitrary percent filled for indicator icons, and arbitrary size.  The pre-curated sets are packaged at a fixed size with only a few combinations of colors designed to provide a few good, general purpose options.  But if you want icons at different sizes or with your own colors, you can generate these using the icon drawing functions without having to resort to a paint program to create them.

Each drawing function returns an image. 

<center>[[image:CISL_IconDrawing_fns.png]]</center>

The list of drawing functions are as follows (the CISL_ prefix stands for Cell Icon Sets Library and is present to avoid name collisions).
*CISL_Arrow_icon( fillColor, edgeColor, angle, width, height )
*CISL_Round_icon( fillColor, edgeColor, width, height, char, charColor )
*CISL_Triangle_icon( fillColor, edgeColor, angle, width, height, char )
*CISL_Diamond_icon( fillColor, edgeColor,width, height )
*CISL_Dash_icon( fillColor, edgeColor, width, height )
*CISL_Flag_indicator( fillColor, edgeColor, width, height )
*CISL_Star_rating( fillColor, edgeColor, pctFilled, width, height )
*CISL_Circle_rating( fillColor, edgeColor, pctFilled, width, height )
*CISL_Grid_rating( fillColor, edgeColor, bgColor, pctFilled, width, height )
*CISL_Bars_rating( fillColor, edgeColor, bgColor, pctFilled, width, height )
*CISL_Gauge_rating( fillColor, edgeColor, pct, width, height )
*CISL_Checkmark_icon( fillColor, edgeColor, width, height )
*CISL_ExclamationIcon( fillColor, edgeColor, width, height )
*CISL_X_icon( fillColor, edgeColor, width, height )

Examples:
:<code>CISL_Gauge_rating( 'Blue', 'Green',  15%, 50, 30 ) </code> &rarr; [[image:gauge50x30.png]]
:<code>CISL_Round_icon( 'Beige', 'Brown', 30, 30, Chr(0x2665), 'Red')</code> &rarr; [[image:circleWithHeart.png]]

Note: The cached icon sets use a size of 16. 

== See Also ==
* [[CellIcon]]
* [[Computed cell formats]]
* [[Sparklines]]
* [https://lumina.com/community/sub-forum/icon-sets-in-result-table-is-it-possible/ Icon sets in result table?  Is it possible?] - Forum post.