Site Navigation

User Guide

Reference

Packages

 

DESCRIPTION

[TBD]

METHODS

Common methods apply to most windows, controls and resources.

new

new(PARENT, %OPTIONS)

Creates a new ListView object; can also be called as PARENT->AddListView(%OPTIONS).

Class specific %OPTIONS are:

  -align => left, top
  -imagelist => IMAGELIST
  -report => 0/1
  -list => 0/1
  -singlesel => 0/1
  -showselalways => 0/1
  -sortascending => 0/1
  -sortdescending => 0/1
  -nolabelwrap => 0/1
  -autoarrange => 0/1
  -editlabel => 0/1
  -noscroll => 0/1
  -alignleft => 0/1
  -ownerdrawfixed => 0/1
  -nocolumnheader => 0/1
  -nosortheader => 0/1
  -gridlines => 0/1
  -subitemimages => 0/1
  -checkboxes => 0/1
  -hottrack => 0/1
  -reordercolumns => 0/1
  -fullrowselect => 0/1
  -oneclickactivate => 0/1
  -twoclickactivate => 0/1
  -flatsb => 0/1
  -regional => 0/1
  -infotip => 0/1
  -underlinehot => 0/1
  -underlinecold => 0/1
  -multiworkareas => 0/1

See also the common options.

Add

Add(ITEM, ITEM .. ITEM)

Inserts one or more items in the control; each item must be passed as an hash reference. See InsertItem() for a list of the available key/values of these hashes.

ApproximateViewRect

ApproximateViewRect(cx,cy,icount=-1)

Calculates the approximate width and height required to display a given number of items.

Arrange

Arrange([FLAG])

LVA_ALIGNLEFT = Aligns items along the left edge of the window. LVA_ALIGNTOP = Aligns items along the top edge of the window. LVA_DEFAULT = Aligns items according to the ListView's current alignment styles (the default value). LVA_SNAPTOGRID = Snaps all icons to the nearest grid position.

ChangeItem

ChangeItem(%OPTIONS)

See SetItem()

Clear

Clear()

See DeleteAllItems()

ColumnWidth

ColumnWidth(COLUMN, [WIDTH])

Gets or sets the width of the specified COLUMN; WIDTH can be the desired width in pixels or one of the following special values:

  -1 automatically size the column
  -2 automatically size the column to fit the header text

Count

Count()

See GetItemCount()

CreateDragImage

CreateDragImage(index, xcor, ycor)

Creates a transparent version of an item image. The xcor and yxcor are the initial location of the upper-left corner of the image.

DeleteAllItems

DeleteAllItems()

Deletes all items from the ListView.

DeleteColumn

DeleteColumn(INDEX)

Removes a column from a ListView.

DeleteItem

DeleteItem(INDEX)

Removes the zero-based INDEX item from the ListView.

Deselect

Deselect(INDEX)

Deselects the zero-based INDEX item from the ListView. Use Deselect(-1) to deselect all items. Focus is unchanged.

DeselectAll

DeselectAll()

Alternate method to deselect all items from the ListView. Focus is unchanged.

EditLabel

EditLabel(INDEX)

Begins in-place editing of the specified list view item's text.

EnsureVisible

EnsureVisible(INDEX, [FLAG])

Ensures that a list view item is either entirely or partially visible, scrolling the ListView if necessary.

FindItem

FindItem(FROM, %OPTIONS)

Searches for a list view item with the specified characteristics.

%OPTIONS :

 -string => STRING
    Item must exactly match the string.
 -prefix => 0/1
    Find item text begins with the string.
 -wrap   => 0/1
    Continues the search at the beginning if no match is found.

GetBkColor

GetBkColor()

Retrieves the background color of a ListView.

GetBkImage

GetBkImage()

Retrieves the background image in a ListView.

GetCallbackMask

GetCallbackMask()

Retrieves the callback mask for a ListView.

GetCheckState

GetCheckState(INDEX)

Determines if an item in a ListView is selected.

GetColumn

GetColumn(INDEX)

Retrieves the attributes of a ListView's column.

GetColumnOrderArray

GetColumnOrderArray()

Retrieves the current left-to-right order of columns in a ListView.

GetColumnWidth

GetColumnWidth(INDEX)

Retrieves the width of a column in report or list view.

GetCountPerPage

GetCountPerPage()

See VisibleCount()

GetEditControl

GetEditControl()

Retrieves the handle to the edit control being used to edit a list view item's text.

GetExtendedListViewStyle

GetExtendedListViewStyle()

Retrieves the extended styles that are currently in use for a given ListView.

GetHeader

GetHeader()

Retrieves the handle to the header control used by a ListView.

GetHotCursor

GetHotCursor()

Retrieves the cursor used when the pointer is over an item while hot tracking is enabled.

GetHotItem

GetHotItem()

Retrieves the index of the hot item.

GetHoverTime

GetHoverTime()

Retrieves the amount of time that the mouse cursor must hover over an item before it is selected.

GetImageList

GetImageList([TYPE=LVSIL_NORMAL])

Retrieves the handle to an image list used for drawing list view items. Type :

  LVSIL_NORMAL Image list with large icons.
  LVSIL_SMALL  Image list with small icons.
  LVSIL_STATE  Image list with state images.

GetISearchString

GetISearchString(STRING)

Retrieves the incremental search string of a ListView.

GetItem

GetItem(INDEX, [SUBINDEX])

Returns an associative array of information about the given zero-based INDEX item.

Return Hash :

    -image
    -state
    -text

Optionally, a SUBINDEX (one-based index) can be given, to get the text for the specified column.

GetItemCount

GetItemCount()

Returns the number of items in the ListView.

GetItemPosition

GetItemPosition(index)

Retrieves the position of a list view item, in listview co-ordinates. See GetOrigin() to convert to client co-ordinates.

GetItemRect

GetItemRect(index,[code=LVIR_BOUNDS])

Retrieves the bounding rectangle for all or part of an item in the current view, in client co-ordinates.

GetItemSpacing

GetItemSpacing([flag=FALSE])

Determines the spacing between items in a ListView. Flag is true to return the item spacing for the small icon view, and false to return the icon spacing for large icon view.

GetItemState

GetItemState(index,mask)

Determines the spacing between items in a ListView. Index is the listview item for which to retrieve information. mask is a combination of the fllowing flags:

 LVIS_CUT            The item is marked for a cut-and-paste operation.
 LVIS_DROPHILITED    The item is highlighted as a drag-and-drop target.
 LVIS_FOCUSED        The item has the focus, so it is surrounded by a standard
                     focus rectangle. Although more than one item may be selected,
                     only one item can have the focus.
 LVIS_SELECTED       The item is selected. The appearance of a selected item depends
                     on whether it has the focus and also on the system colors used for selection.
 LVIS_OVERLAYMASK    Use this mask to retrieve the item's overlay image index.
 LVIS_STATEIMAGEMASK Use this mask to retrieve the item's state image index.

The only valid its in the response are those bits that correspond to bits set in mask.

GetItemText

GetItemText(index,[subitem=0])

Retrieves the text of a ListView item or subitem

GetNextItem

GetNextItem(index,[mask=LVNI_ALL])

Searches for a list view item that has the specified properties and bears the specified relationship to a specified item.

GetNumberOfWorkAreas

GetNumberOfWorkAreas()

Retrieves the number of working areas in a ListView.

GetOrigin

GetOrigin()

Retrieves the current view origin for a ListView. Use the values returned to convert between listview co-ordinates and client co-ordinates.

GetSelectedCount

GetSelectedCount()

Determines the number of selected items in a ListView.

GetSelectionMark

GetSelectionMark()

Retrieves the selection mark from a ListView.

GetStringWidth

GetStringWidth(STRING)

Determines the width of a specified string using the specified ListView's current font.

GetSubItemRect

GetSubItemRect(iItem, iSubitem,[code=LVIR_BOUNDS])

Retrieves the bounding rectangle for all or part of an item in the current view, in client co-oridinates.

GetTextBkColor

GetTextBkColor()

Retrieves the text background color of a ListView.

GetTextColor

GetTextColor()

Retrieves the text color of a ListView.

GetToolTips

GetToolTips()

Retrieves the tooltip control that the ListView uses to display tooltips.

GetTopIndex

GetTopIndex()

Retrieves the index of the topmost visible item when in list or report view.

GetUnicodeFormat

GetUnicodeFormat()

Retrieves the UNICODE character format flag for the control.

GetViewRect

GetViewRect()

Retrieves the bounding rectangle of all items in the ListView.

HitTest

HitTest(X, Y)

Determine the index of the listview item at X,Y. X,Y are in client co-ordinates. In list context, returns a 2 member list, the first member containing the item index of the item under the tested position (or -1 of no such item), and the second member containing flags giving information about the result of the test:

 LVHT_ABOVE           The position is above the control's client area.
 LVHT_BELOW           The position is below the control's client area.
 LVHT_NOWHERE         The position is inside the list-view control's client window,
                      but it is not over a list item.
 LVHT_ONITEMICON      The position is over a list-view item's icon.
 LVHT_ONITEMLABEL     The position is over a list-view item's text.
 LVHT_ONITEMSTATEICON The position is over the state image of a list-view item.
 LVHT_TOLEFT          The position is to the left of the list-view control's client area.
 LVHT_TORIGHT         The position is to the right of the list-view control's client area.

InsertColumn

InsertColumn(%OPTIONS)

Inserts a new column in a ListView.

%OPTIONS :

 -text => Column text
 -align => [right,left,center]
 -width => width
 -index | -item => column index
 -subitem => subitem number
 -image => image index
 -bitmaponright => 0/1
 -order => Column order

InsertItem

InsertItem(%OPTIONS)

Inserts a new item in the control.

%OPTIONS :

 -image => NUMBER
   index of an image from the associated ImageList
 -indent => NUMBER
   how much the item must be indented; one unit is the width of an item image,
   so 2 is twice the width of the image, and so on.
 -item => NUMBER
   zero-based index for the new item; the default is to add the item at the end of the list.
 -selected => 0/1, default 0
 -text => STRING
   the text for the item.  If STRING an array refereence, then the array contains the text for
   item at position 0, and all other array members are treated as text for subitems.

Item

Item(INDEX)

Return an Win32::GUI::ListView::Item.

ItemCheck

ItemCheck(INDEX,[FLAG])

Set or Get item checked state.

ItemInfo

ItemInfo(INDEX, [SUBINDEX])

See GetItem()

ItemPosition

ItemPosition(INDEX, [X, Y])

Get or set the position of an item in icon or small icon view. X,Y are in listview co-ordinates.

MoveItem

MoveItem(INDEX, X, Y)

See SetItemPosition()

RedrawItems

RedrawItems(first,last)

Forces a ListView to redraw a range of items.

Scroll

Scroll(first,last)

Scrolls the content of a ListView.

Select

Select(INDEX)

Selects and sets focus to the zero-based INDEX item from the ListView. Use Select(-1) to select all items and set focus to item 0.

SelectAll

SelectAll()

Alternate method to select all items. Sets focus to the zero-based INDEX item from the ListView.

SelectCount

SelectCount()

See GetSelectedCount()

SelectedItems

SelectedItems()

Returns an array containing the zero-based indexes of selected items, or an empty list if no items are selected.

SetBkColor

SetBkColor(color)

Sets the background color of a ListView.

SetBkImage

SetBkImage(%OPTIONS)

Sets the background image in a ListView.

%OPTIONS :

 -url => STRING
   URL of the background image.
 -tiled => 0/1
   The background image will be tiled to fill the entire background.
 -xOffsetPercent => NUMBER
   Percentage of the control's client area that the image should be offset horizontally.
 -yOffsetPercent => NUMBER
   Percentage of the control's client area that the image should be offset vertically.

SetCallbackMask

SetCallbackMask(MASK)

Changes the callback mask for a ListView.

SetColumn

SetColumn(COLUMN, %OPTIONS)

Change column option in a ListView.

%OPTIONS : See InsertColumn()

SetColumnOrderArray

SetColumnOrderArray(...)

Sets the left-to-right order of columns in a ListView .

SetColumnWidth

SetColumnWidth(COLUMN, [WIDTH])

Sets the width of the specified COLUMN; WIDTH can be the desired width in pixels or one of the following special values:

  -1 automatically size the column
  -2 automatically size the column to fit the header text

SetExtendedListViewStyle

SetExtendedListViewStyle(EXSTYLE)

Sets extended styles for ListViews.

SetExtendedListViewStyleEx

SetExtendedListViewStyleEx(MASK, EXSTYLE)

Sets extended styles for ListView using the style mask

SetHotCursor

SetHotCursor(CURSOR)

Sets the HCURSOR that the ListView uses when the pointer is over an item while hot tracking is enabled.

SetHotItem

SetHotItem(index)

Sets the hot item in a ListView.

SetHoverTime

SetHoverTime(TIME)

Sets the amount of time that the mouse cursor must hover over an item before it is selected.

SetIconSpacing

SetIconSpacing(X,Y)

Sets the spacing between icons in ListView set to the LVS_ICON style.

SetImageList

SetImageList(IMAGELIST, [TYPE=LVSIL_NORMAL])

Assigns an image list to a ListView.

Type of image list. This parameter can be one of the following values:

 LVSIL_NORMAL (0) Image list with large icons.
 LVSIL_SMALL  (1) Image list with small icons.
 LVSIL_STATE  (2) Image list with state images.

SetItem

SetItem(%OPTIONS)

Change item options.

%OPTIONS : See InsertItem().

SetItemCount

SetItemCount(COUNT)

Sets the amount of time that the mouse cursor must hover over an item before it is selected.

SetItemCountEx

SetItemCountEx(COUNT,FLAG)

Sets the virtual number of items in a virtual ListView.

SetItemPosition

SetItemPosition(INDEX, X, Y)

Moves an item to a specified position in a ListView (in icon or small icon view). X,Y are in listview co-ordinates.

SetItemState

SetItemState(INDEX,STATE,MASK)

Changes the state of an item in a ListView.

SetItemText

SetItemText(INDEX,TEXT,[SUBITEM=0])

Changes the text of an item in a ListView.

SetSelectionMark

SetSelectionMark(index)

Sets the selection mark in a ListView.

SetTextBkColor

SetTextBkColor(COLOR)

Sets the background color of text in a ListView.

SetTextColor

SetTextColor(COLOR)

Sets the text color of a ListView.

SetToolTips

SetToolTips(TOOLTIP)

Sets the tooltip control that the ListView will use to display tooltips.

SetUnicodeFormat

SetUnicodeFormat(FLAG)

Sets the UNICODE character format flag for the control.

SubItemHitTest

SubItemHitTest(X, Y)

Test to find which sub-item is at the position X,Y. X,Y are inclient-co-ordinates. Returns a 3 memeber list, giving the item number, subitem number and flags related to the test. the item number is -1 if no item or subitem is under X,Y. flags are a combination of:

 LVHT_ABOVE           The position is above the control's client area.
 LVHT_BELOW           The position is below the control's client area.
 LVHT_NOWHERE         The position is inside the list-view control's client window,
                      but it is not over a list item.
 LVHT_ONITEMICON      The position is over a list-view item's icon.
 LVHT_ONITEMLABEL     The position is over a list-view item's text.
 LVHT_ONITEMSTATEICON The position is over the state image of a list-view item.
 LVHT_TOLEFT          The position is to the left of the list-view control's client area.
 LVHT_TORIGHT         The position is to the right of the list-view control's client area.

TextBkColor

TextBkColor([COLOR])

Gets or sets the background color for the text in the ListView.

TextColor

TextColor([COLOR])

Gets or sets the text color for the ListView.

Update

Update(INDEX)

Updates a list view item.

View

View([MODE])

[TBD]

VisibleCount

VisibleCount()

Calculates the number of items that can fit vertically in the visible area of a ListView when in list or report view.

EVENTS

Common events apply to most windows and controls.

BeginDrag

BeginDrag(ITEM)

Notifies a list-view control that a drag-and-drop operation involving the left mouse button is being initiated. Passes the item being dragged.

BeginLabelEdit

BeginLabelEdit(ITEM)

Sent when the user is about to edit the specified item of the ListView The event should return 0 to prevent the action, 1 to allow it.

For a ListView to receive this event, -editlabels need to be set to true.

ColumnClick

ColumnClick(ITEM)

Sent when the user clicks on a column header in the ListView; ITEM specifies the one-based index of the selected column.

EndLabelEdit

EndLabelEdit(ITEM,TEXT)

Sent when the user has finished editing a label in the ListView control. You have explicitly set the text of the item to reflect the new changes. If the user cancels the edit, the text is undef.

ItemChanged

ItemChanged(ITEM, NEWSTATE, OLDSTATE, CHANGED)

Sent for any change of state of an item in the ListView. ITEM specifies the zero-based index of the selected item. NEWSTATE specifies the new item state (LVIS_). OLDSTATE specifies the old item state (LVIS_). CHANGED specifies the item attributes that have changed (LVIF_).

ItemChanging

ItemChanging(ITEM, NEWSTATE, OLDSTATE, CHANGED)

Sent when the item is about to change state. The event should return 0 to prevent the action, 1 to allow it. ITEM specifies the zero-based index of the selected item. NEWSTATE specifies the new item state (LVIS_). OLDSTATE specifies the old item state (LVIS_). CHANGED specifies the item attributes that have changed (LVIF_).

ItemCheck

ItemCheck(ITEM)

Sent when the user changes the checkbox of an item in the ListView; ITEM specifies the zero-based index of the selected item.

ItemClick

ItemClick(ITEM)

Sent when the user selects an item in the ListView; ITEM specifies the zero-based index of the selected item.

KeyDown

KeyDown(KEY)

Sent when the user presses a key while the ListView control has focus; KEY is the ASCII code of the key being pressed.

VERSION

Documentation for Win32::GUI v1.06 created 13 Feb 2008

This document is autogenerated by the build process. Edits made here will be lost. Edit docs/per_package.tpl instead.

SUPPORT

Homepage: http://perl-win32-gui.sourceforge.net/.

For further support join the users mailing list(perl-win32-gui-users@lists.sourceforge.net) from the website at http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users. There is a searchable list archive at http://sourceforge.net/mail/.

COPYRIGHT and LICENCE

Copyright (c) 1997..2008 Aldo Calpini. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.