ListView ActiveX Control
"Microsoft ListView Control 6.0 (SP4)" "MSComctlLib.ListViewCtrl.2" "{BDD1F04B-858B-11D1-B16A-00C0F0283628}" 
ActiveX Controls have been deprecated by Microsoft in the latest versions of the Windows operating system in favor of the DotNet framework and its controls.
While MAXScript still supports ActiveX controls, these have to be installed and registered on the system to be accessible to MAXScript.
As a replacement of ActiveX controls, MAXScript supports DotNet controls in 3ds Max 9 and higher.
See the topic Converting ActiveX ListView Control to DotNet ListView Control for an example of switching existing ActiveX code to DotNet.
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 : AppearanceConstant( #ccFlat | #cc3D ) Get/Set the appearance of the ListView control. #cc3D is default.
.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.
.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.
.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.
The 3ds Max keyboard shortcuts (accelerators) have to be disabled to be able to type in the label text field! See ActiveX - Disable3ds Max keyboard accelerators for details!
.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.
.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.
.BackColor : OLE_COLOR Controls the background color used to draw the ListView.
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
.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:
.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"
.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
.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:
.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 applyUIScaling:<true>.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, alignment 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.
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.
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.
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.
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 .
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.
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.
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.