Title: Working with the Delphi Object Repository
Question: How to add to, remove from, change, manage and understand the Delphi Object Repository.
Answer:
--------------------------
--------------------------
Working with Delphis Object Repository
--------------------------
--------------------------
Author: Phil Gilmore
Email: spgilmore@juno.com
Version: 1, Revision: 0
10/21/2003
Difficulty: Easy
--------------------------
Prerequisites
--------------------------
Delphi (This tutorial follows version 6)
Object-Oriented Programming Concepts
--------------------------
What is the object repository?
--------------------------
The object repository is where all root VCL forms and projects live. If you create a project in Delphi, you got a template from the repository and the IDE duplicated it or modified it just for your new project. If you ever added a new item to your project, you probably got it from the repository.
The repository is a collection of templates for building objects, in other words, classes. Although I will repeatedly call them objects, the object repository is usually used to generate CLASSES for your project, not objects.
The term Object Repository may be used to describe this collection of templates, or it may be used by some to describe the dialog that pops up when you choose NEW or ADD from the file menu. For clarity, Ill refer to this dialog as the New Items Dialog, as that is the text that appears in the title bar of said dialog.
There is also a dialog accessible from the TOOLS | REPOSITORY menu item. This dialog is called the Object Repository Properties dialog.
The items that are in the repository when you install Delphi are much more diverse than those that you may be able to add yourself. You will be able to add forms, frames, and projects.
--------------------------
Adding your objects to the repository
--------------------------
When you construct a form, frame or project that you wish to reuse as-is or use for a template in the future, you may add it to the repository. Your object will appear in the New Items dialog just as if it came with Delphi. It will be as easy to add as a blank form or login dialog.
If you wish to add a form or a frame, youll need to right-click on the form or frame and select Add To Repository from the popup menu. This will summon the Add Form to Repository Dialog. The title will say Add To Repository. It requires you to select the form or frame to be added to the repository, and requests a number of fields to be filled in. It also requires an icon.
The Title field is the text that will appear under the icon in the New Items dialog. The description should be as long as it needs to be to tell the user (or remind the author) what this object is used for. The author will be your name, and the page is the tab of the New Items dialog under which you want your icon to appear. The Icon, obviously, is the .ico image that will be displayed for this item.
If you wish to add a PROJECT to the object repository, you must select Project from the Main menu, then Add To Repository . This will summon the Add Project To Repository dialog. It has the same title as the previous Add dialog, but youll see that it is not the same dialog. This one lacks the form selection list. All the other criteria in this dialog is identical to the items in the previous dialog and should be entered in the same manner. When you click OK, your project will be added to the repository.
--------------------------
Managing the repository
--------------------------
Managing the repository is a trivial task. Start by opening the New Item Dialog. You may change views at any time by right-clicking in the listboxs whitespace. From that popup menu, you may select your view, and the desired sort order for the icons. You may also drag the corners of the window to size it. If you try using the DETAILS view, youll see all the information that you entered when you added an item the repository. Here you can see the description, author, etc. You may sort by any of these columns.
If you select PROPERTIES from the listbox popup menu, it will summon the object repository dialog. This dialog is also accessible from the TOOLS menu under REPOSITORY.
From this dialog, you can move objects between pages by selecting PROPERTIES from the listbox popup menu. You may select an object to add to the current project (or select a project) as it you were using the New Items dialog, but It also allows you to manage the tabs from the New Items dialog. It permits you to create new tabs, delete tabs, delete objects or assign them to different pages of the dialog.
--------------------------
Creating new objects from the repository
--------------------------
There are 4 types of objects that can be created from the repository. If you select any item from the NEW tab, youll see that the 3 radio buttons at the bottom of the dialog are disabled. This is the first type. These items are all special because theyre on the NEW tab. The other 3 are the types indicated by the radio buttons at the bottom of the listbox. You may USE, COPY or INHERIT an object from one of the other tabs.
The COPY method is the default and most common method of creating an object from the repository. The repository may contain objects that were intended as a base class for new objects, and others may be intended to be used as-is. Objects that should be used as-is can be created with the COPY radio button selected. To create a new object that inherits from the object in the repository, you may select INHERIT. Classes created with INHERIT or COPY will have the name of their base class followed by a 1. Youve seen this before when you create a new application with a form. The form inherits from the TForm object in the repository and is suffixed with a 1, making the name of your new object class TForm1.
Lets say you add a frame whose class name is declared like this:
Type TDateSelector = Class(TFrame)
You could add that project to the repository and then pull it back out. If you create the new object using the COPY radio selection, your new frame appears with this class declaration:
Type TDateSelector1 = Class(TFrame)
You can see that we have a class that is nearly the same as the object we put in the repository, but it has its own name. Youll also find that any changes you make wont affect the template that is stored in the repository.
If you create the new object using the INHERIT radio selection, your new frame appears with this class declaration:
Type TDateSelector1 = Class(TDateSelector)
You see that the base class is TDateSelector, which means we created a new class and derived it from the class that is in the repository.
If you create the new object using the USE radio selection, your new frame appears with this class declaration:
Type TDateSelector = Class(TFrame)
Youll find that the entire class is identical to the one that you added. If you change it, it changes in the repository, so it would have to be identical, wouldnt it?
--------------------------
Changing existing objects in the repository
--------------------------
Changing existing objects is dangerously easy to do. If you wish to change a form or frame class that you have already added to the repository, you need only add a new item to the current project, specifying the USE radio selection. This causes a direct reference to the class in the object repository to be added to your project. Any changes you make to this form or frame in the designer or to its class in the editor will immediately be applied to the object in the repository. This will also change the objects in any other projects that used this item with the USE radio selection. This can be dangerous. It is best to use the USE radio selection only for updating the item in the repository, then destroy the object and recreate it with a COPY or INHERIT radio selection.
If you try to change a project in the repository, youll find that there is no USE selection available. There is only a COPY option available. There is no way to change that. To update a project in the repository, you either need to delete it, change the original source and re-add it, or create a new project from the repository template, change it and add it as a new item alongside the original.
--------------------------
Changing Default Project Types
--------------------------
You may have seen the checkboxes in the Object Repository Dialog. These can be neat if you know what they do. If clicked one by accident, the result may surprise you. Lets follow along with an example to demonstrate. Open the object repository dialog. From the DIALOGS tab, select the DIALOG WIZARD object. Click the MAIN FORM checkbox. Click OK and then close the Delphi IDE. Restart the IDE and watch what happens. Wow. Before Delphi would pop up with your empty form and blank form class in the editor. Now, the form is not there. You only see a dialog wizard in front of you. You may think thats strange and just close it, then go to NEW | APPLICATION to open the type of project youre familiar with.. Lo and behold, the same thing happens. You see the Dialog wizard. The dialog wizard will always pop up whenever you choose a new VCL application, despite the method you use.
Try walking through the wizard and youll get a blank form. If you want to add another form, you could do that. Go to NEW | FORM. Youll see that you get a normal form.
To undo this madness, go back to the object repository dialog and select the dialog wizard again. Uncheck the MAIN FORM checkbox, and mark the NEW FORM checkbox and close the dialog. Again, go to the New Items dialog and select Application. This time, our familiar blank form comes up. Now when we want to add a second form, youll find that again, the dialog wizard is launched. This is the effect of the NEW FORM checkbox in the object repository dialog. To change it back to the regular blank form, uncheck this checkbox as explained before.
Although I havent found much use for this feature, you can see how you could become bewildered to find a SOAP WSDL import wizard popping up when they start Delphi or when they add a new form unless you know how its done. If youre going to torment your coworkers with this, please wait until April Fools day. Its a mean prank. Youll need a good excuse.
--------------------------
Preserving and Restoring your repository
--------------------------
Sorry. This author knows no way to preserve the repository or to merge it on another machine, etc. My experience is with Delphi 6. Perhaps successive versions will remedy this. Until then, try saving all your objects in their own directories under a parent directory named MyRepository before adding them to the repository. This way, you can back up that directory using your preferred tools, and while it may take some time to rebuild your repository if your machine crashes, it is possible and your data will be preserved. Remember to store the icon with it by the same name. You can see an example of how Borland did this in the \program files\borland\delphi_\objrepos directory. I dont condone mashing all the little ones into a single directory the way they did, but it might be okay for you. I would like to suggest using individual directories, at least for larger templates, like you see for CLXMDIAPP, LOGOAPP, MDIAPP, SDIAPP, and WIN2KAPP.
If anyone knows of any utilities for backup and restore of the Delphi or C++Builder repositories, please inform the author (spgilmore@juno.com) so that it may be suggested in this tutorial.