1. Technology
RTL reference|Glossary|Tips/Tricks|FREE App/VCL|Books|Link Back

TInstanceControl
Full source code of a Delphi component that can control the behavior of your application's multiple instances: with the option to limit the number of running instances. Part 2 of the "Controlling the number of application instances" article.
Win prizes by sharing code!
Do you have some Delphi code you want to share? Are you interested in winning a prize for your work?
Delphi Programming Quickies Contest
More of this Feature
Download component
Join the Discussion
"Post your views, comments, questions and doubts to this article."
Discuss!
Related Resources
Run-once enabling an application
Building components (tutorials)
Windows API

A promise is a promise. As agreed in the "Controlling the number of application instances" article, here I bring you the full source code of a Delphi component, TadpInstanceControl, designed to control the behavior of your application's multiple instances.

Instance control?
Yep. Sooner or later you'll be creating an application that you want to be run only once - with the option to prevent the second instance of the application from starting. There are many situations and reasons why you would need to make sure that only one instance of your application executes. For example, if your application is relying on the Registry, having multiple instances of the same application reading and writing registry data files may result in data corruption.

We've already discussed how to "run-once" enable a Delphi application that can check for its previous (running) instance. Along the process, several techniques of implementing such a check were discussed; as well as how to bring your already running application to the foreground, if a user tries to run it "one more time". The article presented a copy-to-go code to control the behavior of your application's multiple instances: with the option to limit the number of running instances.

This time I bring you all the code you need, encapsulated in one single component - including full source code.

TadpInstanceControl
The TadpInstanceControl VCL Delphi component is designed to prevent users from running "too many" instances of an application.

Usage
The usage is very simple: just drop the component on the application's main form. Set the MaxInstances integer property: let it have the value of 1 if you want to enable only one instance of the application, set it to 5 (for example) if only 5 instances can be run simultaneously. By default, when TadpInstanceControl detects that maximum running instances have been reached, it brings the last started instance's main form to front and closes the application. You can even customize application's behavior by handing the OnMaxInstancesReached event. The component also exposes the Enabled property - thus enabling you to enable or disable its "task".

Implementation
The TadpInstanceControl component uses file mapping to share data between multiple instances of an application. The idea is presented in the "The file mapping approach" page of the "Controlling the number of application instances" article.

As you will see inside the source (look for the "ThisOnce" TObject type variable), only one copy of this component can be dropped on a form - or an EInstanceControl exception will be raised. This needs to be done since two TadpInstanceControl components would prevent you from running your application even only once.

When the max instances has been reached (MaxInstancesReached procedure inside the source), and the application is going to be terminated, the component hides the application's hidden window to avoid a "flash" on the taskbar.

Installing into a Component palette
First, download the component. The TadpInstanceControl comes as a single unit file (.pas extension). You'll need to add the component into an existing package. Here's "How to Install Custom Component in Delphi (into Existing Package)"

TadpInstanceControl: example application
Here's how to prevent a user from running your Delphi application more that two times:
  1. Start a new Delphi project and drop a TadpInstanceControl on a form (from the "delphi.about.com" component palette).
  2. By default, the Enabled property is set to True, MaxInstances is set to 1.
  3. Set the MaxInstances property to 2.
    TadpInstanceControl properties in Object Inspector
  4. Handle the OnMaxInstancesReached event.
    TadpInstanceControl's event in Object Inspector

    Here's an example:

    procedure TForm1.adpInstanceControl1MaxInstancesReached(
          Sender: TObject;
          const LastInstanceHandle: Cardinal);
    begin
      ShowMessage('Ups I cannot be run! Bye, Bye.');
    end;
    

    Note the LastInstanceHandle parameter in the procedure - it is the handle to the last started instance's main form.

  5. Run the application 2 times. Now try to run it one more time ... ups :

    TadpInstanceControl at work!

That's it. Don't forget to download the component; and as always if there are any questions or comments please post them on the Delphi Programming Forum.

Next page > Full source code! > Page 1, 2

All graphics (if any) in this feature created by Zarko Gajic.

More Delphi
· Learn another routine every day - RTL Quick Reference.
· Download free source code applications and components.
· Talk about Delphi Programming, real time.
· Link to the Delphi Programming site from your Web pages.
· Tutorials, articles, tech. tips by: DATE or by TOPIC.
Stay informed with all new and interesting things about Delphi (for free).
Subscribe to the Newsletter
Name
Email

Got some code to share? Got a question? Need some help?

©2014 About.com. All rights reserved.