The "madNVAssistant" unit is used by madExcept to show thread safe
assistants to the end user. Each assistant consists of one or more forms,
which are shown until the end user either aborts one of the forms, or until
all steps/forms of the assistant are through.
A full list of what is contained in the whole unit can be found in the
madNVAssistant Reference.
The assistant is managed through an interfaced named "INVAssistant". The
only way to get an instance of such an interface is indirectly through the
IMESettings interface. The single most interesting method of the
"INVAssistant" interface is the "ShowModal" method:
|
type
INVAssistant = interface ['{14A3AFE4-B39F-4745-8F85-08FFABE8771C}'];
type
TNVModalResult = (nvmInvalid, nvmOk, nvmSkip, nvmCancel);
function INVAssistant.ShowModal (parentWindow: dword = 0) : TNVModalResult;
MESettings.GetAssistant('SomeAssistant').ShowModal;
|
|
There are some more properties, which are more or less interesting. E.g. you
can retrieve the exception interface, in case the assistant was created from
an exception context. Plus you can set and get a "Data" pointer, which you
can use for any purpose you like.
|
type
TNVAction = (nvaFormCreate, nvaFormShow, nvaFormClose, nvaItemEvent);
type
TNVActionHandler = procedure (form: INVForm; action: TNVAction; item: INVItem; exception: IMEException);
property INVAssistant.Title : string;
property INVAssistant.FormCount : integer;
property INVAssistant.Forms [index : integer] : INVForm;
property INVAssistant.Form [name : string ] : INVForm;
property INVAssistant.ModalResult : TNVModalResult;
property INVAssistant.OnAction : TNVActionHandler;
property INVAssistant.Exception : IUnknown;
property INVAssistant.Data : pointer;
|
|
Each step/form of an assistant is represented by an "INVForm" interface.
The only way to get an "INVForm" interface instance is indirectly through
either the INVAssistant interface or the TNVActionHandler
callback.
|
type
INVForm = interface ['{9C62303F-3C4A-4E2F-9C14-74C518871995}'];
|
|
The only situation where it makes sense for you to even touch the "INVForm"
interface is probably inside of an TNVActionHandler event. During
that event it might make sense for you to access the forms controls and to
do something with them.
You can either enumerate through all controls by using the "ItemCount" and
"Items" properties. Or you can directly access any controls by referencing
them via their type and name. Finally you can directly access the three
default main buttons that belong to each form.
|
property INVForm.ItemCount : integer;
property INVForm.Items [index: integer] : INVItem;
for i1 := 0 to form.ItemCount - 1 do
form.Items[i1].Enabled := false;
function INVForm.nvEdit (item: string) : INVEdit;
function INVForm.nvLabel (item: string) : INVLabel;
function INVForm.nvButton (item: string) : INVButton;
function INVForm.nvCheckBox (item: string) : INVCheckBox;
function INVForm.nvImage (item: string) : INVImage;
property INVForm.ContinueButton : INVButton;
property INVForm.SkipButton : INVButton;
property INVForm.CancelButton : INVButton;
form.ContinueButton.Enabled := form.nvEdit('NameEdit').Text <> '';
|
|
As with the INVAssistant interface, the "INVForm" interface also has
some more properties, which will probably be less exciting to you. Here's a
list just for the sake of completeness:
|
property INVForm.Assistant : INVAssistant;
property INVForm.Name : string;
property INVForm.Title : string;
property INVForm.Message : string;
property INVForm.Handle : dword;
property INVForm.Timer : dword;
property INVForm.ModalResult : TNVModalResult;
property INVForm.ActiveControl : string;
property INVForm.OnAction : TNVActionHandler;
property INVForm.Exception : IUnknown;
property INVForm.Data : pointer;
|
|
The controls are all descendants of the basic "INVItem" interface and thus
share some general properties & methods, e.g. the control "Name" and the
"Enabled" state.
|
type
INVItem = interface ['{36EE4E77-B6B3-41D0-ABA7-3D9B90847EC0}'];
property INVItem.Name : string;
property INVItem.Handle : dword;
property INVItem.TabStop : boolean;
property INVUtem.Spacing : integer;
property INVItem.Enabled : boolean;
procedure INVItem.SetFocus;
|
|
The label control is fairly easy. It only adds the property "Caption" to the
INVItem basic interface.
|
type
INVLabel = interface (INVItem) ['{EA968486-7DA2-486F-9D40-DE0B7BDECBEC}'];
property INVLabel.Caption : string;
|
|
For button controls you can specify a "MinWidth". If the button "Caption"
needs more space than you entered in "MinWidth", the real width is auto
adjusted to the width needed to draw the full "Caption".
|
type
INVButton = interface (INVItem) ['{20E07644-4788-4FDF-8F90-B62C0E61E20B}'];
property INVButton.Caption : string;
property INVButton.MinWidth : integer;
|
|
The check box control is slightly more complex. It has a "Caption" and a
"Checked" property, just like the VCL check box component. Additionally it
has a property named "OutputName". If you write a name in here, the check
box value (that is "yes" or "no") is added to the bug report header under
the name specified by "OutputName". If you leave the field empty, the check
box value is not added to the bug report header.
|
type
INVCheckBox = interface (INVItem) ['{34E76977-C2B5-4819-B8F6-B6170089A03C}'];
property INVCheckBox.Caption : string;
property INVCheckBox.Checked : boolean;
property INVCheckBox.OutputName : string;
|
|
The edit control can behave as either an edit box or a memo field, depending
on how the "Lines" property is set. If "Lines" is greater than 1, we have a
memo control. The property "Optional" defines whether the user must fill
this edit/memo control before he may forward to the next assistant step. If
"Optional" is false, the continue button is automatically disabled, as
long as the edit/memo control contains no text or invalid text. You can
specify whether an edit control has valid content by settings the "Valid"
property. It makes sense to do that in an INVForm.OnAction event
handler. If the "Colored" property is true, the edit/memo field is colored
in green or red, depending on whether the content is valid. Otherwise it is
colored black.
If the "OutputName" property
is filled, the edit/memo text is written to the bug report. Depending on how
"OutputType" is set, the edit/memo text is either added to the bug report
header, or stored into a seperate bug report section.
|
type
INVEdit = interface (INVItem) ['{22AC205D-0FED-425B-BEBB-9FBAB850C1DC}'];
property INVEdit.Lines : integer;
property INVEdit.Optional : boolean;
property INVEdit.Text : string;
property INVEdit.Colored : boolean;
property INVEdit.Valid : boolean;
type
TOutputType = (otHeader, otOwnSection);
property INVEdit.OutputName : string;
property INVEdit.OutputType : TOutputType;
|
|
The image control can load an image "File_" from harddisk, or you can
manually fill the image by writing to the "Bitmap" property. If you specify
the "Width" and "Height" properties at design time, the image is zoomed (if
necessary) to fit your wishes. When zooming the aspect ratio of the image
is maintained, though. So if you specify e.g. a "Width" and "Height" of e.g.
200 pixels each and then enter a bitmap with 800x600 pixels, the final
size of the image will be 200x150 pixels. If you leave "Width" and "Height"
empty at design time, the optimal size of the image is auto calculated.
|
type
INVImage = interface (INVItem) ['{A0DE7AC1-F790-4BDB-B6B2-453AF25A6B7B}'];
property INVImage.File_ : string;
property INVImage.Bitmap : INVBitmap;
property INVImage.Clickable : boolean;
property INVImage.Border : boolean;
property INVImage.Width : integer;
property INVImage.Height : integer;
|
|