Class TDSAForm (unit DSAMsg)

Inherits from

TForm

: The TDSAForm 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... TDSAForm, 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.

Constructors


constructor Create(AOwner: TComponent);

Create creates and initializes an instance of TGradientForm.


Functions

destructor Destroy;

: Destroys an instance of TGradientForm, storing DSA information.

procedure DSAClear;

: Use the DSAClear method to reset form's displayable state.

procedure DSAShow;

: Shows the form modelessly, or not if the user has requested that it.

function DSAShowModal: Integer;

: Shows the form modally, or not if the user has requested that it.

function GetVersion: TDFSVersion;


procedure Notification(AComponent: TComponent; Operation: TOperation);

empty write method, just needed to get it to show up in Object Inspector

procedure SetVersion(const Val: TDFSVersion);


function GetDSAShowable: boolean;


procedure SetDSAShowable(Value: boolean);

opInsert

Properties

property DSA_CheckBox : TCheckBox

: The DSA_CheckBox property identifies the TCheckBox component on the.

property DSA_DefaultResult : integer

: The DSA_DefaultResult property is used to specify what value the.

property DSA_Filename : string

: The DSA_UseRegistry property is used to indicate if the displayable state.

property DSA_ID : string

: DSA_ID is the INI section name (DSA_UseRegistry = FALSE) or Registry.

property Version : TDFSVersion


property DSA_Showable : boolean

: The DSA_Showable property is used to check or set the displayable state.

Events

Variables

FDSA_CheckBox : TCheckBox;


FDSA_DefaultResult : integer;


FDSA_Filename : string;

Internal flag only!

FDSA_ID : string;


FDSA_NotShowable : boolean;



Constructors


constructor Create(AOwner: TComponent);

Create creates and initializes an instance of TGradientForm. } {: No documentaion, does nothing special the client needs to be aware of.

Create creates and initializes an instance of TDSAForm.


Functions


destructor Destroy;

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

have to call after so we don't stomp on stuff that may happen in OnCreate


procedure DSAClear;

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

Flag it so we don't overwrite with the checkbox value


procedure DSAShow;

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


function DSAShowModal: Integer;

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

Flag it so we don't overwrite with the checkbox value


function GetVersion: TDFSVersion;


procedure Notification(AComponent: TComponent; Operation: TOperation);

empty write method, just needed to get it to show up in Object Inspector


procedure SetVersion(const Val: TDFSVersion);


function GetDSAShowable: boolean;


procedure SetDSAShowable(Value: boolean);

opInsert


Properties


property DSA_CheckBox : TCheckBox

: 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_DefaultResult : integer

: 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_Filename : string

: 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. } {: 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_ID : string

: 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 Version : TDFSVersion


property DSA_Showable : boolean

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


Events


Variables


FDSA_CheckBox : TCheckBox;


FDSA_DefaultResult : integer;


FDSA_Filename : string;

Internal flag only!


FDSA_ID : string;


FDSA_NotShowable : boolean;