MGCEListView - ListView Object for Windows CE, Version 1.02
Written by Mark Gamber, September 1999

NS Basic is (c) NS Basic Corporation
Windows CE is (c) Microsoft Corporation

MGCEListView provides a ListView control to programs which use controls
of this type, such as NS Basic. Note that this object is NOT plug-in
compatible with the Microsoft ListView object for Windows CE. Like
the Listview control itself, MGCEListView is a somewhat complex object
which requires some understanding of the basic listview control.

A Listview control is somewhere between a listbox and a grid. It is
a two-dimensional control, like a grid, but doesn't allow the user to
change anything anywhere at any time like a grid. In addition, a list-
-view allows varying views, such as large icons, small icons and
listings, as is demonstrated by simply changing the view of files in
Explorer which uses a listview control. In effect, there is only one
column in a listview control. Therefore, rather than referring to items
in a listview by row and column, as you would with a grid, items are
referred to as "items" and "subitems". An "item" is data appearing in
the leftmost column of a listview when placed in report (or "detailed")
mode and is the column which contains data a user may directly edit.
Columns within the same row are referred to as "subitems" and contain
data the user cannot directly change. Going back to Explorer, the "item"
column is that which displays the file name. Other columns, such as
"Size", "Type" and "Attributes", are all "subitems". "Attributes", for
example, would be subitem four in Explorer (The desktop version of
Explorer!). The explanation above is for the purpose of understanding
the following object documentation.

In addition to text data, a Listview control can make use of images.
This is done through with "image lists" which are nothing more than
just that: Lists of images. MGCEListView maintains two image lists, one
for small images (16x16 pixels) and a second for large images (32x32
pixels). You may use one, both or neither of these image lists as your
project demands. An image list simply maintains the images for you
in memory in a numbered list. When adding bitmap files to an image
list, the first image added is image one and the count increases by
one for every image you add to the list. If you add ten images to an
image list and you want to use the last image you added, you want to
use image ten and so on.

It's important to understand that the MGCEListView is based on the Windows
Listview common control. For a more indepth look at what a listview
control is and how it works, refer to Microsoft documentation on the
control. MGCEListView enhances the control slightly for the purpose of it's
use as an object under Windows CE, but it's still a Windows ListView
common control underneath it all.

**************************************************************************
**************************************************************************

*** Adding a MGCEListView object (This is easy!):
AddObject "MGCEListView.ListView", "LView", 10, 10, 400, 160

**************************************************************************

Methods:

*** AddContextItem
	Adds an item to the context menu. If the item begins with a dash
(-), a separator is added to the menu.

	LView.AddContextItem "Item &1"



*** AddLgImage
	AddLgImage adds an image to the "large image list". The image
must be a standard Windows bitmap file. 16 colors is recommended.

	LView.AddLgImage "\lgimg1.bmp"



*** AddSmImage
	AddSmImage adds an image to the "small image list". The image
must be a standard Windows bitmap file. 16 colors is recommended.

	LView.AddSmImage "\smimg1.bmp"



*** Arrange
	Arrange items in Icon View using. Use 0 for default alignment,
one to align along the left edge of the control, two to align along the
top of the control and five to align along a default grid.

	lvAlignDefault = 0
	lvAlignLeft = 1
	lvAlignTop = 2
	lvAlignGrid = 5
	LView.Arrange lvAlignDefault



*** Clear
	Clear removes all data from the control.

	LView.Clear



*** ClearContext
	Removes all items from the context menu.

	LView.ContextClear



*** DeleteColumn
	DeleteColumn removes a column, the leftmost being column one,
from the control. Columns are displayed when the control is in
"Report View". The column parameter is optional.

	LView.DeleteColumn 1



*** DeleteItem
	DeleteItem removes a row of data from the control, the topmost
row being row one. All columns in the row are removed. The row parameter
is optional.

	LView.DeleteItem iRow


*** EnsureVisible
	Use this method to be certain that an item is visible.

	LView.EnsureVisible 1


*** Hide
	Hide the listview control.

	LView.Hide


*** InsertColumn
	InsertColumn adds a new column in the specified position, starting
with one. The column text, width and image are also specified with
InsertColumn. Note: The first image in an image list is number one. If you
do not want an image in the column header, use zero as the image number.
The column number, width and image parameters are optional and default to
zero.

	LView.InsertColumn iColumn, "Column 1", iWidth, iImage



*** InsertItem
	InsertItem adds a data item to the control at the specified position,
the first position being one. The item's text, image and a user defined value
are also specified with InsertItem. If you do not want an image displayed
with the text, use zero as the imagenum parameter. The Row, Image and Value
parameters are optional and default to zero. Version 1.04 updates the method
by returning the actual insertion point of a new item. This is useful when
sorting is enabled and subitems are added after a new item is inserted. The
row, image and tagvalue are all optional.

	iItem = LView.InsertItem( iRow, "Item 1", iImage, iTagValue )



*** RemoveContextItem
	Removes an item from the context menu based on it's index, starting
with one.

	LView.RemoveContextItem 1



*** RemoveLgImage
	Remove an image from the Large Image List.

	LView.RemoveLgImage 3



*** RemoveSmImage
	Remove an image from the Small Image List.

	LView.RemoveSmImage iImage



*** SetItem
        SetItem does double duty in that it modifies data anywhere in the
listview as well as adding subitems to an existing row of data. The row
and column parameters, both starting at one, specify the position in the
control. "text" is data to display in the listview and the imagenum refers
to the number of an image within an image list to display with the text.
Use zero if you do not want an image. The Row, Column, Image and Value
parameters are optional and default to zero.

	LView.SetItem iRow, iCol, "data", iImage, iTagValue



*** SetColumn
	SetColumn modifies an existing column header which is displayed
when the listview is in "Report View" mode.

	LView.SetColumn iColNum, "Column", iWidth, iImage


*** SetFocus
	Gives the control input focus.

	LView.SetFocus


*** Show
	Display the listview control.

	LView.Show


**************************************************************************

Properties:

*** AllowEvent
	Certain events may be allowed or cancelled depending on this
property's setting from within the event handler. For these events, set
AllowEvent to TRUE to allow the event to continue or FALSE to cancel the
event and discard any changes that come from the event. This is a write-
-only property and the default value is based on the value of the
AllowEventAsDefault property.

	LView.AllowEvent = FALSE


*** AllowEventAsDefault
	This property is used as the default value of events which are not
specifically handled or do not set the AllowEvent property. The default is
TRUE which allows all events to continue by default.

	LView.AllowEventAsDefault = FALSE
	iCurrentDef = LView.AllowEventAsDefault


*** BackColor
	BackColor sets the background color for parts of the listview control
containing data.

	clr = LView.BackColor
	LView.BackColor = ( 255 * 65536 )



*** Border
	Enables and disables the border. Use zero for no border, any other
number to display a border.

	LView.Border = TRUE
	b = LView.Border



*** Checkboxes
	Enables and disables checkboxes in the first column of the control.
Use zero to disable checkboxes, any other number to display checkboxes.

	LView.Checkboxes = TRUE
	c = LView.Checkboxes



*** Checked
	Read-only. A value of zero indicates that a row's checkbox is
unchecked. Any other value indicates that the checkbox is checked. This
property cannot be set, only read and is undetermined if checkboxes are
not enabled at the time.

	iChecked = LView.Checked( 4 )



*** ColumnCount
	The read-only ColumnCount property returns the number of columns
currently displayed within a listview control.

	iCount = LView.ColumnCount



*** ColumnOrder
	An array of integer values is used to set and retrieve the display
order of columns displayed when in "Report Mode". See the program code
below for an example of setting and retriving the column order.

	colorder = Array( 3, 2, 1 )
	LView.ColumnOrder = colorder
	cols = LView.ColumnOrder
	for i = 1 to UBound( cols )
		print cols( i )
	next



*** ColumnImage
	Set and retrieve the image number current in use by an item or
subitem.

	img = LView.ColumnImage
	LView.ColumnImage = 1



*** ColumnText
	Set and retrieve the displayed text of an item or subitem.

	s = LView.ColumnText( 1, 1 )
	LView.ColumnText( 1, 2 ) = "Subitem 1"



*** ColumnWidth
	Set and retrieve the pixel width of any individual column.

	i = LView.ColumnWidth( 1 )
	LView.ColumnWidth( 1 ) = 120



*** Count
	The number of items (subitems are not included) may be retrieved
by reading this property. Setting the property forces the listview control
to allocate memory to contain that number of items rather than it's
allocating memory for every item added as it is added to the control.

	print "There are " & CStr( LView.Count ) & " items"



*** EditItems
	When set to zero, the user may not directly edit data in the first
column of the control. Set to any other number, the user may edit the data
by clicking on a selected item.

	LView.EditItems = 0
	iEdit = LView.EditItems


*** FindText iStart, "text"
	Read-only, FindText locates an item containing the specified text,
returning the row in which it was found. Set iStart to one to begin at
the first row. The search is not exact. If you specify "Fin" and one item
contains "Find this" and another, greater in number contains "Fin", it will
find "Find this" first.

	iItem = LView.FindText( 1, "test" )


*** FontBold
	TRUE (non-zero) selects a bold font, FALSE (zero) selects a normal
font.

	LView.FontBold = TRUE
	b = LView.FontBold


*** FontName
	Specifies the name of a font to apply to the listview control.

	LView.FontName = "Arial"
	s = LView.FontName


*** FontSize
	Specify the size of a font to apply to the listview control.

	LView.FontSize = 12
	iFontSize = LView.FontSize


*** FullRowSelect
	Set to a non-zero number to select an entire row of data if any
column in that row is selected. Set to zero, only the leftmost column
is selected regardless of what is selected in that row by the user.

	LView.FullRowSelect = 1
	iSel = LView.FullRowSelect



*** GridLines
	Set to a non-zero number to display grid lines between each
row and column in the control. Set to zero to eliminate these lines.

	LView.GridLines = FALSE;
	i = LView.GridLines


*** hWnd
	Retrieve the window handle of the displayed object.

	lWindow = LView.hWnd



*** ImageLists
	MGCEListView maintains two images lists, one for small images and
another for large images. In order to use the image lists, you need to
add images, then apply the image lists to the listview, which is the
purpose of the ImageLists property. Set this property to zero if you
do not use the image lists at all. Otherwise, one will apply the small
image list to the control, two will apply the large image list to the
control and four will apply small images to the column header. You may
use any combination of these. For example, to use only small images in
the listview and it's header, you would use 1 + 4 or five.

	lvSmallImages = 1
	lvLargeImages = 2
	lvHeaderImages = 4
	LView.ImageLists = lvSmallImages + lvLargeImages + lvHeaderImages
	i = LView.ImageLists



*** ItemImage
	Set and retrieve the image number currently in use by an item
or subitem.

	LView.ItemImage( 1, 1 ) = 2
	iImage = LView.ItemImage( 1, 2 ) = 1



*** ItemText
	Set and retrieve the text displayed by an item or subitem.

	s = LView.ItemText( 2, 3 )
	LView.ItemText( 3, 3 ) = "Los Alamos"



*** ItemValue
	Set and retrieve a 32 bit value associated with an item or subitem.
This value is user defined and has no meaning to the control itself.

	i = LView.ItemValue( 1, 3 )
	LView.ItemValue( 3, 3 ) = 0



*** LgImageCount
	Read-only, this retrieves the number of images in the large
image list.

	iCount = LView.LgImageList



*** RowsPerPage
	A read-only property which returns the number of rows of data that
will completely fit vertically within the control without scrolling when the
control is in list or report views. When in another view, the value returned
is the number of items currently contained by the control.

	iVRows = LView.RowsPerPage



*** Select
	Set and retrieve the selected state of a row. Non-zero indicates
that an item is selected or to be selected. Zero indicates that an item
is not selected or to be deselected.

	iSel = LView.Select( 12 )
	LView.Select( iRow ) = TRUE



*** SelectedCount
	Read-only value which returns the number of selected items in
the listview control.

	ISelCount = LView.SelectedCount



*** Selection
	Set Selection to zero if you only want a single item selected at
any given time. A non-zero setting allows multiple items to be selected.

	iSelType = LView.Selection
	LView.Selection = TRUE



*** SelectionDisplay
	When set to zero, the display of a selected item is lost when the
listview control loses focus. The selection itself is not lost and is again
displayed when the control regains focus. Set to a non-zero number, the
control displays selected items as selected regardless of focus.

	i = LView.SelectionDisplay
	LView.SelectionDisplay = FALSE



*** SmImageCount
	Read-only, this returns the number of items in the small image list.

	iCount = LView.SmImageCount



*** Sort
	Set to zero if you don't care about sorting. Set to one, sorting is
done is ascending order. Set to -1, sorting is done in descending order.

	LView.Sort = -1
	iSort = LView.Sort


*** Style
	Set and retrieve the Style property which determines how the edge
of the control is displayed. This is different from the Border property.
Styles include:
	0: No edge
	1: "Sunken" edge
	2: "Raised" edge

	LView.Style = 2
	iStyle = LView.Style


*** SubItemImages
	When set to zero, subitems (columns other than the leftmost) do not
display images even if an image is specified for data displayed in those
columns. Setting this property to a non-zero number enables image display
in those columns.

	iUsesImages = LView.SubItemImages
	LView.SubItemImages = TRUE


*** Tabstop
	Set this property to TRUE (non-zero) to include the control in the
tab order. FALSE removes it from the tab order and the default is TRUE.

	LView.Tabstop = TRUE
	iIsTabOrdered = LView.Tabstop


*** TextColor
	Set and retrieve the color used when displaying text.

	clr = LView.TextColor
	LView.TextColor = 255



*** TopIndex
	A read-only property which returns the index of the first visible item
when the control is in list or report views.

	iItem = LView.TopIndex



*** View
	Set and retrieve the current view. Use zero for "Large Icon view",
one for "Report View", two for "Small Icon view" and three for "List View".

	lvIcon = 0
	lvReport = 1
	lvSmallIcon = 2
	lvList = 3
	LView.View = lvReport
	iView = LView.View


**************************************************************************

Events:

*** ColumnClick
	When the user clicks upon a column, this event is called and passes
the column number that was clicked upon, staring with one for the leftmost
column.

	sub LView_ColumnClick( lColumn )
		print "Column " & CStr( lColumn ) & " was clicked"
	end sub



*** ContextMenu
	The ContextMenu event is called when an item is selected from the
listview context menu. The listview item over which the menu was displayed
(may be zero for no item) and the text of the selected menu item is passed
to the event handler.

	sub LView_ContextMenu( item, text )
		MsgBox text & " was selected from the menu"
	end sub



*** EndEdit
	When the EditItems property is set, the user may directly change
data in the first column of the listview control. When that data is
changed, this event occurs which passes the row and column that was
changed. In addition, new data, if any, is also passed to the event
handler. The text can be empty ("") if the user cancelled the change or
entered nothing into the edit box. By default, changes are allowed to
be reflected by the control itself but setting AllowEvent to FALSE from
within the handler or setting AllowEventAsDefault to FALSE will prevent
changes from showing in the control.

	sub LView_EndEdit( row, column, textstring )
		print "The item at " & CStr( row ) & "," & CStr( column )
			& " wants to be " & textstring
	end sub



*** EndHeaderDrag
	Columns may be resized by the user dragging a border edge. When
the user finishes dragging the edge and resizing the column, this event
is fired, passing along the identifier of the resized column.

	sub LView_EndHeaderDrag( item )
		MsgBox "Column " & CStr( item ) & " has been resized"
	end sub



*** HeaderDrag
	This event is called as a column header is being resized by the
user dragging a column edge. The event receives the column identifier.

	sub LView_HeaderDrag( item )
		print "Column " & CStr( item ) & " is being dragged"
	end sub



*** ItemActivate
	Double-clicking an item in the listview control causes this event.
The row and column that was double-clicked is passed to the event.

	sub LView_ItemActivate( row, column )
		print "The item at " & CStr( row ) & "," & CStr( column )
			& " was double-clicked"
	end sub



*** ItemClick
	Clicking upon an item in the listview control triggers this event
which passes the row and column of the item that was clicked upon.

	sub LView_ItemClick( row, column )
		print "The item at " & CStr( row ) & "," & CStr( column )
			& " was clicked"
	end sub


*** Keypress
	Pressing a key while the object has input focus triggers this
event, passing the value of the key pressed along with it.

	sub LView_Keypress( lKey )
		print Chr( lKey ) & " was pressed"
		LView.SetFocus
	end sub


*** PostClick
	If checkboxes are enabled and a checkbox value is changed, the
value is not actually updated until after the ItemClick event. The
PostClick event is slightly delayed, allowing accurate polling of a
checkbox.

	sub LView_PostClick( item, subitem )
		iVal = LView.Checked( item )
	end sub


*** StartDragSelect
	Multiple items in a listview control may be selected by moving the
stylus to draw a "box" around the items. The start of this process triggers
this event which may be cancelled by setting AllowEvent to FALSE from within
the event handler.

	sub LView_StartDragSelect
		LView.AllowEvent = FALSE
	end sub


*** StartEdit
	When the listview control enters "edit mode", this event is triggered
and the item about to enter edit mode is passed to the event. The event may
be cancelled by setting AllowEvent to FALSE from within the handler. Only
items may use edit mode, not subitems.

	sub LView_StartEdit( item )
		LView.AllowEvent = TRUE
	end sub

**************************************************************************

