--------- IMPORTANT --------- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Dimeric Software Product Information Rinse FULL Version * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Thank you for purchasing Rinse -- we hope you will find it as useful and reliable as we do. If you have any questions or comments, please vist our website... http://www.Dimeric.com/ or send us an email... Support@Dimeric.com Release Notes ------------- 2.1.11 - June 18, 2003 * New component: TSmartRecListView. It can be found on the Dimeric tab of the component palette. It has properties that you can set and events that you can handle that make displaying a list at runtime as simple as: ListView.List := SomeService.GetMyList(...) The following describes its use. The Rinse Tutorial also covers using the TSmartRecListView component. List Columns --------------- In order for the code above (ListView.List := ...) to display something useful, you will need to setup your list columns. If you drop a TSmartRecListView on a form and select it, you can click on the "..." button on the Columns property in the Object Inspector, just as you would with a basic TListView. The TSmartRecListColumn objects that you add to the list of columns, however, have additional properties and events related to smart records. The most important property of TSmartRecListColumn is the "ValueExpr" property. This property holds a MiniCalc expression for display in the column. This expression can be as simple as the name of a field in your smartrecord. For example, if your smartrecord has "Name" and "AcctNbr" properties then you can create columns with ValueExprs that are just "Name" and "AcctNbr". If you want to simply add a column for every property in a smartrecord, then you can right-click on the list view and select "Add Properties" from the popup menu. This will display a dialog where you can select properties from the smartrecord to display. The smartrecord used for this purpose is determined by the SmartRecType property of the list view. You will need to set SmartRecType before "Add Properties" will work. Click on the "..." button on the SmartRecType property in the Object Inspector with the list view selected to set this property. You will be presented with a list of smartrecords from all rinse units in the current project from which to select. You can use MiniCalc operators and functions in ValueExpr as well as just field names. For example, you might want to display some default text if a smartrecord doesn't have a particular value. In that case you might have an expression like "@IfNull(Amt, '-')". For more information on MiniCalc see the MiniCalc documentation. If you want more control over the column's value than MiniCalc provides, then you can handle the column's OnGetValue event. If you do, then the ValueExpr property is ignored. Both OnGetValue and ValueExpr return a Variant. If you just have one of these set, then at runtime this Variant is converted to text and displayed. This is usually fine for Integer and string values, for example, but if you don't want to use the default conversion to text, then you can handle the OnGetText event. Your OnGetText handler is passed the Variant obtained from ValueExpr or OnGetValue. You can then convert this Variant to text yourself. For example, you could use the Format function. So, you should still supply a ValueExpr or handle OnGetValue even if you handle OnGetText. Sorting ---------- A nice built-in feature of TSmartRecListView is automatic sorting when you click on column headers. By default when you click on a column, the sort order is based on the values in the column, the textual representation of values in the column. So, if you have a smartrecord with an integer property TrdNbr, and your ValueExpr is "TrdNbr" then it will be sorted on TrdNbr as an integer. That is, the numbers 1, 2 and 10 will be sorted in that order and not in the order 1, 10, 2. If you want to customize sorting on a column, then you can use the SortExprs property or handle the OnSort event of TSmartRecListColumn. This can be useful, for example, if you want to reverse sorting order (e.g. 10, 2, 1) or if you want a case-sensitive ordering, or if you want to provide a secondary sort (e.g., sort first by AcctNbr then by EntryDateTime). If you click on the "..." button on the SortExprs property in the Object Inspector, then you will see a dialog with a list where you can put value expressions, just like the ValueExpr propery of the column. When the column heading is clicked, the list view will be sorted first by the first value, then by the next value, and so on. You can also specify whether you want to reverse the sort or if you want case sensitive or case insensitive comparison. If you want more control over sorting than MiniCalc value comparisons can provide, then you can handle the OnSort event. If you have an OnSort handler, then SortExprs is ignored. You can set the SortExprs property or handle the OnSort even for each column in your list view. The list column that is currently being used to sort is controlled by the SortingColumn Boolean property on TSmartRecListColumn. Only one column at a time can have SortingColumn set to True. Setting one column's SortingColumn property to True sets it to False for all other columns in the list view. You should set this property at design time on the column that you want to use for sorting by default. Each column's sort order is combined with the KeyCompareExprs or OnKeyCompare sorting defined on the TSmartRecListView itself. The key comparison is a secondary sort on every column's primary sort. See the "Refreshing the List" section below for more information on key comparison. If you don't want your list view sorted, then don't set the SortingColumn property. If you don't want automatic sorting at all (i.e. you don't want the user to be able to click on the column headings to sort) then set the list view's AutoSort property to False. If you set the ColumnClick property to False or handle the OnColumnClick event yourself, then you also won't get auto-sorting behavior. List Items ------------- Each list item in a TSmartRecListView is a TSmartRecListItem. The main difference between TSmartRecListItem and TListItem is that it has a property, SmartRec, of type ISmartRecord. This property holds the smartrecord that the item represents. If you want a list of smartrecords that correspond to the selected items in the list view, then call the SelectedRecords method of TSmartRecListView. It returns an ISmartRecordList, which you can cast to the same type of list you gave to the list view. For example, if your list view represents an IFooList smartlist of IFoo smartrecords, then you can get a list of fselected IFoo objects as follows: ListView.SelectedRecords as IFooList; Refreshing the List ---------------------- TSmartRecListView has a List property that is used to supply a list of smartrecords to display. This is a read-write property. When you set this property the list view refreshes itself based on the list. It makes a TSmartRecListItem for each item in the list that has an ObjectState of osNew, osExisting or osModified (not osDeleted or osOld). Each column uses its ValueExpr or OnGetValue and possibly OnGetText to determine how to display each item. If there is a sort order defined with SortExprs or an OnSort event handler on the SortingColumn then this is used to order the items in the list view. One common programming task that developers tackle each time they use a list view is how to preserve a list's selection, focused item and scroll position when refreshing the list. In the case of TSmartRecListView, this is simple. You can select the list view and click on the "..." button on the KeyCompareExprs property of on the Object Inspector. This brings up the same dialog for listing comparison fields as the SortExprs property of a column. If you want more control, then you can handle the OnKeyCompare event. The key comparison is not only used to identify items that are the same (i.e. which items are selected and focused) when refreshing items in the list, it is also used as a secondary sort for every column sort. For example, if you are listing trades and you have specified the Cusip ID column as the SortingColumn and the TrdNbr column as the key (in KeyCompareExprs) then the trades will be sorted first by Cusip ID and then by AcctNbr. If the user clicks on the Trade Date column, then the trades will be sorted by Trade Date and then TrdNbr. Other than setting the list view's List property, you can cause the list view to refresh by calling its RefreshFromList method. If you have added or removed items from the list displayed in the list view or if you have modified properties of smartrecords in the list, then you can call this method to refresh the list view's display to match the list. If you just want to refresh the display of a single list item, then you can call that list item's RefreshFromRec method. Getting Started --------------- After you install Rinse, you can use the New Rinse Unit Wizard, File | New | Other | Rinse Unit, to create a new Rinse unit and add it to your project. Also, the Tools | Rinse Explorer command allows you to configure the Rinse Translator (this command can be found on the Help menu in Delphi 5). Documentation ------------- Rinse comes with extensive documentation, as well as an in-depth tutorial (which is the best place to begin). The tutorial can be found in Dimeric\RinseTutorial\Tutorial.rtf. The source code for each step of the tutorial can be found in the folder Dimeric\RineTutorial\Step N, where N is the step number. These projects represent the completed tutorial step, and are ready to compile and run. The Rinse documentation is Dimeric\Doc\Rinse Intro.rtf, and is partly a reference -- the tutorial is a better place to begin. Documentation on the units in RinseLib is located in the Dimeric\Help folder. The install program automatically integrates this help file into Delphi's IDE help system. Deploying Applications Built With Rinse --------------------------------------- Rinse features royalty-free application deployment. You may distribute free of charge applications (EXE files) and libraries (DLL and BPL files) built with Rinse and/or DSUtil. You may not distribute Rinse or DSUtil source code (PAS, INT, DCU and DCP files). See the software license (License.txt) for more information.