DlgType property

Project: Message Dialogue Components.

Unit: PJMessageDialog.

Class: TPJVCLMsgDlg

Applies to: ~>3.0

property DlgType: LongWord;

Description

This property provides an alternative method to setting the ButtonGroup and Kind properties using a subset of the constants used to customise the MessageBox Windows API function via its uType parameter. However, not all the API flags are supported.

DlgType is never stored in a form file - it’s value is determined by the ButtonGroup and Kind property values and whether a help button is displayed. Changing any of these values modifies the value of DlgType. Conversely, setting DlgType can update one or more of the ButtonGroup, Buttons and Kind properties.

Often the value of DlgType will change as soon as it is set because of the presence of any unsupported values, whether a help button is displayed or if a required value has not been provided.

Reading and writing the property are dealt with separately below.

Setting DlgType

DlgType supports a combination of various categories of constants that are ORd together.

Button Group

The buttons displayed in the dialogue box can be determined by specifying one, and only one, of the following constants. Setting one of these values also updates the ButtonGroup property, which in turn updates the Buttons property.

If any other value in the range $00000000 to $0000000F is specified then ButtonGroup is set to bgUnknown and the value in DlgType is replaced by UNKNOWN_BUTTONGROUP (defined in PJMessageDialog.pas). To check for an unknown or invalid button group first set DlgType then perform the following test:

begin
  if PJVCLMsgDlg1.DlgType and MB_TYPEMASK = UNKNOWN_BUTTONGROUP then
    // button group unknown or unsupported
end;

Dialogue Kind

The kind of dialogue box (its icon, default title, etc.) is specified by ORing one of the following constants with one of those used to determine the button group. Setting one of these values updates the Kind property.

If any other value in the range $00000010 to $000000F0 is specified then Kind is set to mkUnknown and the value in DlgType is replaced by UNKNOWN_ICON (defined in PJMessageDialog.pas). To check for an unknown or invalid dialogue kind first set DlgType then perform the following test:

begin
  if PJVCLMsgDlg1.DlgType and MB_ICONMASK = UNKNOWN_ICON then
    // dialogue kind unknown or not supported
end;

Help Button

In the standard Windows API call specifying MB_HELP causes a help button to be displayed. In this component including MB_HELP in DlgType causes mbHelp to be included in the Buttons property. This may or may not cause a help button to be displayed, according to whether mdoAutoHelpBtn is included in the Options property.

Including MB_HELP in DlgType does not necessarily mean it will be included in the property when read. See the “Help Button” description in the “Reading DlgType” section below for details.

Note: Because of the way the Buttons and ButtonGroup properties interact, including MB_HELP in DlgType can cause ButtonGroup to be set to bgUnknown. To avoid this make sure you include mdoGroupIgnoresHelp in the Options property.

Reading DlgType

The value returned when DlgType is read does not directly relate to the value set. This is because the value of DlgType is not stored and its value when read is calculated from the values of various other properties. Consequently any unsupported flags are stripped away. Furthermore DlgType introduces some new flags to indicate errors.

Factors that determine the value of DlgType are:

1. The ButtonGroup property.
2. The Kind property.
3. Whether a help button will be displayed by the dialogue.

Each of these factors is discussed separately below.

Button Group

The button group component of DlgType is set according to the value of the ButtonGroup property as per the following table:

UNKNOWN_BUTTONGROUP and MB_CANCELTRYCONTINUE are both defined in the PJMessageDialog unit and the remaining values are defined in the Windows unit.

The button group values are ORd with other values stored in DlgType. To extract them AND the value of DlgType with MB_TYPEMASK. E.g.

var
  BG: LongWord;
begin
  BG := PJVCLMsgDlg1.DlgType and MB_TYPEMASK;
end;

Dialogue Kind

The component of DlgType that identifies the kind of dialogue box displayed is set according to the value of the Kind property as per the following table:

UNKNOWN_ICON is defined in the PJMessageDialog unit. Note that mkWinLogo and mkApplication have no equivalent in the MessageBox API function and are therefore flagged as unknown.

The dialogue kind values are ORd with other values stored in DlgType. To extract them AND the value of DlgType with MB_ICONMASK. E.g.

var
  K: LongWord;
begin
  K := PJVCLMsgDlg1.DlgType and MB_ICONMASK;
end;

Help Button

If the dialogue box will show a help button when displayed then MB_HELP is included in DlgType. This occurs in the following circumstances, depending on the Options property:

• mdoAutoHelpBtn is included in Options and HelpContext is non-zero.
• mdoAutoHelpBtn is not included in Options and mrHelp is included in Buttons.

These rules mean that the presence of MB_HELP when setting DlgType does not necessarily mean MB_HELP will be present when reading the property.

Check for the presence of MB_HELP like this:

begin
  if PJVCLMsgDlg1.DlgType and MB_HELP = MB_HELP then
    // MB_HELP present
end;