Delphi Cookbook - Second Edition

VCL styles can be used to revamp an old application or to create a new one with a non-standard 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. So, let's create a new VCL application and drag and drop some components onto the main form (for example, two TButton, one TListBox, one TComboBox, and a couple of TCheckBox).

You can now see the resultant form that is running on my Windows 8.1 machine:

Figure 1.1: A form without style

Now, we've got to apply a set of nice styles by following these steps:

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

The following lines are the interesting section:

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 added a line just before the creation of the main form, setting the default style for all the applications using TStyleManager.TrySetStyle static methods.

TStyleManager is very important class when dealing with VCL styles. We'll see more about it in the upcoming recipe, where you'll learn how to change styles at runtime.

Delphi and C++ Builder 10.1 Berlin come with 36 VCL styles available in the folder (with a standard installation):

C:\Program Files (x86)\Embarcadero\Studio\18.0\Redist\styles\vcl\

Moreover, it is possible to create your own styles or modify the existing ones using the Bitmap Style Designer. You can access it by going to Tools | Bitmap Style Designer Menu.

For more details on how to create or customize a VCL style, visit http://docwiki.embarcadero.com/RADStudio/en/Creating_a_Style_using_the_Bitmap_Style_Designer.

The Bitmap Style Designer also provides test applications to test VCL styles.

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

In this recipe, we'll change the style while the 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.

Style manipulation at runtime is done using the class methods of the TStyleManager class. Follow these steps to change the style of your VCL application at runtime:

The TStyleManager class has all the methods we need to:

After loading new styles from the disk, the new styles are completely similar to the styles linked in 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 (some third-party controls are not be style aware). If your external components do not support styles, you will end up with some styled controls (the original included in Delphi) and some not styled (your external third-party controls)!

Go to Tools | Bitmap Style Designer. Using a custom VCL style we can also:

Many VCL controls are able to delegate their drawing, or part of it, to user code. It 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 percent of exams already passed with a progress bar and, if the percent is higher than 50, there should also be a check in another column. Moreover, after listening to the pieces played at the exams, each musician received votes from an external examination committee. The last column needs to show the mean of votes from this committee as a rating from 0 to 5.

We'll use a special in memory table from the FireDAC library. FireDAC is a new data access library from Embarcadero 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, which holds its data only in memory. However, at the end of the section, there are some links to the FireDAC documentation, and I strongly suggest that you read them if you still don't know FireDAC:

By setting the DBGrid property DefaultDrawing to False, we told the grid that we want to manually draw all the data into every cell. OnDrawColumnCell allows us to actually draw using 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 we are currently drawing. In this case, we want to draw only the calculated columns and the Rating field in a custom 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 call method, DefaultDrawColumnCell that passes 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 a Rect object (of type TRect) that represents the specific area we're about to draw. There is a column object (of type TColumn) that is a reference to the current column of the grid and a State (of type TGridDrawState) that is a set of the grid cell states (for example, Selected, Focused, HotTrack, and many more). 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 Pascal Sets Intersect to know whether the current cell should be drawn as a Selected or Focused cell. Refer the following code for better clarity:

  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 into the Vcl.GraphUtil unit. Otherwise, if you need images, you could use TImageList to hold all the images needed by your grid, as we did in this recipe for the Rating field.

The good news is that the drawing code can be reused by different kinds of controls, so try to organize your code in a way that allows code reutilization by 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, testable function or class.

As we saw in the recipe, Customizing TDBGrid, many VCL controls are able to delegate their drawing, or part of it, to user code. It 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 the processing in a way 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've used TImageList as the image repository for the listbox. Using the Index parameter, we've read the correspondent image in TImageList and drawn on the listbox Canvas. 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 that you 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 OnDrawItem, you can do whatever you want with the TListBox Canvas. Moreover, the State parameter (of type TOwnerDrawState) tells you in which states the listbox item is (for example, Selected, Focused, HotTrack, and so on). So, you can use a different kind of drawing, depending on the item state. Check out the Customizing TDBGrid recipe to find out about the TDBGrid owner drawing for an example about the 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() in 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.

Let's say you are in charge of developing a controller panel for a hotel's light system. You have a list of lamps to power on, and you, using some hardware, have to power on some lamps by clicking on a button. Customers tell you that buttons should show some additional information about the lamp, for example:

The question is how to implement this kind of UI. One of the possible ways is to use TDrawGrid and draw all the needed details in each cell, using the cell also as a button. Using TDrawGrid, you have a grid of buttons for free. You have also the greatest flexibility about the information displayed because you are using the TCanvas method to custom draw each cell. This is quite a popular solution for this kind of non-standard UI. However, when you deploy this application, the customers ask about the possibility of changing the style of the application to fit the needs of the current user. So, you think about VCL styles, and you are right. However, the graphics drawn into the cells don't follow the currently selected VCL style, and your beautiful application becomes a bad mix of colors. In other words, when users change the selected VCL style, all the controls reflect the new style, but the owner drawn grid, which is unaware to the selected style, doesn't look as nice as the rest of the UI. How to solve this problem? How to draw custom graphics by adhering to the selected VCL style? In this recipe, you'll learn how to do it using the lamp control grid example.

At design time, the form looks like the one shown in the following screenshot:

Figure 5.1 The form as it looks at design time

When the form is created, the list of available styles is loaded in the Radio group using code similar to the following one:

  RadioGroup1.Items.Clear;
  RadioGroup1.Columns := Length(TStyleManager.StyleNames);
  for LStyleName in TStyleManager.StyleNames do
    RadioGroup1.Items.Add(LStyleName);
  RadioGroup1.ItemIndex := 0;
  TStyleManager.SetStyle('Windows');

Then, a list of the TLampInfo object is created and initialized using the information contained in the Zones array. After that, the draw grid is initialized according to the LAMPS_FOR_EACH_ROW constant. Here's the relevant code:

  FLamps := TObjectList<TLampInfo>.Create(True);
  for I := 1 to LAMPS_FOR_EACH_ROW * 4 do
  begin
    FLamps.Add(TLampInfo.Create(Zones[I]));
  end;

  DrawGrid1.DefaultColWidth := 128;
  DrawGrid1.DefaultRowHeight := 64;
  DrawGrid1.ColCount := LAMPS_FOR_EACH_ROW;
  DrawGrid1.RowCount := FLamps.Count div LAMPS_FOR_EACH_ROW;

The FormCreate event handler initializes the styles list and the list of the lamps (the model) of the form. Now, we'll see how the other event handlers will use them.

The TDrawGrid OnSelectCell event, as the name suggests, is used to address the current "lamp" from the FLamps and to toggle its state. That's it. If the lamp is on, then the lamp will be powered down, else the lamp will be powered on. After that, the code forces the grid to redraw using the Invalidate method:

procedure TMainForm.DrawGrid1SelectCell(Sender: TObject; ACol, ARow: Integer; var CanSelect: Boolean);
begin
  FLamps[ACol + ARow * LAMPS_FOR_EACH_ROW].ToggleState;
  DrawGrid1.Invalidate;
end;

Now, really interesting things happened in the DrawThemed method called inside the TDrawGrid OnDrawCell event. This method receives information about the coordinates of the cell to draw, and then it draws a button on the canvas using the information contained in the correspond TLampInfo instance. The code is quite long, but an interesting concept is that no specific colors are used. When it is necessary to draw something, the code asks StyleService to get the correct color according to the current style. This approach is also used for font color and for system colors. Here's a handy table that summarizes these concepts:

So, when we have to highlight the (pseudo) button, if there are electrical problems on the power line, we will use the following code:

if LLamp.ThereAreElectricalProblems then
   LCanvas.Brush.Color := StyleServices.GetStyleColor(scButtonHot)
else
   LCanvas.Brush.Color := StyleServices.GetStyleColor(scWindow);
LCanvas.FillRect(LRect);

When we've got to draw normal text, we will use the following code:

LCanvas.Font.Color := StyleServices.GetStyleFontColor(sfButtonTextNormal);
LCanvas.TextRect(LRect, LValue, [TTextFormats.tfCenter, TTextFormats.tfVerticalCenter]);

It is clear that the paradigm is:

Clicking on the Simulate Problems button, it is possible to see how the graphics is drawn in the case of problems on the power line. The images are drawn directly from the image list using the following code:

procedure TMainForm.DrawImageOnCanvas(ACanvas: TCanvas; var ARect: TRect; ImageIndex: Integer);
begin
  ImageList1.Draw(ACanvas, ARect.Left + 4, ARect.Top + ((ARect.Bottom - ARect.Top) div 2) - 16, ImageIndex);
end;

Using this approach, the application created in this recipe, which has a lot of custom graphics, behaves very well even on VCL styles. Here are some screenshots:

Fig. 5.2 The application while it is using the Windows style

Fig. 5.3 The application while it is using the Luna style

Fig. 5.4 The application while it is using the Charcoal Dark Slate style

As you see, the application correctly draws the owner draw parts of the UI using the right colors from the selected style.

The VCL style infrastructure is very powerful. In the case of TWinControl descendants, you can even define specific hooks for you components using TStyleHook. TStyleHook is a class that handles messages for controls acting as a wrapper for the hooked control. If you have a custom control that you want to be style enabled, inherit from TStyleHook and provide custom processing for that control. As examples, see TEditStyleHook and TComboBoxStyleHook. You need to register the style hook class with the style engine using the RegisterStyleHook method as shown in the following code:

TCustomStyleEngine.RegisterStyleHook(TCustomEdit, TEditStyleHook);

Moreover, the StyleServices function returns an instance of TCustomStyleServices, which provides a lot of customization methods related to the VCL styles. Check out the related documentation at http://docwiki.embarcadero.com/Libraries/en/Vcl.Themes.TCustomStyleServices_Methods to see all the possibilities

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 code repository (Chapter1\RECIPE06).

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:

Figure 5.1: The main form containing seven embedded child forms

The project is composed of a bunch of forms. The main form has TTabControl, which allows us to switch between the active forms. All embedded forms inherit from EmbeddableForm. The most important is the method Show shown here:

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

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

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

The AddForm method is in charge of adding an actual instance of a form into the tabs, keeping a reference to it. The following code shows how it 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 out 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 us to create flexible GUIs without using TPageControl and Frames. Probably, for the end user, this multi-tabbed 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's point of view, the multi-tabbed 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 done 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 doesn't rely on Windows Messaging and so is also cross-platform) may be based on the System.Messaging.TMessageManager class. More information about TMessageManager can be obtained at http://docwiki.embarcadero.com/Libraries/en/System.Messaging.TMessageManager.

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 an advantage when you have to read a JSON string into some kind of language-specific structure, because every modern language supports the JSON datatypes as simple types or as HashMap (in the case of JSON objects) or List (in the case of JSON arrays). 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 the JSON types with a nice object oriented interface. In this recipe, you'll see how to generate, modify, and parse a JSON string.

Although not the fastest or the most standard compliant on the market, JSON usability is important 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 one.

Other notable JSON parsers are:

If your main concern is speed, then check out these alternative JSON 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. Just as an example, in Chapter 5, The Thousand Faces of Multithreading, in the Using tasks to make your customer happier recipe 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, you will see how to carry out 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), to validate an XML using another XML (XML Schema or DTD), to transform an XML into another kind of format using another XML (XSLT), and many others use http://en.wikipedia.org/wiki/List_of_XML_markup_languages. The good thing is that just like XML, 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:

TXMLDocument uses a Windows-only vendor by default. If you are designing a FireMonkey application that is intended to run on other platforms than Windows, select a cross-platform DOM vendor.

XSLT allows you to transform an XML to something else, using another XML as a "stylesheet." As we saw in this recipe, you can use an XML file and an XSLT file to generate an HTML page that shows the data contained in the XML using XSLT to format the data.

The following function loads the XML and an XSLT documents from two string variables. Then, we use the XSLT document to transform the XML document. The code that follows shows this in detail:

function Transform(XMLData: string; XSLT: string): String;
var
  LXML, LXSL: IXMLDocument;
  LOutput: WideString;
begin
  LXML := LoadXMLData(XMLData);
  LXSL := LoadXMLData(XSLT);
  LXML.DocumentElement.TransformNode(
    LXSL.DocumentElement, LOutput);
  Result := String(LOutput);
end;

This function doesn't know about the output format because it is defined by the XSLT document. The result could be an XML, an HTML, a CSV, or a plain text, or whatever the XSLT defines, but the code does not change.

XSLT can be really useful. I recommend that you go and visit http://www.w3schools.com/xsl/xsl_languages.asp for further details on the language.

In the good old Pascal days, there were a set of functions to handle the I/O (AssignFile, Reset, Rewrite, CloseFile, and many more). Now, we've a bunch of classes. All Delphi streams inherit from TStream and can be used as the internal stream of one of the adapter classes (by adapter, I mean an implementation of the Adapter, or Wrapper, design pattern from the Gang of Four famous book about design patterns).

There are 10 fundamental types of streams.

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

As Joel Spolsky says, "You can no longer pretend that "plain" text 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? And 1 GB? How will my program behave in that case?" Handling a file one line at time and not loading all the file contents in memory is usually a good insurance for these cases. A stream of data is a good way to do this. In this recipe, you'll see the practical utilization of streams, stream writers, and stream readers.

The project is not complex. All the interesting stuff happens in btnWriteFile and btnReadFile.

To write the file, TStreamWriter is used. TStreamWriter (as its counterpart TStreamReader) is a wrapper for a TStream descendant 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 underling stream using the BaseStream property of the wrapper. Just after having written 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 TMemo at all in your real project. The btnReadFile simply opens the file using a stream and passes the stream to TStreamReader that, using the right encoding, will read the file one line at a time.

Now, let's run 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:

Figure 8.1: Garbage text written to the file using the wrong encoding. No one line 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. By clicking on btnWriteFile, you will see the correct text in the memo. Try to change the current encoding 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 to safely read file's contents. To read the text that we wrote, we have to use the same encoding. Play with other encodings to see the different behavior.

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

Also, a less known possibility, if you ever will write a program that needs to access the good old STD_INPUT, STD_OUTPUT, or STD_ERROR, is that 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 has some helper methods to write shorter and more readable code.

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 the services that you will need.

The project has been created starting from the default project template accessible by going to 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 the Windows Service Manager is done by the TService class. In ServiceU.pas, 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 Service Controller 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 ServiceController commands but doesn't do any actual functional work. This is done using ServiceThread.ProcessRequests(false); in a while loop.

Usually the OnExecute event handler is like this:

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

The wait 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. It should not be 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 the 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 thread safe for this use.

Delphi services don't have a default description under the 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, this is the code to write 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. Then, run this command:

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

If everything is ok, you should see this message:

Figure 11.1: The service installation is ok

Now, you can check under the Windows Services Console and 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 and Continue and check the file activity.

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

In the respective 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 also 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 here:

Figure 11.2: 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:

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 (Firebird SQL Embedded database files or SQLite database files). So, a double-click actually was a connection to that database.

TTaskdialog is a dialog box somewhat like the standard call to Application.MessageBox in the VCL but much more powerful. Task Dialog API has been available since Windows Vista and Windows Server 2008, and your application must be theme enabled to use it (go to Project | Options | Application | Runtime Themes | Enable Runtime Themes).

Besides the usual default set of buttons (OK, Cancel, Yes, No, Retry, and Close), you can define extra buttons and many other customizations. The following Windows API provides task dialogs:

More information about API utilization can be obtained from https://msdn.microsoft.com/en-us/library/windows/desktop/bb787471(v=vs.85).aspx.

While the API can be useful in some border cases, the VCL comes with a very nice component that does all the low-level stuff for us. Let's see the sample program that shows how it is simple to create a modern look and feel application.

Open the TaskDialogs.dproj project and understand how it works.

There are six buttons on the form. The first one shows a simple utilization of the Task Dialog API, while the other five show a different utilization of the TTaskDialog component, which wraps that API.

The first button uses the Windows API directly with the following code:

procedure TMainForm.btnAPIClick(Sender: TObject);
var
  LTDResult: Integer;
begin
  TaskDialog(0, HInstance,
    PChar('The Title'),
    PChar('These are the main instructions'),
    PChar('This is another content'),
    TDCBF_OK_BUTTON or TDCBF_CANCEL_BUTTON,
    TD_INFORMATION_ICON, @LTDResult);
  case LTDResult of
    IDOK:
      begin
        ShowMessage('Clicked OK');
      end;
    IDCANCEL:
      begin
        ShowMessage('Clicked Cancel');
      end;
  end;
end;

The TaskDialog function is declared inside the Winapi.CommCtrl.pas unit. So far, you could ask, "Why should I use a component for TaskDialogs? Seems quite simple." Yes, it is, if you only want to mimic MessageDlg, but things get complicated very fast if you want to use all the features of the Task Dialog API. So, the second button uses the TTaskDialog component. Let's see the relevant properties configured at design time for the tdSimple component:

object tdSimple: TTaskDialog
  Caption = 'The question'
  CommonButtons = [tcbYes, tcbNo]
  DefaultButton = tcbYes
  ExpandButtonCaption = 'More information'
  ExpandedText = 'Yes, you have to decide something about this question...' + ' but I cannot help you a lot'
  Flags = [tfUseHiconMain, tfUseHiconFooter, tfVerificationFlagChecked]
  FooterIcon = 4
  FooterText = 'This is an important question...'
  Text = 'To be or not to be, this is the question. To be?'
  Title = 'William ask:'
end

As you can see, only the minimum properties have been set, just to show the power of the component. This configuration shows up a dialog with two buttons labelled Yes and No. The TTaskDialog component can be configured at design time using the Object Inspector, or can be configured at runtime by code. In this first example, the configuration is defined at design time so that at runtime we only have to call the Execute method and read the user response. Here's the code that actually uses the tdSimple instance:

procedure TMainForm.btnSimpleClick(Sender: TObject);
begin
  tdSimple.Execute; //show the taskdialog
  if tdSimple.ModalResult = mrYes then
    ShowMessage('yes')
  else
    ShowMessage('no')
end;

Even in this case, it is quite simple, but let's go deeper with the configuration. Let's say that we need a TaskDialog similar to the following screenshot:

Fig. 12.1 The TTaskDialog component is configured to show three radio buttons

Using the plain API is not so simple to do this. So, let's see how to configure the component:

object tdRadioButtons: TTaskDialog
  Caption = 'The question'
  DefaultButton = tcbYes
  ExpandButtonCaption = 'More information'
  ExpandedText = 
    'Yes, you have to decide something about this question... ' + 'but I cannot help you a lot'
  Flags = [tfUseHiconMain, tfUseHiconFooter, tfVerificationFlagChecked]
  FooterIcon = 4
  FooterText = 'This is an important question...'
  RadioButtons = <
    item
      Caption = 'Yes, I want to buy this book'
    end
    item
      Caption = 'No, this book is awful'
    end
    item
      Caption = 'Maybe in the future'
    end>
  Text = 'Do you wanna buy "The Tragedy of Hamlet"?'
  Title = 'William ask:'
end

The preceding block of code contains the definition for the three radio buttons. The following code shows the dialog and the retrieval of the result:

procedure TMainForm.btnRadioClick(Sender: TObject);
begin
  tdRadioButtons.Execute;
  if tdRadioButtons.ModalResult = mrOk then
    ShowMessage('Selected radio button ' + tdRadioButtons.RadioButton.ID.ToString);
end;

Even in this case, we have defined the properties at design time so that the runtime code is quite simple. Just note that the user choice is stored in the RadioButton.ID property.

The TTaskDialog.Flags property can greatly change the behavior of the dialog. Here's the meaning of each element of its set:

The real power of TaskDialogs comes when you build your dialog at runtime. Let's check what the fourth button does under the hood:

procedure TMainForm.btnConfirmClick(Sender: TObject);
var
  LFileName: string;
  LGSearch: String;
const
  GOOGLE_SEARCH = 99;
begin
  LFileName := 'MyCoolProgram.exe';
  tdConfirm.Buttons.Clear;
  tdConfirm.Title := 'Confirm Removal';
  tdConfirm.Caption := 'My fantastic folder';
  tdConfirm.Text :=
    Format('Are you sure that you want to remove ' + 'the file named "%s"?', [LFileName]);
  tdConfirm.CommonButtons := [];
  with TTaskDialogButtonItem(tdConfirm.Buttons.Add) do
  begin
    Caption := 'Remove';
    CommandLinkHint := Format('Delete file %s from the folder.', [LFileName]);
    ModalResult := mrYes;
  end;
  with TTaskDialogButtonItem(tdConfirm.Buttons.Add) do
  begin
    Caption := 'Keep';
    CommandLinkHint := 'Keep the file in the folder.';
    ModalResult := mrNo;
  end;

  if TPath.GetExtension(LFileName).ToLower.Equals('.exe') then
  begin
    with TTaskDialogButtonItem(tdConfirm.Buttons.Add) do
    begin
      Caption := 'Google search';
      CommandLinkHint := 'Let''s Google tell us what ' + 'this program is.';
      ModalResult := GOOGLE_SEARCH;
    end;
  end;

  tdConfirm.Flags := [tfUseCommandLinks];
  tdConfirm.MainIcon := tdiInformation;

  if tdConfirm.Execute then
  begin
    case tdConfirm.ModalResult of
      mrYes:
        ShowMessage('Deleted');
      mrNo:
        ShowMessage(LFileName + 'has been preserved');
      GOOGLE_SEARCH:
        begin
          LGSearch := Format('https://www.google.it/#q=%s', [LFileName]);
          ShellExecute(0, 'open', PChar(LGSearch), nil, nil, SW_SHOWNORMAL);
        end;
    end; //case
  end; //if
end;

It seems like a lot of code, but it is simple and can be easily parameterized and reused inside your program. The resultant dialog is as shown:

Fig. 12.3 The dialog customized by code

The third choice allows the user to search on Google about the program executable name. This is not a common choice in the MessageDlg dialog where buttons are predefined, but using the Task Dialog you can even ask something "strange" to the user (such as "do you want to ask Google about it?")

To achieve a better apparent speed, progress bars are great! The Task Dialog API provides a simple way to use progress bars inside dialogs. The classic Delphi solution relays a custom form with a progress bar and some labels (just like the "Compiling" dialog that you see when you compile a program within the Delphi IDE). However, in some cases, you need some simple stuff done and a Task Dialog is enough. If TTaskDialog has the tfCallbackTimer flag and tfShowProgressBar, the OnTimer event will be called every 200 milliseconds (five times a second), and the dialog will show a progress dialog that you can update within the OnTimer event handler. However, the OnTimer event handler runs in the main thread so that all the related advice applies (if the UI becomes unresponsive, consider a proper background thread and a queue to send information to the main thread).

This is the design time configuration of TTaskDialog tdProgress:

object tdProgress: TTaskDialog
  Caption = 'Please wait'
  CommonButtons = [tcbCancel]
  ExpandButtonCaption = 'More'
  ExpandedText = 
    'A prime number (or a prime) is a natural number greater'+' than 1 that has no positive divisors other than 1 ' + 'and itself.'
  Flags = [tfAllowDialogCancellation, tfShowProgressBar, 
tfCallbackTimer]
  FooterIcon = 3
  FooterText = 'Please wait while we are calculate prime numbers'
  Text = 'Let'#39's calculate prime numbers up to 1000'
  Title = 'Calculating prime numbers...'
  VerificationText = 'Remember my choice'
  OnButtonClicked = tdProgressButtonClicked
  OnTimer = tdProgressTimer
end

There are two event handlers, one to handle click on the Cancel button inside the dialog and one to handle the callback:

const
  MAX_NUMBERS = 1000;
  NUMBERS_IN_A_SINGLE_STEP = 50;

procedure TMainForm.tdProgressButtonClicked(Sender: TObject;
  ModalResult: TModalResult; var CanClose: Boolean);
begin
  if not FFinished then
  begin
    tdProgress.OnTimer := nil;
    ShowMessage('Calculation aborted by user');
    CanClose := True;
  end;
end;

procedure TMainForm.tdProgressTimer(Sender: TObject; TickCount: Cardinal;
  var Reset: Boolean);
var
  I: Integer;
begin
  for I := 1 to NUMBERS_IN_A_SINGLE_STEP do
  begin
    if IsPrimeNumber(FCurrNumber) then
      Inc(FPrimeNumbersCount);
    tdProgress.ProgressBar.Position := FCurrNumber * 100 div MAX_NUMBERS;
    Inc(FCurrNumber);
  end;

  FFinished := FCurrNumber >= MAX_NUMBERS;
  if FFinished then
  begin
    tdProgress.OnTimer := nil;
    tdProgress.ProgressBar.Position := 100;
    ShowMessage('There are ' + FPrimeNumbersCount.ToString + ' prime numbers up to ' + MAX_NUMBERS.ToString);
  end;
end;

To not block the main thread, the prime numbers are calculated a few at a time. When the calculation is ended, the callback is disabled by setting the OnTimer event handler to nil.

In other words, the real calculation is done in the main thread, so you should slice your process in to smaller parts so that it can be executed one (small) piece at time.

The following code fires the progress Task Dialog:

procedure TMainForm.btnProgressClick(Sender: TObject);
begin
  FCurrNumber := 1;
  FFinished := False;
  FPrimeNumbersCount := 0;
  tdProgress.ProgressBar.Position := 0;
  tdProgress.OnTimer := tdProgressTimer;
  tdProgress.Execute;
end;

Here's the resultant dialog:

Fig. 12.4 The Task Dialog with an embedded Progress Bar

The new Task Dialog API can give your application a fresh breath, but that comes with cost because it works only on Vista or better, with enabled themes. So, how to work around the problem if you need to run the application also in Windows XP or in machine without themes enabled? For button 6, there's a simple code to check whether you can safely use the TTaskDialog component or whether you have to come back to normal ShowMessage or MessageDlg. Here's the event handler for the button 6:

procedure TMainForm.btnCheckWinVerClick(Sender: TObject);
var
  LTaskDialog: TTaskDialog;
begin
  if (Win32MajorVersion >= 6) and ThemeServices.ThemesEnabled then
  begin
    LTaskDialog := TTaskDialog.Create(Self);
    try
      LTaskDialog.Caption := 'MY Fantastic Application';
      LTaskDialog.Title := 'The Cook Task Dialog!';
      LTaskDialog.Text :=
        'This is a Task Dialog, so I''m on Vista ' + 'or better with themes enabled';
      LTaskDialog.CommonButtons := [tcbOk];
      LTaskDialog.Execute;
    finally
      LTaskDialog.Free;
    end
  end
  else
  begin
    ShowMessage('This is an old and boring ShowMEssage, ' + 'here only to support old Microsoft Windows OS ' + '(XP and below)');
  end;
end;

Try to disable the themes for your application and click on button 6.

Obviously, it is strongly suggested that you wrap this code in a function so that you do not have to write the same check code repeatedly.