Copyright: Copyright ® 1996 Eric G.V. Fookes


SLIC Reference


Contents
Super Labeled Input Controls

The Super Labeled Input Controls (SLIC) package offers three sets of Delphi components organized in separate units. The first set consists of enhanced versions of the standard input controls TEdit, TMaskEdit, TMemo, TComboBox, and TListBox offering a host of useful new features. These include clipboard methods, overwrite mode, undo changes, additional events, etc. (see key features page for more details).  The second set is derived from the enhanced controls and adds the time saving auto-labeling feature. The third set consists of labeled controls derived from the standard data-aware input controls.

Topics

•	Introduction

•	Key Features

•	Installation

•	Component Overview

•	Registering

•	Unlocking the source-code file

•	Where to Obtain the latest Version

•	Distribution License

•	Legal

•	Revision History


Introduction

If the standard input controls provided with Delphi (TEdit, TMemo, TComboBox, etc.) satisfy you as they are, then perhaps you won't find these Super Labeled Input Controls very useful. If, however, you need enhanced input controls with an overwrite mode or a reliable undo method, or perhaps a context sensitive shortcut menu with clipboard and editing commands, or memo and list box controls that can format tab stops, or combo boxes that can automatically scroll to items in the list as you type, or trigger an event when an entered item does not exist in the list, or automatically add new items to the list, etcetera... then you have found the right set of components for the job.

When designing forms, adding and accurately aligning labels to input controls can often take up a lot of valuable time. The labeled input controls provided in this package take care of this task very efficiently and save you lots of time. Once you assign text to the control's label property, the label is automatically created, positioned, and linked through the FocusControl property. Various properties let you define how the label should be positioned with respect to its input control.

Take a look at the key features to find out how much you can improve your programs and save on development time!


Key Features

General

•	Input controls can insert/overwrite text and undo changes;

•	shortcut menu for input controls with Undo, Copy, Cut, Paste, etc. commands;

•	help file with all the new methods, properties, and events explained.

Labeled Components

•	Labels are automatically created and attached to input controls;

•	properties to easily and accurately position label with respect to its input control;

•	labels resize properly when forms run under different resolutions;

•	when input control is moved (at design or runtime), attached label moves with it;

•	when input control is disabled or hidden, the attached label does the same.

Enhanced Edit

•	Accepts multiple lines;

•	WordWrap property;

•	new Alignment property.

Enhanced Memo

•	New methods to indicate and set cursor position in text;

•	new method to set tab stops;

•	new very fast method to load text from a file or stream.

Enhanced ComboBox

•	Can automatically fill in a value that matches the characters you type;

•	new OnNotInList event;

•	new OnListPick event triggered whenever a new item is selected from the list or when the selection becomes null (i.e. Text = '');

•	can automatically add new items to list (as well as attached objects);

•	can automatically destroy objects in list;

•	can sort list based on data stored in item objects.

Enhanced ListBox

•	Adds horizontal scroll bar;

•	new method to set tab stops;

•	items can be displayed as selected (in bold), disabled (dimmed), or deleted (striked out);

•	new OnChange event triggered whenever a new item is selected in the list;

•	can automatically destroy objects in list;

•	can sort list based on data stored in item objects.


Installation

IMPORTANT: If you are updating from an earlier version (prior 2.0), you should be aware that one of the components has changed names. TEnhMemo is now called TEicMemo. If you have used it (instead of its labeled descendant), you will have to manually rename it in your unit (*.PAS) and form (*.DFM) files.

Make sure you don't already have components with the same name as those you are about to install (unless you are updating a previous version of these components). There are no special methods required to install the components, just the standard procedure:

1 	Copy the files EF_INPUT.DCU, EF_INPUT.DCR, EF_EDIT.DCU, EF_EDIT.DCR, EF_DBEDT.DCU, EF_DBEDT.DCR to your DELPHI\LIB directory. Keep the other package files in a location where they are easily accessible (particularly the help file SLIC.HLP, and the interface files *.INT).

2 	In Delphi 1: from the "Options" menu, select "Install Components"; in Delphi 2: from the "Component" menu, select "Install". Press the "Add" button, and then the "Browse" button. Go to the LIB directory, and select UNIT file types (*.DCU). Then select EF_INPUT.DCU and press "OK". Press "OK" for the Install Components dialog box. Repeat the same procedure for EF_EDIT.DCU and EF_DBEDT.DCU if you want to install the data-aware version of these controls (please note that EF_DBEDT.DCU requires EF_EDIT.DCU to operate).

3 	When Delphi is done compiling there will be 18 new components in the "Slic" palette.

Note: Be careful that there aren't any other units (*.DCU, *.PAS) that have the same name in your include path.

If you have registered the package, use your password to unlock the source-code file and install the PAS files instead of the DCU files.


Registering

Thank you for choosing to evaluate the Super Labeled Input Controls. This component package is shareware, and is distributed to be used for a limited trial period of 30 days (that includes any software in which these components are used). You are free to copy and distribute this software in unmodified form. After the 30 day period the software should be registered or removed from the user's system.

Advantages

When you register, you become a legal user of the product, you get access to the source code of the three units, and you no longer get the "unregistered" message window each time you start an application that makes use of the product.

Pricing

The cost of registering these Super Labeled Input Controls is only U.S. $10 (equivalent local currency accepted). Send me a note by post, fax, or E-mail, indicating the product name and version number (e.g. Super Labeled Input Controls v2.03) you want to register, your name, address and E-mail (or fax number if you cannot be reached by E-mail).

Don't forget to include your complete address information! This is how I send you the password to unlock the ZIP file with the source code. Please add U.S. $1 to cover transmission costs if you can only be contacted by fax. Add U.S. $2 if you can only be reached by snail mail.

Payment can be made the following way:

•	direct transfer to my Swiss postal account: CCP Geneva, Nr 12-51699-7

•	direct transfer to my Swiss bank account: Société de Banque Suisse (SBS), Geneva, C0-612.461.0

•	cash in U.S. dollars or Swiss francs (other currencies: bank notes only, purchase exchange rate), at your own risk!

Due to the low cost, please DO NOT send your payment in the form of a check (our banks refuse them).

Then send your registration note (and payment if cash) to...

My Address

  Eric G.V. Fookes
  Av. Eugène-Pittard 22 Ter
  CH - 1206 GENEVA
  Switzerland

  E-mail: <fookes@sc2a.unige.ch>
  Fax: +41 (0)22 - 789 58 44

What happens then?

Once your payment reaches me, I will send you the registration key that will give you access to the content of the SLIC_PAS.LCK file. This ZIP file contains the complete source-code for the components in the package. Place the *.PAS files contained in it in your DELPHI\LIB directory, delete the corresponding *.DCU files and rebuild the component library (Delphi 1: Options|Rebuild Library; Delphi 2: Component|Rebuild Library). It's that simple!


Getting the Source Code

After registering this component package, you will receive a registration key that will give you access to the source code in the locked SLIC_PAS.LCK file.

To unlock it, run the UNLOCK.EXE utility (included in this component package). Note that both files must be in the same directory. You will then be prompted to enter the password. If it is correct, the utility will create a new file called SLIC_PAS.ZIP. This is a standard ZIP file in which you will find the following three units: EF_INPUT.PAS, EF_EDIT.PAS and EF_DBEDT.PAS.

Place these *.PAS files in your DELPHI\LIB directory, delete their corresponding *.DCU files and rebuild the component library (Delphi 1: Options|Rebuild Library; Delphi 2: Component|Rebuild Library). The registered components will then replace the unregistered ones in the component palette.


Where to Obtain the latest Version

You will find the latest version of these components and others (Freeware and Shareware) on the World Wide Web from my homepage which you will find at the following address:

http://www.unige.ch/sciences/terre/geologie/fookes/delphi.htm


Distribution License

I encourage you to freely copy and distribute this Shareware version of Super Labeled Input Controls (SLIC) to any and all who are interested in obtaining a copy, including distributing it on BBS's or shareware distribution libraries. The package is subject to the following restrictions:

The Super Labeled Input Controls package must be distributed as a complete package including the following 13 Files:

1 	SLIC.HLP        	this file

2 	SLIC.TXT        	text file about the Super Labeled Input Controls

3 	EF_INPUT.DCU    	compiled unit for enhanced input components

4 	EF_INPUT.DCR    	toolbar icons

5 	EF_INPUT.INT    	interface section of the EF_INPUT.PAS file

6 	EF_EDIT.DCU     	compiled unit for labeled input controls

7 	EF_EDIT.DCR     	toolbar icons

8 	EF_EDIT.INT     	interface section of the EF_EDIT.PAS file

9 	EF_DBEDT.DCU    	compiled unit for data-aware labeled components

10 	EF_DBEDT.DCR    	toolbar icons

11 	EF_DBEDT.INT    	interface section of the EF_DBEDT.PAS file

12 	SLIC_PAS.LCK    	source code in locked ZIP file

13 	UNLOCK.EXE      	utility to unlock SLIC_PAS.LCK

If any of these files are missing, then the package is not complete and distribution is forbidden.

•	The package - including all related program files and documentation files CANNOT be modified in any way and must be distributed as a complete package, without exception.

•	You may charge a distribution fee for the package, but you must not represent in any way that you are selling the software itself.

•	You shall not use, copy, rent, lease, sell, modify, decompile, disassemble, otherwise reverse engineer, or transfer the licensed program except as provided in this agreement. Any such unauthorized use shall result in immediate and automatic termination of this distribution license.

•	You may not use/include any part of the source code, whether whole or modified, in a component package intended for distribution without my prior permission.

All rights not expressly granted here are reserved by Eric G.V. Fookes.


Legal

The author of these components accepts no responsibility for damages resulting from their use and makes no warranty or representation, either express or implied, including but not limited to, any implied warranty of merchantability or fitness for a particular purpose. These components are provided "AS IS", and you, its user, assume all risks when using them.


SLIC Components


Component Overview

The unit EF_INPUT comprises two new components and five enhanced components (TEicEdit, TEicMaskEdit, TEicMemo, TEicComboBox, TEicListbox). The components in unit EF_EDIT inherit the new properties of those in EF_INPUT and add the auto-labeling feature. The third unit EF_DBEDT, which requires EF_EDIT, offers data-aware auto-labeling controls.

The package offers four types of components:

1 	Improved standard input controls that fix some inconsistencies and omissions, and added features such as Insert/Overwrite modes, context sensitive shortcut menu, and undo capabilities.

2 	New invisible components that make it easy to control the Insert/Overwrite modes for the whole form, and the shortcut menu with commands to undo, copy, cut, paste, insert, overwrite, etc.

3 	Auto-labeling controls based on the improved standard input controls.

4 	Data-aware auto-labeling controls (in a separate unit to avoid the requirement of the Borland Database Engine when you don't use them).

Note that the "Eic" prefix used for the name of several components stands for Enhanced Input Control.

Components in EF_INPUT:

•	TEicEdit

•	TEicMaskEdit

•	TEicMemo

•	TEicComboBox

•	TEicListbox

•	TInputBoxMaster

•	TInputBoxMenu

Components in EF_EDIT:

•	TEnhLabel

•	TLblEdit

•	TLblMaskEdit

•	TLblMemo

•	TLblComboBox

•	TLblListbox

Components in EF_DBEDT:

•	TDbLblEdit

•	TDbLblMemo

•	TDbLblComboBox

•	TDbLblListbox

•	TDbInputBoxMaster


Improved Standard Controls


Enhanced Input Controls

The enhanced input controls are derived from the standard Delphi components TEdit, TMaskEdit, TMemo, TComboBox, and TListBox. They add much improved functionality through a host of new methods, properties and events. In some cases, features have been implemented to correct bugs affecting certain controls. Many of the new features are shared by the enhanced components with the exception of TEicListBox (due to the fact that it does not include an input box for text). Other new features are specific to certain components (see for example the large number of new features specific to TEicListBox).

TEicEdit, TEicMaskEdit, TEicMemo, and TEicComboBox all share the following new elements:

All the enhanced controls (except TEicListBox) offer methods to easily integrate clipboard and editing functions in menus (usually the Edit menu or context sensitive popup menus). Use the CanClear, CanCut, CanCopy, CanPaste, CanSelectAll and Modified methods to determine if the corresponding menu item should be enabled or not. Although TComboBox does not have clipboard methods, TEicComboBox does. Use Clear to delete all text in the control's input window and UndoEdit to undo any editing made by the user. When you use the ClearModifyFlag method, the current text is placed in the UndoBuffer and becomes the default text used by UndoEdit. If you want changes to be undone when the user hits the ESC key, make sure the UndoWhenEsc property is set to True.

Whenever you want to initialize controls in your program (for example each time you want to update a form with a new record), use the DefaultValue property. As a result, the undo buffer is initialized to the default text, the Modified flag is set to False, and the OnEdited event is not triggered. The OnEdited event is useful for detecting whenever the user (and not the program) makes changes to the text (UpdatingField must be False - which it is by default).

You can detect whether a control is in insert or overwrite mode by checking the OverwriteMode property. When True, the current character in the input box is always selected (unless the user has extended the selection) and is overwritten by text entered through the keyboard. If you add the invisible InputBoxMaster component to your form, then insert/overwrite mode can change simultaneously in all the enhanced controls on the form whenever the user presses the INS key. The DispatchInsMode property of the focused control must be True for this to happen.

InputBoxMaster is also very useful if you want to automatically add a special shortcut menu to all the input controls on the form (except list boxes, radio buttons and check boxes) with editing and clipboard commands. Set its UseContextMenu property to True to enable this useful feature.

Methods

•	procedure RunTimeLoaded;

•	procedure Copy2Printer;

•	procedure ToggleInsMode;

•	procedure UndoEdit;

•	procedure Clear;

•	function CanClear:Boolean;

•	function CanCut:Boolean;

•	function CanCopy:Boolean;

•	function CanPaste:Boolean;

•	function CanSelectAll:Boolean;

•	procedure ClearModifyFlag;

Properties

•	property InputBoxMaster:TInputBoxMaster

•	property UpdatingField:Boolean

•	property UndoBuffer:TUndoBuffer

•	property DefaultValue:string (PChar with TEicMemo)

•	property Value:string (PChar with TEicMemo)

Published Properties

•	property DispatchInsMode:Boolean

•	property OverwriteMode:Boolean

•	property UndoWhenEsc:Boolean

Events

•	property OnEdited:TNotifyEvent


TEnhLabel

TEnhLabel is derived from TLabel and is automatically created by the Labeled Input Controls when text is assigned to their LabelText property.

When clicked on, the label component will change the focus to its FocusControl if it is enabled. Also, TEnhLabel turns dark gray (by default) when disabled. The color is determined by the DisabledColor property. Normal labels become medium gray and cannot be distinguished from the standard form background (an oversight in Delphi or Windows). The Disabled property is used instead of the standard Enabled property to enable this feature.

Properties

•	property Disabled:Boolean

Published Properties

•	property DisabledColor:TColor


TEnhLabel Declaration


Disabled

property Disabled:Boolean read FDisabled write SetDisabled;

Use this property instead of the standard Enabled property. When Disabled is True, the label turns dark gray (by default) and is usually still visible on the form.

Note that if you set the Enabled property to False, labels become medium gray and usually cannot be distinguished from the form color. They therefore become invisible instead of appearing shaded.

See also:

•	DisabledColor


DisabledColor

property DisabledColor:TColor read FDisabledColor write SetDisabledColor default clBtnShadow;

Use this property if you want to choose a different color for the label when it is disabled. The default color is dark gray (or clBtnShadow).

See also:

•	Disabled


TEicEdit

TEicEdit allows multiple lines and word wrapping like memo controls. It also offers an Alignment property which is particularly useful for displaying numbers right aligned.

Published Properties

•	property Alignment:TAlignment

•	property WordWrap:Boolean

It also has the new component elements of the other Enhanced Input Controls.


TEicEdit Declaration


Alignment

property Alignment:TAlignment read FAlignment write SetAlignment

         default taLeftJustify;

The Alignment property aligns text in the TEicEdit component.

These are the possible values:

taLeftJustify	Align text to the left side of the control

taCenter	Center text horizontally in the control

taRightJustify	Align text to the right side of the control


WordWrap

property WordWrap:Boolean read FWordWrap write SetWordWrap;

The WordWrap property determines if text in the input window wraps at the right margin so that it fits in the control.

The default value is False.


TEicMemo

TEicMemo lets you configure tab stops through the new SetTabStops method. You can load larger amounts of text much faster from files or streams with the FileToMemo and StreamToMemo methods. TMemo will often crash your program if you attempt to load a file that is too large for the control. FileToMemo won't; instead you can retrieve the function result to determine whether it was able to load the full file or only part of it.

You can retrieve or set the cursor position in the memo text with the CursorRow and CursorCol properties. If you need to retrieve or set both coordinates, use the GetCursorPos and SetCursorPos methods for improved performance. If you want to update a status bar with the cursor coordinates, you can use the OnCursorMove event which is triggered each time the cursor moves.

Methods

•	procedure SetTabStops(Tabs:array of Word);

•	procedure MakeTextWrap;

•	procedure GetCursorPos(var Row,Col:Integer);

•	procedure SetCursorPos(Row,Col:Integer);

•	procedure SetSelStart(AValue:Integer);

•	procedure AssignDefaultValue(Source:TPersistent);

•	procedure AssignValue(Source:TPersistent);

•	function FileToMemo(const FileName:string):Integer;

•	function StreamToMemo(Stream:TStream):Integer;

•	procedure ScrollToCaret; (only Delphi 2)

Properties

•	property UpdatingLines:Boolean

•	property DefaultValueText:string

•	property ValueText:string

•	property CursorRow:Integer

•	property CursorCol:Integer

Events

•	property OnCursorMove:TNotifyEvent

It also has the new component elements of the other Enhanced Input Controls.


TEicMemo Declaration


CursorCol

property CursorCol:Integer read GetCursorCol write SetCursorCol;

Use this property to read or set the current cursor column position in the memo text. The function returns 1 when it is at the beginning of the line.

See also:

•	GetCursorPos

•	CursorRow


CursorRow

property CursorRow:Integer read GetCursorRow write SetCursorRow;

Use this property to read and set the current cursor row position in the memo text. The function returns 1 when the cursor is on the first line.

See also:

•	GetCursorPos

•	CursorCol


DefaultValueText

property DefaultValueText:string read GetDefaultValueText write SetDefaultValueText;

Use this method to set the default string value for the TEicMemo input control (and its descendants). Doing so will trigger the OnChange event, but not the OnEdited event. Both the Edit window text and the UndoEdit buffer will contain the assigned value. Modifying the Text, Lines or Value properties after this and then calling the UndoEdit method will restore the default string value.

See also:

•	DefaultValue

•	ValueText


FileToMemo

function FileToMemo(const FileName:string):Integer;

This method is faster than LoadFromFile and doesn't fail if the file is larger than the memo size limit (32Kb for 16-bit version and about 61Kb under Win95). Unlike LoadFromFile, however, this method does not check if each end-of-line break is composed of the correct control characters (#13#10) used with DOS/Windows systems. Unless your text files may originate from other systems, this is no issue.

Possible values returned are:

•	0 = Failed

•	1 = Success

•	2 = Partially loaded (was larger than memo size limit)


GetCursorPos

procedure GetCursorPos(var Row,Col:Integer);

Use this procedure to read the current cursor position in the memo text. Row returns 1 when the cursor is on the first line, and Col returns 1 when it is at the beginning of the line.

See also:

•	CursorRow

•	CursorCol


MakeTextWrap

procedure MakeTextWrap;

This method ensures that word wrap will really be used when activated. MakeTextWrap sets the WordWrap property to True and removes the horizontal scroll bar if there is one.

NB: When the memo component has a horizontal scroll bar, WordWrap has no effect.


OnCursorMove

property OnCursorMove:TNotifyEvent read FOnCursorMove write FOnCursorMove;

This event is triggered whenever the caret changes position in the TEicMemo control's window. You can use it to update a status bar with the caret column and row position.

See also:

•	GetCursorPos

•	CursorRow

•	CursorCol


ScrollToCaret

procedure ScrollToCaret;

This method is only available under Delphi 2 and higher. Use it to make the Memo window scroll to the caret position in order to make it visible. This method is not needed under Delphi 1 as scrolling to the caret is done automatically when it moves out of the displayed area.


SetCursorPos

procedure SetCursorPos(Row,Col:Integer);

Use this method to change the cursor position in the TEicMemo text.

See also:

•	GetCursorPos

•	CursorRow

•	CursorCol


SetSelStart

procedure SetSelStart(AValue:Integer);

If you want to trigger the OnCursorMove event, use this method instead of assigning a value directly to the SelStart property.


StreamToMemo

function StreamToMemo(Stream:TStream):Integer;

This method is faster than LoadFromStream and doesn't fail if the data is larger than the memo size limit (32Kb for 16-bit version and about 61Kb under Win95). Unlike LoadFromStream, however, this method does not check if each end-of-line break is composed of the correct control characters (#13#10) used with DOS/Windows systems. Unless your data uses different control characters, this is no issue.

Possible values returned are:

•	0 = Failed

•	1 = Success

•	2 = Partially loaded (was larger than memo size limit)


ValueText

property ValueText:string read GetValueText write SetValueText;

Use this method to modify the current value for the TEicMemo (and its descendants) input control. Doing so will trigger both the OnChange and the OnEdited event (unless you set the UpdatingField property to True). Calling the UndoEdit method after this will restore the default value.

See also:

•	DefaultValueText

•	Value


TEicComboBox

TEicComboBox adds the CutToClipboard, CopyToClipboard, and PasteFromClipboard methods to provide the same clipboard functionality as the other standard input controls.

Several new features let you control how a user can choose or add items to the control. For example, when the LimitToList property is True, the user can only enter an item that exists in the list. If AllowNull is True, the user can also leave the control empty. If at any time the user enters text that is not in the list, the OnNotInList event is triggered. You can use this event to display an error message or add the new item to the list. If AddNewToList is True, new text will automatically be added to the list. Use the AddNewToStart property to add new items to the beginning of the list instead of the end. If AutoExpand is True, entering text in the edit window will automatically scroll to and highlight the first item that matches the input.

You can use the OnListPick event to detect every time the user selects a new item from the list. If AutoPickItem is True, the OnListPick event is also triggered when a new item is scrolled to as a result of the AutoExpand feature; if it is False, the user will have to press the ENTER key or shift the focus to another control to initiate the event. Use the PickItemIndex method when you want to programmatically change the selected item and also trigger the OnListPick event.

By default, objects that are associated with text items in the list are not destroyed when the list is cleared or destroyed. By setting DestroyObjects True, TEicComboBox will take care of destroying an item's object whenever it is deleted. Use the ClearList method when you want to empty the list. Note that when renaming a string item, Windows first destroys it. This is problematic when DestroyObjects is True and can result in serious GPF exceptions. Use the ChangeText method to avoid this type of problem.

Although the standard TComboBox lets you sort items based on the list's string element, you may sometimes want to sort items based on other criteria. If these criteria are stored in the object part of the list, you can use the OnCompare event to control the new sorting order. Use SortObjects to sort your list or AddSortObject when you are adding items to an empty or "object" sorted list.

Methods

•	function AddSortObject(const S:string; AObject:TObject):Integer;

•	procedure SortObjects;

•	procedure ChangeText(I:Integer; const NewText:string);

•	procedure ClearList;

•	function TakeEnter:Boolean;

•	procedure PickItemIndex(I:Integer);

•	procedure CutToClipboard;

•	procedure CopyToClipboard;

•	procedure PasteFromClipboard;

Properties

•	property Modified:Boolean

•	property Focused:Boolean

•	property DefaultIndex:Integer

Published Properties

•	property AddNewToList:Boolean

•	property AddNewToStart:Boolean

•	property AllowNull:Boolean

•	property AutoExpand:Boolean

•	property AutoPickItem:Boolean

•	property DestroyObjects:Boolean

•	property LimitToList:Boolean

•	property ReadOnly:Boolean

Events

•	property OnCompare:TCompareEvent

•	property OnListPick:TNotifyEvent

•	property OnNotInList:TAddToListEvent

It also has the new component elements of the other Enhanced Input Controls.

Note that with Delphi 1 programs running under Windows 95, the shortcut menu will not popup when you click inside the edit window of this component (except the arrow button). Instead, Windows will display its own popup window. This is due to a bug in Delphi 1 for which, unfortunately, I have not found a solution yet.


TEicComboBox Declaration


AddNewToList

property AddNewToList:Boolean read FAddNewToList write SetAddNewToList;

When True, new items are automatically added to the list unless you cancel the process through the OnNotInList event. When false, new items can only be added to the list if you allow it when using the OnNotInList event.

The AddNewToList property has no effect if LimitToList is True.

See also:

•	AddNewToStart

•	LimitToList

•	OnNotInList


AddNewToStart

property AddNewToStart:Boolean read FAddNewToStart write FAddNewToStart;

When this property is True, items added to the list as a result of the OnNotInList event will be inserted at the beginning of the list instead of appended at the end of it.

See also:

•	AddNewToList

•	OnNotInList


AutoExpand

property AutoExpand:Boolean read FAutoExpand write FAutoExpand Default True;

When this property is True, entering text in the edit window will automatically scroll to and highlight the first item that matches the input. Pressing the Delete key removes the added text. Note that when an item is selected this way, it does not trigger the OnListPick event (unless AutoPickItem is True). However, the event is triggered when you press the Enter key or move the focus to another control.

See also:

•	AutoPickItem

•	TakeEnter

•	OnListPick


AutoPickItem

property AutoPickItem:Boolean read FAutoPickItem write FAutoPickItem Default True;

AutoPickItem is a published property of TEicComboBox. This property is only used when AutoExpand is True. When AutoPickItem is True, an OnListPick event is triggered whenever a new list item is selected through the expand feature. If it is False, expanded input text does not trigger the OnListPick event until the Enter key is pressed to confirm the selection.

See also:

•	AutoExpand

•	OnListPick


Focused

property Focused:Boolean read FIsFocused write FIsFocused;

Use this property instead of the HasFocus method Delphi provides. HasFocus does not always tell the truth with ComboBox components!


LimitToList

property LimitToList:Boolean read FLimitToList write SetLimitToList;

When this property is True, text in the edit window must always correspond to an item in the list. If not, the OnNotInList event is triggered. You can use the event to add the item to the list or display a message. If there is no text, the OnNotInList event is not triggered.

The AddNewToList property has no effect if LimitToList is True.

See also:

•	OnNotInList

•	AddNewToList


OnNotInList

property OnNotInList:TAddToListEvent read FOnNotInList write FOnNotInList;

This event is triggered whenever the input is checked (after pressing the Enter key or shifting the focus to another control) and the item entered is not in the list. You can use the event to add the item to the list or display a message.

See also:

•	TAddToListEvent

•	LimitToList

•	AddNewToList

•	AddNewToStart


TAddToListEvent

TAddToListEvent = procedure (Sender:TObject; var NewText:string; var NewObject:TObject; var Accept:Boolean) of object;

This event is triggered whenever the TEicComboBox input is checked (after pressing the Enter key or shifting the focus to another control) and the item entered is not in the list. You can use the event to add the NewText to the list (NB: not necessary if AddNewToList is True) or display a message. If AddNewToList is True and you don't want to add the NewText, set Accept to False.

If you want to add NewText to the list together with an object, then assign that object to NewObject.


TakeEnter

function TakeEnter:Boolean;

Use this method if you want to simulate the Enter key programmatically. This will make the TEicComboBox check the content of the edit window and trigger events such as OnListPick or OnNotInList if necessary. The function returns True if the combo box input text required processing.


TEicListbox

TEicListBox displays the horizontal scroll bar and can align tabbed items. You can configure tab stops through the SetTabStops method and set the horizontal scroll width through the ScrollWidth property. If AutoAdjustScrollWidth is True, TEicListBox will automatically calculate the scroll width value so that the longest item is not clipped from the viewable area. Unfortunately, this feature is only accurate with the System font.

You can use the OnChange event to detect every time the user selects a new item from the list. Use the PickItemIndex method when you want to programmatically change the selected item and also trigger the OnChange event. When AllowNull is True and MultiSelect is not enabled, clicking on a selected Item will deselect it if AllowToggle is True.

By default, objects that are associated with text items in the list are not destroyed when the list is cleared or destroyed. By setting DestroyObjects True, TEicListBox will take care of destroying an item's object whenever it is deleted. Use the ClearList method when you want to empty the list. Note that when renaming a string item, Windows first destroys it. This is problematic when DestroyObjects is True and can result in serious GPF exceptions. Use the ChangeText method to avoid this type of problem.

Although the standard TListBox lets you sort items based on the list's string element, you may sometimes want to sort items based on other criteria. If these criteria are stored in the object part of the list, you can use the OnCompare event to control the new sorting order. Use SortObjects to sort your list or AddSortObject when you are adding items to an empty or "object" sorted list.

Through the OnAskItemAttr event, you can control the aspect of each item (bold, dimmed, striked out) as it is displayed in the list box.

Methods

•	procedure RunTimeLoaded; dynamic;

•	function AddSortObject(const S:string; AObject:TObject):Integer;

•	procedure SortObjects;

•	procedure ChangeText(I:Integer; const NewText:string);

•	procedure PickItemIndex(I:Integer);

•	procedure ClearList;

•	procedure SetTabStops(Tabs:array of Word);

•	function Text:string;

•	procedure UndoEdit;

Properties

•	property DefaultIndex:Integer

•	property Modified:Boolean

Published Properties

•	property AllowNull:Boolean

•	property AllowToggle:Boolean

•	property AutoAdjustScrollWidth:Boolean

•	property DestroyObjects:Boolean

•	property ReadOnly:Boolean

•	property ScrollWidth:Integer

Events

•	property OnAskItemAttr:TOnAskItemAttr

•	property OnCompare:TCompareEvent

•	property OnChange:TNotifyEvent

•	property OnModified:TNotifyEvent


TEicListBox Declaration


AllowToggle

property AllowToggle:Boolean read FAllowToggle write FAllowToggle;

AllowToggle is a published property of TEicListBox. When True, this feature lets a user toggle a list box selection on and off just by clicking on it. This property is only used when MultiSelect is False and AllowNull is True.

See also:

•	AllowNull


AutoAdjustScrollWidth

property AutoAdjustScrollWidth:Boolean read FAutoAdjustScrollWidth write SetAutoAdjustScrollWidth default True;

When True, the extent of horizontal scrolling is estimated and the horizontal scroll bar is automatically adjusted. Note that the method used to estimate the list width can be relatively inaccurate depending on the font used for the list box. Values are only accurate when the System font is used. The same applies to tab settings. This seems to be due to a bug in Windows. You may prefer to use the ScrollWidth property instead.


OnAskItemAttr

property OnAskItemAttr:TOnAskItemAttr read FOnAskItemAttr write FOnAskItemAttr;

This event is triggered each time a list box line has to be drawn or redrawn. You can use this event to determine the appearance of the line by setting the appropriate TItemAttr attribute to the event parameter.

See also:

•	TOnAskItemAttr

•	TItemAttr


OnModified

property OnModified:TNotifyEvent read FOnModified write FOnModified;

The OnModified event of TEicListbox is triggered whenever the selection changes but not when the field is being updated (UpdatingField = True). This event is triggered just after the OnChange event.

See also:

•	OnChange


ScrollWidth

property ScrollWidth:Integer read GetScrollWidth write SetScrollWidth;

Lets you define the extent of horizontal scrolling in the TEicListBox control. This property is ignored if AutoAdjustScrollWidth is True.

See also:

•	AutoAdjustScrollWidth


Text

function Text:string;

This TEicListbox method returns the text of the selected item. When there is no item selected, it returns an empty string.


TItemAttr

TItemAttr = set of (iaSelected,iaDisabled,iaDeleted);

This data type is used by the OnAskItemAttr event. The values determine the appearance of each line as it is displayed in the list box.

iaSelected

This attribute will display the line in bold.

iaDisabled

This attribute will display the line in gray.

iaDeleted

Lines displayed with this attribute will be striked out.


TOnAskItemAttr

TOnAskItemAttr = procedure (Sender:TObject; Index:Integer; var ItemAttr:TItemAttr) of object;

This event is triggered each time a list box line has to be drawn or redrawn. You can use this event to determine the appearance of the line by setting the appropriate value to the ItemAttr parameter.

See also:

•	TItemAttr


Enhanced Methods and Properties


AddSortObject

function AddSortObject(const S:string; AObject:TObject):Integer;

Use this method to add new strings with objects in a sorted order. If the list already contains items, make sure they have been sorted with respect to its objects. Note that the list will not be sorted if you haven't assigned a procedure to the OnCompare event. Note also that the standard Sorted property must be False before you use this method (Sorted is only valid when sorting is done on the string part of the list).

See also:

•	SortObjects

•	OnCompare


AllowNull

property AllowNull:Boolean read FAllowNull write FAllowNull default True;

When True, the control may have no item selected from its list (ItemIndex = -1). When False, the control will attempt to automatically select an item in the list (if available) so that, whenever possible there is always an ItemIndex greater than -1. Note that this feature cannot be enforced when you manipulate the ItemIndex programmatically.

See also:

•	AllowToggle


AssignDefaultValue

procedure AssignDefaultValue(Source: TPersistent);

This method is similar to the control's Lines.Assign method. Use AssignDefaultValue when you want to assign default text to the memo component and trigger the OnChange event.

See also:

•	AssignValue

•	DefaultValue


AssignValue

procedure AssignValue(Source:TPersistent);

This method is similar to the control's Lines.Assign method. Use AssignValue when you want to assign lines of text to the memo component and trigger the OnChange and OnEdited event.

See also:

•	AssignDefaultValue

•	Value


CanClear

function CanClear:Boolean;

Use this function to check if you can clear the content of the component's edit window. The function will return false if the control is ReadOnly or if there is no text to clear.

See also:

•	Clear


CanCopy

function CanCopy:Boolean;

Use this function to check if you can copy text from the component's edit window to the clipboard. The function will return false if there is no text to copy.

See also:

•	CopyToClipboard


CanCut

function CanCut:Boolean;

Use this function to check if you can cut text from the component's edit window to the clipboard. The function will return false if the control is ReadOnly or if there is no text to clear.

See also:

•	CutToClipboard

•	ReadOnly


CanPaste

function CanPaste:Boolean;

Use this function to check if you can paste text from the clipboard to the component's edit window. The function will return false if the control is ReadOnly or if there is no text to paste.

See also:

•	PasteFromClipboard


CanSelectAll

function CanSelectAll:Boolean;

Use this function to check if you can select all the text in the component's edit window. The function will return false if there is no text or if all the text is already selected.


ChangeText

procedure ChangeText(I:Integer; const NewText:string);

The ChangeText method has been added to TEicComboBox and TEicListBox to avoid potential trouble when renaming list items. When renaming items and DestroyObjects is True, you should use this method instead of directly accessing the Items.Strings array. Renaming a string item directly causes the associated object to be destroyed.

When a list item is renamed, Windows temporarily stores the associated object pointer and then actually destroys the list item before inserting the new string. In doing so, Windows sends a WM_DESTROY message to the control. When DestroyObjects is True, this message will actually result in the destruction of  the associated object. As a result, the new item will potentially contain an invalid pointer which will ultimately lead to a GPF exception.

Parameters: I is the item index and NewText is the text to use at that position in the list.

See also:

•	DestroyObjects


Clear

procedure Clear;

This methods deletes the content of the component's edit window.

See also:

•	CanClear


ClearList

procedure ClearList;

Use this method to clear all the items in the list. If the DestroyObjects property is True, then all assigned list objects are destroyed during this process.

See also:

•	DestroyObjects


ClearModifyFlag

procedure ClearModifyFlag;

Use this method when you want to set the Modified flag to False and make the text that is currently in the component's edit window the default text.

See also:

•	DefaultValue

•	Modified

•	UndoEdit

•	UpdatingField


Copy2Printer

procedure Copy2Printer;

This methods copies the content of the component's edit window to the printer.


CopyToClipboard

procedure CopyToClipboard;

Use this method to copy the control's selected text to the clipboard.

See also:

•	CanCopy

•	CutToClipboard

•	PasteFromClipboard


CutToClipboard

procedure CutToClipboard;

The CutToClipboard method copies the selection to the clipboard and deletes it from the component's edit window.

See also:

•	CanCut

•	CopyToClipboard

•	PasteFromClipboard


DefaultIndex

property DefaultIndex:Integer read GetDefaultIndex write SetDefaultIndex;

Use this method to set the default index value for the input control. Doing so will trigger the OnChange event (if the value is different from ItemIndex), but not the OnEdited event (in the case of TEicComboBox). The OnChange event also triggers the TEicComboBox OnListPick event. Both the Edit window text and the UndoEdit buffer will contain the item represented by the ItemIndex. Modifying the Text, Value or ItemIndex properties after this and then calling the UndoEdit method will restore the default value.

See also:

•	OnListPick (TEicComboBox only)

•	UndoEdit


DefaultValue

property DefaultValue:string read GetDefaultValue write SetDefaultValue;

For TEicMemo and its descendants, the property is as follows:

property DefaultValue:PChar read GetDefaultValue write SetDefaultValue;

Use this method to set the default value for the input control. Doing so will trigger the OnChange event, but not the OnEdited event. Both the Edit window text and the UndoEdit buffer will contain the assigned value. Modifying the Text or Value properties after this and then calling the UndoEdit method will restore the default value.

Note that assigning a value to the Text property at design time has the same effect as using the DefaultValue property.

See also:

•	UndoEdit

•	Modified

•	ClearModifyFlag

•	UpdatingField

•	DefaultValueText (for TEicMemo )

•	DefaultIndex (for TEicComboBox and TEicListBox )


DestroyObjects

property DestroyObjects:Boolean read FDestroyObjects write FDestroyObjects;

Set this property to True if you would like to let TEicComboBox or TEicListbox take care of the destruction of objects in its list whenever the component is destroyed or when items are deleted from its list. Beware that renaming items can cause objects to be destroyed when this property is True. See ChangeText for more information.

See also:

•	ChangeText


DispatchInsMode

property DispatchInsMode:Boolean read FDispatchInsMode write FDispatchInsMode Default True;

When this property is True and you press the Insert key, it will notify the InputBoxMaster (if there is one on the form), who will then toggle the insert/overwrite mode of all the enhanced input controls. When this property is false, hitting the Insert key when the component has the focus will not change the insert/overwrite mode of the other components.

If there is no TInputBoxMaster component on the form, this property will have no effect.

See also:

•	ToggleInsMode

•	OverwriteMode

•	TInputBoxMaster


InputBoxMaster

property InputBoxMaster:TInputBoxMaster read FInputBoxMaster write FInputBoxMaster;

This property is used to point to the TInputBoxMaster component if there is one on the form. This property is used internally and is probably not useful to you.


Modified

property Modified:Boolean read FModified write FModified;

Use this property to check if the text in the control's edit window or the list box item index has been changed by the user.

See also:

•	ClearModifyFlag

•	UndoEdit

•	UpdatingField


OnChange

property OnChange:TNotifyEvent read FOnChange write FOnChange;

This event is triggered whenever the content of the Text, Value, DefaultValue or the ItemIndex (through PickItemIndex) property changes.

See also:

•	OnEdited

•	OnListPick

•	PickItemIndex


OnCompare

property OnCompare:TCompareEvent read FOnCompare write FOnCompare;

The OnCompare event is used and required by the SortObjects method. Use this event to compare and return which of the two objects is greater. Make sure you test for nil values if your control's list hasn't got objects assigned to every item.

Example:

Suppose you have used the following type of object in your list...

type
   TMyObject = class
    private
       FAge,FWeight:Integer;
    public
       property Age:Integer read FAge write FAge;
       property Weight:Integer read FWeight write FWeight;
   end;

Now, if you want to sort your list using age as your criteria, here is the code you should assign to the OnCompare event...

procedure TForm1.EicListbox1Compare(Sender, O1, O2: TObject;
   var Value: TCompareResult);
begin
   if TMyObject(O1).Age = TMyObject(O2).Age then
      Value := crEqual else
   if TMyObject(O1).Age > TMyObject(O2).Age then
      Value := crFirstIsGreater
   else
      Value := crFirstIsSmaller;
end;

See also:

•	AddSortObject

•	SortObjects

•	TCompareEvent

•	TCompareResult


OnEdited

property OnEdited:TNotifyEvent read FOnEdited write FOnEdited;

The OnEdited event is triggered by the Change method just before the OnChange event and only when the UpdatingField property is False. It is activated when you change the Text or Value properties but not the DefaultValue property.


OnListPick

property OnListPick:TNotifyEvent read FOnListPick write FOnListPick;

This event is triggered whenever a new item is selected from the list or when the selection becomes null (i.e. Text = ''), but not when ItemIndex is modified programmatically. If you want the OnListPick event triggered in this case, use the PickItemIndex method instead of  ItemIndex. OnListPick is also triggered when the DefaultValue or DefaultIndex properties are modified. Use the UpdatingField property to check if the event is triggered by a change to the default value (it will return True in this case).

See also:

•	PickItemIndex

•	AutoPickItem

•	UpdatingField


OverwriteMode

property OverwriteMode:Boolean read FOverwrite write SetOverwrite;

When OverwriteMode is True, the input control is in overwrite mode and typing text will overwrite the characters at the caret position. When False, the insert mode is active.

See also:

•	ToggleInsMode

•	DispatchInsMode


PasteFromClipboard

procedure PasteFromClipboard;

Use this method to paste text stored in the clipboard to the control's edit window.

See also:

•	CanPaste

•	CopyToClipboard

•	CutToClipboard


PickItemIndex

procedure PickItemIndex(I:Integer);

Use this method when you want to change ItemIndex programmatically and need the OnChange and OnListPick events triggered. The parameter "I" receives the value you want to set to ItemIndex. A value of -1 will clear the control's edit window, 0 will select the first item in the list, etc.

See also:

•	OnListPick

•	OnChange


ReadOnly

property ReadOnly:Boolean read FReadOnly write SetReadOnly;

Use this property to check or change the input control's read-only status. If set to True, the user will not be able to change text in the component's edit window or the selected item (list boxes).


RunTimeLoaded

procedure RunTimeLoaded;

The RunTimeLoaded procedure is called by the Loaded method when a form is loaded to memory from a form file (DFM). You should only use this method if you make a call to the component's constructor at runtime. Execute this method only after you have set any of the published properties or events. If you create the component at runtime and omit the call to this method, then the component will not necessarily work as required.


SetTabStops

procedure SetTabStops(Tabs:array of Word);

Use this method to set the memo text or listbox tabstops to those specified in the Tabs open array.  Tabstops are measured in pixels and must be defined in ascending order.

E.g. SetTabStops([16,35,50]);


SortObjects

procedure SortObjects;

This method lets you sort the item list of TEicComboBox and TEicListbox based on the associated item objects instead of the strings. Since this method knows nothing of the nature of your objects, you must use the control's OnCompare event to indicate how objects evaluate during each comparison. If the standard Sorted property is True, the SortObjects method will set it to False (Sorted is only valid when sorting is done on the string part of the list).

SortObjects uses the QuickSort algorithm.

See also:

•	AddSortObject

•	OnCompare


TCompareEvent

TCompareEvent = procedure (Sender:TObject; O1,O2:TObject; var Value:TCompareResult) of Object;

This type of event is triggered by the SortObjects method available with TEicComboBox and TEicListbox. You should make a comparison between the two objects O1 and O2 and assign the appropriate result to Value. See TCompareResult for possible values.

See also:

•	OnCompare

•	SortObjects

•	TCompareResult


TCompareResult

TCompareResult = (crEqual, crFirstIsGreater, crFirstIsSmaller);

This data type is used by the OnCompare event to return the result of a comparison between two objects. Use crEqual if O1 = O2, crFirstIsGreater if O1 > O2, and crFirstIsSmaller if O1 < O2.

See also:

•	OnCompare

•	TCompareEvent

•	SortObjects


ToggleInsMode

procedure ToggleInsMode;

This method toggles the insert/overwrite status of the input control.

See also:

•	OverwriteMode


UndoBuffer

property UndoBuffer:TUndoBuffer read FUndoBuffer;

Read-only property that points to the TUndoBuffer object.


UndoEdit

procedure UndoEdit;

This method replaces the content of the controls edit window with the text assigned to the DefaultValue property. With list boxes, the default item is selected.

See also:

•	ClearModifyFlag

•	UpdatingField


UndoWhenEsc

property UndoWhenEsc:Boolean read FUndoWhenEsc write FUndoWhenEsc;

Use this property to determine whether the Escape key triggers a call to the UndoEdit method of the focused control. Pressing the Escape key when this property is set to False will not undo the controls modified text.

See also:

•	DefaultValue

•	Modified

•	UndoEdit


UpdatingField

property UpdatingField:Boolean read FUpdatingField write SetUpdatingField;

When this property is True and text is assigned to the Text or Value property, the OnEdited event is not called. Setting this property to False will clear the Modified flag and copy the text to the UndoEdit buffer. This property is used internally but can be useful in some cases to check its status when the OnChange or OnListPick event is triggered.

See also:

•	DefaultValue

•	Modified

•	UndoEdit

•	OnChange

•	OnListPick


UpdatingLines

property UpdatingLines:Boolean read FUpdatingLines write SetUpdatingLines;

Use this property instead of the Lines.BeginUpdate/EndUpdate methods. When set to True, the property makes a call to the BeginUpdate method and ensures that the OnChange (and OnEdited if UpdatingField is False) events are not triggered until UpdatingLines is set to False again (this calls the EndUpdate method).

See also:

•	OnChange

•	OnEdited

•	UpdatingField


Value

property Value:string read GetEditBoxText write SetEditBoxText;

For TEicMemo and its descendants, the property is as follows:

property Value:PChar read GetEditBoxText write SetEditBoxText;

Use this method to modify the current value for the input control. Doing so will trigger both the OnChange and the OnEdited event (unless you set the UpdatingField property to True). Calling the UndoEdit method after this will restore the default value.

This property is similar to the standard Text property, but unlike modifications to Text, it will always trigger the OnChange event, and the OnEdited event if the UpdatingField property is False. With TEicMemo components, the Value property is of type PChar, not String as with the Text property.

See also:

•	ValueText (for TEicMemo )

•	PickItemIndex (for TEicComboBox and TEicListbox )

•	DefaultValue

•	Modified


TUndoBuffer

TUndoBuffer is a new object (not a component) derived from TObject. It is used by all the enhanced input controls to store and retrieve their default value.

Methods

•	procedure ClearUndoBuffer;

Properties

•	property UndoPChar:PChar

•	property UndoString:string


ClearUndoBuffer

procedure ClearUndoBuffer;

Use this method to clear the content of the undo buffer.


UndoPChar

property UndoPChar:PChar read FBuffer write SetUndoBuffer;

Use this property to set or retrieve the buffer content using data of type PChar. Assigning a PChar variable to UndoPChar produces a copy of it.

See also:

•	UndoString


UndoString

property UndoString:string read GetUndoString write SetUndoString;

Use this property to set or retrieve the buffer content using data of type String.

See also:

•	UndoPChar


Controls with labels


Labeled Input Controls

TLblEdit, TLblMaskEdit, TLblMemo, TLblComboBox, TLblListbox inherit all the new features of their enhanced controls and all share the new elements listed below.

When you add a labeled input control to you form, it initially has no attached label. However, once you assign text to the LabelText property, an enhanced label component is automatically created and added to your form. Its initial position is to the left of the input control (if you are a registered users, you can edit the EF_EDIT.PAS unit and change the DefaultLabelPos constant to another setting) and a colon is automatically added. If you want to remove the colon, just set the LabelColon property to False. You can change the amount of space between the input control and its label by modifying the value of LabelMargin. Use the LabelPos property to choose a different position for the label. You can also easily align all labels by changing their relative coordinates through the LabelRelLeft and LabelRelTop properties.

Although you can control many aspects of the attached label through its labeled input control, you can also select the label at design time and change any of the label's properties just as you would with any standard component. If you delete the input control, then its label is also deleted. At runtime, if you hide/show or enable/disable the input control, its label will do likewise. If you move or resize the input control, its label will automatically reposition itself.

Note that a label should never be shared between several labeled controls. Therefore, using the cut and paste method to duplicate labeled controls is not recommended. This is due to the fact that all published properties are replicated. As a result, you will have two controls using the same attached label. This is a situation you should avoid as the behavior of the controls will become unpredictable.

Global Constants

•	DefaultLabelPos = lpLeft;

•	DefaultMargin = 8;

•	DefaultAddColon = True;

•	AdjLabelToControl : Integer = 3;

•	LabelPrefix : string[5] = 'el_';

Methods

•	function HasLabel:Boolean;

•	procedure SetLabelRelPosition(ALeft,ATop:Integer);

Published Properties

•	property LabelText:string

•	property LabelPos:TLabelPos

•	property LabelMargin:Integer

•	property LabelColon:Boolean

•	property LabelComponent:TLabel

•	property LabelRelLeft:Integer

•	property LabelRelTop:Integer


TLblEdit

TLblEdit is derived from TEicEdit. It inherits all the features of TEicEdit and offers the new component elements common to all the labeled input components.


TLblMaskEdit

TLblMaskEdit is derived from TEicMaskEdit. It inherits all the features of TEicMaskEdit and offers the new component elements common to all the labeled input components.


TLblMemo

TLblMemo is derived from TEicMemo. It inherits all the features of TEicMemo and offers the new component elements common to all the labeled input components.


TLblComboBox

TLblComboBox is derived from TEicComboBox. It inherits all the features of TEicComboBox and offers the new component elements common to all the labeled input components.


TLblListbox

TLblListbox is derived from TEicListbox. It inherits all the features of TEicListbox and offers the new component elements common to all the labeled input components.


Data-Aware Labeled Input Controls

When you add a labeled input control to you form, it initially has no attached label. However, once you assign text to the LabelText property, an enhanced label component is automatically created and added to your form. Its initial position is to the left of the input control (if you are a registered users, you can edit the EF_EDIT.PAS unit and change the DefaultLabelPos constant to another setting) and a colon is automatically added. If you want to remove the colon, just set the LabelColon property to False. You can change the amount of space between the input control and its label by modifying the value of LabelMargin. Use the LabelPos property to choose a different position for the label. You can also easily align all labels by changing their relative coordinates through the LabelRelLeft and LabelRelTop properties.

Although you can control many aspects of the attached label through its labeled input control, you can also select the label at design time and change any of the label's properties just as you would with any standard component. If you delete the input control, then its label is also deleted. At runtime, if you hide/show or enable/disable the input control, its label will do likewise. If you move or resize the input control, its label will automatically reposition itself.

Note that a label should never be shared between several labeled controls. Therefore, using the cut and paste method to duplicate labeled controls is not recommended. This is due to the fact that all published properties are replicated. As a result, you will have two controls using the same attached label. This is a situation you should avoid as the behavior of the controls will become unpredictable.

TDbLblEdit, TDbLblMemo, TDbLblComboBox, TDbLblListbox (except those marked with * ) all share the following new elements:

Global Constants

•	DefaultLabelPos = lpLeft;

•	DefaultMargin = 8;

•	DefaultAddColon = True;

•	AdjLabelToControl : Integer = 3;

•	LabelPrefix : string[5] = 'el_';

Methods

•	function  HasLabel:Boolean;

•	procedure SetLabelRelPosition (ALeft,ATop:Integer);

•	procedure ToggleInsMode; *

Properties

•	property DbInputBoxMaster:TDbInputBoxMaster *

Published Properties

•	property LabelText:string

•	property LabelPos:TLabelPos

•	property LabelMargin:Integer

•	property LabelColon:Boolean

•	property LabelComponent:TLabel

•	property LabelRelLeft:Integer

•	property LabelRelTop:Integer

•	property DispatchInsMode:Boolean *

•	property OverwriteMode:Boolean *


Methods and Properties


AdjLabelToControl

AdjLabelToControl : Integer = 3;

Relative height in pixels of label top from control window top when LabelPos is lpLeft or lpRight. This constant is used to align the label with the text in the input control. A value of 3 works well under most resolutions.

If you set this constant to 0, the top of labels will be aligned with the top of their input control. Increasing this value places the label lower down.


DefaultAddColon

DefaultAddColon = True;

The default value for the LabelColon property is determined by this global constant. If you don't want a colon added to your label by default, change the constant value to False.

See also:

•	LabelColon


DefaultLabelPos

DefaultLabelPos = lpLeft;

The default value for the LabelPos property is determined by this global constant. If, for example, you usually place labels above the input control rather than to the left, open the Ef_Edit unit and change the assignment as follows:

   DefaultLabelPos = lpTop;

Once you have changed the source code, remember to rebuild the component library (Options | Rebuild Library) so the changes become effective. Note that you can also change the default label margin by assigning a value to DefaultMargin.

See also:

•	DefaultMargin

•	LabelPos


DefaultMargin

   DefaultMargin = 8;

The default value for the LabelMargin property is determined by the global constant DefaultMargin. If you want to change the value to for example 12, open the Ef_Edit unit and change the assignment as follows:

   DefaultMargin = 12

Once you have changed the source code, remember to rebuild the component library (Options | Rebuild Library) so the changes become effective. Note that you can also change the default label position by assigning a value to DefaultLabelPos.

See also:

•	DefaultLabelPos

•	LabelMargin


HasLabel

function HasLabel:Boolean;

Returns true if the input control has a label attached to it.


LabelColon

property LabelColon:Boolean read FAddColon write SetAddColon;

When true, adds a colon to the label caption. The default value is determined by the DefaultAddColon constant.

See also:

•	DefaultAddColon

•	LabelText


LabelComponent

property LabelComponent:TLabel read FLabel write SetLabel;

This property points to the attached Label component. Can be a preexisting TLabel component or descendant, or the internally created TEnhLabel component. The label must (of course) be on the same form as the input control. You will rarely need to use this property, but it can be useful to change properties of the attached label at run time.


LabelMargin

property LabelMargin:Integer read FMargin write SetMargin default 8;

Determines the amount of space in pixels separating the label from the input control. This property is ignored if LabelPos is set to lpCustom and the label has already been created.

The default value for this property is determined by the global constant DefaultMargin. If you want a different default value, you can edit the number assigned to the constant.

See also:

•	LabelPos

•	DefaultMargin


LabelPos

property LabelPos:TLabelPos read FLabelPos write SetLabelPos default lpLeft;

Property for reading or setting the position of the input control's label with respect to itself. Can be placed above, below, left or right of the input control, or at a custom location. If the parent of both components is different, then only custom location can be set.

If LabelPos is set to lpCustom, you can change the relative position of the label by dragging it to a different position. However, moving the input control will move the label along with it and preserve its relative position.

The default value for this property is determined by the global constant DefaultLabelPos. If you usually place labels in an other position than left of the input control, you can change the constant to a more suitable value.

See also:

•	TLabelPos

•	LabelMargin

•	DefaultLabelPos


LabelPrefix

LabelPrefix : string[5] = 'el_';

This constant is defined in the Ef_Edit unit and is used when naming labels that are created by the Labeled Input Controls. The label name is created by adding the Labeled Input Control's name to the prefix. You can change the prefix to another value if you think the names generated this way could clash with preexisting component names. Note however, that changing this constant when you have already created forms with labeled controls will result in the loss of the link between the input control and its label on those forms.

If you edit the source code, remember to rebuild the component library (Options | Rebuild Library) so the changes become effective.


LabelRelLeft

property LabelRelLeft:Integer read FLabelRelLeft write SetLabelRelLeft;

Use this property to modify the relative horizontal position of an attached label. The LabelPos property is automatically adjusted to lpCustom.

A negative value places the leftmost part of the label to the left of the leftmost part of the input control. A positive value places the leftmost part of the label to the right of the leftmost part of the input control.

This property is particularly useful when you have aligned a set of labeled controls and want to align their labels with each other. At design time, select all the Labeled Input Controls concerned and then choose an appropriate value for the LabelRelLeft property. Your labels will then be aligned in the following manner:

Label 1         [Input Control 1]
Longer Label 2  [Input Control 2]
Lbl             [Input Control 3]

See also:

•	LabelRelTop

•	SetLabelRelPosition


LabelRelTop

property LabelRelTop:Integer read FLabelRelTop write SetLabelRelTop;

Use this property to modify the relative vertical position of an attached label. The LabelPos property is automatically adjusted to lpCustom.

A negative value places the topmost part of the label above the topmost part of the input control. A positive value places the topmost part of the label below the topmost part of the input control.

See also:

•	LabelRelLeft

•	SetLabelRelPosition


LabelText

property LabelText:string read GetLabelCaption write SetLabelCaption;

Property for reading or setting the caption of the input control's label. If the control has no associated label, setting text to this property automatically creates an associated TEnhLabel component.

See also:

•	LabelPos

•	LabelColon


SetLabelRelPosition

procedure SetLabelRelPosition(ALeft,ATop:Integer);

Use this method to modify the relative position of an attached label. The LabelPos property is automatically changed to lpCustom.

This method is faster than LabelRelLeft and LabelRelTop if you need to modify both values.

See also:

•	LabelPos

•	LabelRelLeft

•	LabelRelTop


TLabelPos

TLabelPos = (lpCustom,lpTop,lpLeft,lpBottom,lpRight);

Use the appropriate constant to define the position of an attached label with respect to its input control.


Invisible Components

The following are invisible components that can be used to further enhance the functionality of the input controls:

TInputBoxMaster

TDbInputBoxMaster

TInputBoxMenu


TInputBoxMaster

TInputBoxMaster is a new invisible component derived from TComponent. Place one of these components on a form containing the enhanced components or their labeled derivatives. You will then be able to add a context sensitive shortcut menu to all of them at once and toggle their insert/overwrite status at design or runtime.

Placing this component on a form makes it possible to propagate at runtime insert/overwrite mode changes to all the Enhanced Input Controls on that form. If the DispatchInsMode property of the control receiving the Insert key press is True, TInputBoxMaster will be informed by that control and then automatically adjust the insert/overwrite status of all the enhanced controls on the same form.

Methods

•	procedure RunTimeLoaded;

Properties

•	property UpdateMode:Boolean

Published Properties

•	property InputBoxMenu:TInputBoxMenu

•	property OverwriteMode:Boolean

•	property UseContextMenu:Boolean

Events

•	property OnModeChange:TNotifyEvent


TInputBoxMaster Declaration


InputBoxMenu

property InputBoxMenu:TInputBoxMenu read FInputBoxMenu write SetInputBoxMenu;

Property that points to a TInputBoxMenu object. You only need to use this property if you want to assign a different popup menu from the one created by the TInputBoxMaster component.

See also:

•	UseContextMenu


OnModeChange

property OnModeChange:TNotifyEvent read FOnModeChange write FOnModeChange;

This event is triggered whenever the insert/overwrite mode is changed. This can happen when OverwriteMode is modified or when an enhanced input control propagates a mode change when the Insert key is pressed.

See also:

•	DispatchInsMode

•	OverwriteMode


UpdateMode

property UpdateMode:Boolean read FUpdateMode write SetUpdating;

Use this property if you want to change the value of the UpdatingField property for all the enhanced input controls on the form.


UseContextMenu

property UseContextMenu:Boolean read FUseContextMenu write SetUseContextMenu;

When you set this property True, the TInputBoxMaster component automatically creates a TInputBoxMenu component (unless there is already one with the name "ef_InputBoxMenu"). It will then take care of assigning it to all the enhanced input controls on the form. Setting this property to False will clear the Popup property of all the enhanced input controls assigned to the same menu as InputBoxMenu. Note that doing this will not delete the TInputBoxMenu component.

Setting this property to True will make a context sensitive shortcut menu available to all the enhanced input controls (except TEicListbox ).

See also:

•	TInputBoxMenu


TDbInputBoxMaster

TDbInputBoxMaster is a new invisible component derived from TComponent. Place one of these components on a form containing the labeled data-aware components. You will then be able to toggle their insert/overwrite status at design or runtime. If you allow it, pressing the Insert key at runtime will automatically adjust the insert/overwrite status of all these controls on the form.

Published Properties

•	property OverwriteMode:Boolean

Events

•	property OnModeChange:TNotifyEvent


TInputBoxMenu

TInputBoxMenu is a new component derived from TPopupMenu. It provides a shortcut menu which is available to all the Enhanced Input Controls. The commands provided in this menu let you undo, toggle insert mode, cut, copy, paste, delete, etc. text in the controls edit window.

This component is created automatically by TInputBoxMaster when you assign True to its UseContextMenu property. You can also place the component on the form the usual way if you don't want to use TInputBoxMaster. The TInputBoxMenu component can be attached (either manually or automatically) to any of the Enhanced Input Controls.

At design time, you will see the menu items generated by this component. Do not assign your own events to these items. You can, however, add your own menu items by placing them at the end of the list.

Note that with Delphi 1 programs running under Windows 95, the shortcut menu will not popup when you click inside the edit window of the TEicComboBox (except the arrow button). Instead, Windows will display its own popup window. This is due to a bug in Delphi 1 for which, unfortunately, I have not found a fix.

Methods

•	procedure RunTimeLoaded; dynamic;

Published Properties

•	property ShowInMenu:TShowMenuSet


TInputBoxMenu Declaration


ShowInMenu

property ShowInMenu:TShowMenuSet read FShowInMenu write SetShowInMenu default [smUndo..smSelectAll];

Use this property to define which commands you would like to use in the popup menu. See TShowMenuSet for the menu items available.


TShowMenuSet

Type
  TShowMenu = (smUndo, smOverwrite,
               smBreak1,
               smCut, smCopy, smPaste, smDelete, smClear,
               smBreak2,
               smSelectAll);

  TShowMenuSet = set of TShowMenu;

The set defines which commands you would like to use in the popup menu:

smUndo:	displays an undo changes command for the input box.

smOverwrite:	lets the user toggle between insert and overwrite mode by using the shortcut menu instead of the keyboard.

smCut:	provides the clipboard cut command.

smCopy:	provides the clipboard copy command.

smPaste:	provides the clipboard paste command.

smDelete:	lets the user delete selected text by using the shortcut menu instead of the keyboard.

smClear:	displays a command that clears the content of the input box.

smSelectAll:	displays a command that selects all the text in the input box.


Revision History

Here you will find information on the changes that were made to each successive version of the component package:

Version 2.03

Version 2.02

Version 2.01

Version 2.00

Version 1.05

Version 1.04

Version 1.03

Version 1.02

Version 1.01

Version 1.00


Version 2.03

Released November 18, 1996

Changes:

•	Improved TInputBoxMenu which can now be used with the standard input controls TEdit, TMaskEdit, and TMemo (revision 2.02b).

•	Renamed the TEicMemo method CurrentCursorPos to GetCursorPos (revision 2.02b).

•	The TEicMemo TextToMemo and FileToMemo methods now set the Modified flag (revision 2.02b).

•	The TEicMemo methods UndoEdit and Clear now call the Changed method (revision 2.02b).

•	Fixed a bug in the algorithm used to sort the objects contained in the lists of TEicComboBox and TEicListBox.

•	Changed the prefix used for the TCompareResult items from "ca" to "cr" (crEqual,crFirstIsGreater,crFirstIsSmaller).

•	Improved the help file thanks to a new authoring tool.

Additions:

•	Added the Alignment property to TEicEdit (revision 2.02b).

•	Added the OnCursorMove event and the SetCursorPos method to TEicMemo (revision 2.02b).

•	Added the SetSelStart method to TEicMemo. It triggers the new OnCursorMove event (revision 2.02b).

•	Added the ScrollWidth property to TEicListBox. This lets you define the extent of horizontal scrolling (revision 2.02b).

•	Added the AutoAdjustScrollWidth property to TEicListBox. When True, the extent of horizontal scrolling is estimated and the horizontal scroll bar is automatically adjusted. Note that the method used to estimate the list width can be relatively inaccurate depending on the font used for the list box. Values are only accurate when the System font is used. The same applies to tab settings. This seems to be due to a bug in Windows (revision 2.02b).

•	Added the AddSortObject method to TEicComboBox and TEicListBox to allow adding new strings with objects in a sorted order.

Bug fixes:

•	When the WordWrap feature was added to TEicEdit, the OnChange event was not properly triggered and AutoSelect no longer worked. These problems have now been fixed. Also, when WordWrap is enabled, the AutoSelect and AutoSize property is now set to False (when AutoSize is True, the control adjusts its height to show only one line) (revision 2.02a).

•	Fixed a bug caused by Delphi 2.0 that did not allow setting values for SelStart and SelLength in TEicComboBox. As a result, overwrite mode could not select just one character (revision 2.02b).

•	There was a bug in the SetTabStops method of TEicListBox which caused an exception. This has been fixed.


Version 2.02

Released October 17, 1996

Additions:

•	Added the SortObjects method and OnCompare event to TEicComboBox and TEicListBox. The method uses the QuickSort algorithm to sort the list of items according to the associated objects. You provide the result of each object comparison through the OnCompare event.

•	Added the AutoPickItem property to TEicComboBox. This feature works when AutoExpand is True. An OnListPick event is triggered whenever a new list item is selected through the expand feature.

•	Added the AllowToggle property to TEicListBox. This feature lets the user toggle a selection on and off just by clicking on it. Works only when MultiSelect is False and AllowNull is True.

•	Added the ChangeText method to TEicComboBox and TEicListBox. If DestroyObjects is True, you should use this method instead of renaming items by accessing the Items.Strings array directly. Renaming a string item directly causes the associated object to be destroyed and can result in hard to find GPF exceptions.

Bug fixes:

•	Fixed a bug relating to default values which were not properly updated (revision 2.01a).

•	Fixed a bug in TInputBoxMenu which sometimes caused a GPF exception when the component was destroyed (revision 2.01b).

•	Fixed a bug in TInputBoxMenu which sometimes caused an out of range exception.

•	The Undo method in TEicComboBox did not always work when the undo buffer was empty and ItemIndex was equal to -1. This has been fixed.

•	When TEicComboBox is of type csDropDownList, the OnListPick event was not triggered. This has been fixed.

•	Fixed a bug in TEicListBox which caused a selection using the mouse to immediately change from a selected state to unselected after an item was deleted.


Version 2.01

Released September 25, 1996

Changes:

•	Improved TEicListbox behavior when MultiSelect is True.

•	Fixed a bug that converted all LabelPos attributes to lpCustom when form is loaded during design time.

•	Fixed minor bugs in TEicComboBox and TEicListbox, particularly the OnListPick event which was not triggered in some cases.

Additions:

•	Added SetTabStops method to TEicListbox so that you can display item data in columns.

•	Added FileToMemo method to TEicMemo. It is faster than LoadFromFile and doesn't fail if the file is larger than the memo size limit (32Kb for 16-bit version and 61Kb for 32-bit version).

•	Added StreamToMemo method to TEicMemo. It is faster than LoadFromStream and doesn't fail if the data is larger than the memo size limit (32Kb for 16-bit version and 61Kb for 32-bit version).

•	Added AllowNull published property to TEicComboBox and TEicListbox. When set to False, the control ensures that an item is always selected.

•	Added ScrollToCaret method to TEicMemo (only valid in Delphi 2).


Version 2.00

Released September 12, 1996

New product name:

•	Super Labeled Input Controls (SLIC)

New package name:

•	Slic16.zip and Slic32.zip

Changes:

•	When installed, components are now added to the Slic palette.

•	Improved positioning of attached labels when LabelPos is set to lpCustom. Relative position is now taken into account through the use of two new properties: LabelRelLeft and LabelRelTop. Now, when you move a labeled control, its label moves with it whilst preserving its relative position. Moving the label, however, readjusts the values defining its relative position.

•	When LabelPos is set to lpLeft or lpRight, the label is now aligned with the text in the input control instead of the top of the input control's window.

•	The default value for LabelColon is now True, LabelPos is now lpLeft instead of lpTop and the default value for LabelMargin is 8 instead of 2.

•	Renamed TEnhMemo to TEicMemo.

•	Source code no longer freely available (this is unfortunate, but users were not motivated to pay/register the earlier versions as everything was already included).

•	New price.

Additions:

•	Added Insert/Overwrite capabilities.

•	Added Undo capabilities to all the non-data aware input controls.

•	Added shortcut menu designed to work with all the non-data aware enhanced input controls (like in Win95 but better, and also available under Win 3.1).

•	Added global constants DefaultAddColon, DefaultLabelPos and DefaultMargin to make it easier to change the default values for LabelColon, LabelPos and LabelMargin properties respectively.

•	Added a labeled list box component and a collection of enhanced standard components.

•	Added this help file.


Version 1.05

Released May 24, 1996

Changes:

•	Improved the behavior of the new TEnhLabel's Disabled property. Note that when TEdit's Enable property is set to False at design time, nothing happens to its appearance and it will not appear grayed-out at runtime (Delphi bug?). Nevertheless, it will behave as if it is disabled.


Version 1.04

Released May 15, 1996

Changes:

•	Added published property to TEnhLabel which lets you define a color for when it is disabled (standard labels usually become invisible when Enable = False).

•	When the Enable property of an input control is changed, its attached label is also enabled or disabled.


Version 1.03

Released April 16, 1996

Changes:

•	Source code modified to provide full compatibility with both Delphi 1.0 and 2.0.

•	I've moved, so please take note my new address when you  register!

Bug fix:

•	There was a bug in earlier versions that appeared when one of these labeled controls was placed on a TPanel component. Destroying the TPanel (other than through the destruction of  the owner form) when it contained a labeled input control caused a nasty GPF. This was due to an oversight in the DestroyLabel method. Indeed, the form (= Owner) is not the only window control that will destroy its owned components when in the process of being destroyed, the parent control does it too. Therefore it is necessary to also test if the parent of the label is being destroyed, thereby causing the destruction of the labeled input controls placed on it.


Version 1.02

Released March 16, 1996

Changes:

•	Added two exceptions for each labeled control. One to ensure that the attached label is on the same form as the input control. The other to forbid values other than custom for the LabelPos property if the attached-label's parent is different from the input-control's parent.


Version 1.01

Released March 11, 1996

Changes:

•	Added lpCustom option for LabelPos property. When this option  is set, the input control does not affect the label's position.

•	Renamed ComponentLabel property to LabelComponent, made it read and write, and published it. Standard TLabel component can be assigned to this property.

•	Added properties to TEnhLabel so that attached input control is notified of any changes that could affect label's position.

•	Improved the implementation and made better use of some of Delphi's less well documented features.


Version 1.00

Released March 6, 1996

Product name:

•	Labeled Input Controls

Package name:

•	Lblinput.zip and Lblinp32.zip


the software
the Super Labeled Input Components


same name
Component names: TInputBoxMenu, TInputBoxMaster, TEicEdit, TEicMaskEdit, TEicMemo, TEicComboBox, TEicListbox, TEnhLabel, TLblEdit, TLblMaskEdit, TLblMemo, TLblComboBox, TLblListbox, TDbInputBoxMaster, TDbLblEdit, TDbLblMemo, TDbLblComboBox, TDbLblListbox


the product
the Super Labeled Input Components


author
Eric G.V. Fookes