Declaration
procedure SetGaugeHook( HwndGauge: HWnd );
Description
Defines a window that time consuming operations may communicate with in order to inform the user as to the progress of the operation.
This method is not supported under remote tables using Apollo Database Server. Progress for remote table operations is tracked using the TApolloConnection.OnServerProgress event.
The following methods can utilize SetGaugeHook:
• CopyFile
• Pack
• Index
• IndexTag
• Reindex
With the Apollo 4.0 release, as part of thread-safe support, the SetGaugeHook method is no longer a global hook as it was in prior Apollo releases. Therefore, if you are dealing with multiple TApolloTable objects, you must now call TApolloTable.SetGaugeHook for each table object that you wish to track processes for.
Parameters
HwndGauge: The window handle of an edit control that is to receive messages from the sending operation.
If the window handle is valid (i.e., the window exists), a KeyDown event is fired for the defined window whenever the completion percentage of the operation changes.
The KeyCode parameter passed to the KeyDown event contains the percentage complete as a negative number instead of a key value. This allows the programmer to distinguish between normal key events and the gauge hook events.
If the operation using the gauge hook is working on a single file (e.g., Index), the percentage passed is an absolute measure of the progress of the procedure.
If the operation is one in which a number of files are involved (e.g., Pack, Reindex), you must invent an algorithm to process successive percentages as a ratio of all of the files taking part in the procedure.
For example, if packing a file that has two active indexes (or tags) and a memo file, the window receiving the gauge hook messages will receive percentages of 1 to 100 four times (for the dbf, the 2 indexes, and the memo file). Before displaying the percentage or setting your gauge, you must therefore divide the absolute value of the percentage received from the hook by 4 (the number of files) before displaying it.
Delphi Example
procedure Form1.Button1Click(Sender: TObject);
begin
with ApTbl do
begin
Open;
IndexOpen( 'c:\Apollo\Data\sxcust1.ntx' );
Gauge1.Visible := True;
SetGaugeHook( Form1.Handle );
Reindex;
Gauge1.Visible := False;
SetGaugeHook( 0 );
Close;
end;
end;
// In Form1's OnKeyDown event, add the following code
procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word; Shift: TShiftState);
var
wVal : Word;
begin
if (Key and $7000) <> 0 then
begin
wVal := -SmallInt( Key );
Gauge1.Progress := wVal;
Application.ProcessMessages;
Key := 0;
end;
end;
C++Builder Example
void __fastcall TForm1::Button1Click(TObject * Sender)
{
Screen->Cursor = crHourGlass;
ProgressBar1->Visible = true;
ApTbl->SetGaugeHook( int( Form1->Handle ));
ApTbl->IndexTag( "", "NAME", "UPPER(LAST+FIRST)", IDX_NONE, false, "" );
ApTbl->SetGaugeHook( 0 );
ProgressBar1->Visible = false;
Screen->Cursor = crDefault;
}
// In Form1's OnKeyDown event, add the following code
void __fastcall TForm1::FormKeyDown(TObject * Sender, int *Key, TShiftState * Shift)
{
WORD wVal;
if ((Key && 0x7000) != 0)
{
wVal = -Char(Key);
ProgressBar1->Position = wVal;
Key = 0;
}
}
See Also
TApolloConnection.OnServerProgress, AppendFrom, CopyFile, DbfDecrypt, DbfEncrypt, Pack, Index, IndexTag, Reindex