dsamsg.pas

动态提示控件

   the HelpCtx parameter to specify the context ID for the help topic that...
   should appear when the user clicks the help button or presses F1 while the...
   dialog is displayed. Use the DefaultResult value to specify what value to...
   return if the user has elected not to display the dialog.

   DSAMessageDlg returns the value of the button the user selected, or the...
   value of the DefaultResult parameter if the dialog was not displayed. These...
   are the possible return values if DefaultResult is not used:

   	mrNone	mrAbort	mrYes
   	mrOk	mrRetry	mrNo
   	mrCancel	mrIgnore	mrAll

   $<EXAMPLE> }
function DSAMessageDlg(const Msg: string; AType: TMsgDlgType;
   AButtons: TMsgDlgButtons; HelpCtx: Longint; 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 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 dialog that has been disabled, you can use the...
   DSAIdentsClear function, passing it the same Filename and ID parameters 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...
   the HelpCtx parameter to specify the context ID for the help topic that...
   should appear when the user clicks the help button or presses F1 while the...
   dialog is displayed.  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.  Use the DefaultResult value to...
   specify what value to return if the user has elected not to display the...
   dialog.

   DSAIdentsMessageDlg returns the value of the button the user selected, or...
   the value of the DefaultResult parameter if the dialog was not...
   displayed. These are the possible return values if DefaultResult is not used:

   	mrNone	mrAbort	mrYes
   	mrOk	mrRetry	mrNo
   	mrCancel	mrIgnore	mrAll

   $<EXAMPLE> }
function DSAIdentsMessageDlg(const Msg: string; AType: TMsgDlgType;
   AButtons: TMsgDlgButtons; HelpCtx: Longint; Filename, ID: string;
   DefaultResult: word): Word;


{: Use the DSAFormClear procedure to reset a DSAShowModal form that has been...
   disabled by the user.  Simply pass the class type of the form that was...
   passed to the DSAShowModal function.

   Normally, there is no way to re-enable a dialog 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.

   $<EXAMPLE> }
procedure DSAFormClear(const AFormClass: TFormClass);


{: Use the DSAClear procedure to reset a DSAMessageDlg dialog that has been...
   disabled by the user.  Simply pass the same text in the Msg parameter as...
   you do in the Msg parameter of the DSAMessageDlg function.

   Normally, there is no way to re-enable a dialog 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.

   $<EXAMPLE> }
procedure DSAClear(const Msg: string);


{: Use the DSAIdentsClear procedure to reset a DSAIdentsMessageDlg dialog..
   that has been disabled by the user.  Simply pass the same values in the...
   Filename and ID parameters as you do in the Filename and ID parameters of...
   the DSAIdentsMessageDlg function.

   Normally, there is no way to re-enable a dialog 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.

   $<EXAMPLE>
}
procedure DSAIdentsClear(Filename, ID: string);


{: This routine allows you to get the displayable state a form that is used...
   with the DSAShowModal or DSAIdentsShowModal function.

   Simply pass the form class to the function and if the form has been...
   disabled by the user, this function returns FALSE; otherwise, TRUE is...
   returned.

   This function is useful when allowing users to restore DSA dialogs that...
   they have hidden.

   $<EXAMPLE> }
function DSAFormGetState(const AFormClass: TFormClass): boolean;


{: This routine allows you to set the displayable state a form that is used...
   with the DSAShowModal or DSAIdentsShowModal function.

   Simply pass the form class to the function and a boolean value indicating...
   whether or not the form should be displayed.

   This function is useful when allowing users to override DSA dialogs...
   settings, in a configuration dialog for instance.

   $<EXAMPLE> }
procedure DSAFormSetState(const AFormClass: TFormClass; Value: boolean);


{: This routine allows you to get the displayable state for a dialog that is...
   used with the DSAMessageDlg function.

   Simply pass the same message string to the function that is passed to the...
   DSAMessageDlg function and if the dialog has been disabled by the user,...
   this function returns FALSE; otherwise, TRUE is returned.

   This function is useful when allowing users to restore DSA dialogs that...
   they have hidden.

   $<EXAMPLE> }
function DSAGetState(Msg: string): boolean;


{: This routine allows you to set the displayable state for a dialog that is...
   used with the DSAMessageDlg function.

   Simply pass the same message string to the function that is passed to the...
   DSAMessageDlg function and a boolean value indicating whether or not the...
   dialog should be displayed by DSAMessageDlg.

   This function is useful when allowing users to set preferences for showing...
   or hiding DSA dialogs from a central location (say a configuration dialog...
   that lists all DSA dialogs).

   $<EXAMPLE> }
procedure DSASetState(Msg: string; Value: boolean);


{: This routine allows you to get the displayable state for a dialog that is...
   used with the DSAIdentsMessageDlg function.

   Simply pass the same Filename and ID parameters to the function that are...
   passed to the DSAIdentsMessageDlg function and if the dialog has been...
   disabled by the user, this function returns FALSE; otherwise, TRUE is...
   returned.

   This function is useful when allowing users to restore DSA dialogs that...
   they have hidden.

   $<EXAMPLE> }
function DSAIdentsGetState(Filename, ID: string): boolean;


{: This routine allows you to set the displayable state for a dialog that is...
   used with the DSAIdentsMessageDlg function.

   Simply pass the same Filename and ID parameters to the function that are...
   passed to the DSAIdentsMessageDlg function and and a boolean value...
   indicating whether or not the dialog should be displayed by...
   DSAIdentsMessageDlg.

   This function is useful when allowing users to set preferences for showing...
   or hiding DSA dialogs from a central location (say a configuration dialog...
   that lists all DSA dialogs).

   $<EXAMPLE> }
procedure DSAIdentsSetState(Filename, ID: string; Value: boolean);


const
  {: This constant is the string that is assigned to the Name property of the...
     checkbox that is created by the various DSA dialog functions.  It is...
     included in case you ever needed to find the checkbox component.  You...
     can simply search for it using the FindComponent method, passing this...
     value as the parameter. 

   $<EXAMPLE> }
  DSA_CHECKBOX_NAME = '__DSA_CheckBox'; { in case you ever need to find it. }

{$IFDEF DFS_WIN32}
{$WRITEABLECONST ON}
  {: This writeable constant (also known as a static variable) allows you to...
     control whether the dialog display state storage uses the registry or an...
     INI file.  By default, the registry is used for Win32 (Windows 95 and...
     Windows NT), but simply setting this to FALSE will cause values to saved...
     in an INI file.

     This is only available under Win32.  It does not exist in Delphi 1 since...
     the registry is not the same as it is in Win32.  Only INI files can be...
     used in Delphi 1.

   $<EXAMPLE> }
  UseRegistry: boolean = TRUE;

  {: This writeable constant (also known as a static variable) allows you to...
     control which root registry key is used when storing dialog display...
     state information to the registry.  By default, the HKEY_CURRENT_USER...
     key is used, as that is the recommend key for applications to use...
     However, you may assign any of the HKEY_* constants to this to change...
     the root key.

     This is only available under Win32.  It does not exist in Delphi 1 since...
     the registry is not the same as it is in Win32.  Only INI files can be...
     used in Delphi 1.

   $<EXAMPLE> }
  RegRootKey: HKey = HKEY_CURRENT_USER;

{$ENDIF}

  {: This writeable constant (also known as a static variable) allows you to...
     control the default registry key or INI filename to use when storing...
     dialog display state information.

     This value is used by DSAMessageDlg, and also by DSAIdentsMessageDlg...
     when the Filename parameter has been left blank.

     If you are compiling for Win32, the default is 'Software\your_app_title\...
     DSADialogs\' where 'your_app_title' is the value returned by...
     Application.Title.

     If you are compiling for Win16, the default is an INI file with the same...
     name as your executable, and in the same directory.

   $<EXAMPLE> }
  DefaultFilename: string = ''; { Value set in initialization section }

  {: This writeable constant (also known as a static variable) allows you to...
     control the text that appears next to the check box.  By default, this...
     value is "&Don't show this message again".  If you do not like this, or...
     if using a foreign language, you can change the text by assigning your...
     own value.

   $<EXAMPLE> }
  DontShowMsgText: string = SDontShow;

  { Allowable characters in INI/registry keys.  Modified in InitValidChars below}
  Valid_Key_chars: set of char = ['~', '!', '@', '#', '$', '%', '^', '&',
     '_', '-'];


implementation

uses
  SysUtils, WinProcs, IniFiles;


{$IFDEF DFS_DELPHI_1}
function Trim(const S: string): string;
var
  I, L: Integer;
begin
  L := Length(S);
  I := 1;
  while (I <= L) and (S[I] <= ' ') do Inc(I);
  if I > L then Result := '' else
  begin
    while S[L] <= ' ' do Dec(L);
    Result := Copy(S, I, L - I + 1);
  end;
end;
{$ENDIF}


{ Utility function to strip invalid characters from INI and registry keys }
function StripInvalidChars(const S: string; AllowSlash: boolean): string;
var
  x: integer;
begin
  Result := '';
  for x := 1 to Length(S) do
  begin
    if (S[x] in ['\', '.', ':']) and AllowSlash then
      Result := Result + S[x]
    else if S[x] in Valid_Key_Chars then
      Result := Result + S[x]
    else
      Result := Result + ' ';
  end;
  { Also have to strip leading/trailing blanks or it messes up INI sections }
  Result := Trim(Result);
end;


{ Create creates and initializes an instance of TdfsDSAForm. }
constructor TdfsDSAForm.Create(AOwner: TComponent);
begin
  FDSA_NotShowable := FALSE;
  {$IFDEF DFS_WIN32}
  FDSA_UseRegistry := TRUE;
  {$ENDIF}
  FDSA_DefaultResult := mrOk;

  { have to call after so we don't stomp on stuff that may happen in OnCreate }
  inherited Create(AOwner);
end;


destructor TdfsDSAForm.Destroy;
var
  {$IFDEF DFS_WIN32}
  OldUseReg: boolean;
  {$ENDIF}
  AnID: string;
begin
  if assigned(FDSA_CheckBox) and (not FDSA_NotShowable) then
  begin
    if DSA_ID = '' then
      AnID := ClassName
    else
      AnID := DSA_ID;

    {$IFDEF DFS_WIN32}
    OldUseReg := UseRegistry;
    UseRegistry := DSA_UseRegistry;
    try
    {$ENDIF}
      DSAIdentsSetState(DSA_Filename, AnID, not DSA_CheckBox.Checked);
    {$IFDEF DFS_WIN32}
    finally
      UseRegistry := OldUseReg;
    end;
    {$ENDIF}
  end;

  inherited Destroy;
end;

function TdfsDSAForm.GetVersion: string;
begin
  Result := DFS_COMPONENT_VERSION;
end;

procedure TdfsDSAForm.SetVersion(const Val: string);
begin
  { empty write method, just needed to get it to show up in Object Inspector }
end;

procedure TdfsDSAForm.Notification(AComponent: TComponent; Operation: TOperation);
begin
  if Operation = opRemove then
  begin
    if AComponent = FDSA_CheckBox then
      FDSA_CheckBox := NIL;
  end else begin  { opInsert }
    if (FDSA_CheckBox = NIL) and (AComponent is TCheckBox) then
      FDSA_CheckBox := TCheckBox(AComponent);
  end;

  inherited Notification(AComponent, Operation);
end;


procedure TdfsDSAForm.SetDSAShowable(Value: boolean);
{$IFDEF DFS_WIN32}
var
  OldUseReg: boolean;
{$ENDIF}
begin
  if ([csLoading, csReading] * ComponentState) <> [] then