Custom Control Library Documentation This file contains information useful to you if you intend to use the file CtrlDLL.DLL and the Percent Complete control included in it in your own programs. You should read file this before you use the code. If you use this code for any of your own programs and find any bugs in it, please let me know. FILES IN THE ARCHIVE ==================== The following files should have been included in the archive when you downloaded it: CUSTCTRL.TXT This file. PERCENT BMP 406 11-09-91 9:40a Bitmap for RW tool bar PERCENT CUR 326 11-09-91 10:23a Cursor for RW CTRLCOMM INC 1133 11-10-91 7:35p Include file for RW & programs CTLDLLIM PAS 126 9-15-91 6:40p Unit to use with TESTIT.PAS CTRLCOMM PAS 1504 11-09-91 11:59a DLL common declarations unit CTRLDLGS PAS 3193 11-10-91 11:28p Control style dialog unit CTRLDLL PAS 13761 11-10-91 11:28p Main DLL source file CTRLFLAG PAS 1514 11-10-91 11:30p Control flag proc unit CTRLINFO PAS 2874 11-10-91 11:28p Control information unit CTRLINIT PAS 3833 11-10-91 11:28p DLL initialization unit CUSTCNTL PAS 2248 11-10-91 11:29p Custom Control definitions PERCENTC PAS 1891 11-10-91 9:52p WObjects compatible unit TESTIT PAS 7919 11-07-91 9:10p Test program for the % control WNDFNPER PAS 16477 11-10-91 11:29p Percent control window proc CTRLDLL RC 2334 11-10-91 7:35p Resource script for DLL TESTIT RC 1766 11-07-91 7:26p Resource script for test prog. INSTALLING THE SOURCE CODE ========================== After unzipping the archive, should place all the source files for the DLL into the same directory. Development was done in the directory C:\PROGRAMS\UNITS, but you may place the code in any directory that suits your working habits. Just be sure that TPW is configured properly to find and place all .PAS, .INC, .TPU, and .DLL files. COMPILING THE LIBRARY ===================== When you compile the library, be sure to MAKE or BUILD the file CTRLDLL.PAS within the TPW Integrated Development Environment. The compiler will then automatically compile all source files and build a .DLL file. Once this is done, you can now write programs that use the control class defined in the DLL. This code is intended for use with Borland International's Turbo Pascal for Windows compiler. It was specifically written for use with the version 1.0 product. Compatibility with future versions of the compiler is not guaranteed by the author. Attempting to compile this code for any other environment is not recommended. Make sure you place the compiled DLL file in a directory on your path. This will make it easier for a program that uses the DLL to find it and load it. Remember, if Windows can't find the DLL file, it will prompt you to place a disk in A:, which probably won't be of much help! USING THE PERCENT COMPLETE CONTROL ================================== The discussion of using the Percent Complete Control is divided into three parts, as follows: 1. Control styles defined & their effects on an instance 2. User interface considerations 3. Programming considerations 1. Control Styles ----------------- A Percent Complete Control is composed of several parts. The control draws them from the top down. The parts, in order from top to bottom, are: an optional caption, a bar showing the current percent setting of the control, an optional digital display of the current percent setting in the middle of the bar, optional tickmarks in either 10%, 25%, or 50% gradations, and an optional axis labeling each of the tickmarks. The control defines 5 different style identifiers, which may be used in various combinations. These identifiers and their effects are: Pct_10Grads Draws percentage tickmarks at 10% gradations Pct_25Grads Draws percentage tickmarks at 25% gradations Pct_50Grads Draws percentage tickmarks at 50% gradations Pct_DrawAxis Draws an axis under the tickmarks. Pct_DrawPct Draws the percentage as "x^" in the center of the bar Note that Pct_10Grads, Pct_25Grads, and Pct_50Grads are all mutually exlusive styles. You can use one or none of these identifiers in the window style of an instance of the control. Not using any of them causes the control to not draw any tickmarks, while using one of them causes it to draw tick marks in the gradations indicated. You should also not use Pct_DrawAxis if you do not also use one of the tickmark styles. It makes no sense to draw an axis if you don't also draw tickmarks! Finally, Pct_DrawPct may be freely mixed with any of the other styles. The control always has a percentage complete bar, whose height is dependent on whether or not there is a caption, and on which styles have been set for the control. The following paragraphs detail the effects of certain combinations on the height of the bar. Specifying a caption: Specifying a caption causes the control to leave space above it for the caption plus some white space to separate the caption from the top of the control's area & from the percent complete bar. No styles specified : Not specifying any of the styles will cause the control to draw itself as a solid bar across the entire width of the control. The bar's height will be the height of the control minus any space required by the control's caption and any white space needed to separate it from the bar. Pct_XXGrads: Specifying one of these three styles causes the control to leave room beneath the bar for tickmarks four dialog units high. Pct_DrawAxis: Specifying this style causes the control to leave additional room beneath the control to draw an axis 8 dialog units high, plus some additional white space to separate the axis text from the bottom of the control's space. The bar's width is decreased by 20 dialog units to allow the axis to fit within the control's space. Pct_DrawPct: Specifying this style has no effect on the height of the percentage complete bar. The following paragraphs briefly describe the algorithms used by the control when it draws itself on the screen. The control responds to the wm_EraseBackground message. When this message is processed, the control sends the wm_CtlColor message to its parent. This allows your dialog boxes to exert control over the appearance of the control by specifying the brush the control will use to erase its background. In addition, if the control's background is not to use the stock white brush, the control will draw a 3D depression around itself before it draws itself. This allows the control to be used BorDlg dialogs without using a group shade box to enclose the control. The appearance of the percentage bar is modeled after that of the same type of control used in the Norton Desktop for Windows. When it is drawn, the bar has a 3D button-like appearance. The global system colors COLOR_BUTTON, COLOR_WINDOW, & COLOR_BTNSHADOW are used to determine the face color of the button and the colors to use for the button shadow & highlight. At 0 percent, the control appears to be a trough in the dialog display; as the percentage approaches 100%, the bar comes closer to appearing as a complete button. Any caption, percentage complete digits, tickmarks, and axis labels are drawn using the pen currently selected in the window's DC. That is, the pen that's specified in the DC when the BeginPaint procedure returns. I believe this pen may be set by the control's parent, which is why the control does not change the pen at this time. 2. User Interface ----------------- The Percent Complete Control is a passive control window class that is intended to only display data. As such, the control does not respond to any mouse or keyboard messages, and should never receive the input focus. 3. Programming Considerations ----------------------------- When an instance of the control is created, it will show 0% complete. Since the control does not accept keyboard or mouse input, a problem presents itself. That is, how do you change the percentage displayed? To change the percentage value currently displayed by the control, you use one of 4 different messages the control recognizes. These messages and their meanings are: pcm_ResetPercent: Reset percentage displayed to 0. pcm_AddPercent: Add wParam (signed) percent to the value displayed. pcm_GetPercent: Control returns value displayed. pcm_SetPercent: Set value displayed to an arbitrary value. Note that the percentage displayed may never be below 0 or above 100. Also, the percentage is stored as an integer value, so the control is not capable of displaying 50.5% complete, as an example. Two units are provided in the archive which enable your programs to use the percentage control. One is in the file PERCENTC.PAS, and the other is in CTRLDLLIM.PAS. Both of these files are provided for two different purposes, as explained below. Using CTRLDLLIM.PAS ------------------- The CTRLDLLIM.PAS unit is intended to be used by programs like RW that must import the DLL and gain direct access to the routines in the DLL. Note that this is probably not very useful in most circumstances, since RW & the MS SDK program DIALOG.EXE don't need or use this interface! It is provided to allow TESTIT.EXE to run, and can be used if you find you need it for a program. Note that the CenterPopup routine exported by the DLL may come in handy in your own programs. It is intended to be used by popup windows, such as dialog boxes, either modal or modeless. The procedure takes the handle to a window and a handle to that window's device context (DC) as parameters. The routine automatically centers the dialog box either within the borders of its parent/owner window (if the parent is big enough to completely contain the popup window), or within the screen in the event the parent/owner window does not completely contain the popup. The code included in CenterPopup is a Pascal translation of a C routine written by Kevin P. Welch & included in an article he wrote in the July 1990 issue of MSJ. Using PERCENTC.PAS ------------------ The PERCENTC.PAS unit implements an ObjectWindows class called TPercentCtrl. This control is a descendant of TControl and allows any OWL program to use this control. The class defines methods corresponding to the 4 custom messages the control implements. COPYRIGHT INFORMATION ===================== All code in this unit is the property of Anthony M. Vitabile, Copyright 1991. You may use this code in your own programs provided you include the above copyright notice. Please note that the code included in the files that make up the DLL is provided "as-is." I'll gladly allow anyone to use this code, but I don't make any warranties or guarantees about its fitness for anything.