Currently, the sample for C++ is a hidden gem in the form of the “Print and Design Reports (SQL data source)” sample. If you’re about to start your development in C++, this is the recommended starting point. That’s also the reason why we removed and deprecated several other C++ samples in LL21. Of course, we’ll fully support the “old” way of working with List & Label with your custom print loop. However, if you’re looking for advanced features, the IDataProvider interface will be the way to go.
This is what the interface looks like:
interface ILLDataProvider : public IUnknown // IID_ILLDATAPROVIDER 0x3cbae450,0x8880,0x11d2,0x96,0xa3,0x00,0x60,0x08,0x6f,0xef,0xff { virtual HRESULT _stdcall OpenTable(LPCWSTR pszTableName, IUnknown** ppUnkOfNewDataProvider)=0; virtual HRESULT _stdcall OpenChildTable(LPCWSTR pszRelation, IUnknown** ppUnkOfNewDataProvider)=0; virtual HRESULT _stdcall GetRowCount(INT* pnRows)=0; virtual HRESULT _stdcall MoveNext()=0; virtual HRESULT _stdcall DefineRow()=0; virtual HRESULT _stdcall Dispose()=0; virtual HRESULT _stdcall SetUsedIdentifiers(const VARIANT* arvFieldRestriction)=0; virtual HRESULT _stdcall ApplySortOrder(LPCWSTR pszSortOrder)=0; virtual HRESULT _stdcall ApplyFilter(const VARIANT* arvFields, const VARIANT* arvValues)=0; virtual HRESULT _stdcall ApplyAdvancedFilter(LPCWSTR pszFilter, const VARIANT* arvValues)=0; virtual HRESULT _stdcall SetOption(INT nIndex, const VARIANT* vValue)=0; };
Your code needs to implement this interface and pass it via option to List & Label – just like in the screenshot from this tweet: https://twitter.com/jbartlau/status/649907919241244672. The sample shows an implementation for SQLite databases that will quite easily translate to other relational database systems.
The interface functions are quite easy to understand:
Method | Purpose |
OpenTable | Requests an interface to the table pszTableName. The tables are passed using the usual LlDbAddTable(Ex)() APIs before printing and designing. This is the only method that will be called on your “root” provider, i.e. the interface instance you’re passing in the first place. In the second parameter, you need to return a new IDataProvider instance. The other methods will all be called on this or other sub instances. |
OpenChildTable | Requests an interface to the child table that is identified by pszRelation. The relations are passed using the usual LlDbAddTableRelation() API before printing and designing. You need to make sure that the filter on the child table matches the current record of the table on which this method is called. |
GetRowCount | Requests the row count for the table. Used for the progress meter. You may safely return S_FALSE if your data source does not support counting rows. |
MoveNext | Requests to move the cursor to the next row. Return S_FALSE if you’ve reached the end of the table. Important: for pristine instances of tables, the first MoveNext() expects you to move the cursor to the first record. |
DefineRow | Requests to define the current row using the usual LlDefine…() APIs. |
Dispose | Can be used for clean up purposes. Will be called just before the IDataProvider is released. |
SetUsedIdentifiers | Reserved for future use, currently you can just provide an empty implementation. |
ApplySortOrder | Requests to apply the sort order pszSortOrder to the table. The sort orders are passed using the usual LlDbAddTableSortOrder() API before printing and designing. |
ApplyFilter | Requests to apply the passed filter to the records. You receive an array of field names and a corresponding array of values. This method is called during drilldown. |
ApplyAdvancedFilter | Reserved for future use, currently you can just provide an empty implementation. |
This interface enables List & Label to hold several database cursors simultaneously and traverse them independently from each other. It is this feature that is required for multiple report containers and nested tables to work. For the actual implementation just take a look at the sample that ships with List & Label 21.