lazarus/docs/xml/lcl/taskdlgemulation.xml

660 lines
19 KiB
XML

<?xml version="1.0" encoding="utf-8"?>
<fpdoc-descriptions>
<package name="lcl">
<!--
========================================================================
TaskDlgEmulation
========================================================================
-->
<!--
TODO: Added in df338fd867.
Added in LCL version 4.0.
Check for reusable content from the deprecated lcltaskdialog.xml file.
-->
<module name="TaskDlgEmulation">
<short>
Implements an emulated task dialog for platforms where the Task Dialog API is
not supported.
</short>
<descr>
<p>
<file>TaskDlgEmulation.pp</file> contains types, routines, and variable used to implement a non-native, emulated Task Dialog. It is used in widgetset classes for platforms where the task dialog API is not available, or not supported for a specific version of an operating system.
</p>
<p>
It contains TLCLTaskDialog - a dynamically configured form displayed when a task dialog is executed using its configuration settings.
</p>
<p>
<file>TaskDlgEmulation.pp</file> is part of the Lazarus Component Library
(<b>LCL</b>).
</p>
<remark>
Added in LCL version 4.0 as replacement for the deprecated types in the
<file>lcltaskdialog.pas</file> unit.
</remark>
</descr>
<!-- unresolved references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LazUTF8"/>
<element name="LCLType"/>
<element name="LCLStrConsts"/>
<element name="LCLIntf"/>
<element name="InterfaceBase"/>
<element name="ImgList"/>
<element name="LCLProc"/>
<element name="DateUtils"/>
<element name="Math"/>
<element name="LResources"/>
<element name="Menus"/>
<element name="Graphics"/>
<element name="Forms"/>
<element name="Controls"/>
<element name="StdCtrls"/>
<element name="ExtCtrls"/>
<element name="Buttons"/>
<element name="Dialogs"/>
<element name="DialogRes"/>
<!-- TODO: Needs content. -->
<element name="TTaskDialogElement">
<short/>
<descr/>
<seealso/>
</element>
<element name="TTaskDialogElement.tdeContent">
<short/>
</element>
<element name="TTaskDialogElement.tdeExpandedInfo">
<short/>
</element>
<element name="TTaskDialogElement.tdeFooter">
<short/>
</element>
<element name="TTaskDialogElement.tdeMainInstruction">
<short/>
</element>
<element name="TTaskDialogElement.tdeEdit">
<short/>
</element>
<element name="TTaskDialogElement.tdeVerif">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="TLCLTaskDialog">
<short/>
<descr/>
<seealso/>
</element>
<!-- private -->
<element name="TLCLTaskDialog.RadioIndent"/>
<element name="TLCLTaskDialog.ComboBoxHeight"/>
<element name="TLCLTaskDialog.LargeImageSize"/>
<element name="TLCLTaskDialog.SmallImageSize"/>
<element name="TLCLTaskDialog.FDlg">
<short>
The task dialog structure which created the form.
</short>
</element>
<element name="TLCLTaskDialog.FVerifyChecked"/>
<element name="TLCLTaskDialog.FExpanded"/>
<element name="TLCLTaskDialog.FCommandLinkButtonWidth"/>
<element name="TLCLTaskDialog.Timer"/>
<element name="TLCLTaskDialog.TimerStartTime"/>
<element name="TLCLTaskDialog.RadioButtonArray"/>
<element name="TLCLTaskDialog.DialogCaption"/>
<element name="TLCLTaskDialog.DlgTitle"/>
<element name="TLCLTaskDialog.DlgText"/>
<element name="TLCLTaskDialog.ExpandButtonCaption"/>
<element name="TLCLTaskDialog.CollapseButtonCaption"/>
<element name="TLCLTaskDialog.ExpandedText"/>
<element name="TLCLTaskDialog.FooterText"/>
<element name="TLCLTaskDialog.VerificationText"/>
<element name="TLCLTaskDialog.CommonButtons"/>
<element name="TLCLTaskDialog.TopPanel"/>
<element name="TLCLTaskDialog.MidPanel"/>
<element name="TLCLTaskDialog.BottomPanel"/>
<element name="TLCLTaskDialog.Image"/>
<element name="TLCLTaskDialog.Element">
<short>
The labels corresponding to the Task Dialog main elements.
</short>
</element>
<element name="TLCLTaskDialog.QueryCombo">
<short>
Combo-box control with the Task Dialog selection list.
</short>
</element>
<element name="TLCLTaskDialog.QueryEdit">
<short>
Edit control with the optional Task Dialog query editor.
</short>
</element>
<element name="TLCLTaskDialog.VerifyCheckBox">
<short>
Check-box control used for optional Task Dialog verification.
</short>
</element>
<element name="TLCLTaskDialog.ExpandBtn">
<short>
The expand/collapse button (expando control) for the Task dialog.
</short>
</element>
<!-- private -->
<element name="TLCLTaskDialog.GetDefaultButtons"/>
<element name="TLCLTaskDialog.GetDefaultButtons.AButtonDef"/>
<element name="TLCLTaskDialog.GetDefaultButtons.ARadioDef"/>
<element name="TLCLTaskDialog.InitCaptions"/>
<element name="TLCLTaskDialog.InitGlobalDimensionsAndStyle"/>
<element name="TLCLTaskDialog.InitGlobalDimensionsAndStyle.ACustomButtonsTextLength"/>
<element name="TLCLTaskDialog.InitGlobalDimensionsAndStyle.AWidth"/>
<element name="TLCLTaskDialog.InitGlobalDimensionsAndStyle.AFontHeight"/>
<element name="TLCLTaskDialog.GetGlobalLeftMargin"/>
<element name="TLCLTaskDialog.GetGlobalLeftMargin.Result"/>
<element name="TLCLTaskDialog.AddIcon"/>
<element name="TLCLTaskDialog.AddIcon.ALeft"/>
<element name="TLCLTaskDialog.AddIcon.ATop"/>
<element name="TLCLTaskDialog.AddIcon.AGlobalLeftMargin"/>
<element name="TLCLTaskDialog.AddIcon.AParent"/>
<element name="TLCLTaskDialog.AddPanels"/>
<element name="TLCLTaskDialog.AddRadios"/>
<element name="TLCLTaskDialog.AddRadios.ARadioOffSet"/>
<element name="TLCLTaskDialog.AddRadios.AWidth"/>
<element name="TLCLTaskDialog.AddRadios.ARadioDef"/>
<element name="TLCLTaskDialog.AddRadios.AFontHeight"/>
<element name="TLCLTaskDialog.AddRadios.ALeft"/>
<element name="TLCLTaskDialog.AddRadios.ATop"/>
<element name="TLCLTaskDialog.AddRadios.AParent"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons.ALeft"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons.ATop"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons.AWidth"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons.AButtonDef"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons.AFontHeight"/>
<element name="TLCLTaskDialog.AddCommandLinkButtons.AParent"/>
<element name="TLCLTaskDialog.AddButtons"/>
<element name="TLCLTaskDialog.AddButtons.ALeft"/>
<element name="TLCLTaskDialog.AddButtons.ATop"/>
<element name="TLCLTaskDialog.AddButtons.AButtonLeft"/>
<element name="TLCLTaskDialog.AddButtons.AWidth"/>
<element name="TLCLTaskDialog.AddButtons.AButtonDef"/>
<element name="TLCLTaskDialog.AddButtons.AParent"/>
<element name="TLCLTaskDialog.AddCheckBox"/>
<element name="TLCLTaskDialog.AddCheckBox.ALeft"/>
<element name="TLCLTaskDialog.AddCheckBox.ATop"/>
<element name="TLCLTaskDialog.AddCheckBox.XB"/>
<element name="TLCLTaskDialog.AddCheckBox.AWidth"/>
<element name="TLCLTaskDialog.AddCheckBox.AParent"/>
<element name="TLCLTaskDialog.AddExpandButton"/>
<element name="TLCLTaskDialog.AddExpandButton.ALeft"/>
<element name="TLCLTaskDialog.AddExpandButton.ATop"/>
<element name="TLCLTaskDialog.AddExpandButton.XB"/>
<element name="TLCLTaskDialog.AddExpandButton.AWidth"/>
<element name="TLCLTaskDialog.AddExpandButton.AParent"/>
<element name="TLCLTaskDialog.AddFooter"/>
<element name="TLCLTaskDialog.AddFooter.ALeft"/>
<element name="TLCLTaskDialog.AddFooter.ATop"/>
<element name="TLCLTaskDialog.AddFooter.XB"/>
<element name="TLCLTaskDialog.AddFooter.AFontHeight"/>
<element name="TLCLTaskDialog.AddFooter.AWidth"/>
<element name="TLCLTaskDialog.AddFooter.AGlobalLeftMargin"/>
<element name="TLCLTaskDialog.AddFooter.AParent"/>
<element name="TLCLTaskDialog.AddLabel"/>
<element name="TLCLTaskDialog.AddLabel.Result"/>
<element name="TLCLTaskDialog.AddLabel.AText"/>
<element name="TLCLTaskDialog.AddLabel.BigFont"/>
<element name="TLCLTaskDialog.AddLabel.ALeft"/>
<element name="TLCLTaskDialog.AddLabel.ATop"/>
<element name="TLCLTaskDialog.AddLabel.AFontHeight"/>
<element name="TLCLTaskDialog.AddLabel.AWidth"/>
<element name="TLCLTaskDialog.AddLabel.AParent"/>
<element name="TLCLTaskDialog.AddQueryCombo"/>
<element name="TLCLTaskDialog.AddQueryCombo.ALeft"/>
<element name="TLCLTaskDialog.AddQueryCombo.ATop"/>
<element name="TLCLTaskDialog.AddQueryCombo.AWidth"/>
<element name="TLCLTaskDialog.AddQueryCombo.AParent"/>
<element name="TLCLTaskDialog.AddQueryEdit"/>
<element name="TLCLTaskDialog.AddQueryEdit.X"/>
<element name="TLCLTaskDialog.AddQueryEdit.Y"/>
<element name="TLCLTaskDialog.AddQueryEdit.AWidth"/>
<element name="TLCLTaskDialog.AddQueryEdit.AParent"/>
<element name="TLCLTaskDialog.SetupTimer"/>
<element name="TLCLTaskDialog.ResetTimer"/>
<element name="TLCLTaskDialog.ExpandDialog"/>
<element name="TLCLTaskDialog.CollapseDialog"/>
<element name="TLCLTaskDialog.DoDialogConstructed"/>
<element name="TLCLTaskDialog.DoDialogCreated"/>
<element name="TLCLTaskDialog.DoDialogDestroyed"/>
<!--
Naming schemes... choose one.
<element name="TLCLTaskDialog.ButtonClicked"/>
<element name="TLCLTaskDialog.ButtonClicked.Sender"/>
-->
<element name="TLCLTaskDialog.OnButtonClicked"/>
<element name="TLCLTaskDialog.OnButtonClicked.Sender"/>
<!--
<element name="TLCLTaskDialog.RadioButtonClick"/>
<element name="TLCLTaskDialog.RadioButtonClick.Sender"/>
-->
<element name="TLCLTaskDialog.OnRadioButtonClick"/>
<element name="TLCLTaskDialog.OnRadioButtonClick.Sender"/>
<!--
<element name="TLCLTaskDialog.VerifyClicked"/>
<element name="TLCLTaskDialog.VerifyClicked.Sender"/>
-->
<element name="TLCLTaskDialog.OnVerifyClicked"/>
<element name="TLCLTaskDialog.OnVerifyClicked.Sender"/>
<!--
<element name="TLCLTaskDialog.DoTimer"/>
<element name="TLCLTaskDialog.DoTimer.Sender"/>
-->
<element name="TLCLTaskDialog.OnTimer"/>
<element name="TLCLTaskDialog.OnTimer.Sender"/>
<element name="TLCLTaskDialog.OnExpandButtonClicked">
<short>
Implements the event handler signalled when the expand/collapse button (expando
control) has been clicked on the task dialog.
</short>
<descr>
<p>
<var>OnExpandButtonClicked</var> is a method method used to perform actions
needed when the expand/collapse button for the task dialog has been clicked. It
is assigned during form set-up to the OnClick event handler for the TButton
instance used on the form.
</p>
<p>
OnExpandButtonClicked ensures that the correct private method is called for the
button click; the current value in the expanded state is used to determine
whether expandable text is changed from expanded to collapsed, or vice versa.
It also sets the new value for the private expanded state member.
</p>
<p>
The DoOnExpandButtonClicked in the TTaskDialog instance for the dialog form is
called with the new value for the Expanded property.
</p>
</descr>
<version>
Added in LCL version 4.0.
</version>
<seealso>
<link id="#lcl.dialogs.TTaskDialog.Expanded">TTaskDialog.Expanded</link>
<link id="#lcl.dialogs.TTaskDialog.ExpandedText">TTaskDialog.ExpandedText</link>
<link id="#lcl.dialogs.TTaskDialog.DoOnExpandButtonClicked">TTaskDialog.DoOnExpandButtonClicked</link>
</seealso>
</element>
<element name="TLCLTaskDialog.OnExpandButtonClicked.Sender">
<short>
Not used in the method.
</short>
</element>
<element name="TLCLTaskDialog.DoOnHelp"/>
<!-- protected -->
<element name="TLCLTaskDialog.SetupControls">
<short>
Configures and initialize properties and controls used on the emulated task
dialog form.
</short>
<descr>
<p>
<var>SetupControls</var> is a method used to configure / initialize controls
on the emulated dialog form using the properties in the <var>TTaskDialog</var>
instance where the form is displayed. SetupControls performs actions needed to
set property values on the dialog form to match the settings and values on the
TTaskDialog instance. This includes:
</p>
<ul>
<li>
Default button in the Buttons property (when assigned).
</li>
<li>
Default radio button in the RadioButtons property (when assigned).
</li>
<li>
Dialog caption using the title from the main form or application when none is
assigned.
</li>
<li>
Dialog title using the default message for the associated main icon when a
value has not been assigned.
</li>
<li>
Values in the text, expanded text, and footer text properties.
</li>
<li>
Value for the expand / collapse button on the dialog.
</li>
<li>
Content in the Verification text.
</li>
<li>
Value for the Verification check-box.
</li>
<li>
Captions displayed next to the expand / collapse indicator (expando button).
</li>
<li>
Common buttons (and the default button) on the dialog form.
</li>
<li>
Applies value in Flags using the settings in the TTaskDialog instance. May
include setting the border icons when the dialog can be cancelled.
</li>
<li>
Sets the Position for the dialog form using flag values.
</li>
<li>
Uses the default system font on the dialog when emulating the classic style.
</li>
<li>
Calculates the width for the dialog form using values in the title, caption,
and buttons for the dialog. Size constraints are applied and the resulting
width is normally in the range 120..480 pixels.
</li>
</ul>
<p>
SetupControls creates and populates controls needed to display the various UI
elements enabled for the dialog form. It also calls SetupTimer to initialize
the timer used for progress bar display (when enabled in Flags).
</p>
<p>
Finally, the ActiveControl on the form is updated for the enabled controls on
the dialog.
</p>
<p>
SetupControls is called from the Execute method for the emulated task dialog.
</p>
</descr>
<seealso>
<link id="TLCLTaskDialog.Execute"/>
</seealso>
</element>
<!-- public -->
<element name="TLCLTaskDialog.KeyDown">
<short>
Implements the OnKeyDown event handler for the task dialog.
</short>
<descr>
<p>
<var>KeyDown</var> is an overridden method in <var>TLCLTaskDialog</var> which
implements the handler routine for OnKeyDown events in the dialog form.
KeyDown ensures that Esc, Alt+F4, and F1 key down events are applied properly
for the emulated task dialog.
</p>
<p>
When BorderIcons indicates that the dialog form can be closed (contains
biSystemMenu), the Esc (Escape) key can be used to close the dialog form by
calling the Close method. Without the system border icon, the Esc key is not
handled in the method.
</p>
<p>
When Key and Shift indicate that the Alt+F4 key was pressed, the value in Key
is digested (set to 0). The native task dialog blocks Alt+F4 to close the
dialog, so it is blocked in the emulated task dialog as well.
</p>
<p>
When Key indicates that F1 was pressed, the DoOnHelp method in the TTaskDialog
instance is called to signal an assigned OnHelp event handler in the task
dialog. The value in Key is set to 0 to consume the key event.
</p>
<p>
KeyDown calls the inherited method prior to exit.
</p>
</descr>
<seealso>
<link id="#lcl.forms.TForm.BorderIcons">TForm.BorderIcons</link>
<link id="#lcl.controls.TWinControl.KeyDown">TWinControl.KeyDown</link>
<link id="#lcl.controls.TWinControl.OnKeyDown">TWinControl.OnKeyDown</link>
<link id="#rtl.classes.TShiftState">TShiftState</link>
</seealso>
</element>
<element name="TLCLTaskDialog.KeyDown.Key">
<short>
Virtual key code examined in the method.
</short>
</element>
<element name="TLCLTaskDialog.KeyDown.Shift">
<short>
Shift, Control, or Alt modifier for the key.
</short>
</element>
<!-- TODO: Needs additional content. -->
<element name="TLCLTaskDialog.CreateNew">
<short>
Alternate constructor for the class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TLCLTaskDialog.CreateNew.AOwner">
<short>
Owner of the class instance.
</short>
</element>
<element name="TLCLTaskDialog.CreateNew.Num">
<short>
Instance sequence number for the new class instance. Included as a suffix in
the Name for the class.
</short>
</element>
<!-- TODO: Needs additional content. -->
<element name="TLCLTaskDialog.Destroy">
<short>
Destructor for the class instance.
</short>
<descr/>
<seealso/>
</element>
<!-- TODO: Needs additional content. -->
<element name="TLCLTaskDialog.AfterConstruction">
<short>
Performs actions needed when a new instance of the class has been created.
</short>
<descr/>
<seealso/>
</element>
<!-- TODO: Needs content. -->
<element name="TLCLTaskDialog.Execute">
<short/>
<descr/>
<seealso/>
</element>
<element name="TLCLTaskDialog.Execute.Result">
<short/>
</element>
<element name="TLCLTaskDialog.Execute.AParentWnd">
<short/>
</element>
<element name="TLCLTaskDialog.Execute.ARadioRes">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="TTaskDialogTranslate">
<short/>
<descr/>
<seealso/>
</element>
<element name="TTaskDialogTranslate.Result">
<short/>
</element>
<element name="TTaskDialogTranslate.AString">
<short/>
</element>
<element name="TaskDialog_Translate">
<short>
Variable with the function used to translate strings used on an emulated task
dialog instance.
</short>
<descr/>
<notes>
<note>
Comment in source code:
Do we really need this? We already use resource strings that can be translated
using translations unit.
</note>
</notes>
<seealso>
<link id="TTaskDialogTranslate"/>
</seealso>
</element>
<!-- TODO: Needs content. -->
<element name="ExecuteLCLTaskDialog">
<short/>
<descr/>
<seealso/>
</element>
<element name="ExecuteLCLTaskDialog.Result">
<short/>
</element>
<element name="ExecuteLCLTaskDialog.ADlg">
<short/>
</element>
<element name="ExecuteLCLTaskDialog.AParentWnd">
<short/>
</element>
<element name="ExecuteLCLTaskDialog.ARadioRes">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="TLCLTaskDialogIcon">
<short/>
<descr/>
<seealso/>
</element>
<element name="TLCLTaskDialogIcon.tiBlank">
<short/>
</element>
<element name="TLCLTaskDialogIcon.tiWarning">
<short/>
</element>
<element name="TLCLTaskDialogIcon.tiQuestion">
<short/>
</element>
<element name="TLCLTaskDialogIcon.tiError">
<short/>
</element>
<element name="TLCLTaskDialogIcon.tiInformation">
<short/>
</element>
<element name="TLCLTaskDialogIcon.tiNotUsed">
<short/>
</element>
<element name="TLCLTaskDialogIcon.tiShield">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="TLCLTaskDialogFooterIcon">
<short/>
<descr/>
<seealso/>
</element>
<element name="TLCLTaskDialogFooterIcon.tfiBlank">
<short/>
</element>
<element name="TLCLTaskDialogFooterIcon.tfiWarning">
<short/>
</element>
<element name="TLCLTaskDialogFooterIcon.tfiQuestion">
<short/>
</element>
<element name="TLCLTaskDialogFooterIcon.tfiError">
<short/>
</element>
<element name="TLCLTaskDialogFooterIcon.tfiInformation">
<short/>
</element>
<element name="TLCLTaskDialogFooterIcon.tfiShield">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="IconMessage">
<short/>
<descr/>
<seealso/>
</element>
<element name="IconMessage.Result">
<short/>
</element>
<element name="IconMessage.Icon">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="TF_DIALOGICON">
<short/>
<descr/>
<seealso/>
</element>
<element name="TF_DIALOGICON.Result">
<short/>
</element>
<element name="TF_DIALOGICON.AIcon">
<short/>
</element>
<!-- TODO: Needs content. -->
<element name="TF_FOOTERICON">
<short/>
<descr/>
<seealso/>
</element>
<element name="TF_FOOTERICON.Result">
<short/>
</element>
<element name="TF_FOOTERICON.AIcon">
<short/>
</element>
</module>
<!-- TaskDlgEmulation -->
</package>
</fpdoc-descriptions>