The Big Red Toolbox

MGCEListView

An enhanced ListView Control

November 4, 1999

© NSB Corporation. All rights reserved.
MGCEListView - ListView Object for Windows CE
Written by Mark Gamber, October 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 listview 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 its use as an object under Windows CE, but it's still a Windows ListView common control underneath it all.

Installation

Connect your Windows CE device to your desktop using ActiveSync. On the desktop, run the program MGCEListview.exe. Follow the instructions on the screen to complete the installation.

Object Creation

AddObject "MGCEListView.ListView", "LView", 10, 10, 400, 160

Samples

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
SetFocus Gives the control input focus.

LView.SetFocus
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. This method returns the postion the item was inserted: useful when using a sorted listview.

i=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

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 its 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
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
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" )
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
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 its 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 a number if you only want a single item selected at any given time. A 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/CODE>
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
Version Gets the version number of the control as an integer.

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

Change Log

10/5/99: Fixed Hide, Show

10/10/99: Added ColumnCount, FontBold, FontName, FontSize, RowsPerPage, TopIndex, EndHeaderDrag and HeaderDrag.

10/28/99: ItemImage and ItemValue now can be set, and PostClick event added.

11/4/99: InsertItem now returns the position where inserted