Delphi Cookbook

VCL styles can be used to revamp an old application or to create a new one with a nonstandard GUI. VCL styles are a completely different beast to FireMonkey styles. They are both styles but with completely different approaches and behavior.

To get started with VCL styles, we'll use a new application. Let's create a new VCL application and drag-and-drop some components onto the main form (for example, two TButton components, one TListBox component, one TComboBox component, and a couple of TCheckBox components).

The following screenshot is the resultant form that runs on a Windows 7 machine:

A form without style

Now we've to apply a set of nice styles. To do this, perform the following steps:

Selecting one or more styles by navigating to Project | Options | Application | Appearance can cause the Delphi linker to link the style resource to your executable. It is possible to link many styles to your executable, but you can use only one style at time. So, how does Delphi know which style you want to use when there are more than one styles? If we check the Project file (the file with the .dpr extension) by navigating to Project | View Source, you can see where and how this little magic happens.

The following lines are the interesting part:

begin
  Application.Initialize;
  Application.MainFormOnTaskbar := True;
  TStyleManager.TrySetStyle('Iceberg Classico');
  Application.CreateForm(TMainForm, MainForm);
  Application.Run;
end.

When we've selected the Iceberg Classico style as the default style, the Delphi IDE adds a line just before the creation of the main form, setting the default style for the application using the TStyleManager.TrySetStyle static method.

TStyleManager is a very important class when dealing with VCL styles. We'll see more about it in the next recipe when we'll learn how to change a style at runtime.

Delphi and C++Builder XE6 come with 29 VCL styles available in C:\Program Files (x86)\Embarcadero\Studio\14.0\Redist\styles\vcl\ (with a standard installation).

Moreover, it is possible to create your own styles or modify the existing ones by using the Bitmap Style Designer available at Tools | Bitmap Style Designer menu. The Bitmap Style Designer also provides test applications to test VCL styles.

For more details on how to create or customize a VCL style, check the following link:

http://docwiki.embarcadero.com/RADStudio/XE6/en/Creating_a_Style_using_the_Bitmap_Style_Designer

Because a VCL style is simply a particular kind of binary file, we can allow our users to load their preferred style at runtime, and we can even provide new styles—publishing them on a website or sending them by an e-mail to our customers.

In this recipe, we'll be able to change the style while an application is running using a style already linked at design time or let the user choose between a set of styles deployed inside a folder.

Styles manipulation at runtime is done using the class methods of the TStyleManager class:

The TStyleManager class has all the methods we need:

After loading new styles from the disk, these new styles are completely similar to the styles linked to the executable during the compile and link phases and can be used in the same way.

Other things to consider are third-party controls. If your application uses third-party controls, take care with their style support. If your external components do not support styles, you will end up with some controls styled (the original included in Delphi) and some not (your external third-party controls)!

By navigating to Tools | Bitmap Style Designer and using a custom VCL style, we can also perform the following actions:

The following screenshot shows the Bitmap Style Designer window while working on a custom style:

The Bitmap Style Designer while it is working on a custom style

Many VCL controls are able to delegate their drawing, or part of it, to user code. This means that we can use simple event handlers to draw standard components in different ways. It is not always simple, but TDBGrid is customizable in a really easy way. Let's say that we have a class of musicians that have to pass a set of exams. We want to show the percentage of musicians who have already passed exams with a progress bar, and if the percent is higher than 50 percent, there should also be a check in another column.

We'll use a special in-memory table from the FireDAC library. FireDAC is a new data access library from Embarcadero, which is included in RAD Studio since Version XE5. If some of the code seems unclear at the moment, consider the in-memory table as a normal TDataSet descendant. However, at the end of this section, there are some links to the FireDAC documentation, and I strongly suggest you to read them if you still don't know FireDAC. To customize TDBGrid, perform the following steps:

By setting the DBGrid property DefaultDrawing to false, we told the grid that we want to manually draw all the data into every cell. The OnDrawColumnCell event allows us to actually draw using the standard Delphi code. For each cell we are about to draw, the event handler is called with a list of useful parameters to know which cell we're about to draw and what data we have to read considering the column currently drawn. In this case, we want to draw only the calculated columns in a customized way. This is not a rule, but this can be done to manipulate all cells. We can draw any cell in the way we like. For the cells where we don't want to do custom drawing, a simple DefaultDrawColumnCell call method passing the same parameters we got from the event and the VCL code will draw the current cell as usual.

Among the event parameters, there is Rect (of the TRect type) that represents the specific area we're about to draw, there is Column (of the TColumn type) that is a reference to the current column of the grid, and there is State (of the TGridDrawState type) that is a set of the grid cell states (for example, Selected, Focused, HotTrack, and so on). If our drawing code ignores the State parameter, all the cells will be drawn in the same way and users cannot see which cell or row is selected.

The event handler uses a sets intersection to know whether the current cell should be drawn as a selected or focused cell:

if [gdSelected, gdFocused] * State <> [] then
  Grid.Canvas.Brush.Color := clHighlight;

Owner drawing is a really large topic and can be simple or tremendously complex involving much Canvas related code. However, often the kind of drawing you need will be relatively similar. So, if you need checks, arrows, color gradients, and so on, check the procedures in the Vcl.GraphUtil unit. Otherwise, if you need images, you could use a TImageList class to hold all the images needed by your grid.

The good news is that the drawing code can be reused by different kind of controls, so try to organize your code in a way that allows code reutilization avoiding direct dependencies to the form where the control is.

The code in the drawing events should not contain business logic or presentation logic. If you need presentation logic, put it in a separate and testable function or class.

As we saw in the Customizing TDBGrid recipe, many VCL controls are able to delegate their drawing, or part of it, to user code. This means that we can use simple event handlers to draw standard components in different ways. Let's say that we have a list of products in our store and we have to set discounts on these products. As there are many products, we want to make it simple so that our users can make a fast selection between the available discount percentages using a color code.

The TListBox.OnDrawItem event handler allows us to customize the drawing of the listbox. In this recipe, we used a TImageList component as the image repository for the listbox. Using the Index parameter, we read the correspondent image in the image list and drawn on the Canvas listbox. After this, all the other code is related to the alignment of image and text inside the listbox row.

Remember that this event handler will be called for each item in the list, so the code must be fast and should not do too much slow Canvas writing. Otherwise, all your GUI will be unresponsive. If you want to create complex graphics on the fly in the event, I strongly suggest you to prepare your images the first time you draw the item and then put them in a sort of cache memory (TObjectList<TBitmap> is enough).

While you are in the OnDrawITem function, you can do whatever you want with the TListBox Canvas. Moreover, the State parameter (of the TOwnerDrawState type) tells you in which states the listbox item is (for example, Selected, Focused, HotTrack, and so on), so you can use different kind of drawings depending on the item's state. You can check the Customizing TDBGrid recipe to know about the TDBGrid owner drawing for an example ofthe State parameter.

If you want to make your code aware of the selected VCL style, changing the color used according to it, you can use StyleServices.GetStyleColor(), StyleServices.GetStyleFontColor(), and StyleServices.GetSystemColor() into the Vcl.Themes unit.

The icons used in this recipe are from the Icojam website (http://www.icojam.com). The specific set used is available at http://www.icojam.com/blog/?p=259.

This recipe is a bit more complex than the previous recipes, so I'll not explain all the code but only the fundamental parts. You can find the complete code in the book's code repository (Chapter1\RECIPE05).

Let's say we want to create a tabbed interface for our software that is used to manage product orders, sales, and invoices. All the forms must be usable at the same time without having to close the previous one. Before we begin, the following screenshot is what we want to create:

The main form containing seven embedded child forms

The project is composed by a bounce of forms. The main form has a TTabControl component that allows switching between the active forms. All embedded forms inherit from EmbeddableForm. The most important is the Show method shown as follows:

procedure TEmbeddableForm.Show(AParent: TPanel);
begin
  Parent := AParent;
  BorderStyle := bsNone;
  BorderIcons := [];
  Align := alClient;
  Show;
end;

All the other forms descend from the EmbeddableForm method and are added to the TTabControl component on the main form with a line of code similar to the following:

procedure TMainForm.MenuOrdersClick(Sender: TObject);
begin
  AddForm(TForm1.Create(self));
end;

The MainForm AddForm method is in charge of adding an actual instance of a form into the tabs, keeping a reference of it. The following code shows you how this is done:

//Add a form to the stack
procedure TMainForm.AddForm(
  AEmbeddableForm: TEmbeddableForm);
begin
  AEmbeddableForm.Show(Panel1);
  //each tab show the caption of the containing form and   
  //hold the reference to it
  TabControl1.Tabs.AddObject(
         AEmbeddableForm.Caption, AEmbeddableForm);
  ResizeTabsWidth;
  ShowForm(AEmbeddableForm);
end;

Other methods are in charge of bringing an already created form to the front when a user clicks on the related tab and then to close a form when the related tab is removed (check the ShowForm and WMEmbeddedFormClose methods).

There is a bit of code, but the concepts are simple:

Embedding a form into another TWinControl is not difficult and allows you to create flexible GUIs without using TPageControl and frames. For the end user, this multitabbed GUI is probably more familiar because all the modern browsers use it, and probably your user already knows how to use a browser with different pages or screens opened. From the developer point of view, the multitabbed interface allows for much better programming patterns and practices. This technique can also be used for other scenarios where you have to embed one screen into another.

More flexible (and complex) solutions can be created involving the use of Observers, but in simple cases, this recipe's solution based on Windows Messaging is enough.

More information about the Observer design pattern can be found at http://sourcemaking.com/design_patterns/observer/delphi.

Another interesting solution (that does not rely on Windows Messaging and so is also cross platform) may be based on the System.Messaging.TMessageManager class. More info about TMessageManager can be found at http://docwiki.embarcadero.com/Libraries/XE6/en/System.Messaging.TMessageManager.

The code in this recipe can be used with every component that uses TStringList to show items (TListBox, TComboBox, and so on) and can be adapted easily for other scenarios.

In the recipe code, you'll also find a nice way to show status messages generated by the embedded forms and a centralized way to show application hints in the status bar.

JSON provides the following five datatypes: string, number, object, array, Boolean, and null.

This simplicity is a plus when you have to read a JSON string into some kind of language-specific structures, because every modern language supports JSON datatypes as simple types, HashMap (in case of JSON object), or List (in case of JSON array). So, it makes sense that a data format that is interchangeable with programming languages is also based on these types and structures.

Since Version 2009, Delphi provides built-in support for JSON. The System.JSON.pas unit contains all JSON types with a nice object-oriented interface. In this recipe, we'll see how to generate, modify, and parse a JSON string.

Although not the fastest or the most standard compliant on the market (at the time of writing), it is important to know the JSON Delphi parser because other Delphi technologies such as DataSnap use it. Luckily, there are a lot of alternative JSON parsers for Delphi if you find you have trouble with the standard ones.

Other notable JSON parsers are as follows:

If your main concern is speed, then check the Delphi Web Script or the superobject parsers.

There are also a lot of serialization libraries that use JSON as a serialization format. In general, every parser has its own way to serialize an object to JSON. Find your favorite. For example, in the Serializing objects to JSON and back using RTTI recipe in Chapter 5, Putting Delphi on the Server, you will see an open source library containing a set of serialization helpers using the default Delphi JSON parser.

However, JSON is not the right tool for every interchange or data representation job. XML has been creating other technologies that can help if you need to search, transform, and validate your data in a declarative way. In JSON land, there is no such level of standardization apart from the format itself. However, over the years, there is an effort to include at least the XML Schema counterpart in JSON, and you can find more details at http://json-schema.org/.

All the basic XML-related activities can be summarized with the following points:

In this recipe, we will see how to do all these activities.

There are many things to say about XML ecospace. There are XML engines that provide facilities to search data in an XML tree (XPath), validate an XML using another XML (XML Schema or DTD), transform an XML into another kind of format using another XML (XSLT), and for many others uses (http://en.wikipedia.org/wiki/List_of_XML_markup_languages). The good thing is that, just like XML itself, the DOM object is also standardized, so every library that is compliant to the standard has the same methods, from Delphi to JavaScript and from Python to C#.

TXMLDocument allows you to select the DOMVendor implementation. By default, there are three implementations available:

In the good old Pascal days, there was a set of functions to handle the I/O (AssignFile, Reset, Rewrite, CloseFile, and so on), now we've a bounce of classes. All Delphi streams inherit from TStream and can be used as an internal stream of one of the adapter classes (as adapter, I mean an implementation of the Adapter or Wrapper design pattern from the famous Gang of Four, Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides, Addison-Wesley Professional, book about design patterns).

There are 10 fundamental types of streams:

You can check the complete list and their intended use directly on the Embarcadero website at http://docwiki.embarcadero.com/RADStudio/XE6/en/Streams,_Reader_and_Writers.

As Joel Spolsky (http://www.joelonsoftware.com/articles/Unicode.html) says, "You can no longer pretend that plaintext is ASCII", so while we write streams, we've to pay attention to which encoding our text has and which encoding our counterpart is waiting for. One of the most frequent necessities is to efficiently read and write a text file using the correct encoding.

The point Joel is making is that the content of a string doesn't know about the type of character encoding it uses.

When you think about file handling, ask yourself: could this file become 10 MB? And 100 MB? 1 GB? How will my program behave in that case? Handling a file one line at time and not loading all the files contents in memory is usually a good insurance for these cases. A stream of data is a good way to do this kind of thing. In this recipe, we'll see the practical utilization of streams, stream writers, and streams readers.

The project is not complex, all the interesting stuff happens in the btnWriteFile and btnReadFile files.

To write the file, we use TStreamWriter. The TStreamWriter class (as its counterpart TStreamReader) is a wrapper for a TStream descendent and adds some useful high-level methods to write to the stream. There are a lot of overloaded methods (Write/WriteLine) to allow an easy writing to the underlying stream. However, you can access the underlying stream using the BaseStream property of the wrapper. Just after writing the file, the memo reloads the file using the same encoding used to write it and shows it. This is only a fast check for this recipe, you don't need the TMemo component at all in your real project. The btnReadFile file simply opens the file using a stream and passes the stream to a TStreamReader that, using the right encoding, reads the file one line at time.

Now, let's do some checks. Run the program and with the encoding set to ASCII, click on btnWriteFile. The memo will show garbage text, as shown in the following screenshot. This is because we are using the wrong encoding for the data we are writing in the file.

Garbage text written to the file using the wrong encoding. No one line of text is equal to the original one. It is necessary to know the encoding for the text before writing and reading it.

Now select UTF8 from the RadioGroup and retry. Clicking on btnWriteFile, you will see the correct text in the memo. Try to change the Current Encoding setting using ASCII and click on btnReadFile. You will still get garbage text. Why? Because the file has been read with the wrong encoding. You have to know the encoding before safely reading the file contents. To read the text that we wrote, we have to use the very same encoding. Play with the other encodings to see different behaviors.

Streams are very powerful and their uniform interface helps us to write portable and generic code. With the help of streams and polymorphism, we can write code that uses a TStream component to do some work without knowing which kind of stream it is!

Also, a lesser known possibility, if you ever write a program that needs to access to the good-old STD_INPUT, STD_OUTPUT, or STD_ERROR, you can use THandleStream to wrap these system handles to a nice TStream interface with the following code:

program StdInputOutputError;
//the following directive instructs the compiler to create a 
//console application and not a GUI one, which is the default.
{$APPTYPE CONSOLE} 
uses
  System.Classes, // required for Stream classes
  Winapi.Windows; // required to have access to the STD_* handles
var
  StdInput: TStreamReader;
  StdOutput, StrError: TStreamWriter;
begin
  StdInput := TStreamReader.Create(
               THandleStream.Create(STD_INPUT_HANDLE));
  StdInput.OwnStream;
  StdOutput := TStreamWriter.Create(
                THandleStream.Create(STD_OUTPUT_HANDLE));
  StdOutput.OwnStream;
  StdError := TStreamWriter.Create(
               THandleStream.Create(STD_ERROR_HANDLE));
  StdError.OwnStream;
  { HERE WE CAN USE OURS STREAMS }
  // Let's copy a line of text from STD_IN to STD_OUT
  StdOutput.writeln(StdInput.ReadLine);
  { END - HERE WE CAN USE OURS STREAMS }
  StdError.Free;
  StdOutput.Free;
  StdInput.Free;
end.

Moreover, when you work with file-related streams, the TFile class (contained in System.IOUtils.pas) is very useful, and it has some helper methods to write shorter and more readable code.

This recipe is about creating a good Windows citizen application. Let's say our application allows us to execute a huge search in a database. When the user starts this long operation, the application UI remains usable. During the request execution, the user can decide to wait in front of the form or minimize it to the taskbar. If the user minimizes the application window, it also goes on the tray bar and when the operation finishes and it will alert the user with a nonintrusive message.

This recipe is a bit articulated. Let's start from the beginning.

The actual code that executes the request uses a nice helper class provided by Embarcadero in the Samples folder of RADStudio (not officially supported, it is just an official sample). The TAnonymousThread<T> constructor is a class that simplifies the process of starting a thread and when the thread ends, this class updates the UI with data retrieved by the thread.

The TAnonymousThread<T> constructor (there are other overloads, but this the most used) expects three anonymous methods:

The background thread (the first function passed to the TAnonymousThread<T> constructor) creates a memory table using the TFDMemTable component (we will talk about this component in the FireDAC-related section) and then that object is passed to the second anonymous method that adds it to the form's components using the InsertComponent() method and binds it to the DBGrid causing the data visualization.

When the data is ready in the grid, a call to the ShowSuccessBalloon() function shows a balloon message in the tray area, informing users that their data is finally available. If the user clicks on the balloon (or double-clicks on the tray icon), the application is restored. The balloon message is shown in the following screenshot:

The balloon message when the data are ready in DBGrid

If the user clicks on the balloon, the form is restored. However, since Windows XP (with some variation in subsequent versions), the system restricts which processes can set the foreground window. An application cannot force a window to the foreground while the user is working with another window. The calls to SetWindowPos are needed to bring the form to the front.

In the included code, there is also another version of the recipe (20_VCLAppFlashNotification) that uses the most recent flash on the taskbar to alert the user. Consider this approach when you want to implement an application that, when minimized, has to alert the user in some way. The tray area may become rapidly crowded with icons. So consider to flash your icons in the taskbar instead.

The other code is required to correctly handle the memory ownership of the TFDMemTable instance.

The use of a tray icon is a well-known pattern in Windows development. However, the concept of I'll go into the background for a while, if you want, and I'll show you the notification as soon something happens is used very often on Android, iOS, and Mac OS X. In fact, some part of this recipe code is reusable also on Mac OS X, iOS, and Android. Obviously, using the right system to alert the user when the background thread finishes (for example, on a mobile platform) execution should use the notification bar. The thread handling of this recipe works on every platform supported by Delphi.

The way to go, in the previous scenario, is to develop a Windows service. In this recipe, we'll see how to write a good Windows service scaffold and this can be the skeleton for many other services, so feel free to use this code as a template to create all services that you will need.

The project has been created starting from the default project template accessible from File | New | Other | Delphi Projects | Service Application and then has been integrated with a set of functionalities to make it real.

All the low-level interfacing with Windows Service Manager is done by the TService class. In the ServiceU.pas component, there is the actual descendant of TService that represents the Windows service we are implementing. Its event handlers are used to communicate with the operating system.

Usually, a service needs to respond to the Windows ServiceController commands independently of what it is doing, so we need a background thread to do the actual work, while the TService.OnExecute event should not do any real work (this is not a must, but usually is the way to go). The unit named WorkerThreadU.pas contains the thread and the main service needed to hold a reference to the instance of this thread.

The background thread starts when the service is started (the OnStart event) and stops when the service is stopped (the OnStop event). The OnExecute event waits and handles the ServiceController commands but doesn't do any actual functional work. This is done using the ServiceThread.ProcessRequests(false); event in a while loop.

Usually, the OnExecute event handler looks like the following:

procedure TSampleService.ServiceExecute(Sender: TService);
begin
  while not Terminated do
  begin
    ServiceThread.ProcessRequests(false);
    TThread.Sleep(1000); 
  end;
end;

The waiting time of 1000 milliseconds is not a must, but consider that the wait time should be not too high because the service needs to be responsive to the Windows service controller messages, and not too low because, otherwise, the thread context switch may waste resources.

The background thread writes a line in a logfile once a second. While it is in a Paused state, the service stops writing. When the service continues, the thread will restart writing the log line. In the service event handlers, there is a logic to implement this change of state:

procedure TSampleService.ServiceContinue(Sender: TService;
   var Continued: Boolean);
begin
   FWorkerThread.Continue;
   Continued := True;
end;

procedure TSampleService.ServicePause(Sender: TService; 
   var Paused: Boolean);
begin
   FWorkerThread.Pause;
   Paused := True;
end; 

In the thread, there is the actual logic to implement the Paused state and in this case, it is fairly simple; we've to pause the writing of the logfile.

Here's an extract:

    Log := TStreamWriter.Create(
               TFileStream.Create(LogFileName, 
                       fmCreate or fmShareDenyWrite));
    try
      while not Terminated do
      begin
        if not FPaused then
        begin
          Log.WriteLine('Message from thread: ' + TimeToStr(now));
        end;
        TThread.Sleep(1000);
      end;
    finally
      Log.Free;
    end;

The boolean instance variable FPaused can be considered as a thread safe for this use.

Delphi services don't have a default description under Windows Service Manager. If we want to give a description, we have to write a specific key in the Windows registry. Usually, this is done in the AfterInstall event. In our service, write the following code in the AfterInstall event handler:

procedure TSampleService.ServiceAfterInstall(
   Sender: TService);
var
   Reg: TRegistry; //declared in System.Win.Registry;
begin
   Reg := TRegistry.Create(KEY_READ or KEY_WRITE);
  try
       Reg.RootKey := HKEY_LOCAL_MACHINE;
       if Reg.OpenKey(
         '\SYSTEM\CurrentControlSet\Services\' + name, 
         False {do not create if not exists}) then
    begin
         Reg.WriteString('Description', 
        'My Fantastic Windows Service');
      Reg.CloseKey;
    end;
  finally
       Reg.Free;
  end;
end;

It is not necessary to delete this key in the AfterUnInstall event because Windows deletes all the keys related to the service (under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<MyServiceName>) when it is actually uninstalled.

Let's try an installation. Build the project, open the Windows command prompt, and go to the folder where the project has been built and run this command:

C:\<ExeProjectPath>\WindowsService.exe /install

If all is okay, you should see this message:

The service installation is okay

Now, you can check in the Windows Services Console. You should find the service installed. Click on Start, wait for the confirmation, and the service should start to write its logfile.

Play with Pause, Continue, and check the file activity.

Windows services are very powerful. Using the abstractions that Delphi provides, you can also create an application that can act as a normal GUI application or as a Windows service after reading a parameter on the command line.

In the recipe folder, there is another recipe called 20_WindowsServiceOrGUI.

This application can be used as a normal Windows service using the normal command-line switches used so far, but if launched with /GUI, it acts as a GUI application and can use the same application code (not TService). In our example, the GUI version uses the same worker thread as the service version. This can be very useful for debugging purposes.

Run the application with the following command:

C:\<ExeProjectPath>\WindowsServiceOrGUI.exe /GUI

You will get a GUI version of the service, as shown in the following screenshot:

The GUI version of the Windows service

LogMessage('Your message goes here for SUCCESS', 
         EVENTLOG_SUCCESS, 0, 1);

The hard work is done by the operating system itself. We have to instruct Windows to provide the following information:

Let's start!

One application can register many file types. In some cases, I've used this technique to register some specific desktop database files to my application (FirebirdSQL Embedded database files or SQLite database files). So a double-click on such database file (registered with an application-specific extension) was actually a connection to that database.