TMsgDisplay – Documentation Overview This component displays a message in a panel centered in the middle of any component (Parent). It can also display a warn message with automatic delay time given in milliseconds. The TMsgDisplay will be shown non- modal so the user can be informed about any time consuming operations the application is processing. The site of the MsgDisplay is automatically sized to the display text. You can also set the message text when the control is shown so you can inform the user at any time. You can also define that the control is only closed when the user clicks an notify button or any Key or Mouse Click (see Options). Requirements You need Delphi 2, Delphi 3 or Borland C++ Builder (Version 1.0 will do). You can use MsgDisplay with either Window 95 (98) and NT (4.0, 5.0). Versions There are some different versions of the class availbale. Either separate archives for Delphi2, Delphi3 and C++Builder. Use the following addresses below: Delphi 2.0 http://members.aol.com/hpgue/bin/d20/msgdisp.zip Delphi 3.0 http://members.aol.com/hpgue/bin/d30/msgdisp.zip Borland C++Builder 1.0 http://members.aol.com/hpgue/bin/cb/msgdisp.zip All-in-one archive http://members.aol.com/hpgue/bin/msgdisp.zip Each archive contains the class as .dcu, .dpl or .obj file and full source code of the demonstration application. Installation Copy the files in the installation path (For Delphi 2) cls_MsgDisplay.dcu cls_MsgDisplay.dcr (For Delphi 3) msgdisplay.dpl msgdisplay.dcp (For C++Builder) cls_MsgDisplay.h cls_MsgDisplay.obj cls_MsgDisplay.dcr to the place where you store your VCL classes/ packages. From inside C++ Builder or Delphi 2 select menu component and then install. Select cls_MsgDisplay(.obj/.dcu) as new component and then rebuild the library. Done. For Delphi 3: Select from the menu Component and then Install Packages. Click on the Add button. Enter the msgdisplay.dpl. Check the new Item “Message Display Package” and click on OK. Done. Copyright TMsgDisplay is Freeware and Noteware for non-commercial use only. You can use TMsgDisplay under the Following conditions: Freeware or Shareware package Sending me an email that you use TMsgDisplay in your application Adding a note like the following in your manual: This application uses TMsgDisplay © 1997 by H.P.G Homepage: http://members.aol.com/hpgue/hpgintl.htm E-Mail: hpgue@aol.com If you want to use the component in commercial a software package please contact the author for special conditions and package licenses. Usage Use the component like any other component. Add it at design time to any form. Set the appropriated properties with the object inspector. Component TMsgDisplay – class documentation Properties: property AsyncDelay : Integer read FAsyncDelay write FAsyncDelay stored true default 500; property AbortCaption : TCaption read FAbortCaption write setAbortCaption stored true nodefault; property OnClose : TOnMsgDisplayCloseEvent read FOnClose write FOnClose; property OnOpen : TOnMsgDisplayOpenEvent read FOnOpen write FOnOpen; ? Status Status : TStringList TStringList *Status These are the text lines which will be displayd in the MsgDisplay. The size of the control will be changed so that the text is entirely visible. ? Caption Caption : TCaption (String) TCaption Caption This is also the Status, but here given as string. You can use either Caption or status to set display text. ? Options Options : TMsgDisplayOptions TmsgDisplayOption=set of TMsgDisplayOptionItems; typedef Set< TMsgDisplayOptionItems, doLockParent, doShowButton> TMsgDisplayOptions this options defines the behavior of the MsgDisplay. TMsgDisplayOptionItems are defined as follows: TMsgDisplayOptionItems=( doLockParent, doLockApplication, doWaitForClick, doForbidTimer, doShowButton); enum TMsgDisplayOptionItem { doLockParent, doLockApplication, doWaitForClick, doForbidTimer, doShowButton }; doLockParent if Options contains this the parents’ cursor will be automatically changed to crAppStart. This is NOT a flag for modal showing the control nor is the parent control really locked. doLockApplication if Options contains this the parents‘ cursor and the Screen’s cursor will be automatically changed to crAppStart. This is NOT a flag for modal showing the control nor is the parent control really locked. doWaitForClick if Options contains this the user can close the MsgDisplay either with a keystroke or a mouse click. If another control gets the focus the Display is also closed. If you do not set doWaitForClick and yout do not set the doShowButton then the display can be closed only by calling the CloseDisplay function. Note: If the user closes the Display with either the mouse click or a key press then the OnClose event will be fired doForbidTimer Due to the limited system timers on some OSes this flag forbis the creation of a system timer. If you set this option a call to AsyncDisplay will always return false and the MsgDisplay will not open only by the use of the OpenDisplay function. doShowButton If you set this a button will be displayed at the bottom of the MsgDisplay and the window will be closed automatically if the user clicked the button. The Caption of the button is for default Abort. You can chage this with the AbortCaption property. Note: If the user clicks on the Abort button then the OnClose event will be fired ? Types Types : TMsgDisplayTyxpes enum TMsgDisplayTypes Types this is a shorthand method to specify whether the control is used as a warn TMsgDisplay or not. TMsgDisplayTypes are defined as follows: TMsgDisplayTypes= ( tdNormal, tdWarn ); enum TMsgDisplayTypes { tdNormal, tdWarn }; tdNormal the MsgDisplay’s color is set to clBtnFace. tdWarn the MsgDisplay’s color is set to clRed. ? AsyncDelay AsyncDelay : Integer int AsyncDelay this is the delay time given in milliseconds for the AsyncDisplay() function. This defaults to 500 this is equal to ½ second delay time. Setting the value of AsyncDelay to 0 means wait infinite. ? AbortCaption AbortCaption : TCaption (String) AnsiString AbortCaption This is the text the abort button will use. Default is Abort. Methods: ? OpenDisplay function OpenDisplay : Boolean; bool __fastcall OpenDisplay(void); this is the standard method to open the TMsgDisplay without any timeout. The MsgDisplay will be shown until the destructor is called or the function CloseDisplay is called. If this function returns false the MsgDisplay is already shown or any error occurred. ? CloseDisplay function CloseDisplay : Boolean; bool __fastcall CloseDisplay(void); if the control is opened either with the OpenDisplay or AsynDisplay function CloseDisplay will close or hide the control. If this function returns false the MsgDisplay is currently not shown or any error occurred. ? AsyncDisplay function AsyncDisplay : Boolean; bool __fastcall AsyncDisplay(void); this function will be used to display a message with automatically delay time. I.e. to display a warning or to prevent the program for waiting of the user click you may have to if you use AsyncDisplay instead of OpenDisplay or a MessageBox. Set the DelayTime to the timeout value in milliseconds you want to be shown the control. If this function returns false any error occurred. I.e. the internal creation of the TTimer may failed due to the limitations of system timers in some OSes or you set the doForbidTimer in Options. Example: // this will open the MsgDisplay for upto 10 seconds. The MsgDisplay // contains also an Abort button. The // MsgDisplay will be closed if either user clicks the button or the // 10 seconds have gone (Delphi) MsgDisplay1.Options:=MsgDisplay1.Options+[doShowButton]; // Show an Abort button MsgDisplay1.Delaytime:=10 * 1000; // Set timeout to 10 seconds If (MsgDisplay1.AsyncDisplay) then begin // okay the message have been shown continue what ever you want here…… end else begin // any error occurred with memory, ttimer etc. end; (C++Builder) MsgDisplay1->Options = MsgDisplay1->Options << doShowButton; // Show an Abort button MsgDisplay1->Delaytime=10 * 1000; // Set timeout to 10 seconds If (MsgDisplay1->AsyncDisplay()) { // okay the message have been shown continue what ever you want here…… } else { // any error occurred with memory, ttimer etc. } Events: ? OnOpen OnOpen = TOnMsgDisplayOpenEvent; TOnMsgDisplayOpenEvent=procedure (Sender:TObject;OpenKind:TOpenKind) of object; enum TOpenKind { okStandard, okAsync }; typedef void __fastcall (__closure *TOnMsgDisplayOpenEvent)(System::TObject* Sender, TOpenKind OpenKind); OnOpen is called whenever the TMsgDisplay is opened either with the OpenDisplay or AsyncDisplay function. The OpenKind Parameter is set to okStandard if the MsgDisplay is opened via a call to OpenDisplay or to okAsync if the AsyncDisplay method is used ? OnClose TCloseReason=(crTimeOut,crClick); TOnMsgDisplayCloseEvent=procedure (Sender:TObject;Reason:TCloseReason) of object; enum TCloseReason { crTimeOut, crClick }; typedef void __fastcall (__closure *TOnMsgDisplayCloseEvent)(System::TObject* Sender, TCloseReason Reason); The OnClose event occurs only when the user click on the Abort button or enters any key if the Options contain doWaitForClick. Calling the CloseDisplay method will not fire the OnClose event. The Reason Parameter is set to crTimeOut if the MsgDisplay is closed by time out else reason is set to crClick. Author If you have any questions, suggestions or want to contact me send a message to the following address: hpgue@aol.com Visit also my home page at http://members.aol.com/hpgue/hpgintl.htm ___