The Multiple Document Interface

Transcription

1 Tips and techniques for Delphi April 1997 Vol. 3 No. 4 US $7.50 Simulate MDI without Multiple Document Interface overhead by Brendan Delumpa Because of space considerations, the full source listings for this article don t appear in the journal. You can use anonymous FTP to download a ZIP file of the entire project from ftp.cobb.com/ddj. The filename is SIM_MDI.ZIP. The Multiple Document Interface (MDI) has been a mainstay GUI application paradigm for Windows since its inception. Though Microsoft now dismisses it as an outdated interface standard to be supplanted by the Single Document Interface (SDI), it seems that many software developers just can t get away from it. And to this day, you ll see that many programs are still built around MDI, despite Microsoft s recommendation. MDI remains popular among developers as evidenced by the software packages that even today follow MDI conventions. I d say this popularity is due to the natural application integration MDI affords developers. Think about it for a moment: Every child window is contained in a single, main application window, so it isn t necessary to think about screen locality or to perform really complex window management routines. Windows offers built-in support that makes MDI window management easy and convenient. And since MDI has been around for several years, Microsoft has had time to refine it. These features all contribute to a very attractive foundation on which to build applications. It s no wonder that MDI applications remain so popular. Unfortunately, all the ease and convenience comes with a lot of resource baggage, not to mention some oddities that many developers have run across at one time or another. Let s take a look at some of these quirks. Overcoming MDI s shortcomings By default, programs create MDI child windows when they start, and those windows remain in memory until the program ends. This retention isn t such a bad thing if the child windows are fairly simple forms with just a few components. However, if an MDI program has several child windows containing multiple embedded components, then you may run into resource problems. One way to avoid such problems is to create the children only when you need them and destroy them as soon as you ve finished with them. That is, never create the child windows at program startup. MDI forms frequently don t act like non- MDI forms in some very important respects. For instance, if you set the FormStyle property of an MDI child window to wsmaximized, the child window first pops up in a normal state and then maximizes, producing an annoying flash. One way to fix this behavior is to enclose the window creation of the child window within a LockWindowUpdate block. IN THIS ISSUE 1 Simulate MDI without Multiple Document Interface overhead 6 Creating perforated forms 8 Displaying virtual memory information 11 Delphi s dynamic data structures 12 Understanding indirect scope 16 VCL for C++ programmers, Part II A Publication of The Cobb Group

2 The following code illustrates how you accomplish this enclosure: procedure TForm1.Button1Click(Sender: TObject); LockWindowUpdate(Handle); Form2 := TForm2.Create(Application); Form2.Show; LockWindowUpdate(0); The LockWindowUpdate() function delays screen updates for a window specified by its handle; it doesn t refresh the screen until you call LockWindowUpdate(0). Any code enclosed within this block will run without affecting anything onscreen. This is brute-force programming at its best. Furthermore, unlike non-mdi forms, MDI child forms in Delphi 1.0 can t be hidden. According to Microsoft, hiding an MDI form creates some internal problems in Windows 3.1 itself. Thus the Windows API, by default, prevents you from hiding forms. The solution (which I won t go into here) involves making some Windows API calls to hide the windows a dicey proposition at best, and not really recommended. You re probably better off if you simply destroy the window using Action := cafree; in the OnClose event handler to remove the form from view. Remember, you can always re-create the form if you need to. All in all, while these examples don t add up to much, they do indicate the existence of some internal complexities and quirks in the MDI specification. You may want to avoid these problems, especially if what you re intending to write doesn t require all of MDI s functionality. You can avoid some problems by performing the Windows trickery that I ll demonstrate below. From a form to a child window Changing a form into a child window can be as easy as specifying a parent in the form s OnCreate handler. Look at the example below: procedure TForm2.OnCreate(Sender : TObject); Parent := Application.MainForm; There s absolutely nothing wrong with following this example. In fact, it works quite well though it isn t very elegant. A better place to specify parentage would be in the form s virtual method, called CreateParams. This method initializes a TCreateParams structure that is passed to the Windows API function CreateWindowEx, which is responsible for creating all windows in Windows. The TCreateParams structure passes vital initialization information to CreateWindowEx, so that the latter knows how to display a window. Delphi automatically handles parameters that you set through the Object Inspector and provides default values. But it is possible to override the CreateParams() function and change the parameters to suit your particular initialization requirements. Take a look at the following structure: type TCreateParams = record Caption: PChar; Style: Longint; ExStyle: Longint; X, Y: Integer; Width, Height: Integer; WndParent: HWND; Param: Pointer WindowClass: TWndClass; WinClassName: array[0..63] of Char; As you can see, there s a lot you can change here. For our discussion, though, we re interested in the Style field, which controls the physical display of the form. While its type is LongInt, it s actually a bit field that stores constant values that you can set using bit-wise operations. To make a form a child, you append OR and the window-style constant WS_CHILD to the bit field, like so: Style := (Style OR WS_CHILD); However, the Windows help file states that you can t include the window style WS_POPUP in the bit field if a window is designated as a child. So in addition to applying the WS_CHILD style, we have to remove the WS_POPUP value. Therefore, it s actually better to write the following: Style := (Style OR WS_CHILD) AND (NOT WS_POPUP); 2 Delphi Developer s Journal

3 Unfortunately, this bit of rewriting isn t all we have to do here. We must also notify both Windows and Delphi of the impending relationship just to cover our bases. We ll do this by assigning the WndParent field to the parent of our choice. For pseudo-mdi applications, the parent will be the main form, as in WndParent := Application.MainForm.Handle; Finally, to let Delphi know about the relationship, we set the Parent property of the form to the main form of our application: Parent := Application.MainForm; The complete CreateParams method looks like this: procedure TChildFrm.CreateParams(var Params : TCreateParams); inherited CreateParams(Params); with Params do {Set the child window's style - WS_CHILD is absolutely required but you can optionally set other flags as well.} Style := (Style OR WS_CHILD) AND (NOT WS_POPUP); {Designate the child form's parent in Windows} WndParent := Application.MainForm.Handle; {Let Delphi know about the relationship now} Parent := Application.MainForm; I realize that implementing this code is more work than just setting the Parent property to the Application.MainForm in the OnCreate event handler. But what we re actually doing is working in Delphi behind the scenes and at a much lower level to change the form s behavior. In fact, since you declared the CreateParams() method as a protected virtual method, you can put this form in the object repository for easy subclassing. Granted, you could achieve the same effect by applying the above technique to existing forms, but that s really just setting a property at runtime and not truly adjusting the form s behavior. Here, we re using the objectoriented programming (OOP) concept of inheritance to create a true descendant of TForm. In any case, we re still not done; we have one more item on the agenda. Window topping A couple of phenomena occur when you make a form act as a non-mdi child of another. First of all, the form loses its ability to be a top-level window. What this loss means is that even though you can manipulate it like a regular form, the form s caption bar will always be colored with the inactive form color (typically gray). No matter what you do, you ll never get true focus or activation of the form because it s no longer a top-level window. MDI children don t have this problem because the MDI specification handles the Z- order of child forms. Figure A illustrates the phenomenon of the non-mdi child window. Figure A Simply making a form a child window won t make it behave like an MDI window. If you click on Form3 in Figure A, you d expect its caption bar color to change to blue (or whatever active form color you have set in your system). You can move the form, resize it, and manipulate it to your heart s content, but it will never activate. Furthermore, let s say you create and display two child forms inside the main window. Because you can t activate either form, clicking on a child that s underneath another child won t move that form to the top of the Z-order (the order of the windows from front to back). Figure B on the next page illustrates this problem. As you can see in Figure B, two child forms appear on the main form, but both look like inactive forms. The forms appearance can be a problem because it may confuse users as to which is the active form. Now, to get around these snags, you might think of setting the ExStyle parameter to WS_EX_TOPMOST in the TCreateParams April

4 Figure B You can t activate simple child forms, so the window ordering never changes. structure to force the form to be a top-level window. But these settings won t work. In fact, you ll get an access violation error and crash your program because top-level-ness is a Windows trait, not a Delphi trait; therefore, you can t manipulate the setting without causing problems. So now what? You trick Windows. Tricking Windows The trickery involved here is nothing complex. On the contrary, it s merely a matter of sending an activation message to the child form under the proper circumstances. When Windows detects the activation message, it changes the color of the caption bar and activates the form. The specific message we send is WM_NCACTIVATE, which is the Windows message sent to a window when it s time to change a window s nonclient area (caption and border) to indicate an active or inactive state. You might be wondering why we don t send the WM_ACTIVATE message instead of WM_NCACTIVATE. We don t send this particular message because it works only on top-level windows. Since our child form isn t a toplevel window, nothing would happen if we sent a WM_ACTIVATE message to it. On the other hand, the WM_NCACTIVATE message works on any window, so it seems natural to use this message. A form can receive a WM_NCACTIVATE message in three distinct circumstances: when the application creates it at runtime, when the user clicks (with either the right or left mouse button) on the window s client area, and when the user clicks on the window s caption bar (again, using either the left or right mouse button). There s a corresponding Windows message for each of these situations, and you can trap and handle them separately. With Delphi, it s a matter of writing a custom message handler. You ve probably seen Delphi message handlers before; they re usually in the following form: procedure WM<WinMessage>(var Msg: T<WinMessage>); message WM_<WinMessage>; For example, to override the message handler for a left-click, your declaration would look like the following: procedure WMLButtonDown(var Msg : TWMLButtonDown); message WM_LBUTTONDOWN; You could actually name the handler anything you prefer, but convention dictates that you name it the closest approximation of the Windows message you re handling. I mentioned earlier that you can activate a form in three circumstances (actually, in five, if you count the mouse-clicks separately) and that each circumstance has an associated Windows message. Therefore, it s natural to assume that we d have to write five custom message handlers for each of the messages. In many cases, that s correct, but since we want to do the same for each circumstance, writing that many procedures is a bit of a waste. In this case, we need to turn to a procedure that intercepts all the messages that go to a window. Doing so enables us to handle several messages in one fell swoop. This particular method is another virtual method of TForm called WndProc. The WndProc method receives all messages sent to a form and dispatches them accordingly. It s the ideal place to intercept messages that trigger identical actions. For our purposes, we re interested in the following messages: WM_CREATE, which is sent to WndProc when a form is created; WM_LBUTTONDOWN and WM_RBUTTONDOWN, which are sent to WndProc when a user presses the left or right mouse button, respectively, in the client area of a form; and finally, WM_NCLBUTTONDOWN and WM_NCRBUTTONDOWN, which are sent in response to left or right mouse clicks in a form s caption or border area. We d handle these messages in WndProc with the following lines of code: procedure TChildFrm.WndProc(var Msg : TMessage); {Call the default Window procedure so all default actions are taken on all messages} inherited WndProc(Msg); 4 Delphi Developer s Journal

5 {If the following occur, take further action} if (Msg.Msg = WM_CREATE) OR {window create} (Msg.Msg = WM_LBUTTONDOWN) OR {left-click in client area} (Msg.Msg = WM_RBUTTONDOWN) OR {right-click in client area} (Msg.Msg = WM_NCLBUTTONDOWN) OR {left-click in non-client area} (Msg.Msg = WM_NCRBUTTONDOWN) then {right-click in non-client area} {"Trick" Windows into thinking this is an active, top-level form.} Perform(WM_NCACTIVATE, Ord(True), 0); {Change all other forms of the same class to look inactive.} ActivateForm; end You ll want the method to first call the inherited WndProc procedure to ensure that all messages get dispatched. (If you fail to do this, you ll get some really abnormal behavior.) Then, if the messages in which we re interested do occur, we do more processing. In this particular case, we dispatch another method to the form the WM_NCACTIVATE message! Notice that we use WM_NCACTIVATE with the Perform procedure. This procedure allows a control to send a message to itself, completely bypassing the Windows message queue and communicating directly with the control s window procedure (WndProc). Now you can see why calling the inherited WndProc was vital: By sending WM_NCACTIVATE to the form, we ensure that the overridden WndProc processes all messages. So our activation message gets processed. In fact, this one message makes the child forms behave in the way you d expect MDI child forms to behave relative to their main forms! Unfortunately, we re not finished. Since the child forms aren t really activated, Windows essentially ignores them. Therefore, once you make the change to the caption bar, the caption bar retains the change. Similarly, once a child form is activated by one of the above messages, it retains its look of activation. The results in this case are similar to those in Figure B, only now, all of the caption bars are the active form color. We re in no better shape than we were before. But don t lose hope there s a solution. You may have noticed that our code makes a call to a method called ActivateForm. This custom method more accurately acts as a deactivator of other child forms that are of the same class as the one most currently activated, but are not the current form. Here s the code for that method: procedure TChildFrm.ActivateForm; var I : Integer; inherited; {Set the private ChildHndl variable to Self.Handle, so we know which form is active} ChildHndl := Self.Handle; Self.BringToFront; with Screen do {Go through all the forms on screen.} for I := 0 to FormCount - 1 do if (Forms[I].ClassName = Self.ClassName) then if (Forms[I].Handle <> ChildHndl) then {If a "Child" is of the same type, but not the current one, as specified by ChildHndl then make it inactive} SendMessage(Forms[I].Handle, WM_NCACTIVATE, Ord(False), 0); As you can see in the code, the procedure sets a THandle variable called ChildHndl (which is defined in the private section of the form) to the value of the current form s handle. Then it iterates through all the forms on the screen. If a form has the same ClassName value as the current form but has a different Handle value than ChildHndl, a WM_NCACTIVATE with a wparam of False is sent to the window to deactivate it. The net result appears in Figure C. Does this result remind you of something? That s right it looks just like an MDI application! And at this point, we re finally finished. Figure C If you deactivate the windows that aren t on top, they ll appear to be MDI child windows. April

6 Conclusion Whew! We ve just covered a lot of ground! I suggest that you look deeper into CreateParams and WndProc because this article demonstrates only the tip of the iceberg of what you can accomplish with these very useful methods. Besides, getting to know those procedures in greater depth will help you gain an even better understanding of the inner workings of your Delphi programs. Brendan Delumpa is a Senior Systems Engineer with a small health care technology company. You can reach Brendan via at bdelumpa@delumpa.com or @compuserve.com. Figure A 2.0 WINDOWS 95/NT PROGRAMMING Creating perforated forms Standard windows are so commonplace that you might not remember you can create forms that do many nonstandard things. One of the more unusual effects you can create is a form that appears to have a hole in it, which we call a perforated form. In addition to looking rather strange, perforated forms demonstrate that you can create windows that have complex shapes. Under Windows 3.x, creating perforated forms was a significant undertaking. In contrast, Windows 95/NT applications make this task much simpler, thanks to If you create a perforated form, you can click on the objects you see behind the form. the GetWindowRgn() and SetWindowRgn() functions in the Windows Application Programming Interface (API). In this article, we ll show how you can use these API functions to create perforated forms like the one shown in Figure A. Hole-y form! As we mentioned earlier, the key to creating a perforated form is using the SetWindowRgn() API function. This function, which is new for Windows 95/NT, applies to a particular window the shape of any valid form s Windows region. Creating a region is fairly simple. The Windows API supplies four basic region-creation functions: CreateRectRgn(), CreateEllipticRgn(), CreateRoundRectRgn(), and CreatePolyPolygonRgn(). In each case, the return value of the function is a handle to a region, or HRgn. Once you ve created a basic region, you can combine its shape with that of another region using the CombineRgn() function. This function accepts four parameters: the destination region, the first region, the second region, and one of five constant values that determine how the function should combine the regions. If you re creating a perforated form, you ll want to use either RGN_XOR (which results in 6 Delphi Developer s Journal

7 the superset of both regions minus the subset) or RGN_DIFF (which results in the first region minus the second). To create a hole in a form window, you ll first need to retrieve or create a region that has the same coordinates as the form window. The easiest way to do this is by calling the GetWindowRgn() function. Unfortunately, you can t modify the region that this function returns and then reapply it to the form window. Instead, you need to delete the window s current region and create a new one of the same size. Next, you ll need to create the region that represents the hole, or perforation, in the form. Once you have a region for the form window and a region for the hole, you can use the CombineRgn() function to generate the final result. Now that you have the combined region, you can apply it to the form window using the SetWindowRgn() function and then delete the region that represents the hole in the form. (If you don t delete this region, you ll create a resource leak every time the user resizes the form. You don t have to delete the combined region because Windows will delete the region when it destroys the form window.) The SetWindowRgn() function accepts three parameters: a window handle, the new region, and a Boolean value that determines whether to repaint the form as a result of this operation. (For our purposes, we ll always want to set the Boolean value to True to force Windows to repaint the form.) If you apply this technique to a form window, you ll probably want to use a combination of Panel and Shape components to represent the edge of the hole in the window. Using these components isn t absolutely necessary, but doing so adds some visual clues about the form s boundaries. Now, let s create a sample application that displays a perforated main form. A hole in one First, create a blank-form project and place five Panel components on it. We ll use these components to specify the boundaries of the hole in the form. Set the properties of the five according to Table A. Next, place two Shape components on Panel5. Set the Height property of the first to 1 and set its Align property to altop. Set the Width property of the second to 1, and set its Align property to alleft. Now, create an OnResize event handler for the form, and change the new method to match the following: procedure TForm1.FormResize(Sender: TObject); var WindowRgn, HoleRgn : HRgn; WindowRgn := 0; GetWindowRgn(Handle, WindowRgn); DeleteObject(WindowRgn); WindowRgn := CreateRectRgn(0,0,Width,Height); HoleRgn := CreateRectRgn(Panel3.Width + 6, Panel1.Height + 25, Width - (Panel4.Width + 6), Height - (Panel2.Height + 6)); CombineRgn(WindowRgn, WindowRgn, HoleRgn, RGN_DIFF); SetWindowRgn(Handle, WindowRgn, TRUE); DeleteObject(HoleRgn); Table A: Panel components Panel1 Align altop BevelOuter bvnone Caption Height 5 Panel2 Align albottom BevelOuter bvnone Caption Height 10 Panel3 Align alleft BevelOuter bvnone Caption Width 10 Panel4 Align alright BevelOuter bvnone Caption Width 10 Panel5 Align BevelOuter alclient bvlowered April

8 When you finish modifying this method, save the project as HOLEPROJ.PRJ and the form as HOLEFORM.PAS. Build and run the project, checking to see that the main form resembles the one shown in Figure A. To confirm that the form actually has a hole in it, position the form over another window or over some icons on the desktop. You ll notice that not only can you see these items, you can also click them through the perforated form. Conclusion Creating windows with complex shapes was complicated under Windows 3.x. Under Windows 95/NT, the SetWindowRgn() function makes it easy to define complex shapes and simplifies the process of applying them to your Delphi form windows. 2.0 WIN32 PROGRAMMING Displaying virtual memory information Any Windows 95 or Windows NT system has a fixed amount of randomaccess memory (RAM). To accommodate the occasional need for extra memory, the Win32 operating system provides a powerful virtual memory system. This system can simulate the effect of more RAM by swapping lesser-used regions of memory to a file (known as the swap file) on the hard disk. Obviously, if a system starts using a significant percentage of the swap file, it s because the system has run out of physical RAM. As you d expect, system performance suffers when applications try to access memory that the operating system has temporarily swapped out to the disk. Many applications track available system resources and memory usage, and some even display this data in the application s About dialog box. In this article, we ll show how you can determine various data about the memory status of the host system and then display this information to the user. Status symbols The key to assessing the memory status of a Windows 95/NT system is a relatively obscure Windows function named GlobalMemoryStatus(). Unlike most of the other memory-related Windows functions, GlobalMemoryStatus() provides information about the entire system not just the memory used by the current process. To call GlobalMemoryStatus(), you need to pass the name of a TMemoryStatus record. The declaration of the record is as follows: TMemoryStatus = record dwlength: DWORD; dwmemoryload: DWORD; dwtotalphys: DWORD; dwavailphys: DWORD; dwtotalpagefile: DWORD; dwavailpagefile: DWORD; dwtotalvirtual: DWORD; dwavailvirtual: DWORD; As you must do with many Windows functions, you ll need to initialize the first data member in this case, dwlength to the size of the entire record by calling the function sizeof(tmemorystatus). While this process may seem rather odd, it allows Microsoft to add new data members to the end of the record without you having to worry about the possibility of GlobalMemoryStatus() writing past the end of the record (or what you thought was the end). After you ve initialized the dwlength data member, you ll call GlobalMemoryStatus() by passing the TMemoryStatus record directly not using a pointer or the address of the record. When the function returns, the record will contain several important pieces of information, as described in Table A. To display the values from the TMemoryStatus record, you can use the IntToStr() function to convert the data 8 Delphi Developer s Journal

9 into strings. Now let s build an example that demonstrates how you can determine specific information about the current system s memory. Swap meet Begin by placing several Label components, four Gauge components, and a Timer component on the form. Use Figure A as a reference for placing the components. Figure A Table A: TMemoryStatus data members Data member dwmemoryload dwtotalphys dwavailphys dwtotalpagefile dwavailpagefile dwtotalvirtual dwavailvirtual Description A mysterious value that represents a somewhat arbitrary rating of the current memory load on a scale of 0 to 100 The total amount of physical RAM in the current system The total amount of physical RAM that s available for use The total amount of disk space available for use as a swap file The amount of available swap file space, minus the amount that s currently in use The total amount of memory available to each process The total amount of memory available to the current process, minus the amount that s really in use Figure B Lay out the Label and Gauge components according to this pattern. Next, double-click the Timer component to generate a new event-handling method. Then, enter the appropriate code from Listing A on page 10. (We ve highlighted in red the code you ll need to enter.) When you finish entering the code, build and run the application. When the main form appears, confirm that it resembles the one shown in Figure B. Every half second, this application will report the current virtual memory statistics. IN RECENT ISSUES February 1997 Creating a System Menu Component Displaying the Correct Border Style for MDI Parent Windows Evaluating Constants at Runtime Eliminating Circular Unit References Defining Non-menu Accelerators Accessing Protected Properties Displaying Forms Without Captions Changes to Delphi Developer s Journal March 1997 Formatting, Editing, and Printing String Grids Auto-Scale Delphi Forms in any Resolution VCL for C++ Programmers, Part I Accessing Private Data in Derived Classes April

10 Listing A: MEMSTAT.PAS unit VMStatus; interface uses Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls, ExtCtrls, Gauges; type TForm1 = class(tform) Label1: TLabel; Label2: TLabel; Label3: TLabel; Label4: TLabel; Label5: TLabel; Label6: TLabel; Label7: TLabel; Label8: TLabel; Label9: TLabel; Label10: TLabel; Label11: TLabel; Label12: TLabel; Label13: TLabel; Label14: TLabel; Gauge1: TGauge; Gauge2: TGauge; Gauge3: TGauge; Gauge4: TGauge; Bevel1: TBevel; Bevel2: TBevel; Bevel3: TBevel; Bevel4: TBevel; Timer1: TTimer; procedure FormCreate(Sender: TObject); procedure Timer1Timer(Sender: TObject); private { Private declarations } procedure UpdateMemStatus; public { Public declarations } var Form1: TForm1; implementation {$R *.DFM} function ConvertToK(Value : DWORD) : DWORD; result := Value div 1024; procedure TForm1.UpdateMemStatus; var Status : TMemoryStatus; Status.dwLength := sizeof(tmemorystatus); GlobalMemoryStatus(Status); with Status do Label8.Caption := IntToStr(dwMemoryLoad); Label9.Caption := IntToStr(ConvertToK(dwTotalPhys)) + ' Kb'; Label10.Caption := IntToStr(ConvertToK(dwTotalPhys - dwavailphys)) + ' Kb'; Label11.Caption := IntToStr(ConvertToK(dwTotalPageFile)) + ' Kb'; Label12.Caption := IntToStr(ConvertToK((dwTotalPageFile - dwavailpagefile))) + ' Kb'; Label13.Caption := IntToStr(ConvertToK(dwTotalVirtual)) + 'Kb'; Label14.Caption := IntToStr(ConvertToK((dwTotalVirtual - dwavailvirtual))) + ' Kb'; Gauge1.Progress := dwmemoryload; Gauge2.MaxValue := dwtotalphys; Gauge2.Progress := (dwtotalphys - dwavailphys); Gauge3.MaxValue := dwtotalpagefile; Gauge3.Progress := (dwtotalpagefile - dwavailpagefile); Gauge4.MaxValue := dwtotalvirtual; Gauge4.Progress := (dwtotalvirtual - dwavailvirtual); procedure TForm1.FormCreate(Sender: TObject); UpdateMemStatus; procedure TForm1.Timer1Timer(Sender: TObject); UpdateMemStatus; end. 10 Delphi Developer s Journal

11 OBJECT PASCAL PROGRAMMING Delphi s dynamic data structures by Alan C. Moore Because of space considerations, the source listings for this article don t appear in the journal. You can use anonymous FTP to download a ZIP file of the entire project from ftp.cobb.com/ddj. The filename is DYNADATA.ZIP. Since Delphi provides several powerful database tools and features to help manage data, many older approaches such as large in-memory arrays aren t as necessary as they once were. For other tasks, though, Delphi s database capabilities can suffer from overkill or inefficiency. For situations that don t require database facilities, Delphi 1.0 and 2.0 support standard arrays and records. You can use arrays to manage homogenous data, and records to formally structure dissimilar data. You re probably familiar with arrays and records, which are basic to the Pascal language. However, Delphi provides other, more powerful data structures whose capabilities go well beyond those of traditional arrays and records. These structures, such as the TList class, may be less familiar to new Delphi pro- grammers. In addition, Delphi 2 reintroduces (at least in name) a data structure that was part of Borland Pascal 7.0: the TCollection class. While TList and TCollection are more complex and difficult to use than simple arrays or records, their increased capabilities make the effort worthwhile. In this article, we ll discuss how you can use the special Delphi data structures TList and (in Delphi 2.0) TCollection to manage modest amounts of data. We ll examine the unique qualities and uses of each class, along with its shortcomings and limitations. In particular, we ll consider some occasions where you might use TList or TCollection for a specific task. Finally, we ll create a new TList descendant class to implement a complex collection. TList and TCollection: A quick comparison Delphi s CLASSES.PAS unit defines the TList and TCollection classes. Like simple arrays, both classes provide a means of grouping objects. With TCollection, objects must be of the same type, a descendant of TCollectionItem. 2.0 Table A: Tlist and TCollection Use of Property or Method/Property TList TCollection/TCollectionItem Add item to list or collection; Add() Add() latter uses Items property Get number of items in list or collection Count property Count property Delete item(s) from list or collection Delete() Clear()/TCollectionItem.Clear Insert item at specific location Insert() TCollectionItem.Add() Delete referenced item Remove() No comparable method Change position of item Move() No comparable method Exchange position of two items in a list Exchange() No comparable method Perform a quick sort on items in list Sort() No comparable method Move to first item in list or collection First() Items[0] Move to last item in list or collection Last() Items[Count-1] Get allocated size of the array of Capacity property No comparable method pointers maintained by a TList Increase maximum size of a list Expand() No comparable method Remove all nil pointers in a list Pack() No comparable method Prevent updating of collection until you No comparable method BeginUpdate() call EndUpdate Re-enable screen repainting turned No comparable method EndUpdate() off with BeginUpdate April

12 However, TList allows you to collect objects of different types. The two classes share some properties and methods, which appear in Table A on the previous page. Descending from TObject, TList is lower in the Delphi hierarchy than TCollection, which descends from TPersistent. Because of this lineage, TCollection can take advantage of Delphi s streaming support; with Tlist, this isn t the case. However, as we ll see, you can write your own stream-enabling methods for TList descendants. The type of TPersistent behavior included in TCollection is important if you re creating a new visual component with a series of subcomponents of the same type. You can use TCollection to accomplish the needed streaming tasks. On the other hand, TList does have additional methods that aren t available in TCollection (see Table A). For example, only the former includes methods for packing, sorting, and expanding the list. While the Visual Control Library (VCL) uses both classes, only TList is part of a sample program (ExeImage.Pas, which is part of the ResXplor project.) Understanding indirect scope Scope is an important, if peculiar, concept. Scope determines whether you can create an object of a given type and whether you can access certain variables. In this article, we ll examine the concept of indirect scope and explain this somewhat confusing aspect of Delphi and Object Pascal. Header gobbler If you ve programmed in C or C++, you re probably familiar with how the #include directive imports header files. If you add the line #include <frank.h> the compiler will search for a file with this name and then import the variable and procedure declarations from FRANK.H into the scope of the current file. If FRANK.H also contains #include directives, the compiler will search them recursively until it has imported all of the header files that the main source file names directly or indirectly in an #include directive. In contrast, Object Pascal imports declarations and variable names via the uses clause. When a unit imports declarations and names from a second unit, the first unit will have access only to the names and types declared and defined in that unit. If the second unit imports other declarations and names from a third unit, the first unit will have severely limited access to the third unit s declarations and names. The limits to the first unit s access to the third unit s declarations and names conform to the following rule: Only the names and types that appear in the units directly imported by a uses clause are accessible within a given unit. This restriction means that the first unit could use types from the third unit, but only if the intermediate (second) unit declares variables of a type that you ve defined in the third unit. By the way, even though the first unit can access a variable in the second unit whose type appears in the third unit, the first unit can t declare new objects of that type. This limitation makes sense if you remember that the first unit hasn t imported the type definition from the third unit. All it knows about that type is its callable interface. The first unit knows nothing about creating a new variable of that type. As a result of these rules, it s easy to see why Delphi can compile a group of units so quickly. Toplevel units don t need to recursively scan the units they use indirectly, because the information they retrieve from the units they directly import contains all the information necessary to reference those declarations and names. To clarify this, let s create three units and set up the type of indirect referencing we ve just described. Import regulation Begin by creating a blank-form project and two new units. Save the main form s unit as MAIN.PAS, the first auxiliary unit as PEEKING.PAS, and the second auxiliary unit as HIDDEN.PAS. Enter the following declarations in the interface section of the HIDDEN.PAS file: 12 Delphi Developer s Journal

13 Finally, because it s a single, self-contained class, TList is easier to work with. TCollection consists of two classes: TCollection itself and TCollectionItem. The TList class provides all the basic properties and methods to create a dynamic array of objects, very similar to the old TCollection. Among other things, you can add, delete, insert, remove, move, or exchange objects used in a list. Like TCollection, TList contains a property that s a list of pointers to the objects in the list. You can access a particular item in the list with the Items property or find an item s position with the IndexOf method. The Count property returns the number of items in the list. Many of these items appear in the sample program accompanying this article. However, before we examine the use of TList in building a dynamic array or data collections, let s look at the TCollection class. Anatomy of a collection, Delphi 2 style In Delphi 2, the TCollection s primary function is to provide a container for creating type THidden = Class public procedure DoSomething; Now, add the DoSomething method to the implementation section of the same file, as shown here: procedure THidden.DoSomething; (We ve intentionally left the body of the function empty.) In the interface section of the PEEKING.PAS file, enter the following type declaration and uses clause: uses hidden; type TPeeker = record AHiding : THidden; This clause declares a simple record type that contains an instance of the THidden class. Next, double-click on the main form to create an OnCreate event handler, and add the code shown below: procedure TForm1.FormCreate(Sender: TObject); var Peek : TPeeker; {Hider2 : THidden;} Peek.AHiding.DoSomething; {Hider2.DoSomething;} BHiding.Dosomething; At this point, add the following units to the MAIN.PAS file s interface section uses clause: Peeking, {Hidden,} When you finish entering the code, build the project to confirm that the FormCreate() method has calling access to the THidden objects referenced in the Peek and BHiding variables. Remove the braces from the Hider2 variable declaration. Now, from the Hider2.DoSomething method, call and rebuild the project. This time, you ll see the following error: Undeclared identifier: THidden. You ll see this error because the MAIN.PAS file doesn t import the necessary information to create a THidden object it imports just enough information to reference existing variables of that type and call the objects methods. To eliminate the Undeclared Identifier error, you remove the braces from around the Hidden unit name in the uses clause. Doing so will force the compiler to import all the interface information from the HIDDEN.PAS unit, including the information necessary to create the new objects of the THidden class. Conclusion Delphi s indirect unit referencing rules may seem complex, but they have significant performance benefits. In addition, many of the exotic methods that C/C++ programmers use to prevent redundant processing of header files are unnecessary in Delphi, because Delphi doesn t try to recursively import all the declaration and variable information from units that a file may indirectly reference. April

14 subcomponents dynamically. Examples in the VCL include the THeaderSections collection for the THeaderControl and the TStatusPanels collection for the TStatusBar. To manage the individual items, each collection has a TCollectionItem descendant for the collections THeaderSection and TStatusPanel. If you study the source code for these classes in the VCL, you ll discover their interrelationships, which are most evident in the constructor methods. For example, the component THeaderControl contains a private field, FSections, which is set to the THeaderSections collection it uses. The component s Create constructor sets this field with the following line of code: FSections := THeaderSections.Create(Self); Conversely, the destructor, Destroy, contains another line of code to dispose of the collection when the control is freed: FSections.Free; After the constructor creates the FSections object, it s essentially empty it still doesn t contain any sections. You can use the SetSections() method to insert existing sections, or you can use the UpdateSection() method, which in turn calls UpdateItem() to manipulate the sections. Compared to the component and its supporting collection, there s an even stronger relationship between the collection and its TCollectionItem class, in this case THeaderSections and THeaderSection. So, how does this new incarnation of TCollection compare with the one you may have encountered in Borland Pascal 7.0 (BP7)? Same as the BP7 TCollection? If you ve programmed in BP7 and have used its TCollection class, you may have reacted with excitement to the reintroduction of this useful data structure in Delphi 2. I certainly did. However, it may be too soon to celebrate. In the process of writing this article, and with the objective of learning firsthand about the TList class and the new Delphi 2 implementation of TCollection, I rewrote a portion of an older program that used the BP7 version of TCollection. For that application, the TList class worked well, so I used it instead of TCollection. Let s take a look at the steps involved in using TList to build a collection. A TList collection In the sample program, COLLPRJ, I create a collection called QACollection of type TQAList. Establishing a TList or a TList descendant (such as TQAList ) involves three steps: Creating the TList Reading data from or writing data to TList and then using the data Destroying the TList Now let s take a look at the sample program s code. In the FormActivate() method, the following line creates the collection: QACollection := TQAList.Create; Then, in the FormDeactivate() method, we destroy the collection using the line If QACollection<>Nil then QACollection.Free; The main action takes place in the Q_A_Dlg3 unit. For each new question/answer we enter, the application creates a TList item with the line QACollection.Add(TQuestAnswer.Create); We then enter the data in the new TempQuestAns object with these lines: TempQuestAns := QACollection.Items[QACollection.Count-1]; TempQuestAns.Init(fQuestID, fquestion, fqtype, [], fmatchanswer, fshortanswer, Nil); If flonganswer[0]<>#0 then TempQuestAns.ALongAnswer := StrNew(fLongAnswer); The TempQuestAnswer object is of type TQuestAnswer, which we declared in the QzDataD2 unit. All of the data contained within it, except for two PCHAR variables, are kept in an AQARec record, QuestAnswerRec. This organization also facilitates reading and writing the data to a file using a stream, as we ll now discover. 14 Delphi Developer s Journal

15 Streaming support Provided that you ve defined an object, such as our TQUESTANSWER, it s easy to write methods to save it to and retrieve it from a stream. The four basic methods you need are LoadFromStream(), LoadFromFile(), SaveToStream(), and SaveToFile(); here, two additional methods are defined to handle PChar input and output: ReadPChar() and WritePChar(). These methods first read or write a Word variable that contains the number of bytes in the PChar, or 0 if it s Nil. Then we can safely read or write the PChar string itself. Overall, the implementation is straightforward. The advantage of using records is that we can read and write data to or from a file with a single statement: Stream.Write(TempRec.AQARec, SizeOf(TempRec.AQARec)); The saving/retrieving process involves three steps: Creating the stream Using the stream (reading, writing, etc.) Destroying the stream Here s how we implement the three steps in TQAList class s SaveToFile() method: CollectStream := TFileStream.Create(FileName, fmcreate); SaveToStream(CollectStream); CollectStream.Free; In the first statement, fmcreate opens a new file (and possibly destroys an existing file) with the name FileName. Most of the work takes place in the SaveToStream() method. The relationship of LoadFromStream() and LoadFromFile() is analogous to the writing methods. However, when we open the file, we use fmopenread instead. Creating a sample application So far, we ve presented a lot of theory and multiple code fragments. For a practical example, I wrote an application that can write and retrieve complex data for a Computer-Assisted Instructional program. Instead of reproducing the entire application here, let s examine the most important code segments. In the ViewBtn OnClick handler, you ll find the following lines of code: If ShowQuestionsandAnswers.OpenQAFile.Execute then QACollection := TQAList.Create; try QACollection.LoadFromFile( ShowQuestionsandAnswers.OpenQAFile.FileName); ShowQuestionsandAnswers.ShowModal; finally QACollection.Free; These lines simply create the list, load the data from a user-selected file, and then free the list when we re done. Now let s consider the code that implements the main buttons of the TQuestionandAnswerDialog. For the first three buttons, we added some specific code for the OnClick handlers. For NextBtn we added the following: var QuestType : QType; QuestType := QType(QuestionType.ItemIndex); NewQuestionDlg.Execute(QuestType, QuestNum); Inc(QuestNum); For FinishBtn add: var SaveCollection : Boolean; SaveCollection := Application.MessageBox ('Save Question/Answer Collection?', 'Confirm Save Collection', mb_okcancel) = IDOK; If SaveCollection then if SaveDialog1.Execute then QACollection.SaveToFile(SaveDialog1.FileName); QAFileOpen := False; Close; In contrast, the code for the CancelBtn is simply a call to Close. Finally, we added a method named Execute, which returns a Boolean value of True if the data entry is successful. The entire method is as follows: April

16 function TQuestionandAnswersDlg.Execute: boolean; AQAMode := qaenter; QAFileOpen := True; Result := ShowModal=mrOK; Now let s consider the final form, Q_A_Dlg2. As with the previous dialog boxes, we added three TBitBtns: NextBtn, FinishBtn, and HelpBtn. Next, we set the FinishBtn s ModalResult property to mrok. As before, this form s NextBtn uses the following code in its event handler: var QuestType: QType; TempRec: TQuestAnswer; TempRec := TQuestAnswer.Create; TempRec := QACollection.Items[ItemNum]; QuestType := TempRec.AQARec.QuestionType; NewQuestionDlg.Execute(QuestType, ItemNum); Inc(ItemNum); If ItemNum=QACollection.Count then ItemNum := 0; ShowMessage('End of list encountered; starting over'); Conclusion As complex as this application may be, we can t consider it finished; you ll find many places where you can enhance and expand it. However, the application does demonstrate the use of a TList to create a dynamic array or collection, save it to file, and retrieve and view it. We ve described a powerful technique that you can use when your applications don t need full-blown database support. C++ Builder 1.0 C++BUILDER PROGRAMMING VCL for C++ programmers, Part II by Kent Reisdorph Last month, in Part I of this series, we discussed the Visual Component Library (VCL) and how using the VCL in C++Builder differs from the C++ programming you ve been doing. We talked about the component model (also called the properties, methods, and events or PME model) and how that model uses properties. This month, we ll focus on events what they are and how to use them in your applications. First we ll define an event. After that, we ll talk about how events handle Windows messages in ways that differ from the old-fashioned C++ way. What s an event? When we talk about an event in VCL programming, we re using the term in separate contexts. In one context, we use the word event to describe something that happens within Windows or within a particular component. For example, when the user presses an arrow key while in an Edit component, Windows sends a WM_KEYDOWN message. This message generates a VCL event an OnKeyDown event, to be specific. So in this context, we can use the word event to refer to something that happens within a component or within Windows itself. In another context, we use the word event to describe a language feature. In VCL, an event is more than just something that occurs it s also a type of function pointer. While this definition may not make much sense at the moment, you ll soon learn more about events and how they work in your C++Builder applications. The two contexts we ve just described are interrelated and can t really be separated from one another. I mention the two contexts to warn you that you ll see the word event used in more than one way. In any event (pun intended!), events are among the most powerful tools in C++Builder s repertoire. Let me explain with an illustration. (You probably already know most of this, but bear with me for a moment while I go over some old ground.) Let s say you have a button on a form. Naturally, you want your program to do something when the user clicks that button. 16 Delphi Developer s Journal