dsamsg.pas

动态提示控件

{$I DFS.INC}  { Standard defines for all Delphi Free Stuff components }

{------------------------------------------------------------------------------}
{ DSAMsg Unit v2.17                                                            }
{------------------------------------------------------------------------------}
{ A unit that provides "Don't Show Again" dialog and form services.  Included  }
{ is a form class that you can descend your own forms from, routines for       }
{ showing standarad TForm descendants, and replacement rountines for the       }
{ MessageDlg function.  DSA services allow the user to specify whether or not  }
{ they want to see the dialog or form in the future with only minimal effort   }
{ on the application programmer's part.                                        }
{                                                                              }
{ Copyright 2000-2001, Brad Stowers.  All Rights Reserved.                     }
{                                                                              }
{ Copyright:                                                                   }
{ All Delphi Free Stuff (hereafter "DFS") source code is copyrighted by        }
{ Bradley D. Stowers (hereafter "author"), and shall remain the exclusive      }
{ property of the author.                                                      }
{                                                                              }
{ Distribution Rights:                                                         }
{ You are granted a non-exlusive, royalty-free right to produce and distribute }
{ compiled binary files (executables, DLLs, etc.) that are built with any of   }
{ the DFS source code unless specifically stated otherwise.                    }
{ You are further granted permission to redistribute any of the DFS source     }
{ code in source code form, provided that the original archive as found on the }
{ DFS web site (http://www.delphifreestuff.com) is distributed unmodified. For }
{ example, if you create a descendant of TDFSColorButton, you must include in  }
{ the distribution package the colorbtn.zip file in the exact form that you    }
{ downloaded it from http://www.delphifreestuff.com/mine/files/colorbtn.zip.   }
{                                                                              }
{ Restrictions:                                                                }
{ Without the express written consent of the author, you may not:              }
{   * Distribute modified versions of any DFS source code by itself. You must  }
{     include the original archive as you found it at the DFS site.            }
{   * Sell or lease any portion of DFS source code. You are, of course, free   }
{     to sell any of your own original code that works with, enhances, etc.    }
{     DFS source code.                                                         }
{   * Distribute DFS source code for profit.                                   }
{                                                                              }
{ Warranty:                                                                    }
{ There is absolutely no warranty of any kind whatsoever with any of the DFS   }
{ source code (hereafter "software"). The software is provided to you "AS-IS", }
{ and all risks and losses associated with it's use are assumed by you. In no  }
{ event shall the author of the softare, Bradley D. Stowers, be held           }
{ accountable for any damages or losses that may occur from use or misuse of   }
{ the software.                                                                }
{                                                                              }
{ Support:                                                                     }
{ Support is provided via the DFS Support Forum, which is a web-based message  }
{ system.  You can find it at http://www.delphifreestuff.com/discus/           }
{ All DFS source code is provided free of charge. As such, I can not guarantee }
{ any support whatsoever. While I do try to answer all questions that I        }
{ receive, and address all problems that are reported to me, you must          }
{ understand that I simply can not guarantee that this will always be so.      }
{                                                                              }
{ Clarifications:                                                              }
{ If you need any further information, please feel free to contact me directly.}
{ This agreement can be found online at my site in the "Miscellaneous" section.}
{------------------------------------------------------------------------------}
{ The lateset version of my components are always available on the web at:     }
{   http://www.delphifreestuff.com/                                            }
{ See DSAMsg.txt for notes, known issues, and revision history.                }
{------------------------------------------------------------------------------}
{ Date last modified:  June 28, 2001                                           }
{------------------------------------------------------------------------------}


{: This unit provides "Don't Show Again" dialog and form services.  Included...
   is a form class that you can descend your own forms from, routines for...
   showing standarad TForm descendants, and replacement rountines for the...
   MessageDlg function.  DSA services allow the user to specify whether or not...
   they want to see the dialog or form in the future with only minimal effort...
   on the application programmer's part.

   The dialog has a check box positioned at the bottom left corner which...
   the user can check to specify that he does not wish to see it again. If...
   checked, calling the function again will not display the dialog, it will...
   simply return a default value immediately.

   Procedures to get and set the state of the dialog are also provided so that...
   you can programmatically re-enable a dialog that has been hidden by the user.
}

unit DSAMsg;

interface

uses
  Dialogs, Classes, StdCtrls, Controls,
  {$IFDEF DFS_WIN32}
  Registry, Windows,
  {$ELSE}
  WinTypes,
  {$ENDIF}
  Forms;



{$IFDEF DFS_COMPILER_3_UP}
resourcestring
{$ELSE}
const
{$ENDIF}
  SDontShow = '&Don''t show this message again';
  SDSAGetSpecifierBlank = 'DSAIdentsGetState storage specifier blank';
  SDSASetSpecifierBlank = 'DSAIdentsSetState storage specifier blank';

  
const
  { This shuts up C++Builder 3 about the redefiniton being different. There
    seems to be no equivalent in C1.  Sorry. }
  {$IFDEF DFS_CPPB_3_UP}
  {$EXTERNALSYM DFS_COMPONENT_VERSION}
  {$ENDIF}
  DFS_COMPONENT_VERSION = 'DSAMsg Unit v2.17';

type
{: The TdfsDSAForm class is a TForm descendant that you can base your forms on...
   to easily provide "Don't Show Again" functionalitiy.  Several properties...
   have been added to provide complete control over where the information...
   on the displayable state of the dialog is stored, but you will often find...
   that simply leaving them blank (which uses default values based on your...
   application) will be sufficient.

   The DSA_CheckBox property is key as it defines the TCheckbox component on...
   the form to be used to indicate whether or not the user wishes to see the...
   form in the future or not.  You must assign a TCheckbox to it, or the DSA...
   state can not be saved.

   The two key methods that you need to be aware of are DSAShow and...
   DSAShowModal.  Because the Show and ShowModal methods of TForm are not...
   virtual, they can not be overriden by descendants.  Therefore, I had to...
   provide completely new equivalents of these functions.  One nice side...
   effect of this is that if you want to treat the form as DSA in some...
   situations but not others, you would simply call the old methods and not...
   have to fool with making sure it was displayable first.

   Design-time support of the new properties is available for Delphi...
   3.  Previous versions of Delphi and C++Builder 1.0 do NOT support...
   design-time access of TForm descendants.  Sorry, just be happy Borland...
   added it to Delphi 3 (and I presume C++B 3.0).  Unlike a normal component,...
   TForm descendant classes must also have a package installed for the...
   registration process to work.  See the installation notes in DSAMsg.Txt...
   for complete installation instructions.

   If you are not using Delphi 3, you can still have your forms descend from...
   TdfsDSAForm, you simply won't have design-time access to the properties.  In...
   that case you will have to set the property values in code, most likely in...
   the form's OnCreate event handler or just after calling the form's Create...
   constructor if operating outside of the form's code.
   }
  TdfsDSAForm = class(TForm)
  private
    FDSA_NotShowable: boolean; { Internal flag only! }
    {$IFDEF DFS_WIN32}
    FDSA_UseRegistry: boolean;
    {$ENDIF}
    FDSA_Filename: string;
    FDSA_ID: string;
    FDSA_DefaultResult: integer;
    FDSA_CheckBox: TCheckBox;

    procedure SetDSAShowable(Value: boolean);
    function GetDSAShowable: boolean;
  protected
    function GetVersion: string;
    procedure SetVersion(const Val: string);
    procedure Notification(AComponent: TComponent; Operation: TOperation); override;
  public
    { Create creates and initializes an instance of TGradientForm. }
    {: No documentaion, does nothing special the client needs to be aware of. }
    constructor Create(AOwner: TComponent); override;
    {: Destroys an instance of TGradientForm, storing DSA information. The...
       DSA_Checkbox value must still be valid in the destructor, since that...
       is the point at which the DSA information is stored.  You must not...
       free the TCheckbox that is used for DSA purposes or the information...
       cannot be stored. }
    destructor Destroy; override;

    {: Shows the form modelessly, or not if the user has requested that it...
       not be shown.  In that case, the window is simply closed.  The...
       instance of the form is not freed unless you have set CloseAction to...
       caFree in then OnClose event handler.

       Note that this function MUST be used in place of the normal Show...
       method because Show is not virtual (i.e. it can't be overriden to...
       modify behavior).  One nice side effect of this is that if you want...
       to treat the form as DSA in some situations but not others, you would...
       simply call the Show method and not have to fool with making sure it...
       was displayable first.
    }
    procedure DSAShow;
    {: Shows the form modally, or not if the user has requested that it...
       not be shown.  In that case, the window is simply closed and the value...
       of DSA_DefaultResult is returned.  The instance of the form is not...
       automatically freed, and must be treated as you would any normal TForm.

       Note that this function MUST be used in place of the normal ShowModal...
       method because ShowModal is not virtual (i.e. it can't be overriden to...
       modify behavior).  One nice side effect of this is that if you want...
       to treat the form as DSA in some situations but not others, you would...
       simply call the ShowModal method and not have to fool with making sure...
       it was displayable first.
    }
    function DSAShowModal: Integer;

    {: Use the DSAClear method to reset form's displayable state.  That is, if...
       the user has elected not to show the form, you can reset it so that...
       it will show up again.

       Normally, there is no way to re-enable a form once the user has turned...
       it off since it isn't displayed any longer.  However, it is wise to...
       include the ability to turn these back on in case the user disabled it...
       by accident, or changes its mind.  This functionality is often found in...
       a configuration/settings dialog.
    }
    procedure DSAClear;
  published
    property Version: string
       read GetVersion
       write SetVersion
       stored FALSE;
    {: The DSA_UseRegistry property is used to indicate if the displayable state...
       of the form should be stored in the registry or an INI file.  The...
       actual location in the registry or INI file is controlled by the...
       DSA_Filename and DSA_ID properties.  This property merely indicates...
       how those values should be interpretted.

       This property is not avaible under Delphi 1.
    }
    {$IFDEF DFS_WIN32}
    property DSA_UseRegistry: boolean
       read FDSA_UseRegistry write FDSA_UseRegistry;
    {$ENDIF}
    {: DSA_Filename is the INI file name (DSA_UseRegistry = FALSE) or Registry...
       path (Win32 only, DSA_UseRegistry = TRUE) that is used in conjunction...
       with the DSA_ID property to store the displayable state of the form.

       If this value is blank, the value of the DefaultFilename global is used.
    }
    property DSA_Filename: string
       read FDSA_Filename write FDSA_Filename;
    {: DSA_ID is the INI section name (DSA_UseRegistry = FALSE) or Registry...
       path subkey (Win32 only, DSA_UseRegistry = TRUE) that is used in...
       conjunction with the DSA_Filename property to store the displayable...
       state of the form.

       If this value is blank, the value of the ClassName property is used.
    }
    property DSA_ID: string
       read FDSA_ID write FDSA_ID;
    {: The DSA_DefaultResult property is used to specify what value the...
       DSAShowModal method should return if the user has elected not to...
       display the form.
    }
    property DSA_DefaultResult: integer
       read FDSA_DefaultResult write FDSA_DefaultResult;
    {: The DSA_CheckBox property identifies the TCheckBox component on the...
       form that should be treated as the "Don't Show Again" checkbox.  If...
       this property is blank (NIL), DSA functionality is disabled for the...
       form (i.e. DSAShowModal and DSAShow will always show the form).

       Simply assign any existing TCheckBox component on the form to this...
       property and when the form is destroyed, this checkbox will be used...
       to indicate the displayable state of the form for future calls to...
       DSAShow and DSAShowModal.

       If the box is checked, that indicates that it should not be shown in...
       the future.  The checkbox's caption should be worded accordingly.
    }
    property DSA_CheckBox: TCheckBox
       read FDSA_CheckBox write FDSA_CheckBox;
    {: The DSA_Showable property is used to check or set the displayable state...
       of the form.

       Normally, there is no way to re-enable a form once the user has turned...
       it off since it isn't displayed any longer.  However, it is wise to...
       include the ability to turn these back on in case the user disabled it...
       by accident, or changes its mind.  This functionality is often found in...
       a configuration/settings dialog.

       Setting this value to FALSE is equivalent to calling the DSAClear method.
    }
    property DSA_Showable: boolean
       read GetDSAShowable write SetDSAShowable;
  end;


{: A TForm.ShowModal replacement function.  This function will display the...
   form passed in the AForm parameter using the form class' ShowModal...
   function.  However, before ShowModal is called, the function will add a...
   check box in the bottom left corner of the form.  If the user checks it...
   before closing the form, the form will not be displayed in the future...
   when this function is called.

   The text that appears next to the check box is "Don't show this message...
   again", but this can be changed by using the DontShowMsgText global variable.

   If the user elects not to display the form in the future, this function...
   stores a value in an INI file or the registry (Win32 only) to identify...
   this fact.  Where this value is stored is controlled by three global...
   variables defined in the DSAMsg unit: UseRegistry, RegRootKey, and...
   DefaultFilename.  These values can be changed in your program if you so...
   desire.  A unique identifier based on the class name of the form will also...
   be used.  If you need more precise control over the storage location, you...
   should use the DSAIdentsShowModal function.

   If you need to re-enable a form that has been disabled, you can use the...
   DSAFormClear function, passing it the class type of the form variable you...
   passed to this function.  The form will then be displayed when this...
   function is called.

   AForm is an instance of the form you want to display already created.  The...
   DefaultResult value is used to specify what value to return if the user...
   has elected not to display the form.

   DSAShowModal returns the same value that TForm.ShowModal returns, except...
   if the form is not displayed.  In that case, the value of the...
   DefaultResult parameter is returned.

   $<EXAMPLE> }
function DSAShowModal(const AForm: TForm; DefaultResult: word): Word;


{: A TForm.ShowModal replacement function.  This function will display the...
   form passed in the AForm parameter using the form class' ShowModal...
   function.  However, before ShowModal is called, the function will add a...
   check box in the bottom left corner of the form.  If the user checks it...
   before closing the form, the form will not be displayed in the future...
   when this function is called.

   The text that appears next to the check box is "Don't show this message...
   again", but this can be changed by using the DontShowMsgText global variable.

   If the user elects not to display the form in the future, this function...
   stores a value in an INI file or the registry (Win32 only) to identify...
   this fact.  Where this value is stored is controlled by the Filename and...
   ID parameters, along with three global variables defined in the DSAMsg...
   unit: UseRegistry, RegRootKey, and DefaultFilename.  These values can be...
   changed in your program if you so desire.  If you leave the Filename...
   parameter blank, the value in DefaultFilename will be used.  If this is...
   also blank, or if ID is blank, an exception will be raised.

   If you need to re-enable a form that has been disabled, you can use the...
   DSAIdentsClear function, passing it the same Filename and ID parameters as...
   you passed to this function.  The form will then be displayed when this...
   function is called.

   AForm is an instance of the form you want to display already...
   created.  Filename is the INI file name or Registry path (Win32 only) that...
   is used in conjunction with the ID identifier to store the displayable...
   state of the dialog.  DefaultResult value is used to specify what value to...
   return if the user has elected not to display the form.

   DSAIdentsShowModal returns the same value that TForm.ShowModal returns,...
   except if the form is not displayed.  In that case, the value of the...
   DefaultResult parameter is returned.

   $<EXAMPLE> }
function DSAIdentsShowModal(const AForm: TForm; Filename, ID: string;
   DefaultResult: word): Word;


{: A MessageDlg replacement function.  This function will display a dialog...
   that is identical to the one that MessageDlg will display, except it will...
   also include a check box in the bottom left corner of the dialog.  If the...
   user checks it before closing the dialog, the dialog will not be displayed...
   in the future when this function is called.

   The text that appears next to the check box is "Don't show this message...
   again", but this can be changed by using the DontShowMsgText global variable.

   If the user elects not to display the dialog in the future, this function...
   stores a value in an INI file or the registry (Win32 only) to identify...
   this fact.  Where this value is stored is controlled by three global...
   variables defined in the DSAMsg unit: UseRegistry, RegRootKey, and...
   DefaultFilename.  These values can be changed in your program if you so...
   desire.  A unique identifier based on the Msg parameter will also be...
   used.  If you need more precise control over the storage location, you...
   should use the DSAIdentsMessageDlg.

   If you need to re-enable a dialog that has been disabled, you can use the...
   DSAClear function, passing it the same Msg parameter as you pass to this...
   function.  The dialog will then be displayed when this function is called.

   The message box displays the value of the Msg parameter.  Use the AType...
   parameter to indicate the purpose of the dialog.  Use the AButtons...
   parameter to indicate what buttons should appear in the message box.  Use...