All Blog Posts  |  Next Post  |  Previous Post

FlexCel 5 for VCL/FireMonkey release notes

Monday, March 5, 2012

This post has been updated in Apr 2013 to reflect the new changes

I am really happy to say we have finally released our first version of FlexCel 5 for VCL/Firemonkey. It has been a huge lot of hard work, and even when there is still a lot of work to do, the biggest part is done. This version doesn't include the rendering and reporting engines, but that is no more than 20% of the total lines of code; the other 80% has already been delivered.

I still need to write a post about the technical stuff on how it was created (which I think is quite interesting), but today I want to speak about the release itself, how you can use it, what is changed and what is still missing.

What's included?

As you might know, FlexCel is actually 3 products in one: A library for reading and writing Excel files, a reporting library to create Excel files by writing tags inside a template, and a rendering library that can print, preview and convert any Excel file to pdf, html or images.

While I would have loved to include everything in this first release, the reality is that it would have made no sense to make people who needs the library to read and write xls/x files wait until the rendering engine is finished. So we are launching things as soon as they are ready, and this first version is about the first of those products, the library to read and write xls/x files. The reporting and rendering engine are still being worked on, and will be released in other updates in the same way, as soon as they are ready.

We plan for a lot of releases in the coming months while we work towards full feature parity with FlexCel.NET. Below is a rough scheme of what is still missing:

Launch schedule:

Update Apr 2013: FlexCel is now at 5.6.5, and it includes Full Recalculation, ApiMate, C++ builder support (XE2 or newer), Encrypted xls and xlsx files, improved documentation and demos, the stability fixes, and the rendering engine inclding pdf and html support. The only thing missing from the schedule is the reporting engine, which should be coming soon. Many things not planned like a FireMonkey viewer were added too.

v5.1 (estimated for the end of march):

It will focus in finishing the parts of the API that couldn't be ready for the first launch. Those include:

  • Full recalculation support: We found some showstopper bugs and had to disable recalculation in v5.0, but it will be coming as soon as we can possibly fix the problem.

  • APIMate: APIMate is a tool that tells you how to code an Excel sheet. You open an xls/xlsx file created with Excel in APIMate, and it will tell you the exact Delphi code you need to create that file. As with recalculation, APIMate is internally working and I hoped it would make the initial release, but it had some bugs (related to RTTI in initialized enums) that made us delay it.

  • If possible, C++ Builder support: I am not 100% sure if this one is even possible, the truth is that Delphi produces completely bonked hpp headers for FlexCel that won't even compile. After some investigation headers could manually be fixed, but there are also bugs in the way Rad Studio returns records (C structs) to C++ builder, causing AVs when some records are returned. As said, we still need to investigate this in depth so I can't say much more until we do.

  • Encrypted files xls and xlsx files: Support for encrypted files is already in the shipped 5.0 code, but not enabled since we need to code our own encryption algorithms like SHA1 and AES for it to work. At the moment the code just calls some abstract interfaces for SHA1 and AES and will not open encrypted files.

  • Documentation and demos: We should be improving a lot in the documentation, providing F1 help, and adding many new demos. APIMate should help a lot with the learning curve too.

  • Stability fixes: As with any first release, we expect to find many small issues that we will be fixing in this 5.1 release.


  • Reporting Engine: A completely rewritten report engine that will allow a lot of new stuff in Reports. A converter from v3 reports to v5 reports will be included.

  • Rendering Engine: Exporting xls/x files to pdf, html or images. Printing and previewing Excel files.
Please note that the reporting engine and the rendering engine are being worked in parallel, so order is not certain at this point. I would expect reports to be simpler to finish than the rendering engine, but it might not be the case. Whatever is finished first will be 5.2 and the other 5.3.

Also note that this is a tentative schedule, as mentioned at the start of this post, the idea is to release things as soon as they get ready to use, so we might get more releases if some parts prove more difficult so we don't keep the other parts waiting for that. Also final release numbers might be different, the only thing certain about version numbers is that when we achieve full FlexCel .NET parity, it will go to the number FlexCel .NET is at that moment.

After that we will resume a parallel schedule with FlexCel .NET, and releases from there are going to be simultaneous in both platforms.

Structural changes

FlexCel v5 is a big change and completely independent from FlexCel v3. This means that you can (and probably should for a while if you have any legacy code) have both versions installed in parallel.

Where have my components gone? Update Apr 2013: FlexCel 5.6.5 has now one visual component, TFlexCelPreviewer, available for VCL and for FireMonkey.

The first thing that you will notice when you install FlexCel 5 is that no components are installed in the toolbar. You will still see FlexCelImport and FlexCelReport and all the v3 components if you have v3 installed, but no new ones. If you don't have v3, you won't see any new components at all.

The reason is simple, we have changed all non visual components to classes. "FlexCelImport" being a component didn't add anything to it and it created issues, like for example not being able to have 2 components of the same name registered in the palette. (so you wouldn't be able to have a v3 FlexCelReport and a v5 FlexCelReport installed at the same time, unless we renamed the v5 component as "FlexCelReport5" or other silly name). It also was problematic if you had say a console application and no form where to drop the component, and as said, having them be "components" didn't add much. So they are now classes instead.

This means that now, instead of dropping a FlexCelImport into a form, you would write the following code: (note that FlexCelImport changed to XlsFile, see "Class Architecture" below)
  xls: TXlsFile;
  xls := TXlsFile.Create(true);

Class Architecture

If we focus in the main components (forgetting helper components like TTemplateStore or TFlxMemTable), the original v3 FlexCel architecture looked something like the following:

TExcelAdapter was an abstract class that provided an interface between an actual Excel file and the components doing the work. We originally provided two different implementations of TExcelAdapter: TXlsAdapter (native interface) and TOleAdapter (interface using OLE Automation). Then you could plug TFlexCelReport into a TXlsAdapter and have a report generated natively, or plug it to an OLE Adapter and have the report generated by OLE Automation.

This was a nice abstraction and it worked fine at the beginning (when we only had a FlexCelReport component), but with the introduction of FlexCelImport (a component that was originally designed to only read xls files as its name implies, but later was expanded to also write files) things got a little too complex.

As you can see in the diagram, you have an "Adapter" and a "FlexCelImport" class that do mostly the same. So most of the methods (but not all) in FlexCelImport, just call the same method in the ExcelAdapter engine. This meant not only a lot of redundant code (and redundancy is one of the main things that we want to avoid), but also a lot of confusion in users who didn't know what to use, if ExcelAdapter or FlexCelImport. We explained in the documentation that you should use FlexCelImport and not ExcelAdapter, but people kept using ExcelAdapter. And when people keeps doing the "wrong" thing despite what the docs say, this normally means not a problem in the docs or the users, but a deeper problem in the conceptual design of the code. This wasn't as intuitive as it could be.

The last problem with this architecture was that FlexCelImport was at the same level as FlexCelReport, so they couldn't "see" each other. The design was top-down, and the components at the top can only know about the components at the bottom. So in the places where FlexCelReport allowed hand-optimization of the code, it had to expose an Adapter component (the only thing it knew about) and not a FlexCelImport component. But you were supposed to use FlexCelImport to do manual modifications in the file, not the Adapters.

If we sit back and take a look from the distance, all the problems came from the fact that FlexCelImport was added as a separate layer over the Adapter components, and it didn't had to be that way. So, in v5 we only have one class to read and write Excel files, and it is at the bottom where everybody else can use them, as it should be. There is no more FlexCelImport in v5, and the scheme looks something like this:

Where now the abstract class to read and write is TExcelFile, and the native implementation of that class is TXlsFile. All the code you used to use with FlexCelImport, should use TXlsFile now instead.

Migration from v3 to v5

The first thing to know when planning the migration is that, as mentioned earlier, you can have both versions installed at the same time. As this is a big change, it will help being able to migrate code part by part and at your own peace.

Migrating FlexCelImport code

Migrating FlexCelImport code shouldn't be difficult. You need to replace the TFlexCelImport component by TXlsFile class, but most methods remain the same or similar. Probably the most important change is that properties have been changed to Get/Set methods (because C++ builder can get very buggy when dealing with indexed properties), so instead of a property FlexCelImport.CellValue[row, col] you now have a TXlsFile.SetCellValue and TXlsFile.GetCellValue methods. Once you learn the little differences migration gets quite easy.

Update Apr 2013: APIMate for delphi and C++ Builder is already released.

Once we release APIMate, there will also be another option, that is creating the file in v3, opening it in APIMate, and get the v5 code.

Migrating Reports

Reports in v5 have a lot of new stuff, they are way more powerful now.
The main difference with the old reports is tags: we have unified them all. Now all tags are in the form <#tag>. This means you have to write <#table.field> instead of ##table##field, <#delete row> instead of ...delete row... and <#reportvar> instead of #.reportvar#.

We will be providing a tool to do the migration that should take care for most of it automatically, but you will probably want to look at the old reports anyway to make use of the new functionality. And as you can have both versions installed, you can go changing them one by one as you feel you can.

Using TXlsxAdapter

Update Apr 2013: TXlsxAdapter is already released, you can get it when you install the latest FlexCel 3 (currently 3.7) from the registered downloads page. It is recommended that you replace all your TXlsAdapters byTXlsxAdapters.

There is another tool, that while not literally a migration helper, will help building a bridge between v3 and v5 until we have finished the functionality in v5 and you had your time to migrate everything. If you look at the v3 class diagram above, you will see that we have an abstract "Adapter" class that serves as an engine where the other components talk. We had an OLEAdapter and a TXlsAdapter in v3, but what if we added a new adapter to the mix? A "TXlsxAdapter" that uses v5 to read the Excel files and can be used by v3 FlexCelImport and v3 FlexCelReport? As this adapter will use v5 to read and write to the file, it will be able to read and write xls and xlsx/xlsm files. And you will be able to read and write those files with the v3 components. While in the long term the idea is to move to v5 components, by using TXlsxAdapter you can keep using v3 and reading and writing xlsx files.

We will be shipping TXlsxAdapter this week, as a separate download.


To round up this post, I would like to end up with a personal note. I would like to personally thank you for all the support and the amazing response FlexCel 5 got. There were times during the days after the launch where I would have say 20 emails to answer, I would answer 10, look again, and I would now have 24 emails to answer!

I would also want to apologize for all the delays v5 got, nobody more than me would have liked to have it sooner, but the reality is that coding an Excel clone is a lot of work, much more than it would appear once you start looking at all the little details, and we are doing it twice (once for .NET and once for VCL).

So when at the beginning of this post I said I was really happy with this launch I really mean it, it has been a lot of work and I am glad it is finally out there. Well, if you excuse me now I am going back to work to get that 5.1 release ready.

Adrian Gallero

This blog post has received 5 comments.

1. Friday, December 14, 2012 at 8:23:14 AM

Upgrade sound to be easy, but how about TFlexCelGrid? How to show excel file with new version?

Timo Kervinen

2. Friday, December 14, 2012 at 8:45:57 AM


FlexCelGrid isn''t included in FlexCel 5, but it does include "TFlexCelPreviewer" which will show any xls/x file with a great level of detail and almost identical to what Excel shows in the preview. (this is a much more closer to excel rendering than what FlexCelGrid offered).

Please take a look at the "Custom preview" demo to see how it is used in a real application.

Adrian Gallero

3. Monday, December 17, 2012 at 1:56:25 AM

TFlexCelPreviewer might be good for print preview for small reports, but this we need grid view (excel style) to view large sheets . TFlexCelGrid was good for that!

Timo Kervinen

4. Monday, December 17, 2012 at 4:03:25 AM

I am not sure on why you say TFlexCelPreviewer is for small reports, I actually use it myself for big ones. You can even have thumbnails at the side which help you navigate in big files (similar to when you see a file in acrobat), and FlexCelPreviewer can display thousands of pages without issues.

I see the advantage of FlexCelGrid more if you need to do some editing, but for displaying sheets, I personally find TFlexCelPreviewer much better (as long as the file is designed for preview, which it should if you want to ever print it or export it to pdf). In any case, TFlexCelGrid might be coming back in the future (As said, mostly for people who want to provide editing), but not just now, more in a 7.0 timeframe.

But well, if you prefer FlexCelGrid, FlexCelGrid v3 still works and it is fully functional, you can still use it with XlsxAdapter to display xls/x files.


Adrian Gallero

5. Monday, April 8, 2013 at 10:27:02 AM

Just used the new XLSX adapter with my 3.7 Flexcel code in Delphi XE. Works really well, and seems blazingly fast. Thanks again for such a great tool.

Stevens Richard

Add a new comment

You will receive a confirmation mail with a link to validate your comment, please use a valid email address.
All fields are required.

All Blog Posts  |  Next Post  |  Previous Post