ListView ActiveX Control

"Microsoft ListView Control 6.0 (SP4)"
"MSComctlLib.ListViewCtrl.2"
"{BDD1F04B-858B-11D1-B16A-00C0F0283628}"

Description:

The ListView ActiveX Control is one of the most often user ActiveX Controls in MAXScript rollouts. It is very flexible and customizable and is thus discussed in detail in this chapter. It can be used to create lists and spreadsheet-like user interface controls.

Constructor:

activeXControl lv "MSComctlLib.ListViewCtrl"

Properties:

ListItems

.ListItems : IListItems

This property provides access to the ListItems. ListItems represent the rows in the Listview and have the following properties and methods:

.ListItems Properties:

.ListItems.Count : integer

Get/Set the number of ListItems in the ListView control.

.ListItems[IndexList] : IListItem, read-only

Returns the Indexed ListItem. The index is 1-based.

.ListItems Methods:

.ListItems.Add Index:undefined Key:undefined Text:undefined Icon:undefined SmallIcon:undefined

Adds a new ListItem to the ListView control.

.ListItems.Clear()

Clears the ListItems.
All ListItems will be removed from the ListView.

.ListItems.Remove Index:undefined

Removes the indexed ListItem. The index is 1-based.

ColumnHeaders

.ColumnHeaders : IColumnHeaders

This property provides access to the column headers of the ListView.

.ColumnHeaders Properties:

.Count : integer

Get/Set the number of Column Headers in the ListView control.

.Item[Index:undefined] : IColumnHeader, read-only

Get the indexed Column Header from the ListView control.
The index is 1-based!

See ColumnHeader Properties and Methods for a list of properties of single Column Headers.

.ColumnHeaders Methods:

.Clear()

Clears the ColumnHeaders.
All Column Headers will be removed from the ListView.

.Remove Index:undefined

Removes the indexed Column Header.
The index is 1-based.

._NewEnum()

Not accessible through MAXScript, return type is not supported.

.Add Index:undefined Key:undefined Text:undefined Width:undefined Alignment:undefined Icon:undefined

Adds a new Column to the ListView control.

.HideColumnHeaders : Boolean

This property lets you enable and disable the column headers. When set to true, the column headers will be hidden. When set to false, the column headers will be displayed. Note that column headers are only available when the .View property is set to #lvwReport.

.AllowColumnReorder : Boolean

When set to true, the user can drag the columns to define their order. When set to false (default), the columns order is locked and cannot be changed interactively.

ListView Layout:

.View : ListViewConstants( #lvwIcon | #lvwSmallIcon | #lvwList | #lvwReport )

Get/Set the view type of the ListView control.

.Appearance : AppearanceConstants( #ccFlat | #cc3D )

Get/Set the appearance of the ListView control. #cc3D is default.

ListView_Appearance_ccFlat.gif ListView_Appearance_cc3D.gif

.BorderStyle : BorderStyleConstants( #ccNone | #ccFixedSingle )

Controls the border style when .Appearance is set to #ccFlat. When set to #ccFixedSingle, a single pixel border will be drawn around the ListView.

ListView_Appearance_ccFlat.gif ListView_Appearance_ccFlat_ccFixedSingle.gif

.Arrange : ListArrangeConstants( #lvwNone | #lvwAutoLeft | #lvwAutoTop )

Controls the arrangement of the ListView control. Default is #lvwNone.

.DropHighlight : IListItem

If a ListItem is assigned to this property, the ListItem will be displayed as highlighted (appearing to be selected, but without having the selected state flag set). The highlight will not be affected by the selection highlight, leaving the specified ListItem highlighted until the DropHighlight is set to undefined again.

In the screenshot below, the ListItem representing Teapot01 was assigned to DropHighlight, while the ListItem representing Box01 was selected with the mouse.

ListView_DropHighlight.gif

.LabelEdit : ListLabelEditConstants( #lvwAutomatic | #lvwManual )

Controls the editing of the label (this is the text in the first column of a ListItem). Default is #lvwAutomatic.

When set to #lvwAutomatic, the user can click to select the item, then click again at the label location to open the text field to type in custom text.

When set to #lvwManual, the label editing can only be initiated by the developer by using the .StartLabelEdit() method.

WARNING!

The 3ds Max keyboard shortcuts (accelerators) have to be disabled to be able to type in the label text field! See ActiveX - Disable 3ds Max keyboard accelerators for details!

ListView_LabelEdit_Automatic.gif

.LabelWrap : Boolean

Controls the label wrapping.

.Checkboxes : Boolean

When set to true, checkboxes will be displayed in the first column for each ListItem. When set to false (default), only the ListItem label will be displayed.

ListView_Checkboxes_True.gif ListView_Checkboxes_False.gif

.Enabled : Boolean

When set to true (default), the ListItems can be selected, labels can be edited, checkboxes can be checked, column widths can be adjusted etc. When set to false, the ListItems will be "frozen" and cannot be changed in any way.

.ForeColor : OLE_COLOR

Controls the foreground (text) color used to draw the ListView.

Note

OLE_COLOR values used by ActiveX Controls are BGR and not RGB!

.BackColor : OLE_COLOR

Controls the background color used to draw the ListView.

Note

OLE_COLOR values used by ActiveX Controls are BGR and not RGB!

The following screenshots show the default white background (.BackColor property not set), .BackColor = color 225 215 210, .BackColor = color 215 225 210 and .BackColor = color 210 215 225

ListView_BG_White.gif ListView_BG_Blue.gif

ListView_BG_Green.gif ListView_BG_Red.gif

.GridLines : Boolean

When set to false (default), no grid lines will be drawn. When set to true, lines will be drawn to delimit the rows and columns:

ListView_BG_White_NoGrid.gif ListView_BG_White.gif

.FlatScrollBar : Boolean

When set to false (default), the scrollbar will be displayed. When set to true, no scrollbar will be drawn. You can still scroll down by moving the selection using the arrow keys, but cannot scroll horizontally.

.Picture : IPictureDisp

Lets you assign a picture to the background. See loadPicture for details on passing pictures as IPuctureDisp values to ActiveX controls.

In the example below, a yellow-red gradient with the size 500x200 pixels was created in Photoshop, saved as 24 bit BMP to disk and passed to the .Picture property using the line

lv.picture = loadPicture "c:/3dsmax6/images/activex_gradient.bmp"

ListView_BG_Picture.gif

.PictureAlignment : ListPictureAlignmentConstants( #lvwTopLeft | #lvwTopRight | #lvwBottomLeft | #lvwBottomRight | #lvwCenter | #lvwTile )

Controls the alignment of the picture assigned to the .Picture property.

.TextBackground : ListTextBackgroundConstants( #lvwTransparent | #lvwOpaque )

Controls the appearance of the text background. When set to #lvwOpaque, the above example will appear as

ListView_BG_Picture_OpaqueText.gif

.Font : IFontDisp

Returns an MSDisplatch value controlling the font used. Cannot be set by MAXScript.

Selection

.SelectedItem : IListItem, read-only, default:undefined

Returns the selected item.

.FullRowSelect : boolean

When set to true, selecting an item or sub-item will select the complete row. When set to false, only the ListItem (first column) will be selected.

.MultiSelect : Boolean

When set to true, the user can select multiple ListItems simultaneously. When set to false (default), only one ListItem at a time can be selected.

.HideSelection : Boolean

When set to true, the selection will not be displayed.When set to false, the selection will be displayed.

.HotTracking : Boolean

When set to true, the ListItems will be highlighted as the mouse moves over them. When set to false (default), there will be no effect when the mouse is moving over ListItems.

.HoverSelection : Boolean

When set to true, the ListItems will be selected automatically when the mouse hovers over them. When set to false (default), ListItems will only be selected if the user clicks with the mouse.

Mouse Access

.MouseIcon : IPictureDisp

Returns the mouse icon as IPictureDisp value. Cannot be set by MAXScript.

.MousePointer : MousePointerConstants( #ccDefault | #ccArrow | #ccCross | #ccIBeam | #ccIcon | #ccSize | #ccSizeNESW | #ccSizeNS | #ccSizeNWSE | #ccSizeEW | #ccUpArrow | #ccHourglass | #ccNoDrop | #ccArrowHourglass | #ccArrowQuestion | #ccSizeAll | #ccCustom )

Get/Set the mouse pointer type when over the ListView Control. The script developer could use the mouse events described further on this page to change the mouse pointer depending on the underlying content or the allowed actions...

Sorting

.Sorted : Boolean

When set to false (default), the ListItems will be displayed in the order they have been added to the ListView.ListItems array.

When set to true, the ListItems will be sorted alphabetically. By default, the sorting will be ascending based on the text in the first column

.SortOrder : ListSortOrderConstants( #lvwAscending | #lvwDescending )

When .Sort is set to true, this property controls the direction of sorting.

The following screenshots show the same objects displayed Unsorted, Sorted in Ascending and Descending order:

ListView_Unsorted.gif ListView_SortAscending.gif ListView_SortDescending.gif

.SortKey : integer

Cannot be set by MAXScript.

Icons

The following properties lets you assign an ImageList ActiveX Control to provide images to be used as icons by the ListView Control.

Note that icons are only visible when the .View property is set to #lvwIcon resp. #lvwSmallIcon

.Icons : IVBDataObject

The property lets you assign icons to the ListView Control. The IVBDataObject containing the images to be used as icons is provided by an ImageList ActiveX Control.

.SmallIcons : IVBDataObject, read-only, default:undefined

The property lets you assign small icons to the ListView Control. The IVBDataObject containing the images to be used as icons is provided by an ImageList ActiveX Control.

.ColumnHeaderIcons : IVBDataObject, read-only, default:undefined

The property lets you assign icons to the column headers of the ListView Control. The IVBDataObject containing the images to be used as icons is provided by an ImageList ActiveX Control.

Drag and Drop

.OLEDragMode : OLEDragConstants( #ccOLEDragManual | #ccOLEDragAutomatic )

Controls the OLE Drag mode.

.OLEDropMode : OLEDropConstants( #ccOLEDropNone | #ccOLEDropManual )

Controls the OLE Drop mode.

OLE Windows Messaging

.hWnd : OLE_HANDLE

This is the ActiveX handle needed to send Windows Messages to the ActiveX Control. See Sending Windows Message for details.

Methods:

.FindItem sz:string Where:undefined Index:undefined fPartial:undefined

 

.GetFirstVisible()

 

.HitTest x:float y:float

 

.StartLabelEdit()

 

.OLEDrag()

 

.Refresh()

Events:

on <control_name> BeforeLabelEdit Cancel:integer do ( ... )

Called before the Label Editing starts.

on <control_name> AfterLabelEdit Cancel:integer NewString:string do ( ... )

Called after the Label Editing ends.

on <control_name> ColumnClick ColumnHeader:ColumnHeader do ( ... )

Called when the user clicked a Column Header. The ColumnHeader argument will contain the ColumnHeader that has been clicked. The ColumnHeader has its own properties including index, aliagnment controls etc. See ColumnHeader Properties and Methods for details.

on <control_name> ItemClick Item:ListItem do ( ... )

Called when the user clicked a ListItem. The Item argument will contain the 0-based index of the row that has been clicked.

Keyboard and Mouse Click Events

on <control_name> KeyDown KeyCode:integer Shift:integer do ( ... )

Called when the user pressed a key. The KeyCode argument will contain the integer code of the key that has been pressed, the Shift argument will contain an integer whose bits represent the pressed state of the Shift, Control and Alt keys - bit 1 represents Shift, bit 2 represents Control, bit 3 represents Alt.

0 - No modifier keys pressed

1 - Left or Right Shift key pressed

2 - Left or Right Control key pressed

3 - Control + Shift keys pressed simultaneously

4 - Left or Right Alt key pressed

6 - Control + Alt keys pressed simultaneously

7 - Control, Alt and Shift keys pressed simultaneously

An example of the MAXScript syntax is:

on lv_objects keyDown theKeyCode theShiftState do

(

format "Key Code is %, Shift State is %\n" theKeyCode theShiftState

)

--where lv_objects is the name of the ActiveX ListView,

--theKeyCode and theShiftState are user-defined variable names.

 

on <control_name> KeyUp KeyCode:integer Shift:integer do ( ... )

Called when the user releases a key. The KeyCode argument will contain the integer code of the key that has been released, the Shift argument will contain an integer whose bits represent the pressed state of the Shift, Control and Alt keys - see above.

on <control_name> KeyPress KeyAscii:integer do ( ... )

Called when the user pressed a key. The KeyAscii argument will contain the ASCII integer code of the key that has been pressed. For example, pressing Space Bar will return 32, pressing Shift+A will return 65 etc.

on <control_name> MouseDown Button:integer Shift:integer x:OLE_XPOS_PIXELS y:OLE_YPOS_PIXELS do ( ... )

Called when the user clicked the ListView with the mouse.

The Button argument will contain an integer whose bits will correspond to the mouse buttons: bit 1 represents Left Mouse Button, bit 2 represents Right Mouse Button, bit 3 represents Middle Mouse Button / Wheel.

1 - Left Mouse Button pressed.

2 - Right Mouse Button pressed.

4 - Middle Mouse Button / Wheel pressed.

Note

Pressing two or three mouse buttons simultaneously will NOT add the values but generate separate events for each button!

The Shift argument will contain the state of the Shift, Control and Alt keys as described earlier on this page.

The x and y arguments will contain the location of the click in ListView pixel coordinates (NOT Twips!), where 0,0 is the upper left corner of the ListView Control.

For example

rollout test "Test"

(

activeXControl lv "MSComctlLib.ListViewCtrl" height:100 width:100

on lv MouseDown Button Shift x y do

format "Button: %, Shift: %, xy: %,%\n" Button Shift x y

)

createDialog test

 

 

on <control_name> MouseMove Button:integer Shift:integer x:OLE_XPOS_PIXELS y:OLE_YPOS_PIXELS do ( ... )

Called when the user moves the mouse inside the ListView control.

The Button argument will contain an integer whose bits will correspond to the mouse buttons: bit 1 represents Left Mouse Button, bit 2 represents Right Mouse Button, bit 3 represents Middle Mouse Button / Wheel.

1 - Left Mouse Button pressed.

2 - Right Mouse Button pressed.

4 - Middle Mouse Button / Wheel pressed.

Note

Pressing two or three mouse buttons simultaneously will NOT add the values but generate separate events for each button!

The Shift argument will contain the state of the Shift, Control and Alt keys as described earlier on this page.

The x and y arguments will contain the location of the click in ListView pixel coordinates (NOT Twips!), where 0,0 is the upper left corner of the ListView Control.

For example

--This script will print the mouse values

--while you move the mouse inside the ListView control

rollout test "Test"

(

activeXControl lv "MSComctlLib.ListViewCtrl" height:100 width:100

on lv MouseMove Button Shift x y do

format "Button: %, Shift: %, xy: %,%\n" Button Shift x y

)

createDialog test

 

 

on <control_name> MouseUp Button:integer Shift:integer x:OLE_XPOS_PIXELS y:OLE_YPOS_PIXELS do ( ... )

Called when the user released the mouse over the ListView control.

The Button argument will contain an integer whose bits will correspond to the mouse buttons: bit 1 represents Left Mouse Button, bit 2 represents Right Mouse Button, bit 3 represents Middle Mouse Button / Wheel.

1 - Left Mouse Button pressed.

2 - Right Mouse Button pressed.

4 - Middle Mouse Button / Wheel pressed.

Note

Pressing two or three mouse buttons simultaneously will NOT add the values but generate separate events for each button!

The Shift argument will contain the state of the Shift, Control and Alt keys as described earlier on this page.

The x and y arguments will contain the location of the click in ListView pixel coordinates (NOT Twips!), where 0,0 is the upper left corner of the ListView Control.

For example

rollout test "Test"

(

activeXControl lv "MSComctlLib.ListViewCtrl" height:100 width:100

on lv MouseUp Button Shift x y do

format "Button: %, Shift: %, xy: %,%\n" Button Shift x y

)

createDialog test

 

 

on <control_name> Click do ( ... )

Called when the user clicked inside the ListView control. This event does not return specific ListItems, but it could be used to query the selection state or other properties of all ListItems. It is a general notification that the user clicked the ListView, the actual actions performed by the event are up to the script developer.

on <control_name> DblClick do ( ... )

Called when the user double-clicked inside the ListView control.

on <control_name> ItemCheck Item:ListItem do ( ... )

Called when the user changed the state of a ListItem's checkbox (if available because of property .checkboxes = true).

The Item argument will contain ListItem whose checkbox has been changed. You can then access the new state by accessing the .checked property of the item. You can also access any other ListItem property.

OLE Drag and Drop Events

on <control_name> OLEStartDrag &Data:DataObject &AllowedEffects:integer do ( ... )

Called when the user started dragging from the ListView control.

on <control_name> OLEGiveFeedback &Effect:integer &DefaultCursors:boolean do ( ... )

Called when the user started dragging from the ListView control.

on <control_name> OLESetData &Data:DataObject &DataFormat:integer do ( ... )

 

on <control_name> OLECompleteDrag &Effect:integer do ( ... )

 

on <control_name> OLEDragOver &Data:DataObject &Effect:integer &Button:integer &Shift:integer &x:float &y:float &State:integer do ( ... )

 

on <control_name> OLEDragDrop &Data:DataObject &Effect:integer &Button:integer &Shift:integer &x:float &y:float do ( ... )

 

ListItem Properties and Methods

A ListItem is created by using the .ListItems.Add() method and can be accessed using 1-based indexed access as described above. Every ListItem has the following properties and methods:

ListItem Properties:

.Text : string

Get/Set the Text of the ListItem.

.Ghosted : Boolean

Get/Set the Ghosted state of the ListItem.

.Height : float

Returns the Height of the ListItem in Twips. Cannot be set by MAXScript.

.Icon : undefined

Get/Set the Icon of the ListItem. The icon is a 1-based index into the .icons array which in turn is managed by an ImageList ActiveX Control.

.Index : integer

Returns the Index of the ListItem. Cannot be set by MAXScript.

.Key : string

Returns the Key of the ListItem. Cannot be set by MAXScript.

.Selected : Boolean

Get/Set the Selected state of the ListItem. When true, the item is selected, when false, it is not. Depending on the state of the .MultiSelect property of the ListView, only one or multiple ListItems can be selected at the same time. Settings the .selected property of one ListItem to true while .MultiSelect is set to false will automatically deselect any other selected ListItems.

.SmallIcon : undefined

Get/Set the SmallIcon of the ListItem.

.Tag : undefined

Get/Set the Tag of the ListItem.

.Top : float

Returns the Top coordinates of the ListItem in Twips.

.Left : float

Returns the Left coordinates of the ListItem in Twips.

.Width : float

Returns the Width of the ListItem in Twips.

.ListSubItems : IListSubItems

Provides access to the array of Sub-Items of the ListItem. Sub-Items represent the columns after the first column. Sub-Items

SubItems can be accessed through indexed access to the .ListSubItems.

For example

--to access the second sub-item of the first item in

--a ListView Control stored in the variable lv,

--you could use:

lv.listItems[1].listSubItems[2]

 

.Checked : Boolean

Get/Set the checked state of the List Item. See also the on ItemCheck do event handler further on this page.

.ForeColor : OLE_COLOR

Get/Set the Text color of the ListItem.

Note

OLE_COLOR values used by ActiveX Controls are BGR and not RGB!

.ToolTipText : string

Get/Set the Tooltip Text of the ListItem.

.Bold : Boolean

Get/Set the Bold Text property of the ListItem. When set to true, the text will be displayed in Bold characters.

.ListItem Methods:

.CreateDragImage()

 

.EnsureVisible()

Ensures that the ListItem is visible in the ListView by scrolling the view as needed.

ListSubItem Properties and Methods

A ListSubItem is created by using the .ListItems.Add() method and can be accessed using 1-based indexed access as described above. Every ListItem has the following properties:

ListSubItem Properties:

.Text : string

Get/Set the Text of the ListSubItem.

.ForeColor : OLE_COLOR

Get/Set the Text color of the ListSubItem.

Note

OLE_COLOR values used by ActiveX Controls are BGR and not RGB!

.Bold : boolean

Get/Set the Bold Text property of the ListSubItem. When set to true, the text will be displayed in Bold characters.

.ToolTipText : string

Get/Set the Tooltip Text of the ListSubItem.

.Index : integer

Returns the Index of the ListSubItem. Cannot be set by MAXScript.

.Key : string

.Tag : undefined

.ReportIcon : undefined

ListSubItem Methods:

No methods exposed.

 

ColumnHeader Properties and Methods

Every ColumnHeader has the following properties:

ColumnHeader Properties:

.Text : string

Get/Set the text displayed by the Column Header.

.Alignment : ListColumnAlignmentConstants( #lvwColumnLeft | #lvwColumnRight | #lvwColumnCenter )

Get/Set the alignment of the Column Header's text.

.Index : integer

Get the index of the Column Header.

.Key : string

Get the key of the Column Header.

.Left : float

Get the left margin of the Column Header in Twips.

.SubItemIndex : integer

Get the sub item index of the Column Header.

.Tag : undefined

Get/Set the tag of the Column Header.

.Width : float

Get/Set the width of the Column in Twips.

.Icon : undefined

Get/Set the icon of the Column Header. The icon is a 1-based index into the .icons array which in turn is managed by an ImageList ActiveX Control. When no icon is assigned, the property returns 0.

.Position : integer

Get/Set the position of the Column Header. The position controls the order of the columns. By default, .Position is set to be equal to the .Index property. Setting .Position to a different value effectively changes the order of the columns, placing the column at the desired position.

ColumnHeader Methods:

No methods exposed.

 

See also

ListView ActiveX Helper Functions

TabStrip ActiveX Control

ActiveX Controls in MAXScript Rollouts

How To ... Develop a Selected Objects Inspector using ListView ActiveX Control - Part One

How To ... Develop a Selected Objects Inspector using ListView ActiveX Control - Part Two

 

External Reference:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cmctl198/html/vbobjlistview.asp