Copyright: Copyright (C) 1993-4 Apex Software Corp.


Crescent Help File

The CSCombo (bound combo box), CSVlist (bound list box) and CSOptionList (bound option list or radio buttons) custom controls are licensed from Crescent Software, Inc., and are bundled free of charge with TrueGrid.  These controls are contained in Crescent's very popular QuickPak Professional for Windows product.  QuickPak includes more than 30 custom controls, more than 400 routines, 2.7 megabytes of sample programs, and more than 3 megabytes of source code and 1,000 pages of documentation.  To learn more about QuickPak, please refer to the QPAKPRO.WRI file in your TrueGrid installation directory

Bound Controls

CSCombo	Bound Combo Box

CSOptionList	Bound Option Button

CSVlist	Bound List Box

Property Reference

AutoSearch	BorderEffect
ColDelim	ColWidths
Contents	Dropped
Extended	FoundIndex
HScroll	ItemCaption
ItemValue	LeftMargin
ListBoxHeight	ListCount
ListDataFields	ListDataSource
SearchString	SelCount
ShadowColor	Spacing
StartSearch	TextDisplay
ThreeD	TopMargin
Value	ValueCol
Event Reference

CloseUp

DropDown

NewItem

QueryItem

Contacting Crescent


CSCombo Box
CSCombo

Purpose	Contents
Overview	Properties
Visual Basic 3.0 Support	Events
Searching	Methods
Custom control contained in CSCOMBO.VBX

Purpose:

The CSCombo control is a replacement for the standard Visual Basic combo box which provides a number of important enhancements including searching and data awareness.

Overview:

At first glance, CSCombo behaves like the standard Visual Basic combo box and supports all of the properties, methods and events of that control in a compatible fashion. However, CSCombo goes far beyond the standard by adding automatic features that you would otherwise have to code yourself or that would be impossible to implement directly in Visual Basic.

Visual Basic 3.0 Data support:

Standard database support is provided via the DataSource and DataField properties. By default, the edit box portion of the combo box (or the label portion when Style is set to 2) behaves much like a standard text box. Whatever is in the text control is bound to a data control. The combo box is used, in this case, to specify what the user enters into the text box portion of the control.

The simplest use of this would be to be to create a picklist for a text field. First, set the Style property to 2 and then link the Datasource and DataField properties to a Payment Terms field in a table. You could use the AddItem method to populate the list with such phrases as Net 30, C.O.D. and AMEX. Or you could click on the Contents property in design mode, and enter all of the default items to be displayed in the control. Your user could then easily select a payment term from the list. This is how you would expect to use a combo box, but the features of this control go much further.

First of all, you might want the data displayed for the user to be different from that which is stored in the database. For example, if you want to make a picklist of states you could, as outlined above, give a list of state codes from which the user would make a selection. However, which is MI? Michigan or Mississippi? Ideally, you would display a list of complete state names for the user but store and retrieve only the state codes. This process, often called aliasing, can be fairly tricky to program but is simple using the CSCombo ValueCol property. Here are the steps:

1. Set the ColDelim  property to ;
2. Open the Contents dialog and enter the following:
Michigan;MI
Mississippi;MS
New York;NY
  etc.
3. Set the ValueColproperty to 1.
4. Bind the control to a State field.

The result is a picklist which displays both state name and state column but which, behind the scenes, is only storing and retrieving the state code. This is identical to the Bound Column property of a combo box in Access. If you want, you can even hide the value column by setting its column width to zero, either in the ColWidths dialog or using the ColWidth array property. Once you become used to it, you will find that aliasing is one of the most important features of CSCombo. If you are not bound to a data control, the value of the combo box can be retrieved using the .Value property or simply the name of the control in the form: SCode$ = CSCombo1. See the CSCOMBO.MAK sample program for an example of using the aliasing feature.

The other aspect of data awareness has to do with the source of the list box portion of the combo box. You can bind the text box portion to a data control, and you can bind the list box portion as well (readonly). This is done with the ListDataSource and ListDataFields properties. You can also link the Text Box and List to the same data control, but that is rarely done. Instead, you will want to use a second data control for a foreign key lookup from the main table. Using the BIBLIO database (supplied by Microsoft) as an example, the Titles table has a field for AuId which is the sequential ID of that author. The rest of the author information must be looked up in the Authors table. So, if you create a form for authors and you want to add a new book, you would have to enter the ID of that author instead of his name, which is rather tedious.

Instead, you could create a new data control linked to Authors, and then use the ListDataSource property to link to that data control. Be default you would get all of the columns from that data control. It's possible to change the order of these columns or restrict the number of them using the ListDataFields property. You can use either field names or column numbers. So, in this example, you might specify Author,AuID in list data fields. You would next specify that the ValueCol was 1, thereby binding to the AuID. Finally, for aesthetic purposes, you could hide the AuID column by setting its column width to zero. After doing this, when entering a new title, the user could pick from a list of author names (and see author names when browsing through titles) when, internally, it was the id which was being stored and retrieved. See the TITLES.MAK sample which demonstrates this technique. NOTE: The list box portion of CSCombo is limited to about 5000 items, though you won't want to give the user a picklist bigger than that anyway.

Searching:

There are two forms of searching: manual and automatic. To search manually you can use the properties shared with the QPList control: StartSearch, SearchString and FoundIndex. These functions allow you to search for items in the list box portion of the CSCombo control programmatically. Note that the CBFindString routine in QPRO.DLL is much faster for this purpose and the search can be completed in a single statement.

CSCombo also provides an automatic search mode so that you can easily emulate the behavior of a number of popular Windows programs. These are specified via the AutoSearch property. There are two different forms of autosearching. First is Unique Match. This type of searching is found in Access, MS Money and Quicken. When activated, searching will take place as the user types. As soon as a unique match is found the whole selection is retrieved and placed in the edit box.

The second form of searching is Incremental, and this is like the searching behavior in WinHelp. As you search, the first matching prefix is highlighted in the list. Bear in mind that the item itself is not selected until a selection is made from the list.

If a new item is entered into the Text box portion of the control and the control loses focus, the _NewItem event is fired so you don't have to manually search here either.

Contents:

CSCombo provides a number of ways to make populating the list box portion of the control easier. First the ColDelim property lets you set the delimiter to separate Tab columns. By default is the Tab character like the standard Visual Basic combo box, but you can set it to any character. If you set it to a semicolon, for example, you could add an item to a combo box with the line:

CSCombo.AddItem "Col1;Col2"

instead of having to do this:

CSCombo.AddItem "Col1" + Chr$(9) + "Col2"

as you would have to in a standard combo box. This feature makes it very easy to load information from a delimited ASCII file as well.

Another important feature of CSCombo is the Contents dialog. When you doubleclick on Contents in the properties window you can simply enter the items into a text box, delimited by the character you specify in the ColDelim property. This way you can populate a combo box without code and even via the clipboard.

Properties:

AutoSearch	BackColor	BorderEffect
ColDelim	ColWidths	Contents
DataChanged	DataField	DataSource
DragIcon	DragMode	Dropped
Enabled	Extended	FontBold
FontItalic	FontName	FontSize
FontStrikethru	FontUnderline	ForeColor
FoundIndex	Height	HelpContextID
hWnd	Index	ItemData
Left	List	ListBoxHeight
ListCount	ListDataFields	ListDataSource
ListIndex	MousePointer	Name
NewIndex	Parent	SearchString
SelLength	SelStart	SelText
Sorted	StartSearch	Style
TabIndex	TabStop	Tag
Text	TextDisplay	Top
Value	ValueCol	Visible
Width
Events:

Change	Click
CloseUp	DblClick
DragDrop	DragOver
DropDown	GotFocus
KeyDown	KeyPress
KeyUp	LostFocus
Methods:

AddItem	Clear
Drag	Move
RemoveItem	SetFocus
ZOrder


CSOptionList

 Purpose

 Properties

 Events

 Methods

Custom control contained in CSOPT.VBX

Purpose:

CSOptionList is a convenient replacement for the Frame & Option Button combination in Visual Basic. CSOptionList combines the two into a single, easy to use, control. You draw a frame on a form and specify the option buttons that should be displayed on the frame and a string value for each. The Value property of the frame will reflect the value of the currently selected radio button, eliminating the need to walk through each option button, checking its state, as you must do with native Visual Basic controls.

Further, when bound to a data control field, the CSOption list makes it possible to store and retrieve a value which is different than the captions displayed in the option buttons.

Note: You can set separate fonts for the frame and the items as a group.  To set the font for the group items, use the ItemFontxxx properties just as you would the standard Font properties.

Properties:

Alignment	BackColor	BorderEffect
BorderStyle	Caption	Contents
DataChanged	DataField	DataSource
DragIcon	DragMode	Enabled
FontBold	FontItalic	FontName
FontSize	FontStrikethru	FontUnderline
ForeColor	Height	HelpContextID
hWnd	Index	ItemCaption
ItemFontBold	ItemFontItalic	ItemFontName
ItemFontSize	ItemFontStrikethru	ItemFontUnderline
ItemForeColor	ItemValue	Left
LeftMargin	List	ListCount
ListIndex	MousePointer	Name
Parent	Selected	ShadowColor
Spacing	TabIndex	TabStop
Tag	ThreeD	Top
TopMargin	Value	Visible
Width
Events:

Click	DblClick
DragDrop	DragOver
GotFocus	KeyDown
KeyPress	KeyUp
LostFocus
Methods:

AddItem	Drag
Move	Refresh
RemoveItem	SetFocus
ZOrder


CSVList

Purpose	Properties
Overview	Events
Visual Basic 3.0 Support	Methods
Manual mode
Custom control contained in CSVLIST.VBX

Purpose:

CSVList is a virtual list box which allows you to store more items than could fit in a normal list box.

Overview:

CSVList is a virtual list box, in that it doesn't store its own data. Instead, it provides a convenient display device for data stored elsewhere such as a database, an array or a file. When the virtual list is connected to a data control, the display of data is handled automatically. When the list is in manual mode, however, you are queried for item text via an event. This allows you to easily link the contents of the list box to any data you have access to in a line oriented fashion such as a recordoriented database, a text file or an array.

Visual Basic 3.0 Data support:

The easiest way to use the CSVList control is to connect it to a Visual Basic 3.0 data control by setting the ListDataSource property. You can specify which columns to display using the ListDataFields property or leave it blank to get all columns. In this mode, it would require only a single line of code to create a query tool. You would create a Text Box for entering SQL statements and then set the RecordSource property of the data control to the text of the text box. The results will then be displayed automatically in the virtual list. Aside from the fact that the data is being retrieved from a database, the virtual list will behave just like the standard Visual Basic list box, including scrolling and support for multiple selections. In addition, features found in our QPList control are also available in CSVList including searching, and horizontal scrolling. Finally, you can override the default column widths using the ColWidths property and even hide columns by setting the width to zero!

As with CSCombo, CSVList mimics Microsoft Access's ability to specify a bound column in the control. By specifying a column number in the ValueCol property you determine which column will be used as the Value of the virtual list when an item is selected. The standard Visual Basic list box requires you to parse the Text property, looking for the appropriate column. In the virtual list this is handled automatically. When the user makes a selection in the list, the Value property of the list box will reflect the data from the value column of the selected item.

Accordingly, it is the Value property of the list box which is bound to a data control by setting the DataSource and DataField standard properties. This configuration allows you to build a data entry field in the form of a pick list. The list would display multiple items for each row, but only the key field would be retrieved and stored in the database.

Manual Mode:

When the ListDataSource property is empty the virtual list operates manually.  Therefore, it is up to you to supply the data that will be displayed in the list as it is needed. Unlike a standard list box, you must directly set the ListCount property to the total number of items to be displayed to allow the virtual list to manage the vertical scrollbar. The virtual list doesn't actually store any data.  Instead, it prompts you for the text for a particular item as it needs to be painted, using the QueryItem event. In the QueryItem event handler, you are passed the item number and a text property that you set to the appropriate value for that item. Given this architecture, you have complete flexibility as to how you store the data  in an array, a database, or a text file. The virtual list manages the selection state of each item but the actual text is up to you. You can store your data in any format, rather than having to build Tabdelimited strings by explicitly setting the ColDelim property.

Properties:

BackColor	BorderStyle	BorderEffect
ColDelim	ColWidths	Name
DataField	DataSource	DragIcon
DragMode	Enabled	FontBold
FontItalic	FontName	FontSize
FontStrikeThru	FontUnderline	ForeColor
Height	HelpContextId	HScroll
HWnd	Index	Left
ListCount	ListDataSource	ListDataFields
ListIndex	MousePointer	MultiSelect
Selected	SelCount	ShadowColor
TabIndex	TabStop	Tag
Top	TopIndex	Value
ValueCol	Visible	Width
Events:

Click	DblClick
DragDrop	DragOver
GotFocus	KeyDown
KeyPress	KeyUp
LostFocus	MouseDown
MouseMove	MouseUp
QueryItem	Change
Methods:

Clear

Drag

Move

Refresh

SetFocus

ZOrder


AutoSearch Property
AutoSearch  (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The AutoSearch property allows you to specify the autosearching behavior of a CSCombo control.

Syntax:

[form.]CSCombo.AutoSearch[ = searchtype%]

Design Time Interface:

List Box:	0  No Search
1  Unique Match
2  Incremental Search

Data Type:

Integer (enumerated)

Usage:

Read/Write at design time and runtime

Comments:

Modeled after features in popular Windows products, the AutoSearch feature of CSCombo allows you to specify a search behavior that would otherwise require quite a bit of Visual Basic code. The two types of searching are as follows:

1.  Unique Match

Modeled after Microsoft Money and Quicken, this search type will wait until you have typed enough characters into the list box to uniquely match a string in the list. When a match is found the whole string is displayed in the edit box. The portions not typed by you are selected for easy overtyping. This search type is most often used with combo box style 0, Drop Down List, with the Sorted property set to True.

2.  Incremental Search

Modeled after the search dialog in the Windows help system, this search type will search for partial matches as you type in the list. When the user finds the string for which they search, they can simply click it from this list. This search type is commonly used with combo box style 1, Simple Combo Box, with the Sorted property set to True.

See Also:

The Style standard property, the Extended custom property, and the NewItem event.  For manual searching from code, see the FoundIndex, SearchString, and StartSearch properties.


BorderEffect Property
BorderEffect (Custom Property)

SUPPORTED BY:

CSCombo, CSOptionList, CSVList

Purpose:

The BorderEffect property lets you create a sunken or raised effect for a control by drawing an additional frame around it.

Syntax:

[form.]CtlName.BorderEffect[ = integer%]

Design Time Interface:

List Box: 	0  None
1  Raised (Convex Frame)
2  Lowered (Concave Frame)
3  Drop Shadow (CSCheckList, CSOptionList, CSVList)
4  Inset (CSCheckList, CSOptionList, CSVList)

Runtime Data Type:

Integer

Usage:

Read/Write at runtime and design time

Comments:

When this property is set to either 1 or 2, an additional border is  drawn around the control (outside any existing border drawn when BorderStyle = 1).  When BorderEffect = 1 the top and left sides are  drawn in white, and the bottom and left sides are grey.


ColDelim Property
ColDelim (Custom Property)

SUPPORTED BY:

CSCombo and CSVList

Purpose:

The ColDelim property allows you to specify the column delimiter of the list box portion of a CSCombo combo box, or a CSVList control.

Syntax:

[form.]CtlName.ColDelim[ = char$]

Design Time Interface:

Edit Window

Data Type:

String

Usage:

Read/Write at design time and runtime

Comments:

The primary purpose of the ColDelim property is to populate a list, by either the Contents dialog or at runtime with the .AddItem method. By using this property it is possible to use something other than a Tab character to separate columns. The columns will be separated by Tabs in the list itself; however, if no delimiter character is specified, the default is Tab or Chr$(9).

See Also:

The ColWidths, Contents, ListCols and ValueCol properties, and the AddItem method.


ColWidths Property
ColWidths (Custom Property)

SUPPORTED BY:

CSCombo and CSVList

Purpose:

The ColWidths array property of the CSCombo control allows you to specify the width of Tab or field (when ListDataFields is set) columns in characters.

Syntax:

[form.]CtlName.ColWidths(tabindex%)[ = nChars%]

Design Time Interface:

Popup Edit box in which to list column widths (doubleclick ColWidths)

Data Type:

Integer

Usage:

Read/Write at design time and runtime.

Comments:

Column widths are based on the width of the M character of the currently selected font.  To hide a column set ColWidths to 0.

If the control is bound to a recordset via the ListDataFields property, setting ColWidths to -1 (the default) causes the control to use the width of the data field automatically.

See Also:

The ColDelim, Contents, ListCols and ValueCol properties, and the AddItem method.


Contents
Contents  (Custom Property)

SUPPORTED BY:

CSCombo, CSOptionList and CSCheckList

Purpose:

The Contents property allows you to specify the contents of the control at design time.

Syntax:

n/a

Design Time Interface:

Popup Edit box in which you may list the default items that should appear in the control.

Data Type:

n/a

Usage:

Read/Write at design time only.

Comments:

This is a not a real property, per se; however, it allows you to specify data items that will eventually correspond to various properties of the control.

In CSCombo, the items you enter will correspond to the List() array property that you would otherwise have to add using the AddItem method in your code. The character you set in the ColDelim property will be used to parse data entered here into Tab columns at runtime.

In CSOptionList and CSCheckList, the items you enter will correspond to the ItemValue() and ItemCaption array properties. You must separate the values from the captions with a semicolon. (i.e. 16;Caption3 for a CSCheckBox item)

See Also:

The ColDelim, ColWidths, List, ListCols and ValueCol properties, and the AddItem method.


Dropped Property
Dropped (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The Dropped property specifies whether or not the list box portion of a CSCombo control (style 0 or 2) is dropped down or not.

Syntax:

[form.]CSCombo.Dropped[ = boolean%]

Design Time Interface:

none

Data Type:

Boolean Integer

Usage:

Read/Write at runtime only

Comments:

The Dropped property can be used to determine whether the list box is dropped or to directly manipulate the state of the list.

See Also:

The CloseUp, and DropDown events.


Extended Property
Extended (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The Extended property dictates whether or not a CSCombo control should use the extended User Interface.

Syntax:

[form.]CSCombo.Extended[ = boolean%]

Design Time Interface:

True/False List Box

Data Type:

Boolean Integer

Usage:

Read/Write at design time and runtime

Comments:

The extended user interface differs from the default user interface in the following ways:

1.	Clicking the static control displays the list box (Drop Down List (2) only).

2.	Pressing the Down Arrow key displays the list box (F4 is disabled).

3.	Scrolling in the static control is disabled when the item list is not visible (arrow keys 	are disabled).

See Also:

The standard Style, and the custom AutoSearch properties.


FoundIndex Property
FoundIndex (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

Returns the index of a matching item found using the SearchString property.

Syntax:

integer% = [form.]CSCombo.FoundIndex

Design Time Interface:

None

Data Type:

Integer

Usage:

Readonly at runtime, not available at design time

Comments:

After a search takes place, the index (element number) of the matching string prefix is stored in this property.  If the search is unsuccessful FoundIndex instead returns 1:

' Look for a string
CSCombo1.SearchString = Text2Find$
If CSCombo1.FoundIndex < 0 Then
Print "No more matches."
Else
Print "The text was found at item: "; CSCombo1.FoundIndex
End If


HScroll Property
HScroll (Custom Property)

SUPPORTED BY:

CSVList

Purpose:

The HScroll property determines whether or not the list can be scrolled horizontally if the items are wider than the list.

Syntax:

[form.]CSVList.HScroll[ = boolean%]

Design Time Interface:

True/False Combo Box

Data Type:

Boolean integer

Usage:

Read/Write at runtime and design time

Comments:

When the HScroll property is set to True, the list will automatically display a horizontal scrollbar if needed. When the list is bound to a data control using the ListDataSource property, the horizontal scrollbar will appear if the sum of the column widths, set with the ColWidth property, is greater than the width of the list. In manual mode when no ListDataSource has been set, the horizontal scrollbar will appear as soon as an item specified in the QueryItem event is too long to fit the list.


ItemCaption Property
ItemCaption (Custom Property)

SUPPORTED BY:

CSOptionList

Purpose:

The ItemCaption array property specifies the caption of an item within a CSOptionList.

Syntax:

[form.]CSOptionList.ItemCaption(item%)[ = Capt$]

Design Time Interface:

PopUp Edit Box

Data Type:

String

Usage:

Read/Write at design time and runtime


ItemValue Property
ItemValue (Custom Property)

SUPPORTED BY:

CSOptionList

Purpose:

The ItemValue array property refers to the value that will be set for a CSOptionList when a particular item is selected.

Syntax:

[form.]CSOptionList.ItemValue(item%)[ = data$]

Design Time Interface:

Popup Contents dialog box

Data Type:

CSOptionList: 	String

Usage:

Read/Write at design time and runtime

Comments:

Because it is actually the value of the frame which is saved into a database, this property allows the developer to set what that value will be for a given item within the frame.

For the CSOptionList control, the string value of the control (the Value property) directly corresponds to the ItemValue of the selected option button.  If, for example, the frame contains a list of months you can set each item's ItemValue property to an abbreviation for the month such as Jan, Feb, and so on.  Then when the user selects the second item at runtime, the control's Value property will return Feb.

See Also:

The Value property.


LeftMargin Property
LeftMargin (Custom Property)

SUPPORTED BY:

CSOptionList and CSCheckList

Purpose:

The LeftMargin property specifies the distance between the left edge of the frame portion of a CSOptionList or CSCheckList and the left edge of the items.

Syntax:

[form.]CSOptionList.LeftMargin[ = twips&]

[form.]CSCheckList.LeftMargin[ = twips&]

Design Time Interface:

Edit Box

Data Type:

Twips

Usage:

Read/Write at design time and runtime


ListBoxHeight Property
ListBoxHeight (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The ListBoxHeight property specifies the height of the list box portion of the CSCombo control (styles 0 and 2).

Syntax:

[form.]CSCombo.ListBoxHeight[ = ListHeight&]

Design Time Interface:

Edit Box

Data Type:

Long Integer (Twips)

Usage:

Read/Write at design time and runtime


ListCount Property
ListCount (Custom Property)

SUPPORTED BY:

CSVList

Purpose:

The ListCount property sets (Manual mode) or returns the number of items currently in a List Box.

Syntax:

[form.]CSVList.ListCount[ = integer%]

Design Time Interface:

None

Data Type:

Integer

Usage:

Read/Write at runtime only

Comments:

The ListCount property is identical to the one found in a Visual Basic list box control, except it can also be written to when using the list box in manual mode.  In manual mode, you must assign this property in order for the control to know how many items you want to be able to display.


ListDataFields Property
ListDataFields (Custom Property) [Visual Basic 3.0]

SUPPORTED BY:

CSCombo and CSVList

Purpose:

The ListDataFields property lets you specify which columns to display from the data control bound to a CSVList control, or the List Box portion of the CSCombo control.

Syntax:

[form.]CtlName.ListDataFields[ = Fields$]

Design Time Interface:

Edit Box, or Dialog Box

Data Type:

Comma delimited string

Usage:

Read/Write at design time and runtime

Comments:

If this property is null, all fields within the Table or Dynaset will be displayed.  If you wish to restrict which fields are displayed you can specify their names in a comma delimited string.  The following example causes the list to display the first name and last name fields from the table:

CSCombo1.ListDataFields = "au_fname, au_lname"

After setting ListDataFields as above, the control automatically sizes the displayed columns to the appropriate widths, unless the ColWidth property is used to set them manually.

Note that if you create fields on the fly using SQL statements such as Select au_lname+','+au_fname the resulting fields do not have names.  If you need to specify one of these fields, you can enter an ordinal position number instead of a name as follows:

CSCombo1.ListDataFields = "Company, 10"

Here, the number 10 represents the tenth field in the record which, in this case, is the derived field.  If the control cannot find a field name in the bound Table or Dynaset, it uses an ordinal position if the given field name is a number.  This also lets you specify ordinal positions instead of field names in cases where the field name isn't known, or when it is more convenient to use a number.

See Also:

The ColWidths, ListDataSource, and ValueCol properties.


ListDataSource Property
ListDataSource (Custom Property) [Visual Basic 3.0]

SUPPORTED BY:

CSCombo and CSVList

Purpose:

The ListDataSource property specifies the name of the data control to bind to a CSVList control, or the List Box portion of a CSCombo control.

Syntax:

n/a

Design Time Interface:

Drop Down List

Data Type:

String

Usage:

Read/Write at design time only

Comments:

The CSCombo control can be connected to two data controls  one for its list and one for its value. The ListDataSource property specifies the data control from which to retrieve the contents of the drop down list.

See the ListDataFields property to restrict which columns are retrieved.

See Also:

The ListDataFields and ValueCol properties.


SearchString Property
SearchString (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The SearchString property specifies a string to search for, and also triggers a search within the List portion of the control.

Syntax:

[form.]CSCombo.SearchString[ = string$]

Design Time Interface:

None

Data Type:

String

Usage:

Writeonly at runtime, not available at design time

Comments:

Setting this property causes the list box to search for a matching text prefix.  The search begins at the element defined in the StartSearch assignment, and the result of the search is stored in the FoundString property:

' Set index for search

CSCombo1.StartSearch = 0

' Look for a string

CSCombo1.SearchString = Text2Find$

If CSCombo1.FoundIndex < 0 Then

Print "No more matches."

Else

Print "The text was found at item: "; CSCombo1.FoundIndex

End If

Also see the descriptions of the FoundIndex and SearchString custom properties listed elsewhere in this section of the manual.


SelCount Property
SelCount (Custom Property)

SUPPORTED BY:

CSVList

Purpose:

The SelCount property returns the number of items currently selected in a List Box control.

Syntax:

[form.]CSVList.SelCount

Design Time Interface:

None

Data Type:

Integer

Usage:

Read only at runtime only

Comments:

Note: This property applies only if the Selection property is nonzero (multiple selections allowed). SelCount can be used to determine the number of selected items in a List Box.  A selected item is one that has been highlighted by the user, or set using the custom property Selected().  A typical use would be to find the necessary size of an array used to hold the text of the selected items:

ReDim SelData$(1 To QPList1.SelCount)

To actually determine which items have been selected, see the custom property Selected() elsewhere in this chapter.


ShadowColor Property
ShadowColor (Custom Property)

SUPPORTED BY:

CSOptionList

Purpose:

The ShadowColor property specifies the color of the shadow that is displayed in a control with BorderEffect = 3 (DropShadow).

Syntax:

[form.]CSOpt.ShadowColor[ = clr&]

Design Time Interface:

PopUp Color Dialog

Data Type:

Long (Color Value)

Usage:

Read/Write at design time and runtime


Spacing Property
Spacing (Custom Property)

SUPPORTED BY:

CSOptionList

Purpose:

The Spacing property specifies the vertical spacing between items in the control.

Syntax:

[form.]CSOptionList.Spacing[ = twips&]

Design Time Interface:

Edit Box

Data Type:

Twips

Usage:

Read/Write at design time and runtime


StartSearch Property
StartSearch (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The StartSearch property specifies the first item to search when using the SearchString property to locate a string within a CSCombo control.

Syntax:

[form.]CSCombo.StartSearch[ = integer%]

Design Time Interface:

Edit Window

Data Type:

Integer

Usage:

Read/Write at design time and runtime

Comments:

When searching a combo box's list for a string of text this property specifies the first item to consider.  While you would normally start searching at the first item in the list, you can also use this property to continue a search as follows:

CSCombo1.StartSearch = CSCombo1.FoundIndex + 1

CSCombo1.SearchString = Text2Find$

If CSCombo1.FoundIndex = CSCombo1.StartSearch Then

Print "No more matches!"

Else

Print "The text was found at item: "; CSCombo1.FoundIndex

End If

Here, StartSearch is set to one higher than the index of any previous match, so searching is continued on subsequent items.

See Also:

The descriptions of the FoundIndex and SearchString.custom properties listed elsewhere in this section.


TextDisplay Property
TextDisplay (Custom Property)

SUPPORTED BY:

CSCombo

Purpose:

The TextDisplay property determines the text which is displayed in the edit portion of a CSCombo control.

Syntax:

[form.]TextDisplay[ = integer%]

Design Time Interface:

Combo Box	0  First Visible
1  All Visible

Data Type:

Integer

Usage:

Read/Write at design time and runtime

Comments:

This is a fairly specialized property that is useful only under certain circumstances.  When the Style property of a CSCombo control is set to Drop Down List (0) or Simple Combo Box (1), the control is composed of a text box and a list box.  The TextDisplay property determines what text is displayed in the text box when a selection is made from the list when there are multiple columns of data.  If TextDisplay = 0 (default), the first visible column is displayed. Columns are hidden by setting ColWidth to 0.  If TextDisplay = 1, then all visible columns are copied to the text box.  However, since a single line text box cannot contain tabs, the text will be delimited by the delimiter set in the ColDelim property.


ThreeD Property
ThreeD (Custom Property)

SUPPORTED BY:

CSOptionList

Purpose:

The ThreeD property determines whether the control is displayed with a threedimensional appearance.

Syntax:

[form.]CSOptionList.ThreeD[ = setting%]

Design Time Interface:

True/False List Box

Data Type:

Boolean Integer

Usage:

Read/Write at design time and runtime

Comments:

The CSOptionList and CSCheckList settings are as follows:

Setting	Description
True (1)	Items within the frame are displayed with a 3D appearance.
False (0)	Items are displayed with thier normal (not 3D) appearance.


TopMargin Property
TopMargin (Custom Property)

SUPPORTED BY:

CSOptionList

Purpose:

The TopMargin property specifies the distance from the top of the control to the first item.

Syntax:

[form.]CSOptionList.TopMargin[ = twips&]

Design Time Interface:

Edit Box

Data Type:

Twips

Usage:

Read/Write at design time and runtime


Value Property
Value (Custom Property)

SUPPORTED BY:

CSCombo, CSOptionList, CSVList

Purpose:

The Value property is the default property of the control and the property used for Visual Basic 3.0 data access.

Syntax:

[form.]CSCombo.Value[ = data$]

[form.]CSOptionList.Value[ = data$]

[form.]CSVList.Value[ = data&]

Design Time Interface:

none

Data Type:

CSCombo: 	String
CSOptionList: 	String
CSVList:	String

Usage:

Read/Write at runtime only

Comments:

The Value property accounts for the fact that the "value" of a control is often not what the user sees. Very often the text displayed for the user is an alias of the real data, especially when connecting to a database.

In the CSCombo control, the Value is a string, determined by the ValueCol property.

In the CSOptionList control, the Value is the ItemValue string associated with the selected radio button in the frame.

In the CSVList control, the Value is a string, determined by the ValueCol property.

See Also:

The standard Text and DataField properties as well as the ValueCol property


ValueCol Property
ValueCol (Custom Property) [Visual Basic 3.0]

SUPPORTED BY:

CSCombo and CSVList

Purpose:

The ValueCol property of the CSCombo and CSVList controls allows you to specify the column that should be used for the Value property. In Visual Basic 3.0 ValueCol can also be used for data binding.

Syntax:

[form.]CtlName.ValueCol[ = nCol%]

Design Time Interface:

Edit box

Data Type:

Integer

Usage:

Read/Write at design time and runtime

Comments:

Very often you will want to display more information to the user than is actually stored in a database. A classic example is a State field, when you want the user to pick from a list of state names but you are actually storing a state code to save disk space. The Value property of CSCombo or CSVList can be used to set or retrieve the current item text. With the ValueCol property you can specify a particular column to match. For Access users this is the equivalent of (the default) BoundCol property of a combo box. If ValueCol is -1 then the entire row is used as the value.

See Also:

The standard DataField and custom Value properties.


CloseUp Property
CloseUp (Custom Event)

SUPPORTED BY:

CSCombo

Purpose:

The CloseUp event occurs whenever the list box portion of a CSCombo control is closed.

Syntax:

Sub CSCombo_CloseUp ()

Comments:

The list box is usually closed because a selection has been made or the user has once again clicked on the combo box button. This event doesn't occur with Style 1, Simple Combo in which the list is always visible.

See Also:

The Dropped property


DropDown Property
DropDown (Custom Event)

SUPPORTED BY:

CSCombo

Purpose:

The DropDown event occurs whenever the List Box portion of a CSCombo control becomes visible.

Syntax:

Sub CSCombo_DropDown ()

Comments:

The List Box is usually opened because the user has clicked on the combo box button. This event doesn't occur with Style 1, Simple Combo in which the list is always visible.

See Also:

The Dropped property


NewItem Property
NewItem (Custom Event)

SUPPORTED BY:

CSCombo

Purpose:

The NewItem event occurs whenever the control looses focus after the user has entered a value in a combo box which is not found in the list.

Syntax:

Sub CSCombo_NewItem (ComboText As String, KeepFocus As Integer)

Where:

ComboText is the new text entered by the user.  KeepFocus is a flag that when set to True (1) causes the control to keep the focus rather than passing it to the next control in the Tab order.

Comments:

This event makes it easier for the user to enter new data in the edit portion of the combo box. For example, the list might be populated from a database table. When the user enters a new item, the program could popup a form to enter that new item into the database table.

See Also:

The AutoSearch, and Style properties


QueryItem Property
QueryItem (Custom Event)

SUPPORTED BY:

CSVList

Purpose:

The QueryItem event provides a means by which a Visual Basic program can specify the text of an item to display in a virtual list in manual mode.

Syntax:

Sub CSVList_QueryItem (Item As Long, Text As String)

Where:

Item is the item to be displayed

Text is the text to display for that item

Comments:

This event is only fired when a virtual list is in manual mode, because no ListDataSource has been specified. Unlike most events, this one is designed to retrieve information from you rather than providing it for you. It is fired whenever an item in a virtual list needs to be displayed. Inside the event handler, you need to set Text to the string you want displayed. If you are using the virtual list to display items in a string array, your event handler might look something like this:

Sub CSVList_QueryItem (Item As Long, Text As String)

Text = MyArr$(Item)

End Sub

That's all there is to it! If the data you set into the Text parameter is delimited by a character other than the Tab, you need to specify this, using the ColDelim property.


Contacting Crescent
If you have any problems concerning the use of the CSCOMBO.VBX, CSOPT.VBX, or CSVLIST.VBX controls please contact Crescent directly as they will best be able to help you.

Crescent Software, Inc.
11 Bailey Avenue
Ridgefield, CT  06877-4505
PHONE:	203.438.5300
FAX:	203.431.4626