fLISTVIEW

Quick Data

General Description

The fLISTVIEW is a component with a lot of everything. It is a component which could be quite useful. This is the component that you see as your desktop - displaying icons with text. It's also the component that you see whenever you browse a directory - a set of icons with text, that can be viewed many different ways. You can add icons with captions to one of these listviews (or no icons, if you so wish), and then display these as icons, or icons with extra details in seperate columns, or just list the icons as small icons. There are many different things that you can do with this component.

To allow the use of icons, this class uses the fIMAGELIST class as well. However, if you don't want any icons at all, then you do not need to include this class. The fIMAGELIST class is automatically included when you include this class; if you don't want that to happen, then #define F_LISTVIEW_H_NO_IMAGELISTS before you include this class.

Before we get too much further, there is some terminology that you must be familiar with. The following is a screenshot from Windows Explorer, and I've added labels to show what each part is called. An understanding of this will be very useful as you read this document.

Another thing that will be useful to understand will be the different modes of a Listview, which is described by the image below.

This component is derived from _GUIBASE, and inherits the properties from that.

Primary Options

Secondary Options

Methods

Extended styles

Some styles for Listviews can not be set with primary or secondary options, and must be done manually via these functions.

To save stating the obvious over and over, if you pass TRUE for Set, it will set the style, and if you pass FALSE for Set, then it will unset the style.

Prototype	Description
void MakeFullRowSelect(bool Set);	This style is only relevant to the Report mode. If the user selects an item in report mode, and this style is set, then the whole row will get selected - not just the icon and the caption for that item.
void MakeHotTrack(bool Set);	This style makes the item's captions light up with an underline and will change the colour of the caption when the mouse comes over that item. Also, the mouse pointer will change to a hand - just like Internet Exploder.
void MakeColdTrack(bool Set);	This style forces all of the item's captions to be underlined by default, and when the mouse pointer moves over an item, its underlining will dissapear, and the mouse pointer will change into a hand.
void MakeOneClick(bool Set);	This style makes the item's captions just like hyperlinks in Internet Explorer - one click will be equivilent of two clicks, and the item will not only be selected, but 'executed'.
void MakeTwoClick(bool Set);	This style makes the Listview work in the usual two click style - one click to select the item, and another click to execute the item.
void MakeCheckBoxes(bool Set);	This style makes the Listview display checkboxes next to each item when the list is in Report mode. I suppose there is someway of returning their state?
void MakeFlatScrollbars(bool Set);	This style makes the Listview's scrollbars be of the flat scrollbar type, which seems to be pretty popular these days.
void MakeGridLines(bool Set);	This style makes the Listview display gridlines between each item and each column in Report mode.
void MakeHeaderDragAndDrop(bool Set);	This style allows the user to drag and drop the headers in Report mode, to arrange the columns as they wish. Don't worry about having to manage this; Windows does all the work for you - all you need to do is place the data in the Listview like you normally would.
void MakeSubItemImages(bool Set);	When in Report mode, each column's item is called a subitem. It is possible, after you set this style, to add an icon to that subitem as well, which could be rather handy.

And now we continue with the ordinary functions...

However, the functions have been broken up into subcategories, as there are many, many functions that make up this class.

Functions to add and edit items and subitems

Functions to manage columns in the Listview

Functions to set options for the Listview (and other functions that don't quite fit in elsewhere)

Functions to get data from items and to get information about the items, and about the Listview's display

Events

Please note that the events listed here are done in pairs; one as a property, and the other as a function. The property is assigned a function name, ie. Object.OnClick = &FunctionName, whilst the function is called to verify that an event has occured. Please see the chapter on event handling for information on how to use these correctly.

One more note: all of the events for the Listview are sent under the WM_NOTIFY message - so if you are going to manually intercept these messages, don't forget! Attempting to intecept these events from the WM_COMMAND message will result in an access violation.

Sample Code

The following snippet gives a basic idea of how to use this component.

//Create an instance of the Listview...
fLISTVIEW ListView;

//Create some associated fIMAGELISTS...
fIMAGELIST ImageListBig;
fIMAGELIST ImageListSmall;

//In this example, we are going to load a DLL, and display
//all the icon in it in this Listview. Also, we shall create some
//columns to display extra information, should you wish to
//use report mode. If you have even the remote possibility of using
//report mode, then just add the columns anyway.

//Firstly, we create the window...
ListView.CreateWin(Window.GetHandle(), "Any caption here", 123456, lvNormal, AvWind | lvIconView | lvIconAlignAuto);

//Set some options for the ListView...
ListView.MakeFullRowSelect(TRUE);
ListView.MakeHeaderDragAndDrop(TRUE);

//Add some columns to the ListView...
ListView.AddColumn(0, "Icon", 200, 0);
ListView.AddColumn(1, "Icon Index", 100, 1);
//For Add column: AddColumn(Column Index, "Caption", Width, Sub Item ID)

//Now we set up the ImageLists and add all the icons from SHELL32.DLL
ImageListBig.Create(32,32, bdDeviceDependant, 1,1);
ImageListSmall.Create(16,16, bdDeviceDependant, 1,1);

//Find the number of icons...
int TempNo = ImageListBig.GetNumberIcons("SHELL32.DLL");

//We are just assuming that there are icons in the file. If the above
//function returns 0 (Zero), then there are no icons, and we should
//not try to get icons from this file.

//Now add the icons to the ImageLists...
int Temper;
for (Temper = 0; Temper < TempNo; Temper++)
    {
    ImageListBig.LoadIconFromDLL("SHELL32.DLL", Temper);
    ImageListSmall.LoadIconFromDLL("SHELL32.DLL", Temper);
    }

//Apply the imagelists...
ListView.SetImageLists(&ImageListBig, &ImageListSmall);

//Add the actual items and also the extra column information...
bstring Numbering;   //This is used to convert numbers to a string.
Temper = (TempNo-1); //Start from the end
int NewItem;         //Used to make sure we add the subitem to the correct item.
for ( ; Temper > -1; Temper--) //Start at the end, move forwards.
    {
    Numbering.tostr("Icon number %d", Temper); //Convert to a string.
    NewItem = ListView.AddItem(Numbering.data, Temper); //Add the item.
    //The above line also remembers the new items index, which you must
    //do if you have a sorting ListView.
    Numbering.tostr("%d", Temper); //Convert to a string
    ListView.AddSubItem(NewItem, 1, Numbering.data); //Add SubItem.
    //For adding a subitem: AddSubItem(Item to add to, SubItemID, Caption)
    }

//Now here's an unrelated example: how to determine what items
//are selected, if multiple selections are allowed. Here's how.
//Basically you just cycle through each item, and test each one.
//Set up a for loop...
for (int Cycle = 0; Cycle < ListView.GetNumberitems(); Cycle++)
    {
    //Now test the item...
    if (ListView.IsSelected(Cycle))
       {
       //Ok, this item is selected.
       } else {
       //Nope, this item is not selected.
       }
    }