mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-04-26 12:03:51 +02:00
Docs: Improve docs of QuestionDlg() and DefaultQuestionDlg().
This commit is contained in:
wp_xyz
parent
e17301cab0
commit
c9ea96d637
@ -4062,7 +4062,7 @@ end;
|
||||
Buttons
|
||||
</dt>
|
||||
<dd>
|
||||
Contains a pointer to an array of LongInt values which define the buttons displayed for the dialog. The values correspond to idButtonBase values defined in the LCLType unit like: idButtonOk, idButtonCancel, idButtonHelp, idButtonYes, idButtonNo, idButtonClose, idButtonAbort, idButtonRetry, idButtonIgnore, idButtonAll, idButtonYesToAll, or idButtonNoToAll. Buttons using the identifiers idButtonOpen, idButtonSave, and idButtonShield are not implemented in the current LCL version. The values for each of the buttons indicates the default icon and text for the button, as well as its modal result value.
|
||||
Contains a pointer to an array of LongInt values which define the buttons displayed for the dialog. The values correspond to idButtonBase values defined in the LCLType unit like: idButtonOk, idButtonCancel, idButtonHelp, idButtonYes, idButtonNo, idButtonClose, idButtonAbort, idButtonRetry, idButtonIgnore, idButtonAll, idButtonYesToAll, or idButtonNoToAll. Buttons using the identifiers idButtonOpen, idButtonSave, and idButtonShield are not implemented in the current LCL version. The values for each of the buttons indicate the default icon and text for the button, as well as its modal result value.
|
||||
</dd>
|
||||
<dt>
|
||||
ButtonCount
|
||||
@ -4157,50 +4157,50 @@ end;
|
||||
</element>
|
||||
|
||||
<element name="QuestionDlg">
|
||||
<short>Show a question to the user and get a response.</short>
|
||||
<short>Show a question to the user and get a response. Similar to MessageDlg, but allows to use custom button captions and any response values.</short>
|
||||
<descr>
|
||||
<p>
|
||||
QuestionDlg has the same functionality as MessageDlg except for the parameter Buttons which is of a different type. You can define your own captions and return values of this function.
|
||||
QuestionDlg has the same functionality as MessageDlg except for the parameter <var>Buttons</var> which is of a different type. You can define your own captions and return values of this function.
|
||||
</p>
|
||||
<p>
|
||||
Buttons is a list of TModalResult (defined as constants [mrNone..MrYesToAll] in <link id="Controls"/>) and strings. For each TModalResult a button is created. To set a custom caption, add a string after a button. You can use the special string parameters 'isdefault' and 'iscancel' to setup the default and cancel buttons.
|
||||
<var>Buttons</var> contains an array of integer identifiers and optional strings. For each number a button is created. Usually the identifiers are selected as the <var>TModalResult</var> constants <var>[mrNone..mrYesLast]</var> in <link id="Controls"/>); the correspondig buttons will be decorated by an associated icon. Any other integers can be used as well, but their buttons will have no icon. The identifier number of the clicked button is returned by the <var>QuestionDlg()</var> function. The order of the buttons on the dialog form will be the same as the order of the array elements.
|
||||
</p>
|
||||
<p>
|
||||
The default TModalResults defined in controls.pp (mrNone..mrLast) don't need a caption. The default captions will be used.
|
||||
Each string following the button identifier in the <var>Buttons</var> array denotes the caption of the button. When the button identifier is one of the default <var>TModalResult</var> values defined in controls.pp (<var>mrNone..mrLast</var>) the caption can be omitted, and the default caption will be used. For non-<var>TModalResult</var> identifiers, the caption MUST be specified. Empty strings are not allowed as captions, they will create a runtime error.
|
||||
</p>
|
||||
<p>
|
||||
You can mark one default button using the 'IsDefault' option. When the user presses 'Return' this button is triggered.
|
||||
You can mark one default button by adding the 'IsDefault' option after the caption string. When the user presses 'Return' this button is triggered.
|
||||
</p>
|
||||
<p>
|
||||
Some widgetsets provide an Escape key and/or a close button. This results in mrCancel even if it is not in the given button list. Use the 'IsCancel' option to redirect it to a button of your choice. You can combine 'IsDefault' and 'IsCancel'.
|
||||
Some widgetsets provide an Escape key and/or a close button. This results in <var>mrCancel</var> even if it is not in the given button list. Use the 'IsCancel' option after the caption string to redirect it to a button of your choice. You can combine 'IsDefault' and 'IsCancel'.
|
||||
</p>
|
||||
<p>
|
||||
<b>Example</b>
|
||||
</p>
|
||||
<code>
|
||||
case QuestionDlg('COPYING',
|
||||
'Abort?',
|
||||
mtConfirmation,
|
||||
[mrNo, '&No','IsDefault',
|
||||
mrYes,'&Yes'],0)
|
||||
of
|
||||
mrYes : ShowMessage('You clicked Yes');
|
||||
mrNo : ShowMessage('You clicked No');
|
||||
else
|
||||
// mrCancel
|
||||
ShowMessage('You cancelled the dialog.');
|
||||
end;
|
||||
var
|
||||
res: TModalResult;
|
||||
...
|
||||
res := case QuestionDlg('COPYING', 'Abort?', mtConfirmation, [mrNo,'&No','IsDefault', mrYes,'&Yes'], 0)
|
||||
case res of
|
||||
mrYes : ShowMessage('You clicked Yes');
|
||||
mrNo : ShowMessage('You clicked No');
|
||||
else
|
||||
// mrCancel
|
||||
ShowMessage('You cancelled the dialog.');
|
||||
end;
|
||||
</code>
|
||||
</descr>
|
||||
<seealso>
|
||||
<link id="MessageDlg"/>
|
||||
<link id="InputQuery"/>
|
||||
<link id="DefaultQuestionDialog"/>
|
||||
</seealso>
|
||||
</element>
|
||||
<element name="QuestionDlg.Result">
|
||||
<short>
|
||||
The result of this function is the button the user pressed to close the dialog.
|
||||
The result of this function is the identifier number of the button that the user had pressed to close the dialog.
|
||||
</short>
|
||||
<descr>
|
||||
The result of this function is the button the user pressed to close the dialog.
|
||||
</descr>
|
||||
</element>
|
||||
<element name="QuestionDlg.aCaption">
|
||||
<short>Used to set the caption of the question dialog.</short>
|
||||
@ -4211,58 +4211,91 @@ end;
|
||||
<descr>The question the user has to answer.</descr>
|
||||
</element>
|
||||
<element name="QuestionDlg.DlgType">
|
||||
<short>The type of dialog to be shown in fact which icon will be shown.</short>
|
||||
<short>The type of dialog, it determines which icon will be shown.</short>
|
||||
</element>
|
||||
<element name="QuestionDlg.Buttons">
|
||||
<short>
|
||||
An array of return values and caption for the buttons on the question dialog.
|
||||
An array of return values and captions for the buttons on the question dialog.
|
||||
</short>
|
||||
<descr>
|
||||
<p>
|
||||
Buttons is defined as a array of const. This means you can define any number of buttons to be shown. If your array consists of only predefined return values like mrOK and mrCancel, the standard OK and Cancel buttons will be shown.
|
||||
</p>
|
||||
<p>
|
||||
The strength of this function is however that you can fill the array like:
|
||||
<var>Buttons</var> is defined as a array of const. This means you can define any number of buttons to be shown. If your array consists only of predefined return values like <var>mrOK</var> and <var>mrCancel</var>, the standard OK and Cancel buttons will be shown. The strength of this function, however, is that you can fill the array with arbitrary button identifiers and captions:
|
||||
</p>
|
||||
<code>[400, 'Yes!!!', 401, 'Are you mad?', 402, 'My mistake']</code>
|
||||
<p>
|
||||
This will create a dialog with three buttons; the captions for the buttons will be the strings values given in the array.
|
||||
</p>
|
||||
<p>
|
||||
The return value of the function will be 400, 401 or 402, depending on whether the user clicked the 'Yes!!!', the 'Are you mad?' or the 'My mistake' button.
|
||||
This will create a dialog with three buttons; the captions for the buttons will be the strings values given in the array after the numeric return values. The return value of the function will be 400, 401 or 402, depending on whether the user clicked the 'Yes!!!', the 'Are you mad?' or the 'My mistake' button.
|
||||
</p>
|
||||
</descr>
|
||||
</element>
|
||||
<element name="QuestionDlg.HelpCtx">
|
||||
<short>HelpCtx is used to specify which topic from the help should be shown.</short>
|
||||
<descr>HelpCtx is used to specify which topic from the help should be shown.</descr>
|
||||
<short>HelpCtx specifies the help topic that should be shown when F1 is pressed.</short>
|
||||
<descr>HelpCtx specifies the help topic that should be shown when F1 is pressed.</descr>
|
||||
</element>
|
||||
<element name="QuestionDlg.HelpKeyword">
|
||||
<short/>
|
||||
<short>HelpKeyword specifies the help topic that should be shown when F1 is pressed.</short>
|
||||
<descr>HelpKeyword specifies the help topic that should be shown when F1 is pressed.</descr>
|
||||
</element>
|
||||
|
||||
<element name="DefaultQuestionDialog">
|
||||
<short>Implements a widgetset-independent dialog.</short>
|
||||
<short>Implements a widgetset-independent dialog similar to QuestionDlg.</short>
|
||||
<descr>
|
||||
<p>
|
||||
Shows a dialog with aCaption as Title, aMsg as Text, DlgType as Icon,
|
||||
HelpCtx as Help context and Buttons to define the shown buttons and their
|
||||
TModalResult.
|
||||
<p>DefaultQuestionDialog displays a message dialog, similar to QuestionDlg, but it uses a LCL <var>TForm</var> instance instead of relying on dialogs provided by the operating system. The content displayed on the dialog form is specified by the arguments passed to the routine, including:
|
||||
</p>
|
||||
<dl>
|
||||
<dt>aCaption</dt>
|
||||
<dd>
|
||||
The title of the dialog, displayed in the title bar of the dialog form. In case of an empty string (''), the default caption of the dialog type (<var>DlgType</var> parameter) is selected, or, when the <var>DlgType</var> is not one of the <var>idDialogXXX</var> values the application title is used instead.
|
||||
</dd>
|
||||
<dt>aMsg</dt>
|
||||
<dd>The text of the message or question displayed in the dialog</dd>
|
||||
<dt>DlgType</dt>
|
||||
<dd>
|
||||
A LongInt value which defines the icon and default caption displayed for the dialog. It contains one of the constant values defined in the <var>LCLType</var> unit like: <var>idDialogWarning</var>, <var>idDialogError</var>, <var>idDialogInfo</var>, <var>idDialogConfirm</var>, or <var>idDialogShield</var>. Do not use the <var>mtXXXX</var> values used by other dialogs, they will produce the wrong icon.
|
||||
</dd>
|
||||
<dt>Buttons</dt>
|
||||
<dd>A collection of items representing the buttons shown in the dialog. Each item describes the button by its caption, an integer value which is returned by the function when this button is clicked, as well as boolean flags to identify the "Default" or "Cancel" button. The return value is typed <var>TModalResult</var>, but any other integers can be used as well. Be careful if you plan to use the <var>idButtonXXX</var> constants declared in the <var>LCLType</var> unit because they will assign the icons to the buttons differently. An empty caption string is NOT replaced by a default string here.
|
||||
</dd>
|
||||
<dt>HelpCtx</dt>
|
||||
<dd>Help context value for the help text to be displayed when the user presses F1.</dd>
|
||||
</dl>
|
||||
<p>
|
||||
Buttons is a list of TModalResult and strings. For each number a button is
|
||||
created. To set a custom caption, add a string after a button.
|
||||
<b>Example</b>
|
||||
</p>
|
||||
<p>
|
||||
Since <var>Buttons</var> is a <var>TCollection</var> each item must be added individually:
|
||||
</p>
|
||||
<code>
|
||||
var
|
||||
btns: TDialogButtons; // requires "uses InterfaceBase"
|
||||
res: Integer;
|
||||
...
|
||||
btns := TDialogButtons.Create(TDialogButton);
|
||||
with btns.Add do
|
||||
begin
|
||||
Caption := 'OK';
|
||||
ModalResult := mrOK;
|
||||
end;
|
||||
with btns.Add do
|
||||
begin
|
||||
Caption := 'Cancel now';
|
||||
ModalResult := mrCancel;
|
||||
end;
|
||||
with btns.Add do
|
||||
begin
|
||||
Caption := 'Ignore';
|
||||
ModalResult := mrIgnore;
|
||||
end;
|
||||
with btns.Add do
|
||||
begin
|
||||
Caption := 'Do it';
|
||||
ModalResult := 300;
|
||||
Default := true;
|
||||
end;
|
||||
|
||||
res := DefaultQuestionDialog('This is the caption', 'This is the title', idDialogError, btns, 0);
|
||||
</code>
|
||||
<p>
|
||||
The default TModalResults defined in controls.pp (mrNone..mrLast) does not need
|
||||
a caption. The default captions will be used.
|
||||
</p>
|
||||
<p>
|
||||
Examples for Buttons:
|
||||
</p>
|
||||
<code>[mrOk,mrCancel,'Cancel now',mrIgnore,300,'Do it','IsDefault']</code>
|
||||
<p>
|
||||
This will result in 4 buttons:
|
||||
This code will display a dialog box with the following four buttons:
|
||||
</p>
|
||||
<ul>
|
||||
<li>'Ok' returning mrOk</li>
|
||||
@ -4274,22 +4307,33 @@ end;
|
||||
<seealso/>
|
||||
</element>
|
||||
<element name="DefaultQuestionDialog.Result">
|
||||
<short/>
|
||||
<short>
|
||||
Returns the number value associated with each button.
|
||||
</short>
|
||||
</element>
|
||||
<element name="DefaultQuestionDialog.ACaption">
|
||||
<short/>
|
||||
<short>
|
||||
Title text of the dialog form
|
||||
</short>
|
||||
</element>
|
||||
<element name="DefaultQuestionDialog.AMsg">
|
||||
<short/>
|
||||
<short>
|
||||
Message text displayed in the dialog form.
|
||||
</short>
|
||||
</element>
|
||||
<element name="DefaultQuestionDialog.DlgType">
|
||||
<short/>
|
||||
<short>
|
||||
A number to select the icon shown in the dialog. Select one of the <var>idDialogXXXX</var> constants declared in the unit LCLType (<var>idDialogWarning</var>, <var>idDialogError</var>, <var>idDialogInfo</var>, <var>idDialogConfirm</var> or <var>idDialogShield</var>). Do not use the TMsgDlgType values which are used by other dialogs!
|
||||
</short>
|
||||
</element>
|
||||
<element name="DefaultQuestionDialog.Buttons">
|
||||
<short/>
|
||||
<short>
|
||||
A collection of button definitions with caption, return value when clicked, and boolean flags to identify the default and cancel button.
|
||||
</short>
|
||||
</element>
|
||||
<element name="DefaultQuestionDialog.HelpCtx">
|
||||
<short/>
|
||||
<short>HelpCtx specifies the help topic that should be shown when F1 is pressed.</short>
|
||||
<descr>HelpCtx specifies the help topic that should be shown when F1 is pressed.</descr>
|
||||
</element>
|
||||
|
||||
<element name="ShowMessage">
|
||||
|
||||
Loading…
Reference in New Issue
Block a user