NSBImageList ActiveX

Part of NS BASIC Controls.

1. Overview

The NSBImageList control is not a visual object. It is a storage for small images you use with other controls. Thus the NSBImageList should be considered as helper which allows you manipulate sets of images as whole and assign them to the controls that need them. 

As a rule the controls that use NSBImageList create implicitly as much instances of the object as they need. Then the implicitly created NSBImageList-s are exposed through their properties and you can use them directly typically without need to ever create the NSBImageList on your own. For example the NSListView control exposes 3 such image lists through its Icons, SmallIcons and ColumnHeaderIcons properties (see the NS BASIC Controls FAQ for a quick illustration).

2. Architecture 

The NSBImageList control has the following structure:

Actually it is a typical collection with elements - NSBListImage objects. The elements can be addressed by index:
Set li = objImageList(2)
By name (if names are set to some of the elements - i.e. this is optional):
Set li = objImageList("MyImage")
Or enumerated:
For li In objImageList
  ' Do something with each li (NSBListImage)
Next

The indices are 1-based, the names are optional.

Typically the applications rarely need to work with the individual images in the list except for loading and sometimes removing them. Thus usually the image list is filled with images and the control that uses the list is instructed to show one image or another with certain visual elements in it. This is done by specifying index or key name of an image from the list. For example in the NSListView control you can assign index or a key name to the Icon property of the ListItem object thus instructing the control to show the corresponding image from the image list with that item. However, the application in no way uses the individual image from the list directly - it only tells which one to use.

2. Members reference

NSBImageList object

A collection of NSBListImage objects. It provides access to the general image list features, means to load images and members for the list manipulation.

Name	Syntax	Description
Clear	object.Clear	Removes all the images from the list.
LoadBitmap	n = object.LoadBitmap(file [,key])	Loads one or more images from the specified bitmap file.  The arguments are: file - full path name to a bitmap file key - (optional) string which is assigned as key name to all the loaded images. returns: the index of the first of the loaded images  The bitmap is expected to contain 1 or more images each Width pixels wide and Height pixels high.
Remove	object.Remove index_or_key	Removes image from the list by index or key name. If key name is specified and there are more than one image with the same key name only the first is removed.
Count	n = object.Count	Returns the number of images in the image list.
BackColor	object.BackColor = clr clr = object.BackColor	Specifies the background color used by the list when the images are drawn on the screen. Most often this property is controlled by the control using the list and you do not need to take care about it (see the remarks).
MaskColor	object.MaskColor = clr clr = object.MaskColor	Puts/gets the mask color which is used to for masking the loaded images. This property has effect only when images are loaded from a bitmap (e.g. using the LoadBitmap method). If UseMaskColor is also True the loaded images are masked with this color and all the pixels on them with that color are considered transparent (see the remarks).
UseMaskColor	object.UseMaskColor = b b = object.UseMaskColor	Enables/Disables the usage of the MaskColor.
Height	object.Height = h h = object.Height	Puts/gets the height of the images in the list in pixels.
Width	object.Width = w w = object.Width	Puts/gets the width of the images in the list in pixels.
Tag	object.Tag = v Set object.Tag = o v = object.Tag Set o = object.Tag	The application can save in this property any data and then access it when needed.

Remarks

The image list supports masked and unmasked images. The mask is used to point out which pixels of the image are transparent. For the bitmaps do not have such feature the mask must be specified somehow. The MaskColor serves that purpose. When you create images for the application you must select a color that will mark the pixels that will appear transparent. Then by specifying that color in the MaskColor Property and setting the UseMaskColor to True you instruct the control to automatically create transparency masks for the images loaded from bitmaps (e.g. using LoadBitmap). 

FYI: How the transparency is achieved? In most cases there is no need of true transparency and when the controls (such as NSListView) need to draw images from the image list they set its BackColor to the color of the background over which they are going to draw. Then when individual images are drawn the transparent pixels are drawn with this color. This method is not true transparency but is faster.

NSBListImage object

Syntax:

Set img = NSBImageList.Item(index)
Set img = NSBImageList(index)
or
Set img = NSBImageList.Item("key")
Set img = NSBImageList("key")
or
For Each img In NSBImageList
   ' make use of img
Next

Members reference

Name	Syntax	Description
Index	v = object.Index	Numeric - returns the index of the NSBListImage object in the image list (the NSBImageList object to which it belongs).
Key	v = object.Key object.Key = string	String. Sets/gets the key name of the object under which it can be accessed through the NSBImageList that contains it.
Tag	v = object.Tag object.Tag = v Set object.Tag = o	A storage for application specific data.