List Browsers part 1

From Vectorlab
Jump to: navigation, search
Stop.png
This vcor page needs language cleanup.

If you wish to help, clean up the page, then remove me deleting the line "{{Language cleanup}}". In the category:Language cleanup you'll find a list of all pages marked for cleanup.


List Browsers dissected Part 1: creation and columns. By Orso B. Schmid

Introduction Part 1: Creation and columns Part 2: Rows and cells

Create a List Browser

List Browsers are called in a Layout Creation routine with CreateLB.

CreateLB(dialogID: LONGINT; componentID: LONGINT; 
	widthInCharacters: INTEGER; heightInCharacters: INTEGER);
widthInCharacters, heightInCharacters
is different between Mac and PC. Basically on Mac all dialog items with a scroll bar interpret the width excluding the bar. This will influence the width of dialog elements such as PullDown menus, List Browsers, Lists and such. These items won't align with Static Texts, Edit fields and similar: the scroll bar will be outside alignment. Correct for this.


List Browsers in resizable dialogs

List Browsers are special dialog items with a built-in binding to their parent container. If a dialog is resizable, they resize width and height automatically, without any Edge Binding setting. For this reason you'll prefer to leave List Browsers outside groups: they will fit beautifully to the dialog window without you to bother.


dlog := CreateResizableLayout('List Browsers test', TRUE, 'Close', '', TRUE, FALSE);
{ ... }
CreateLB(dlog, cLB, cLBWidth, cLBHeight);


Load a List Browser

Your List Browser after creation is just an empty container without columns, rows and any data. Before loading the List Browser it is relevant to understand what needs to be loaded once and what needs to be loaded repeatedly after destroying data. Aside of images, which must be really loaded only once, all other List Browser elements can be loaded, destroyed, created or modified according to your needs. The typical script will set up a List Browser once in SetupDialogC and manipulate repeatedly only rows data. Commonly you will:

Then you'll organize your loading code as follows:

  • needs loading once --> has a place in the SetupDialogC CASE item of your dialog driver routine
  • needs loading repeatedly --> resides in a subroutine with wider validity scope (including SetupDialogC for the first run).


Items and Sub-items (0-based)

At start the main difficulty in understanding List Browsers consists in the official naming of the routine parameters. Everyone will struggle initially with "itemIndex" and "subItemIndex", sometimes also called (more clearly) "columnIndex". The official documentation uses names not consequently. Just some examples:

GetLBItemInfo(dialogID: LONGINT; componentID: LONGINT; itemIndex: INTEGER; subItemIndex: INTEGER; 
	VAR itemString: STRING; VAR imageIndex: INTEGER): BOOLEAN;

GetLBItemData(nDialogID, nComponentID :LONGINT; nItemIndex, nSubItemIndex :INTEGER; 
	VAR nUserData :LONGINT);

InsertLBColumn( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER;
	headerString:STRING; width:INTEGER):INTEGER;
the row index
itemIndex, nItemIndex
the column index
subItemIndex, nSubItemIndex, columnIndex

If you see both parameters for row and for column you know that you'll target a cell (intersection of row and column).

All indexes in List Browsers are 0-based:

This implies that for setting the absence of an image -for example- you need to pass "-1". Take care to init your variables to -1. Mind the routine AddLBImage which on Mac might return "0" also if it failed to insert an image.

Many mistakes in List Browsers are caused by unwanted 0-indexes in images or Column Data Items.


Icons (list)

Very relevant for the layout of a List Browser is the list of icons (optional). Here you store small icons that will be available to the whole List Browser. The icons must be either loaded from external resource files or recycled among the built-in Vectorworks icons. They can be used directly from the singular cells and/or be used to build data in the List of Data Items of a column. An Icon List can be created using AddListBrowserImage, from VW 2014, which replaces AddLBImage, now obsolete. There is a single routine allowing to load icon resources without pre-loading them in the Icon List first: SetLBImageIndexes, which applies only to columns with control type Multiple Icons. To my knowledge, once loaded the original indexes of the icon-resources are lost: for example it's not possible to fetch the original resource index of icon "2" in the Icon List and substitute it with something else. This is only possible on Mac using columns of type Multiple Icons when they are loaded with SetLBImageIndexes, but I didn't try this with the new routine, only with its precursor: SetLBMultImageIndexes (obsolete).

It's also not possible to delete the image-list from the List Browser, once created. For this reason images must be loaded only once In SetupDialogC and attention be paid that AddListBrowserImage doesn't land in any repetitive routine: this would add the same image over and over again, each time increasing the index count.

The sequence defined by adding images is not relevant if you need the icons for singular cells or for a List of Data Items, but becomes very important if your icons need to be displayed in Radio columns, since this control follows the insertion order of the Icon List precisely.

AddListBrowserImage(dialogID: LONGINT; listBrowserID: LONGINT; imageSpecifier: DYNARRAY[] of CHAR): INTEGER;
imageSpecifier 
the path to the image resource (since VW 2104), for example: 'Vectorworks/ResourceBrowser/WallStyle.png'.

I prefer to "borrow" icons from the application self, where there is a very large choice: loading resources from Vectorworks spares you the creation of your own resource file[s]. The application ships with a huge number of icons and you always find something that fits your needs.

result (0-based)
the index of the newly inserted icon. This increases at each newly inserted icon. Once added, images cannot be deleted and stay with the List Browser until script ends. For this reason Images should be added to the List Browser only once. This is best done in the SetupDialogC section of the dialog driver.
Since the index is 0-based you should remember later to use "-1" for telling cells not to use images. Whenever you see a routine allowing for an image index (for example SetLBItemInfo) and you don't want an image to load, set the image index parameter to "-1". A typical mistake is to write "0", which will load the first image in the LB, if any loaded. If you didn't load images into your LB previously, you don't need to bother much.
BUG
the incremental index behaves differently between Mac and PC, if the image resources requested are missing, please see MAC PC differences.


Example Script

We wish to use toggles in our List Browser so we load three images. The numbers "1485, 1486, 1487" are image resources borrowed from Vectorworks. We recycle them. Below you can see how they look like.

{ add three images to a List Browser }
	gImgCnt := -1; { init }
	gImgCnt := AddListBrowserImage(gD, cLB_Styles, 'Vectorworks/Standard Images/Visible'); { visible: black eye }
	gImgCnt := AddListBrowserImage(gD, cLB_Styles, 'Vectorworks/Standard Images/Invisible'); { invisible: cross }
	gImgCnt := AddListBrowserImage(gD, cLB_Styles, 'Vectorworks/Standard Images/Gray'); { grayed: gray eye }
LB toggleImgs.png
Since we know that the list starts at zero and the counter always increases by 1, we store the final index in the variable "gImgCnt". If something goes wrong, we have the needed "-1" value to declare the lack of images. To access them later we'll only need to subtract to this variable. You might prefer to access indexes in this fashion whenever your script uses only few images.


Columns

After creating an (optional) list of Icons you can proceed to add columns to the List Browser. While creating each column it is simple to set immediately its appearance and eventually some modifiers which affect -it goes without saying- the whole column and all cells there included. A column creates ready to display text which doesn't react on clicks. Any other display involves a resetting of Control Type and Display Type.

Most of the times you create columns only at dialog setup and in a loop. If you do it only once -because you won't delete columns later- the loop needs a place in SetupDialogC and nowhere else. Nothing forbids you, though, to delete columns and redo them according to your script needs. In this case you'll have the column creation in a sub-routine callable on demand with a wider script scope. But is seldom.

Settings Modifiers Column set up
Insert columns using InsertLBColumn. Set for each column:

Outside any loop set for the whole List Browser:


GetNumLBColumns( dialogID:LONGINT; componentID:LONGINT):INTEGER;

Count of columns present in a List Browser. You will use this call extensively for adding columns. Remember to decrease the count of columns of -1, if you use it as column index reference, since -again- column indexes are 0-based.


InsertLBColumn( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	headerString:STRING; width:INTEGER):INTEGER;

Inserts a column ready to be filled with text cells. Call InsertLBColumn for each column to be inserted, use the returned index for further column settings. Defaults upon creation are:

result (0-based)
index of the new column in the List Browser.
columnIndex
at which position in the List Browser the column should be inserted.
BUG: passing "0" as insertion position the title will center after the first row. Moreover in VW 13 if the List Browser has icons loaded, an icon will unexpectedly appear in the title. For this reason is always wise to insert new columns only at the end using GetNumLBColumns.
headerString
the column's title (string). The title aligns left by default. If a different alignment is needed it can be fixed later with SetLBColumnHeaderJust.
width
the width of the column. Can be modified anytime using SetLBColumnWidth. Don't pass a zero width.


GetLBColumnWidth( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	VAR width:INTEGER):BOOLEAN;
	
SetLBColumnWidth( dialogID:LONGINT; componentID:LONGINT; 
	fromColumn:INTEGER; toColumn:INTEGER; width:INTEGER):BOOLEAN;
fromColumn, toColumn
the range of columns where the width should apply. Mind that the title seems to create a large white space at the end. You should dimension columns rather large otherwise they won't display the whole title text. Under VW 14+ you can use GetLBHeaderTextWidth to dimension precisely your column width.
Often you'll create columns in a loop from string arrays or external files data. In this case you insert the columns with some default width and reset precisely only those columns that need to be different.
BUG: Column widths "0" crash VW 13 (fixed by build 87094). You must programmatically avoid them and also make sure that your user is not in the position of resizing them to zero, if you wish to grant compatibility with VW 13.


GetLBHeaderTextWidth(className: STRING; allowForSortIcon: BOOLEAN): INTEGER ;

(VW14+) returns the column width needed to fit the column title without resizing. There is a parameter "allowForSortIcon". I didn't try this call yet.


Column Titles

Frequently an array of string is a good way to create the titles in a loop. Other times data will be loaded from external files or from existing document objects. Whatever system you choose, you shall remember that column titles cannot be changed after creation. In order to change a column's title the only solution is to destroy the column and recreate it. This can be done with DeleteLBColumn.


SetLBColumnImage(nDialogID, nComponentID :LONGINT; 
	nColumnIndex, nImageIndex :INTEGER) :BOOLEAN;
result
FALSE if the column index "nColumnIndex" points to a column that doesn't exists. Note that the routine doesn't return false if the icon index "nImageIndex" points to a missing icon.
nImageIndex
Use an icon as column title. This replaces the text, you cannot have both text and icon. The image must available in the List Browser's Icon List.


GetLBColumnHeaderJust( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	VAR justification:INTEGER):BOOLEAN;
	
SetLBColumnHeaderJust( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	justification:INTEGER):BOOLEAN;

Modify the alignment of the column title. Use following constants:

  • 1 = Left
  • 2 = Center
  • 3 = Right


GetLBColumnHeaderToolTip( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	VAR toolTipPrimaryText:STRING; VAR toolTipSubText:STRING):BOOLEAN;

SetLBColumnHeaderToolTip( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	toolTipPrimaryText:STRING; toolTipSubText:STRING):BOOLEAN;

Gets/sets hovering tips for the column headers. Setting tool tips is quite handy when the column width will certainly be too small and titles will be cropped: pass then titles as tool tip.

toolTipPrimaryText
text appearing on hovering over the column title.
toolTipSubText
text appearing pressing the cmd/alt (Mac/Win) key while hovering.
BUG
don't use GetLBColumnHeaderToolTip if you plan to use your script on VW 13. It crashes VW under Mac (fixed by VW 14, built 90067).


Column Lines

Column lines are the gray vertical lines drawn between each column. They are optional. Columns with control type Radio have an extra option for setting the sub-titles column lines.


AreLBColumnLinesEnabled(dialogID: LONGINT; componentID: LONGINT): BOOLEAN;

Checks on/off status of column lines for a List Browser.


EnableLBColumnLines(dialogID: LONGINT; componentID: LONGINT; 
	enableColumnLines:BOOLEAN);

Default: FALSE. Toggles the vertical column lines on/off. It affects a whole List Browser, so this call shall be kept outside repetitive routines. Usually it is called at the end of the List Browser setup routine. Don't confuse it with EnableLBRadioColumnLines.


AreLBRadioColumnLinesEnabled(dialogID: LONGINT; componentID: LONGINT; columnIndex: INTEGER): BOOLEAN;

(only for control type Radio) Checks on/off status of the sub-column lines for a chosen radio column. Note that this applies to a column, not to the whole List Browser as AreLBColumnLinesEnabled.


EnableLBRadioColumnLines(dialogID: LONGINT; componentID: LONGINT; columnIndex: INTEGER; 
	enableRadioColumnLines: BOOLEAN);

Default: FALSE. (only for control type Radio) Draws extra gray vertical lines for each sub-column in the chosen Radio column. For this to show you need:

This is applied on column index basis. Most of the times only a single Radio column is needed in a List Browser, so you'll choose to enable the radio vertical lines at the end of -and outside- the column creation loop (if any).


Column Data Items (list)

If you're not a programmer -like me-, you'll struggle quite a bit to understand what Data Items are and above all what they do: they are items in a list of data. This list is available to the column where it's defined. I believe that a column can use only ONE list. At least in Vectorscript I could distinguish no access to multiple lists for a single column index.

Whenever you start using List Browsers, soon or later you have the burning wish to coerce cells to a certain list of values. If you could, you'd just love to insert a pull-down menu in your cell, perhaps one with images in it, but this is not possible. You have Column Data Items instead. These, once defined, are available column-wide. With Column Data Items you can coerce all cells in a column to show only values present in a list. Each list element is a Column Data Item.

LB ColumnDataItemsImgs.png
For example you could wish to pair the string "visible" with the black-eye icon. Probably you would like to have more of these items, so you'll define also an item <string "invisible" with the cross icon> and <string "grayed" with the grayed-eye icon>. For each you need to create one Data Item using InsertLBColumnDataItem (and you already loaded the icons in the List Browser's Icon List through AddListBrowserImage).

Not all column's Control Types manage these lists, but for those who do, you will observe that cells using Column Data Items will stop being free and only display a range of Data Items values. For example: "visible, invisible, grayed" and/or show the respective images on user's click.

The sequence in which you create the data items is relevant. Column Data Items build an indexed list whose order is used by the columns where you apply them. The behavior of your cells depends on the column's Control Type. Moreover is influenced by the chosen column's Display Type. The only exception is the control Radio, which uses the insertion order of the Icon List.

On-click behavior
you can distinguish among column's controls which display their list of Column Data Items on click and those who don't. All cells can be loaded with one Column Data Item using SetLBItemUsingColumnDataItem, but only cells whose columns belong to Multi State and Single Instance Icon will toggle Data items on click (even if they weren't pre-loaded using SetLBItemUsingColumnDataItem). Radio columns do this too, but are a world on their own, please see Radio.

Column Data Items are to be used only on columns with control type Multi State, Single Instance or Radio. And -stating the obvious- you have no reason whatsoever to use these controls without Column Data Items. But in rare circumstances you might find comfortable to store hidden data in Column Data Items just to be able to fetch it on need even from columns whose click-response is not available, like Static.

Control Multi State or Single Instance Icon
you should always pre-load cells using with this control type with SetLBItemUsingColumnDataItem in order to have proper start values. Don't use SetLBItemInfo. This is particularly important for cells whose column has control type Single Instance Icon. Under circumstances you'll like to pre-load an empty image.
Control Radio
it has the peculiar behavior to load all images starting with the first defined in the Icon List, unregarded the icon indexes passed in InsertLBColumnDataItem. It can only display images ignoring text altogether. See Radio.


Column Data Items and Control Type
Control Type Edit Display Response on click:
1 Static <doesn't respond>
2 Radio
  • Image
  • Text and Image
Shows multiple choices with icons, creates a sub-column for each call to InsertLBColumnDataItem, although it displays the Icon List, in a sequence. Upon clicking on a sub-column, the image corresponding to the sub-column index (0-based) will show. Is unable to display text.
3 Multi State
  • any
At each click displays the next Data Item by index in the list.
4 Single Instance Icon
  • any
Upon clicking in a cell display "item 1" of the Data Item list.

Any previous selection will be set to "item 0" in the list. Thus you'll have one single instance of item 1 in a whole column. For this control you need only two Column Data Items, the others don't display.

5 Static Icon <doesn't respond>
6 Number <doesn't respond>
7 Multiple Icons <doesn't respond>


Manage the Data Items List

InsertLBColumnDataItem( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	itemString:STRING; imageOn:INTEGER; imageOff:INTEGER; itemData:LONGINT):INTEGER;

Inserts one Data Item in the list for the chosen column. You will repeat the call for each Item to be inserted in your Column Data Items list.

result (0-based)
index of the newly inserted Data Item. Most of the times is advisable to store only the start or end value of a Data Item List and use that adding or subtracting needed indexes. You might prefer this approach instead of storing singular Item indexes.
itemString
the string attached to this index of Column Data Item. MUST be defined otherwise the item doesn't insert in the List.
  • Multi State, Single Instance Icon: you can decide to create a Data Item containing only strings setting both "imageOn" and "imageOff" to "-1".
  • Radio: no string support, but the string must be nevertheless defined.
imageOn
is an icon index of the Icon List, the image to be triggered on user's click. Set to "-1" to make image undefined.
  • Multi State: the icon shown when selecting a cell. At each further click, the next image in the list will be displayed. When the list has reached the end, the whole begins anew from the start.
  • Single Instance Icon: on click shows image index 1. Any other selection shows image index 0.
  • Radio: see dedicated chapter.
imageOff
is an icon index of the Icon List, the image to be triggered on deselection. Set to "-1" to make the icon undefined.
itemData
elsewhere called "User data". No idea how to use this. If you set something here it will block toggles, if the Longint passed exceeds the Icon List. See User Data.
Notes
  • If you don't want to load images pass "-1" to the parameters "imageOn" and "imageOff". Here is to be noted that:
  • Multi State and Single Instance Icon columns: ignore the "-1" and show the last valid image previously defined. If no images has been defined at all, the cells show nothing.
  • Radio columns: show white space
  • Multi State and Single Instance Icon add the images according to the index passed in the parameter "imageOn". Radio columns add them according to the Icon List's index corresponding to the count of calls of the routine InsertLBColumnDataItem. This has been damn tough to find out.
  • (only Radio) If you load the parameter "imageOff" you should leave "imageOn" to "-1". Then it will display the image defined for off. If you define both, you'll have "imageOn" permanently visible both on selection and not. All other control types (supporting Column Data Items) will only use imageOn.


GetLBColumnDataItemInfo(dialogID: LONGINT; componentID: LONGINT; columnIndex: INTEGER; 
	columnDataItemIndex: INTEGER; 
	VAR itemString:STRING; VAR imageOn: INTEGER; VAR imageOff:INTEGER; VAR itemData: LONGINT): BOOLEAN;

Query a Data Items List of a column for the values associated to a particular item index.

columnDataItemIndex
the column data item to be queried
itemString
the item text associated with that data item
imageOn
the "on" image associated with that data item on selection
imageOff
the "off" image associated with that data item on deselection
itemData
the item user data. See User Data


FindLBColumnDataItem( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; itemString:STRING; 
	VAR columnDataItemIndex:INTEGER):BOOLEAN;

Queries a Data Items List for a specific string and returns the index of the found Data Item, if any. If no item can be found returns FALSE and sets the variable "columnDataItemIndex" to "-1".


RemoveLBColumnDataItem( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	columnDataItemIndex:INTEGER):BOOLEAN;
	
RemoveAllLBColumnDataItems( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER);

Remove one or all items from a Column Data List.


Example: Data Items

Here words don't help. If you wish to understand the plurality of Column Data Items lists, you must go through some experiments. Get nuts with this:

Example
Data Item won't insert because of empty string
{ will be ignored since the string is missing }
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, '', imgIndex, -1, 0);
Example
text only toggles
{ text only toggles: use Edit Display "Text only" }
dataItemCnt1 := InsertLBColumnDataItem(dlog, LB, col, 'Orso', -1, -1, 0);
dataItemCnt1 := InsertLBColumnDataItem(dlog, LB, col, 'Atta', -1, -1, 0);
dataItemCnt1 := InsertLBColumnDataItem(dlog, LB, col, 'Ax', -1, -1, 0);
Example
text/image toggles
{ text/image toggles: use Edit Display "Image and text"}
{ gImgCnt is the count of images loaded in the Icon List }
dataItemCnt3 := InsertLBColumnDataItem(dlog, LB, col, 'image 1', gImgCnt-2, -1, 0);
dataItemCnt3 := InsertLBColumnDataItem(dlog, LB, col, 'image 2', gImgCnt-1, -1, 0);
dataItemCnt3 := InsertLBColumnDataItem(dlog, LB, col, 'image 3', gImgCnt, -1, 0);
Example
only string and one image at start: icon 2
{ emtpy on "Radio", always image 2 on "Multi State" and "Single instance" }
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'string only', 2, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'string only 2', -1, -1, 0); 
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'string only 3', -1, -1, 0);
Example
targeted index sequence
{ having 10 items defined in the Icon list }
{ sequence 0, 1, 2, 3 on "Radio" }
{ sequence 8, 9, 6, 5 on "Multi State" }
{ sequence 8, 9 on "Single instance" }
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 8', 8, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 9', 9, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 6', 6, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 5', 5, -1, 0);
Example
use imageOff on Radio column
{ having 10 items defined in the Icon list }
{ sequence -, 1, 2, 3 on "Radio", with image 9 on sub-col 0 when NOT selected }
{ sequence 0, 0, 0, 0 on "Multi State" (facit: always image 0, perfectly senseless) }
{ sequence 0, 0 on "Single instance" }
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 9 on off', -1, 9, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 1', 0, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 2', 0, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'image 3', 0, -1, 0);


Display Type

The Display Type determines which type of content a column should show: Text only, Image, or Text and Image. Image means here Icon. What you see at the end depends on the column's Control Type, if Column Data Items are setup or not, not last it depends on the Owner of the singular cell. The Display Type choice applies to all cells in a column. Default upon column creation is Text only.

There are two kind of Display Types. They used to behave differently but as of VW 2017 they seem to be fully exchangeable:

  • Item Display: the same as Edit Display (tested in VW 2017)
  • Edit Display: the same as Item Display (tested in VW 2017)
  • Control type Radio is indifferent to both Item and Edit Display: it can only display Images.


Display Type Description Control Type requirement
1-Image shows only an image

LB dispImg.png

Item or Edit Display no Display needed
2-Text only shows only text

LB dispTxt.png

3-Image and Text shows both image and text

LB dispTxtImg.png


Item Display

The same as Edit Display. Radio columns ignore it.

GetLBItemDisplayType( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER):INTEGER;

SetLBItemDisplayType( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	displayType:INTEGER):BOOLEAN;


Edit Display

The same as Item Display. Radio columns ignore it.

GetLBEditDisplayType( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER):INTEGER;

SetLBEditDisplayType( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	displayType:INTEGER):BOOLEAN;


Example Script

We need to observe what happens changing Item or Edit Type. Two pull-down menus allow you to experiment with these settings. After you change the values, the List Browser will refresh. For this reason we set these values in a sub-routine that will be called on demand: "LB_LoadColumns".

FOR col:=1 TO GetNumLBColumns(dlog, LB) -1 DO BEGIN
	temp_b := SetLBItemDisplayType(dlog, LB, col, itemType); 
	temp_b := SetLBEditDisplayType(dlog, LB, col, editType);
	
	{ ... }


Control Type

The Control Type determines how a column will react to the user. Nevertheless in order to achieve the desired effect, you must combine control types with appropriate Item or Edit Display Type. The Control Type and related Display Type choice depends on the kind of content that you mean to display in the column: picking from a List of Column Data Item or not. The default control type upon column creation is "1" = Static.

It's not always necessary to set a control type, only when the default value Static is not sufficient, that is, whenever you need special facilities for using a List of Column Data Items. The control type can be changed after column insertion using SetLBControlType.

The official Vectorscript Language documentation contains a few lines about control types (see : "List Browsers" in the VW Help). There it's stated that currently the only operational controls for Column Data Items are Radio and Multi State. This information is probably obsolete. There are more controls operational as of VW 13.


Control Type Display Type needs is good for
1- Static Item or Edit Display - Text, simple icons, color cells, line style cells, thumbnail cells
2- Radio ignores it Column Data Items Multiple options with clickable icons. Can only do this.
3- Multi State Item or Edit Display Column Data Items Multiple toggles on click of column data items, otherwise like Static
4- Single Instance Icon Item or Edit Display Two Column Data Items On-off toggle on click of two column data items, otherwise like Static
5- Static Icon Item or Edit Display Icon from column data items, otherwise like Static
6- Number Item or Edit Display - Numbers, otherwise like Static
7- Multiple Icons Item or Edit Display Icon Resources from external file More icons in one cell, without preloading in the Icon List, otherwise like Static (Mac only)

The three Control Types below only work properly if associated to a List of Column Data Items. As stated before in the chapter Column Data Items, you have no reason whatsoever to use them without such a list.

Inside the dialog event handling these types don't even return an active control without a list, not even the expected "-1". Experiment with the generic routine GetActiveEditItem passing the dialog ID, try with and without Column Data Items associated to the column. Facit: use them only with Column Data Items.


temp_b := SetLBControlType(dlog, LB, colNr, controlType);
result
returns FALSE if
  • no columns are present in the List Browser
  • you try to set the control type on a column whose control is already set to the value "controlType" passed in the routine. For this reason is not advisable to code depending on the TRUE result of this routine. For example: set the Display Type if SetLBControlType returns TRUE. It will fail to change the display simply because the control was already set as you wish. Just assign the result of SetLBControlType to a temporary boolean variable which you'll trash.
controlType
use one of the constants below. It is advisable to store them in an external px file to be loaded as include whenever a dialog involves List Browsers.
  • kLBctrNone = 1; { Static }
  • kLBctrRadio = 2;
  • kLBctrMultiState = 3;
  • kLBctrSingleInstance = 4;
  • kLBctrNoClick = 5; { Static icon }
  • kLBctrNumber = 6;
  • kLBctrMultipleImages = 7;


Static

LB controlStatic.png
Static is the default control upon column creation. Sometimes also called None (not to be mistaken for the cell Owner None). It displays well anything not involving Column Data Items toggles: in fact it can display them too, but only statically, no toggle on user's click, thus its name, I suppose. Using Data Items here make this control nearly identical to Static Icon.

Excluding the above mentioned toggles, this is the secure choice for text, simple icons, resource thumbnails, colored cells, line styles. Numbers should be created with a control type Number, since that offers a few more targeted facilities.

For this to work you need
nothing. But a few observations can be made as to the display:
  • Item Display: Image: shows an icon (if loaded in the Icon List) or attribute cell
  • Item Display: Text: shows only text (really no good for attribute cells: infamous "AAAAA string" if you didn't set the cell's owner at the right place of your code)
  • Item Display: Text and Image : shows both icon and text (even worse for attribute cells)
Use it for columns dedicate to cells with following Owner Types
  • All attributes cell Owners:


Radio

LB controlRadio.png
Radio is the purest Column Data Items control. You can use this control to display multiple choices represented in sub-columns of icons triggered on click. Compared to the other controls it's a radical modifier with following peculiarities:
  • ignores any string (expected).
  • ignores fully Display Types (expected).
  • displays icons always according to the sequence defined in the Icon list, ingoring the indexes passed in the parameter "imageOn" in the Data Items List. For each sub-column to be created a call to InsertLBColumnDataItem must be performed. Each call matches the sub-column to the corresponding index from the Icon list. It means that you cannot "shuffle" the order set in the Icon List and must plan the insertion order of the icons in the Icon List carefully. This behavior is unique among Column Data Item aware control types.
For this to work you need

See Column Lines for setting up Radio Column Lines for the sub-columns.


InsertLBColumnDataItem( dialogID:LONGINT; componentID:LONGINT; columnIndex:INTEGER; 
	itemString:STRING; imageOn:INTEGER; imageOff:INTEGER; itemData:LONGINT):INTEGER;

Inserts one sub-column in the Radio column. You will repeat the call for each Column Data Item to be inserted in your list. Each created sub-column corresponds to the same index of the Icon List.

For example: passing icon index "5" in the first call to InsertLBColumnDataItem won't load that icon in the first sub-column. The icon displayed on click will be index "0" (first item in the Icon List).

itemString
is ignored but must be defined, otherwise the sub-column doesn't generate.
imageOn
is an icon stored in the Icon List: the icon to be shown on column selection. The index passed to "imageOn" can be anything within the range "0 - countOfIcons" in the Icon List. Set to "-1" to make it undefined.
imageOff
is an icon stored in the Icon List: the icon to be shown upon de-selection. Set to "-1" to make it undefined. Use "imageOff" only as alternative to '"imageOn". You shouldn't have both "imageOn" and "imageOff" defined in a single call to InsertLBColumnDataItem otherwise "imageOn" displays permanently. Using "imageOff" instead of "imageOn" it will display "imageOff" on deselection.


Evil question - How many sub-columns does this generate? And what do they do?
{ sub-col 0 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'imageOn-0', gImg, -1, 0);
{ sub-col 1 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'no images', -1, -1, 0); { string only }
{ sub-col 2 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, '', gImg+2, -1, 0); { will be ignored: no string }
{ sub-col 3 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'imageOn-1', gImg +1, -1, 0);
{ sub-col 4 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'imageOff-1', -1, gImg+1, 0);
{ sub-col 5 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'imageOn-0', gImg, -1, 0);
{ sub-col 6 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, '', -1, -1, 0); { will be ignored: no string }
{ sub-col 7 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'imageOff-2', -1, gImg+2, 0);
{ sub-col 8 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, '', gImg+1, -1, 0); { will be ignored: no string }
{ sub-col 9 } dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'no images', -1, -1, 0); { string only }


Passing the same imageOn over and over still make the Radio column display the full Icon List sequence.
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'try0', 2, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'try1', 2, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'try2', 2, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'try3', 2, -1, 0);


Multi State

LB controlMultiState.png
Multi State is a charming Column Data Items control, whereby you won't notice the difference until a list of Column Data Items is employed, in absence of which it behaves like Static. If Column Data Items are loaded in form of string or images (or both) the cell will loop down all items at each user's click. Multi State justifies the name "List Browser": it browses the list (... of Column Data Items). You'll use it when you wish to restrict the available choices to a controlled range. It expects Edit Display.

Proper Column Data Items should be pre-loaded in each cell using SetLBItemUsingColumnDataItem in the row creation routine.

For this to work you need


Single Instance Icon

LB controlSingleInstIcon.png
Single Instance is another Column Data Items control. Also behaves as Static if no Data Items are used. Seems bizarre at first. You'll use it when you need a single instance of data to be present in a whole column, for example an icon marking the currently -only- active layer. Unregarded the definition, you can also use if for text strings. A NNA example of its usage can be seen in the Organization Dialog > Classes, when the option "Details" is on: is the selection icon on the left of the class names. It expects Edit Display.

It has a built-in Single line Selection enabled: you can't select multiple rows when you click on a cell belonging to a Single Instance column. It's a Column Data Item toggle. As soon as you click on a cell it will set the value to the second item defined in the Items list of the parent column. By clicking, the cell previously selected will be assigned the first Item.

For this to work you need

This will only work well if you really make sure to init the cells to proper values: use SetLBItemUsingColumnDataItem and NOT SetLBItemInfo. The problem is when there wasn't a previous selection (just after launch for example) and the cells are set to a value whose appearance is not that of the Column Data Items.

Just pay attention to set well your cells in this column for the first launch: all cells in the Single Instance column should be initialized to the first Column Data Item, but one, which will get the second.

Since you know that all cells in the Single Instance column will (should) have the same value but one, you can search it securely using FindLBColumnItem.


Static Icon

LB controlStaticIcon.png
Static Icon is the last Column Data Items control. As usual behaving like Static if no Data Items are used. This control is sometimes called No click, which in this case is a good hint to the functionality that it triggers in its cells: it displays a single Data Item without allowing for any user interaction on click. As a whole it behaves absolutely the same as Static when passing to it a Data Item index (no click toggles). It expects Edit Display.

The only difference that I could discover is that Static Icon cells send on click an event "-2" which I believe to be indicative of "Data-Items-awareness" while Static won't ever do it. The finesse of this control type is too much for me and I never used it. I'd love to know more about it, most likely I am missing the party, here.

For this to work you need


Number

LB controlNumber.png
Number is a column control mainly dedicated to Drag and Drop. Otherwise it feels a little underdeveloped, above all because it won't sort cells numerically (or I didn't find out how). "400" will appear before "70", typical of alphabetical sorting. It expects Item Display.

It has a feature: it will strip out leading zeros from strings, if applicable. For example "0006" turns into "6" and will nevertheless sort as 0006. This opens the workaround to pad strings with a large amount of zeros at start and bring all numbers in a column to have the same characters' length. At this point you can sort also alphabetically and it will look like a numerical sorting.

And to my knowledge this is the only way of letting the columns sort "numerically". If anyone knows the straight way I beg to be informed.

Owner Number also doesn't automatically align left cell content. You must align the singular cells with SetLBItemTextJust. It doesn't do math: passing string "7-6" doesn't return "1", but this shouldn't be expected.

For this to work you need

Anything else is just wilderness [... of pain]. See the image on the right: only the "Owner Text" reliably displays a number. And this with Edit Display Image.


Multiple Icons

LB controlMultiIcons.png
Multiple Icons is sometimes also called Multiple Images. This control can display up to three images at the same time in a cell. The icon resources can be loaded directly from a resource file and don't need to be preloaded in the Icon List. It doesn't react on user's click and is not operational with Column Data Items (whereby it sends an event "-2", which is indicative of some Data Items awareness, but I didn't succeed in discovering which). Is an image-based control type which expects Edit Display. A NNA example of Multiple Icons can be seen in the Organization dialog > Saved Views > Class Options, when the "Visibility" option is activated.

This control type behaves differently between Mac and PC:

PC
Doesn't display any image whatsoever. Whereby I am tempted here to file a VectorScript bug, since according to the SDK the corresponding callback routine SetListBrowserMultImageIndexes is implemented for both platforms. Which leaves the error to rely only on the control type Multiple Icons. And there are examples on the Organization dialog which work flawlessly on both platforms.
MAC
Allows to load directly three images from a resource file without adding them previously to the List of icons through AddListBrowserImage.
For this to work you need... a Mac, then
  • Cell Owner: None (default) is a good choice
  • Image Resources: the access is the same as for Add Images. All three images must be set, otherwise nothing display. You cannot pass -1 to any of the variables, but you can pass "0" which will make the image blank (since at index "0" of the built-in resources there is no image loaded).
  • Edit Display Image: shows only three images.
  • Edit Display Image and text: shows three images and the first Column Data Item defined if any, or the text set in the rows info. Mind, this is not a control that seems to be interesting with Lists of Data Items.

Studying this routine a little, it is evident that it offers a fast and most flexible switch, since you don't have to bother with pre-loading the images. Too bad that it doesn't work on PC.


Example: columns

Final Example
A column creation routine

Create nine columns. Titles are stored in an array of string "gTitles" defined elsewhere. The default column width is "90".

{ first column is of type 6 = Number }
col := InsertLBColumn(dlog, LB, GetNumLBColumns(dlog, LB), '#', 40);
temp_b := SetLBControlType(dlog, LB, col, 6);
{ display type: not defined, defaults is 2 = text, OK for number columns }
	
{ enable drag and drop, this will only work on a column of type Number }
IF EnableLBDragAndDrop(dlog, LB, TRUE) THEN BEGIN
	temp_b := SetLBDragDropColumn(dlog, LB, col); 
	temp_b := SetLBColumnHeaderJust(dlog, LB, col, 2); { justify title center }
END;


{ loop to add seven other columns }
FOR n:=1 TO 7 DO BEGIN
	col := InsertLBColumn(dlog, LB, GetNumLBColumns(dlog, LB), gTitles[n], 90);
	{ control type: not defined, defaults is 1 = Static, OK for me }
	{ display type: not defined, defaults is 2 = Text only, OK for me }
	
	temp_b := SetLBColumnHeaderToolTip(dlog, LB, col, gTitles[n], ''); { add title as column tip }
	
	{ ... }
END;


{ last column is of type 2 = Radio }
col := InsertLBColumn(dlog, LB, GetNumLBColumns(dlog, LB), 'Radio title', 100);
temp_b := SetLBControlType(dlog, LB, col, 2);
{ Display Type undefined, is irrelevant for Radio columns }

{ create a list of data items for this col, the icons are already in the LB Icon List }
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'visible', 0, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'invisible', 0, -1, 0);
dataItemCnt := InsertLBColumnDataItem(dlog, LB, col, 'grayed', 0, -1, 0);

{ zero ImageON might be confusing, but is enough for Radio columns, 
they just need a call to InsertLBColumnDataItem and will create 
the icons in the order where you added them to the List Browser }

EnableLBRadioColumnLines(dlog, LB, col, TRUE);

EnableLBColumnLines(dlog, LB, TRUE); { enable gray lines between columns }
SetLBSortColumn(dlog, LB, 0, TRUE); 
{ sorting is on by default, no need to enable it, just enable the column 0 }


Introduction Part 1: Creation and columns Part 2: Rows and cells