NSBImageList ActiveX

This control is part of NS BASIC Controls package. Please see its documentation to get full information about this package.

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.

3. 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.
LoadResource	n = object.LoadResource(           [file],           [resID],           [type],           [key])	Loads a resource from a DLL or EXE module. Depending on the resource type and size one or more images are created in the image list. file - the path to the module from which to load a resource. If empty the executable of the application is assumed. resID - integer or string ID of the resource to load (Most often integer ID-s are used). You need to know the resource ID and specify it. type - resource type: 0 - bitmap, 1 - icon, 2 - cursor. If a bitmap is specified multiple images may be created in the list as many as the bitmap size permits (each image is Width wide and Height high). If the width of the bitmap is less than the value of the Width property no images are loaded. key - if specified this key name is assigned to the new image(s) created.  See also the remarks section.
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.

The LoadResource method enables you to consume applicable resources from any EXE/DLL. Note that the corresponding EXE/DLL must be for the same platform on which the program is running.  I.e. you cannot get a DLL from a desktop and put it on a Pocket PC because you like to use a few icons in its resources.

What is the resource ID? This is a number or a name (but cannot be both) assigned to the resource (icon, bitmap, etc.) by the developer of the corresponding DLL/EXE.  I.e. the EXE/DLL module contains a directory of resources and the Resource ID is like a file name or number in it. Most developers prefer numeric ID-s in order to cut some size from their EXE/DLL. If you want to learn the resource ID-s of the icons, bitmaps, cursors in an EXE/DLL from another developer (or a system one) you can use any available resource browser/editor at hand. For example MS Visual Studio can open EXE/DLL files and show the resources in them.

Some NS Basic developers practice usage of resource DLL. These are DLL with no code in them, packing only useful resources such as icons, bitmaps and others. This can be done with the appropriate MS Visual Studio version for the platform and does not need any programming. To create such a DLL create a DLL project, create a new <something>.rc file and add it to the project. Then go to the linker settings and in the project options edit box add /NOENTRY command line option. Then compile the DLL. Using the resource editor you can add/import various resources into the project and then use them. Check the generated resource.h file to learn the numeric ID-s or specify names for the resources you add in "" (quotes) to force textual identifiers.

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.