Unit DSAMsg

Standard defines for all Delphi Free Stuff components } {-----------------------------------------------------------------------------} { DSAMsg Unit v2.03 } {-----------------------------------------------------------------------------} { 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 1998, Brad Stowers. All Rights Reserved. } { This unit can be freely used and distributed in commercial and private } { environments, provied this notice is not modified in any way and there is } { no charge for it other than nomial handling fees. Contact me directly for } { modifications to this agreement. } {-----------------------------------------------------------------------------} { Feel free to contact me if you have any questions, comments or suggestions } { at bstowers@pobox.com. } { The lateset version will always be available on the web at: } { http://www.pobox.com/~bstowers/delphi/ } { See DSAMsg.txt for notes, known issues, and revision history. } {-----------------------------------------------------------------------------} { Date last modified: June 9, 1998 } {-----------------------------------------------------------------------------} {: 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.

Classes

TDSAForm - : The TDSAForm class is a TForm descendant that you can base your forms on.

Functions

DSAClear - : Use the DSAClear procedure to reset a DSAMessageDlg dialog that has been.
DSAFormClear - : Use the DSAFormClear procedure to reset a DSAShowModal form that has been.
DSAFormGetState - : This routine allows you to get the displayable state a form that is used.
DSAFormSetState - : This routine allows you to set the displayable state a form that is used.
DSAGetState - : This routine allows you to get the displayable state for a dialog that is.
DSAIdentsClear - : Use the DSAIdentsClear procedure to reset a DSAIdentsMessageDlg dialog.
DSAIdentsGetState - : This routine allows you to get the displayable state for a dialog that is.
DSAIdentsMessageDlg - : A MessageDlg replacement function.
DSAIdentsSetState - : This routine allows you to set the displayable state for a dialog that is.
DSAIdentsShowModal - : A TForm.
DSAMessageDlg - : A MessageDlg replacement function.
DSASetState - : This routine allows you to set the displayable state for a dialog that is.
DSAShowModal - : A TForm.

Types

Constants

DefaultFilename
DFS_COMPONENT_VERSION
DontShowMsgText
DSA_CHECKBOX_NAME

Variables


Functions


procedure DSAClear(const Msg: string);

: 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. $

procedure DSAFormClear(const AFormClass: TFormClass);

: 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. $

function DSAFormGetState(const AFormClass: TFormClass): boolean;

: 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. $

procedure DSAFormSetState(const AFormClass: TFormClass; Value: 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. $

function DSAGetState(Msg: string): 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. $

procedure DSAIdentsClear(Filename, ID: 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. $

Don't need to free DSA item because it is owned by the form. It will do it when it is freed.


function DSAIdentsGetState(Filename, ID: string): 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. $

function DSAIdentsMessageDlg(const Msg: string; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: Longint; 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 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 $

procedure DSAIdentsSetState(Filename, ID: string; Value: 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). $

function DSAIdentsShowModal(const AForm: TForm; Filename, ID: string; 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. $

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 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... 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 $

Don't need to free DSA item because it is owned by the form. It will do it when it is freed.


procedure DSASetState(Msg: string; Value: 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). $

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 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. $

Types


Constants

DefaultFilename = ''

in case you ever need to find it. } {: 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. $

DFS_COMPONENT_VERSION = 'DSAMsg Unit v2.03'

DontShowMsgText = '&Don''t show this message again'

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. $

DSA_CHECKBOX_NAME = '__DSA_CheckBox'

: 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. $

Variables