Improve TaskDialogMsgBox so caller can request to have Cancel in the main list of options instead of as a regular button at the bottom. Also add some comments.

Projects/Src/Shared.TaskDialogFunc.pas

@@ -105,13 +105,11 @@ begin
 end;
 
 function TaskDialogMsgBox(const Icon, Instruction, Text, Caption: String; const Typ: TMsgBoxType; const Buttons: Cardinal; const ButtonLabels: array of String; const ShieldButton: Integer; const VerificationText: String = ''; const pfVerificationFlagChecked: PBOOL = nil): Integer;
-var
-  IconP: PChar;
-  TDCommonButtons: Cardinal;
-  NButtonLabelsAvailable: Integer;
-  ButtonIDs: array of Integer;
 begin
   Application.Restore; { See comments in AppMessageBox }
+
+  { Set icon }
+  var IconP: PChar;
   if Icon <> '' then
     IconP := PChar(Icon)
   else begin
@@ -123,7 +121,11 @@ begin
       IconP := nil; { No other TD_ constant available, MS recommends to use no icon for questions now and the old icon should only be used for help entries }
     end;
   end;
-  NButtonLabelsAvailable := Length(ButtonLabels);
+
+  { Set ButtonIDs and TDCommonButtons }
+  const NButtonLabelsAvailable = Length(ButtonLabels);
+  var ButtonIDs: array of Integer;
+  var TDCommonButtons: Cardinal;
   case Buttons of
     MB_OK, MB_OKCANCEL:
       begin
@@ -171,8 +173,20 @@ begin
         TDCommonButtons := 0; { Silence compiler }
       end;
   end;
+
+  { Allow extra label to replace TDCBF_CANCEL_BUTTON by an IDCANCEL button id }
+  if (TDCommonButtons or TDCBF_CANCEL_BUTTON <> 0) and
+     (NButtonLabelsAvailable-1 = Length(ButtonIDs)) then begin
+    TDCommonButtons := TDCommonButtons and not TDCBF_CANCEL_BUTTON;
+    SetLength(ButtonIDs, NButtonLabelsAvailable);
+    ButtonIDs[NButtonLabelsAvailable-1] := IDCANCEL;
+  end;
+
+  { Check }
   if Length(ButtonIDs) <> NButtonLabelsAvailable then
     DoInternalError('TaskDialogMsgBox: Invalid ButtonLabels');
+
+  { Go }
   if not DoTaskDialog(GetOwnerWndForMessageBox, PChar(Instruction), PChar(Text),
            GetMessageBoxCaption(PChar(Caption), Typ), IconP, TDCommonButtons, ButtonLabels, ButtonIDs, ShieldButton,
            GetMessageBoxRightToLeft, IfThen(Typ in [mbError, mbCriticalError], MB_ICONSTOP, 0), Result, PChar(VerificationText), pfVerificationFlagChecked) then //note that MB_ICONEXCLAMATION (used by mbError) includes MB_ICONSTOP (used by mbCriticalError)