Copyright: Delphi v.2.0 Copyright 1982-1996, Borland International. Inc.


Abort procedure

Exception handling routines

Unit

SysUtils

Declaration

procedure Abort;

Description

The Abort procedure raises a special "silent exception" which operates like any other exception, but does not display an error message to the end user.

Use Abort to escape from an execution path without reporting an error.


Abs function

Example	Arithmetic Routines

Unit

System

Declaration

function Abs(X);

Description

The Abs function returns the absolute value of the argument.

X is an integer-type or real-type expression.


Example

var

  r: Real;

  i: Integer;

begin

  r := Abs(-2.3);	{ 2.3 }

  i := Abs(-157);	{ 157 }

end;


AddExitProc procedure

Miscellaneous Routines

Unit

SysUtils

Declaration

procedure AddExitProc(Proc: TProcedure);

Description

AddExitProc adds the given procedure to the run-time library's exit procedure list. When an application terminates, its exit procedures are executed in reverse order of definition, i.e. the last procedure passed to AddExitProc is the first one to get executed upon termination.


Addr function

Example

Unit

System

Declaration

function Addr(X): Pointer;

Description

The Addr function returns the address of a specified object.

X is any variable, procedure or function identifier. The result is a pointer to X.

The result of Addr is of the predefined type Pointer, which means that it is assignment-compatible with all pointer types but can't be dereferenced directly without a typecast.


Example

var

  P: Pointer;

begin

  P := Addr(P);	{ Now points to itself }

end;


AdjustLineBreaks function

See Also

Unit

SysUtils

Declaration

function AdjustLinesBreaks(const S: string): string;

Description

The AdjustLinesBreaks function adjusts all line breaks in the given string S to be true CR/LF sequences. The function changes any CR characters not followed by a LF and any LF characters not preceded by a CR into CR/LF pairs. It also converts LF/CR pairs to CR/LF pairs. The LF/CR pair is common in Unix text files.


See Also

TrimLeft function

TrimRight function


AllocMem function

See also	Memory management routines

Unit

SysUtils

Declaration

function AllocMem(Size: Cardinal): Pointer;

Description

AllocMem allocates a block of the given size on the heap. Each byte in the allocated buffer is set to zero. To dispose the buffer, use the FreeMem standard procedure.


See also

ReAllocMem function


AnsiCompareStr function

See also	String formatting routines

Unit

SysUtils

Declaration

function AnsiCompareStr(const S1, S2: string): Integer;

Description

AnsiCompareStr compares S1 to S2, with case sensitivity. The compare operation is controlled by the currently installed language driver. The return value is:

Condition	Return Value

S1 > S2	> 0

S1 < S2	.< 0

S1 = S2	= 0


See also

AnsiCompareText function


AnsiCompareText function

See also	String formatting routines

Unit

SysUtils

Declaration

function AnsiCompareText(const S1, S2: string): Integer;

Description

AnsiCompareText compares S1 to S2, without case sensitivity. The compare operation is controlled by the currently installed language driver. The return value is the same as for CompareStr.


See also

AnsiCompareStr function


AnsiLowerCase function

See also	String formatting routines

Unit

SysUtils

Declaration

function AnsiLowerCase(const S: string): string;

Description

AnsiLowerCase converts all characters in the given string to lower case. The conversion uses the currently installed language driver.


See also

AnsiUpperCase function

LowerCase function


AnsiUpperCase function

See also	String formatting routines

Unit

SysUtils

Declaration

function AnsiUpperCase(const S: string): string;

Description

AnsiUpperCase converts all characters in the given string to upper case. The conversion uses the currently installed language driver.


See also

AnsiLowerCase function

UpperCase function


Append procedure

See also	Example	String formatting routines

Unit

System

Declaration

procedure Append(var f: Text);

Description

The Append procedure opens an existing file with the name assigned to F, so that new text can be added.

F is a text file variable and must be associated with an external file using AssignFile.

If no external file of the given name exists, an error occurs.

If F is already open, it is closed, then reopened. The current file position is set to the end of the file.

If a Ctrl+Z (ASCII 26) is present in the last 128-byte block of the file, the current file position is set so that the next character added to the file overwrites the first Ctrl+Z in the block. In this way, text can be appended to a file that terminates with a Ctrl+Z.

If F was not assigned a name, then, after the call to Append, F refers to the standard output file.

After calling Append, F is write-only, and the file pointer is at the end of the file.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var F: TextFile;

begin

  if OpenDialog1.Execute then	{ Bring up open file dialog }

  begin

    AssignFile(F, OpenDialog1.FileName);	{ Open file selected in dialog }

    Append(F);	{ Add more text onto end }

    Writeln(F, 'appended text');

    CloseFile(F);	{ Close file, save changes }

  end;

end;


See also

AssignFile procedure

FileClose procedure

Reset procedure

Rewrite procedure


ArcTan function

See also	Example	Arithmetic routines

Unit

System

Declaration

function ArcTan(X: Extended): Extended;

Description

The ArcTan function returns the resulting arctangent of the argument.

You can calculate other trigonometric functions using Sin, Cos, and ArcTan in the following expressions:

Tan(x) = Sin(x) / Cos(x)

ArcSin(x) = ArcTan (x/sqrt (1-sqr (x)))

ArcCos(x) = ArcTan (sqrt (1-sqr (x)) /x)


Example

var
  R: Extended;

begin

  R := ArcTan(Pi);

end;


See also

Cos function

Sin function


Assigned function

See also	Example	Pointer and Address Routines

Unit

System

Declaration

function Assigned(var P): Boolean;

Description

The Assigned function tests if a pointer or procedural variable is nil (unassigned).

P must be a variable reference of a pointer or procedural type. Assigned(P) corresponds to the test P<> nil for a pointer variable, and @P <> nil for a procedural variable.

Assigned returns False if P is nil, True otherwise.

Note:	Assigned can't detect a "stale" pointer--that is, one that isn't nil but no longer points to valid data. For example, in the code example for Assigned, Assigned won't detect the fact that P isn't valid.


Example

var P: Pointer;

begin

  P := nil;

  if Assigned (P) then Writeln ('You won''t see this');

  GetMem(P, 1024);	{P valid}

  FreeMem(P, 1024);	{P no longer valid and still not nil}

  if Assigned (P) then Writeln ('You''ll see this');

end;


See Also

nil


AssignFile procedure

See also	Example	I/O routines

Unit

System

Declaration

procedure AssignFile(var F; FileName: string);

To avoid scope conflicts, AssignFile replaces Assign in Delphi. However, for backward compatibility you can still use Assign.

The AssignFile procedure associates the name of an external file with a file variable.

F is a file variable of any file type, and FileName is a string-type expression or an expression of type PChar if extended syntax is enabled. All further operations on F operate on the external file name.

After calling AssignFile, F is associated with the external file until F is closed.

When the FileName parameter is empty, F associates with the standard input or standard output file.

If assigned an empty name, after a call to Reset (F), F refers to the standard input file, and after a call to Rewrite (F), F refers to the standard output file.

Do not use AssignFile on a file variable that is already open.


Example

var

  F: TextFile;

  S: string;

begin

  if OpenDialog1.Execute then          { Display Open dialog box }

  begin

    AssignFile(F, OpenDialog1.FileName);   { File selected in dialog box }

    Reset(F);

    Readln(F, S);                          { Read the first line out of the file }

    Edit1.Text := S;                       { Put string in a TEdit control }

    CloseFile(F);

  end;

end;


See also

Append procedure

CloseFile procedure

Reset procedure

Rewrite procedure


Beep procedure

Unit

SysUtils

Declaration

procedure Beep;

Description

The Beep procedure calls the Windows API MessageBeep with a parameter of zero.


BlockRead procedure

See also	Example	Untyped-file routines

Unit

System

Declaration

procedure BlockRead(var F: File; var Buf; Count: Integer [; var Result: Integer]);

Description

The BlockRead procedure reads one or more records from an open file into a variable.

F is an untyped file variable, Buf is any variable, Count is an expression of type Integer, and Result is an optional variable of type Integer.

BlockRead reads Count or fewer records from the file F into memory, starting at the first byte occupied by Buf. The actual number of complete records read (less than or equal to Count) is returned in Result.

The entire transferred block occupies at most Count * RecSize bytes. RecSize is the record size specified when the file was opened (or 128 if the record size was not specified).

If the entire block was transferred, Result is equal to Count.

If Result is less than Count, ReadBlock reached the end of the file before the transfer was complete. If the file's record size is greater than 1, Result returns the number of complete records read.

If Result isn't specified, an I/O error occurs if the number of records read isn't equal to Count. You can use the EInOutError exception to handle this error.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

  FromF, ToF: file;

  NumRead, NumWritten: Integer;

  Buf: array[1..2048] of Char;

begin

  if OpenDialog1.Execute then                               { Display Open dialog box }

  begin

    AssignFile(FromF, OpenDialog1.FileName);

    Reset(FromF, 1);	{ Record size = 1 }

    if SaveDialog1.Execute then                              { Display Save dialog box}

    begin

      AssignFile(ToF, SaveDialog1.FileName);	{ Open output file }

      Rewrite(ToF, 1);	{ Record size = 1 }

      Canvas.TextOut(10, 10, 'Copying ' + IntToStr(FileSize(FromF))

        + ' bytes...');

      repeat

        BlockRead(FromF, Buf, SizeOf(Buf), NumRead);

        BlockWrite(ToF, Buf, NumRead, NumWritten);

      until (NumRead = 0) or (NumWritten <> NumRead);

        CloseFile(FromF);

        CloseFile(ToF);

    end;

  end;

end;


See also

BlockWrite procedure

TFileStream object


BlockWrite procedure

See also	Example	Untyped-file routines

Unit

System

Declaration

procedure BlockWrite(var f: File; var Buf; Count: Integer [; var Result: Integer]);

Description

The BlockWrite procedure writes one or more records from a variable to an open file.

F is an untyped file variable, Buf is any variable, Count is an expression of type Integer, and Result is an optional variable of type Integer.

BlockWrite writes Count or fewer records to the file F from memory, starting at the first byte occupied by Buf. The actual number of complete records written (less than or equal to Count) is returned in Result.

The entire block transferred occupies at most Count * RecSize bytes. RecSize is the record size specified when the file was opened (or 128 if the record size was unspecified).

If the entire block is transferred, Result is equal to Count on return.

If Result is less than Count, the disk became full before the transfer was complete. In this case, if the file's record size is greater than 1, Result returns the number of complete records written.

The current file position is advanced by Result records as an effect of the BlockWrite.

If Result isn't specified, an I/O error occurs if the number written isn't equal to Count. You can use exception handler EInOutError to deal this error.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

  FromF, ToF: file;

  NumRead, NumWritten: Integer;

  Buf: array[1..2048] of Char;

begin

  if OpenDialog1.Execute then                               { Display Open dialog box }

  begin

    AssignFile(FromF, OpenDialog1.FileName);

    Reset(FromF, 1);	{ Record size = 1 }

    if SaveDialog1.Execute then                            { Display Save dialog box }

    begin

      AssignFile(ToF, SaveDialog1.FileName);	{ Open output file }

      Rewrite(ToF, 1);	{ Record size = 1 }

      Canvas.TextOut(10, 10, 'Copying ' + IntToStr(FileSize(FromF))

        + ' bytes...');

      repeat

        BlockRead(FromF, Buf, SizeOf(Buf), NumRead);

        BlockWrite(ToF, Buf, NumRead, NumWritten);

      until (NumRead = 0) or (NumWritten <> NumRead);

        CloseFile(FromF);

        CloseFile(ToF);

    end;

  end;

end;


See als

BlockRead procedure

TFileStream object


Break procedure

See also	Example	Flow-control routines

Unit

System

Declaration

procedure Break;

Description

The Break procedure causes the flow of control to exit a for, while, or repeat statement and continue at the next statement following the loop statement.

If you use a call to Break, it must be contained in a for, while, or repeat statement, or the compiler reports an error.

Note:	Break will go into any finally blocks between it and the loop exit. For more information on handling run-time library exceptions, see Handling RTL Exceptions.


Example

var

  S: string;

begin

  while True do

  begin

    ReadLn(S);

    try

      if S = '' then Break;

      WriteLn(S);

    finally

    { do something for all cases }

    end;

  end;

end;


See also

Continue procedure

Exit procedure

Halt procedure


ChangeFileExt function

Example	File management routines

Unit

SysUtils

Declaration

function ChangeFileExt(const FileName, Extension: string): string;

Description

The ChangeFileExt function takes the file name passed in FileName and changes the extension of the file name to the extension passed in Extension.


Example

The following code generates the name of an .INI file based on the name of the program:

function INIFileName: string;

begin

  Result := ChangeFileExt(ParamStr(0), '.INI');

end;


ChDir procedure

See also	Example

Unit

System

Declaration

procedure ChDir(S: string);

Description

The ChDir procedure changes the current directory to the path specified by S.
If S specifies a drive letter, the current drive is also changed.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors. IOResult returns 0 if the operation was successful; otherwise, it returns a nonzero error code.


Example

begin

  {$I-}

  { Change to directory specified in Edit1 }

  ChDir(Edit1.Text);

  if IOResult <> 0 then

    MessageDlg('Cannot find directory', mtWarning, [mbOk], 0);

end;


See also

GetDir procedure

MkDir procedure

RmDir procedure


Chr function

See also	Example	Transfer routines

Unit

System

Declaration

function Chr(X: Byte): Char;

Description

The Chr function returns the character with the ordinal value (ASCII value) of the byte-type expression, X.


Example

begin

  Canvas.TextOut(10, 10, Chr(65));  { The letter 'A'}

end;


See also

Ord function


Close procedure

See also	Example	I/O routines

Unit

System

Declaration

procedure Close(var F);

Description

The Close procedure provides compatibility with existing Borland Pascal code. When writing applications for Delphi, you should use CloseFile.

The Close procedure terminates the association between the file variable and an external disk file.

F is a file variable of any file type opened using Reset, Rewrite, or Append. The external file associated with F is completely updated and then closed, freeing the file handle for reuse.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


See also

Append procedure

AssignFile procedure

Reset procedure

Rewrite procedure


CloseFile procedure

See also	Example	I/O routines

Unit

System

Declaration

procedure CloseFile(var F);

Description

Due to naming conflicts, the CloseFile procedure replaces the Borland Pascal Close procedure. Use the CloseFile procedure instead of Close to terminate the association between the file variable and an external disk file.

F is a file variable of any file type opened using Reset, Rewrite, or Append. The external file associated with F is completely updated and then closed, freeing the file handle for reuse.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

  F: TextFile;

begin

  if OpenDialog1.Execute then  { Bring up open file dialog }

  begin

    AssignFile(F, OpenDialog1.FileName);

            { File selected in dialog }

    Reset(F);

    Edit1.Text := IntToStr(FileSize(F);

        { Put file size string in a TEdit control }

    CloseFile(F);   { Close file }

  end;

end;


CmdLine variable

See also

Unit

System

Declaration

var CmdLine: PChar;

Description

In a program, the CmdLine variable contains a pointer to a null-terminated string that contains the command-line arguments specified when the application was started. It is recommended that you use ParamStr to access individual arguments.

In a library (DLL), CmdLine is nil.


See also

ParamStr function


CmdShow variable

See also

Unit

System

Declaration

var CmdShow: Integer;

Description

In a program, the CmdShow variable contains the parameter value that Windows expects to be passed to ShowWindow when the application creates its main window.

In a library (DLL), CmdShow is always zero.


See also

ShowWindow WinAPI.


CompareStr function

See also	Example	String-handing routines (Object Pascal style)

Unit

SysUtils

Declaration

function CompareStr(const S1, S2: string): Integer;

Description

CompareStr compares S1 to S2, with case-sensitivity. The return value is less than 0 if S1 is less than S2, 0 if S1 equals S2, or greater than 0 if S1 is greater than S2. The compare operation is based on the 8-bit ordinal value of each character and is not affected by the currently installed language driver.


Example

The following code compares String1, 'STEVE', to String2, 'STEVe'. Note that CompareStr returns a number less than 0 because the value of 'e' is greater than the value of 'E'.

var

  String1, String2 : string;

  I : integer;

begin

  String1 := 'STEVE';

  String2 := 'STEVe';

  I := CompareStr(String1, String2);  { the value of I is < 0 }

  if I < 0 then

    MessageDlg('The strings are not equal', mtWarning, [mbOK], 0)

end;

See also

CompareText function


CompareText function

See also	Example	String-handing routines (Object Pascal style)

Unit

SysUtils

Declaration

function CompareText(const S1, S2: string): Integer;

Description

The CompareText function compares the strings S1 and S2 and returns 0 if they are equal. If S1 is greater than S2, CompareText returns an integer greater than 0. If S1 is less than S2, CompareText returns an integer less than 0. The CompareText function is not case sensitive. For example, CompareText finds 'object pascal' and 'Object Pascal' to be equal.


Example

The following code compares String1, 'ABC, to String2, 'aaa'. Because CompareText is case insensitive, String2 is larger.

var

  String1, String2 : string;

  I : integer;

begin

  String1 := 'ABC';

  String2 := 'aaa';

  I := CompareStr(String1, String2);  { the value of I is < 0 }

  if I < 0 then

    MessageDlg('The strings are not equal', mtWarning, [mbOK], 0)

end;


See also

CompareStr function


Concat function

See also	Example	String-handing routines (Object Pascal style)

Unit

System

Declaration

function Concat(s1 [, s2,..., sn]: string): string;

Description

The Concat function merges two or more strings into one large string.

Each parameter is a string-type expression. The result is the concatenation of all the string parameters.

Using the plus (+) operator has the same effect on two strings as using the Concat function:

S := 'ABC' + 'DEF';


Example

 var

  S: string;

begin

  S := Concat('ABC', 'DEF');     { 'ABCDE' }

end;

See also

Copy function

Delete procedure

Insert procedure

Length function

Pos function


Continue procedure

See also	Example	Flow-control routines

Unit

System

Declaration

procedure Continue;

Description

The Continue procedure has the flow of control proceed to the next iteration of the calling for, while, or repeat statement.

The compiler reports an error if a call to Continue isn't enclosed by a for, while, or repeat statement.

Note:	Continue will go into any finally blocks between it and the loop exit. For more information on handling run-time library exceptions, see Handling RTL Exceptions.


Example

var

  F: File;

  i: integer;

begin

  for i := 0 to (FileListBox1.Items.Count - 1) do begin

  try

    if FileListBox1.Selected[i] then begin

      if not FileExists(FileListBox1.Items.Strings[i]) then begin

        MessageDlg('File: ' + FileListBox1.Items.Strings[i] +

                   ' not found', mtError, [mbOk], 0);

        Continue;

      end;

      AssignFile(F, FileListBox1.Items.Strings[i]);

      Reset(F, 1);

      ListBox1.Items.Add(IntToStr(FileSize(F)));

      CloseFile(F);

    end;

   finally

   { do something here }

   end;

  end;

end;

See also

Break procedure

Exit procedure

Halt procedure


Copy function

See also	Example	String-handing routines (Object Pascal style)

Unit

System

Declaration

function Copy(S: string; Index, Count: Integer): string;

Description

The Copy function returns a substring of a string.

S is a string-type expression. Index and Count are integer-type expressions. Copy returns a string containing Count characters starting with at S[Index].

If Index is larger than the length of S, Copy returns an empty string.

If Count specifies more characters than are available, the only the characters from S[Index] to the end of S are returned.


Example

 var S: string;

begin

  S := 'ABCDEF';

  S := Copy(S, 2, 3);	{ 'BCD' }

end;

See also

Concat function

Delete procedure

Insert procedure

Length function

Pos function


Cos function

See also	Example	Arithmetic routines

Unit

System

Declaration

function Cos(X: Extended): Extended;

Description

The Cos function returns the cosine of the angle X, in radians.


Example

 var R: Extended;

begin

  R := Cos(Pi);

end;


See also

ArcTan function

Sin function


CreateDir function

See Also

Unit

SysUtils

Declaration

function CreateDir(const Dir: string): Boolean;

Description

The CreateDir function creates a new directory. The return value is True if a new directory was successfully created, or False if an error occurred.


See Also

ExtractFileDir function

GetCurrentDir function

RemoveDir function

SetCurrentDir function


Currency and date/time formatting variables

See also	Example

Unit

SysUtils

Declaration

CurrencyString: string;

CurrencyFormat: Byte;

NegCurrFormat: Byte;

ThousandSeparator: Char;

DecimalSeparator: Char;

CurrencyDecimals: Byte;

DateSeparator: Char;

ShortDateFormat: string;

LongDateFormat: string;

TimeSeparator: Char;

TimeAMString: string;

TimePMString: string;

ShortTimeFormat: string;

LongTimeFormat: string;

ShortMonthNames: array[1..12] of string;

LongMonthNames: array[1..12] of string;

ShortDayNames: array[1..7] of string;

LongDayNames: array[1..7] of string;

Description

The SysUtils unit includes a number of variables that are used by the date and time routines. You can assign new values to these variables to change the formats of date and time strings. The initial values of these variables are fetched from the system registry using the GetLocaleInfo function in the Win32 API. Delphi VCL (non-console) applications will automatically update these formatting variables in response to WM_WININICHANGE messages. Application.UpdateFormatSettings will either allow or not allow changes in system settings. The default is True. Set this property to False to prevent the system settings from changing.

The description of each variable specifies the LOCALE_XXXX constant used to fetch the initial value using the GetLocaleInfo Win32 API.

Typed constant	Defines

CurrencyString	CurrencyString defines the currency symbol (or characters) used in floating-point to decimal conversions. The initial value is fetched from LOCALE_SCURRENCY.

CurrencyFormat	CurrencyFormat defines the currency symbol placement and separation used in floating-point to decimal conversions. Possible values are:0 = '$1'1 = '1$'2 = '$ 1'3 = '1 $'The initial value is fetched from LOCALE_ICURRENCY.

NegCurrFormat	NegCurrFormat defines the currency format used in floating-point to decimal conversions of negative numbers. Possible values are:0 = ($1)    4 = (1$)    8 = -1 $    12 = $ -11 = -$1     5 = -1$     9 = -$ 1    13 = 1- $2 = $-1     6 = 1-$    10 = 1 $-    14 = ($ 1)3 = $1-     7 = 1$-    11 = $ 1-    15 = (1 $)The initial value is fetched from LOCALE_INEGCURR.

ThousandSeparator	ThousandSeparator is the character used to separate thousands in numbers with more than three digits to the left of the decimal separator. The initial value is fetched from LOCALE_STHOUSAND.

DecimalSeparator	DecimalSeparator is the character used to separate the integer part from the fractional part of a number. The initial value is fetched from LOCALE_SDECIMAL.

CurrencyDecimals	CurrencyDecimals is the number of digits to the right of the decimal point in a currency amount. The initial value is fetched from LOCALE_ICURRDIGITS.

DateSeparator	DateSeparator is the character used to separate the year, month, and day parts of a date value. The initial value is fetched from LOCATE_SDATE.

ShortDateFormat	ShortDateFormat is the format string used to convert a date value to a short string suitable for editing. For a complete description of date and time format strings, refer to the documentation for the FormatDateTime function. The short date format should only use the date separator character and the  m, mm, d, dd, yy, and yyyy format specifiers. The initial value is fetched from LOCALE_SSHORTDATE..

LongDateFormat	LongDateFormat is the format string used to convert a date value to a long string suitable for display but not for editing. For a complete description of date and time format strings, refer to the documentation for the FormatDateTime function. The initial value is fetched from LOCALE_SLONGDATE.

TimeSeparator	TimeSeparator is the character used to separate the hour, minute, and second parts of a time value. The initial value is fetched from LOCALE_STIME.

TimeAMString	TimeAMString is the suffix string used for time values between 00:00 and 11:59 in 12-hour clock format. The initial value is fetched from LOCALE_S1159.

TimePMString	TimePMString is the suffix string used for time values between 12:00 and 23:59 in 12-hour clock format. The initial value is fetched from LOCALE_S2359.

ShortTimeFormat	ShortTimeFormat is the format string used to convert a time value to a short string with only hours and minutes. The default value is computed from LOCALE_ITIME and LOCALE_ITLZERO.

LongTimeFormat	LongTimeFormat is the format string used to convert a time value to a long string with hours, minutes, and seconds. The default value is computed from LOCALE_ITIME and LOCALE_ITLZERO.

ShortMonthNames	ShortMonthNames is the array of strings containing short month names. The mmm format specifier in a format string passed to FormatDateTime causes a short month name to be substituted. The default values are fecthed from the LOCALE_SABBREVMONTHNAME system locale entries.

LongMonthNames	LongMonthNames is the array of strings containing long month names. The mmmm format specifier in a format string passed to FormatDateTime causes a long month name to be substituted. The default values are fecthed from the LOCALE_SMONTHNAME system locale entries.

ShortDayNames	ShortDayNames is the array of strings containing short day names. The ddd format specifier in a format string passed to FormatDateTime causes a short day name to be substituted. The default values are fecthed from the LOCALE_SABBREVDAYNAME system locale entries.

LongDayNames	LongDayNames is the array of strings containing long day names. The dddd format specifier in a format string passed to FormatDateTime causes a long day name to be substituted. The default values are fecthed from the LOCALE_SDAYNAME system locale entries.


Example

This example uses a label and a button on a form. When the user clicks the button, the current date displays in the caption of the label. Because some of the date variables are assigned new values, the format of the date in the label changes. For example, if the date is 9/15/94, the date displays as 15-09-1994.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DateOrder := doDMY;

  DateSeparator := '-';

  DateFullYear := True;

  DateLeadZero := True;

  Label1.Caption := DateToStr(Date);

end;


See Also

Date and Time Routines

TDateTime


Date function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function Date: TDateTime;

Description

The Date function returns the current date.


Example

This example uses a label and a button on a form. When the user clicks the button, the current date is displayed in the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := 'Today is  ' + DateToStr(Date);

end;


See also

Date and Time Typed Constants

 DateToStr function

DayOfWeek function

DecodeDate procedure

Now function

Time function


DateTimeToFileDate function

See Also	Date/Time Routines

Unit

SysUtils

Declaration

function DateTimeToFileDate(DateTime: TDateTime): Integer;

Description

DateTimeToFileDate converts a TDateTime value to a DOS date-and-time value. The FileAge, FileGetDate, and FileSetDate routines operate on DOS date-and-time values, and the Time field of a TSearchRec used by the FindFirst and FindNext functions contains a DOS date-and-time value.


See also

FileDateToDateTime function


DateTimeToStr function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function DateTimeToStr(DateTime: TDateTime): string;

Description

The DateTimeToStr function converts a variable of type TDateTime to a string. If DateTime parameter does not contain a date value, the date displays as 00/00/00. If the DateTime parameter does not contain a time value, the time displays as 00:00:00 AM. You can change how the string is formatted by changing some of the date and time typed constants.


Example

This example uses a label and a button on a form. When the user clicks the button, the current date and time is converted to a string and displayed as the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := DateTimeToStr(Now);

end;


See also

Date function

DateToStr function

Now function

StrToDate function

Time function

TimeToStr function


DateTimeToString procedure

See Also	Date/Time Routines

Unit

SysUtils

Declaration

procedure DateTimeToString(var Result: string; const Format: string; DateTime: TDateTime);

Description

DateTimeToString converts the date and time value given by DateTime using the format string given by Format into the string variable given by Result. For further details, see the description of the FormatDateTime function.


See also

FormatDateTime function

TDateTime type


DateToStr function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function DateToStr(Date: TDateTime): string;

Description

The DateToStr function converts a variable of type TDateTime to a string. The conversion uses the format specified by the ShortDateFormat global variable.


Example

This example uses a label and a button on a form. When the user clicks the button, the current date is converted to a string and displayed as the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := DateToStr(Date);

end;


See also

Date function

Date and Time Typed Constants

 DateTimeToStr function

StrToDate function


DayOfWeek function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function DayOfWeek(Date: TDateTime): Integer;

Description

The DayOfWeek function returns the day of the week of the specified date as an integer between 1 and 7. Sunday is the first day of the week and Saturday is the seventh.


Example

This example uses a button, an edit box, and a label on a form. When the user enters a date in the edit box using the Month/Day/Year format, the caption of the label reports the day of the week for the specified date.

procedure TForm1.Button1Click(Sender: TObject);

var

  ADate: TDateTime;

begin

  ADate := StrToDate(Edit1.Text);

  Label1.Caption := 'Day ' + IntToStr(DayOfWeek(ADate)) + ' of the week';

end;


See also

Date and Time typed constants

 Date function

EncodeDate function

Now function

StrToDate function

StrToDateTime function


Dec procedure

See Also	Example	Ordinal Routines

Unit

System

Declaration

procedure Dec(var X[ ; N: Longint]);

Description

The Dec procedure subtracts one or N from a variable.

Dec(X) corresponds to X := X - 1, and Dec(X, N) corresponds to X := X - N.

X is an ordinal-type variable or a variable of type PChar if the extended syntax is enabled, and N is an integer-type expression.

Dec generates optimized code and is especially useful in a tight loop.

Note:	Dec(S, I) where S is a ShortInt and the result is a number greater than 127 will cause an EIntOverFlow exception to be raised if range and overflow checking are on. Under Delphi 1.0 this did not raise an exception.


Example

 var

  IntVar: Integer;

  LongintVar: Longint;

begin

  Intvar := 10;

  LongintVar := 10;

  Dec(IntVar);	{ IntVar := IntVar - 1 }

  Dec(LongintVar, 5);	{ LongintVar := LongintVar - 5 }

end;


See also

Inc procedure

Pred function

Succ function


DecodeDate procedure

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

procedure DecodeDate(Date: TDateTime; var Year, Month, Day: Word);

Description

The DecodeDate procedure breaks the value specified as the Date parameter into Year, Month, and Day values. If the given TDateTime value is less than or equal to zero, the year, month, and day return parameters are all set to zero.


Example

This example uses a button and two labels on a form. When the user clicks the button, the current date and time are reported in the captions of the two labels.

procedure TForm1.Button1Click(Sender: TObject);

var

  Present: TDateTime;

  Year, Month, Day, Hour, Min, Sec, MSec: Word;

 begin

  Present:= Now;

  DecodeDate(Present, Year, Month, Day);

  Label1.Caption := 'Today is Day ' + IntToStr(Day) + ' of Month '

    + IntToStr(Month) + ' of Year ' + IntToStr(Year);

  DecodeTime(Present, Hour, Min, Sec, MSec);

  Label2.Caption := 'The time is Minute ' + IntToStr(Min) + ' of Hour '

    + IntToStr(Hour);

end;


See also

Date and Time typed constants

DecodeTime procedure


DecodeTime procedure

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

procedure DecodeTime(Time: TDateTime; var Hour, Min, Sec, MSec: Word);

Description

The DecodeTime procedure breaks the value specified as the Time parameter into hours, minutes, seconds, and milliseconds.


Example

This example uses a button and two labels on a form. When the user clicks the button, the current date and time are reported in the captions of the two labels.

procedure TForm1.Button1Click(Sender: TObject);

var

  Present: TDateTime;

  Year, Month, Day, Hour, Min, Sec, MSec: Word;

 begin

  Present:= Now;

  DecodeDate(Present, Year, Month, Day);

  Label1.Caption := 'Today is Day ' + IntToStr(Day) + ' of Month '

    + IntToStr(Month) + ' of Year ' + IntToStr(Year);

  DecodeTime(Present, Hour, Min, Sec, MSec);

  Label2.Caption := 'The time is Minute ' + IntToStr(Min) + ' of Hour '

    + IntToStr(Hour);

end;


See also

Date and Time typed constants

 DecodeDate procedure

EncodeTime function

Time function


Delete procedure

See Also	Example	String-handling routines (Pascal style)

Unit

System

Declaration

procedure Delete(var S: string; Index, Count:Integer);

Description

The Delete procedure removes a substring of Count characters from string S starting at S[Index].

S is a string-type variable. Index and Count are integer-type expressions.

If Index is larger than the length of S, no characters are deleted. If Count specifies more characters than remain starting at the S[Index], Delete removes the rest of the string.


Example

 var

   s: string;

 begin

   s := 'Honest Abe Lincoln';

   Delete(s,8,4);

   Canvas.TextOut(10, 10, s);	{ 'Honest Lincoln' }

 end;


See also

Concat function

Copy function

Insert procedure

Length function

Pos function


DeleteFile function

Example	File management routines

Unit

SysUtils

Declaration

function DeleteFile(const FileName: string): Boolean;

Description

The DeleteFile function erases the file named by FileName from the disk.

If the file cannot be deleted or does not exist, the function returns False but does not raise an exception.


Example

The following code erases the file DELETE.ME in the current directory:

DeleteFile('DELETE.ME');


DiskFree function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function DiskFree(Drive: Byte): Integer;

Description

DiskFree returns the number of free bytes on the specified drive number, where 0 = Current, 1 = A, 2 = B, and so on.

DiskFree returns -1 if the drive number is invalid.


Example

var

  S: string;

begin

  S := IntToStr(DiskFree(0) div 1024) + ' Kbytes free.';

  Canvas.TextOut(10, 10, S);

end;


See also

DiskSize function


DiskSize function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function DiskSize(Drive: Byte): Integer;

Description

DiskSize returns the size in bytes of the specified drive number, where 0 = Current, 1 = A, 2 = B, etc. DiskSize returns -1 if the drive number is invalid.


Example

var

  S: string;

begin

  S := IntToStr(DiskSize(0) div 1024) + ' Kbytes capacity.';

  Canvas.TextOut(10, 10, S);

end;


See also

DiskFree function


Dispose procedure

See Also	Example	Dynamic Allocation routines

Unit

System

Declaration

procedure Dispose(var P: Pointer);

Description

The Dispose procedure releases memory allocated for a dynamic variable.

After a call to Dispose, the value of P is undefined and it is an error to reference P. If {$I+}, you can use exceptions to handle this error. If you pass an invalid pointer to Dispose it will raise an EInvalidPointer exception. For more information on handling run-time library exceptions, see Handling RTL Exceptions.


Example

type

  Str18 = string[18];

 var

  P: ^Str18;

begin

  New(P);

  P^ := 'Now you see it...';

  Dispose(P);	{ Now you don't... }

end;


See also

EInvalidPointer object

FreeMem procedure

GetMem procedure

New procedure


DisposeStr procedure

See Also	Example	String-handling routines (Pascal style)

Unit

SysUtils

Declaration

procedure DisposeStr(P: PString);

Description

The DisposeStr procedure disposes a string pointer that was previously allocated using NewStr. DisposeStr is only provided for backwards compatibility only for existing code that allocated a string using NewStr. Both DisposeStr and NewStr are obsolete.

The DisposeStr procedure disposes of the dynamically allocated string pointed to by P. P must have been allocated previously with NewStr function. If the given pointer is nil or points to an empty string, StrDispose does nothing.


Example

The following code allocates and frees heap space for a copy of string S pointed to by P, then deallocates the heap space pointed to by P:

var

  P: PString;

  S: string;

begin

  S := 'Ask me about Blaise';

  P := NewStr(S);

  DisposeStr(P):

end;


See also

NewStr function


DLLProc variable

Unit

System

Declaration

var DLLProc: Pointer;

Description

The DLLProc variable is used to specify a procedure that is invoked every time a DLL's entry point is called. A procedure assigned to DLLProc must take one parameter of type Integer; for example,

  procedure LibraryProc(Reason: Integer);

When the procedure is invoked, the Reason parameter contains a value between 0 and 3 as defined by the following group of constants in the Windows unit:

const

  DLL_PROCESS_DETACH = 0;

  DLL_PROCESS_ATTACH = 1;

  DLL_THREAD_ATTACH  = 2;

  DLL_THREAD_DETACH  = 3;

For further details on the meaning of these constants, please refer to the description of the DllEntryPoint function in the Win32 API.


EAbort object

Unit

SysUtils

Declaration

EAbort = class(Exception)

Description

The EAbort exception is Delphi's "silent" exception. When it is raised, no message box appears to inform the user. Your application can handle the exception without the user ever knowing it occurred.


EAccessViolation object

Unit

SysUtils

Declaration

EAccessViolation = class(Exception);

Description

The EAccessViolation exception is raised when the processor detects an invalid access to a memory region.  This can occur when dereferencing a nil pointer, attempting to write to a code page, or when accessing an area in memory that has no physical memory allocated.


EControlC object

Unit

SysUtils

Declaration

EControlC = class(Exception);

Description

The EControlC is raised when the user presses Ctrl-C while running a console-mode application.


EConvertError object

Unit

SysUtils

Declaration

EConvertError = class(Exception);

Description

The EConvertError exception is raised when either the StrToInt or StrToFloat functions are unable to convert the specified string to a valid integer or floating-point value, respectively. For example, this code raises the convert error exception because 3.4 is not a valid integer:

var

  X: Integer;

begin

  X := StrToInt('3.4');

end;


EDivByZero object

Unit

SysUtils

Declaration

EDivByZero = class(EIntError);

Description

The EDivByZero exception is an integer math exception. The exception occurs when your application attempts to divide an integer type by zero. For example, this code raises an EDivByZero exception:

var

 X, Y: Integer;

begin

 X := 0;

 Y := 10;

 Y := Y div X;

end;


EExternalException object

Unit

SysUtils

Declaration

EControlC = class(Exception);

Description

The EExternalException is raised when an exception code is detected that is not recognized as one of the following:

STATUS_INTEGER_DIVIDE_BY_ZERO

 STATUS_ARRAY_BOUNDS_EXCEEDED

 STATUS_FLOAT_OVERFLOW

 STATUS_FLOAT_INEXACT_RESULT

STATUS_FLOAT_INVALID_OPERATION

 STATUS_FLOAT_STACK_CHECK

 STATUS_FLOAT_DIVIDE_BY_ZERO

 STATUS_INTEGER_OVERFLOW

 STATUS_FLOAT_UNDERFLOW

 STATUS_FLOAT_DENORMAL_OPERAND

 STATUS_ACCESS_VIOLATION

 STATUS_PRIVILEGED_INSTRUCTION

 STATUS_CONTROL_C_EXIT

 STATUS_STACK_OVERFLOW


EInOutError object

Unit

SysUtils

Declaration

EInOutError = class(Exception)
public
  ErrorCode: Integer;
end;

Description

The EInOutError is raised any time a file input/output operating system error occurs. The resulting error code is returned in the ErrorCode field.

EInOutError exceptions will be raised only is the $I+ directive is in effect. If an I/O error occurs when your application is in the $I- state, your application must call the IOResult function to clear the error.


EIntError object

Unit

SysUtils

Declaration

EIntError = class(Exception);

Description

The EIntError exception is a generic integer math exception. Although it is never raised in the run-time library, it is the base from which other integer math exceptions descend. These are the integer math exceptions:

Exception	Meaning

EDivByZero	An attempt was made to divide by zero

ERangeError	Number or expression out of range

EIntOverflow	Integer operation overflowed


EIntOverflow object

Unit

SysUtils

Declaration

EIntOverFlow = class(EIntError);

Description

The EIntOverFlow exception is an integer math exception. It occurs when a calculated result is too large to fit within the register allocated for it and therefore, data is lost. For example, this code results in an overflow condition as the calculation result overflows a register:

var

  SmallNumber: Shortint;

   X, Y: Integer;

begin

  X := 127000;

  Y := 127000;

  SmallNumber := X * Y * 100;

end;

The EIntOverFlow occurs only if range checking is turned on (your code includes the $Q+ directive or you set the Overflow-checking option using the Options|Project dialog box).

Note:	Overflow is determined by the size of the machine register. A calculation which would overflow in a 16-bit program will probably not overflow in a 32-bit program. In 32-bit programs you'd probably get a range check exception instead. For example, if overflow occurs before assignment, an EIntOverflow error occurs. If the error is checked at the point of assignment, then a ERangeError happens. Overflow is not the same in 16-bit and 32-bit Delphi.

See also the ERangeError exception.


EInvalidCast object

Unit

SysUtils

Declaration

EInvalidCast = class(Exception);

Description

The EInvalidCast exception occurs when your application tries to typecast an object into another type using the as operator, and the requested typecast is illegal. For example, an invalid typecast exception is raised if in this expression AnObject is not of a type compatible with TObjectType:

AnObject as TObjectType


EInvalidOp object

Unit

SysUtils

Declaration

EInvalidOp = class(EMathError);

Description

The EInvalidOp exception is a floating-point math exception. It occurs whenever the processor encounters an undefined instruction, an inexact result, an invalid operation, or a floating-point processor stack overflow.


EInvalidPointer object

Unit

SysUtils

Declaration

EInvalidPointer = class(Exception);

Description

The EInvalidPointer exception is raised when your application attempts an invalid pointer operation. For example, it can occur if your application tries to dispose of the same pointer twice, or your application calls the Free method twice to destroy an object.


EMathError object

Unit

SysUtils

Declaration

EMathError = class(Exception);

Description

The EMathError exception is never raised on its own, but it provides a base exception object from which all the specific floating-point math exceptions descend. These are the floating-point math exceptions:

Exception	Meaning

EInvalidOp	Processor encountered an undefined instruction

EZeroDivide	Attempt to divide by zero

EOverflow	Floating-point operation overflowed

EUnderflow	Floating-point operation underflowed


EncodeDate function

See Also	Example	Date and Time routines

Unit

SysUtils

Declaration

function EncodeDate(Year, Month, Day: Word): TDateTime;

Description

The EncodeDate function returns a TDateTime type from the values specified as the Year, Month, and Day parameters.

The year must be between 1 and 9999.

Valid Month values are 1 through 12.

Valid Day values are 1 through 28, 29, 30, or 31, depending on the Month value. For example, the possible Day values for month 2 (February) are 1 through 28 or 1 through 29, depending on whether or not the Year value specifies a leap year.

If the specified values are not within range, an EConvertError exception is raised. The resulting value is one plus the number of days between 12/30/1899 and the given date.


Example

This example uses a button and a label on a form. When the user clicks the button, a specified date is encoded as a MyDate variable of type TDateTime. MyDate is then displayed as a string in the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

var

  MyDate: TDateTime;

begin

  MyDate := EncodeDate(83, 12, 31);

  Label1.Caption := DateToStr(MyDate);

end;


See also

Date and Time typed constants

DateToStr function

DecodeDate procedure

EncodeTime function


EncodeTime function

See Also	Example	Date and Time routines

Unit

SysUtils

Declaration

function EncodeTime(Hour, Min, Sec, MSec: Word): TDateTime;

Description

The EncodeTime function returns a TDateTime type from the values specified as the Hour, Min, Sec, and MSec parameters.

If the value of the Time24Hour typed constant is False, valid Hour values are 0 through 12. If the value of Time24Hour is True, valid Hour values are 0 through 23.

Valid Min and Sec values are 0 through 59. Valid MSec values are 0 through 999.

If the specified values are not within range, an EConvertError exception is raised. The resulting value is a number between 0 (inclusive) and 1 (not inclusive) that indicates the fractional part of a day given by the specified time. The value 0 corresponds to midnight, 0.5 corresponds to noon, 0.75 corresponds to 6:00 pm, etc.


Example

procedure TForm1.Button1Click(Sender: TObject);

var

  MyTime: TDateTime;

begin

  MyTime := EncodeTime(0, 45, 45, 7);

  Label1.Caption := TimeToStr(MyTime);

end;


See also

Date and Time typed constants

 DecodeTime procedure

EncodeDate function


Eof function

See Also	Example	I/O routines

Unit

System

Declaration

Typed or untyped files:

function Eof(var F): Boolean;

Text files:

function Eof [ (var F: Text) ]: Boolean;

Description

The Eof function tests whether or not the current file position is the end-of-file.

F is a text file variable. If F is omitted, the standard file variable Input is assumed.

Eof(F) returns True if the current file position is beyond the last character of the file or if the file contains no components; otherwise, Eof(F) returns False.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

  F1, F2: TextFile;

  Ch: Char;

begin

  if OpenDialog1.Execute then begin

    AssignFile(F1, OpenDialog1.Filename);

    Reset(F1);

    if SaveDialog1.Execute then begin

      AssignFile(F2, OpenDialog1.Filename);

      Rewrite(F2);

      while not Eof(F1) do

      begin

        Read(F1, Ch);

        Write(F2, Ch);

      end;

      CloseFile(F2);

    end;

    CloseFile(F1);

  end;

end;


See also

Eoln function

SeekEof function


Eoln function

See Also	Example	Text File routines

Unit

System

Declaration

function Eoln [(var F: Text) ]: Boolean;

Description

The Eoln function test whether the current file position is the end-of-line of a text file.

F, if specified, is a text file variable. If F is omitted, the standard file variable Input is assumed.

Eoln(F) returns True if the current file position is at an end-of-line or if Eof(F) is True; otherwise, Eoln(F) returns False.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

begin

 { Tells program to wait for keyboard input }

   WriteLn(Eoln);

 end;


See also

Eof function

SeekEoln function


EOutOfMemory object

Unit

SysUtils

Declaration

EOutOfMemory = class(Exception);

Description

The EOutOfMemory exception is a heap exception. It occurs when your application attempts to allocate dynamic memory, but there wasn't enough free memory in the system to complete the requested operation.


EOverflow object

Unit

SysUtils

Declaration

EOverflow = class(EMathError);

Description

The EOverflow exception is a floating-point math exception. It occurs when a calculated result is too large to fit within the register allocated for it and therefore, data is lost.


EPrivilege object

Unit

SysUtils

Declaration

EPrivilege = class(Exception);

Description

The EPrivilege is raised when a user program tries to execute a processor instruction that is invalid for the current processor privilege level.


EPropReadOnly object

Unit

SysUtils

Declaration

EPropReadOnly = class(Exception);

Description

The EPropReadOnly exception is raised if you try to write to a read-only property using OLE Automation.


EPropWriteOnly object

Unit

SysUtils

Declaration

EPropWriteOnly = class(Exception);

Description

The EPropWriteOnly is raised if you try to read a write-only property using OLE Automation.


ERangeError object

Unit

SysUtils

Declaration

ERangeError = class(EIntError);

Description

The ERangeError exception is an integer math exception. It occurs when an integer expression evaluates to a value that exceeds the bounds of the specified integer type to which it is assigned. For example, this code raises an ERangeError exception:

var

  SmallNumber: Shortint;

  X, Y: Integer;

begin

  X := 100;

  Y := 75;

  SmallNumber := X * Y;

end;

Attempting to access an item in an array with an index value that is not within the defined array results in a range error exception. For example, this code attempts to assign a value to Values[11] when the highest index of the Values array is 10:

var

  Values: array{1..10] of Integer;

  I: Integer;

begin

  for I := 1 to 11 do

    Values[I] := I; { on the last loop a range error exception is raised }

end;

The ERangeError exception is raised only if range checking is turned on (your code includes the $R+ directive or you set the Range-checking option using the Project|Options dialog box).


Erase procedure

See Also	Example	I/O routines

Unit

System

Declaration

procedure Erase(var F);

Description

The Erase procedure deletes the external file associated with F.

F is a file variable of any file type.

Always close a file before erasing it.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

procedure TForm1.Button1Click(Sender: TObject);

var

  F: Textfile;

begin

  OpenDialog1.Title := 'Delete File';

  if OpenDialog1.Execute then begin

    AssignFile(F, OpenDialog1.FileName);

    try

      Reset(F);

      if MessageDlg('Erase ' + OpenDialog1.FileName + '?',

        mtConfirmation, [mbYes, mbNo], 0) = mrYes then

      begin

        CloseFile(F);

        Erase(F);

      end;

    except

      on EInOutError do

        MessageDlg('File I/O error.', mtError, [mbOk], 0);

    end;

  end;

end;


See also

Rename procedure


ErrorAddr variable

See Also

Unit

System

Declaration

var ErrorAddr: Pointer;

Description

The ErrorAddr variable contains the address of the statement causing a run-time error. If a program terminates normally or stops due to a call to Halt, ErrorAddr is nil. If a program ends because of a run-time error, ErrorAddr contains the address of the statement in error.


See also

ExitCode variable

Exit Procedures

 ExitProc variable


ErrorProc variable

See Also	Example

Unit

System

Declaration

const ErrorProc: Pointer;

Description

ErrorProc is a procedure variable pointing to the RTL run-time error handler. The standard RTL ErrorProc reports the run-time error and terminates the program.

The ErrorProc variable is retained in Delphi 2.0 primarily for compatibility with older Pascal code.  Delphi applications should not specify an alternate run time error proceedure using ErrorProc as Delphi SysUtils uses this variable to convert run time errors into exceptions. Unlike run time errors, exceptins may be processed by Delphi applications.

If you use SysUtils in your program, it will force ErrorProc to its own routine and convert the run-time error into an exception. When a run-time library error occurs, the ErrorProc is called.  The ErrorCode parameter contains the run-time error number and the ErrorAddr parameter contains the machine code address that caused the run time error.


Example

procedure MyErrorHandler(ErrorCode: Integer; ErrorAddr: Pointer);

  ErrorProc := MyErrorHandler

end;


See also

ErrorAddr variable

Exit Procedures

 ExitCode variable


EStackOverflow object

Unit

SysUtils

Declaration

EStackOverflow = class(Exception);

Description

The EStackOverflow exception is raised when the current thread's stack grows into the final guard page.  In other words the system cannot dynamically grow the stack.


EUnderflow object

Unit

SysUtils

Declaration

EUnderflow = class(EMathError);

Description

The EUnderflow is a floating-point math exception. By default, when a floating-point math operation produces a value that is too small to be represented in a floating-point variable, the result becomes zero. If an application changes the numeric co-processor's control word to unmask underflow hardware exceptions, an EUnderflow exception will be raised when the co-processor reports an underflow hardware exception.


EVariantError object

Unit

SysUtils

Declaration

EVariantError = class(Exception);

Description

The EVariantError exception is raised for the following reasons:

Invalid variant typecast

Invalid variant operation

Variant does not contain an OLE Idispatch object.

Unable to create a Variant array

Variant is not an array

Variant array index is out of bounds


ExceptAddr function

See Also	Exception handling routines

Unit

SysUtils

Declaration

function ExceptAddr: Pointer;

Description

The ExceptAddr function returns the address at which the current exception was raised. If there is no current exception, ExceptAddr returns nil.


See also

Raising an exception


Exception object

Unit

SysUtils

Declaration

Exception = class(TObject)

  private

    FMessage: string;

    FHelpContext: Integer;

public

    constructor Create(const Msg: string);

    constructor CreateFmt(const Msg: string; const Args: array of const);

    constructor CreateRes(Ident: Integer);

    constructor CreateResFmt(Ident: Integer; const Args: array of const);

    constructor CreateHelp(const Msg: string; AHelpContext: Integer);

    constructor CreateFmtHelp(const Msg: string; const Args: array of const; AHelpContext: Integer);

    constructor CreateResHelp(Ident: Integer; AHelpContext: Integer);

    constructor CreateResFmtHelp(Ident: Integer; const Args: array of const; AHelpContext: Integer);

    destructor Destroy; override;

   property HelpContext: Integer

    property Message: string;

end;

Description

The Exception object is the base class for all exceptions. Therefore, all exceptions inherit the methods and properties declared within Exception.

The Message property is the message displayed when the exception occurs.

The CreateFmt method allows you to create a formatted message as the value of Message. The Msg constant is the string you specify, and the Args constant is an array of format specifiers used to format the message. CreateFmt uses the Format function to format the message.

The CreateRes method obtains the string that becomes the value of the Message property from a resource file. Specify the string as the value of the Ident parameter.

The CreateResFmt method obtains the string that becomes the value of the Message property and formats it using the Format function.

The CreateHelp method creates an exception object with an help context ID number.

The CreateFmtHelp method allows you to create a formatted message as the value of Message with a context-sensitive ID help number. The Msg constant is the string you specify, and the Args constant is an array of format specifiers used to format the message. The AHelpContext parameter is the context- sensitive help ID number. CreateFmt uses the Format function to format the message.

The CreateResHelp method obtains the string that becomes the value of the Message property from a resource file. Specify the string as the value of the Ident parameter. The AHelpContext parameter is for a context-sensitive ID number.

The CreateResFmtHelp method obtains the string that becomes the value of the Message property and formats it using the Format function. The AHelpContext parameter is for a context-sensitive ID number.


ExceptionClass typed constant

See Also

Unit

System

Declaration

const ExceptionClass: TClass;

Description

ExceptionClass is a class reference variable that determines what exception classes will be reported by the debugger. ExceptionClass is set to Exception by default, so only objects descended from Exception and raised in the Raise statement will be reported by the debugger during a debug session.


See also

Exception handling


ExceptObject function

See Also	Exception handling routines

Unit

SysUtils

Declaration

function ExceptObject: TObject;

Description

The ExceptObject function returns a reference to the current exception object -- that is, the object associated with the currently raised exception. If there is no current exception, ExceptObject returns nil. In most cases, you do not need to call ExceptObject explicitly; instead, you can use the language construct

on E: ExceptionType do

This constructs maps the identifier E onto the object instance of the current exception statement that follows if the current exception is of ExceptionType. However, if you create a default exception handler by using an else in your exception block, the only way to access the current exception object is by calling ExceptObject.


See Also

Exception Handling


ExceptProc variable

Unit

System

Declaration

const ExceptProc: Pointer;

Description

ExceptProc is a pointer that points to the lowest-level RTL exception handler. Unhandled exceptions are handled by ExceptProc. You can hook into ExceptProc to change how unhandled exceptions are reported, much like hooking into ExitProc.


Exclude procedure

See Also	Miscellaneous routines

Unit

System

Declaration

procedure Exclude(var S: set of T;I:T);

Description

The Exclude procedure removes element I from set S.

S is a set type variable, and I is an expression of a type compatible with the base type
of S.

The construct Exclude (S, I) corresponds to S := S - (I) but the Exclude procedure generates more efficient code.


See also

Include procedure


Exit procedure

See Also	Flow-control routines

Unit

System

Declaration

procedure Exit;

Description

The Exit procedure immediately passes control away from the current procedure.

If the current procedure is the main program, Exit causes the program to terminate.

Exit will cause the calling procedure to continue with the statement after the point at which the procedure was called.

Note:	Exit is not constained by blocks but by procedures.

When using exception handling Exit will go into any finally blocks between it and the loop exit. This is the same type of behavior that occurs with the Break and Continue procedures. For example code illustrating this behavior, see those procedures. For more information on handling run-time library exceptions, see Handling RTL Exceptions.


See also

Halt procedure


ExitCode variable

See Also

Unit

System

Declaration

var ExitCode: Integer;

Description

The ExitCode variable is provided for backwards compatibility only. Use finalization instead. The ExitCode variable contains the application's exit code.

An exit procedure can learn the cause of termination by examining ExitCode.

If the program terminates normally, ExitCode is zero.

If the program terminates due to a call to Halt, ExitCode contains the value passed to Halt.

If the program terminates due to a run-time error, ExitCode contains the error code.


See also

ErrorAddr variable

Exit procedures

 ExitProc variable


ExitProc variable

See Also

Unit

System

Declaration

var ExitProc: Pointer;

Description

The ExitProc pointer variable enables you to install an exit procedure. The exit procedure always gets called as part of a program's termination.

An exit procedure takes no parameters and must be compiled with a far procedure directive to force it to use the far call model.

When implemented properly, an exit procedure actually becomes part of a chain of exit procedures. The procedures on the exit chain get executed in reverse order of installation.

To keep the exit chain intact, you need to save the current contents of ExitProc before changing it to the address of your own exit procedure.

The first statement in your exit procedure must reinstall the saved value of ExitProc.


See also

ErrorAddr variable

Exit procedures

 ExitCode variable


Exp function

See Also	Example	Arithmetic routines

Unit

System

Declaration

function Exp(X: Real): Real;

Description

The Exp function returns the exponential of X.

The return value is e raised to the power of X, where e is the base of the natural logarithms.


Example

 var

  S: string;

begin

  S := 'e = ' + FloatToStr(Exp(1.0));

  Canvas.TextOut(10, 10, S);

end;


See also

Ln function


ExpandFileName function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function ExpandFileName(const FileName: string): string;

Description

The ExpandFileName function returns a string containing a fully qualified path name for the file passed in the FileName. A fully qualified path name includes the drive letter and any directory and subdirectories in addition to the file name and extension.


Example

The following code converts a file name into a fully-expanded file name:

MyFileName := ExpandFileName(MyFileName);


See also

ExtractFileName function


ExtractFileDir function

See Also

Unit

SysUtils

Declaration

function ExtractFileDir(const FileName: string): string;

Description

The ExtractFileDir function extracts the drive and directory parts of the given file name. The resulting string is a directory name suitable for passing to the CreateDir, GetCurrentDir, RemoveDir, and SetCurrentDir functions. The resulting string is empty if FileName contains no drive and directory parts.


See Also

CreateDir function

GetCurrentDir function

RemoveDir function

SetCurrentDir function


ExtractFileExt function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function ExtractFileExt(const FileName: string): string;

Description

The ExtractFileExt function extracts the extension part of the given file name. The resulting string includes the period character that separates the name and extension parts. The resulting string is empty if the given filename has no extension.


Example

The following code returns the extension from a file name:

MyFilesExtension := ExtractFileExt(MyFileName);


See also

ExtractFileName function


ExtractFileName function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function ExtractFileName(const FileName: string): string;

Description

The ExtractFileName function extracts the name and extension parts of the given file name. The resulting string is the leftmost characters of FileName, starting with the first character after the colon or backslash that separates the path information from the name and extension. The resulting string is equal to FileName if FileName contains no drive and directory parts.


Example

The following code changes the caption of Form1 to read "Editing <FileName>".

Form1.Caption := 'Editing '+ ExtractFileName(FileName);


See also

ExpandFileName function

ExtractFilePath function


ExtractFilePath function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function ExtractFilePath(const FileName: string): string;

Declaration

The ExtractFilePath function extracts the drive and directory parts of the given file name. The resulting string is the rightmost characters of FileName, up to and including the colon or backslash that separates the path information from the name and extension. The resulting string is empty if FileName contains no drive and directory parts.


Example

The following code changes the current directory to the location of FileName.

ChDir(ExtractFilePath(FileName));


See also

ExtractFileName function


EZeroDivide object

Unit

SysUtils

Declaration

EZeroDivide = class(EMathError);

Description

The EZeroDivide exception is a floating-point math exception. It occurs when your application attempts to divide a floating-point value by zero. For example, this code raises a EZeroDivide exception:

var

  X, Y, Z: Double;

begin

  X := 0.0;

  Y := 10.11111;

  Y := Y / X;

  Z := Y;

end;


File mode constants

Unit

SysUtils

Declaration

fmClosed = $D7B0;
fmInput  = $D7B1;
fmOutput = $D7B2;
fmInOut  = $D7B3;

Description

Use the file mode constants when opening and closing disk files. The Mode field of TFileRec and TTextRec will contain one of these values.


File open mode constants

Unit

SysUtils

Declaration

fmOpenRead       = $0000;
fmOpenWrite      = $0001;
fmOpenReadWrite  = $0002;
fmShareCompat    = $0000;
fmShareExclusive = $0010;
fmShareDenyWrite = $0020;
fmShareDenyRead  = $0030;
fmShareDenyNone  = $0040;

The file open mode constants are used to control the shareability of a file or stream when you open it.

TFileStream.Create has a Mode parameter that you can set to one of these constants:

Constant	Definition

fmOpenRead	Open for read access only.

fmOpenWrite	Open for write access only.

fmOpenReadWrite	Open for read and write access.

fmShareCompat	Compatible with the way FCBs are opened.

fmShareExclusive	Read and write access is denied.

fmShareDenyWrite	Write access is denied.

fmShareDenyRead	Read access is denied.

fmShareDenyNone	Allows full access for others.


FileAge function

File management routines

Unit

SysUtils

Declaration

function FileAge(const FileName: string): Integer;

Description

The FileAge function returns the age of the file named by FileName as an Integer.


FileClose procedure

See Also	Example	File management routines

Unit

SysUtils

Declaration

procedure FileClose(Handle: Integer);

Description

The FileClose procedure closes the specified file. Use of the non-native Pascal file variable handlers such as FileClose is discouraged. For more information on which file handling routines to use see FileOpen.


Example

The following code closes a file opened with FileOpen:

FileClose(MyFileHandle);


See also

FileCreate function

FileOpen function


FileCreate function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function FileCreate(const FileName: string): Integer;

Description

The FileCreate function creates a new file by the specified name. If the return value is positive, the function was successful and the value is the file handle of the new file. A return value of -1 indicates that an error occurred.

Use of the non-native Pascal file variable handlers such as FileCreate is discouraged. For more information on which file handling routines to use see FileOpen.


Example

The following example creates a new file and assigns it to the identifier MyFileHandle.

MyFileHandle := FileCreate('NEWFILE.TXT');


See also

FileClose procedure

FileOpen function


FileDateToDateTime function

See Also	File management routines

Unit

SysUtils

Declaration

function FileDateToDateTime(FileDate: Integer): TDateTime;

Description

FileDateToDateTime converts a DOS date-and-time value to a TDateTime value. The FileAge, FileGetDate, and FileSetDate routines operate on DOS date-and-time values, and the Time field of a TSearchRec used by the FindFirst and FindNext functions contains a DOS date-and-time value.


See also

DateTimeToFileDate function


FileExists function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function FileExists(const FileName: string): Boolean;

Description

The FileExists function returns True if the file specified by FileName exists. If the file does not exist, FileExists returns False.


Example

The following code prompts you for confirmation before deleting a file:

if FileExists(FileName) then

  if MsgBox('Do you really want to delete ' + ExtractFileName(FileName)

    + '?'), []) = IDYes then DeleteFile(FileName);


See also

FileSearch function


FileGetAttr function

See Also	File management routines

Unit

SysUtils

Declaration

function FileGetAttr(const FileName: string): Integer;

Description

The FileGetAttr function returns the file attributes of the file given by FileName. The attributes can be examined by AND-ing with the faXXXX constants defined above. A return value of -1 indicates that an error occurred.


See also

FileSetAttr function


FileGetDate function

See Also	File management routines

Unit

SysUtils

Declaration

function FileGetDate(Handle: Integer): Integer;

Description

The FileGetDate function returns the DOS date-and-time stamp of the file given by Handle. The return value is -1 if the handle is invalid. The FileDateToDateTime function can be used to convert the returned value to a TDateTime value.


See also

FileSetDate procedure


FileMode variable

See Also

Unit

System

Declaration

var FileMode: Byte;

Description

The FileMode variable determines the access mode to use when typed and untyped files (not text files) are opened using the Reset procedure.

The default FileMode is 2. Assigning another value to FileMode causes all subsequent Resets to use that mode.

Valid FileMode values are:

0	Read only

1	Write only

2	Read/Write


See also

Rewrite procedure

TFileStream object


FileOpen function

See Also	Example	File Management Routines

Unit

SysUtils

Declaration

function FileOpen(const FileName: string; Mode: Integer): Integer;

Description

The FileOpen function opens the specified file using the specified access mode. The access mode value is constructed by OR-ing one of the fmOpenXXXX constants with one of the fmShareXXXX constants. If the return value is positive, the function was successful and the value is the file handle of the opened file. A return value of -1 indicates that an error occurred.


Example

procedure OpenForShare(const FileName: String);

var

  FileHandle : Integer;

begin

  FileHandle := FileOpen(FileName, fmOpenWrite or fmShareDenyNone);

  if FileHandle > 0 then

    [valid file handle}

  else

    [Open error: FileHandle = negative DOS error code]

end;

Note:	Use of the non-native Pascal file variable handlers such as FileOpen is discouraged. These routines map to the Windows API functions and return file handles, not normal Pascal file variables. These are low-level file access routines. For normal file operations use the normal AssignFile, Rewrite, Reset operations instead of FileOpen.


See Also

AssignFile procedure

FileClose procedure

FileCreate function

File open mode constants

Reset procedure

Rewrite procedure


FilePos function

See Also	Example	I/O routines

Unit

System

Declaration

function FilePos(var F): Longint;

Description

The FilePos function returns the current file position within a file.

To use FilePos the file must be open and it can't be used on a text file.

F is a file variable.

Position	Result

Beginning of file	FilePos(F) = 0

Middle of file	FilePos(F) = current file position

End of file	Eof(F) = True

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

   f: file of Byte;

   size : Longint;

   S: string;

   y: integer;

 begin

   if OpenDialog1.Execute then begin

     AssignFile(f, OpenDialog1.FileName);

     Reset(f);

     size := FileSize(f);

     S := 'File size in bytes: ' + IntToStr(size);

     y := 10;

     Canvas.TextOut(5, y, S);

     y := y + Canvas.TextHeight(S) + 5;

     S := 'Seeking halfway into file...';

     Canvas.TextOut(5, y, S);

     y := y + Canvas.TextHeight(S) + 5;

     Seek(f,size div 2);

     S := 'Position is now ' + IntToStr(FilePos(f));

     Canvas.TextOut(5, y, S);

     CloseFile(f);

   end;

 end;


See also

FileSize function

Seek procedure


FileRead function

See Also	Example	I/O routines

Unit

System

Declaration

function FileRead(Handle: Integer; var Buffer; Count: Integer): Integer;

Description

The FileRead function reads Count bytes from the Handle into the buffer. The function result is the actual number of bytes read, which may be less than Count. The Handle that is passed to FileRead must be opened with FileOpen or FileCreate. You should not mix routines that take or return file handles with those that use Pascal file variables (typically seen as var F).


Example

The following code fills a buffer from a file.

ActualRead := FileRead(MyFileHandle, Buffer, SizeOf(Buffer));

Note:	Use of the non-native Pascal file variable handlers such as FileRead is discouraged. For more information on which file handling routines to use see FileOpen.


See also

BlockRead procedure

FileOpen function

FileCreate function

FileSeek function

FileWrite function

Read procedure


FileSearch function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function FileSearch(const Name, DirList: string): string;

Description

The FileSearch function searches through the directories passed in DirList for a file named Name. DirList should be in the same format as a DOS path: directory names separated by semicolons. If FileSearch locates a file matching Name, it returns a string containing a fully-qualified path name for that file. If no matching file exists, FileSearch returns an empty string.


Example

The following code searches for FINDME.DLL in a series of directories:

FoundIt := FileSearch('FINDME.DLL', MyAppDir+'\';'+WinDir+';'+WinDir+'\SYSTEM');


See also

FileExists function


FileSeek function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function FileSeek(Handle, Offset, Origin: Integer): Integer;

Description

The FileSeek function positions the current file pointer within a previously opened file. Handle contains the file handle. The Handle that is passed to FileSeek must have been opened with FileOpen or FileCreate. You should not mix routines that take or return file handles with those that use Pascal file variables (typically seen as var F).

Offset specifies the number of bytes from Origin where the file pointer should be positioned. Origin is a code with three possible values, denoting the beginning of the file, the end of the file, and the current position of the file pointer.

Origin	Action

    0	The file pointer is positioned Offset bytes from the beginning of the file.

    1	The file pointer is positioned Offset bytes from its current position.

    2	The file pointer is positioned Offset bytes from the end of the file.

If FileSeek is successful, it returns the new position of the file pointer; otherwise, it returns -1.


Example

The following code positions the file pointer at the end of a file:

if FileSeek(MyFileHandle,0,2) = HFILE_ERROR then

  HandleFileError

else

  AppendStuff;

Note:	Use of the non-native Pascal file variable handlers such as FileRead is discouraged. For more information on which file handling routines to use see FileOpen.


See also

FileOpen function

FileCreate function

FileRead function

FileWrite function

Seek procedure


FileSetAttr function

See Also	File management routines

Unit

SysUtils

Declaration

function FileSetAttr(const FileName: string; Attr: Integer): Integer;

Description

The FileSetAttr function sets the file attributes of the file given by FileName to the value given by Attr. The attribute value is formed by OR-ing the appropriate faXXXX constants. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


See also

FileGetAttr function


FileSetDate function

See Also	File management routines

Unit

SysUtils

Declaration

function FileSetDate(Handle: Integer; Age: Integer): Integer;

Description

The FileSetDate function sets the DOS date-and-time stamp of the file given by Handle to the value given by Age. The DateTimeToFileDate function can be used to convert a TDateTime value to a DOS date-and-time stamp. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


See also

FileCreate function

FileGetDate function

FileOpen function


FileSize function

See Also	Example	I/O routines

Unit

System

Declaration

function FileSize(var F): Integer;

Description

The FileSize function returns the size in bytes of file F. However, if F is a record file FileSize will return the number of records in the file.

To use FileSize the file must be open and it can't be used on a text file.

F is a file variable.

If the file is empty, FileSize(F) returns 0.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

   f: file of Byte;

   size : Longint;

   S: string;

   y: integer;

 begin

   if OpenDialog1.Execute then begin

     AssignFile(f, OpenDialog1.FileName);

     Reset(f);

     size := FileSize(f);

     S := 'File size in bytes: ' + IntToStr(size);

     y := 10;

     Canvas.TextOut(5, y, S);

     y := y + Canvas.TextHeight(S) + 5;

     S := 'Seeking halfway into file...';

     Canvas.TextOut(5, y, S);

     y := y + Canvas.TextHeight(S) + 5;

     Seek(f,size div 2);

     S := 'Position is now ' + IntToStr(FilePos(f));

     Canvas.TextOut(5, y, S);

     CloseFile(f);

   end;

 end;


See also

FilePos function


FileWrite function

See Also	File management routines

Unit

SysUtils

Declaration

function FileWrite(Handle: Integer; const Buffer; Count: Integer): Integer;

Description

This is an internal routine, and you will not need to use it.

The FileWrite function writes Count bytes to the file given by Handle from the buffer specified by Buffer. The return value is the number of bytes actually written, or -1 if an error occurred.

Use of the non-native Pascal file variable handlers such as FileWrite is discouraged. For more information on which file handling routines to use see FileOpen.


See also

FileRead function

FileSeek function

Writeln function

Write function


FillChar procedure

See Also	Example	Miscellaneous routines

Unit

System

Declaration

procedure FillChar(var X; Count: Integer; value);

Description

The FillChar procedure fills Count number of contiguous bytes with a specified value (can be type Byte or Char).

This function does not perform any range checking.


Example

 var

  S: array[0..79] of char;

begin

  { Set to all spaces }

  FillChar(S, SizeOf(S), ' ');

end;


See also

Move procedure


Finalize procedure

See Also

Unit

System

Declaration

procedure Finalize( var V [; Count: Integer] );

Description

The Finalize procedure finalizes (uninitializes) a dynamically allocated variable. Finalize should be used only in situations where a dynamically allocated variable is deallocated by other means than the Dispose standard procedure.

For global variables, local variables, objects, and dynamic variables deallocated using the Dispose standard procedure, the compiler generates code that finalizes all long strings and variants contained by a variable upon destruction of the variable. If a dynamic variable is deallocated by other means than the Dispose standard procedure (for example using FreeMem), if the variable contains long strings or variants, and if all long strings and variants are not empty or Unassigned, a call to Finalize is required to finalize the variable before it can be deallocated. Finalize simply sets all long strings to empty and all variants to Unassigned, thus properly releasing any memory that was referenced by the long strings and variants.

In cases where several variables are deallocated in a contiguous memory block such as a dynamically allocated array of strings, the additional Count parameter can be specified to finalize all variables in one operation.

If the variable specified in a call to Finalize contains no long strings and variants, the compiler eliminates the call and generates no code for it.


See also

Initialize procedure


FindClose procedure

See Also	File management routines

Unit

SysUtils

Declaration

procedure FindClose(var F: TSearchRec);

Description

The FindClose procedure releases memory allocated by FindFirst. FindClose terminates a FindFirst/FindNext sequence. FindClose does nothing in the 16-bit version of Windows, but is required in the 32-bit version, so for maximum portability every FindFirst/FindNext sequence should end with a call to FindClose.


See also

FindFirst function

FindNext function


FindFirst function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function FindFirst(const Path: string; Attr: Integer; var F: TSearchRec): Integer;

Description

The FindFirst function allocates resources (memory) which must be released by calling FindClose. FindFirst searches the specified directory for the first entry matching the specified file name and set of attributes.

The Path constant parameter is the directory and file name mask, including wildcard characters. For example, 'c:\test\*.*' specifies all files in the C:\TEST directory).

The Attr parameter specifies the special files to include in addition to all normal files. Choose from these file attribute constants when specifying the Attr parameter:

Constant	Value	Description

faReadOnly	$00000001	Read-only files

faHidden	$00000002	Hidden files

faSysFile	$00000004	System files

faVolumeID	$00000008	Volume ID files

faDirectory	$00000010	Directory files

faArchive	$00000020	Archive files

faAnyFile	$0000003F	Any file

You can combine attributes by adding their constants or values. For example, to search for read-only and hidden files in addition to normal files, pass (faReadOnly + faHidden) the Attr parameter.

FindFirst returns the results of the directory search in the search record you specify in the F parameter. You can then use the fields of the search record to extract the information you want.

FindFirst searches the directory given by Path for the first entry that matches the filename given by Path and the attributes given by Attr. The result is returned in the search record given by SearchRec. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


Example

FindFirst is typically used in conjunction with FindNext and FindClose as follows, where ProcessSearchRec represents user-defined code that processes the information in a search record:

begin

    Result := FindFirst(Path, Attr, SearchRec);

    while Result = 0 do

    begin

      ProcessSearchRec(SearchRec);

      Result := FindNext(SearchRec);

    end;

    FindClose(SearchRec);

end;


See also

FindClose function

FindNext function


FindNext function

See Also	Example	File management routines

Unit

SysUtils

Declaration

function FindNext(var F: TSearchRec): Integer;

Description

The FindNext function returns the next entry that matches the name and attributes specified in the previous call to the FindFirst function.

The search record must be the same one you passed to the FindFirst function.

FindNext returns the next entry that matches the name and attributes specified in a previous call to FindFirst. The search record must be one that was passed to FindFirst. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


Example

This example uses a label, a button named Search, and a button named Again on a form. When the user clicks the Search button, the first file in the specified path is found, and the name and the number of bytes in the file appear in the label's caption. Each time the user clicks the Again button, the next matching file name and size is displayed in the label:

var

  SearchRec: TSearchRec;

procedure TForm1.SearchClick(Sender: TObject);

begin

  FindFirst('c:\delphi\bin\*.*', faAnyFile, SearchRec);

  Label1.Caption := SearchRec.Name + ' is ' + IntToStr(SearchRec.Size) +

    ' bytes in size';

end;

procedure TForm1.AgainClick(Sender: TObject);

begin

  FindNext(SearchRec);

  Label1.Caption := SearchRec.Name + ' is ' + IntToStr(SearchRec.Size) +

    ' bytes in size';

end;


See also

FindFirst function


FloatToDecimal procedure

Floating point conversion routines

Unit

SysUtils

Declaration

procedure FloatToDecimal(var Result: TFloatRec; const Value; ValueType: TFloatValue; Precision, Decimals: Integer);

FloatToDecimal converts a floating-point value to a decimal representation that is suited for further formatting.

The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter.

For values of type Extended, the Precision parameter specifies the requested number of significant digits in the result--the allowed range is 1..18. For values of type Currency, the Precision parameter is ignored, and the implied precision of the conversion is 19 digits.

The Decimals parameter specifies the requested maximum number of digits to the left of the decimal point in the result. Precision and Decimals together control how the result is rounded. To produce a result that always has a given number of significant digits regardless of the magnitude of the number, specify 9999 for the Decimals parameter.

The result of the conversion is stored in the specified TFloatRec record as follows:

Field	Value

Exponent	Contains the magnitude of the number, i.e. the number of significant digits to the right of the decimal point. The Exponent field is negative if the absolute value of the number is less than one. If the number is a NAN (not-a-number), Exponent is set to -32768. If the number is INF or -INF (positive or negative infinity), Exponent is set to 32767.

Negative	True if the number is negative, False if the number is zero or positive.

Digits	Contains up to 18 (for type Extended) or 19 (for type Currency) significant digits followed by a null terminator. The implied decimal point (if any) is not stored in Digits. Trailing zeros are removed, and if the resulting number is zero, NAN, or INF, Digits contains nothing but the null terminator.


FloatToStr function

Floating point conversion routines

Unit

SysUtils

Declaration

function FloatToStr(Value: Extended): string;

Description

FloatToStr converts the floating-point value given by Value to its string representation. The conversion uses general number format with 15 significant digits.

For further details, see the description of the FloatToStrF function.


FloatToStrF function

Floating point conversion routines

Unit

SysUtils

Declaration

function FloatToStrF(Value: Extended; Format: TFloatFormat; Precision,
  Digits: Integer): string;

Description

FloatToStrF converts the floating-point value given by Value to its string representation.

The Format parameter controls the format of the resulting string.

The Precision parameter specifies the precision of the given value. It should be 7 or less for values of type Single, 15 or less for values of type Double, and 18 or less for values of type Extended.

The meaning of the Digits parameter depends on the particular format selected.

The possible values of the Format parameter, and the meaning of each, are described below.

Value	Meaning

ffGeneral 	General number format. The value is converted to the shortest possible decimal string using fixed or scientific format. Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format, and the Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).

ffExponent	Scientific format. The value is converted to a string of the form "-d.ddd...E+dddd". The resulting string starts with a minus sign if the number is negative, and one digit always precedes the decimal point. The total number of digits in the resulting string (including the one before the decimal point) is given by the Precision parameter. The "E" exponent character in the resulting string is always followed by a plus or minus sign and up to four digits. The Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).

ffFixed	Fixed point format. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative, and at least one digit always precedes the decimal point. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18. If the number of digits to the left of the decimal point is greater than the specified precision, the resulting value will use scientific format.

ffNumber	Number format. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The ffNumber format corresponds to the ffFixed format, except that the resulting string contains thousand separators.

ffCurrency	Currency format. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, and DecimalSeparator global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panels. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18.

For all formats, the actual characters used as decimal and thousand separators are obtained from the DecimalSeparator and ThousandSeparator global variables.

If the given value is a NAN (not-a-number), the resulting string is 'NAN'. If the given value is positive infinity, the resulting string is 'INF'. If the given value is negative infinity, the resulting string is '-INF'.


FloatToText function

Floating point conversion routines

Unit

SysUtils

Declaration

function FloatToText(Buffer: PChar; const Value; ValueType: TFloatValue; Format: TFloatFormat; Precision, Digits: Integer): Integer;

Description

The FloatToText function converts the given floating-point value to its decimal representation using the specified format, precision, and digits. The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter. The resulting string of characters is stored in the given buffer, and the returned value is the number of characters stored. The resulting string is not null-terminated. For further details, see the description of the FloatToStrF function.


FloatToTextFmt function

Floating point conversion routines

Unit

SysUtils

Declaration

function FloatToTextFmt(Buffer: PChar; const Value; ValueType: TFloatValue; Format: PChar): Integer;

Description

The FloatToTextFmt converts the given floating-point value to its decimal representation using the specified format. The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter. The resulting string of characters is stored in the given buffer, and the returned value is the number of characters stored. The resulting string is not null-terminated.

For further details, see the description of the FormatFloat function.


Flush procedure

See Also	Example	Text file routines

Unit

System

Declaration

procedure Flush(var F: Text);

Description

The Flush procedure clears the buffer of a text file open for output.

F is a text file variable.

When a text file is opened for output using Rewrite or Append, Flush empties the file's buffer. This guarantees that all characters written to the file at that time have actually been written to the external file. Flush has no effect on files opened for input.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

  f: TextFile;

begin

  if OpenDialog1.Execute then

  begin                                                            { open a text file }

    AssignFile(f, OpenDialog1.FileName);

    Append(f);

    Writeln(f, 'I am appending some stuff to the end of the file.');

    Flush(f);  { ensures that the text was actually written to file }

    { insert code here that would require a Flush before closing the file }

    CloseFile(f);

  end;

end;


See also

Append procedure

Rewrite procedure


FmtLoadStr function

See Also	String formatting routines

Unit

SysUtils

Declaration

function FmtLoadStr(Ident: Integer; const Args: array of const): string;

Description

FmtLoadStr loads a string from a program's resource string table and uses that string, plus the Args array, as a parameter to Format. Ident is the string resource ID of the desired format string. Result is the output of Format.

For information on the format strings, see Format Strings.


See also

Format function


FmtStr procedure

See Also	String formatting routines

Unit

SysUtils

Declaration

procedure FmtStr(var Result: string; const Format: string; const Args: array of const);

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the Pascal format string Format; the results are returned in the parameter Result.

For information on the format strings, see Format Strings.


See also

FormatBu f function

StrFmt function

StrLFmt function


Format function

String formatting routines

Unit

SysUtils

Declaration

function Format(const Format: string; const Args: array of const): string;

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the Object Pascal format string Format; the results are returned in the function result as a Pascal string.

For information on the format strings, see Format Strings.


FormatBuf function

String formatting routines

Unit

SysUtils

Declaration

function FormatBuf(var Buffer; BufLen: Cardinal; const Format; FmtLen: Cardinal; const Args: array of const): Cardinal;

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the format string Format (whose length is given by FmtLen); the results are returned in Buffer (whose length is given by BufLen). The function result contains the number of bytes in the Result buffer.

For information on the format strings, see Format Strings.


FormatDateTime function

Example	Date/Time routines

Unit

SysUtils

Declaration

function FormatDateTime(const Format: string; DateTime: TDateTime): string;

Description

FormatDateTime formats the date-and-time value given by DateTime using the format given by Format. The following format specifiers are supported:

Specifier	Displays

c	Displays the date using the format given by the ShortDateFormat global variable, followed by the time using the format given by the LongTimeFormat global variable. The time is not displayed if the fractional part of the DateTime value is zero.

d	Displays the day as a number without a leading zero (1-31).

dd	Displays the day as a number with a leading zero (01-31).

ddd	Displays the day as an abbreviation (Sun-Sat) using the strings given by the ShortDayNames global variable.

dddd	Displays the day as a full name (Sunday-Saturday) using the strings given by the LongDayNames global variable.

ddddd	Displays the date using the format given by the ShortDateFormat global variable.

dddddd	Displays the date using the format given by the LongDateFormat global variable.

m	Displays the month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mm	Displays the month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mmm	Displays the month as an abbreviation (Jan-Dec) using the strings given by the ShortMonthNames global variable.

mmmm	Displays the month as a full name (January-December) using the strings given by the LongMonthNames global variable.

yy	Displays the year as a two-digit number (00-99).

yyyy	Displays the year as a four-digit number (0000-9999).

h	Displays the hour without a leading zero (0-23).

hh	Displays the hour with a leading zero (00-23).

n	Displays the minute without a leading zero (0-59).

nn	Displays the minute with a leading zero (00-59).

s	Displays the second without a leading zero (0-59).

ss	Displays the second with a leading zero (00-59).

t	Displays the time using the format given by the ShortTimeFormat global variable.

tt	Displays the time using the format given by the LongTimeFormat global variable.

am/pm	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon, and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

a/p	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

ampm	Uses the 12-hour clock for the preceding h or hh specifier, and displays the contents of the TimeAMString global variable for any hour before noon, and the contents of the TimePMString global variable for any hour after noon.

/	Displays the date separator character given by the DateSeparator global variable.

:	Displays the time separator character given by the TimeSeparator global variable.

'xx'/"xx"	Characters enclosed in single or double quotes are displayed as-is, and do not affect formatting.

Format specifiers may be written in upper case as well as in lower case letters--both produce the same result.

If the string given by the Format parameter is empty, the date and time value is formatted as if a 'c' format specifier had been given.


Example

The following example assigns 'The meeting is on Wednesday, February 15, 1995 at 10:30 AM' to the string variable S.

S := FormatDateTime('"The meeting is on" dddd, mmmm d, yyyy, ' +

  '"at" hh:mm AM/PM', StrToDateTime('2/15/95 10:30am'));


FormatFloat function

Example	Floating point conversion routines

Unit

SysUtils

Declaration

function FormatFloat(const Format: string; Value: Extended): string;

Description

FormatFloat formats the floating-point value given by Value using the format string given by Format. The following format specifiers are supported in the format string:

Specifier	Represents

0	Digit placeholder. If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the output string. Otherwise, a '0' is stored in that position in the output string.

#	Digit placeholder. If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.

.	Decimal point. The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored. The actual character used as a the decimal separator in the output string is determined by the DecimalSeparator global variable. The default value of DecimalSeparator is specified in the Number Format of the International section in the Windows Control Panel.

,	Thousand separator. If the format string contains one or more ',' characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of ',' characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is determined by the ThousandSeparator global variable. The default value of ThousandSeparator is specified in the Number Format of the International section in the Windows Control Panel.

E+	Scientific notation. If any of the strings 'E+', 'E-', 'e+', or 'e-' are contained in the format string, the number is formatted using scientific notation. A group of up to four '0' characters can immediately follow the 'E+', 'E-', 'e+', or 'e-' to determine the minimum number of digits in the exponent. The 'E+' and 'e+' formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The 'E-' and 'e-' formats output a sign character only for negative exponents.

'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting.

;	Separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost '0' before the decimal point in the format string and the rightmost '0' after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ('0' or '#') to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the '.' character in the format string, the extra digits are output before the first digit placeholder.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

One section: The format string applies to all values.

Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

If the section for positive values is empty, or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits, corresponding to a call to FloatToStrF with the ffGeneral format. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.


Example

The following table shows some sample formats and the results produced when the formats are applied to different values:

Format string-	1234	-1234	0.5	0

1234	-1234	0.5	0

0	1234	-1234	1	0

0.00 	1234.00	-1234.00	0.50	0.00

#.##  	1234	-1234	.5

#,##0.00	1,234.00	-1,234.00	0.50	0.00

#,##0.00;(#,##0.00)	1,234.00	(1,234.00)	0.50	0.00

#,##0.00;;Zero 	1,234.00	-1,234.00	0.50	Zero

0.000E+00   	1.234E+03	-1.234E+03	5.000E-01	0.000E+00

#.###E-0  	1.234E3	-1.234E3	5E-1	0E0


Frac function

See Also	Example	Arithmetic routines

Unit

System

Declaration

function Frac(X: Real): Real;

Description

The Frac function returns the fractional part of the argument X.

X is a real-type expression. The result is the fractional part of X; that is,
Frac(X) = X - Int(X).


Example

 var

  R: Real;

begin

  R := Frac(123.456);    { 0.456 }

  R := Frac(-123.456);   { -0.456 }

end;


See also

Int function


FreeMem procedure

See Also	Example	Dynamic allocation routines

Unit

System

Declaration

procedure FreeMem(var P: Pointer[; Size: Integer]);

Description

The FreeMem procedure disposes of a dynamic variable of a given size.

P is a variable of any pointer type previously assigned by the GetMem procedure or assigned a meaningful value using an assignment statement.

Size specifies the size in bytes of the dynamic variable to dispose of; if specified, it must be exactly the number of bytes previously allocated to that variable by GetMem.

FreeMem destroys the variable referenced by P and returns its memory to the heap. If P does not point to memory in the heap, a run-time error occurs.

After calling FreeMem, the value of P is undefined, and an error occurs if you subsequently reference P^. You can use the exceptions to handle this error. For more information on handling run-time library exceptions, see Handling RTL Exceptions.


Example

The following example opens a file named 'test.txt' and reads the entire file into a dynamically allocated buffer. The buffer and the size of the file are then passed to a routine that processes the text, and finally the dynamically allocated buffer is freed and the file is closed.

var

  F: file;

  Size: Integer;

  Buffer: PChar;

begin

  AssignFile(F, 'test.txt');

  Reset(F, 1);

  try

    Size := FileSize(F);

    GetMem(Buffer, Size);

    try

      BlockRead(F, Buffer^, Size);

      ProcessFile(Buffer, Size);

    finally

      FreeMem(Buffer);

    end;

  finally

    CloseFile(F);

  end;

end;


See also

Dispose procedure

GetMem procedure

New procedure


GetCurrentDir function

See Also

Unit

SysUtils

Declaration

function GetCurrentDir: string;

Description

The GetCurrentDir function returns a string containing the name of the current directory.


See Also

CreateDir function

ExtractFileDir function

RemoveDir function

SetCurrentDir function


GetDir procedure

See Also	Example	I/O routines

Unit

System

Declaration

procedure GetDir(D: Byte; var S: string);

Description

The GetDir procedure returns the current directory of a specified drive.

D can be set to any of the following values:

Value	Drive

0	Default

1	A

2	B

3	C

Performs no error checking. If the drive specified by D is invalid, S returns X:\ as if it were the root directory of the invalid drive.


Example

var

   s : string;

 begin

   GetDir(0,s); { 0 = Current drive }

   MessageDlg('Current drive and directory: ' + s, mtInformation, [mbOk] , 0);

 end;


See also

ChDir function

MkDir procedure

RmDir procedure


GetFormatSettings procedure

Unit

SysUtils

Declaration

procedure GetFormatSettings;

Description

GetFormatSettings resets all date and number format variables to their default values. GetFormatSettings is called in non-console Delphi applications in response to WM_WININICHANGE messages.


GetHeapStatus function

Unit

System

Declaration

function GetHeapStatus: THeapStatus;

Description

The GetHeapStatus function returns the current status of the memory manager in a THeapStatus record.


GetMem procedure

See Also	Example	Dynamic allocation routines

Unit

System

Declaration

procedure GetMem(var P: Pointer; Size: Integer);

Description

The GetMem procedure creates a dynamic variable of the specified size and puts the address of the block in a pointer variable.

P is a variable of any pointer type. Size is an expression specifying the size in bytes of the dynamic variable to allocate. You should reference the newly created variable as P^.


Example

The following example opens a file named 'test.txt' and reads the entire file into a dynamically allocated buffer. The buffer and the size of the file are then passed to a routine that processes the text, and finally the dynamically allocated buffer is freed and the file is closed.

var

  F: file;

  Size: Integer;

  Buffer: PChar;

begin

  AssignFile(F, 'test.txt');

  Reset(F, 1);

  try

    Size := FileSize(F);

    GetMem(Buffer, Size);

    try

      BlockRead(F, Buffer^, Size);

      ProcessFile(Buffer, Size);

    finally

      FreeMem(Buffer);

    end;

  finally

    CloseFile(F);

  end;

end;


See also

Dispose procedure

FreeMem procedure

New procedure


GetMemoryManager procedure

See Also

Unit

System

Declaration

procedure GetMemoryManager(var MemMgr: TMemoryManager);

Description

The GetMemoryManager pocedure returns the entry points of the currently installed memory manager in a TMemoryManager record.


See also

SetMemoryManager procedure


Halt procedure

See Also	Example	Flow control routines

Unit

System

Declaration

procedure Halt [ ( Exitcode: Integer) ];

Description

The Halt procedure performs an abnormal termination of a program and returns to the operating system. To perform a normal termination of Delphi VCL non-console application, call Application.Terminate. Exitcode is an optional expression that specifies the exit code of your program.

Example

begin

   if 1 = 1 then

     begin

       if 2 = 2 then

         begin

           if 3 = 3 then

             begin

               Halt(1); { Halt right here! }

             end;

         end;

     end;

   Canvas.TextOut(10, 10, 'This will not be executed');

 end;


See also

Exit procedure

RunError procedure


Hi function

See Also	Example	Miscellaneous routines

Unit

System

Declaration

function Hi(X): Byte;

Description

The Hi function returns the high-order byte of X as an unsigned value. X is an expression of type Integer or Word.


Example

var B: Byte;

begin

  B := Hi($1234);   { $12 }

end;


See also

Lo function

Swap function


High function

See Also	Example	Transfer routines

Unit

System

Declaration

function High(X);

Description

The High function returns the highest value in the range of the argument.

The result type is X, or the index type of X.

X is either a type identifier or a variable reference. The type denoted by X, or the type of the variable denoted by X, must be one of the following types.

For this type	High returns

Ordinal type	The highest value in the range of the type

Array type	The highest value within the range of the index type of the array

String type	The declared size of the string

Open array 	The value, of type Integer, giving the number of elements in the actual parameter minus one

String parameter	The value, of type Inteeger, giving the number of elements in the actual parameter minus one


Example

function Sum( var X: array of Double): Double;

var

  I: Word;

  S: Double;

begin

  S := 0;  { Note that open array index range is always zero-based. }

  for I := 0 to High(X) do S := S + X[I];

  Sum := S;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  List1: array[0..3] of Double;

  List2: array[5..17] of Double;

  X: Word;

  S, TempStr: string;

begin

  for X := Low(List1) to High(List1) do

    List1[X] := X * 3.4;

    for X := Low(List2) to High(List2) do

    List2[X] := X * 0.0123;

  Str(Sum(List1):4:2, S);

  S := 'Sum of List1: ' + S + #13#10;

  S := S + 'Sum of List2: ';

  Str(Sum(List2):4:2, TempStr);

  S := S + TempStr;

  MessageDlg(S, mtInformation, [mbOk], 0);

end;


See also

Low function


HInstance variable

Unit

System

Declaration

var HInstance: Longint;

Description

The HInstance variable contains the instance handle of the application or library as provided by the Windows environment.


Inc procedure

See Also	Example	Ordinal routines

Unit

System

Declaration

procedure Inc(var X [ ; N: Longint ] );

Description

The Inc procedure adds one or N to the variable X.

X is an ordinal-type variable or a variable of type PChar if the extended syntax is enabled and N is an integer-type expression.

X increments by 1, or by N if N is specified; that is, Inc(X) corresponds to the statement
X := X + 1, and Inc(X, N) corresponds to the statement X := X + N.

Inc generates optimized code and is especially useful in tight loops.

Note:	Inc(S, I) where S is a ShortInt and I is a number greater than 127 will cause an EIntOverFlow exception to be raised if range and overflow checking are on. Under Delphi 1.0 this did not raise an exception.


Example

var

  IntVar: Integer;

  LongintVar: Longint;

begin

  Inc(IntVar);	{ IntVar := IntVar + 1 }

  Inc(LongintVar, 5);	{ LongintVar := LongintVar + 5 }

end;

See also

Dec procedure

Pred function

Succ function


Include procedure

See Also	Miscellaneous routines

Unit

System

Declaration

procedure Include(var S: set of T; I:T);

Description

The Include procedure adds the element I to the set S.

S is a set type variable, and I is an expression of a type compatible with the base
type of S.

The construct Include(S,I) corresponds to S := S + [I] but the Include procedure generates more efficient code.


See also

Exclude procedure


Initialize procedure

See Also

Unit

System

Declaration

procedure Initialize(var V [ ; Count: Integer ] );

Description

The Initialize procedure initializes a dynamically allocated variable. Initialize should be used only in situations where a variable is dynamically allocated by other means than the New standard procedure.

For global variables, local variables, objects, and dynamic variables allocated using the New standard procedure, the compiler generates code that initializes all long strings and variants contained by a variable upon creation of the variable. If a dynamic variable is created by other means than the New standard function (for example using GetMem or ReallocMem), if the variable contains long strings or variants, and if the memory allocated for the variable is not initialized to zeros, a call to Initialize is required to initialize the variable before it can be used. Initialize simply zeros out the memory occupied by long strings and variants, thus causing long strings to be empty and variants to be Unassigned.

In cases where several variables are allocated in a contiguous memory block, the additional Count parameter can be specified to initialize all variables in one operation.

If the variable specified in a call to Initialize contains no long strings and variants, the compiler eliminates the call and generates no code for it.


See also

Finalize procedure


InOutRes variable

Unit

System

Declaration

var InOutRes: Integer;

Description

The built-in I/O routines use the InOutRes variable to store the value that the next call to the IOResult standard function will return.


Input variable

See Also

Unit

System

Declaration

var Input: Text;

Description

The Input variable is a read-only file associated with the operating system's standard input device, which is usually the keyboard.

In many of Delphi's standard file-handling routines, the file variable parameter can be omitted. Instead the routine operates on the Input or Output file variable. The following standard file-handling routines operate on the Input file when no file parameter is specified:

Eof

Eoln

Read

Readln

SeekEof

SeekEoln

When an application is compiled as a console application (using the Generate console application checkbox on the Linker page of the Project|Options dialog, or a -cc command line switch with the command-line compiler), Delphi automatically associates the Input and Output files with the application's console window. For non-console applications, any attempt to read from Input or write to Output will generate an I/O error.


See also

Output variable

TextFile type


Insert procedure

See Also	Example	String handling routines (Pascal style)

Unit

System

Declaration

procedure Insert(Source: string; var S: string; Index: Integer);

Description

The Insert procedure merges a substring into a string beginning at a specified point.

Source is a string-type expression. S is a string-type variable of any length. Index is an integer-type expression. It is a character index and not a byte index.

Insert merges Source into S at the position S[index].


Example

 var

  S: string;

begin

  S := 'Honest Lincoln';

  Insert('Abe ', S, 8);                    { 'Honest Abe Lincoln' }

end;


See also

Concat function

Copy function

Delete procedure

Length function

Pos function


Int function

See Also	Example	Arithmetic routines

Unit

System

Declaration

function Int(X: Real): Real;

Description

The Int function returns the integer part of the argument.

X is a real-type expression. The result is the integer part of X; that is, X rounded toward zero.


Example

var

  R: Real;

begin

  R := Int(123.456);    { 123.0 }

  R := Int(-123.456);   { -123.0 }

end;


See also

Frac function

Round function

Trunc function


IntToHex function

See Also	Example	String handling routines (Pascal style)

Unit

SysUtils

Declaration

function IntToHex(Value: Integer; Digits: Integer): string;

Description

The IntToHex function converts a number into a string containing the number's hexadecimal (base 16) representation . Value is the number to convert. Digits indicates the minimum number of hexadecimal digits to return.


Example

When the user clicks the button on the form, this code converts the number entered in Edit1 to a hexadecimal string. The string displays in Edit2.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit2.Text := IntToHex(StrToInt(Edit1.Text), 6);

end;


See also

IntToStr function


IntToStr function

See Also	Example	String handling routines (Pascal style)

Unit

SysUtils

Declaration

function IntToStr(Value: Integer): string;

Description

The IntToStr function converts an integer into a string containing the decimal representation of that number.


Example

This example uses a button and an edit box on a form. The code assigns a value to the Value variable and displays the string representation of the Value variable in the edit box.

procedure TForm1.Button1Click(Sender: TObject);

var

  Value: Integer;

begin

  Value := 1234;

  Edit1.Text := IntToStr(Value);

end;


See also

IntToHex function

StrToInt function

StrToIntDef function

FloatToStr function

DateToStr function

TimeToStr function


IOResult function

Example	I/O routines

Unit

System

Declaration

function IOResult: Integer;

Description

The IOResult function returns the status of the last I/O operation performed.

I/O-checking must be off--{$I-}--to trap I/O errors using IOResult.

If an I/O error occurs and I/O-checking is off, all subsequent I/O operations are ignored until a call is made to IOResult. Calling IOResult clears the internal error flag.

An alternative way to handle I/O errors is to use exception handling. For more information on handling run-time library exceptions, see Handling RTL Exceptions.


Example

var

  F: file of Byte;

begin

  if OpenDialog1.Execute then begin

    AssignFile(F, OpenDialog1.FileName);

    {$I-}

    Reset(F);

    {$I+}

    if IOResult = 0 then

      MessageDlg('File size in bytes: ' + IntToStr(FileSize(F)),

        mtInformation, [mbOk], 0);

    else

      MessageDlg('File access error', mtWarning, [mbOk], 0);

  end;

end;


IsConsole variable

Unit

System

Declaration

var IsConsole: Boolean;

Description

The IsConsole variable is True if the module was compiled as a console application. This will be True in both an EXE and in a DLL.


IsLibrary variable

Unit

System

Declaration

var IsLibrary: Boolean;

Description

The IsLibrary variable is True if the module is a DLL.


IsValidIdent function

String formatting routines

Unit

SysUtils

Declaration

function IsValidIdent(const Ident: string): Boolean;

Description

IsValidIdent returns True if the given string is a valid Pascal identifier. An identifier is defined as a character from the set ['A'..'Z', 'a'..'z', '_'] followed by zero or more characters from the set ['A'..'Z', 'a'..'z', '0..'9', '_'].

Note:	All component names must be valid Object Pascal identifiers.


Length function

See Also	Example	String Handling Routines (Pascal style)

Unit

System

Declaration

function Length(S: string): Integer;

Description

The Length function returns the number of characters actually used in the string S.

Note: :	The number of characters is not necessarily the number of bytes.


Example

var

  S: string;

begin

  S := 'The Black Knight';

  Canvas.TextOut(10, 10, 'String Length = ' + IntToStr(Length(S)));

end;


See also

Concat function

Copy function

Delete procedure

Insert procedure

Pos function


Ln function

See Also	Example	Arithmetic Routines

Unit

System

Declaration

function Ln(X: Real): Real;

Description

The Ln function returns the natural logarithm (Ln(e) = 1) of the real-type expression X.


Example

var

   e : real;

   S : string;

begin

   e := Exp(1.0);

   Str(ln(e):3:2, S);

   S := 'ln(e) = ' + S;

   Canvas.TextOut(10, 10, S);

end;


See also

Exp function


Lo function

See Also	Example	Miscellaneous Routines

Unit

System

Declaration

function Lo(X): Byte;

Description

The Lo function returns the low-order Byte of the argument X as an unsigned value. X is an expression of type Integer.


Example

var B: Byte;

begin

  B := Lo($1234);   { $34 }

end;


See also

Hi function

Swap function


LoadStr function

String formatting routines

Unit

SysUtils

Declaration

function LoadStr(Ident: Integer): string;

Description

LoadStr loads the string resource given by Ident from the application's executable file. If the string resource does not exist, an empty string is returned.

Moving display strings into string resources makes your application easier to localize without rewriting your program.


LongRec type

See Also

Unit

SysUtils

Declaration

LongRec = packed record
  Lo, Hi: Word;
end;

Description

LongRec declares a utility record that stores the high- and low-order bytes of the specified variable as type Word.

LongRec is useful for typecasting four-byte datatypes (pointers, integers, and so on) to access their low and high words separately.


See also

Hi function

Lo function


Low function

See Also	Example	Transfer Routines

Unit

System

Declaration

function Low(X);

The Low function returns the lowest value in the range of the argument.

Result type is X, or the index type of X where X is either a type identifier or a variable reference.

Type	Low returns

Ordinal type	The lowest value in the range of the type

Array type	The lowest value within the range of the index type of the array

String type	Returns 0

Open array	Returns 0

String parameter	Returns 0


Example

function Sum( var X: array of Double): Double;

var

  I: Word;

  S: Real;

begin

  S := 0;               { Note that open array index range is always zero-based. }

  for I := 0 to High(X) do S := S + X[I];

  Sum := S;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  List1: array[0..3] of Double;

  List2: array[5..17] of Double;

  X: Word;

  S, TempStr: string;

begin

  for X := Low(List1) to High(List1) do

      List1[X] := X * 3.4;

  for X := Low(List2) to High(List2) do

      List2[X] := X * 0.0123;

  Str(Sum(List1):4:2, S);

  S := 'Sum of List1: ' + S + #13#10;

  S := S + 'Sum of List2: ';

  Str(Sum(List2):4:2, TempStr);

  S := S + TempStr;

  MessageDlg(S, mtInformation, [mbOk], 0);

end;


See also

High function


LowerCase function

See Also	Example	String handling routines (Pascal style)

Unit

System

Declaration

function LowerCase(const S: string): string;

Description

The LowerCase function returns a string with the same text as the string passed in S, but with all letters converted to lowercase. The conversion affects only 7-bit ASCII characters between 'A' and 'Z'. To convert 8-bit international characters, use AnsiLowerCase.


Example

This example uses two edit boxes and a button on a form. When the user clicks the button, the text in the Edit1 edit box displays in the Edit2 edit box in lowercase letters.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit2.Text := LowerCase(Edit1.Text);

end;


See also

AnsiLowerCase function

UpperCase function


MkDir procedure

See Also	Example	I/O Routines

Unit

System

Declaration

procedure MkDir(S: string);

Description

The MkDir procedure creates a new subdirectory with the path specified by string S. The last item in the path cannot be an existing file name.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for an I/O error.


Example

uses Dialogs;

begin

  {$I-}

  { Get directory name from TEdit control }

  MkDir(Edit1.Text);

  if IOResult <> 0 then

    MessageDlg('Cannot create directory', mtWarning, [mbOk], 0)

  else

    MessageDlg('New directory created', mtInformation, [mbOk], 0);

end;


See also

ChDir procedure

GetDir procedure

RmDir procedure


Move procedure

See Also	Example	Miscellaneous Routines

Unit

System

Declaration

procedure Move(var Source, Dest; Count: Integer);

Description

The Move procedure copies Count bytes from a Source to Dest. No range-checking is performed.

Move compensates for overlaps between the source and destination blocks. Whenever possible, use SizeOf to determine the count.


Example

var

  A: array[1..4] of Char;

  B: Integer;

begin

  Move(A, B, SizeOf(B));            { SizeOf = safety! }

end;

See also

FillChar procedure

SizeOf function


New procedure

See Also	Example	Dynamic Allocation Routines

Unit

System

Declaration

procedure New(var P: Pointer);

Description

The New procedure creates a new dynamic variable and sets a pointer variable to point to it. P is a variable of any pointer type. The size of the allocated memory block corresponds to the size of the type that P points to. The newly created variable can be referenced as P^. If there isn't enough memory available to allocate the dynamic variable, an EOutOfMemory exception is raised. For more information on handling run-time library exceptions, see Handling RTL Exceptions. in the help system.

When an application is finished using a dynamic variable created with New, it should dispose of the memory allocated for the variable using the Dispose standard procedure.


Example

type

  PListEntry = ^TListEntry;

  TListEntry = record

    Next: PListEntry;

    Text: string;

    Count: Integer;

  end;

var

  List, P: PListEntry;

begin

  ...

  New(P);

  P^.Next := List;

  P^.Text := 'Hello world';

  P^.Count := 1;

  List := P;

  ...

end;


See also

Dispose procedure

FreeMem procedure

GetMem procedure


NewStr function

String Handling Routines (Pascal style)

Unit

SysUtils

Declaration

function NewStr(const S: string): PString;

Description

The NewStr function is provided for backward compatibility only.


Now function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function Now: TDateTime;

Description

The Now function returns the current date and time, corresponding to Date + Time.


Example

This example uses a label and a button on a form. When the user clicks the button, the current date and time appear as the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := 'The date and time is  ' + DateTimeToStr(Now);

end;


See also

Date function

Date and time typed constants

DateTimeToStr function

Time function


Null constant

See Also

Unit

System

Declaration

const Null: Variant;

Description

The Null constant is used to indicate that a variant has no value, but that it has been initialized (and is therefore not Unassigned). Null is used in database applications to indicate missing or unknown data.

Null values propagate through expressions. When used in an expression involving Variant values, a Null causes the result of the entire expression to become Null.

To set a Variant variable to Null, simply assign the Null constant to the variable. To test whether a Variant value is Null, compare it to the Null constant, or use the VarIsNull standard function. When used to a Null variant, the VarType standard function returns varNull.

If you assign Null to a variable of any other type than Variant, an EVariantError exception is raised. Likewise, if you attempt to convert a Null variant to another type (using VarAsType or VarCast), an EVariantError exception is raised.


See also

Unassigned constant

VarIsNull function

VarType function


Odd function

Example	Ordinal Routines

Unit

System

Declaration

function Odd(X: Longint): Boolean;

Description

The Odd function tests if the argument is an odd number.

Odd returns True if X is an odd number.


Example

begin

   if Odd(5) then

     Canvas.TextOut(10, 10, '5 is odd.')

   else

     Canvas.TextOut(10, 10, 'Something is odd!');

 end;


Ord function

See Also	Example	Transfer Routines

Unit

System

Declaration

function Ord(X): Longint;

Description

The Ord function returns the ordinal value of an ordinal-type expression.

X is an ordinal-type expression. The result is of type Longint, and its value is the ordinal position of X.


Example

uses Dialogs;

type

   Colors = (RED,BLUE,GREEN);

var

  S: string;

 begin

   S := 'BLUE has an ordinal value of ' + IntToStr(Ord(BLUE)) + #13#10;

   S := 'The ASCII code for "c" is ' + IntToStr(Ord('c')) +  ' decimal';

   MessageDlg(S, mtInformation, [mbOk], 0);

 end;

See also

Chr function


OutOfMemoryError procedure

Exception handling routines

Unit

SysUtils

Declaration

procedure OutOfMemoryError;

Description

The OutOfMemoryError procedure raises the EOutOfMemory exception.


Output variable

See Also

Unit

System

Declaration

var Output: Text;

Description

The Output variable is a write-only file associated with the operating system's standard output file, which is usually the display.

In many of Delphi's standard file-handling routines, the file variable parameter can be omitted. Instead the routine operates on the Input or Output file variable. The following standard file-handling routines operate on the Output file when no file parameter is specified:

Write

Writeln

When an application is compiled as a console application (using the Generate console application checkbox on the Linker page of the Project|Options dialog, or a -cc command line switch with the command-line compiler), Delphi automatically associates the Input and Output files with the application's console window. For non-console applications, any attempt to read from Input or write to Output will generate an I/O error.


See also

Input variable

TextFile type


ParamCount function

See also	Example	Miscellaneous Routines

Unit

System

Declaration

function ParamCount: Integer;

Description

The ParamCount function returns the number of parameters passed to the program on the command line. Separate parameters with spaces or tabs. Use double quotes to wrap multiple words as one parameter (such as long file names containing spaces).


Example

begin

  if ParamCount = 0 then

    Canvas.TextOut(10, 10, 'No parameters on command line')

  else

    Canvas.TextOut(10, 10, IntToStr(ParamCount) + ' parameter(s)');

end;


See also

ParamStr function


ParamStr function

See also	Example	Miscellaneous Routines

Unit

System

Declaration

function ParamStr(Index: Integer): string;

Description

The ParamStr function returns a specified command-line parameter.

Index is an expression of type Integer. ParamStr returns the parameter from the command line that corresponds to Index, or an empty string if Index is greater than ParamCount. For example, an Index value of 2 returns the second command-line parameter.

ParamStr(0) returns the path and file name of the executing program (for example, C:\TEST\MYPROG.EXE).


Example

var

  I: Word;

  Y: Integer;

begin

  Y := 10;

  for I := 1 to ParamCount do begin

    Canvas.TextOut(5, Y, ParamStr(I));

    Y := Y + Canvas.TextHeight(ParamStr(I)) + 5;

  end;

end;


See also

ParamCount function


Pi function

Arithmetic Routines

Unit

System

Declaration

function Pi: Extended;

Description

The Pi function returns the value of Pi, which is defined as 3.1415926535897932385.


Pos function

See also	Example	String Handling Routines (Pascal style)

Unit

System

Declaration

function Pos(Substr: string; S: string): Integer;

Description

The Pos function searches for a substring in a string.

Substr and S are string-type expressions.

Pos searches for Substr within S and returns an integer value that is the index of the first character of Substr within S.

If Substr is not found, Pos returns zero.


Example

var S: string;

begin

  S := '   123.5';

  { Convert spaces to zeroes }

  while Pos(' ', S) > 0 do

    S[Pos(' ', S)] := '0';

end;


See also

Concat function

Copy function

Delete procedure

Insert procedure

Length function


Pred function

See also	Example	Ordinal Routines

Unit

System

Declaration

function Pred(X);

Description

The Pred function returns the predecessor of the argument.

X is an ordinal-type expression. The result, of the same type as X, is the predecessor
of X.


Example

uses Dialogs;

type

   Colors = (RED,BLUE,GREEN);

 var

   S: string;

 begin

   S := 'The predecessor of 5 is ' + IntToStr(Pred(5)) + #13#10;

   S := S + 'The successor of 10 is ' + IntToStr(Succ(10)) + #13#10;

   if Succ(RED) = BLUE then

     S := S + 'In the type Colors, RED is the predecessor of BLUE.';

   MessageDlg(S, mtInformation, [mbOk], 0);

 end;


See also

Dec procedure

Inc procedure

Succ function


Ptr function

See also	Pointer and Address Routines

Unit

System

Declaration

function Ptr(Address: Integer): Pointer;

The Ptr function converts the given address to a pointer. A call to this function generates no code, but simply treats the 32-bit value given by Address as a pointer. Like nil, the result of Ptr is assignment compatible with all pointer types.


See also

Addr function


Random function

See also	Example	Miscellaneous Routines

Unit

System

Declaration

function Random [ ( Range: Integer) ];

Description

The Random function returns a random number within the range 0 <= X < Range.

If Range is not specified, the result is a real-type random number within the range
0 <= X < 1.

To initialize the random number generator, call Randomize, or assign a value to the RandSeed variable.


Example

var

   I: Integer;

 begin

   Randomize;

   for I := 1 to 50 do begin

     { Write to window at random locations }

     Canvas.TextOut(Random(Width), Random(Height), 'Boo!');

   end;

 end;

Note:	Because the implementation of the Random function may change between compiler versions, we do not recommend using Random for encryption or other purposes that require reproducible sequences of pseudo-random numbers.


See also

Randomize procedure

RandSeed variable


Randomize procedure

See also	Example	Miscellaneous Routines

Unit

System

Declaration

procedure Randomize;

Description

The Randomize procedure initializes the built-in random number generator with a random value (obtained from the system clock).

The random number generator should be initialized by making a call to Randomize, or by assigning a value to RandSeed.


Example

var

   I: Integer;

 begin

   Randomize;

   for I := 1 to 50 do begin

     { Write to window at random locations }

     Canvas.TextOut(Random(Width), Random(Height), 'Boo!');

   end;

 end;


See also

Random function

RandSeed variable


RandSeed variable

See also

Unit

System

Declaration

var RandSeed: LongInt;

Description

The RandSeed variable stores the built-in random number generator's seed. By assigning a specific value to RandSeed, the Random function can repetitively generate a specific sequence of random numbers. This is useful for applications that deal with data statistics and simulations. For applications that deal with encryption see the note under the Random function.


See also

Random function

Randomize procedure


Read procedure

See also	Example	Text File Routines

Unit

System

Declaration

Typed files:

procedure Read(F , V1 [, V2,...,Vn ] );

Text files:

procedure Read( [ var F: Text; ] V1 [, V2,...,Vn ] );

Description

The Read procedure can be used in the following ways.

For typed files, it reads a file component into a variable.

For text files, it reads one or more values into one or more variables.

With a type string variable

Read reads all characters up to, but not including, the next end-of-line marker or until Eof(F) becomes True; it does not skip to the next line after reading. If the resulting string is longer than the maximum length of the string variable, it is truncated.

After the first Read, each subsequent Read sees the end-of-line marker and returns a zero-length string.

Use multiple Readln calls to read successive string values.

When the extended syntax is enabled, Read can read null-terminated strings into zero-based character arrays.

With a type character variable

Read reads one character from the file and assigns it to the variable. If Eof(F) was True before Read was executed, the value Chr(26) (a Ctrl-Z character) is assigned to the variable.

With type integer or type real variables

Read skips any blanks, tabs, or end-of-line markers preceding the numeric string.

If the numeric string does not conform to the expected format, an I/O error occurs; otherwise, the value is assigned to the variable.

The next Read starts with the blank, tab, or end-of-line marker that terminated the numeric string.


Example

uses Dialogs;

 var

  F1, F2: TextFile;

  Ch: Char;

begin

  if OpenDialog1.Execute then begin

    AssignFile(F1, OpenDialog1.Filename);

    Reset(F1);

    if SaveDialog1.Execute then begin

      AssignFile(F2, OpenDialog1.Filename);

      Rewrite(F2);

      while not Eof(F1) do

      begin

        Read(F1, Ch);

        Write(F2, Ch);

      end;

      CloseFile(F2);

    end;

    CloseFile(F1);

  end;

end.


See also

Eof function

Readln procedure

Write procedure

Writeln procedure


Readln procedure

See also	Example	Text File Routines

Unit

System

Declaration

procedure Readln([ var F: Text; ] V1 [, V2, ...,Vn ]);

Description

The Readln procedure reads a line of text and then skips to the next line of the file.

Readln(F) with no parameters causes the current file position to advance to the beginning of the next line if there is one; otherwise, it goes to the end of the file.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions. If you are using {$I-}, you must use IOResult to check for I/O errors.

When an application is compiled as a console application (using the Generate console application checkbox on the Linker page of the Project|Options dialog, or a -cc command line switch with the command-line compiler), Delphi automatically associates the Input and Output files with the application's console window. For non-console applications, any attempt to read from Input or write to Output will generate an I/O error.


Example

var

   s : string;

 begin

   Write('Enter a line of text: ');

   Readln(s);

   Writeln('You typed: ',s);

   Writeln('Hit <Enter> to exit');

   Readln;

 end;


See also

Read procedure

Writeln procedure


ReallocMem procedure

See also	Memory Management Routines

Unit

Systems

Declaration

procedure ReallocMem(var P: Pointer; Size: Integer);

Description

ReallocMem reallocates a dynamic variable. On entry, P must be nil or point to a dynamic variable that was previously allocated with GetMem or ReallocMem.

If P is nil and Size is zero, ReallocMem does nothing.

If P is nil and Size is not zero, ReallocMem allocates a new block of the given size and sets P to point to the block. This corresponds to a call to GetMem.

If P is not nil and Size is zero, ReallocMem disposes the block referenced by P and sets P to nil. This corresponds to a call to FreeMem, except that FreeMem doesn't clear the pointer.

If P is not nil and Size is not zero, ReallocMem reallocates the block referenced by P to the size given by Size. Existing data in the block is not affected by the reallocation, but if the block is made larger, the contents of the newly allocated portion of the block is undefined. If the block cannot be reallocated in place, it is moved to a new location in the heap, and P is updated accordingly.


See also

AllocMem function


RemoveDir function

See Also

Unit

SysUtils

Declaration

function RemoveDir(const Dir: string): Boolean;

Description

The RemoveDir function deletes an existing empty directory. The return value is True if a new directory was successfully deleted, or False if an error occurred.


See Also

ExtractFileDir function

GetCurrentDir function

RemoveDir function

SetCurrentDir function


Rename procedure

See also	Example	I/O Routines

Unit

System

Declaration

procedure Rename(var F; Newname);

Description

The Rename procedure changes the name of an external file.

F is a variable of any file type. Newname is a string-type expression or an expression of type PChar if the extended syntax is enabled.

The external file associated with F is renamed Newname. Further operations on F operate on the external file with the new name.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

uses Dialogs;

var

   f : file;

 begin

   OpenDialog1.Title := 'Choose a file... ';

   if OpenDialog1.Execute then begin

     SaveDialog1.Title := 'Rename to...';

     if SaveDialog1.Execute then begin

       AssignFile(f, OpenDialog1.FileName);

       Canvas.TextOut(5, 10, 'Renaming ' + OpenDialog1.FileName + ' to ' +

         SaveDialog1.FileName);

       Rename(f, SaveDialog1.FileName);

     end;

   end;

 end;


See also

Erase procedure


RenameFile function

See also	Example	File Management Routines

Unit

SysUtils

Declaration

function RenameFile(const OldName, NewName: string): Boolean;

Description

The RenameFile function attempts to change the name of the file specified by OldFile to NewFile. If the operation succeeds, RenameFile returns True. If it cannot rename the file (for example, if a file called NewName already exists), it returns False.


Example

The following code renames a file:

if not RenameFile('OLDNAME.TXT','NEWNAME.TXT') then

  ErrorMsg('Error renaming file!');


See also

DeleteFile function


Reset procedure

See also	Example	I/O Routines

Unit

System

Declaration

procedure Reset(var F [: File; RecSize: Word ] );

Description

The Reset procedure opens an existing file.

F is a variable of any file type associated with an external file using AssignFile. RecSize is an optional expression, which can be specified only if F is an untyped file. If F is an untyped file, RecSize specifies the record size to be used in data transfers. If RecSize is omitted, a default record size of 128 bytes is assumed.

Reset opens the existing external file with the name assigned to F. An error results if no existing external file of the given name exists. If F is already open, it is first closed and then reopened. The current file position is set to the beginning of the file.

If F is assigned an empty name, such as AssignFile(F, ''), then after the call to Reset, F refers to the standard input file.

If F is a text file, F becomes read-only.

After a call to Reset, Eof(F) is True if the file is empty; otherwise, Eof(F) is False.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

function FileExists(FileName: string): Boolean;

{ Boolean function that returns True if the file exists; otherwise,

  it returns False. Closes the file if it exists. }

 var

  F: file;

begin

  {$I-}

  AssignFile(F, FileName);

  FileMode := 0;  ( Set file access to read only }

  Reset(F);

  CloseFile(F);

  {$I+}

  FileExists := (IOResult = 0) and (FileName <> '');

end;  { FileExists }

begin

  if FileExists(ParamStr(1)) then {Get file name from command line}

    Canvas.TextOut(10, 10, 'File exists')

  else

    Canvas.TextOut(10, 10, 'File not found');

end;


See also

Append procedure

AssignFile procedure

FileClose procedure

Rewrite procedure

Truncate procedure


Rewrite procedure

See also	Example	I/O Routines

Unit

System

Declaration

procedure Rewrite(var F: File [; Recsize: Word ] );

Description

The Rewrite procedure creates and opens a new file.

F is a variable of any file type associated with an external file using AssignFile. RecSize is an optional expression, which can be specified only if F is an untyped file. If F is an untyped file, RecSize specifies the record size to be used in data transfers. If RecSize is omitted, a default record size of 128 bytes is assumed.

Rewrite creates a new external file with the name assigned to F.

If an external file with the same name already exists, it is deleted and a new empty file is created in its place.

If F is already open, it is first closed and then re-created. The current file position is set to the beginning of the empty file.

If F was assigned an empty name, such as AssignFile(F,''), then after the call to Rewrite, F refers to the standard output file.

If F is a text file, F becomes write-only.

After calling Rewrite, Eof(F) is always True.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var F: TextFile;

begin

  AssignFile(F, 'NEWFILE.$$$');

  Rewrite(F);

  Writeln(F, 'Just created file with this text in it...');

  CloseFile(F);

end;


See also

Append procedure

AssignFile procedure

Reset procedure

Truncate procedure


RmDir procedure

See also	Example	I/O Routines

Unit

System

Declaration

procedure RmDir(S: string);

Description

The RmDir procedure deletes an empty subdirectory.

RmDir removes the subdirectory with the path specified by S. If the path does not exist, is non-empty, or is the currently logged directory, an I/O error occurs.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

uses Dialogs;

begin

   {$I-}

   { Get directory name from TEdit control }

   RmDir(Edit1.Text);

   if IOResult <> 0 then

     MessageDlg('Cannot remove directory', mtWarning, [mbOk], 0)

   else

     MessageDlg('Directory removed', mtInformation, [mbOk], 0);

 end;


See also

ChDir procedure

GetDir procedure

MkDir procedure


Round function

See also	Example	Transfer Routines

Unit

System

Declaration

function Round(X: Extended): Longint;

Description

The Round function rounds a real-type value to an integer-type value.

X is a real-type expression. Round returns a Longint value that is the value of X rounded to the nearest whole number. If X is exactly halfway between two whole numbers, the result is the number with the greatest absolute magnitude.

If the rounded value of X is not within the Longint range, you will generate a run-time error, which you can handle using the EInvalidOp exception.


Example

var

   S, T: string;

begin

   Str(1.4:2:1, T);

   S := T + ' rounds to ' + IntToStr(Round(1.4)) + #13#10;

   Str(1.5:2:1, T);

   S := S + T + ' rounds to ' + IntToStr(Round(1.5)) + #13#10;

   Str(-1.4:2:1, T);

   S := S + T + ' rounds to ' + IntToStr(Round(-1.4)) + #13#10;

   Str(-1.5:2:1, T);

   S := S + T + ' rounds to ' + IntToStr(Round(-1.5));

   MessageDlg(S, mtInformation, [mbOk], 0);

end;


See also

Int function

Trunc function


RunError procedure

See Also	Example	Flow Control Routines

Unit

System

Declaration

procedure RunError [ ( Errorcode: Byte ) ];

Description

The RunError procedure stops program execution by generating a run-time error with the given number at the current statement. Errorcode is the run-time error number (0 if omitted).


Example

begin

{$IFDEF Debug}

  if P = nil then

    RunError(204);

{$ENDIF}

end;


See also

Exit procedure

Halt procedure


Seek procedure

See Also	Example	I/O Routines

Unit

System

Declaration

procedure Seek(var F; N: Longint);

Description

The Seek procedure moves the current position of a file to a specified component. You can use Seek only on open typed or untyped files.

In the above syntax, F is a typed or untyped file variable, and N is an expression of type Longint.

The current file position of F moves to component number N. The number of the first component of a file is 0.

To expand a file, you can seek one component beyond the last component; that is, the statement Seek(F, FileSize(F)) moves the current file position to the end of the file.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

uses Dialogs;

var

   f: file of Byte;

   size : Longint;

   S: string;

   y: integer;

 begin

   if OpenDialog1.Execute then begin

     AssignFile(f, OpenDialog1.FileName);

     Reset(f);

     size := FileSize(f);

     S := 'File size in bytes: ' + IntToStr(size);

     y := 10;

     Canvas.TextOut(5, y, S);

     y := y + Canvas.TextHeight(S) + 5;

     S := 'Seeking halfway into file...';

     Canvas.TextOut(5, y, S);

     y := y + Canvas.TextHeight(S) + 5;

     Seek(f,size div 2);

     S := 'Position is now ' + IntToStr(FilePos(f));

     Canvas.TextOut(5, y, S);

     CloseFile(f);

   end;

 end;


See also

FilePos function


SeekEof function

See Also	Example	Text File Routines

Unit

System

Declaration

function SeekEof [ (var F: Text) ]: Boolean;

Description

The SeekEof function returns the end-of-file status of a file.

SeekEof can only be used on open text files.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

   f : System.TextFile;

   i, j, Y : Integer;

 begin

   AssignFile(f,'TEST.TXT');

   Rewrite(f);

   { Create a file with 8 numbers and some

     whitespace at the ends of the lines }

   Writeln(f,'1 2 3 4 ');

   Writeln(f,'5 6 7 8 ');

   Reset(f);

   { Read the numbers back. SeekEoln returns TRUE if there are no more numbers on the

     current line; SeekEof returns TRUE if there is no more text (other than whitespace)

     in the file. }

   Y := 5;

   while not SeekEof(f) do

   begin

     if SeekEoln(f) then

       Readln; { Go to next line }

     Read(f,j);

     Canvas.TextOut(5, Y, IntToStr(j));

     Y := Y + Canvas.TextHeight(IntToStr(j)) + 5;

   end;

 end;

See also

Eof function

SeekEoln function


SeekEoln function

See Also	Example	Text File Routines

Unit

System

Declaration

function SeekEoln [ (var F: Text) ]: Boolean;

Description

The SeekEoln function returns the end-of-line status of a file.

SeekEoln can be used only on open text files.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.

Example

var

   f : System.TextFile;

   i, j, Y : Integer;

 begin

   AssignFile(f,'TEST.TXT');

   Rewrite(f);

   { Create a file with 8 numbers and some

     whitespace at the ends of the lines }

   Writeln(f,'1 2 3 4 ');

   Writeln(f,'5 6 7 8 ');

   Reset(f);

   { Read the numbers back. SeekEoln returns TRUE if there are no more numbers on the

     current line; SeekEof returns TRUE if there is no more text (other than whitespace)

     in the file. }

   Y := 5;

   while not SeekEof(f) do

   begin

     if SeekEoln(f) then

       Readln; { Go to next line }

     Read(f,j);

     Canvas.TextOut(5, Y, IntToStr(j));

     Y := Y + Canvas.TextHeight(IntToStr(j)) + 5;

   end;

 end;


See also

Eoln function

SeekEof function


SetCurrentDir function

See Also

Unit

SysUtils

Declaration

function SetCurrentDir(const Dir: string): Boolean;

Description

The SetCurrentDir function sets the current directory. The return value is True if the current directory was successfully changed, or False if an error occurred.


See Also

CreateDir function

ExtractFileDir function

GetCurrentDir function

RemoveDir function


SetLength procedure

Unit

System

Declaration

procedure SetLength(var S: string; NewLength: Integer);

Description

The SetLength procedure sets the dynamic length of a string variable.

For a short string variable, SetLength simply sets the length indicator character (the character at S[0]) to the given value. In this case, NewLength must be a value between 0 and 255.

For a long string variable, SetLength reallocates the string referenced by S to the given new length. Any existing characters in the string are preserved, but the contents of any newly allocated space is undefined. If there is not enough memory available to reallocate the string, an EOutOfMemory exception is raised. Following a call to SetLength, S is guaranteed to reference a unique string, that is a string with a reference count of one.


SetMemoryManager procedure

See Also	Example

Unit

System

Declaration

procedure SetMemoryManager(const MemMgr: TMemoryManager);

Description

The SetMemoryManager procedure sets the entry points of the memory manager to the three functions specified by the MemMgr parameter. Using SetMemoryManager you can change the memory allocation routines that are used for:

The GetMem, ReallocMem, and FreeMem standard procedures.

The New and Dispose standard procedures.

Allocation and deallocation of objects through constructors and destructors.

Allocation and deallocation of dynamic strings.

The GetMem field of the MemMgr parameter must point to a function that allocates the given number of bytes and returns a pointer to the newly allocated block. The Size parameter passed to the GetMem function will never be zero. If the GetMem function cannot allocate a block of the given size, it should return nil.

The FreeMem field of the MemMgr parameter must point to a function that deallocates the given block. The pointer parameter passed to the FreeMem function will never be nil. If the FreeMem function successfully deallocates the given block, it should return zero. Otherwise, it should return a non-zero value.

The ReallocMem field of the MemMgr parameter must point to a function that reallocates the given block to the given new size. The pointer parameter passed to the ReallocMem function will never be nil, and the Size parameter will never be zero. The ReallocMem function must reallocate the given block to the given new size, possibly moving the block if it cannot be resized in place. Any existing contents of the block must be preserved, but newly allocated space can be uninitialized. The ReallocMem function must return a pointer to the reallocated block, or nil if the block cannot be reallocated.


Example

The following example implements a memory manager that counts the number of times the GetMem, FreeMem, and ReallocMem entry points are called. The new memory manager is installed through a call to the SetNewMemMgr routine. Notice how the new memory manager routines simply pass on the requests to the previous memory manager after incrementing the appropriate counter.

var

  GetMemCount: Integer;

  FreeMemCount: Integer;

  ReallocMemCount: Integer;

  OldMemMgr: TMemoryManager;

function NewGetMem(Size: Integer): Pointer;

begin

  Inc(GetMemCount);

  Result := OldMemMgr.GetMem(Size);

end;

function NewFreeMem(P: Pointer): Integer;

begin

  Inc(FreeMemCount);

  Result := OldMemMgr.FreeMem(P);

end;

function NewReallocMem(P: Pointer; Size: Integer): Pointer;

begin

  Inc(ReallocMemCount);

  Result := OldMemMgr.ReallocMem(P, Size);

end;

const

  NewMemMgr: TMemoryManager = (

  GetMem: NewGetMem;

  FreeMem: NewFreeMem;

  ReallocMem: NewReallocMem);

procedure SetNewMemMgr;

begin

  GetMemoryManager(OldMemMgr);

  SetMemoryManager(NewMemMgr);

end;


See also

GetMemoryManager procedure


SetString procedure

Unit

System

Declaration

procedure SetString(var s: string; buffer: PChar; len: Integer);

Description

The SetString standard procedure sets the contents and length of the given string variable to the block of characters given by the Buffer and Len parameters.

For a short string variable, SetString sets the length indicator character (the character at S[0]) to the value given by Len and then, if the Buffer parameter is not nil, copies Len characters from Buffer into the string starting at S[1]. For a short string variable, the Len parameter must be a value between 0 and 255.

For a long string variable, SetString sets S to reference a newly allocated string of the given length. If the Buffer parameter is not nil, SetString then copies Len characters from Buffer into the string; otherwise, the contents of the new string is left uninitialized. If there is not enough memory available to create the string, an EOutOfMemory exception is raised. Following a call to SetString, S is guaranteed to reference a unique string, that is a string with a reference count of one.


SetTextBuf procedure

See Also	Example	Text File Routines

Unit

System

Declaration

procedure SetTextBuf(var F: Text; var Buf [ ; Size: Integer] );

Description

The SetTextBuf procedure assigns an I/O buffer to a text file.

F is a text file variable, Buf is any variable, and Size is a optional expression.

Each Text file variable has an internal 128-byte buffer that buffers Read and Write operations. This buffer is adequate for most operations. However, heavily I/O-bound programs benefit from a larger buffer to reduce disk head movement and file system overhead.

SetTextBuf changes the text file F to use the buffer specified by Buf instead of F's internal buffer. Size specifies the size of the buffer in bytes. If Size is omitted, SizeOf(Buf) is assumed. The new buffer remains in effect until F is next passed to AssignFile.

SetTextBuf can be called immediately after Reset, Rewrite, and Append, but never apply it to an open file.

If you call SetTextBuf on an open file once I/O operations have taken place, you could lose data because of the change of buffer.

Delphi does not ensure that the buffer exists for the entire duration of I/O operations on the file. A common error is to install a local variable as a buffer, then use the file outside the procedure that declared the buffer.


Example

uses Dialogs;

var

  F, FTwo: System.TextFile;

  Ch: Char;

  Buf: array[1..4095] of Char;  { 4K buffer }

begin

  if OpenDialog1.Execute then begin

    AssignFile(F, ParamStr(1));

    { Bigger buffer for faster reads }

    SetTextBuf(F, Buf);

    Reset(F);

    { Dump text file into another file }

    AssignFile(FTwo, 'WOOF.DOG');

    Rewrite(FTwo);

    while not Eof(f) do

    begin

      Read(F, Ch);

      Write(FTwoCh);

    end;

    System.CloseFile(F);

    System.CloseFile(FTwo);

  end;

end;


See also

Append procedure

AssignFile procedure

Read procedure

Reset procedure

Rewrite procedure

SizeOf function

Write procedure


ShowException procedure

Exception handling routines

Unit

SysUtils

Declaration

procedure ShowException(ExceptObject: TObject; ExceptAddr: Pointer);

Description

This procedure displays the message associated with an exception, together with the exception's physical address. The exception's address can be used with Search|Find Error menu command to find the statement that raised the exception.


Sin function

See Also	Example	Arithmetic Routines

Unit

System

Declaration

function Sin(X: Extended): Extended;

Description

The Sin function returns the sine of the argument.

X is a real-type expression. Sin returns the sine of the angle X in radians.


Example

var

  R: Extended;

  S: string;

begin

  R := Sin(Pi);

  Str(R:5:3, S);

  Canvas.TextOut(10, 10, 'The Sin of Pi is ' + S);

end;


See also

ArcTan function

Cos function


SizeOf function

See Also	Example	Miscellaneous Routines

Unit

System

Declaration

function SizeOf(X): Integer;

Description

The SizeOf function returns the number of bytes occupied by X.

X is either a variable reference or a type identifier.

Always use SizeOf when passing values to FillChar, Move, and GetMem.


Example

type

  CustRec = record

    Name: string[30];

    Phone: string[14];

  end;

 var

  P: ^CustRec;

begin

  GetMem(P, SizeOf(CustRec));

  Canvas.TextOut(10, 10, 'The size of the record is ' + IntToStr(SizeOf(CustRec)));

  FreeMem (P, SizeOf(CustRec));

  Readln;

end;


See also

FillChar procedure

GetMem procedure

Move procedure


Slice function

Unit

System

Declaration

function Slice(var A: array; Count: Integer): array;

Description

The Slice standard function allows you to select a sub-section (slice) of an array to be passed as an open array parameter. Slice is only allowed as an actual parameter in a call to a procedure or function that expects an open array parameter. Slice selects the first Count elements of the array given by A to be passed as an open array parameter. A can itself be an open array parameter. This alllows you to pass dynamically allocated arrays to open array parameters.


Sqr function

See Also	Example	Arithmetic Routines

Unit

System

Declaration

function Sqr(X: Extended): Extended;

Description

The Sqr function returns the square of the argument.

X is a floating-point expression. The result, of the same type as X, is the square of X, or X*X.


Example

var

  S, Temp: string;

begin

   Str(Sqr(5.0):3:1, Temp);

   S := '5 squared is ' + Temp + #13#10;

   Str(Sqrt(2.0):5:4, Temp);

   S := S + 'The square root of 2 is ' + Temp;

   MessageDlg(S, mtInformation, [mbOk], 0);

end;


See also

Sqrt function


Sqrt function

See Also	Example	Arithmetic Routines

Unit

System

Declaration

function Sqrt(X: Extended): Extended;

Description

The Sqrt function returns the square root of the argument.

X is a floating-point expression. The result is the square root of X.


Example

var

  S, Temp: string;

begin

   Str(Sqr(5.0):3:1, Temp);

   S := '5 squared is ' + Temp + #13#10;

   Str(Sqrt(2.0):5:4, Temp);

   S := S + 'The square root of 2 is ' + Temp;

   MessageDlg(S, mtInformation, [mbOk], 0);

end;


See also

Sqr function


Str procedure

See Also	Example	String Handling Routines (Pascal style)

Unit

System

Declaration

procedure Str(X [: Width [: Decimals ]]; var S);

Description

The Str procedure converts X to a string representation according to the Width and Decimals formatting parameters. The effect is like a call to Write except the resulting string is stored in S instead of being written to a text file.

X is an integer-type or real-type expression. Width and Decimals are integer-type expressions. S is a string-type variable or a zero-based character array variable if extended syntax is enabled.


Example

function MakeItAString(I: Longint): string;

{ Convert any integer type to a string }

var

  S: string[11];

begin

  Str(I, S);

  MakeItAString:= S;

end;

begin

  Canvas.TextOut(10, 10, MakeItAString(-5322));

end;


See also

Val procedure

Write procedure


StrAlloc function

String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrAlloc(Size: Cardinal): PChar;

Description

This function allocates a buffer for a null-terminated string with a maximum length of Size - 1 (1 byte must be reserved for the termination character). The result points to the location where the first character of the string is to be stored. A 32-bit number giving the total amount of memory allocated is stored in the four bytes preceding the first character; it is equal to Size + 4. If space for a string is allocated with StrAlloc, it should be deallocated via StrDispose.

StrAlloc is used by NewStr and is a general purpose routine. Since long strings are implicitly null terminated and dynamically allocated, the use of StrAlloc is in decline.


StrBufSize function

String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrBufSize(Str: PChar): Cardinal;

Description

This function returns the maximum number of characters that can be stored in a string buffer allocated by StrAlloc. This number includes the termination character. If Str does not point to a string buffer allocated by StrAlloc, no error message is returned, and the result is unpredictable.


StrCat function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrCat(Dest, Source: PChar): PChar;

Description

The StrCat function appends a copy of Source to the end of Dest and returns the concatenated string.

StrCat does not perform any length checking. The destination buffer must have room for at least StrLen(Dest)+StrLen(Source)+1 characters.

If you want length checking, use the StrLCat function.


Example

uses SysUtils;

const

  Obj: PChar = 'Object';

  Pascal: PChar = 'Pascal';

 var

  S: array[0..15] of Char;

begin

  StrCopy(S, Obj);

  StrCat(S, ' ');

  StrCat(S, Pascal);

  Canvas.TextOut(10, 10, StrPas(S));

end;


See also

StrLCat function


StrComp function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrComp(Str1, Str2 : PChar): Integer;

Description

The StrComp function compares Str1 to Str2.

Return value	Condition

<0	if Str1< Str2

=0	if Str1= Str2

>0	if Str1 > Str2


Example

uses SysUtils;

const

  S1: PChar = 'Wacky';

  S2: PChar = 'Code';

var

  C: Integer;

  Result: string;

begin

  C := StrComp(S1, S2);

  if C < 0 then Result := ' is less than ' else

    if C > 0 then Result := ' is greater than ' else

      Result := ' is equal to ';

  Canvas.TextOut(10, 10, StrPas(S1) + Result + StrPas(S2));

end;


See also

StrIComp function

StrLComp function

StrLIComp function


StrCopy function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrCopy(Dest, Source: PChar): PChar;

Description

The StrCopy function copies Source to Dest and returns Dest.

StrCopy does not perform any length checking. The destination buffer must have room for at least StrLen(Source)+1 characters.

If you want to use length checking, use the StrLCopy function.


Example

uses SysUtils;

var

  S: array[0..12] of Char;

begin

  StrCopy(S, 'ObjectPascal');

  Canvas.TextOut(10, 10, StrPas(S));

end;


See also

StrECopy function

StrLCopy function


StrDispose procedure

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

procedure StrDispose(Str: PChar);

Description

The StrDispose procedure is provided for backwards compatibility only. StrDispose disposes of a string on a heap that was previously allocated with StrAlloc or StrNew.

If Str is nil, StrDispose does nothing.


See also

StrAlloc function

StrNew function


StrECopy function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrECopy(Dest, Source: PChar): PChar;

Description

The StrECopy function copies Source to Dest and returns StrEnd(Dest).

StrECopy does not perform any length checking. The destination buffer must have room for at least StrLen(Source)+1 characters.

Nested calls to StrECopy to concatenate a sequence of strings will run more efficiently than multiple calls to StrCat.


Example

uses SysUtils;

const

  Turbo: PChar = 'Object';

  Pascal: PChar = 'Pascal';

 var

  S: array[0..15] of Char;

begin

  StrECopy(StrECopy(StrECopy(S, Turbo), ' '), Pascal);

  Canvas.TextOut(10, 10, StrPas(S));

end;


See also

StrCat function

StrCopy function

StrEnd function


StrEnd function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrEnd(Str: PChar): PChar;

Description

The StrEnd function returns a pointer to the null character at the end of Str.


Example

uses SysUtils;

const

  S: PChar = 'Yankee Doodle';

begin

  Canvas.TextOut(5, 10, 'The string length of "' + StrPas(S) + '" is ' +

    IntToStr(StrEnd(S) - S));

end;


See also

StrLen function


StrFmt function

String Formatting Routines

Unit

SysUtils

Declaration

function StrFmt(Buffer, Format: PChar; const Args: array of const): PChar;

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the null-terminated format string Format; the results are returned in Buffer. The function result contains a pointer to the destination buffer.

For information on the format strings, see Format Strings.


StringOfChar function

Unit

System

Declaration

function StringOfChar(Ch: Char; Count: Integer): string;

Description

The StringOfChar function returns a string containing Count characters with the character value given by Ch. For example,

S := StringOfChar('A', 10);

sets S to the string 'AAAAAAAAAA'.


StringToWideChar function

Wide character routines

Unit

System

Declaration

function StringToWideChar(const Source: string; Dest: PWideChar; DestSize: Integer): PWideChar;

Description

The StringToWideChar function converts the string given by Source from ANSI to UNICODE and stores the result in the buffer given by Dest and DestSize. Following the call, the Dest buffer contains at most DestSize - 1 characters from the source string, terminated by a NULL wide character. The function result value is Dest.


StrIComp function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrIComp(Str1, Str2:PChar): Integer;

Description

The StrIComp function compares Str1 to Str2 without case sensitivity. The return value is the same as StrComp.


Example

uses SysUtils;

const

  S1: PChar = 'Wacky';

  S2: PChar = 'Code';

var

  C: Integer;

  Result: string;

begin

  C := StrIComp(S1, S2);

  if C < 0 then Result := ' is less than ' else

    if C > 0 then Result := ' is greater than ' else

      Result := ' is equal to ';

  Canvas.TextOut(10, 10, StrPas(S1) + Result + StrPas(S2));

end;


See also

StrComp function

StrLComp function

StrLIComp function


StrLCat function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrLCat(Dest, Source: PChar; MaxLen: Cardinal): PChar;

Description

The StrLCat function appends at most MaxLen - StrLen(Dest) characters from Source to the end of Dest and returns Dest. The SizeOf standard function can be used to determine the MaxLen parameter.


Example

uses SysUtils;

var

  S: array[0..13] of Char;

begin

  StrLCopy(S, 'Object', SizeOf(S) - 1);

  StrLCat(S, ' ', SizeOf(S) - 1);

  StrLCat(S, 'Pascal', SizeOf(S) - 1);

  Canvas.TextOut(10, 10, StrPas(S));

end;


See also

SizeOf function

StrCat function


StrLComp function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrLComp(Str1, Str2: PChar; MaxLen: Cardinal): Integer;

Description

The StrLComp function compares Str1 to Str2, up to a maximum length of MaxLen characters. The return value is the same as StrComp.


Example

uses SysUtils;

const

  S1: PChar = 'Enterprise'

  S2: PChar = 'Enter'

var

  Result: string;

begin

  if StrLComp(S1, S2, 5) = 0 then

    Result := 'equal'

  else

    Result := 'different';

  Canvas.TextOut(10, 10, 'The first five characters are ' + Result);

end;


See also

StrComp function

StrIComp function

StrLIComp function


StrLCopy function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrLCopy(Dest, Source: PChar; MaxLen: Cardinal): PChar;

Description

The StrLCopy function copies at most MaxLen characters from Source to Dest and returns Dest. The SizeOf standard function can be used to determine the MaxLen parameter.


Example

uses SysUtils;

var

  S: array[0..11] of Char;

begin

  StrLCopy(S, 'ObjectPascal', SizeOf(S) - 1);

  Canvas.TextOut(10, 10, StrPas(S));

end;


See also

SizeOf function

StrCopy function


StrLen function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrLen(Str: PChar): Cardinal;

Description

The StrLen function returns the number of characters in Str, not counting the null terminator.


Example

uses SysUtils;

const

  S: PChar = 'E Pluribus Unum';

begin

  Canvas.TextOut(5, 10, 'The string length of "' + StrPas(S) + '" is ' +

    IntToStr(StrLen(S)));

end;


See also

StrEnd function


StrLFmt function

See Also	String Formatting Routines

Unit

SysUtils

Declaration

function StrLFmt(Buffer: PChar; MaxLen: Cardinal; Format: PChar; const Args: array of const): PChar;

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the null-terminated format string Format; the results are returned in Buffer, whose maximum length is given by MaxLen. The function result contains a pointer to the destination buffer.

For information on the format strings, see Format Strings.


See also

FormatBuf function

StrFmt function

FmtStr procedure


StrLIComp function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrLIComp(Str1, Str2: PChar; MaxLen: Cardinals): Integer;

Description

StrLIComp compares Str1 to Str2 , up to a maximum length of MaxLen characters, without case sensitivity.

The return value is the same as StrComp.


Example

uses SysUtils;

const

  S1: PChar = 'Enterprise'

  S2: PChar = 'Enter'

var

  Result: string;

begin

  if StrLIComp(S1, S2, 5) = 0 then

    Result := 'equal'

  else

    Result := 'different';

  Canvas.TextOut(10, 10, 'The first five characters are ' + Result);

end;


See also

StrComp function

StrIComp function

StrLComp function


StrLower function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrLower(Str: PChar): PChar;

Description

The StrLower function converts Str to lowercase and returns Str.


Example

uses SysUtils;

const

  S: PChar = 'A fUnNy StRiNg'

begin

  Canvas.TextOut(5, 10, StrPas(StrLower(S)) + ' ' + StrPas(StrUpper(S)));

end;


See also

AnsiLowerCase function

LowerCase function

StrUpper function


StrMove function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrMove(Dest, Source: PChar; Count: Cardinal): PChar;

Description

The StrMove function copies exactly Count characters from Source to Dest and returns Dest. Source and Dest can overlap.


Example

uses SysUtils;

function AHeapaString(S: PChar): PChar;

{ Allocate string on heap }

 var

  L: Cardinal;

  P: PChar;

begin

 StrNew := nil;

 if (S <> nil) and (S[0] <> #0) then

  begin

    L := StrLen(S) + 1;

    GetMem(P, L);

    StrNew := StrMove(P, S, L);

  end;

end;

procedure DisposeDaString(S: PChar);

{ Dispose string on heap }

begin

  if S <> nil then FreeMem(S, StrLen(S) + 1);

end;

var

  S: PChar;

begin

  AHeapaString(S);

  DisposeDaString(S);

end;


See also

Move procedure


StrNew function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrNew(Str: PChar): PChar;

Description

The StrNew function allocates a copy of Str on the heap.

If Str is nil or points to an empty string, StrNew returns a pointer to a new empty string.

Otherwise, StrNew makes a duplicate of Str, obtaining space with a call to the StrAlloc procedure, and returns a pointer to the duplicated string.

The allocated space is StrLen(Str) + 5 bytes long.


Example

uses SysUtils;

const

  S: PChar = 'Nevermore';

 var

  P: PChar;

begin

  P := StrNew(S);

  Canvas.TextOut(10, 10, StrPas(P));

  StrDispose(P);

end;


See also

GetMem procedure

StrDispose function


StrPas function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrPas(Str: PChar): string;

Description

The StrPas function converts the null-terminated Str to a Pascal-style string. This function is provided for backwards compatibility only. To convert a null terminated string to a Pascal style string, use a typecast or an assignment.


Example

uses SysUtils;

const

  A: PChar = 'I love the smell of Object Pascal in the morning.';

 var

  S: string[79];

begin

  S := StrPas(A);

  Canvas.TextOut(10, 10, S);

{ note that the following also works }

  Canvas.TextOut(10, 10, A);

end;


See also

StrPCopy function


StrPCopy function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrPCopy(Dest: PChar; Source: string): PChar;

Description

The StrPCopy function copies a Pascal-style string Source into a null-terminated string Dest.

StrPCopy does not perform any length checking.

The destination buffer must have room for at least Length(Source)+1 characters.


Example

uses SysUtils;

var

  A: array[0..79] of Char;

  S: String;

begin

  S := 'Honk if you know Blaise.';

  StrPCopy(A, S);

  Canvas.TextOut(10, 10, StrPas(A));

end;


See also

StrCopy procedure


StrPLCopy function

String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrPLCopy(Dest: PChar; const Source: string; MaxLen: Cardinal): PChar;

Description

StrPLCopy copies a maximum of MaxLen characters from the Pascal-style string Source into the null-terminated string Dest. Dest is also returned as the function result.


StrPos function

Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrPos(Str1, Str2: PChar): PChar;

Description

The StrPos function returns a pointer to the first occurrence of Str2 in Str1.

If Str2 does not occur in Str1, StrPos returns nil.


Example

uses SysUtils;

const

  S: PChar = 'Ready, Set, Go! ';

  SubStr: PChar = 'Set';

var

  P: PChar;

begin

  P := StrPos(S, SubStr);

  if P = nil then

    Canvas.TextOut(10, 10, 'Substring not found')

  else

    Canvas.TextOut(10, 10, 'Substring found at index ' + IntToStr(P - S));

end;


StrRScan function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrRScan(Str: PChar; Chr: Char): PChar;

Description

The StrRScan function returns a pointer to the last occurrence of Chr in Str.

If Chr does not occur in Str, StrRScan returns nil. The null terminator is considered to be part of the string.


Example

{ Return pointer to name part of a full path name }

uses SysUtils;

function NamePart(FileName: PChar): PChar;

 var

  P: PChar;

begin

  P := StrRScan(FileName, '\');

  if P = nil then

  begin

    P := StrRScan(FileName, ':');

    if P = nil then P := FileName;

  end;

  NamePart := P;

end;

var

  S : string;

begin

  S := StrPas(NamePart('C:\Test.fil'));

  Canvas.TextOut(10, 10, S);

end;


See also

StrScan function


StsrScan function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrScan(Str: PChar; Chr: Char): PChar;

Description

The StrScan function returns a pointer to the first occurrence of Chr in Str.

If Chr does not occur in Str, StrScan returns nil. The null terminator is considered to be part of the string.


Example

uses SysUtils;

function HasWildcards(FileName: PChar): Boolean;

{ Return true if file name has wildcards in it }

begin

  HasWildcards := (StrScan(FileName, '*') <> nil) or

    (StrScan(FileName, '?') <> nil);

end;

const

  P: PChar = 'C:\Test.* ';

begin

  if HasWildcards(P) then

    Canvas.TextOut(20, 20, 'The string has wildcards')

  else

    Canvas.TextOut(20, 20, 'The string doesn't have wildcards')

end;


See also

StrRScan function


StrToDate function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function StrToDate(const S: string): TDateTime;

Description

The StrToDate function converts a string to date format. The date in the string must be a valid date.

The string must consist of two or three numbers, separated by the character defined by the DateSeparator global variable. The order for month, day, and year is determined by the ShortDateFormat global variable--possible combinations are m/d/y, d/m/y, and y/m/d.

If the string contains only two numbers, it is interpreted as a date (m/d or d/m) in the current year. Year values between 0 and 99 are assumed to be in the current century.

If the given string does not contain a valid date, an EConvertError exception is raised.

Note:	The correct format of the date string varies if you change the value of some of the date and time typed constants.


Example

This example uses an edit box, a label, and a button on a form. When the user enters a date in the edit box in the MM/DD/YY format, the string entered is converted to a TDateTime value. This value is then converted back to a string value so it can appear as the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

var

  ADate: TDateTime;

begin

  ADate := StrToDate(Edit1.Text);

  Label1.Caption := DateToStr(ADate);

end;


See also

DateToStr function

StrToDateTime function

StrToTime function


StrToDateTime function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function StrToDateTime(const S: string): TDateTime;

Description

The StrToDateTime function converts a string into a date and time format. The string specified as the S parameter must be in the MM/DD/YY HH:MM:SS format unless the value of the value of the date and time typed constants has changed. Specifying AM or PM as part of the time is optional, as are the seconds. You should use 24-hour time (7:45 PM is entered as 19:45, for example) if you don't specify AM or PM.

Note:	You must use another format to specify a date and time string if you change the value of the some of the date and time typed constants.


Example

This example uses an edit box, a label, and a button on the form. When the user enters a date and time in the edit box in the MM/DD/YY HH:MM:SS format, the string entered is converted to a TDateTime value. This value is then converted back to a string value so it can appear as the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

var

  ADateAndTime: TDateTime;

begin

  ADateAndTime := StrToDateTime(Edit1.Text);

  Label1.Caption := DateTimeToStr(ADateAndTime);

end;


See also

DateTimeToStr function

StrToDate function

StrToTime function


StrToFloat function

Floating-Point Conversion Routines

Unit

SysUtils

Declaration

function StrToFloat(const S: string): Extended;

Description

StrToFloat converts the given string to a floating-point value. The string must consist of an optional sign (+ or -), a string of digits with an optional decimal point, and an optional 'E' or 'e' followed by a signed integer. Leading and trailing blanks in the string are ignored.

The DecimalSeparator global variable defines the character that must be used as a decimal point. Thousand separators and currency symbols are not allowed in the string. If the string doesn't contain a valid value, an EConvertError exception is raised.


StrToInt function

See Also	Example	String Handling Routines (Pascal style)

Unit

SysUtils

Declaration

function StrToInt(const S: string): Integer;

Description

The StrToInt function converts a string representing an integer-type number in either decimal or hexadecimal notation into a number. If the string does not represent a valid number, StrToInt raises an EConvertError exception.


Example

This example uses an edit box and a button on a form. When the user clicks the button, the code converts the string '22467' into an integer, increments that value, then reconverts that new value back to an a string so that it can display in the edit box:

procedure TForm1.Button1Click(Sender: TObject);

var

  S: string;

  I: Integer;

begin

  S := '22467';

  I := StrToInt(S);

  Inc(I);

  Edit1.Text := IntToStr(I);

end;


See also

IntToHex function

IntToStr function

StrToIntDef function


StrToIntDef function

See Also	Example	String Handling Routines (Pascal style)

Unit

SysUtils

Declaration

function StrToIntDef(const S: string; Default: Integer): Integer;

Description

The StrToIntDef function converts the string passed in S into a number. If S does not represent a valid number, StrToIntDef returns the number passed in Default.


Example

This example uses two edit boxes and a button on a form. The user enters a number in the first edit box and clicks the button. If the number entered was a valid integer, the same value appears in the second edit box. If the number was not a valid integer, the default value of 1000 appears in the second edit box:

procedure TForm1.Button1Click(Sender: TObject);

var

  NumberString: string;

  Number: Integer;

begin

  NumberString := Edit1.Text;

  Number := StrToIntDef(NumberString, 1000);

  Edit2.Text := IntToStr(Number);

end;


See also

IntToStr function

StrToInt function


StrToTime function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function StrToTime(const S: string): TDateTime;

Description

The StrToTime function converts the given string to a time value. The string must consist of two or three numbers, separated by the character defined by the TimeSeparator global variable, optionally followed by an AM or PM indicator. The numbers represent hour, minute, and (optionally) second, in that order. If the time is followed by AM or PM, it is assumed to be in 12-hour clock format. If no AM or PM indicator is included, the time is assumed to be in 24-hour clock format. If the given string does not contain a valid time, an EConvertError exception is raised..


Example

This example uses an edit box, a label, and a button on a form. When the user enters a time in the edit box in the HH:MM:SS format, the string entered is converted to a TDateTime value. This value is then converted back to a string value so it can appear as the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

var

  ATime: TDateTime;

begin

  ATime := StrToTime(Edit1.Text);

  Label1.Caption := TimeToStr(ATime);

end;


See also

StrToDate function

StrToDateTime function

TimeToStr function


StrUpper function

See Also	Example	String Handling Routines (null-terminated)

Unit

SysUtils

Declaration

function StrUpper(Str: PChar): PChar;

Description

The StrUpper function converts Str to uppercase and returns Str.


Example

uses SysUtils;

const

  S: PChar = 'A fUnNy StRiNg'

begin

  Canvas.TextOut(5, 10, StrPas(StrLower(S)) + ' ' +   StrPas(StrUpper(S)));

end;


See also

AnsiUpperCase function

UpperCase function

StrLower function


Succ function

See Also	Example	Ordinal Routines

Unit

System

Declaration

function Succ(X);

Description

The Succ function returns the successor of the argument.

X is an ordinal-type expression. The result, of the same type as X, is the successor of X.


Example

uses Dialogs;

type

   Colors = (RED,BLUE,GREEN);

 var

   S: string;

 begin

   S := 'The predecessor of 5 is ' + IntToStr(Pred(5)) + #13#10;

   S := S + 'The successor of 10 is ' + IntToStr(Succ(10)) + #13#10;

   if Succ(RED) = BLUE then

     S := S + 'In the type Colors, RED is the predecessor of BLUE.';

   MessageDlg(S, mtInformation, [mbOk], 0);

 end;


See also

Dec procedure

Inc procedure

Pred function


Swap function

See Also	Example	Miscellaneous Routines

Unit

System

Declaration

function Swap(X);

Description

The Swap function exchanges the high-order bytes with the low-order bytes of the argument.

X is an expression of type Integer or Word.


Example

var

  X: Word;

begin

  X := Swap($1234);   { $3412 }

end;


See also

Hi function

Lo function


SysErrorMessage function

Unit

SysUtils

Declaration

function SysErrorMessage(ErrorCode: Integer): string;

Description

The SysErrorMessage returns an error message string that corresponds to the given operating system error code. A number of routines in the Win32 API return error codes. This function can be used to convert those error codes into strings.


TDateTime type

Unit

System

Declaration

TDateTime: type Double;

Description

TDateTime is the type used by date and time routines to hold date and time values.

Delphi stores date and time values in the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is the time of day.

Following are some examples of TDateTime values and their corresponding dates and times:

0	   12/30/1899 12:00 am

2.75	   1/1/1900 6:00 pm

-1.25	   12/29/1899 6:00 am

35065	   1/1/1996 12:00 am

To find the fractional number of days between two dates, simply subtract the two values. Likewise, to increment a date and time value by a certain fractional number of days, simply add the fractional number to the date and time value.

Note:	Delphi 1.0 calculated the date from year 1 instead of from 1899. To convert a Delphi 1.0 date to a Delphi 2.0 date, subtract 693594.0 from the Delphi 1.0 date. The date format changed to be more compatible with OLE 2.0 Automation.


TextToFloat function

Floating Point Conversion Routines

Unit

SysUtils

Declaration

function TextToFloat(Buffer: PChar; var Value; ValueType: TFloatValue): Boolean;

Description

TextToFloat converts the null-terminated string given by Buffer to a floating-point value which is returned in the variable given by Value. The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter. The return value is True if the conversion was successful, or False if the string is not a valid floating-point value. For further details, see the description of the StrToFloat function.

For further details, see the description of the StrToFloat function.


TFileName type

Unit

SysUtils

Declaration

TFileName = string;

Description

The TFileName type is the type for the FileName property of Open and Save dialog boxes.


TFileRec type

Unit

SysUtils

Declaration

TFileRec = record
  Handle: Integer;
  Mode: Integer;
  RecSize: Cardinal;
  Private: array[1..28] of Byte;
  UserData: array[1..32] of Byte;
  Name: array[0..259] of Char;
end;

Description

TFileRec is the internal format for typed and untyped files. TFileRec enables you to typecast a file variable to access its internal fields.

Note:	You would normally never declare a variable of this type.


TFloatFormat type

See Also

Unit

SysUtils

Declaration

TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency);

Description

TFloatFormat defines an enumerated list of formatting codes for the float functions.

Format	Defines

ffGeneral	General number format. The value is converted to the shortest possible decimal string using fixed or scientific format. Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format, and the Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).

ffExponent	Scientific format. The value is converted to a string of the form "-d.ddd...E+dddd". The resulting string starts with a minus sign if the number is negative, and one digit always precedes the decimal point. The total number of digits in the resulting string (including the one before the decimal point) is given by the Precision parameter. The "E" exponent character in the resulting string is always followed by a plus or minus sign and up to four digits. The Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).

ffFixed	Fixed point format. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative, and at least one digit always precedes the decimal point. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18. If the number of digits to the left of the decimal point is greater than the specified precision, the resulting value will use scientific format.

ffNumber	Number format. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The ffNumber format corresponds to the ffFixed format, except that the resulting string contains thousand separators.

ffCurrency	Currency format. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, and DecimalSeparator global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panel. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18.

See also

Date and Time Typed Constants

 FloatToDecimal procedure

FloatToStr function

FloatToStrF function

FloatToText function

FloatToTextFmt function


TFloatRec type

Unit

SysUtils

Declaration

TFloatRec = record
  Exponent: Smallint;
  Negative: Boolean;
  Digits: array[0..20] of Char;
end;

Description

TFloatRec is the FloatToDecimal result record.


TFloatValue type

Unit

SysUtils

Declaration

TFloatValue = (fvExtended, fvCurrency);

Description

TFloatValue is the type of the ValueType parameter of the FloatToText, FloatToTextFmt and TextToFloat functions and the FloatToDecimal procedure. The ValueType parameter indicates whether the value being passed to the function or procedure is a currency value or a normal floating-point value.

Value	Meaning

fvExtended	The value is a normal floating-point type.

fvCurrency	THe value is a currency type.


THeapStatus type

See Also

Unit

System

Declaration

type

THeapStatus = record

   TotalAddrSpace: Cardinal;s

   TotalUncommitted: Cardinal;

   TotalCommitted: Cardinal;

   TotalAllocated: Cardinal;

   TotalFree: Cardinal;

   FreeSmall: Cardinal;

   FreeBig: Cardinal;

   Unused: Cardinal;

   Overhead: Cardinal;

   HeapErrorCode: Cardinal;

end;

Description

The THeapStatus type is the return type of the GetHeapStatus function. These are the meanings of the values in the THeapStatus record:.

Field	Meaning

TotalAddrSpace	The (current) total address space available to your pascal program, in bytes. This will grow as your program's dynamic memory usage grows.

TotalUncommitted	The total number of bytes (of TotalAddrSpace) for which space has not been allocated in the swap file.

TotalCommitted	The total number of bytes (of TotalAddrSpace) for which space has been allocated in the swap file.NOTE: TotalUncommitted + TotalCommitted = TotalAddrSpace

TotalAllocated	The total number of bytes dynamically allocated by your program.

TotalFree	 The total number of free bytes available in the (current) address space for allocation by your program. If this number is exceeded, and enough virtual memory is available, more address space will be allocated from the OS; TotalAddrSpace will be incremented accordingly.

FreeSmall	Total bytes of small memory blocks which are not currently allocated by your program.

FreeBig	Total bytes of big memory blocks which are not currently allocated by your program. Large free blocks can be created by coalescing smaller, contiguous, free blocks or by freeing a large dynamic allocation.  (The exact size of the blocks is immaterial)

Unused	Total bytes which have never been allocated by your program. NOTE: Unused + FreeBig + FreeSmall = TotalFreeNOTE: These three are speaking about dynamic allocation from the user program.

Overhead	The total number of bytes required by the heap manager to manage all the blocks dynmically allocated by your program.

HeapErrorCode	Indicates the current status of the heap, as internally determined.

Note:	TotalAddrSpace, TotalUncommitted and TotalCommitted refer to OS memory used by the program, where as TotalAllocated and TotalFree refer to the heap memory used within the program by dynamic allocations. Therefore, to monitor dynamic memory used in your program use TotalAllocated and TotalFree.


See Also

GetHeapStatus function


Time function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function Time: TDateTime;

Description

The Time function returns the current time.


Example

This example uses a label and a button on a form. When the user clicks the button, the current time displays in the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := 'The time is  ' + TimeToStr(Time);

end;


See also

Date and Time Typed Constants

 Date function

DecodeTime procedure

Now function

TimeToStr function


TimeToStr function

See Also	Example	Date/Time Routines

Unit

SysUtils

Declaration

function TimeToStr(Time: TDateTime): string;

Description

The TimeToStr function converts the Time parameter, a variable of type TDateTime, to a string. The conversion uses the format specified by the LongTimeFormat global variable. You can change the format of how the string is displayed by changing the values of some of the date and time variables.


Example

This example uses a label and a button on a form. When the user clicks the button, the current time appears as the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := TimeToStr(Time);

end;


See also

Date and Time Typed Constants

 DateTimeToStr function

DateToStr function

StrToDateTime function

Time function


TMemoryManager type

See Also

Unit

System

Declaration

type

  PMemoryManager = ^TMemoryManager;

  TMemoryManager = record

    GetMem: function(Size: Integer): Pointer;

    FreeMem: function(P: Pointer): Integer;

    ReallocMem: function(P: Pointer; Size: Integer): Pointer;

end;

Description

The TMemoryManager type is used by the GetMemoryManager and SetMemoryManager procedures.


See Also

GetMemoryManager procedure

SetMemoryManager procedure


TMethod type

Unit

SysUtils

Declaration

TMethod = record

  Code, Data: Pointer;

end;

Description

The TMethod type declares a record that stores the Code and Data fields as type Pointer.

This type can be used in a type cast of a method pointer to access the code and data parts of the method pointer.


Trim function

See Also

Unit

SysUtils

Declaration

function Trim(const S: string): string;

Description

The Trim function trims leading and trailing spaces and control characters from the given string S.


See Also

TrimLeft function

TrimRight function


TrimLeft function

See Also

Unit

SysUtils

Declaration

function TrimLeft(const S: string): string;

Description

The TrimLeft function trims leading spaces and control characters from the given string S.


See Also

Trim function

TrimRight function


TrimRight function

See Also

Unit

SysUtils

Declaration

function TrimRight(const S: string): string;

Description

The Trim function trims trailing spaces and control characters from the given string S.


See Also

TrimLeft function

TrimRight function


Trunc function

See Also	Example	Transfer Routines

Unit

System

Declaration

function Trunc(X: Extended): Longint;

Description

The Trunc function truncates a real-type value to an integer-type value.

X is a real-type expression. Trunc returns a Longint value that is the value of X rounded toward zero.

If the truncated value of X is not within the Longint range, an error occurs, which you can handle using the EInvalidOp exception. If you do not handle it, you will receive a run-time error.


Example

var

   S, T: string;

begin

   Str(1.4:2:1, T);

   S := T + ' Truncs to ' + IntToStr(Trunc(1.4)) + #13#10;

   Str(1.5:2:1, T);

   S := S + T + ' Truncs to ' + IntToStr(Trunc(1.5)) + #13#10;

   Str(-1.4:2:1, T);

   S := S + T + ' Truncs to ' + IntToStr(Trunc(-1.4)) + #13#10;

   Str(-1.5:2:1, T);

   S := S + T + ' Truncs to ' + IntToStr(Trunc(-1.5));

   MessageDlg(S, mtInformation, [mbOk], 0);

end;


See also

Int function

Round function


Truncate procedure

See Also	Example	I/O Routines

Unit

System

Declaration

procedure Truncate(var F);

Description

The Truncate procedure deletes all records in the file after the current file position F. The current file position also becomes end-of-file (Eof(F) is True).

F is a file variable of any type. Truncate does not work on text files. F must be open.

{$I+} lets you handle run-time errors using exceptions. For more information on handling run-time library exceptions, see Handling RTL Exceptions.

If you are using {$I-}, you must use IOResult to check for I/O errors.


Example

var

   f: file of Integer;

   i,j: Integer;

 begin

   AssignFile(f,'TEST.INT');

   Rewrite(f);

   for i := 1 to 6 do

     Write(f,i);

   Writeln('File before truncation:');

   Reset(f);

   while not Eof(f) do

   begin

     Read(f,i);

     Writeln(i);

   end;

   Reset(f);

   for i := 1 to 3 do

     Read(f,j); { Read ahead 3 records }

   Truncate(f); { Cut file off here }

   Writeln;

   Writeln('File after truncation:');

   Reset(f);

   while not Eof(f) do

   begin

     Read(f,i);

     Writeln(i);

   end;

   CloseFile(f);

   Erase(f);

 end;


See also

Reset procedure

Rewrite procedure

Seek procedure


TSearchRec type

Unit

SysUtils

Declaration

TSearchRec = record

  Time: Integer;

  Size: Integer;

  Attr: Integer;

  Name: TFileName;

  ExcludeAttr: Integer;

  FindHandle: THandle;

  FindData: TWin32FindData;

end;

Description

The TSearchRec type defines file information searched for by a FindFirst or FindNext function call. If a file is found, the fields of the TSearchRec type parameter are modified to specify the found file.

Attr represents the file attributes the file attributes of the file. Test Attr against the following attribute constants or values to determine if a file has a specific attribute:

Constant	Value	Description

faReadOnly	$00000001	Read-only files

faHidden	$00000002	Hidden files

faSysFile	$00000004	System files

faVolumeID	$00000008	Volume ID files

faDirectory	$00000010	Directory files

faArchive	$00000020	Archive files

faAnyFile	$0000003F	Any file

To test for an attribute, combine the value of the Attr field with the attribute constant with the and operator. If the file has that attribute, the result will be greater than 0. For example, if the found file is a hidden file, the following expression will evaluate to True: (SearchRec.Attr and faHidden > 0).

Time contains the time stamp of the file. Size contains the size of the file in bytes. Name contains the DOS file name and extension.


TTextRec type

Unit

SysUtils

Declaration

PTextBuf = ^TTextBuf;
TTextBuf = array[0..127] of Char;
TTextRec = record
  Handle: Integer;
  Mode: Integer;
  BufSize: Cardinal;
  BufPos: Cardinal;
  BufEnd: Cardinal;
  BufPtr: PChar;
  OpenFunc: Pointer;
  InOutFunc: Pointer;
  FlushFunc: Pointer;
  CloseFunc: Pointer;
  UserData: array[1..32] of Byte;
  Name: array[0..259] of Char;
  Buffer: TTextBuf;
end;

Description

TTextRec is the internal format of a variable of type text. You would never declare a variable of this type. However, you would use TTextRec to typecast a text file variable to access the internal data fields, such as the file name.

Note:	Do not use this unless you are familiar with writing Object Pascal text file device drivers.


TThreadFunc type

See Also

Unit

System

Declaration

TThreadFunc = function(Parameter: Pointer): Integer;

Description

The TThreadFunc type defines a type of routine that is the starting address for a new thread of execution. A TThreadFunc routine is passed to the Delphi routine BeginThread or the Windows API CreateThread function. When BeginThread executes, TThreadFunc acts as the entry point for the new thread.

The Parameter pointer passed to the TThreadFunc routine is passed directly to BeginThread. Parameter can be a single 32-bit value or a 32-bit pointer to other data. The value in Parameter can be used within the TThreadFunc routine.

TThreadFunc returns the value of the thread entry point procedure. This result is usually passed to the EndThread routine. An application can retrieve the TThreadFunc return value by calling the Windows API GetExitCodeThread function.

See also

BeginThread function, EndThread function


TVarData type

See Also

Unit

System

Declaration

const

 varEmpty    = $0000;

 varNull     = $0001;

 varSmallint = $0002;

 varInteger  = $0003;

 varSingle   = $0004;

 varDouble   = $0005;

 varCurrency = $0006;

 varDate     = $0007;

 varOleStr   = $0008;

 varDispatch = $0009;

 varError    = $000A;

 varBoolean  = $000B;

 varVariant  = $000C;

 varUnknown  = $000D;

 varString   = $0100;

 varTypeMask = $0FFF;

 varArray    = $2000;

 varByRef    = $4000;

type

  TVarArrayBound = record

    ElementCount: Integer;

    LowBound: Integer;

  end;

  PVarArray = ^TVarArray;

  TVarArray = record

    DimCount: Word;

    Flags: Word;

    ElementSize: Integer;

    LockCount: Integer;

    Data: Pointer;

    Bounds: array[0..255] of TVarArrayBound;

  end;

  TVarData = record

   VType: Word;

   Reserved1, Reserved2, Reserved3: Word;

   case Integer of

    varSmallint: (VSmallint: Smallint);

    varInteger:  (VInteger: Integer);

    varSingle:   (VSingle: Single);

    varDouble:   (VDouble: Double);

    varCurrency: (VCurrency: Currency);

    varDate:     (VDate: Double);

    varOleStr:   (VOleStr: PWideChar);

    varDispatch: (VDispatch: Pointer);

    varError:    (VError: Integer);

    varBoolean:  (VBoolean: WordBool);

    varUnknown:  (VUnknown: Pointer);

    varString:   (VString: Pointer);

    varArray:    (VArray: PVarArray);

    varByRef:    (VPointer: Pointer);

end;

Description

The TVarData type represents the internal structure of a Variant variable. The internal structure of a Variant is identical to the Variant type used by OLE and the Win32 APIs.

The TVarData type can be used in typecasts of Variant variables to access the internals of a variable; for example,

var

  V: Variant;

begin

  ...

  if TVarData(V).VType = varEmpty then ...;

  ...

  VarClear(V);

  TVarData(V).VType := varInteger;

  TVarData(V).VInteger := 1234567;

  ...

end;

The VType field of a TVarData record contains the type code of the variant in the lower twelve bits (the bits defined by the varTypeMask constant). In addition, the varArray bit may be set to indicate that the variant is an array, and the varByRef bit may be set to indicate that the variant contains a reference as opposed to a value.

The Reserved1, Reserved2, and Reserved3 fields of a TVarData record are unused.

The contents of the remaining eight bytes of a TVarData record depend on the VType field. If neither the varArray nor the varByRef bits are set, the variant contains a value of the given type.

If the varArray bit is set, the variant contains a pointer to a TVarArray structure that defines the specifics of the array. The type of each array element is given by the varTypeMask bits in the VType field.

If the varByRef bit is set, the variant contains a reference to a value of the type given by the varTypeMask and varArray bits in the VType field.

Note that the varString type code is private to Delphi. Variants containing a varString value should never be passed to a non-Delphi function. Delphi's OLE Automation support will automatically convert varString variants to varOleStr variants before passing them as parameters to external functions.


See Also

VarAsType function

VarType function


TVarRec type

See Also

Unit

System

Declaration

const

  vtInteger    = 0;

  vtBoolean    = 1;

  vtChar       = 2;

  vtExtended   = 3;

  vtString     = 4;

  vtPointer    = 5;

  vtPChar      = 6;

  vtObject     = 7;

  vtClass      = 8;

  vtWideChar   = 9;

  vtPWideChar  = 10;

  vtAnsiString = 11;

  vtCurrency   = 12;

  vtVariant    = 13;

type

  PVarRec = ^VarRec;

  TVarRec = record

   case Byte of

     vtInteger:    (VInteger: Integer; VType: Byte);

     vtBoolean:    (VBoolean: Boolean);

     vtChar:       (VChar: Char);

     vtExtended:   (VExtended: PExtended);

     vtString:     (VString: PShortString);

     vtPointer:    (VPointer: Pointer);

     vtPChar:      (VPChar: PChar);

     vtObject:     (VObject: TObject);

     vtClass:      (VClass: TClass);

     vtWideChar:   (VWideChar: WideChar);

     vtPWideChar:  (VPWideChar: PWideChar);

     vtAnsiString: (VAnsiString: Pointer);

     vtCurrency:   (VCurrency: PCurrency);

     vtVariant:    (VVariant: PVariant);

end;

Description

TVarRec type is used inside a procedure with a parameter type of array of const. The VType field lets the procedure know the simple type of each parameter passed in the open array.

The variable type constants represent the values passed in the tag of the TVarRec structure.


See Also

Type-Safe Open Arrays


TypeInfo function

Unit

System

Declaration

function TypeInfo(TypeIdent): Pointer;

Description

The TypeInfo function returns a pointer to the compiler generated run-time type information for the given type identifier. Certain low-level VCL procedures and functions require run-time type information pointers as parameters. The actual format of the run-time type information is internal to the compiler and may change between releases.


Unassigned constant

See Also

Unit

System

Declaration

const Unassigned: Variant;

Description

The Unassigned constant is used to indicate that a Variant variable has not yet been assigned a value. The initial value of any Variant variable is Unassigned. The Unassigned value disappears as soon as a Variant variable is assigned any other value, including the value 0, a zero-length string, and the Null value.

Using an Unassigned variant in an expression causes an EVariantError exception to be raised. Likewise, if you attempt to convert an Unassigned variant to another type (using VarAsType or VarCast), an EVariantError exception is raised.

You can make a Variant variable unassigned by assigning the Unassigned constant to it. This is particularly useful in situations where a Variant contains a reference to an OLE Automation Object, thus keeping the object "alive" until another value is assigned to the Variant. For example, in the code fragment shown below, the statement that assigns Unassigned to the MSWord variable causes the OLE Automation Object that was created to interface with Word to be released.

var

  MSWord: Variant;

begin

  ...

  MSWord := CreateOleObject('Word.Basic');

  ...

  MSWord := Unassigned;

  ...

end;

To test whether a Variant value is Unassigned, compare it to the Unassigned constant, or use the VarIsEmpty standard function. When used on an unassigned variant, the VarType standard function returns varEmpty.


See Also

Null constant

VarIsEmpty function

VarType function


UniqueString procedure

Unit

System

Declaration

procedure UniqueString(var S: string);

Description

The UniqueString standard procedure makes the given string unique. Following a call to SetString, S is guaranteed to reference a unique string; that is, a string with a reference count of one. For normal string handling, there is no need to ever call UniqueString. Only in cases where an application casts a string to a PChar and then modifies the contents of the string must UniqueString be used.


UpCase function

See Also	Example	Miscellaneous Routines

Unit

System

Declaration

function UpCase(Ch: Char): Char;

Description

The UpCase function converts a Ch to uppercase.

Ch is an expression of type Char. Character values not in the range a..z are unaffected.


Example

uses Dialogs;

var

   s : string;

   i : Integer;

 begin

   { Get string from TEdit control }

   s := Edit1.Text;

   for i := 1 to Length(s) do

     s[i] := UpCase(s[i]);

   MessageDlg('Here it is in all uppercase: ' + s, mtInformation, [mbOk], 0);

 end;


See also

AnsiUpperCase function

StrUpper function

UpperCase function


UpperCase function

See Also	Example	String Handling Routines (Pascal style)

Unit

SysUtils

Declaration

function UpperCase(const S: string): string;

Description

The UpperCase function returns a string containing the same text as S, but with all letters converted to uppercase.

Example

This example uses a list box and a button on a form. Use the Items property editor in the Object Inspector to enter a list of strings in the list box. When you run the application and click the button, the strings in the list box become uppercase.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to ListBox1.Items.Count -1 do

    ListBox1.Items[I] := UpperCase(ListBox1.Items[I]);

end;


See also

AnsiUpperCase function

LowerCase function


Val procedure

See Also	Example	String Handling Routines (Pascal style)

Unit

System

Declaration

procedure Val(S; var V; var Code: Integer);

Description

The Val function converts the string value S to its numeric representation, as if it were read from a text file with Read.

S is a string-type expression; it must be a sequence of characters that form a signed whole number. V is an integer-type or real-type variable. Code is a variable of type Integer.

If the string is invalid, the index of the offending character is stored in Code; otherwise, Code is set to zero. For a null-terminated string, the error position returned in Code is one larger than the actual zero-based index of the character in error.

Val performs range checking differently depending upon the state of $R and the type of the parameter V.

Setting	Result

{$R+}	An out-of-range value always generates a run-time error.

{$R-}	The values for out-of-range vary depending upon the data type of V.


Example

uses Dialogs;

var

  I, Code: Integer;

begin

  { Get text from TEdit control }

  Val(Edit1.Text, I, Code);

  { Error during conversion to integer? }

  if code <> 0 then

    MessageDlg('Error at position: ' + IntToStr(Code), mtWarning, [mbOk], 0);

  else

    Canvas.TextOut(10, 10, 'Value = ' + IntToStr(I));

  Readln;

end;

See also

Str procedure


VarArrayCreate function

SeeAlso	Example	Variant support routines

Unit

System

Declaration

function VarArrayCreate(const Bounds: array of Integer; VarType: Integer): Variant;

Description

The VarArrayCreate function creates a variant array with the bounds given by Bounds and the element type given by VarType. The Bounds parameter must contain an even number of values, and each pair of values specify the upper and lower bounds of one dimension of the array. The element type of the array, given by the VarType parameter, must be one of the varXXXX type codes, and cannot include the varArray or varByRef bits. The element type cannot be varString. To create a variant array of strings, you must instead use the varOleStr type code. If the element type is varVariant, the elements of the array are themselves variants and can in turn contain variant arrays.

NOTE: :	Variant arrays with an element type of varByte are the preferred method of passing binary data between OLE Automation controllers and servers. Such arrays are subject to no translation of their data, and can be efficiently accessed using the VarArrayLock and VarArrayUnlock routines.


Example

The following example creates a one-dimensional variant array with five elements. Each of the elements are of type Variant, and can therefore contain values of varying types, as is illustrated by the example. Notice in particular how the value of the last element of the array is itself a variant array.

var

  A: Variant;

begin

  A := VarArrayCreate([0, 4], varVariant);

  A[0] := 1;

  A[1] := 1234.5678;

  A[2] := 'Hello world';

  A[3] := True;

  A[4] := VarArrayOf([1, 10, 100, 1000]);

  WriteLn(A[2]);	{ Hello world }

  WriteLn(A[4][2]);	{ 100 }

end;


See Also

VarArrayOf function

VarArrayRedim procedure


VarArrayDimCount function

See Also	Variant support routines

Unit

System

Declaration

function VarArrayDimCount(const A: Variant): Integer;

Description

The VarArrayDimCount function returns the number of dimensions of the given variant. The resulting value is zero if the given variant is not a variant array.


See also

VarArrayHighBound function

VarArrayLowBound function


VarArrayHighBound function

See Also	Variant support routines

Unit

System

Declaration

function VarArrayHighBound(const A: Variant; Dim: Integer): Integer;

Description

The VarArrayHighBound function returns the high bound of the given dimension in the given variant array. The Dim parameter should be 1 for the leftmost dimension, 2 for the second leftmost dimension, and so on. An EVariantError exception is raised if the variant given by A is not an array, or if the dimension specified by Dim does not exist.


See also

VarArrayDimCount function

VarArrayLowBound function


VarArrayLock function

See Also	Example	Variant support routines

Unit

System

Declaration

function VarArrayLock(var A: Variant): Pointer;

Description

The VarArrayLock function locks the given variant array and returns a pointer to the data stored in the array. While locked, a variant array can not be resized and any calls to the VarArrayRedim procedure will fail. Once locked, a variant array must later be unlocked using the VarArrayUnlock procedure. An EVariantError exception is raised if the variant given by A is not an array.

The pointer returned by VarArrayLock points to an array of elements in which the leftmost dimension increases first. In other words, the dimensions of the returned array pointer are reversed from the dimensions of the variant array.

Once you have verified that a variant array has the correct bounds and dimensions, you can use VarArrayLock to gain direct access to the array data which results in much improved performance.


Example

type

  PArrayData = ^TArrayData;

  TArrayData = array[0..9, 1..3] of Integer;

var

  A: Variant;

  P: PArrayData;

  I, J: Integer;

begin

  A := VarArrayCreate([1, 3, 0, 9], varInteger);

  P := VarArrayLock(A);

  try

  for I := 0 to 9 do

    for J := 1 to 3 do

      P^[I, J] := J * 10 + I;

  finally

  VarArrayUnlock(A);

  end;

  WriteLn(A[1, 9]);	{ 19 }

  WriteLn(A[3, 4]);	{ 34 }

end;


See also

VarArrayUnlock procedure


VarArrayLowBound function

See Also	Variant support routines

Unit

System

Declaration

function VarArrayLowBound(const A: Variant; Dim: Integer): Integer;

Description

The VarArrayLowBound function returns the low bound of the given dimension in the given variant array. The Dim parameter should be 1 for the leftmost dimension, 2 for the second leftmost dimension, and so on. An EVariantError exception is raised if the variant given by A is not an array, or if the dimension specified by Dim does not exist.


See also

VarArrayDimCount function

VarArrayHighBound function


VarArrayOf function

See Also	Variant support routines

Unit

System

Declaration

function VarArrayOf(const Values: array of Variant): Variant;

Description

The VarArrayOf function returns a one-dimensional variant array with the elements given by the Values parameter. The low bound of the returned array is zero, the high bound is the number of values given by the Values parameter less one, and the element type is Variant.


See also

VarArrayCreate function


VarArrayRedim procedure

See Also	Variant support routines

Unit

System

Declaration

procedure VarArrayRedim(var A: Variant; HighBound: Integer);

Description

The VarArrayRedim procedure resizes the given variant array by changing the high bound of the rightmost dimension to the given value. Existing elements of the array are preserved, and new elements are set to zero or empty. An EVariantError exception is raised if the variant given by A is not an array, or if there is not enough memory to resize the array.


See also

VarArrayCreate function


VarArrayUnlock procedure

See Also	Variant support routines

Unit

System

Declaration

procedure VarArrayUnlock(var A: Variant);

Description

The VarArrayUnlock procedure unlocks a variant array that was previously locked by VarArrayLock. An EVariantError exception is raised if the variant given by A is not an array.


See also

VarArrayLock. function


VarAsType function

See Also	Variant support routines

Unit

System

Declaration

function VarAsType(const V: Variant; VarType: Integer): Variant;

Description

The VarAsType function converts the variant given by V to the type given by VarType. The resulting value is a variant of the type given by VarType. The VarType parameter must be one of the varXXXX type codes, and cannot include the varArray or varByRef bits. An EVariantError exception is raised if the variant cannot be converted to the given type.

The VarCast procedure provides the same functionality as VarAsType.


See also

VarCast procedure

VarType function


VarCast procedure

See Also	Variant support routines

Unit

System

Declaration

procedure VarCast(var Dest: Variant; const Source: Variant; VarType: Integer);

Description

The VarCast procedure converts the variant given by Source to the type given by VarType and stores the resulting variant in Dest. The VarType parameter must be one of the varXXXX type codes, and cannot include the varArray or varByRef bits. An EVariantError exception is raised if the variant cannot be converted to the given type.

The VarAsType function provides the same functionality as VarCast.


See also

VarAsType function

VarType function


VarClear procedure

See Also	Variant support routines

Unit

System

Declaration

procedure VarClear(var V: Variant);

Description

The VarClear procedure clears the given variant. After the call to VarClear, the variant has the value Unassigned.


See also

Unassigned constant

VarType function


VarCopy procedure

Variant support routines

Unit

System

Declaration

procedure VarCopy(var Dest: Variant; const Source: Variant);

Description

The VarCopy procedure copies the variant given by Source into the variant given by Dest. The call VarCopy(Dest, Source) is the same as writing Dest := Source.


VarFromDateTime function

See Also	Variant support routines

Unit

System

Declaration

function VarFromDateTime(DateTime: TDateTime): Variant;

Description

The VarFromDateTime function returns a variant that contains the given date and time value. The type code of the resulting variant is varDate.


See also

TDateTime type

VarToDateTime function


VarIsArray function

See Also	Variant support routines

Unit

System

Declaration

function VarIsArray(const V: Variant): Boolean;

Description

The VarIsArray function returns True if the given variant is an array. Otherwise, the function result is False.


See also

VarArrayCreate function


VarIsEmpty function

See Also	Variant support routines

Unit

System

Declaration

function VarIsEmpty(const V: Variant): Boolean;

Description

The VarIsEmpty function returns True if the given variant contains the value Unassigned. If the variant contains any other value, the function result is False.


See also

Unassigned constant

VarType function


VarIsNull function

See Also	Variant support routines

Unit

System

Declaration

function VarIsNull(const V: Variant): Boolean;

Description

The VarIsNull function returns True if the given variant contains the value Null. If the variant contains any other value, the function result is False.


See also

Null constant

VarType function


VarToDateTime function

See Also	Variant support routines

Unit

System

Declaration

function VarToDateTime(const V: Variant): TDateTime);

Description

The VarToDateTime function converts the given variant to a date and time value. An EVariantError exception is raised if the conversion fails.


See also

TDateTime type

VarFromDateTime function


VarType function

See Also	Variant support routines

Unit

System

Declaration

function VarType(const V: Variant): Integer;

Description

The VarType function returns the type code of the given variant. The resulting value is constructed from the following constants declared in the System unit.

const

  varEmpty    = $0000;

  varNull     = $0001;

  varSmallint = $0002;

  varInteger  = $0003;

  varSingle   = $0004;

  varDouble   = $0005;

  varCurrency = $0006;

  varDate     = $0007;

  varOleStr   = $0008;

  varDispatch = $0009;

  varError    = $000A;

  varBoolean  = $000B;

  varVariant  = $000C;

  varUnknown  = $000D;

  varByte     = $0011;

  varString   = $0100;

  varTypeMask = $0FFF;

  varArray    = $2000;

  varByRef    = $4000;

The lower twelve bits of a variant type code (the bits defined by the varTypeMask bit mask) define the type of the variant. The varArray bit is set if the variant is an array of the given type. The varByRef bit is set if the variant is a reference to a value of the given type as opposed to an actual value.

The following table describes the meaning of each of the variant type codes.

VarType	Contents of variant

varEmpty	The variant is Unassigned.

varNull	The variant is Null.

varSmallint	16-bit signed integer (type Smallint).

varInteger	32-bit signed integer (type Integer).

varSingle	Single-precision floating-point value (type Single).

varDouble	Double-precision floating-point value (type Double).

varCurrency	Currency floating-point value (type Currency).

varDate	Date and time value (type TDateTime).

varOLEStr	Reference to a dynamically allocated UNICODE string.

varDispatch	Reference to an OLE automation object (an IDispatch interface pointer).

varError	Operating system error code.

varBoolean	16-bit boolean (type WordBool).

varUnknown	Reference to an unknown OLE object (an IUnknown interface pointer).

varString	Reference to a dynamically allocated Pascal string (type AnsiString).

The value returned by VarType corresponds to the VType field of a TVarData record.

The type of a variant can be changed using the VarAsType standard function.


See also

TVarData type

VarAsType function


WideCharLenToString function

See Also	Wide character routines

Unit

System

Declaration

function WideCharLenToString(Source: PWideChar; SourceLen: Integer): string;

Description

The WideCharLenToString function converts SourceLen Unicode characters from the buffer given by Source to an ANSI string. The function uses the WideCharToMultiByte Win32 API function to perform the actual conversion.


See also

StringToWideChar function

WideCharToString function


WideCharToString function

See Also	Wide character routines

Unit

System

Declaration

function WideCharToString(Source: PWideChar): string;

Description

The WideCharToString function converts the given null-terminated Unicode string to an ANSI string. The function uses the WideCharToMultiByte Win32 API function to perform the actual conversion.


See also

StringToWideChar function

WideCharToString function


WordRec type

See also

Unit

SysUtile

Declaration

WordRec = packed record
  Lo, Hi: Byte;
end;

Description

The WordRec type declares a utility record that stores the high and low order bytes of the specified variable as type Byte. WordRec is used primarily for typecasting.


See also

Hi function

Lo function


Write procedure

Unit

System

There are two versions of the standard procedure Write, one for text files, the other for typed files.

Write procedure for text files

Write procedure for typed files


Write procedure for text files
Write procedure

See Also	Text File Routines

Declaration

procedure Write( [var F: Text; ] P1 [ , P2,..., Pn] );

Description

The Write procedure writes one or more values to a text file. F, if specified, is a text file variable. If F is omitted, the standard file variable Output is assumed. Each P is a write parameter. Each write parameter includes an output expression whose value is to be written to the file. A write parameter can also contain the specifications of a field width and a number of decimal places. Each output expression must be of a type Char, one of the Integer types (Byte, Shortint, Word, Longint, Cardinal) , one of the floating-point types (Single, Real, Double, Extended, Currency) , one of the string types (PChar, AnsiString, ShortString) , a packed string, or one of the Boolean types (Boolean, Bool).

A write parameter has the form

OutExpr [: MinWidth [: DecPlaces ] ]

where OutExpr is an output expression. MinWidth and DecPlaces are type integer expressions.

MinWidth specifies the minimum field width, which must be greater than 0. Exactly MinWidth characters are written (using leading blanks if necessary) except when OutExpr has a value that must be represented in more than MinWidth characters. In that case, enough characters are written to represent the value of OutExpr. Likewise, if MinWidth is omitted, then the necessary number of characters are written to represent the value of OutExpr.

DecPlaces specifies the number of decimal places in a fixed-point representation of one of the Real types. It can be specified only if OutExpr is one of the Real types, and if MinWidth is also specified. When MinWidth is specified, it must be greater than or equal to 0.

Write with a character-type value

If MinWidth is omitted, the character value of OutExpr is written to the file. Otherwise, MinWidth - 1 blanks followed by the character value of OutExpr is written.

Write with one of the integer type values

If MinWidth is omitted, the decimal representation of OutExpr is written to the file with no preceding blanks. If MinWidth is specified and its value is larger than the length of the decimal string, enough blanks are written before the decimal string to make the field width MinWidth.

Write with one of the real type values

If OutExpr has one of the real type values, its decimal representation is written to the file. The format of the representation depends on the presence or absence of DecPlaces.

If DecPlaces is omitted (or if it's present but has a negative value), a floating-point decimal string is written. If MinWidth is also omitted, a default MinWidth of 17 is assumed; otherwise, if MinWidth is less than 8, it's assumed to be 8. The format of the floating-point string is

[   | - ] <digit> . <decimals> E [ + | - ] <exponent>

The following table lists the components of the output string..

Component	Meaning

 [  | - ]	" " or "-", according to the sign of OutExpr

<digit> 	Single digit, "0" only if OutExpr is 0

<decimals> 	Digit string of MinWidth-7 (but at most 10) digits

E 	Uppercase [E] character

[ + | - ] 	According to sign of exponent

<exponent> 	Two-digit decimal exponent

If DecPlaces is present, a fixed-point decimal string is written. If DecPlaces is larger than 11, it's assumed to be 11. The format of the fixed-point string follows:

[ <blanks> ] [ - ] <digits> [ . <decimals> ]

The following table lists the components of the fixed-point string.

Component	Meaning

 [ <blanks> ] 	Blanks to satisfy MinWidth

[ - ]	If OutExpr is negative

 <digits> 	At least one digit, but no leading zeros

[ . <decimals> ]	Decimals if DecPlaces > 0

Write with one of the string-type values

If MinWidth is omitted, the string value of OutExpr is written to the file with no leading blanks. If MinWidth is specified, and its value is larger than the length of OutExpr, enough blanks are written before the decimal string to make the field width MinWidth.

Write with a packed string-type value

If OutExpr is of packed string type, the effect is the same as writing a string whose length is the number of elements in the packed string type.

Write with one of the Boolean type values

If OutExpr is of type Boolean, the effect is the same as writing the strings True or False, depending on the value of OutExpr.

Note:	When using Write the file must be open for output.


See also

Read procedure

Readln procedure

Writeln procedure


Write procedure for typed files
Write procedure

See Also	Text File Routines

Declaration

procedure Write(F, V1,...,Vn);

Description

The Write procedure writes a file to a file component. F is a file variable, and each V is a variable of the same type as the component type of F. For each variable written, the current file position is advanced to the next component. If the current file position is at the end of the file (that is, if Eof(F) is True), the file is expanded.


See also

Writeln procedure


WriteIn procedure

See Also	Example	Text File Routines

Unit

System

Declaration

procedure Writeln([ var F: Text; ] P1 [, P2, ...,Pn ] );

Description

The Writeln procedure is an extension to the Write procedure, as it is defined for text files.

After executing Write, Writeln writes an end-of-line marker (carriage-return/linefeed) to the file. Writeln(F) with no parameters writes an end-of-line marker to the file. (Writeln with no parameter list corresponds to Writeln(Output).)

The file must be open for output.

Note:	When an application is compiled as a console application (using the Generate console application checkbox on the Linker page of the Project|Options dialog, or a -cc command line switch with the command-line compiler), Delphi automatically associates the Input and Output files with the application's console window. For non-console applications, any attempt to read from Input or write to Output will generate an I/O error.


Example

var

   s : string;

 begin

   Write('Enter a line of text: ');

   Readln(s);

   Writeln('You typed: ',s);

   Writeln('Hit <Enter> to exit');

   Readln;

 end;


See also

Write procedure


Procedures and functions categorical
Procedures and functions (categorical)

This is a categorical list of all the procedures and functions.

Arithmetic routines

Date/time routines

Dynamic allocation routines

Exception-handling routines

File-management routines

Floating-point conversion routines

Flow-control routines

I/O routines

Memory management routines

Miscellaneous routinesOle string support routines

Ordinal routines

Pointer and address routines

String-formatting routines

String-handling routines (Pascal-style)

String-handling routines (null-terminated)

Text-file routines

Thread support routines

Transfer routines

Untyped-file routines

Variant support routines

Wide character routines


Arithmetic routines

Categorical procedures and functions

Abs	Returns the absolute value of the argument.

ArcTan	Returns the arc tangent of the argument.

Cos	Returns the cosine of the argument (x is an angle, in radians).

Exp	Returns the exponential of the argument.

Frac	Returns the fractional part of the argument.

Int	Returns the Integer part of the argument.

Ln	Returns the natural logarithm of the argument.

Pi	Returns the value of Pi.

Sin	Returns the sine of the argument.

Sqr	Returns the square of the argument.

Sqrt	Returns the square root of the argument.


Date and time routines

Categorical procedures and functions

Date	Returns the current date.

DateTimeToStr	Converts a value from time format to a string.

DateTimeToString	Converts a value from time format to a string.

DateToStr	Converts a value from date format to a string.

DayOfWeek	Returns the current day of the week

DecodeDate	Decodes the specified date

DecodeTime	Decodes the specifies time.

EncodeDate	Returns values specified in date format.

EncodeTime	Returns values specified in time format.

FormatDateTime	Formats a date and time using the specified format.

Now	Returns the current date and time.

StrToDate	Coverts a string to a date format.

StrToDateTime	Converts a string to a date/time format.

StrToTime	Converts a string to a time format.

Time	Returns the current time.

TimeToStr	Converts a time format to a string.

Note:	All of the Date/Time routines use the Currency and Date/Time formatting variables.


Dynamic allocation routines

Categorical procedures and functions

Dispose	Disposes of a dynamic variable.

FreeMem	Disposes of a dynamic variable of a given size.

GetMem	Creates a dynamic variable of the specified size and puts the address of the block in a pointer variable.

New	Creates a new dynamic variable and sets a pointer variable to point to it.


Exception-handling routines

Categorical procedures and functions

Abort	Raises a silent exception.

ExceptAddr	Returns the address at which current exception was raised.

ExceptObject	Returns a reference to the current exception.

OutOfMemoryError	Raises the OutOfMemory exception.

ShowException	Displays the message associated with an exception.


File-management routines

Categorical procedures and functions

ChangeFileExt	Changes the file extension

DateTimeToFileDate	Converts the Delphi date format to the DOS date format.

DeleteFile	Removes a file.

DiskFree	Returns the amount of free disk space.

DiskSize	Returns the size of the specified disk.

ExpandFileName	Returns a string containing a fully qualified path name and file name.

ExpandUNCFileName	Returns a string containing a fully qualified network path name and file name.

ExtractFileDir 	Returns only the drive and directory parts of the file name.

ExtractFileDrive	Returns a only the drive'portion of a fully qualified path name.

ExtractFileExt	Returns only the file extension.

ExtractFileName	Returns only the file name.

ExtractFilePath	Returns the path to the specified file.

FileAge	Returns the age of a file.

FileClose	Closes a specific file.

FileCreate	Creates a file with the specified name.

FileDateToDateTime	Converts a DOS date format to the Delphi date format.

FileExists	Returns True if file exists.

FileGetAttr	Returns file attributes

FileGetDate	Returns the DOS date-and-time stamp of the file.

FileOpen	Opens a specific file using specified access mode.

FileRead	Reads from a specific file.

FileSearch	Searches through the directories for a specific file.

FileSeek	Changes the current position of the file.

FileSetAttr	Sets file attributes

FileSetDate	Sets the DOS date-and-time stamp of the file.

FileWrite	Writes to a specific file.

FindClose	Terminates a FindFirst/FindNext sequence.

FindFirst	Searches a directory for a specified file name and set of attributes.

FindNext	Returns the next entry that matches the name and attributes.

RenameFile	Renames a file.


Floating-point conversion routines

Categorical procedures and functions

FloatToDecimal	Converts a floating-point value to a decimal representation.

FloatToStrF	Converts the floating-point value to its string representation.

FloatToStr	Converts the floating-point value to its string representation.

FloatToText	Converts the given floating-point value to its decimal representation.

FloatToTextFmt	Converts the given floating-point value to its decimal representation.

FormatFloat	Formats the floating-point value using the format string given by Format.

StrToFloat	Converts the given string to a floating-point value.

TextToFloat	Converts the null-terminated string to a floating-point value.


Flow-control routines

Categorical procedures and functions

Break	Terminates a for, while, or repeat statement.

Continue	Continues a for, while, or repeat statement.

Exit	Exits immediately from the current block.

Halt	Stops program execution and returns to the operating system.

RunError	Stops program execution.


I/O routines

See also	Categorical procedures and functions

AssignFile	Assigns the name of an external file to a file variable.

CloseFile	Closes an open file.

Eof	Returns the end-of-file status.

Erase	Erases an external file.

FilePos	Returns the current file position of a file.

FileSize	Returns the current size of a file.

GetDir	Returns the current directory of specified drive.

IOResult	Returns the status of the last I/O operation performed.

MkDir	Creates a subdirectory.

Rename	Renames an external file.

Reset	Opens an existing file.

Rewrite	Creates and opens a new file.

RmDir	Removes an empty subdirectory.

Seek	Moves the current position of a file to a specified component.

Truncate	Truncates the file at the current file position.


See also

File-management routines


Memory-management routines

Categorical procedures and functions

AllocMem	Allocates a block onto the heap.

GetHeapStatus	Returns the current status of the memory manager.

GetMemoryManager	Returns the entry points of memory manager.

ReAllocMem	Allocates a dynamic variable.

SetMemoryManager	Sets entry points of the memory manager.


Miscellaneous routines

Categorical procedures and functions

AddExitProc	Adds a procedure to the run-time library's exit procedure list

ChDir	Changes the current directory

Exclude	Excludes an element from a set.

FillChar	Fills a specified number (count) of contiguous bytes with a specified value (can be type Byte or Char).

Hi	Returns the high-order byte of the argument.

Include	Includes an element in a set.

Lo	Returns the low-order Byte of the argument.

Move	Copies bytes from source to dest.

ParamCount	Returns the number of parameters passed to the program on the command line.

ParamStr	Returns a specified command-line parameter.

Random	Returns a random number.

Randomize	Initializes the built-in random number generator with a random value (obtained from the system clock).

SizeOf	Returns the number of bytes occupied by the argument.

Swap	Swaps the high- and low-order bytes of the argument.

UpCase	Converts a character to uppercase.


Ole string support routines

Categorical procedures and functions

OleStrToString

OleStrToStrVar

StringToOleStr


Ordinal routines

Categorical procedures and functions

Dec	Decrements a variable.

Inc	Increments a variable.

Odd	Tests if the argument is an odd number.

Pred	Returns the predecessor of the argument.

Succ	Returns the successor of the argument.


Pointer and address routines

Categorical procedures and functions

Addr	Returns the address of a specified object.

Assigned	Tests to determine if a function or procedural variable is nil.


String-formatting routines

Categorical procedures and functions

FmtStr	Formats a series of arguments and the results are returned in the parameter Result.

Format	Formats a series of arguments and returns the result as a Pascal string.

FormatBuf	Formats a series of arguments.

StrFmt	Formats a series of arguments.

StrLFmt	Formats a series of arguments and the result contains a pointer to the destination buffer.


String-handling routines (null-terminated)

See also	Categorical procedures and functions

StrAlloc	Allocates a buffer for a null-terminated string with a maximum length of Size - 1.

StrBufSize	Returns the maximum number of characters that may be stored in a string buffer allocated by StrAlloc.

StrCat	Appends a copy of one string to the end of another and returns the concatenated string.

StrComp	Compares two strings.

StrCopy	Copies one string to another.

StrDispose	Disposes a string on a heap.

StrECopy	Copies one string to another and returns a pointer to the end of the resulting string.

StrEnd	Returns a pointer to the end of a string.

StrIComp	Compares two strings without case sensitivity.

StrLCat	Appends characters from one string to the end of another and returns the concatenated string.

StrLComp	Compares two strings, up to a maximum length.

StrLCopy	Copies characters from one string to another.

StrLen	Returns the number of characters in Str.

StrLIComp	Compares two strings, up to a maximum length, without case sensitivity.

StrLower	Converts a string to lower case.

StrMove	Copies characters from one string to another.

StrNew	Allocates a string on a heap.

StrPas	Converts a null-terminated string to a Pascal-style string.

StrPCopy	Copies a Pascal-style string to a null-terminated string.

StrPLCopy	Copies a maximum of MaxLen characters from the Pascal style string Source into the null-terminated string Dest.

StrPos	Returns a pointer to the first occurrence of a string in another string.

StrRScan	Returns a pointer to the last occurrence of a character in a string.

StrScan	Returns a pointer to the first occurrence of a character in a string.

StrUpper	Converts a string to upper case.


See also

Null-terminated strings

String-handling routines (Pascal-style)


String-handling routines (Pascal-style)

See also	Categorical procedures and functions

AdjustLineBreaks 	Adjusts line breaks in a given string to be true CR/LF sequences.

AnsiCompareStr	Performs a case sensitive compare of two strings.

AnsiCompareText	Performs a non-case sensitive compare of two strings.

AnsiLowerCase	Converts characters to lowercase.

AnsiUpperCase	Converts characters to uppercase.

CompareStr	Performs a case sensitive compare of two strings

CompareText	Performs a non-case sensitive compare of two strings

Concat	Concatenates a sequence of strings.

Copy	Returns a substring of a string.

Delete	Deletes a substring from a string.

DisposeStr	Deallocates a string from the heap.

FmtLoadStr	Loads a string from a program's resource string table

Insert	Inserts a substring into a string.

IntToHex	Converts an integer to a hexidecimal

IntToStr	Converts an integer to a string

IsValidIdent	Returns true if the given string is a valid identifier.

Length	Returns the dynamic length of a string.

LoadStr	Loads the string resource from the application's executable file.

LowerCase	Lowercases the given string

NewStr	Allocates a new string on the heap.

Pos	Searches for a substring in a string.

Str	Converts a numeric value to a string.

StrToInt	Converts a string to an integer.

StrToIntDef	Converts a string to an integer or the default.

 Trim 	Trims leading and trailing spaces and control characters from a given string.

 TrimLeft 	Trims leading spaces and control characters from a given string.

 TrimRight 	Trims trailing spaces and control characters from a given string.

UpperCase	Uppercases the given string.

Val	Converts a string value to its numeric representation.


See also

PChar  routines


Text-file routines

Categorical procedures and functions

Append	Opens an existing file for appending.

Eoln	Returns the end-of-line status of a text file.

Flush	Flushes the buffer of a text file open for output.

Read	For typed files, reads a file component into a variable. For text files, reads one or more values into one or more variables.

Readln	Executes the Read procedure, then skips to the next line of the file.

SeekEof	Returns the end-of-file status of a file.

SeekEoln	Returns the end-of-line status of a file.

SetTextBuf	Assigns an I/O buffer to a text file.

Write	For typed files, writes a variable into a file component. For text files, writes one or more values to the file.

Writeln	Executes the Write procedure, then outputs an end-of-line marker to the file.


Thread support routines

Categorical procedures and functions

BeginThread	Creates a thread in a manner appropriate for use with the memory manager.

EndThread	Calls the WinAPI routine ExitThread.


Transfer routines

Categorical procedures and functions

Chr	Returns a character with a specified ordinal number.

High	Returns the highest value in the range of the argument.

Low	Returns the lowest value in the range of the argument.

Ord	Returns the ordinal number of an ordinal-type value.

Round	Rounds a real-type value to an Integer-type value.

Trunc	Truncates a real-type value to an Integer-type value.


Untyped file routines

Categorical procedures and functions

BlockRead	Reads one or more records into a variable.

BlockWrite	Writes one or more records from a variable.


Variant support routines

Categorical procedures and functions

VarArrayCreate	Creates a variant array of given bounds and type.

VarArrayDimCount	Returns the number of dimensions of a given variant.

VarArrayHighBound	Returns the high bound of a given dimension of a given variant array.

VarArrayLock	Locks a given variant array.

VarArrayLowBound	Returns the low bound of a given dimension of a given variant array.

VarArrayOf	Returns a given variant array with specified elements.

VarArrayRedim	Resizes a given variant array by changing the high bound.

VarArrayUnLock	Unlocks a given variant array.

VarAsType	Converts a variant to a specified type.

VarCast	Converts a variant to a specified type and stores it.

VarClear	Clears a given variant.

VarCopy	Copies a given variant into a specified variant.

VarFromDateTime	Returns a variant that contains a given date and time.

VarIsArray	Returns whether a given variant is an array.

VarIsEmpty	Returns whether a given variant is Unassigned.

VarIsNull	Returns whether a given variant is NULL.

VarToDateTime	Converts a given variant to a date and time value.

VarType	Converts a variant to a specified type and stores it.


Wide character routines

Categorical procedures and functions

StringToWideChar	Converts a string from ANSI to UNICODE.

WideCharLenToString 	Converts UNICODE characters to ANSI.

WideCharLenToStrVar

WideCharToString 	Converts a UNICODE string to an ANSI string.

WideCharToStrVar


Units
VCL units

Here is a listing of the standard units that are shipped with the Delphi Visual Component Library.

Buttons unit

Classes unit

ClipBrd unit

ComCtrls

Controls unit

DB unit

DBCtrls unit

DBGrids unit

DBLogDlg unit

DBLookup unit

DBTables unit

DDEMan unit

Dialogs unit

DsgnIntf unit

ExtCtrls unit

FileCtrl unit

Forms unit

Graphics unit

Grids unit

IniFiles unit

Mask unit

Menus unit

Messages unit

MPlayer unit

Outline unit

Oleauto unit

Olectnrs unit

OleCtrls unit

Printers unit

Registry unit

Report unit

StdCtrls unit

TabNotBk unit

Tabs unit

For a listing of the units that are part of the RTL see RTLUnits.


Buttons unit

The Buttons unit contains the declarations for SpeedButtons, bitmap buttons, and for the enumerated type associated with them.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Buttons unit:

Components

TBitBtn

TSpeedButton

Types

TBitBtnKind

TButtonLayout

TButtonStyle

TNumGlyphs

Routines

DrawButtonFace

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Classes unit

The Classes unit contains the declarations for many of the base object classes that are used by Delphi.

The Classes unit is automatically added to the uses clause whenever you create a new form.

The following is a list of items declared in the Classes unit:

Objects

TBits

TCollection

TCollectionItem

TCustomMemoryStream

TFiler

TFileStream

THandleStream

TList

TMemoryStream

TPersistent

TReader

TResourceStream

TStream

TStringList

TStrings

TThread

TWriter

Components

TComponent

Types

TAlignment

TComponentClass

TComponentName

TComponentState

TComponentStyle

TDuplicates

TFilerFlags

TFindMethodEvent

TGetChildProc

TGetStrProc

THelpContext

THelpEvent

TLeftRight

TListSortCompare

TNotifyEvent

TOperation

TPersistentClass

TReadComponentsProc

TReaderError

TReaderProc

TSetNameEvent

TShiftState

TStreamProc

TThreadMethod

TThreadPriority

TValueType

TWriterProc

Exceptions

EBitsError

EClassNotFound

EComponentError

EFCreateError

EFilerError

EFOpenError

EInvalidImage

EListError

EParserError

EReadError

EResNotFound

EStreamError

EStringListError

EThread

EWriteError

Constants

MaxListSize

Routines

Bounds

FindClass

GetClass

ObjectTextToResource

ObjectBinaryToText

ObjectResourceToText

ObjectTextToBinary

Point

ReadComponentRes

ReadComponentResFile

Rect

RegisterClass

RegisterClassAlias

RegisterClasses

RegisterComponents

RegisterNoIcon

UnRegisterClass

UnRegisterClasses

WriteComponentResFile

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Clipbrd unit

The ClipBrd unit contains the declaration for the Clipboard object and creates an instance of the Clipboard. The Clipboard object encapsulates the Windows Clipboard.

If you want to use the Clipbrd unit, you must add it to the unit's uses clause.

The following items are declared in the Clipbrd unit:

Objects

TClipboard

Variables

CF_PICTURE

CF_Component

Routines

Clipboard

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


ComCtrls unit

The ComCtrls unit contains the declarations for the components that appear on the Win95 page of the Component palette and their assocated routines and types.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the ComCtrls unit:

Objects

TConversion

THeaderSection

THeaderSections

TIconOptions

TListColumn

TListColumns

TListItem

TListItems

TParaAttributes

TStatusPanel

TStatusPanels

TTextAttributes

TTreeNode

TTreeNodes

Components

THeaderControl

THotKey

TListView

TPageControl

TProgressBar

TRichEdit

TStatusBar

TTabControl

TTabSheet

TTreeView

TTrackBar

TUpDown

Types

TConsistentAttribute

TConsistentAttributes

TDisplayCode

TDrawPanelEvent

TDrawSectionEvent

THeaderSectionStyle

THitTest

THitTests

THKInvalidKey

THKInvalidKeys

THKModifier

THKModifiers

TIconArrangement

TItemChange 	For OnChange events

TItemChange 	For OnChanging events

TItemState

TItemStates

TListArrangement

TLVChangeEvent

TLVChangingEvent

TLVCompareEvent

TLVColumnClickEvent

TLVDeletedEvent

TLVEditedEvent

TLVEditingEvent

TNodeAttachMode

TNumberingStyle

TRichEditProtectChange

TRichEditResizeEvent

TRichEditSaveClipboard

TSearchType

TSearchTypes

TSectionNotifyEvent

TSectionTrackEvent

TSectionTrackState

TSortType

TStatusPanelBevel

TStatusPanelStyle

TTabChangingEvent

TTickMark

TTickStyle

TTrackBarOrientation

TTVChangedEvent

TTVChangingEvent

TTVCollapsingEvent

TTVCompareEvent

TTVEditedEvent

TTVEditingEvent

TTVExpandedEvent	For OnDeletion events

TTVExpandedEvent	For OnExpanded events

TTVExpandingEvent

TUDAlignButton

TUDBtnType

TUDChangingEvent

TUDClickEvent

TUDOrientation

TViewStyle

Exceptions

ETreeViewError

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Controls unit

The Controls unit contains the declarations for many controls such as TControl, TWinControl, TGraphicControl and TCustomControl and their assocated routines and types.

The Controls unit is automatically added to the uses clause whenever you create a new form.

The following items are declared in the Controls unit:

Objects

TChangeLink

TDragControlObject

TDragObject

Components

TControl

TControlCanvas

TCustomControl

TGraphicControl

THintWindow

TImageList

TWinControl

Types

TAlign

TCaption

TCMActivate

TCMCancelMode

TCMDeactivate

TCMDesignHitTest

TCMDialogChar

TCMDialogKey

TCMEnter

TCMExit

TCMFocusChanged

TCMGotFocus

TCMHitTest

TCMLostFocus

TCMWantSpecialKey

TControlClass

TControlState

TControlStyle

TCreateParams

TCursor

TDragDropEvent

TDragMode

TDragOverEvent

TDragState

TEndDragEvent

THintWindowClass

TImageType

TKeyEvent	For OnKeyDown events

TKeyEvent	For OnKeyUp events

TKeyPressEvent

TLoadResource

TMouseButton

TMouseEvent	For OnMouseDown events

TMouseEvent	For OnMouseUp events

TMouseMoveEvent

TResType

TStartDragEvent

TTabOrder

Exceptions

EInvalidOperation

EOutOfResources

Constants

Cursor identifiers

TModalResult values

VCL control message IDs

VCL control notification IDs

Routines

CursorToIdent

CursorToString

FindControl

FindDragTarget

GetCaptureControl

GetCursorValues

GetLongHint

GetShortHint

IdentToCursor

SetCaptureControl

StringToCursor

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DB unit

The DB unit contains the declarations for the TDatabase, TDataSource, and TField components and includes their associated routines and types.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the DB unit:

Objects

TFieldDef

TFieldDefs

TSessionList

Components

TDataBase

TDataSource

TField

TSession

Types

TBookmark

TConfigMode

TDataAction

TDataChangeEvent

TDataSetErrorEvent	For the OnDeleteError event

TDataSetErrorEvent	For the OnEditError event

TDataSetErrorEvent	For the OnPostError event

TDataSetNotifyEvent

TDataSetState

TFieldClass

TFieldGetTextEvent

TFieldKind

TFieldNotifyEvent	For the OnChange event

TFieldNotifyEvent	For the OnValidate event

TFieldSetTextEvent

TFieldType

TFilterOption

TFilterOptions

TFilterRecordEvent

TLocale

TLocateOption

TLocateOptions

TLoginEvent

TOnServerYieldEvent

TPasswordEvent

TSymbolStr

TTraceFlag

TTraceFlags

TTransIsolation

TUpdateAction

TUpdateErrorEvent

TUpdateKind

TUpdateRecordEvent

TUpdateRecordTypes

TUpdateStatus

Exceptions

EDatabaseError

Variables

Session

Sessions

Routines

AnsiToNative

Check

DatabaseError

DbiError

NativeToAnsi

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DBCtrls unit

The DBCtrls unit contains the declarations for the data aware components.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the DBCtrls unit:

Components

TDBCheckBox

TDBComboBox

TDBCtrlGrid

TDBEdit

TDBImage

TDBListBox

TDBLookupComboBox

TDBLookupListBox

TDBMemo

TDBNavigator

TDBRadioGroup

TDBText

Types

ENavClick

TButtonSet

TDBCtrlGridBorder

TDBCtrlGridKey

TDBCtrlGridOrientation

TNavigateBtn

TPaintPanelEvent

Exceptions

To see a listing of items declared in this unit including their declarations, use the ObjectBrower


DBGrids unit

The DBGrids unit contains the declarations for the database grid and its associated routines and types.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the DBGrids unit:

Objects

TColumn

TColumnTitle

TDBGridColumns

Components

TDBGrid

Types

TColumnButtonStyle

TColumnValues

TDBGridColumnsState

TDBGridOption

TDBGridOptions

TDrawColumnCellEvent

TDrawDataCellEvent

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DBLookup Unit
DBLogDlg unit

The DBLogDlg unit contains the declarations for the LoginDialog and LoginDialogEx functions:

Routines

LoginDialog

LoginDialogEx

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DBLogDlg Unit
DBLookup unit

The DBLookup unit contains the declarations for the TDBLookupCombo and TDBLookupList.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the DBLookup unit:

Components

TDBLookupCombo

TDBLookupList

Types

TDBLookupComboStyle

TDBLookupListOption

TDBLookupListOptions

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DBTables unit

The DBTables unit contains the declarations for the TTable, TQuery, TBatchMove, and TStoredProc components, as well as, the declarations for the fields associated with a table.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the DBTables unit:

Components

TAutoIncField

TBatchMove

TBCDField

TBlobField

TBlobStream

TBooleanField

TBytesField

TCurrencyField

TDateField

TDateTimeField

TFloatField

TGraphicField

TIntegerField

TMemoField

TQuery

TSmallIntField

TStoredProc

TStringField

TTable

TTimeField

TUpdateSQL

TVarBytesField

TWordField

Objects

TIndexDef

TIndexDefs

TParam

TParams

Types

TBlobType

TBatchMode

TBlobStreamMode

TIndexOptions

TLockType

TParamBindMode

TParamType

TTableType

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DdeMan unit

See also

The DdeMan unit contains components and types that enable you to build applications for dynamic-data exchange (DDE).

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the DdeMan unit:

Components

TDdeClientConv

TDdeClientItem

TDdeServerConv

TDdeServerItem

Types

TDataMode

TMacroEvent

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


See also

Using DDE


Dialogs unit

The Dialogs unit contains the declarations for the common dialog boxes which are found on the Dialogs page of the Component palette and routines for displaying message boxes. All components declared in this unit are decendants of TCommonDialog.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Dialogs unit:

Components

TColorDialog

TCommonDialog

TFindDialog

TFontDialog

TOpenDialog

TPrintDialog

TPrinterSetupDialog

TReplaceDialog

TSaveDialog

Types

TColorDialogOptions

TCustomColors

TFDApplyEvent

TFileEditStyle

TFileExt

TFindOptions

TFontDialogDevice

TFontDialogOptions

TMsgDlgBtn

TMsgDlgButtons

TMsgDlgType

TOpenOptions

TPrintDialogOptions

TPrintRange

Constants

mbAbortRetryIgnore

mbOKCancel

mbYesNoCancel

Routines

InputBox

InputQuery

MessageDlgPos

MessageDlg

ShowMessagePos

ShowMessage

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


DsgnIntf unit

The DsgnIntf unit contains the declarations for the various property editors that Delphi uses in the Object Inspector. It also contains objects which enable you to create your own property editors and routines which enable you to register your editor with your custom component.

To use any of the property editors in your own components, you must add the DsgnIntf unit to the uses clause of the calling form's unit.

The following items are declared in the DsgnIntf unit:

Objects

TCaptionProperty

TCharProperty

TClassProperty

TColorProperty

TComponentEditor

TComponentList

TComponentProperty

TCursorProperty

TDefaultEditor

TEnumProperty

TFloatProperty

TFontNameProperty

TFontProperty

TFormDesigner

TIntegerProperty

TMethodProperty

TModalResultProperty

TMPFilenameProperty

TOrdinalProperty

TPropertyEditor

TSetElementProperty

TSetProperty

TShortCutProperty

TStringProperty

TTabOrderProperty

Types

TComponentEditorClass

TGetPropEditProc

TPropertyAttributes

TPropertyEditorClass

Exceptions

EPropertyError

Routines

GetComponentEditor

GetComponentProperties

RegisterComponentEditor

RegisterPropertyEditor

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


ExtCtrls unit

The ExtCtrls unit contains the declarations for the certain components on the Standard and Additional pages of the Component palette.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the ExtCtrls unit.

Components

TBevel

TCustomPanel

TCustomRadioGroup

THeader

TImage

TNotebook

TPaintBox

TPanel

TRadioGroup

TShape

TTimer

Objects

Types

TBevelShape

TBevelStyle

TBevelWidth

TBorderWidth

TPanelBevel

TSectionEvent	for OnSized events

TSectionEvent	for OnSizing events

TShapeType

Routines

Frame3D

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


FileCtrl unit

The FileCtrl unit contains the declarations for the certain components on the System page of the Component palette.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the FileCtrl unit:

Components

TDirectoryListBox

TDriveComboBox

TFileListBox

TFilterComboBox

Types

TFileAttr

TFileType

TSelectDirOpts

TTextCase

Routines

DirectoryExists

ForceDirectories

SelectDirectory

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Forms unit

The Forms unit contains the declarations for TForm and its associated objects, types, and routines.

The Forms unit is automatically added to the uses clause whenever you create a new form.

The following items are declared in the Forms unit:

Components

TApplication

TControlScrollBar

TForm

TScreen

TScrollBox

TScrollingWinControl

Objects

TDesigner

Types

TBorderIcons

TBorderStyle

TCloseAction

TCloseEvent

TCloseQueryEvent

TExceptionEvent

TFormBorderStyle

TFormClass

TFormStyle

TIdleEvent

TMessageEvent

TModalResult

TPosition

TPrintScale

TScrollBarInc

TScrollBarKind

TShowHintEvent

TTileMode

TWindowHook

TWindowState

TWndMethod

Variables

Application

HintWindowClass

Screen

Routines

AllocateHWnd

DeallocateHWnd

FreeObjectInstance

GetParentForm

IsAccel

KeyDataToShiftState

KeysToShiftState

MakeObjectInstance

ValidParentForm

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Graphics unit

The Graphics unit contains the Delphi encapsulation of the Windows GDI unit. It enables you to use fonts, bitmaps, metafiles, and pictures in your application.

The Graphics unit is automatically added to the uses clause whenever you create a new form.

The following items are declared in the Graphics unit:

Objects

TBitmap

TBrush

TCanvas

TFont

TGraphic

TGraphicsObject

TIcon

TMetafile

TMetafileCanvas

TPen

TPicture

Types

HMETAFILE

TBrushStyle

TColor

TCopyMode

TFillStyle

TFontName

TFontPitch

TFontStyles

TGraphicClass

TPenMode

TPenStyle

Exceptions

EInvaildGraphic

EInvalidGraphicOperation

Constants

Color constants for the Color property

Color mode contants for the CopyMode property

Routines

ColorToIdent

ColorToRGB

ColorToString

GetColorValues

GetDIB

GetDIBSizes

GraphicExtension

GraphicFilter

IdentToColor

InitGraphics

MemAlloc

PaletteChanged

StringToColor

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Grids unit

The Grids unit contains the declarations for TDrawGrid, and TStringGrid and their associated types and routines.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Grids unit:

Components

TDrawGrid

TStringGrid

Objects

TCustomGrid

Exceptions

EInvalidGridOperation

Types

TDrawCellEvent

TGetEditEvent	For the OnGetEditMask event

TGetEditEvent	For the OnGetEditText event

TGridCoord

TGridDrawState

TGridOptions

TGridRect

TGridScrollDirection

TMovedEvent

TSelectCellEvent

TSetEditEvent

Constants

MaxCustomExtents

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


IniFiles unit

The IniFiles unit contains the declaration for an object which enables you to read and write your own .INI files.

To use the IniFiles unit, you must add it to the uses clause of the calling form's unit.

The following items are declared in the IniFiles unit:

Object

TIniFile

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Mask unit

The Mask unit contains declarations character masks and picture fields.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Mask unit:

Components

TCustomMaskEdit

TMaskEdit

Types

Exceptions

EDBEditError

Constants

Mask Character Constants

Routines

FormatMaskText

MaskGetFldSeparator

MaskGetMaskBlank

MaskGetMaskSave

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Menus unit

The Menus unit contains the declarations for TMainMenu and TPopupMenu and their associated objects, types, and routines.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Menus unit:

Components

TMainMenu

TMenu

TMenuItem

TPopupMenu

Types

TFindItemKind

TMenuBreak

TPopupAlignment

TShortCut

Exceptions

EMenuError

Routines

NewItem

NewLine

NewMenu

NewPopupMenu

NewSubMenu

ShortCut

ShortCutToKey

ShortCutToText

TextToShortCut

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Messages unit

See also

The Messages Unit provides message-structured types for all the standard Windows messages.

The types declared in this unit split out fields that are packed into message parameters.

The Messages unit is automatically added to the uses clause whenever you create a new form.

Note:	There is not a message structure for all of the Windows messages. If a particular message structure does not exist, use the generic message structure TMessage.

The following items are declared in the Messages unit:

Types

TMessage

TWMActivate

TWMActivateApp

TWMAskCBFormatName

TWMCancelMode

TWMChangeCBChain

TWMChar

TWMCharToItem

TWMChildActivate

TWMChooseFont_GetLogFont

TWMClear

TWMClose

TWMCommand

TWMCommNotify

TWMCompacting

TWMCompareItem

TWMCopy

TWMCreate

TWMCtlColor

TWMCut

TWMDDE_Ack

TWMDDE_Advise

TWMDDE_Data

TWMDDE_Execute

TWMDDE_Initiate

TWMDDE_Poke

TWMDDE_Request

TWMDDE_Terminate

TWMDDE_Unadvise

TWMDeadChar

TWMDeleteItem

TWMDestroy

TWMDestroyClipboard

TWMDevModeChanged

TWMDrawClipboard

TWMDrawItem

TWMDropFiles

TWMEnable

TWMEndSession

TWMEnterIdle

TWMEraseBkgnd

TWMFontChange

TWMGetDlgCode

TWMGetFont

TWMGetMinMaxInfo

TWMGetText

TWMGetTextLength

TWMHScroll

TWMHScrollClipboard

TWMIconEraseBkgnd

TWMInitDialog

TWMInitMenu

TWMInitMenuPopup

TWMKey

TWMKeyDown

TWMKeyUp

TWMKillFocus

TWMLButtonDblClk

TWMLButtonDown

TWMLButtonUp

TWMMButtonDblClk

TWMMButtonDown

TWMMButtonUp

TWMMDIActivate

TWMMDICascade

TWMMDICreate

TWMMDIDestroy

TWMMDIGetActive

TWMMDIIconArrange

TWMMDIMaximize

TWMMDINext

TWMMDIRestore

TWMMDISetMenu

TWMMDITile

TWMMeasureItem

TWMMenuChar

TWMMenuSelect

TWMMouse

TWMMouseActivate

TWMMouseMove

TWMMove

TWMNCActivate

TWMNCCalcSize

TWMNCCreate

TWMNCDestroy

TWMNCHitTest

TWMNCHitMessage

TWMNCLButtonDblClk

TWMNCLButtonDown

TWMNCLButtonUp

TWMNCMButtonDblClk

TWMNCMButtonDown

TWMNCMButtonUp

TWMNCMouseMove

TWMNCPaint

TWMNCRButtonDblClk

TWMNCRButtonDown

TWMNCRButtonUp

TWMNextDlgCtl

TWMNoParams

TWMPaint

TWMPaintClipboard

TWMPaintIcon

TWMPaletteChanged

TWMPaletteIsChanging

TWMParentNotify

TWMPaste

TWMPower

TWMQueryDragIcon

TWMQueryEndSession

TWMQueryNewPalette

TWMQueryOpen

TWMQueueSync

TWMQuit

TWMRButtonDblClk

TWMRButtonDown

TWMRButtonUp

TWMRenderAllFormats

TWMRenderFormat

TWMScroll

TWMSetCursor

TWMSetFocus

TWMSetFont

TWMSetRedraw

TWMSetText

TWMShowWindow

TWMSize

TWMSizeClipboard

TWMSpoolerStatus

TWMSysChar

TWMSysColorChange

TWMSysCommand

TWMSysDeadChar

TWMSysKeyDown

TWMSysKeyUp

TWMSystemError

TWMTimeChange

TWMTimer

TWMUndo

TWMVKeyToItem

TWMVScroll

TWMVScrollClipboard

TWMWindowPosChanged

TWMWindowPosChanging

TWMWindowPosMsg

TWMWinIniChange

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


See also

Handling messages


MPlayer unit

The MPlayer unit contains the declaration for the media player component and its associated types.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the MPlayer unit:

Components

TMediaPlayer

Types

TButtonSet

TMPBtnType

TMPDevCaps

TMPDevCapsSet

TMPDeviceTypes

TMPModes

TMPNotifyValues

TMPTimeFormats

Exceptions

EMPNotify

EMPPostNotify

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


OleCtnrs unit

The OleCntrs unit contains the declarations for TOleContainer and its associated objects, types and routines.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the OleCntrs unit:

Components

TOleContainer

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


OleCtrls unit

The OleCtrls unit contains the declarations for TOleControl and its associated objects, types and routines.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the OleCtrls unit:

Components

TOleControl

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Outline unit

The Outline unit contains the declaration for TOutline and its associated objects, types, and routines.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Outline unit:

Components

TOutline

Objects

TCustomOutline

TOutlineNode

Types

TAttachMode

TOutlineOptions

TOutlineOptions

TOutlineStyle

TOutlineType

Exceptions

EOutlineChange	For OnCollapse events

EOutlineChange	For OnExpand events

EOutlineError

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Printers unit

The Printers unit contains the declaration for TPrinter and its associated objects, variables, and routines.

TPrinter is the Delphi encapsulation of the Windows printer interface.

To use the Printers unit, you must add it to the uses clause of the calling form's unit.

The following items are declared in the Printers unit:

Objects

TPrinter

Types

TPrinterOrientation

Exceptions

EPrinter

Routines

AssignPrn

Printer

SetPrinter

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Registry unit

The Registry unit contains the declarations for the Registry object and its corresponding Ini file object.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Registry unit:

Objects

TRegIniFile

TRegistry


Report unit

The Report unit contains the declarations for TReport and its associated objects, and constants.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Report unit:

Components

TReport

Types

Exceptions

EReportError

Constants

Server type constants

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


You do not have Report Smith Help installed.


StdCtrls unit

The StdCtrls unit contains declarations for the components that appear on the Standard page of the Component palette and their associated objects, types, and constants.

The StdCrtls unit is automatically added to the uses clause whenever you create a new form.

The following items are declared in the StdCtrls unit:

Components

TButton

TButtonControl

TCheckBox

TComboBox

TCustomCheckBox

TCustomComboBox

TCustomEdit

TCustomLabel

TCustomListBox

TCustomMemo

TEdit

TGroupBox

TLabel

TListBox

TMemo

TRadioButton

TScrollBar

Types

TCheckBoxState

TComboBoxStyle

TEditCharCase

TDrawItemEvent

TListBoxStyle

TMeasureItemEvent

TOwnerDrawState

TScrollCode

TScrollEvent

TScrollStyle

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


TabNotBk unit

The TabNotBk unit contains the declaration for the TTabbedNotebook component and its associated objects.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the TabNotBk unit:

Components

TTabbedNotebook

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Tabs unit

The Tabs unit contains the declaration for the tab set and its associated objects, and types.

When you add a component declared in this unit to a form, the unit is automatically added to the uses clause of that form's unit.

The following items are declared in the Tabs unit:

Components

TTabSet

Types

TDrawTabEvent

TMeasureTabEvent

TTabChangingEvent

TTabStyle

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Abort method

See also	Example

Applies to

TPrinter object

Declaration

procedure Abort;

Description

The Abort procedure terminates the printing of a print job, dropping all unprinted data. The device is then set for the next print job. Use Abort to terminate the print job before it completes; otherwise, use the EndDoc method.

To use the Abort method, you must add the Printers unit to the uses clause of your unit.


Example

The following code aborts a print job if the user presses Esc. Note that you should set KeyPreview to True to ensure that the OnKeyDown event handler of Form1 is called.

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word; Shift: TShiftState);

begin

  if (Key=VK_ESCAPE) and Printer.Printing then

  begin

    Printer.Abort;

    MessageDlg('Printing aborted', mtInformation, [mbOK],0);

  end;

end;


See also

BeginDoc method

EndDoc method

Printer function

Printing property


Aborted property

See also	Example

Applies to

TPrinter object

Declaration

property Aborted: Boolean;

Description

Run-time and read-only. The Aborted property determines if the user aborted the print job, thereby calling the Abort method. If Aborted is True, the print job was aborted. If it is False, the user did not abort the print job.


Example

The following code displays a dialog box if the print job was aborted:

if Printer.Aborted then

  MessageDlg('The print job did not finish printing'), mtInformation, [mbOK], 0);


See also

Abort method

Printer variable

Printing property


AbortOnKeyViol property

See also	Example

Applies to

TBatchMove component

Declaration

property AbortOnKeyViol: Boolean;

Description

If AbortOnKeyViol is True (the default) and an integrity (key) violation occurs during the batch move operation, the Execute method will immediately terminate the operation. If you prefer to have the operation continue, with all key violations posted to the key violations table, set AbortOnKeyViol to False.

Note:	If you set AbortOnKeyViol to False, you should provide a KeyViolTableName to hold the records with errors.


Example

BatchMove1.AbortOnKeyViol := False;

BatchMove1.KeyViolTableName := 'KEYVIOL.DB';


See also

KeyViolCount property

KeyViolTableName property


AbortOnProblem property

See also	Example

Applies to

TBatchMove component

Declaration

property AbortOnProblem: Boolean;

Description

If AbortOnProblem is True (the default) and it would be necessary to discard data (truncate fields) from a source record to place it into the Destination, the Execute method will immediately terminate the batch move operation. If you prefer to have the operation continue, with all problems posted to the problems table, set AbortOnProblem to False.

Note:	If you set AbortOnProblem to False, you should provide a ProblemTableName to hold the records with problems.


Example

BatchMove1.AbortOnProblem := False;

BatchMove1.ProblemTableName := 'PROB.DB';


See also

ProblemCount property

ProblemTableName property


AbsoluteIndex property for tree nodes
AbsoluteIndex property

See also

Applies to

TTreeNode object

Declaration

property AbsoluteIndex: Integer;

Description

Run-time and read only. The AbsoluteIndex property is the Index of the item relative to the first item. The first item has an index of 0, and subsequent items are numbered sequentially. If an item has children, the Index value of the parent item is one less than the Index value of its first child item.


See also

Index property


Active property

Applies to

TApplication, TForm, TQuery, TSession, TStoredProc, TTable components

Description

Active property for Forms and Applications

Active property for Queries, Tables, and Stored Procedures

Active property for Sessions


Active property

Applies to

TApplication, TForm components

Declaration

property Active: Boolean;

Description

Read-only and run-time only. The Active property specifies whether the form or application form is active and has focus. Active returns True if the form or application has focus, or False if not.


Active property

Example

Applies to

TQuery, TStoredProc, TTable components

Declaration

property Active: Boolean;

Description

Set the Active property to True to open a dataset and put it in Browse state. Set it to False to close the dataset and put it in Inactive state. Changing the Active property is equivalent to calling the Open or Close method.

For TQuery and TStoredProc, if the SQL statement or stored procedure does not return a result set, then setting Active to True will raise an exception because Delphi expects to get a cursor. Use the ExecSQL or ExecProc method for such SQL statements or stored procedures. Note that the SQL statement or stored procedure will still be executed if you set Active to True, but an EDatabaseError exception is raised with the message 'Error creating cursor handle.'

Note:	Post is not called implicitly by setting Active to False. Use the BeforeClose event to post any pending edits explicitly or they will be lost.


Example

This example will toggle the table's Active property and update the form's caption accordingly.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Table1.Active := not Table1.Active;

  if Table1.Active then

    Caption := 'Table is Active'

  else

    Caption := 'Table is not Active';

end;


Active property

See also

Applies to

TSession component

Declaration

property Active: Boolean;

Description

The Active property specifies whether a session is active. Set it to True to start the session and make it the current session. Set it False to close the session. Setting Active to True triggers the OnStartup event and initializes the session with the values you gave to the NetFileDir and PrivateDir properties. Changing Active is equivalent to calling the Open or Close methods.


See also

Session variable

Close method

NetFileDir property

Open method

PrivateDir property


ActiveControl property

See also	Example

Applies to

TForm, TScreen components

Declaration

property ActiveControl: TWinControl;

Description

For forms, the ActiveControl property indicates which control has focus, or has focus initially when the form becomes active. Your application can use the ActiveControl property to access methods of the active control. Only one control, the active control, can have focus at a given time in an application.

For the screen, ActiveControl is a read-only property. The value of ActiveControl is the control that currently has focus on the screen.

Note:	When focus shifts to another control, the ActiveControl property is updated before the OnExit event of the original control with focus occurs.


Example

The following event handler responds to timer events by moving the active control one pixel to the right:

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  ActiveControl.Left := ActiveControl.Left + 1;

end;


See also

ActiveForm property

OnActiveControlChange event

OnEnter event

OnExit event


ActiveForm property

See also	Example

Applies to

TScreen component

Declaration

property ActiveForm: TForm;

Description

Run-time and read only. The ActiveForm property indicates which form currently has focus, or will have focus when the application becomes active again after another Windows application has been active.


Example

This example changes the color of the current form.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Screen.ActiveForm := clBlue;

end;


See also

ActiveControl property

ActiveMDIChild property

OnActivate event

OnActiveFormChange event

Screen variable


ActiveMDIChild property

See also	Example

Applies to

TForm component

Declaration

property ActiveMDIChild: TForm;

Description

Run-time and read only. The value of the ActiveMDIChild property is the form that currently has focus in an MDI application. This only applies if the form is of type fsMDIForm.


Example

This code uses a button on an MDI application. When the user clicks the button, the active MDI child form turns blue.

procedure TForm1.Button1Click(Sender: TObject);

var
  BlueForm: TForm;

begin

  BlueForm := Form1.ActiveMDIChild;

  BlueForm.Color := clBlue;

end;


See also

ActiveForm property

FormStyle property

MDIChildCount property

MDIChildren property


ActivePage property

Applies to

TNotebook, TPageControl, TTabbedNotebook components

Description

ActivePage property for TNotebook and TTabbedNotebook components

ActivePage property for TPageControl components


ActivePage property for TNotebook and TTabbedNotebook components
ActivePage property

See also	Example

Applies to

TNotebook, TTabbedNotebook components

Declaration

property ActivePage: string;

Description

The ActivePage property determines which page displays in the notebook or tabbed notebook control. The value of ActivePage must be one of the strings contained in the Pages property.


Example

This example uses a notebook control and a button on the form. The notebook has multiple pages, including one called Graphics options. When the user clicks the button, the Graphics options page displays in the notebook control.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Notebook1.ActivePage := 'Graphics options';

end;


See also

PageIndex property

TTabSet component


ActivePage property for page controls
ActivePage property

See also

Applies to

TPageControl component

Declaration

property ActivePage: TTabSheet;

Description

The ActivePage property specifies the active page and brings it to the foreground in the sequence of overlapping pages. Each page is a TTabSheet object. To activate a particular page either select its tab or set the ActivePage property. To select pages whose tabs are not visible use the FindNextPage or SelectNextPage methods. Only one page can be active at a time.


See also

FindNextPage method

Pages property

PageCount property

SelectNextPage method


Add method

Applies to

TCollection, TDBGridColumns, TFieldDefs ,THeaderSections, TIndexDefs, TList, TListColumns, TListItems, TStatusPanels, TStringList, TStrings, TTreeNodes, objects; TImageList, TMenuItem, TOutline components

Description

The Add method adds an item to a component.

Add method for TDBGridColumns Objects

Add method for List Objects

Add method for String Objects

Add method for Menu Items

Add method for Outlines

Add method for TFieldDefs Objects

Add method for TIndexDefs Objects

Add method for Collection Objects

Add method for Status Panels

Add method for Header Sections

Add method for Tree Nodes Objects

Add method for Image ListObjects

Add method for List Columns Objects

Add method for List Items Objects


Add method

See also

Applies to

TImageList object

Declaration

function Add(Image, Mask: TBitmap): Integer;

Description

The Add method adds an image and its mask to the ImageList object. Add returns the index of the added image.


See also

AddIcon method

AddMasked method

AddImages method


Add method for image list objects
Add method

See also	Example

Applies to

TTreeNodes object

Declaration

function Add(Node: TTreeNode; const S: string): TTreeNode;

Description

The Add method adds a new item (TTreeNode object) to a tree view. The item is added last in the list to which the item specified by the Node parameter belongs. The S parameter specifies the Text property of the new node. Add returns the item that has been added.


Example

The following example adds an item last in the list to which the selected item belongs in the tree view control.

TreeView1.Items.Add(TreeView1.Selected,'Sub Item1');


See also

AddChildFirst method

AddChildObjectFirst method

AddChildObject method

AddFirst method

AddChild method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


Add method for grid columns
Add method

Applies to

TDBGridColumns object

Declaration

function Add: TColumn;

Description

The Add method creates and returns a new TColumn object. The Columns Editor takes care of creating column objects at design time, so you only need to use Add if you want to create columns at run-time. The new column object is available via the Items property.


Add method for image list objects
Add method

Applies to

TFieldDefs object

Declaration

procedure Add(const Name: string; DataType: TFieldType; Size: Word; Required: Boolean);

Description

The Add method creates a new TFieldDef object using the Name, DataType, Size, and Required parameters, and adds it to Items.

You generally only need to use this method when creating new fields in a dataset, because the Items is filled for you when you open the dataset, or because Update fills Items without opening the dataset.

The Size parameter is only useful for some field types, such as ftString or ftBlob. For numeric field types, Size should be set to 0.

The value of the Required parameter determines whether the newly added field definition is a required field (that is, must contain data before the record can be posted). If the Required parameter is True, the value of the Required property of the TFieldDef object is also True. If the Required parameter is False, the value of the Required property is also False.


Add method for index definition objects
Add method

Applies to

TIndexDef object

Declaration

procedure Add(const Name, Fields: string; Options: TIndexOptions);

Description

The Add method creates a new TIndexDef object using the Name, Fields, and Options parameters, and adds it to Items. Generally you'll only need to use this method when you're creating new indexes on the fly, as the dataset will have already filled Items for you when it is opened, or the Update method will fill Items without opening the dataset.


Add method for image list objects
Add method

See also	Example

Applies to

TList object

Declaration

function Add(Item: Pointer): Integer;

Description

The Add method adds a new item to the end of a list. Add returns the position of the item in the list stored in the Items property; the first item in the list has a value of 0. Specify the item you want added to the list as the value of the Item parameter.


Example

This example adds a new object to a list in a list object:

type

  TMyClass = class

    MyString: string;

    constructor Create(S: string);

  end;

constructor TMyClass.Create(S: string);

begin

  MyString := S;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  MyList: TList;

  MyObject, SameObject: TMyClass;

begin

  MyList := TList.Create;	{ create the list }

  try

    MyObject := TMyClass.Create('Semper Fidelis!');	{ create a class instance }

    try

      MyList.Add(MyObject);	{ add instance to list }

      SameObject := TMyClass(MyList.Items[0]);	{ get first element in list }

      MessageDlg(SameObject.MyString, mtInformation, [mbOk], 0);	{ show it }

    finally

      MyObject.Free;

    end;	 don't forget to clean up! }

  finally

    MyList.Free;

  end;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  MyList: TList;

  MyObject, SameObject: TMyClass;

begin

  MyList := TList.Create;	{ create the list }

  try

    MyObject := TMyClass.Create('Semper Fidelis!');	{ create a class instance }

    try

      MyList.Add(MyObject);	{ add instance to list }

      SameObject := TMyClass(MyList.Items[0]);	{ get first element in list }

      MessageDlg(SameObject.MyString, mtInformation, [mbOk], 0);	{ show it }

    finally

      MyObject.Free;

    end;	{ don't forget to clean up! }

  finally

    MyList.Free;

  end;

end;


See also

Capacity property

Clear method

Delete method

Expand method

First method

IndexOf method

Insert method

Last method

Remove method


Add method for image list objects
Add method

See also	Example

Applies to

TStrings, TStringList objects

Declaration

function Add(const S: string): Integer;

Description

The Add method adds a new string to a string list. The S parameter is the new string. Add returns the position of the item in the list; the first item in the list has a value of 0.

For TStrings objects, such as the Items property of a list box, the new string is appended to the end of the list unless the Sorted property of the list box or combo box is True. In such a case the string is inserted into the list of strings so as to maintain the sort order.

For TStringList objects, the value of the Sorted property determines how a string is added. If Sorted is False, the string is appended to the list. If Sorted is True, the new string is inserted into the list of strings so as to maintain the sort order.


Example

This code uses a button and a list box on a form. When the user clicks the button, the code adds a new string to a list box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Add('New string');

end;

This code uses a list box, a button, and a label on a form. When the user clicks the button, the code adds a new string to the list box and reports its position in the list box as the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

var

  Position: Integer;

begin

  Position:= ListBox1.Items.Add('New item');

  Label1.Caption := IntToStr(Position);

end;


See also

AddObject method

AddStrings method

Clear method

Delete method

Duplicates property

Exchange method

Insert method

Items property

Move method

Sorted property


Add method for image list objects
Add method

See also	Example

Applies to

TMenuItem component

Declaration

procedure Add(Item: TMenuItem);

Description

The Add method adds a menu item to the end of a menu. Specify the menu item you want added as the value of the Item parameter.


Example

This code adds a menu item to a File menu:

procedure Form1.Button1Click(Sender: TSender);

var

  NewItem: TMenuItem;

begin

  NewItem := TMenuItem.Create(Self);

  NewItem.Caption := 'New item';

  File.Add(NewItem);

end;


See also

Delete method

Insert method


Add method for image list objects
Add method

See also	Example

Applies to

TOutline component

Declaration

function Add(Index: LongInt; const Text: string): LongInt;

Description

The Add method adds an outline item (TOutlineNode object) to an outline. The value of the Index parameter specifies where to add the new item. The Text parameter specifies the Text property value of the new item. Add returns the Index property value of the added item.

The added item is positioned in the outline as the last sibling of the outline item specified by the Index parameter. The new item shares the same parent as the item specified by the Index parameter. Outline items that appear after the added item are moved down one row and reindexed with valid Index values. This is done automatically unless BeginUpdate was called.

Note:	To add items to an empty outline, specify zero (0) as the Index parameter.


Example

The following code adds a new item at the top level of the outline. The new item is identified by the text 'New item':

Outline1.Add(0, 'New item');


See also

AddChild method

AddChildObject method

AddObject method

Insert method

MoveTo method


Add method for image list objects
Add method

See also

Applies to

TCollection object

Declaration

function Add: TCollectionItem;

Description

The Add method creates a new TCollectionItem object and adds it to the indexed array property Items. Add returns the new collection item. The Index property of the TCollectionItem contains its index value in the Items array of the TCollection object to which it is associated.


See also

Index property

Items property


Add method for image list objects
Add method

See also	Example

Applies to

TStatusPanels object

Declaration

function Add: TStatusPanel;

Description

The Add method creates a new TStatusPanel object on a status bar control. The TStatusPanels object is the container of these individual panels and is accessible with the Panels property of the status bar. To add a new panel to a status bar at design-time, use the Panels property and choose Add from the StatusBar Editor dialog box. The new panel is automatically added to the indexed list of status panels. It is also added to the TStatusPanels indexed property Items. The Index property of the TStatusPanel contains its index value in the Items array of the TStatusPanels object to which it belongs. New panels can also be added at run-time by using the Add method.


Example

This example adds a panel to a status bar when the user clicks on the button.

procedure TForm1.Button1Click(Sender: TObject);

begin

  StatusBar1.Panels.Add;

end;


See also

Index property

Items property

Panels property

BeginUpdate method


Add method for image list objects
Add method

See also

Applies to

THeaderSections object

Declaration

function Add: THeaderSection;

Description

The Add method creates a new THeaderSection object and adds it to the indexed property Items. The Index property of the THeaderSection contains its index value in the Items array of the THeaderSections object to which it belongs. To add a new section to a header at design time, use the Sections property and choose Add from the HeaderControl Sections Editor dialog box. The new header is added to the automatically indexed list of header sections.


See also

Index property

Items property

Sections property

BeginUpdate method


Add method for list items objects
Add method

See also	Example

Applies to

TListItems object

Declaration

function Add: TListItem;

Description

The Add method adds a new list item to the list view control. Add returns the list item that is added.

Example

The following example adds a new item to ListView1:

procedure TForm1.Button2Click(Sender: TObject);

var NewItem : TListItem;

begin

  NewItem := ListView1.Items.Add;

  NewItem.Caption := 'New Item';

end;


See also

Insert method

Items property

SubItems property


Add property for list columns objects
Add method

See also	Example

Applies to

TListColumns object

Declaration

function Add: TListColumn;

Description

Run-time only. The Add method for list columns objects adds a new TListColumn to the list view. To see the new column the list views ViewStyle property must be set to vsReport and ShowColumnHeaders must be set to True. Add returns the list column that is added.

Example

The following example adds a new column to the list view and sets its caption:

procedure TForm1.Button1Click(Sender: TObject);

var

  NewColumn: TListColumn;

begin

  NewColumn := ListView1.Columns.Add;

  NewColumn.Caption := 'NewColumn';

end;


See also

ViewStyle property

Columns property


AddAlias method

See also	Example

Applies to

TSession component

Declaration

procedure AddAlias(const Name, Driver: string; List: TStrings);

Description

The AddAlias method adds an alias of the given name to the session. Driver is the name of the database driver the database represented by the alias will use. List is a string list containing the parameters for the alias.

The session's ConfigMode property determines whether the alias is global (available to all applications that use the BDE) or local (available only to the session). Call the SaveConfigFile method to save global aliases permanently in the BDE configuration file.


Example

This example creates an alias for an InterBase database specifying needed parameters in the call to AddAlias.

var

  MyList: TStringList;

begin

  try

    MyList := TStringList.Create;

    with MyList do begin

      Add('SERVER NAME=IB_SERVER:/PATH/DATABASE.GDB');

      Add('USER NAME=MYNAME');

    end;

    Session1.AddAlias('NewIBAlias', 'INTRBASE', MyList);

  finally

    MyList.Free;

  end;

end;


See also

AddStandardAlias method

DeleteAlias method

GetDriverParams method

ModifyAlias method

Session variable


AddChild method

Applies to

TTreeNodes object; TOutline component

Description

AddChild Method for Outlines

AddChild Method for Tree Nodes Objects


AddChild method

See also	Example

Applies to

TOutline component

Declaration

function AddChild(Index: LongInt; const Text: string): LongInt;

Description

The AddChild method adds an outline item (TOutlineNode object) to an outline as a child of an existing item. The value of the Index parameter specifies where to add the new item. The Text parameter specifies the Text property value of the new item. AddChild returns the Index property value of the added item.

The added item is positioned in the outline as the last child of the outline item specified by the Index parameter. Outline items that appear after the added item are moved down one row and reindexed with valid Index values. This is done automatically unless BeginUpdate was called.

Note:	To add items to an empty outline, specify zero (0) as the Index parameter.


Example

The following code adds a new child to the selected item of the outline. The new item is identified by the text 'New child':

Outline1.AddChild(Outline1.SelectedItem, 'New child');


See also

Add method

AddChildObject method

AddObject method

Insert method

MoveTo method


AddChild method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddChild(Node: TTreeNode; const S: string): TTreeNode;

Description

The AddChild method adds a new item (TTreeNode object) to a tree view. The item is added as a child of the item specified by the Node parameter. It is added to the end of Node's list of child items. The S parameter specifies the Text property of the new item. AddChild returns the item that has been added.

Example

The following example adds a child to the selected item's list of child items in the tree view control.

TreeView1.Items.AddChild(TreeView1.Selected,'SubItem1');


See also

AddChildFirst method

AddChildObjectFirst method

AddChildObject method

AddFirst method

Add method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


AddChildFirst method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddChildFirst(Node: TTreeNode; const S: string): TTreeNode;

Description

The AddChildFirst method adds a new item (TTreeNode object) to a tree view. The item is added as a child of the item specified by the Node parameter. It is added to the beginning of Node's list of child items. The S parameter specifies the Text property of the new item. Items that appear after the added item are moved down one row and reindexed with valid Index values. AddChildFirst returns the item that has been added.


Example

The following example adds a child to the beginning of the selected item's list of child items in the tree view control.

TreeView1.Items.AddChildFirst(TreeView1.Selected,'SubItem1');


See also

AddChild method

AddChildObjectFirst method

AddChildObject method

AddFirst method

Add method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


AddChildObject method

Applies to

TTreeNodes object; TOutline component

Description

AddChildObject Method for Outlines

AddChildObject Method for Tree Nodes Objects


AddChildObject

See also	Example

Applies to

TOutline component

Declaration

function AddChildObject(Index: LongInt; const Text: string; const Data: Pointer): LongInt;

Description

The AddChildObject method adds an outline item (TOutlineNode object) containing data to an outline as a child of an existing item. The value of the Index parameter specifies where to add the new item. The Text parameter specifies the Text property value of the new item. The Data parameter specifies the Data property value of the new item. AddChild returns the Index property value of the added item.

The added item is positioned in the outline as the last child of the outline item specified by the Index parameter. Outline items that appear after the added item are moved down one row and reindexed with valid Index values. This is done automatically unless BeginUpdate was called.

Note:	To add items to an empty outline, specify zero (0) as the Index parameter.


Example

The following code adds a new child to the selected item of the outline. The new item is identified by the text 'New child'. The TBitmap object named Bitmap1 is attached to the new item:

Outline1.AddChildObject(Outline1.SelectedItem, 'New child', Bitmap1);


See also

Add method

AddChild method

AddObject method

Insert method

MoveTo method


AddChildObject method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddChildObject(Node: TTreeNode; const S: string; Ptr: Pointer):TTreeNode;

Description

The AddChildObject method adds a new item (TTreeNode object) containing data to a tree view. The item is added as a child of the item specified by the Node parameter. It is added to the end of Node's list of child items. The S parameter specifies the Text property of the new item. The Ptr parameter specifies the Data property value of the new item. AddChildObject returns the item that has been added.


Example

The following example adds a new child to the selected item's list of child items in the tree view control. The new item is identified by the text 'New Item'. The TBitmap object is attached to the new item.

TreeView1.Items.AddChildObject(TreeView1.Selected,'New Item',MyBitMap);


See also

AddChildFirst method

AddChild method

AddChildObject method

AddFirst method

Add method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


AddChildObjectFirst method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddChildObjectFirst(Node: TTreeNode; const S: string; Ptr: Pointer): TTreeNode;

Description

The AddChildObjectFirst method adds a new item (TTreeNode object) containing data to a tree view. The item is added as a child of the item specified by the Node parameter. It is added to the beginning of Node's list of child items. Items that appear after the added item are moved down one row and reindexed with valid Index values. The S parameter specifies the Text property of the new item. The Ptr parameter specifies the Data property value of the new item. AddChildObjectFirst returns the item that has been added.


Example

The following example adds a new item to the selected item's list of child items in the tree view control. The new item is added first in the list of child items. The new item is identified by the text 'New Item'. The TBitmap object is attached to the new item.

TreeView1.Items.AddChildObjectFirst(TreeView1.Selected,'New Item',MyBitMap);


See also

AddChildFirst method

AddChild method

AddChildObject method

AddFirst method

Add method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


AddFieldDesc method

Applies to

TFieldDefs object

Declaration

procedure AddFieldDesc(FieldDesc: FLDDesc; Required: Boolean; FieldNo: Word);

Description

AddFieldDesc creates a new TFieldDef object using the information provided by the Borland Database Engine in the FieldDesc parameter, and adds it to Items. Except for special purposes, you do not need to use this method because the Items is filled for you when you open the dataset, or because Update fills Items without opening the dataset.


AddFirst method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddFirst(Node: TTreeNode; const S: string): TTreeNode;

Description

The AddFirst method adds a new item (TTreeNode object) to a tree view. The item is added first to the list to which the item specified by the Node parameter belongs. Items that appear after the added item are moved down one row and reindexed with valid Index values. The S parameter specifies the Text property of the new node. AddFirst returns the item that has been added.


Example

The following example adds an item first in the list to which the selected item belongs in the tree view control.

TreeView1.Items.AddFirst(TreeView1.Selected,'Sub Item1');


See also

AddChild method

AddChildObjectFirst method

AddChildObject method

AddChildFirst method

Add method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


Add method for image list objects
AddIcon method

See also

Applies to

TImageList component

Declaration

function AddIcon(Image: TIcon): Integer;

Description

The AddIcon method adds an icon to the ImageList object. AddIcon returns the index of the added image.


See also

Add method

AddMasked method

AddImages method


Add method for image list objects
AddImages method

See also

Applies to

TImageList component

Declaration

procedure AddImages(Value: TCustomImageList);

Description

The AddImages method adds images from another image list specified by Value to the ImageList object.


See also

Add method

AddMasked method

AddIcon method


AddIndex method

See also	Example

Applies to

TTable component

Declaration

procedure AddIndex(const Name, Fields: string; Options: TIndexOptions);

Description

The AddIndex method creates a new index for the TTable. Name is the name of the new index. Fields is a list of the fields to include in the index. Separate the field names by a semicolon. Options is a set of values from the TIndexOptions type.

Note:	You can't add an index to a dBASE table with the index option ixCaseInsensitive. For example, the following code returns an error if Table1 is a dBASE table:

Table1.AddIndex(Name, Fields, [ixCaseInsensitive]);


Example

Table1.AddIndex('NewIndex', 'CustNo;CustName', [ixUnique, ixCaseInsensitive]);


See also

DeleteIndex method

IndexDefs property

IndexName property


Add method for image list objects
AddMasked method

See also

Applies to

TImageList component

Declaration

function AddMasked(Image: TBitmap; MaskColor: TColor): Integer;

Description

The AddMasked method adds an image to the ImageList, along with a color which is used to generate the transparent mask from the image.


See also

Add method

AddImages method


AddObject method

Applies to

TStringList, TStrings TTreeNodes objects; TOutline component

Description

The AddObject method adds an item containing data to a list.

AddObject Method for String and String List Objects

AddObject Method for Outlines

AddObject Method for Tree Nodes Objects


AddObject method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddObject(Node: TTreeNode; const S: string; Ptr: Pointer): TTreeNode;

Description

The AddObject method adds a new item (TTreeNode object) containing data to a tree view. The item is added last in the list to which the item specified by the Node parameter belongs. The S parameter specifies the Text property of the new node. The Ptr parameter specifies the Data property value of the new item. AddObject returns the item that has been added. The memory referenced by Ptr is not freed when the tree nodes object is freed.

Example

The following example adds an item last in the list to which the selected item belongs in the tree view control. The TBitmap object is attached to the new item.

TreeView1.Items.Add(TreeView1.Selected,'Sub Item1', MyBitmap);


See also

AddChildFirst method

AddChildObjectFirst method

AddChildObject method

AddFirst method

AddChild method

AddObjectFirst method

AddObject method

Insert method

MoveTo method

InsertObject method


AddObject method

See also	Example

Applies to

TStrings, TStringList objects

Declaration

function AddObject(const S: string; AObject: TObject): Integer;

Description

The AddObject method adds both a string and an object to a string or string list object. The string and the object are appended to the list of strings. Specify the string to be added as the value of the S parameter, and specify the object to be added as the value of the AObject parameter. The memory referenced by Ptr is not freed when the string object is freed.


Example

This code adds the string 'Orange' and a bitmap of an orange to an owner-draw list box:

procedure TForm1.Button1Click(Sender: TSender);

var

  Icon: TIcon;

begin

  Icon := TIcon.Create;

  Icon.LoadFromFile('ORANGE.ICO');

  ListBox1.Items.AddObject('Orange', Icon);

end;


See also

Add method

AddStrings method

IndexOf method

IndexOfObject method

InsertObject method

Objects property

Strings property


AddObject method

See also	Example

Applies to

TOutline component

Declaration

function AddObject(Index: LongInt; const Text: string; const Data: Pointer): LongInt;

Description

The AddObject method adds an outline item (TOutlineNode object) containing data to an outline. The value of the Index parameter specifies where to add the new item. The Text parameter specifies the Text property value of the new item. The Data parameter specifies the Data property value of the new item. AddObject returns the Index property value of the added item.

The added item is positioned in the outline as the last sibling of the outline item specified by the Index parameter. The new item shares the same parent as the item specified by the Index parameter. Outline items that appear after the added item are moved down one row and reindexed with valid Index values. This is done automatically unless BeginUpdate was called.

Note:	To add items to an empty outline, specify zero (0) as the Index parameter.


Example

The following code defines a record type of TMyRec and a record pointer type of PMyRec.

type

  PMyRec = ^TMyRec;

  TMyRec = record

    FName: string;

    LName: string;

  end;

Assuming these types are used, the following code adds an outline node to Outline1. A TMyRec record is associated with the added item. The FName and LName fields are obtained from edit boxes Edit1 and Edit2. The Index parameter is obtained from edit box Edit3. The item is added only if the Index is a valid value.

var

  MyRecPtr: PMyRec;

  OutlineIndex: LongInt;

begin

  New(MyRecPtr);

  MyRecPtr^.FName := Edit1.Text;

  MyRecPtr^.LName := Edit2.Text;

  OutlineIndex := StrToInt(Edit3.Text);

  if (OutlineIndex <= Outline1.ItemCount) and (OutlineIndex >= 0) then

    Outline1.AddObject(OutlineIndex, 'New item', MyRecPtr);

end;

After an item containing a TMyRec record has been added, the following code retrieves the FName and LName values associated with the item and displays the values in labels.

Label4.Caption := PMyRec(Outline1.Items[Outline1.SelectedItem].Data)^.FName;

Label5.Caption := PMyRec(Outline1.Items[Outline1.SelectedItem].Data)^.LName;


See also

Add method

AddChild method

AddChildObject method

Insert method

MoveTo method


AddObjectFirst method

See also	Example

Applies to

TTreeNodes object

Declaration

function AddObjectFirst(Node: TTreeNode; const S: string; Ptr: Pointer): TTreeNode;

Description

The AddObjectFirst method adds a new item (TTreeNode object) containing data to a tree view. The item is added first to the list to which the item specified by the Node parameter belongs. Items that appear after the added item are moved down one row and reindexed with valid Index values. The S parameter specifies the Text property of the new node. The Ptr parameter specifies the Data property value of the new item. AddObjectFirst returns the item that has been added.


Example

The following example adds an item first in the list to which the selected item belongs in the tree view control. The TBitmap object is attached to the new item.

TreeView1.Items.AddObjectFirst(TreeView1.Selected,'Sub Item1', MyBitmap);


See also

AddChildFirst method

AddChildObjectFirst method

AddChildObject method

AddFirst method

Add method

AddChild method

AddObject method

Insert method

MoveTo method

InsertObject method


AddParam method

See also	Example

Applies to

TParams object

Declaration

procedure AddParam(Value: TParam);

Description

AddParam adds Value as a new parameter to the Items property.


Example

{ Move all parameter info from Params2 to Params1 }

while Params2.Count <> 0 do

  begin

{ Grab the first parameter from Params2 }

  TempParam := Params2[0];

{ Remove it from Params2 }

  Params2.RemoveParam(TempParam);

{ And add it to Params1 }

  Params1.AddParam(TempParam);

  end;


See also

RemoveParam method


AddPassword method

See also	Example

Applies to

TSession component

Declaration

procedure AddPassword(const Password: string);

Description

The AddPassword method is used to add a new password to the current TSession component for use with Paradox tables. When an application opens a Paradox table that requires a password, the user will be prompted to enter a password unless the Session has a valid password for the table.


Example

Session.AddPassword('ASecret');


See also

Session variable


AddStandardAlias method

See also

Applies to

TSession component

Declaration

procedure AddStandardAlias(const Name, Path, DefaultDriver: string);

Description

The AddStandardAlias method adds an alias for a standard (that is, not SQL-based) database of the given name to the session. The Path parameter specifies the directory name where the database is located. DefaultDriver specifies the table type to use ('PARADOX', 'DBASE', or 'ASCIIDRV') when using tables with no extension in TableName and a TableType of ttDefault.

The session's ConfigMode property determines whether the alias is global (available to all applications that use the BDE) or local (available only to the session). Call the SaveConfigFile method to save global aliases permanently in the BDE configuration file.


See also

AddAlias method

DeleteAlias method

ModifyAlias method

Session variable


AddStrings method

See also	Example

Applies to

TStringList, TStrings objects

Declaration

procedure AddStrings(Strings: TStrings);

Description

The AddStrings method adds a group of strings to the list of strings in a string list object. The new strings are appended to the existing strings. Specify a string object containing the list of strings you want added as the value of the Strings parameter. Object references are also copied if the TStrings object supports objects (TMemo.Lines does not, for example)


Example

This code adds the list of strings contained in ListBox1.Items to the end of the ListBox2.Items list of strings:

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox2.Items.AddStrings(ListBox1.Items);

end;


See also

Add method

AddObject method

Strings property


AfterCancel event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterCancel: TDataSetNotifyEvent;

Description

The AfterCancel event is activated when the dataset finishes a call to the Cancel method. This event is the last action before Cancel returns to the caller. If the dataset is not in Edit state, there are no changes pending, or an exception occurs during BeforeCancel processing or during Cancel itself, then Cancel will not activate the AfterCancel event.

By assigning a method to this property, you can take any special actions required by the event.


Example

This example updates the form's status bar with a message when an AfterCancel event occurs.

procedure TForm1.Table1AfterCancel(DataSet: TDataSet);

begin

   StatusBar1.SimpleText := 'Record changes cancelled';

end;


See also

BeforeCancel event


AfterClose event

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterClose: TDataSetNotifyEvent;

Description

The AfterClose event is activated after a dataset is closed, either by calling the Close method or by setting the Active property to False. This event is the last action before Close returns to the caller. Typically, the AfterClose event handler closes any private lookup tables opened by the BeforeOpen event.

By assigning a method to this property, you can take any special actions required by the event.


See also

BeforeClose event


AfterDelete event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterDelete: TDataSetNotifyEvent;

Description

The AfterDelete event is activated when the dataset finishes a call to the Delete method. This event is the last action before Delete returns to the caller. When AfterDelete is called, the deleted record has already been removed from the dataset, and the dataset cursor will be positioned on the following record.

By assigning a method to this property, you can take any special actions required by the event.


Example

This example displays a message on the form's status bar indicating the table's record count after a record is deleted.

procedure TForm1.Table1AfterDelete(DataSet: TDataSet);

begin

  StatusBar1.SimpleText := Format('There are now %d records in the table',

    [DataSet.RecordCount]);

end;


See also

BeforeDelete event


AfterEdit event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterEdit: TDataSetNotifyEvent;

Description

The AfterEdit event is activated when a dataset finishes a call to the Edit method. This event is the last action before Edit returns to the caller.

Note:	The event occurs before any changes have been made to the current record.

By assigning a method to this property, you can take any special actions required by the event.


Example

This example updates the form's status bar with a message when an AfterEdit event occurs.

procedure TForm1.Table1AfterEdit(DataSet: TDataSet);

begin

   StatusBar1.SimpleText := 'Editing record';

end;


See also

BeforeEdit event


AfterInsert event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterInsert: TDataSetNotifyEvent;

Description

The AfterInsert event is activated when a dataset finishes a call to the Insert or Append methods. This event is the last action before Insert or Append returns to the caller.


Example

This example updates the form's status bar with a message when an AfterInsert event occurs.

procedure TForm1.Table1AfterInsert(DataSet: TDataSet);

begin

   StatusBar1.SimpleText := 'Inserting new record';

end;


See also

BeforeInsert event

OnNewRecord event


AfterOpen event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterOpen: TDataSetNotifyEvent;

Description

The AfterOpen event is activated after a dataset is opened, either by calling the Open method or by setting the Active property to True. This event is the last action before Open returns to the caller.

By assigning a method to this property, you can take any special actions required by the event.


Example

This example updates the form's status bar with a message when an AfterOpen event occurs.

procedure TForm1.Table1AfterOpen(DataSet: TDataSet);

begin

   StatusBar1.SimpleText := 'Table opened';

end;


See also

BeforeOpen event


AfterPost event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AfterPost: TDataSetNotifyEvent;

Description

The AfterPost event is activated after a call to the Post method. This event is the last action before Post returns to the caller.

If a TTable has a range (set with ApplyRange or SetRange) or filter (set via the Filter property or OnFilterRecord event) in effect, and if the key value of the newly posted record falls outside the range, then in the AfterPost event, the cursor will not be positioned on the newly posted record.

By assigning a method to this property, you can take any special actions required by the event.


Example

This example updates the form's status bar with a message when an AfterPost event occurs.

procedure TForm1.Table1AfterPost(DataSet: TDataSet);

begin

   StatusBar1.SimpleText := 'Record changes complete';

end;


See also

BeforePost event


AliasName property

Example

Applies to

TDataBase component

Declaration

property AliasName: TSymbolStr;

Description

AliasName is the name of an existing BDE alias defined with the BDE Configuration Utility. This is where the TDatabase component gets its default parameter settings. This property will be cleared if DriverName is set. If you try to set AliasName of a TDatabase for which Connected is True, Delphi will raise an exception.


Example

Database1.AliasName := 'DBDEMOS';


Align property

See also

Applies to

At design time: TBevel, TDBGrid, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TFileListBox, TGroupBox, THeader, THeaderControl, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPaintBox, TPageControl, TPanel, TProgressBar, TRadioGroup, TRichEdit, TScrollBox, TStatusBar, TStringGrid, TTabControl, TTabbedNotebook, TTabSet, TTreeView components

At run time: All other controls

Declaration

property Align: TAlign;

Description

The Align property determines how the controls align within their container (or parent control). These are the possible values:

Value	Meaning

alNone	The component remains where you place it in the form. This is the default value.

alTop	The component moves to the top of the form and resizes to fill the width of the form. The height of the component is not affected.

alBottom	The component moves to the bottom of the form and resizes to fill the width of the form. The height of the component is not affected.

alLeft	The component moves to the left side of the form and resizes to fill the height of the form. The width of the component is not affected.

alRight	The component moves to the right side of the form and resizes to fill the height of the form. The width of the component is not affected.

alClient	The component resizes to fill the client area of a form. If a component already occupies part of the client area, the component resizes to fit within the remaining client area.

The default for THeaderControl is alTop. The default for TStatusBar is alBottom. If the form or a component containing other components is resized, the components realign within the form or control.

Using the Align property is useful when you want a control to stay in one position on the form or within a panel, even if the size of the form or the panel changes. For example, you could use a panel component with a various controls on it as a tool palette. By changing Align to alLeft, you guarantee that the tool palette remains on the left side of the form and always equals the client height of the form.

Note that if you set the Align property to alClient the component fills the entire client area so that it will not be possible to select the parent form by clicking on it. In this case use the Object Inspector to access the form or press ESC.

Any number of components can have the same Align value in which case they will stack up along the edge of the containing form or panel. To adjust the order in which the controls stack up, drag the controls into their desired positions.


See also

Left property


AlignButton property

See also

Applies to

TUpDown component

Declaration

property AlignButton: TUDAlignButton;

Description

The AlignButton property determines the position of the TUpDown component relative to its companion control specified by the Associate property. These are the possible values:

Value	Meaning

udLeft	The updown control aligns itself to the left edge of the companion control.

udRight	The updown control aligns itself to the right edge of the companion control.

The default value is udRight. The TUpDown control resizes itself as it aligns .


See also

Associate property

Orientation property


Alignment property

Applies to

TColumn, TColumnTitle, THeaderSection, TParaAttributes , TStatusPanel, TListColumn, objects; TBCDField, TBooleanField, TCheckBox, TCurrencyField, TDateField, TDateTimeField, TDBCheckBox, TDBMemo, TDBText, TFloatField, TIntegerField, TLabel, TMemo, TPanel, TPopupMenu, TRadioButton, TRichEdit, TSmallintField, TStringField, TTimeField, TWordField components

Description

The Alignment property aligns text or captions in components.

Alignment Property for Labels, Memos, Panels, and Rich Edits components , and for Header Section, ParaAttributes, ListColumn and Status Panel objects

Alignment Property for Check Boxes and Radio Buttons

Alignment Property for Pop-up Menus

Alignment Property for Field Components


Alignment property for labels, memos, and panels
Alignment property

See also	Example

Applies to

THeaderSection, TParaAttributes , TStatusPanel, TListColumn, TColumn, TColumnTitle objects; TLabel, TMemo, TPanel, TRichEdit components

Declaration

property Alignment: TAlignment;

Description

The Alignment property specifies how text is aligned within the component.

These are the possible values:

Value	Meaning

taLeftJustify	Align text to the left side of the control

taCenter	Center text horizontally in the control

taRightJustify	Align text to the right side of the control

Note:	For the TStatusPanel object, used with the TStatusBar control, taRightJustify should not be used when the SizeGrip property is True. When these are used together the text in the last panel will be truncated .


Example

This code aligns text to the right side of a label named Label1 in response to a click on a button named RightAlign:

procedure TForm1.RightAlignClick(Sender: TObject);

begin

  Label1.Alignment := taRightJustify;

end;


See also

Caption property

Text property


Alignment property

See also	Example

Applies to

TCheckBox, TDBCheckBox, TRadioButton components

Declaration

property Alignment: TLeftRight;

Description

For check boxes and radio buttons, the control's caption is always left-aligned within the text area.

These are the possible values:

Value	Meaning

taLeftJustify	The caption appears to the left of the check box or radio button.

taRightJustify	The caption appears to the right of the check box or radio button.


Example

This code makes the check box and puts it on the left side of the text:

procedure TForm1.Button1Click(Sender: TObject);

begin

  CheckBox1.Ctl3D := False;

  CheckBox1.Alignment := taLeftJustify;

end;


See also

Caption property


Alignment property for popup menus
Alignment property

See also	Example

Applies to

TPopupMenu components

Declaration

property Alignment: TPopupAlignment;

Description

The Alignment property determines where the pop-up menu appears when the user clicks the right mouse button. These are the possible values and their meanings:

Value	Meaning

paLeft	The pop-up menu appears with its top left corner under the mouse pointer.

paCenter	The pop-up menu appears with the top center of the menu under the mouse pointer.

paRight	The pop-up menu appears with its top right corner under the mouse pointer.

The default value is paLeft.


Example

This example uses a pop-up menu component and a button on a form. The code places the top right corner of a pop-up menu under the mouse pointer when the menu appears:

procedure TForm1.AlignPopupMenuClick(Sender: TObject);

begin

  PopupMenu1.Alignment := paRight;

end;


See also

AutoPopup property

OnPopup event


Alignment property

Applies to

TBCDField, TBooleanField, TCheckBox, TCurrencyField, TDateField, TDateTimeField, TFloatField, TIntegerField, TSmallintField, TStringField, TTimeField, TWordField components

Declaration

property Alignment: TAlignment;

Description

The Alignment property is used by some data-aware controls to center, left-, or right-align the data in a field. Data-aware controls that support alignment include TDBGrid and TDBEdit.


AllocBy property

Applies to

TImageList, TListView components

Description

AllocBy property for List Views

AllocBy property for Image Lists


AllocBy property

See also

Applies to

TListView components

Declaration

property AllocBy: Integer;

Description

The AllocBy property prepares a list view control for adding a large number of items. Set AllocBy before adding a large number of items. AllocBy enables a list view control to reallocate its internal data structures only once rather than every time you add an item.


See also

Items property

SubItems property

Add method


AllocBy property

See also

Applies to

TImageList object

Declaration

property AllocBy: Integer;

Description

The AllocBy property sets the number of images which the ImageList will grow by when it needs to resize to make room for internal structures.


See also

Count property


AllowAllUp property

See also	Example

Applies to

TSpeedButton component

Declaration

property AllowAllUp: Boolean;

Description

The AllowAllUp property determines if all speed buttons in a group this speed button belongs to can be unselected (in their up state) at the same time. AllowAllUp should be used only with speed buttons in a group (that is, each button's GroupIndex property is not zero). See the GroupIndex property for information on how to create a group of speed buttons. If GroupIndex is zero, AllowAllUp has no effect.

If AllowAllUp is True, all of the speed buttons in a group can be unselected. All buttons can appear in their up state.

If AllowAllUp is False, one of the speed buttons belonging to a group must be selected (in its down state) at all times. Clicking a down button won't return the button to its up state. The button only becomes unselected when the user clicks one of the other buttons in the group. In such a group, one button must always be selected. Determine which speed button will be initially down by setting its Down property to True.

The default value is False.

Changing the value of the AllowAllUp property for one speed button in a group changes the AllowAllUp value for all buttons in the group.

You can use AllowAllUp with a single bitmap button in its own group (with a GroupIndex value greater than 0) so that the button can be selected and remain selected until the user clicks the button again--at which time it becomes unselected. In other words, the button can work much like a check box. To make a single speed button behave this way, set its GroupIndex property to a value greater than 0 (but different from any other GroupIndex value of any other speed buttons you have), and set AllowAllUp to True.


Example

In this example, there are three speed buttons on a form. All three belong to the same group as all three have a GroupIndex value of 1. This line of code changes the AllowAllUp property to True for all three speed buttons, so it's possible that all the speed buttons in the group can be unselected at the same time:

SpeedButton3.AllowAllUp := True;


See also

Down property

Glyph property

GroupIndex property


AllowClick property

See also

Applies to

THeaderSection object

Declaration

property AllowClick: Boolean;

Description

The AllowClick property allows a section to be clicked. Clicked sections depress and look similar to buttons when they are clicked.


See also

OnSectionClick event


AllowDelete property

Applies to

TDBCtrlGrid component

Declaration

property AllowDelete: Boolean;

Description

If True (the default), the user can delete the current record by pressing Ctrl+Delete. (You can get the same effect in code by calling DoKey with the rkDelete parameter.) If False, TDBCtrlGrid won't delete records, though you can still do so by calling the attached dataset's Delete method.


AllowGrayed property

See also	Example

Applies to

TCheckBox, TDBCheckBox components

Declaration

property AllowGrayed: Boolean;

Description

The value of the AllowGrayed property determines if a check box can have two or three possible states. If AllowGrayed is False, the default value, clicking a check box alternately checks and unchecks it. If AllowGrayed is True, clicking a check box either checks, grays, or unchecks it.


Example

This example uses a check box on a form. When the application runs, the check box is initially checked. When the user clicks it, the check box is unchecked. Clicking it again grays the check box.

procedure TForm1.FormCreate(Sender: TObject);

begin

  CheckBox1.AllowGrayed := True;

  CheckBox1.State := cbChecked;

end;


See also

Checked property

State property


AllowInsert property

Applies to

TDBCtrlGrid component

Declaration

property AllowInsert: Boolean;

Description

If True (the default), the user can insert or append new records by pressing Insert or Ctrl+Insert (respectively) while not editing a record. (You can get the same effect with code by calling DoKey with a parameter of gkInsert or gkAppend.) If False, TDBCtrlGrid won't insert or append new records, though you can still do so by calling the attached dataset's Insert or Append methods.


AllowResize property

See also	Example

Applies to

THeader component

Declaration

property AllowResize: Boolean;

Description

The value of the AllowResize property determines if the user can modify the size of the header at run time with the mouse. If AllowResize is False, the sections within a header can't be resized. If AllowResize is True, clicking a border of a header section and dragging it left or right changes the width of the section. The default value is True.


Example

The following code allows the resizing of the sections of Header1.

Header1.AllowResize := True;


See also

OnSized event

Sections property

SectionWidth property

Sizing event


AlphaSort method

Applies to

TTreeNode object; TListView , TTreeView components

Description

AlphaSort method for tree views and tree node objects

AlphaSort method for list views


AlphaSort method

See also	Example

Applies to

TTreeNode object; TTreeView component

Declaration

function AlphaSort: Boolean;

Description

The AlphaSort method for a tree view sorts all root items and each item alphabetically by label in the tree view control. For a tree node object, the AlphaSort method sorts the item's list of immediate children alphabetically. If successful, the method returns True.


Example

The following example sorts all items in TreeView1 when the user clicks on the button.

procedure TForm1.Button1Click(Sender: TObject);

begin

  TreeView1.AlphaSort;

end;


See also

SortType property

CustomSort method


AlphaSort method

See also

Applies to

TListView component

Declaration

function AlphaSort: Boolean;

Description

The AlphaSort method for a list view sorts all list items alphabetically in the list view control. If successful, the method returns True.


See also

CustomSort method

SortType property


AnsiToNative function

Unit

DB

Declaration

function AnsiToNative(Locale: TLocale; const AnsiStr: string; NativeStr: PChar;
  MaxLen: Integer): PChar;

Description

The AnsiToNative function translates the ANSI characters in AnsiStr (or the first MaxLen characters) to the native character set according to Locale by calling DBIAnsiToNative. The translated characters are returned in NativeStr with a null terminator. AnsiToNative returns NativeStr.


Append method

Applies to

TStrings, TStringList objects; TQuery, TStoredProc, TTable components

Description

Append method for tables, queries, and stored procedures

Append method for strings and string lists objects


Append method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure Append;

Description

The Append method moves the cursor to the end of the dataset, puts the dataset into Insert state , and opens a new, empty record. When an application calls Post, the new record will be inserted in the dataset in a position based on its index, if defined. To discard the new record, use Cancel.

This method is valid only for datasets that can be modified (where the CanModify property is True).

Note:	For indexed tables, when you call Post after calling the Append and Insert methods, these methods will put the new record in the correct location in the table, based on the table's index. If no index is defined on the underlying table, then the record will maintain its position--Append will add the record to the end of the table, and Insert will insert it at the current cursor position. In either case, posting a new record may cause rows displayed in a data grid to change as the dataset follows the new row to its indexed position and then fetches data to fill the data grid around it.


Example

This example appends a new record to a table when the user clicks a button. The two fields ALPHANUMERIC and INTEGER are filled from the contents of two edit controls.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Table1.Append;

  Table1['ALPHANUMERIC'] := Edit1.text;

  Table1['INTEGER'] := StrToInt(Edit2.text);

  Table1.Post;

end;


See also

TField component


Append method

See also	Example

Applies to

TStrings, TStringList objects

Declaration

procedure Append(const S: string);

Description

The Append method performs the same function as the Add method for strings and string lists but doesn't return the result. Use this method rather than Add when you need it as a parameter for a function requiring a TGetStrProc or when you don't need to know where the string is added.


Example

This code uses a button and a list box on a form. When the user clicks the button, the code appends a new string to a list box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Append('New string');

end;


See also

Add method

AddObject method

AddStrings method

Clear method

Delete method

Duplicates property

Exchange method

Insert method

Items property

Move method

Sorted property


AppendRecord method

See also	Example

Applies to

TTable, TQuery components

Declaration

procedure AppendRecord(const Values: array of const);

Description

The AppendRecord method appends a new record to the dataset with the field values passed in the Values parameter. The assignment of the elements of Values to fields in the record is sequential; the first element is assigned to the first field, the second to the second, etc. The order of fields in the dataset is determined by the arrangement of the TFields defined for the database table. You can change this order using the fields editor.

The number of elements in Values may be fewer than the number of actual fields in the record; any remaining fields are left unassigned and are NULL. The type of each element of Values must be compatible with the type of the field in that the field must be able to perform the assignment using AsString, AsInteger, and so on, according the type of the Values element.

This method is valid only for datasets that return a live result set.

Note:	For indexed tables, the AppendRecord and InsertRecord methods will both put the new record in the correct location in the table, based on the table's index. If no index is defined on the underlying table, then the record will maintain its position--AppendRecord will add the record to the end of the table, and InsertRecord will insert it at the current cursor position. In either case, posting a new record in a data grid may cause all the rows before and after the new record to change as the dataset follows the new row to its indexed position and then fetches data to fill the grid around it.


Example

This statement appends a record to the Customer table. Note that Nulls are entered for some of the values, but are not required for missing values at the end of the array argument, i.e. after the Discount field.

Customer.AppendRecord([CustNoEdit.Text,CoNameEdit.Text, AddrEdit.Text,
  Null, Null, Null, Null, Null, Null, DiscountEdit.Text]);


See also

TField component

InsertRecord method


Application variable

See also	Example

Unit

Forms

Declaration

Application: TApplication;

Description

The Application variable declares an instance of your application for your project. By default, when you create a new project, Delphi constructs an application object and assigns it to Application. Application has several properties you can use to get information about your application while it runs; see the TApplication component for the list of properties.


Example

This code displays the name of your project in an edit box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.Text := Application.Title;

end;


See also

Icon property

Run method

Title property


Apply method

Applies to

TUpdateSQL component

Declaration

procedure Apply(UpdateKind: TUpdateKind);

Description

The Apply method replaces parameters in and executes the SQL statement associated with the UpdateKind parameter (for example, calling Apply and passing ukModify would use the SQL statement held in the ModifySQL property). Apply combines calls to SetParams and ExecSQL into one.


ApplyFilePath method

See also	Example

Applies to

TFileListBox component

Declaration

procedure ApplyFilePath(const EditText: string);

Description

ApplyFileEditText is intended to be used in a dialog box that approximates the utility and behavior of an Open dialog box. Such a dialog box would contain a file list box (TFileListBox), a directory list box (TDirectoryListBox), a drive combo box (TDriveComboBox), a filter combo box TFilterComboBox, a label, and an edit box where the user can type a filename including a full directory path. When the user then chooses the OK button, you would like all the controls to update with the information the user entered in the edit box. For example, you would want the directory list box to change to the directory specified in the path the user typed, and you want the drive combo box to change to the correct drive if the path included a different drive letter.

If the file list box, directory list box, drive combo box, filter combo box, label, and edit box are connected using the FileEdit, FileList, DirLabel, and DirList properties, your application can call ApplyFilePath to update the controls with the text the user entered in the edit box.

The user can enter any of these strings in the edit box: a filename, with or without a path, a drive only, a drive and directory only, relative paths, or a file mask using wildcard characters. In all cases, the ApplyFilePath method updates the controls as you would expect. For example, if the user includes a directory name, the directory list box makes that directory the current one.

The EditText parameter is the text within the edit box.


Example

This example uses a file list box, a directory list box, a filter combo box, a drive combo box, a label, an edit box, and a button on a form. When the user runs the application and enters a path or filename in the edit box, all the controls update:

procedure TForm1.FormCreate(Sender: TObject);

begin

  FileListBox1.FileEdit := Edit1;

  FilterComboBox1.FileList := FileListBox1;

  DirectoryListBox1.FileList := FileListBox1;

  DirectoryListBox1.DirLabel := Label1;

  DriveComboBox1.DirList := DirectoryListBox1;

  Button1.Default := True;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  FileListBox1.ApplyFilePath(Edit1.Text);

end;


See also

Directory property

Drive property


ApplyRange method

See also	Example

Applies to

TTable component

Declaration

procedure ApplyRange;

Description

The ApplyRange method is used to apply the start and end ranges established with the SetRangeStart and SetRangeEnd methods or the EditRangeStart and EditRangeEnd methods. This will filter the set of records from the database table accessible to the application.

Note:	When comparing fields for range purposes, a NULL field is always less than any other possible value.


Example

with Customer do

begin

  EditRangeStart;

  CustomerCompany.AsString := Edit1.Text;

  {Set start range based on text of Edit1 component}

  EditRangeEnd;

  CustomerCompany.AsString := Edit2.Text;

  {Set end range based on value of Edit2 component}

  ApplyRange; {Apply the ranges}

end;


See also

CancelRange method

KeyExclusive property

KeyFieldCount property

SetRange method


ApplyUpdates method

Applies to

TTable, TQuery, TStoredProc , TDatabase components

Description

ApplyUpdates method for tables, queries, and stored procedures

ApplyUpdates method for database components


ApplyUpdates for tables, queries and stored procedures
ApplyUpdates method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure ApplyUpdates;

Description

ApplyUpdates applies all pending cached updates. After you call ApplyUpdates, call CommitUpdates to reflect that cached updates were written. Generally, you should call the database object's ApplyUpdates method instead of the dataset's. It calls ApplyUpdates and CommitUpdates within a transaction.

If the dataset has an OnUpdateRecord event handler, it will be called for each record that has updates in the cache. If a record in the cache can't be updated, the dataset's OnUpdateError event will be triggered. If the dataset's UpdateObject property points to a TUpdateSQL component and doesn't have an OnUpdateRecord event handler, its Apply method will be called automatically for each record that has updates in the cache.


See also

CommitUpdates method, OnUpdateRecord event, UpdateObject method


ApplyUpdates method for database components
ApplyUpdates method

See also

Applies to

TDatabase component

Declaration

procedure ApplyUpdates(const DataSets: array of TDataSet);

Description

ApplyUpdates applies and commits all pending cached updates for the datasets specified in the DataSets open array parameter (by calling the datasets' ApplyUpdates and CommitUpdates methods). It uses a transaction (if one is not already started) to ensure that all updated records in all affected datasets (such as in a master/detail relationship) are updated in their entirety.


See also

CachedUpdates property

CancelUpdates method

RevertRecord method

UpdateStatus method

UpdateRecordTypes property


Arc method

See also	Example

Applies to

TCanvas object

Declaration

procedure Arc(X1, Y1, X2, Y2, X3, Y3, X4, Y4: Integer);

Description

The Arc method draws an arc on the canvas along the perimeter of the ellipse bounded by the specified rectangle. Coordinates (X1, Y1 and X2, Y2) define the enclosing rectangle for the arc. The arc starts at the intersection of the ellipse edge and the line from the center of the ellipse to the specified starting point (X3, Y3). The arc is drawn counterclockwise until it reaches the position where the ellipse edge intersects the line from the center of the ellipse to the specified ending point (X4, Y4).


Example

The following lines of code draw the top quarter of an arc bounded by the current window:

TForm1.FormPaint(Sender: TObject);

var

  R: TRect;

begin

  R := GetClientRect;	{Gets the rectangular coordinates of the current window}

  Canvas.Arc(R.Left, R.Top, R.Right, R.Bottom, R.Right, R.Top, R.Left, R.Top);

end;


See also

Chord method

Draw method

DrawFocusRect method

Ellipse method

Pie method


Arrange method

See also

Applies to

TListView component

Declaration

procedure Arrange(Code: TListArrangement);

Description

Run-time only. The Arrange method arranges icons in a list view that has a ViewStyle of vsIcon or vsSmallIcon. The Code parameter specifies how to arrange the icons. These are the possible values for the code parameter:

Value	Meaning

arAlignBottom	Aligns items along the bottom edge of the window

arAlignLeft	Aligns items along the left edge of the window

arAlignRight	Aligns items along the right edge of the window

arAlignTop	Aligns items along the top edge of the window

arDefault	Aligns items according to the list view control's current alignment styles (the default value)

arSnapToGrid	Snaps all icons to the nearest grid position


See also

TListArrangement type

IconOptions property

ViewStyle property

AutoArrange property


ArrangeIcons method

See also	Example

Applies to

TForm component

Declaration

procedure ArrangeIcons;

Description

The ArrangeIcons method arranges the icons of minimized forms so that they are evenly spaced and don't overlap. The ArrangeIcons method applies only to forms that are MDI parent forms (have a FormStyle property value of fsMDIForm).


Example

This code runs when the user chooses a menu item called Window|Arrange Icons:

procedure TForm1.WindowArrangeIconsClick(Sender: TObject);

begin

  Form1.ArrangeIcons;

end;


See also

Cascade method

Next method

Previous method

Tile method


Arrangement property

See also

Applies to

TIconOptions object

Declaration

property Arrangement: TIconArrangement;

Description

The Arrangement property determines where the items are to be aligned in the list view. The Arrangement property of the IconOptions object for the list view allows you to specify a TIconArrangement. The list view must have a ViewStyle of vsIcon or vsSmallIcon to have an alignment for icons take affect.

Value	Meaning

iaTop	Specifies that items are aligned left to right in rows at the top of the list view control

iaLeft	Specifies that items are aligned in columns top to bottom at the left of the list view control.


See also

TIconArrangement type

ViewStyle property

IconOptions property


ArrowKeys property

See also

Applies to

TUpDown component

Declaration

property ArrowKeys: Boolean;

Description

The ArrowKeys property is used only when a TUpDown component is associated with a companion window. ArrowKeys provides a keyboard interface so that the TUpDown component can processes the Up arrow and Down arrow keys. It can process these keys even when its companion window has the focus. The default is True. To set a companion window use the Associate property.


See also

Associate property

Position property


AsBCD property

See also

Applies to

TParam object

Declaration

property AsBCD: Double;

Description

Assigning a value to the AsBCD property sets the DataType property to ftBCD and saves the value as the current data for the parameter.


See also

TFieldType type


AsBoolean property

Applies to

TParam object; TBooleanField, TStringField components

Description

AsBoolean Property for Field Components

AsBoolean Property for TParam Objects


AsBoolean property for TParam objects
AsBoolean property

Applies to

TParam object

Declaration

property AsBoolean: Boolean;

Description

Assigning a value to the AsBoolean property sets the DataType property to ftBoolean and saves the value as the current data for the parameter. Accessing the AsBoolean property attempts to convert the current data to a Boolean value and returns that value.


AsBoolean property for Boolean and string fields
AsBoolean property

Example

Applies to

TBooleanField, TStringField components

Declaration

property AsBoolean: Boolean;

Description

Run-time only. This is a conversion property. For a TBooleanField, AsBoolean can be used to read or set the value of the field, but Value should be used for this purpose instead.

For a TStringField, AsBoolean returns True on reading the value of the field if its text begins with the letters "Y", "y", "T" or "t" (for "Yes" or "True"), and False otherwise. Using AsBoolean to write a TStringField's value sets the string to 'T' or 'F'.


Example

if Table1.FieldByName('BackOrdered').AsBoolean then ...


AsCurrency property

See also

Applies to

TParam object

Declaration

property AsCurrency: Double;

Description

Assigning a value to the AsCurrency property sets the DataType property to ftCurrency and saves the value as the current data for the parameter. Accessing the AsCurrency property attempts to convert the current data to a Double value and returns that value.


See also

TFieldType type


AsDate property

See also

Applies to

TParam object

Declaration

property AsDate: TDateTime;

Description

Assigning a value to the AsDate property sets the DataType property to ftDate and saves the value as the current data for the parameter. Accessing the AsDate property attempts to convert the current data to a TDateTime value and returns that value.


See also

StrToDateTime function

TFieldType type


AsDateTime property

Applies to

TParam object; TDateField, TDateTimeField, TStringField, TTimeField components

Description

AsDateTime Property for Field Components

AsDateTime Property for TParam Objects


AsDateTime property

See also

Applies to

TParam object

Declaration

property AsDateTime: TDateTime;

Description

Assigning a value to the AsDateTime property sets the DataType property to ftDateTime and saves the value as the current data for the parameter. Accessing the AsDateTime property attempts to convert the current data to a TDateTime value and returns that value.


See also

StrToDateTime function

TFieldType type


AsDateTime property for fields
AsDateTime property

See also	Example

Applies to

TDateField, TDateTimeField, TStringField, TTimeField components

Declaration

property AsDateTime: TDateTime;

Description

Run-time only. This is a conversion property. For TDateField, TDateTimeField or TTimeField, AsDateTime can be used to read or set the value of the field, but Value should be used for this purpose instead.

For a TStringField, AsDateTime converts a date to a string on assigning a value to the string field, and converts a string to a date when reading from the field.


Example

The following statement converts a string to a date for insertion into a date field:

Table1.FieldByName(TimeStamp).AsDateTime := StrToDateTime(Now);


See also

DateToStr function

StrToDate function

StrToDateTime function

DateTimeToStr function

TimeToStr function

StrToTime function

Value property


AsFloat property

Applies to

TParam object; TBCDField, TCurrencyField, TFloatField, TStringField components

Description

AsFloat Property for Field Components

AsFloat Property for TParam Objects


AsFloat property for TParam objects
AsFloat property

See also

Applies to

TParam object

Declaration

property AsFloat: Double;

Description

Assigning a value to the AsFloat property sets the DataType property to ftFloat and saves the value as the current data for the parameter. Accessing the AsFloat property attempts to convert the current data to a Double value and returns that value.


See also

TFieldType type


AsFloat property for fields
AsFloat property

See also

Applies to

TBCDField, TCurrencyField, TFloatField, TStringField components

Declaration

property AsFloat: Double;

Description

Run-time only. This is a conversion property. For a TFloatField, TBCDField or TCurrencyField, AsFloat can be used to read or set the value of the field as a Double, but Value should be used for this purpose instead.

For a TStringField, AsFloat converts a float to a string on assigning a value to the field, and converts a string to a float when reading from the field.


See also

FloatToStr function

StrToFloat function


AsInteger property

Applies to

TParam object; TIntegerField, TSmallintField, TStringField, TWordField components

Description

AsInteger Property for Field Components

AsInteger Property for TParam Objects


AsInteger property for TParam objects
AsInteger property

See also

Applies to

TParam object

Declaration

property AsInteger: LongInt;

Description

Assigning a value to the AsInteger property sets the DataType property to ftInteger and saves the value as the current data for the parameter. Accessing the AsInteger property attempts to convert the current data to a Longint value and returns that value.


See also

TFieldType type


AsInteger property for fields
AsInteger property

See also

Applies to

TIntegerField, TSmallintField, TStringField, TWordField components

Declaration

property AsInteger: Longint;

Description

Run-time only. This is a conversion property. For a TIntegerField, TSmallintField or TWordField, AsInteger can be used to read or set the value of the field as a Longint, but Value should be used for this purpose instead.

For a TStringField, AsInteger converts an integer to a string on assigning a value to the field, and converts a string to an integer when reading from the field.


See also

Data Access Components Hierarchy

IntToStr function

StrToInt function

Value property


Assign method

Applies to

TBitmap, TBrush, TClipboard, TCollection, TControlScrollBar, TFieldDef, TFieldDefs, TFont, THeaderSection, TIcon, TIndexDef, TIndexDefs, TListItems, TMetafile, TParaAttributes, TParam, TParams , TPen, TPicture, TStatusPanel, TStringList, TStrings, TTextAttributes,TTreeNodes, TTreeNodes, TColumn, TColumnTitle, TDBGridColumns objects; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TImageList, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField, components

Description

Assign Method for Image List Objects

Assign Method for Clipboard Objects

Assign Method for Fields

Assign Method for TFieldDefs Objects

Assign Method for TIndexDefs Objects

Assign Method for TParam Objects

Assign Method for TParams Objects

Assign Method for Tree Node Objects

Assign Method for Tree Nodes Objects

Assign Method for List Items Objects

Assign Method for Other Objects


Add method for image list objects
Assign method

Applies to

TImageList object

Declaration

procedure Assign(Source: TPersistent);

Description

If Source is another TImageList component, Assign discards any current image information and replaces it with the information from Source. If Source is any other type of object, Assign calls its inherited method. Use this method to copy another object's information.


Assign method for TClipboard objects
Assign method

See also	Example

Applies to

TClipboard object

Declaration

procedure Assign(Source: TPersistent);

Description

The Assign method assigns the object specified by the Source parameter to the Clipboard. If the object is a TGraphic, TBitmap, TPicture or TMetafile, the image will be copied to the Clipboard in the corresponding format (either CF_BITMAP or CF_METAFILE). For example, the following code copies the bitmap from a bitmap object named Bitmap1 to the Clipboard:

Clipboard.Assign(Bitmap1);

To retrieve an object from the Clipboard, simply use the Assign method of an appropriate object. For example, if a bitmap is on the Clipboard, the following code copies it to a bitmap object named Bitmap1:

Bitmap1.Assign(Clipboard);


Example

The following code copies the bitmap of a speed button named SpeedButton1 to the Clipboard:

Clipboard.Assign(SpeedButton1.Glyph);


See also

AsText property

Clipboard function

HasFormat property


Assign method for TFieldDefs objects
Assign method

Applies to

TFieldDefs object

Declaration

procedure Assign(FieldDefs: TFieldDefs);

Description

Assign creates a new set of TFieldDef objects in Items from the FieldDefs parameter. Any previously entries in Items are freed.


Assign method for TIndexDefs objects
Assign method

Applies to

TIndexDefs object

Declaration

procedure Assign(IndexDefs: TIndexDefs);

Description

Assign creates a new set of TIndexDef objects in Items from the IndexDefs parameter. Any previously entries in Items are freed.


Assign method for fields
Assign method

See also	Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

procedure Assign(Source: TPersistent);

Description

Assign copies data from one field to another. Both fields must be valid and have the same DataType and Size, and the DataSize of Source must be 255 bytes or less.

The restrictions on type compatibility and size do not apply to TBlobField, TBytesField, TGraphicField, TMemoField, and TVarBytesField. For a TBlobField, TBytesField or TVarBytesField, the source can be a TBlobField, TBytesField, TVarBytesField, TMemoField, TGraphicField, TMemoField, TStrings, TPicture, or TGraphicField.


Examples

{ Copy one date-time field to another }

DateTimeField1.Assign(DateTimeField2);

{ Copy a graphic field to a blob field }

BlobField1.Assign(GraphicField1);

{Copy strings in a TMemo to a TMemoField}

MemoField1.Assign(Memo1.Lines);


See also

DataType property

Size property


Assign method for TParam objects
Assign method

See also	Example

Applies to

TParam object

Declaration

procedure Assign(Param: TParam);

Description

The Assign method transfers all of the data contained in the Param parameter to the TParam object that calls it. If, however, you have specified a value for the ParamType property of the TParam object that calls Assign, the data in the ParamType parameter will not be assigned to the TParam object.


Example

This example will copy the CustNo parameter from Query1 to Query2.

Query2.ParamByName('CustNo').Assign(Query1.ParamByName('CustNo'));


See also

ParamType property

DataType property

AssignField method


Assign method for TParams objects
Assign method

See also	Example

Applies to

TParams object

Declaration

procedure Assign(Source: TPersistent);

Description

If Source is another TParams object, Assign discards any current parameter information and replaces it with the information from Source. Use this method to save and restore a set of parameter information or copy another object's information.


Example

var SavedParams: TParams;

...

{ Initialize SavedParams }

SavedParams := TParams.Create;

try

  { Save the parameters for Query1 }

  SavedParams.Assign(Query1.Params);

  { Do something with Query1 }

  ...

  { Restore the parameters to Query1 }

  Query1.Params.Assign(SavedParams);

finally

  SavedParams.Free;

end;


See also

AssignValues method


Assign method for tree node objects
Assign method

See also

Applies to

TTreeNode object

Declaration

procedure Assign(Source: TPersistent);

Description

If Source is another TTreeNode object, Assign discards any current property information and replaces it with the information from the Source. If Source is any other type of object, Assign calls its inherited method. Use this method to copy information from one item to another.


See also

Insert method

MoveTo method

InsertObject method


Assign method for tree nodes objects
Assign method

See also

Applies to

TTreeNodes object

Declaration

procedure Assign(Source: TPersistent);

Description

If Source is another TTreeNodes object, Assign discards any current property information and replaces it with the information from the Source. If Source is any other type of object, Assign calls its inherited method. Use this method to copy information from one tree nodes object to another.


See also

Insert method

MoveTo method

InsertObject method


Assign method for image list objects
Assign method

See also

Applies to

TListItems object

Declaration

procedure Assign(Source: TPersistent); override;

Description

If Source is another TListItems object, Assign discards any current property information and replaces it with the information from the Source. If Source is any other type of object, Assign calls its inherited method. Use this method to copy information from one list items object to another.


See also

Items property


Assign method for other objects
Assign method

Example

Applies to

TBitmap, TBrush, TCollection, TControlScrollBar, TFieldDef, TFont, THeaderSection, TIcon, TIndexDef, TMetafiles, TPen, TPicture, TStatusPanel, TStringList, TStrings, TColumn, TColumnTitle, TDBGridColumns objects

Declaration

procedure Assign(Source: TPersistent);

Description

The Assign method assigns one object to another. The general form of a call to Assign is

Destination.Assign(Source);

which tells the Destination object to assign the contents of the Source object to itself.

In general, the statement "Destination := Source" is not the same as the statement "Destination.Assign(Source)". The statement "Destination := Source" makes Destination reference the same object as Source, whereas "Destination.Assign(Source)" copies the contents of the object references by Source into the object referenced by Destination.

If Destination is a property of some object, however, and that property is not a reference to another object (such as the ActiveControl property of a form, or the DataSource property of a data-aware control), then the statement "Destination := Source" is the same as "Destination.Assign(Source)". Consider these statements:

Button1.Font := Button2.Font;

ListBox1.Items := Memo1.Lines;

Table1.Fields[0] := Query1.Fields[2];

They correspond to these statements:

Button1.Font.Assign(Button2.Font);

ListBox1.Items.Assign(Memo1.Lines);

Table1.Fields[0].Assign(Query1.Fields[2]);

The actions performed by Assign depend on the actual types of Destination and Source. For example, if Destination and Source are string objects (TStrings), the strings contained in Source are copied into Destination. Likewise, if Destination and Source are bitmaps (TBitmap), the bitmap contained in Source is copied into Destination.

Although the compiler allows any two TPersistent objects to be used in a call to Assign, the call succeeds at run time only if the objects involved "know" how to perform an assignment. For example, if Destination is a button (TButton) and Source is an edit box (TEdit), the call to Assign raises an EConvertError exception at run time.

An object of one type can always be assigned to another object of the same type. In addition, Assign supports the following special cases:

If Destination is of type TPicture then Source can be of type TBitmap, TIcon, or TMetafile.

If Destination is of type TBitmap, TIcon, or TMetafile then Source can be of type TPicture if the Graphic property of the picture is of the same type as Destination.

If Destination is of type TBlobField then Source can be of type TBitmap, TPicture, or TStrings.


Example

The following code changes the properties of a label's font so that they match the properties of the button's font when the user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Font.Assign(Button1.Font);

end;


AssignField method

Applies to

TParam object

Declaration

procedure AssignField(Field: TField);

Description

The AssignField method transfers the DataType value and Name from Field. Use AssignField to set a parameter from a TField component.


AssignFieldValue method

See also

Applies to

TParam object

Declaration

procedure AssignFieldValue(Field: TField; const Value: Variant);

Description

The AssignFieldValue method transfers the DataType value and Name from Field and sets the value of the parameter to Value. Use AssignFieldValue to set a parameter from a TField component.


See also

AssignField method


AssignPrn procedure

Example

Unit

Printers

Declaration

procedure AssignPrn(var F: Text);

Description

The AssignPrn procedure assigns a text-file variable to the printer. After the variable is assigned, your application must call the Rewrite procedure. Then any time an application writes data to F, the text-file variable, the data is sent to the printer using the pen and font of the Canvas property.


Example

This code prints a line of text on the printer when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

var

  MyFile: TextFile;

begin

  AssignPrn(MyFile);

  Rewrite(MyFile);

  Writeln(MyFile, 'Print this text');

  System.CloseFile(MyFile);

end;


AssignValue method

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

procedure AssignValue(const Value: TVarRec);

Description

The AssignValue method sets the field to Value using one of the AsInteger, AsBoolean, AsString or AsFloat properties, depending on the type of Value. If Value is of type TObject or a TObject descendant, AssignValue uses the Assign method to transfer the information.


Example

Field1.AssignValue('new string');


AssignValues method

Example

Applies to

TParams object

Declaration

procedure AssignValues(Value: TParams);

Description

For each entry in Items, the AssignValues method attempts to find a parameter with the same Name property in Value. If successful, the parameter information (type and current data) from the Value parameter is assigned to the Items entry. Entries in Items for which no match is found are left unchanged.


Example

var SavedParams: TParams;

...

{ Initialize SavedParams }

SavedParams := TParams.Create;

{ Save the parameters for Query1 }

SavedParams.Assign(Query1.Parameters);

{ Do something with Query1 }

...

{ Restore the parameters to Query1 }

Query1.Parameters.AssignValues(SavedParams);

SavedParams.Free;


AsSmallInt property

Applies to

TParam object

Declaration

procedure SetAsSmallInt(Value: Longint);

Description

Assigning a value to the AsSmallInt property sets the DataType property to fsSmallInt and save the value as the current data for the parameter. Accessing the AsSmallInt property attempts to convert the current data to a SmallInt value and returns that value.


Associate property

See also

Applies to

TUpDown component

Declaration

property Associate: TWinControl;

Description

Use the Associate property to select a companion control, called a buddy window. The TUpDown component automatically positions itself on the edge of the buddy window and resizes itself.

Note::	At design-time the companion control does not move with the TUpDown. You must either multi-select or first move the companion control and then Associate it with the TUpDown.


See also

AlignButton property

Orientation property

Position property


AsString property

Applies to

TParam object; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

AsString Property for Field Components

AsString Property for TParam Objects


AsString property for TParam objects
AsString property

See also

Applies to

TParam object

Declaration

property AsString: string;

Description

Assigning a value to the AsString property sets the DataType property to ftString and saves the value as the current data for the parameter. Accessing the AsString property attempts to convert the current data to a string value and returns that value.


See also

DateToStr function

DateTimeToStr function

FloatToStr function

IntToStr function

TFieldType type

TimeToStr function


AsString property for fields
AsString property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property AsString: string;

Description

Run-time only. This a conversion property. For a TStringField, AsString can be used to read or set the value of the field as a string, but Value should be used for this purpose instead.

For TBCDField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TIntegerField, TSmallintField, TTimeField, and TWordField, AsString converts a string to the appropriate type on inserting to or updating the field, and converts the type to a string when reading from the field.

For TBooleanField, on insert or update AsString sets the value to True if the text begins with the letter "Y", "y", "T" or "t" and to False otherwise. When reading from a Boolean field, AsString returns 'T' or 'F'.

For a TMemoField, AsString should only be used to read from the field. It sets the string value to '(Memo)'. An exception is raised if AsString is used to write to a TMemoField.

For a TGraphicField, AsString should only be used to read from the field. It sets the string value to '(Graphic)'. An exception is raised if AsString is used to write to a TGraphicField.

For a TBlobField, AsString should only be used to read from the field. It sets the string value to '(Blob)'. An exception is raised if AsString is used to write to a TBlobField.

For a TBytesField, AsString should only be used to read from the field. It sets the string value to '(Bytes)'. An exception is raised if AsString is used to write to a TBytesField.

For a TVarBytesField, AsString should only be used to read from the field. It sets the string value to '(Var Bytes)'. An exception is raised if AsString is used to write to a TVarBytesField.

Note:	When working with TMemoField, TGraphicField, or TBlobField, use the Assign, LoadFromFile, or LoadFromStream methods to write to a field, and Assign, SaveToFile, or SaveToStream methods to read from a field.


AsText property

See also	Example

Applies to

TClipboard object

Declaration

property AsText: string;

Description

Run-time only. The AsText property returns the current contents of the Clipboard as a string. The Clipboard must contain a string or an exception occurs.

You can also use the AsText property to place a copy of a string on the Clipboard. Assign a string as the value of AsText.

The string value of the AsText property is limited to 255 characters. If you need to set and retrieve more than 255 characters, use the SetTextBuf and GetTextBuf Clipboard methods.

If the Clipboard contains a string, this expression is True:

Clipboard.HasFormat(CF_TEXT)


Example

The following code retrieves the contents of the Clipboard as a string and displays the value in a label:

begin

  Label1.Caption := Clipboard.AsText;

end;


See also

Clipboard function

HasFormat method


AsTime property

See also

Applies to

TParam object

Declaration

property AsTime: TDateTime;

Description

Assigning a value to the AsTime property sets the DataType property to ftTime and saves the value as the current data for the parameter. Accessing the AsTime property attempts to convert the current data to a TDateTime value and returns that value.


See also

StrToDateTime function

TDateTime type

TFieldType type


AsVariant property

Applies to

All field components

Declaration

property AsVariant: Variant;

Description

Run-time only. The AsVariant property lets you access and set the field's value as a variant. Using variants is useful when you don't know the actual field type and don't want to use one of the other As... properties to convert the field value to another type. TField's Value property uses AsVariant to read and write field values.


AsWord property

See also

Applies to

TParam object

Declaration

property AsWord: Longint;

Description

Assigning a value to the AsWord property sets the DataType property to ftWord and saves the value as the current data for the parameter. Accessing the AsWord property attempts to convert the current data to a Longint value and returns that value.


See also

TFieldType type


AutoArrange property

See also

Applies to

TIconOptions object

Declaration

property AutoArrange: Boolean;

Description

The AutoArrange property determines if the icons in a list view with ViewStyle set to vsIcon will be automatically arranged when items are added, removed, or moved. Set this property to True to have icons arranged automatically.


See also

IconOptions property

Arrangement property

ViewStyle property


AutoCalcFields property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property AutoCalcFields: Boolean;

Description

The AutoCalcFields property determines when OnCalcFields is called. OnCalcFields is always called whenever an application retrieves a record from the database. If AutoCalcFields is True, then OnCalcFields is called also whenever a field in a dataset is edited.

If AutoCalcFields is True, OnCalcFields should not perform any actions that modify the dataset (or the linked dataset if it is part of a master-detail relationship), because this can lead to recursion. For example, if OnCalcFields performs a Post, and AutoCalcFields is True, then OnCalcFields will be called again, leading to another Post, and so on.


AutoDisplay property

See also	Example

Applies to

TDBImage, TDBMemo component

Declaration

property AutoDisplay: Boolean;

Description

The value of the AutoDisplay property determines whether to automatically display the contents of a memo or graphic BLOB in a database memo (TDBMemo) or database image (TDBImage) control.

If AutoDisplay is True (the default value), the control automatically displays new data when the underlying BLOB field changes (such as when moving to a new record).

If AutoDisplay is False, the control clears whenever the underlying BLOB field changes. To display the data, the user can double-click on the control or select it and press Enter. In addition, by calling the LoadMemo method of a database memo or the LoadPicture method of a database image you can ensure that the control is showing data.

You might want to change the value of AutoDisplay to False if the automatic loading of BLOB fields seems to take too long.


Example

The following code displays the text BLOB in DBMemo1.

DBMemo1.AutoDisplay := True;


See also

LoadMemo method

LoadPicture method


AutoEdit property

Applies to

TDataSource component

Declaration

property AutoEdit: Boolean;

Description

AutoEdit determines if data-aware controls connected to TDataSource automatically place the current record into edit mode by calling the table's Edit method when the user begins typing within one of them. AutoEdit is True by default; set it to False to protect the data from being unintentionally modified. When AutoEdit is False, you can still call the Edit method to modify a field.


AutoEnable property

See also	Example

Applies to

TMediaPlayer component

Declaration

property AutoEnable: Boolean;

Description

The AutoEnable property determines whether the media player automatically enables and disables individual buttons in the component.

If AutoEnable is True, the media player automatically enables or disables its control buttons. The media player determines which buttons to enable or disable by the current mode specified in the Mode property, and the current multimedia device type specified in the DeviceType property.

AutoEnable overrides the EnabledButtons property. The buttons enabled or disabled automatically by the media player supersede any buttons enabled or disabled with EnabledButtons.

If AutoEnable is False, the media player does not enable or disable buttons. You must enable or disable buttons with the EnabledButtons property.

The following table shows whether buttons are automatically enabled or disabled for each device mode:

Button	Play	Record	Pause	Stop	Not Open

Back	Enabled	Enabled	Enabled	Enabled	Disabled

Eject	Enabled	Enabled	Enabled	Enabled	Disabled

Next	Enabled	Enabled	Enabled	Enabled	Disabled

Pause	Enabled	Enabled	Enabled	Disabled	Disabled

Play	Disabled	Disabled	Enabled	Enabled	Disabled

Prev	Enabled	Enabled	Enabled	Enabled	Disabled

Record	Disabled	Disabled	Enabled	Enabled	Disabled

Step	Enabled	Enabled	Enabled	Enabled	Disabled

Stop	Enabled	Enabled	Disabled	Disabled	Disabled


Example

The following code causes all of the buttons of MediaPlayer1 to become disabled when a bitmap button is clicked:

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    AutoEnable := False;

    EnabledButtons := [];

  end;

end;


See also

AutoOpen property


AutoMerge property

See also	Example

Applies to

TMainMenu component

Declaration

property AutoMerge: Boolean;

Description

The AutoMerge property determines if the main menus (TMainMenu) of forms other than the main form merge with the main menu of the main form in non-MDI applications at run time. The default value is False. To merge the form's menus with the main menu in the main form, set the AutoMerge property of each main menu you want merged to True. Make sure that the AutoMerge property of the main menu you are merging with other menus remains False. How menus merge depends on the value of the GroupIndex property for each menu item.

If the application is an MDI application (the FormStyle properties are set so the main form is a parent form and subsequent forms are child forms), menu merging occurs automatically and you don't need to use the AutoMerge property.


Example

This example uses two forms with a main menu and a button on each form. Using the Object Inspector, set the GroupIndex value for each menu item on the menu bar in the second form to a number greater than 0. When the application runs and the user clicks the button on the first form, the main menu on the second form merges with the main menu of the first form. When the user clicks the button on the second form, the form closes.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form2.MainMenu1.AutoMerge := True;

  Form2.Show;

end;

This is the code for the button-click event handler on the second form:

procedure TForm2.Button1Click(Sender: TObject);

begin

  Close;

end;

To run this example, you must add Unit2 to the uses clause of Unit1.


See also

GroupIndex property

Merge method

Unmerge method


AutoOpen property

See also	Example

Applies to

TMediaPlayer component

Declaration

property AutoOpen: Boolean;

Description

The AutoOpen property determines if the media player is opened automatically when the application is run. If AutoOpen is True, the media player attempts to open the multimedia device specified by the DeviceType property (or FileName if DeviceType is dtAutoSelect) when the form containing the media player component is created at run time. If AutoOpen is False, the device must be opened with a call to the Open method. AutoOpen defaults to True.

If an error occurs when opening the device, an exception of type EMCIDeviceError is raised which contains the error message. Upon completion, a numerical error code is stored in the Error property, and the corresponding error message is stored in the ErrorMessage property.

The Wait property determines whether control is returned to the application before opening the multimedia device. The Notify property determines whether opening the device generates an OnNotify event.


Example

The following code opens MediaPlayer1 if AutoOpen was not set to True. This code assumes that an appropriate value was specified for FileName at design time.

with MediaPlayer1 do

  if not AutoOpen then

    Open;


See also

Close method


AutoPopup property

See also	Example

Applies to

TPopupMenu component

Declaration

property AutoPopup: Boolean;

Description

The AutoPopup property determines if the pop-up menu appears when the user clicks the right mouse button on the component that has this menu specified as the value of its PopupMenu property. If AutoPopup is True, a right click displays the pop-up menu. If AutoPopup is False, the menu won't appear when the user clicks the right mouse button. The default value is True.

The application key present on keyboards specifically designed for Windows 95 will also show this menu when pressed.

To display a pop-up menu when AutoPopup is False, you must use the Popup method.


Example

The following prevents the pop-up menu from appearing when the user clicks the right mouse button:

PopupMenu1.AutoPopup := False;


See also

OnPopup event, Popup method


AutoRewind property

See also	Example

Applies to

TMediaPlayer component

Declaration

property AutoRewind: Boolean;

Description

The AutoRewind property determines if the media player control rewinds before playing or recording.

If AutoRewind is True and the current position is at the end of the medium, Play or StartRecording moves the current position to the beginning of the medium before playing or recording. If AutoRewind is False, the user must click the Prev button or your code must call Previous to move to the beginning.

Note:	If values have been assigned to StartPos or EndPos or if the multimedia device uses tracks, AutoRewind has no effect on playing or recording. When you call Play or StartRecording, the current position remains at the end of the medium.


Example

The following code plays MediaPlayer. If AutoRewind is False, Previous is called to rewind after Play is finished.

MediaPlayer.Wait := True;

MediaPlayer.Play;

if not MediaPlayer.AutoRewind then MediaPlayer.Previous;


See also

Rewind method


AutoScroll property

Applies to

TForm, TScrollBox, TTabSet components

Description

AutoScroll Property for Tab Set Controls

AutoScroll Property for Forms and Scroll Boxes


AutoScroll property for tab set controls
AutoScroll property

See also	Example

Applies to

TTabSet component

Declaration

property AutoScroll: Boolean;

Description

The AutoScroll property determines if scroll buttons automatically appear in a tab set control if there isn't room in the control to display all the tabs.

If AutoScroll is False, your application can still access tabs that aren't visible by using the FirstIndex or TabIndex properties at design time or run time, but the user can't click on the tabs with the mouse at run time.


Example

This code displays scroll buttons in the tab set control if all the tabs aren't visible:

TabSet11.AutoScroll := True;


See also

FirstIndex property

TabIndex property


AutoScroll property for forms and scroll boxes
AutoScroll property

See also	Example

Applies to

TForm, TScrollBox components

Declaration

property AutoScroll: Boolean;

Description

The AutoScroll property determines if scroll bars appear on the form when the form is not large enough to display all the controls it contains. If AutoScroll is True, the scroll bars appear automatically when necessary. For example, if the user resizes the form so that it is smaller and some controls are partially obscured, scroll bars appear. If AutoScroll is False, no scroll bars appear.


Example

This example uses a label on a form. When the form becomes active, the label displays a message informing the user whether scroll bars will be available if the form is resized so that not all controls are fully visible.

procedure TForm1.FormActivate(Sender: TObject);

begin

  if AutoScroll then

    Label1.Caption := 'Scroll bars might appear!'

  else

    Label1.Caption := 'No scroll bars will appear';

end;


See also

HorzScrollBar property

ScrollInView method

VertScrollBar property


AutoSelect property

See also	Example

Applies to

TDBEdit, TDBLookupCombo, TEdit, TMaskEdit components

Declaration

property AutoSelect: Boolean;

Description

The value of the AutoSelect property determines if the text in the edit box or combo box is automatically selected when the user tabs to the control. If AutoSelect is True, the text is selected. If AutoSelect is False, the text is not selected.

The default value is True.


Example

This example uses an edit box and a check box on a form. Set the caption of the check box to 'AutoSelect text'. When the user checks the check box, text is automatically selected each time the user tabs to the edit box. If the user unchecks the check box, text is no longer selected automatically when the user tabs to the edit box.

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    Edit1.AutoSelect := True

  else

    Edit1.AutoSelect := False;

  end;

end;


See also

AutoSize property

SelLength property

SelStart property

SelText property

Text property


AutoSize property

Applies to

TDBEdit, TDBText, TEdit, THotKey, TImage, TLabel, TMaskEdit components

Description

The AutoSize property determines if the component automatically resizes to match the size of its contents.

AutoSize Property for Image Components

AutoSize Property for Edit Box,Hot Key and Database Lookup Combo Box Components

AutoSize Property for Label and Database Text Components


AutoSize property

See also	Example

Applies to

TDBImage, TImagecomponents

Declaration

property AutoSize: Boolean;

Description

When the AutoSize property is True, the image control resizes to accommodate the image it contains (specified by the Picture property). When AutoSize is False, the image control remains the same size, regardless of the size of the image. If the image control is smaller than the image, only the portion of the picture that fits inside the image component will be visible.

The default value is False.

Note:	You must remember to set the AutoSize property to True before loading the picture, or AutoSize has no effect.

To resize the image to fill an image control completely when the control is larger than the native size of the image, use the Stretch property.


Example

This example uses an image control and a button. Resize the image control so that it is too small to display the entire bitmap. When the user clicks the button, the bitmap is loaded into the image control, and the image control resizes to display the bitmap in its entirety.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Image1.AutoSize := True;

  Image1.Picture.LoadFromFile('c:\windows\arches.bmp');

end;


See also

LoadFromFile method

Stretch property


AutoSize property

See also	Example

Applies to

TDBEdit, TDBLookupCombo, TEdit, THotKey, TMaskEdit components

Declaration

property AutoSize: Boolean;

Description

When the AutoSize property is True, the height of the edit box changes to accommodate font size changes to the text. When AutoSize is False, the edit box remains the same size, regardless of any font changes. The default value is True.

If an edit box has no border, changing the value of AutoSize has no effect. In other words, the BorderStyle property must have a value of bsSingle.


Example

This example uses an edit box, a label, and a button on a form. When the user clicks the button, the font in the edit box enlarges, and the edit box enlarges also to accommodate the larger font size.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.AutoSize := True;

  Edit1.Font.Size := 20;

  Label1.Caption := 'The edit box is bigger now';

end;


See also

Font property


AutoSize property

See also	Example

Applies to

TDBText, TLabel components

Declaration

property AutoSize: Boolean;

Description

When the AutoSize property is True, the label component resizes to the width and length of the current string in the label's Caption property. If you type text for a label while AutoSize is True, the label grows for each character you type. If you change the font size of the text, the label resizes to the new font size. When AutoSize is False, the size of the label is not affected by the length of the string in its Caption property.

The default value of AutoSize is True.


Example

The following code keeps the size of the label control constant, even though the length of the label's caption changes. As a result, the caption of the label is probably too long to display in the label when the user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.AutoSize := False;

  Label1.Caption := 'This string is too long as the caption of this label';

end;


See also

WordWrap property


AutoUnload property

Example

Applies to

TReport component

Declaration

property AutoUnload: Boolean;

Description

The AutoUnload property determines whether ReportSmith unloads from memory when you have finished running a report.

If AutoUnload is True, ReportSmith unloads as soon as the report is finished running.

If AutoUnload is False, ReportSmith remains in memory. For example, you can create an application that includes a menu item that runs a report. After the report runs, you want ReportSmith to stay in memory so the report can be quickly rerun again. To remove ReportSmith from memory when AutoUnload is False, you must then call the CloseApplication method.


Example

The following code sets AutoUnload to False, so that Report1 can be run twice using two different variables. After the second run, ReportSmith is unloaded by a call to CloseApplication.

Report1.AutoUnload := False;

if Report1.SetVariable('FName', 'Linda') then

  Report1.Run;

if Report1.SetVariable('LName', 'King') then

  Report1.Run;

Report1.CloseApplication(False);


Back method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Back;

Description

The Back method steps backward a number of frames (determined by the value of the Frames property) in the currently loaded medium. Back is called when the Back button on the media player control is clicked at run time.

Upon completion, Back stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Back method has been completed. The Notify property determines whether Back generates an OnNotify event.


Example

The following example lets the user pick an .AVI video file using OpenDialog1 and opens that file in MediaPlayer1. Then, the Back button can be used to step backward through the .AVI clip. You could use this to hide MediaPlayer1 and design your own user interface for the media player.

procedure TForm1.OpenClick(Sender: TObject);

begin

  OpenDialog1.Filename := '*.*';

  if OpenDialog1.Execute then

  begin

    MediaPlayer1.Filename := OpenDialog1.Filename;

    MediaPlayer1.Open;

  end;

end;

procedure TForm1.BackClick(Sender: TObject);

begin

  MediaPlayer1.Back;

end;


See also

Capabilities property

OnClick event

Rewind method

Step method


BackgroundColor property

See also	Example

Applies to

TTabSet component

Declaration

property BackgroundColor: TColor;

Description

The BackgroundColor property determines the background color of the tab set control. The background area of the tab set control is the area between the tabs and the border of the control. For a list of possible color values, see the Color property.


Example

This code changes the background color of the tab set control:

TabSet1.BackgroundColor := clBackground;


See also

DitherBackground property


BatchMove method

See also	Example

Applies to

TTable component

Declaration

function BatchMove(ASource: TDataSet; AMode: TBatchMode): Longint;

Description

The BatchMove method copies, appends, updates, or deletes records in the TTable. ASource is a TTable linked to a database table containing the source records. AMode is the copy mode; it can be any of the elements of TBatchMode: batAppend, batUpdate, batAppendUpdate, batDelete, or batCopy.

BatchMove returns the number of records operated on.


Example

Table1.BatchMove(Table2, batAppend);


See also

TBatchMove component


BeforeCancel event

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforeCancel: TDataSetNotifyEvent;

Description

The BeforeCancel event is activated at the beginning of a call to the Cancel method. This event is the first action taken by Cancel. If the dataset is not in Edit state or there are no changes pending, then Cancel will not activate the BeforeCancel event.

By assigning a method to this property, you can take any special actions required by the event. By raising an exception in this event handler, you can prevent the Cancel operation from occurring.


See also

AfterCancel event


BeforeClose event

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforeClose: TDataSetNotifyEvent;

Description

The BeforeClose event is activated before the dataset is closed, either by calling the Close method or by setting the Active property to False. This event is the first action taken by Close.

By assigning a method to this property, you can take any special actions required by the event. By raising an exception in this event handler, you can prevent the Close operation from occurring.


See also

AfterClose event


BeforeDelete event

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforeDelete: TDataSetNotifyEvent;

Description

The BeforeDelete event is activated when the dataset begins a call to Delete. This event is the first action taken by the Delete method.

By assigning a method to this property, you can take any special actions required by the event. By raising an exception in this event handler, you can prevent the Delete operation from occurring.


See also

AfterDelete event


BeforeEdit event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforeEdit: TDataSetNotifyEvent;

Description

The BeforeEdit event is activated when the dataset begins a call to the Edit method. This event is the first action taken by Edit.

By assigning a method to this property, you can take any special actions required by the event. By raising an exception (such as by calling the Abort procedure) in this event handler, you can prevent the Edit operation from occurring.


Example

This example uses the form's status bar to display the contents of the table's first field before the table enters edit mode.

procedure TForm1.Table1BeforeEdit(DataSet: TDataSet);

begin

  StatusBar1.SimpleText := 'First field before edit = ' +

   Table1.Fields[0].AsString;

end;


See also

AfterEdit event

Abort procedure


BeforeInsert event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforeInsert: TDataSetNotifyEvent;

Description

The BeforeInsert event is activated when the dataset begins a call to the Insert or Append methods. This event is the first action taken by Insert or Append.

By assigning a method to this property, you can take any special actions required by the event. By raising an exception (such as by calling the Abort procedure) in this event handler, you can prevent the Insert operation from occurring.


Example

This example uses the BeforeInsert event to do data validation; if the StrToInt function raises an exception, the edit control's contents are set to a valid value so the assignment to the INTEGER field in the table will succeed.

procedure TForm1.Table1BeforeInsert(DataSet: TDataSet);

begin

  try

    {Make sure edit field can be converted to integer --

     will throw an exception if it can't }

    StrToInt(Edit1.Text);

  except

    Edit1.Text := '1000';

  end;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Table1.Insert;

  Table1.FieldByName('INTEGER').AsInteger := StrToInt(Edit1.Text);

  Table1.Post;

end;


See also

AfterInsert event

Abort procedure

OnNewRecord event


BeforeOpen event

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforeOpen: TDataSetNotifyEvent;

Description

The BeforeOpen event is activated before the dataset is opened, either by calling the Open method or by setting the Active property to True. This event is the first action taken by the Open method. Typically, the BeforeOpen event handler opens any private lookup tables used by other event handlers in the dataset.

By assigning a method to this property, you can take any special actions required by the event. By raising an exception in this event handler, you can prevent the Open operation from occurring.


See also

AfterOpen event


BeforePost event

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BeforePost: TDataSetNotifyEvent;

Description

The BeforePost event is activated at the beginning of a call to the Post method. This event is the first action taken by the Post method, after it calls the UpdateRecord method to reflect any changes made to the record by data controls. The BeforePost event can be used to validate a record before it is posted. By raising an exception (such as by calling the Abort procedure), a BeforePost event handler can prevent the posting of an invalid record.


Example

This example checks for a valid entry in a TDBEdit control and calls the Abort procedure if the control is empty; Abort cancels the post before it happens.

procedure TForm1.Table1BeforePost(DataSet: TDataSet);

begin

  if DBEdit1.Text = '' then

    Abort;

end;


See also

AfterPost event

Abort procedure


BeginDoc method

See also	Example

Applies to

TPrinter object

Declaration

procedure BeginDoc;

Description

The BeginDoc method sends a print job to the printer. If the print job is sent successfully, the application should call EndDoc to end the print job. The print job won't actually start printing until EndDoc is called.

To use the BeginDoc method, you must add the Printers unit to the uses clause of your unit.


Example

This code prints a rectangle on the default printer:

begin

  Printer.BeginDoc;                              { begin to send print job to printer }

  Printer.Canvas.Rectangle(20,20,1000,1000);     { draw rectangle on printer's canvas }

  Printer.EndDoc;                         { EndDoc ends and starts printing print job }

end;

To use the BeginDoc method, you must add the Printers unit to the uses clause of your unit.


See also

Abort method

Printer function


BeginDrag method

See also

Applies to

All controls

Declaration

procedure BeginDrag(Immediate: Boolean);

Description

The BeginDrag method starts the dragging of a control. If the Immediate parameter is True, the mouse pointer changes to the value of the DragCursor property and dragging begins immediately. If Immediate is False, the mouse pointer doesn't change to the value of the DragCursor property and dragging doesn't begin until the user moves the mouse pointer a short distance (5 pixels). This allows the control to accept mouse clicks without beginning a drag operation.

Your application needs to call the BeginDrag method to begin dragging only when the DragMode property value for the control is dmManual.


See also

DragMode property

EndDrag method

OnDragDrop event

OnDragOver event

OnEndDrag event

Starting a Drag Operation


BeginDrag method

See also

Applies to

TImageList

Declaration

function BeginDrag(Window: HWND; X, Y: Integer): Boolean;

Description

The BeginDrag method starts the dragging of an image. Window is the handle to the image list. The X and Y are the coordinates of the drag position relative to the upper-left corner of the image


See also

EndDrag method

OnDragDrop event

OnDragOver event

OnEndDrag event

Starting a Drag Operation


BeginUpdate method

See also	Example

Applies to

TCollection, THeaderSections, TListItems, TStatusPanels, TStringList, TStrings objects; TOutline component

Declaration

procedure BeginUpdate;

Description

The BeginUpdate method prevents the updating of the collection, item list, outline or string object until the EndUpdate method is called. For string objects, BeginUpdate prevents the screen from being repainted when new strings are added. For collections, item lists, and outlines, BeginUpdate prevents the screen from being repainted and prevents outline items from being reindexed when new items are added, deleted, or inserted. Outline items affected by the changes will have invalid Index values until EndUpdate is called.

For example, the Lines property of a memo component is of type TStrings. If your application calls the AddStrings method to add several strings at once to the Lines property, AddStrings calls BeginUpdate before the strings are added. After the strings are added, AddStrings calls EndUpdate and the screen repaints, displaying the new list of strings.

Use BeginUpdate to prevent screen repaints and to speed processing time while you are rebuilding your list.


Example

The following example adds a panel to the status bar control when the user clicks the button and adds a caption to the panel. The code uses BeginUpdate and EndUpdate within which is a try...finally block that ensures EndUpdate is called even when an exception occurs.

procedure TForm1.Button1Click(Sender: TObject);

var

  PanelIndex : Integer;

begin

  with StatusBar1 do

  begin

    Panels.BeginUpdate;

    PanelIndex := StatusBar1.Panels.Count - 1;

    try

      Panels.Add;

      Inc(PanelIndex);

      Panels.Items[PanelIndex].Text := 'Panel' + IntToStr(PanelIndex-1);

    finally

      Panels.EndUpdate;

    end;

  end;

end;


See also

EndUpdate method


Bevel property

See also

Applies to

TStatusPanel object

Declaration

property Bevel: TStatusPanelBevel;

Description

The Bevel property determines the bevel style of the individual panels of a TStatusBar.

Value	Meaning

pbNone	The panel has no bevel and appears flat.

pbLowered	The panel has a lowered bevel and appears inset.

pbRaised	The panel appears raised.

Each individual panel in the status bar can have a different bevel style. The default is pbLowered.


See also

Panels property


BevelInner property

See also	Example

Applies to

TPanel component

Declaration

property BevelInner: TPanelBevel;

Description

A panel component has two bevels, an outer bevel drawn next to the border of the control, and an inner bevel drawn inside the outer bevel the number of pixels specified in the BorderWidth property.

The BevelInner property determines the style of the inner bevel of a panel component. These are the possible values:

Value	Meaning

bvNone	No inner bevel exists.

bvLowered	The inner bevel is lowered.

bvRaised	The inner bevel is raised.


Example

This example uses a panel component and a button named CreateStatusLine on a form. The code moves the panel to the bottom of the form when the user clicks the button and gives the panel the appearance of a status line by changing the value of the BevelInner, BevelOuter, BevelWidth, and BorderWidth properties.

procedure TForm1.CreateStatusLineClick(Sender: TObject);

begin

with Panel1 do

  begin

    Align := alBottom;

    BevelInner := bvLowered;

    BevelOuter := bvRaised;

    BorderWidth := 1;

    BevelWidth := 1;

  end;

end;


See also

BevelOuter property

BevelWidth property

BorderWidth property

TPanelBevel type


BevelOuter property

See also	Example

Applies to

TPanel component

Declaration

property BevelOuter: TPanelBevel;

Description

A panel component has two bevels, an outer bevel drawn next to the border of the control, and an inner bevel drawn inside the outer bevel. The width of the inner bevel is specified in the BorderWidth property in pixels.

The BevelOuter property determines the style of the outer bevel of a panel component. These are the possible values:

Value	Meaning

bvNone	No outer bevel exists.

bvLowered	The outer bevel is lowered.

bvRaised	The outer bevel is raised.


Example

This code creates a lowered frame 10 pixels wide around a panel component named Panel1:

Panel1.BorderWidth := 10;

Panel1.BevelInner := bvRaised;

Panel1.BevelOuter := bvLowered;


See also

BevelInner property

BevelWidth property

BorderWidth property


BevelWidth property

See also	Example

Applies to

TPanel component

Declaration

property BevelWidth: TBevelWidth;

Description

The BevelWidth property determines the width in pixels between the inner and the outer bevels of a panel. The BevelInner property determines how the inner bevel appears, and the BevelOuter property determines how the outer bevel appears. By changing these properties, you change the appearance of the panel.


Example

This code alternately displays and hides the bevels of a panel when the user clicks the Button1 button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  with Panel1 do

  begin

    BevelInner := bvLowered;

    BevelOuter := bvRaised;

    if BevelWidth = 0 then

      BevelWidth := 2

    else

      BevelWidth := 0;

  end;

end;


See also

BorderWidth property


Bitmap property

Applies to

TBrush, TPicture objects

Description

The Bitmap property specifies a TBitmap object.

Bitmap Property for Brushes

Bitmap Property for Pictures


Bitmap property

Example

Applies to

TBrush object

Declaration

property Bitmap: TBitmap;

Description

Run-time only. The Bitmap property enables a brush to use a bitmap image for painting with the ability to produce special painting effects such as patterns. The bitmap must be 8 pixels high and 8 pixels wide.

Note:	Unlike other TBitmap properties, a Bitmap property for a TBrush is a reference to a bitmap. This reference is nil until you create and assign a bitmap object to the property. Once you are finished with the brush, you must also free the bitmap since the brush will not free it. Changing the bitmap will not affect the brush until the bitmap is reassigned to the brush.


Example

The following code loads a bitmap from a file and assigns it to the Brush of the Canvas of Form1:

var

  Bitmap: TBitmap;

begin

  Bitmap := TBitmap.Create;

  try

    Bitmap.LoadFromFile('MyBitmap.bmp');

    Form1.Canvas.Brush.Bitmap := Bitmap;

    Form1.Canvas.FillRect(Rect(0,0,100,100));

  finally

    Form1.Canvas.Brush.Bitmap := nil;

    Bitmap.Free;

  end;

end;


Bitmap property

See also	Example

Applies to

TPicture object

Declaration

property Bitmap: TBitmap;

Description

The Bitmap property specifies the contents of the TPicture object as a bitmap graphic (.BMP file format). If Bitmap is referenced when the TPicture contains a Metafile or Icon graphic, the graphic won't be converted. Instead, the original contents of the TPicture are discarded and Bitmap returns a new, blank bitmap.


Example

The following code copies the bitmap in Picture1 to the Glyph of BitBtn1.

BitBtn1.Glyph := Picture1.Bitmap;


See also

Graphic property


BkColor property

See also

Applies to

TImageList object

Declaration

property BkColor: TColor;

Description

The BkColor property determines which background color to use when drawing an image. clNone specifies no background color i.e. the image is drawn transparently while clDefault specifies using the image lists background color when drawing.


See also

BlendColor property


BlendColor property

See also

Applies to

TImageList object

Declaration

property BlendColor: TColor

Description

The BlendColor property determines which foreground color to use when drawing an image. clNone specifies no blend color while clDefault specifies the system highlight color for the foreground color.


See also

BkColor property


BlobType property

Applies to

TBlobField, TMemoField, TGraphicField components

Declaration

property BlobType: TBlobType;

Description

The BlobType property precisely identifies the type of blob field associated with a blob field object. Specifying blob types when you're using a TBlobField object to represent a blob type that VCL doesn't directly support (such as a formatted memo blob) lets VCL ensure that the blob type in the table matches what you expect to work with.


See also

TFieldType type


BOF property

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property BOF: Boolean;

Description

Run-time and read only. BOF is a Boolean property that indicates whether a dataset is known to be at its first row. The BOF property returns a value of True only after:

An application first opens a table

A call to a dataset's First method

A call to a dataset's Prior method fails because the cursor is on the first row


Example

This example uses TDataSource's OnDataChange event to detect when the user moves to another record. If the beginning of file is reached (BOF property becomes True), a message is displayed on the form's status bar.

procedure TForm1.DataSource1DataChange(Sender: TObject; Field: TField);

begin

   if Table1.BOF then

      StatusBar1.SimpleText := 'You''re at the beginning of the table';

end;


See also

MoveBy method

EOF property


BorderColor property

Example

Applies to

TShape component

Declaration

property BorderColor: TColor;

Description

The BorderColor property is used to color the border of a shape component. For a complete list of the values the BorderColor property can have, see the Color property.


Example

This example changes the border color of a shape component at run time:

Shape1.BorderColor := clBlack;


BorderIcons property

See also	Example

Applies to

TForm component

Declaration

property BorderIcons: TBorderIcons;

Description

The BorderIcons property is a set whose values determine which icons appear on the title bar of a form. These are the possible values that the BorderIcons set can contain:

Value	Meaning

biSystemMenu	 The form has a Control menu (also known as a System menu)

biMinimize	The form has a Minimize button

biMaximize	The form has a Maximize button

biHelp	The form shows help in pop-up windows, rather than starting Windows Help (WINHELP.EXE). If biMinimize and biMaximize are excluded, a question mark appears in the form's title bar; otherwise, it is hidden.


Example

The following code removes a form's Maximize button when the user clicks a button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  BorderIcons := BorderIcons - [biMaximize];

end;


See also

BorderStyle property


BorderStyle property

Applies to

TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDrawGrid, TEdit, TForm, THeader, TListBox, TListView, TMaskEdit, TMemo, TOutline, TPanel, TRichEdit, TScrollBox, TStringGrid, TTreeView components

Description

The BorderStyle property controls the kind of border the component displays.

Border Style Property for Forms

BorderStyle Property for Controls


BorderStyle Property for Forms and Labels
BorderStyle property

See also	Example

Applies to

TForm component

Declaration

property BorderStyle: TFormBorderStyle;

Description

The BorderStyle property for forms specifies both the appearance and the behavior of the form border. You normally set BorderStyle at design time, but you can also change it at run time.

BorderStyle can have any of the following values:

Value	Meaning

bsDialog	Not resizeable; standard dialog box border

bsSingle	Not resizeable; single-line border

bsNone	Not resizeable; no visible border line, Minimize or Maximize buttons, or Control menu

bsSizeable	Standard resizeable border

bsToolWindow	like bsSingle but with a smaller caption

bsSizeToolWin	like bsSizeable with a smaller caption

Changing the border style of an MDI child form to bsDialog or bsNone has no effect.


Example

This example creates a form with a single-line border that the user can't resize:

Form1.BorderStyle := bsSingle;


See also

BorderIcons property


BorderStyle Property for Edit Boxes, Gauges, and Grid Controls
BorderStyle property

See also	Example

Applies to

TDBEdit, TDBGrid, TDBListBox, TDBMemo, TDrawGrid, TEdit, TListBox, TListView, THeader, THotKey, TMaskEdit, TMemo, TOutline, TPanel, TRichEdit, TScrollBox, TStringGrid, TTreeView components

Declaration

property BorderStyle: TBorderStyle;

Description

The BorderStyle property of edit boxes, list boxes, memo controls, grid controls, outlines, and scroll boxes determines whether these components have a border. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border

If you set the AutoSize property of an edit box or hot-key to True, the edit box or hot-key resizes automatically when the font size of the text changes. You must set the value of the BorderStyle property to fsSingle, or else AutoSize has no effect.


Example

The following example puts a single-line border around the edit box, Edit1.

Edit1.BorderStyle := bsSingle;


See also

Ctl3D property


BorderWidth property

See also	Example

Applies to

TPanel component

Declaration

property BorderWidth: TBorderWidth;

Description

The BorderWidth property determines the width in pixels of the border around a panel. The default value is 0, which means no border.


Example

This example uses a panel component and a button named CreateStatusLine on a form. The code moves the panel to the bottom of the form when the user clicks the button, and gives the panel the appearance of a status line by changing the value of the BevelInner, BevelOuter, BevelWidth, and BorderWidth properties:

procedure TForm1.CreateStatusLineClick(Sender: TObject);

begin

  with Panel1 do

    Align := alBottom;

    BevelInner := bvLowered;

    BevelOuter := bvRaised;

    BorderWidth := 1;

    BevelWidth := 1;

  end;

end;


See also

BevelInner property

BevelOuter property

BevelWidth property


Bound property

Applies to

TParam object

Declaration

property Bound: Boolean;

Description

The Bound property indicates whether a value (null or otherwise) is specified for the parameter associated with the TParam object.  Bound also determines if Delphi automatically sets the parameter value for a parameterized query or stored procedure.

If Bound is False, then the parameter is not bound to an actual value, and Delphi attempts to assign a value from the dataset associated with the DataSource property of a query, or it attempts to supply a value directly from the server in the case of a stored procedure.


BoundingRect property

Applies to

TListView component

Declaration

property BoundingRect: TRect;

Description

Run-time and read only. The BoundingRect property retrieves the bounding rectangle of all items in the list view control. The list view's ViewStyle property must be either vsIcon or vsSmallIcon.


Bounds function

See also	Example

Unit

Classes

Declaration

function Bounds(ALeft, ATop, AWidth, AHeight: Integer): TRect;

Description

The Bounds function returns a rectangle with the given dimensions. The statement

R := Bounds(X, Y, W, H);

corresponds to

R := Rect(X, Y, X + W, Y + H);


Example

This example returns a TRect record that defines a rectangle that is 100 pixels long on each side with the top left corner at coordinate 10, 10.

var

  R: TRect;

begin

  R := Bounds(10, 10, 100, 100);

end;


See also

BoundsRect property


BoundsRect property

See also	Example

Applies to

All controls

Declaration

property BoundsRect: TRect;

Description

The BoundsRect property returns the bounding rectangle of the control, expressed in the coordinate system of the parent control. The statement

R := Control.BoundsRect;

corresponds to

R.Left := Control.Left;

R.Top := Control.Top;

R.Right := Control.Left + Control.Width;

R.Bottom := Control.Top + Control.Height;


Example

This code resizes a button control to twice as wide and half as high:

procedure TForm1.Button1Click(Sender: TObject);

var

  MyRect: TRect;

begin

  MyRect := Button2.BoundsRect;

  MyRect.Right := MyRect.Left + 2 * (MyRect.Right - MyRect.Left);

  MyRect.Bottom := MyRect.Top + (MyRect.Bottom - MyRect.Top) div 2;

  Button2.BoundsRect := MyRect;

end;


See also

Bounds function


Break property

See also	Example

Applies to

TMenuItem component

Declaration

property Break: TMenuBreak;

Description

The Break property lets you break a long menu into columns. These are the possible values:

Value	Meaning

mbNone	No menu breaking occurs.

mbBarBreak	The menu breaks into another column with the menu item appearing at the top of the new column. A bar separates the new and the old columns.

mbBreak	The menu breaks into another column with the menu item appearing at the top of the new column. Only space separates the new and the old columns.

The default value is mbNone.


Example

This example uses a button and a main menu component with several subitems on it, including one labeled Save As, so that Delphi automatically names that menu item SaveAs1. When the user clicks the button on the form, the menu breaks so Save As appears in a second column with a bar between the two columns. The change to the menu is visible when the menu displays.

procedure TForm1.Button1Click(Sender: TObject);

begin

  SaveAs1.Break := mbBarBreak;

end;


See also

Checked property

Enabled property


BringToFront method

See also	Example

Applies to

All controls; TForm component

Declaration

procedure BringToFront;

Description

The BringToFront method puts the component or form in front of all other components or forms within its parent component or form. BringToFront is especially useful for making certain that a form is visible. You can also use it to reorder overlapping components within a form.

The order in which controls stack on top of each order (also called the Z order) depends on whether the controls are windowed or non-windowed controls. For example, if you put a label and an image on a form so that one is on top of the other, the one you placed first on the form is the one on the bottom. Because both the label and the image are non-windowed controls, they "stack" as you would expect them to. Suppose that the label is on the bottom. If you call the BringToFront method for the label, the label then appears on top of the image.

The stacking order of windowed controls is the same. For example, if you put a memo on a form, then put a check box on top of it, the check box remains on top. If you call BringToFront for the memo, the memo appears on top.

The stacking order of windowed and non-windowed controls cannot be mingled. For example, if you put a memo, a windowed control, on a form, and then put a label, a non-windowed control, on top of it, the label disappears behind the memo. Windowed controls always stack on top of non-windowed controls. In this example, if you call the BringToFront method of the label, it remains behind the memo.


Example

The following code uses two forms. Form1 has a button on it. The second form is used as a tool palette. This code makes the palette form visible, and ensures it is the top form by bringing it to the front.

To run this example, you must put Unit2 in the uses clause of your unit.

procedure TForm1.ShowPaletteButtonClick(Sender: TObject);

begin

  if Form2.Visible = False then Form2.Visible := True;

  Form2.BringToFront;

end;


See also

SendToBack method


Brush property

See also	Example

Applies to

All controls; TCanvas object; TForm, TShape components

Declaration

property Brush: TBrush;

Description

A canvas or shape object's Brush property determines what kind of color and pattern the canvas uses for filling graphical shapes and backgrounds. Controls also specify an additional brush in their Brush properties, which they use for painting their backgrounds.

For controls, Brush is a read only and run-time only property.


Example

The following code sets the color of the brush used by Form1 to fill shapes drawn on it with red:

procedure TForm1.MakeRedButtonClick(Sender: TObject);

begin

  Canvas.Brush.Color := clRed;

end;

This code changes the shape, color, and pattern of a shape component:

procedure TForm1.ChangeShapeClick(Sender: TObject);

begin

  Shape1.Shape := stEllipse;

  Shape1.Brush.Color := clMaroon;

  Shape1.Brush.Style := bsFDiagonal;

end;


See also

BrushCopy method

Canvas property

Font property

Pen property

TCanvas object


BrushCopy method

See also	Example

Applies to

TCanvas object

Declaration

procedure BrushCopy(const Dest: TRect; Bitmap: TBitmap; const Source: TRect; Color: TColor);

Description

The BrushCopy method copies a portion of a bitmap onto a portion of a canvas, replacing one of the colors of the bitmap with the brush of the destination canvas. Dest specifies the rectangular portion of the destination canvas to copy to. Bitmap specifies the graphic to copy from. Source specifies the rectangular area of the bitmap to copy. Color specifies the color in Bitmap to replace with the brush of the canvas (specified in the Brush property).

You could use BrushCopy to make the copied image partially transparent, for example. To do this, you would specify the color of the surface being copied to (clBackground for example) as the Color of the Brush property of the destination canvas, then call BrushCopy.

This is provided mainly for backwards compatibility. Use a TImageList instead of BrushCopy.


Example

The following code illustrates the differences between CopyRect and BrushCopy. The bitmap graphic 'TARTAN.BMP' is loaded into Bitmap and displayed on the Canvas of Form1. BrushCopy replaces the color black in the graphic with the brush of the canvas, while CopyRect leaves the colors intact.

var

  Bitmap: TBitmap;

  MyRect, MyOther: TRect;

begin

  MyRect.Top := 10;

  MyRect.Left := 10;

  MyRect.Bottom := 100;

  MyRect.Right := 100;

  MyOther.Top := 111; {110}

  MyOther.Left := 10;

  MyOther.Bottom := 201; {210}

  MyOther.Right := 100;

  Bitmap := TBitmap.Create;

  Bitmap.LoadFromFile('c:\windows\tartan.bmp');

  Form1.Canvas.BrushCopy(MyRect,Bitmap, MyRect, clBlack);

  Form1.Canvas.CopyRect(MyOther,Bitmap.Canvas,MyRect);

  Bitmap.Free;

end;


See also

Brush property

CopyRect method

TImageList component


BtnClick method

Example

Applies to

TDBNavigator component

Declaration

procedure BtnClick(Index: TNavigateBtn);

Description

The BtnClick method simulates a button click on the database navigator, invoking the action of the button. Specify which button BtnClick should operate on as the value of the Index parameter.


Example

This line of code simulates the clicking of the Next button on a database navigator control, which makes the next record in the dataset the current record:

DBNavigator1.BtnClick(nbNext);


Busy property

Applies to

TReport component

Declaration

property Busy: Boolean;

Description

Runtime and Read-only.  The Busy property indicates if ReportSmith is ready to perform an operation. If Busy is True, then ReportSmith is busy performing some task.  If Busy is False, then ReportSmith can execute another command.

Note:	Communication with ReportSmith is possible even while a task is being performed.


Buttons property

Example

Applies to

TDBRadioGroup, TRadioGroup components

Declaration

property Buttons: TList;

Description

Run-time and read only. The Buttons property lets your application access the list of radio buttons in the database radio button group box. Use the properties and methods of a list object (TList) to manipulate the list of buttons.


Example

The following code disables the first button in DBRadioGroup1.

TRadioButton(DBRadioGroup1.Buttons.First).Enabled := False;


ButtonStyle property

Applies to

TColumn object

Declaration

property ButtonStyle: TColumnButtonStyle;

Description

The ButtonStyle property lets you specify how you want the user to be able to choose data from a list for a column in a TDBGrid.


CachedUpdates property

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property CachedUpdates: Boolean;

Description

CachedUpdates indicates whether cached updates are enabled. While cached updates are enabled, updates you make to the dataset (such as posting changes or deleting records) are cached instead of being written to the dataset. You can call ApplyUpdates to apply all the cached updates en masse. Setting CachedUpdates to False while there are pending cached updates will discard them.


See also

ApplyUpdates method

CancelUpdates method

CommitUpdates method

RevertRecord method

UpdateRecordTypes property

UpdateStatus method


Calculated property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField, components

Declaration

property Calculated: Boolean;

Description

Calculated is True if the value of the field is calculated by the OnCalcFields event handler. Calculated fields can be updated with the Fields Editor, but are not stored in or retrieved from the physical tables underlying a dataset. Instead they are calculated for each record in the table by the dataset's OnCalcFields event handler, which typically uses expressions involving values from other fields in the record to generate a value for each calculated field. For example, a table might have non-calculated fields for Quantity and UnitPrice, and a calculated field for ExtendedPrice, which would be calculated by multiplying the values of the Quantity and UnitPrice fields. Calculated fields are also useful for performing lookups in other tables. For example, a part number can be used to retrieve a part description for display in an invoice line item.


Cancel method

See also	Example

Applies to

TTable, TQuery, TStoredProc, components

Declaration

procedure Cancel;

Description

The Cancel method returns the dataset to Browse state and discards any changes to the current record.


Example

This example prompts the user to confirm changes to a record; if the user clicks Yes, the record is posted to the table, otherwise the changes are cancelled.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if MessageDlg('Update Record?', mtConfirmation, [mbYes, mbNo], 0) =

       mrYes then

    Table1.Post

  else

    Table1.Cancel;

end;


See also

Append method

Insert method

Post method


Cancel property

See also	Example

Applies to

TBitBtn, TButton components

Declaration

property Cancel: Boolean;

Description

The Cancel property indicates whether a button or a bitmap button is a Cancel button. If Cancel is True, any time the user presses Esc, the OnClick event handler for the button executes. Although your application can have more than one button designated as a Cancel button, the form calls the OnClick event handler only for the first button in the tab order that is visible.


Example

The following code designates a button called Button1 as a Cancel button:

Button1.Cancel := True;


See also

Default property

OnClick event


CancelCurrentUpdate method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function CancelCurrentUpdate: Boolean;

Description

CancelCurrentUpdate discards the most recently posted cached update. It returns True if successful, and False if not.


See also

ApplyUpdates method

CancelUpdates method

UpdateStatus method

UpdateRecordTypes property


CancelEdit method

See also	Example

Applies to

TListItem object

Declaration

procedure CancelEdit;

Description

The CancelEdit method ends the editing of an item's (TListItem object) label in a list view.


Example

The following example takes the selected item out of editing mode.

ListView1.Selected.CancelEdit;


See also

OnEditing event

OnEdited event

Caption property


CancelRange method

Applies to

TTable component

Declaration

procedure CancelRange;

Description

The CancelRange method removes any range limitations for the TTable which were previously established by calling the ApplyRange or SetRange methods.


CancelUpdates method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure CancelUpdates;

Description

CancelUpdates discards all pending cached updates. CancelUpdates is always successful, so no errors will occur. The dataset returns to the state it was at before cached updates were enabled.


See also

ApplyUpdates method

RevertRecord method

UpdateStatus method

UpdateRecordTypes property


CanFocus method

See also	Example

Applies to

All controls

Declaration

function CanFocus: Boolean;

Description

The CanFocus method determines whether a control can receive focus. CanFocus returns True if both the control and its parent(s) have their Visible and Enabled properties set to True. If all the Visible and Enabled properties of the control and the components from which the control descends are not True, then CanFocus returns False.


Example

This example uses a group box, a label, and a button on a form. The group box contains a check box. When the application runs, the group box is disabled (Enabled is set to False). Because the group box is the parent of the check box, the user can never tab to the check box. When the user clicks the button, the caption of the label reports that the check box can not receive the input focus:

procedure TForm1.FormCreate(Sender: TObject);

begin

  GroupBox1.Enabled := True;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  if CheckBox1.CanFocus then

    Label1.Caption := 'The check box can focus'

  else

    Label1.Caption := 'The check box cannot focus';

end;


See also

Parent property


CanModify property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStoredProc, TStringField, TQuery, TTable, TTimeField, TVarBytesField, TWordField components

Description

CanModify Property for Tables, Queries, Stored Procedures

CanModify Property for Field Components


CanModify property

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property CanModify: Boolean;

Description

Run-time and read only. CanModify specifies whether an application can modify the data in a dataset. When CanModify is False, the dataset is read-only, and cannot be put into Edit or Insert state. When CanModify is True, the dataset can enter Edit or Insert state.

Even if CanModify is True, it is not a guarantee that a user will be able to insert or update records in a table. Other factors may come in to play, for example, SQL access privileges.

TTable has a ReadOnly property that requests write privileges when set to False. When ReadOnly is True, CanModify will automatically be set to False. When ReadOnly is False, CanModify will be True if the database allows read and write privileges for the dataset and the underlying table.

CanModify will be True for queries only if you use cached updates or set RequestLive to True before opening the query, and if the Borland Database Engine (BDE) can actually return a live result set. If it can't, or if RequestLive is False (the default), CanModify will be False. If you set CachedUpdates to True and create an OnUpdateRecord event handler or assign a TUpdateSQL component to the query's UpdateObject property, CanModify will be True. Cached updates let you perform updates to a query that would otherwise be read-only.


Example

This example checks the CanModify property of a table whenever the form is activated and provides a message on the form's status bar.

procedure TForm1.FormActivate(Sender: TObject);

begin

   if Table1.CanModify then

      StatusBar1.SimpleText := 'You can make changes to the table'

   else

      StatusBar1.SimpleText := 'You can''t make changes to the table';

end;


See also

Active property

RequestLive property


CanModify property

See also

Applies to

All field components

Declaration

property CanModify: Boolean;

Description

Run-time and read only. Specifies if a field can be modified for any reason, such as during a SetKey operation. CanModify is True if the value of the field can be modified. If the ReadOnly property of the field is True, or the ReadOnly property of the dataset is True, then CanModify is False.


See also

DataSet property


Canvas property

Applies to

TBitmap, TComboBox, TDBComboBox, TDBGrid, TDBListBox, TDirectoryListBox, TDrawGrid, TFileListBox, TForm,THeaderControl, TImage, TListBox, TOutline, TPaintBox, TPrinter,TStatusBar,TStringGrid components

Description

Run-time only. The Canvas property provides a graphical area on which you can draw at run time.

Canvas property for forms and paint boxes

Canvas property for list box, combo box, and outline components

Canvas property for grids

Canvas property for printer objects

Canvas property for bitmap objects

Canvas property for status bar components

Canvas property for header control components


Canvas property for forms and paint boxes
Canvas property

See also	Example

Applies to

TForm, TImage, TPaintBox components

Declaration

property Canvas: TCanvas;

Description

Run-time only. The Canvas property gives you access to a drawing surface that you can use when implementing a handler for the OnPaint event of a form, an image, or a paint box.

The Canvas property of an image or a form is read only.


Example

The following example paints a cross-hatched ellipse onto Image1 which is a TImage on the form when the user clicks on Button1.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with Image1 do begin

    Canvas.brush.color := clBlack;

    Canvas.brush.style := bsDiagCross;

    Canvas.Ellipse(0, 0, Image1.Width, Image1.Height);

  end;

end;


See also

Drawing Graphics at Run Time


Canvas Property for List Boxes
Canvas property

See also	Example

Applies to

TComboBox, TDirectoryListBox, TFileListBox, TListBox, TOutline components

Declaration

property Canvas: TCanvas;

Description

Run-time and read only. The Canvas property gives you access to a drawing surface that you can use when implementing a handler for the OnDrawItem event of an owner-draw list box, combo box, or outline control.


Example

The following code draws a graphic stored in the Objects property of the Items list of ListBox1. This code should be attached to the OnDrawItem event handler of ListBox1, and the Style property of ListBox1 should be lbOwnerDrawFixed.

procedure TForm1.ListBox1DrawItem(Control: TWinControl; Index: Integer;

  Rect: TRect; State: TOwnerDrawState);

var

  SourceRect: TRect;

begin

  SourceRect.Top := 0;

  SourceRect.Left := 0;

  SourceRect.Bottom := TBitmap(ListBox1.Items.Objects[Index]).Height;

  SourceRect.Right := TBitmap(ListBox1.Items.Objects[Index]).Width;

  ListBox1.Canvas.CopyRect(Rect, TBitmap(ListBox1.Items.Objects[Index]).Canvas,

    SourceRect);

end;

The following code draws a graphic stored in the Data property of the Items list of Outline1. This code should be attached to the OnDrawItem event handler of Outline1, and the Style property of Outline1 should be otOwnerDraw.

procedure TForm1.Outline1DrawItem(Control: TWinControl; Index: Integer;

  Rect: TRect; State: TOwnerDrawState);

var

  SourceRect: TRect;

begin

  SourceRect.Top := 0;

  SourceRect.Left := 0;

  SourceRect.Bottom := TBitmap(Outline1.Items[Index].Data).Height;

  SourceRect.Right := TBitmap(Outline1.Items[Index].Data).Width;

  Outline1.Canvas.CopyRect(Rect, TBitmap(Outline1.Items[Index].Data).Canvas,

    SourceRect);

end;


See also

ItemHeight property

OnDrawCell event

OnDrawDataCell event

OnDrawItem event

OnPaint event


Canvas Property for Forms and Grids
Canvas property

Applies to

TDBGrid, TDrawGrid, TStringGrid, TDBCtrlGrid components

Declaration

property Canvas: TCanvas;

Description

Run-time and read only. The Canvas property gives you access to a drawing surface that you can use when implementing a handler for the OnDrawCell or OnDrawDataCell event of a grid control.


Canvas Property for Printer Objects
Canvas property

See also	Example

Applies to

TPrinter objects

Declaration

property Canvas: TCanvas;

Description

Run-time only and read only. The Canvas property for a printer object represents the surface of the currently printing page.

Note:	Some printers do not support graphics. Therefore, the Draw, StretchDraw, or CopyRect methods might fail on these printers.


Example

The following code prints the text 'Hello, world!':

Printer.BeginDoc;

Printer.Canvas.TextOut(0, 0, 'Hello, world');

Pritner.EndDoc;


See also

Brush property

Font property

Pen property

TextOut method


Canvas property

See also	Example

Applies to

TBitmap object

Declaration

property Canvas: TCanvas;

Description

Run-time and read only. The Canvas property gives you access to a drawing surface that represents the bitmap. When you draw on the canvas you are in effect modifying the underlying bitmap.


Example

The following example converts an icon to a bitmap for use as the bit button's glyph when the user clicks on Button1. Since it uses the ExtractIcon Windows API function, ShellApi must be added to the uses clause of the unit.

procedure TForm1.Button1Click(Sender: TObject);

var

  Picture1 : TPicture;

  Icon1 : TIcon;

begin

  Icon1 := TIcon.Create;

  Icon1.Handle := ExtractIcon(HInstance, 'chemical.ico', 0);

  Picture1 := TPicture.Create;

  Picture1.Icon := Icon1;

  BitBtn1.Glyph := TBitmap.Create;

  with BitBtn1.Glyph do

  begin

    width := Icon1.Width;

    Height := Icon1.Height;

    Canvas.Draw(0, 0, Picture1.Icon);

  end;

end;


See also

Draw method


Canvas property for status bars
Canvas property

See also	Example

Applies to

TStatusBar component

Declaration

property Canvas: TCanvas;

Description

Run-time and read only. The Canvas property provides access to the drawing surface (device context) of the status bar when the Style property of any of its panels is set to OwnerDraw. Put the code to handle drawing within the status bar in the OnDrawPanel event handler of the status bar.


Example

The following code draws each panel adding text and icons stored in ImageList1. The image list contains as many icons as there are header sections.

procedure TForm1.StatusBar1DrawPanel(StatusBar: TStatusBar;

  Panel: TStatusPanel; const Rect: TRect);

begin

with StatusBar1.Canvas do

  begin

    Brush.Color := clRed;

    FillRect(Rect);

    Font.Color := clYellow;

    ImageList1.Draw(StatusBar1.Canvas,Rect.Left,Rect.Top,Panel.Index);

    TextOut(Rect.left + 30, Rect.top + 2, 'Status Bar');

  end;

end;


See also

OnDrawPanel event


Canvas property for header controls
Canvas property

See also	Example

Applies to

THeaderControl component

Declaration

property Canvas: TCanvas;

Description

Run-time and read only. The Canvas property gives you access to a drawing surface (device context) that you can use when implementing a handler for the OnDrawSection event of an owner-draw header control.


Example

The following code draws each header section adding text for a title and icons stored in ImageList1. The image list contains as many icons as there are header sections.

procedure TForm1.HeaderControl1DrawSection(HeaderControl: THeaderControl;

  Section: THeaderSection; const Rect: TRect; Pressed: Boolean);

begin

  with HeaderControl1.Canvas do

  begin

    Brush.Color := clRed;

    FillRect(Rect);

    Font.Color := clYellow;

    TextOut(Rect.left + 30, Rect.top + 2, 'Header Control');

    ImageList1.Draw(HeaderControl1.Canvas,Rect.Left,Rect.Top,Section.Index);

  end;

end;


See also

OnDrawSection event


Capabilities property

See also	Example

Applies to

TMediaPlayer component

Declaration

property Capabilities: TMPDevCapsSet;

Description

Run-time and read only. The Capabilities property determines the capabilities of the open multimedia device.

The various capabilities specified in Capabilities are determined when the device is opened with the Open method. The following table lists the capabilities a device can have:

Value	Capability

mpCanEject	Can eject media

mpCanPlay	Can play media

mpCanRecord	Can record media

mpCanStep	Can step forward or backward within media

mpUsesWindows	Uses a window for displaying output

Note:	Currently, there is no way to check whether a device can step forward or backward. Capabilities includes mpCanStep only if the device type (specified in the DeviceType property) is Animation, AVI Video, Digital Video, Overlay, or VCR.


Example

The following code determines whether the device opened by the media player control MediaPlayer1 uses a window to display output. If so, the output displays in a form named Form2:

if mpUsesWindows in MediaPlayer1.Capabilities then

  MediaPlayer1.Display := Form2;


See also

Back method

Display property

Eject method

Play method

StartRecording method

Step method


Capacity property

See also	Example

Applies to

TList object

Declaration

property Capacity: Integer;

Description

Run time only. The Capacity property contains the allocated size of the array of pointers maintained by a TList object. This is different from the Count property, which contains the number of entries that are actually in use. The value of the Capacity property is always greater than or equal to the value of the Count property.

When setting the Capacity property, an EOutOfMemory exception occurs if there is not enough memory to expand the list to its new size.

When an element is added to a list whose Capacity and Count are equal (indicating that all allocated entries are in use), the Capacity is automatically increased by 16 elements. In situations where you are going to be adding a known number of elements to a list, you can reduce memory reallocations by first increasing the list's capacity. For example,

List.Clear;

List.Capacity := Count;

for I := 1 to Count do List.Add(...);

The assignment to Capacity before the for loop ensures that each of the following Add operations doesn't cause the list to be reallocated, which in turn means that the Add operations are guaranteed to never raise an exception.


Example

The following code sets the Capacity of List1 to 5.

List1.Capacity := 5;


See also

Count property

Expand method

Items property

Pack method


Caption property

Applies to

TColumnTitle, TListColumn objects; TBitBtn, TButton, TCheckBox, TDBCheckBox, TDBRadioGroup, TForm, TGroupBox, TLabel, TMenuItem, TPanel, TRadioButton, TSpeedButton, TTabSheet components

Description

Caption Property for Forms

Caption Property for All Other Controls


Caption Property for Forms
Caption property

See also	Example

Applies to

TForm component

Declaration

property Caption: string;

Description

The Caption property is the text that appears in the form's title bar; this text also appears as the icon label when the form is minimized.


Example

The following code creates a caption that says "Hello, World!" on a form called MyForm:

MyForm.Caption := 'Hello, World!';


See also

BorderStyle property


Caption Property for Non-Form Components
Caption property

See also	Example

Applies to

All controls; TMenuItem component

Declaration

property Caption: string;

Description

For components other than forms, the Caption property contains the text string that labels the component. To underline a character in a string, include an ampersand (&) before the character. This type of character is called an accelerator character. The user can then select the control or menu item by pressing Alt while typing the underlined character. The default value is the name of the component.

For menu items, you can use the Caption property to include a line that separates the menu into parts. Specify a hyphen character (-) as the value of Caption for the menu item.

The Caption property of a data grid is available at run time only.


Example

This code changes the caption of a group box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  GroupBox1.Caption := 'Fancy options';

end;


See also

FocusControl property

ShowAccelChar property

Text property


Cascade method

See also	Example

Applies to

TForm component

Declaration

procedure Cascade;

Description

The Cascade method rearranges the child forms in your application so they overlap. The top of each form remains visible so that you can easily select one of the forms. The Cascade method applies only to MDI parent forms (with a FormStyle property value of fsMDIForm).


Example

This code arranges all MDI children of the current MDI parent form in a cascade pattern when the user chooses the Cascade menu command:

  procedure TForm1.Cascade1Click(Sender: TObject);

  begin

    Cascade;

  end;


See also

ArrangeIcons method

Next method

Previous method

Tile method


CellRect method

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

function CellRect(ACol, ARow: Longint): TRect;

Description

The CellRect method creates a rectangle of type TRect for the cell defined by the column ACol and the row ARow. If the cell indicated by ACol and ARow is not visible, CellRect returns an empty rectangle.


Example

This example uses a string grid, four labels, and a button on a form. When the user clicks the button, the coordinates of the cell in the second column and first row appear in the label captions.

procedure TForm1.Button1Click(Sender: TObject);

var

  Rectangle: TRect;

begin

  Rectangle := StringGrid1.CellRect(3, 2);

  Label1.Caption := IntToStr(Rectangle.Top) + ' is the top';

  Label2.Caption := IntToStr(Rectangle.Bottom) + ' is the bottom';

  Label3.Caption := IntToStr(Rectangle.Left) + ' is the left side';

  Label4.Caption := IntToStr(Rectangle.Right) + ' is the right side';

end;


See also

MouseToCell method


Cells property

See also	Example

Applies to

TStringGrid component

Declaration

property Cells[ACol, ARow: Integer]: string;

Description

Run-time only. The Cells property is an array of strings, one string for each cell in the grid. Use the Cells property to access a string within a particular cell. ACol is the column coordinate of the cell, and ARow is the row coordinate of the cell. The first row is row zero, and the first column is column zero.

The ColCount and RowCount property values define the size of the array of strings.


Example

This code fills each cell of a grid with the same string.

procedure TForm1.Button1Click(Sender: TObject);

var

  I, J: Integer;

begin

  with StringGrid1 do

    for I := 0 to ColCount - 1 do

      for J:= 0 to RowCount - 1 do

        Cells[I,J] := 'Delphi';

end;


See also

Cols property

Objects property

Rows property


Center property

See also	Example

Applies to

TDBImage, TImage components

Declaration

property Center: Boolean;

Description

The Center property determines whether an image is centered in the image control. If Center is True, the image is centered. If Center is False, the image aligns with the top left corner of the control. The default value is True.


Example

The following code centers the image in Image1 when the user checks CheckBox1:

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  Image1.Center := CheckBox1.Checked;

end;


See also

AutoSize property

Stretch property


ChangedCount property

See also	Example

Applies to

TBatchMove component

Declaration

property ChangedCount: Longint;

Description

Run-time and read only. ChangedCount is the number of records added to the table specified by ChangedTableName. If ChangedTableName is not specified, the count is still valid.


Example

with BatchMove1 do

  begin

  Execute;

  if ChangedCount <> Source.RecordCount then { something went wrong };

  end;


See also

ChangedTableName property


ChangedTableName property

Example

Applies to

TBatchMove component

Declaration

property ChangedTableName: TFileName;

Description

ChangedTableName, if specified, creates a local (Paradox) table containing all records in the destination table that changed as a result of the batch operation. The number of records placed in the new table is reported in the ChangedCount property.


Example

BatchMove1.ChangedTableName := 'oldrecs.db';


ChangeLevelBy method

See also	Example

Applies to

TOutlineNode object

Declaration

procedure ChangeLevelBy(Value: TChangeRange);

Description

The ChangeLevelBy method changes the level of an outline item. Specify a Value parameter value of -1 to move up (toward the root) one level. Specify a Value parameter value of 1 to move down (away from the root) one level.

When moving up one level, an item becomes the next sibling of its former parent. When moving down one level, an item becomes the last child of its former prior sibling. Therefore, you can not change the level of the first item in the outline, as it has no parent or prior sibling. Also, you can not move items that are already on the first level up one level.

ChangeLevelBy modifies the value of the Level property to reflect the new level. You can only move an item up or down one level at a time.


Example

Attach the following code to the OnClick event handlers of two buttons to allow the user to move the selected outline item up or down. The code for UpBtn checks to see if the selected item is not already on the first level before moving it up. The code for DownBtn checks to see if the selected item has a prior sibling before moving it down.

procedure TForm1.UpBtnClick(Sender: TObject);

begin

  with Outline1[Outline1.SelectedItem] do

    if Level > 1 then ChangeLevelBy(-1);

end;

procedure TForm1.DownBtnClick(Sender: TObject);

begin

  with Outline1[Outline1.SelectedItem] do

    if Outline1[Parent.GetPrevChild(Index)] <> -1 then

      ChangeLevelBy(1);

end;


See also

Level property

MoveTo method


CharCase property

Example

Applies to

TDBEdit, TEdit, TMaskEdit components

Declaration

property CharCase: TEditCharCase;

Description

The CharCase property determines the case of the Text property of the edit box. These are the possible values:

Value	Meaning

ecLowerCase	The text of the edit box displays in lowercase

ecNormal	The text of the edit box displays in mixed case

ecUpperCase	The text of the edit box displays in uppercase

If the user tries to enter a different case than the current value of CharCase, the characters the user enters appear in the case specified by CharCase. For example, if the value of CharCase is ecLowerCase, only lowercase characters appear in the edit box, even if the user tries to enter uppercase characters.


Example

This example uses an edit box and group box containing three radio buttons. When the user selects the first radio button, the text in the edit box becomes lowercase, and any text the user types in the edit box also appears in lowercase. When the user selects the second radio button, the text in the edit box becomes uppercase, and any text the user types in the edit box also appears in uppercase. When the user selects the third radio button, the text in the edit box remains unchanged, but the user can type using either upper- or lowercase characters:

procedure TForm1.RadioButton1Click(Sender: TObject);

begin

  Edit1.CharCase := ecLowerCase;

end;

procedure TForm1.RadioButton2Click(Sender: TObject);

begin

  Edit1.CharCase := ecUpperCase;

end;

procedure TForm1.RadioButton3Click(Sender: TObject);

begin

  Edit1.CharCase := ecNormal;

end;


Check procedure

Unit

DB

Declaration

procedure Check(Status: Integer);

Description

The Check procedure tests Status for a nonzero value and calls DbiError passing Status. This is useful for checking for and reporting errors when calling the BDE (Borland Database Engine) directly.


CheckBrowseMode method

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure CheckBrowseMode;

Description

The CheckBrowseMode method verifies that the dataset is open and has no pending changes. If the dataset's State property is dsEdit, dsInsert, or dsSetKey, the Post method is called to post any pending changes. If the dataset is closed, an EDataBaseError exception will be raised.


Checked property

See also	Example

Applies to

TCheckBox, TDBCheckBox, TMenuItem, TRadioButton components

Declaration

property Checked: Boolean;

Description

Run-time only. The Checked property determines whether an option is selected. These are the possible values:

Component	Value	Meaning

Check box	True	A check mark appears in the check box, indicating the option is selected.

False	No check mark appears, indicating the option is not selected. The value of the Checked property is False if the State of the check box is cbGrayed (the check box is grayed) or cbUnChecked (the check box is unchecked).

Radio button	True	A black circle appears in the radio button, indicating that the option is selected.

False	No black circle appears in the radio button, indicating the option is not selected.

Menu item	True	A check mark appears next to the menu item in the menu, indicating the item is selected.

False	No check mark appears, indicating the item is not selected.


Example

This example fills in a radio button at run time:

RadioButton1.Checked := True;

This example uses a main menu component that contains a menu item named SnapToGrid1 on a form. When the user chooses the Snap To Grid command, a check mark appears next to the command. When the user chooses the Snap To Grid command again, the check marks disappears:

procedure TForm1.SnapToGrid1Click(Sender: TObject);

begin

  SnapToGrid1.Checked := not SnapToGrid1.Checked;

end;


See also

AllowGrayed property

State property


CheckOpen method

Applies to

TTable, TQuery, TStoredProc components

Declaration

function CheckOpen(Status: DBIResult): Boolean;

Description

The CheckOpen method is useful if you use low-level calls to the Borland Database Engine (BDE). It verifies that a BDE result code indicates a successful opening of a table, or, if it indicates a problem because of a missing password, it automatically invokes the password dialog box to get the password from the user.


Chord method

See also	Example

Applies to

TCanvas object

Declaration

procedure Chord(X1, Y1, X2, Y2, X3, Y3, X4, Y4: Integer);

Description

The Chord method draws a line on the canvas connecting two points on the ellipse bounded by the specified rectangle. The screen pixel coordinates (X1, Y1) and (X2, Y2) define the enclosing rectangle for the chord. (X3,Y3) is the starting point for the line, and (X4, Y4) is the ending point.


Example

This code draws a chord on the top of an ellipse bounded by the current window:

var

  R: TRect;

begin

  R := GetClientRect;     {Gets the rectangular coordinates of the current window}

  Canvas.Chord(R.Left, R.Top, R.Right, R.Bottom, R.Right, R.Top, R.Left, R.Top);

end;


See also

Arc method

Draw method

Ellipse method

Pie method


ClassName method

See also	Example

Applies to

All objects and components

Declaration

class function ClassName: string;

Description

The ClassName function returns the name of an object or a class. For example, TButton.ClassName returns the string 'TButton'.

The name returned by ClassName is the name of the actual class of the object, as opposed to the object's declared class. For example, the following code assigns 'TButton' to S, not 'TObject':

var

  MyObject: TObject;

  S: string;

begin

  MyObject := TButton.Create(Application);

  S := MyObject.ClassName;

  ...

  MyObject.Free;

end;


Example

This example uses a button, a label, a list box, a check box, and an edit box on a form. When the user clicks one of the controls, the name of the control's class appears in the edit box.

procedure FindClassName(AControl:TObject);

begin

  Form1.Edit1.Text := AControl.ClassName;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  FindClassName(Button1);

end;

procedure TForm1.Label1Click(Sender: TObject);

begin

  FindClassName(Label1);

end;

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  FindClassName(CheckBox1);

end;

procedure TForm1.ListBox1Click(Sender: TObject);

begin

  FindClassName(ListBox1);

end;


See also

ClassParent method

ClassType method


ClassParent method

See also	Example

Applies to

All objects and components

Declaration

class function ClassParent: TClass;

Description

The ClassParent method returns the parent class of an object or a class. The returned value is the immediate ancestor of the object or class. For example, TScrollBar. ClassParent returns TWinControl as TScrollBar is derived from TWinControl.

Note that TObject.ClassParent returns nil because TObject has no parent.


Example

This code example uses a button and a list box on a form. When the user clicks the button, the name of the button's class and the names of its parent classes are added to the list box.

procedure TForm1.Button1Click(Sender: TObject);

var

  ClassRef: TClass;

begin

  ListBox1.Clear;

  ClassRef := Sender.ClassType;

  while ClassRef <> nil do

  begin

    ListBox1.Items.Add(ClassRef.ClassName);

    ClassRef := ClassRef.ClassParent;

  end;

end;

The list box contains the following strings after the user clicks the button:

TButton

TButtonControl

TWinControl

TControl

TComponent

TPersistent

TObject


See also

ClassName method

ClassType method


ClassType method

See also	Example

Applies to

All objects and components

Declaration

function ClassType: TClass;

Description

The ClassType function returns the class of an object.


Example

This example uses a button and a label on a form. When the user clicks the button, the type of the button component (TButton) appears in the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

var

  ButtonClassType: TClass;

begin

  ButtonClassType := Button1.ClassType;

  Label1.Caption := ButtonClassType.ClassName;

end;


See also

ClassName method

ClassParent method


Clear method

Applies to

TClipboard, TCollection, TFieldDefs, THeaderSections, TIndexDefs, TList, TListItems, TParam, TParams, TStatusPanels, TStringList, TStrings, TDBGridColumns, TListColumns objects; TBCDField, TBlobField, TBooleanField, TBytesField, TComboBox, TDBComboBox, TCurrencyField, TDateField, TDateTimeField, TDBEdit, TDBListBox, TDBMemo, TDirectoryListBox, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TFloatField, TGraphicField, TImageList, TIndexDefs, TIntegerField, TListBox, TMaskEdit, TMemo, TMemoField, TOutline, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

Clear Method for Image List Components

Clear Method for Field Components

Clear Method for Field Definitions

Clear Method for Index Definitions

Clear Method for Index Definition Objects

Clear Method for TParam Objects

Clear Method for TParams Objects

Clear Method for Other Objects and Components


Add method for image list objects
Clear method

See also

Applies to

TImageList object

Declaration

procedure Clear;

Description

The Clear method clears all images from the image list.


See also

Delete method


Add method for image list objects
Clear method

Example

Applies to

TParams object

Declaration

procedure Clear;

Description

The Clear method deletes all parameter information from Items.


Example

Params1.Clear;


Add method for image list objects
Clear method

Example

Applies to

TParam object

Declaration

procedure Clear;

Description

The Clear method sets the parameter to NULL, erasing all previously assigned data. The Name, DataType and ParamType properties are not altered.


Example

This example clears the CustNo parameter for Query 1.

Query1.ParamByName('CustNo').Clear;


Add method for image list objects
Clear method

Applies to

TIndexDef object

Declaration

procedure Clear;

Description

The Clear method frees all of the entries in the Items property.


Add method for image list objects
Clear method

Applies to

TFieldDefs object

Declaration

procedure Clear;

Description

The Clear method frees all of the entries in the Items property, effectively removing all TFieldDef objects from TFieldDefs.


Add method for image list objects
Clear method

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

procedure Clear;

Description

Clear sets the value of the field to NULL.


Add method for image list objects
Clear method

See also	Example

Applies to

TClipboard, TCollection, TList, TListItems, TStringList, TStrings, TDBGridColumns, TListColumns objects; TComboBox, TDBComboBox, TDBEdit, TDBListBox, TDBMemo, TDirectoryListBox, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TListBox, TMaskEdit, TMemo, TOutline components

Declaration

procedure Clear;

Description

The Clear method deletes all text from the control, or, in the case of collection, list and string objects or outlines, deletes all items. For the Clipboard object, Clear deletes the contents of the Clipboard; this happens automatically each time data is added to the Clipboard (cut and copy operations).


Example

The following code removes the text from an edit box control called NameField:

NameField.Clear;

This example uses a list box and a button on a form. When the form is created, strings are added to the list box. When the user clicks the button, all the strings contained in the Items property, a TStrings object, are cleared.

procedure TForm1.FormCreate(Sender: TObject);

begin

  ListBox1.Items.Add('One');

  ListBox1.Items.Add('Two');

  ListBox1.Items.Add('Three');

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Clear;

end;


See also

CopyToClipboard method

CutToClipboard method

Items property

Pack method

PasteFromClipboard method

Text property

Strings property


ClearFields method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure ClearFields;

Description

The ClearFields method clears all fields of the current record to their default values (normally NULL.) The dataset must be in Edit state or an EDatabaseError exception will be raised.


See also

Edit method

State property

TField component


ClearSelection method

See also	Example

Applies to

TDBEdit, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

procedure ClearSelection;

Description

The ClearSelection method deletes text selected in an edit box or memo control. If no text is selected in the control when ClearSelection is called, nothing happens.


Example

This code uses a memo control named MyMemo and a button on a form. When the user clicks the button, the text the user selected in the memo control is deleted.

procedure TForm1.Button1Click(Sender: TObject);

begin

  MyMemo.ClearSelection;

end;


See also

Clear method

CopyToClipboard method

CutToClipboard method

PasteFromClipboard method


Click method

Applies to

TBitBtn, TButton, TDBNavigator, TMenuItem, TSpeedButton components

Description

The Click method simulates a mouse click on a component.

Click Method for Menu Items and Buttons

Click Method for Database Navigators


Click method

See also	Example

Applies to

TBitBtn, TButton, TMenuItem, TSpeedButton components

Declaration

procedure Click;

Description

The Click method simulates a mouse click, as if the user had clicked a menu item or button, executing any code attached to the OnClick event.


Example

This example uses a main menu component and a button named Print. The main menu component has a Print1 menu item on it. When the user clicks the button, the code attached to the OnClick event of the Print1 menu item runs.

procedure TForm1.PrintClick(Sender: TObject);

begin

  Print1.Click;

end;


See also

OnClick event


Click method

Example

Applies to

TDBNavigator component

Declaration

procedure Click(Button: TNavigateBtn);

Description

The Click method simulates a mouse click, as if the user had clicked a button on the database navigator, executing any code attached to the OnClick event. Specify which button the Click method applies to using the Button parameter.


Example

The following code simulates a click on the Next button of DBNavigator1.

DBNavigator1.Click(nbNext);


ClientHandle property

Applies to

TForm component

Declaration

property ClientHandle: HWND;

Description

Read only. The ClientHandle property value is the handle to the internal MDI (Multiple Document Interface) client window. The property value is meaningful only if the form is an MDI parent form with its FormStyle property set to fsMDIForm.


ClientHeight property

See also	Example

Applies to

All controls; TForm component

Declaration

property ClientHeight: Integer;

Description

The ClientHeight property is the height of the control's client area in pixels. For most controls, ClientHeight is exactly the same as Height. For forms, however, ClientHeight represents the height of the usable area inside the form's frame.

ClientHeight is a run-time only property for all controls except forms.


Example

This example reduces the height of the form's client area by half when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form1.ClientHeight := Form1.ClientHeight div 2;

end;

Note that only the client area is halved, not the entire form.


See also

ClientWidth property

Height property


ClientOrigin property

See also	Example

Applies to

All controls; TForm component

Declaration

property ClientOrigin: TPoint;

Description

Run-time and read only. The ClientOrigin property is used to determine the screen coordinates (in pixels) of the top left corner of a control or form client area. ClientOrigin returns X and Y coordinates in a record of type Point.


Example

This example displays the Y screen coordinate of the top right corner of the Button1 button client area:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.Text := IntToStr(Button1.ClientOrigin.Y);

end;


See also

ClientRect property


ClientRect property

See also	Example

Applies to

All controls; TForm component

Declaration

property ClientRect: TRect;

Description

Run-time and read only. The ClientRect property is used to determine the size (in pixels) of a control or form client area. ClientRect returns the Top, Bottom, Left, and Right coordinates in one record of type TRect. ClientRect is equivalent to Rect(0,0,ClientWidth, ClientHeight).


Example

The following code uses ClientRect to find and draw a line from the top left to the bottom right of the current form:

with ClientRect do

begin

  Canvas.MoveTo(Left,Top);

  Canvas.LineTo(Right, Bottom);

end;


See also

ClientOrigin property


ClientToScreen method

See also	Example

Applies to

All controls

Declaration

function ClientToScreen(Point: TPoint): TPoint;

Description

The ClientToScreen method translates the given point from client area coordinates to global screen coordinates. In client area coordinates (0, 0) corresponds to the upper left corner of the control's client area. In screen coordinates (0, 0) corresponds to the upper left corner of the screen.

Using the ClientToScreen and ScreenToClient methods you can convert from one control's coordinate system to another control's coordinate system. For example,

P := TargetControl.ScreenToClient(SourceControl.ClientToScreen(P));

which converts P from coordinates in SourceControl to coordinates in TargetControl.


Example

This example uses two edit boxes on a form. When the user clicks a point on the form, the X screen coordinate appears in Edit1, and the Y screen coordinate appears in Edit2.

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

var

  P, Q : TPoint;

begin

  P.X := X;                          { P is the TPoint record for the form}

  P.Y := Y;

  Q := ClientToScreen(P);            { Q is the TPoint for the screen }

  Edit1.Text := IntToStr(Q.X) + ' is the X screen coordinate';

  Edit2.Text := IntToStr(Q.Y) + ' is the Y screen coordinate';

end;


See also

ScreenToClient method


ClientWidth property

See also	Example

Applies to

All controls

Declaration

property ClientWidth: Integer;

Description

The ClientWidth property is the horizontal size of the control's client area in pixels. For most controls, ClientWidth is exactly the same as Width. For forms, however, ClientWidth represents the width of the usable area inside the form's frame.

ClientWidth is a run-time only property for all components except forms.


Example

This example uses a button on a form. Each time the user clicks the button, the button grows 10 pixels wider.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.ClientWidth := Button1.ClientWidth + 10;

end;


See also

ClientHeight property

Width property


Clipboard function

Unit

Clipbrd

Declaration

function Clipboard: TClipboard;

Description

The Clipboard function creates an instance of a global TClipboard object. Use Clipboard when you want to use the TClipboard object.

Clipboard is declared in the Clipbrd unit. Whenever you use Clipboard and the TClipboard object you must add Clipbrd to the uses clause of your unit.


ClipRect property

See also

Applies to

TCanvas object

Declaration

property ClipRect: TRect;

Description

Read only. The ClipRect property specifies a bounding clipping rectangle. The rectangle specified by ClipRect defines the outer boundaries of the drawing area of the canvas. Any drawing that occurs at coordinates outside the ClipRect are clipped and don't appear on screen. For example, the ClipRect of the canvas of a form is the same size as the client area of the form.

When handling an OnPaint event, the Canvas' ClipRect property is set to the rectangle that needs to be painted. OnPaint routines can use this value to optimize the painting and speed the overall performance of the application.


See also

ClientRect property


Close method

Applies to

TClipboard object; TDataBase, TForm, TMediaPlayer, TQuery, TSession, TStoredProc, TTable, TOleContainer components

Description

The Close method closes an object or device.

Close for Forms

Close for Clipboard Objects

Close for Media Player Controls

Close for Database Components

Close for Queries, Tables, and Stored Procedures

Close for TSession Components

Close for TOleContainer components


Close method

See also

Applies to

TOleContainer component

Declaration

procedure Close

Description

Deactivates the OLE object and terminates its server application, but doesn't remove it from the container. Any changes the user made to the OLE object are automatically saved. There must be an OLE object in the container before calling Close. After calling Close, the container's State property is osLoaded.


See also

State property


Close method

See also	Example

Applies to

TForm component

Declaration

procedure Close;

Description

The Close method closes a form. Calling the Close method on a form corresponds to the user selecting the Close menu item on the form's System menu. The Close method first calls the CloseQuery method to determine if the form can close. If CloseQuery returns False, the close operation is aborted. Otherwise, if CloseQuery returns True, the code attached to the OnClose event is executed. The CloseAction parameter of the OnClose event controls how the form is actually closed.

Note:	When the main form of the application is closed, the application terminates.


Example

The following method closes a form when a button called Done is clicked:

procedure TForm1.DoneButtonClick(Sender: TObject);

begin

  Close;

end;


See also

Hide method


Close method

See also	Example

Applies to

TClipboard object

Declaration

procedure Close;

Description

For Clipboard objects, Close closes the Clipboard if it is open. The Clipboard can be opened with a call to Open multiple times before being closed. Because the Clipboard object counts each time it is opened, your application must close it the same number of times it was opened before the Clipboard is actually closed.


Example

The following code closes the Clipboard:

Clipboard.Close;


See also

Clipboard function


Close method

See also

Applies to

TMediaPlayer component

Declaration

procedure Close;

Description

The Close method closes the open multimedia device.

Upon completion, Close stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Close method is completed. The Notify property determines whether Close generates an OnNotify event.

Close is called automatically when the application is terminated.


See also

Open method


Close method

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure Close;

Description

The Close method closes the dataset, returning it to Inactive state. Calling Close is equivalent to setting the Active property to False.

Note:	Post is not called implicitly by the Close method. Use the BeforeClose event to post any pending edits explicitly.


Close method

See also	Example

Applies to

TDataBase components

Declaration

procedure Close;

Description

The Close method closes the TDatabase component and all the dataset components linked to it. This is the same as setting the Connected property to False.


Example

Database1.Close;


See also

CloseDatasets method


Close method

See also

Applies to

TSession components

Declaration

procedure Close;

Description

The Close method closes the session, exactly the same as setting the Active property to False.


See also

Open method

Session variable


CloseApplication method

See also

Applies to

TReport component

Declaration

function CloseApplication(ShowDialogs: Boolean): Boolean;

Description

The CloseApplication method stops ReportSmith, if it is running. CloseApplication attempts to terminate ReportSmith and looks for confirmation from ReportSmith in return. If CloseApplication returns True, ReportSmith terminated successfully; if it returns False, ReportSmith was not able to close at the current time.

The value of the ShowDialogs parameter determines whether ReportSmith displays dialog boxes prompting users to save the existing report before closing, and so on. If ShowDialogs is True, the dialog boxes appear before ReportSmith closes. If the parameter is False, no dialog boxes appear.

See also

CloseReport method


CloseDatabase method

See also	Example

Applies to

TSession component

Declaration

procedure CloseDatabase(Database: TDatabase);

Description

The CloseDatabase method closes a TDatabase component. The parameter Database specifies the TDatabase component to close. Normally, this is handled automatically when an application closes the last table in the database associated with a TDatabase component. CloseDatabase decrements the Session's reference count of the number of open database connections.

You should always use CloseDatabase with OpenDatabase, typically in a try...finally block to ensure that database connections are handled properly.


Example

Database := Session.OpenDatabase('DBDEMOS');

try

   {Do Something}

finally

    Session.CloseDatabase('DBDEMOS');

end;


See also

Session variable


CloseDatasets method

See also	Example

Applies to

TDataBase component

Declaration

procedure CloseDatasets;

Description

The CloseDatasets method closes all of the dataset components linked to the TDatabase component, but does not close the database connection itself.


Example

Database1.CloseDatasets;


See also

Close method


CloseDialog method

See also

Applies to

TFindDialog, TReplaceDialog components

Declaration

procedure CloseDialog;

Description

The CloseDialog method closes the Find and Replace dialog boxes.


See also

Execute method


CloseIndexFile method

See also

Applies to

TTable component

Declaration

procedure CloseIndexFile(const IndexFileName: string);

Description

Closes the specified dBASE non-production index file. Once closed, non-production index files aren't maintained.


See also

OpenIndexFile method

IndexFiles property


CloseLink method

See also	Example

Applies to

TDDEClientConv component

Declaration

function CloseLink;

Description

The CloseLink method terminates an ongoing DDE conversation. After a link is closed, no DDE communication can take place between the DDE client and server until another link is opened.


Example

The following code terminates the DDE conversation.

DDEClientConv1.CloseLink;


See also

OnClose event

OpenLink method


CloseQuery method

See also	Example

Applies to

TForm component

Declaration

function CloseQuery: Boolean;

Description

The CloseQuery method is called as part of a form's Close method processing to determine if the form can actually close. CloseQuery executes the code attached to the OnCloseQuery event. If the OnCloseQuery event handler assigns False to its CanClose parameter, CloseQuery will return False indicating that the form cannot close. Otherwise CloseQuery returns True, indicating that the form is ready to close.

The CloseQuery method of the main form of an MDI application automatically calls the CloseQuery method of each MDI child form before executing its own OnCloseQuery event. If any of the child forms return False, the main form's CloseQuery stops and also returns False. Your application can use the OnCloseQuery event to ask users if they want special processing to occur, such as saving information on the form, before the form is closed.


Example

When the user attempts to close the form in this example, a message dialog appears that asks if it is OK to close the form. If the user chooses No, the form doesn't close. If the user chooses OK, the form closes.

procedure TForm1.FormCloseQuery(Sender: TObject; var CanClose: Boolean);

var

  ButtonSelected: Word;

begin

  ButtonSelected := MessageDlg('Is it OK to close the form?', mtInformation,

    [mbOk, mbNo], 0);

  if ButtonSelected = mrOk then

    CanClose := True

  else

    CanClose := False;

end;


See also

Close method

OnCloseQuery event


CloseReport method

See also	Example

Applies to

TReport component

Declaration

function CloseReport(ShowDialogs: Boolean): Boolean;

Description

The CloseReport method determines whether the running of a ReportSmith report terminates. CloseReport tells ReportSmith to terminate the report and then waits for confirmation in return. If CloseReport returns True, ReportSmith received the message to terminate the report. If CloseReport returns False, ReportSmith could not terminate the report at the current time.

The ShowDialogs parameter determines whether dialog boxes that prompt the user about saving the report appear before the report closes, and so on. If ShowDialogs is True, the dialog boxes appear. If it is False, the dialog boxes are not shown.


Example

The following code terminates the running report if the user chooses Yes from a dialog box:

if MessageDlg('Do you want to stop running ' + Report1.ReportName + ' ?',

  mtConfirmation, [mbYes, mbNo], 0) = mrYes then

  if Report1.CloseReport(False) then MessageDlg(Report1.ReportName + ' canceled.',

    mtInformation, [mbOK], 0);


See also

CloseApplication method


CloseUp method

Applies to

TDBLookupCombo, TDBLookupComboBox components

Description

CloseUp method for DBLookupComboBox

CloseUp method for DBLookupCombo


CloseUp method for TDBLookupComboBox
CloseUp method

See also

Applies to

TDBLookupComboBox component

Declaration

procedure CloseUp(Accept: Boolean);

Description

The CloseUp method closes an opened or "dropped-down" database lookup combo box. The Accept parameter determines whether to modify the DataField with the selected value in the combo box.


See also

DropDown method

OnCloseUp event


CloseUp method for TDBLookupCombo
CloseUp method

See also

Applies to

TDBLookupCombo component

Declaration

procedure CloseUp;

Description

The CloseUp method closes an opened or "dropped-down" database lookup combo box.


See also

DropDown method


Col property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property Col: Longint;

Description

Run-time only. The value of the Col property indicates the current column of the cell that has input focus. You can use the Col property along with the Row property to determine which cell is selected at run time.


Example

This example uses a string grid with a label above it on a form. When the user clicks a cell in the grid, the location of the cursor is displayed in the label caption.

procedure TForm1.StringGrid1Click(Sender: TObject);

begin

  Label1.Caption := 'The cursor is in column ' + IntToStr(StringGrid1.Col + 1)

     +  ', row ' + IntToStr(StringGrid1.Row + 1);

end;


See also

ColCount property

ColWidths property

DefaultColWidth property


ColCount property

Applies to

TDrawGrid, TStringGrid, TDBCtrlGrid components

Description

ColCount for Draw and String Grids

ColCount for Control Grids


ColCount property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property ColCount: Longint;

Description

Run-time only. The value of the ColCount property determines the number of columns in the grid. The default value is 5.


Example

The following line of code adds one column to a string grid named MyStrngGrd:

MyStrngGrd.ColCount := MyStrngGrd.ColCount + 1;


See also

Col property

ColWidths property

RowCount property


ColCount property

Applies to

TDBCtrlGrid components

Declaration

property ColCount: Integer;

Description

Represents the number of columns of panels shown in the grid. When you set the ColCount property, the grid resizes itself to fit the new number of columns; PanelWidth doesn't change.


Collapse method

Applies to

TOutlineNode, TTreeNode objects

Description

Collapse method for Outline Node Objects

Collapse method for Tree Node Objects


Collapse method

See also	Example

Applies to

TOutlineNode object

Declaration

procedure Collapse;

Description

The Collapse method collapses an outline item by assigning False to its Expanded property. When an outline item is collapsed, its sub-items are hidden and the plus picture or closed picture might be displayed, depending on the outline style specified in the OutlineStyle property of the TOutline component.


Example

The following code collapses the first outline item.

Outline1.Items[1].Collapse;


See also

Expand method

FullCollapse method

FullExpand method

PictureClosed property

PicturePlus property


Collapse method for tree node objects
Collapse method

See also

Applies to

TTreeNode object

Declaration

procedure Collapse(Recurse: Boolean);

Description

The Collapse method collapses an item. When an item is collapsed, its subitems are hidden and the plus button might be displayed, depending on whether the tree view's ShowButtons property is set. If Recurse is True, then all subitems will be collapsed as well and when the item is next expanded the children will be collapsed. If Recurse is False, the child items won't be collapse and the next time the item is expanded, the children will be in the same state as when Collapse was called.


See also

OnCollapsed event

OnCollapsing event

OnExpanded event

OnExpanding event

FullCollapse method

FullExpand method


Collate property

Applies to

TPrintDialog component

Declaration

property Collate: Boolean;

Description

The Collate property determines if the Collate check box is checked and, therefore, if collating is selected. Regardless of the initial setting of the Collate property, the user can always check or uncheck the Collate check box (and change the Collate property) to choose or not choose to collate the print job. The default setting is False.


Collection property

See also

Applies to

TCollectionItem, THeaderSection, TStatusPanel objects

Declaration

property Collection: TCollection;

Description

Run-time only. The Collection property specifies the TCollection object to which the TCollectionItem belongs. The collection object maintains an array of its collection item type in its indexed Items property. TCollectionItem objects are indexed in the Items array of a TCollection object. THeaderSection objects are indexed in the Items array of a THeaderSections object TStatusPanel objects are indexed in the Items array of a TStatusPanels object.


See also

Index property


Color property

Applies to

TBrush, TFont, TPen, TColumn objects;

TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TForm, TGroupBox, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPaintBox, TPageControl, TPanel, TRadioButton, TRichEdit, TScrollBox, TStringGrid, TTextAttributes, TTreeView, TBitBtn, TCheckBox components

Declaration

Color Property for Color Dialog Boxes

Color Property for Column Objects

Color Property for All Other Components and Objects


Color property

Applies to

TBrush, TFont, TPen, TColumn objects;TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TForm, TGroupBox, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPaintBox, TPageControl, TPanel, TRadioButton, TRichEdit, TScrollBox, TStringGrid, TTextAttributes, TTreeView, TBitBtn, TCheckBox components

Declaration

property Color: TColor;

Description

For all components or objects except the Color dialog box, the Color property determines the background color of a form or the color of a control or graphics object.

If a control's ParentColor property is True, then changing the Color property of the control's parent automatically changes the Color property of the control. When you assign a value to a control's Color property, the control's ParentColor property is automatically set to False. These are the possible values of Color:

Value	Meaning

clBlack	Black

clMaroon	Maroon

clGreen	Green

clOlive	Olive green

clNavy	Navy blue

clPurple	Purple

clTeal	Teal

clGray	Gray

clSilver	Silver

clRed	Red

clLime	Lime green

clBlue	Blue

clFuchsia	Fuchsia

clAqua	Aqua

clWhite	White

clBackground	Current color of your Windows background

clActiveCaption	Current color of the title bar of the active window

clInactiveCaption	Current color of the title bar of inactive windows

clMenu	Current background color of menus

clWindow	Current background color of windows

clWindowFrame	Current color of window frames

clMenuText	Current color of text on menus

clWindowText	Current color of text in windows

clCaptionText	Current color of the text on the title bar of the active window

clActiveBorder	Current border color of the active window

clInactiveBorder	Current border color of inactive windows

clAppWorkSpace	Current color of the application workspace

clHighlight	Current background color of selected text

clHightlightText	Current color of selected text

clBtnFace	Current color of a button face

clBtnShadow	Current color of a shadow cast by a button

clGrayText	Current color of text that is dimmed

clBtnText	Current color of text on a button

clInactiveCaptionText	Current color of the text on the title bar of an inactive window

clBtnHighlight	Current color of the highlighting on a button

cl3DDkShadow 	Windows 95 only: Dark shadow for three-dimensional display elements

cl3DLight 	Windows 95 only: Light color for three-dimensional display elements (for edges facing the light source)

clInfoText 	Windows 95 only: Text color for tooltip controls

clInfoBk 	Windows 95 only: Background color for tooltip controls

The second half of the colors listed here are Windows system colors. The color that appears depends on the color scheme users are using for Windows. Users can change these colors using the Control Panel in Program Manager. The actual color that appears will vary from system to system. For example, the color fuchsia may appear more blue on one system than another.


Color Property for Color Dialog Boxes
Color property

See also	Example

Applies to

TColorDialog component;

When you use the Color dialog box to select a color, you are assigning a new color value to the dialog box's Color property. You can then use the value within the Color property and assign it to the Color property of another control.


Example

This code colors a form red:

Form1.Color := clRed;

The following code changes the color of an edit box control using the Color dialog box. The example displays the Color dialog box when the Button1 button is clicked, allowing the user to select a color with the dialog box. The example then assigns the color value selected with the dialog box to the Color property of the edit box control:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if ColorDialog1.Execute then   Edit1.Color := ColorDialog1.Color;

end;


See also

ColorToRGB function

ParentColor property

TColorDialog component


Color Property for Column Objects
Color property

Applies to

TColumn object

Declaration

property Color: TColor;

Description

The background color of data shown in a column of a TDBGrid component.


ColoredButtons property

See also	Example

Applies to

TMediaPlayer component

Declaration

property ColoredButtons: TButtonSet;

Description

The ColoredButtons property determines which of the buttons on the media player control has color. If a button is not colored with ColoredButtons, it appears in black-and-white when visible. All media player control buttons are colored by default.

Button	Value	Action

Play	btPlay	Plays the media player

Record	btRecord	Starts recording

Stop	btStop	Stops playing or recording

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks

Step	btStep	Moves forward a number of frames

Back	btBack	Moves backward a number of frames

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium


Example

The following example displays all of the media player component's buttons in color:

TMediaPlayer1.ColoredButtons := [btPlay, btPause, btStop, btNext, btPrev, btStep, btBack,
  btRecord, btEject]


See also

EnabledButtons property

VisibleButtons property


ColorToRGB function

See also	Example

Unit

Graphics

Declaration

function ColorToRGB(Color: TColor): Longint;

Description

The ColorToRGB function returns the RGB value that Windows uses from a TColor type used by Delphi. If the color represents a system color, the current RGB value for that system color is returned.


Example

The following code converts the color of the current form, Form1, to a Windows RGB value:

var

  L : Longint;

begin

  L := ColorToRGB(Form1.Color);

end;


See also

Color property


Cols property

See also	Example

Applies to

TStringGrid component

Declaration

property Cols[Index: Integer]: TStrings;

Description

The Cols property is an array of the strings and their associated objects in a column. The number of strings and associated objects is always equal to the value of the ColCount property, the number of columns in the grid. Use the Cols property to access the strings and their associated objects within a particular column in the grid. The Index parameter is the number of the column you want to access; the Index value of the first column in the grid is zero.


Example

The following line of code adds the string 'Hello' to the end of the list of strings in column four of the string grid named StringGrid1:

  StringGrid1.Cols[3].Add('Hello');


See also

Cells property

Objects property

Rows property


Column property

See also

Applies to

TListView component

Declaration

property Column[Index: Integer]: TListColumn;

Description

Run-time and read only. The Column property returns the column with the given Index parameter.


Example

The following example returns and changes the width of the column that has an index of 2.

ListView1.Column[2].Width := 100;


See also

Columns property

Index property

IndexOf method


ColumnClick property

See also

Applies to

TListView component

Declaration

property Columnclick: Boolean;

Description

The ColumnClick property determines whether the column header behaves like a button. A column header is a panel with a caption that identifies the category of its list of items. To display the headers the ShowColumnHeaders property must be set to True and the ViewStyle property must be set to vsReport.


See also

Columns property

ViewStyle property

ShowColumnHeaders property


Columns property

Applies to

TDBGrid, TDBRadioGroup, TDirectoryListBox, TListBox, TListView, TRadioGroup components

Description

Columns Property for List Boxes and Radio Groups

Columns Property for List View

Columns Property for Database Grids


Columns property

Applies to

TDBRadioGroup, TDirectoryListBox, TListBox, TRadioGroup components

Declaration

property Columns: Longint;

Description

The Columns property denotes the number of columns in the list box or radio group box. Specify the number of columns you want for the list box or radio group box as the value of Columns.


Columns property for list views
Columns property

See also	Example

Applies to

TListView component

Declaration

property Columns: TListColumns;

Description

The Columns property contains the optional column headers for a TListView control. To display the columns you must set the list view ViewStyle property to vsReport (vsIcon is the default).

When setting Columns at design-time a ListView Columns Editor dialog appears. This dialog displays an indexed list of the columns that is maintained by the TListColumns object. The individual columns are TListColumn objects. You can use this dialog to add or delete columns (TListColumn objects), and to edit their display properties. At run-time use the Caption, Alignment and Width properties to change the appearance of the column headers.


Example

The following example modifies the properties of the column headings in the list view.

with ListView1.Columns do

  begin

    Items[0].Caption := 'Wider1';

    Items[0].Width := 100;

    Items[1].Caption := 'Wider2';

    Items[1].Width := '100';

  end;


See also

ViewStyle property

ShowColumnHeaders property


Columns property

Applies to

TDBGrid component

Declaration

property Columns: TDBGridColumns;

Description

The Columns property returns the TDBGridColumns collection object holding the TColumn objects representing the columns in the grid. Use Columns to access TDBGridColumns methods and properties for manipulating the attributes of one or more columns or to add or delete columns from the grid.


ColWidths property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property ColWidths[Index: Longint]: Integer;

Description

Run-time only. The ColWidths property determines the width in pixels of all the cells within the column referenced by the Index parameter.

By default, all the columns are the same width, the value of the DefaultColWidth property. To change the width of all columns within a grid, change the DefaultColWidth property value.

To change the width of one column without affecting others, change the ColWidths property. Specify the column you want to change as the value of the Index parameter. Remember the first column always has an Index value of 0.


Example

The following code changes the width of column 0 in the string grid called StringGrid1 to twice the default value.

StringGrid1.ColWidths[0] := StringGrid1.DefaultColWidth * 2;


See also

RowHeights property


Command property

Example

Applies to

TMenuItem component

Declaration

property Command: Word;

Description

Run-time and read only. The Command property value is the command number passed to Windows and the number that arrives in the WM_COMMAND message sent by Windows to the form when the user chooses this menu item on the menu. Command is useful only if you are handling WM_COMMAND messages directly.


Example

The following procedure is a WM_COMMAND message handler. It checks the ItemID field of Msg to see if the message was generated by a menu item called MenuThink. If so, it displays a message dialog box. When writing message handlers, remember to call Inherited afterward, if necessary, so Windows can perform default message processing.

procedure TForm1.WMCommand(var Msg: TWMCommand);

begin

  if Msg.ItemID = MenuThink.Command then

    MessageDlg('This is the Think command', mtInformation, [mbOk], 0);

  Inherited;

end;


CommaText property

See also	Example

Applies to

TStringList, TStrings objects

Declaration

property CommaText: string;

Description

The CommaText property retrieves and sets the strings of the string list in system data format (SDF) style. When retrieving CommaText, the string returned contains each string in the string list separated by commas. If a string in the string list has spaces, commas or quotes, then the individual string will be quoted as well. For example, if the string list contains the following strings:

Stri,,ng 1

Stri""ng 2

String 3

String4

CommaText will return:

"Stri,,ng 1","Stri""""ng 2","String 3",String4

When assigning CommaText, the string is parsed in as SDF formatted text. For SDF format, strings are separated by commas, spaces, #10, #13 and #0, and delimited by double quotes. For example, suppose CommaText is set to:

"Stri,,ng 1","Stri""""ng 2",String 3,String4

The string list will then contain:

Stri,,ng 1

Stri""ng 2

String

3

String4


Example

The following example reads an SDF text file containing a list of customers into a string list, then uses the CommaText method to parse the file into the list box.

procedure TForm1.Button1Click(Sender: TObject);

var

  FileString : TStringList;

begin

  FileString := TStringList.Create;

  try

    FileString.LoadFromFile('c:\customers.txt');

    ListBox1.Items.CommaText := FileString.Text;

  finally

    FileString.Free;

end;


See also

Values property

Names property

Text property


Commit method

See also	Example

Applies to

TDataBase component

Declaration

procedure Commit;

Description

The Commit method writes all modifications since the last call to StartTransaction to the database and ends the current transaction. If no transaction is active, Delphi raises an exception.


Example

with Database1 do

  begin

    StartTransaction;

{ Update one or more records in tables linked to Database1 }

...

    Commit;

  end;


See also

Rollback method

TransIsolation property

InTransaction property


CommitUpdates method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure CommitUpdates;

Description

The CommitUpdates method updates the cache to reflect that pending cached updates were successfully applied by a call to the ApplyUpdates method. Generally, you should call the database object's ApplyUpdates method instead of the dataset's. It calls ApplyUpdates and CommitUpdates within a transaction.


See also

CachedUpdates property

CancelUpdates method

RevertRecord method

UpdateStatus method

UpdateRecordTypes property


ComponentCount property

See also	Example

Applies to

All components

Declaration

property ComponentCount: Integer;

Description

Run-time and read only. The ComponentCount property indicates the number of components owned by the component as listed in the Components array property. For example, ComponentCount of a form contains the same number of items as in the Components list of a form.

Note:	ComponentCount is always 1 more than the highest Components index, because the first Components index is always 0.


Example

This code uses several controls on a form, including a button and an edit box. When the user clicks the button, the code counts all the components on the form and displays the number in the Edit1 edit box. While the components are being counted, each is evaluated to see if it is a button component. If the component is a button, the code changes the font on the button face.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to ComponentCount -1 do

     if Components[I] is TButton then

       TButton(Components[I]).Font.Name := 'Courier';

  Edit1.Text := IntToStr(ComponentCount) + ' components';

end;


See also

ComponentIndex property

Components property


ComponentIndex property

See also	Example

Applies to

All components

Declaration

property ComponentIndex: Integer;

Description

Run-time and read only. The ComponentIndex property indicates the position of the component in its owner's Components property list. The first component in the list has a ComponentIndex value of 0, the second has a value of 1, and so on.


Example

The following code uses a button and a wide edit box on a form. When the user clicks the button, the edit box displays the index value of the button component:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.Text := 'The index of the button is ' + IntToStr(Button1.ComponentIndex);

end;


See also

ComponentCount property

Components property


Components property

See also	Example

Applies to

All components

Declaration

property Components[Index: Integer]: TComponent;

Description

Run-time and read only. The Components array property is a list of all components owned by the component. You can use the Components property to access any of these owned components, such as the controls owned by a form. The Components property is most useful if you need to refer to owned components by number rather than name.

Don't confuse the Components property with the Controls property. The Components property lists all components that are owned by the component, whereas the Controls property lists all the controls that are child windows of this control. All components on a form are owned by the form, and therefore, they appear in the form's Components property list.

Consider this example. If you put a control in a group box, the form still owns the control, but the control's window parent is the group box control, and therefore, is listed in the group box's Controls property array.


Example

This code uses several controls on a form, including a button and an edit box. When the user clicks the button, the code counts all the components on the form and displays the number in the Edit1 edit box. While the components are being counted, each is evaluated to see if it is a button component. If the component is a button, the code changes the font on the button face.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to ComponentCount -1 do

     if Components[I] is TButton then

       TButton(Components[I]).Font.Name := 'Courier';

  Edit1.Text := IntToStr(ComponentCount) + ' components';

end;


See also

ComponentCount property

ComponentIndex property

Owner property

Parent property

TabOrder property


ConfigMode property

See also	Example

Applies to

TSession

Declaration

property ConfigMode: TConfigMode;

Description

Run-time only. The ConfigMode property determines whether new aliases (created with AddAlias or AddStandardAlias) are global (cmPersistent and cmAll) or local (cmSession). Permanent aliases are available to all applications that use the Borland Database Engine (BDE). Local aliases are available only within the session that created them. Call the SaveConfigFile method to save global aliases permanently in the BDE configuration file.

ConfigMode also determines which aliases the GetAliasNames method returns.

Note:	For most applications, we do not recommend changing the value of ConfigMode from it's default of cmAll.


Example

The following example specifically creates a local alias pointing to the application directory.  Note that this alias is automatically be deleted when the application terminates and will not be saved to the BDE configuration file.

  begin

      with Session do

      begin

        ConfigMode := cmSession;

        try

          AddStandardAlias('TEMPDB', ExtractFilePath(ParamStr(0)), 'PARADOX');

        finally

          ConfigMode := cmAll;

        end;

      end;


See also

Session variable


ConfirmDelete property

See also

Applies to

TDBNavigator component

Declaration

property ConfirmDelete: Boolean;

Description

The ConfirmDelete property determines whether a message box asking you to confirm the deletion when the user uses the database navigator to delete the current record in the dataset. If ConfirmDelete is True, a prompting message box appears and the record isn't deleted unless the user chooses the OK button. If ConfirmDelete is False, no message box appears and the record is deleted.

The default value is True.


See also

VisibleButtons property


Connect method

Applies to

TReport component

Declaration

function Connect(ServerType: Word; const ServerName, UserName, Password,

DatabaseName: string): Integer;

Description

The Connect method connects the report to a database, bypassing the ReportSmith log in dialog box. Specify the server type and name with the ServerType and ServerName parameters. Specify the user name, the log-in password, and the name of the database using the UserName, Password, and DatabaseName parameters.


Connected property

Example

Applies to

TDataBase component

Declaration

property Connected: Boolean;

Description

The Connected property indicates whether the TDatabase component has established a connection to a database. Connected will be set to True when an application opens a table in a database (logging in to a server, if required). It will be set back to False when the table is closed (unless KeepConnection is True). Set Connected to True to establish a connection to a database without opening a table. Set Connected to False to close a database connection.

The KeepConnection property of TDatabase specifies whether to maintain database connections when no tables in the database are open. The KeepConnections property of TSession specifies whether to maintain database connections when there is no explicit TDatabase component for the database.


Example

Database1.Connected := True;


ConnectMode property

Example

Applies to

TDDEClientConv component

Declaration

property ConnectMode: TDataMode;

Description

The ConnectMode property determines the type of connection to establish when initiating a link with a DDE server application. These are the possible values:

Value	Meaning

ddeAutomatic	The link is automatically established when the form containing the TDDEClient component is created at run time. This is the default value.

ddeManual	The link is established only when the OpenLink method is called.


Example

The following code sets the connect mode of DDEClientConv1 to manual.

DDEClientConv1.ConnectMode := ddeManual;


ConsistentAttributes property

See also

Applies to

TTextAttributes object

Declaration

property ConsistentAttributes: TConsistentAttributes;

Description

Run-time and read only. The ConsistentAttributes property contains character formatting information about the selected text of a rich edit control. The values of the ConsistentAttributes property indicate whether or not a particular text attribute is consistent throughout the selected text. It does not indicate what the attribute is for the selected text, for example, whether or not it is bold. These are the possible values:

Value	Meaning

caBold	Characters are consistently either bold or not bold throughout the entire selection.

caColor	Indicates that the color of character font is consistent throughout the entire selection.

caFace	Indicates that the facename of the character font is consistent throughout the entire selection.

caItalic	Characters are consistently either italic or not italic throughout the entire selection.

caSize	Indicates that the size of the character font is consistent throughout the entire selection.

caStrikeout	Characters consistently either have the strikeout style or they do not have the strikeout style throughout the entire selection.

caUnderline	Characters are consistently either underlined or not underlined throughout the entire selection.

caProtected	Text is consistently either protected or not protected. Protected text means read-only.

The ConsistentAttributes property is one of several properties of the TTextAttributes object. Several of the others, Color, Name, Pitch, Size, Style, and Height, are identical to the like-named properties of TFont. You can assign fonts to text attributes and vice versa.

TTextAttributes is the type of the DefAttributes and SelAttributes properties of TRichEdit.


See also

DefAttributes property

OnSelectionChange event

Paragraph property

PlainText property

SelAttributes property


ContainsControl method

Example

Applies to

All windowed controls

Declaration

function ContainsControl(Control: TControl): Boolean;

Description

The ContainsControl method indicates whether a specified control exists within a control. If the method returns True, the control specified as the value of the Control parameter exists within the control. If the method returns False, the specified control is not within the control.


Example

This example uses a label, a list box, and a button on a form. When the user clicks the button, the caption of the label reports that the form contains the list box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if ContainsControl(ListBox1) then

    Label1.Caption := 'The form contains ListBox1';

end;


ControlAtPos method

Applies to

All windowed controls

Declaration

function ControlAtPos(Pos: TPoint; AllowDisabled: Boolean): TControl;

Description

The ControlAtPos method returns the windowed control's child control (from those in the Controls array property) located at client coordinates of the windowed control. The client coordinates are passed in Pos . If there is no control at the specified position, ControlAtPos returns nil. The AllowDisabled parameter controls whether the search for controls includes disabled controls.


ControlCount property

See also	Example

Applies to

All controls

Declaration

property ControlCount: Integer;

Description

Run-time and read only. The ControlCount property indicates the number of controls that are children of the control. The children are listed in the Controls property array.

Note:	The value of ControlCount is always 1 greater than the highest Controls index, because the first Controls index is 0.


Example

This example uses a group box on a form, with several controls contained within the group box. The form also has an edit box and a button outside of the group box. The code counts each control's child controls turning each of them invisible as they are counted. The total number of controls counted appears in the edit box.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I:= 0 to GroupBox1.ControlCount -1 do

     GroupBox1.Controls[I].Visible := False;

  Edit1.Text := IntToStr(GroupBox1.ControlCount) + ' controls';

end;


See also

Controls property


Controls property

See also	Example

Applies to

All controls

Declaration

property Controls[Index: Integer]: TControl;

Description

Run-time and read only. The Controls property is an array of all controls that are children of the control. The Controls property is most useful if you have a need to refer to the children of a control by number rather than name.

Don't confuse the Controls property with the Components property. The Components property lists all components that are owned by the component, while the Controls property lists all the controls that are child windows of the control. All components put on a form are owned by the form, and therefore, they appear in the form's Components property list.

For example, if you put a control in a group box, the form still owns the control, but the control's window parent is the group box control, and therefore, is listed in the group box's Controls property array.


Example

This example uses a group box on a form, with several controls contained within the group box. The form also has an edit box and a button outside of the group box. The code counts each control's child controls turning each of them invisible as they are counted. The total number of controls counted displays in the edit box.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I:= 0 to GroupBox1.ControlCount -1 do

     GroupBox1.Controls[I].Visible := False;

  Edit1.Text := IntToStr(GroupBox1.ControlCount) + ' controls';

end;


See also

ControlCount property

Owner property

Parent property


ControlsDisabled method

Applies to

TTable, TQuery, TStoredProc components

Declaration

function ControlsDisabled: Boolean;

Description

ControlsDisabled returns True if DisableControls has been called without a corresponding EnableControls call, meaning that data-aware controls aren't displaying data from their data sources.


Conv property

Applies to

TDdeClientConv component

Declaration

property Conv: HConv;

Description

Run-time and read-only. The Conv property contains the handle for the current DDE conversation. If you need to use a Windows API function that requires a handle for a DDE conversation, you can pass the handle in the Conv property of a TDdeClientConv component.


Copies property

Example

Applies to

TPrintDialog component

Declaration

property Copies: Integer;

Description

The value of the Copies property determines the number of copies of the print job to print. If you change the value of Copies at design time, the value you specify is the default value in the edit box control when the Print dialog box appears. The default value is 0.


Example

The following code sets the default number of copies for the print dialog box, PrintDialog1, to 3 before displaying the dialog box:

PrintDialog1.Copies := 3;

PrintDialog1.Execute;


CopyMode property

See also	Example

Applies to

TCanvas object

Declaration

property CopyMode: TCopyMode;

Description

The CopyMode property determines how a canvas treats an image copied from another canvas. By default, CopyMode is cmSrcCopy, meaning that pixels from the other canvas are copied to the canvas, overwriting any image already there. By changing CopyMode, you can create many different effects. The following table shows possible values of CopyMode and describes each:

Value	Meaning

cmBlackness	Turns all output black.

cmDstInvert	Inverts the destination bitmap.

cmMergeCopy	Combines the pattern and the source bitmap by using the Boolean AND operator.

cmMergePaint	Combines the inverted source bitmap with the destination bitmap by using the Boolean OR operator.

cmNotSrcCopy	Copies the inverted source bitmap to the destination.

cmNotSrcErase	Inverts the result of combining the destination and source bitmaps by using the Boolean OR operator.

cmPatCopy	Copies the pattern to the destination bitmap with the pattern by using the Boolean XOR operator.

cmPatInvert	Combines the destination bitmap with the pattern by using the Boolean XOR operator

cmPatPaint	Combines the inverted source bitmap with the pattern by using the Boolean OR operator. Combines the result of this operation with the destination bitmap by using the Boolean OR operator.

cmSrcAnd	Combines pixels from the destination and source bitmaps by using the Boolean AND operator.

cmSrcCopy	Copies the source bitmap to the destination bitmap.

cmSrcErase	Inverts the destination bitmap and combines the result with the source bitmap by using the Boolean AND operator.

cmSrcInvert	Combines pixels from the destination and source bitmaps by using the Boolean XOR operator.

cmSrcPaint	Combines pixels from the destination and source bitmaps by using the Boolean OR operator.

cmWhiteness	Turns all output white.


Example

The following code copies the inverted source bitmap to the Canvas of Form2:

Form2.Canvas.CopyMode := cmNotSrcCopy;

Form2.Canvas.CopyRect(ClientRect, Canvas, ClientRect);


See also

CopyRect method


CopyParams method

Example

Applies to

TStoredProc component

Declaration

procedure CopyParams(Value: TParams);

Description

The CopyParams method copies all of the parameter information from the stored procedure component to Value. Use this method to copy parameters from one stored procedure component to another.


Example

The following code copies all parameters from StoredProc1 to StoredProc2:

StoredProc1.CopyParams(StoredProc2.Params);


CopyRect method

See also

Applies to

TCanvas object

Declaration

procedure CopyRect(Dest: TRect; Canvas: TCanvas; Source: TRect);

Description

The CopyRect method copies part of an image from another canvas into the canvas object. The Dest property specifies the destination rectangle on the destination canvas where the image will be copied. The Canvas property specifies the source canvas. The Source property specifies the source rectangle from the source canvas that will be copied.


See also

CopyMode property


CopyToClipboard method

Applies to

TDBEdit, TDBImage, TDBMemo, TDDEServerItem, TEdit, TMemo components

Description

The CopyToClipboard method copies a selection to the Clipboard.

CopyToClipboard method for Edit Box and Memo components

CopyToClipboard method for the DDE Server components

CopyToClipboard method for Database Image components


CopyToClipboard method

See also	Example

Applies to

TDBEdit, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

procedure CopyToClipboard;

Description

The CopyToClipboard method copies the text selected in the control to the Clipboard, replacing any text that exists there. If no text is selected, nothing is copied.


Example

The following method copies the selected text from the memo control named Memo1 to the Clipboard and pastes it into an edit box named Edit1 when the user clicks the button named Button1:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Memo1.CopyToClipboard;

  Edit1.PasteFromClipboard;

end;


See also

Clear method

ClearSelection method

CutToClipboard method

PasteFromClipboard method


CopyToClipboardMethod

See also	Example

Applies to

TDDEServerItem component

Declaration

procedure CopyToClipboard;

Description

The CopyToClipboard method copies the text data specified in the Text or Lines property of a DDE server item component to the Windows Clipboard, as well as DDE link information. You can then create a link by activating the DDE client application, selecting the topic and item of the DDE conversation, and executing an Edit|Paste Link command, or its equivalent in the command structure of the DDE client application.

CopyToClipboard can be used to create a DDE link at run-time only. To create a link at design time, select the DDE server item component and choose Edit|Copy from the menu. Then, activate the DDE server application and paste the link according to the rules of the DDE server application. See the documentation for the DDE server application for specific information about pasting the link.

If the Clear parameter is True, the prior contents of the Clipboard are deleted before CopyToClipboard places its data on the Clipboard. If Clear is False, the Clipboard won't be cleared before the copy.


Example

The following code copies the DDE link information of DDEServerItem1 to the Clipboard, clearing the contents of the Clipboard before the copy.

DDEServerItem1.CopyToClipboard;


See also

Clear method


CopyToClipboard method

See also	Example

Applies to

TDBImage components

Declaration

procedure CopyToClipboard;

Description

The CopyToClipboard method copies the image of the database image component to the Clipboard.


Example

The following code copies the contents of DBImage1 to the Clipboard without clearing the contents of the Clipboard first.

DBImage1.CopyToClipboard(False);


See also

CutToClipboard method

PasteFromClipboard method


Count method

Example

Applies to

TParams object

Declaration

function Count: Integer;

Description

The Count method returns the number of entries in Items.


Example

{ Assign 99999 to any integer parameter which does not have a value }

for I := 0 to Params.Count - 1 do

  if (Params.Items[I].IsNull) and (Params.Items[I].DataType = ftInteger) then

{ Items is the default property, so you can omit its name }

    Params[I].AsInteger := 99999;


Count property

Applies to

TCollection, TDBGridColumns, TFieldDefs, THeaderSections, TIndexDefs, TList, TListItems, TParams, TSessionList, TStringList, TStrings, TTreeNode, TTreeNodes, TListColumns, TStatusPanels objects; TImageList, TMenuItem, TTreeView components

Description

Count Property for Index Definitions

Count Property for Field Definitions

Count Property for Menu Items, String Objects, List and List Columns Objects, Header Sections and Status Panels objects.

Count Property for Session List objects

Count Property for TDBGridColumns Objects


Count property

See also

Applies to

TFieldDefs object

Declaration

property Count: Integer;

Description

The Count property specifies the total number of TFieldDef objects in this TFieldDefs object.


See also

Items property


Count property

Applies to

TIndexDefs objects

Declaration

property Count: Integer;

Description

Run-time and read only. The Count property holds the number of entries in the Items property.


Count property

Applies to

TDBGridColumns objects

Declaration

property Count: Integer;

Description

Run-time and read only. Returns the number of TColumn objects held by a TDBGridColumns collection object. Count is most useful if you want to use the Items array property to access column objects by index and need to know the range of possible index values (0..Count - 1).


Count property

See also

Applies to

TSessionList objects

Declaration

property Count: Integer;

Description

The Count property returns the number of TSession components stored by the TSessionList object. Count is most useful if you want to use the Sessions array property to access session components by index and need to know the range of possible index values (0..Count - 1).


See also

Sessions variable


Count property

See also	Example

Applies to

TListItems, TList, TParams, TStringList, TStrings, TTreeNode, TTreeNodes, TStatusPanels, THeaderSections, TListColumns objects; TMenuItem, TCollection components

Declaration

property Count: Integer;

Description

Run-time and read only. The Count property contains the number of items in a collection, list, menu item, tree nodes object, tree node, header section, list column or a status bar.

For string and string list objects, Count is the number of strings in the list of strings. For list objects, Count is the number of items in the list. For collections, Count is the number of collection items in the collection. For status panels, Count is the number of panels in the status panel. For headers sections, Count is the number of header sections in a header control.

For a tree node, Count is the number of child items the tree node has. For tree nodes, Count is the number of items in the tree view that owns the tree nodes object. For menu items, Count contains the number of subitems that belongs to a menu item. Subitems can be the menu items in a drop-down or pop-up menu, or the items in a submenu.

For example, if you have a File menu item on the main menu bar, but haven't added any commands to the File menu yet, the File menu's Count property value is 0. If you add New and Open commands to the File menu, the Count property value is 2. Because New and Open are also menu items, they too have Count property values. Unless either of these menu items have submenus, their Count property values are 0.


Example

The following code displays the number of items in a list box in the caption of a label when the user clicks the CountItems button:

procedure TForm1.CountItemsClick(Sender: TObject);

begin

  Label1.Caption := 'There are ' + IntToStr(ListBox1.Items.Count) +

    ' items in the listbox.';

end;

The following example assumes the form contains a main menu component, which includes a File menu and a label. This code displays the number of menu items that make up the File menu.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := IntToStr(FileMenu.Count):

end;


See also

Collection property

Items property

List property

Strings property


Create method

Applies to

All objects and components

Description

The Create method creates an object or component.

Create Method for Ini File Objects

Create Method for Outline Node Objects

Create Method for Control Scroll Bar Components

Create Method for TIndexDef Objects

Create Method for TIndexDefs Objects

Create Method for TFieldDefs Objects

Create Method for Blob Stream Objects

Create Method for Meta File Objects

Create Method for all other Components

Create Method for all other Objects


Create Method for TIniFile Objects
Create method

Example

Applies to

TiniFile object

Declaration

constructor Create(const FileName: string);

Description

The Create method allocates memory to create a TIniFile object and passes it the filename of the .INI file. Delphi looks for the specified .INI file in the Windows directory unless you include a path in the filename.


Example

This code creates an .INI file object and passes it the name of the .INI file, SUPERAPP.INI:

var

  IniFile: TIniFile;

begin

  IniFile := TIniFile.Create('SUPERAPP.INI');

  IniFile.Free;

end;


Create method

Applies to

TOutlineNode object

Declaration

constructor Create(AOwner: TCustomOutline);

Description

The Create method creates a new outline node owned by the outline passed in the AOwner parameter. You shouldn't need to call Create, as this is done for you when you add a new subitem to the outline with the Add method.


Create method

Applies to

TControlScrollBar object

Declaration

constructor Create(AControl: TScrollingWinControl; AKind: TScrollBarKind);

Description

The Create method creates a new control scroll bar. AControl specifies the component that owns the control scroll bar. AControl is of type TScrollingWinControl, which is simply a base class for TForm and TScrollBox components. AKind specifies the type of scroll bar, either sbHorizontal or sbVertical.


Create method

Applies to

TIndexDef object

Declaration

constructor Create(Owner: TIndexDefs; const Name, Fields: string; Options: TIndexOptions);

Description

The Create constructor creates a new TIndexDef object using the Name, Fields, and Options parameters and adds it to the Items property of the Owner parameter.


Create method

Applies to

TIndexDefs object

Declaration

constructor Create(Table: TTable);

Description

The Create constructor creates a new TIndexDefs object for the Table parameter.


Create method

Applies to

TFieldDefs object

Declaration

constructor Create(DataSet: TDataSet);

Description

The Create constructor creates a new TFieldDefs object for the DataSet parameter. The dataset can be a TTable or TQuery.


Create method for Blob Streams
Create method

Example

Applies to

TBlobStream object

Declaration

constructor Create(Field: TBlobField; Mode: TBlobStreamMode);

Description

The Create method links a TBlobField, TMemoField, or TGraphicField to the TBlobStream. Mode may be one of the following elements of TBlobStreamMode: bmRead to access existing data in the field; bmWrite to clear the contents of the field and assign a new value; bmReadWrite to modify an existing value.


Examples

The following example links BlobStream1 to MyBlobField for data access only

 BlobStream1 := TBlobStream.Create(MyBlobField, bmRead);

try

  Size := BlobStream1.Seek(0, 2);

finally

  BlobStream1.Free;

end;

The following example copies the data in the Notes field of Table1 to the Remarks field of Table2.

procedure TForm1.Button1Click(Sender: TObject);

var

  Stream1, Stream2 : TBlobStream;

begin

  Stream1 := TBlobStream.Create(Table1Notes, bmRead);

  try

    Table2.Edit;

    Stream2 := TBlobStream.Create(Table2Remarks, bmReadWrite);

    try

      Stream2.CopyFrom(Stream1, Stream1.Size);

      Table2.Post;

    finally

      Stream2.Free;

    end;

  finally

    Stream1.Free;

  end;

end;


Create Method for meta files
Create method

See also

Applies to

TMetaFile, TMetaFileCanvas object

Declaration

constructor Create(AMetafile: TMetafile; ReferenceDevice: HDC);

Description

The Create method allocates memory to create the metafile canvas.

To create a metafile image from scratch, you must draw the image in a metafile canvas.  When the metafile canvas is destroyed, it transfers the image into the metafile object provided to the metafile canvas constructor. After the image is drawn on the canvas and the canvas is destroyed, the image is 'playable' in the metafile object.


See also

CreateWithComment method


Create Method for Components
Create method

See also	Example

Applies to

All other components

Declaration

constructor Create(AOwner: TComponent);

Description

The Create method allocates memory to create the component and initializes its data as needed. Each object can have a Create method customized to create that particular kind of object. The owner of the created component is passed in the AOwner parameter.

Usually you don't need to create objects manually. Objects you design in Delphi are automatically created for you when you run the application and destroyed when you close the application.

If you construct a component by calling Create, and give it an owner, the owner disposes of the component when the owner is destroyed. If you don't want another component to own the created component, pass Self in the AOwner parameter.


Example

The following code creates a TButton and makes Form1 the owner.

var

  Button1: TButton;

begin

  Button1 := TButton.Create(Form1);

end;


See also

Free method


Create Method for All Other Objects
Create method

See also	Example

Applies to

All other objects

Declaration

constructor Create;

Description

The Create method allocates memory to create the object and initializes its data as needed. Each object can have a Create method customized to create that particular kind of object.


Example

The following code creates a TBitmap and loads the bitmap graphic file C:\WINDOWS\256COLOR.BMP into it. Then, the bitmap is drawn in a paint box by the OnPaint event handler of PaintBox1.

procedure TForm1.PaintBox1Paint(Sender: TObject);

var

  Bitmap1: TBitmap;

begin

  Bitmap1 := TBitmap.Create;

  Bitmap1.LoadFromFile('c:\windows\256color.bmp');

  PaintBox1.Canvas.Draw(0, 0, Bitmap1);

  Bitmap1.Free;

end;


See also

Free method


CreateBy property for TMetafile objects
CreatedBy property

See also

Applies to

TMetafile object

Declaration

property CreatedBy: String

Description

Run-time and read- only. The CreatedBy property returns the optional name of the author or application used to create the metafile, embedded in the metafile.


See also

Description property, CreateWithComment method


CreateField method

Applies to

TFieldDef object

Declaration

function CreateField(Owner: TComponent): TField;

Description

CreateField creates a TField component of the appropriate type that corresponds to the TFieldDef object itself. Owner is the dataset component containing the field.


CreateForm method

Example

Applies to

TApplication component

Declaration

procedure CreateForm(FormClass: TFormClass; var Reference);

Description

The CreateForm method creates a new form of the type specified by the FormClass parameter and assigns it to the variable given by the Reference parameter. The owner of the new form is the Application object. The form created by the first call to CreateForm in a project becomes the project's main form.

A Delphi project typically contains one or more calls to CreateForm in the project's main statement part, but there is seldom any need for you to call CreateForm yourself.


Example

The following code creates Form1 of type TForm1.

Application.CreateForm(TForm1, Form1);


CreateNew method

Applies to

TForm component

Declaration

constructor CreateNew(AOwner: TComponent);

Description

The CreateNew method creates a new instance of the current form type without reading any state information from resource files or .DFM files. The form is blank, with no controls and all properties at their default. It can be used in place of Create to bypass loading of the associated form file.


CreateParam method

Example

Applies to

TParams object

Declaration

function CreateParam(FldType: TFieldType; const ParamName: string;
  ParamType: TParamType): TParam;

Description

The CreateParam method attempts to create a new entry in Items, using the FieldType, ParamName, and ParamType parameters.


Example

The following code creates a new parameter for CustNo and assigns a value of 999 to it:

with Params.CreateParam(ftInteger, 'CustNo', ptInput) do

  AsInteger := 999;


Add method for image list objects
CreateSize method

See also

Applies to

TImageList component

Declaration

constructor CreateSize(AWidth, AHeight: Integer);

Description

The CreateSize constructor creates a TImageList object with a size that overrides the default image size of 16 x 16. The initial size of the image list is determined by the AHeight and AWidth parameters. The height and width can be altered after the image list has been constructed using the Width and Height properties.


See also

Width property, Height property


CreateTable method

Example

Applies to

TTable component

Declaration

procedure CreateTable;

Description

The CreateTable method creates a new empty database table. Before calling this method, the DatabaseName, TableName, TableType, FieldDefs and IndexDefs properties must be assigned values.


Example

with Table1 do

begin

  Active := False;

  DatabaseName := 'DBDEMOS';

  TableName := 'CustInfo';

  TableType := ttParadox;

  with FieldDefs do

  begin

    Clear;

    Add('Field1', ftInteger, 0, False);

    Add('Field2', ftInteger, 0, False);

  end;

  with IndexDefs do

  begin

    Clear;

    Add('Field1Index', 'Field1', [ixPrimary, ixUnique]);

  end;

  CreateTable;

end;


Add method for image list objects
CreateWithComment method

See also

Applies to

TMetafileCanvas object

Declaration

constructor CreateWithComment(AMetafile: TMetafile; ReferenceDevice: HDC;

   const CreatedBy, Description: String);

Description

The CreateWithComment constructor behaves like Create for a metafile canvas, but it also allows you to set the optional text with CreatedBy and Description strings embedded in a new metafile.

To create a metafile image from scratch, you must draw the image in a metafile canvas.  When the metafile canvas is destroyed, it transfers the image into the metafile object provided to the metafile canvas constructor. After the image is drawn on the canvas and the canvas is destroyed, the image is 'playable' in the metafile object.


See also

CreatedBy property, Description property


Ctl3D property

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TColorDialog, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBNavigator, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFindDialog, TFilterComboBox, TFontDialog, TForm, TGroupBox, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOpenDialog, TOutline, TPanel, TRadioButton, TReplaceDialog, TRichEdit, TSaveDialog, TScrollBar, TScrollBox, TStringGrid, TTrackBar, TTreeView components

Declaration

property Ctl3D: Boolean;

Description

The Ctl3D property determines whether a control has a three-dimensional (3-D) or two-dimensional look. If Ctl3D is True, the control has a 3-D appearance. If Ctl3D is False, the control appears normal or flat. The default value of Ctl3D is True.

For dialog boxes, the value of Ctl3D affects the dialog box and all the controls it contains.

If a control's ParentCtl3D property is True, then changing in the Ctl3D property of the control's parent automatically changes the Ctl3D property of the control. When you assign a value directly to a control's Ctl3D property, the control's ParentCtl3D property is automatically set to False.

Note:	For Ctl3D to work with radio buttons, check boxes, and any of the common dialog boxes on Windows NT 3.51, CTL3D32.DLL must be installed in the System32 directory.


Example

The following code toggles the 3-D look of a memo control when the user clicks a button named Toggle:

procedure TForm1.ToggleClick(Sender: TObject);

begin

  Memo1.Ctl3D := not Memo1.Ctl3D; {Toggles the Ctl3D property of Memo1}

end;


See also

ParentCtl3D property


Currency property

See also

Applies to

TBCDField, TCurrencyField, TFloatField components

Declaration

property Currency: Boolean;

Description

Run-time only. The Currency property is used to control the format of the value of a TBCDField, TCurrencyField, and TFloatField when both DisplayFormat and EditFormat properties are not assigned.

Currency is True by default for TCurrencyField and False for TFloatField and TBCDField. When Currency is True formatting is performed by FloatToText using ffCurrency for display text or ffFixed for editable text. When Currency is False, the formatting is performed by FloatToTextFmt.


See also

DisplayFormat property

EditFormat property

FloatToText function

FloatToTextFmt function


Cursor property

Applies to

All controls, TScreen component

Cursor Property for All Controls

Cursor Property for Screen Objects


Cursor property

See also	Example

Applies to

All controls

Declaration

property Cursor: TCursor;

Description

The Cursor property is the image used when the mouse passes into the region covered by the control. These are the possible images:

Value	Image	Value	Image	Value	Image

crDefault	crSizeNESW	crHourglass

crArrow	crSizeNS	crDrag

crCross	crSizeNWSE	crNoDrop

crIBeam	crSizeWE	crHSplit

crSize	crUpArrow	crVSplit

To learn how to make a custom cursor available to your application, see the Cursors property.


Example

This line of code changes the display of the image to the cross cursor when the user moves the mouse pointer over Button1:

Button1.Cursor := crCross;


See also

Cursors property

DragCursor property


Cursor property

Example

Applies to

TScreen component

Declaration

property Cursor: TCursor;

Description

The Screen object's Cursor property controls the mouse cursor shape at a global level. Assigning any value but crDefault to the Screen object's Cursor property sets the mouse cursor shape for all windows belonging to the application. The global mouse cursor shape remains in effect until you assign crDefault to the Screen object's Cursor property, at which point normal cursor behavior is restored.

To see a list of possible cursor shapes, see the Cursor property for all controls.


Example

Assignments to the Screen object's cursor property are typically guarded by a try...finally statement to ensure that normal cursor behavior is restored, for example:

Screen.Cursor := crHourglass;                 { Show hourglass cursor }

try

  { Do some lengthy operation }

finally

  Screen.Cursor := crDefault;                  { Always restore to normal }

end;


CursorPosChanged method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure CursorPosChanged;

Description

The CursorPosChanged method is needed only if you use the Handle property to make direct calls to the Borland Database Engine (BDE) API which cause the cursor position to change. To notify the dataset that the underlying BDE cursor's position has changed, call CursorPosChanged after the direct calls to the BDE.


See also

UpdateCursorPos method


Cursors property

See also	Example

Applies to

TScreen component

Declaration

property Cursors[Index: Integer]: HCursor;

Description

Run-time only. The Cursors property gives you access to the list of cursors available for your application. To access a particular cursor, specify its position in the list of cursors as the value of the Index parameter with the first position in the list having an index of 0, the second having an index of 1, and so on.

Using the Cursors property, you can make custom cursors available to your application.

These are the cursor constants and their position in the Cursors property array:

Cursor	Value	Cursor	Value

crDefault	     0	crSizeWE	     -9

crNone	     -1	crUpArrow	     -10

crArrow	     -2	crHourglass	     -11

crCross	     -3	crDrag	     -12

crIBeam	     -4	crNoDrop	     -13

crSize	     -5	crHSplit	     -14

crSizeNESW	     -6	crVSplit	     -15

crSizeNS	     -7	crMultiDrag	     -16

crSizeNWSE	     -8	crSQLWait	     -17

To make a custom cursor available to your application,

1	Create the cursor resource using a resource editor.

2	Declare a cursor constant with a value that does not conflict with an existing cursor constant.

3	Use the Windows API function LoadCursor to make your cursor available to your application, specifying the newly declared cursor constant as the value of the Index parameter for the Cursors property array. For more information, search for LoadCursor in the Win32 Developer's Reference (WIN32.HLP)

Note:	You don't need to call the WinAPI function DestroyCursor when you are finished using the custom cursor; Delphi does this automatically.


Example

This example assumes you have created a cursor resource with the name NewCursor. The code loads the new cursor into the Cursors property array and makes the newly loaded cursor the cursor of the form:

const

  crMyCursor = 5;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Screen.Cursors[crMyCursor] := LoadCursor(HInstance, 'NewCursor');

  Cursor := crMyCursor;

end;


See also

Cursor property

DragCursor property


CustomColors property

Example

Applies to

TColorDialog component

Declaration

property CustomColors: TStrings;

Description

The value of the CustomColors property determines the custom colors that are available in the Color dialog box. Each custom color is represented as a string that follows this format:

ColorX=HexValue

For example, this string could indicate that the first custom color box in the Color dialog box:

ColorA=808022

You can have up to 16 custom colors, ColorA through ColorP.

Use the string list of custom colors to save the custom colors specified in the dialog box so you can use them elsewhere. For example, you might save them to an .INI file for your application so your application can use the custom colors.


Example

This example displays the Color dialog box, allowing the user to create custom colors, then displays the custom color strings in a list box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if ColorDialog1.Execute then

    ListBox1.Items.AddStrings(ColorDialog1.CustomColors);

end;


CustomSort method

Applies to

TTreeNode object; TListView, TTreeView, components

Description

CustomSort Method for Tree Views and Tree Node Objects

CustomSort Method for List Views


CustomSort method for tree views and tree nodes
CustomSort method

See also	Example

Applies to

TTreeView component; TTreeNode object

Declaration

function CustomSort(SortProc: TTVCompare; Data: Longint): Boolean;

Description

The CustomSort method allows you to sort child items based on criteria that you define. When you use this method, you specify an application-defined callback function that the tree view and tree node can call whenever the relative order of two child items needs to be decided. The parameter SortProc is a pointer to the application defined callback function. The Data parameter is optional for passing a data value into the function.

The tree node's CustomSort will sort all child items of the node that called it. The tree view's CustomSort method will sort all items in the tree view.

The callback function receives two nodes for the items being compared and a third 32-bit value that you specify.

The callback function has the following form:

function CompareFunc(Node1, Node2: TTreeNode; ParamSort: Integer): Integer; stdcall;

The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent. The Node1 and Node2 parameters are the two items being compared.

If the parameter SortProc is nil, the default AlphaSort method is called. This can be useful since CustomSort has the Data parameter which AlphaSort doesn't.


Example

The following code orders a tree view in reverse alphabetical order on the click of a button. The callback function CustomSortProc calls the Windows API function lstrcmp and negates its return value.

function CustomSortProc(Node1, Node2: TTreeNode; ParamSort: integer): integer; stdcall;

begin

  Result := -lstrcmp(PChar(Item1.Text),  PChar(Item2.Text));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  TreeView1.CustomSort(@CustomSortProc, 0);

end;


See also

SortType property

AlphaSort method


CustomSort method for list views
CustomSort method

See also	Example

Applies to

TListView component

Declaration

function CustomSort(SortProc: TLVCompare; lParam: Longint): Boolean;

Description

The CustomSort method allows you to sort list items based on criteria that you define. When you use this method, you specify an application-defined callback function that the list view can call whenever the relative order of two list items needs to be decided. The parameter SortProc is a pointer to the application defined callback function. The lParam parameter is optional for passing a data value into the function.

The callback function receives the two items being compared and a third 32-bit value that you specify.

The callback function has the following form:

function CompareFunc(Item1, Item2: TListItem; ParamSort: Integer): Integer; stdcall;

The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent. The Item1 and Item2 parameters are the two items being compared.

If the parameter SortProc is nil, the default AlphaSort method is called. This can be useful since CustomSort has the lParam parameter that AlphaSort doesn't.


Example

The following code orders a list view in reverse alphabetical order on the click of a button. The callback function CustomSortProc calls the Windows API function lstrcmp and negates its return value.

function CustomSortProc(Item1, Item2: TListItem; ParamSort: integer): integer; stdcall;

begin

  Result := -lstrcmp(PChar(TListItem(Item1).Caption),

    PChar(TListItem(Item2).Caption));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListView1.CustomSort(@CustomSortProc, 0);

end;


See also

SortType property

AlphaSort method


Cut property

See also	Example

Applies to

TTreeNode object, TListItem component

Declaration

property Cut: Boolean;

Description

Run-time only. The Cut property determines if the item (TTreeNode object or TListItem object) is selected as part of a cut and paste operation. If the Cut is True, then the item has been selected as part of a cut and paste operation.


Example

The following example set the state of the selected item for cut and paste.

TreeView1.Selected.Cut := True;


See also

Selected property

Focused property


CutToClipboard method

See also	Example

Applies to

TDBEdit, TDBImage, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

procedure CutToClipboard;

Description

The CutToClipboard method deletes the text selected in the control and copies it to the Clipboard, replacing any text that exists there. If no text is selected, nothing is copied.

For database images, CutToClipboard deletes the image in the control and copies it to the Clipboard, replacing the contents of the Clipboard.


Example

The following method cuts the text the user selects in Memo1 to the Clipboard and pastes it from the Clipboard in an edit box control when the user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Memo1.CutToClipboard;

  Edit1.PasteFromClipboard;

end;


See also

Clear method

ClearSelection method

CopyToClipboard method

PasteFromClipboard method


Data property

See also	Example

Applies to

TTreeNode, TListItem object; TTOutlineNode component

Declaration

property Data: Pointer;

Description

Run-time only. The Data property specifies any data you want associated with an outline item, a tree node of a TTreeView control, or a list item of a TListView control.


Example

The following code is an example for an outline node. It creates a TBitmap and adds it to the Data of the selected outline item.

var

  Bitmap: TBitmap;

begin

  Bitmap := TBitmap.Create;

  Outline1.Items[Outline1.SelectedItem].Data := Bitmap;

end;


See also

GetDataItem method

Text property


Database property

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property Database: TDatabase;

Description

Run-time and read-only. Database specifies the database (TDatabase) component associated with the dataset component. If you did not create a TDatabase at design time, then Delphi will create one at run time. Use the Database property to reference the properties and methods of the database.


Example

{ Do a transaction }

with Table1.Database do

  begin

    StartTransAction;

  { Post some records with Table1 }

    Commit;

  end;


DatabaseCount property

See also	Example

Applies to

TSession component

Declaration

property DatabaseCount: Integer;

Description

Run-time and read-only. DatabaseCount is the number of TDataBase components currently attached to the Session.


Example

{ Close all databases }

var

  i: integer;

begin

  with Session do

  for i:= 0 to DatabaseCount - 1 do

    Databases[I].Close;


See also

Databases property

Session variable


DatabaseError procedure

Example

Unit

DB

Declaration

procedure DatabaseError(const Message: string);

Description

The DatabaseError procedure creates and raises the EDatabaseError exception object, using Message as the text for the exception.


Example

{ Test for an error and raise an exception if so }

if { some error has occured } then DatabaseError('Some error has occured');


DatabaseName property

Applies to

TDataBase, TQuery, TStoredProc, TTable components

Description

DatabaseName for Database Components

DatabaseName for Tables, Queries, and Stored Procedures


DatabaseName property

Example

Applies to

TDataBase component

Declaration

property DatabaseName: TFileName;

Description

Set the DatabaseName property to define an application-specific alias. Dataset components can reference this name instead of a BDE alias, directory path, or database name. In other words, this is the name of an application-specific alias defined by the dataset component that will show up in the DatabaseName drop-down list of TTable, TQuery, and TStoredProc components.

If you try to set DatabaseName of a TDatabase for which Connected is True, Delphi will raise an exception.


Example

Database1.DatabaseName := 'Delphi_Demos';


DatabaseName property

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property DatabaseName: TFileName;

Description

Set the DatabaseName property to specify the database to access. This property can specify:

A defined BDE alias,

A directory path for desktop database files,

An application-specific alias defined by a TDatabase component

Note:	Use the Close method to put a dataset in Inactive state before changing DatabaseName.


Example

{ Close the DBDataSet }

Table1.Active := False;

try

{ First try to use an alias }

  Table1.DatabaseName := 'Delphi_Demos';

  Table1.Active := True;

except

  on EDatabaseError do

{ If that fails, try to use the drive and directory }

    Table1.DatabaseName := 'c:\delphi\demos\database';

    Table1.Active := True;


See also

Active property


Databases property

See also	Example

Applies to

TSession component

Declaration

property Databases[Index: Integer]: TDatabase;

Description

Run-time and read-only. The Databases property holds a list of all of the currently active TDatabase components.


See also

DatabaseCount property

Session variable


DataField property

Example

Applies to

TDBCheckBox, TDBComboBox, TDBEdit, TDBImage, TDBListBox, TDBLookupComboBox, TDBLookupList, TDBMemo, TDBRadioGroup, TDBText components

Declaration

property DataField: string;

Description

The DataField property identifies the field from which the data-aware control displays data. The dataset the field is located in is specified in a data source component (TDataSource). The DataSource property of the data-aware control specifies which data source component.

If the DataField value of a database edit box (TDBEdit) is an integer or floating-point value, only characters that are valid in such a field can be entered in the edit box. Characters that are not legal are not accepted.


Example

The following code specifies that the DataField of DBEdit1 is 'FNAME'.

DBEdit1.DataField := 'FNAME';


DataModules property

See also

Applies to

TScreen object

Declaration

property DataModules[Index: Integer];

Description

The DataModules property maintains a list of all the data modules that are currently created in the application.


See also

DataModuleCount property


DataModuleCount property

See also

Applies to

TScreen object

Declaration

property DataModuleCount: Integer;

Description

The DataModuleCount property contains a count of all the data modules that are currently created in the application.


See also

DataModules property

FormCount property

ComponentCount property


DataSet property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDataSource, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TUpdateSQL, TVarBytesField, TWordField components

Description

DataSet for Field Components

DataSet for Data Sources

DataSet for TUpdateSQL Components


DataSet property

Example

Applies to

TDataSource component

Declaration

property DataSet: TDataSet

Description

DataSet specifies the dataset component (TTable, TQuery, and TStoredProc) that is providing data to the data source. Usually you set DataSet at design time with the Object Inspector, but you can also set it programmatically. The advantage of this interface approach to connecting data components is that the dataset, data source, and data-aware controls can be connected and disconnected from each other through the TDataSource component. In addition, these components can belong to different forms.


Example

DataSource1.DataSet := Table1; {get data from this form's Table1}

DataSource1.DataSet := Form2.Table1; {get data from Form2's Table1}


DataSet property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property DataSet: TDataSet;

Description

Run-time only. DataSet identifies the dataset to which a TField component belongs. Only assign a value to this property if you are programmatically creating TField component .


DataSet property

Applies to

TUpdateSQL component

Declaration

property DataSet: TDataSet;

Description

Run-time only. DataSet identifies the dataset to which a TUpdateSQL component belongs. Only assign a value to this property if you are programmatically creating a TUpdateSQL component.


DatasetCount property

See also	Example

Applies to

TDataBase component

Declaration

property DatasetCount: Integer;

Description

DatasetCount is the number of dataset components (TTable, TQuery, and TStoredProc) that are currently using the TDatabase component. Read-only and run-time only.


Example

{ Check to see if any record associated with this database has pending updates }

Changed := False;

with Database1 do

  for I := 0 to DatasetCount - 1 do

    Changed := Changed or DataSets[I].Modified;


See also

Datasets property


Datasets property

See also	Example

Applies to

TDataBase component

Declaration

property Datasets[Index: Integer]: TDBDataSet;

Description

Run-time and read-only. Datasets is the set of dataset components that are currently sharing the TDatabase component.


Example

{ Check to see if any record associated with this database has pending updates }

Changed := False;

with Database1 do

  for I := 0 to DatasetCount - 1 do

    Changed := Changed or DataSets[I].Modified;


See also

DatasetCount property


DataSize property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property DataSize: Word;

Description

Run-time and read-only. The value of DataSize is the number of bytes required to store the field in memory.

For TBoolean, TSmallint, and TWordField, the value is two bytes. For TDateField, TIntegerField, and TTimeField, the value is four bytes. For TCurrencyField, TDateTimeField, and TFloatField, the value is eight bytes. For TBCDField, the value is eighteen bytes. For TStringField, the value is the maximum size of the text plus one (not more than 255 characters). For TBlobField, TBytesField, TGraphicField, TMemoField, and TVarBytesField, the value is the size of the field as stored in the record buffer.


DataSource property

Applies to

TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupComboBox, TDBLookupList, TDBMemo, TDBNavigator, TQuery, TDBRadioGroup, TDBText components

Description

DataSource Property for Data-aware Controls

DataSource Property for Queries


DataSource property

See also	Example

Applies to

TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupComboBox, TDBLookupList, TDBMemo, TDBNavigator, TDBRadioGroup, TDBText components

Declaration

property DataSource: TDataSource;

Description

The DataSource property determines where the component obtains the data to display. Specify the data source component that identifies the dataset the data is found in.


Example

The following code specifies DataSource1 to be the DataSource of DBGrid1.

DBGrid1.DataSource := DataSource1;


See also

DataField property

SQL property


DataSource property

See also	Example

Applies to

TQuery component

Declaration

property DataSource: TDataSource;

Description

Set the DataSource property to the name of a TDataSource component in the application to assign values to parameters not bound to values programmatically with Params or ParamByName. If the unbound parameter names match any column names in the specified data source, Delphi binds the current values of those fields to the corresponding parameters. This capability enables applications to have linked queries.


Example

The LINKQRY sample application illustrates the use of the DataSource property to link a query in a master-detail form. The form contains a TQuery component (named Orders) with the following in its SQL property:

SELECT Orders.CustNo, Orders.OrderNo, Orders.SaleDate

   FROM Orders

   WHERE Orders.CustNo = :CustNo

The form also contains:

A TDataSource named OrdersSource, linked to Orders by its DataSet property.

A TTable component (named Cust).

A TDataSource named CustSource linked to Cust.

Two data grids; one linked to CustSource and the other to OrdersSource.

Orders' DataSource property is set to CustSource. Because the parameter :CustNo does not have any value assigned to it, at run time Delphi will try to match it with a column name in CustSource, which gets its data from the Customer table through Cust. Because there is a CustNo column in Cust, the current value of CustNo in the Cust table is assigned to the parameter, and the two data grids are linked in a master-detail relationship. Each time the Cust table moves to a different row, the Orders query automatically re-executes to retrieve all the orders for the current customer.


See also

SQL property


DataType property

Applies to

TFieldDef, TParam objects; All field components

Description

DataType for TFieldDef Objects

DataType for TParam Objects

DataType for Field Components


DataType property

Applies to

TFieldDef object

Declaration

property DataType: TFieldType;

Description

Run-time and read-only. Read DataType to determine a physical field's type. Possible values are those of the TFieldType type.


DataType property

Applies to

All field components

Declaration

property DataType: TFieldType;

Description

Run-time and read-only. DataType identifies the data type of the TField. Possible values are those of the TFieldType type.


DataType property

Example

Applies to

TParam object

Declaration

property DataType: TFieldType;

Description

The DataType property is the type of the parameter. Possible values are those of the TFieldType type.


Example

with Query1 do

  for I := 0 to ParamCount - 1 do

    if Params[I].DataType = ftUnknown then

      MessageDlg(Format('Parameter %d is undefined', [I]), mtWarning, [mbOK], 0);


DBHandle property

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property DBHandle: HDBIDB;

Description

Run-time and read-only. The DBHandle property lets an application make direct calls to the Borland Database Engine (BDE) API. Many BDE function calls require a database handle, which this property provides.

Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Example

This example uses the DBHandle property to make a call to the DbiGetDirectory BDE API function. Because it uses a BDE API function directly, you must add uses BDE; in the implementation section of the unit.

procedure TForm1.Button1Click(Sender: TObject);

var

  Directory: String;

begin

  SetLength(Directory, 250);

  if DbiGetDirectory(Table1.DBHandle, True, PChar(Directory)) <> dbiErr_None then

    MessageDlg('Error getting default directory', mtError, [mbOk], 0)

  else

    ShowMessage('Default directory = ' + Directory);

  if DbiGetDirectory(Table1.DBHandle, False, PChar(Directory)) <> dbiErr_None then

    MessageDlg('Error getting current working directory', mtError, [mbOk], 0)

  else

    ShowMessage('Current working directory = ' + Directory);

end;


DBIError procedure

Unit

DB

Declaration

procedure DBIError(ErrorCode: DBIResult);

Description

The DBIError procedure creates an error message by querying the Borland Database Engine for the last error number and text and calls DatabaseError passing the result. ErrorCode is used to obtain a text message from the engine if the error has already been cleared.


DBIResult type

Declaration

DBIResult: Word;

Description

DBIResult is used to specify a Borland Database Engine error code for the DBIError procedure.


DBLocale property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property DBLocale: TLocale;

Description

Run-time and read-only. The DBLocale property allows you to make direct calls to the Borland Database Engine using this specification of the language driver. Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


DBSession property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property DBSession: TSession;

Description

Run-time and read-only. The DBSession property returns the session associated with this data set. If you've indicated that a certain session is to be used by setting the SessionName property, that session is returned. Otherwise, it returns the session linked to the database associated with this data set. If it's not a valid session, DBSession returns the global Session variable.


DDEConv property

See also	Example

Applies to

TDDEClientItem component

Declaration

property DdeConv: TDdeClientConv;

Description

The DDEConv property specifies the DDE client conversation component to associate with the DDE client item component. The value of DDEConv is the name of the DDE client conversation component that defines the DDE conversation.


Example

The following code specifies DDEClientConv1 as the conversation of DDEClientItem1.

DDEClientItem1.DDEConv := DDEClientConv1.


See also

Name property


DdeFmt property

Applies to

TDdeClientConv component

Declaration

property DdeFmt: Integer;

Description

Run-time and read-only. The DdeFmt property contains an integer value representing the standard clipboard format used for submitting or requesting a data item.


DDEItem property

See also	Example

Applies to

TDDEClientItem component

Declaration

property DDEItem: string;

Description

The DDEItem property specifies the item of a DDE conversation. The value of DDEItem depends on the linked DDE server application. DDEItem is typically a selectable portion of text, such as a spreadsheet cell or a database field in an edit box. If the DDE server is a Delphi application, DDEItem is the name of the linked DDE server component. For example, to link to a DDE server component named DDEServer1, set DDEItem to 'DDEServer1'.

See the documentation for the DDE server application for the specific information about specifying DDEItem.

At design time, you can specify DDEItem either by typing the item string in the object inspector or by pasting a link using the DDE Info dialog box, which appears if you click the ellipsis (...) button for DDEService or DDETopic in the Object Inspector. After you choose Paste Link in the DDE Info dialog box, you can choose the item from a list of possible items for DDEItem in the object inspector if link information is still on the Clipboard.


Example

The following code specifies a DDE item of 'DDEServer1'.

DDEClientItem1.DDEItem := 'DDEServer1';


See also

DDEService property

DDETopic property


DDEService property

See also	Example

Applies to

TDDEClientConv component

Declaration

property DDEService: string;

Description

The DDEService property specifies the DDE server application to be linked to a DDE client. Typically, DDEService is the file name (and path, if necessary) of the DDE server application's main executable file without the .EXE extension. If the DDE server is an Delphi application, DDEService is the project name without the .DPR or .EXE extension. For example, to link to a TDDEServerConv component in PROJ1.DPR, set DDEService to 'PROJ1'.

See the documentation for the DDE server application for the specific information about specifying DDEService.

At design time, you can specify DDEService either by typing the DDE server application name in the object inspector or by choosing Paste Link in the DDE Info dialog box.


Example

The following code specifies a DDE service of 'Project1'.

DDEClientConv1.DDEService := 'Project1';


See also

DDEItem property

DDETopic property


DDETopic property

See also	Example

Applies to

TDDEClientConv component

Declaration

property DDETopic: string;

Description

The DDETopic property specifies the topic of a DDE conversation. Typically, DDETopic is a filename (and path, if necessary) used by the application specified in DDEService. If the DDE server is an Delphi application, by default DDETopic is the caption of the form containing the linked component. For example, to link to a component on a form named Form1, set DDETopic to 'Form1'. However, if the DDE client is linked to a TDDEServerConv component, DDETopic is the name of the server conversation component instead of the form caption. For example, to link to DDEServerConv1, set DDETopic to 'DDEServerConv1'.

See the documentation for the DDE server application for the specific information about specifying DDETopic.

At design time, you can specify DDETopic either by typing the DDE server application name in the object inspector or by choosing Paste Link in the DDE Info dialog box.


Example

The following code specifies a DDE topic of 'Form1'.

DDEClientConv1.DDETopic := 'Form1';


See also

DDEItem property


DefAttributes property

See also	Example

Applies to

TRichEdit component

Declaration

property DefAttributes: TTextAttributes;

Description

Run-time only. The DefAttributes property contains a description of the attributes of the default text, meaning text in the rich edit up to text with specified attributes.

DefAttributes applies to newly inserted text, only if the current selection is empty. For example, text is considered default text if it is not specially formatted, and then, only if it is inserted before the point in the rich edit where other text is specially formatted. Once text has special formatting, no selection of text that follows the formatted selection is considered default, even if it has the same attributes as the default text.

If the current selection is not empty, any newly typed text will be formatted according to the text that it replaces. To determine the character formatting information of the selected text use the SelAttributes property. DefAttributes and SelAttributes are both of type TTextAttributes.


Example

The following example changes the default attributes of text in the rich edit control when the user clicks on the button. Text will become red, underlined, and of size 20.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with RichEdit1.DefAttributes do

  begin

    Color := clRed;

    Style := [fsUnderLine];

    Size := 20;

  end;

end;


See also

ConsistentAttributes property

OnSelectionChange event

Paragraph property

PlainText property

SelAttributes property


Default property

Applies to

TBitBtn, TButton, TMenuItem components

Description

There are two different VCL properties called Default.

Default property for buttons

Default property for menu items


Default property for buttons
DefaultProperty

See also	Example

Applies to

TBitBtn, TButton components

Declaration

property Default: Boolean;

Description

The Default property indicates whether a push or bitmap button is the default button. If Default is True, any time the user presses Enter, the OnClick event handler for that button runs. The only exception to this is if the user selects another button before pressing Enter, in which case the OnClick event handler for that button runs. Although your application can have more than one button designated as a default button, the form calls the OnClick event handler for the first button in the tab order.

Whenever any button has focus, it becomes the default button temporarily. When the focus moves to a control that isn't a button, the button with its Default property set to True becomes the default button once again.


Example

This example makes the button named OK the default button:

procedure TForm1.FormCreate(Sender: TObject);

begin

  OK.Default := True;

end;


See also

Cancel property


Default property for menu items
Default property

Applies to

TMenuItem components

Declaration

property Default: Boolean;

Description

The Default property the determines whether the menu item is bold and whether the menu item will be invoked when the parent item is double clicked. The default value is False.

Note:	The Default property will only work under Windows 95 and under Windows NT 3.51 if the "new shell" has been installed.


DefaultAlignment method

Applies to

TColumn, TColumnTitle objects

Description

DefaultAlignment method for columns

DefaultAlignment method for column titles


DefaultAlignment method for columns
DefaultAlignment method

See also

Applies to

TColumn objects

Declaration

function DefaultAlignment: TAlignment;

Description

Returns the default alignment of data shown in a column of a TDBGrid component. If the column has a field object associated with it, DefaultAlignment returns its Alignment property; otherwise, it returns taLeftJustify.


See also

DefaultColor method

DefaultFont method

DefaultReadOnly method

DefaultWidth method


DefaultAlignment method for column titles
DefaultAlignment method

See also

Applies to

TColumnTitle objects

Declaration

function DefaultAlignment: TAlignment;

Description

Returns the default alignment of the title of a column in a TDBGrid component. By default, the title is left-aligned.


See also

DefaultCaption method

DefaultColor method

DefaultFont method


DefaultCaption method

See also

Applies to

TColumnTitle object

Declaration

function DefaultCaption: string;

Description

Returns the default caption for the title of a column in a TDBGrid component. If there's a field object associated with this column, its DisplayName property is used as the default caption. Otherwise, the column object's FieldName property is used as the default caption.


See also

DefaultAlignment method

DefaultColor method

DefaultFont method


DefaultColor method

Applies to

TColumnTitle, TColumn objects

Description

DefaultColor method for columns

DefaultColor method for column titles


DefaultColor method for columns
DefaultColor method

See also

Applies to

TColumn object

Declaration

function DefaultColor: TColor;

Description

Returns the default background color of data shown in a column of a TDBGrid component. This color is the same as the grid's Color property.


See also

DefaultAlignment method

DefaultFont method

DefaultReadOnly method

DefaultWidth method


DefaultColor method for column titles
DefaultColor method

See also

Applies to

TColumnTitle object

Declaration

function DefaultColor: TColor;

Description

Returns the default background color of the title of a column in a TDBGrid component. This color is the same as the grid's FixedColor property.


See also

DefaultAlignment method

DefaultCaption method

DefaultFont method


DefaultColWidth property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property DefaultColWidth: Integer;

Description

The DefaultColWidth property determines the width of all the columns within the grid.

If you want to change the width of a single column within a grid without changing other columns, use the ColWidths property during run time. If you change the DefaultColWidth property value after changing the width of specified columns, all the columns become the height specified in the DefaultColWidth property once again.

The default value is 64 pixels.


Example

The following line of code changes the default width of the columns in a string grid to twice the original value:

StringGrid1.DefaultColWidth := StringGrid1.DefaultColWidth * 2;


See also

ColWidth property

DefaultRowHeight property


DefaultDrawing property

See also	Example

Applies to

TDBGrid, TDrawGrid, TStringGrid components

Declaration

property DefaultDrawing: Boolean;

Description

The DefaultDrawing property determines if the cell is painted and the item it contains is drawn automatically. If True, the default drawing occurs. If False, your application must handle all the drawing details in the OnDrawCell event handler, or in the OnDrawDataCell event handler for the data grid.

When DefaultDrawing is True, the Paint method initializes the Canvas' font and brush to the control font and the cell color. The cell is prepainted in the cell color and a focused TRect object is drawn in the cell. The state of the cell is returned. The possible states are a fixed cell, a focused cell, or a cell within the area the user has selected.


Example

The following code sets DefaultDrawing to False for DrawGrid1.

DrawGrid1.DefaultDrawing := False;


See also

OnDrawCell event

OnDrawDataCell event


DefaultExt property

See also	Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property DefaultExt: TFileExt;

Description

The DefaultExt property specifies the extension that is added to the file name the user types in the File Name edit box if the user doesn't include a file-name extension in the filename. If the user specifies an extension for the filename, the value of the DefaultExt property is ignored. If the DefaultExt value remains blank, no extension is added to the filename entered in the File Name edit box.

Legal property values include strings up to 3 characters in length. Don't include the period (.) that divides the filename and its extension.


Example

This example sets the default file extension to TXT, displays the Open dialog box, then assigns the filename the user selects with the dialog box to a variable the application can use to open a file:

procedure TForm1.Button1Click(Sender: TObject);

var

  NameOfFile : TFileName;

begin

  OpenDialog1.DefaultExt := 'TXT';

  if OpenDialog1.Execute then

    NameOfFile := OpenDialog1.FileName;

end;

When this code runs, if the user types a filename in the File Name edit box in the Open dialog box, but doesn't specify an extension, the TXT extension is added to the filename, and the entire filename is saved in the NameOfFile variable. For example, if the user types MYNOTES as the filename, the string saved in the NameOfFile variable is MYNOTES.TXT.


See also

FileName property

TOpenDialog component

TSaveDialog component


DefaultFont method

See also

Applies to

TColumnTitle objects

Declaration

function DefaultFont: TFont;

Description

Returns the default font used to display the title of a column in a TDBGrid component. The default font is the same as the grid's TitleFont property.


See also

DefaultAlignment method

DefaultCaption method

DefaultColor method

TitleFont property


DefaultReadOnly method

See also

Applies to

TColumn object

Declaration

function DefaultReadOnly: Boolean;

Description

Returns the default read-only setting for data in a column of a TDBGrid component. The default read-only setting is False.


See also

DefaultAlignment method

DefaultColor method

DefaultFont method

DefaultWidth method


DefaultRowHeight property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property DefaultRowHeight: Integer;

Description

The DefaultRowHeight property determines the height of all the rows within the grid. The default value is 24 pixels.

If you want to change the height of a single row within a grid without changing other rows, use the RowHeights property during run time. If you change the DefaultRowHeight property value after changing the height of specified rows, all the rows become the height specified in the DefaultRowHeight property once again.


Example

The following line of code changes the default height of the rows in a string grid control to 10 pixels more than the original value:

StringGrid1.DefaultRowHeight := StringGrid1.DefaultRowHeight + 10;


See also

DefaultColWidth property

RowHeights property


DefaultWidth method

See also

Applies to

TColumn object

Declaration

function DefaultWidth: Integer;

Description

Returns the default width of a column in a TDBGrid component. The default column width is based on several factors. If you create a field object using the Fields editor, the field's DisplayWidth property is used to calculate the width in pixels. If the grid has a title row and the width of the column title is bigger than that of DisplayWidth, the title width becomes the default column width.


See also

DefaultAlignment method

DefaultColor method

DefaultFont method

DefaultReadOnly method


DefocusControl method

Example

Applies to

TForm

Declaration

procedure DefocusControl(Control: TWinControl; Removing: Boolean);

Description

The DefocusControl procedure removes focus from a control if it has focus.  Control is the control from which to remove focus. If Removing is True and the control has focus, DefocusControl sets the focus to the control's parent.  If the control is the form's active control, DefocusControl sets the ActiveControl property of the form to nil.


Example

The following example removes the focus from Button1 on Form1:

procedure Button1Click(Sender: Tobject);

begin

  DefocusControl(TWinControl(Sender), False);

  if GetFocus = Handle then

    ShowMessage('The form now has focus.');

end;


See also

FocusControl method


Delete method

Applies to

TImageList, TList, TStringList, TStrings, TTreeNode, TTreeNodes objects; TMenuItem, TOutline, TQuery, TTable components

Description

The Delete method removes an item from an object or component.

Delete Method for List and String Objects and Menu Items

Delete Method for Outlines

Delete Method for Tables and Queries

Delete Method for Tree Node Objects

Delete Method for Tree Nodes Objects

Delete Method for Image List Objects

Delete Method for List Item Objects

Delete Method for List Items Objects


Delete method

See also	Example

Applies to

TTreeNodes objects

Declaration

function Delete(Node: TTreeNode);

Description

The Delete method removes the item (TTreeNode object) in the tree view specified by the Node paramter.


Example

The following example deletes the item at the point X, Y in the tree view when the user clicks a button on an item in the tree view.

procedure TForm1.TreeView1MouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

var

  HT : THitTests;

begin

  if (CheckBox1.Checked and (Sender is TTreeView)) then

    begin

      HT := TreeView1.GetHitTestInfoAt(X,Y);

      if (htOnItem in HT) then

        TreeView1.Items.Delete(TreeView1.GetNodeAt(X,Y));

    end;

end;


See also

DeleteChildren method

OnDeletion event

Deleting property

MoveTo method


Delete method for list and string objects and menu items
Delete method

See also	Example

Applies to

TList, TStringList, TStrings objects; TMenuItem component

Declaration

Procedure Delete(Index: Integer);

Description

The Delete method removes the item specified with the Index parameter. The item can be deleted from

the list of a list object

the strings and their associated objects of a string or string list object

a menu

In all cases, the index is zero-based, so the first item has an Index value of 0, the second item has an Index value of 1, and so on.

If a string is deleted from a string object, the reference to its associated object is also deleted.

If the item deleted is a menu item that has a submenu, the submenus are also deleted.

If the item is deleted in a list object, the list contains a nil value in the item's position in the list.


Example

FileMenu in the following code is a menu that contains four menu items (menu commands). They are New, Open, Save, and Save As, in that order. This event handler deletes the Save command from the menu:

procedure TForm1.Button1Click(Sender: TObject);

begin

  FileMenu.Delete(2);

end;

This example uses a list box and a button on a form. When the form appears, five items are in the list box. When the user clicks the button, the second item in the list box is deleted:

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  for I := 1 to 5 do

    ListBox1.Items.Add('Item ' + IntToStr(I));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Delete(1);

end;


See also

Add method for list objects

Add method for string and string list objects

Add method for menu items

Clear method

Insert method

Remove method


Delete method

See also	Example

Applies to

TOutline object

Declaration

procedure Delete(Index: LongInt);

Description

The Delete method removes the outline item with an Index property value equal to the Index parameter from the list outline. If that item has subitems, the subitems are also deleted.

Outline items that appear after the deleted item are moved up and reindexed with valid Index values. This is done automatically unless BeginUpdate has been called.


Example

The following code deletes the selected item from Outline1.

Outline1.Delete(Outline1.SelectedItem);


See also

Add method

AddChild method

Insert method


Delete method for tree node objects
Delete method

Applies to

TQuery, TTable components

Declaration

procedure Delete;

Description

The Delete method deletes the current record from the dataset. The next record then becomes the new current record. If the record deleted was the last record in the dataset, then the previous record becomes the current record.

This method is valid only for datasets that return a live result set.


Delete method for tree node objects
Delete method

See also

Applies to

TTreeNode object

Declaration

procedure Delete;

Description

The Delete method deletes the item (TTreeNode object) that calls it.


See also

DeleteChildren method

Deleting property

OnDeletion event


Add method for image list objects
Delete method

See also

Applies to

TImageList object

Declaration

procedure Delete(Index: Integer);

Description

The Delete method deletes a particular image from the image list.


See also

Clear method


Delete method for list items objects
Delete method

See also	Example

Applies to

TListItems object

Declaration

procedure Delete(Index: Integer);

Description

The Delete method removes the item (TListItem object) in the list view specified with the Index parameter. The index is zero-based, so the first item has an index of 0, the second item has an index on 1, and so on.


Example

The following example deletes the item in the list view that has an index of 1.

ListView1.Items.Delete(1);


See also

Index property, Items property, OnDeletion event


Delete method for list items objects
Delete method

See also

Applies to

TListItem object

Declaration

procedure Delete;

Description

The Delete method for the list item deletes the calling list item.


See also

Items property

OnDeletion event


DeleteAlias method

See also

Applies to

TSession component

Declaration

procedure DeleteAlias(const Name: string);

Description

The DeleteAlias method removes the alias with the specified name from the session. If the alias you deleted was permanent, call SaveConfigFile to save the deletion to the BDE configuration file.


See also

AddAlias method

AddStandardAlias method

ModifyAlias method

Session variable

ConfigMode property


DeleteChildren method for tree node objects
DeleteChildren method

See also	Example

Applies to

TTreeNode object

Declaration

procedure DeleteChildren;

Description

The DeleteChildren method deletes all children of the item (TTreeNode object) that calls it.


Example

The following example deletes all child items of the selected item in TreeView1.1.

TreeView1.Selected.DeleteChildren;


See also

Delete method

Deleting property

OnDeletion event


DeleteIndex method

See also	Example

Applies to

TTable component

Declaration

procedure DeleteIndex(const Name: string);

Description

The DeleteIndex method deletes a secondary index for a TTable. Name is the name of the index. You must have opened the table with exclusive access (Exclusive = True).


Example

Table1.DeleteIndex('NewIndex');


See also

AddIndex method


DeleteSQL property

Applies to

TUpdateSQL component

Declaration

property DeleteSQL: TStrings;

Description

The DeleteSQL property returns the string list containing the SQL statement to be used when applying the cached deletion of a record. Generally, such an SQL statement would be an DELETE FROM statement. You can use the UpdateSQL Editor (by double-clicking the TUpdateSQL component) to generate an appropriate SQL statement, such as the following:

delete from "COUNTRY.DB"

where

  Name = :OLD_Name


DeleteTable method

Example

Applies to

TTable component

Declaration

procedure DeleteTable;

Description

The DeleteTable method deletes an existing database table. Before calling this method, the DatabaseName, TableName and TableType properties must be assigned values. The table must be closed.


Example

with Table1 do

begin

  Active := False;

  DatabaseName := 'DBDEMOS';

  TableName := 'Customer';

  TableType := ttParadox;

  DeleteTable;

end;


Deleting property

See also

Applies to

TTreeNode object

Declaration

property Deleting: Boolean;

Description

Run-time and read-only. The Deleting property for a tree node indicates that an item's Destroy method has been called and is in the process of being deleted.


See also

Delete method

DeleteChildren method

OnDeletion event


Deleting property for tree nodes
Description property

See also

Applies to

TMetafile object

Declaration

property Description: String;

Description

Run-time and read-only. The Description property is the optional text description embedded in the metafile. You can set the CreatedBy and Description strings of a new metafile by calling TMetafileCanvas' CreateWithComment.


See also

CreatedBy property

CreateWithComment method


DescriptionsAvailable method

See also	Example

Applies to

TStoredProc component

Declaration

function DescriptionsAvailable: Boolean;

Description

The DescriptionsAvailable method indicates whether stored procedure parameter information is available from the server. If the information is available, it returns True. Otherwise, it returns False. Different servers may require additional information to obtain the parameter information. If DescriptionsAvailable returns False, you will have to specify parameters either with the Parameters Editor or with explicit code.


Example

if not StoredProc1.DescriptionsAvailable then

  begin

  { Build the Parameters property explicitly }

  end;


See also

Overload property

StoredProcName property


Destination property

Example

Applies to

TBatchMove component

Declaration

property Destination: TTable;

Description

Destination specifies a TTable component corresponding to the database table that will be the destination of the batch move operation. The destination table may or may not already exist.


Example

BatchMove1.Destination := Table1;


Destroy method

See also

Applies to

All objects and components

Declaration

destructor Destroy;

Description

The Destroy method destroys the object, component, or control and releases the memory allocated to it.

You seldom need to call Destroy. Objects designed with Delphi create and destroy themselves as needed, so you don't have to worry about it. If you construct an object by calling the Create method, you should call Free to release memory and dispose of the object. Free checks to see if the pointer is nil before calling Destroy and is also more efficient in code size.


See also

Free method

Release method


Device property

See also	Example

Applies to

TFontDialog component

Declaration

property Device: TFontDialogDevice;

Description

The Device property selects the device from which to retrieve the list of available fonts (screen or printer) . These are the possible values:

Value	Meaning

fdScreen	Retrieve from the screen

fdPrinter	Retrieve from the printer

fdBoth	Retrieve from both the screen and the printer


Example

This example lets the user select a font to use for printing a file:

procedure TForm1.Button1Click(Sender: TObject);

var

  FontName: TFont;

begin

  FontDialog1.Device := fdPrinter;

  FontDialog1.Execute;

  FontName := FontDialog1.Font;

end;


See also

TFont object


DeviceID property

Example

Applies to

TMediaPlayer component

Declaration

property DeviceID: Word;

Description

Run-time and read-only. The DeviceID property specifies the device ID for the currently open multimedia device.

The value of DeviceID is determined when an device is opened with the Open method. If no device is open, DeviceID is 0.


Example

The following code opens MediaPlayer1 and displays the DeviceID in Edit1. If an exception occurs, a message window displays the error number and string.

procedure TForm1.BitBtn1Click(Sender: TObject);

var

  MyErrorString: string;

begin

  try

    MediaPlayer1.Open;

    Edit1.Text := IntToStr(MediaPlayer1.DeviceID);

  except

    MyErrorString := 'ErrorCode: ' + IntToStr(Error) + #13#10;

    MessageDlg(MyErrorString + MediaPlayer1.ErrorMessage, mtError, [mbOk], 0);

  end;

end;


DeviceType property

Example

Applies to

TMediaPlayer component

Declaration

property DeviceType: TMPDeviceTypes;

Description

The DeviceType property specifies a multimedia device type to open with the Open method. The default is dtAutoSelect. The valid values for DeviceType are dtAutoSelect, dtAVIVideo, dtCDAudio, dtDAT, dtDigitalVideo, dtMMMovie, dtOther, dtOverlay, dtScanner, dtSequencer, dtVCR, dtVideodisc, or dtWaveAudio.

If DeviceType is dtAutoSelect, the device type is determined by the file extension specified in the FileName property. If no device type is associated with the extension, you must explicitly specify the correct device type by setting DeviceType to a value other than dtAutoSelect.

A multimedia device is typically associated with an appropriate file-name extension when you install the device. Associations are specified in the registry or SYSTEM.INI file. See the documentation for your specific device for instructions about how to associate file-name extensions with the device.


Example

The following code checks to make sure that a filename is specified for MediaPlayer1 if the DeviceType is set to dtAutoSelect before opening the device.

procedure TForm1.FormCreate(Sender: TObject);

begin

  with MediaPlayer1 do

    if (DeviceType = dtAutoSelect) and (FileName = '') then

      MessageDlg('You must specify a filename for the MediaPlayer', mtError, [mbOk], 0)

    else

      Open;

end;


Directory property

See also	Example

Applies to

TDirectoryListBox, TFileListBox components

Declaration

property Directory: string;

Description

The value of the Directory property determines the current directory for the file list box and directory list box components. The file list box displays the files in the directory specified in the Directory property. The directory list box displays the value of the Directory property as the current directory in the list box.

Examine the example to see how a directory list box and a file list box can work together through their Directory properties.


Example

If you have a file list box and a directory list box on a form, this code changes the current directory in the directory list box and displays the files in that directory in the file list box when the user changes directories using the directory list box:

procedure TForm1.DirectoryListBox1Change(Sender: TObject);

begin

  FileListBox1.Directory := DirectoryListBox1.Directory;

end;


See also

DirLabel property

Drive property

FileList property


DirectoryExists function

See also	Example

Unit

FileCtrl

Declaration

function DirectoryExists(Name: string): Boolean;

Description

The DirectoryExists function determines whether the directory specified as the value of the Name parameter exists. If the directory exists, the function returns True. If the directory does not exist, the function returns False.

If only a directory name is entered as the value of Name, DirectoryExists searches for the directory within the current directory. If a full path name is entered, DirectoryExists searches for the directory along the designated path.


Example

This example uses an edit box, a label, and a button on a form. When the user enters a directory name in the edit box and clicks the button, whether or not the directory exists is reported in the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if DirectoryExists(Edit1.Text) then

    Label1.Caption := Edit1.Text + ' exists'

  else

    Label1.Caption := Edit1.Text + ' does not exist';

end;


See also

ForceDirectories procedure

SelectDirectory function


DirLabel property

See also	Example

Applies to

TDirectoryListBox component

Declaration

property DirLabel: TLabel;

Description

The DirLabel property provides a simple way to display the current directory as the caption of a label control. When the current directory changes in the directory list box, the change is reflected in the caption of the label.

Specify the label you want updated with the current directory as the value of the DirLabel property.


Example

This example uses a button, an edit box, a label, a drive combo box, a directory list box, a file list box, and a filter combo box on a form. When the user clicks the button, the rest of the controls of the form begin working together like the controls in an Open or Save dialog box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DriveComboBox1.DirList := DirectoryListBox1;

  DirectoryListBox1.FileList := FileListBox1;

  DirectoryListBox1.DirLabel := Label1;

  FileListBox1.FileEdit := Edit1;

  FilterComboBox1.FileList := FileListBox1;

end;


See also

Caption property

Directory property

DirList property

FileEdit property

FileList property


DirList property

See also	Example

Applies to

TDriveComboBox component

Declaration

property DirList: TDirectoryListBox;

Description

The DirList property provides a simple way to connect a drive combo box with a directory list box. When a new drive is selected in the drive combo box, the specified directory list box updates to display the directory structure and the current directory on the new drive.

Specify the directory list box you want updated as the value of DirList.


Example

This example uses a button, an edit box, a label, a drive combo box, a directory list box, a file list box, and a filter combo box on a form. When the user clicks the button, the rest of the controls of the form begin working together as the controls in an open or save dialog box do.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DriveComboBox1.DirList := DirectoryListBox1;

  DirectoryListBox1.FileList := FileListBox1;

  DirectoryListBox1.DirLabel := Label1;

  FileListBox1.FileEdit := Edit1;

  FilterComboBox1.FileList := FileListBox1;

end;


See also

Directory property

DirLabel property

Drive property

FileEdit property

FileList property


DisableControls method

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure DisableControls;

Description

The DisableControls method temporarily disconnects the dataset from all TDataSource components. While the data sources are disconnected, associated data-aware controls will not reflect changes to datasets. When iterating over a dataset with Next or Prior methods, calling DisableControls first will speed the process, eliminating the need to update the screen each time.

Use EnableControls to restore the connection. The dataset maintains a count of the number of calls to DisableControls and EnableControls, so only the last call to EnableControls will actually update the data sources.


Example

with Table1 do

  begin

  DisableControls;

{ Move forward five records }

  try

    for I := 1 to 5 do Next;

  finally

{ Update the controls to the current record }

    EnableControls;

  end;


Display property

See also	Example

Applies to

TMediaPlayer component

Declaration

property Display: TWinControl;

Description

The Display property specifies the display window for an multimedia device that uses a window for output. Assign the name of a windowed control such as a form or panel to Display to display output in that control.

The default value of Display is nil. If the value of Display is nil, the device creates its own window to display output. Also, if you Free the control assigned to Display after the device has been opened, video output will be in its own default window.

Examples of multimedia devices that use a window to display output are Animation, AVI Video, Digital Video, Overlay, and VCR.


Example

The following example displays the .AVI video file 'FOOTBALL.AVI'  in the client area of Form2.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do

  begin

    FileName := 'football.avi';

    Open;

    Display := Form2;

    Form2.Show;

    Play;

  end;

end;


See also

Capabilities property

DeviceType property

DisplayRect property

Open method


DisplayFormat property

See also

Applies to

TDateField, TDateTimeField, TIntegerField, TSmallintField, TTimeField, TWordField, TBCDField, TCurrencyField, TFloatField components

Declaration

property DisplayFormat: string

Description

The DisplayFormat property is used to format the value of the field for display purposes.

For TIntegerField, TSmallintField, and TWordField, formatting is performed by FloatToTextFmt. If DisplayFormat is not assigned a string, the value is formatted by Str.

For TDateField, TDateTimeField, and TTimeField, formatting is performed by DateTimeToStr. If DisplayFormat is not assigned a string, the value is formatted according to the default Windows specifications in the [International] section of the WIN.INI file.

For TBCDField, TCurrencyField, and TFloatField, formatting is performed by FloatToTextFmt. If DisplayFormat is not assigned a string, the value is formatted according to the value of the Currency property.


See also

FmtStr procedure

Format function

FormatBuf function

FormatDateTime function

FormatFloat

StrFmt function

StrLFmt function


DisplayLabel property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property DisplayLabel: string;

Description

DisplayLabel contains the column heading for a field displayed by a TDBGrid component. If DisplayLabel is null, the FieldName property is used to supply the column heading.


DisplayName property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property DisplayName: Pstring;

Description

Run-time and read-only. DisplayName returns the name of the field for display purposes. Use DisplayName in your code to use the same algorithm that other Delphi components use when they need the DisplayLabel or FieldName of a field.


DisplayRect property

Applies to

TMediaPlayer, TTabControl components

Description

DisplayRect property for media players

DisplayRect property for tab controls


DisplayRect property for media players
DisplayRect property

See also	Example

Applies to

TMediaPlayer component

Declaration

property DisplayRect: TRect;

Description

Run-time only. The DisplayRect property specifies the rectangle area within the form specified in the Display property used to display output from a multimedia device. DisplayRect is ignored if Display is nil.

Assign a TRect record to DisplayRect to display output in a specific rectangle area on a form. The Rect function can be used to create a TRect record.

Examples of multimedia devices that use a window to display output are Animation, AVI Video, Digital Video, Overlay, and VCR.

Media that use a rectangle to display output usually perform best if the default DisplayRect size is used. To set DisplayRect to the default size, use 0, 0 for the lower right corner. Position the rectangle with the upper left corner.

Note:	You must set DisplayRect after the media device is opened.


Example

The following example positions the upper left corner of the display rectangle to 10, 10 and uses the default display size:

MediaPlayer1.DisplayRect := Rect(10, 10, 0, 0);


See also

Capabilities property

DeviceType property

Open method


DisplayRect property for tab controls
DisplayRect property

Applies to

TTabControl component

Declaration

property DisplayRect: TRect;

Description

Run-time and read-only. The DisplayRect property is used to determine the size (in pixels) of a tab control client area. DisplayRect returns the Top, Bottom, Left, and Right coordinates in one record of type TRect.


DisplayRect method

Applies to

TListItem, TTreeNode objects

Description

DisplayRect method for tree node objects

DisplayRect method for list item objects


DisplayRect method for tree node objects
DisplayRect method

See also

Applies to

TTreeNode objects

Declaration

function DisplayRect(TextOnly: Boolean): TRect;

Description

The DisplayRect method returns the bounding rectangle (TRect record) for a tree-view item (TTreeNode). If the TextOnly parameter is True, the bounding rectangle includes only the text of the item. Otherwise, it includes the entire line that the item occupies in the tree-view control.


See also

Text property


DisplayRect method for list item objects
DisplayRect method

See also

Applies to

TListItem object

Declaration

function DisplayRect(Code: TDisplayCode): TRect;

Description

The DisplayRect method returns the bounding rectangle (TRect record) for a list view item (TListItem). The Code parameter specifies the display type when retrieving the bounding rectangle for all or part of an item in the list view. These are the possible values for the Code parameter.

Value	Meaning

drBounds	Returns the bounding rectangle of the entire list item, including the icon and label.

drIcon	Returns the bounding rectangle of the icon or small icon

drLabel	Returns the bounding rectangle of the item text

drSelectBounds	Returns the union of the icon and label rectangles, but excludes columns in details view


See also

Caption property

BoundingRect property


DisplayText property

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property DisplayText: string;

Description

Run-time and read-only. The string value for the field when it is displayed in a data-aware control that is not in Edit mode. Data-aware controls such as TDBEdit rely on DisplayText to provide the formatting for each field.

The default string depends on a field's data type. You can control the strings returned by DisplayText by specifying a DisplayFormat string or by providing an OnGetText event handler.

For a TStringField, the contents of the field is formatted using the EditMask property.

For a TIntegerField, TSmallintField, or TWordField, if DisplayFormat has been assigned a value, FloatToTextFmt is called with it; otherwise Str is called.

For a TFloatField or TBCDField, FloatToTextFmt is called with the DisplayFormat property.

For a TCurrencyField, if DisplayFormat has been assigned a value, FloatToTextFmt is called with it; otherwise, FloatToTextFmt is called with the ffCurrency flag and CurrencyDecimals variable.

For a TDateTimeField, DateTimeToStr is called with the DisplayFormat property. For a TDateField, DateTimeToStr is called with the DisplayFormat property, except that the ShortDateFormat variable will be substituted if DisplayFormat is unassigned. For a TTimeField, DateTimeToStr is called with the DisplayFormat property, except that the LongTimeFormat variable will be substituted if DisplayFormat is unassigned.


Example

The following code displays a message that the current value is invalid:

  MessageDlg(Field1.DisplayText + ' is invalid', mtWarning, [mbOK], 0);


DisplayValue property

See also	Example

Applies to

TDBLookupComboBox, TDBLookupList components

Declaration

property DisplayValue : string;

Description

Run-time only. The DisplayValue is the string that appears in the database lookup combo box or database lookup list box. Its value is contained in the field specified as the LookupDisplay field. The current value of the Value property, which determines the current record in the lookup table, also determines which string is the DisplayValue string.


Example

The following code makes the caption of a button equal to the DisplayValue of DBLookupCombo1.

Button1.Caption := DBLookupCombo1.DisplayValue;


See also

LookupField property


DisplayValues property

Example

Applies to

TBooleanField component

Declaration

property DisplayValues: string;

Description

DisplayValues controls the manner in which the TBooleanField is translated to and from display format. Set DisplayValues to 'T;F' to use 'T' and 'F' for values of True and False. You can use any pair of phrases you want, separated by a semicolon. If one phrase is omitted, no text is displayed and a data-aware control with no text assigns the corresponding value to the field. The default value is 'True;False'.


Example

Field1.DisplayValues := 'Yes;No';

Field2.DisplayValues := 'Oui;Non';


DisplayWidth property

See also

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property DisplayWidth: Integer;

Description

DisplayWidth specifies the number of characters that should be used to display a field in a TDBGrid control. For TStringField, DisplayWidth is the number of characters in the field. For all other fields the default value is 10.


See also

DisplayLabel property

DisplayText property


DitherBackground property

See also	Example

Applies to

TTabSet component

Declaration

property DitherBackground: Boolean;

Description

The DitherBackground property determines whether the selected background color set with the BackgroundColor property is dithered. Dithering means the background is lightened by 50%, which is intended to make the tabs easier to see. If DitherBackground is True, the tab set control background is dithered. If it is False, there is no dithering.

The default value is True.


Example

This event handler toggles the dithering of the tab set control's background each time the user clicks the form:

procedure TForm1.FormClick(Sender: TObject);

begin

  if TabSet1.DitherBackground = True then

    TabSet1.DitherBackground := False

  else

    TabSet1.DitherBackground := True;

end;


See also

Color property


DoKey method

Applies to

TDBCtrlGrid component

Declaration

procedure DoKey(Key: TDBCtrlGridKey);

Description

The DoKey method implements the record-grid component's responses to a number of standard keystrokes. You can create your own keystroke mappings by calling DoKey from a handler for the OnKeyPress event.


Down property

See also	Example

Applies to

TSpeedButton component

Declaration

property Down: Boolean;

Description

The Down property of a speed button determines if the button appears in an up (unselected) or down (selected) state. Speed buttons are initially in their up (unselected) state. This occurs because the default setting of the Down property is False.

To initially display a speed button in its down state, set the Down property to True. For example, if you use a panel component with several speed buttons to create a tools palette, you might want one of the speed buttons selected when the palette first appears.

Although you can use a group of speed buttons with the AllowAllUp property set to False to make the tool palette buttons work as a group, you must set the Down property for the button you want to be selected initially. You can also use the Down property at run time any time you want to put a button in a down state without the user clicking it first.


Example

This code displays the speed button in a down state:

SpeedButton1.Down := True;


See also

AllowAllUp property

GroupIndex property


DragCursor property

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupComboBox, TDBLookupList, TDBMemo, TDBNavigator, TDBRadioGroup, TDBText, TDirectoryListBox, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TGroupBox, THeaderControl, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TScrollBar, TScrollBox, TShape, TStatusBar, TTrackBar, TTreeView, TNotebook, TImageList controls

Declaration

property DragCursor: TCursor;

Description

The DragCursor property determines the shape of the mouse pointer when the pointer is over a component that will accept an object being dragged. These are the possible images:

Value	Image	Value	Image	Value	Image

crDefault	crSizeNESW	crHourglass

crArrow	crSizeNS	crDrag

crCross	crSizeNWSE	crNoDrop

crIBeam	crSizeWE	crHSplit

crSize	crUpArrow	crVSplit


Example

The following code changes the DragCursor of Memo1 to crIBeam.

Memo1.DragCursor := crDrag;


See also

BeginDrag method

Cursor property

Cursors property

Dragging method

EndDrag method

OnDragDrop event

OnDragOver event

OnEndDrag event


DragDrop method

See also

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBNavigator, TDBText, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TGroupBox, THeaderControl, TImage, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBar, TScrollBox, TShape, TStatusBar, TStringGrid, TTabControl, TTabSet, TTrackBar, TTreeView components

Declaration

procedure DragDrop(Source: TObject; X, Y: Integer);

Description

The DragDrop method calls the OnDragDrop event handler, if one exists.  The Source parameter of the DragDrop method is the object to be considered dropped by the handler. The X and Y parameters are the coordinates of the mouse positioned where the object is to be considered dropped.


See also

Dragging and Dropping

DragCursor property

DragMode property

OnDragOver event

OnEndDrag event

OnDragDrop event


Dragging method

See also	Example

Applies to

All controls

Declaration

function Dragging: Boolean;

Description

The Dragging method specifies whether a control is being dragged. If Dragging returns True, the control is being dragged. If Dragging is False, the control is not being dragged.


Example

This example uses three check boxes on a form. When the user begins dragging one of the check boxes, the color of the form changes:

procedure TForm1.FormActivate(Sender: TObject);

begin

  CheckBox1.DragMode := dmAutomatic;

  CheckBox2.DragMode := dmAutomatic;

  CheckBox3.DragMode := dmAutomatic;

end;

procedure TForm1.FormDragOver(Sender, Source: TObject; X, Y: Integer;

  State: TDragState; var Accept: Boolean);

begin

  if CheckBox1.Dragging then

    Color := clAqua;

  if CheckBox2.Dragging then

    Color := clYellow;

  if CheckBox3.Dragging then

    Color := clLime;

end;


See also

BeginDrag method

DragMode property

EndDrag method

OnDragDrop event

OnDragOver event

TDragState type


Dragging property

See also

Applies to

TImageList

Declaration

property Dragging: Boolean;

Description

Run-time and read only. The Dragging property returns whether an image in the image list is being dragged. If Dragging returns True, an image in the image list is being dragged. If Dragging is False, no image is being dragged.


See also

BeginDrag method

DragMode property

EndDrag method

OnDragDrop event

OnDragOver event

TDragState type


Add method for image list objects
DragLock method

See also

Applies to

TImageList component

Declaration

function DragLock(Window: HWND; XPos, YPos: Integer): Boolean;

Description

The DragLock method associates the drag image with the given Window handle and draws it at the position given by the parameters XPos and YPos while the window is in drag mode. Returns True if successful.


See also

SetDragImage method

DragMove method

DragUnlock method

EndDrag method


DragMode property

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBText, TDBListBox, TDBLookupComboBox, TDBLookupList, TDBMemo, TDBNavigator, TDBRadioGroup, TDirectoryListBox, TListView, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TGroupBox, THeaderControl, TImage, TLabel, TListBox, TMaskEdit, TMemo, TOutline, TPageControl,TPaintBox, TRadioButton, TRichEdit, TScrollBar, TScrollBox, TShape, TStatusBar, TStringGrid, TTrackBar, TTreeView, TNotebook components

Declaration

property DragMode: TDragMode;

Description

The DragMode property determines the drag and drop behavior of a control. These are the possible values:

Value	Meaning

dmAutomatic	If dmAutomatic is selected, the control is ready to be dragged; the user just clicks and drags it.

dmManual	If dmManual is selected, the control can't be dragged until the application calls the BeginDrag method.

If a control's DragMode property value is dmAutomatic, the application can disable the drag and drop capability at run time by changing the DragMode property value to dmManual.


Example

This example determines whether the drag mode of the button on the form is manual. If it is, the dragging the button becomes possible.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if Button1.DragMode = dmManual then

    Button1.BeginDrag(True);

end;


See also

BeginDrag method

EndDrag method


Add method for image list objects
DragMove method

See also

Applies to

TImageListcomponent

Declaration

function DragMove(X, Y: Integer): Boolean;

Description

The DragMove method moves the drag image to a new position specified by X and Y within its currently associated window while the window is in drag mode. Returns True if successful.


See also

SetDragImage method

DragLock method

DragUnlock method

Dragging method

EndDrag method


Add method for image list objects
DragUnlock method

See also

Applies to

TImageListcomponent

Declaration

procedure DragUnlock;

Description

The DragUnlock method removes the association between the drag image and a window.


See also

DragLock method

DragMove method

Dragging method

SetDragImage method

EndDrag method


Draw method

Applies to

TCanvas object; TImageListcomponent

Draw method for canvases

Draw method for image lists


Draw method for canvases
Draw method

See also	Example

Applies to

TCanvas objects

Declaration

procedure Draw(X, Y: Integer; Graphic: TGraphic);

Description

The Draw method draws the graphic specified by the Graphic parameter on the canvas at the location given in the screen pixel coordinates (X, Y). Graphics can be bitmaps, icons, or metafiles.


Example

The following code draws the graphic in C:\WINDOWS\TARTAN.BMP centered in Form1 when the user clicks Button1. Attach this code to the OnClick event handler of Button1.

procedure TForm1.Button1Click(Sender: TObject);

var

  Bitmap1: TBitmap;

begin

  Bitmap1 := TBitmap.Create;

  Bitmap1.LoadFromFile('c:\windows\tartan.bmp');

  Form1.Canvas.Draw((Form1.Width div 2)-(Bitmap1.Width div 2),

    (Form1.Height div 2) - (Bitmap1.Height div 2), Bitmap1);

end;


See also

StretchDraw method

TBitmap object

TIcon object

TMetafile object


Draw method for image list objects
Draw method

See also	Example

Applies to

TImageList object

Declaration

procedure Draw(Canvas: TCanvas; X, Y, Index: Integer);

Description

The Draw method draws the image specified by the Index parameter onto the provided Canvas at position X, Y. The image is drawn according to the style set in the DrawingStyle property.


Example

The following code draws each header section adding text for a title and icons stored in ImageList1. The image list contains as many icons as there are header sections.

procedure TForm1.HeaderControl1DrawSection(HeaderControl: THeaderControl;

  Section: THeaderSection; const Rect: TRect; Pressed: Boolean);

begin

  with HeaderControl1.Canvas do

  begin

    Brush.Color := clRed;

    FillRect(Rect);

    Font.Color := clYellow;

    TextOut(Rect.left + 30, Rect.top + 2, 'Header Control');

    ImageList1.Draw(HeaderControl1.Canvas,Rect.Left,Rect.Top,Section.Index);

  end;

end;


See also

DrawingStyle property

ImageIndex property


DrawFocusRect method

See also	Example

Applies to

TCanvas object

Declaration

procedure DrawFocusRect(const Rect: TRect);

Description

The DrawFocusRect method draws a rectangle in the style used to indicate that the rectangle has the focus. Because this is an XOR function, calling it a second time and specifying the same rectangle removes the rectangle from the screen.

The rectangle this function draws cannot be scrolled. To scroll an area containing a rectangle drawn by this function, call DrawFocusRect to remove the rectangle from the screen, scroll the area, and then call DrawFocusRect to draw the rectangle in the new position.


Example

This examples uses a radio button and a button on a form. When the user clicks the button, the code draws a rectangle around the radio button.

procedure TForm1.Button1Click(Sender: TObject);

var

  NewRect: TRect;

begin

  NewRect := RadioButton1.BoundsRect;

  with NewRect do

  begin

    Left := Left - 10;

    Top := Top - 10;

    Right := Right + 10;

    Bottom := Bottom + 10;

  end;

  Form1.Canvas.DrawFocusRect(NewRect);

end;


See also

Arc method

Chord method

Ellipse method

FrameRect method

Pie method

Rectangle method


DrawingStyle property

See also

Applies to

TImageList component

Declaration

property DrawingStyle: TDrawingStyle;

Description

The DrawingStyle property specifies the style to be used when the ImageList is drawing an image. These are the possible values:

Value	Meaning

dsFocused	Draws the image blending 25% with the system highlight color. This only affects image lists which contain masks.

dsSelected	Draws the image blending 50% with the system highlight color. This only affects image lists which contain masks.

dsNormal	Draws the image using the color specified in the BkColor property. If the BkColor is clNone then the image is drawn transparently using the mask.

dsTransparent	Draws using the mask regardless of the BkColor setting.


See also

Draw method, DrawOverlay method


Add method for image list objects
DrawOverlay method

See also

Applies to

TImageList component

Declaration

procedure DrawOverlay(Canvas: TCanvas; X, Y: Integer; ImageIndex: Integer; Overlay: TOverlay);

Description

The DrawOverlay method draws an image and an overlay onto the provided Canvas.  Note that the Overlay method must be called first for an image to allow an image to be used as an overlay.


See also

Overlay method

ImageIndex property


Drive property

See also	Example

Applies to

TDirectoryListBox, TDriveComboBox, TFileListBox components

Declaration

property Drive: Char;

Description

Run-time only. For the drive combo box, the Drive property determines which drive is displayed in the edit control of the combo box. When the user uses the drive combo box to select a new drive, the selected drive becomes the value of the Drive property. The value of the Text property also changes to the new volume name when the Drive property value changes.

For the directory list box, the Drive property determines which drive the list box displays the directory structure on. When the value of Drive changes, the Directory value changes also to the current directory on the specified drive.

For the file list box, the Drive property determines which drive the list box displayed the files on. When the value of Drive changes, the Directory value also changes to the current directory on the specified drive.


Example

The following example assumes that a drive combo box, a file list box, and a directory list box are on a form. This code changes the drive displayed in the drive combo box, displays the current directory of the selected drive in the directory list box, and displays the files in the current directory of the selected drive in the file list box when the user selects a drive in the drive combo box:

procedure TForm1.DriveComboBox1Change(Sender: TObject);

begin

  DirectoryListBox1.Drive := DriveComboBox1.Drive;

  FileListBox1.Directory := DirectoryListBox1.Directory;

end;


See also

Directory property

DirList property

Text property


DriverName property

Example

Applies to

TDataBase component

Declaration

property DriverName: TSymbolStr;

Description

DriverName is the name of a BDE driver, such as STANDARD (for dBASE and Paradox), ORACLE, SYBASE, INFORMIX or INTERBASE. This property will be cleared if AliasName is set, because an AliasName specifies a driver type. Conversely, setting this property will clear AliasName.

If you try to set DriverName of a TDatabase for which Connected is True, Delphi will raise an exception.


Example

Database1.DriverName := 'STANDARD';


DropConnections method

See also	Example

Applies to

TSession component

Declaration

procedure DropConnections;

Description

The DropConnections method drops all inactive database connections. By default, temporary database components keep their connections to the server open even when not in use so that they do not have to log in to the server each time a dataset component is opened.


Example

Session.DropConnections;


See also

Session variable

Temporary property


DropDown method

See also

Applies to

TDBLookupComboBox, TDBLookupCombo component

Declaration

procedure DropDown;

Description

The DropDown method opens or "drops down" the database lookup combo box so that the user has a list of values to choose from.


See also

CloseUp method


DropDownCount property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBLookupComboBox components

Declaration

property DropDownCount: Integer;

Description

The DropDownCount property determines how long the drop-down list of a combo box is. By default, the drop-down list is long enough to contain eight items without requiring the user to scroll to see them all. If you would like the drop-down list to be smaller or larger, specify a number larger or smaller than eight as the DropDownCount value.

If the DropDownCount value is larger than the number of items in the drop-down list, the drop-down list is just large enough to hold all the items and no larger. For example, if the list contains three items, the drop-down list is only long enough to display the three items, even if the DropDownCount is eight.


Example

The following code assigns three to the DropDownCount property of ComboBox1. To see more than three items in the drop-down list, the user must scroll.

ComboBox1.DropDownCount := 3;


See also

DropDownWidth property


DropDownWidth property

See also	Example

Applies to

TDBLookupCombo, TDBLookupComboBox components

Declaration

property DropDownWidth: Integer;

Description

The DropDownWidth property determines how wide the drop-down list of the combo box is in pixels. The default value is 0, which means the drop-down list is the same width as the combo box.

The DropDownWidth property is useful when you are displaying multiple fields, and therefore, multiple columns in the database lookup combo box.


Example

This code displays three fields in the drop-down list of the database lookup combo box. Each column has a title and is separated from the other columns by a line. The combo box displays ten items at a time; therefore, the user must scroll to view the rest of the items. The drop-down list is 600 pixels wide so all the fields fit in the drop-down list.

procedure TForm1.FormCreate(Sender: TObject);

begin

 DBLookupCombo1.LookupDisplay := 'Company;City;Country';

 DBLookupCombo1.Options := [loColLines,loTitles];

 DBLookupCombo1.DropDownCount := 10;

 DBLookupCombo1.DropDownWidth := 600;

end;


See also

DropDownCount property

LookupDisplay property

Options property


DroppedDown property

See also

Applies to

TComboBox, TDBComboBox components

Declaration

property DroppedDown: Boolean;

Description

Run-time only. The DroppedDown property determines whether the drop-down list of the combo box is open or closed. If DroppedDown is True, the drop-down list is visible. If DroppedDown is False, the drop-down list is closed. The default value is False.


See also

DropDownCount property


DropTarget property for tree views
DropTarget property

Applies to

TTreeNode object; TListView, TTreeView components

Description

DropTarget property for tree views

DropTarget property for tree node objects

DropTarget property for list views


DropTarget property

See also

Applies to

TreeView components

Declaration

property DropTarget: TTreeNode;

Description

Run-time only. The DropTarget property determines the item (TTreeNode object) in the tree view that is selected as a drag and drop target. An item that has this state is drawn in the style used to indicate a drag and drop target.


See also

Items property

Selected property

Focused property

DragMode property


DropTarget property

See also

Applies to

TTreeNode object

Declaration

property DropTarget: Boolean;

Description

Run-time only. The DropTarget property determines whether the item (TTreeNode or TListItem object) in the tree view or list view is selected as a drag and drop target. An item that has this state is drawn in the style used to indicate a drag and drop target.


See also

Items property

Selected property

Focused property

DragMode property


DropTarget property for list views
DropTarget property

See also

Applies to

TListView component

Declaration

property DropTarget: TListItem;

Description

Run-time only. The DropTarget property for list views returns the item in the list view that is the target of a drag and drop operation. If no item is a drag drop target, then DropTarget returns nil.


See also

Selected property

Items property

DragMode property


dsEditModes constant

Unit

DB

Declaration

dsEditModes = [dsEdit, dsInsert, dsSetKey];

Description

dsEditModes is the subset of TDataSetState elements which the State property of a dataset component will have if the current record of the dataset is being modified. It is also uses by the UpdateRecord of a dataset component.


Duplicates property

See also	Example

Applies to

TStringList object

Declaration

property Duplicates: TDuplicates;

Description

The Duplicates property determines whether duplicate strings are allowed in the sorted list of strings of a string list object. If the list is not sorted, the value of Duplicates has no effect. These are the possible values:

Value	Meaning

dupIgnore	Attempts to add a duplicate string to a sorted string list are ignored

dupAccept	Duplicate strings can be added to a sorted string list

dupError	Adding a duplicate string results in an EListError exception


Example

The following code makes StringList1 ignore duplicate entries.

StringList1.Duplicates := dupIgnore;


See also

Sort method

Sorted property


EBitsError object

Unit

Classes

Declaration

EBitsError = class(Exception);

Description

The EBitsError exception raised when the index of the Bits property of a TBits object is either less than zero, or greater than or equal to size. EBitsError is also raised if Size is less than zero.


EClassNotFound object

Unit

Classes

Declaration

EClassNotFound = class(EFilerError);

Description

The EClassNotFound exception is raised when a class name which has not been linked into the current program is encountered while reading from a stream. This can happen when a component exists on the form, but has been removed from the type declaration. For example, this form type declaration includes two panel components:

type

  TForm1 = class(TForm)

    Panel1: TPanel;

    SpeedButton1: TSpeedButton;

    SpeedButton2: TSpeedButton;

    Panel2: TPanel;

  private

    { Private declarations }

  public

    { Public declarations }

  end;

If you compile the application, then delete both Panel1 and Panel2 from the TForm1 type declaration, for example, the next time you attempt to run the application, the class not found exception is raised.


EComponentError object

Unit

Classes

Declaration

EComponentError = class(Exception);

Description

The EComponentError exception is raised when an attempt is made to register a component outside of the Register procedure. It is also raised when your application changes the name of a component at run time so that it has the same name as another component. It can also occur if the name of a component is changed to a name that is not a valid Object Pascal identifier.


EDatabaseError object

Unit

DB

Declaration

EDatabaseError = class(Exception);

Description

The EDatabaseError type is the exception type raised when a database error is detected by a component. Use EDatabaseError with an exception handling block or to create a database exception. With an exception handling block, you can detect the condition and handle it yourself. If something in your code encounters an error, you can create and raise the exception yourself.

{ Try to open Tablel1 }

repeat { until successful or Cancel button is pressed }

  try

    Table1.Active := True; { See if it will open }

    Break; { If no error, exit the loop }

  except

    on EDatabaseError do

      { Ask if it is OK to retry }

      if MessageDlg('Could not open Table1 - check server', mtError,

        [mbOK, mbCancel], 0) <> mrOK then raise; { If not, reraise to abort }

      { Otherwise resume the repeat loop }

  end;

  until False;

{ Test for an error and raise an exception if so }

if { some error has occured } then

  raise EDatabaseError.Create('Some error has occured');


EDBEditError object

Unit

Mask

Declaration

EDBEditError = class(Exception);

Description

The EDBEditError exception is raised when the data is not compatible with the mask specified for the field.


EDBEngineError object

Unit

DB

Declaration

EDBEngineError = class(EDatabaseError)

private

  FErrors: TList;

  function GetError(Index: Integer): TDBError;

  function GetErrorCount: Integer;

public

  constructor Create(ErrorCode: DBIResult);

  destructor Destroy;

  property ErrorCount: Integer;

  property Errors[Index: Integer]: TDBError;

end;

Description

The EDBEngineError exception is raised whenever a BDE error occurs. The exception contains two public properties of significance:

Property	How used

Errors	A list of the entire Borland Database Engine error stack. The first error has an index value of 0.

ErrorCount	The total number of errors contained in the Errors property.

The objects contained in the Errors property are of type TDBError, which is declared like this:

TDBError = class

private

  FErrorCode: DBIResult;

  FNativeError: Longint;

  FMessage: TMessageStr;

  function GetCategory: Byte;

  function GetSubCode: Byte;

public

  constructor Create(Owner: EDBEngineError; ErrorCode: DBIResult;

    NativeError: Longint; Message: PChar);

  property Category: Byte;

  property ErrorCode: DBIResult;

  property SubCode: Byte;

  property Message: TMessageStr;

  property NativeError: Longint;

end;

These are the public properties of the TDBError object:

Property	How used

ErrorCode	The error code returned by the Borland Database Engine

Category	The category of the error referenced by ErrorCode

SubCode	The subcode of the error code

NativeError	The remote error code returned from the server. If NativeError is 0, the error is not a server error.

Message	The server message for native errors, or the BDE message for non-server errors.


EDDEError object

Unit

DDEMan

Declaration

EDDEError = class(Exception);

Description

The EDDEError exception is raised when your application can't find the specified server or conversation, or when a session is unexpectedly terminated.


Edit method

Applies to

TDataSource, TQuery, TTable components

Description

Edit Method for Queries and Tables

Edit method for Data Sources


Edit method

Applies to

TQuery, TTable components

Declaration

procedure Edit;

Description

The Edit method prepares the current record of the dataset for changes and puts the dataset in Edit mode, setting the State property to dsEdit. Data-aware controls cannot modify existing records unless the dataset is in Edit mode.

Calling this method for a dataset that cannot be modified raises an exception. The CanModify property will be True for datasets that can be modified. This method is valid only for datasets that return a live result set.


See also

AutoEdit property


Edit method

Applies to

TDataSource components

Declaration

procedure Edit;

Description

Edit calls the dataset's Edit method if AutoEdit is True and State is dsBrowse.


See also

DataSet property

Insert method


EditCaption method

See also

Applies to

TListItem object

Declaration

function EditCaption: Boolean;

Description

The EditCaption method begins in-place editing of the specified list item's text. The method implicitly selects and focuses the specified item.


See also

ReadOnly property

ItemFocused property


EditFormat property

Applies to

TBCDField, TCurrencyField, TFloatField, TIntegerField, TSmallintField, TWordField components

Declaration

property EditFormat: string;

Description

EditFormat is used to format the value of the field for editing purposes.

For TIntegerField, TSmallintField, and TWordField, formatting is performed by FloatToTextFmt. If EditFormat is not assigned a string, but DisplayFormat does have a value, the DisplayFormat string is used. Otherwise, the value is formatted by to the shortest possible string.

For TBCDField, TCurrencyField, and TFloatField, formatting is performed by FloatToTextFmt. If EditFormat is not assigned a string but DisplayFormat does have a value, the DisplayFormat string will be used. Otherwise, the value is formatted according to the value of the Currency property.


EditKey method

See also	Example

Applies to

TTable component

Declaration

procedure EditKey;

Description

Use the EditKey method to modify the contents of the search key buffer. This method is useful only when searching on multiple fields after calling SetKey. Call GotoKey to move the cursor to the record with the corresponding key.

EditKey differs from SetKey in that the latter clears all the elements of the search key buffer to the default values (or NULL). EditKey leaves the elements of the search key buffer with their current values.


Example

with Table1 do

  begin

    EditKey;

    FieldByName('State').AsString := 'CA';

    FieldByName('City').AsString := 'Santa Barbara';

    GotoKey;

  end;


See also

IndexFields property


EditMask property

See also	Example

Applies to

TDateField, TDateTimeField, TMaskEdit, TStringField, TTimeField components

Declaration

property EditMask: string;

Description

The EditMask property is the mask that is used to limit the data that can be put into a masked edit box or entered into a data field. A mask restricts the characters the user can enter to valid characters and formats. If the user attempts to enter a character that is not valid, the edit box does not accept the character. Validation is performed on a character-by-character basis. Use an OnValidate event to validate the entire input.

For a TStringField, EditMask can be used to format output with the DisplayText property.

A mask consists of three fields with semicolons separating the fields. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are saved as part of the data. The third part of the mask is the character used to represent a blank in the mask.

These are the special characters used to create masks:

Character	Meaning in mask

      !	If a ! character appears in the mask, leading blanks don't appear in the data. If a ! character is not present, trailing blanks don't appear in the data.

     >	If a > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a < character is encountered.

     <	If a < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a > character is encountered.

     <>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data.

     \	The character that follows a \ character is a literal character. Use this character when you want to allow any of the mask special characters as a literal in the data.

     L	The L character requires only an alphabetic character only in this position. For the US, this is A-Z, a-z.

     l	The l character permits only an alphabetic character in this position, but doesn't require it.

     A	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.

     a	The a character permits an alphanumeric character in this position, but doesn't require it.

     C	The C character requires a character in this position.

     c	The c character permits a character in this position, but doesn't require it.

     0	The 0 character requires a numeric character only in this position.

     9	The 9 character permits a numeric character in this position, but doesn't require it.

     #	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.

     :	The : character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the International settings of the Control Panel utility on your computer system, that character is used instead of :.

     /	The / character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the International settings of the Control Panel utility on your computer system, that character is used instead of /.

     ;	The ; character is used to separate masks.

     _	The _ character automatically inserts a blank the edit box. When the user enters characters in the field, the cursor skips the blank character. When using the EditMask property editor, you can change the character used to represent blanks. You can also change this value programmatically. See the following table.

These characters (already mentioned in previous table) are typed constants declared in the Mask unit whose value you can change at run time, although the need for this should be limited:

Typed constant	Initial value	Meaning

DefaultBlank	     _	Blanks in the mask are represented by the _ character

MaskFieldSeparator	     ;	The ; character separates the fields of a mask.

MaskNoSave	     0	The 0 character means that the mask is not saved as part of the data. The 1 character means that the mask is saved as part of the data.For example, a telephone number could have parentheses around the area code as part of the mask. If MaskNoSave is 0, the parentheses do not become part of the data, making the size of the field slightly smaller.


Example

This example assigns an edit mask to the masked edit box on the form. The edit mask makes it easy to enter American telephone numbers in the edit box.

procedure TForm1.FormCreate(Sender: TObject);

begin

  MaskEdit1.EditMask := '!\(999\)000-0000;1;

  MaskEdit1.Text := '';

  MaskEdit1.AutoSelect := False;

end;


See also

OnGetEditMask event

EditText property

Text property


EditMaskPtr property

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property EditMask PTR: string;

Description

Run-time and read-only. EditMaskPtr is a pointer to the EditMask property of a string.


Example

Field1.EditMask := Field2.EditMaskPtr^;


EditMode property

Applies to

TDBCtrlGrid component

Declaration

property EditMode: Boolean;

Description

Run-time only. When True, the user is editing the current record. The user can toggle EditMode by pressing F2 or Enter.


EditorMode property

Applies to

TDBCtrlGrid ,TDBGrid, TDrawGrid, TStringGrid, TDBLookupList components

Description

EditorMode Property for Database Control Grids

EditorMode for Database, Draw and String Grids


EditorMode property

Applies to

TDBCtrlGrid component

Declaration

property EditorMode: Boolean;

Description

Run-time only. When True, the user is editing the current record. The user can toggle EditMode by pressing F2 or Enter.


EditorMode property

See also

Applies to

TDBGrid, TDrawGrid, TStringGrid, TDBLookupList components

Declaration

property EditorMode: Boolean;

Description

Run-time only. The EditorMode property determines whether the grid is in automatic Edit mode. When the grid is in automatic edit mode, the user can type in a cell without having to press Enter or F2 first. If the Options property set includes the value goAlwaysShowEditor (goAlwaysShowEditor is True), the grid is in automatic edit mode, just as if EditorMode is True. If goAlwaysShowEditor is False, EditorMode becomes False whenever a new cell is selected. While you are most likely to set the Options property values at design time, the EditorMode property makes it easy to control when editing is permitted at run time.

If EditorMode is True, the grid is in automatic edit mode as long as the Options property set includes the value goEditing (or dgEditing for the data grid). If goEditing or dgEditing is not in the Options set (goEditing or dgEditing is False), setting EditorMode to True has no effect, and the user cannot edit the contents of a cell.

If EditorMode is False and the Options property set includes the value goEditing or dgEditing, but not the value goAlwaysShowEditor (or dgAlwaysShowEditor for the data grid), the user can enter edit mode by pressing either Enter or F2 before editing the contents of each cell.


See also

Options property


EditRangeEnd method

See also	Example

Applies to

TTable component

Declaration

procedure EditRangeEnd;

Description

EditRangeEnd enables you to modify the beginning range of the dataset filter established with SetRangeEnd. Subsequent assignments to field values will modify the values of the ending field range previously set with SetRangeEnd. Call ApplyRange to apply the new range and filter the dataset.

EditRangeEnd differs from SetRangeEnd in that the latter clears all the elements of the search key buffer to the default values (NULL). EditRangeEnd leaves the elements of search key buffer with their current values.

Note:	With Paradox or dBASE tables, these methods work only with indexed fields. With SQL databases, they can work with any columns specified in the IndexFieldNames property.


Example

{ Limit the range from 'Goleta' to 'Santa Barbara'}

with Table1 do

  begin

    EditRangeStart; { Set the beginning key }

    FieldByName('City').AsString := 'Goleta';

    EditRangeEnd; { Set the ending key }

    FieldByName('City').AsString := 'Santa Barbara';

    ApplyRange; { Tell the dataset to establish the range }

  end;


See also

KeyExclusive property

KeyFieldCount property


EditRangeStart method

See also	Example

Applies to

TTable component

Declaration

procedure EditRangeStart;

Description

EditRangeStart enables you to modify the lower key limit established with SetRangeStart. Call ApplyRange to apply the new range and filter the dataset.

EditRangeStart differs from SetRangeStart in that the latter clears all the elements of the search key buffer to the default values (NULL). EditRangeStart leaves the elements of the search key buffer with their current values.

Note:	With Paradox or dBASE tables, these methods work only with indexed fields. With SQL databases, they can work with any columns specified in the IndexFieldNames property.


Example

{ Limit the range from 'Goleta' to 'Santa Barbara'}

with Table1 do

  begin

  EditRangeStart; { Set the beginning key }

  FieldByName('City').AsString := 'Goleta';

  EditRangeEnd; { Set the ending key }

  FieldByName('City').AsString := 'Santa Barbara';

  ApplyRange; { Tell the dataset to establish the range }

  end;


See also

KeyExclusive property

EditRangeEnd method

SetRange method

SetRangeEnd method


EditText method for tree node objects
EditText method

See also	Example

Applies to

TTreeNode object

Declaration

function EditText: Boolean;

Description

The EditText method begins in-place editing of the specified item's text, replacing the text of the item with a single-line edit control containing the text. This message implicitly selects and focuses the specified item. The tree view's OnEditing event will be triggered.


Example

The following example begins in-place editing of the selected item in TreeView1.

TreeView1.Selected.EditText;


See also

OnEditing event

OnEdited event

Text property

EndEdit method


EditText property

See also

Applies to

TDBEdit, TMaskEdit components

Declaration

property EditText: string;

Description

Run-time only. The EditText property is the value of the Text property as it appears in the edit box at run time with the mask specified in the EditMask property applied. If literal mask characters are not saved and no character is substituted for blanks, the values of EditText and Text are the same.

EditText is what the user actually sees in the edit box at run time.


See also

EditMask property

Text property


EFCreateError object

Unit

Classes

Declaration

EFCreateError = class(EStreamError);

Description

The EFCreateError exception is raised when an error occurs as a file is being created. For example, the specified file might have an invalid filename, or the file can't be recreated because it would overwrite a read-only file.


EFilerError object

Unit

Classes

Declaration

EFilerError = class(EStreamError);

Description

The EFilerError is raised when an attempt is made to register the same class twice. It is also the parent of these exceptions that occur when reading or writing streams:

Exception	Description

EReadError	The ReadBuf method cannot read the specified number of bytes

EWriteError	The WriteBuf method cannot write the specified number of bytes

EClassNotFound	A component on the form has been deleted from the form type declaration


EFOpenError object

Unit

Classes

Declaration

EFOpenError = class(EStreamError);

Description

The EFOpenError exception is raised when an attempt is made to create a file stream object and the specified file cannot be opened.


EInvalidGraphic object

Unit

Graphics

Declaration

EInvaldGraphic = class(Exception);

Description

An EInvalidGraphic exception is raised when your application attempts to load a file that is not a valid bitmap, icon, metafile, or user-defined graphic type into a picture. For example, this code raises an invalid graphic exception:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Image1.Picture.LoadFromFile('README.TXT');

end;

Because the README.TXT file doesn't contain a valid graphic, the exception is raised.


EInvalidGraphicOperation object

Unit

Graphics

Declaration

EInvalidGraphicOperation = class(Exception);

Description

An EInvalidGraphicOperation is raised when an illegal operation is attempted on a graphic. For example, if your application attempts to resize an icon, the invalid graphic operation is raised:

var

  AnIcon: TIcon;

begin

  AnIcon := TIcon.Create;

  AnIcon.LoadFromFile('C:\WINDOWS\DIRECTRY.ICO');

  AnIcon.Width := 100;        { an invalid graphic operation exception is raised }

  ...


EInvalidGridOperation object

Unit

Grids

Declaration

EInvalidGridOperation = class(Exception);

Description

An EInvalidGridOperation is raised when an illegal operation is attempted on a grid. For example, your application might try to access a cell that does not exist within the grid.


EInvalidImage object

Unit

Classes

Declaration

EInvalidImage = class(EFilerError);

Description

The EInvalidImage exception is raised when your application attempts to read a resource file and the specified file is not a resource file. When your application calls the ReadComponentRes method, it must also use the corresponding WriteComponentRes method to write to a resource file. Similarly, when you application calls the ReadComponent method, it must use the corresponding WriteComponent method.


EInvalidOperation object

Unit

Controls

Declaration

EInvalidOperation = class(Exception);

Description

An EInvalidOperation exception is raised when your application does some operation that requires a window handle and your component does not have a parent (Parent = nil). It can also occur if you try to perform drag and drop operations from the form such as Form1.BeginDrag.


Eject method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Eject;

Description

The Eject method ejects the loaded medium from the open multimedia device. Eject is called when the Eject button on the media player control is clicked at run time.

Upon completion, Eject stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Eject method has been completed. The Notify property determines whether Eject generates an OnNotify event.


Example

This code ejects the CD from the CD-ROM player after 10 seconds. For the code to run correctly, you must have your CD audio device installed correctly, and the device must have software ejecting capabilities.

var

  TimerOver: Word;

procedure TForm1.FormClick(Sender: TObject);

begin

  MediaPlayer1.DeviceType := dtCDAudio;

  MediaPlayer1.Open;

  MediaPlayer1.Play;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  if TimeOver = 10 then

  begin

    MediaPlayer1.Eject;

    MediaPlayer1.Close;

    Timer1.Enabled := False;

  end

  else

    Inc(TimeOver);

end;


See also

Capabilities property


EListError object

Unit

Classes

Declaration

EListError = class(Exception);

Description

The EListError is an exception that is raised when an error is made in a list, string, or string list object. List error exceptions commonly occur when your application refers to an item in a list that is out of the list's range. For example, the following code is an event handler that attempts to access an item in a list box that does not exist. The EListError is raised and handled:

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Add('First item');                  { Items[0] }

  ListBox1.Items.Add('Another item');                { Items{1] }

  ListBox1.Items.Add('Still another item');          { Items[2] }

  try

    ListBox1.Items[3] := 'This item does not exist';

  except

    on EListError do

      MessageDlg('List box contains fewer than 4 strings', mtWarning, [mbOK], 0);

    end;

end;

Also, a list error occurs when your application tries to add a duplicate string to a string list object when the value of the Duplicates property is dupError.

A list error exception is raised when you insert a string into a sorted string list, as the string you insert at the specified position may put the string list out of sorted order. For example, this code raises the list error exception:

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  for I := 1 to 5 do

    ListBox1.Items.Add('Item ' + IntToStr(I));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  try

    ListBox1.Items.Insert(0, 'Try to insert here');

  except

    on EListError do

       MessageDlg('Attempt to insert into a sorted list', mtWarning, [mbOK], 0);

    end;

  end;


Ellipse method

See also	Example

Applies to

TCanvas object

Declaration

procedure Ellipse(X1, Y1, X2, Y2: Integer);

Description

The Ellipse method draws an ellipse defined by a bounding rectangle on the canvas. The top left point of the bounding rectangle is at pixel coordinates (X1, Y1) and the bottom right point is at (X2, Y2). If the points of the rectangle form a square, a circle is drawn.


Example

The following code draws an ellipse filling the background of a form:

procedure TForm1.FormPaint(Sender: TObject);

begin

  Canvas.Ellipse(0, 0, ClientWidth, ClientHeight);

end;


See also

Arc method

Chord method

Draw method

DrawFocusRect method

Pie method

StretchDraw method


EMCIDeviceError object

Unit

MPlayer

Declaration

EMCIDeviceError = class(Exception);

Description

The EMCIDeviceError exception is raised if an error occurs when accessing a multimedia device. The most common cause for the exception is trying to access a multimedia device before it has been opened with the Open method.


EMenuError object

Unit

Menus

Declaration

EMenuError = class(Exception);

Description

The EMenuError exception is raised if an error occurs when your application is working with menu items. For example, if you application attempts to delete a menu item that doesn't exist, a menu error exception occurs.


Empty property

See also	Example

Applies to

TBitmap, TGraphic, TIcon, TMetafile objects

Declaration

property Empty: Boolean;

Description

Read-only. The Empty property specifies whether the graphics object contains a graphic. If Empty is True, no graphic has been loaded into the graphics object. If Empty is False, a graphic is contained by the graphics object.


Example

The following loads a file into Graphic1 if it does not already contain a graphic.

if Graphic1.Empty then Graphic1.LoadFromFile('myfile.bmp');


See also

LoadFromFile method


EmptyTable method

Example

Applies to

TTable component

Declaration

procedure EmptyTable;

Description

The EmptyTable method deletes all records from the database table specified by TableName. Before calling this method, the DatabaseName, TableName and TableType properties must be assigned values.

Note:	If the table is open, it must have been opened with the Exclusive property set to True.


Example

with Table1 do

  begin

  Active := False;

  DatabaseName := 'Delphi_Demos';

  TableName := 'CustInfo';

  TableType := ttParadox;

  EmptyTable;

  end;


EnableControls method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure EnableControls;

Description

The EnableControls method restores the connections from the dataset to all TDataSource components that were disconnected by a call to the DisableControls method. While the data sources are disconnected, changes in the active record will not be reflected in them. The dataset maintains a count of the number of calls to DisableControls and EnableControls, so only the last call to EnableControls will actually update the data sources.


Example

with Table1 do

  begin

  DisableControls;

{ Move forward five records }

  try

    for I := 1 to 5 do Next;

  finally

{ Update the controls to the current record }

    EnableControls;

  end;


See also

Enabled property


Enabled property

Applies to

All controls; TDataSource, TForm, TMenuItem, TTimer components

Description

The Enabled property determines if the control responds to mouse, keyboard, or timer events, or if the data-aware controls update each time the dataset they are connected to changes.

Enabled Property for Controls, Menu Items, and Timers

Enabled Property for Data Source Components


Enabled property

Example

Applies to

All controls; TMenuItem, TTimer components

Declaration

property Enabled: Boolean;

Description

The Enabled property controls whether the control responds to mouse, keyboard, and timer events. If Enabled is True, the control responds normally. If Enabled is False, the control ignores mouse and keyboard events, and in the case of a timer control, the OnTimer event. Disabled controls appear dimmed.


Example

To disable a button called FormatDiskButton,

FormatDiskButton.Enabled := False;

This code alternately dims or enables a menu command when a user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if OpenCommand.Enabled then

    OpenCommand.Enabled := False

  else

    OpenCommand.Enabled := True;

end;


Enabled property

Example

Applies to

TDataSource component

Declaration

property Enabled: Boolean;

Description

Enabled specifies if the display in data-aware controls connected to TDataSource is updated when the current record in the dataset changes. For example, when Enabled is True and the Next method of a dataset component is called many times, each call updates all controls. Setting Enabled to False allows the Next calls to be made without performing updates to the controls. Once you reach the desired record, set Enabled to True to update the controls to that record.

Note:	Setting Enabled to False clears the display in data-aware controls until you set it to True again. If you want to leave the controls with their current contents while moving through the table or query, call the DisableControls and EnableControls.


Example

DataSource1.Enabled := False;

while not DataSource1.DataSet.EOF do DataSource1.DataSet.Next;

DataSource1.Enabled := True;


EnabledButtons property

See also	Example

Applies to

TMediaPlayer component

Declaration

property EnabledButtons: TButtonSet;

Description

The EnabledButtons property determines which buttons on the media player are enabled. An enabled button is colored and usable. A disabled button is dimmed and not usable. If a button is not enabled with EnabledButtons, it is disabled. By default, all buttons are enabled.

If the AutoEnable property is True, AutoEnable supersedes EnabledButtons. The buttons automatically enabled or disabled by the media player override any buttons enabled or disabled with the EnabledButtons property.

Button	Value	Action

Play	btPlay	Plays the media player

Record	btRecord	Starts recording

Stop	btStop	Stops playing or recording

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks

Step	btStep	Moves forward a number of frames

Back	btBack	Moves backward a number of frames

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium


Example

The following example enables all of the media player component's buttons:

TMediaPlayer1.EnabledButtons := [btPlay, btPause, btStop, btNext, btPrev, btStep, btBack,
  btRecord, btEject]


See also

ColoredButtons property

VisibleButtons property


EndDoc method

See also	Example

Applies to

TPrinter object

Declaration

procedure EndDoc;

Description

The EndDoc method ends the current print job and closes the text file variable. After the application calls EndDoc, the printer begins printing. Use EndDoc after successfully sending a print job to the printer. If the print job isn't successful, use the Abort method.

The Close procedure calls the EndDoc method.


Example

This example uses a button on a form. When the user clicks it, the event handler prints a rectangle on the printer and displays a message on the form.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with Printer do

  begin

    BeginDoc;

    Canvas.Rectangle(20, 20, 400, 300);

    EndDoc;

  end;

   Canvas.TextOut(10, 10, 'Printed');

end;

To use the EndDoc method, you must add the Printers unit to the uses clause of your unit.


See also

BeginDoc method


EndDrag method

See also	Example

Applies to

All controls

Declaration

procedure EndDrag(Drop: Boolean);

Description

The EndDrag method stops an object from being dragged any further. If the Drop parameter is True, the object being dragged is dropped. If the Drop parameter is False, the object is not dropped and dragging is canceled.


Example

The following code cancels the dragging of Label1 without dropping the object.

Label1.EndDrag(False);


See also

BeginDrag method

DragMode property

OnEndDrag event

Dragging and Dropping


EndDrag method

See also

Applies to

TImageList

Declaration

function EndDrag: Boolean;

Description

The EndDrag method ends the drag operation.  EndDrag returns True if successful, False if it fails.


See also

BeginDrag method

DragMode property

OnEndDrag event

Dragging and Dropping


CancelEdit method for tree node objects
EndEdit method

See also

Applies to

TTreeNode object

Declaration

procedure EndEdit(Cancel Boolean);

Description

The EndEdit method ends the editing of an item's (TTreeNode object) label in a tree view. The tree views OnEdited event will be triggered if the user has made changes and if Cancel is False.


See also

EditText method

ReadOnly property

OnEditing event

OnEdited event

Text property


EndMargin property

See also	Example

Applies to

TTabSet component

Declaration

property EndMargin: Integer;

Description

The EndMargin property determines how far in pixels the rightmost tab appears from the right edge of the tab set control. The default value is 5. Together with the StartMargin property, EndMargin can play a role in determining how many tabs can fit within the tab set control.

If AutoScroll is True and scroll buttons appear in the tab set control, EndMargin determines how far in pixels the rightmost tab appears from the left edge of the scroll buttons, rather than the edge of the tab set control.


Example

This example displays the tab set control so the tabs are no closer than 20 pixels from the edge of the tab control on the left and from the scroll buttons on the right:

procedure TForm1.FormCreate(Sender: TObject);

begin

  with TabSet1 do

  begin

    AutoScroll := True;

    StartMargin := 20;

    EndMargin := 20;

  end;

end;


See also

StartMargin property


EndPage property

See also	Example

Applies to

TReport component

Declaration

property EndPage: Word;

Description

The value of the EndPage property specifies the last page of the report that is printed. The default value is 9999. If the report is fewer than 9999 pages and you don't change the value of EndPage, your entire report is printed.


Example

The following code prints only the first page of Report1.

Report1.EndPage := 1;

Report1.Run;


See also

PrintCopies property

StartPage property


EndPos property

See also	Example

Applies to

TMediaPlayer component

Declaration

property EndPos: Longint;

Description

Run-time only. The EndPos property specifies the position within the currently loaded medium at which to stop playing or recording. EndPos is specified using the current time format, which is specified in the TimeFormat property.

The EndPos property affects only the next Play or StartRecording method called after setting EndPos. You must reset EndPos to affect any subsequent calls to Play or StartRecording.


Example

The following procedure begins playing the .WAV audio file from the beginning of the file to middle only.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with MediaPlayer1 do

  begin

    FileName := 'D:\WINAPPS\SOUNDS\CARTOON.WAV';

    Open;

    EndPos := TrackLength[1] div 2;

    Play;

  end;

end;


See also

StartPos property


EndUpdate method

See also	Example

Applies to

TCollection, TListItems, TStringList, TStrings objects; TOutline component

Declaration

procedure EndUpdate;

Description

The EndUpdate method re-enables screen repainting and outline item reindexing that was turned off with the BeginUpdate method.


Example

BeginUpdate and EndUpdate should always be used in conjunction with a try...finally statement to ensure that EndUpdate is called if an exception occurs. A block that uses BeginUpdate and EndUpdate typically looks like this:

ListBox1.Items.BeginUpdate;

try

  ListBox1.Items.Clear;

  ListBox1.Items.Add(...);

  ...

  ListBox1.Items.Add(...);

finally

  ListBox1.Items.EndUpdate;	{ Executed even in case of an exception }

end;


See also

BeginUpdate method


Enhanced property

See also

Applies to

TMetafile object

Declaration

property Enhanced: Boolean;

Description

Run-time only. The Enhanced property determines how the metafile will be stored on disk. If Enhanced = True (default) it stores the metafile as an EMF (Win32 Enhanced Metafile); If Enhanced = False, it stores the metafile as a WMF (Windows 3.1 Metafile, with Aldus header). The in-memory format is always EMF.  WMF has very limited capabilities; storing as WMF will lose information that would be retained by EMF. This property is set to match the metafile type when loaded from a stream or file.  This maintains form file compatibility with 16 bit Delphi. If loaded as WMF, then save as WMF.


See also

CreatedBy property

Description property


EOF property

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property EOF: Boolean;

Description

Run-time and read-only. EOF is a Boolean property that indicates whether a dataset is known to be at its last row. The EOF property returns a value of True after:

An application opens an empty dataset

A call to a table's Last method

A call to a table's Next fails because the cursor is on the last row


Example

This example uses TDataSource's OnDataChange event to detect when the user moves to another record. If the end of file is reached (EOF property becomes True), a message is displayed on the form's status bar.

procedure TForm1.DataSource1DataChange(Sender: TObject; Field: TField);

begin

  if Table1.EOF then

    StatusBar1.SimpleText := 'You''re already at the end of the table';

end;


See also

BOF property

MoveBy method


EOutlineError object

Unit

Outline

Declaration

EOutlineError = class(Exception);

Description

The EOutlineError exception is raised when an error occurs as your application works with an outline component.


EOutOfResources object

Unit

Controls

Declaration

EOutOfResources = class(EOutOfMemory);

Description

The EOutOfResources exception occurs when your application attempts to create a Windows handle and Windows has no more handles to allocate.


EParserError object

Unit

Classes

Declaration

EParserError = class(Exception);

Description

The EParserError is raised when your application attempts to read from a text form using ObjectTextToBinary or ObjectTextToResource and it is unable to read some part of it, due to a syntax error.


EPrinter object

Unit

Printers

Declaration

EPrinter = class(Exception);

Description

The EPrinter exception is raised when a printing error occurs. For example, if your application attempts to print to a printer that doesn't exist, or if the print job can't be sent to the printer for some reason, a printer exception occurs.


Equals method

See also

Applies to

TStringList, TStrings objects

Declaration

function Equals(Strings: TStrings): Boolean;

Description

The Equals method returns True if Strings and the calling TStrings object are equal in count and each byte in the strings are equal.


See also

Values property


EraseSection method

See also	Example

Applies to

TIniFile object

Declaration

procedure EraseSection(const Section: string);

Description

The EraseSection method erases an entire section of an .INI file.

The Section constant identifies the section of the .INI file to erase. For example, the WIN.INI for Windows contains a [Desktop] section.


Example

This examples erases the SaveSettings section in the MYAPP.INI file when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

var

  MyAppIni: TIniFile;

begin

  MyAppIni := TIniFile.Create('MYAPPINI.INI');

  MyAppIni.EraseSection('SaveSettings');

  MyAppIni.Free;

end;


See also

ReadSection method


EReadError object

Unit

Classes

Declaration

EReadError = class(EFilerError);

Description

The EReadError is raised when your application attempts to read data from a stream by calling the ReadBuffer method, but the number of bytes specified in the Count parameter of the method cannot be read.

A read error exception can also occur while creating a form if Delphi is unable to read a property because either a component incorrectly reads the form resource or the resource is corrupt.


EReportError object

Unit

Report

Declaration

EReportError = class(Exception);

Description

The EReportError exception is raised when the Connect method of a report component (TReport) cannot connect the report to a database because the specified server is invalid.


EResNotFound object

Unit

Classes

Declaration

EResNotFound = class(Exception);

Description

The EResNotFound exception is raised when the ReadComponentRes method cannot find the name of the specified resource in the resource file. If you receive this exception on the startup of your application, or when you create a form, check the form's .PAS file for the {*.RES} directive. If this is missing or commented out, the .DFM file will not be included into the .EXE file and this exception will be generated when the form is created.


Error property

Example

Applies to

TMediaPlayer component

Declaration

property Error: Longint;

Description

Run-time and read-only. The Error property specifies the MCI error code returned by the most recent media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop).

The error codes returned by media control methods are the same error codes returned by the mciSendCommand function, which is documented in MMSYSTEM.HLP. The message describing the error code is stored in the ErrorMessage property.

The value of Error is zero if the most recent media control method didn't cause an error. If a method results in an error, a value other than zero is stored in Error. If the error occurs during the opening of the device, an EMCIDeviceError exception occurs.


Example

The following code opens, closes, then plays MediaPlayer1. If an error occurs, a message window displays the error number.

procedure TForm1.BitBtn1Click(Sender: TObject);

var

  MyErrorString: String;

begin

  MediaPlayer1.Open;

  MediaPlayer1.Close;

  MediaPlayer1.Play;

  MyErrorString := 'ErrorCode: ' + IntToStr(Error);

  MessageDlg(MyErrorString, mtError, [mbOk], 0);

end;


ErrorMessage property

Example

Applies to

TMediaPlayer component

Declaration

property ErrorMessage: string;

Description

Run-time and read-only. The ErrorMessage property specifies the error message that describes the error code returned from the most recent media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop). The error code described by the message is stored in the Error property.


Example

The following code opens MediaPlayer1. If an exception occurs, a message window displays the error number and string.

procedure TForm1.BitBtn1Click(Sender: TObject);

var

  MyErrorString: String;

begin

  try

    MediaPlayer1.Open;

  except

    MyErrorString := 'ErrorCode: ' + IntToStr(Error) + #13#10;

    MessageDlg(MyErrorString + MediaPlayer1.ErrorMessage, mtError, [mbOk], 0);

  end;

end;


EStreamError object

Unit

Classes

Declaration

EStreamError = class(Exception);

Description

The EStreamError exception is raised when an error occurs when a stream is read with the LoadFromStream method. It also is the parent of these two stream exceptions:

Exception	Description

EFCreateError	An error occurred while creating a file

EFOpenError	An error occurred while opening a file


EStringListError object

Unit

Classes

Declaration

EStringListError = class(Exception);

Description

The EStringListError exception occurs when an error is made in a string list object. String list error exceptions commonly occur when your application refers to an item in a list that is out of the string list's range.


ETreeViewError object

Unit

ComCtrls

Declaration

ETreeViewError = class(Exception);

Description

The ETreeViewError exception is raised whenever an invalid index is requested from a TTreeView component.


EWriteError object

Unit

Classes

Declaration

EWriteError = class(EFilerError);

Description

The EWriteError exception is raised when the WriteBuffer method of a stream object is unable to write the number of bytes specified in its Count parameter.


Exchange method

See also	Example

Applies to

TList, TStringList, TStrings objects

Declaration

procedure Exchange(Index1, Index2: Integer);

Description

The Exchange method exchanges the position of two items in the list of a list object, or in the list of strings of a string or string list object. The items are specified with their index values in the Index1 and Index2 parameters. Because the indexes are zero-based, the first item in the list has an index value of 0, the second item has an index value of 1, and so on.

If a string in a string or string list object has an associated object, Exchange changes the position of both the string and the object.


Example

This example uses a list box that contains several strings as the value of the Items property, and a button. When the user clicks the button, the second and third items in the list box switch places in the list box.

procedure TForm1.Button1Click(Sender: TObject);

begin

   ListBox1.Items.Exchange(1, 2);

end;


See also

Add method

AddStrings method

Delete method

IndexOf method

Insert method

Move method


Exclusive property

Example

Applies to

TTable component

Declaration

property Exclusive: Boolean;

Description

Set the Exclusive property to True to prevent any other user from accessing the table. If other users are accessing the table when you try to open it, your exception handler will have to wait for those users to release it. If you do not provide an exception handler and another user already has the table open, your application will be terminated.

Note:	Set the Active property to False before changing Exclusive to prevent an exception.

Do not set Active and Exclusive to True in the Object Inspector Window. Since the Object Inspector will have the table open, that will prevent your program from opening it.

Set Exclusive to True only when you must have complete control over the table.


Example

{ Try to open Table1 with Exclusive True }

{ First, close Table1 }

Table1.Active := False;

repeat { until successful or Cancel button is pressed }

  try

    Table1.Exclusive := True; { See if it will open }

    Table1.Active := True;

    Break; { If no error, exit the loop }

  except

    on EDatabaseError do

      { Ask if it is OK to retry }

      if MessageDlg('Could not open Table1 exclusively - OK to retry?', mtError,

        [mbOK, mbCancel], 0) <> mrOK then raise; { If not, reraise to abort }

      { Otherwise resume the repeat loop }

  end;

  until False;


ExecProc method

Example

Applies to

TStoredProc component

Declaration

procedure ExecProc;

Description

The ExecProc method executes the stored procedure on the server. If any input parameters are to be used, specify them first in the Params property at design time or at run time. Call the Prepare method before executing the stored procedure with ExecProc. If any output parameters are returned from the stored procedure, the values can be accessed by indexing into the Params string list or by using the ParamByName method.


Example

The following code executes the stored procedure:

StoredProc1.Params[0].AsString := Edit1.Text;

StoredProc1.Prepare;

StoredProc1.ExecProc;


ExecSQL method for TQuery
ExecSQL method

Example

Applies to

TQuery component

Declaration

procedure ExecSQL;

Description

Use the ExecSQL method to execute an SQL statement assigned to the SQL property of a TQuery if the statement does not return a result set. If the SQL statement is an INSERT, UPDATE, DELETE, or any DDL statement, then use this method.

If the SQL statement is a SELECT statement, use Open instead.


Example

Query1.Close;

Query1.SQL.Clear;

Query1.SQL.Add('Delete from Country where Name = 'Argentina');

Query1.ExecSQL;


ExecSQL method for TUpdateSQL
ExecSQL method

Applies to

TUpdateSQL component

Declaration

procedure ExecSQL(UpdateKind: TUpdateKind);

Description

The ExecSQL method executes the SQL statement associated with the UpdateKind parameter (for example, calling ExecSQL and passing ukModify would execute the SQL statement held in the ModifySQL property). Note that ExecSQL does not perform parameter binding; you can do so by calling SetParams before calling ExecSQL, or by calling Apply, which calls SetParams then ExecSQL.


Execute method

Applies to

TBatchMove, TColorDialog, TFindDialog, TFontDialog, TOpenDialog, TPrintDialog, TPrinterSetupDialog, TReplaceDialog, TSaveDialog components, TThread object

Description

Execute method for Common Dialog Boxes

Execute method for Batch Move components

Execute method for Thread objects


Execute method for Threads
Execute method

See also

Applies to

TThread object

Declaration

procedure Execute;

Description

Protected and abstract. You must override Execute in your thread class. Execute is where you put the code you want your thread to execute. Returning from Execute terminates the thread, frees the thread's stack, and calls the OnTerminate event handler (if there is one).  Your Execute method must periodically check the Terminated property; when True, Execute must return immediately. Failure to do so means that your thread won't terminate when the Terminate method is called.


See also

OnTerminate event

Terminated property


Execute Method of Color, Font, Open, Save, and Print Common Dialog Boxes
Execute method

Example

Applies to

TColorDialog, TFontDialog, TOpenDialog, TPrintDialog, TPrinterSetupDialog, TSaveDialog components

Declaration

function Execute: Boolean;

Description

The Execute method displays the dialog box in the application and returns True when the user closes the dialog box by choosing the OK button. If the user chooses Cancel or closes the dialog box by using the system menu, Execute returns False.


Example

This example uses a main menu component, a memo, an Open dialog box, and a Save dialog box on a form. To use it, you need to create a File menu that includes an Open command. This code is an event handler for the OnClick event of the Open command on the File menu. If the user has selected a filename by choosing the Open dialog box's OK button, the code sets the Save dialog box Filename property to the same filename, and displays the selected filename as the caption of the form.

procedure TForm1.Open1Click(Sender: TObject);

begin

  if OpenDialog1.Execute then

  begin

    Memo1.Lines.LoadfromFile(OpenDialog1.FileName);

    SaveDialog1.Filename := OpenDialog1.FileName;

    Caption := OpenDialog1.FileName;

  end;

end;


Execute method for Batch Move components
Execute method

Example

Applies to

TBatchMove component

Declaration

procedure Execute;

Description

The Execute method performs the batch move operation specified by Mode from the Source table to the Destination table.


Example

BatchMove1.Execute;


ExecuteMacro method

See also	Example

Applies to

TDDEClientConv component

Declaration

function ExecuteMacro(Cmd: PChar; WaitFlg: Boolean): Boolean;

Description

The ExecuteMacro method attempts to send a macro command string to a DDE server application. ExecuteMacro returns True if the macro was successfully passed to the DDE server application. If ExecuteMacro was unable to send a command string, ExecuteMacro returns False.

Cmd is a null-terminated string that contains the macro to be executed by the DDE server application. The actual value of Cmd depends on the DDE server application. See the documentation of the DDE server application for the command strings it will accept.

WaitFlg determines if your application should wait until the DDE server application finishes executing the macro before allowing another successful call to ExecuteMacro or the ExecuteMacroLines, PokeData, or PokeDataLines methods. If WaitFlg is set to True, subsequent calls to these methods before the DDE server application completes the first macro do not send data to the DDE server and return False. If WaitFlg is set to False, subsequent calls to these methods before the DDE server application completes the first macro do attempt to send data to the DDE server.

If you need to send a macro command string list rather than a single string, use the ExecuteMacroLines method.

Note:	Depending on the DDE server, attempting to execute a macro or poke data before the DDE server application completes the first macro might cause the first macro to execute unsuccessfully or produce unpredictable results. See the documentation of the DDE server application for the results of sending command strings or poking data before macro execution has completed.


Example

The following code executes the macro that is specified by the Text of Edit1. The macro sets WaitFlg to True to wait until the server has completed macro execution.

var

  TheMacro: PChar;

begin

  StrPCopy(TheMacro, Edit1.Text);

  DDEClientConv1.ExecuteMacro(TheMacro, True);

end;


See also

StrPCopy function


ExecuteMacroLines method

Example

Applies to

TDDEClientConv component

Declaration

function ExecuteMacroLines(Cmd: TStrings; WaitFlg: Boolean): Boolean;

Description

The ExecuteMacroLines method attempts to send a macro command string list to a DDE server application. ExecuteMacroLines returns True if the macro was successfully passed to the DDE server application. If ExecuteMacroLines was unable to send a command string list, ExecuteMacroLines returns False.

Cmd contains the macro to be executed by the DDE server application. WaitFlg determines if your application should wait until the DDE server application finishes executing the macro before allowing another successful call to ExecuteMacroLines or the ExecuteMacro, PokeData, or PokeDataLines methods.

Use ExecuteMacroLines to execute a macro command string list rather than a single macro command string (which is what the ExecuteMacro method passes for its Cmd parameter).


Example

The following code executes the macro that exists in the Lines of Memo1. Wait is a boolean variable that specifies whether to wait for the server to complete macro processing before sending more data to the server.

DDEClientConv1.ExecuteMacroLines(Memo1.Lines, Wait);


ExeName property

See also	Example

Applies to

TApplication component

Declaration

property ExeName: string;

Description

Run-time and read-only. The ExeName property contains the name of the executable application including path information. The name of the application is the name you gave the project file with an .EXE extension. If you haven't specified a name, the default name is PROJECT1.EXE.


Example

This code displays the current name of the application's .EXE file in a label control when the user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := Application.ExeName;

end;

For example, if the application name is C:\DELPHI\WORK\MYAPP.EXE, that entire string appears in the label control.


See also

Title property


Expand method

Applies to

TList, TOutlineNode, TTreeNode objects

Description

Expand Method for Lists

Expand Method for Outline Nodes

Expand Method for Tree Node Objects


Expand method

See also	Example

Applies to

TList objects

Declaration

function Expand: TList;

Description

The Expand method increases the maximum size of the list maintained by a list object, creating more space to add new list items and incrementing the value of the Capacity property. If the value of the Capacity property is greater than 8, the Expand method increases the capacity of the list by 16. If the value of Capacity is greater than 4, but less than 9, then the capacity of the list increases by 8. Finally if the value of Capacity is less than 4, then the capacity of the list grows by 4.

The returned value is the expanded list.


Example

The following code expands List1.

List1.Expand;


See also

Capacity property


Expand method

See also	Example

Applies to

TOutlineNode objects

Declaration

procedure Expand;

Description

The Expand method expands an outline item by assigning True to its Expanded property. When an outline item is expanded, its sub-items are displayed and the minus picture or open picture might be displayed, depending on the outline style specified in the OutlineStyle property of the TOutline component.


Example

The following code expands the first child of the first outline item, if it has children.

with Outline1.Items[1] do

  if HasItems then

    Outline1.Items[GetFirstChild].Expand;


See also

Collapse method

FullCollapse method

FullExpand method

PictureMinus property

PictureOpen property


Expand method for tree node objects
Expand method

See also	Example

Applies to

TTreeNode object

Declaration

procedure Expand(Recurse: Boolean);

Description

The Expand method expands an item's list of child items. When an item is expanded, its subitems are displayed and the minus '-' button might be displayed, depending on whether the tree view's ShowButtons property is set. If Recurse is True, all child items are expanded as well.


Example

The following example expands the list of child items of the selected item in TreeView1.

TreeView1.Selected.Expand(True);


See also

OnExpanded event

OnExpanding event

FullExpand method

Expanded property

Collapse method


ExpIndex property

Applies to

TQuery, TStoredProc, TTable components

Declaration

property ExpIndex: Boolean;

Description

Run-time and read-only. ExpIndex is True if the current index is a dBASE expression index. ExpIndex is always False for Paradox and SQL tables.


Expanded property

See also	Example

Applies to

TOutlineNode , TTreeNode object

Declaration

property Expanded: Boolean;

Description

Run-time only. The Expanded property specifies whether the outline item or tree node is expanded or not. When an outline item is expanded, its subitems are displayed and the minus picture or open picture might be displayed, depending on the outline style specified in the OutlineStyle property of the TOutline component for the outline item. When a tree node is expanded, its subitems are displayed and the minus button may be displayed if the ShowButtons property of the TTreeView component is True.

Expanded is True if the item is expanded, False if it isn't expanded.


Example

The following code toggles the state of the selected outline item.

with Outline1 do

  Items[SelectedItem].Expanded := not Items[SelectedItem].Expanded;


See also

Collapse method

Expand method

FullCollapse method

FullExpand method

PictureMinus property

PictureOpen property


Expression property

Applies to

TIndexDef object

Declaration

property Expression: string;

Description

Run-time and read-only. Read expressions in dBASE indexes.


ExtendedSelect property

See also

Applies to

TListBox component

Declaration

property ExtendedSelect: Boolean;

Description

The ExtendedSelect property determines if the user can select an range of items in the list box. ExtendedSelect works in conjunction with the MultiSelect property. If MultiSelect is False, the setting of ExtendedSelect has no effect as the user will not be able to select more than one item at a time in the list box.

If MultiSelect is True and ExtendedSelect is True, the user can select an item then hold down the Shift key and select another and all the items in between the two selected items also become selected. If the user doesn't hold down the Shift or Ctrl key while selecting a second item, the first selected item becomes unselected--in other words, the user must use the Ctrl key to select multiple noncontiguous items, or the Shift key to select a range of items. If ExtendedSelect is False, the user can select multiple items without using the Shift or Ctrl key, but they can't select a range of items in one operation.


See also

MultiSelect property


Field property

Applies to

TColumn object; TDBCheckBox, TDBComboBox, TDBEdit, TDBImage, TDBListBox, TDBMemo, TDBRadioGroup, TDBText components

Description

Field Property for Data-Aware Controls

Field Property for Columns


Field property

Applies to

TDBCheckBox, TDBComboBox, TDBEdit, TDBImage, TDBListBox, TDBMemo, TDBRadioGroup, TDBText components

Declaration

property Field: TField;

Description

Run-time and read-only. The Field property returns the TField object the data-aware control is linked to. Use the Field object when you want to change the value of the data in the field programmatically.


Field property

Applies to

TColumn object

Declaration

property Field: TField;

Description

Field is the TField object corresponding to the field in the dataset the TColumn object displays. The Columns Editor assigns Field at design time, so you'd only need to do so if you were creating column objects at run-time.


FieldByName method

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

function FieldByName(const FieldName: string): TField;

Description

The FieldByName method returns the TField with the name passed as the argument in FieldName. Using FieldByName protects your application from a change in the order of the fields in the dataset. If the field cannot be found, FieldByName raises an exception. If you are not certain whether a field with the requested name exists, use the FindField method.


Example

with Table1 do

  begin

  { This is the safe way to change 'CustNo' field }

    FieldByName('CustNo').AsString := '1234';

  { This is *not* the safe way to change 'CustNo' field }

    Fields[0].AsString := '1234';

  end;


FieldClass property

Applies to

TFieldDef object

Declaration

property FieldClass: TFieldClass;

Description

Run-time and read-only. Read FieldClass to determine the type of the TField component that corresponds to this TFieldDef object.


FieldCount property

See also	Example

Applies to

TDBGrid, TDBLookupList, TQuery, TStoredProc, TTable components

Declaration

property FieldCount: Integer;

Description

Run-time and read-only. The FieldCount property specifies the number of fields (columns) in a dataset. It may not be the same as the number of fields in the underlying data set, because you can add calculated fields and remove fields with the fields editor.

For the data grid and database lookup list box, the value of the FieldCount property is the number of fields in the dataset displayed in the control.


Example

This example displays a message box with the names of all fields in the table.

procedure TForm1.Button2Click(Sender: TObject);

var

   i: Integer;

   Info: String;

begin

   Info := 'The fields are:'#13#10#13#10;

   for i := 0 to Table1.FieldCount - 1 do

      Info := Info + Table1.Fields[i].FieldName + #13#10;

   ShowMessage(Info);

end;


See also

Fields property

SelectedField property


FieldDefs property

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property FieldDefs: TFieldDefs;

Description

Run-time only. The FieldDefs property holds information about each TFieldDef in the dataset. You can use this property to determine which fields are in the dataset, their name, type, and size.


See also

Fields property

TField component


FieldKind property

Applies to

All field components

Declaration

property FieldKind: TFieldKind;

Description

Run-time only. FieldKind indicates whether a field represents a column in a data set (fkData), or if it's a calculated field (fkCalculated) or a lookup field (fkLookup). You can set FieldKind directly, or you can change the field's Calculated and Lookup properties.


FieldName property

Applies to

TColumn object, All field components

Descriptions

FieldName Property for Field Components

FieldName Property for Columns


FieldName property

See also

Applies to

All field components

Declaration

property FieldName: string;

Description

FieldName is the name of the physical column in the underlying dataset to which a TField component is bound. FieldName is used as a default column heading by the data grid when the DisplayLabel property is null. For calculated fields, supply a FieldName when you define the field. For non-calculated fields, an exception occurs if a FieldName is not a column name in the physical table.


See also

DisplayName property


FieldName property

Applies to

TColumn object

Declaration

property FieldName: String;

Description

FieldName is the name of the field the TColumn object displays. The Columns Editor assigns FieldName at design time, so you'd only need to do so if you were creating column objects at run-time. Setting FieldName changes the Field property to the field object with the specified field name.


FieldNo property

Applies to

TFieldDef object; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

FieldNo Property for TFieldDef Objects

FieldNo Property for Field Components


FieldNo property

See also	Example

Applies to

TFieldDef objec

Declaration

property FieldNo: Integer;

Description

Run-time and read-only. FieldNo is the physical field number used by the Borland Database Engine to reference the field.


Example

This example displays the field name and number.

with FieldDef1 do

  MessageDlg(Name + ' is field ' + IntToStr(FieldNo), mtInformation, [mbOK], 0);


See also

TField component


FieldNo property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property FieldNo: Integer;

Description

Run-time and read-only. FieldNo is the ordinal of the TField component in its dataset. This property is available for programs that make direct calls to the Borland Database Engine.


Fields property

Applies to

TIndexDef object; TDBGrid, TDBLookupList, TQuery, TStoredProc, TTable components

Description

Fields Property for TIndexDef Objects

Fields Property for Grids, Lookup Lists, Tables, Queries, and Stored Procedures


Fields property

See also	Example

Applies to

TDBGrid, TDBLookupList, TQuery, TStoredProc, TTable components

Declaration

property Fields[Index: Integer]: TField;

Description

Run-time only. The Fields property returns a specific field in the dataset. Specify the field using the Index parameter. By default, Index values start at 0 with the first field in the data set; if you used the fields editor to create field objects, Index values start at 0 in the order listed in the fields editor. The range for Index is 0..FieldCount - 1.


Example

This example displays a message box listing the names of all the field objects

being displayed in a TDBGrid. note that to get a useful result requires you to

use the fields editor to create field objects.

procedure TForm1.Button3Click(Sender: TObject);

var

   i: Integer;

   Info: String;

begin

   Info := 'The grid''s field objects are:'#13#10#13#10;

   for i := 0 to Table1.FieldCount - 1 do

     with DBGrid1.Fields[i] do

       if Name <> '' then

         Info := Info + Name + #13#10;

   ShowMessage(Info);

end;


See also

FieldCount property

FieldDefs property

SelectedField property

SelectedIndex property


Fields property

Applies to

TIndexDef object

Declaration

property Fields: string;

Description

Run-time and read-only. Fields is a string consisting of the names or numbers of the fields comprising the index, separated by semicolons (";"). When numbers are used, they are the physical field numbers in the table; for example, 1..N.


FieldValues property

Applies to

TQuery, TStoredProc, TTable components

Declaration

property FieldValues[const FieldName: string]: Variant; default;

Description

The FieldValues array property returns the value of the field with the specified name as a Variant. Using a name as the array index protects your code from relying on numeric indexes, which change if the order of fields in a table change. Returning the value as a variant lets you avoid specifying how to return the field value (for example, using the AsInteger or AsString properties).

FieldValues is the default array property for all dataset components, which means that you don't have to specify the FieldValues name as part of your expression. For example:

Table1['FieldName'] := 'FieldValue';


FileEdit property

See also	Example

Applies to

TFileListBox component

Declaration

property FileEdit: TEdit;

Description

The FileEdit property provides a simple way to display a file selected in a file list box as the text of an edit box, as is commonly done in Open and Save dialog boxes. If no file is selected in the file list box, the text of the edit box is the current value of the file list box's Mask property.

Specify the edit box you want the mask or selected file to appear in as the value of the FileEdit property.


Example

This example uses a button, an edit box, a label, a drive combo box, a directory list box, a file list box, and a filter combo box on a form. When the user clicks the button, the rest of the controls of the form begin working together like the controls in an Open or Save dialog box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DriveComboBox1.DirList := DirectoryListBox1;

  DirectoryListBox1.FileList := FileListBox1;

  DirectoryListBox1.DirLabel := Label1;

  FileListBox1.FileEdit := Edit1;

  FilterComboBox1.FileList := FileListBox1;

end;


See also

DirLabel property

DirList property

FileList property

Mask property

Text property


FileEditStyle property

See also

Applies to

TOpenDialog, TSaveDialog components

Declaration

property FileEditStyle: TFileEditStyle;

Description

The FileEditStyle property is obsolete and is provided for backwards compatibility only.


See also

HistoryList property

TFilterComboBox component


FileList property

See also	Example

Applies to

TDirectoryListBox, TFilterComboBox components

Declaration

property FileList: TFileListBox;

Description

The FileList property is used for two different purposes, depending on the type of control it is a property of.

For directory list boxes, FileList provides a simple way to connect a directory list box with a file list box. Once the two controls are connected and new directory is selected as the current directory using a directory list box, the file list box displays the files in the current directory. Specify the file list box in which you want to display the files in the directory selected in the directory list box as the value of the FileList property.

For filter combo boxes, FileList provides a simple way to connect a filter combo box with a file list box. Once the two controls are connected and a new filter is selected using a filter combo box, the file list box displays the files that match the selected filter. Specify the file list box you want to display the files matching the selected filter as the value of the FileList property.


Example

This example uses a button, an edit box, a label, a drive combo box, a directory list box, a file list box, and a filter combo box on a form. When the user clicks the button, the rest of the controls on the form begin working together like the controls in an open or save dialog box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DriveComboBox1.DirList := DirectoryListBox1;

  DirectoryListBox1.FileList := FileListBox1;

  DirectoryListBox1.DirLabel := Label1;

  FileListBox1.FileEdit := Edit1;

  FilterComboBox1.FileList := FileListBox1;

end;


See also

DirLabel property

Directory property

DirList property

FileEdit property

FileList property

Filter property

Mask property


FileLoad method

See also

Applies to

TImageList component

Declaration

function FileLoad(ResType: TResType; Name: string; MaskColor: TColor): Boolean;

Description

The FileLoad method loads a file of type TResType into the ImageList. The MaskColor is used to set the transparent color for the images in the file.


See also

GetResource method

ResourceLoad method

Masked property


FileName property

Applies to

TFileListBox, TMediaPlayer, TOpenDialog, TSaveDialog components; TIniFile object

Description

The FileName property specifies the name of a file.

FileName property for Open and Save dialog boxes

FileName property for Media Player components

FileName property for File List Box components

FileName property for IniFile objects


FileName Property for Open and Save Common Dialog Boxes
FileName property

See also	Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property FileName: TFileName;

Description

The FileName property specifies the file name that appears in the File Name edit box when the dialog box opens. The user can then select that filename or specify any other. Once the user specifies a filename and chooses OK, the value of the FileName property becomes the name of the file the user selected.

The path name can include a path. For example, to open the file README.TXT in the directory C:\TEMP, set FileName to C:\TEMP\README.TXT.

The FileName property can be set to the name of a file that doesn't exist in the current directory. In an Open dialog box, you can use this capability to let the user open a new file, and in a Save dialog box, the user can save a file that hasn't been saved before.


Example

This example displays an Open dialog box and suggests the filename LIST.PAS to the user. Once the user selects a filename, the code displays that name in a label on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  OpenDialog1.FileName := 'LIST.PAS';

  if OpenDialog1.Execute then

    Label1.Caption := OpenDialog1.FileName;

end;


See also

Files property


FileName Property for Media Player Component
FileName property

Example

Applies to

TMediaPlayer component

Declaration

property FileName: string;

Description

The FileName property specifies the media file to be opened by the Open method, or the file to save by the Save method. At design time, you can use a file open dialog box to specify the FileName property by clicking the ellipses button (...) in the Object Inspector.


Example

The following code determines what type of media device to open from the results of an Open dialog box, then opens the file.

if OpenDialog1.Execute then

begin

  MediaPlayer1.DeviceType := dtAutoSelect;

  MediaPlayer1.FileName := OpenDialog1.FileName;

  MediaPlayer1.Open;

end;


FileName Property for TIniFile Objects
FileName property

See also	Example

Applies to

TFileListBox component

Declaration

property FileName: string;

Description

Run-time only. The FileName property contains the name of the selected file in the list box, including the path name.


Example

This example uses a file list box and a label on a form. When the user selects a file in the file list box, the name of the file appears as the caption of the label.

procedure TForm1.FileListBox1Click(Sender: TObject);

begin

  Label1.Caption := FileListBox1.FileName;

end;


See also

FileList property


FileName Property for TIniFile Objects
FileName property

Applies to

TIniFile object

Declaration

property FileName: string;

Description

Run-time and read-only. The FileName property contains the name of the .INI file the TIniFile object encapsulates.


Files property

See also	Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property Files: TStrings;

Description

Run-time and read-only. The Files property value contains a list of all the file names selected in the Open or Save dialog box including the path names.

To let users select multiple file names in the dialog box, include ofAllowMultiSelect in the Options property set (set ofAllowMultiSelect to True).

The first item in the list of names is returned as the value of the FileName property. FileName will contain only the first 127 characters.


Example

This example uses an Open dialog box, a list box, and a button on a form. When the user clicks the button, the Open dialog box appears. When the user selects files in the dialog box and chooses the OK button, the list of selected files appears in the list box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  OpenDialog1.Options := [ofAllowMultiSelect];

  OpenDialog1.Filter := 'All files (*.*)|*.*';

  if OpenDialog1.Execute then

    ListBox1.Items := OpenDialog1.Files;

end;


See also

Filter property

Options property


FileType property

See also	Example

Applies to

TFileListBox component

Declaration

property FileType: TFileType;

Description

The FileType property determines which files are displayed in the file list box based on the attributes of the files. Because FileType is of type TFileType, which is a set of file attributes, FileType can contain multiple values. For example, if the value of FileType is a set containing the values ftReadOnly and ftHidden, only files that have the read-only and hidden attributes are displayed in the list box. These are the values that can occur in the FileType property:

Value	Meaning

ftReadOnly	When ftReadOnly is True, the list box can display files with the read-only attribute.

ftHidden	When ftHidden is True, the list box can display files with the hidden attribute.

ftSystem	When ftSystem is True, the list box can display files with the system attribute.

ftVolumeID	When ftVolumeID is True, the list box can display the volume name.

ftDirectory	When ftDirectory is True, the list box can display directories.

ftArchive	When ftArchive is True, the list box can display files with archive attribute.

ftNormal	When ftNormal is True, the list box can display files with no attributes.

If you use the Object Inspector to change the value of FileType, click the FileType property to see the attribute values. Then you can set each value to True or False, which builds the FileType set.


Example

This example uses a file list box on a form. When the application runs, only read-only files, directories, volume IDs, and files with no attributes appear in the list box.

procedure TForm1.FormCreate(Sender: TObject);

begin

  FileListBox1.FileType := [ftReadOnly, ftDirectory, ftVolumeID, ftNormal];

end;


See also

Mask property

TFileType type


FillRect method

See also	Example

Applies to

TCanvas object

Declaration

procedure FillRect(const Rect: TRect);

Description

The FillRect method fills the specified rectangle on the canvas using the current brush.


Example

This code creates a rectangle on the form's canvas and colors it red by changing the canvas Brush property to clRed.

procedure TForm1.ColorRectangleClick(Sender: TObject);

var

  NewRect: TRect;

begin

  NewRect := Rect(20, 30, 50, 90);

  Form1.Canvas.Brush.Color := clRed;

  Form1.Canvas.FillRect(NewRect);

end;


See also

Brush property

Rect function


Filter property

Applies to

TFilterComboBox, TOpenDialog, TSaveDialog, TTable, TQuery, TStoredProc components

Description

The Filter property specifies a file mask for a component.

Filter Property for Open and Save Dialog Boxes

Filter Property for Filter Combo Box Components

Filter Property for Tables, Queries and Stored Procedures


Filter property

See also	Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property Filter: string;

Description

The Filter property determines the file masks available to the user for use in determining which files display in the dialog box's list box.

A file mask or file filter is a file name that usually includes wildcard characters (*.PAS, for example). Only files that match the selected file filter are displayed in the dialog box's list box, and the selected file filter appears in the File Name edit box. To specify a file filter, assign a filter string as the value of Filter. To create the string, follow these steps:

1	Type some meaningful text that indicates the type of file.

2	Type a | character (this is the "pipe" or "or" character).

3	Type the file filter.

Don't put in any spaces around the | character in the string.

Here's an example:

OpenDialog1.Filter := 'Text files|*.TXT'

If you entered the preceding example as the Filter of an Open or Save dialog box, the string "Text files" appears in the List Files of Type drop-down list box when the dialog box appears in your application, the file filter appears in the File Name edit box, and only .TXT files appear in the list box. You can specify multiple file filters so that a list of filters appears in the List Files of Type drop-down list box or in the filter combo box. This allows the user to select from a number of file filters and determine which files are displayed in the list box.

To specify multiple file filters,

1	Create a file filter string as previously shown.

2	Type another file filter in the same way, but separate the second file filter from the first with the | character.

3	Continue adding as many file filters as you like, separating them with the | character. The string can be up to 255 characters.

Here's an example of three file filters specified as the value of the Filter property:

'Text files (*.TXT)|*.TXT|Pascal files (*.PAS)|*.PAS|Quattro Pro files (*.WB1)|*.WB1'

Now when the dialog box appears, the user can choose from three file filters that appear in the List Files of Type drop-down list box.

Note that the previous example includes the file filters in parentheses in the text parts. This isn't required, but it's a common convention that helps users understand what to expect when they select a file filter.

You can string multiple wildcard file filters together if you separate them with semicolons:

OpenDialog1.Filter := 'All files|*.TXT;*.PAS;*.WB1';


Example

This code sets the value of the Filter property, displays the dialog box, and assigns the file name the user selects to a variable:

procedure TForm1.Button1Click(Sender: TObject);

var

  NameOfFile : TFileName;

begin

  OpenDialog1.Filter := 'Text files (*.TXT)|*.TXT|Pascal files (*.PAS)' +

    '|*.PAS|Quattro Pro files (*.WB1)|*.WB1';

  if OpenDialog1.Execute then

    NameOfFile := OpenDialog1.FileName;

  ...

end;


See also

FileName property

FilterIndex property


Filter property

See also	Example

Applies to

TFilterComboBox components

Declaration

property Filter: string;

Description

The Filter property determines the file masks displayed in the filter combo box.

A file mask or file filter is a file name that usually includes wildcard characters (*.PAS, for example). When your application runs, the file filter the user selects in the filter combo box becomes the value of the Mask property. To specify a file filter, assign a filter string as the value of Filter. To create the string, follow these steps:

1	Type some meaningful text to indicate the type of file.

2	Type a | character (this is the "pipe" or "or" character).

3	Type the file filter.

Don't put in any spaces around the | character in the string.

Here's an example:

FilterComboBox1.Filter := 'Text files|*.TXT';

If you entered this string, the string "Text files" appears in the filter combo box.

You can specify multiple file filters so that a list of filters appears in the filter combo box from which the user can select. To specify multiple file filters,

1	Type a file filter as shown previously.

2	Type another file filter in the same way, but separate the second file filter from the first with the | character.

3	Continue adding as many file filters as you like, separating them with the | character. The string can be up to 255 characters.

Here's an example of three file filters specified as the value of the Filter property:

'Text files (*.TXT)|*.TXT|Pascal files (*.PAS)|*.PAS|Quattro Pro files (*.WB1)|*.WB1'

Note that the previous example includes the file filters in parentheses in the text parts. This isn't required, but it's a common convention that helps users understand what to expect when they select a file filter.

You can string multiple wildcard file filters together if you separate them with semicolons:

FilterComboBox1.Filter := 'All files|*.TXT;*.PAS;*.WB1';


Examples

This example uses a filter combo box on a form. When the application runs, three filters appear in the filter combo box:

procedure TForm1.FormCreate(Sender: TObject);

begin

  FilterComboBox1.Filter := 'Text files (*.TXT)|*.TXT|Pascal files (*.PAS)' +

  '|*.PAS|Quattro Pro files (*.WB1)|*.WB1';

end;

This example uses a filter combo box, a file list box, and an edit box on a form. The code connects the three controls through the FileList and FileEdit properties. When the user selects a filter in the filter combo box, the filter is applied to the files in the list box so the list box displays only the files that match the filter. The filter in effect on the file list box appears in the edit box. When the user selects a file in the file list box, the selected file appears in the edit box.

procedure TForm1.FormCreate(Sender: TObject);

begin

  FilterComboBox1.Filter := 'All files (*.*)|*.*|Pascal files (*.pas)|' +

    '*.PAS|DLLs (*.dll)|*.DLL';

  FilterComboBox1.FileList := FileListBox1;

  FileListBox1.FileEdit := Edit1;

end;


See also

FileList property

Mask property


Filter property

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property Filter: string;

Description

The Filter property is a string that lets you specify which records you want to see in the data set. Filters are similar to, though less powerful than, queries, with the benefit that filters work on the data set itself, meaning that the result is always "live" (unlike queries which sometimes produce result sets that can't be modified). You can turn a filter on and off by changing the Filtered property.

The syntax for the filter string is very similar to that used in the WHERE clause of an SQL statement. You can compare fields to other fields and to literal values, using the comparison operators in the following table:

Operator	Meaning

<	Less than

>	Greater than

>=	Greater than or equal to

<=	Less than or equal to

=	Equal to

<>	Not equal

For example,

PatientAge >= 18

Temperature < 212

SalePrice < BulkPrice

You can use the AND, NOT, and OR operators to combine comparisons:

(PatientAge >= 18) AND (Balance > 0)

(Temperature < 212) AND (NOT Windy)

(SalePrice < BulkPrice) OR (Terms > 30)

Enclose field names with spaces in square brackets:

[Patient Age] > 18


See also

FilterOptions property

OnFilterRecord event


Filtered property

See also

Applies to

TQuery, TStoredProc, TTable components

Declaration

property Filtered: Boolean;

Description

Filtered lets you turn off the filtering provided by the Filter property and the OnFilterRecord event. If you set Filtered to True, the filter is activated and only records meeting the filter criteria will be visible. If you set Filtered to False, all records in the data set become visible (minus those that are already excluded because of range and master/detail settings).


See also

FilterOptions property


FilterIndex property

See also	Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property FilterIndex: Integer;

Description

The FilterIndex property determines which file filter specified in the Filter property appears as the default file filter in the List Files of Type drop-down list box. For example, if you set the FilterIndex value to 2, the second file filter listed in the Filter property becomes the default filter when the dialog box appears. The default FilterIndex value is 1. If you specify a value greater than the number of file filters in the Filter property, the first filter is chosen.

The default value is 1.


Example

This code specifies three file filters as the value of the Filter property, sets the FilterIndex to 2 so that the second file filter is the default file filter, and displays the Open dialog box. Once the user selects a file with the dialog box and chooses OK, the filename the user selected appears in a label on the form.

procedure TForm1.Button1Click(Sender: TObject);

begin

  OpenDialog1.Filter := 'Text files (*.TXT)|*.TXT|Pascal files (*.PAS)' +

    '|*.PAS|dBASE program files (*.PRG)|*.PRG';

  OpenDialog1.FilterIndex := 2;

  if OpenDialog1.Execute then

    Label1.Caption := OpenDialog1.FileName;

end;


See also

Filter property


FilterOptions property

See also

Applies to

TQuery, TStoredProc, TTable components

Declaration

property FilterOptions: TFilterOptions;

Description

FilterOptions lets you fine-tune the filtering provided by the Filter property.


See also

Filtered property


Find method

Applies to

TFieldDefs, TStringList objects

Description

Find Method for Field Definitions

Find Method for String List Objects


Find method

See also	Example

Applies to

TStringList objects

Declaration

function Find(const S: string; var Index: Integer): Boolean;

Description

The Find method searches for a specified string in the list of strings kept in a string list object. If the string specified as the value of the S parameter is found, Find returns True and the position of the string in the string list is stored as the value of the Index parameter. Because the index is zero-based, the first string in the string list has an index value of 0, the second string has an index value of 1, and so on.

Find returns False if the specified string is not found. Use Find with sorted lists only. For unsorted lists use the IndexOf method instead.


Example

This example uses a list box and a label on a form. When the application runs, a string list object is created and three strings are added to it. The Find method searches the strings to look for a match with the string 'Flowers'. If the string is found, all the strings in the string list are added to the list box, and the index value of the 'Flowers' string appears in the caption of the label control.

procedure TForm1.FormCreate(Sender: TObject);

var

  MyList: TStringList;

  Index: Integer;

begin

  MyList := TStringList.Create;

  MyList.Add('Animals');

  MyList.Add('Flowers');

  MyList.Add('Cars');

  MyList.Sort;

  if MyList.Find('Flowers', Index) then

  begin

    ListBox1.Items.AddStrings(MyList);

    Label1.Caption := 'Flowers has an index value of ' + IntToStr(Index);

  end;

  MyList.Free;

end;


See also

Add method

Clear method

IndexOf method

Strings property


Find method

See also	Example

Applies to

TFieldDefs objects

Declaration

function Find(const Name: string): TFieldDef;

Description

The Find method returns a pointer to an entry in the Items property whose Name property matches the Name parameter. Use this method to obtain information about a particular TFieldDef object.


Example

This example displays the field name and number.

MessageDlg('CustNo is field ' + IntToStr(FieldDefs.Find('CustNo').FieldNo),   mtInformation, [mbOK], 0);


See also

Name property


FindCaption method

See also

Applies to

TListView component

Declaration

function FindCaption(StartIndex: Integer; Value: string; Partial, Inclusive, Wrap: Boolean): TListItem;

Description

Run-time only. The FindCaption method searches for and returns a list view item with the specified characteristics. The search will start at the list item specified by StartIndex. It will search for the caption specified by Value. If Partial is True, it will find the caption that begins with the string specified by Value. If Inclusive is True, it will include the list item with StartIndex in the search. If Wrap is True, the search continues at the beginning if no match is found. If no item is found, nil is returned.


See also

Caption property

Items property

Index property

FindData method


FindComponent method

See also	Example

Applies to

All components

Declaration

function FindComponent(const AName: string): TComponent;

Description

The FindComponent method returns the component in the Components array property with the name that matches the string in the AName parameter. FindComponent is not case sensitive.


Example

To set up this example, place several components on a form, including an edit box and a button. When the user clicks the button, the code displays the value of the ComponentIndex of the edit box in the edit box.

procedure TForm1.Button1Click(Sender: TObject);

var

  TheComponent: TComponent;

begin

  TheComponent := FindComponent('Edit1');

  Edit1.Text := IntToStr(TheComponent.ComponentIndex);

end;


See also

ComponentCount property

ComponentIndex property

Components property


FindData method

See also

Applies to

TListView component

Declaration

procedure FindData(StartIndex: Integer; Value: Pointer; Inclusive, Wrap: Boolean): TListItem;

Description

Run-time only. The FindData method searches for and returns a list view item with the specified characteristics. The search will start at the list item specified by StartIndex. It will search for the data item specified by Value. If Inclusive is True, it will include the list item with StartIndex in the search. If Wrap is True, the search continues at the beginning if no match is found. If no item is found, nil is returned.


See also

Data property

FindCaption method


FindDatabase method

See also	Example

Applies to

TSession component

Declaration

function FindDatabase(const DatabaseName: string): TDatabase;

Description

The FindDatabase method attempts to find a TDatabase component in the Databases collection with a DatabaseName property which matches the DatabaseName parameter. If there is no such database, FindDatabase returns nil.


Example

MyDatabase := Session.FindDatabase('MYDB');


See also

Session variable


FindField method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

function FindField(const FieldName: string): TField;

Description

The FindField method returns the field with the name passed in FieldName. While calling FindField is slightly slower than a direct reference to the Fields property, using FindField protects your application from a change in the order of the fields in the component. If the field can not be found, FindField returns nil.


Example

with Table1 do

  begin

  { This is the safe way to change 'CustNo' field }

    FindField('CustNo').AsString := '1234';

  { This is *not* the safe way to change 'CustNo' field }

    Fields[0].AsString := '1234';

  end;


See also

FieldByName method


FindFirst method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function FindFirst: Boolean;

Description

FindFirst provides a way for you to find the first record that meets certain criteria. You specify the criteria by writing an OnFilterRecord event handler or specifying filter criteria in the Filter property. (The Filtered property doesn't have to be True when you call FindFirst; if necessary, FindFirst turns on filtering to find the first matching record, then turns it off.) FindFirst returns True if a record matching the criteria is found and False if not.


See also

FindLast method

FindNext method

FindPrior method

First method

Found property


FindIndexForFields method

Applies to

TIndexDefs object

Declaration

function FindIndexForFields(const Fields: string): TIndexDef;

Description

Run-time and read-only. Returns the TIndexDef object that is present in Items corresponding to a semicolon-separated list of fields.


FindItem method

See also	Example

Applies to

TMainMenu component

Declaration

function FindItem(Value: Word; Kind: TFindItemKind): TMenuItem;

Description

The FindItem method returns the menu item owned by the menu that has either a menu handle, menu command, or menu shortcut matching the value of the Value parameter. The Kind parameter can be any of these values:

Value	Meaning

fkCommand	Menu command number used by Windows WM_COMMAND message

fkHandle	Menu handle

fkShortCut	Menu shortcut


Example

This example uses a label, a button, and a main menu component. The menu is a File menu that contains Open, Save, and Close commands. Delphi automatically names the menu items that are the commands, Open1, Save1, and Close1. The Open1 menu item has a ShortCut value of F3. The code locates the menu item that has the specified shortcut and reports the name of the menu item in the caption of the label.

Note that the shortcut is specified as a virtual key code. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

procedure TForm1.Button1Click(Sender: TObject);

var

  ItemName: TMenuItem;

begin

  ItemName := MainMenu1.FindItem(VK_F3, fkShortCut);

  Label1.Caption := ItemName.Name;

end;


See also

Command property

ShortCut property

TMenuItem component


FindKey method

See also	Example

Applies to

TTable component

Declaration

function FindKey(const KeyValues: array of const): Boolean;

Description

The FindKey method searches the database table to find a record whose index fields match those passed in KeyValues. FindKey takes a comma-delimited array of values as its argument, where each value corresponds to a index column in the underlying table. The values can be literals, variables, null, or nil. If the number of values supplied is less than the number of columns in the database table, then the remaining values are assumed to be null. FindKey will search for values specified in the array in the current index.

FindKey does the following:

Puts the TTable in SetKey state.

Finds the record in the table that matches the specified values. If a matching record is found, it moves the cursor there, and returns True.

If a matching record is not found, it does not move the cursor, and returns False.


Example

This example will search for CustNo = '1234':

if Table1.FindKey(['1234']) then

   ShowMessage('Customer Found');


See also

FindNearest method

GotoKey method


FindLast method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function FindLast: Boolean;

Description

FindLast provides a way for you to find the last record that meets certain criteria. You specify the criteria by writing an OnFilterRecord event handler or specifying filter criteria in the Filter property. (The Filtered property doesn't have to be True when you call FindLast; if necessary, FindLast turns on filtering to find the last matching record, then turns it off.) FindLast returns True if a record matching the criteria is found and False if not.


See also

FindFirst method

FindNext method

FindPrior method

Found property

Last method


FindNearest method

See also	Example

Applies to

TTable component

Declaration

procedure FindNearest(const KeyValues: array of const);

Description

The FindNearest method moves the cursor to the first record whose index fields' values are greater than or equal to those passed in KeyValues. The search begins at the first record, not at the current cursor position. This method can be used to match columns of string data type only. If you do not supply values for each field in the index key, any unassigned fields will use a null value.

FindNearest works by default on the primary index column. To search the table for values in other indexes, you must specify the field name in the table's IndexFieldNames property or the name of the index in the IndexName property.

The KeyExclusive property indicates whether a search will position the cursor on or after the specified record being searched for.

Note:	With Paradox or dBASE tables, FindNearest works only with indexed fields. With SQL databases, it can work with any columns specified in the IndexFieldNames property.


Example

This example will search for CustNo >= '1234':

Table1.FindNearest(['1234']);


See also

FindKey method

GotoKey method

GotoNearest method

TField component


FindNext method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function FindNext: Boolean;

Description

FindNext provides a way for you to find the next record that meets certain criteria. You specify the criteria by writing an OnFilterRecord event handler or specifying filter criteria in the Filter property. (The Filtered property doesn't have to be True when you call FindNext; if necessary, FindNext turns on filtering to find the next matching record, then turns it off.) FindNext returns True if a record matching the criteria is found and False if not.


See also

FindFirst method

FindLast method

FindPrior method

Found property

Next method


FindNextPage method

See also	Example

Applies to

TPageControl component

Declaration

function FindNextPage(CurPage: TTabSheet; GoForward, CheckTabVisible: Boolean): TTabSheet;

Description

The FindNextPage method returns the next page in the TPageControl before or after CurPage depending on the value of GoForward. Each page is a TTabSheet object. To select the next page at design-time, right click the TPageControl and choose Next Page.

When CheckTabVisible is True, FindNextPage returns the next page with a TabVisible property set to True; if CheckTabVisible is False, FindNextPage returns the next page, including pages with TabVisible set to False. FindNextPage is useful in accessing a tab sheet that does not have a visible tab.

It the GoForward parameter is True, FindNextPage will find the next page in the page control after CurPage; if GoForward is False, FindNextPage will find the next page previous to CurPage.


Example

The following code allows the user to select tab sheets by clicking on a button rather than a tab:

procedure TForm1.Button1Click(Sender: TObject);

begin

  With PageControl1 do

    ActivePage := FindNextPage(ActivePage,True,True);

end;


See also

ActivePage property

PageCount property

Pages property

SelectNextPage method


FindPrior method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function FindPrior: Boolean;

Description

FindPrior provides a way for you to find the previous record that meets certain criteria. You specify the criteria by writing an OnFilterRecord event handler or specifying filter criteria in the Filter property. (The Filtered property doesn't have to be True when you call FindPrior; if necessary, FindPrior turns on filtering to find the previous matching record, then turns it off.) FindPrior returns True if a record matching the criteria is found and False if not.


See also

FindFirst method

FindLast method

FindNext method

Found property

Prior method


FindSession method

See also

Applies to

TSessionList object

Declaration

function FindSession(const SessionName: string): TSession;

Description

FindSession returns the TSession component whose SessionName property matches the name you supply as a parameter to FindSession. If you pass an empty string, FindSession returns the default global Session variable. If you pass a string that doesn't match the SessionName of any session, FindSession returns nil.


See also

GetSessionNames method

List property

Sessions variable


FindText property

See also	Example

Applies to

TFindDialog, TReplaceDialog components

Declaration

property FindText: string;

Description

The FindText property contains the string your application can search for if it uses the Find dialog box.

You can specify a FindText value before the user displays the Find dialog box so that when it appears, the FindText value appears in the Find What edit box. The user can then either accept or change the FindText value before choosing the Find Next button in the dialog box.


Example

The following OnFind event handler searches a memo component for the text specified in the FindText property of a find dialog component. If found, the first occurrence of the text in Memo1 is selected. The code uses the Pos function to compare strings, and stores the number of characters to skip when determining the selection position in the SkipChars variable. Because there is no handling of case, whole word, or search direction in this algorithm, it is assumed that the Options property of FindDialog1 was set to [frHideMatchCase, frHideWholeWord, frHideUpDown].

procedure TForm1.FindDialog1Find(Sender: TObject);

var

  I, J, PosReturn, SkipChars: Integer;

begin

  For I := 0 to Memo1.Lines.Count do

  begin

    PosReturn := Pos(FindDialog1.FindText,Memo1.Lines[I]);

    if PosReturn <> 0 then {found!}

      begin

        Skipchars := 0;

        for J := 0 to I - 1 do

          Skipchars := Skipchars + Length(Memo1.Lines[J]);

        SkipChars := SkipChars + (I*2);

        SkipChars := SkipChars + PosReturn - 1;

        Memo1.SetFocus;

        Memo1.SelStart := SkipChars;

        Memo1.SelLength := Length(FindDialog1.FindText);

      end;

  end;

end;


See also

ReplaceText property


FindText method for rich edit controls
FindText method

Applies to

TRichEdit component

Declaration

procedure FindText(const SearchStr: string; StartPos, Length: Integer; Options: TSearchTypes); Integer;

Description

The FindText method searches for a string in the text of a TRichEdit given a text range to search, the string, and search parameters of TSearchTypes. With the search parameters you can specify whether or not to search using case-sensitivity and whole word. The FindText method does a forward search only.


First method

Applies to

TList object; TQuery, TStoredProc, TTable components

Description

First Method for List Objects

First Method for Queries, Tables, and Stored Procedures


First method

See also	Example

Applies to

TList object

Declaration

function First: Pointer;

Description

The First method returns a pointer that points to the first item referenced in the List property, which is indexed by Items[0].


Example

The following code assumes that the items in MyList are objects that have a text field named Desc. If the Desc of the first item in the list is 'Blue', the following code changes it to 'Green'.

if MyList.First.Desc = 'Blue' then MyList.First.Desc := 'Green';


See also

IndexOf method

Last method


First method

See also

Applies to

TQuery, TStoredProc, TTable components

Declaration

procedure First;

Description

The First method moves the cursor to the first record in the active range of records of the dataset. The active range of records is affected by the filter established with ApplyRange.

If the dataset is in Edit or Insert state, First will perform an implicit Post of any pending data.


See also

Last method

MoveBy method

Next method

Prior method

SetRange method

SetRangeStart method


FirstIndent property

See also

Applies to

TParaAttributes object

Declaration

property FirstIndent: Longint;

Description

The FirstIndent property contains the size in pixels of the indentation of the first line in the currently selected paragraph in a TRichEdit control. It is one of several properties of the TParaAttributes object which is the type of the run-time, read-only Paragraph property of TRichEdit. The properties of the TParaAttributes object contain information about the indentation, numbering and tabs in the currently selected paragraph.


See also

LeftIndent property

Paragraph property

RightIndent property


FirstIndex property

See also	Example

Applies to

TTabSet component

Declaration

property FirstIndex: Integer;

Description

Run-time only. The value of the FirstIndex property is the tab that appears in the leftmost visible position in the tab set control. Any tabs with a lower value in the FirstIndex property scroll to the left in the tab set control and don't appear until the user scrolls the tabs.

The default value of FirstIndex is 0 indicating that the tab with an index of 0 is in the leftmost position. For example, if you have three tabs labeled First, Second, and Third with TabIndex values of 0, 1, and 2, respectively, First appears first, by default, because it has an index value of 0. If you want to shift the tabs so the Second or Third tab appears leftmost in the tab set control, change the FirstIndex value to 1 or 2.


Example

This example uses a tab set control, a label, and a button on a form.

This code in an event handler creates 20 tabs labeled Tab 1 through Tab 20 when Form1 is created:

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to 19 do

   TabSet11.Tabs.Add('Tab ' + IntToStr(I));

end;

Users can scroll through the tabs. When they click the button, the caption of the first tab visible in the tab set control is displayed in the label control.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  Label1.Caption := IntToStr(TabSet11.FirstIndex);

end;


See also

TabIndex property

Tabs property


FixedColor property

See also	Example

Applies to

TDBGrid, TDrawGrid, TStringGrid components

Declaration

property FixedColor: TColor;

Description

The value of the FixedColor property determines the color of nonscrolling or fixed columns and rows within the grid. Refer to the Color property for a list of the possible values for FixedColor.

The default color is clBtnFace, the color of the face of a button.


Example

This example uses a draw grid and a button on a form. When the user clicks the button, the color of the nonscrolling (fixed) rows and columns of the draw grid changes color.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if DrawGrid1.FixedColor = clBlue then

    DrawGrid1.FixedColor := clLime

  else

    DrawGrid1.FixedColor := clMaroon;

end;


See also

Color property

FixedCols property

FixedRows property


FixedCols property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property FixedCols: Integer;

Description

The FixedCols property determines the number of nonscrolling columns within a grid. The default value is 1. Nonscrolling columns remain fixed at the far left of the grid, even when the user scrolls the other columns. Nonscrolling columns are useful for displaying row titles that need to remain visible in the grid at all times.

Each grid must have a least one column that isn't fixed. In other words, the value of the FixedCols property must always be at least one less than the value of the ColCount property, which contains the number of columns in the grid.


Example

This example uses a string grid and a button. When the user clicks the button, a message dialog box appears informing the user that a fixed column number of 2 is recommended. The dialog box also offers the user an opportunity to accept the recommended number if the number of fixed columns isn't already 2. If the user chooses Yes, the number of fixed columns changes to 2.

procedure TForm1.Button1Click(Sender: TObject);

var

  Check: Integer;

begin

  if StringGrid1.FixedCols <> 2 then

  begin

    Check := MessageDlg('2 fixed columns are recommended!  Change?',

        mtWarning, mbYesNoCancel, 0);

    if Check = IdYes then

       StringGrid1.FixedCols := 2;

  end;

end;


See also

FixedColor property

FixedRows property

LeftCol property


FixedRows property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property FixedRows: Integer;

Description

The FixedRows property determines the number of nonscrolling rows within a grid. The default value is 1. Nonscrolling rows remain fixed at top of the grid, even when the user scrolls the other rows. Nonscrolling rows are useful for displaying column titles that need to remain visible in the grid at all times.

Each grid must have a least one row that isn't fixed. In other words, the value of the FixedRows property must always be at least one less than the value of the RowCount property, which contains the number of rows in the grid.


Example

This example uses a string grid and three radio buttons on a form. With the Object Inspector, specify the following event handler for all OnClick events of the three radio buttons. As the user selects different radio buttons, the number of fixed rows in the string grid changes.

procedure TForm1.RadioButton1Click(Sender: TObject);

begin

  if RadioButton1.Checked then

    StringGrid1.FixedRows := 1

  else if RadioButton2.Checked then

    StringGrid1.FixedRows := 2

  else if RadioButton3.Checked then

    StringGrid1.FixedRows := 3;

end;


See also

FixedColor property

FixedCols property

TopRow property


FloodFill method

See also	Example

Applies to

TCanvas object

Declaration

procedure FloodFill(X, Y: Integer; Color: TColor; FillStyle: TFillStyle);

Description

The FloodFill method fills an area of the screen surface using the current brush specified by the Brush property. The FloodFill method begins at the point at coordinates (X, Y) and continues in all directions to the color boundary.

The way in which the area is filled is determined by the FillStyle parameter. If FillStyle is fsBorder, the area fills until a border of the color specified by the Color parameter is encountered. If FillStyle is fsSurface, the area fills as long as the color specified by the Color parameter is encountered. fsSurface fills are useful to fill an area with a multicolored border.


Example

The following code floodfills from the center point of Form1's client area until the color black is encountered.

Form1.Canvas.FloodFill(ClientWidth div 2, ClientHeight div 2, clBlack, fsBorder);


See also

Ellipse method

FillRect method

Polygon method

Rectangle method


FocusControl method

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

function FocusControl;

Description

Sets a form's focus to the first data-aware component associated with a TField. Use this method when doing record-oriented validation (for example, in the BeforePost event) since a field may be validated whether its associated data-aware components have focus.


Example

The following code sets the focus to the first data-aware component associated with Field1:

Field1.FocusControl;


FocusControl property

See also	Example

Applies to

TLabel component

Declaration

property FocusControl: TWinControl;

Description

The FocusControl links the label control with another control on the form. If the Caption of a label includes an accelerator key, the control specified as the value of the FocusControl property becomes the focused control when the user uses the accelerator key.

The caption of a label often identifies the purpose of another control on the form, or directs the user to interact with it. For example, a label placed right above an edit box might have the caption '&File Name', indicating the user should type a file name in the edit box. In this case, making that edit box the value of the label's FocusControl property gives the edit box the focus when the user presses Alt+F.


Example

This code displays a line of text in a label on the form and associates the label with an edit box control. Note that the label caption includes an accelerator key. When the user presses Alt+N, the edit box control receives the focus:

Label1.Caption := '&Name';

Label1.FocusControl := Edit1;

For this example, you need to place the label and edit box control close together to make sure that users understand that they should enter text in the edit box.


See also

ShowAccelChar property

TabStop property


Focused method

See also	Example

Applies to

All windowed controls

Declaration

function Focused: Boolean;

Description

The Focused method is used to determine whether a windowed control has the focus and is therefore is the ActiveControl.


Example

This example uses an edit box and a memo on a form. When the user switches the focus between the two controls, the control that currently has the focus becomes red:

type

  TForm1 = class(TForm)

    Edit1: TEdit;

    Memo1: TMemo;

    Button1: TButton;

    procedure FormCreate(Sender: TObject);

  private

    { Private declarations }

  public

    procedure ColorControl(Sender: TObject);

  end;

var

  Form1: TForm1;

implementation

{$R *.DFM}

procedure TForm1.ColorControl(Sender: TObject);

begin

  if Edit1.Focused then

    Edit1.Color := clRed

  else

    Edit1.Color := clWindow;

  if Memo1.Focused then

    Memo1.Color := clRed

  else

    Memo1.Color := clWindow;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Screen.OnActiveControlChange := ColorControl;

end;


See also

ActiveControl property

OnActiveControlChange event

SetFocus method


Focused property for tree views
Focused property

See also	Example

Applies to

TTreeNode, TListItem objects

Declaration

property Focused: Boolean;

Description

Run-time only. The Focused property determines whether the item has the focus, that is, it's surrounded by a standard focus rectangle. Only one item can have the focus.


Example

The following code sets the focus to the selected item.

TreeView1.Selected.Focused := True;


See also

OnChange event

OnChanging event

SelectedIndex property

OnGetSelectedIndex event

Selected property


Font property

Applies to

TCanvas object; TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TFontDialog, TForm, TGroupBox, THeader, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBox, TSpeedButton, TStatusBar, TStringGrid, TTabbedNotebook, TTabSet, TTreeView, THeaderControl components

Description

Font Property for Font Dialog Boxes

Font Property for All Other Components and Objects


Font property

See also	Example

Applies to

TFontDialog components

Declaration

property Font: TFont;

Description

The Font property is the font the Font dialog box returns when the user uses the Font dialog box. Your application can then use this returned Font value for further processing.

You can also specify a default font before displaying the Font dialog box; the font name then appears selected in the Font combo box. Use the Object Inspector to specify a Font property, or assign a value to Font before using the Execute method to display the dialog box.


Example

This example uses a button, a Font dialog box, and a label on a form. When the user clicks the button, the Font dialog box appears. If the user uses the dialog box to change the font and chooses OK, the caption of the label changes to reflect the user's font selection.

procedure TForm1.Button1Click(Sender: TObject);

begin

  FontDialog1.Font.Name := 'System';

  FontDialog1.Font.Size := 10;

  if FontDialog1.Execute then

    Label1.Font := FontDialog1.Font;

end;


See also

Color property

Name property

Size property


Font property

See also	Example

Applies to

TCanvas object; TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TGroupBox, THeader, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBox, TSpeedButton, TStatusBar, TStringGrid, TTabbedNotebook, TTabSet, TTreeView components

Declaration

property Font: TFont;

Description

The Font property is a font object that controls the attributes of text written on or in the component or object or sent to the printer. To modify a font, you change the value of the Color, Name, Size, or Style properties of the font object.

Note :	The THeader control does not support font colors. If you want to use other colors, use owner-draw to draw the sections yourself.


Example

This code changes color of text in a memo control to dark blue:

Memo1.Font.Color := clNavy;


See also

ParentFont property


Fonts property

See also	Example

Applies to

TPrinter object; TScreen component

Declaration

property Fonts: TStrings;

Description

Run-time and read-only. The Fonts property for the screen component returns a list of fonts supported by the screen.

The Fonts property for a printer object holds a list of fonts supported by the printer. The list contains TrueType fonts even if the printer doesn't support them natively because the Windows Graphics Device Interface (GDI) can draw TrueType fonts accurately when a print job uses them.


Example

This code displays the fonts supported by the screen in a FontList list box when the user clicks the ListFonts button:

procedure TForm1.ListFontsClick(Sender: TObject);

begin

  FontList.Clear;

  FontList.Sorted := True;

  FontList.Items := Screen.Fonts;

end;


See also

Canvas property

Screen variable

Printer variable


ForceDirectories procedure

See also	Example

Unit

FileCtrl

Declaration

procedure ForceDirectories(Dir: string);

Description

Whenever you create directories using DOS and Windows, you must create one at a time. For example, if you want to create the C:\APPS\SALES\LOCAL directory, the APPS and SALES directories must exist before you can create the LOCAL directory.

The ForceDirectories can create all the directories specified along a directory path all at once if they don't exist. If the first directories in the path do exist, but the latter ones don't, ForceDirectories creates just the ones that don't exist.


Example

This example uses a label and a button on a form. When the user clicks the button, all the directories along the specified path that don't exist are created. The results are reported in the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

var

  Dir: string;

begin

  Dir := 'C:\APPS\SALES\LOCAL';

  ForceDirectories(Dir);

  if DirectoryExists(Dir) then

    Label1.Caption := Dir + ' was created'

end;


See also

DirectoryExists function

SelectDirectory function


Format strings

Format strings passed to the string formatting routines contain two types of objects--plain characters and format specifiers. Plain characters are copied verbatim to the resulting string. Format specifiers fetch arguments from the argument list and apply formatting to them.

Format specifiers have the following form:

"%" [index ":"] ["-"] [width] ["." prec] type

A format specifier begins with a % character. After the % come the following, in this order:

An optional argument index specifier, [index ":"]

An optional left justification indicator, ["-"]

An optional width specifier, [width]

An optional precision specifier, ["." prec]

The conversion type character, type

The following table summarizes the possible values for type:

  d  	Decimal. The argument must be an integer value. The value is converted to a string of decimal digits. If the format string contains a precision specifier, it indicates that the resulting string must contain at least the specified number of digits; if the value has less digits, the resulting string is left-padded with zeros.

  e  	Scientific. The argument must be a floating-point value. The value is converted to a string of the form "-d.ddd...E+ddd". The resulting string starts with a minus sign if the number is negative. One digit always precedes the decimal point.

 	The total number of digits in the resulting string (including the one before the decimal point) is given by the precision specifier in the format string--a default precision of 15 is assumed if no precision specifier is present. The "E" exponent character in the resulting string is always followed by a plus or minus sign and at least three digits.

  f  	Fixed. The argument must be a floating-point value. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative.

 	The number of digits after the decimal point is given by the precision specifier in the format string--a default of 2 decimal digits is assumed if no precision specifier is present.

  g  	General. The argument must be a floating-point value. The value is converted to the shortest possible decimal string using fixed or scientific format. The number of significant digits in the resulting string is given by the precision specifier in the format string--a default precision of 15 is assumed if no precision specifier is present.

 	Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format.

  n  	Number. The argument must be a floating-point value. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The "n" format corresponds to the "f" format, except that the resulting string contains thousand separators.

  m  	Money. The argument must be a floating-point value. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, DecimalSeparator, and CurrencyDecimals global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panel. If the format string contains a precision specifier, it overrides the value given by the CurrencyDecimals global variable.

  p  	Pointer. The argument must be a pointer value. The value is converted to a string of the form "XXXX:YYYY" where XXXX and YYYY are the segment and offset parts of the pointer expressed as four hexadecimal digits.

  s  	String. The argument must be a character, a string, or a PChar value. The string or character is inserted in place of the format specifier. The precision specifier, if present in the format string, specifies the maximum length of the resulting string. If the argument is a string that is longer than this maximum, the string is truncated.

  x  	Hexadecimal. The argument must be an integer value. The value is converted to a string of hexadecimal digits. If the format string contains a precision specifier, it indicates that the resulting string must contain at least the specified number of digits; if the value has fewer digits, the resulting string is left-padded with zeros.

Conversion characters may be specified in uppercase as well as in lowercase--both produce the same results.

For all floating-point formats, the actual characters used as decimal and thousand separators are obtained from the DecimalSeparator and ThousandSeparator global variables.

Index, width, and precision specifiers can be specified directly using decimal digit string (for example "%10d"), or indirectly using an asterisk character (for example "%*.*f"). When using an asterisk, the next argument in the argument list (which must be an integer value) becomes the value that is actually used. For example,

Format('%*.*f', [8, 2, 123.456])

is the same as

Format('%8.2f', [123.456]).

A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (a "-" character preceding the width specifier), the result is left-justified by adding blanks after the value.

An index specifier sets the current argument list index to the specified value. The index of the first argument in the argument list is 0. Using index specifiers, it is possible to format the same argument multiple times. For example "Format('%d %d %0:d %d', [10, 20])" produces the string '10 20 10 20'.

The format strings are used by the following routines:

Format function

FormatBuf function

FmtStr procedure

StrFmt function

StrLFmt function


FormatChars property

Example

Applies to

TDDEClientConv component

Declaration

property FormatChars: Boolean;

Description

The FormatChars property determines if certain characters are filtered out of text data transferred from a DDE server application. Some DDE server applications transfer backspaces, linefeeds, carriage returns, and tabs with the text data. Sometimes, this can cause incorrect spacing, line breaks, or characters in the DDE client data. If this is the case, the characters should be filtered. The default value of FormatChars is False.

If False, all text characters of the linked data from the DDE server appear in the linked data in the DDE client. If True, ASCII characters 8 (backspace), 9 (tab), 10 (linefeed), and 13 (carriage return) are filtered out and won't appear in the DDE client data.


Example

The following code formats characters if the DDE service name is "SuperWrd".

if DDEClientConv.DDEService = 'SuperWrd' then

  DDEClientConv.FormatChars := True;


FormatCount property

See also	Example

Applies to

TClipboard object

Declaration

property FormatCount: Integer;

Description

Run-time and read-only. The FormatCount property value is the number of formats contained in the Formats array property of a Clipboard object.


Example

The following code adds each format on the Clipboard to ListBox1 when Button1 is clicked:

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to Clipboard.FormatCount-1 do

    ListBox1.Items.Add(IntToStr(Clipboard.Formats[I]));

end;


See also

Assign method

AsText property

Clipboard variable

GetComponent method

HasFormat method

SetComponent method


Formats property

See also	Example

Applies to

TClipboard object

Declaration

property Formats[Index: Integer]: Word;

Description

Run-time and read-only. The Formats property array contains a list of all the formats the Clipboard contains. Usually when an application copies or cuts something to the Clipboard, it places it there in multiple formats.

Your application can place items of a particular format on the Clipboard and retrieve items with a particular format from the Clipboard if the format is in the Formats array. You can find out if a particular format is available on the Clipboard with the HasFormat method.

The Index parameter of the Formats property lets you access a format by its position in the array.


Example

The following code adds each format on the Clipboard to ListBox1 when Button1 is clicked:

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to Clipboard.FormatCount-1 do

    ListBox1.Items.Add(IntToStr(Clipboard.Formats[I]));

end;


See also

Assign method

AsText property

Clipboard variable

FormatCount property

HasFormat method


FormCount property

See also	Example

Applies to

TScreen component

Declaration

property FormCount: Integer;

Description

Run-time and read-only. The FormCount property value contains the number of forms displayed on the screen.


Example

The following code adds the name of all forms on the screen to ListBox1 when Button1 is clicked.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  For I := 0 to Screen.FormCount-1 do

    ListBox1.Items.Add(Screen.Forms[I].Name);

end;


See also

Forms property

Screen variable


Forms property

See also	Example

Applies to

TScreen component

Declaration

property Forms[Index: Integer]: TForm;

Description

Run-time and read-only. The Forms property lets you access a form on the screen by specifying its position in the list of forms kept by the TScreen component using its Index value. The first form has an index value of 0, the second has an index value of 1, and so on.


Example

The following code adds the name of all forms on the screen to ListBox1 when Button1 is clicked.

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  For I := 0 to Screen.FormCount-1 do

    ListBox1.Items.Add(Screen.Forms[I].Name);

end;


See also

FormCount property

Screen variable


FormStyle property

See also	Example

Applies to

TForm component

Declaration

property FormStyle: TFormStyle;

Description

The FormStyle property determines the style of the form. These are the possible values and their meanings:

Value	Meaning

fsNormal	The form is neither an MDI parent window nor an MDI child window.

fsMDIChild	The form is an MDI child window.

fsMDIForm	The form is an MDI parent window.

fsStayOnTop	This form remains on top of other forms in the project, except any others that also have FormStyle set to fsStayOnTop.

The default value is fsNormal. Set this property at design-time as it is not advisable to change the value of FormStyle at run-time.

All MDI (Multiple Document Interface) applications must have the FormStyle property of the main form set to fsMDIForm. All forms specified as MDI child forms display as forms contained within the MDI parent form. You can have as many child forms as you like.


Example

This example ensures the main form of the application is an MDI parent form:

procedure TForm1.FormCreate(Sender: TObject);

begin

  if FormStyle <> fsMDIForm then

    FormStyle := fsMDIForm;

  if FormStyle = fsMDIForm then

    Edit1.Text := 'MDI form'

  else

    Edit1.Text := 'Not an MDI form';   {This line never runs}

end;


See also

CreateForm method

MainForm property

Visible property


Found property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property Found: Boolean;

Description

Run-time and read-only. Found is True if the FindFirst, FindLast, FindNext, or FindPrior methods found a record that matched the criteria specified in the OnFilterRecord event handler.


FrameRect method

See also	Example

Applies to

TCanvas object

Declaration

procedure FrameRect(const Rect: TRect);

Description

The FrameRect method draws a rectangle using the Brush of the canvas to draw the border. FrameRect does not fill the interior of the rectangle with the Brush pattern.


Example

The following code displays the text "Hello, world!" in a rectangle defined by the coordinates (10, 10) and (100, 100). After displaying the text with the TextRect method, the code draws a black, vertical line frame around the rectangle.

var

  TheRect: TRect;

begin

  Form1.Canvas.Brush.Color := clBlack;

  Form1.Canvas.Brush.Style := bsVertical;

  TheRect.Top := 10;

  TheRect.Left := 10;

  TheRect.Bottom := 100;

  TheRect.Right := 100;

  Form1.Canvas.TextRect(TheRect,10,10,'Hello, world!');

  Form1.Canvas.FrameRect(TheRect);

end;


See also

Brush property

Rect function

TextRect method


Frames property

Applies to

TMediaPlayer component

Declaration

property Frames: Longint;

Description

Run-time-only. The Frames property specifies the number of frames the Step method steps forward or the Back method steps backward.

Frames defaults to ten percent of the length of the currently loaded medium, which is specified by the Length property.

Note:	The definition of frame varies by multimedia device. For display media, a frame is one still image.


Free method

See also	Example

Applies to

All objects and components

Declaration

procedure Free;

Description

The Free method destroys the object and frees its associated memory. If you created the object yourself using the Create method, you should use Free to destroy and release memory. Free is successful even if the object is nil, so if the object was never initialized, for example, calling Free won't result in an error.

When you call Free for a component, it will call Free for all components that it owns, that is, all components in its component list. A form owns all the controls and non-visual components that are created on it in design mode. When it is freed, all of these components are automatically freed as well. Since, by default, all forms are owned by the Application object, when the application terminates, it frees the Application object, which frees all forms. For all objects that are not components, or for components created by a nil owner, be sure to call Free after you are finished with the object; otherwise the memory allocated to the object will not be usable until after the application terminates.

You should never explicitly free a component within one of its own event handlers, nor should you free a component from an event handler of a component the component owns or contains. For example, you should avoid freeing a button in its OnClick event handler. Nor should you free the form that owns the button from the button's OnClick event.

If you want to free the form, call the Release method, which destroys the form and releases the memory allocated for it after all its event handlers and those of the components it contains are through executing.


See also

Destroy method

Release method


FreeBookmark method

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure FreeBookmark(Bookmark: TBookmark);

Description

Use the FreeBookmark method in combination with the GetBookmark and GotoBookmark methods. FreeBookmark releases the system resources reserved during a call to GetBookmark.


Example

var MyBookmark: TBookmark;

...

with Table1 do

  begin

{ Save the current record position in MyBookmark }

  MyBookmark := GetBookmark;

  ... { Other code here }

{ Return to the record associated with MyBookmark }

  GotoBookmark(MyBookmark);

{ Release the resources for MyBookmark }

  FreeBookmark(MyBookmark);

  end;


Frequency property

See also

Applies to

TTrackBar component

Declaration

property Frequency: Integer;

Description

The Frequency property sets the internal frequency for tick marks on a track bar control. For example, a value of 2 will set a tick mark at every other increment. To use this property you must set the TickStyle of the TickMarks property to tsAuto.


See also

TickMarks property


FromPage property

See also	Example

Applies to

TPrintDialog component

Declaration

property FromPage: Integer;

Description

The value of the FromPage property determines on which page the print job begins. The default value is 0.


Example

This example uses a Print dialog box on a form. These lines set up the Print dialog box so that when it appears, the default values of 1 and 1 are the default starting and ending values for the Pages From and To edit boxes.

PrintDialog1.Options := [poPageNums];

PrintDialog1.FromPage := 1;

PrintDialog1.ToPage := 1;


See also

ToPage property


FullCollapse method

Applies to

TOutline, TOutlineNode, TTreeView components

Description

FullCollapse Method for Outlines

FullCollapse Method for Tree Views


FullCollapse method

See also	Example

Applies to

TOutline, TOutlineNode components

Declaration

procedure FullCollapse;

Description

FullCollapse collapses all the items within an outline.

For outlines, when an item is collapsed, its Expanded property is set to False, its subitems are hidden, and the closed or plus pictures might be displayed, depending on the outline style specified in the OutlineStyle property.


Example

The following code collapses the outline if the selected item is visible.

if Outline[Outline1.SelectedItem].IsVisible then

  Outline1.FullCollapse;


See also

Collapse method

Expand method

FullExpand method

OnCollapse event

PictureClosed property

PicturePlus property


FullCollapse method for tree views
FullCollapse method

See also

Applies to

TTreeView component

Declaration

procedure FullCollapse;

Description

The FullCollapse method collapses all the items within a tree view control. When collapsed, the child items are hidden.


See also

OnCollapsing event

OnCollapsed event

Collapse method

Expanded property

FullExpand method


FullExpand method for tree views
FullExpand method

Applies to

TOutlineNode object; TOutline, TTreeView components

Description

FullExpand method for outlines

FullExpand method for tree views


FullExpand method for tree views
FullExpand method

See also	Example

Applies to

TOutlineNode object; TOutline component

Declaration

procedure FullExpand;

Description

FullExpand expands the items within an outline. If the FullExpand method belongs to a TOutline component, all items in the outline are expanded. If the FullExpand method belongs to a TOutlineNode object, only the items on the same branch as the outline node are expanded. This means that all subitems are expanded, and all parents up to the top item on level 1 (specified by the TopItem property) are expanded. No items on other branches (with different level 1 parents) are expanded.

When an item is expanded, its Expanded property is set to True, its subitems are displayed, and the open or minus pictures might be displayed, depending on the outline style specified in the OutlineStyle property.


Example

The following code expands the outline if the selected item is not visible:

if not Outline1.Items[Outline1.SelectedItem].IsVisible then

  Outline1.FullExpand;


See also

Collapse method

Expand method

FullCollapse method

OnExpand event

PictureMinus property

PictureOpen property


FullExpand method for tree views
FullExpand method

See also

Applies to

TTreeView component

Declaration

Procedure FullExpand;

Description

The FullExpand method expands all items within a tree view control. When expanded, each child item is displayed below its corresponding parent item. If ShowButtons is True, then the any buttons will change from '+' to '-'.


See also

Expanded property

Expand method

FullCollapse method

OnExpanding event

OnExpanded event


FullPath property

See also	Example

Applies to

TOutlineNode object

Declaration

property FullPath: string;

Description

Run-time and read-only. The FullPath property specifies the path of outline items from the top item on level 1 to the item contained by the TOutlineNode. The path consists of the values of the Text properties of the outline items separated by the string specified in the ItemSeparator property of the TOutline component.


Example

The following code displays the full path of the selected outline item in Label1:

Label1.Caption := Outline1.Items[Outline1.SelectedItem].FullPath;


See also

Items property

SelectedItem property


GetAliasDriverName method

See also

Applies to

TSession component

Declaration

function GetAliasDriverName(const AliasName: string): string;

Description

The GetAliasDriverName method returns the database driver name associated with the given alias. Using GetAliasDriverName on a standard alias (for local table types such as Paradox and dBASE) returns a database driver name of STANDARD. For other aliases, the returned name will vary depending on the server type.


See also

GetAliasNames method

GetAliasParams method

GetDriverNames method

Session variable


GetAliasNames method

See also	Example

Applies to

TSession component

Declaration

procedure GetAliasNames(List: TStrings);

Description

The GetAliasNames method clears the parameter List and adds to it the names of all defined BDE aliases. Application-specific aliases are not included. The list returned will be determined by the current ConfigMode state.


Example

try

  MyStringList := TStringList.Create;

  Session.GetAliasNames(MyStringList);

finally

  MyStringList.Free;

end;


See also

GetDataBaseNames method

Session variable


GetAliasParams method

See also	Example

Applies to

TSession component

Declaration

procedure GetAliasParams(const AliasName: string; List: TStrings);

Description

The GetAliasParams method clears List and adds to it the parameters associated with the BDE alias passed in AliasName.


Example

try

  MyStringList := TStringList.Create;

  Session.GetAliasParams('DBDEMOS',MyStringList);

finally

  MyStringList.Free;

end;


See also

Session variable


GetAsHandle method

See also	Example

Applies to

TClipboard object

Declaration

function GetAsHandle (Format: Word): THandle;

Description

The GetAsHandle method returns the data from the Clipboard in a windows handle for the format specified in the Format parameter. For more information, see the Win32 Developer's Reference (WIN32.HLP) for information about the available formats.

Your application doesn't own the handle, so it should copy the data before using it.

Note:	The handle returned by GetAsHandle is only valid as long as the Clipboard is open. As soon as the Clipboard is closed, the handle is deallocated by Windows and is no longer accessible. It is recommended that if data associated with the handle is needed for a long period of time you should copy the data to another handle.


Example

The following code locks the memory for text on the Clipboard, then converts the text to a Pascal-style string.

var

  MyHandle: THandle;

  TextPtr: PChar;

  MyString: string;

begin

  ClipBoard.Open

  Try

    MyHandle := Clipboard.GetAsHandle(CF_TEXT);

    TextPtr := GlobalLock(MyHandle);

    MyString := StrPas(TextPtr);

    GlobalUnlock(MyHandle);

  finally

    Clipboad.Close;

  end;

end;


See also

FormatCount property

Formats property

HasFormat method

SetAsHandle method


GetBitmap method

See also

Applies to

TImageList component

Declaration

procedure GetBitmap(Index: Integer; Image: TBitmap);

Description

The GetBitmap method returns the image specified by the Index parameter as a bitmap into the provided TBitmap object.


See also

GetImageBitmap method

GetMaskBitmap method

ImageIndex property


GetBookmark method

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

function GetBookmark: TBookmark;

Description

The GetBookmark method saves the current record information of the dataset to allow you to return to that record with a later call to the GotoBookmark method. The bookmark should be eventually be passed to the FreeBookmark method to release the resources reserved during the call to GetBookmark. If the dataset is empty or not in Browse state, GetBookmark will return nil.

Note:	All bookmarks are invalidated when a dataset is closed and when a table's index is changed.


Example

var MyBookmark: TBookmark;

...

with Table1 do

  begin

{ Save the current record position in MyBookmark }

  MyBookmark := GetBookmark;

  ... { Other code here }

{ Return to the record associated with MyBookmark }

  GotoBookmark(MyBookmark);

{ Release the resources for MyBookmark }

  FreeBookmark(MyBookmark);

  end;


GetComponent method

See also	Example

Applies to

TClipboard object

Declaration

function GetComponent(Owner, Parent: TComponent): TComponent;

Description

The GetComponent method retrieves a component from the Clipboard and places it according to the value of the Owner and Parent parameters. With Owner, specify the component that becomes the owner of the retrieved component--usually this is a form. With Parent, specify the component that becomes the parent of the component. Both Owner and Parent can be nil.

Before a class can be read in from the Clipboard, it must first be registered with the Classes unit by calling RegisterClasses. If you attempt to read in a class that has not been registered, you will receive an EClassNotFound exception.


Example

This example uses a button and a group box on a form. When the user clicks the button, the button is copied to the Clipboard and then retrieved from the Clipboard and placed in the new parent of the button, the group box. The name of the original button is changed to an empty string to avoid having two components with the same name at the same time.

implementation

uses Clipbrd;

{$R *.DFM}

procedure TForm1.Button1Click(Sender: TObject);

begin

  Clipboard.SetComponent(Button1);                { copies button to the Clipboard }

  Button1.Name := '';          { prevents having two components with the same name }

  Clipboard.GetComponent(Self, GroupBox1);   { retrieves button from Clipboard and }

end;                                                  { places it in the group box }

initialization

  RegisterClasses([TButton]);                        { registers the TButton class }

end.


See also

AsText property

Owner property

Parent property

SetComponent method


GetConfigParams method

See also

Applies to

TSession component

Declaration

procedure GetConfigParams(const Path, Section: string; List: TStrings);

Description

The GetConfigParams method lets you query the Borland Database Engine for any type of configuration information. You're responsible for creating and destroying the string list you pass. The Path and Section names you supply depend on the type of information you're interested in. For example, a Path of '\SYSTEM\FORMATS\TIME' returns the settings the user chose in the Borland Database Engine Configuration utility for time formatting.

GetConfigParams uses the Format function to let you use formatting characters to substitute the Section name into the Path. For example, if you wanted to examine alias information, you could use a Path of '\DATABASES\%s\DB INFO' and a Section of the alias name. GetConfigParams would substitute the %s with the alias name and read the alias parameters into the string list.


See also

Session variable


GetData method

Applies to

TParam object; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

GetData for Field Components

GetData for TParam Objects


GetData method

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

function GetData(Buffer: Pointer): Boolean;

Description

GetData is the method used to obtain "raw" data from the field. Unlike the AsString, DisplayText, and Text properties, GetData performs no translation or interpretation of the data. Buffer must have sufficient space allocated for the data. Use the DataSize property to determine the space required. If the data is NULL, GetData returns False and no data is transferred to Buffer. Otherwise, it returns True.


Example

{ Retrieve the "raw" data from Field1 }

with Field1 do

  begin

{ Allocate space }

  GetMem(Buffer, DataSize);

  if not Field1.GetData(Buffer) then

    MessageDlg(FieldName + ' is NULL', mtInformation, [mbOK], 0)

  else { Do something with the data };

{ Free the space }

  FreeMem(Buffer, DataSize);

  end;


GetData method

See also	Example

Applies to

TParam object

Declaration

procedure GetData(Buffer: Pointer);

Description

The GetData method copies the current value of the parameter in native format to Buffer. Buffer must have enough space to hold the information; use the GetDataSize method to determine the requirement.


Example

var Buffer: Pointer;

{ Allocate enough space to hold the CustNo data }

GetMem(Buffer, Query1.ParamByName('CustNo').GetDataSize);

{ Retrieve the data }

Query1.ParamByName('CustNo').GetData(Buffer);


See also

SetData method


GetDatabaseNames method

See also	Example

Applies to

TSession component

Declaration

procedure GetDatabaseNames(List: TStrings);

Description

The GetDatabaseNames method clears List and adds to it the names of all BDE aliases and the database names of all TDatabase components.


Example

try

  MyStringList := TStringList.Create;

  Session.GetDatabaseNames(MyStringList);

finally

  MyStringList.Free;

end;


See also

GetAliasNames method

Session variable


GetDataItem method

See also	Example

Applies to

TOutline component

Declaration

function GetDataItem(Value: Pointer): Longint;

Description

The GetDataItem method returns the Index value of the first outline item that contains the data specified in the Value parameter in its Data property. Use GetDataItem when you have a pointer to data and you want to know which outline item contains the data.


Example

The following code displays the Text of the outline item that points to the variable P3 in its Data property. The text is displayed in a label.

Label1.Caption := Outline1.Items[GetDataItem(p3)].Text;


See also

GetItem method

GetTextItem method


GetDataSize method

Example

Applies to

TParam object

Declaration

function GetDataSize: Word;

Description

The GetDataSize method returns the number of bytes required to hold the parameter's value. Use GetDataSize in conjunction with the GetData method to allocate memory for the parameter's data.


Example

var Buffer: Pointer;

{ Allocate enough space to hold the CustNo data }

GetMem(Buffer, Query1.ParamByName('CustNo').GetDataSize);

{ Retrieve the data }

Query1.ParamByName('CustNo').GetData(Buffer);


GetDriverNames method

See also	Example

Applies to

TSession component

Declaration

procedure GetDriverNames(List: TStrings);

Description

The GetDriverNames method clears List and adds to it the names of all BDE drivers currently installed. This will not include 'PARADOX' or 'DBASE', since these databases are handled by the driver named 'STANDARD'.


Example

try

  MyStringList := TStringList.Create;

  Session.GetDriverNames(MyStringList);

finally

  MyStringList.Free;

end;


See also

Session variable


GetDriverParams method

See also	Example

Applies to

TSession component

Declaration

procedure GetDriverParams(const DriverName: string; List: TStrings);

Description

The GetDriverParams method clears List and adds to it the default parameters for the driver named in DriverName parameter. The driver named 'STANDARD' (used for Paradox and dBASE tables) has only one parameter, 'PATH='. SQL drivers will have varying parameters.


Example

try

  MyStringList := TStringList.Create;

  Session.GetDriverParams(MyStringList);

finally

  MyStringList.Free;

end;


See also

Session variable


GetFieldList method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure GetFieldList(List: TList; const FieldNames: string);

Description

The GetFieldList method fills a list object with the field objects representing the dataset's fields listed in FieldNames. To list more than one field in FieldNames, separate each field name with a semicolon. You're responsible for creating and destroying the list object.


See also

FieldByName method


GetFieldNames method

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure GetFieldNames(List: TStrings);

Description

The GetFieldNames method clears the TStrings argument, List, and then adds the name of each field in the dataset to it.


Example

var FieldNames: TStringList;

...

{ Initialize FieldNames to hold the names }

  FieldNames := TStringList.Create;

{ Get the names }

  Table1.GetFieldNames(FieldNames);

{ Do something with them }

...

{ Free the TStringList }

  FieldNames.Free;


GetFirstChild method

Applies to

TOutlineNode ,TTreeNode objects

Description

Get First Child method for Outlines

Get First Child method for Tree Node Objects


GetFirstChild method

See also	Example

Applies to

TOutlineNode object

Declaration

function GetFirstChild: Longint;

Description

The GetFirstChild method returns the Index value of the first subitem in an outline item. If the item has no subitems, GetFirstChild returns -1.


Example

The following code expands the selected outline item if it has children and then selects the first child.

with Outline1 do

if Items[SelectedItem].HasItems then

begin

  Items[SelectedItem].Expanded := True;

  SelectedItem := Items[Items[SelectedItem].GetFirstChild];

end;


See also

GetLastChild method

GetNextChild method

GetPrevChild method


GetFirstChild method for tree node objects
GetFirstChild method

See also

Applies to

TTreeNode object

Declaration

function GetFirstChild: TTreeNode;

Description

The GetFirstChild method returns the first child item (TTreeNode object) of the calling item. If the calling item has no children, GetFirstChild returns nil.


See also

GetLastChild method

GetNextChild method


GetFirstNode method

See also	Example

Applies to

TTreeNodes object

Declaration

function GetFirstNode: TTreeNode;

Description

The GetFirstNode method returns the first item (TTreeNode object) in the tree view.


Example

The following example adds the Text for the first item in the tree view to the list box.

ListBox1.Items.Add(TreeView1.Items.GetFirstNode.Text);


See also

GetNodeAt method

TopItem property

GetFirstChild method

GetNode method


GetFormImage method

See also	Example

Applies to

TForm component

Declaration

function GetFormImage: TBitmap;

Description

The GetFormImage returns a bitmap of the form as it appears when printed.


Example

This example uses an image, a button, and a shape component on a form. When the user clicks the button, an image of the form is stored in the FormImage variable and copied to the Clipboard. Then image of the form in then copied back to the image component, producing an interesting result, especially if the button is clicked multiple times.

procedure TForm1.Button1Click(Sender: TObject);

var

  FormImage: TBitmap;

begin

  FormImage := GetFormImage;

  try

    Clipboard.Assign(FormImage);

    Image1.Picture.Assign(Clipboard);

  finally

    FormImage.Free;

  end;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Shape1.Shape := stEllipse;

  Shape1.Brush.Color := clLime;

  Image1.Stretch := True;

end;


See also

PrintScale property


GetHelpContext method

See also

Applies to

TMainMenu component

Declaration

function GetHelpContext(Value: Word; ByCommand: Boolean): THelpContext;

Description

The GetHelpContext method returns the help context number associated with the menu identified by Value. If ByCommand is True, Value is the Command property of a TMenuItem. If ByCommand is False, Value is the Handle property.


See also

HelpContext property

HelpContext method

HelpJump method

OnHelp event


GetHitTestInfoAt method

See also	Example

Applies to

TTreeView component

Declaration

function GetHitTestInfoAt(X, Y: Integer): THitTests;

Description

The GetHitTestInfoAt method of the TTreeView component returns information about where a point is, relative to the client area of a tree view control. It returns a THitTests type which is a set of values indicating where the location X,Y is relative to the tree view control. The possible return values of GetHitTestInfoAt are:

Value	Meaning

htAbove	The point is above the client area of the tree view control.

htBelow	The point is below the client area of the tree view control.

htNowhere	The point is in the client area of the tree view control but below the last item.

htOnItem	The point is on the bitmap or label associated with an item.

htOnButton	The point is on the button associated with an item.

htOnIcon	The point is on the bitmap associated with an item.

htOnIndent	The point is on the indentation associated with an item.

htOnLabel	The point is on the label (text) associated with an item.

htOnRight	The point is in the area to the right of an item.

htOnStateIcon	The point is on the state icon for a tree view item that is in a user-defined state.

htToRight	The point is to the right of the client area of the tree view control.

htToLeft	The point is to the left of the client area of the tree view control.


Example

The following code checks a list of htHitTest types and adds the ones that occur when the mouse was pressed while on the tree view.

procedure TForm1.TreeView1MouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

var

  MyHitTest : THitTests;

begin

  MyHitTest := TreeView1.GetHitTestInfoAt(X,Y);

  if htNowhere in MyHitTest then

    ListBox1.Items.Add('NoWhere');

  if htOnItem in MyHitTest then

    ListBox1.Items.Add('OnItem');

  if htOnButton in MyHitTest then

    ListBox1.Items.Add('OnButton');

  if htOnIndent in MyHitTest then

    ListBox1.Items.Add('OnIndent');

  if htOnLabel in MyHitTest then

    ListBox1.Items.Add('OnLabel');

  if htOnRight in MyHitTest then

    ListBox1.Items.Add('OnRight');

end;


See also

ShowButtons property

ShowLines property

Indent property

MoveTo method

Insert method

Items property


Add method for image list objects
GetHotSpot method

See also

Applies to

TImageList component

Declaration

function GetHotSpot: TPoint;

Description

The GetHotSpot method returns the hot spot associated with the current drag image.


See also

DragLock method

DragUnlock method

DragMove method

SetDragImage method


GetIcon method

See also

Applies to

TImageList component

Declaration

procedure GetIcon(Index: Integer; Image: TIcon);

Description

The GetIcon method returns the image specified by Index as an icon into the provided icon object Image.


See also

GetBitmap method

GetMaskBitmap method

ImageIndex property


GetImageBitmap method

See also

Applies to

TImageList component

Declaration

function GetImageBitmap: HBITMAP;

Description

The GetImageBitmap method returns a handle to a bitmap containing all of the images in the ImageList.


See also

GetMaskBitmap method


GetIndexForPage method

Example

Applies to

TTabbedNotebook component

Declaration

function GetIndexForPage(const PageName: string): Integer;

Description

The GetIndexForPage method returns the PageIndex value of the specified page. The PageIndex property value is determined by the page's position in the Pages property array. Specify the name of the page as the value of the PageName parameter. The name you specify must be one of the strings in the Pages property.


Example

This example uses a tabbed notebook and a label on a form. When the form is created, pages are added to the tabbed notebook. The PageIndex value of the Preferences page appears in the caption of the label.

procedure TForm1.FormCreate(Sender: TObject);

begin

  with TabbedNotebook1 do

  begin

    Pages.Clear;

    Pages.Add('Styles');

    Pages.Add('Fonts');

    Pages.Add('Preferences');

  end;

  Label1.Caption := 'The Preferences page has an index of ' +

    IntToStr(TabbedNotebook1.GetIndexForPage('Preferences'));

end;


GetIndexNames method

See also	Example

Applies to

TTable component

Declaration

procedure GetIndexNames(List: TStrings);

Description

The GetIndexNames method adds the names of all available indexes for the TTable to the List parameter.


Example

var

  MyList: TStringList;

...

MyList := TStringList.Create;

Table1.GetIndexNames(MyList);

{ Do something with the names }

MyList.Free;


See also

IndexName property


GetItem method

See also	Example

Applies to

TOutline component

Declaration

function GetItem(X, Y: Integer): Longint;

Description

The GetItem method returns the Index value of the outline item that resides at the pixel coordinates (X, Y). Use GetItem when you want to know which outline item is in a specific screen location.


Example

The following code makes the item at screen coordinates (34,100) the selected item.

Outline1.SelectedItem := Outline1.GetItem(34,100);


See also

GetDataItem method

GetTextItem method


GetItemAt method

See also

Applies to

TListView component

Declaration

function GetItemAt(X, Y: Integer): TListItem;

Description

Run-time only. The GetItemAt method returns the list item that is found at the position specified by the parameters X and Y in pixels relative to the top left corner of the list view. If there is no item at the location, then nil is returned.


See also

Items property

Index property

GetNearestItem method

GetPosition method

GetNextItem method

DisplayRect method


GetItemPath method

See also	Example

Applies to

TDirectoryListBox component

Declaration

function GetItemPath(Index : Integer): string;

Description

The GetItemPath method returns as a string the path of a directory in a directory list box. Specify the directory with the Index value using the first directory in the list that has an index value of 0.


Example

This example uses a directory list box, a button, and a label on a form. When the user selects a directory in the directory list box and clicks the button, the selected directory opens, and the path of the second directory displayed in the list box appears as the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DirectoryListBox1.OpenCurrent;

  Label1.Caption := DirectoryListBox1.GetItemPath(1);

end;


See also

Directory property

Drive property

OpenCurrent method


GetLastChild method

Applies to

TOutlineNode, TTreeNode object

Description

GetLastChild Method for Outlines

GetLastChild Method for Tree Nodes


GetLastChild method

See also	Example

Applies to

TOutlineNode object

Declaration

function GetLastChild: Longint;

Description

The GetLastChild method returns the Index value of the last subitem in an outline item. If the item has no subitems, GetLastChild returns -1.


Example

The following code expands the selected outline item if it has children and then selects the last child.

with Outline1 do

if Items[SelectedItem].HasItems then

begin

  Items[SelectedItem].Expanded := True;

  SelectedItem := Items[Items[SelectedItem].GetLastChild];

end;


See also

GetFirstChild method

GetNextChild method

GetPrevChild method


GetLastChild method for tree node objects
GetLastChild method

See also

Applies to

TTreeNode object

Declaration

function GetLastChild: TTreeNode;

Description

The GetLastChild method returns the last immediate child item (TTreeNode object) of the calling item. If the calling item has no children, GetLastChild returns nil.


See also

GetFirstChild method

GetNextChild method

GetNext method

GetNextSibling method

GetNextVisible method

GetPrev method

GetPrevChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetLongHint function

See also	Example

Unit

Controls

Declaration

function GetLongHint(const Hint: string): string;

Description

The GetLongHint function returns the second part of the two-part string specified as the value of the Hint property. The second part of the string is the text following the | character. If the Hint string value is not separated into two parts, GetLongHint returns the entire Hint string.


Example

This code assigns a two-part string as to the Hint property of an edit box and then displays the "long" or second part of the string as the text of the edit box:

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  Edit1.Hint := 'Name|Enter full name';

  Edit1.Text := GetLongHint(Edit1.Hint);

end;


See also

GetShortHint function

OnHint event

ShowHint property


GetMaskBitmap method

See also

Applies to

TImageList component

Declaration

function GetMaskBitmap: HBITMAP;

Description

The GetMaskBitmap method returns a handle to a bitmap containing all of the masks for images in the ImageList.


See also

GetImageBitmap method


GetNearestItem method

See also

Applies to

TListView component

Declaration

function GetNearestItem(Point: TPoint; Direction: TSearchDirection): TListItem;

Description

Run-time only. The GetNearestItem method searches for and returns the list item nearest the list view item at the Point specified, in the direction given by the parameter Direction. Direction can be sdLeft, sdRight, sdAbove, sdBelow, and sdAll. If no item is found, nil is returned.


See also

TSearchDirection type

GetNextItem method

GetPosition method

GetItemAt method

Items property


GetNext method for tree node objects
GetNext method

See also

Applies to

TTreeNode object

Declaration

function GetNext: TTreeNode;

Description

The GetNext method returns the next item (TTreeNode object) after the calling item in the tree view. If the calling item is the last item, GetNext returns nil. It will return the next item including items that aren't visible and child items. To get the next item at the same level as the calling item, use GetNextSibling. To get the next visible item, use GetNextVisible.


See also

GetLastChild method

GetNextChild method

GetFirstChild method

GetNextSibling method

GetNextVisible method

GetPrev method

GetPrevChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetNextChild method

Applies to

TOutlineNode, TTreeNode objects

Description

GetNextChild Method for Outline Nodes

GetNextChild Method for Tree Nodes


GetNextChild method

See also	Example

Declaration

function GetNextChild(Value: Longint): Longint;

Description

The GetNextChild method returns the Index value of the next outline item that shares the same parent item as the item that has an Index value equal to the Value parameter. This is useful when the item indexed by Value has subitems, thus the index of its next sibling is not simply one more than Value. If the item indexed by Value has no next sibling, GetNextChild returns -1.


Example

The following code selects the next sibling of the selected item.

with Outline1 do

  SelectedItem := Items[SelectedItem].GetNextChild(SelectedItem);


See also

GetFirstChild method

GetLastChild method

GetPrevChild method


GetNextChild method for tree node objects
GetNextChild method

See also

Applies to

TTreeNode object

Declaration

function GetNextChild(Value: TTreeNode): TTreeNode;

Description

The GetNextChild method returns the next child item (TTreeNode object) after Value of the calling item. If the calling item has no children or there is no item after Value, GetNextChild returns nil.


See also

GetLastChild method

GetFirstChild method

GetNext method

GetNextSibling method

GetNextVisible method

GetPrev method

GetPrevChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetNextItem method

See also

Applies to

TListView component

Declaration

function GetNextItem(StartItem: TListItem; Direction: TSearchDirection; States: TItemStates): TListItem;

Description

Run-time only. The GetNextItem method returns the next list item after the StartItem in the direction given by Direction and in a state included in the States parameter. Direction can be sdLeft, sdRight, sdAbove, sdBelow, and sdAll. These are the possible values for the States parameter:

Value	Meaning

isNone	The item is in its default state.

isCut	The item is marked for a cut and paste operation

isDropHilited	The item is highlighted as a drag-and-drop target

isFocused	The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus

isSelected	The item is selected. The appearance of a selected item depends on whether it has the focus and on the system colors used for selection.


See also

GetNearestItem method

GetItemAt method

Items property


GetNextSibling method for tree node objects
GetNextSibling method

See also

Applies to

TTreeNode object

Declaration

function GetNextSibling: TTreeNode;

Description

The GetNextSibling method returns the next item (TTreeNode object) in the tree view at the same level as the calling item. GetNextSibling will return the next item, regardless if it's visible. To find the next item in the tree view including child items, use GetNext.


See also

GetLastChild method

GetNextChild method

GetNext method

GetFirstChild method

GetNextVisible method

GetPrev method

GetPrevChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetNextVisible method for tree node objects
GetNextVisible method

See also

Applies to

TTreeNode object

Declaration

function GetNextVisible: TTreeNode;

Description

The GetNextVisible method returns the next visible item(TTreeNode object) in the tree view after the calling item. An item is visible if its parent item is expanded.


See also

GetLastChild method

GetNextChild method

GetNext method

GetNextSibling method

GetFirstChild method

GetPrev method

GetPrevChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetNode method

See also

Applies to

TTreeNodes object

Declaration

function GetNode(ItemId: HTreeItem): TTreeNode;

Description

The GetNode method returns the item (TTreeNode object) given the ItemId of the tree node. ItemId is a handle to the item in the tree view.


See also

ItemId property

GetNodeAt method

TopItem property

GetFirstChild method

GetNode method


GetNodeAt method

See also	Example

Applies to

TTreeView component

Declaration

function GetNodeAt(X, Y: Integer): TTreeNode;

Description

The GetNodeAt method returns the node that is found at the position specified by the parameters X and Y in pixels relative to the top left corner of the tree view. If there is no node at the location, then nil is returned.


See also

Items property


GetParentForm function

See also	Example

Unit

Forms

Declaration

function GetParentForm(Control: TControl): TForm;

Description

The GetParentForm function returns the form that contains the control specified in the Control parameter. If the specified control is not on a form, GetParentForm returns nil.

If you'd rather have the function return an exception when the specified control is not on a form, use the ValidParentForm function.


Example

The following code shows the form that contains Button2:

GetParentForm(Button2).Show;


See also

ValidParentForm function


GetPassword method

See also

Applies to

TSession component

Declaration

function GetPassword: Boolean;

Description

The GetPassword method invokes the OnPassword event (if any) or displays the default password dialog box. It then returns True if the user chose the OK button and False if the user chose the Cancel button.


See also

Session variable


GetPosition method

See also

Applies to

TListItem object

Declaration

function GetPosition: TPoint;

Description

The GetPosition method returns the position of the item as a point.


See also

SetPosition method

GetItemAt method

Items property

GetNextItem method

GetNearestItem method


GetPrev method for tree node objects
GetPrev method

See also

Applies to

TTreeNode object

Declaration

function GetPrev: TTreeNode;

Description

The GetPrev method returns the previous item (TTreeNode object) in the tree view before the calling item. GetPrev will return the previous item whether or not it is visible. To get the previous visible item, use GetPrevVisible.


See also

GetLastChild method

GetNextChild method

GetNext method

GetNextSibling method

GetNextVisible method

GetFirstChild method

GetPrevChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetPrevChild method

Applies to

TOutlineNode, TTreeNode objects

Description

GetPrevChild Method for Outline Items

GetPrevChild Method for Tree Nodes


GetPrevChild method

See also	Example

Applies to

TOutlineNode objects

Declaration

function GetPrevChild(Value: Longint): Longint;

Description

The GetPrevChild method returns the Index value of the previous outline item that shares the same parent item as the item that has an Index value equal to the Value parameter. This is useful when the previous sibling has subitems, thus its index is not simply one less than Value. If the item indexed by Value has no previous sibling, GetPrevChild returns -1.


Example

The following code tests to determine if the selected item has a previous sibling. The results are displayed in a label.

with Outline1 do

  if (Items[SelectedItem].GetPrevChild > -1) then

    Label1.Caption := 'Has a prior sibling'

  else

    Label1.Caption := 'Has no prior sibling';


See also

GetFirstChild method

GetLastChild method

GetNextChild method


GetPrevChild method for tree node objects
GetPrevChild method

See also

Applies to

TTreeNode object

Declaration

function GetPrevChild(Value: TTreeNode): TTreeNode;

Description

The GetPrevChild method returns the previous child item before the child item specified by the parameter Value of the calling item. If there is no item before Value, GetPrevChild returns nil.


See also

GetLastChild method

GetNextChild method

GetNext method

GetNextSibling method

GetNextVisible method

GetPrev method

GetFirstChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetPrevSibling method for tree node objects
GetPrevSibling method

See also

Applies to

TTreeNode object

Declaration

function GetPrevSibling: TTreeNode;

Description

The GetPrevSibling method returns the previous item (TTreeNode object) before the calling item and at the same level. To find the next visible sibling item, use GetNextSibling.


See also

GetPrevChild method

GetLastChild method

GetNextChild method

GetNext method

GetNextSibling method

GetNextVisible method

GetPrev method

GetFirstChild method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetPrevVisible method for tree node objects
GetPrevVisible method

See also

Applies to

TTreeNode object

Declaration

function GetPrevVisible: TTreeNode;

Description

The GetPrevVisible method returns the previous visible item (TTreeNode object) before the calling item. To get the previous item, including non-visible, use GetPrev.


See also

GetPrevSibling method

GetPrevChild method

GetLastChild method

GetNextChild method

GetNext method

GetNextSibling method

GetNextVisible method

GetPrev method

GetFirstChild method

GetPrevSibling method

GetPrevVisible method

GetFirstNode method

GetNodeAt method


GetPrinter method

See also

Applies to

TPrinter object

Declaration

procedure GetPrinter (ADevice, ADriver, APort: PChar; var ADeviceMode: THandle);

Description

The GetPrinter method retrieves the current printer. You should rarely need to call this method and should instead access the printer you want in the Printers property array. For more information, see the CreateDC function in the Win32 Developer's Reference (WIN32.HLP).


See also

SetPrinter method


GetResource method

See also

Applies to

TImageList component

Declaration

TLoadResources = Set of TLoadResource;

function GetResource(ResType: TResType; Name: string; Width: Integer; LoadFlags: TLoadResources; MaskColor: TColor): Boolean;

Description

The GetResource method loads an image specified by Name, with the specified ResType , and MaskColor into the ImageList using the specified LoadFlags. These are the possible values for the LoadFlags parameter:

Value	Meaning

lrNone 	No specific resource flags.

lrDefaultColor	Use the color format of the display.

lrDefaultSize	Use system metrics for Height and Width if the Width parameter to GetResource is 0. If the Width parameter is 0 and this option is not specified for cursors and icons, the resources width and height will be used.

lrFromFile	Loads the resource from the specified file.

lrMap3DColors	Replaces the images grey shades with the 3D windows colors.

lrTransparent	Replaces the color table entry for the first pixel of the resource with the default window color (COLOR_WINDOW).  This applies only to images with color tables.

lrMonoChrome	Loads the resource as black and white.


See also

ResourceLoad method


GetResults method

Example

Applies to

TParam object

Declaration

procedure GetResults;

Description

You only need to call this method with a Sybase stored procedure that returns a result set. GetResults returns the output parameter values from the stored procedure. Usually, TStoredProc does this automatically, but Sybase stored procedures do not return the values until the cursor reaches the end of the result set, so you must call GetResults explicitly.


Example

StoredProc1.Open

while not EOF do

begin

  StoredProc1.Next;

  {Do Something}

end;

StoredProc1.GetResults;

Edit1.Text := StoredProc1.ParamByName('Output');


GetSearchString method

See also

Applies to

TListView component

Declaration

function GetSearchString: string;

Description

Run-time only. The GetSearchString method retrieves the incremental search string of a list view control. The return string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. A timeout period of less than a second is associated with each character that the user types. If the timeout period elapses before the user types another character, the incremental search string is reset. If the system finds a match, it selects the item and, if necessary, scrolls it into view.


See also

SortType property

AlphaSort method

CustomSort method


GetSelTextBuf method

See also	Example

Applies to

TDBEdit, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

function GetSelTextBuf(Buffer: PChar; BufSize: Integer): Integer;

Description

The GetSelTextBuf method copies the selected text from the edit box or memo control into the buffer pointed to by Buffer, up to a maximum of (BufSize - 1) characters, and returns the number of characters copied.


Example

procedure TForm1.Button1Click(Sender: TObject);

var

  Buffer: PChar;

  Size: Integer;

begin

  Size := Edit1.SelLength;          {Get length of selected text in Edit1}

  Inc(Size);                        {Add room for null character}

  GetMem(Buffer, Size);             {Creates Buffer dynamic variable}

  Edit1.GetSelTextBuf(Buffer,Size); {Puts Edit1.Text into Buffer}

  Edit2.Text := StrPas(Buffer);     {Converts string in Buffer into Pascal-style string}

  FreeMem(Buffer, Size);            {Frees memory allocated to Buffer}

end;


See also

GetTextBuf method

SelText property

SetSelTextBuf method


GetSessionNames method

See also

Applies to

TSessionList object

Declaration

procedure GetSessionNames(List: TStrings);

Description

GetSessionNames fills a string list object you create with the names (SessionName property) of all available sessions. You're responsible for both creating and destroying the string list.


See also

FindSession method

List property


GetShortHint function

See also	Example

Unit

Controls

Declaration

function GetShortHint(const Hint: string): string;

Description

The GetShortHint function returns the first part of the two-part string specified as the value of the Hint property. The first part of the string is the text preceding the | character. If the Hint string value is not separated into two parts, GetShortHint returns the entire Hint string.


Example

This code assigns a two-part string as the Hint property of an edit box and then displays the "short" or first part of the string as the text of the edit box:

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  Edit1.Hint := 'Name|Enter full name';

  Edit1.Text := GetShortHint(Edit1.Hint);

end;


See also

GetLongHint function

OnHint event

ShowHint property


GetStoredProcNames method

See also	Example

Applies to

TSession component

Declaration

procedure GetStoredProcNames(const DatabaseName: string; List: TStrings);

Description

GetStoredProcNames returns a list of all stored procedures defined for the specified SQL database. This method is not valid for Paradox or dBASE databases.


Example

try

  MyStringList := TStringList.Create;

   Session.GetStoredProcNames('IB_EMPLOYEE', MyStringList);

finally

  MyStringList.Free;

end;


See also

Session variable


GetTableNames method

See also	Example

Applies to

TSession component

Declaration

procedure GetTableNames(const DatabaseName, Pattern: string;
  Extensions, SystemTables: Boolean; List: TStrings);

Description

The GetTableNames method clears List and then adds to it the names of all the tables in the database referenced by DatabaseName. The Pattern parameter will limit the table names to those matching Pattern.

For SQL servers, set SystemTables to True to obtain system tables in addition to user tables. For desktop (non-SQL) databases, set Extensions to True to include file-name extensions in the table names.


Example

try

  MyStringList := TStringList.Create;

  Session.GetTableNames('DBDEMOS','*.db',False, False, MyStringList);

finally

  MyStringList.Free;

end;


See also

Session variable


GetTextBuf method

See also	Example

Applies to

All controls; TClipboard object

Declaration

function GetTextBuf(Buffer: PChar; BufSize: Integer): Integer;

Description

The GetTextBuf method retrieves the control's text and copies it into the buffer pointed to by Buffer, up to the number of characters given by BufSize, and returns the number of characters copied.

The resulting text in Buffer is a null-terminated string.

To find out how many characters the buffer needs to hold the entire text, you can call the GetTextLen method before calling GetTextBuf.


Example

This example copies the text in an edit box into a null-terminated string, and puts this string in another edit box when the user clicks the button on the form.

procedure TForm1.Button1Click(Sender: TObject);

var

  Buffer: PChar;

  Size: Byte;

begin

  Size := Edit1.GetTextLen;       {Get length of string in Edit1}

  Inc(Size);                      {Add room for null character}

  GetMem(Buffer, Size);           {Creates Buffer dynamic variable}

  Edit1.GetTextBuf(Buffer,Size);  {Puts Edit1.Text into Buffer}

  Edit2.Text := StrPas(Buffer);   {Converts Buffer to a Pascal-style string]

  FreeMem(Buffer, Size);          {Frees memory allocated to Buffer}

end;


See also

GetSelTextBuf method

SetTextBuf method


GetTextItem method

See also	Example

Applies to

TOutline component

Declaration

function GetTextItem(Value: string): Longint;

Description

The GetTextItem method returns the Index value of the first outline item that contains the string specified in the Value parameter in its Text property. Use GetTextItem when you want to know which outline item is identified by a string.


Example

The following code returns the index of the outline item that contains the text 'Perry' to a variable called PerryIndex.

PerryIndex := Outline1.GetTextItem('Perry');


See also

GetDataItem method

GetItem method


GetTextLen method

See also	Example

Applies to

All controls

Declaration

function GetTextLen: Integer;

Description

The GetTextLen method returns the length of the control's text. The most common use of GetTextLen is to find the size needed for a text buffer in the GetTextBuf method.


Example

This example uses two edit boxes and a button on a form. When the user clicks the button, the length of the text in the Edit1 is displayed in Edit2.

procedure TForm1.Button1Click(Sender: TObject);

var

  Size: Integer;

begin

  Size := Edit1.GetTextLen;

  Edit2.Text := ('Edit1 has ' + IntToStr(Size) + 'characters in it');

end;


See also

GetTextBuf method


Glyph property

See also	Example

Applies to

TBitBtn, TSpeedButton controls

Declaration

property Glyph: TBitmap;

Description

The Glyph property specifies the bitmap that appears on the selected bitmap button or on a speed button. Use the Open dialog box that appears as an editor in the Object Inspector to choose a bitmap file (with a .BMP extension) to use on the button, or specify a bitmap file at run time.

You can provide up to four images on a bitmap button or speed button with a single bitmap. Delphi then displays one of these images depending on the state of the button.

Image position in bitmap	Button state	Description

First	Up	This image appears when the button is unselected. If no other images exist in the bitmap, Delphi also uses this image for all other images.

Second	Disabled	This image usually appears dimmed to indicate that the button can't be selected.

Third	Down	This image appears when a button is clicked. The up state image reappears when the user releases the mouse button.

Fourth	Stay down	This image appears when a button stays down indicating that it remains selected. (This fourth state applies only to speed buttons.)

If only one image is present, Delphi attempts to represent the other states by altering the image slightly for the different states, although the stay down state is always the same as the up state. If you aren't satisfied with the results, you can provide one or more additional images in the bitmap.

If you have multiple images in a bitmap, you must specify the number of images that are in the bitmap with the NumGlyphs property. All images must be the same size and next to each other in a horizontal row.

Note:	The lower left hand pixel of the bitmap is reserved for the "transparent" color. Any pixel in the bitmap which matches that lower left hand pixel will be "transparent".


Example

This example uses a bitmap button on a form. When the application runs and the form is created, a bitmap is placed on the bitmap button.

procedure TForm1.FormCreate(Sender: TObject);

begin

  BitBtn1.Glyph.LoadFromFile('TARTAN.BMP');

end;

These lines of code load a four-image bitmap into the Glyph property of a speed button, and specify the appropriate value for the NumGlyphs property:

SpeedButton1.Glyph.LoadFromFile('MYBITMAP.BMP');

SpeedButton1.NumGlyphs := 4;


See also

Layout property

Margin property

ModalResult property

NumGlyphs property

Spacing property

TBitmap object


GotoBookmark method

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure GotoBookmark(Bookmark: TBookmark);

Description

The GotoBookmark method moves the cursor to the record corresponding to the bookmark obtained through a call to GetBookmark. While you must eventually call the FreeBookmark method to release the resources reserved during the call to GetBookmark, you are free to make as many calls to GotoBookmark as you wish before calling FreeBookmark. If the Bookmark parameter is nil, GotoBookmark does nothing.


Example

var MyBookmark: TBookmark;

...

with Table1 do

  begin

{ Save the current record position in MyBookmark }

  MyBookmark := GetBookMark;

  ... { Other code here }

{ Return to the record associated with MyBookmark }

  GotoBookMark(MyBookMark);

{ Release the resources for MyBookmark }

  FreeBookmark(MyBookmark);

  end;


GotoCurrent method

Example

Applies to

TTable component

Declaration

procedure GotoCurrent(Table: TTable);

Description

Use the GotoCurrent method to synchronize the positions of two TTable components that use the same database table. GotoCurrent changes the position of the table to match that of the Table parameter.

Note:	Both tables must have the same DatabaseName and TableName or a "table mismatch" exception will be raised.


Example

Table1.GotoCurrent(Table2);


GotoKey method

See also	Example

Applies to

TTable component

Declaration

function GotoKey: Boolean;

Description

The GotoKey method is used with the SetKey or EditKey method to move to a specific record in a TTable. Call SetKey to put the table in SetKey state. In SetKey state, assignments to fields indicate values to search for in indexed fields. GoToKey then moves the cursor to the first row in the table that matches those field values.

GoToKey is a Boolean function that moves the cursor and returns True if the search is successful. If the search is unsuccessful, it returns False and does not change the position of the cursor.

Note:	If you want to search on a subset of fields in a multiple-field key, you must set the KeyFieldCount property to the number of fields on which you want to search.


Example

with Table1 do

  begin

  EditKey;

  FieldByName('CustNo').AsFloat := 610;

  GotoKey;

  end;


See also

FindKey method


GotoNearest method

See also	Example

Applies to

TTable component

Declaration

procedure GotoNearest;

Description

The GotoNearest method is used with the EditKey or SetKey method to move to a record in the dataset whose index fields are greater than or equal to the IndexFields property. Call SetKey first to put the TTable in SetKey state, modify the fields of the key, and finally call GotoNearest to perform the move.

The KeyExclusive property indicates whether a search will position the cursor on or after the specified record being searched for.

Note:	You do not have to assign a value for each field in the index key. Any unassigned field will use a NULL value.

The search begins at the first record in the table, not at the current cursor position.


Example

with Table1 do

  begin

  SetKey;

  FieldByName('State').AsString := 'CA';

  FieldByName('City').AsString := 'Santa';

  GotoNearest;

  end;


See also

GotoKey method

KeyFieldCount property

SetKey method


Graphic property

See also	Example

Applies to

TPicture object

Declaration

property Graphic: TGraphic;

Description

The Graphic property specifies the graphic that the picture contains. The graphic can be a bitmap, icon, or metafile, or user-defined graphic class.


Example

The following code draws the graphic in Picture1 in the top-left corner of the canvas of Form1.

Form1.Canvas.Draw(0,0 Picture1.Graphic);


See also

Bitmap property

Icon property

Metafile property

RegisterFileFormat method


GraphicExtension function

See also	Example

Unit

Graphics

Declaration

function GraphicExtension(GraphicClass: TGraphicClass): string;

Description

The GraphicExtension function returns the file-name extension of the graphics object specified by the GraphicClass parameter. The TGraphicClass type is simply a container class for the TBitmap, TGraphic, TIcon, TMetafile objects and for user-defined custom graphics classes. These are the file extensions returned for each graphics class:

Graphic class	File extension returned

TGraphic	.BMP, .ICO, .WFM or .EMF

TBitmap	.BMP

TIcon	.ICO

TMetafile	.EMF


Example

The following code tests to determine if the graphic in Picture1 is an icon. If so, the minimized icon of Form1 is set to the graphic.

if GraphicExtension(Picture1.Graphic)='.ICO' then

  Form1.Icon := Picture1.Graphic;


See also

GraphicFilter function

RegisterFileFormat method


GraphicFilter function

See also	Example

Unit

Graphics

Declaration

function GraphicFilter(GraphicClass: TGraphicClass): string;

Description

The GraphicFilter function returns a filter string compatible with the Filter property value of an Open or Save dialog box. The GraphicClass parameter can be one of these values: TBitmap, TGraphic, TIcon, TMetafile or user-defined graphic class. These are the strings that are returned for each class:

Graphic class	Filter string returned

TBitmap	Bitmaps (*.BMP)|*.BMP

TIcon	Icons (*.ICO)|*.ICO

TMetafile	Enhanced Metafiles (*.EMF)|*.EMF

TGraphic	All (*.BMP; *.WMF; *.ICO)|*.BMP; *.WMF; *.ICO|Bitmaps (*.BMP|*.BMP|Metafiles (*.WFM|*.WMF|Icons (*.ICO)|*.ICO


Example

This code displays an Open dialog box with the TBitmap filter string in the List Files of Type combo box:

OpenDialog1.DefaultExt := GraphicExtension(TBitmap);

OpenDialog1.Filter := GraphicFilter(TBitmap);

if OpenDialog1.Execute then

  ...


See also

GraphicExtension function

TOpenDialog component

TSaveDialog component

RegisterFileFormat method


Grid property

Applies to

TDBGridColumns object

Declaration

property Grid: TCustomDBGrid;

Description

Run-time and read-only. Represents the TDBGrid component whose columns are represented by this TDBGridColumns object.


GridHeight property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property GridHeight: Integer;

Description

Run-time and read-only. The GridHeight property is the height of the grid in pixels. If the grid is too tall to be fully displayed causing the user to scroll to see its entire contents, the value of GridHeight is the same as the ClientHeight property value for the grid.


Example

This example uses a string grid and a label on a form. The height of the grid appears in the caption of the label.

procedure TForm1.FormCreate(Sender: TObject);

var

  ARow, ACol: Integer;

begin

  with StringGrid1 do

  begin

    for ARow := 1 to RowCount - 1 do

      for ACol := 1 to ColCount - 1 do

        Cells[ARow, ACol] := 'Delphi';

  end;

  Label1.Caption := IntToStr(StringGrid1.GridHeight) + ' pixels';

end;


See also

GridWidth property


GridLineWidth property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property GridLineWidth: Integer;

Description

The GridLineWidth property determines the width of the lines between the cells in the grid. The default value is 1 pixel. Larger values create heavier lines.


Example

This example includes a draw grid on a form. When the application runs and the form is created, the width of the lines on the draw grid changes if the default column width of the grid is over 90 pixels wide:

procedure TForm1.FormCreate(Sender: TObject);

begin

  with DrawGrid1 do

  begin

    if DefaultColWidth > 90 then

      GridLineWidth := 2

    else

      GridLineWidth := 1;

   end;

end;


See also

ColWidths property

DefaultColWidth property

GridHeight property

GridWidth property

RowHeights property


GridWidth property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property GridWidth: Integer;

Description

Run-time and read-only. The GridWidth property is the width of the grid in pixels. If the grid is too wide to be fully displayed causing the user to scroll it to see its entire contents, the value of GridWidth is the same as the ClientWidth property value for the grid.


Example

This example uses a string grid and a label on a form. The label reports the width of the grid.

procedure TForm1.FormCreate(Sender: TObject);

var

  ARow, ACol: Integer;

begin

  with StringGrid1 do

  begin

    for ARow := 1 to RowCount - 1 do

      for ACol := 1 to ColCount - 1 do

        Cells[ARow, ACol] := 'Pascal';

  end;

  Label1.Caption := IntToStr(StringGrid1.GridWidth) + ' pixels';

end;


See also

GridHeight property


GroupIndex property

Applies to

TMenuItem, TSpeedButton components

Description

The GroupIndex property either specifies which speed buttons work together as a group or determines the position of menu items in the menu bar.

GroupIndex Property for Speed Button Controls

GroupIndex Property for Menu Items


GroupIndex property

See also	Example

Applies to

TSpeedButton component

Declaration

property GroupIndex: Integer;

Description

The GroupIndex property determines which speed buttons work together as a group.

By default, speed buttons have a GroupIndex property value of 0, indicating that they do not belong to a group. When the user clicks such a speed button, the button appears "pressed," or in its down state, then the button returns to its normal up state when the user releases the mouse button.

Speed buttons with the same GroupIndex property value (other than 0), work together as a group. When the user clicks one of these speed buttons, it remains "pressed," or in its down state, until the user clicks another speed button belonging to the same group. Speed buttons used in this way can present mutually exclusive choices to the user.

The default value is 0.


Example

This code assures that the three speed buttons work together as a group:

SpeedButton1.GroupIndex := 1;

SpeedButton2.GroupIndex := 1;

SpeedButton3.GroupIndex := 1;


See also

AllowAllUp property

Down property


GroupIndex property

See also

Applies to

TMenuItem component

Declaration

property GroupIndex: Byte;

Description

If your application has multiple forms, you'll probably want your application's main menu to change as different forms become active. The alternative is for each form to display its own menu within itself. MDI applications always merge the menus of child windows with the main menu of the parent window. By using the GroupIndex property for menu items, you can determine how menus are merged. You can choose to replace or insert menu items in a menu bar.

Each menu item has a GroupIndex property value. By default, all menu items in a menu bar have the same GroupIndex value, unless you explicitly change them. Each successive menu item in a menu bar must have a GroupIndex value equal to or greater than the previous menu item.

Replacing menu items in a menu bar

If a menu item in a menu bar on a form other than the main form has the same GroupIndex value as a menu item in a menu bar on the main form, the menu item replaces the menu item in the menu bar of the main form when that form becomes active.

If multiple menu items in the menu bar on the main form have the same GroupIndex value, and all menu items of another form also have the same GroupIndex value, then the other form's menu items replace all menu items on the menu bar on the main form.

For example, imagine that the menu bar on Form1 has three items: One, Two, and Three, and all have a GroupIndex value of 0. If Form2 has a menu bar with one menu item, Four, with a GroupIndex value of 0, when Form2 becomes active, only the menu item Four appears in the menu bar on Form1.

Inserting menu items in a menu bar

If one or more menu items in a menu bar on a form that isn't the main form have a GroupIndex value greater than a menu item in the menu bar on the main form, those menu items are inserted into the menu bar on the main form when the menus merge. If the item's GroupIndex value is greater than all other GroupIndex values in the main form's menu bar, the item appears at the end of the menu. If the GroupIndex value is between other GroupIndex values in the menu bar on the main form, the menu item appears between other menu items, depending on the value.

For example, an item with a GroupIndex value of 2 would be inserted between items with GroupIndex values of 1 and 3. An item with a GroupIndex value of 4 would appear after all the other items.

Note:	The GroupIndex value must be different from all others in the menu bar on the main form, or else the new menu item will replace one or more menu items with the same GroupIndex value, which you may or may not want to do.

OLE application menus

When you activate an object created by an OLE 2.0 server application, the server might try to merge its menus with the menus of your container application, depending on the OLE server application. The GroupIndex property of each of the container application's menus determines where the merging menu items appear in the container's menu bar. Merged menu items from the OLE server might replace those on the main menu bar, or they might be inserted beside existing container application menu items.

Note:	See the documentation for the OLE server for information about whether it attempts menu merge during in-place activation.

The OLE server can merge up to three groups of menu items. Each group is distinguished by a unique group index and can contain any number of menu commands. The following table summarizes the menu item groups that the OLE server application can merge:

Group	Index	Description

Edit	1	Menu item(s) from the server for editing the active OLE object

View	3	Menu item(s) from the server for modifying the view of the OLE object.

Help	5	Menu item(s) from the server for accessing the server's online Help

Any menu items in your container application with values of 1, 3, or 5 for their GroupIndex properties are replaced by menu items with corresponding index values from the OLE server application. The menu items from your OLE container with a GroupIndex value other than 1, 3, or 5 won't be replaced by menus from the server.

Note:	TMenuItems with RadioItem set to True will act like radio buttons. Checking one will uncheck the others in the same GroupIndex group. In Windows 95 and Windows NT with the Windows 95 shell, these menus will also be displayed with a round dot instead of a check. This will only work on TMenuItems that are either in a TPopupMenu or a sub-menu of a TMainMenu.


See also

AutoMerge property

FormStyle property


Handle property

Applies to

All windowed controls; TApplication, TBitmap, TBrush, TCanvas, TFont, TIcon, TMetafile, TPen, TPrinter, TTreeNode, TListItem, TTreeNodes, TListItems, TThread objects; TDatabase, TFindDialog, TMainMenu, TMenuItem, TPopupMenu, TQuery, TSession, TStoredProc, TTable components

Description

The Handle property gives you access to the Windows handle, so you can access GDI objects or so you can call Windows API functions that take a handle as a parameter.

Handle Property for Graphics (Bitmap, Brush, Canvas, Font, Icon, Metafile, Pen) Objects

Handle Property for Windowed Controls, Applications, and Dialog Boxes

Handle Property for Menu Components

Handle Property for Printer Objects

Handle Property for Database Components

Handle Property for Sessions

Handle Property for Queries, Tables, and Stored Procedures

Handle Property for Image List Objects

Handle Property for Tree Node Objects

Handle Property for Tree Nodes Objects

Handle Property for Thread Objects


Handle property

Applies to

TThread object

Declaration

property Handle: THandle;

Description

Runtime and readonly. The Handle property is the thread's handle. The thread handle is useful if you need to call Win32 API functions for manipulating the thread.


Handle property for image list objects
Handle property

See also

Applies to

TImageList object

Declaration

property Handle;

Description

The Handle property lets you access the Windows image list object handle so you can pass the handle to a Windows API function that requires it.


See also

HandleAllocated method


Handle property for graphics objects
Handle property

Applies to

TBitmap, TBrush, TCanvas, TFont, TIcon, TMetafile, TPen, objects

Declaration

property Handle: HBitmap;    {for TBitmap objects}

property Handle: HBrush;     {for TBrush objects}

property Handle: HDC;        {for TCanvas objects}

property Handle: HFont;      {for TFont objects}

property Handle: HIcon;      {for TIcon objects}

property Handle: HMetafile;  {for TMetafile objects}

property Handle: HPen;       {for TPen objects}

Description

The Handle property lets you access the Windows GDI object handle, so you can access the GDI object. If you need to use a Windows API function that requires the handle of a pen object, you could pass the handle from the Handle property of a TPen object.


Handle property

See also	 Example

Applies to

All windowed controls

Declaration

property Handle: HWND;

Description

Read and run-time only. The Handle property gives you access to window handle of the application, the Find and Replace dialog boxes, and all controls in case you need to call a Windows API function that requires a handle.


Example

The following code uses the Windows API function ShowWindow to display Form2 as an icon, but does not activate it.

ShowWindow(Form2.Handle, SW_SHOWWINMINNOACTIVE);


See also

HandleAllocated method

HandleNeeded method


Handle property

Example

Applies to

TMainMenu, TMenuItem, TPopupMenu, components

Declaration

property Handle: HMENU;

Description

Read and run-time only. The Handle property lets you access the menu or menu item's window handle, so you can call a Windows API function that requires a menu handle.


Example

The following code uses the Windows API function HiliteMenuItem to highlight the first menu item in MainMenu1 on Form1.

HiliteMenuItem(Form1.Handle, MainMenu1.Handle, 0, MF_BYPOSITION+MF_HILITE);


Handle property

Applies to

TPrinter object

Declaration

property Handle: HDC;

Description

Read and run-time only. The Handle property give you access to the handle of the printer object.


Handle property for sessions
Handle property

Applies to

TSession component

Declaration

property Handle: HDBISES;

Description

Run-time and read-only. The Handle property allows you to make direct calls to the Borland Database Engine using this handle to the session (TSession). Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Handle property

Applies to

TQuery, TStoredProc, TTable components

Declaration

property Handle: HDBICur;

Description

Run-time and read-only. The Handle property enables an application to make direct calls to the Borland Database Engine API using this handle of a dataset component.

Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Handle property

Applies to

TDatabase components

property Handle: HDBIDB;

Description

Run-time only. The Handle property lets an application make direct calls to the Borland Database Engine (BDE) API. Many BDE function calls require a database handle, which this property provides.

Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Handle property

See also

Applies to

TTreeNode, TListItem objects

Declaration

property Handle: HWND;

Description

Run-time and read-only. The Handle property returns the Handle property of the tree view control or list view control that owns the item, a tree node, or list item object, respectively.


See also

Owner property

TreeView property

ListView property


Handle property

See also

Applies to

TTreeNodes, TListItems objects

Declaration

property Handle: HWND read GetHandle;

Description

Run-time and read-only. The Handle property returns the Handle property of the object that owns the tree nodes object or list items object, a tree view control, or a list view control, respectively.


See also

Owner property


HandleAllocated method

See also	Example

Applies to

All controls

Declaration

function HandleAllocated: Boolean;

Description

The HandleAllocated method returns True if a window handle for the control exists. If no window handle exists, HandleAllocated returns False. If you query the Handle property of a control directly, a handle is automatically created if it didn't previously exist. Therefore, you should call the HandleAllocated method if you don't want a handle created automatically for the control, but simply want to know if one exists.


Example

The following code displays the value of the handle of GroupBox1 if it exists. If not, it displays a message.

var

  TheValue: string;

begin

  if GroupBox1.HandleAllocated then

    TheValue := IntToStr(GroupBox1.Handle)

  else TheValue := 'Handle not allocated.';

  Label1.Caption := TheValue;

end;


See also

HandleNeeded method


HandleException method

See also	Example

Applies to

TApplication component

Declaration

procedure HandleException(Sender: TObject);

Description

The HandleException method handles the exceptions for the application. If an exception passes through all the try blocks in your application code, your application automatically calls the HandleException method, which displays a dialog box indicating an error occurred. To assign other exception handling code for the application, use the OnException event handler.


Example

The following code uses the default error handling:

try

  { Some code that may produce an exception goes here }

except

  Application.HandleException(Self);

end;


See also

Application variable

OnException event


HandleMessage method

See also	Example

Applies to

TApplication

Declaration

procedure HandleMessage;

Description

The HandleMessage method interrupts the execution of your application so that Windows can process a single message in the Windows message queue and then return control to your application.  If the message queue is empty, HandleMessage calls the application's Idle method, which, in turn, calls the OnIdle event handler if one is defined.


Example

The following code demonstrates handling windows messages with HandleMessage:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Button1.Caption := 'Ignore Messages';

  Button2.Caption := 'Handle Message';

  Application.OnIdle:= MyIdleHandler;

end;

procedure TForm1.MyIdleHandler(Sender: TObject; var Done: Boolean);

begin

  { This tells TApplication not to wait for a message }

  Done:= False;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  I, J, X, Y: Word;

begin

  I := 0;

  J := 0;

  while I < 64000 do

  begin

    Randomize;

    while J < 64000 do

    begin

      Y := Random(J);

      Inc(J);

    end;

    X := Random(I);

    Inc(I);

  end;

  Canvas.TextOut(10, 10, 'The Button1Click handler is finished');

end;

procedure TForm1.Button2Click(Sender: TObject);

var

  I, J, X, Y: Word;

begin

  I := 0;

  J := 0;

  while I < 64000 do

  begin

    Randomize;

    while J < 64000 do

    begin

      Y := Random(J);

      Inc(J);

      Application.HandleMessage;

    end;

  X := Random(I);

  Inc(I);

  end;

  Canvas.TextOut(10, 10, 'The Button2Click handler is finished');

end;


See also

OnIdle event

ProcessMessage procedure


HandleNeeded method

See also	Example

Applies to

All controls

Declaration

procedure HandleNeeded;

Description

The HandleNeeded method creates a window handle for the control if one doesn't already exist.


Example

The following code creates a window handle for Button1:

Button1.HandleNeeded;


See also

Handle property

HandleAllocated method


HasAsParent method for tree node objects
HasAsParent method

See also

Applies to

TTreeNode object

Declaration

function HasAsParent(Value: TTreeNode): Boolean;

Description

The HasAsParent method returns True if Value is a parent item (TTreeNode object) of the calling item.


See also

HasChildren property

Parent property


HasChildren property for tree nodes
HasChildren property

See also

Applies to

TTreeNode object

Declaration

property HasChildren: Boolean;

Description

Run-time only. The HasChildren property determines if an item has any child items. Child items appear below and indented from their parent item when the parent is expanded. HasChildren is True if the item has subitems, or False if the item has no subitems. If ShowButtons of the tree view is True, and HasChildren is True, a plus (+) button will appear to the left of the item. However, if an item has no children, setting HasChildren to True will show a (+) plus button, but will not add child items and the item cannot be expanded.


See also

HasAsParent method

GetFirstChild method


HasFormat method

See also	Example

Applies to

TClipboard object

Declaration

procedure HasFormat(Format: Word): Boolean;

Description

The HasFormat method determines if the Clipboard object contains a particular format. If HasFormat is True, the format is present; if False, the format is absent. The Clipboard object keeps a list of available formats in the Formats array property.

Some of the possible values of the Format parameter follow. There are many more Clipboard formats provided by Windows, and custom formats can be registered. All are supported by HasFormat..

Value	Meaning

CF_TEXT	Text with each line ending with a CR-LF combination. A null character identifies the end of the text.

CF_BITMAP	A Windows bitmap graphic.

CF_METAFILE	A Windows metafile graphic.

CF_PICTURE	An object of type TPicture.

CF_OBJECT	Any persistent object.


Example

This example uses a button on a form. When the user clicks the button, a message box appears if there is no text on the Clipboard; otherwise, you don't see anything happen.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if not Clipboard.HasFormat(CF_TEXT) then

      MessageDlg('There is no text on the Clipboard', mtInformation,

        [mbOK],0);

end;


See also

Assign method

FormatCount property

Formats property

GetComponent method

SetComponent method


HasItems property

See also	Example

Applies to

TOutlineNode object

Declaration

property HasItems: Boolean;

Description

Run-time and read-only. The HasItems property determines if an outline item has any subitems. Subitems appear below and indented from their parent item when the parent is expanded. The Index value of the parent item is one less than the Index value of its first subitem. HasItems is True if the item has subitems, or False if the item has no subitems.


Example

The following code expands the selected item of Outline1 if it has subitems:

with Outline1[Outline1.SelectedItem] do

  if HasItems then Expand;


See also

GetFirstChild method

GetLastChild method

GetNextChild method

GetPrevChild method


Height property

Applies to

All controls; TBitmap, TFont, TGraphic, TIcon, TMetafile, TPicture, TTextAttributes objects; TForm, TImageList, TScreen components

Description

The Height property determines vertical size of a component or object.

Height Property for Controls, Forms, and Graphics Objects

Height Property for Screens

Height Property for Font and TTextAttributes Objects

Height Property for Image Lists


Height Property for Controls and Forms
Height property

See also

Applies to

TImageList component

Declaration

property Height: Integer;

Description

The Height property specifies the height for an image within the image list. The ImageList will be cleared if this value changes.


See also

Width property

CreateSize constructor


Height property

See also	Example

Applies to

All controls; TBitmap, TGraphic, TIcon, TImageList, TMetafile, TPicture objects; TForm component

Declaration

property Height: Integer;

Description

Height property of a control is the vertical size of the control, form, or graphic in pixels.


Example

The following code doubles the height of a list box control:

ListBox1.Height := ListBox1.Height * 2;


See also

ClientHeight property

SetBounds method

Width property


Height Property for Screens
Height property

See also	Example

Applies to

TScreen component

Declaration

property Height: Integer;

Description

Read and run-time only. The Height property of a screen component contains the vertical size of the screen device in pixels.


Example

To following code sets a form's height to half the height of the screen:

Form1.Height := Screen.Height div 2;


See also

Screen variable

Width property


Height Property for Font Objects
Height property

See also	Example

Applies to

TFont, TTextAttributes objects

Declaration

property Height: Integer;

Description

The Height property value is the height of the font, which is the size of the font minus the internal leading that appears at the top of the font. Whenever you specify a font height in pixels, use the Height property. If you are concerned with the size of the font in points--use the Size property instead of Height. Users usually specify font size in points within an application, while programmers are usually concerned with the actual size of the font in pixels--which includes the internal leading--when displaying a font on the screen.

Delphi determines the value of the Height property using this formula:

Font.Height = -Font.Size * 72 / Font.PixelsPerInch

Therefore, whenever you enter a positive value for the Height property, the font's Size property value changes to a negative number. Conversely, if you enter a positive value for the Size property, the font's Height property changes to a negative number. Positive Height includes the internal leading and negative excludes it.


Example

This example uses button and a label on a form. When the user clicks the button, the height of the font changes to 36 pixels on the screen:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Font.Height := 36;

end;


See also

Font property

PixelsPerInch property

Size property


HelpCommand method

See also	Example

Applies to

TApplication component

Declaration

function HelpCommand(Command: Word; Data: Longint): Boolean;

Description

The HelpCommand method gives you quick access to any of the Help commands in the WinHelp API (application programming interface). For information about the commands you can call and the data passed to them, see the WinHelp topic in the Help system.


Example

This example uses a bitmap button on a form. When the user clicks the button, the Help contents screen of the specified Help file appears.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  Application.HelpFile := 'MYHELP.HLP';

  Application.HelpCommand(HELP_CONTENTS, 0);

end;


See also

Application variable

HelpContext method

HelpContext property

HelpFile property

HelpJump method


HelpContext method

See also	Example

Applies to

TApplication component

Declaration

function HelpContext(Context: THelpContext): Boolean;

Description

The HelpContext method calls WinHelp, the Windows Help system program, if the HelpFile property is assigned a file to use for Help. HelpContext passes the file name contained in HelpFile and the context number passed in Context parameter. For example, if you specify the Context value as 714, the HelpContext method displays the screen with the context help ID of 714 in the Help file.

HelpContext returns False if HelpFile is an empty string, meaning the application has no Help file assigned. In all other cases, HelpContext returns True.


Example

This example uses a bitmap button on a form. When the user clicks the button, the screen with the context number of 714 in the DATA.HLP Help file appears:

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  Application.HelpFile := 'DATA.HLP';

  Application.HelpContext(714);

end;


See also

Application variable

HelpFile property

OnHelp event


HelpContext property

See also	Example

Applies to

All controls; Exception, TColorDialog, TFindDialog, TFontDialog, TMenuItem, TPopupMenu, TOpenDialog, TPrintDialog, TPrinterSetupDialog, TReplaceDialog, TSaveDialog components

Declaration

property HelpContext: THelpContext;

Description

The HelpContext property provides a context number for use in calling context-sensitive online Help. Each screen in the Help system should have a unique context number. When a component is selected in the application, pressing F1 displays a Help screen. Which Help screen appears depends on the value of the HelpContext property.

If HelpContext is zero, then the control will "inherit" the help context of its parent control. For example, if a button with zero help context is contained in a form with a non-zero help context and F1 is pressed, the context screen for the form will be shown.


Example

The following code associates a Help file with the application, and makes the screen with a context number of 7 the context-sensitive Help screen for the Edit1 edit box:

procedure TForm1.FormActivate(Sender: TObject);

begin

  Application.HelpFile := 'MYHELP.HLP';

  Edit1.HelpContext := 7;

end;


See also

HelpContext method

HelpFile property

HelpJump method

OnHelp event

BorderIcons property


HelpFile property

See also	Example

Applies to

TApplication component

Declaration

property HelpFile: string;

Description

Run-time only. The HelpFile property holds the name of the file the application uses to display Help. By default, HelpFile is a null string, and the application's Help method ignores attempts to display Help. If HelpFile contains anything, the HelpContext method passes it to the Windows Help system as the name of the file to use for Help.


Example

To specify the MYHELP.HLP file as the Help file for your application, use this line of code:

Application.HelpFile := 'MYHELP.HLP';


See also

HelpContext method


HelpJump method

See also	Example

Applies to

TApplication component

Declaration

function HelpJump(const JumpID: string): Boolean;

Description

The HelpJump method calls WinHelp, the Windows Help system program, if the HelpFile property is assigned a file to use for Help. HelpJump passes the file name contained in HelpFile and the context string specified in the JumpID parameter. For example, if you specify the JumpID value as 'vclDefaultProperty', the HelpJump method displays the screen in the Help file that has the context string 'vclDefaultProperty'.

HelpJump returns False if HelpFile is an empty string, meaning the application has no Help file assigned. In all other cases, HelpJump returns True.


Example

This example uses a bitmap button on a form. When the user clicks the button, the Help screen describing the Default property in the DELPHI.HLP file appears, because the Default property screen has the a JumpID string of 'vclDefaultProperty'.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  Application.HelpFile := 'DELPHI.HLP';

  Application.HelpJump('vclDefaultProperty');

end;


See also

Application variable

HelpCommand method

HelpContext method

HelpContext property

HelpFile property

OnHelp event


Hide method

See also	Example

Applies to

TForm component, All controls

Declaration

procedure Hide;

Description

The Hide method makes a form or control invisible by setting the Visible property of the form or control to False. Although a form or control that is hidden is not visible, you can still set the properties of the form or control, or call its methods.


Example

This code uses a button and a timer on a form. When the user clicks the button, the form disappears for the period of time specified in the Interval property of the timer control, then the form reappears:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Timer1.Enabled := True;

  Hide;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  Visible := True;

  Timer1.Enabled := False;

end;


See also

Close method

Show method

ShowModal method


HideDragImage method for TImageList
HideDragImage method

See also

Applies to

TImageList component

Declaration

procedure HideDragImage;

Description

The HideDragImage method hides the current drag image if it was previously shown.


See also

SetDragImage method


HideScrollBars property

See also

Applies to

TRichEdit component

Declaration

property HideScrollBars: Boolean;

Description

The HideScrollBars property controls whether the scroll bars disappear when not needed to scroll the window. The default is True.

This property is only useful when the ScrollBars property is not set to its default which is ssNone.


See also

ScrollBars property


HideSelection property

See also	Example

Applies to

TEdit, TListView, TMemo, TRichEdit, TTreeView components

Declaration

property HideSelection: Boolean;

Description

The HideSelection property determines whether text that is selected in an edit or memo remains selected when the focus shifts to another control. If True, the text is no longer selected until the focus returns to the control. If False, the text remains selected. The default value is True.


Example

This example uses an edit box and a memo on a form. When the user jumps from one control to the other, selected text remains selected in the memo, but not in the edit box.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Edit1.HideSelection := True;

  Memo1.HideSelection := False;

end;


See also

AutoSelect property


Hint property

See also	Example

Applies to

All controls; TApplication, TMenuItem components

Declaration

property Hint: string;

Description

The Hint property is the text string that can appear when the OnHint event occurs, which happens when the user moves the mouse pointer over a control or menu item. The code within the OnHint event handler determines how the string is displayed. A common use of an OnHint event handler is to display the hint as the caption of a panel component that is being used as a status bar.

You can have a Help Hint, a box containing help text, appear for a control when the user moves the mouse pointer over the control and pauses momentarily. This is how:

1	Specify a Hint value for each control you want a Help Hint to appear for.

2	Set the ShowHint property of each control to True.

3	At run time, set the value of application's ShowHint property to True.

You can specify a hint to be used for both for a Help Hint box and in an OnHint handler (as the application's Hint property value) by specifying two values separated by a | character (the "or" or "pipe" symbol). For example,

Edit1.Hint := 'Name|Enter Name in the edit box';

The 'Name' string appears in the Help Hint box, and the 'Enter full name' string appears as specified in the OnHint event handler.

If you specify just one value, it can be used both as a Help Hint and as the Hint property of the application. If the application's ShowHint property is False, the Help Hint won't appear, but the other hint still will.

If a control has no Hint value specified, but its parent control does, the control uses the Hint value of the parent control as long as the control's ShowHint property is True.


Example

This example uses an edit box and a list box on a form. Items are added to the list box and a Help Hint is assigned to both controls. The last statement enables the Help Hints for the entire application.

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  Edit1.Hint := 'Enter your name';

  Edit1.ShowHint := True;

  with ListBox1 do

  begin

    for I := 1 to 10 do

      Items.Add('Item ' + IntToStr(I));

    Hint := 'Select an item';

    ShowHint := True;

  end;

  Application.ShowHint := True;

end;

To see a example that displays the hints of controls in some place other than in a Help Hint box, see the OnHint example.


See also

GetLongHint function

GetShortHint function

HintColor property

HintPause property

ShowHint property for controls

ShowHint property for the application


HintColor property

See also	Example

Applies to

TApplication component

Declaration

property HintColor: TColor

Description

Run-time only. The HintColor property determines the color of the hint boxes for the Help Hints of the controls in the application. For a table of possible color values, see the Color property.


Example

This example includes an control that has a Hint property value and has its ShowHint property value set to True. When the application runs and the user places the mouse cursor over the control, a Help Hint appears for the control in an aqua hint box after a delay of 1000 milliseconds:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.ShowHint := True;

  Application.HintColor := clAqua;

  Application.HintPause := 1000;

end;


See also

Application variable

Hint property

HintPause property

ShowHint property

TColor type


HintHidePause property

Applies to

TApplication component

Declaration

property HintHidePause: Integer

Description

Run-time only. The HintHidePause property specifies the pause to wait before hiding the hint if the mouse has not moved from the control.  Default value is 2500 ms or 2.5 seconds.


HintPause property

See also	Example

Applies to

TApplication component

Declaration

property HintPause: Integer;

Description

The HintPause property determines the time interval that passes when the user places the mouse pointer on a control before the control's Help Hint specified in its Hint property appears. The interval is in milliseconds. The default value is 800 milliseconds.


Example

This example includes an control that has a Hint property value and has its ShowHint property value set to True. When the application runs and the user places the mouse cursor over the control, a Help Hint appears for the control in an aqua hint box after a delay of 1000 milliseconds:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.ShowHint := True;

  Application.HintColor := clAqua;

  Application.HintPause := 1000;

end;


See also

Application variable

Hint property

HintColor property

ShowHint property


Hints property

See also	Example

Applies to

TDBNavigator component

Declaration

property Hints: TStrings;

Description

The Hints property allows you to customize the Help Hints for the buttons on the database navigator. Each hint is a string. The first string in the string object becomes the Help Hint for the first button on the navigator. The seventh hint becomes the Help Hint for the seventh button (the Edit button).

If you don't want to change the Help Hint for every button, enter an empty string ('') for the Help Hint you want to stay the same, or simply leave the line blank if you are using the string list property editor of the Object Inspector for the Hints property.


Example

This example uses a database navigator and a button on a form. When the user clicks the button, the Help Hints for the navigator are modified.

procedure TForm1.Button1Click(Sender: TObject);

var

  NewStrings: TStringList;

begin

  NewStrings := TStringList.Create;

  with NewStrings do

  begin

    Add('Beginning of dataset');

    Add('Previous record');

    Add('');

    Add('End of dataset');

  end;

  DBNavigator1.Hints := NewStrings;

  DBNavigator1.ShowHint := True;

end;


See also

Hint property

HintColor property

HintPause property


HintShortPause property

Applies to

TApplication component

Declaration

property HintShortPause: Integer

Description

Run-time only. The HintShortPause property specifies the pause to wait before bringing up a hint if a hint has already been shown.  It is used to reduce the flicker when moving the mouse quickly over a set of buttons that all have help hints on. The default value is 50ms.


HistoryList property

Applies to

TOpenDialog, TSaveDialog components

Declaration

property HistoryList: TStrings ;

Description

The HistoryList property is obsolete and is provided for backwards compatibility only.


HMetafile type

Unit

Graphics

Declaration

HMETAFILE = THandle;

Description

HMetafile is the handle of a TMetafile object.


HorzScrollBar property

See also	Example

Applies to

TForm, TScrollBox components

Declaration

property HorzScrollBar: TControlScrollBar;

Description

The HorzScrollBar property is the form's or scroll box's horizontal scroll bar. The values of HorzScrollBar's nested properties determines how the horizontal scroll bar behaves.

To make a horizontal scroll bar appear on a form or scroll box, the nested properties of HorzScrollBar must be set like this:

Visible must be True.

The value of the Range property must be greater than the value of the ClientWidth property of the form or the Width property of the scroll box.


Example

This example implements a horizontal scroll bar on the form. The scroll bar scrolls the form 100 pixels more than the form width:

procedure TForm1.FormCreate(Sender: TObject);

begin

  ClientWidth := 300;

  with HorzScrollBar do

  begin

    Increment := 4;

    Position := 0;

    Range := ClientWidth + 100;     {Range must be greater than the form's client width}

    Visible := True;

  end;

end;


See also

AutoScroll property

Increment property

Position property

Range property

ScrollPos property

VertScrollBar property

Visible property


HotKey property

See also

Applies to

THotKey component

Declaration

property HotKey: TShortCut;

Description

The HotKey property contains the current key combination of the hot-key control. Alt+A is the default. To modify the value of the HotKey property either edit it directly or set the value of the Modifiers property. At run-time the HotKey property is reset when the hot key has focus and the user presses valid key combinations.


See also

InvalidKeys property

Modifiers property


Icon property

Applies to

TPicture object; TApplication, TForm components

Description

The Icon property specifies an TIcon object.

Icon Property for Forms

Icon Property for Pictures

Icon Property for Applications


Icon property

See also	Example

Applies to

TForm component

Declaration

property Icon: TIcon

Description

The Icon property determines the icon that is displayed when the window or form is minimized. If you don't assign a specific icon to Icon, the form uses the application's icon.


Example

This code assigns an icon to a form when the form is created:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Icon.LoadFromFile('MYICON.ICO');

end;


See also

LoadFromFile method

SaveToFile method


Icon property

See also	Example

Applies to

TPicture component

Declaration

property Icon: TIcon

Description

The Icon property specifies the contents of the TPicture object as an icon graphic (.ICO file format). If Icon is referenced when the TPicture contains a Bitmap or Metafile graphic, the graphic won't be converted. Instead, the original contents of the TPicture are discarded and Icon returns a new, blank icon.


Example

The following code allows the user to use a dialog box to redefine the icon for the application at run time. When the user clicks Button1, OpenDialog1 executes and the user specifies an icon filename. The file is loaded into the Icon property of the TheIcon picture object. Then, the Icon of TheIcon is assigned to the Icon of Form1.

procedure TForm1.Button1Click(Sender: TObject);

var TheIcon: TPicture;

begin

  OpenDialog1.FileName := '*.ICO';

  if OpenDialog1.Execute then

  begin

    TheIcon := TPicture.Create;

    TheIcon.LoadFromFile(OpenDialog1.FileName);

    Form1.Icon := TheIcon.Icon;

  end;

end;


See also

Graphic property


Icon property

See also	Example

Declaration

property Icon: TIcon;

Description

The value of the Icon property determines which icon represents the application when it is minimized or displayed in the Program Manager.


Example

This line of code uses the icon in the MYAPP.ICO files for the application's icon:

Application.Icon.LoadFromFile('MYAPP.ICO');


See also

Application variable

LoadFromFile method

Minimize method

SaveToFile method


IconOptions property

See also

Applies to

TListView component

Declaration

property IconOptions: TIconOptions;

Description

The IconOptions property contains options pertaining to the icons displayed in a list view. The ViewStyle of the list view must be set to either vsIcon or vsSmallIcons for these options to affect the control. Use the Arrangement property to have the icons align at the top or the left of the list view. Set AutoArrange to True to have the icons arranged automatically when icons are added, moved, deleted or otherwise redrawn. Set WrapText to True to have the Caption of the item wrap rather than display on one line when it exceeds the width of the icon.


See also

Arrangement property

AutoArrange property

WrapText property

ViewStyle property


IgnorePalette property

Applies to

TBitmap object

Declaration

property IgnorePalette: Boolean;

Description

When set to True, the bitmap will not realize its palette when drawing itself. This results in lower picture quality on 256 color video drivers, but quicker drawing of the bitmap.  Used only when TDBImage is replicated (in a TDBCtrlGrid).


ImageIndex property for tree nodes
ImageIndex property

See also

Applies to

TTreeNode, TListItem objects

Declaration

property ImageIndex: Integer;

Description

Run-time only. The ImageIndex property determines which image from the image list will be displayed when an item is at its normal state is not currently selected.


See also

Images property

OnGetImageIndex event

Images property

OnGetSelectedIndex property

StateImages property

OverlayIndex property

StateIndex property


Images property

See also	Example

Applies to

TTreeView component

Declaration

property Images: TImageList;

Description

Run-time only. The Images property for a tree view determines which image list (TImageList) is associated with the tree view. An image list contains a list of bitmaps that can be displayed to the left of an items label.


Example

The following example sets the tree views Items property to ImageList1.

TreeView1.Images := ImageList1;


See also

OnGetImageIndex event

OnGetSelectedIndex event

SelectedIndex property

StateImages property

OverlayIndex property

StateIndex


ImageType property

See also

Applies to

TImageList component

Declaration

property ImageType: TImageType;

Description

The ImageType property determines whether the ImageList will use the image or the associated image mask when drawing. These are the possible values:

Value	Meaning

itImage	Draws the image.

itMask	Draws the mask.


See also

Draw method

Masked property

InsertMasked method

AddMasked method


Inch property

Applies to

TMetafile object

Declaration

property Inch: Word;

Description

The Inch property value is the number of pixels per inch that are used for the metafile's coordinate mapping. For example, if the metafile was created in a Twips coordinate system (using MM_TWIPS mapping), the value of Inch is 1440.


Increment property

See also	Example

Applies to

TControlScrollBar component

Declaration

property Increment: Integer;

Description

The Increment property determines how many positions the scroll box in a form scroll bar moves when the user clicks one of the small end arrows. The default value is 8.


Example

This example implements a horizontal scroll bar on the form. The scroll bar scrolls the form 100 pixels more than the form width. Each time the user clicks a scroll arrow on the scroll bar, the form scrolls 7 pixels:

procedure TForm1.FormCreate(Sender: TObject);

begin

  ClientWidth := 300;

  with HorzScrollBar do

  begin

    Position := 0;

    Increment := 7;

    Range := ClientWidth + 100;     {Range must be greater than the form's client width}

    Visible := True;

  end;

end;


See also

HorzScrollBar property

Position property

Range property

ScrollPos property

VertScrollBar property


Indent property

Applies to

TTreeView component

Declaration

property Indent: Integer;

Description

The Indent property specifies the amount of indentation in pixels when a list of child items is expanded. When a list of child items is expanded, it is indented relative to the parent item.


Index property

Applies to

TCollectionItem, THeaderSection, TOutlineNode, TListItem, TStatusPanel objects; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField,TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

Index property for outline nodes and tree nodes

Index property for field components

Index property for collection items, header sections, and status panels

Index property for list items


Index property

See also	Example

Applies to

TOutlineNode, TTreeNode objects

Declaration

property Index: Longint;

Description

The Index property uniquely identifies each item of an outline or tree view. The first item has an Index value of 1, and subsequent items are indexed sequentially. If an item has subitems, the Index value of the parent item is one less than the Index value of its first subitem.

The value of the Index property corresponds to the index in the Items property array of the TOutline component. When an item is added, inserted, or deleted from the outline, the values of the Index properties of all subsequent items must be recalculated to be valid. This happens automatically, unless the BeginUpdate method has been called.


Example

The following code tests to determine if the selected item is the top item in the outline.

with Outline1 do

  if Items[SelectedItem].Index = 1 then

    { The selected item is the top item }

  else

    { The selected item is not the top item };


See also

Add method

Delete method

EndUpdate method

Insert method


Index property

See also

Applies to

TCollectionItem, THeaderSection, TStatusPanel objects;

Declaration

property Index: Integer;

Description

Run-time only. The Index property contains the zero-based index value of the TCollectionItem in the Items array of its associated TCollection object. Items is the collection property that contains all of the items in the collection. For THeaderSection objects, Index is its index value in the Items array of a THeaderSections object. For TStatusPanel objects Index is its index value in the Items array of a TStatusPanels object.


See also

Items property


Index property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField,TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property Index: Integer;

Description

Index is a field's index number into the Fields property of the dataset. It corresponds to the order of the field in the dataset. You can change the order of a field's position in the dataset by changing its Index property. A better way to change field order, however, is by dragging and dropping fields in the Fields Editorat design time.


Index property for list item objects
Index property

See also

Applies to

TListItem object

Declaration

property Index: Integer;

Description

Run-time and read-only. The Index property uniquely identifies each item (TListItem object) in a list view. The first item has an index of 0, and subsequent items are numbered sequentially.


See also

Items property

IndexOf method


IndexDefs property

Example

Applies to

TTable component

Declaration

property IndexDefs: TIndexDefs;

Description

Run-time and read-only. The IndexDefs property holds information about all the indexes for the TTable.

Note:	The IndexDefs property may not always reflect the current set of indexes. Before examining any property of IndexDefs, call its Update method to ensure that it has the most recent set of information.


Example

{ Get the current available indicies }

Table1.IndexDefs.Update;

{ Find one which combines Customer Number ('CustNo') and Order Number ('OrderNo') }

for I := 0 to Table1.IndexDefs.Count - 1 do

  if Table1.IndexDefs.Items[I].Fields = 'CustNo;OrderNo' then


IndexFieldCount property

Example

Applies to

TTable component

Declaration

property IndexFieldCount: Integer;

Description

Run-time only. The IndexFieldCount property is the number of actual fields for the current index. If you are using the primary index for the component, this value will be one. If the component is not Active, the value of IndexFieldCount will be zero.


Example

TotalLen := 0;

with Table1 do

{ Calculate the total length of the index }

  for I := 0 to IndexFieldCount - 1 do

    Inc(TotalLen, IndexFields[I].FieldDef.DataSize);


IndexFieldNames property

Example

Applies to

TTable component

Declaration

property IndexFieldNames: string;

Description

The IndexFieldNames property is used with an SQL server to identify the columns to be used as an index for the TTable. Separate the column names with semicolon characters (";"). If you have too many column names or the names are too long to fit within the 255 character limit, use column numbers instead of names.

Note:	IndexFieldNames and IndexName are mutually exclusive. Setting one will clear the other.


Example

Query1.IndexFieldNames := 'CustNo;OrderNo';


IndexFields property

See also	Example

Applies to

TTable component

Declaration

property IndexFields[Index: Integer]: TField;

Description

Run-time only. The IndexFields property gives you access to information about each field of the current index for the dataset. The Active property must be True or the information will not be valid.


Example

S := '';

with Table1 do

{ Create a composite string with the index's names separated by "@" }

for I := 0 to IndexFieldCount - 1 do

    S := S + '@' + IndexFields[I].FieldName;


See also

IndexFieldCount property


IndexFiles property

See also

Applies to

TTable component

Declaration

property IndexFiles: TStrings;

Description

The IndexFiles property is a list of file names containing non-production indexes for dBASE tables. Because IndexFiles is of type TStrings, you can add, insert, delete, and clear index filenames using the Add, Insert, Delete, and Clear methods of TStrings. As you add index filenames (using Add or Insert), TTable opens them. While the indexes are opened, updates made to the table maintain the indexes. You can make one the active index by setting the IndexName property. As you delete index filenames (using Delete or Clear), TTable closes them and they are no longer maintained.


See also

CloseIndexFile method

OpenIndexFile method


IndexName property

See also	Example

Applies to

TTable component

Declaration

property IndexName: string;

Description

The IndexName property identifies a secondary index for the TTable. If no value is assigned to IndexName, the table's primary index will be used to order the records.

For dBASE tables, the index must reside in the table's master index file. The master index file is determined by taking the TableName property and replacing any file extension with "MDX". Non-maintained indexes are not supported.

Note:	IndexFieldNames and IndexName are mutually exclusive. Setting one will clear the other.


Example

Table1.IndexName := 'CustNoIndex';


See also

MasterFields property

MasterSource property


IndexOf method

Applies to

TList, TStringList, TStrings, TTreeNode, TListItems objects; TIndexDefs, TFieldDefs, TMenuItem components

Description

The IndexOf method returns the position of an item in an object or component.

IndexOf Method for Menu Items

IndexOf Method for List Objects

IndexOf Method for List Items

IndexOf Method for String Objects

IndexOf Method for Field Definitions

IndexOf Method for Index Definitions

IndexOf Method for Tree Node Objects


IndexOf method

See also	Example

Applies to

TMenuItem component

Declaration

function IndexOf(Item: TMenuItem): Integer;

Description

The IndexOf method returns the position of a menu item within a menu. The first position in a menu is 0. If a menu item is not in the menu, IndexOf returns -1.


Example

This example uses a main menu named File1, a button, and a label on a form. The File1 menu contains three menu commands, Open, Save, and Close. Delphi automatically names these menu items Open1, Save1, and Close1. This code returns the position of the Close command in the File menu and reports it as the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := IntToStr(File1.IndexOf(Close1));

end;

The label displays the number 2, indicating that Close is the third menu command in the File menu. The first menu item, Open, has an index value of 0.


See also

FindItem method


IndexOf method

See also	Example

Applies to

TList objects

Declaration

function IndexOf(Item: Pointer): Integer;

Description

The IndexOf method returns the position of an item in a list kept by the List property. The first position in a list is 0. If an item is not in the list, IndexOf returns -1.


Example

The following code adds an object to MyList if it isn't already in the list.

if MyList.IndexOf(MyObject)=-1 then MyList.Add(MyObject);


See also

Add method

Count property


IndexOf method for string list objects
IndexOf method

See also	Example

Applies to

TList, TStringList, TStrings, TTreeNode objects; TIndexDefs, TMenuItem components

Applies to

TStringList, TStrings objects

Declaration

function IndexOf(const S: string): Integer;

Description

The IndexOf method returns the position of a string in a list of strings in a string or string list object. Specify the string you want to locate as the value of the S parameter. The first position in the list of strings is 0. If the string is not in the string list, IndexOf returns -1.

Note:	The comparison is case sensitive for string lists.


Example

This example uses a combo box that contains five strings (enter them as the value of the Items property with the Object Inspector) and a label. When the user selects a string in the combo box, the index of the selected string appears as the caption of the label.

procedure TForm1.ComboBox1Click(Sender: TObject);

begin

  Label1.Caption := IntToStr(ComboBox1.Items.IndexOf(ComboBox1.SelText));

end;

This example uses a file list box, a directory list box, and a label on a form. When the user uses the directory list box to change directories, a message appears and the color of the form changes if the file AUTOEXEC.BAT is in the new directory. The code is written in the OnChange event of the directory list box:

procedure TForm1.DirectoryListBox1Change(Sender: TObject);

begin

  FileListBox1.Directory := DirectoryListBox1.Directory;

  if FileListBox1.Items.IndexOf('AUTOEXEC.BAT') > -1 then

  begin

    Color := clYellow;

    Label1.Caption := 'You are in the root directory!';

  end;

end;


See also

IndexOfObject method

Strings property


IndexOf method

Applies to

TIndexDefs object

Declaration

function IndexOf(const Name: string): Integer;

Description

The IndexOf method returns the index of the entry in Items whose Name property matches the Name parameter.


IndexOf method for tree node objects
IndexOf method

See also

Applies to

TTreeNode object

Declaration

function IndexOf(Value: TTreeNode): Integer;

Description

The IndexOf method returns the position of an immediate child item (Value parameter) of the calling item. If Value isn't an immediate child of the calling item, IndexOf returns -1. The first child item has an index on 0, the second an index of 1, and so on.


See also

GetFirstChild method

HasChildren property


IndexOf method for list items objects
IndexOf method

See also	Example

Applies to

TListItems object

Declaration

function IndexOf(Value: TListItem): Integer;

Description

The IndexOf method returns the index of the list item specified by the Value parameter.


Example

The following example displays the selected item's index in the list box.

with ListView1 do

  ListBox1.Items.Add('Index: ' + IntToStr(Items.IndexOf(Selected)));


See also

Items property

Index property


IndexOf method

Applies to

TFieldDefs object

Declaration

function IndexOf(const Name: string): Integer;

Description

The IndexOf method returns the index number of the entry in Items whose Name property matches the Name parameter.


IndexOfName method

See also	Example

Applies to

TStringList, TStrings objects

Declaration

function IndexOfName(const Name: string): Integer

Description

The IndexOfName method returns the Index of the name part of a string which is of the form Name=Value. Specify the Name you want to locate as the value of the Name parameter. The first position in the list of objects is 0. If the name is not in the list of strings, IndexOfName returns -1.


Example

The following example merges the strings in the memo control into strings contained in the list box. If a string in the list box is of the form Name=Value and the Name is also contained in the memo, its value will be replaced by the memo's value.

procedure MergeStrings(Dest, Source: TStrings);

var

  DI, I, P: Integer;

  S: string;

begin

  for I := 0 to Source.Count - 1 do

  begin

    S := Source[I];

    P := Pos('=', S);

    if P > 1 then

    begin

      DI := Dest.IndexOfName(Copy(S, 1, P - 1));

      if DI > -1 then Dest[DI] := S;

    end;

  end;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  MergeStrings(ListBox1.Items,Memo1.Lines);

end;


See also

Add method

IndexOf method

Insert method

Values property


IndexOfObject method

See also	Example

Applies to

TStringList, TStrings objects

Declaration

function IndexOfObject(AObject: TObject): Integer;

Description

The IndexOfObject method returns the position of an object stored in the Objects property of a string object. Specify the object you want to locate as the value of the AObject parameter. The first position in the list of objects is 0. If the object is not in the list of objects, IndexOfObject returns -1.


Example

The following code determines if MyObject is the first object in MyStringList.

if MyStringList.IndexOfObject(MyObject)=0 then

  { MyObject is the first object in the list };


See also

AddObject method

IndexOf method

InsertObject method


InitialDir property

See also	Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property InitialDir: string;

Description

The InitialDir property determines the current directory when the dialog box first appears and value of the InitialDir property is shown as the current directory in the directory tree. Only files in the current directory appear in the dialog box's list box of filenames. After the dialog box appears, users can then use the directory tree to change to another directory if they want.

When specifying the initial directory, include the full path name. For example,

C:\WINDOWS\SYSTEM

If no initial directory is specified, the directory that is current when the dialog box appears remains the current directory. The same is true if you specify a directory that does not exist.


Example

This code specifies C:\WINDOWS as the initial directory when the dialog box appears, displays the dialog box, and displays the name of the file the user selects with the dialog box in a label on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  OpenDialog1.InitialDir := 'C:\WINDOWS';

  if OpenDialog1.Execute then

    Label1.Caption := OpenDialog1.FileName;

end;


See also

Filter property


InitialValues property

See also	Example

Applies to

TReport component

Declaration

property InitialValues: TStrings;

Description

The InitialValues property is a list of report variable strings the specified report uses to run. By specifying these initial values, your application can bypass the dialog boxes that prompt you for these values when the report runs.


Example

The following code adds two report variable values and runs the report.

Report1.InitialValues.Add('@Report1=<35>');

Report1.InitialValues.Add('@Report2=<test>');

Report1.Run;


See also

SetVariable method

SetVariableLines method


InputBox function

See also	Example

Declaration

function InputBox(const ACaption, APrompt, ADefault: string): string;

Description

The InputBox function displays an input dialog box ready for the user to enter a string in its edit box. The ACaption parameter is the caption of the dialog box, the APrompt parameter is the text that prompts the user to enter input in the edit box, and the ADefault parameter is the string that appears in the edit box when the dialog box first appears.

If the user chooses the Cancel button, the default string is the value returned. If the user chooses the OK button, the string in the edit box is the value returned.

Use the InputBox function when it doesn't matter if the user chooses either the OK button or the Cancel button (or presses Esc) to exit the dialog box. When your application needs to know if the user chooses OK or Cancel (or presses Esc), use the InputQuery function.


Example

This example displays an input dialog box when the user clicks the button on the form. The input dialog box includes a prompt string and a default string. The string the user enters in the dialog box is stored in the InputString variable.

uses Dialogs;

procedure TForm1.Button1Click(Sender: TObject);

var

  InputString: string;

begin

  InputString:= InputBox('Input Box', 'Prompt', 'Default string');

end;


See also

MessageDlg function

MessageDlgPos function


InputQuery function

See also	Example

Unit

Dialogs

Declaration

function InputQuery(const ACaption, APrompt: string; var Value: string): Boolean;

Description

The InputQuery function displays an input dialog box ready for the user to enter a string in its edit box. The ACaption parameter is the caption of the dialog box, the APrompt parameter is the text that prompts the user to enter input in the edit box, and the Value parameter is the string that appears in the edit box when the dialog box first appears. If the user enters a string in the edit box and chooses OK, the Value parameter changes to the new value.

The InputQuery function returns True if the user chooses OK, and False if the user chooses Cancel or presses the Esc key.

If your application doesn't need to know whether the user chooses OK or Cancel, use the InputBox function.


Example

This example uses a button and a label on the form. When the user clicks the button, a the input box displays. If the user chooses OK, the string that appears in the edit box of the dialog box displays as the caption of the label on the form. If the user chooses Cancel, the dialog box closes and the caption of the label remains unchanged.

procedure TForm1.Button1Click(Sender: TObject);

var

  NewString: string;

  ClickedOK: Boolean;

begin

  NewString := 'Default String';

  Label1.Caption := NewString;

  ClickedOK := InputQuery('Input Box', 'Prompt', NewString);

  if ClickedOK then                             { NewString contains new input string }

    Label1.Caption := 'The new string is ''' + NewString + '''';

end;


See also

MessageDlg function

MessageDlgPos function


Insert method

Applies to

TImageList, TList, TListItems, TMenuItem, TStringList, TStrings, TTreeNodes objects; TOutline, TQuery, TTable components

Description

The Insert method inserts an item into an object or component.

Insert Method for List Objects

Insert Method for List Items

Insert Method for String Objects

Insert Method for Menu Items

Insert Method for Outlines

Insert Method for Tables and Queries

Insert Method for Tree Nodes Objects

Insert Method for Image List Objects


Add method for image list objects
Insert method

See also

Applies to

TImageList object

Declaration

procedure Insert(Index: Integer; Image, Mask: TBitmap);

Description

The Insert method inserts a bitmap and its mask after the image specified by Index into the ImageList.


See also

Add method

AddImages method

InsertIcon method


Insert method

See also	Example

Applies to

TTreeNodes object

Declaration

function Insert(Node: TTreeNode; const S: string): TTreeNode;

Description

The Insert method for a tree nodes object inserts an item(TTreeNode) into the tree view after the item specified by the Node parameter. The S parameter specifies the Text property of the new item. Insert returns the new item.


Example

The following example inserts a new item after the selected item in the tree view.

TreeView1.Items.Insert(TreeView1.Selected, 'Insert Item');


See also

AddChildFirst method

AddChildObjectFirst method

AddChildObject method

AddFirst method

AddChild method

AddObjectFirst method

AddObject method

Add method

MoveTo method


Insert Method for List Objects
Insert method

See also	Example

Applies to

TList objects

Declaration

procedure Insert(Index: Integer; Item: Pointer);

Description

The Insert method inserts an item into the list of items stored in the List property of a list object. Specify the item to insert as the value of the Item parameter. Specify the position in the list where you want the item inserted as the value of the Index parameter. The index is zero-based, so the first position in the list has an index value of 0.

If your application calls Insert when the list of items is sorted, an EListError exception is raised.


Example

The following code inserts MyObject into MyList at the position immediately following the position of MyOtherObject.

MyList.Insert(IndexOf(MyOtherObject)+1, MyObject);


See also

Add method

Clear method

Count property

Delete method

First method

IndexOf method

Last method


Insert Method for String and String List Objects
Insert method

See also	Example

Applies to

TStrings object

Declaration

procedure Insert(Index: Integer; const S: string);

Description

The Insert method inserts a string into the list of strings in a string or string list object. The string S is inserted into the position in the list indicated by the value of Index. The index is zero-based, so the first position in the list has an index value of 0.


Example

This example uses a list box and a button on a form. When the form appears, it contains five items. When the user clicks the button, another string is inserted at the top of the list of items:

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  for I := 1 to 5 do

    ListBox1.Items.Add('Item ' + IntToStr(I));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin  ListBox1.Items.Insert(0, 'Inserted here');

end;


See also

Add method

AddStrings method

Clear method

Delete method

IndexOf method

InsertObject method


Insert method

See also	Example

Applies to

TMenuItem objects

Declaration

procedure Insert(Index: Integer; Item: TMenuItem);

Description

The Insert method inserts a menu item in a menu at the position indicated by the value of Index.


Example

This example inserts a new menu item after the first item in a menu named FileMenu:

procedure TForm1.Button1Click(Sender: TObject);

var

  NewItem: TMenuItem;

begin

  NewItem := TMenuItem.Create(FileMenu);

  try

    NewItem.Caption := 'Do this';

    FileMenu.Insert(1, NewItem);

  finally

    NewItem.Free;

    raise;

  end;

end;


See also

Add method

Count property

Delete method


Insert Method for Outlines
Insert method

See also	Example

Applies to

TOutline component

Declaration

function Insert(Index: Longint; const Text: string): Longint;

Description

The Insert method inserts an outline item (TOutlineNode object) into an outline. The value of the Index and Text parameters are stored in the Index and Text properties of the inserted item. Insert returns the Index property value of the inserted item.

The inserted item appears in the outline position determined by the Index parameter. It is inserted at the same level as the item that previously resided at this position. Therefore, the inserted item and the original item are siblings and share the same parent. The original item and all other outline items that appear after the inserted item are moved down one row and are reindexed with valid Index values. This happens automatically unless the BeginUpdate method was called.

Note:	To insert an item as the last top-level item in an outline, pass zero (0) in the Index parameter.


Example

The following code inserts an item as a sibling of the selected item.

begin

  Outline1.Insert(Outline1.SelectedItem, 'New item');

end;


See also

Add method

AddChild method

AddChildObject method

InsertObject method

MoveTo method


Insert method

Example

Applies to

TTable, TQuery components

Declaration

procedure Insert;

Description

The Insert method puts the dataset into Insert state and opens a new, empty record at the current cursor location. When an application calls Post, the new record will be inserted in the dataset in a position based on its index, if defined. To discard the new record, use Cancel.

This method is valid only for datasets that return a live result set.

Note:	For indexed tables, the Append and Insert methods will both put the new record in the correct location in the table, based on the table's index. If no index is defined on the underlying table, then the record will maintain its position--Append will add the record to the end of the table, and Insert will insert it at the current cursor position. In either case, posting a new record may cause rows displayed in a data grid to change as the dataset follows the new row to its indexed position and then fetches data to fill the data grid around it.


Example

with Table1 do

  begin

{ Move to the end ot the component }

  Last;

  Insert;

  FieldByName('CustNo').AsString := '9999';

  { Fill in other fields here }

  if { you are sure you want to do this} then Post

  else { if you changed your mind } Cancel;

  end.


Insert method for list items objects
Insert method

See also	Example

Applies to

TListItems object

Declaration

function Insert(Index: Integer): TListItem;

Description

The Insert method for a list items object inserts a list item (TListItem object) into the list view after the item specified by the Index parameter. Insert returns the list item that is inserted.


Example

The following example inserts a list item after the selected item in the list view.

procedure TForm1.Button1Click(Sender: TObject);

var InsertItem : TlistItem;

begin

  with ListView1 do

  InsertItem:= Items.Insert(Selected.Index);

  InsertItem.Caption := 'InsertedItem';

end;


See also

Add method

Items property


InsertComponent method

See also	Example

Applies to

All components

Declaration

procedure InsertComponent(AComponent: TComponent);

Description

The InsertComponent method makes the component own the component passed in the AComponent parameter. The component is added to the end of the Components array property. The inserted component must have no name (no specified Name property value), or the name must be unique among all others in the Components list.

When the owning component is destroyed, AComponent is destroyed also.


Example

The following code inserts NewButton into the Components array of Form1.

Form1.InsertComponent(NewButton);


See also

RemoveComponent method


InsertControl method

See also	Example

Applies to

All controls

Declaration

procedure InsertControl(AControl: TControl);

Description

The InsertControl method inserts a control within the Controls property of a windowed control, making the inserted control a child, and the containing control the parent. The inserted control is the value of the AControl parameter.


Example

This example uses a button placed next to a group box. When the user clicks the button, the group box becomes the parent of the button, so the button moves inside the group box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  RemoveControl(Button1);

  GroupBox1.InsertControl(Button1);

end;

Note that it was necessary to remove the button from the Controls property of the form before the button actually moves into the group box.

This code accomplishes the same thing:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Parent := GroupBox1;

end;


See also

Parent property

RemoveControl method


Add method for image list objects
InsertIcon method

See also

Applies to

TImageListcomponent

Declaration

procedure InsertIcon(Index: Integer; Image: TIcon);

Description

The InsertIcon method inserts an icon after the image specified by Index into the ImageList.


See also

AddIcon method

Insert method

Add method

AddImages method


Add method for image list objects
InsertMasked method

See also

Applies to

TImageList object

Declaration

procedure InsertMasked(Index: Integer; Image: TBitmap; MaskColor: TColor);

Description

The InsertMasked method inserts a bitmap after the image specified by Index, creating the mask from the transparent color provided by the parameter MaskColor.


See also

AddMasked method

InsertIcon method

Insert method

ImageIndex property


InsertObject method

See also	Example

Applies to

TStringList, TStrings, TTreeNodes objects; TOutline, TTreeView components

Description

InsertObject for String Objects

InsertObject for Outlines

InsertObject for Tree Nodes Objects


InsertObject method

Applies to

TTreeNodes object

Declaration

function InsertObject(Node: TTreeNode; const S: string; Ptr: Pointer): TTreeNode;

Description

The InsertObject method for a tree nodes object inserts an item (TTreeNode) containing data into the tree view after the item specified by the Node parameter. The S parameter specifies the Text property of the new item. Insert returns the new item. The Ptr parameter specifies the Data property of the new item.


Example

The following example inserts a new item after the selected item in the tree view. The TBitmap object is attached to the new item.

TreeView1.Items.Insert(TreeView1.Selected, 'Insert Item', MyBitmap);


See also

Insert method

AddChildFirst method

AddChildObjectFirst method

AddChildObject method

AddFirst method

AddChild method

AddObjectFirst method

AddObject method

Add method

MoveTo method


InsertObject method

See also	Example

Applies to

TStringList, TStrings objects

Declaration

procedure InsertObject(Index: Integer; const S: string; AObject: TObject);

Description

The InsertObject method inserts a string into the list of strings and an object into the list of objects in a string or string list object. Specify the string you want to insert as the value of the S parameter, and the object you want to insert as the value of the AObject parameter. The Index parameter identifies the position of the string and object in their respective string and object lists. Because the index is zero-based, the first position in each list has an Index value of 0.

If your application calls InsertObject when the list of items is sorted, an EListError exception is raised.


Example

The following code inserts the components of Form1 into the first position of the Lines list of Memo1.

var

  I: Integer;

begin

  for I := 0 to Form1.ComponentCount-1 do

  begin

    with Form1.Components[i] as TComponent do

    Memo1.lines.InsertObject(0, Name, Self);

  end;

end;


See also

AddObject method

IndexOfObject method

Insert method

Objects property

Strings property


InsertObject method

See also	Example

Applies to

TOutline component

Declaration

function InsertObject(Index: Longint; const Text: string; const Data: Pointer): Longint;

Description

The InsertObject method inserts an outline item (TOutlineNode object) containing data into an outline. The value of the Index and Text parameters are stored in the Index and Text properties of the inserted item. The Data parameter specifies the Data property value of the new item. Insert returns the Index property value of the inserted item.

The inserted item appears in the outline position determined by the Index parameter. It will be inserted at the same level as the item that previously resided at this position. Therefore, the inserted item and the original item will be siblings and share the same parent. The original item and all other outline items that appear after the inserted item are moved down one row and are reindexed with valid Index values. This is done automatically unless the BeginUpdate method was called.

Note:	To insert an item as the last top-level item in an outline, pass zero (0) in the Index parameter.


Example

The following code creates a bitmap object named Bitmap1 and inserts an outline item containing Bitmap1 into the first level of Outline1.

var

  Bitmap1: TBitmap;

begin

  Bitmap1 := TBitmap.Create;

  Outline1.InsertObject(1, 'New item', Bitmap1);

end;


See Also

Add method

AddChild method

AddChildObject method

Insert method

MoveTo method


InsertRecord method

See also	Example

Applies to

TTable, TQuery components

Declaration

procedure InsertRecord(const Values: array of const);

Description

The InsertRecord method inserts a new record into the dataset using the field values passed in the Values parameter. The assignment of the elements of Values to fields in the record is sequential; the first element is assigned to the first field, the second to the second, etc. The number of field values passed in Values may be fewer than the number of actual fields in the record; any remaining fields are left unassigned and are NULL. The type of each element of Values must be compatible with the type of the field in that the field must be able to perform the assignment using AsString, AsInteger, etc., according the type of the Values element.

This method is valid only for datasets that return a live result set.

Note:	For indexed tables, the AppendRecord and InsertRecord methods will both put the new record in the correct location in the table, based on the table's index. If no index is defined on the underlying table, then the record will maintain its position--AppendRecord will add the record to the end of the table, and InsertRecord will insert it at the current cursor position. In either case, posting a new record in a data grid may cause all the rows before and after the new record to change as the dataset follows the new row to its indexed position and then fetches data to fill the grid around it.


Example

This statement appends a record to the Customer table. Note that Nulls are entered for some of the values, but are not required for missing values at the end of the array argument.

Customer.InsertRecord([CustNoEdit.Text, CoNameEdit.Text, AddrEdit.Text,

Null, Null, Null, Null, Null, Null, DiscountEdit.Text]);


See also

TField component


InsertSQL property

Applies to

TUpdateSQL component

Declaration

property InsertSQL: TStrings;

Description

The InsertSQL property returns the string list containing the SQL statement to be used when applying the cached insertion of a record. Generally, such an SQL statement would be an INSERT INTO statement. You can use the UpdateSQL Editor (by double-clicking the TUpdateSQL component) to generate an appropriate SQL statement, such as the following:

insert into "COUNTRY.DB"

  (Name, Capital, Continent)

values

  (:Name, :Capital, :Continent)


IntegralHeight property

See also	Example

Applies to

TDBListBox, TDirectoryListBox, TFileListBox, TListBox component

Declaration

property IntegralHeight: Boolean;

Description

The IntegralHeight property controls the way the list box represents itself on the form. If IntegralHeight is True, the list box shows only entries that fit completely in the vertical space, and the bottom of the list box moves up to the bottom of the last completely drawn item in the list. If IntegralHeight is False, the bottom of the list box is at the location determined by its ItemHeight property, and the bottom item visible in the list might not be complete.

If the list box has a Style property value of lbOwerDrawVariable, setting the IntegralHeight property to True has no effect.

If the Style property value of the list box is lsOwnerDrawFixed, the height of the list box at design time is always an increment of the ItemHeight value.


Example

This example uses a list box on a form. To try it, enter as many strings in the Items property as you like using the Object Inspector. When the application runs, the list box displays only entries that fit completely in the vertical space, and the bottom of the list box moves up to the bottom of the last string in the list box if the form is less than 300 pixels in height:

procedure TForm1.FormCreate(Sender: TObject);

begin

  if Height < 300 then

    ListBox1.IntegralHeight := True

  else

    ListBox1.IntegralHeight := False;

end;


See also

ItemHeight property

Items property


Interval property

Example

Applies to

TTimer component

Declaration

property Interval: Cardinal;

Description

The Interval property determines in milliseconds the amount of time that passes before the timer component initiates another OnTimer event.

You can specify any value in the cardinal range as the interval value, but the timer component won't call an OnTimer event if the value is 0. The default value is 1000 (one second).


Example

The code in this OnTimer event handler moves a ball, the shape component (TShape) slowly across a form.

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  Timer1.Interval := 100;

  Shape1.Shape := stCircle;

  Shape1.Left := Shape1.Left + 1;

end;


Invalidate method

See also	Example

Applies to

All controls; TForm component

Declaration

procedure Invalidate;

Description

The Invalidate method forces a control to repaint as soon as possible.


Example

The following code invalidates Form1.

Form1.Invalidate;


See also

Refresh method

Update method


InvalidKeys property

See also

Applies to

THotKey component

Declaration

property InvalidKeys: THKInvalidKeys;

Description

The InvalidKeys property allows the user to specify that one or more modifier keys should be considered invalid. If this property is set, a default modifier should also be specified in the Modifiers property. When the invalid key is selected, the default modifier is displayed in its place.

These are the possible values:

Value	Meaning

hcNone	Unmodified keys are invalid.

hcShift	The Shift key is invalid as a modifier.

hcCtrl	The Ctrl key is invalid as a modifier.

hcAlt	The Alt key is invalid as a modifier.

hcShiftCtrl	The Shift+Ctrl key combination is invalid as a modifier.

hcShiftAlt	The Shift+Alt key combinations invalid as a modifier.

hcCtrlAlt	The Ctrl+Alt key combination is invalid as a modifier.

hcShiftCtrlAlt	The Shift+Ctrl+Alt key combination is invalid as a modifier.

The default values are hcNone and hcShift.


See also

HotKey property

Modifiers property


IsEditing method

See also

Applies to

TListView, TTreeView components

Declaration

function IsEditing: Boolean;

Description

Run-time only. The IsEditing method returns True if any list item in the list view is being edited.


See also

Caption property

OnEditing event

ReadOnly property

Items property


IsIndexField property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property IsIndexField: Boolean;

Description

Run-time and read-only. The IsIndexField property specifies whether a field is indexed. If True, a field is indexed.


IsMasked property

See also	Example

Applies to

TDBEdit, TMaskEdit components

Declaration

property IsMasked: Boolean;

Description

The IsMasked property determines if a mask exists (the EditMask property has a value) for the data displayed in the database edit box or mask edit box. If IsMasked is True, a mask exists. If IsMasked is False, no mask exists.


Example

This example tests the masked edit box to determine if it has an edit mask. If it doesn't an edit mask is assigned. The edit mask is one for dates in the MM/DD/YY format:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if not MaskEdit1.IsMasked then

    MaskEdit1.EditMask := '!99/99/00;1;_';

end;


See also

EditMask property


IsNull property

Applies to

TParam object; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

IsNull Property for Field Components

IsNull Property for TParam Objects


IsNull property

Example

Applies to

TParam object

Declaration

property IsNull: Boolean;

Description

IsNull is a read-only property that returns True if the parameter has no data assigned to it. This should only occur if an application has called:

Assign with another parameter that has no data assigned.

AssignField with a TField whose data is null.

The Clear method.


Example

The following code sets the CustNo parameter to 999 if it is null:

with Params.ParamByName('CustNo') do

  if IsNull then AsInteger := 999;


IsNull property

See also

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property IsNull: Boolean;

Description

Run-time and read-only. IsNull returns True if the value of the field is NULL.


See also

Required property


IsSQLBased property

Applies to

TDataBase component

Declaration

property IsSQLBased: Boolean;

Description

Run-time and read-only. IsSQLBased is True if the TDatabase component uses any driver other than 'STANDARD'. If you are accessing a dBASE or Paradox database or ASCII file, IsSQLBased will be False.


IsValidChar method

See also

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

function IsValidChar(InputChar: Char): Boolean; virtual;

Description

IsValidChar is used by data-aware controls to determine if a particular character entered in the field is valid for the field. TIntegerField, TSmallintField and TWordField allow '+', '-' and '0' to '9'. TBCDField and TFloatField also allow 'E', 'e', and the DecimalSeparator character. All other fields accept all characters.


See also

DecimalSeparator variable


IsVisible property

See also	Example

Applies to

TOutlineNode, TTreeNode objects

Declaration

property IsVisible: Boolean;

Description

Run-time and read-only. The IsVisible property indicates whether the outline item or tee node item is visible within the TOutline component or TTreeView component. For outline items, an item is visible if it is on level 1 or if all its parents are expanded. For tree nodes, an item is visible if it is on level 0 or if all its parents are expanded.


Example

The following code expands the branch of the selected outline item if it isn't visible.

with Outline1.Items[Outline1.SelectedItem] do

  if not IsVisible then FullExpand;


See also

Expanded property

Level property


Item property for tree nodes objects
Item property

Applies to

TListItems, TTreeNode, TTreeNodes objects

Description

Item Property for List Items

Item Property for Tree Node Objects

Item Property for Tree Nodes Objects


Item property for list items objects
Item property

See also

Applies to

TListItems object

Declaration

property Item[Index: Integer]: TListItem;

Description

Run-time only. The Item array property provides access to an item (TListItem object) by its Index position in the list view. The first item has an index of 0, the second an index of 1, and so on.


See also

Index property

Items property


Item property for tree nodes
Item property

See also	Example

Applies to

TTreeNode object

Declaration

property Item[Index: Integer]: TTreeNode;

Description

Run-time only. The Item array property provides access to a child item (TTreeNode object) by its Index position in the list of child items. The first child item has an index of 0, the second an index of 1, and so on.


Example

The following example adds to a list box the text for all the immediate child items of the selected item.

procedure TForm1.Button1Click(Sender: TObject);

var

  I : Integer;

begin

  for I := 0 to (TreeView1.Selected.Count - 1) do

    ListBox1.Items.Add(TreeView1.Selected.Item[I].Text);

end;


See also

GetFirstChild method

Count property


Item property for tree nodes
Item property

See also

Applies to

TTreeNodes object

Declaration

property Item[Index: Integer]: TTreeNode;

Description

Run-time and read-only. The Item array property provides access to an item (TTreeNode object) by its Index position in the tree view. The first item has an index of 0, the second an index of 1, and so on.


See also

Index property

Items property

GetNodeAt method

GetFirstNode method

GetNode method


ItemAtPos method

Applies to

TDBListBox, TDirectoryListBox, TFileListBox, TListBox, TTabSet components

Description

ItemAtPos Method for List Boxes

ItemAtPos Method for Tab Set Controls


ItemAtPos method for list boxes
ItemAtPos method

See also	Example

Applies to

TDBListBox, TDirectoryListBox, TFileListBox, TListBox components

Declaration

function ItemAtPos(Pos: TPoint; Existing: Boolean): Integer;

Description

The ItemAtPos method returns the index of the list box indicated by the coordinates of a point on the control. The Pos parameter is the point in the control in window coordinates.

If Pos is beyond the last item in the list box, the value of the Existing variable determines the returned value. If you set Existing to True, ItemAtPos returns -1, indicating that no item exists at that point. If you set Existing to False, ItemAtPos returns the index of the last item in the list box plus one.

ItemAtPos is useful for detecting if an item exists at a particular point in the control.


Example

This example uses a list box, and edit box, and a button on a form. When the user clicks the button, the index value of the item in the list box which contains the point specified in the code appears in the edit box:

procedure TForm1.Button1Click(Sender: TObject);

var

  APoint: TPoint;

begin

  APoint.X := 30;

  APoint.Y := 50;

  Edit1.Text := IntToStr(ListBox1.ItemAtPos(APoint, False));

end;


See also

ItemIndex property

Items property


ItemAtPos method for tab sets
ItemAtPos method

See also	Example

Applies to

TTabSet component

Declaration

function ItemAtPos(Pos: TPoint): Integer;

Description

The ItemAtPos method returns the index of the tab indicated by the coordinates of a point on the control. The Pos parameter is the point in the control in window coordinates. If the returned index is 0, the tab is the first tab in the tab set, if the index is 1, the tab is the second tab, and so on.

ItemAtPos is useful for determining which tab is located at a particular position in the tab set control.


Example

The following code selects the tab that is at client coordinates (100, 10) in TabSet1.

TabSet1.TabIndex := TabSet1.ItemAtPos(Point(100, 10);


See also

TabIndex property

Tabs property


ItemCount property

See also	Example

Applies to

TOutline component

Declaration

property ItemCount: Longint;

Description

Run-time and read only. The ItemCount property specifies the total number of items in an outline.


Example

The following code turns off automatic reindexing before inserting a new item into the index if the index includes more than 100 items. Otherwise, automatic reindexing remains active.

Outline1.SetUpdateState(Outline1.ItemCount > 100)

Outline1.Insert(1, 'NewItem', MyData);

Outline1.EndUpdate


See also

Items property


Focused property for list views
ItemFocused property

See also

Applies to

TListView component

Declaration

property ItemFocused: TListItem;

Description

Run-time only. The ItemFocused property for list views is used to determine which item, if any, has focus in a list view and to make an item have focus. When an item has focus, it's surrounded by a standard focus rectangle. If no item has focus, ItemFocused will return nil. Only one item can have focus.

Example

The following example changes the caption of the item in the list view that has focus.

ListView1.ItemFocused.Caption := 'Focused';


See also

Selected property

OnChange event

OnChanging event


ItemHeight property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBListBox, TDirectoryListBox, TFileListBox, TListBox, TOutline components

Declaration

property ItemHeight: Integer;

Description

For list boxes, the ItemHeight property is the height of an item in the list box in pixels when the list box's Style property is lsOwnerDrawFixed. If the Style property is lsStandard or lsOwnerDrawVariable, the value of ItemHeight is ignored. You can control the height of an item in a fixed owner-draw list box by changing the height of ItemHeight.

For combo boxes, the ItemHeight property is the height of an item in the combo box list in pixels when the combo box's Style property is csOwnerDrawFixed. If the Style property is any other setting, the value of ItemHeight is ignored. You can control the height of an item in a fixed owner-draw combo box by changing the height of ItemHeight.

For outlines, the ItemHeight property is the height of an item in the outline in pixels when the outline's Style property is osOwnerDraw. If the Style property is osStandard, the value of ItemHeight is ignored. You can control the height of an item in an owner-draw outline by changing the height of ItemHeight.


Example

This example uses a list box and a button on a form. Enter as many strings in the list box as you like using the property editor of the Items property in the Object Inspector. When the user clicks the button on the form, the amount of vertical space allotted to each item in the list box changes.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Style := lbOwnerDrawFixed;

  ListBox1.ItemHeight := 30;

end;


See also

Items property

IntegralHeight property

OnDrawItem event


ItemId property

See also

Applies to

TTreeNode object

Declaration

property ItemId: HTreeItem;

Description

Run-time and read only. The ItemId property is a handle to a TTreeNode of type HTreeItem and uniquely identifies each item in a tree view. Use this property when you need to access items in a tree view from outside of the tree view control.


See also

GetNode method


ItemIndex property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBRadioGroup, TDirectoryListBox, TDriveComboBox, TFileListBox, TFilterComboBox, TListBox, TRadioGroup components

Declaration

property ItemIndex: Integer;

Description

Run-time only except for the TRadioGroup component. The value of the ItemIndex property is the ordinal number of the selected item in the control's item list. If no item is selected, the value is -1, which is the default value unless MultiSelect is True. To select an item at run time, set the value of ItemIndex to the index of the item in the list you want selected, with 0 being the first item in the list.

For list boxes and combo boxes, if the value of the MultiSelect property is True and the user selects more than one item in the list box or combo box, the ItemIndex value is the index of the selected item that has focus. If MultiSelect is True, ItemIndex defaults to 0.


Example

This example uses a drive combo box on a form. When the user selects a drive in the combo box, the index value of the selected item appears in the caption of the label:

procedure TForm1.DriveComboBox1Change(Sender: TObject);

begin

  Label1.Caption := 'Index value ' + IntToStr(DriveComboBox1.ItemIndex);

end;


See also

Items property


ItemRect method

See also	Example

Applies to

TDBListBox, TDirectoryListBox, TDrawGrid, TFileListBox, TListBox, TStringGrid, TTabSet components

Declaration

function ItemRect(Item: Integer): TRect;

Description

The ItemRect method returns the rectangle that surrounds the item specified in the Item parameter.


Example

This example uses a list box and four labels on a form. When the application runs, three strings are added to the list box. When the user selects one of the strings in the list box, the coordinates of the rectangle taken up by the selected string appear in the four labels:

procedure TForm1.FormCreate(Sender: TObject);

begin

  with ListBox1 do

  begin

    Items.Add('Hello');

    Items.Add('New');

    Items.Add('World');

  end;

end;

procedure TForm1.ListBox1Click(Sender: TObject);

var

  ListBoxItem: TRect;

begin

  ListBoxItem := ListBox1.ItemRect(ListBox1.ItemIndex);

  Label1.Caption := 'Left ' + IntToStr(ListBoxItem.Left);

  Label2.Caption := 'Top ' + IntToStr(ListBoxItem.Top);

  Label3.Caption := 'Right ' + IntToStr(ListBoxItem.Right);

  Label4.Caption := 'Bottom ' + IntToStr(ListBoxItem.Bottom);

end;


See also

TRect type


Items property

Applies to

TDBGridColumns, TFieldDefs, TIndexDefs, TParams objects;TComboBox, TDBComboBox, TDBListBox, TDBRadioGroup, TDirectoryListBox, TDriveComboBox, TFileListBox, TFilterComboBox, TListBox, TListView, TMainMenu, TMenuItem, TOutline, TPopupMenu, TRadioGroup, TTreeView components

Description

The Items property specifies the items of a component or object. It behaves differently depending on which object you are using it with.

Items Property for DBGrid Columns

Items Property for Field Definitions

Items Property for Index Definitions

Items Property for TParams Objects

Items Property for List Boxes, Combo Boxes, and Radio Group Boxes

Items Property for Menu Items

Items Property for Outlines

Items Property for Tree Views

Items Property for List Views

Items Property for List Objects

Items Property for List Columns

Items Property for Header Sections

Items Property for Status Panels

Items Property for Collection objects


Items property

Applies to

TIndexDefs object

Declaration

property Items[Index: Integer]: TIndexDef;

Description

Run-time only. Items holds the TIndexDef objects that describe each index of the dataset. The number of entries is given by the Count property; there will be one entry for each index of the dataset. Index is an integer identifying the index, in the range 0..Count - 1.


Items property

Example

Applies to

TParams object

Declaration

property Items[Index: Word]: TParam;

Description

Run-time only. The Items array property holds the parameters (TParam objects). Use this property when you want to work with the entire set. Index identifies the index in the range 0..Count - 1. While you can use Items to reference a particular parameter by its index, the ParamByName method is recommended to avoid depending on the order of the parameters.


Example

with Query1 do

  { Assign 99999 to any integer parameter which does not have a value }

  for I := 0 to Params.Count - 1 do

    if (Params.Items[I].IsNull) and (Params.Items[I].DataType = ftInteger) then

  { Items is the default property, so you can omit its name }

      Params[I].AsInteger := 99999;


Items property

See also

Applies to

TFieldDefs object

Declaration

property Items[Index: Integer]: TFieldDef;

Description

Items is an array of pointers to the TFieldDef objects that describe each field in the dataset. There is one pointer for each field in the dataset. Index is an integer identifying the index, in the range 0..Count - 1.


See also

Count property


Items property

Applies to

TDBGridColumns object

Declaration

property Items[Index: Integer]: TColumn;

Description

Run-time only. The Items array property holds the TColumn objects representing the columns in the TDBGrid component. Use this property if you want to manipulate the columns at run time. Index is an integer identifying the column, in the range 0..Count - 1.


Items property

See also	Example

Applies to

TTreeView component

Declaration

property Items: TTreeNodes;

Description

The Items property contains the individual items that appear in the tree view control. Individual nodes in a TTreeView are TTreeNode objects. These individual items can be accessed by using the Items property along with the item's index into the tree view. For example, to access the second item in the tree view, you could use the following code.

MyTreeNode := TreeView1.Items[1]

When setting this property at design-time in the Object Inspector the TreeView Items Editor appears. Use the New Item and New SubItem buttons to add items to the tree view. Use the Text property to modify what text is displayed in the label of the item.

At run-time items can be added and inserted by using the TTreeNodes methods AddChildFirst, AddChild, AddChildObjectFirst, AddChildObject, AddFirst, Add, AddObjectFirst, AddObject and Insert.


Example

The following example demonstrates how to add nodes andchild nodes to a TTreeView control.

procedure TForm1.Button1Click(Sender: TObject);

var

  MyTreeNode1, MyTreeNode2: TTreeNode;

begin

  with TreeView1.Items do

  begin

    {Adds a root node}

    Add(TreeView1.Selected, 'RootTreeNode1');

    {Sets MyTreeNode to first node in}

    {tree view and adds a child node to it}

    MyTreeNode1 := TreeView1.Items[0];

    AddChild(MyTreeNode1,'ChildNode1');

    {Adds a root node}

    Add(TreeView1.Selected, 'RootTreeNode2');

    {Sets MyTreeNode to third node in}

    {tree view and adds a child node to it}

    MyTreeNode2:=TreeView1.items[2];

    AddChild(MyTreeNode2,'ChildNode2');

    {Sets MyTreeNode to fourth node in}

    {tree view and adds a child node to it}

    MyTreeNode2:=TreeView1.items[3];

    AddChild(MyTreeNode2,'ChildNode2a');

    {Sets MyTreeNode to fifth node in}

    {tree view and adds a child node to it}

    MyTreeNode2:=TreeView1.items[4];

    Add(MyTreeNode2,'ChildNode2b');

    {add another root node}

    Add(TreeView1.Selected, 'RootTreeNode3');

  end;

end;


See also

AddChildFirst method

AddChild method

AddChildObjectFirst method

AddChildObject method

AddFirst method

Add method

AddObjectFirst method

AddObject method

BeginUpdate method

EndUpdate method

Clear method

GetFirstNode method

Insert method

InsertObject method

Delete method


Items property

See also	Example

Applies to

TListView component

Declaration

property Items: TListItems;

Description

The Items property contains the list of items in a TListView control. When setting this property at design-time a ListView Items Editor dialog appears. This dialog displays an indexed list of the items that is maintained by the TListItems object. The individual items in a list view are TListItem objects.

You can use this dialog to add or delete items or SubItems, and to edit their display properties. At run-time, use each item's Caption, ImageIndex and StateIndex properties to change the appearance of the list items.


Example

The following example changes the caption of the first item in the list view.

ListView1.Items[0].Caption := 'NewItemName';


See also

ImageIndex property

StateIndex property

Caption property

SubItems property


Items property for collection objects
Items property

See also

Applies to

TCollection object

Declaration

property Items[Index:Integer]:TCollectionItem;

Description

Run-time only. The Items property provides access to a collection item (TCollectionItem) by its position in the collection. The value of the Index parameter corresponds to the Index property and represents the position of the collection item in the Items array.


See also

Index property


Items property

See also	Example

Applies to

TStatusPanels object

Declaration

property Items[Index:Integer]:TStatusPanel;

Description

Run-time only. The Items property is an indexed array that provides access to a status panel (TStatusPanel) by its position on the status bar. The value of the Index parameter corresponds to the individual panel Index property and represents the position of the status panel in the Items array. To Add a panel to the status bar at design-time select the Panels property, which displays a StatusBar Panels Editor dialog. Choose Add from this dialog. The Index of Items is displayed in the dialog box, and the new panel is automatically added to it.


See also

Index property, Panels property, BeginUpdate method


Items property for header sections
Items property

See also

Applies to

THeaderSection object

Declaration

property Items[Index:Integer]:THeaderSection;

Description

Run-time only. The Items property provides access to a header section (THeaderSection) by its position on the header control. The value of the Index parameter corresponds to the Index property and represents the position of the header section in the Items array.


See also

Index property


Items property for list columns objects
Items property

See also	Example

Applies to

TListColumns object

Declaration

property Items[Index: Integer]: TListColumn;

Description

Run-time only. The Items property contains an array of the individual columns that appear in the list view control. Individual columns in a TListView are TListColumn objects. To access an individual column in a list view, use the item's index along with the Items property.

Example

The following example changes the caption of the second column in the list view.

ListView1.Items[1].Caption := 'New Caption'


See also

Add method


Items property

See also	Example

Applies to

TComboBox, TDBRadioGroup, TDirectoryListBox, TDriveComboBox, TFileListBox, TFilterComboBox, TListBox, TRadioGroup components

Declaration

property Items: TStrings;

Description

The Items property contains the strings that appear in the list box or combo box, or as radio buttons in a radio group box. Because Items is an object of type TStrings, you can add, delete, insert, and move items using the Add, Delete, Insert, Exchange, and Move methods of the TStrings object.

The ItemIndex property determines which item is selected, if any.

To determine if a particular item in the list of strings that makes up the Items property for a list box or combo box is selected, use the Selected property.


Example

This example uses an edit box, a list box, and a button on a form. When the user clicks the button, the text in the edit box is added to the list box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Add(Edit1.Text);

end;


See also

Add method

Delete method

Exchange method

Insert method

ItemIndex property

Move method

Selected property


Items Property for Menu Items
Items property

See also	Example

Applies to

TMainMenu, TMenuItem, TPopupMenu components

Declaration

property Items[Index: Integer]: TMenuItem;

Description

Read-only property.

For menu items, the Items array property provides access to a subitem of a menu item (TMenuItem) by its position in the list of subitems. The value of Index is the position of the subitem within the Items array. For example, if an application has a File drop-down menu that contains the menu items New, Open, and Save, in that order, FileMenu.Items[2] refers to the Save command. For menu items, Items is run-time only property.

For main menus, the Items property provides access to a menu item on the main menu bar, and is available at both design time and run time.

For pop-up menus, the Items property provides access to a menu item on the pop-up menu, and is available at both design time and run time.


Example

The following code disables all the subitems of MenuItem1.

var

  I: Integer;

begin

  for I := 0 to MenuItem1.ItemCount-1 do

    MenuItem1.Items[I].Enabled := False;

end;


See also

Count property


Items Property for Outlines
Items property

See also	Example

Applies to

TOutline component

Declaration

property Items[Index: Longint]: TOutlineNode;

Description

Run-time and read only. For outlines, the Items array property provides access to a outline node by its row position. The value of the Index parameter corresponds to the Index property and represents the position of the item within the Items array. For example, if an outline has three items with Index property values of 1, 2, and 3 and Text property values of 'Orange', 'Apple', and 'Banana', respectively, Items[2] refers to the 'Apple' item.


Example

The following code collapses the selected item of Outline1.

Outline1.Items[Outline1.SelectedItem].Expanded := False;


See also

SelectedItem property


Items Property for List Objects
Items property

See also	Example

Applies to

TList object

Declaration

property Items[Index: Integer]: Pointer;

Description

Run-time only. The Items array property lets you access a specific pointer kept in the List property of a list object. Using the Index parameter of Items you can access a list item by its position in the list.


Example

This example creates a list object and inserts two records into it. The value of the record fields are written on the form:

procedure TForm1.FormActivate(Sender: TObject);

type

  PMyList = ^AList;

  AList = record

    I: Integer;

    C: Char;

  end;

var

  MyList: TList;

  ARecord: PMyList;

  B: Byte;

  Y: Word;

begin

  MyList := TList.Create;

  New(ARecord);

  ARecord^.I := 100;

  ARecord^.C := 'Z';

  MyList.Add(ARecord);         {Add integer 100 and character Z to list}

  New(ARecord);

  ARecord^.I := 200;

  ARecord^.C := 'X';

  MyList.Add(ARecord);         {Add integer 200 and character X to list}

  Y := 10;                     {Variable used in TextOut function}

{Go through the list until the end is reached}

  for B := 0 to (MyList.Count - 1) do

  begin

    Y := Y + 30;               {Increment Y Value}

    ARecord := MyList.Items[B];

    Canvas.TextOut(10, Y, IntToStr(ARecord^.I)); {Display I}

    Y := Y + 30;                {Increment Y Value again}

    Canvas.TextOut(10, Y, ARecord^.C);  {Display C}

  end;

  MyList.Free;

end;


See also

Add method

Expand method

First method

IndexOf method

Last method

Remove method


ItemSeparator property

See also	Example

Applies to

TOutline component

Declaration

property ItemSeparator: string;

Description

The ItemSeparator property determines the separator string used between the outline item Text values in the FullPath property of the TOutlineNode object. The default value of ItemSeparator is '\'.

For example, if the top-level outline item has a Text value of 'Animals' and a child item with the Text value of 'Dogs', the FullPath property of the 'Dogs' item would have the value 'Animals\Dogs' by default. If the string '->' were assigned to the ItemSeparator property, the FullPath property of the 'Dogs' item would be 'Animals->Dogs'.


Example

The following code changes the item separator to ':'.

Outline1.ItemSeparator := ':';


See also

FullPath property

Text property

TOutlineNode object


KeepConnection property

Example

Applies to

TDataBase component

Declaration

property KeepConnection: Boolean;

Description

The KeepConnection property specifies whether an application remains connected to a database server even when no tables are open. If an application needs to open and close several tables in a single database, it will be more efficient to set KeepConnection to True. That way, the application will remain connected to the database even when it does not have any tables open. It can then open and close tables repeatedly without incurring the overhead of connecting to the database each time. If KeepConnection is False, the database must repeat the login process to the server each time the Connected property is set to True.

The TSession component has an application-wide KeepConnections property that determines the initial state of the KeepConnection property for temporary (automatically-created) TDatabase components.


Example

Database1.KeepConnection := False;


KeepConnections property

See also	Example

Applies to

TSession component

Declaration

property KeepConnections: Boolean;

Description

KeepConnections specifies whether temporary TDatabase components will maintain database connections even if no tables in the database are open. Databases that have an explicit TDatabase component will use TDatabase's KeepConnection property instead to determine if connections are persistent.

If KeepConnections is True (the default), the application will maintain database connections until the application exits or calls the DropConnections method. If KeepConnections is False, then the application will disconnect from the database when all datasets connected to tables in the database are closed.


Example

Session.KeepConnections := False;


See also

Session variable


KeyExclusive property

See also	Example

Applies to

TTable component

Declaration

property KeyExclusive: Boolean;

Description

The KeyExclusive property indicates whether range and search functions will exclude the matching records specified by the functions. KeyExclusive is False by default.

For the SetRangeStart and SetRangeEnd methods, KeyExclusive determines whether the filtered range excludes the range boundaries. The default is False, which means rows will be in the filtered range if they are greater than or equal to the start range specified and less than or equal to the end range specified. If KeyExclusive is True, the methods will filter strictly greater than and less than the specified values.

For the GotoNearest and FindNearest methods, KeyExclusive indicates whether a search will position the cursor on or after the record being searched for. If KeyExclusive is False, then GoToNearest and FindNearest will move the cursor to the record that matches the specified values, if found. If True, then the methods will go the record immediately following the matching record, if found.


Example

{ Limit the range from 1351 to 1356, excluding both 1351 and 1356 }

with Table1 do

  begin

{ Set the beginning key }

  EditRangeStart;

  IndexFields[0].AsString := '1351';

{ Exclude 1351 itself }

  KeyExclusive := True;

{ Set the ending key }

  EditRangeEnd;

  IndexFields[0].AsString := '1356';

{ Exclude 1356 itself }

  KeyExclusive := True;

{ Tell the dataset to establish the range }

  ApplyRange;

  end;


See also

ApplyRange method

EditRangeStart method

EditRangeEnd method

KeyFieldCount property


KeyFieldCount property

See also

Applies to

TTable component

Declaration

property KeyFieldCount: Integer;

Description

KeyFieldCount specifies the number of key fields to use with search functions (GotoKey, FindKey, EditKey, and so on) if you don't want to search on all the fields in the key.


See also

GotoKey method

GotoNearest method

EditKey method

FindKey method

FindNearest method

SetKey method


KeyField property

See also

Applies to

TDBLookupComboBox, TDBLookupListBox components

Declaration

property KeyField: string;

Description

The KeyField property identifies the field in the ListSource data set to match up with the DataField field. As you select items in the data control, the DataField field gets the value of the KeyField field corresponding to the selected item. If the DataField field is a lookup field, you don't need to specify anything for KeyField; the data controls automatically use the lookup field's LookupKeyFields field for KeyField.


See also

KeyValue property

ListField property

ListSource property


KeyFields property

See also

Applies to

All field components

Declaration

property KeyFields: string;

Description

The KeyFields property identifies the field or fields in the field's dataset to match in the lookup dataset when doing a lookup. If you want to use more than one field, separate each field name with a semicolon. The fields you specify in KeyFields must be of the same types as the corresponding fields in LookupKeyFields, or the lookup can't work.

The field whose KeyFields property you're setting must be a lookup field (FieldKind = fkLookup or Lookup = True). When you set the lookup properties, TField automatically looks up the LookupResultField value from the record in the LookupDataSet whose LookupKeyFields values match the values of KeyFields in the field's own dataset.


See also

LookupDataSet property

LookupKeyFields property

LookupResultField property


KeyPreview property

Example

Applies to

TForm component

Declaration

property KeyPreview: Boolean;

Description

When the KeyPreview property is True, most key events (OnKeyDown event, OnKeyUp event, and OnKeyPress event) go to the form first, regardless of which control is selected on the form. This allows your application to determine how to process key events. After going to the form, key events are then passed to the control selected on the form. When KeyPreview is False, the key events go directly to the controls. The default value is False.

The exceptions are the navigation keys, such as Tab, BackTab, the arrow keys, and so on. If the selected control processes such keys, you can use KeyPreview to intercept them; otherwise, you can't.

If KeyPreview is False, all key events go to the selected control.


Example

This example changes a form's color to aqua when the user presses a key, even when a control on the form has the focus. When the user releases the key, the form returns to its original color.

var

  FormColor: TColor;

procedure TForm1.FormCreate(Sender: TObject);

begin

  KeyPreview := True;

end;

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word;

  Shift: TShiftState);

begin

  FormColor := Form1.Color;

  Form1.Color := clAqua;

end;

procedure TForm1.FormKeyUp(Sender: TObject; var Key: Word;

  Shift: TShiftState);

begin

  Form1.Color := FormColor;

end;


KeySize property

Applies to

TQuery, TStoredProc, TTable components

Declaration

property KeySize: Word;

Description

Run-time and read-only. KeySize specifies the length of a key in bytes in the current index. It's useful if you need to make calls to the Borland Database Engine API; if you use VCL objects and components to handle data access, you don't need to worry about using KeySize.


KeyValue property

Applies to

TDBLookupComboBox, TDBLookupListBox components

Declaration

property KeyValue: Variant;

Description

Run-time only. The KeyValue property reflects the value of the KeyField field. If you set this property, the data controls attempt to find a matching record from the ListSource's data set and display it.


KeyViolCount property

Example

Applies to

TBatchMove component

Declaration

property KeyViolCount: Longint;

Description

Run-time and read only. KeyViolCount reports the number of records which could not be replaced, added, or deleted from Destination because of an integrity (key) violations. If AbortOnKeyViol is True, KeyViolCount will never be greater than one, since the first violation will cause the move to terminate.


Example

with BatchMove1 do

  begin

    Execute;

    if KeyViolCount <> 0 then { something went wrong };

  end;


KeyViolTableName property

See also	Example

Applies to

TBatchMove component

Declaration

property KeyViolTableName: TFileName;

Description

KeyViolTableName, if specified, creates a local (Paradox) table containing all records from the source table that caused an integrity violation (such as a key violation) as a result of the batch operation.

If AbortOnKeyViol is True, then there will be at most one record in this table since the operation will be aborted with that first record. KeyViolCount will have the number of records placed in the new table.


Example

BatchMove1.KeyViolTableName := 'KeyViol';


See also

Destination property


Kind property

Applies to

TBitBtn, TScrollBar, TControlScrollBar components

Description

The Kind property specifies the style or type of component.

Kind property for Bitmap Buttons

Kind Property for Scroll Bars


Kind Property for Bitmap Buttons
Kind property

See also	Example

Applies to

TBitBtn component

Declaration

property Kind: TBitBtnKind;

Description

The Kind property determines the kind of bitmap button. These are the possible values and their meanings:

Value	Meaning

bkCustom	You indicate which bitmap you want the bitmap button to have by setting the value of the Glyph property to the bitmap of your choice. Like push buttons, you can either select a ModalResult for the button, or you can supply the code to respond to an OnClick event.

bkOK	A green check mark and the text "OK" appear on the button face. The button becomes the default button (the Default property is automatically set to True). When the user chooses the button, the dialog box closes. The resulting ModalResult value of the bitmap button is mrOK.

bkCancel	A red X and the text "Cancel" appear on the button face. The button becomes the Cancel button (the Cancel property is automatically set to True). When the user chooses the button, the dialog box closes. The resulting ModalResult value of the bitmap button is mrCancel.

bkYes	A green check mark and the text "Yes" appear on the button face. The button becomes the default button (the Default property is automatically set to True). When the user chooses the button, any changes the user made in the dialog box are accepted and the dialog box closes. The resulting ModalResult value of the bitmap button is mrYes.

bkNo	A red no symbol and the text "No" appear on the button face. The button becomes the Cancel button (the Cancel property is automatically set to True). When the user chooses the button, any changes the user made in the dialog box are canceled and the dialog box closes. The resulting ModalResult value of the bitmap button is mrNo.

bkHelp	A cyan question mark and the text "Help" appear on the button face. When the user chooses the button, a Help screen in the application's Help file appears. The Help file that appears is the file specified as the value of the application's HelpFile property. The value of the HelpContext property of the button specifies which Help screen in the Help file appears.

bkClose	A door with a green exit sign over it (use your imagination) and the text "Close" appear on the button face. When the user chooses the button, the form closes. The Default property of the button is True.

bkAbort	A red X and the text "Abort" appear on the button face.

bkRetry	A green circular arrow and the text "Retry" appear on the button face.

bkIgnore	A green man walking away and the text "Ignore" appear on the button face. Use it to allow the user to continue after an error has occurred.

bkAll	A double green check mark and the text "Yes to All" appear on the button face.


Example

This example uses three bitmap buttons on a form. When the application runs, the Kind property for each bitmap button is set, and the BitBtn1 button (the OK button) becomes the default button.

procedure TForm1.FormCreate(Sender: TObject);

begin

  BitBtn1.Kind := bkOK;

  BitBtn2.Kind := bkCancel;

  BitBtn3.Kind := bkHelp;

end;


See also

Cancel property

Default property

ModalResult property


Kind Property for Scroll Bars
Kind property

Example

Applies to

TScrollBar, TControlScrollBar components

Declaration

property Kind: TScrollBarKind;

Description

The Kind property determines if a scroll bar is horizontal or vertical. These are the possible values:

Value	Meaning

sbHorizontal	Scroll bar is horizontal

sbVertical	Scroll bar is vertical

For scroll bars of type TControlScrollBar (form and scroll box scroll bars accessed through the HorzScrollBar and VertScrollBar properties), Kind is a read- and run-time- only property.


Example

This example uses a radio group box and a scroll bar on a form. When the user selects one of the radio buttons, the scroll bar changes orientation accordingly.

procedure TForm1.FormCreate(Sender: TObject);

begin

  RadioGroup1.Items.Add('Vertical');

  RadioGroup1.Items.Add('Horizontal');

  RadioGroup1.ItemIndex := 2;

end;

procedure TForm1.RadioGroup1Click(Sender: TObject);

begin

  if RadioGroup1.Items[RadioGroup1.ItemIndex] = 'Vertical' then

    ScrollBar1.Kind := sbVertical;

  if RadioGroup1.Items[RadioGroup1.ItemIndex] = 'Horizontal' then

    ScrollBar1.Kind := sbHorizontal;

end;


LargeChange property

See also	Example

Applies to

TScrollBar component

Declaration

property LargeChange: TScrollBarInc;

Description

The LargeChange property determines how far the scroll box moves when the user clicks the scroll bar on either side of the scroll box or presses PgUp or PgDn. The default value is 1 position.

For example, if the LargeChange property setting is 1000, each time the user clicks the scroll bar, the scroll box moves 1000 positions. How big the change from one position to another depends on the difference between the Max property value and the Min property value. If Max is 3000 and Min is 0, the user needs to click the scroll bar three times to move the scroll box from one end of the scroll bar to the other.


Example

This code determines that when the user clicks the scroll bar on either side of the scroll box, the scroll box moves 100 positions on the scroll bar:

ScrollBar1.LargeChange := 100;


See also

Max property

Min property

Position property

SmallChange property


LargeImages property

See also	Example

Applies to

TListView component

Declaration

property LargeImages: TImageList;

Description

The LargeImages property for a list view determines which image list (TImageList) is used by the list view when the list view has a ViewStyle property of vsIcon. An image list contains a list of bitmaps that can be displayed next to the item's label.


Example

The following example sets the list view's LargeImages property to ImageList1.

ListView1.LargeImages := ImageList1;


See also

TImageList object

SmallImages property

ImageIndex property

StateIndex property

IconOptions property

ViewStyle property


Last method

Applies to

TList object; TQuery, TStoredProc, TTable components

Description

Last Method for List Objects

Last Method for Queries, Tables, and Stored Procedures


Last method

See also	Example

Applies to

TList object

Declaration

function Last: Pointer;

Description

The Last method returns a pointer that points to the last item referenced in the List property of a list object.


Example

This example inserts two records into a list object and displays the contents of the last record in the list on the form:

procedure TForm1.FormActivate(Sender: TObject);

type

  PMyList = ^AList;

  AList = record

    I: Integer;

    C: Char;

end;

var

  MyList: TList;

  ARecord: PMyList;

begin

  MyList := TList.Create;

  New(ARecord);

  ARecord^.I := 100;

  ARecord^.C := 'Z';

  MyList.Add(ARecord); {Add integer 100 and character Z to list}

  New(ARecord);

  ARecord^.I := 200;

  ARecord^.C := 'X';

  MyList.Add(ARecord); {Add integer 200 and character X to list}

  ARecord := MyList.Last;

  Canvas.TextOut(10, 10, IntToStr(ARecord^.I)); {Display I}

  Canvas.TextOut(10, 40, ARecord^.C);  {Display C}

  MyList.Free;

end;


See also

Capacity property

First method

IndexOf method

Items property


Last method

See also	Example

Applies to

TQuery, TStoredProc, TTable components

Declaration

procedure Last;

Description

The Last method moves the cursor to the last record in the active range of records of the dataset. The active range of records is affected by the filter established with SetRangeEnd.

If the dataset is in Insert or Edit state, Last will perform an implicit Post of any pending data.


Example

Table1.Last;


See also

First method

MoveBy method

Next method

Prior method

SetRangeEnd method


Layout property

See also	Example

Applies to

TBitBtn, TSpeedButton components

Declaration

property Layout: TButtonLayout;

Description

The Layout property determines where the image appears on the bitmap button or a speed button. These are the possible values.:

Value	Meaning

blGlyphLeft	The image appears near the left side of the button.

blGlyphRight	The image appears near the right side of the button.

blGlyphTop	The image appears near the top of the button.

blGlyphBottom	The image appears near the bottom of the button.


Example

This example uses a bitmap button on a form that has a bitmap specified as the value of its Glyph property. When the user clicks the bitmap button, the bitmap randomly changes its position on the button:

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  case Random(4) of

    0: BitBtn1.Layout := blGlyphLeft;

    1: BitBtn1.Layout := blGlyphRight;

    2: BitBtn1.Layout := blGlyphTop;

    3: BitBtn1.Layout := blGlyphBottom;

  end;

end;


See also

Margin property

Spacing property


Left property

See also	Example

Applies to

All controls; TFindDialog, TReplaceDialog components

Declaration

property Left: Integer;

Description

The Left property determines the horizontal coordinate of the left edge of a component relative to the form in pixels. If the control is contained in a TPanel, the Left and Top properties will be relative to the panel. If the control is contained directly by the form, it will be relative to the form. For forms, the value of the Left property is relative to the screen in pixels.

The Left property for the Find and Replace dialog boxes is available at run time only.


Example

The following example moves the button 10 pixels to the right each time a user clicks it:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Left := Button1.Left + 10;

end;


See also

SetBounds method

Top property


LeftCol property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property LeftCol: Longint;

Description

Run-time only. The LeftCol property determines which column in the grid appears at the far left side of the grid.

If you have one or more nonscrolling columns in the grid, they remain at the far left, regardless of the value of the LeftCol property. In this case, the column you specify as the far left column is the first column to the immediate right of the nonscrolling columns.


Example

This line of code positions the fourth column of a string grid at the left edge of the grid:

StringGrid1.LeftCol := 3;


See also

FixedCols property

TopRow property


LeftIndent property

See also

Applies to

TParaAttributes object

Declaration

property LeftIndent: Longint;

Description

The LeftIndent property contains the size in pixels of the left indentation relative to the left margin in the currently selected paragraph in a TRichEdit control.


See also

FirstIndent property

Paragraph property

RightIndent property


Length property

See also	Example

Applies to

TMediaPlayer component

Declaration

property Length: Longint;

Description

Run-time and read-only. The Length property specifies the length of the medium in the open multimedia device. Length is specified using the current time format, which is specified by the TimeFormat property.


Example

The following code sets Wait to False if the Length of the media is over 10,000. If TimeFormat is tfMilliseconds, Wait is set to False if the media is over 10 seconds long.

MediaPlayer1.Wait := (MediaPlayer1.Lenth > 10000);


See also

Position property

Start property

TrackLength property


Level property

Applies to

TOutlineNode, TTreeNode objects

Description

Level property for Outlines

Level property for Tree Node objects


Level property

See also	Example

Applies to

TOutlineNode object

Declaration

property Level: Word;

Description

Run-time and read-only. The Level property indicates the level of indentation of an item within the TOutline component. The value of Level is 1 for items on the top level. The value of Level is 2 for their children, and so on.


Example

The following code tests to determine if the fifth outline item is on the same level as the selected outline item.

if Outline1.Items[5].Level = Outline1.Items[Outline1.SelectedItem].Level then

  { The selected item is on the same level as the fifth item };


See also

ChangeLevelBy method

TopItem property


Level property for tree node objects
Level property

See also	Example

Applies to

TTreeNode object

Declaration

property Level: Integer;

Description

Run-time and read-only. The Level property indicates the level of indentation of an item within the tree view control. The value of Level is 0 for items on the top level. The value of Level is 1 for their children, and so on.


Example

The following example prints the level of the selected item to ListBox1.

ListBox1.Items.Add('Level: ' + IntToStr(TreeView1.Selected.Level));


See also

HasChildren property

HasAsParent method

GetFirstChild method

Index property


Lines property

Applies to

TDBMemo, TDDEClientItem, TDDEServerItem, TMemo, TOutline, TRichEdit components

Description

The Lines property specifies the lines of text that appear in a component.

Lines property for memos and TRichEdit components

Lines property for outlines

Lines property for DDE Items


Lines property

See also	Example

Applies to

TDBMemo, TMemo, TRichEdit components

Declaration

property Lines: TStrings;

Description

The Lines property contains the text lines in a memo or rich edit component.

For a database memo control, the Lines property is a run-time property only.


Example

This example uses a button and a memo control on a form. When the user clicks the button, the contents of the system's AUTOEXEC.BAT file is loaded into the memo, and the sixth line of the file is written across the top of the form.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Memo1.Lines.LoadFromFile('C:\AUTOEXEC.BAT');

  Writeln('The 6th line of AUTOEXEC.BAT is: ', Memo1.Lines[5]);

end;


See also

GetTextBuf method

SetTextBuf method

Text property


Lines property

Example

Applies to

TOutline component

Declaration

property Lines: TStrings;

Description

The Lines property contains the Text property values of the individual items in an outline.

If the Lines property is of an outline component, each line becomes an outline item in a TOutlineNode object. Leading tabs and spaces are converted into levels of the outline. Text without any leading tabs or spaces become level 1 items. For example, to create a level 2 item, lead the text of the item with one tab or space.

The Lines property of outlines is primarily useful for stuffing an outline with items at design time. While you can access the individual items with the Lines property at run time, it is much quicker to access an item with the Items property.


Example

The following two lines of code each produce the same result. In the first line, Lines is used to access the Strings value of the third outline node. In the second line, Items is used to access the Text value of the third outline node. Note that the index used with Items is one more than the index used with Lines.Strings.

Edit1.text := Outline1.Lines.Strings[2];

Edit2.Text := Outline1.Items[3].Text;


Lines property

Example

Applies to

TDDEClientItem, TDDEServerItem components

Declaration

property Lines: TStrings;

Description

The Lines property contains the text data to exchange in a DDE conversation. For TDDEClientItem components, Lines specifies the text that is updated by the DDE server application. For TDDEServerItem components, Lines specifies the text that is sent to any DDE clients when the value of Lines changes or when a client requests to be updated. When Lines is changed, an OnChange event occurs.

Lines corresponds to the Text property. Whenever the value of Lines or Text is changed, the other is updated so that the first line of Lines is always equal to Text.

If the Lines property is of a TDDEClientItem component, you can also send the text in Lines directly to the DDE server by poking data with the PokeDataLines method.

If the Lines property is of a TDDEServerItem component, the DDE client can change Lines by poking data. The poked data replaces the contents of Lines and an OnChange event occurs.


Example

The following code assigns the value to the Lines property of DDEClientItem1 to the Lines of Memo1. This code is executed in the OnChange event handler of DDEClientItem1, so whenever the client is updated, the new data from the server is displayed.

procedure TForm1.DdeClientItem1Change(Sender: TObject);

begin

  Memo1.Lines := DDEClientItem1.Lines

end;


LineSize property

See also

Applies to

TTrackBar component

Declaration

property LineSize: Integer;

Description

The LineSize property determines the number of ticks moved using the arrow keys. The current Position is marked by a slider. The right and down arrow keys increment the value of Position, and the left and up arrow keys decrement the value of Position. Use the PageSize property to set the number of ticks moved using the PgUp and PgDn keys.


See also

Max property

Min property

PageSize property

Position property

TickStyle property


LineTo method

See also	Example

Applies to

TCanvas object

Declaration

procedure LineTo(X, Y: Integer);

Description

The LineTo method draws a line on the canvas from the current drawing position (specified by the PenPos property) to the point specified by X and Y and sets the pen position to (X, Y).


Example

The following code draws a line from the upper left corner of a form to the point clicked with the mouse.

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Canvas.MoveTo(0, 0);

  Canvas.LineTo(X, Y);

end;


See also

MoveTo method


List property

Applies to

TList, TSessionList objects

Description

The List property stores a list of pointers that reference objects of any type.

List property for TList Objects

List property for Sessions


List property

See also	Example

Applies to

TList object

Declaration

property List: PPointerList;

Description

Run-time and read-only. The List property stores a list of pointers that reference objects of any type. The declaration of PPointerList is

PPointerList = ^TPointerList;

The declaration of TPointerList is

TPointerList = array[0..MaxListSize-1] of Pointer;

The elements of the TPointerList array each point to an item of the list.


Example

The following code creates List1 and Object1, then adds Object1 to List1. If the first item in the List property List1 differs from the first item of the Items property of List1 (which shouldn't happen), a message is displayed.

var

  List1: TList;

  Object1: TObject;

begin

  List1 := TList.Create;

  try

    Object1 := TObject.Create;

    try

       List1.Add(Object1);

      if List1.List^[0]<>List1.Items[0] then

         MessageDlg('Something is wrong here', mtInformation, [mbOK], 0);

    finally

      Object1.Free;

    end;

  finally

    List1.Free;

  end;

end;


See also

FileEditStyle property

TStrings object

TSessionList object


List property

See also

Applies to

TSessionList object

Declaration

property List[const SessionName: string]: TSession;

Description

The List array property returns the TSession component with the given name (SessionName property). If no such session exists, List raises an EDatabaseError exception with a message specifying the invalid session name. If you don't want an exception to be raised when a session can't be found, use the FindSession method instead.


See also

Sessions variable


ListField property

See also

Applies to

TDBLookupComboBox, TDBLookupListBox components

Declaration

property ListField: string;

Description

The ListField property identifies the field or fields ( separated by semicolons) whose values are displayed in the data controls. If you don't set ListField, the data controls display KeyField field values by default. If the DataField field is a lookup field, you don't need to specify anything for ListField; the data controls automatically use the lookup field's LookupResultField property as ListField.


See also

KeyField property

KeyValue property

ListSource property

ListfieldIndex property


ListSource property

See also

Applies to

TDBLookupComboBox, TDBLookupListBox components

Declaration

property ListSource: TDataSource;

Description

The ListSource property identifies a data source for the data displayed in the data controls. If the DataField field is a lookup field, you don't need to specify anything for ListSource; the data controls automatically use the lookup field's LookupDataSet property to create a data source.


See also

KeyField property

KeyValue property

ListField property


ListView property

See also

Applies to

TListItem object

Declaration

property ListView: TCustomListView;

Description

Run-time and read-only. The ListView property for a list item specifies the list view that is the owner of the item.


See also

Owner property

Parent property


LoadFromClipboardFormat method

Applies to

TPicture object

Declaration

procedure LoadFromClipboardFormat(AFormat: Word; AData: THandle; APalette: HPALETTE);

Description

The LoadFromClipboardFormat method reads the picture from the handle provided in the given Clipboard format.  If the format is not supported, an exception is generated.


LoadFromFile method

Applies to

TBitmap, TGraphic, TIcon, TMetafile, TPicture, TStringList, TStrings objects; TBlobField, TGraphicField, TMemoField, TOutline, TTreeView, TOleContainer components

Description

LoadFromFile Method for Fields

LoadFromFile Method for OLEContainers

LoadFromFile for Other Objects and Components


LoadFromFile method

Example

Applies to

TBlobField, TGraphicField, TMemoField components

Declaration

procedure LoadFromFile(const FileName: string);

Description

The LoadFromFile method reads a file with the name passed in FileName and loads the contents in TBlobField, TMemoField, or TGraphicField.

Note:	For TMemoField and TGraphicField, the file should have been created by the SaveToFile or SaveToStream method.


Example

The following code loads a blob field with the contents of autoexec.bat:

BlobField1.LoadFromFile('c:\autoexec.bat');


LoadFromFile method

See also	Example

Declaration

procedure LoadFromFile(const FileName: string);

Description

The LoadFromFile method reads the file specified in FileName and loads the data into the object or component. The graphics objects load graphics, and the outline, string and tree view objects load text.


Example

This example uses a bitmap button on a form. When the application runs and the form is created, a bitmap is placed on the bitmap button:

procedure TForm1.FormCreate(Sender: TObject);

begin

  BitBtn1.Glyph.LoadFromFile('TARTAN.BMP');

end;


See also

SaveToFile method

Strings property


LoadFromFile method

See also

Applies to

TOleContainer component

Declaration

procedure LoadFromFile(const FileName: string);

Description

Loads an OLE object from the specified file. If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded. If OldStreamFormat is False, LoadFromFile only loads files saved with Delphi 2.0's TOleContainer component; if OldStreamFormat is True, LoadFromFile loads files saved with Delphi 1.0's TOLEContainer component as well as Delphi 2.0's TOleContainer.


See also

OldStreamFormat property


LoadFromResourceID method

Applies to

TBitMap object

Declaration

procedure LoadFromResourceID(Instance: THandle; ResID: Integer);

Description

The LoadFromResourceName method loads the specified bitmap resource along with palette information from a module's executable file given the resource ID specified by ResID.


LoadFromResourceName method

Applies to

TBitMap object

Declaration

procedure LoadFromResourceName(Instance: THandle; const ResName: String);

Description

The LoadFromResourceName method loads the specified bitmap resource along with palette information from a module's executable file given the resource name specified by ResName.


LoadFromStream method

Applies to

TBlobField, TGraphicField, TMemoField, TOutLine components; TStrings, TStringList, TMetaFile, TIcon, TBitMap objects

LoadFromStream method for OleContainers

LoadFromStream method for other objects


LoadFromStream method

See also	Example

Applies to

TBlobField, TGraphicField, TMemoField, TOutLine components; TStrings, TStringList, TMetaFile, TIcon, TBitMap objects

Declaration

procedure LoadFromStream(Stream: TStream);

Description

The LoadFromStream method reads Stream and stores the contents in the object.

Note:	For a TMemoField or TGraphicField, the file should have been created by the SaveToFile or SaveToStream method.


Example

The following code loads a blob field from an existing stream1:

BlobField1.LoadFromStream(Stream1);


See also

LoadFromFile method

SaveToStream method

SaveToFile method


LoadFromStream method

See also

Applies to

TOleContainer component

Declaration

procedure LoadFromStream(Stream: TStream);

Description

Loads an OLE object from the specified stream. If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded. If OldStreamFormat is False, LoadFromStream only loads files saved with Delphi 2.0's TOLEContainer component; if OldStreamFormat is True, LoadFromStream loads files saved with Delphi 1.0's TOLEContainer component as well as Delphi 2.0's TOleContainer.


See also

OldStreamFormat property


LoadMemo method

See also	Example

Applies to

TDBMemo component

Declaration

procedure LoadMemo;

Description

The LoadMemo method loads a text BLOB into the database memo control. If the value of the AutoDisplay property is False, the text of a memo is not automatically loaded. If AutoDisplay is False, you can control when the text is loaded at run time by calling LoadMemo when you want the text to appear in the control.


Example

This example uses a database memo that is connected to a BLOB text field in the dataset. It also contains a button. When the user clicks the button, the BLOB loads into the memo.

procedure TForm1.FormCreate(Sender: TObject);

begin

  DBMemo1.AutoDisplay := False;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  DBMemo1.LoadMemo;

end;


See also

LoadPicture method


LoadPicture method

See also	Example

Applies to

TDBImage component

Declaration

procedure LoadPicture;

Description

The LoadPicture method loads the image specified as the value of the Picture property into the database image control.

If the value of the AutoDisplay property is False, the image of a database image control is not automatically loaded. If AutoDisplay is False, you can control when the image is loaded at run time by calling LoadPicture when you want the image to appear in the control.


Example

The following code loads the picture into DBImage1.

DBImage1.LoadPicture;


See also

LoadMemo method


Local property

Example

Applies to

TQuery component

Declaration

property Local: Boolean;

Description

Run-time and read-only. The Local property specifies if the table referenced by the TQuery is a local dBASE or Paradox table or an SQL server table. If Local is True, then the table is a dBASE or Paradox table. If Local is False, the table is a SQL table.

For remote SQL tables, some operations (such as record counts) may take longer than for local tables, owing to network constraints.


Example

{ If the table is local, allow the data-aware controls to display the changes }

DataSource1.Enabled := Query1.Local;


Locale property

Applies to

TDataBase, TTable, TQuery, TSession, TStoredProc components

Description

Locale for Database Components

Locale for Queries, Tables, and Stored Procedures

Locale for Sessions


Locale property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property Locale: TLocale;

Description

Run-time and read-only. The Locale property identifies the language driver used with the dataset for use with direct calls to the Borland Database Engine API.

Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Locale property

See also

Applies to

TSession component

Declaration

property Locale: TLocale;

Description

Run-time and read-only. The Locale property identifies the language driver used with the TSession component. It enables you to reference the language driver when making direct calls to the Borland Database Engine API. Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


See also

Session variable


Locale property

Applies to

TDataBase components

Declaration

property Locale: TLocale;

Description

Run-time and read-only. The Locale property identifies the language driver used with the TDatabase component. It allows you to make direct calls to the Borland Database Engine API. Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Locate method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

function Locate(const KeyFields: string; const KeyValues: Variant;
     Options: TLocateOptions): Boolean;

Description

The Locate method locates and moves to the first record matching the supplied search criteria. KeyFields lists the field or fields you want to search; to search more than one, separate each field name with a semicolon. KeyValues is a variant specifying the field value to match, or an array of field values, if KeyFields lists more than one field. Options lets you specify case-insensitive or partial-key matching.

Locate uses the fastest possible method to locate a matching record; if the dataset has an index on the specified fields that's compatible with case-insensitive matching (if you specify that in Options), the index will be used. Otherwise, Locate sets up a Borland Database Engine filter for efficient searching.

Locate returns True if a matching record could be found or False if no matches were found.


Example

The following code moves the cursor to the first row in the CustTable where the value in the Company column is "Professional Divers, Ltd.":

var

  LocateSuccess: Boolean;

  SearchOptions: TLocateOptions;

begin

  SearchOptions := [loPartialKey];

  LocateSuccess := CustTable.Locate('Company', 'Professional Divers, Ltd.',
    SearchOptions);

end;

If Locate finds a match, the first record containing the match becomes the current record. Locate returns True if it finds a matching record, False if it does not. If a search fails, the current record does not change.


See also

GotoKey method

FindKey method

Lookup method


LoginDialog function

See also

Unit

DBLogDlg

Declaration

function LoginDialog(const ADatabaseName: string; var AUserName, APassword: string): Boolean;

Description

The LoginDialog function is used to display a modal login dialog box and retrieve values entered by the user at run time. This function can be used to provide user-created security for local tables.

ADatabaseName should be assigned in advanced. Its value is displayed next to the Database label in the dialog box. AUserName contain the name entered by the user when LoginDialog returns. Optionally, AUserName can be assigned prior to the call to LoginDialog. If so, the preassigned name is displayed in the dialog box when it opens. The APassword parameter contains the password entered by the user when LoginDialog returns. APassword should not be assigned prior to calling LoginDialog.

LoginDialog returns True if the dialog box is closed using the OK button, False otherwise.


See also

LoginDialogEx function


LoginDialogEx function

See also

Unit

DBLogDlg

Declaration

function LoginDialogEx(const ADatabaseName: string; var AUserName, APassword: string; NameReadOnly: Boolean): Boolean;

Description

The LoginDialogEx function is used to display a modal login dialog box and retrieve values entered by the user at run time. This function can be used to provide user-created security for local tables.

ADatabaseName should be assigned in advanced. Its value is displayed next to the Database label in the dialog box. AUserName should be assigned prior to the call to LoginDialog. If so, the preassigned name is displayed in the dialog box when it opens. If NameReadOnly is True, then the user cannot change the name displayed in the UserName edit box in the dialog. The APassword parameter contains the password entered by the user when LoginDialog returns. APassword should not be assigned prior to calling LoginDialog.

LoginDialog returns True if the dialog box is closed using the OK button, False otherwise.


See also

LoginDialog function


LoginPrompt property

See also	Example

Applies to

TDataBase component

Declaration

property LoginPrompt: Boolean;

Description

The LoginPrompt property is used to control how security is handled for SQL databases.

If True, (the default), the standard Delphi Login dialog box will be opened when the application attempts to establish a database connection. The user must then enter a proper user name and password to connect to a database on the server.

If False, then an application will look for login parameters in the Params property of the TDatabase component. These are the USERNAME and PASSWORD parameters. For example,

USERNAME = SYSDBA

PASSWORD = masterkey

This is generally not recommended since it compromises server security.


Example

The following example prohibits display of the login prompt:

Database1.LoginPrompt := False;


See also

OnLogin event


Lookup method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function Lookup(const KeyFields: string; const KeyValues: Variant;
     const ResultFields: string): Variant;

Description

The Lookup method locates and moves to the first record matching the supplied search criteria. KeyFields lists the field or fields you want to search; to search more than one, separate each field name with a semicolon. KeyValues is a variant specifying the field value to match, or an array of field values, if KeyFields lists more than one field.

Lookup uses the fastest possible method to locate a matching record; if the dataset has an index on the specified fields, the index will be used. Otherwise, Lookup sets up a Borland Database Engine filter for efficient searching.

If a matching record couldn't be found, Lookup returns Null. If one could be found, Lookup performs the lookup operations you set up in the lookup fields defined for the dataset (if any). It then extracts the value of the field specified in ResultFields and uses it as its return value. You can list multiple fields in ResultFields by separating their names with semicolons; if you do so, the field values will be returned in a variant array.


See also

GotoKey method

FindKey method

Locate method


LookupDataSet property

See also

Applies to

All field components

Declaration

property LookupDataSet: TDataSet;

Description

The LookupDataSet property identifies the table used to look up field values.

The field whose LookupDataSet property you're setting must be a lookup field (FieldKind = fkLookup or Lookup = True). When you set the lookup properties, TField automatically looks up the LookupResultField value from the record in the LookupDataSet whose LookupKeyFields values match the values of KeyFields in the field's own dataset.


See also

LookupKeyFields property

LookupResultField property

KeyFields property


LookupDisplay property

See also	Example

Applies to

TDBLookupCombo, TDBLookupList components

Declaration

property LookupDisplay : string;

Description

The LookupDisplay property determines which field in the lookup table displays in the database lookup combo box or database lookup list box. Before you specify a LookupDisplay field, link the two datasets using the LookupField property.

You can choose to display multiple fields from the lookup dataset. Each field appears in a separate column. To specify more than one field to display, separate each field name with a semicolon. For example, this line of code displays three columns in the drop-down list of a database lookup combo box. Column 1 is the name of the company, column 2 is the city where the company is located, and column 3 is the country.

  DBLookupCombo1.LookupDisplay := 'Company;City;Country';

You can choose to include titles for the field columns and you can choose to have lines between the rows and columns using the Options property.


Example

The following code specifies that the 'Company' field is displayed in DBLookupCombo1.

DBLookupCombo1.LookupDisplay := 'Company';


See also

LookupField property

Options property


LookupField property

See also	Example

Applies to

TDBLookupCombo, TDBLookupList components

Declaration

property LookupField: string;

Description

The LookupField property links the dataset the database lookup combo box or database lookup list box uses to "look up" data to the primary dataset you are working with.

Although the name of the field specified as the LookupField does not have to be the same as the name of the field specified as the DataField, the two fields must contain the same values. For example, the LookupField value can be CustomerNumber and the DataField value can be CustNo, as along as both fields use the same number to identify a particular customer. When you specify a LookupField, the current value of that field appears in the control, if the Active property of both datasets is True.

After you specify a LookupField field, you can choose which field you prefer to display in the control with the LookupDisplay property.


Example

The following code designates that DBLookupCombo1 looks up data in the 'CustomerNumber' field.

DBLookupCombo1.LookupField := 'CustomerNumber';


See also

DataSource property

LookupSource property


LookupKeyFields property

See also

Applies to

All field components

Declaration

property LookupKeyFields: string;

Description

The LookupKeyFields property identifies the field or fields in the lookup dataset to match when doing a lookup. If you want to use more than one field, separate each field name with a semicolon. The fields you specify in LookupKeyFields must be of the same types as the corresponding fields in KeyFields, or the lookup can't work.

The field whose LookupKeyFields property you're setting must be a lookup field (FieldKind = fkLookup or Lookup = True). When you set the lookup properties, TField automatically looks up the LookupResultField value from the record in the LookupDataSet whose LookupKeyFields values match the values of KeyFields in the field's own dataset.


See also

LookupDataSet property

LookupResultField property

KeyFields property


LookupResultField property

See also

Applies to

All field components

Declaration

property LookupResultField: string;

Description

The LookupResultField property identifies the field in the lookup dataset whose value you want copied into the lookup field. Unlike LookupKeyFields and KeyFields, LookupResultField can only contain the name of a single field, as the lookup field can only hold the value of one field. The lookup field should be of the same type as the field named in LookupResultField.

The field whose LookupDataSet property you're setting must be a lookup field (FieldKind = fkLookup or Lookup = True). When you set the lookup properties, TField automatically looks up the LookupResultField value from the record in the LookupDataSet whose LookupKeyFields values match the values of KeyFields in the field's own datasetdataset.


See also

LookupDataSet property

LookupKeyFields property

KeyFields property


LookupSource property

See also	Example

Applies to

TDBLookupCombo, TDBLookupList components

Declaration

property LookupSource: TDataSource;

Description

The LookupSource of a database lookup combo box or lookup list box is the data source component (TDataSource) that identifies the dataset you want the control to use to "look up" the information you want displayed in the control.


Example

The following code specifies that DataSource1 is the lookup source for DBLookupCombo1.

DBLookupCombo1.LookupSource := DataSource1;


See also

LookupDisplay property

LookupField property


MainForm property

See also

Applies to

TApplication component

Declaration

property MainForm: TForm;

Description

Run-time and read-only. The MainForm property identifies which form in the application is the main form, which is the form that is always created first. When the main form closes, the application terminates.

When you create a new project, Form1 automatically becomes the value of the MainForm property. If you want to make another form become the main form, use the Forms page of the Options|Project Options dialog box.

The main form is the first form created in the main body of the application.


See also

Application variable

CreateForm method

Run method


MakeVisible method

Applies to

TListItem, TTreeNode objects

Description

MakeVisible method for Tree Node objects

MakeVisible method for List Item objects


MakeVisible method for tree node objects
MakeVisible method

See also	Example

Applies to

TTreeNode objects

Declaration

procedure MakeVisible;

Description

The MakeVisible method makes an item visible in a tree view. If an item's parent item(s) are collapsed and the item isn't visible, MakeVisible will expand the items parents to make the item visible.


Example

The following example makes fifth item in the tree view visible if it isn't.

TreeView1.Items[6].MakeVisible


See also

IsVisible property

Expand method

Expanded property


MakeVisible method

See also

Applies to

TListItem object

Declaration

procedure MakeVisible(PartialOK: Boolean);

Description

The MakeVisible method ensures that a list item is entirely or at least partially visible, scrolling the list view control if necessary. The PartialOK parameter specifies whether the item must be entirely visible. If this parameter is True, no scrolling occurs if the item is at least partially visible.


See also

VisibleRowCount property


Mappings property

See also	Example

Applies to

TBatchMove component

Declaration

property Mappings: TStrings;

Description

By default TBatchMove matches columns based on their position in the source and destination tables. That is, the first column in the source is matched with the first column in the destination, and so on.

To override the default column mappings, use the Mappings property. This is a list of column mappings (one per line) in one of two forms. To map the column ColName in the source table to the column of the same name in the destination table, use:

ColName

Or to map the column named SourceColName in the source table to the column named DestColName in the destination table, use:

DestColName = SourceColName

If source and destination column data types are not the same, TBatchMove will perform a "best fit". It will trim character data types, if necessary, and attempt to perform a limited amount of conversion if possible. For example, mapping a CHAR(10) column to a CHAR(5) column will result in trimming the last five characters from the source column.

As an example of conversion, if a source column of character data type is mapped to a destination of integer type, TBatchMove will convert a character value of '5' to the corresponding integer value. Values that cannot be converted will generate errors.

Fields in Destination which have no entry in Mappings will be set to NULL.


Example

var Maps: TStringList;

...

with Maps do

  begin

  Clear;

{ Map the CustomerNum field to CustNo }

  Add('CustNo=CustomerNum');

  end;

BatchMove1.Mappings := Maps;


See also

Source property


Margin property

Applies to

TBitBtn, TControlScrollBar, TSpeedButton components

Description

Margin property for bitmap buttons and speed buttons

Margin property for form and scroll-box scrollbars


Margin property

See also	Example

Applies to

TBitBtn, TSpeedButton components

Declaration

property Margin: Integer;

Description

The Margin property determines the number of pixels between the edge of the image (specified in the Glyph property) and the edge of the button. The edges that the margin separates depends on the layout of the image and text (specified in the Layout property). For example, if Layout is blGlyphLeft, the margin appears between the left edge of the image and the left edge of the button. If Margin is 3, three pixels separates the image and the button edges. If Margin is 0, no distance in pixels separates the image and the button edges.

If Margin is -1 (which it is by default), then the image and text (specified in the Caption property) are centered. The number of pixels between the image and button edge is equal to the number of pixels between the opposite edge of the button and the text.


Example

This example uses a moderately large bitmap button on a form. When the application runs, a bitmap (or glyph) is loaded on to the button, the bitmap appears on the right side of the button, and bitmap is placed 30 pixels from the right edge of the bitmap button.

procedure TForm1.FormCreate(Sender: TObject);

begin

with BitBtn1 do

  begin

   Glyph.LoadFromFile('C:WINDOWS\CARS.BMP');

   Layout := blGlyphRight;

   Margin := 30;

  end;

end;


See also

Caption property

Glyph property

Layout property


Margin property

See also	Example

Applies to

TControlScrollBar components

Declaration

property Margin: Word;

Description

The Margin property value is the minimum number of pixels you want controls on a form or in a scroll box to be from the edge of the form or scroll box. This number is automatically added to the Range value to ensure that the user has a scroll bar whenever the distance from a control and the edge of the form or scroll box becomes less than the Margin value.

The default value is 0.


Example

This example uses a button and a label on a form. Place the label near the left side of the form, and place the button somewhere near the middle of the form. When the user runs the application, a horizontal scroll bar does not appear, because no control on the form is close enough to the right edge. Each time the user clicks the button, the button moves 25 pixels to the right, and the calculated Range value is reported in the caption of the label. Repeatedly clicking the button eventually moves the button close enough to the edge of the form (within the Margin amount) so that a horizontal scroll bar appears:

procedure TForm1.FormCreate(Sender: TObject);

begin

  with HorzScrollBar do

  begin

    Margin:= 25;

    Increment := 10;

  end;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Left := Button1.Left + 25;

  Label1.Caption := IntToStr(HorzScrollBar.Range);

end;


See also

Align property

HorzScrollBar property

Range property

VertScrollBar property


Mask property

Applies to

TFileListBox, TFilterComboBox components

Declaration

property Mask: string

Description

The Mask property specifies a filter for file names or text to appear in a component.

Mask Property for Filter Combo Boxes

Mask Property for File List Boxes


Mask Property for Filter Combo Boxes
Mask property

See also	Example

Applies to

TFilterComboBox components

Declaration

property Mask: string;

Description

Run-time and read-only. The Mask property value is the string selected as the filter in the filter combo box.


Example

This example uses a filter combo box and a label on a form. When the user selects a filter in the filter combo box, the selected mask appears in the caption of the label:

procedure TForm1.FilterComboBox1Change(Sender: TObject);

begin

   Label1.Caption := 'The selected mask is ' + FilterComboBox1.Mask;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  FilterComboBox1.Filter := 'All files (*.*)|*.*| Pascal files (*.pas)|*.pas';

end;


See also

Filter property


Mask Property for File List Boxes
Mask property

See also	Example

Applies to

TFileListBox components

Declaration

property Mask: string;

Description

The Mask property determines which files are displayed in the file list box. A file mask or file filter is a filename that usually includes wildcard characters (*.PAS, for example). Only files that match the mask are displayed in list box. The file mask *.* displays all files, which is the default value.

You can specify multiple file masks. Separate the file mask specifications with semicolons. For example, *.PAS; *.EXE.


Example

This example uses a file list box on a form. When the application runs, the list box displays only files with a .PAS file extension:

procedure TForm1.FormCreate(Sender: TObject);

begin

  FileListBox1.Mask := '*.PAS';

end;


See also

Filter property


Masked property

See also

Applies to

TImageList component

Declaration

property Masked: Boolean;

Description

The Masked property determines whether the ImageList contains transparent or non-transparent images.


See also

AddMasked method, InsertMasked method


MasterFields property

See also	Example

Applies to

TTable component

Declaration

property MasterFields: string;

Description

Use the MasterFields property to specify the column(s) to link a detail table with a master table that is specified by the MasterSource property. MasterFields is a string consisting of one or more column names that join the two tables. Separate multiple column names with semicolons. Each time the current record in the master table changes, the new values in those fields are used to select corresponding records from the detail table for display. At design time, use the Field Link Designer to set this property.


Example

Suppose you have a master table named Customer that contains a CustNo field, and you also have a detail table named Orders that also has a CustNo field. To display only those records in Orders that have the same CustNo value as the current record in Customer, write this code:

Orders.MasterSource := 'CustSource';

Orders.MasterFields := 'CustNo';

If you want to display only the records in the detail table that match more than one field value in the master table, specify each field and separate them with a semicolon.

Orders.MasterFields := 'CustNo;SaleDate';


See also

IndexName property


MasterSource property

See also	Example

Applies to

TTable component

Declaration

property MasterSource: TDataSource;

Description

When linking a detail table to a master table, use the MasterSource property to specify the TDataSource from which the TTable will get data for the master table.


See also

IndexName property

MasterFields property


Max property

Applies to

TProgressBar, TScrollBar, TTrackBar, TUpDown components

Description

Max property for scroll bars

Max property for progress bars

Max property for track bars

Max property for up down components


Max property

See also	Example

Applies to

TScrollBar components

Declaration

property Max: Integer;

Description

The Max property along with the Min property determines the number of possible positions the scroll box can have on the scroll bar. The LargeChange and SmallChange properties use the number of positions to determine how far to move the scroll box when the user uses the scroll bar.

For example, if Max is 30000 and Min is 0, the scroll box can assume 30,000 positions on a horizontal scroll bar. If the LargeChange property setting is 10000 and the scroll box position is at the far left of the scroll bar (Position is 0), the user can click the scroll bar three times to the right of the scroll box before the scroll box is moved all the way to the right of the scroll bar (30000/10000 = 3).

If you want to change the Min, Max, and Position values all at once at run time, call the SetParams method.


Example

This code changes the maximum position of the scroll bar from 100, the default value, to 30000:

ScrollBar1.Max := 30000;


See also

LargeChange property

Min property

Position property

SetParams method

SmallChange property


Max property for track bars
Max property

See also

Applies to

TTrackBar component

Declaration

property Max: Integer;

Description

The Max property sets the maximum position of a TTrackBar. A slider indicates the current Position and moves in increments marked by ticks in a range between Min and Max.


See also

Min property

Position property

SelEnd property

SelStart property


Max property for progress bars
Max property

See also

Applies to

TProgressBar component

Declaration

property Max: Integer;

Description

The Max property represents the range value for a progress bar control.


See also

Minproperty

Position property


Max property for updown controls
Max property

See also

Applies to

TUpDown component

Declaration

property Max: SmallInt;

Description

The Max property sets the maximum value for Position .


See also

Min property

Position property

Thousands property

Wrap property


MaxFontSize property

See also	Example

Applies to

TFontDialog component

Declaration

property MaxFontSize: Integer;

Description

The MaxFontSize property determines the largest font size available in the Font dialog box. Use the MaxFontSize property when you want to limit the font sizes available to the user. To limit the font sizes available, the Options set property of the Font dialog box must also contain the value fdLimitSize. If fdLimitSize is False, setting the MaxFontSize property has no affect on number of fonts available in the Font dialog box.

The default value is 0, which means there is no maximum font size specified.


Example

This example uses a Font dialog box, a button, and a label on a form. When the user clicks the button, the Font dialog box appears. The font sizes available are within the range of 10 to 14. When the user chooses OK, the selected font is applied to the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

begin

  FontDialog1.Options := [fdLimitSize];

  FontDialog1.MaxFontSize := 14;

  FontDialog1.MinFontSize := 10;

  if FontDialog1.Execute then

    Label1.Font := FontDialog1.Font;

end;


See also

MinFontSize property


MaxLength property

Example

Applies to

TComboBox, TDBEdit, TDBLookupCombo, TDBMemo, TEdit, TMaskEdit, TMemo, TRichEdit components

Declaration

property MaxLength: Integer;

Description

The MaxLength property specifies the maximum number of characters the user can enter in an edit box, memo, or combo box. The default setting for MaxLength is 0, which means that there is no limit on the number of characters the control can contain. Any other number limits the number of characters the control accepts.


Example

The following example sets the maximum number of characters for an edit box to 80:

Edit1.MaxLength := 80;


MaxPage property

See also	Example

Applies to

TPrintDialog component

Declaration

property MaxPage: Integer;

Description

The MaxPage property determines the greatest page number the user can use when specifying pages to print. If the user specifies a number greater than the value in MaxPage, a warning message appears and the user must enter a valid number or close the dialog box. The default value is 0.

Note:	The user can specify pages numbers only if the Options property set includes the value poPageNums.


Example

This example uses a button and a Print dialog box on a form. When the user clicks the button, the code makes page four the highest page number the user can select in the Print dialog box and displays the dialog box:

procedure TForm1.Button1Click(Sender:TObject);

begin

  PrintDialog1.Options := [poPageNums];

  PrintDialog1.ToPage := 4;

  PrintDialog1.MaxPage := 4;

  if PrintDialog1.Execute then

    ...;

end;


See also

MinPage property


MaxRecords property

Example

Applies to

TReport component

Declaration

property MaxRecords: Word;

Description

The value of the MaxRecords property is the number of database records you want to use to create the report. For example, if you just want to see a sample report and your database contains 50,000 records, you can specify a MaxRecords value that limits the number of records in the report to a much smaller number.


Example

The following code sets the maximum number of records to be used by Report1 to 3.

Report1.MaxRecords := 3;


MaxTabNameLen constant

Declaration

MaxTabNameLen = 20;

Description

The MaxTabNameLen constant specifies that the longest string that can be displayed on a tab set control (TTabSet) is 20 characters.


MaxValue property

See also	Example

Applies to

TCurrencyField, TFloatField, TIntegerField, TSmallintField, TWordField, TBCDField component

Declaration

property MaxValue: Longint;

Description

The MaxValue property limits the maximum value in the field. Assigning a value greater than MaxValue raises an exception.


Example

The following code limits a field to 1 to 10:

Field1.MaxValue := 10;

Field1.MinValue := 1;


See also

MinValue property


MaxWidth property

See also

Applies to

THeaderSection object

Declaration

property MaxWidth: Integer;

Description

The MaxWidth property sets a maximum width in pixels for a section within a THeaderControl. The default is 10000.


See also

MinWidth property


MDIChildCount property

See also	Example

Applies to

TForm component

Declaration

property MDIChildCount: Integer;

Description

Run-time and read-only. The value of the MDIChildCount property is the number of child windows open in an MDI application.


Example

The following code closes Form1 if it has no MDI children open.

if Form1.MDIChildCount = 0 then Form1.Close;


See also

ActiveMDIChild property

FormStyle property

MDIChildren property


MDIChildren property

See also	Example

Applies to

TForm component

Declaration

property MDIChildren[I: Integer]: TForm;

Description

Run-time and read-only. The MDIChildren property array provides access to a child window or form in an MDI application through an index value, I. The value of I is determined by the order in which the window was created. For example, the first MDI child window has an I value of 0.


Example

The following code closes all the MDI children of Form1.

var

  I: Integer;

begin

  with Form1 do

    for I := MDIChildCount-1 downto 0 do

      MDIChildren[I].Close;

end;


See also

FormStyle property

MDIChildCount property


Menu property

Example

Applies to

TForm component

Declaration

property Menu: TMainMenu;

Description

The Menu property designates the menu bar for the form. Menu automatically refers to the first TMainMenu added to the form at design-time. This property can be used to switch between multiple main menus at run-time.


Example

This code displays a new menu named NewMenu when the user clicks the button ChangeMenu button.

procedure TForm1.ChangeMenuClick(Sender: TObject);

begin

  Menu := NewMenu;

end;


MenuIndex property

See also

Applies to

TMenuItem component

Declaration

property MenuIndex:: Integer;

Description

The MenuIndex property is the index of the menu item within its parent menu. Changing this value will move the menu item within the parent.


See also

RadioItem property


Merge method

See also	Example

Applies to

TMainMenu component

Declaration

procedure Merge(Menu: TMainMenu);

Description

The Merge method merges a main menu of one form with a main menu of another for non-MDI applications. For example, when your application uses the main menu of the first form as the main menu for the application, and your application displays a second form, you can call Merge to merge the main menu on the second form with the main menu of the application.

Specify the menu you want merged with this menu as the Menu parameter.

Depending on the value of the GroupIndex property of menu items on the main menu, the merged menu items can replace menu items on the menu bar, or add or insert menu items into the menu bar. See GroupIndex for information on how to do these things.

It you want merging and unmerging to occur automatically when another form is displayed, change the value of the AutoMerge property to True.


Example

This example uses two forms, each containing a main menu created with the Menu Designer. It also uses a button on Form1. When the user clicks the button, Form2 appears and the main menu of Form2 merges with that of Form1.

Before running this example, add Unit2 to the uses clause of Unit1.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form2.Show;

  MainMenu1.Merge(Form2.MainMenu1);

end;


See also

AutoMerge property

Unmerge method


MessageBox method

See also	Example

Applies to

TApplication component

Declaration

function MessageBox(Text, Caption: PChar; Flags: Word): Integer;

Description

The MessageBox method is an encapsulation of the Windows API MessageBox function except that you don't need to supply a window handle.

The MessageBox method displays a generic dialog box that displays a message and one or more buttons. The value of the Text parameter is the message, which can be longer than 255 characters if necessary. Long messages are automatically wrapped in the message box. The value of the Caption property is the caption that appears in the title bar of the dialog box. Captions can be longer than 255 characters, but they don't wrap. A long caption results in a wide message box.

To see the possible values of the Flags parameter, see the MessageBox function in the Windows API Help file (WinAPI.HLP). The corresponding parameter on that Help screen is called TextType. The values determine the buttons that appear in the message box and the behavior of the message box. The values can be combined to obtain the effect your want.

The return value of the MessageBox method is 0, if there wasn't enough memory to create the message box, or one of these values:

Value	Numeric value	Meaning

IDABORT	     3	The user chose the Abort button

IDCANCEL	     2	The user chose the Cancel button

IDIGNORE	     5	The user chose the Ignore button

IDNO	     7	The user chose the No button

IDOK	     1	The user chose the OK button

IDRETRY	     4	The user chose the Retry button

IDYES	     6	The user chose the Yes button.


Example

This example uses a button and a label on a form. When the user clicks the button, a message box appears. When the user responds to the message box, the button selected is reported in the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

var

  Button: Integer;

begin

  Button := Application.MessageBox('Welcome to Delphi!', 'Message Box', mb_OKCancel +

    mb_DefButton1);

 if Button = IDOK then

   Label1.Caption := 'You chose OK';

 if Button = IDCANCEL then

   Label1.Caption := 'You chose Cancel';

end;


See also

MessageDlg function

MessageDlgPos function

ShowMessage procedure

ShowMessagePos procedure


MessageDlg function

See also	Example

Unit

Dialogs

Declaration

function MessageDlg(const Msg: string; AType: TMsgDlgType; AButtons: TMsgDlgButtons;   HelpCtx: Longint): Word;

Description

The MessageDlg function displays a message dialog box for your application in the center of your screen. The message box displays the value of the Msg string constant.

The AType parameter determines the type of message box that appears. These are the possible values:

Value	Meaning

mtWarning	A message box containing a yellow exclamation point symbol.

mtError	A message box containing a red stop sign.

mtInformation	A message box containing a blue "i".

mtConfirmation	A message box containing a green question mark.

mtCustom	A message box containing no bitmap. The caption of the message box is the name of the application's executable file.

The AButtons parameter determines which buttons appear in the message box. AButtons is of type TMsgDlgBtns, which is a set, so you can include multiple buttons within the set. These are the values you can include in the set:

Value	Meaning

mbYes	A button with a green check mark and the text 'Yes' on its face

mbNo	A button with a red circle and slash mark through the circle and the text 'No' on its face

mbOK	A button with a green check mark and the text 'OK' on its face

mbCancel	A button with a red X and the text 'Cancel' on its face

mbHelp	A button with a cyan question mark and the text 'Help' on its face

mbAbort	A button with a red check mark and the text 'Abort' on its face

mbRetry	A button with two green circular arrows and the text 'Retry' on its face

mbIgnore	A button with a green man walking away and the text 'Ignore' on its face

mbAll	A button with a green double check marks and the text 'All' on its face

In addition to the individual set values, VCL defines three constants that are predefined sets that include common button combinations:

Value	Meaning

mbYesNoCancel	A set that puts the Yes, No, and Cancel buttons in the message box

mbOkCancel	A set that puts the OK and Cancel buttons in the message box

mbAbortRetryIgnore	A set that puts an Abort, Retry, and Ignore buttons in the message box

When using these constants, remember not to add the brackets [ ] to define the set. These constants are already predefined sets.

The HelpCtx parameter determines which Help screen is available for the message box. For more information about Help context values, see the HelpContext property.

The function returns the value of the button the user selected. These are the possible return values:

Return values

mrNone	mrAbort	mrYes

mrOk	mrRetry	mrNo

mrCancel	mrIgnore	mrAll

The MsgDlgButtonStyle typed constant in the Dialogs unit is declared like this:

  MsgDlgButtonStyle: TButtonStyle = bsAutoDetect;

This ensures that the style of the buttons matches the style used by the operating environment your application is running under. If you prefer to always use a particular style, change the value of the MsgDlgButtonStyle. See the Style property for bitmap buttons for the possible values and their meanings.

The MsgDlgGlyphs typed constant in the Dialogs unit is declared like this:

  MsgDlgGlyphs: Boolean = True;

This declaration ensures that bitmaps (or glyphs) appear on the message dialog box buttons. If you prefer that the bitmaps are not present, change the value of MsgDlgButtonStyle to False.


Example

This example uses a button on a form. When the user clicks the button, a message box appears, asking if the user wants to exit the application. If the user chooses Yes, another dialog box appears informing the user the application is about to end. When user chooses OK, the application ends.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if MessageDlg('Welcome to my Object Pascal application.  Exit now?',

    mtInformation, [mbYes, mbNo], 0) = mrYes then

  begin

    MessageDlg('Exiting the Object Pascal application.', mtInformation,

      [mbOk], 0);

    Close;

  end;

end;

This example uses a button on a form. When the user clicks the button, a message box appears with a Yes, No, and Cancel button on it:

procedure TForm1.Button1Click(Sender: TObject);

begin

  MessageDlg('Are you there?', mtConfirmation, mbYesNoCancel, 0);

end;


See also

Kind property

MessageDlgPos function

ModalResult property

MessageBox method

ModalResult property

ShowMessage procedure

ShowMessagePos procedure


MessageDlgPos function

See also	Example

Unit

Dialogs

Declaration

function MessageDlgPos(const Msg: string; AType: TMsgDlgType;
  AButtons: TMsgDlgButtons; HelpCtx: Longint; X, Y: Integer): Word;

Description

The MessageDlgPos functions as MessageDlg except that it displays the message at the position specified by X and Y. Refer to the entry for MessageDlg for additional information.


Example

This example displays a confirmation style message box at screen coordinates 125, 25 that asks users if they want to color the form green. If the user chooses Yes, the form turns bright green:

procedure TForm1.Button1Click(Sender: TObject);

var

  ButtonSelected: Word;

begin

  if MessageDlgPos('Color the form green?', mtConfirmation,

    [mbYes, mbNo], 0, 125, 25) := mrYes then

    Color := clLime;

end;

This example uses a button on a form. When the user clicks the button, a message box appears with a Yes, No, and Cancel button on it:

procedure TForm1.Button1Click(Sender: TObject);

begin

  MessageDlgPos('Are you there?', mtConfirmation, mbYesNoCancel, 0, 200, 200);

end;


See also

Kind property

MessageBox method

MessageDlg function

ModalResult property

ShowMessage procedure

ShowMessagePos procedure


Metafile property

See also	Example

Applies to

TPicture object

Declaration

property Metafile: TMetafile

Description

The Metafile property specifies the contents of the TPicture object as an Enhanced Windows metafile graphic (.EMF file format). If Metafile is referenced when the TPicture contains a Bitmap or Icon graphic, the graphic won't be converted. Instead, the original contents of the TPicture are discarded and Metafile returns a new, blank metafile.


Example

The following line of code displays the pixels-per-inch of the coordinate mapping of a metafile. The Inch property of the metafile stored in the MyGraphic is converted to text and assigned to the Caption of Label1.

Label1.Caption := IntToStr(MyGraphic.Metafile.Inch);


See also

Graphic property


Min property

Applies to

TProgressBar, TScrollBar, TTrackBar, TUpDown components

Description

Min property for scroll bars

Min property for progress bars

Min property for track bars

Min property for TUpDown components


Min property

See also	Example

Applies to

TScrollBar components

Declaration

property Min: Integer;

Description

The Min property along with the Max property determines the number of possible positions the scroll box can have on the scroll bar. The LargeChange and SmallChange properties use the number of positions to determine how far to move the scroll box when the user uses the scroll bar.

For example, if Max is 3000 and Min is 0, the scroll box can assume 3000 positions on a horizontal scroll bar. If the LargeChange property setting is 1000 and the scroll box position is at the far left of the scroll bar (Position is 0), the user can click the scroll bar three times to the right of the scroll box before the scroll box is moved all the way to the right of the scroll bar (3000/1000 = 3).

If you want to change the Min, Max, and Position values all at run time, call the SetParams method.


Example

The following code sets the minimum position to the value specified in an edit box, and sets the maximum position to 1000 more than the minimum position.

ScrollBar1.Min := StrToInt(Edit1.Text);

ScrollBar1.Max := ScrollBar1.Min + 1000;


See also

LargeChange property

Max property

Position property

SetParams method

SmallChange property


Min property for track bars
Min property

See also

Applies to

TTrackBar component

Declaration

property Min: Integer;

Description

The Min property sets the minimum Position of a TTrackBar. A slider indicates the current Position and moves in increments marked by ticks in a range between Min and Max.


See also

Max property

Position property

SelEnd property

SelStart property


Min property for progress bars
Min property

See also

Applies to

TProgressBar component

Declaration

property Min: Integer;

Description

The Min property represents the minimum extent of Position.


See also

Maxproperty

Position property


Min property for updown controls
Min property

See also

Applies to

TUpDown component

Declaration

property Min: SmallInt;

Description

The Min property sets the minimum value for Position .


See also

Max property

Position property

Thousands property

Wrap property


MinFontSize property

See also	Example

Applies to

TFontDialog component

Declaration

property MinFontSize: Integer;

Description

The MinFontSize property determines the smallest font size available in the Font dialog box. Use the MinFontSize property when you want to limit the font sizes available to the user. To limit the font sizes available, the Options set property of the Font dialog box must also contain the value fdLimitSize. If fdLimitSize is False, setting the MinFontSize property has no affect on number of fonts available in the Font dialog box.

The default value is 0, which means there is no minimum font size specified.


Example

This example uses a Font dialog box, a button, and a label on a form. When the user clicks the button, the Font dialog box appears. The font sizes available are within the range of 10 to 14. When the user chooses OK, the selected font is applied to the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

begin

  FontDialog1.Options := [fdLimitSize];

  FontDialog1.MaxFontSize := 14;

  FontDialog1.MinFontSize := 10;

  if FontDialog1.Execute then

    Label1.Font := FontDialog1.Font;

end;


See also

MinFontSize property


Minimize method

See also	Example

Applies to

TApplication component

Declaration

procedure Minimize;

Description

The Minimize method shrinks your application into an icon on your Windows desktop.


Example

This example uses a button named Shrink on a form. When the user clicks the button, the application minimizes to an icon:

procedure TForm1.ShrinkClick(Sender: TObject);

begin

  Application.Minimize;

end;


See also

Application variable

Icon property


MinPage property

See also	Example

Applies to

TPrintDialog component

Declaration

property MinPage: Integer;

Description

The MinPage property determines the smallest page number the user can use when specifying pages to print. If the user specifies a number less than the value of MinPage, a warning message appears and the user must enter a valid number or close the dialog box. The default value is 0.

Note:	The user can specify pages numbers only if the Options property set includes the value poPageNums.


Example

This example uses a button and a Print dialog on a form. When the user clicks the button, the code sets the lowest and the highest possible page numbers the user can select and displays the dialog box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  with PrintDialog1 do

  begin

    Options := [poPageNums];

    MinPage := 2;

    FromPage := 2;

    ToPage := 10;

    MaxPage := 10;

    PrintRange := prPageNums;

    Execute;

  end;

end;


See also

MaxPage property


MinValue property

See also	Example

Applies to

TCurrencyField, TFloatField, TIntegerField, TSmallintField, TWordField, TBCDField component

Declaration

property MinValue: Longint;

Description

The MinValue property limits the minimum value in the field. Assigning a value less than MinValue raises an exception.


Example

The following code limits the field to 1 to 10:

Field1.MaxValue := 10;

Field1.MinValue := 1;


See also

MaxValue property


MinWidth property

See also

Applies to

THeaderSection object

Declaration

property MinWidth: Integer;

Description

The MinWidth property set a minimum width in pixels for a section within a THeaderControl. The default is 0.


See also

MaxWidth property


MMHeight property

See also

Applies to

TMetafile object

Declaration

property MMHeight: Integer;

Description

The MMHeight property contains the width of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles.  The MMHeight property is always in screen device pixel units; you can avoid loss of precision in converting between device pixels and millimeters by setting or reading the dimensions in mm with MMHeight.


See also

MMWidth property


MMWidth property

See also

Applies to

TMetafile object

Declaration

property MMWidth: Integer;

Description

The MMWidth property contains the width of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles.  The MMWidth property is always in screen device pixel units; you can avoid loss of precision in converting between device pixels and mm by setting or reading the dimensions in mm with MMWidth.


See also

MMHeight property


ModalResult property

See also	Example

Applies to

TBitBtn, TButton, TForm components

Declaration

property ModalResult: TModalResult;

Description

Run-time only. The ModalResult property for forms is used to terminate a modal form. By default, ModalResult is 0. Setting ModalResult to any nonzero value ends the form's modal state. When the user chooses to close a modal form, the button click sets ModalResult to close the form. The value assigned to ModalResult becomes the return value of the ShowModal function call which displayed the modal form.

Button controls have a ModalResult property also that is read-only. Use a button's ModalResult property when you want a click of the button to close a modal form. For example, if you create a dialog box with two buttons, OK and Cancel, set the ModalResult property to mrOK for the OK button and mrCancel for the Cancel button. When the user chooses either of these two buttons, the dialog box's modal state ends because ModalResult is greater than mrNone and the dialog box disappears. Using ModalResult, you don't have to write an event handler just to close the dialog box.

These constants are possible ModalResult values:

Constant	Value

mrNone	0

mrOk	idOK

mrCancel	idCancel

mrAbort	idAbort

mrRetry	idRetry

mrIgnore	idIgnore

mrYes	idYes

mrNo	idNo

mrAll	mrNo + 1


Example

The following methods in a form are used as a modal dialog box. The methods cause the dialog box to terminate when the user clicks either the OK or Cancel button, returning mrOK or mrCancel from ShowModal, respectively:

procedure TMyDialogBox.OKButtonClick(Sender: TObject);

begin

  ModalResult := mrOK;

end;

procedure TMyDialogBox.CancelButtonClick(Sender: TObject);

begin

  ModalResult := mrCancel;

end;

You could also set the ModalResult value to mrOK for the OK button and mrCancel for the Cancel button to accomplish the same thing. When the user clicks either button, the dialog box closes.


See also

Kind property

ShowModal method


Mode property

Applies to

TPen object; TMediaPlayer, TBatchMove components

Description

The Mode property specifies either the drawing behavior of a pen or the current state of a multimedia device.

Mode for Pen Objects

Mode for Media Player Controls

Mode for Batch Move Objects


Mode property

See also	Example

Applies to

TPen object

Declaration

property Mode: TPenMode;

Description

The Mode property determines how the pen draws lines on the canvas. The following table describes the behavior for each pen mode.

Mode	Pixel color

pmBlack	Always black.

pmWhite	Always white.

pmNop	Unchanged.

pmNot	Inverse of screen color.

pmCopy	Pen color specified in Color property.

pmNotCopy	Inverse of pen color.

pmMergePenNot	Combination of pen color and inverse of screen color.

pmMaskPenNot	Combination of colors common to both pen and inverse of screen.

pmMergeNotPen	Combination of screen color and inverse of pen color.

pmMaskNotPen	Combination of colors common to both screen and inverse of pen.

pmMerge	Combination of pen color and screen color.

pmNotMerge	Inverse of pmMerge combination of pen color and screen color.

pmMask	Combination of colors common to both pen and screen.

pmNotMask	Inverse of pmMask combination of colors common to both pen and screen.

pmXor	Combination of colors in either pen or screen, but not both.

pmNotXor	Inverse of pmXor combination of colors in either pen or screen, but not both.


Example

The following code sets the mode of the pen of the Canvas of Form1 to the inverse of the pen Color.

Form1.Canvas.Pen.Mode := pmNotCopy;


See also

Pen property

TPen object


Mode property

Example

Applies to

TMediaPlayer components

Declaration

property Mode: TMPModes;

Description

Run-time and read-only. The Mode property specifies the mode of the currently open multimedia device. The following table lists the possible values for Mode:

Value	Mode

mpNotReady	Not ready

mpStopped	Stopped

mpPlaying	Playing

mpRecording	Recording

mpSeeking	Seeking

mpPaused	Paused

mpOpen	Open


Example

The following code declares an array of strings named ModeStr, indexed by the TMPModes type. The Caption of a form is then set to the string describing the current mode of the device:

const

  ModeStr: array[TMPModes] of string[10] = ('Not ready', 'Stopped', 'Playing',
    'Recording', 'Seeking', 'Paused', 'Open');

{Later in your code}

Caption := ModeStr[MediaPlayer1.Mode];


Mode property

Example

Applies to

TBatchMove components

Declaration

property Mode: TBatchMode;

Description

The Mode property specifies what the TBatchMove object will do:

Property	Purpose

batAppend	Append records to the destination table. The destination table must already exist. This is the default mode.

batUpdate	Update records in the destination table with matching records from the source table. The destination table must exist and must have an index defined to match records.

batAppendUpdate	If a matching record exists in the destination table, update it. Otherwise, append records to the destination table. The destination table must exist and must have an index defined to match records.

batCopy	Create the destination table based on the structure of the source table. The destination table must not already exist--if it does, the operation will delete it.

batDelete	Delete records in the destination table that match records in the source table. The destination table must already exist and must have an index defined.


Example

BatchMove1.Mode := batAppendUpdate;


Modified property

Applies to

TBitmap, TGraphic, TIcon, TMetafile objects, TDBEdit, TDBMemo, TEdit, TMaskEdit, TMemo, TQuery, TStoredProc, TTable, TOleContainer components

Description

The Modified property specifies if an object's or component's contents have been modified.

Modified property for Graphics Objects

Modified property for Edit Box and Memo Components

Modified property for Queries, Tables, and Stored Procedures

Modified property for Ole Containers


Modified property

Applies to

TOleContainer component

Declaration

property Modified: Boolean;

Description

Runtime only. Indicates that the OLE object has been modified (including being deleted or replaced by another OLE object). You can set Modified to False and later check it to see if the OLE object has been modified. If there is no OLE object loaded into the container, Modified returns False.


Modified property

Example

Applies to

TBitmap, TGraphic, TIcon, TMetafile objects

Declaration

property Modified: Boolean;

Description

The Modified property specifies if the graphics object has been changed or edited. If Modified is True, the graphics object has changed. If Modified is False, the graphics object is in the same state as when the object was loaded.

Note:	The Modified property only indicates if bitmap objects have been modified. Modified is not True if the graphics object contains an icon or metafile graphic.

If the graphics object was modified, you can save the changes to a file with the SaveToFile method. The next time the application is run, the object can be loaded from the file with the LoadFromFile method.


Example

The following code saves the bitmap object in Graphic1 to a file if it was modified.

if Graphic1.Modified then Graphic1.SaveToFile('myfile.bmp');


Modified property

See also	Example

Applies to

TDBEdit, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

property Modified: Boolean;

Description

Run-time only. The Modified property determines whether the text of an edit box or memo control was changed since it was created or since the last time the Modified property was set to False. If Modified is True, the text was changed. If Modified is False, the text was not changed.


Example

procedure TForm1.Button1Click(Sender: TObject);

begin

if Edit1.Modified = True then

  begin

    MessageDlg('Edit box text was modified',

      mtInformation, [mbOK], 0);

    Edit1.Modified := False;

  end

  else

    MessageDlg('Edit box text was not modified',

      mtInformation, [mbOK], 0);

end;


See also

Text property


Modified property

See also

Applies to

TQuery, TStoredProc, TTable components

Declaration

property Modified: Boolean;

Description

Run-time and read-only. The Modified property is True if a field in the current record has been changed. It is reset to False when the record is updated through a call to the Cancel or Post methods.


See also

UpdateRecord method


Modifiers property

See also

Applies to

THotKey component

Declaration

property Modifiers: THKModifiers;

Description

The Modifiers property allows the selection of a modifier key such as Ctrl, Alt, or Shift for the hot key. These are the possible values:

Value	Meaning

hkShift	The Shift key is used as a modifier.

hkCtrl	The Ctrl key is used as a modifier.

hkAlt	The Alt key is used as a modifier.

hkExt	The Extra key is used as a modifier.

The default value is hkAlt.

Modifier keys are used in combination with another non-modifier key such as character and function keys, arrow keys, and so on. More than one modifier key can be used.


See also

HotKey property

InvalidKeys


ModifyAlias method

See also

Applies to

TSession component

Declaration

procedure ModifyAlias(Name: string; List: TStrings);

Description

The ModifyAlias method lets you change the parameters of a given alias. You're responsible for creating and destroying the string list that holds the alias parameters. The parameters you can change depend on whether the alias is for a standard database (that is, local tables such as Paradox or dBASE) or if for a server database, which parameters the server supports.

You only need to specify the parameters you want to change; parameters whose values you don't want to be changed can be omitted and they won't be affected. You can also use the GetAliasParams to get the existing parameters.


See also

AddAlias method

AddStandardAlias method

DeleteAlias method

GetAliasParams method

GetDriverParams method

Session variable


ModifySQL property

Applies to

TUpdateSQL component

Declaration

property ModifySQL: TStrings;

Description

The ModifySQL property returns the string list containing the SQL statement to be used when applying the cached modification of a record. Generally, such an SQL statement would be an UPDATE statement. You can use the UpdateSQL Editor (by double-clicking the TUpdateSQL component) to generate an appropriate SQL statement, such as the following:

update "COUNTRY.DB"

set

  Name = :Name,

  Capital = :Capital,

  Continent = :Continent

where

  Name = :OLD_Name


Monochrome property

Example

Applies to

TBitmap object

Declaration

property Monochrome: Boolean;

Description

The Monochrome property determines if the bitmap displays in monochrome. If True, the bitmap is monochrome. If False, the bitmap displays in color.


Example

The following code creates Bitmap1 and sets its Monochrome property to True.

var

  Bitmap1: TBitmap;

begin

  Bitmap1 := TBitmap.Create;

  Bitmap1.Monochrome := True;

end;


MouseToCell method

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

procedure MouseToCell(X, Y: Integer; var ACol, ARow: Longint);

Description

The MouseToCell method returns the column and row of the cell the mouse pointer is positioned on. The X and Y parameters are the screen coordinates of the mouse pointer. The ACol parameter is the number of the column where the mouse pointer is positioned, and the ARow parameter is the number of the row.

Usually the MouseToCell method is used in a mouse event handler, which supplies the mouse coordinates to the method call.


Example

This example uses a string grid on a form. When the user selects a cell in the grid and releases the mouse button, the column and row coordinates for the cell appear in the cell. The code for displaying the coordinates is written in the OnMouseUp event handler:

procedure TForm1.FormCreate(Sender: TObject);

begin

  StringGrid1.DefaultColWidth := 100;

end;

procedure TForm1.StringGrid1MouseUp(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

var

  Column, Row: Longint;

begin

  StringGrid1.MouseToCell(X, Y, Column, Row);

  StringGrid1.Cells[Column, Row] := 'Col ' + IntToStr(Column) +

    ',Row ' + IntToStr(Row);

end;


See also

CellRect method

OnMouseDown event

OnMouseMove event

OnMouseUp event


Move method

Applies to

TList, TStringList, TStrings objects; TImageList component

Description

Move Method for Strings and Lists

Move Method for Image Lists


Move property

See also	Example

Applies to

TList, TStringList, TStrings objects component

Declaration

procedure Move(CurIndex, NewIndex: Integer);

Description

The Move method changes the position of an item in the list of a list object or in a list of strings in a string object by giving the item a new index value. The CurIndex parameter is the item's current index, and the NewIndex parameter is the item's new index value.

If a string in a string object has an associated object in the Objects property, Move moves both the string and the object.


Example

This example uses a list box and a button on a form. The list box contains items when the form appears. When the user clicks the button, the fifth item in the list box is moved to the top of the list box:

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  for I := 1 to 5 do

    ListBox1.Items.Add('Item ' + IntToStr(I));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Move(4, 0);

end;


See also

Add method

Delete method

Exchange method

Objects property

Strings property


Add method for image list objects
Move method

See also

Applies to

TImageList object

Declaration

procedure Move(CurIndex, NewIndex: Integer);

Description

The Move method moves an image specified by CurIndex in the ImageList to another position specified by NewIndex within the ImageList.


See also

ImageIndex property, Insert method


MoveBy method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

function MoveBy(Distance: Integer): Integer;

Description

The MoveBy method moves the dataset cursor by Distance records. If Distance is negative, the move is backward. If Distance is positive, the movement is forward. If Distance is zero, no move is done. MoveBy returns the number of records that were traversed.

If the dataset is in Insert or Edit state, MoveBy will perform an implicit Post of any pending data, even if Distance is 0.


Example

The following code skips three records forward:

Table1.MoveBy(3);


See also

BOF property

EOF property

First method

Last method

Next method

Prior method

RecordCount property


MovedCount property

See also	Example

Applies to

TBatchMove component

Declaration

property MovedCount: Longint;

Description

Run-time and read-only. MovedCount is the number of records which were actually processed by the Execute method. This includes any records which had integrity or data size problems.


Example

with BatchMove1 do

  begin

  Execute;

  MessageDlg(IntToStr(MoveCount) + ' records read', mtInformation, [mbOK], 0);

  end;


See also

ChangedCount property

KeyViolCount property

ProblemCount property

RecordCount property


MoveTo method

Applies to

TCanvas, TOutlineNode, TTreeNodee objects

Description

MoveTo Method for Canvases

MoveTo Method for Outline Nodes

MoveTo Method for Tree NodesObjects


MoveTo method

See also	Example

Applies to

TCanvas objects

Declaration

procedure MoveTo(X, Y: Integer);

Description

The MoveTo method changes the current drawing position to the coordinates passed in X and Y. The current position is given by the PenPos property. You should use MoveTo to set the current position rather than setting PenPos directly.


Example

The following code draws a line from the upper-eft corner of a form to the point clicked with the mouse:

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Canvas.MoveTo(0, 0);

  Canvas.LineTo(X, Y);

end;


See also

LineTo method


MoveTo method

See also	Example

Applies to

TOutlineNode object

Declaration

procedure MoveTo(Destination: Longint; AttachMode: TAttachMode);

Description

The MoveTo method moves an outline item from one location to another within an outline (TOutline component). The Destination parameter determines where to move the item. Pass the Index value of another outline item in the Destination parameter. The AttachMode parameter specifies how you want to attach the item to the destination position. These are the possible values of AttachMode:

Value	Meaning

oaAdd	The item is attached as if added with the Add method. The moved item becomes the last sibling of the item specified by the Destination parameter. The moved item will share the same parent as the Destination item.

oaAddChild	The item is attached as if added with the AddChild method. The moved item becomes the last child of the item specified by the Destination parameter. The Destination item will become the parent of the moved item.

oaInsert	The item is attached as if inserted with the Insert method. The moved item replaces the Destination item in the outline, while the Destination item and all other following items are moved down one row.

MoveTo returns the new Index value of the moved item.

Note:	When an item is moved, all its subitems move with it.

When an item (and any subitems) is moved, the other items in the outline are reindexed to obtain new valid Index values. This happens automatically unless BeginUpdate has been called.


Example

The following code moves the selected item to become the first item in the outline.

with Outline1.Items[Outline1.SelectedItem] do

  MoveTo(0, oaInsert);


See also

ChangeLevelBy method


MoveTo method for tree node objects
MoveTo method

See also	Example

Applies to

TTreeNode object

Declaration

procedure MoveTo(Destination: TTreeNode; Mode: TNodeAttachMode);

Description

The MoveTo method for a tree node moves the node to another location on the tree view. The Destination parameter determines where to move the node. The Mode parameter is of type TNodeAttachMode and specifies how the node is to be reattached. These are the possible values for the Mode parameter:

Value	Meaning

naAdd	Adds the item to the end of the list.

naAddFirst	Adds the item at the beginning of the list.

naAddChild	Adds the item as a child of the destination at the end of the child list.

naAddChildFirst	Adds the item as a child at the beginning of the child list of the destination.

naInsert	Insert the item after the destination node.


Example

procedure TForm1.TreeView1DragDrop(Sender, Source: TObject; X, Y: Integer);

var

  AnItem: TTreeNode;

  AttachMode: TNodeAttachMode;

  HT: THitTests;

begin

  if TreeView1.Selected = nil then Exit;

  HT := TreeView1.GetHitTestInfoAt(X, Y);

  AnItem := TreeView1.GetNodeAt(X, Y);

  if (HT - [htOnItem, htOnIcon, htNowhere, htOnIndent] <> HT) then

  begin

    if (htOnItem in HT) or (htOnIcon in HT) then AttachMode := naAddChild

    else if htNowhere in HT then AttachMode := naAdd

    else if htOnIndent in HT then AttachMode := naInsert;

    TreeView1.Selected.MoveTo(AnItem, AttachMode);

  end;

end;


See also

Insert method

InsertObject method

Add method

AddChild method

AddChildObjectFirst method

AddChildObject method

AddFirst method

AddObjectFirst method

AddObject method


Multiline property

See also

Applies to

TPageControl, TTabControl component

Declaration

property MultiLine: Boolean;

Description

The Multiline property allows stacked rows of tabs. By default both TPageControl and TTabControl components display only one row of tabs. If not all tabs can visibly fit within that one row an UpDown control is automatically used to scroll the additional tabs into view. To display all tabs at once in multiple rows set the Multiline property to True.


See also

TabHeight property

TabWidth property


MultiSelect property

See also	Example

Applies to

TFileListBox, TListBox, TListView components

Declaration

property MultiSelect: Boolean;

Description

The MultiSelect property determines whether the user can select more than one element at a time from the list. If MultiSelect is True, the user can select multiple items. If MultiSelect if False, multiple items can be selected in the list box at the same time. The default value is False.


Example

This line of code ensures that the user can select multiple items in a list box:

ListBox1.MultiSelect := True;


See also

ExtendedSelect property

SelCount property

Selected property


Name property

Applies to

All components; TFieldDef, TIndexDef, TFont, TParam objects

Description

The Name property uniquely identifies a component or object.

Name Property for components

Name Property for font and TTextAttributes objects

Name Property for TFieldDef Objects

Name Property for TIndexDef Objects

Name Property for TParam Objects


Name property

Example

Applies to

All components

Declaration

property Name: TComponentName;

Description

The Name property contains the name of the component as referenced by other components. By default, Delphi assigns sequential names based on the type of the component, such as 'Button1', 'Button2', and so on. You may change these to suit your needs.

Note:	Change component names only at design time.


Example

The following code lists the names of all the components of Form1 in a list box.

var

  I: Integer;

begin

  for I := 0 to Form1.ComponentCount-1 do

    ListBox1.Items.Add(Form1.Components[I].Name);

end;


Name property

See also	Example

Applies to

TFont objects

Declaration

property Name: TFontName;

Description

The Name property of a font object determines the name of the font contained within the font object.


Example

This code sets the font for all text that appears on the form to Times New Roman. If the controls on the form have their ParentFont property set to True, text on these controls will also be in Times New Roman.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Font.Name := 'Times New Roman';

end;


See also

ParentFont property


Name property

Applies to

TIndexDef objects

Declaration

property Name: string;

Description

Run-time and read-only. Name is the name of the index.


Name property

Example

Applies to

TParam objects

Declaration

property Name: string;

Description

The Name property is the name of the parameter.


Example

The following code changes the name of the first parameter column to 'CustNo':

Params[0].Name := 'CustNo';


Name property

See also	Example

Applies to

TFieldDef objects

Declaration

property Name: string;

Description

Run-time and read-only. Name is the name of the physical field within the table.


Example

The following example displays the field name and number:

with FieldDef1 do

  MessageDlg(Name + ' is field ' + IntToStr(FieldNo), mtInformation, [mbOK], 0);


See also

TField component


Names property

See also

Applies to

TStringList, TStrings objects

Declaration

property Names[Index: Integer]: string;

Read-only. The Names property returns the name part of a string at the Index position in the string list when the form is Name=Value, otherwise it returns a blank string.


See also

IndexOfName method

Values property


NativeToAnsi procedure

Unit

DB

Declaration

procedure NativeToAnsi(Locale: TLocale; NativeStr: PChar; var AnsiStr: string);

Description

The NativeToAnsi procedure translates native characters in NativeStr to the ANSI character set according to Locale. NativeToAnsi returns the translated string in AnsiStr.


NetFileDir property

See also

Applies to

TSession component

Declaration

property NetFileDir: string;

Description

The NetFileDir property specifies the directory that contains the BDE network control file, PDOXUSRS.NET. This property enables multiple users to share Paradox tables on network drives. NetFileDir overrides the specification defined for the Paradox driver in the BDE Configuration Utility.

All applications that need to share the same Paradox database must specify the same directory, and all must have read/write/create rights for the directory.


See also

Active property

PrivateDir property

Session variable


NewPage method

See also	Example

Applies to

TPrinter object

Declaration

procedure NewPage;

Description

The NewPage method forces the current print job to begin printing on a new page in the printer. It also increments the value of the PageNumber property and resets the value of the Pen property of the Canvas back to (0, 0).


Example

This example uses a button on a form. When the user clicks the button, a rectangle is printed twice, one per page.

To run this example successfully, you must add the Printers unit to the uses clause of your unit.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with Printer do

  begin

    BeginDoc;

    Canvas.Rectangle(10, 10, 200, 200);

    NewPage;

    Canvas.Rectangle(10, 10, 200, 200);

    EndDoc;

  end;

end;


See also

BeginDoc method

EndDoc method

Printer function


NewValue property

See also

Applies to

All field components

Declaration

property NewValue: Variant;

Description

Run-time only. The NewValue property represents the current value of the field (as a Variant) including any changes made in pending cached updates. If the current field value is causing a problem (in an OnUpdateError event handler) applying the cached update (such as in an key violation), you can change NewValue to correct the problem.

Cached updates must be enabled to access the NewValue property.


See also

CachedUpdates property

OldValue property


Next method

Applies to

TForm, TMediaPlayer, TQuery, TStoredProc, TTable components

Description

The Next method either activates the next form, media track, or record.

Next for Forms

Next for Media Player Controls

Next for Tables, Queries, and Stored Procedures


Next method

See also	Example

Applies to

TForm components

Declaration

procedure Next;

Description

The Next method makes the next child form in the form sequence the active form.

For example, if you have three child forms within a parent form in your MDI application and Form2 is the active form, the Next method makes Form3 the active form. Calling Next again makes Form4 active. The next time your application calls Next, the sequence starts over again and Form2 becomes the active form once again.

The Next method applies only to forms that are MDI parent forms (have a FormStyle property value of fsMDIForm).


Example

The following code activates the next child of Form1.

Form1.Next;


See also

ArrangeIcons method

Cascade method

Previous method

Tile method


Next method

See also	Example

Applies to

TMediaPlayer components

Declaration

procedure Next;

Description

The Next method goes to the beginning of the next track of the currently loaded medium. If the current position is at the last track when Next is called, Next makes the current position the beginning of the last track. If the multimedia device doesn't use tracks, Next goes to the end of the medium. Next is called when the Next button on the media player control is clicked at run time.

Upon completion, Next stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Next method has completed. The Notify property determines whether Next generates an OnNotify event.


Example

The following code opens a WAV audio file and fast-forwards to the end of the medium.

MediaPlayer1.DeviceType := dtWAVAudio;

MediaPlayer1.FileName := 'c:\chimes.wav';

MediaPlayer1.Open;

MediaPlayer1.Next;


See also

Position property

Previous method

Tracks property


Next method

See also	Example

Applies to

TQuery, TStoredProc, TTable components

Declaration

procedure Next;

Description

The Next method moves the cursor forward by one record. If the cursor is already on the last record, it does not move. If the dataset is in Insert or Edit state, Next will perform an implicit Post of any pending data.


Example

{ Move to the next record }

Table1.Next;

if Table1.Eof then { No more records };


See also

First method

Last method

MoveBy method

Prior method


NormalizeTopMosts method

See also	Example

Applies to

TApplication component

Declaration

procedure NormalizeTopMosts;

Description

The NormalizeTopMosts method makes forms that have been designated as topmost forms (their FormStyle is fsStayOnTop) behave as if they were not topmost forms. You'll find this method convenient to use if you want a message box or dialog box to appear on top of a topmost form.

For example, while you do not have to call NormalizeTopMosts to use the Delphi methods and functions that display message boxes (such as MessageBox and MessageDlg), you should call it if you want to call Windows API functions directly to display a message box. If you neglect to call NormalizeTopMosts, the message box won't display on top of the form, but the form remains on top. Any time you call Windows API functions to display a window on top of a form, call NormalizeTopMosts first.

To return the forms designated as fsStayOnTop to be topmost again, call RestoreTopMosts.


Example

The following code normalizes topmost forms before calling the MessageBox function in the WinProcs unit. After the message box is closed, the topmost forms are restored.

begin

  Application.NormalizeTopMosts;

  MessageBox(Form1.Handle, 'This should be on top.', 'Message Box', MB_OK);

  Application.RestoreTopMosts;

end;


See also

FormStyle property

RestoreTopMosts method


Notify property

Example

Applies to

TMediaPlayer component

Declaration

property Notify: Boolean;

Description

Run-time only. The Notify property determines whether the next call to a media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop) generates an OnNotify event when the method has completed.

If Notify is True, the next media control method generates OnNotify event upon completion and stores the notification message in the NotifyValue property. If Notify is False, the method does not generate an OnNotify event and NotifyValue remains unchanged.

Notify affects only the next call to a media control method. After an OnNotify event, Notify must be reset to affect any subsequent media control methods.

By default, Play and StartRecording function as if Notify is True. You must set Notify to False before calling Play or StartRecording to prevent an OnNotify event from being generated when playing or recording has finished. By default, all other media control methods function as if Notify is False.

Note:	Set Notify to True if the next media control is expected to take a long time, so your application is notified when the media control method has completed. If you set Notify to True, you might want to set Wait to False so that control returns to the application before the media control method is finished.

Note:	If you try to resume a device that doesn't support Resume, the device is resumed as if you called the Play method. If you have assigned True to Notify before calling Resume (or any other media control method), Notify doesn't affect the call to Resume. Resume does not generate an OnNotify event upon completion, and NotifyValue remains unchanged.


Example

The following code sets Notify to True after opening and playing the Microsoft Video for the Windows file named DUCK.AVI. When the Play method is completed, an OnNotify event occurs, which displays a message.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    FileName := 'duck.avi';

    Open;

    Play;

    Notify := True;

  end;

end;

procedure TForm1.MediaPlayer1Notify(Sender: TObject);

begin

  if MediaPlayer1.NotifyValue=nvSuccessful then

    MessageDlg('Done playing video.', mtInformation, [mbOK], 0);

end;


NotifyValue property

See also	Example

Applies to

TMediaPlayer component

Declaration

property NotifyValue: TMPNotifyValues;

Description

Run-time and read-only. The NotifyValue property reports the result of the last media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop) that requested a notification. Set Notify to True before calling a media control method to request notification.

The following table lists the possible values for NotifyValue.

Value	Result

nvSuccessful	Command completed successfully

nvSuperseded	Command was superseded by another command

nvAborted	Command was aborted by the user

nvFailure	Command failed


Example

This example uses a media player component named MediaPlayer1. When the application runs, the code attempts to play a CD in the CD audio device, and displays a message dialog box indicating whether the attempt to play the CD was successful.

Before you can run this example, you must have a CD audio device installed correctly.

procedure TForm1.FormCreate(Sender: TObject);

begin

  with MediaPlayer1 do

  begin

    DeviceType := dtCDAudio;

    Open;

    Play;

    if NotifyValue <> nvSuccessful then

      MessageDlg('Error playing CD audio', mtError, [mbOk], 0)

    else

      MessageDlg('Playing CD audio', mtInformation, [mbOk], 0);

    Visible := False;

  end;

end;


See also

OnNotify event


Numbering property

See also	Example

Applies to

TParaAttributes object

Declaration

property Numbering: TNumberingStyle;

Description

The Numbering property contains the value specifying numbering options in the currently selected paragraph in a TRichEdit control. These values essentially affect the indentation of the paragraph. These are the possible values:

Value	Meaning

nsNone	No indenting on the left.

nsBullet	Bullet style numbering is specified. Indent sufficiently for bullets..


Example

The following example sets the numbering property of the currently selected paragraph in RichEdit1. If BulletsButton is depressed, then the paragraph is indented sufficiently for bullets.

RichEdit1.Paragraph.Numbering := TNumberingStyle(BulletsButton.Down);


See also

Paragraph property


NumGlyphs property

See also	Example

Applies to

TBitBtn, TSpeedButton components

Declaration

property NumGlyphs: TNumGlyphs;

Description

The NumGlyphs property indicates the number of images that are in the graphic specified in the Glyph property for use on a bitmap button or speed button.

If you have multiple images in a bitmap, you must specify the number of images that are in the bitmap with the NumGlyphs property. All images must be the same size and next to each other in a row. Valid NumGlyphs values are 1 to 4. The default value is 1.

You can provide up to four images on a bitmap button or speed button with a single bitmap. Delphi then displays one of these images depending on the state of the button. Only one image is required in a bitmap.

Image position in bitmap	Speed button state	Description

First	Up	This image appears when the button is unselected. If no other images exist in the bitmap, Delphi uses this image for all other images.

Second	Disabled	This image usually appears dimmed and indicates that the button can't be selected.

Third	Down	This image appears when a button is clicked. The up state image then reappears when the user releases the mouse button.

Fourth	Stay down	This image appears when a button stays down indicating that it remains selected.

If only one image is present, Delphi attempts to represent the other states by altering the image slightly for the different states, although the stay down state is always the same as the up state. If you aren't satisfied with the results, you can provide additional images in the bitmap.


Example

This example uses a speed button and a label on a form. When the example runs, the number of images in the specified bitmap appears as the caption of the label.

procedure TForm1.FormActivate(Sender: TObject);

begin

  SpeedButton1.Glyph.LoadFromFile('C:\WINDOWS\CARS.BMP');

  Label1.Caption := IntToStr(SpeedButton1.NumGlyphs) + ' image(s)';

end;


See also

Glyph property


ObjectMenuItem property

Example

Applies to

TForm component

Declaration

property ObjectMenuItem: TMenuItem;

Description

ObjectMenuItem is used to specify the OLE object menu item. If you create a menu item and specify it as the OLE object menu item with the ObjectMenuItem property, the item is automatically enabled when an OLE object in an OLE container is selected.

The OLE object menu item can be used to activate or convert the selected object. All you need to do is specify the menu item in the ObjectMenuItem component. The processing of activating or converting the object is handled by the OLE server application.


Example

The following code assigns MyObject1 to the ObjectMenuItem property of Form1. When an OLE container that contains an object is selected, the caption of the MyObject1 menu item can be modified by the OLE server and the functionality of MyObject1 will be handled by the server.

Form1.ObjectMenuItem := MyObject1;


Objects property

Applies to

TStringList, TStrings objects; TStringGrid component

Description

Run-time only. The Objects property associates an object with another object or component.

Objects Property for String Lists

Objects Property for String Grids


Objects property for string lists
Objects property

See also	Example

Applies to

TStringList, TStrings objects

Declaration

property Objects[Index: Integer]: TObject;

Description

Run-time only. The Objects property gives you access to an object in the list of objects associated with the list of strings. Each string in the list of strings can have an associated object.

The most common use of objects in a string and string list objects is to associate bitmaps with strings so that you can use the bitmaps in owner-draw controls. For example, if you have an owner-draw list box, you can add a string 'Banana' and a bitmap of a banana to the Items property of the list box using the AddObject method. You can then access the 'Banana' string using the Strings property or the bitmap using the Objects property.

Specify the object you want to access with its position in the list as the value of the Index parameter. The index is zero-based, so the first object in the list of objects has a value of 0, the second object has a value of 1, and so on.

To associate an object with an existing string, assign the object to the Objects property using the same index as that of the existing string in the Strings property. For example, if a string object named Fruits contains the string 'Banana' and an existing bitmap of a banana called BananaBitmap, you could make the following assignment:

Fruits.Objects[Fruits.IndexOf('Banana')] := BananaBitmap;


Example

The following code allows the user to specify a bitmap file with the OpenDialog1 open dialog box component when Form1 is created. Then, the bitmap file specified is added to the Items list of ListBox1.

If ListBox1 is an owner-draw control (specified by a Style property of lbOwnerDrawFixed or lbOwnerDrawVariable), the second procedure is the OnDrawItem event handler for ListBox1. The bitmap in the Object property and the text of an item are retrieved and displayed in Listbox1.

procedure TForm1.FormCreate(Sender: TObject);

var

  TheBitmap: TBitmap;

begin

  if OpenDialog1.Execute then

  begin

    TheBitmap := TBitmap.Create;

    TheBitmap.LoadFromFile(OpenDialog1.FileName);

    ListBox1.Items.AddObject(OpenDialog1.FileName, TheBitmap);

  end;

end;

procedure TForm1.ListBox1DrawItem(Control: TWinControl; Index: Integer;

  Rect: TRect; State: TOwnerDrawState);

var

  DrawBitmap: TBitmap;

begin

  DrawBitmap := TBitmap(ListBox1.Items.Objects[Index]);

  with ListBox1.Canvas do

  begin

    Draw(Rect.Left, Rect.Top + 4, DrawBitmap);

    TextOut(Rect.Left + 2 + DrawBitmap.Width, Rect.Top + 2, ListBox1.Items[Index]);

  end;

end;


See also

AddObject method

InsertObject method

IndexOf method

IndexOfObject method


Objects Property for String Grids
Objects property

See also	Example

Applies to

TStringGrid component

Declaration

property Objects [ACol, ARow: Integer]: TObject;

Description

Run-time only. The Objects property is an array of objects, one for each cell in the grid. The ColCount and RowCount values define the size of the array of objects. Use the Objects property to access an object within a particular cell. ACol is the column coordinate of the cell, and ARow is the row coordinate of the cell.

If you put an object into the Objects array, the object will still exist even if the string grid is destroyed. You must destroy the object explicitly.


Example

The following code stores a TBitmap object called MyBitmap in row 3, column 10 of StringGrid1.

StringGrid1.Objects[10, 3] := MyBitmap;


See also

Cells property

Cols property

Free method

Rows property


OEMConvert property

Applies to

TEdit, TMemo components

Declaration

property OEMConvert: Boolean;

Description

The OEMConvert property determines whether the text in the control is converted to OEM characters. If True, the text is converted. If False, the characters remain as ANSI characters. The default value is False. You should have the text converted to OEM characters if the text consists of filenames.


OldValue property

See also

Applies to

All field components

Declaration

property OldValue: Variant;

Description

Run-time and read-only. The OldValue property represents the original value of the field (as a Variant) before any pending cached updates changed it. Once cached updates are applied successfully, it's not possible to retrieve the old field value. Cached updates must be enabled to access the OldValue property.


See also

CachedUpdates property

NewValue property


OnActivate event

Applies to

TApplication, TForm, TOleContainer components

Description

An OnActivate event occurs when a component becomes active.

OnActivate event for forms

OnActivate event for applications

OnActivate event for Ole Containers


OnActivate event

Applies to

TOleContainer component

Declaration

property OnActivate: TNotifyEvent;

Description

Occurs when the OLE object is inplace activated. Doesn't occur when the OLE object is activated in another window.


event_TFormOnActivate
OnActivate event

See also	Example

Applies to

TForm components

Declaration

property OnActivate: TNotifyEvent;

Description

The OnActivate event for a form occurs when the form becomes active. A form becomes active when focus is transferred to it (when the user clicks on the form, for example).

For MDI child windows (forms with FormStyle property values of fsMDIChild), OnActivate occurs only when focus is shifted from one child to another. If focus is shifted from a non-MDI child window to an MDI child, the OnActivate event occurs for the MDI parent form.

Note:	The OnActivate event of the application (TApplication), not the form, occurs when Windows switches control from another application to your application.


Example

The following code adds the caption of Form2 to a list box in Form1 when a Form2 is activated. To refer to Form1 in Form2's OnActivate event handler you must include the name of the unit in which Form1 is declared to a uses clause in Form2's unit. To avoid a circular unit reference (if Form2 is already referenced by Form1's uses clause), put the new uses clause in the implementation section of Form2's unit.

procedure TForm2.FormActivate(Sender: TObject);

begin

  Form1.ListBox1.Items.Add(Screen.ActiveForm.Caption);

end;


See also

ActiveForm property

Show method

ShowModal method


event_TApplicationOnActivate
OnActivate event

See also	Example

Applies to

TApplication component

Declaration

property OnActivate: TNotifyEvent;

Description

The OnActivate event for an application occurs when the application becomes active. Your application becomes active when it is initially run or when focus is shifted from another Windows application to your application.

Note:	See Handling Application Events for more information about creating event handlers for application events.


Example

The following code is the entire unit which assigns the ApplicationActivate procedure to the OnActivate event of the application. Note that ApplicationActivate is declared as a method of Form1. The code that you add is notes with comments. The rest of the code is generated by Delphi.

unit Unit1;

interface

uses

  SysUtils, WinTypes, WinProcs, Messages, Classes, Graphics, Controls,

  Forms, Dialogs;

type

  TForm1 = class(TForm)

    procedure ApplicationActivate(Sender: TObject);   {Add this declaration line}

    procedure FormCreate(Sender: TObject);

  private

    { Private declarations }

  public

    { Public declarations }

  end;

var

  Form1: TForm1;

implementation

{$R *.DFM}

procedure TForm1.ApplicationActivate(Sender: TObject); {Write this procedure}

begin

  {Put code for your Application.OnActivate here}

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnActivate := ApplicationActivate;       {Write this line of code}

end;

end.


See also

Application variable

OnDeactivate event


OnActiveControlChange event

See also	Example

Applies to

TScreen component

Declaration

property OnActiveControlChange: TNotifyEvent;

Description

The OnActiveControlChange event occurs when the focus on the screen shifts from one control to another. This change in focus means that a new control is now the value of the ActiveControl property of the screen. Use the OnActiveControlChange event to specify special processing you want to occur just before the new control becomes the active control.


Example

This example uses an edit box and a memo on a form. When the user switches the focus between the two controls, the control that currently has the focus becomes red:

type

  TForm1 = class(TForm)

    Edit1: TEdit;

    Memo1: TMemo;

    Button1: TButton;

    procedure FormCreate(Sender: TObject);

  private

    { Private declarations }

  public

    procedure ColorControl(Sender: TObject);

  end;

var

  Form1: TForm1;

implementation

{$R *.DFM}

procedure TForm1.ColorControl(Sender: TObject);

begin

  if Edit1.Focused then

    Edit1.Color := clRed

  else

    Edit1.Color := clWindow;

  if Memo1.Focused then

    Memo1.Color := clRed

  else

    Memo1.Color := clWindow;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Screen.OnActiveControlChange := ColorControl;

end;


See also

ActiveControl property

ActiveForm property

OnActiveFormChange event


OnActiveFormChange event

See also	Example

Applies to

TScreen component

Declaration

property OnActiveFormChange: TNotifyEvent;

Description

The OnActiveFormChange event occurs when a new form becomes the active form on the screen (the form becomes the value of the ActiveForm property). Use the OnActiveFormChange event to specify any special processing to occur just before a new form becomes the active form.


Example

This example uses a two forms with a button on the first form. When the user clicks the button, the second form appears. As the user switches between forms, the form that is active is colored aqua:

type

  TForm1 = class(TForm)

    Button1: TButton;

    procedure FormCreate(Sender: TObject);

    procedure Button1Click(Sender: TObject);

  private

    { Private declarations }

  public

    procedure ColorForm(Sender: TObject);

  end;

var

  Form1: TForm1;

implementation

{$R *.DFM}

uses Unit2;

procedure TForm1.ColorForm(Sender: TObject);

begin

  Color := clBtnFace;

  Form2.Color := clBtnFace;

  Screen.ActiveForm.Color := clAqua;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Screen.OnActiveFormChange := ColorForm;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form2.Show;

end;


See also

ActiveForm property

OnActiveControlChange event


OnApply event

See also	Example

Applies to

TFontDialog component

Declaration

TFDApplyEvent = procedure(Sender: TObject; Wnd: HWND) of object;

property OnApply: TFDApplyEvent

Description

The OnApply event occurs when the user clicks the Apply button in the Font dialog box to apply the selected font to a component. The Apply button won't appear in the Font dialog box unless the form has an OnApply event handler.

The TFDApplyEvent type points to a method that performs an action when the user chooses the Apply button in the Font dialog box.


Example

This code displays the Font dialog box and puts an Apply button in it. When the user clicks the Apply button, the font selected in the dialog box is applied to the Button1 button while the dialog box is still open.

procedure TForm1.Button1Click(Sender: TObject);

begin

  FontDialog1.Execute;

end;

procedure TForm1.FontDialog1Apply(Sender: TObject; Wnd: Word);

begin

  Button1.Font := FontDialog1.Font;

end;


See also

Execute method

Font property


OnCalcFields event

Applies to

TTable, TQuery, TStoredProc components

Declaration

property OnCalcFields: TDataSetNotifyEvent;

Description

The OnCalcFields event is used to set the values of calculated fields. OnCalcFields is called when a dataset reads a record from the database. In addition, if the dataset's AutoCalcFields property is True, OnCalcFields is called when a non-calculated field is modified while the dataset is in Edit or Insert state.

Typically, the OnCalcFields event will be called often, so it should be kept short. OnCalcFields should not perform any actions that modify the dataset (or the linked dataset if it is part of a master-detail relationship), because this can lead to recursion.

While the OnCalcFields event is executed, a dataset will be put in CalcFields state. When a dataset is in CalcFields state, you cannot set the values of any fields other than calculated fields. After OnCalcFields is completed, the dataset will return to its previous state.

The first call to the OnCalcFields event handler may occur before all components in your application have been initialized. If your handler requires access to another component, use the Edit|Creation Order command to ensure that the components are created in the correct order.


OnChange event

Applies to

TBitmap, TBrush, TCanvas, TFont, TGraphic, TGraphicsObject, TMetafile, TPen, TPicture, TStringList, TChangeLink, TConversion objects; TBCDField, TBlobField, TBooleanField, TBytesField, TComboBox, TCurrencyField, TDateField, TDateTimeField, TDBComboBox, TDBEdit, TDBLookupCombo, TDBMemo, TDBRadioGroup, TDDEClientItem, TDDEServerItem, TDirectoryListBox, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TFloatField, TGraphicField, TIntegerField, TListView, TMaskEdit, TMemo, TMemoField, TPageControl, TQuery,TRichEdit, TScrollBar, TSmallintField, TStringField, TTabControl, TTable, TTabSet, TTimeField, TTrackBar, TTreeView, TVarBytesField, TWordField components

Description

An OnChange event occurs when an object or component changes.

OnChange Event for Tab Set Controls

OnChange Event for Tree Views

OnChange Event for List Views

OnChange Event for Image Lists

OnChange Event for DDE Client Item and DDE Server Item Controls

OnChange Event for Data-aware Controls

OnChange Event for Field Components

OnChange Event for ChangeLink objects

OnChange Event for All Other Components and Objects


OnChange event

Applies to

TChangeLink object

Declaration

property OnChange : TNotifyEvent

Description

Runtime only. The OnChange event occurs when there's a change  in any of the images stored in the associated image list component. Use the OnChange event to notify a control that uses the images in the image list.


OnChange event for tab set controls
OnChange event

Example

Applies to

TTabControl, TTabSet control

Declaration

property OnChange: TNotifyEvent;

Description

The OnChange event occurs just before a new tab is selected (the TabIndex value is about to change). To prevent theTabIndex value from changing, you need to write code in the OnChange event handler to stop it from doing so.


Example

The following code uses a check box and a tab set control on a form. If the check box is checked, another tab on the tab set can't be selected.

procedure TForm1.TabSet1Change(Sender: TObject; NewTab: Integer;

  var AllowChange: Boolean);

begin

  AllowChange := not CheckBox1.Checked;

end;


OnChange event for DDE components
OnChange event

Example

Applies to

TDDEClientItem, TDDEServerItem components

Declaration

property OnChange: TNotifyEvent;

Description

An OnChange event occurs when the value of the Text or Lines property of a DDE client item or DDE server item component changes.

If the value changed is that of a DDE client item component, the DDE server application continuously updates the Text and Lines properties of the DDE client item component.

If the value changed is that of a DDE server item component, your application can change the Text or Lines property of the DDE server item component by assigning a new value to it. The DDE client can change Text or Lines by poking data (transferring data from the DDE client to the DDE server). See the documentation of the DDE client application for information about how data is poked. Delphi DDE client applications poke data using the PokeData method.


Example

The following code updates the contents of an edit box with the linked text from a DDE server when the data is updated.

procedure TForm1.DdeClientItem1Change(Sender: TObject);

begin

  Edit1.Text := DDEClientItem1.Text;

end;


OnChange event

Example

Applies to

TDBComboBox, TDBEdit, TDBLookupCombo, TDBMemo, TTable, TDBRadioGroup components

Declaration

property OnChange: TNotifyEvent;

Description

The OnChange event for data-aware controls occurs when the contents of the field the control is accessing changes. Specify any special processing you want to occur at that time in the OnChange event handler


Example

The following code displays a message if the data accessed by DBMemo1 changes.

procedure TForm1.DBMemo1Change(Sender: TObject);

begin

  MessageDlg('Data has changed',mtInformation,[mbOK],0);

end;


OnChange event

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTabControl, TTabSet, TTimeField, TVarBytesField, TWordField components

Declaration

TFieldNotifyEvent = procedure(Sender: TField) of object;

property OnChange: TFieldNotifyEvent;

Description

OnChange is activated when the contents of the field are modified. If a data-aware control is linked to the field, OnChange is not activated until the control attempts to store the changes into the current record.

You can take any special actions required by the event by assigning a method to this property.

The TFieldNotifyEvent type points to a method that handles the validation of data in a field or handles the changing of data in a field.


Example

Field1.OnChange := CapitalizeFirstLetter;


OnChange event for listview controls
OnChange event

See also

Applies to

TListView component

Declaration

TLVChangeEvent = procedure (Sender: TObject; Item: TListItem; Change: TItemChange) of object;

property OnChange: TLVChangeEvent;

Description

The OnChange event occurs whenever the selection has changed from one item to another, or its state, text, or image has changed.


See also

OnChanging event, Selected property, Focused property


OnChange event for tree views
OnChange event

See also

Applies to

TTreeView component

Declaration

TTVChangedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnChange: TTVChangedEvent;

Description

The OnChange event occurs whenever the selection has changed from one item to another.

The TTVChangedEvent type points to a method that is called when the selection has changed from one item to another (OnChange event) in the TTreeView component.


See also

OnChanging event

Selected property


OnChange event

See also

Applies to

TImageList object

Declaration

property OnChange: TNotifyEvent;

Description

The OnChange event is called when the ImageList changes.  Note that any objects registered with the RegisterChanges method will also be notified.


See also

RegisterChanges method

UnRegisterChanges method


OnChange event

See also	Example

Applies to

TBitmap, TBrush, TCanvas, TFont, TGraphic, TGraphicsObject, TMetafile, TPen, TPicture, TStringList, TConversion objects; TComboBox, TDirectoryListBox, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TMaskEdit, TMemo, TPageControl, TRichEdit, TScrollBar, TTrackBar, components

Declaration

property OnChange: TNotifyEvent;

The OnChange event specifies which event handler should execute when the contents of a component or object changes.

For graphics objects, OnChange occurs when the specific graphics item encapsulated by the object changes. For example, the OnChange event for a pen occurs when the Color, Mode, Style, or Width properties of the TPen object are modified.

For components, OnChange occurs when the main value or values of the component are modified. For example, OnChange occurs when the Text property of an edit box is modified.

For combo boxes, the OnChange event also occurs when an item is selected in the drop down list.

For string list objects, the OnChange event occurs when a change to a string stored in the list of strings changes.


Example

This example uses a color grid on a form. The color grid is a component on the Samples page of the Component palette. When the user clicks a color rectangle or drags the mouse cursor across the color grid, the color of the form changes.

procedure TForm1.ColorGrid1Change(Sender: TObject);

begin

  Color := ColorGrid1.ForegroundColor;

end;


See also

OnChanging event


OnChanging event

Applies to

TCanvas object; TListView, TTreeView, TTabControl, TUpDown,TPageControl components

Description

OnChanging event for Canvases

OnChanging event for List Views

OnChanging event for Tree Views

OnChanging event for TPageControl and TTabControl components

OnChanging event for TUpDown components


OnChanging property

Applies to

TCanvas object

Declaration

property OnChanging: TNotifyEvent;

Description

An OnChanging event occurs immediately before the graphic contained in the canvas is modified.


OnChanging event for listview controls
OnChanging event

Applies to

TUpDown components

Declaration

TUDChangingEvent = procedure (Sender: TObject; var AllowChange: Boolean) of object;

property OnChanging: TUDChangingEvent;

Description

The OnChanging event occurs when the value of Position is changed by clicking on the Up or Down arrow buttons. The change can then be allowed or disallowed.

TUDChangingEvent is the type of the OnChanging event of the TUpDown component.


OnChanging event for listview controls
OnChanging event

Example

Applies to

TTabControl , TPageControl component

Declaration

TTabChangingEvent = procedure (Sender: TObject; var AllowChange: Boolean) of object;

property OnChanging: TTabChangingEvent;

Description

The OnChanging event occurs when a new tab is selected, before focus shifts to the new tab. The change can be allowed or disallowed.

TTabChangingEvent is the type of the OnChanging vent of the TTabControl and TPageControl components.


Example

The following code prevents the tab from changing:

procedure TForm1.TabControl1Changing(Sender: TObject; var AllowChange: Boolean);

begin

  AllowChange := False;

end;


OnChanging event for listview controls
OnChanging event

See also

Applies to

TListView component

Declaration

TLVChangingEvent = procedure (Sender: TObject; Item: TListItem; Change: TItemChange) of object;

property OnChanging: TLVChangingEvent;

Description

The OnChanging event occurs when the selection is about to change from one item to another, or its state, text or image is about to change.


See also

OnChange event

Selected property

Focused property


OnChanging event

See also

Applies to

TTreeView component

Declaration

TTVChangingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowChange: Boolean) of object;

property OnChanging: TTVChangingEvent;

Description

The OnChanging event occurs whenever the selection is about to be changed from one item to another.

The TTVChangingEvent type points to a method that is called when the selection is about to be changed from one item to another (OnChanging event) in the TTreeView component. The AllowChange parameter determines whether the change is permitted. If AllowChange is set to False, the user won't be able to select this item.


See also

OnChange event

Selected property


OnClick event

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBNavigator, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TFileListBox, TFilterComboBox, TForm, TGroupBox, TImage, TLabel, TListBox, TListView, TMaskEdit, TMediaPlayer, TMemo, TMenuItem, TNotebook, TOutline, TPaintBox, TPanel, TRadioButton, TScrollBar, TScrollBox, TSpeedButton, TStatusBar, TStringGrid, TTabSet, TTreeView, TUpDown components

Description

An OnClick event occurs when the user clicks the component.

OnClick Event for the Media Player Component

OnClick Event for the Database Navigator Component

OnClick Event for Forms and Other Components

OnClick Event for UpDown Controls


OnClick event

See also	Example

Applies to

TMediaPlayer component

Declaration

EMPNotify = procedure (Sender: TObject; Button: TMPBtnType; var DoDefault: Boolean) of object;

property OnClick: EMPNotify;

Description

An OnClick event occurs when the user presses and releases the mouse button while the mouse pointer is over one of the control buttons of the media player control, or when the user presses Spacebar while the media player control has focus. When the media player control has focus and the Spacebar is pressed, the user can use the Left Arrow or Right Arrow keys to select which control button to click.

The EMPNotify type is a pointer to a method that is called when an OnClick event for a TMediaPlayer components occurs. The . Button argument can be one of the following values: btBack, btEject, btNext, btPause, btPlay, btPrev, btRecord, btStep, or btStop.

The default value of the DoDefault argument is True. If DoDefault is True, the media player control calls the method that corresponds to the clicked button. For example, if the user clicks the Play button (btPlay), the Play method is called.

If DoDefault is False, you must supply the code that executes when a media player control button is clicked in the OnClick event handler. The following table lists the default methods corresponding to the media player control buttons:

Control button	Button value	Method called

Play	btPlay	Play

Record	btRecord	StartRecording

Stop	btStop	Stop

Next	btNext	Next

Prev	btPrev	Previous

Step	btStep	Step

Back	btBack	Back

Pause	btPause	Pause

Eject	btEject	Eject


Example

This example uses a label and a media player on a form. When the user clicks one of the media player buttons, the caption of the label indicates which button was clicked. For this example to run successfully, you must have a CD audio device installed correctly.

procedure TForm1.FormCreate(Sender: TObject);

begin

  MediaPlayer1.DeviceType := dtCDAudio;

  MediaPlayer1.Open;

  MediaPlayer1.Left := 20;

  MediaPlayer1.Top := 12;

  Label1.Top := 44;

  Label1.Left := 20;

  Label1.Color := clYellow;

  Label1.Font.Name := 'Arial';

  Label1.Caption := 'Click Me';

end;

procedure TForm1.MediaPlayer1Click(Sender: TObject; Button: TMPBtnType;

  var DoDefault: Boolean);

begin

  case Button of

    btPlay :

    begin

      Label1.Caption := 'Playing';

      Label1.Left := 20;

    end;

    btPause:

    begin

      Label1.Caption := 'Paused';

      Label1.Left := 48;

    end;

    btStop:

    begin

      Label1.Caption := 'Stopped';

      Label1.Left := 76;

    end;

    btNext:

    begin

      Label1.Caption := 'Next';

      Label1.Left := 104;

    end;

    btPrev:

    begin

      Label1.Caption := 'Previous';

      Label1.Left := 132;

    end;

    btEject:

    begin

      Label1.Caption := 'Eject';

      Label1.Left := 244;

    end;

  end;

end;


See also

OnPostClick event


OnClick event

Example

Applies to

TDBNavigator component

Declaration

ENavClick = procedure (Sender: TObject; Button: TNavigateBtn) of object;

property OnClick: ENavClick;

Description

The OnClick event occurs when the user presses and releases the mouse button with the mouse pointer over one of the database navigator control buttons, or when the user presses Spacebar while the navigator has focus. Calling the Click method also triggers OnClick.

The ENavClick type is a pointer to a method that is called when the user clicks a navigator button. Sender points to the navigator whose button was clicked. Button specifies the control button the user clicked.


Example

The following code determines which database navigator button was clicked and displays a message identifying the name of the button.

procedure TForm1.DBNavigator1Click(Sender: TObject; Button: TNavigateBtn);

var

  BtnName: string;

begin

  case Button of

    nbFirst  : BtnName := 'nbFirst';

    nbPrior  : BtnName := 'nbPrior';

    nbNext   : BtnName := 'nbNext';

    nbLast   : BtnName := 'nbLast';

    nbInsert : BtnName := 'nbInsert';

    nbDelete : BtnName := 'nbDelete';

    nbEdit   : BtnName := 'nbEdit';

    nbPost   : BtnName := 'nbPost';

    nbCancel : BtnName := 'nbCancel';

    nbRefresh: BtnName := 'nbRefresh';

  end;

  MessageDlg(BtnName + ' button clicked.', mtInformation, [mbOK], 0);

end;


OnClick event

Applies to

TUpDown component

Declaration

TUDClickEvent = procedure (Sender: TObject; Button: TUDBtnType) of object;

property OnClick: TUDClickEvent;

Description

The OnClick event indicates whether either of the two buttons of a TUpDown control was clicked. The TUDClickEvent return type for this event has a button parameter that indicates whether the selected button was the right or up arrow key, or the left or down arrow key.


OnClick event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TFileListBox, TFilterComboBox, TForm, TGroupBox, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TMenuItem, TNotebook, TOutline, TPaintBox, TPanel, TRadioButton, TScrollBar, TScrollBox, TSpeedButton, TStatusBar, TStringGrid, TTabSet, TUpDown components

Declaration

property OnClick: TNotifyEvent;

Description

The OnClick event occurs when the user clicks the component. Typically, this is when the user presses and releases the primary mouse button with the mouse pointer over the component. This event can also occur when

The user selects an item in a grid, outline, list, or combo box by pressing an arrow key.

The user presses Spacebar while a button or check box has focus.

The user presses Enter when the active form has a default button (specified by the Default property).

The user presses Esc when the active form has a cancel button (specified by the Cancel property).

The user presses the accelerator key for a button or check box. For example, if the value of the Caption property of a check box is '&Bold', the B is underlined at run time and the OnClick event of the check box is triggered when the user presses Alt+B.

The Checked property of a radio button is set to True.

The value of the Checked property of a check box is changed.

The Click method of a menu item is called.

For a form, an OnClick event occurs when the user clicks a blank area of the form or on a disabled component.


Example

The form in this example changes color each time the user clicks it:

procedure TForm1.FormClick(Sender: TObject);

begin

  Randomize;

  Color := Random(65535);

end;


See also

Click method

OnDblClick event


OnClose event

Applies to

TDDEClientConv, TForm components

Description

An OnClose event occurs when a form or DDE conversation is closed.

OnClose Event for Forms

OnClose Events for DDE Components


OnClose event

See also	Example

Applies to

TForm component

Declaration

TCloseAction = (caNone, caHide, caFree, caMinimize);

TCloseEvent = procedure(Sender: TObject; var Action: TCloseAction) of object;

property OnClose: TCloseEvent;

Description

The OnClose event specifies which event handler to call when a form is about to close. The handler specified by OnClose might, for example, test to make sure all fields in a data-entry form have valid contents before allowing the form to close.

A form is closed by the Close method or when the user chooses Close from the form's system menu.

The TCloseEvent type points to a method that handles the closing of a form. The value of the Action parameter determines if the form actually closes. These are the possible values of Action::

Value	Meaning

caNone	The form is not allowed to close, so nothing happens.

caHide	The form is not closed, but just hidden. Your application can still access a hidden form.

caFree	The form is closed and all allocated memory for the form is freed.

caMinimize	The form is minimized, rather than closed. This is the default action for MDI child forms.

If a form is an MDI child form, and its BorderIcons property is biMinimize, then the default Action is caMinimize. If a MDI child form does not have these settings, the default Action is caNone, meaning that nothing happens when the user attempts to close the form.

If a form is an SDI child form, Action defaults to caHide.

To close and form and free it in an OnClose event, set Action to caFree.


Example

This example displays a message dialog box when the user attempts to close the form. If the user clicks the Yes button, the form closes; otherwise, the form remains open.

procedure TForm1.FormClose(Sender: TObject; var Action: TCloseAction);

begin

  if MessageDlg('Close application ?', mtConfirmation,

    [mbYes, mbNo], 0) = mrYes then

    Action := caFree

  else

    Action := caNone;

end;


See also

OnCloseQuery event

OnOpen event


OnClose property

Example

Applies to

TDDEClientConv component

Declaration

property OnClose: TNotifyEvent;

Description

An OnClose event occurs when a DDE conversation is terminated. A conversation is terminated when one of the applications involved is closed, or when the CloseLink method is called.


Example

The following code displays a message when a conversation is closed.

procedure TForm1.DdeClientConv1Close(Sender: TObject);

begin

  MessageDlg('This conversation is finished!', mtInformation, [mbOK],0);

end;


OnCloseQuery event

See also	Example

Applies to

TForm component

Declaration

TCloseQueryEvent = procedure(Sender: TObject; var CanClose: Boolean) of object;

property OnCloseQuery: TCloseQueryEvent;

Description

The OnCloseQuery event occurs when an action to close the form takes place--that is, when the Close method is called or when the user chooses Close from the form's System menu. An OnCloseQuery event handler contains a Boolean CanClose variable that determines whether a form is allowed to close. It's default value is True.

You can use an OnCloseQuery event handler to ask users if they are sure they really want the form closed immediately. For example, you can use the handler to display a message box that prompts the user to save a file before closing the form.

The TCloseQueryEvent type points to the method that determines whether a form can be closed. The value of the CanClose parameter determines if the form can close or not.


Example

When the user attempts to close the form in this example, a message dialog appears that asks the user if it is OK to close the form. If the user chooses the OK button, the form closes. If the user chooses Cancel, the form doesn't close.

procedure TForm1.FormCloseQuery(Sender: TObject; var CanClose: Boolean);

begin

  if MessageDlg('Close the form?', mtConfirmation,

    [mbOk, mbCancel], 0) = mrCancel then

     CanClose := False;

end;


See also

Close method

OnClose event


OnColEnter event

See also	Example

Applies to

TDBGrid component

Declaration

property OnColEnter: TNotifyEvent;

Description

The OnColEnter event occurs when the user clicks a cell in a column or moves to a column with the Tab key within the data grid. Use the OnColEnter event to specify any processing you want to occur as soon as a column is entered.


Example

The following code concatenates an asterisk to the display label of a field when the column is entered.

procedure TForm1.DBGrid1ColEnter(Sender: TObject);

begin

  with DBGrid1.SelectedField do

    DisplayLabel := '* ' + DisplayLabel;

end;


See also

OnColExit event


OnColExit event

See also	Example

Applies to

TDBGrid component

Declaration

property OnColExit: TNotifyEvent;

Description

The OnColExit event occurs when the user uses the Tab key to move out of a column or clicks a cell in another column. Use the OnColExit event to specify any special processing you want to occur when exiting the column.


Example

The following code deletes the first two characters from the display label of the selected field when exiting a column. Note that FirstTime is a Boolean field that prevents characters from being deleted the first time a column is exited. Use this code in conjunction with code in the example of OnColEnter to modify the appearance of the display label of columns while they are entered.

procedure TForm1.DBGrid1ColExit(Sender: TObject);

var

  TheLabel: string;

begin

  if FirstTime then

    FirstTime := False

  else

  begin

    with DBGrid1.SelectedField do

    begin

      TheLabel := DisplayLabel;

      Delete(TheLabel, 1, 2);

      DisplayLabel := TheLabel;

    end;

  end;

end;

See also

OnColExit event


OnCollapse event

See also	Example

Applies to

TOutline component

Declaration

EOutlineChange = procedure (Sender: TObject; Index: LongInt) of object;

property OnCollapse: EOutlineChange;

Description

An OnCollapse event occurs when an expanded outline item that has subitems is collapsed. An expanded outline item is collapsed when the user double-clicks it at run time, when the FullCollapse method is called, or when its Expanded property is set to False. When collapsed, the subitems no longer appear in the outline. Also, the plus picture or closed picture for the parent item is displayed if the appropriate OutlineStyle has been selected.

The EOutlineChange type is a pointer to a method that is called when an item in a TOutline component is changed by being expanded (OnExpand) or collapsed (OnCollapse). The Index parameter specifies the Index property value of the changed item.


Example

The following code displays the text from a collapsed outline item in a message dialog box.

procedure TForm1.Outline1Collapse(Sender: TObject; Index: Longint);

var

  TheStr: string;

begin

  TheStr :=  Outline1.Items[Index].Text;

  MessageDlg(TheStr+' has collapsed.', mtInformation, [mbOK],0);

end;


See also

OnExpand event

PictureClosed property

PicturePlus property


OnCollapsed event

See also

Applies to

TTreeView component

Declaration

TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnCollapsed: TTVExpandedEvent;

Description

The OnCollapsed event occurs after an item has been collapsed.


See also

OnCollapsing event

OnExpanded event

OnExpanding event

FullCollapse method

FullExpand method

Expanded property

Collapse method

Expand method


OnCollapsing event

See also

Applies to

TTreeView component

Declaration

TTVCollapsingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowCollapse: Boolean) of object;

property OnCollapsing: TTVCollapsingEvent;

Description

The OnCollapsing event occurs when an item is about to be collapsed.

The TTVCollapsingEvent type points to a method that is called when an item is about to be collapsed (OnCollapsing event). The AllowCollapse parameter determines whether the parent item can be collapsed. If AllowCollapse is set to False, the user won't be able to collapse the item.


See also

OnCollapsed event

OnExpanded event

OnExpanding event

FullCollapse method

FullExpand method

Expanded property

Collapse method

Expand method


OnColumnClick event

See also

Applies to

TListView component

Declaration

TLVColumnClickEvent = procedure(Sender: TObject; Column: TListColumn) of object;

property OnColumnClick: TLVColumnClickEvent;

Description

The OnColumnClick event occurs when the user clicks on a column header in a list view. ViewStyle must be set to vsReport and ColumnClick must be set to True.


See also

ViewStyle property

Columns property

ColumnClick property


OnColumnMoved event

See also	Example

Applies to

TDrawGrid, TStringGrid, TDBGrid components

Declaration

TMovedEvent = procedure (Sender: TObject; FromIndex, ToIndex: Longint) of object;

property OnColumnMoved: TMovedEvent;

Description

The OnColumnMoved event occurs when the user moves a column using the mouse. The user can move a column only if the Options property set includes the value goColMoving.

The TMovedEvent type points to a method that handles the moving of a column or row in a draw grid (TDrawGrid) or string grid (TStringGrid). The FromIndex parameter is the index of the column or row that is being moved, with the first column or row having an index value of 0. The ToIndex parameter value is the new location of the column or row after it is moved.


Example

The following code permits one column to be moved (assuming [goColMoving] is specified for the Options property at design time), then locks the columns by preventing any more moves.

procedure TForm1.StringGrid1ColumnMoved(Sender: TObject; FromIndex, ToIndex: Longint);

begin

  StringGrid1.Options := StringGrid1.Options - [goColMoving];

end;


See also

OnRowMoved event


OnCompare event

See also

Applies to

TListView, TTreeView components

Declaration

TLVCompareEvent = procedure(Sender: TObject; Item1, Item2: TListItem; Data: Integer; var Compare: Integer) of object;

TTVCompareEvent = procedure(Sender: TObject; Node1, Node2: TTreeNode; Data: Integer; var Compare: Integer) of object;

property OnCompare: TLVCompareEvent;

property OnCompare: TTVCompareEvent;

Description

The OnCompare event occurs when a request is made by the list view or tree view control's parent window to sort an item.

The TTVCompareEvent type points to a method that is called when two items in the tree view need to be compared (OnCompare event).


See also

SortType property, AlphaSort method, CustomSort method


OnCreate event

See also	Example

Applies to

TForm component

Declaration

property OnCreate: TNotifyEvent;

Description

The OnCreate event specifies which event handler to call when the form is first created. You can write code in the event handler that sets initial values for properties and does any processing you want to occur before the user begins interacting with the form.

Delphi creates a form when the application is run by calling the Create method.

When a form is being created and its Visible property is True, the following events occur in the order listed:

OnCreate

OnShow

OnActivate

OnPaint


Example

This very simple OnCreate event handler assures that the form is the same color as the Windows system color of your application workspace:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Color := clAppWorkSpace;

end;

Note:	The Color property in this example is not prefaced with the name of the form. If you write the statement like this,

Form1.Color := clAppWorkSpace;

the application won't run without error, because Form1 does not yet exist at the time this code is executed


.See also

OnActivate event

OnDestroy event

OnPaint event


OnDataChange event

See also

Applies to

TDataSource component

Declaration

TDataChangeEvent = procedure(Sender: TObject; Field: TField) of object;

property OnDataChange: TDataChangeEvent;

Description

The OnDataChange occurs when the State property changes from dsInactive, or when a data-aware control notifies the TDataSource that something has changed.

Notification occurs when the following items change because of field modification or scrolling to a new record: field component, record, dataset component, content, and layout. The Field parameter to the method may be nil if more than one of the fields changed simultaneously (as in a move to a different record). Otherwise, Field is the field which changed.

The TDataChangeEvent type points to a method that handles the changing of data in a data source component (TDataSource). The Field parameter is the field in which the data is changing. It is used by the OnDataChange event of the data source.


See also

OnStateChange event

State property


OnDblClick event

See also	Example

Applies to

TComboBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBNavigator, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TGroupBox, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPaintBox, TPanel, TRadioButton, TScrollBox, TSpeedButton, TStatusBar, TStringGrid, TTreeView components

Declaration

property OnDblClick: TNotifyEvent;

Description

The OnDblClick event occurs when the user double-clicks the mouse button while the mouse pointer is over the component.


Example

This example notifies the user that the form was double-clicked.

procedure TForm1.FormClick(Sender: TObject);

begin

  MessageDlg('You double-clicked the form', mtInformation, [mbOk], 0);

end;


See also

OnClick event


OnDeactivate event

Applies to

TApplication, TOleContainer components

Description

OnDeactivate event for Ole Containers

OnDeactivate event for Applications


OnDeactivate event for TOleContainer
OnDeactivate event

Applies to

TOleContainer component

Declaration

property OnDeactivate: TNotifyEvent;

Description

Occurs when the OLE object is inplace deactivated. Doesn't occur when the OLE object is deactivated from another window.


OnDeactivate for TApplication
OnDeactivate event

See also	Example

Applies to

TApplication component

Declaration

property OnDeactivate: TNotifyEvent;

Description

The OnDeactivate event occurs when the user switches from your application to another Windows application. Use the OnDeactive event to do any special processing you want to occur before your application is deactivated.

Note:	See Handling Application Events for more information about creating event handlers for application events.


Example

The following code minimizes an application when it's deactivated. Note that AppDeactivate should be declared a method of TForm1.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnDeactivate := AppDeactivate;

end;

procedure TForm1.AppDeactivate(Sender: TObject);

begin

  Application.Minimize;

end;


See also

OnActivate event


OnDeleteError event

Applies to

TTable, TQuery, TStoredProc components

Declaration

type
  TDataSetErrorEvent = procedure(DataSet: TDataSet; E: EDatabaseError;
  var Action: TDataAction) of object;

property OnDeleteError: TDataSetErrorEvent;

Description

The OnDeleteError event occurs when there was an error deleting a record from a dataset. The DataSet parameter is the dataset that had the problem. The E parameter is an EDatabaseError exception object that contains details about the problem. Action is a var parameter that lets you control how the error is handled when the event handler finishes.

TDataSetErrorEvent defines the type of the OnDeleteError event handler.


OnDeletion event

See also

Applies to

TListView, TTreeView components

Declaration

TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

TLVDeletedEvent = procedure (Sender: TObject; Item: TListItem) of object;

property OnDeletion: TTVExpandedEvent;

property OnDeletion: TLVDeletedEvent;

Description

The OnDeletion event occurs when an item in the tree view or list view is deleted.


See also

Delete method

DeleteChildren method

Deleting property


OnDestroy event

See also	Example

Applies to

TForm component

Declaration

property OnDestroy: TNotifyEvent;

Description

The OnDestroy event occurs when a form is about to be destroyed. A form is destroyed by the Destroy, Free, or Release methods, or when the main form of the application is closed.


Example

The following code explicitly allocates memory for a pointer in the OnCreate event of Form1, then releases the memory in the OnDestroy event. Assume that MyPtr is a Pointer type field of TForm1.

procedure TForm1.FormCreate(Sender: TObject);

begin

  New(MyPtr);

end;

procedure TForm1.FormDestroy(Sender: TObject);

begin

  Dispose(MyPtr);

end;


See also

OnCreate event


OnDragDrop event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBNavigator, TDBText, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TGroupBox, THeaderControl, TImage, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBar, TScrollBox, TShape, TStatusBar, TStringGrid, TTabControl, TTabSet, TTrackBar, TTreeView components

Declaration

TDragDropEvent = procedure(Sender, Source: TObject; X, Y: Integer) of object;

property OnDragDrop: TDragDropEvent;

Description

The OnDragDrop event occurs when the user drops an object being dragged. Use the OnDragDrop event handler to specify what you want to happen when the user drops an object. The Source parameter of the OnDragDrop event is the object being dropped, and the Sender is the control the object is being dropped on. The X and Y parameters are the coordinates of the mouse positioned over the control.

The TDragDropEvent type points to a method that handles the dropping of a dragged object. The Source parameter is the object being dragged, Sender is the object the Source is being dropped on, and X and Y are screen coordinates in pixels.


Example

This code comes from an application that contains a list box and three labels, each with a different font and color. The user can select a label and drag it to a list box and drop it. When the label is dropped, the items in the list box assume the color and font of the dropped label. This is the OnDragDrop event handler.

procedure TForm1.ListBox1DragDrop(Sender, Source: TObject; X, Y: Integer);

begin

  if (Sender is TListBox) and (Source is TLabel) then

  begin

    (Sender as TListBox).Font := (Source as TLabel).Font;

  end;

end;

The Source in this example is the label, and the Sender is the list box.


See also

Dragging and Dropping

DragCursor property

DragMode property

OnDragOver event

OnEndDrag event


OnDragOver event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBNavigator, TDBText, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TGroupBox, THeaderControl, TImage, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBar, TScrollBox, TShape, TStatusBar, TStringGrid, TTabControl, TTabSet, TTrackBar, TTreeView components

Declaration

TDragOverEvent = procedure(Sender, Source: TObject; X, Y: Integer; State: TDragState; var Accept: Boolean) of object;

property OnDragOver: TDragOverEvent;

Description

The OnDragOver event occurs when the user drags an object over a component. You use an OnDragOver event to accept an object so the user can drop it.

The OnDragOver event accepts an object when its Accept parameter is True.

Usually, you will want the cursor to change shape, indicating that the control can accept the dragged object if the user drops it. You can change the shape of the cursor by changing the value of the DragCursor property for the control either at design time or at run time before an OnDragOver event occurs.

The TDragOverEvent type points to a method that handles the dragging of one object over another. The Source parameter is the object being dragged. Sender is the object the Source is being dragged over. X and Y are the coordinates within the control in pixels. State is the state of the drag object in relationship to the object being dragged over. And Accept determines whether the Sender recognizes the drag object. Accept defaults to False.


Example

This OnDragOver event handler permits the list box to accept a dropped label:

procedure TForm1.ListBox1DragOver(Sender, Source: TObject; X, Y: Integer;

  State: TDragState; var Accept: Boolean);

begin

  Accept := Source is TLabel;

end;

The Source parameter identifies what is being dragged. The Sender is the control being dragged over.

This code permits the list box to accept any dropped control:

procedure TForm1.ListBox1DragOver(Sender, Source: TObject; X, Y: Integer;

  State: TDragState; var Accept: Boolean);

begin

  Accept := True;

end;


See also

Dragging and Dropping

 DragMode property

OnDragDrop event

OnEndDrag event

TDragState type


OnDrawCell event

Example

Applies to

TDrawGrid, TStringGrid components

Declaration

TDrawCellEvent = procedure (Sender: TObject; Col, Row: Longint; Rect: TRect; State: TGridDrawState) of object;

property OnDrawCell: TDrawCellEvent;

Description

The OnDrawCell event occurs whenever the contents of a grid cell need to be redisplayed. For example, it occurs when the user selects a cell or scrolls the grid.

How a cell is redrawn depends on the value of the DefaultDrawing property. If DefaultDrawing is False, you must write the code that handles all drawing within the cell in the OnDrawCell event handler. If DefaultDrawing is True, the cell is drawn normally and the OnDrawCell event handler is called.

The TDrawCellEvent type points to a method that handles the drawing of a cell in an owner-draw grid control. The Col parameter is the column of the cell in the grid, and the Row parameter is the row of the cell. Rect is the cell area where the drawing occurs, and State is current state of the cell.


Example

The following code draws a focus rectangle around each of the cells of StringGrid1.

procedure TForm1.StringGrid1DrawCell(Sender: TObject; Col, Row: Longint;

  Rect: TRect; State: TGridDrawState);

begin

  StringGrid1.Canvas.DrawFocusRect(Rect);

end;


OnDrawColumnCell event

See also

Applies to

TDBGrid component

Declaration

type
  TDrawColumnCellEvent = procedure (Sender: TObject; const Rect: TRect;
    DataCol: Integer; Column: TColumn; State: TGridDrawState) of object;

property OnDrawColumnCell: TDrawColumnCellEvent;

Description

The OnDrawColumnCell event occurs whenever the contents of a data grid cell need to be repainted. For example, it occurs when the user selects a cell or scrolls the grid. How a cell is redrawn depends partially on the setting of the DefaultDrawing property. If DefaultDrawing is False, you must write code in the OnDrawColumnCell event handler to handle all the drawing within the grid's cell.

The parameters passed to the OnDrawColumnCell event handler supply you with all the information you need to draw the data exactly as if TDBGrid were doing all the drawing.

This event supercedes OnDrawDataCell, which is obsolete but retained for compatibility.

The TDrawColumnCellEvent type points to a method that handles the drawing of a cell in an owner-drawn data grid control. This type replaces the now-obsolete TDrawDataCellEvent, which doesn't supply the column object needed to determine exactly how to draw the cell.

The Rect parameter specifies the cell area where the drawing occurs. The DataCol parameter is the number of the column, counting from zero on the left. Column is the TColumn object representing this column; you need to access its properties to determine how to draw the contents of the cell. The State parameter is the current state of the cell.


See also

DefaultDrawColumnCell method


OnDrawDataCell event

Example

Applies to

TDBGrid component

Declaration

TDrawDataCellEvent = procedure (Sender: TObject; const Rect: TRect; Field: TField; State: TGridDrawState) of object;

property OnDrawDataCell: TDrawDataCellEvent;

Description

The OnDrawDataCell has become obsoleted by OnDrawColumnCell.

The OnDrawDataCell event occurs whenever the contents of a data grid cell need to be redisplayed. For example, it occurs when the user selects a cell or scrolls the grid.

How a cell is redrawn depends on the value of the DefaultDrawing property.If DefaultDrawing is False, you must write the code that handles all the drawing within the cell in the OnDrawDataCell event handler.

The TDrawDataCellEvent type points to a method that handles the drawing of a cell in an owner-draw data grid control. The Rect parameter specifies the cell area where the drawing occurs. The Field parameter specifies which field the drawing takes place in, and the State parameter is the current state of the cell.


Example

The following code fills the cells of DBGrid1 with the pattern defined by the Brush of the Canvas of DBGrid1.

procedure TForm1.DBGrid1.DrawDataCell(Sender: TObject; Rect: TRect; Field: TField;
  State: TGridDrawState)

begin

  DBGrid1.Canvas.FillRect(Rect);

end;


OnDrawItem event

See also	Example

Applies to

TComboBox, TDBComboBox, TDBListBox, TListBox, TOutline components

Declaration

TDrawItemEvent = procedure(ListBox: TListBox; Index: Integer; Rect: TRect; State: TOwnerDrawState) of object;

property OnDrawItem: TDrawItemEvent;

Description

The OnDrawItem event occurs whenever an item in an owner-draw outline, list box, or combo box needs to be redisplayed. For example, it occurs when the user selects an item or scrolls the outline, list box, or combo box. OnDrawItem events occur only for outlines with the Style value osOwnerDraw, for list boxes with the Style values lbOwnerDrawFixed or lbOwnerDrawVariable, and for combo boxes with the Style values csOwnerDrawFixed or csOwnerDrawVariable.

OnDrawItem passes four parameters to its handler describing the item to be drawn:

A reference to the control containing the item

The index of the item in that control

A rectangle in which to draw

The state of the item (selected, focused, and so on)

The size of the rectangle that contains the item is determined either by the ItemHeight property for fixed owner-draw controls or by the response to the OnMeasureItem event for variable owner-draw controls.

The TDrawItemEvent type points to a method that handles the drawing of an item in an owner-draw list box. The Index parameter is the position of the item in the list box, Rect is the area in the list box where the item is to be drawn, and State is the current state of the item in the list box. These are the possible values of State::

Value	Meaning

odSelected	The item is selected.

odDisabled	The entire list box is disabled.

odFocused	The item currently has focus.


Example

Here is a typical handler for an OnDrawItem event. In the example, a list box with the lbOwnerDrawFixed style draws a bitmap to the left of each string.

procedure TForm1.ListBox1DrawItem(Control: TWinControl; Index: Integer; Rect: TRect;
  State: TOwnerDrawState);

var
  Bitmap: TBitmap;	{ temporary variable for the item's bitmap }
  Offset: Integer;	{ text offset width }

begin
  with (Control as TListBox).Canvas do	{ draw on the control canvas, not on the form }
  begin
    FillRect(Rect);	{ clear the rectangle }

    Offset := 2;	{ provide default offset }

    Bitmap := TBitmap((Control as TListBox)Items.Objects[Index]);	{ get the bitmap )

    if Bitmap <> nil then
    begin
      BrushCopy(Bounds(Rect.Left + 2, Rect.Top, Bitmap.Width, Bitmap.Height), Bitmap,
        Bounds(0, 0, Bitmap.Width, Bitmap.Height), clRed);	{ render the bitmap }

      Offset := Bitmap.width + 6;	{ add four pixels between bitmap and text }
    end;

    TextOut(Rect.Left + Offset, Rect.Top, Items[Index])	{ display the text }
  end;
end;

Note that the Rect parameter automatically provides the proper location of the item within the control's canvas.


See also

ItemHeight property

OnMeasureItem event


OnDrawPanel event

See also

Applies to

TStatusBar component

Declaration

TDrawPanelEvent = procedure(StatusBar: TStatusBar; Panel: TStatusPanel; const Rect: TRect) of object;

property OnDrawPanel: TDrawPanelEvent;

Description

The OnDrawPanel event occurs whenever an owner-draw panel needs to be redisplayed. For example, it occurs whenever when the user selects a panel or resizes the parent form. The OnDrawPanel event occurs only when the Style property of a panel (TStatusPanel) is set to hsOwnerDraw.


See also

Canvas property


OnDrawSection event

See also

Applies to

THeaderControl component

Declaration

TDrawSectionEvent = procedure (HeaderControl: THeaderControl; Section: THeaderSection; const Rect: TRect; Pressed: Boolean) of object;

property OnDrawSection: TDrawSectionEvent;

Description

The OnDrawSection event occurs whenever a section needs to be redisplayed. For example, it occurs whenever when the user selects or resizes a section. The OnDrawSection event occurs only when the style of a header section (THeaderSection) is set to hsOwnerDraw in the Style property.


See also

Canvas property

Style property


OnDrawTab event

See also	Example

Applies to

TTabSet component

Declaration

TDrawTabEvent = procedure(Sender: TObject; TabCanvas: TCanvas; R: TRect; Index: Integer; Selected: Boolean) of object;

property OnDrawTab: TDrawTabEvent;

Description

The OnDrawTab event occurs when a tab needs to redisplay only for tab set controls that have the Style property value of tsOwnerDraw. For example, it happens when the user selects a tab or scrolls the tabs using an owner-draw tab set control.

You must write the code in the OnDrawTab event handler to draw the tab.

OnDrawTab occurs just after the OnMeasureTab event, which contains the code to calculate the width of the tab needed. The height of the tab is determined by the value of the TabHeight property of the tab set control. The code you write in the OnDrawTab event handler, therefore, must use the width determined with the OnMeasureTab event to draw the tab.

The TDrawTabEvent type points to a method that handles the drawing of an item in an owner-draw tab. The TabCanvas parameter is the canvas on which the item is drawn. The Index parameter is the position of the tab in the tab set control. R is the area in the tab where the item is to be drawn, and Selected indicates whether the tab is currently selected or not.


Example

The following code loads a bitmap from the Objects property of the Tabs list of the DriveTabSet tab set component. This bitmap is then drawn on the tab, along with the text from the Tabs list.

procedure TFMForm.DriveTabSetDrawTab(Sender: TObject; TabCanvas: TCanvas;

  R: TRect; Index: Integer; Selected: Boolean);

var

  Bitmap: TBitmap;

begin

  Bitmap := TBitmap(DriveTabSet.Tabs.Objects[Index]);

  with TabCanvas do

  begin

    Draw(R.Left, R.Top + 4, Bitmap);

    TextOut(R.Left + 2 + Bitmap.Width, R.Top + 2, DriveTabSet.Tabs[Index]);

  end;

end;


See also

OnMeasureTab event

TabHeight property


OnDropDown event

Example

Applies to

TComboBox, TDBListBox, TDBComboBox, TDBLookupCombo, TDBLookupComboBox, TListBox components

Declaration

property OnDropDown: TNotifyEvent;

Description

The OnDropDown event occurs when the user opens (drops down) a combo box or list box.


Example

The following code doesn't sort the items in a combo box until the user opens it.

procedure TForm1.ComboBox1DropDown(Sender: TObject);

begin

  ComboBox1.Sorted := True;

end;


OnEditButtonClick event

Applies to

TDBGrid component

Declaration

property OnEditButtonClick: TNotifyEvent;

Description

The OnEditButtonClick event occurs whenever the user presses the ellipsis button in a grid column. The normal response to an OnEditButtonClick event is to display some kind of a list the user can choose a value from. Then you can use the SelectedField property to store the user's selection in the corresponding field.


OnEdited event

Applies to

TTreeView, TListView components

Description

OnEdited Event for Tree Views

OnEdited Event for List Views


OnEdited event

See also

Applies to

TTreeView component

Declaration

TTVEditedEvent = procedure(Sender: TObject; Node: TTreeNode; var S: string) of object;

property OnEdited: TTVEditedEvent;

Description

The OnEdited event occurs at the end of label editing of an item's Text property and if the text in the label has been changed. The event can occur only if ReadOnly is set to False.


See also

OnEditing event

Text property

EditText method

EndEdit method

ReadOnly property


OnEdited event

See also

Applies to

TListView component

Declaration

TLVEditedEvent = procedure (Sender: TObject; Item: TListItem; var S: string) of object;

property OnEdited: TLVEditedEvent;

Description

The OnEdited event occurs at the end of label editing of an item's Caption property. The event can occur only if ReadOnly is set to False.


See also

OnEditing event

Caption property

ReadOnly property


OnEditError event

Applies to

TTable, TQuery, TStoredProc components

Declaration

type
  TDataSetErrorEvent = procedure(DataSet: TDataSet; E: EDatabaseError;
  var Action: TDataAction) of object;

property OnEditError: TDataSetErrorEvent;

Description

The OnEditError event occurs when there was an error editing the current record, such as not being able to obtain a lock on the record. The DataSet parameter is the dataset that had the problem. The E parameter is an EDatabaseError exception object that contains details about the problem. Action is a var parameter that lets you control how the error is handled when the event handler finishes.


OnEditing event

See also

Applies to

TListView, TTreeView components

Declaration

TLVEditingEvent = procedure(Sender: TObject; Item: TListItem; var AllowEdit: Boolean) of object;

TTVEditingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowEdit: Boolean) of object;

property OnEditing: TLVEditingEvent

property OnEditing: TTVEditingEvent;

Description

The OnEditing event occurs at the start of label editing of an item's Caption property in the TListView and TTreeView components. This event can occur only if the component's ReadOnly property is set to False.

The TLVEditingEvent and TTVEditingEvent types point to a method that is called at the start of label editing of an item (OnEditing event) in the component. The AllowEdit parameter determines whether the editing is allowed. If AllowEdit is False, the user won't be able to change the label of the item in the tree view control.


See also

ReadOnly property

Caption property

OnEdited event


OnEndDrag event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDBNavigator, TDBText, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TGroupBox, THeaderControl, TImage, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPanel, TRadioButton, TRichEdit, TScrollBar, TScrollBox, TShape, TStatusBar, TStringGrid, TTabControl, TTabSet , TTrackBar, TTreeView components

Declaration

TEndDragEvent = procedure(Sender, Target: TObject; X, Y: Integer) of object;

property OnEndDrag: TEndDragEvent;

Description

The OnEndDrag event occurs whenever the dragging of an object ends, either by dropping the object or by canceling the dragging. Use the OnEndDrag event handler to specify any special processing you want to occur when dragging stops. If the dragged object was dropped and accepted by the control, the Target parameter of the OnEndDrag event is set to the object that accepted the drop. If the object was not dropped successfully, the value of Target is nil.

The TEndDragEvent type points to a method that handles the stopping of the dragging of an object. The Sender is the object being dragged, Target is the object Sender is dragged to, and X and Y are screen coordinates in pixels.


Example

This code displays a message in a label named Status. The message displayed depends on whether or not the dragged label control was dropped into and accepted by a list box control successfully:

procedure TForm1.LabelEndDrag(Sender, Target: TObject; X, Y: Integer);

var

  S: string;

begin

  S := (Sender as TLabel).Name + ' was dropped... and ';

  if Target <> nil then S := S + 'accepted!'

  else S := S + 'rejected!';

  Status.Caption := S;

end;

The Target parameter is the list box and Sender is the label.


See also

Dragging and Dropping

EndDrag method

OnDragDrop event


OnEnter event

See also	Example

Applies to

All windowed controls

Declaration

property OnEnter: TNotifyEvent;

Description

The OnEnter event occurs when a component becomes active. Use the OnEnter event handler to specify any special processing you want to occur when a component becomes active.

Note:	The OnEnter event does not occur when switching between forms or between another Windows application and your application.

Note:	When switching between container controls such as the TPanel and the TGroupBox, an OnEnter event is generated for the container when the control in the container receives focus. This event is generated before the OnEnter event for the control itself is generated. An OnExit event of the container is generated after the OnExit event of the control in a container if focus is given to another control not contained by the container. For example, if you have a group box that contains three radio buttons on a form with an OK button, if focus is currently on the OK button and you click one of the radio buttons, an OnExit is generated for the button. If you then click on the OK button, an OnExit is generated for the radio button followed by an OnExit for the group box, and then the button will receive the OnEnter.


Example

This example uses an edit box and a memo control on a form. When either the edit box or the memo is the active control, it is colored yellow. When the active control becomes inactive, the color of the control returns to the Windows system color for a window.

procedure TForm1.Edit1Enter(Sender: TObject);

begin

  Edit1.Color := clYellow;

end;

procedure TForm1.Edit1Exit(Sender: TObject);

begin

  Edit1.Color := clWindow;

end;

procedure TForm1.Memo1Enter(Sender: TObject);

begin

  Memo1.Color := clYellow;

end;

procedure TForm1.Memo1Exit(Sender: TObject);

begin

  Memo1.Color := clWindow;

end;


See also

ActiveControl property

OnActivate event

OnExit event


OnException event

Example

Applies to

TApplication component

Declaration

TExceptionEvent = procedure (Sender: TObject; E: Exception) of object;

property OnException: TExceptionEvent;

Description

The OnException event occurs when an unhandled exception occurs in your application. By default, the HandleException method calls the OnException event handler, which calls ShowException to display a message dialog box indicating an error occurred. You can change this behavior by specifying what processing you want to occur in the OnException event handler.

The TExceptionEvent type points to a method that handles exceptions in your application. The Sender parameter is the object that raised the exception, and E is the exception message.

Note:	Search Help for "Handling Application Events" for more information about creating event handlers for application events.


Example

The following code defines the default exception handling of the application, assuming AppException is declared a method of TForm1.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnException := AppException;

end;

procedure TForm1.AppException(Sender: TObject; E: Exception);

begin

  Application.ShowException(E);

end;


OnExecuteMacro event

Example

Applies to

TDDEServerConv component

Declaration

TMacroEvent = procedure(Sender: TObject; Msg : string) of object;

property OnExecuteMacro : TMacroEvent;

Description

The OnExecuteMacro event occurs when a DDE client application sends a macro to a DDE server conversation component. Write code to process the macro in the OnExecuteMacro event handler. See the DDE client application documentation for information about how it sends macros. If the DDE client is a Delphi application, a macro is sent with the ExecuteMacro method of the TDDEClientConv component.

The TMacroEvent type points to a method that handles the passing of a macro string from a DDE client to a DDE server conversation (TDDEServerConv) component. Msg contains the macro.


Example

The following code clears the contents of a memo in the server application if the appropriate message is sent from the client application.

procedure TForm1.DdeServerConv1ExecuteMacro(Sender: TObject; Msg: TStrings);

begin

  if Msg.Strings[0] = 'Edit|Clear' then

    Memo1.Clear;

end;


OnExit event

See also	Example

Applies to

All windowed controls

Declaration

property OnExit: TNotifyEvent;

Description

The OnExit event occurs when the input focus shifts away from one control to another. Use the OnExit event handler when you want special processing to occur when this control ceases to be active.

Note:	The OnExit event does not occur when switching between forms or between another Windows application and your application.

Note:	When switching between container controls such as the TPanel and the TGroupBox, an OnEnter event is generated for the container when the control in the container receives focus. This event is generated before the OnEnter event for the control itself is generated. An OnExit event of the container is generated after the OnExit event of the control in a container if focus is given to another control not contained by the container. For example, if you have a group box that contains three radio buttons on a form with an OK button, if focus is currently on the OK button and you click one of the radio buttons, an OnExit is generated for the button. If you then click on the OK button, an OnExit is generated for the radio button followed by an OnExit for the group box, and then the button will receive the OnEnter.

Note:	The ActiveControl property is updated before an OnExit event occurs.


Example

This example uses an edit box and a memo control on a form. When either the edit box or the memo is the active control, it is colored yellow. When the active control becomes inactive, the color of the control returns to the Windows system color for a window.

procedure TForm1.Edit1Enter(Sender: TObject);

begin

  Edit1.Color := clYellow;

end;

procedure TForm1.Edit1Exit(Sender: TObject);

begin

  Edit1.Color := clWindow;

end;

procedure TForm1.Memo1Enter(Sender: TObject);

begin

  Memo1.Color := clYellow;

end;

procedure TForm1.Memo1Exit(Sender: TObject);

begin

  Memo1.Color := clWindow;

end;


See also

OnEnter event


OnExpand event

See also	Example

Applies to

TOutline component

Declaration

EOutlineChange = procedure (Sender: TObject; Index: LongInt) of object;

property OnExpand: EOutlineChange;

Description

An OnExpand event occurs when a collapsed outline item having subitems is expanded. A collapsed outline item is expanded when the user double-clicks on it at run time, when its Expanded property is set to True, or when the FullExpand method of the TOutlineNode object is called. When expanded, the subitems appear in the outline and the minus picture or open picture for the parent item is displayed if the appropriate OutlineStyle has been selected.

The EOutlineChange type is a pointer to a method that is called when an item in a TOutline component is changed by being expanded (OnExpand) or collapsed (OnCollapse). The Index parameter specifies the Index property value of the changed item.


Example

The following code displays the text from a collapsed outline item in a message dialog box.

procedure TForm1.Outline1Expand(Sender: TObject; Index: Longint);

var

  TheStr: string;

begin

  TheStr :=  Outline1.Items[Index].Text;

  MessageDlg(TheStr+' has expanded.', mtInformation, [mbOK],0);

end;


See also

OnCollapse event

PictureMinus property

PictureOpen property


OnExpanded event

See also

Applies to

TTreeView component

Declaration

TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnExpanded: TTVExpandedEvent;

Description

The OnExpanded event occurs whenever an item has been expanded.


See also

OnCollapsed event

OnCollapsing event

OnExpanding event

FullCollapse method

FullExpand method

Expanded property

Collapse method

Expand method

The TTVExpandedEvent type points to a method that is called after an item is expanded (OnExpanded event).


OnExpanding event

See also

Applies to

TTreeView component

Declaration

TTVExpandingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowExpansion: Boolean) of object;

property OnExpanding: TTVExpandingEvent;

Description

The OnExpanding event occurs whenever an item is about to be expanded.

The TTVExpandingEvent type points to a method that is called when an item is about to be expanded (OnExpanding event). The AllowExpansion parameter determines whether the item can be expanded. If AllowExpansion is set to False, the user won't be able to expand the item.


See also

OnCollapsed event

OnCollapsing event

OnExpanded event

FullCollapse method

FullExpand method

Expanded property

Collapse method

Expand method


OnFilterRecord event

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

TFilterRecordEvent = procedure(DataSet: TDataSet; var Accept: Boolean) of object;

property OnFilterRecord: TFilterRecordEvent;

Description

The OnFilterRecord event occurs when filtering is active, either from setting Filtered to True, or by using the FindFirst, FindLast, FindNext, or FindPrior methods. OnFilterRecord event handlers have two parameters: the dataset being filtered and a var Accept parameter to specify whether the record should be included. By default, Accept is True; only when you set Accept to False will a record be excluded.

OnFilterRecord fires once for each record in the dataset, letting you inspect the field values in the record to decide whether it should be excluded. As performance is directly related to how often the event fires and how long it takes to process each event, the code in the OnFilterRecord event handler shouldn't take long to process.

The TFilterRecordEvent type points to a method that responds to an OnFilterRecord event, for including or excluding records from being visible in a dataset.


Example

procedure TForm1.Table1FilterRecord(DataSet: TDataSet; var Accept: Boolean);

begin

  Accept := DataSet['Age'] > 18;

end;


OnFind event

See also	Example

Applies to

TFindDialog, TReplaceDialog components

Declaration

property OnFind: TNotifyEvent;

Description

The OnFind event occurs whenever the user chooses the Find Next button in the Find or Replace dialog box. Use the OnFind event to specify what you want to happen when the user chooses the Find Next button.


Example

The following text compares the FindText to the Text of the Items of Outline1. If the string is found, a message is displayed and I-1 specifies the index of the matching item.

procedure TForm1.FindDialog1Find(Sender: TObject);

var

  I: Integer;

  Found: Boolean;

begin

  I := 1;

  Found := False;

  repeat

    if Outline1.Items[I].Text = FindDialog1.FindText then

    begin

      MessageDlg('Found!', mtInformation, [mbOK], 0);

      Found := True;

    end;

    I := I+1;

  until (I > Outline1.ItemCount) or (Found);

end;


See also

OnReplace event


OnGetEditMask event

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

TGetEditEvent = procedure (Sender: TObject; ACol, ARow: Longint; var Value: string) of object;

property OnGetEditMask: TGetEditEvent;

Description

The OnGetEditMask event occurs when the Options property set contains the value goEditing, and the grid needs to redisplay the text of a cell in the grid using a specified edit mask. For example, the grid needs to redisplay the text when the user scrolls the grid or the user changes the data.

You write the code to specify the edit mask for the cell in the OnGetEditMask event handler.

The TGetEditEvent type points to a method that handles the retrieval of the text displayed in a cell in a draw grid (TDrawGrid) or string grid (TStringGrid) while the grid is in Edit mode, or that handles the retrieval of the edit mask used to display text. The ACol parameter specifies the column of the cell, and the ARow parameter specifies the row of the cell. The Value parameter is the string displayed in the cell or the edit mask used to display the text.


Example

This example specifies an edit mask commonly used to display American telephone numbers for the cell in column 2, row 3 of the string grid:

procedure TForm1.StringGrid1GetEditMask(Sender: TObject; ACol,

  ARow: Longint; var Value: string);

begin

  if ACol = 2 then

    if ARow = 3 then

       Value :=  '!\(999\)000-0000;1';

end;


See also

EditMask property

OnGetEditText event


OnGetEditText event

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

TGetEditEvent = procedure (Sender: TObject; ACol, ARow: Longint; var Value: string) of object;

property OnGetEditText: TGetEditEvent;

Description

The OnGetEditText event occurs when the Options property set contains the value goEditing and the grid needs to redisplay the text of a cell in the grid. For example, the grid needs to redisplay the text when the user scrolls the grid or the user changes the data.

You write the code to retrieve the text of the cell in the OnGetEditText event handler.

When the user edits data in a grid, the OnSetEditText event occurs to change the actual data, then the OnGetEditText event occurs to display the changed data in the grid.

The TGetEditEvent type points to a method that handles the retrieval of the text displayed in a cell in a draw grid (TDrawGrid) or string grid (TStringGrid) while the grid is in Edit mode, or that handles the retrieval of the edit mask used to display text. The ACol parameter specifies the column of the cell, and the ARow parameter specifies the row of the cell. The Value parameter is the string displayed in the cell or the edit mask used to display the text.


Example

The following code appends 'My ' to any text entered in StringGrid1.

procedure TForm1.StringGrid1GetEditText(Sender: TObject; ACol,

  ARow: Longint; var Value: string);

begin

  Value := 'My ' + Value;

end;


See also

OnGetEditMask event

OnSetEditText event


OnGetImageIndex event

See also

Applies to

TTreeView component

Declaration

TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnGetImageIndex: TTVExpandedEvent;

Description

The OnGetImageIndex event occurs when the control inquires about the ImageIndex of an item. This gives the programmer an opportunity to change the image index for the particular item being drawn. For example, the bitmap of a node can be changed to indicate a different state for the item.


See also

Images property

OnGetSelectedIndex event

Images property

ImageIndex property

StateImages property

OverlayIndex property

StateIndex property


OnGetSelectedIndex event

See also

Applies to

TTreeView component

Declaration

TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnGetSelectedIndex: TTVExpandedEvent;

Description

The OnGetSelectedIndex event occurs when the control inquires about the SelectedIndex of the item. This gives the programmer the opportunity to change the selected item's SelectedIndex, the index of the selected item's bitmap in the image list.


See also

Images property

OnGetImageIndex event

Images property

ImageIndex property

StateImages property

OverlayIndex property

StateIndex property


OnGetText event

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

TFieldGetTextEvent = procedure(Sender: TField; var Text: string; DisplayText: Boolean) of object;

property OnGetText: TFieldGetTextEvent;

Description

The OnGetText event is activated when the DisplayText or Text properties are referenced. The DisplayText parameter indicates whether the event should supply the text in display format or in edit format for the Text property.

If OnGetText has been assigned a method, the default processing for DisplayText or Text does not occur. Instead, the event handler is expected to perform any conversion required to display the value. By assigning a method to this property, you can take any special actions required by the event.

The TFieldGetTextEvent type points to a method that retrieves the text in the field. The Text parameter references the text, and the DisplayText parameter determines whether the text is formatted for display. If DisplayText is True, the text is in display format. If DisplayText is False, the text is not formatted for display.


Example

Field1.OnGetText := MyFormatMethod;


OnHelp event

See also	Example

Applies to

TApplication component

Declaration

THelpEvent = function (Command: Word; Data: Longint;   var CallHelp: Boolean): Boolean of      object;

property OnHelp: THelpEvent;

Description

The OnHelp event occurs when your application receives a request for help. Use the OnHelp event handler to specify any special processing you want to occur when help is requested.

To find the possible values of the Command and Data parameters, search for WinHelp in the Win32 Developer's Reference Help (Win32.HLP) file, which explains the WinHelp API (application programming interface).

The HelpContext and the HelpJump methods automatically trigger the OnHelp event.

Note:	See Handling Application Events for more information about creating event handlers for application events.


Example

The following code changes the Help file for the application to the results of the Open dialog component. AppHelp should be assigned to the OnHelp event handler of Application in the OnCreate event of Form1.

function TForm1.AppHelp(Command: Word; Data: Longint): Boolean;

begin

  if OpenDialog1.Execute then

    Application.HelpFile := OpenDialog1.FileName;

end;


See also

HelpCommand method

HelpContext property

HelpFile property

THelpContext type


OnHide event

See also	Example

Applies to

TForm component

Declaration

property OnHide: TNotifyEvent;

Description

The OnHide event occurs just before the form is hidden on the screen. Use the OnHide event to specify any special processing you want to happen just before the form disappears.


Example

This example uses two forms, each with a label and a button. When the user clicks a button, the other form appears and the current form disappears. Also, a message appears in the label of the form that is showing, indicating that the other form is hidden. This is the implementation section of Unit1:

implementation

{$R *.DFM}

uses Unit2;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form2.Show;

  Hide;

end;

procedure TForm1.FormHide(Sender: TObject);

begin

  Form2.Label1.Caption := 'Form1 is hiding';

end;

end.

This is the implementation section of Unit2:

implementation

{$R *.DFM}

uses Unit1;

procedure TForm2.Button1Click(Sender: TObject);

begin

  Form1.Show;

  Hide;

end;

procedure TForm2.FormHide(Sender: TObject);

begin

  Form1.Label1.Caption := 'Form2 is hiding';

end;

end.


See also

OnShow event


OnHint event

See also	Example

Applies to

TApplication component

Declaration

property OnHint: TNotifyEvent;

Description

The OnHint event occurs when the user positions the mouse pointer over a control with a Hint property value other than an empty string (''). Use the OnHint event handler to perform any special processing you want to happen when the OnHint event occurs.

A common use of the OnHint event is to display the value of a control or menu item's Hint property as the caption of a panel control (TPanel), thereby using the panel as a status bar. Using the Hint property, you can specify a Help Hint and a usually longer hint that appears elsewhere when the OnHint event occurs.

Note:	See Handling Application Events for more information about creating event handlers for application events.


Example

This example uses a panel component, a menu, and an edit box on a form. You can design the menu as you want, but remember to include a value for the Hint property for each menu item in the menu. Also, specify a value for the Hint property of the edit box. Align the panel at the bottom of the form (choose alBottom as the value of the Align property), and left justify the caption of the panel (choose taLeftJustify as the value of the Alignment property).

The OnHint event is an event of the TApplication component. You can't use the Object Inspector to generate an empty event handler for TApplication, so you will need to write your own OnHint event handler. To accomplish this, you create a method of the TForm1 object and give it an appropriate name, such as DisplayHint. You write the method in the implementation part of the unit, but you must also remember to declare the method in the TForm1 type declaration in the public section.

In the DisplayHint method, you assign the Hint property of the application to the Caption property of the panel component.

One task remains. The OnHint event is an event of TApplication, so you must assign the new method you created as the method used by the OnHint event. You can do this in the form's OnCreate event handler.

This code shows the complete type declaration, the new method, and the OnCreate event handler. When the user runs the application and positions the cursor over the edit box or a menu item on the menu, the specified hint appears as the caption of the panel at the bottom of the form:

type

  TForm1 = class(TForm)

    Button1: TButton;

    Panel1: TPanel;

    Edit1: TEdit;

    procedure FormCreate(Sender: TObject);

  private

    { Private declarations }

  public

    procedure DisplayHint(Sender: TObject);

  end;

var

  Form1: TForm1;

implementation

{$R *.FRM}

procedure TForm1.DisplayHint(Sender: TObject);

begin

  Panel1.Caption := Application.Hint;

end;procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnHint := DisplayHint;

end;


See also

OnCreate event


OnIdle event

Example

Applies to

TApplication component

Declaration

TIdleEvent = procedure (Sender: TObject; var Done: Boolean) of object;

property OnIdle: TIdleEvent

Description

The OnIdle event occurs whenever the application is idle. Use the OnIdle event handler to specify any special processing to occur when your application is idle. Your application is idle when it is processing code, for example, or when it is waiting for input from the user.

The TIdleEvent type points to a method that runs when your application is idle. TIdleEvent has a Boolean parameter Done that is True by default. When Done is True, the Windows API WaitMessage function is called when OnIdle returns. WaitMessage yields control to other applications until a new message appears in the message queue of your application. If Done is False, WaitMessage is not called. For more information, search for WaitMessage in the Win32 Developer's Reference (WIN32.HLP)

Note:	See Handling Application Events for more information about creating event handlers for application events.


Example

The following code allows other applications to be processed while Application is idle. AppIdle should be declared as a method of TForm1.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnIdle := AppIdle;

end;

procedure TForm1.AppIdle(Sender: TObject; var Done: Boolean);

begin

  Done := True;

end;


OnInsert event

See also

Applies to

TListView component

Declaration

TLVDeletedEvent = procedure (Sender: TObject; Item: TListItem) of object;

property OnInsert: TLVDeletedEvent;

Description

The OnInsert event occurs when a new list item is inserted.


See also

Insert method


OnKeyDown event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TListBox, TListView, TMaskEdit, TMemo, TOutline, TRadioButton, TRichEdit, TScrollBar, TStringGrid, TTrackBar, TTreeView components

Declaration

TKeyEvent = procedure (Sender: TObject; var Key: Word; Shift: TShiftState) of object;

property OnKeyDown: TKeyEvent;

Description

The OnKeyDown event occurs when a user presses any key while the control has focus. Use the OnKeyDown event handler to specify special processing to occur when a key is pressed. The OnKeyDown handler can respond to all keyboard keys, including function keys and keys combined with the Shift, Alt, and Ctrl keys, and pressed mouse buttons.

The Key parameter of the OnKeyDown event handler is of type Word; therefore, you must use WinAPI virtual key codes to determine the key pressed. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

The TKeyEvent type points to a method that handles keyboard events. The Key parameter is the key on the keyboard and Shift is one of these possible states:

State	Meaning

ssShift	The Shift key is held down.

ssAlt	The Alt key is held down.

ssCtrl	The Ctrl key is held down.

ssLeft	The left mouse button is held down.

ssMiddle	The middle mouse button is held down.

ssDouble	Both the right and left mouse buttons are held down.


Example

This event handler displays a message dialog when the user presses Alt+F10:

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word;

  Shift: TShiftState);

begin

  if ((Shift = [ssAlt]) and (Key = VK_F10)) then

    MessageDlg('Alt+F10 pressed down', mtInformation, [mbOK], 0);

end;


See also

KeyPreview property

OnKeyPress event

OnKeyUp event


OnKeyPress event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TListBox, TListView, TMaskEdit, TMemo, TOutline, TRadioButton, TRichEdit, TScrollBar, TStringGrid, TTrackBar, TTreeView components

Declaration

TKeyPressEvent = procedure (Sender: TObject; var Key: Char) of object;

property OnKeyPress: TKeyPressEvent;

Description

The OnKeyPress event occurs when a user presses a single character key. Use the OnKeyPress event handler when you want something to happen as a result of a single character key press.

The Key parameter in the OnKeyPress event handler is of type Char; therefore, the OnKeyPress event registers the ASCII character of the key pressed. Keys that don't correspond to an ASCII Char value (Shift or F1, for example) don't generate an OnKeyPress event. Key combinations (such as Shift+A), generate only one OnKeyPress event (for this example, Shift+A results in a Key value of "A" if Caps Lock is off). If you want to respond to non-ASCII keys or key combinations, use the OnKeyDown or OnKeyUp event handlers.

The TKeyPressEvent type points to a method that handles a single character key press. The Key parameter is the key on the keyboard.


Example

This event handler displays a message dialog box specifying which key was pressed:

procedure TForm1.FormKeyPress(Sender: TObject; var Key: Char);

begin

  MessageDlg(Key + ' has been pressed', mtInformation, [mbOK], 0)

end;


See also

KeyPreview property


OnKeyUp event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TListBox, TListView, TMaskEdit, TMemo, TOutline, TRadioButton, TRichEdit, TScrollBar, TStringGrid, TTrackBar, TTreeView components

Declaration

TKeyEvent = procedure (Sender: TObject; var Key: Word; Shift: TShiftState) of object;

property OnKeyUp: TKeyEvent;

Description

The OnKeyUp event occurs when the user releases a key that has been pressed. Use the OnKeyUp event handler when you want special processing to occur when a key is released. The OnKeyUp handler can respond to all keyboard keys, including function keys and keys combined with the Shift, Alt, and Ctrl keys.

The Key parameter of the OnKeyUp event handler is of type Word; therefore, you must use virtual key code to determine the key pressed. The TKeyEvent type points to a method that handles keyboard events. The Key parameter is the key on the keyboard and Shift is one of these possible states::

State	Meaning

ssShift	The Shift key is held down.

ssAlt	The Alt key is held down.

ssCtrl	The Ctrl key is held down.

ssLeft	The left mouse button is held down.

ssMiddle	The middle mouse button is held down.

ssDouble	Both the right and left mouse buttons are held down.


Example

The following code changes a form's color to aqua when a key is pressed. When the key is released, the form's color reverts to the original color. Note that the KeyPreview property of the form must be set to True to capture all key presses, even if a control has focus:

{In the declarations section of the form}

var

  FormColor: TColor;

(OnKeyDown event handler}

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word;

  Shift: TShiftState);

begin

  FormColor := Form1.Color;

  Form1.Color := clAqua;

end;

{OnKeyUp event handler}

procedure TForm1.FormKeyUp(Sender: TObject; var Key: Word;

  Shift: TShiftState);

begin

  Form1.Color := FormColor;

end;


See also

KeyPreview property

OnKeyDown event

OnKeyPress event


OnLogin event

Applies to

TDataBase component

Declaration

TLoginEvent = procedure(Database: TDatabase; LoginParams: TStrings) of object;

property OnLogin: TLoginEvent;

Description

The OnLogin event is activated whenever a TDatabase component assigned to an SQL database is opened and the LoginPrompt property is True. Use the OnLogin event to set login parameters. The OnLogin event gets a copy of the TDatabase's login parameters array, Params. Use the Values property to change these parameters:

LoginParams.Values['SERVER NAME'] := 'MYSERVERNAME';

LoginParams.Values['USER NAME'] := 'MYUSERNAME';

LoginParams.Values['PASSWORD'] := 'MYPASSWORD';

When control returns from your OnLogin event handler, these parameters will be used to establish a connection.

The TLoginEvent type is the header for the method that handles an OnLogin event for a TDatabase component. The Database parameter is the database. LoginParams is a TStrings object which holds the username and password, along with any other parameters to be used in opening the Database. The username is a string of the form 'USER NAME=John_Doe'. The password is a string of the form 'PASSWORD=His_Password'. The OnLogin event handler should add both the username and password to LoginParams when called.

Note:	For Paradox, dBASE, and ASCII databases, the only possible parameter is PATH, so the OnLogin event will not be activated.


OnMeasureItem event

Example

Applies to

TComboBox, TDBComboBox, TDBListBox, TListBox components

Declaration

TMeasureItemEvent = procedure(Control: TWinControl: Integer; var Height: Integer) of object;

property OnMeasureItem: TMeasureItemEvent;

Description

The OnMeasureItem event occurs whenever an application needs to redisplay an item in an owner-draw list box or combo box with a variable style. That is, for a list box, the Style property is lbOwnerDrawVariable, or for a combo box, the Style property is csOwnerDrawVariable.

The OnMeasureItem event passes three parameters to its handler describing the item to measure:

The control containing the item

The index of the item in the control

The height of the item

The OnMeasureItem event handler should specify the height in pixels that the given item will occupy in the control. The Height parameter is a var parameter, which initially contains the default height of the item or the height of the item text in the control's font. The handler can set Height to a value appropriate to the contents of the item, such as the height of a graphical image to be displayed within the item.

After the OnMeasureItem event occurs, the OnDrawItem event occurs, rendering the item with the measured size.

The TMeasureItemEvent type points to a method that handles the measuring of an item in an owner-draw list box. The Index parameter identifies the position of the item in the list box. Height is the height of the item in pixels.


Example

Here is a typical handler for an OnMeasureItem event. The example assumes that a variable owner-draw list box already has bitmaps associated with each of its strings. It sets the height of the item to the height of the associated bitmap if that height is greater than the default height.

procedure TForm1.ListBox1MeasureItem(Control: TWinControl; Index: Integer;
  var Height: Integer);

var
  Bitmap: TBitmap;

begin
  with Control as TListBox do
  begin
    Bitmap := TBitmap(Items.Objects[Index]);

    if Bitmap <> nil then
      if Bitmap.Height > Height then Height := Bitmap.Height;

  end;
end;


OnMeasureTab event

Example

Applies to

TTabSet component

Declaration

TMeasureTabEvent = procedure(Sender: TObject; Index: Integer; var TabWidth: Integer) of object;

property OnMeasureTab: TMeasureTabEvent;

Description

The OnMeasureTab event occurs when the Style property of the tab set control is tsOwnerDraw and an application needs to redisplay a tab in a tab set control. In the OnMeasureTab event handler, you write the code to calculate the width needed to draw the tab. After the OnMeasureTab event occurs, the OnDrawTab event occurs. You write the code to draw the tab using the width calculated in OnMeasureTab in the OnDrawTab event handler.

The Index parameter of the TMeasureTabEvent method pointer is the position of the tab in the tab set control. The TabWidth parameter is the width of the tab.

The TMeasureTabEvent type points to a method that handles the measuring of a tab in an owner-draw tab set control. The Index parameter identifies the position of the tab in the tab set control. TabWidth is the width of the tab.


Example

The following code measures the width of a bitmap stored in the Objects property of the Tabs list of the DriveTabSet tab set component. It then makes the width of the tab two pixels wider than the bitmap width.

procedure TFMForm.DriveTabSetMeasureTab(Sender: TObject; Index: Integer;

  var TabWidth: Integer);

var

  BitmapWidth: Integer;

begin

  BitmapWidth := TBitmap(DriveTabSet.Tabs.Objects[Index]).Width;

  Inc(TabWidth, 2 + BitmapWidth);

end;


OnMessage event

See also	Example

Applies to

TApplication component

Declaration

TMessageEvent = procedure (var Msg: TMsg; var Handled: Boolean) of object;

property OnMessage: TMessageEvent;

Description

The OnMessage event occurs when your application receives a Windows message. By creating an OnMessage event handler in your application, you can call other handlers that respond to the message. If your application doesn't have a specific handler for an incoming message, the message is dispatched and Windows handles the message. An OnMessage event handler lets trap all Windows messages posted to all windows in your application.

Caution:	Due to the high volume of messages that pass through this event, be careful in regards to performance.

The TMessageEvent type points to a method that handles the processing of incoming Windows messages. The Msg parameter identifies the Windows message, and the Handled parameter determines whether the message is handled or not.

Note:	See  for "Handling Application Events" for more information about creating event handlers for application events.


Example

The following code displays the time of the most recently received Windows message in the Caption of Label1. AppMessage should be declared a method of TForm1.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnMessage := AppMessage;

end;

procedure TForm1.AppMessage(var Msg: TMsg; var Handled: Boolean);

begin

  Label1.Caption := IntToStr(Msg.Time);

end;


See also

ProcessMessages method


OnMinimize event

See also

Applies to

TApplication component

Declaration

property OnMinimize: TNotifyEvent;

Description

The OnMinimize event occurs when the application is minimized, either because the user minimizes the main window, or because of a call to the Minimize method. Use the OnMinimize event handler to put code that performs any special processing you want to happen when the application is minimized.


See also

OnRestore event

Restore method


OnMouseDown event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TDBCheckBox, TDBEdit, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDBNavigator, TDBText, TDirectoryListBox, TDrawGrid, TEdit, TFileListBox, TForm, TGroupBox, THeaderControl, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TProgressBar, TRadioButton, TRichEdit, TScrollBox, TShape, TSpeedButton, TStatusBar, TStringGrid, TTabControl, TTabSet, TTreeView, TUpDown, components

Declaration

TMouseEvent = procedure (Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer) of object;

property OnMouseDown: TMouseEvent;

Description

The OnMouseDown event occurs when the user presses a mouse button with the mouse pointer over a control. Use the OnMouseDown event handler when you want some processing to occur as a result of pressing a mouse button.

The Button parameter of the OnMouseDown event identifies which mouse button was pressed. By using the Shift parameter of the OnMouseDown event handler, you can respond to the state of the mouse buttons and shift keys. Shift keys are the Shift, Ctrl, and Alt keys.

The TMouseEvent type points to a method that handles mouse-button events. The Button parameter determines which mouse button the user pressed. Shift indicates which shift keys (Shift, Ctrl, or Alt) and mouse buttons were down when the user pressed or released the mouse button that generated the mouse-button event. X and Y are the pixel coordinates of the mouse pointer, within the client area of the Sender.


Example

The following code creates and displays a label when a mouse button is pressed. If you attach this event handler to the OnMouseDown event of a form, a label specifying the coordinates of the mouse pointer appears when the user clicks the mouse button. Note that the StdCtrls unit must be added to the uses clause of the interface section of the form's unit to be able to create labels dynamically.

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

var

  NewLabel: TLabel;

begin

  NewLabel := TLabel.Create(Form1);

  NewLabel.Parent := Self;

  NewLabel.Left := X;

  NewLabel.Top := Y;

  NewLabel.Caption := '(' + IntToStr(X) + ',' + IntToStr(Y) + ')';

  NewLabel.Visible := True;

end;


See also

OnMouseMove event

OnMouseUp event


OnMouseMove event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TDBCheckBox, TDBEdit, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDBNavigator, TDirectoryListBox, TDrawGrid, TEdit, TFileListBox, TForm, TGroupBox, THeaderControl, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TProgressBar, TRadioButton, TRichEdit, TTScrollBox, TShape, TSpeedButton, TStatusBar, TStringGrid, TTabControl, TTabSet, TTreeView, TUpDown components

Declaration

TMouseMoveEvent = procedure(Sender: TObject; Shift: TShiftState; X, Y: Integer) of object;

property OnMouseMove: TMouseMoveEvent;

Description

The OnMouseMove event occurs when the user moves the mouse pointer while the mouse pointer is over a control. Use the OnMouseMove event handler when you want something to happen when the mouse pointer moves within the control.

By using the Shift parameter of the OnMouseDown event handler, you can respond to the state of the mouse buttons and shift keys. Shift keys are the Shift, Ctrl, and Alt keys.

The TMouseMoveEvent type points to a method that handles mouse-move events. The Button parameter determines which mouse button the user pressed. Shift indicates which shift keys (Shift, Ctrl, or Alt) and mouse buttons were down when the user moved the mouse. X and Y are pixel coordinates of the new location of the mouse pointer, in the client area of the Sender.


Example

The following code updates two labels when the mouse pointer is moved. The code assumes you have two labels on the form, lblHorz and lblVert. If you attach this code to the OnMouseMove event of a form, lblHorz continually displays the horizontal position of the mouse pointer, and lblVert continually displays the vertical position of the mouse pointer while the pointer is over the form.

procedure TForm1.FormMouseMove(Sender: TObject; Shift: TShiftState; X, Y: Integer);

begin

  lblHorz.Caption := IntToStr(X);

  lblVert.Caption := IntToStr(Y);

end;


See also

OnMouseDown event

OnMouseUp event


OnMouseUp event

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TDBCheckBox, TDBEdit, TDBImage, TDBListBox, TDBLookupCombo, TDBMemo, TDBNavigator, TDBText, TDirectoryListBox, TDrawGrid, TEdit, TFileListBox, TForm, TGroupBox, THeaderControl, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TOutline, TPageControl, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBox, TShape, TSpeedButton, TStatusBar, TStringGrid, TTabControl, TTabSet, TTreeView, TUpDown components

Declaration

TMouseEvent = procedure (Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer) of object;

property OnMouseUp: TMouseEvent;

Description

The OnMouseUp event occurs when the user releases a mouse button that was pressed with the mouse pointer over a component. Use the OnMouseUp event handler when you want processing to occur when the user releases a mouse button.

The OnMouseUp event handler can respond to left, right, or center mouse button presses and shift key plus mouse-button combinations. Shift keys are the Shift, Ctrl, and Alt keys.

The TMouseEvent type points to a method that handles mouse-button events. The Button parameter determines which mouse button the user pressed. Shift indicates which shift keys (Shift, Ctrl, or Alt) and mouse buttons were down when the user pressed or released the mouse button that generated the mouse-button event. X and Y are the pixel coordinates of the mouse pointer, in the client area of the Sender.


Example

The following code draws a rectangle when the user presses a mouse button, moves the mouse, and releases the mouse button. When the mouse button is released, the rectangle appears on the form's canvas. Its top-left and bottom-right corners are defined by the location of the mouse pointer when the user pressed and released the mouse button.

var

  StartX, StartY: Integer;  {Declare in interface section of form's unit}

{Use this code as the OnMouseDown event handler of the form:}

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  StartX := X;

  StartY := Y;

end;

{Use this code as the OnMouseUp event handler of the form:}

procedure TForm1.FormMouseUp(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Form1.Canvas.Rectangle(StartX, StartY, X, Y);

end;


See also

OnMouseDown event

OnMouseMove event


OnNewRecord event

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property OnNewRecord: TDataSetNotifyEvent;

Description

The OnNewRecord event is activated whenever a new record is added to the dataset. The event occurs after the BeforeInsert event and before the AfterInsert event. OnNewRecord enables you to initialize any fields of the record without marking the record as Modified. Any changes to the record after this event will cause Modified to be set.


See also

Append method

Insert method


OnNotify event

See also	Example

Applies to

TMediaPlayer component

Declaration

property OnNotify: TNotifyEvent;

Description

An OnNotify event occurs upon the completion of a media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, Resume, Rewind, StartRecording, Step, or Stop) when the Notify property is set to True before the call to the media control method. After an OnNotify event, the Notify property must be reset to True for the next OnNotify event to occur.


Example

Attach the following code to the OnNotify event handler of a media player named MediaPlayer1. If the Notify property of MediaPlayer1 is set to True, this code displays the value of the NotifyValue property in a message dialog box.

procedure TForm1.MediaPlayer1Notify(Sender: TObject);

var

  MyString: string;

begin

  case MediaPlayer1.NotifyValue of

    nvSuccessful : MyString := 'Success!';

    nvSuperseded : MyString := 'Superseded!';

    nvAborted    : MyString := 'Aborted!';

    nvFailure    : MyString := 'Failure!';

  end;

  MessageDlg('Notify value indicates: ' + MyString, mtInformation, [mbOk], 0)

end;


See also

NotifyValue property

Wait property


OnOpen event

See also	Example

Applies to

TDDEClientConv, TDDEServerConv components

Declaration

property OnOpen: TNotifyEvent;

Description

An OnOpen event occurs when a DDE conversation is opened. A DDE conversation can be initiated automatically or manually. Automatically open a conversation by setting the value of the ConnectMode property to ddeAutomatic. When the form containing the DDE client conversation component is created at run time, the DDE conversation opens. Manually open a conversation by setting the value of ConnectMode to ddeManual and calling the OpenLink method.


Example

The following code sends a macro to the server and closes the link immediately after opening it.

procedure TForm1.DdeClientConv1Open(Sender: TObject);

begin

  with DDEClientConv1 do

  begin

    ExecuteMacro('File|New', False);

    CloseLink;

  end;

end;


See also

OnClose event


OnPageChanged event

See also	Example

Applies to

TNotebook component

Declaration

property OnPageChanged: TNotifyEvent;

Description

The OnPageChanged event occurs just after a new page becomes the active page. Use the OnPageChanged event handler to specify special processing you want to happen at that time.


Example

This example changes the color notebook page each time the OnPageChanged event occurs. To set up the example, add pages to the notebook with the Object Inspector using the Pages property.

var

  NewColor: TColor;

procedure TForm1.FormCreate(Sender: TObject);

begin

  TabSet1.Tabs := Notebook1.Pages;

end;

procedure TForm1.TabSet1Change(Sender: TObject; NewTab: Integer;

  var AllowChange: Boolean);

begin

  Notebook1.PageIndex := TabSet1.TabIndex;

end;

procedure TForm1.Notebook1PageChanged(Sender: TObject);

begin

  NewColor := Notebook1.Color + 3475;

  Notebook1.Color := NewColor;

end;


See also

ActivePage property

Pages property


OnPaint event

See also	Example

Applies to

TForm, TPaintBox component

Declaration

property OnPaint: TNotifyEvent;

Description

The OnPaint event occurs when Windows requires the form or paint box to paint, such as when the form or paint box receives focus or becomes visible when it wasn't previously. Your application can use this event to draw on the canvas of the form or paint box.


Example

The following code is an entire unit that loads a background bitmap onto the Canvas of the main form in the OnPaint event handler.

unit Unit1;

interface

uses

  SysUtils, WinTypes, WinProcs, Messages, Classes, Graphics, Controls, Forms, Dialogs;

type

  TForm1 = class(TForm)

    procedure FormPaint(Sender: TObject);

    procedure FormCreate(Sender: TObject);

  private

    TheGraphic: TBitmap; { Add this declaration for the graphic}

  public

    { Public declarations }

  end;

var

  Form1: TForm1;

implementation

{$R *.DFM}

procedure TForm1.FormPaint(Sender: TObject); { OnPaint event handler}

begin

  Form1.Canvas.Draw(0, 0, TheGraphic); { Draw the graphic on the Canvas }

end;

procedure TForm1.FormCreate(Sender: TObject); { OnCreate event handler }

begin

  TheGraphic := TBitmap.Create; { Create the bitmap object }

  TheGraphic.LoadFromFile('C:\APP\BKGRND.BMP'); { Load the bitmap from a file}

end;

end.


See also

Canvas property


OnPaintPanel event

Applies to

TDBCtrlGrid component

Declaration

TPaintPanelEvent = procedure(DBCtrlGrid: TDBCtrlGrid; Index: Integer) of object;

property OnPaintPanel: TPaintPanelEvent;

Description

Called for each visible panel in the record grid before displaying the panel's controls.

The TPaintPanelEvent type points to a method that handles a panel-painting event for a TDBCtrlGrid component. The DBCtrlGrid parameter indicates which grid is currently painting, and the Index parameter specifies which panel in that grid to paint.


OnPassword event

Applies to

TSession component

Declaration

TPasswordEvent = procedure(Sender: TObject; var Continue: Boolean);

property OnPassword: TPasswordEvent;

Description

The OnPassword event is activated whenever a Paradox table is opened and the Borland Database Engine reports that the application does not have sufficient access rights.

The TPasswordEvent type is a pointer to a method that handles a password exception event. The value of Sender is the Session component. Continue determines whether the caller will make another attempt to access the database. The procedure should add any available additional passwords and set Continue to True. If there are no additional passwords available, set Continue to False.

If no OnPassword event is defined, Session will create a default dialog box for the user to enter a new password.


OnPokeData event

See also	Example

Applies to

TDDEServerItem component

Declaration

property OnPokeData: TNotifyEvent

Description

The OnPokeData event occurs when the DDE client application pokes data to your DDE server application. When a client pokes data, it sends text to the linked DDE server. The Text and Lines properties will be updated to contain the poked data, then the OnPokeData event occurs.

If the DDE client is a Delphi application that uses a TDDEClientConv component, data is poked when the PokeData or PokeDataLines method is called.


Example

The following code uses a Boolean variable FInPoke to protect poked data from being lost by a DDE server application. DoOnPoke is the OnPokeData event handler for the DDE server item component named DDETestItem. When data is poked, FInPoke is set to True, the poked data is stored in the Lines property of Memo2, and FInPoke is set back to False.

The data should be protected because the server data is updated when the Lines of Memo1 are updated by the user. DoOnChange, the OnChange event handler for Memo1, tests FInPoke before updating the server data in DDETestItem. Otherwise, data poked from the client could be lost when Memo1.Lines is changed.

var

  FInPoke: Boolean;

.

.

.

procedure TDdeSrvrForm.doOnPoke(Sender: TObject);

begin

  FInPoke := True;

  Memo2.Lines := DdeTestItem.Lines;

  FInPoke := False;

end;

procedure TDdeSrvrForm.doOnChange(Sender: TObject);

begin

  if not FInPoke then

    DdeTestItem.Lines := Memo1.Lines;

end;


See also

OnExecuteMacro event


OnPopup event

See also	Example

Applies to

TPopupMenu component

Declaration

property OnPopup: TNotifyEvent;

Description

The OnPopup event occurs whenever a pop-up menu appears either because the user right-clicks the component when the pop-up menu's AutoPopup is True or because the Popup method executed. Use the OnPopup event handler when you want some special processing to occur when the component's pop-up menu appears.


Example

The following code enables the Paste item from the pop-up menu if the Clipboard has text data.

procedure TForm1.PopupMenu1Popup(Sender: TObject);

begin

  Paste1.Enabled := Clipboard.HasFormat(CF_TEXT);

end;


See also

PopupMenu property


OnPostClick event

See also

Applies to

TMediaPlayer component

Declaration

EMPPostNotify = procedure (Sender: TObject; Button: TMPBtnType) of object;

property OnPostClick: EMPPostNotify;

Description

An OnPostClick event is generated after the code of the OnClick event handler has been called. If Wait is True when the media player was clicked, OnPostClick won't be called until the completion of the OnClick code. If Wait is False, control can return to the application before completion of the OnClick code; therefore, the OnPostClick event may occur before the actions initiated by the OnClick event have completed.

For example, if the user clicks the Play button and the DoDefault parameter of the OnClick event handler for the media player is True, the media is played. If the media is long enough, it will still be playing when the OnPostClick event is generated if Wait is True. If Wait is False, however, OnPostClick won't occur until the media has finished playing.

The EMPPostNotify type is a pointer to a method that is called when an OnPostClick event for a TMediaPlayer component occurs. The .Button argument can be one of the following values: btBack, btEject, btNext, btPause, btPlay, btPrev, btRecord, btStep, or btStop.


See also

OnClick event


OnPostError event

Applies to

TTable, TQuery, TStoredProc components

Declaration

type
  TDataSetErrorEvent = procedure(DataSet: TDataSet; E: EDatabaseError;
  var Action: TDataAction) of object;

property OnPostError: TDataSetErrorEvent;

Description

The OnPostError event occurs when there was an error posting the current record, such as an integrity violation if key fields changed. The DataSet parameter is the dataset that had the problem. The E parameter is an EDatabaseError exception object that contains details about the problem. Action is a var parameter that lets you control how the error is handled when the event handler finishes.

TDataSetErrorEvent defines the type of the OnPostError event handler.


OnProtectChange event

See also

Applies to

TRichEdit component

Declaration

TRichEditProtectChange = procedure(Sender: TObject; StartPos, EndPos: Integer; var AllowChange: Boolean) of object;

property OnProtectChange: TRichEditProtectChange;

Description

The OnProtectChange event occurs when a user attempts to modify text that has been marked as protected.

The TRichEditProtectChange type is a pointer to a method that is called when the OnProtectChange event occurs. The StartPos and EndPos parameters indicate the beginning and ending of the range of text that would be affected by the modification. AllowChange indicates whether or not should be modified. To allow modification of protected text set AllowChange to True. The default is False.

To set or unset text as protected, use the run-time Protected property of the TTextAttributes object.


See also

Protected property


OnReplace event

See also	Example

Applies to

TReplaceDialog components

Declaration

property OnReplace: TNotifyEvent;

Description

The OnReplace event occurs whenever the user chooses either the Replace or the Replace All button in the Replace dialog box. Use the OnReplace event to specify the processing that replaces text.

Because the OnReplace event occurs when the user chooses either the Replace or Replace All button, the code you write in the OnReplace event handler should determine which button was chosen and supply the appropriate logic. Use the frReplace and frReplaceAll values in the Options set to determine which button was chosen.


Example

The following code calls the user-defined routine DoReplace if the Replace button was clicked, or calls the user-defined routine DoReplaceAll if the Replace All button was clicked.

procedure TForm1.ReplaceDialog1Replace(Sender: TObject);

begin

  if (ReplaceDialog1.Options*[frReplace])=[frReplace] then DoReplace

  else if (ReplaceDialog1.Options*[frReplaceAll])=[frReplaceAll] then DoReplaceAll;

end;


See also

OnFind event


OnResize event

Applies to

TDBNavigator, TForm, THeaderControl, TStatusBar, TPanel, TScrollBox, TOleContainer components

Description

OnResize event for DBNavigators, Forms, Scroll Boxes and Panels

OnResize event for Header and StatusBar Controls

OnResize event for Ole Containers


OnResize event

Applies to

TOleContainer component

Declaration

property OnResize: TNotifyEvent;

Description

Occurs when the container is resized.


OnResize event for DBNavigators, forms, scroll boxes and panels
OnResize event

Example

Applies to

TDBNavigator, TForm, TPanel, TScrollBox components

Declaration

property OnResize: TNotifyEvent;

Description

The OnResize event occurs whenever the form is resized while an application is running. Use the OnResize event handler when you want something to happen in your application when the form is resized.


Example

The following code keeps the right edge on Button1 against the right edge of Form1 when Form1 is resized.

procedure TForm1.FormResize(Sender: TObject);

begin

  Button1.Left := Form1.ClientWidth-Button1.Width;

end;


OnResize event for header controls
OnResize event

See also

Applies to

THeaderControl, TStatusBar components

Declaration

property OnResize: TNotifyEvent;

Description

The OnResize event occurs whenever the header or status bar control is resized while an application is running. This can occur when the form is resized and the Align property is set to anything except alNone. For example, when the Align property of the header or status bar control is set to alTop, the OnResize event will occur when the form is sized horizontally.


See also

Align property

OnSectionResize event


OnResizeRequest Event

See also	Example

Applies to

TRichEdit component

Declaration

TRichEditResizeEvent = procedure (Sender: TObject; Rect: TRect) of object;

property OnResizeRequest: TRichEditResizeEvent;

Description

The OnResizeRequest event indicates that the control is trying to change size because the text has grown beyond the size of its current boundaries. TRichEditResizeEvent is the type of the OnResizeRequest event of the TRichEdit component. OnResizeRequest gets a Rect parameter of type TRect that specifies the new rectangle for the control's boundaries. The size of Rect is sufficient to display all of the text in the rich edit.


Example

The following code resizes the rich edit control to accomodate growing or shrinking lines of text:

procedure TForm1.RichEditResizeRequest(sender: TObject; Rect: TRect);

begin

  RichEdit1.BoundsRect := Rect;

end;


See also

ScrollBars property

WordWrap property


OnRestore event

See also

Applies to

TApplication component

Declaration

property OnRestore: TNotifyEvent;

Description

The OnRestore event occurs when the previously minimized application is restored to its normal size, either because the user restores the application, or because the application calls the Restore method. Use the OnRestore event handler to put code that performs any special processing you want to happen as the application is restored.


See also

Minimize method

OnMinimize event


OnRowMoved event

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

TMovedEvent = procedure (Sender: TObject; FromIndex, ToIndex: Longint) of object;

property OnRowMoved: TMovedEvent;

Description

The OnRowMoved event occurs when the user moves a row using the mouse. The user can move a row only if the Options property set includes the value goRowMoving.

The TMovedEvent type points to a method that handles the moving of a column or row in a draw grid (TDrawGrid) or string grid (TStringGrid). The FromIndex parameter is the index of the column or row that is being moved, with the first column or row having an index value of 0. The ToIndex parameter value is the new location of the column or row after it is moved.


Example

The following code displays the number of rows a row was moved in a label.

procedure TForm1.StringGrid1RowMoved(Sender: TObject; FromIndex, ToIndex: Longint);

begin

  Label1 := IntToStr(Abs(FromIndex-ToIndex));

end;


See also

OnColumnMoved event


OnSaveClipboard event

Applies to

TRichEdit component

Declaration

TRichEditSaveClipboard = procedure(Sender: TObject; NumObjects, NumChars: Integer; var SaveClipboard: Boolean) of object;

property OnSaveClipboard: TRichEditSaveClipboard;

Description

The OnSaveClipboard event occurs when a rich edit control that has text in the Clipboard is about to be destroyed.

TRichEditSaveClipboard type is a pointer to a method that is called when the OnSaveClipboard event occurs. NumChars is the number of characters in the Clipboard and NumObjects is the number of objects in the Clipboard. The SaveClipboard parameter determines whether or not the Clipboard will be saved when the rich edit is destroyed. To destroy the Clipboard set SaveClipboard to False. The default is True.


OnScroll event

Example

Applies to

TScrollBar component

Declaration

TScrollEvent = procedure(Sender: TObject; ScrollCode: TScrollCode; var ScrollPos: Integer) of object;

property OnScroll: TScrollEvent;

Description

The OnScroll event occurs whenever the user uses the scroll bar control. Use the OnScroll event handler if you want something to happen when the user uses the scroll bar control. Within the handler, write the code that responds to the user using the scroll bar.

The TScrollEvent type points to a method that handles the scrolling of a scroll bar. The ScrollCode parameter is one of these values::

Value	Meaning

scLineUp	User clicked the top or left scroll arrow or pressed the Up arrow key

scLineDown	User clicked the bottom or right scroll arrow or pressed the Down arrow key

scPageUp	User clicked the area to the left of the thumb tab or pressed the PgUp key

scPageDown	User clicked the area to the right of the thumb tab or pressed the PgDn key

scPosition	User positioned the thumb tab and released it.

scTrack	User is moving the thumb tab

scTop	User moved the thumb tab to the top or far left on the scroll bar

scBottom	User moved the thumb tab to the bottom or far right on the scroll bar

scEndScroll	User is done moving the thumb tab on the scroll bar

The ScrollPos parameter indicates the position of the thumb tab on the scroll bar.


Example

The following code repositions the thumb tab position by varying amounts. If Page Up was pressed, the box moves up only one. If Page Down was pressed, the box moves down 10. This shows how you can use the OnScroll event handler to move the thumb tab by different increments than specified by the LargeChange and SmallChange properties.

procedure TForm1.ScrollBar1Scroll(Sender: TObject; ScrollCode: TScrollCode;

  var ScrollPos: Integer);

begin

  if ScrollCode = scPageUp then ScrollPos := ScrollPos - 1

    else if ScrollCode = scPageDown then ScrollPos := ScrollPos + 10;

  Label1.Caption := IntToStr(ScrollPos);

end;


OnSectionClick event

See also

Applies to

THeaderControl component

Declaration

TSectionNotifyEvent = procedure (HeaderControl: THeaderControl; Section: THeaderSection) of object;

property OnSectionClick: TSectionNotifyEvent;

Description

OnSectionClick occurs when a section is clicked, after the control is refreshed. Sections have a similar pressed appearance as do buttons when they are clicked. To disable a section from being clicked set its AllowClick property to False.

TSectionNotifyEvent is the type of the OnSectionClick and OnSectionResize events of the THeaderControl component.


See also

AllowClick property


OnSectionResize event

See also

Applies to

THeaderControl component

Declaration

TSectionNotifyEvent = procedure (HeaderControl: THeaderControl; Section: THeaderSection) of object;

property OnSectionResize: TSectionNotifyEvent;

Description

The OnSectionResize event occurs whenever the size of a section in a header control is changed by dragging a divider in the control to a new position. Use the OnSection event handler when you want something to happen in your application when a section header is resized.

TSectionNotifyEvent is the type of the OnSectionClick and OnSectionResize events of the THeaderControl component.


See also

OnResize event


OnSectionTrack event

See also	Example

Applies to

THeaderControl component

Declaration

TSectionTrackEvent = procedure (HeaderControl: THeaderControl; Section: THeaderSection; Width: Integer; State: TSectionTrackState) of object;

TSectionTrackState = (tsTrackBegin, tsTrackMove, tsTrackEnd);

property OnSectionTrack: TSectionTrackEvent;

Description

The OnSectionTrack event occurs when a section in a header control is moved by dragging a divider in the control. To drag the divider, left click the mouse while it is on the divider between Sections and drag it to the desired width of that section.

OnSectionTrack is of type TSectionTrackEvent. The state parameter of this event type indicates which of the three states is occurring. These are the three possible values for those states:

Value	Meaning

tsTrackBegin	Indicates that the divider is about to be dragged.

tsTrackMove	Indicates that the divider is being dragged.

tsTrackEnd	Signals the end of the divider dragging.

Use OnSectionTrack when you want something to happen in your application when the Sections are being moved.

The TSectionTrackState type defines the possible values of the State parameter of TSectionTrackEvent, which is the type of OnSectionTrack event.


Example

The following code queries the tracking state and simply prints the state out as the caption:

procedure TForm1.HeaderControl1SectionTrack(HeaderControl: THeaderControl;

  Section: THeaderSection; Width: Integer; State: TSectionTrackState);

begin

  With Panel1 do

    Case State of

    tsTrackBegin:

      Caption := 'Begin Tracking';

    tsTrackMove:

      Caption := 'Tracking';

    tsTrackEnd:

      Caption := 'End Tracking';

  end;

end;


See also

OnResize event

Sections property


OnSelectCell event

Example

Applies to

TDrawGrid, TStringGrid component

Declaration

TSelectCellEvent = procedure (Sender: TObject; Col, Row: Longint; var CanSelect: Boolean) of object;

property OnSelectCell: TSelectCellEvent;

Description

The OnSelectCell event occurs when the user selects a cell in a draw grid or string grid. Use the OnSelectCell event handler to write the code that handles the selecting of a cell. Using the CanSelect parameter of the event handler type, your code can determine whether the user can select a cell or not.

The TSelectCellEvent type points to a method that handles the selecting of a cell in a draw grid (TDrawGrid) or string grid (TStringGrid). The Col and Row parameters specify the column and row of the selected cell. The value of the CanSelect parameter determines whether the user can successfully select the cell in the grid.


Example

The following code determines that the user cannot select a cell containing the text 'No'.

procedure TForm1.StringGrid1SelectCell(Sender: TObject; Col, Row: Longint;

  var CanSelect: Boolean);

begin

  CanSelect := not (StringGrid1.Cells[Col,Row]='No')

end;


OnSelectionChange Event

See also

Applies to

TRichEdit component

Declaration

property OnSelectionChange: TNotifyEvent;

Description

The OnSelectionChange event occurs when the current selection of text changes. The user selects text by using the mouse or the keyboard. The current selection is the range of highlighted characters, or if no characters are selected it is the position of the cursor.


See also

HideSelection property

SelAttributes property


OnSetEditText event

See also

Applies to

TDrawGrid, TStringGrid component

Declaration

TSetEditEvent = procedure (Sender: TObject; ACol, ARow: Longint; const Text: string)
  of object;

property OnSetEditText: TSetEditTextEvent;

Description

The OnSetEditText event occurs when the user edits the text in the grid. The user can edit the text only if the Options property set contains the value goEditing. The OnSetEditText event makes the actual changes to the data. Use the OnSetEditText event handler to write the code to handle the changes to the text within a cell of the grid.

When the user edits data in a grid, the OnSetEditText event occurs to change the actual data, and then the OnGetEditText event occurs to display the changed data in the grid.

The TSetEditEvent type points to a method that handles the changes the user makes to the text in a cell in a draw grid (TDrawGrid) or string grid (TStringGrid). The ACol parameter specifies the column of the cell, and the ARow parameter specifies the row of the cell. The Text parameter is the text string the editor has changed.


See also

OnGetEditText event


OnSetText event

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

TFieldSetTextEvent = procedure(Sender: TField; const Text: string) of object;

property OnSetText: TFieldSetTextEvent;

Description

The OnSetText event is activated when the Text property is assigned a value. If OnSetText has been assigned a method, the default processing for Text does not occur. The event handler must store the text provided by Text.

By assigning a method to this property, you can take any special actions required by the event.

The TFieldSetTextEvent type points to a method that stores text in a field. The Text parameter is the text that is being stored in the field.


OnShow event

See also	Example

Applies to

TForm component

Declaration

property OnShow: TNotifyEvent;

Description

The OnShow event occurs just before a form becomes visible. Use the OnShow event to specify any special processing you want to happen before the form appears.


Example

This example colors the form and changes its caption when it becomes visible:

procedure TForm1.FormShow(Sender: TObject);

begin

  Color := clLime;

  Caption := 'I am showing';

end;


See also

OnHide event


OnShowHint event

See also	Example

Applies to

TApplication

Declaration

TShowHintEvent = procedure (var HintStr: string; var CanShow: Boolean; var HintInfo: THintInfo) of object;

property OnShowHint: TShowHintEvent;

Description

The OnShowHint event occurs when the application is about to display a hint window for a Help Hint for a particular control. By writing an event handler for OnShowHint, you can change the appearance and behavior of the Help Hint.

The TShowHintEvent type points to a method that displays a Help Hint for a control. The HintStr parameter is the text of the Help Hint. To obtain the text of a hint for a particular control, call the GetShortHint function, assigning the result to HintStr. You can change the contents of this string if you want to change the text.

Use the CanShow variable to permit or prevent the Help Hint from displaying. If CanShow is True, the Help Hint displays. If it is False, the Help Hint does not appear.

The HintInfo parameter is a record that contains information about the appearance and behavior of the Help window.

The HintColor field of the record contains the name of the control for which hint processing is occurring.

The HintPos field determines the default position in screen coordinates of the top-left corner of the hint window. You can change where the window appears by changing this value.

The HintMaxWidth field determines the maximum width of the hint window before word wrapping begins. By default, the value is the width of the screen (Screen.Width).

The CursorRect field determines the rectangle the user's mouse pointer must be in for the hint window to appear. The default value for CursorRect is the client rectangle of the control. Your application can change this value so that a single control can divided into several hint regions. When the user moves the mouse pointer moves outside the rectangle, the hint window disappears.

The CursorPos field contains the location of the mouse pointer within the control.


Example

This example uses three speed buttons on a panel. The code changes the color, width, and position of the text in the Help Hint for the third speed button.

You must declare the DoShow method in the type declaration of the form. Once it is declared, write the code for the DoShow method in the implementation part of the unit. Finally, in the OnCreate event handler for the form, assign the method to the OnShowHint event of the application.

type

  TForm1 = class(TForm)

    Panel1: TPanel;

    SpeedButton1: TSpeedButton;

    SpeedButton2: TSpeedButton;

    SpeedButton3: TSpeedButton;

    procedure FormCreate(Sender: TObject);

   private

    { Private declarations }

  public

    procedure DoShowHint(var HintStr: string; var CanShow: Boolean;

      var HintInfo: THintInfo;

  end;

var

  Form1: TForm1;

implementation

{$R *.DFM}

procedure TForm1.DoShowHint(var HintStr: string; var CanShow: Boolean;

   var HintInfo: THintInfo);

begin

  if HintInfo.HintControl = SpeedButton3 then

  begin

    with HintInfo do

    begin

      HintColor := clAqua;                             { Changes only for this hint }

      MaxHintWidth := 120;       {Hint text word wraps if width is greater than 120 }

      Inc(HintPos.X, SpeedButton3.Width);                 { Move hint to right edge }

    end;

  end;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.OnShowHint := DoShowHint;

end;

end.


See also

Hint property

OnHint event

ParentShowHint property

ShowHint property


OnSized event

See also	Example

Applies to

THeader component

Declaration

TSectionEvent = procedure(Sender: TObject; ASection, AWidth: Integer) of object;

property OnSized: TSectionEvent;

Description

An OnSized event is generated when a sizing operation of a header is complete. A user can resize the header section at run time if the AllowResize property is set to True. Your application can resize the header section at run time by assigning a new value to the SectionWidth property.

The TSectionEvent type is a pointer to a method that is called after resizing of the header is complete. The index of the header section being resized is passed in the ASection parameter, and its width in pixels is passed in the AWidth parameter.


Example

The following code displays the new width of the sized header section in a label.

procedure TForm1.Header1Sized(Sender: TObject; ASection, AWidth: Integer);

begin

  Label1.Caption := IntToStr(AWidth);

end;


See also

OnSizing event


OnSizing event

See also	Example

Applies to

THeader component

Declaration

TSectionEvent = procedure(Sender: TObject; ASection, AWidth: Integer) of object;

property OnSizing: TSectionEvent;

Description

An OnSizing event is generated for each mouse movement when a user is resizing a header by clicking and dragging at run time.

The TSectionEvent type is a pointer to a method that is called during the resizing operation. The index of the header section being resized is passed in the ASection parameter, and its width in pixels is passed in the AWidth parameter.


Example

The following code displays the width of the header section that is being resized. As the user drags the mouse pointer, the label is continuously updated.

procedure TForm1.Header1Sized(Sender: TObject; ASection, AWidth: Integer);

begin

  Label1.Caption := IntToStr(AWidth);

end;


See also

AllowResize property

OnSized event


OnStartDrag event

See also

Applies to

Most visible controls

Declaration

TStartDragEvent = procedure (Sender: TObject; var DragObject: TDragObject) of object;

property OnStartDrag: TStartDragEvent;

Description

The OnStartDrag event occurs when the user has begun to drag an object by left clicking on a component.


See also

OnEndDrag event

OnDragOver event

OnDragDrop event


OnStartup event

Applies to

TSession component

Declaration

property OnStartup: TNotifyEvent;

Description

The OnStartup event fires as part of the session becoming active. It fires before the session actually becomes active, and is a good place to set properties like NetFileDir and PrivateDir if you need to determine them at run-time.


OnStateChange event

See also

Applies to

TDataSource component

Declaration

property OnStateChange: TNotifyEvent;

Description

OnStateChange is activated when the State property changes.

By assigning a method to this property, you can react programmatically to state changes. For example, this event is useful for enabling or disabling buttons (for example, enabling an edit button only when a table is in edit mode), or displaying processing messages.

Note:	OnChangeState can occur even for nil datasets, so it is important to protect any reference to the DataSet property with a nil test:

if DataSource1.Dataset <> nil then

...


See also

OnDataChange event


OnTimer event

See also	Example

Applies to

TTimer component

Declaration

property OnTimer: TNotifyEvent;

Description

The OnTimer event is used to execute code at regular intervals. Place the code you want to execute within the OnTimer event handler.

The Interval property of a timer component determines how frequently the OnTimer event occurs. Each time the specified interval passes, the OnTimer event occurs.


Example

Here is an example of an OnTimer event handler that moves a ball slowly across the screen:

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  Timer1.Interval := 100;

  Shape1.Left := Shape1.Left + 1;

end;


See also

Interval property


OnTopLeftChanged event

Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property OnTopLeftChanged: TNotifyEvent;

Description

The OnTopLeftChanged event occurs whenever the value of either the TopRow property or LeftCol property changes.


Example

The following code displays the latest top row and left column of StringGrid1.

procedure TForm1.StringGrid1TopLeftChanged(Sender: TObject);

begin

  with StringGrid1 do

    MessageDlg('The top row is now '+IntToStr(TopRow)+

      ' and the left col is now '+IntToStr(LeftCol), mtInformation, [mbOK],0);

end;


OnUpdateData event

See also

Applies to

TDataSource component

Declaration

property OnUpdateData: TNotifyEvent;

Description

OnUpdateData is activated by the Post or UpdateRecord method of a dataset component when the current record is about to be updated in the database. It causes all data-aware controls connected to the data source to be notified of the pending update, allowing them to change their associated fields to the current values in the controls. By assigning a method to this property, you can react programmatically to updates.


See also

BeforePost event


OnUpdateError event

Applies to

TTable, TQuery, TStoredProc components

Declaration

type
  TUpdateErrorEvent = procedure(DataSet: TDataSet; E: EDatabaseError;
      UpdateKind: TUpdateKind; var UpdateAction: TUpdateAction) of object;

property OnUpdateError: TUpdateErrorEvent;

Description

The OnUpdateError event occurs when cached updates are enabled (CachedUpdates is True), applied (ApplyUpdates), and there are errors applying the updates. Such errors include integrity violations and cached records being modified or deleted by another user. OnUpdateError event handlers are supplied with the dataset that was involved, an EDatabaseError exception object to get more details about the error, the status code indicating the problem, and a var parameter that lets you specify how the error should be dealt with. If you don't change UpdateAction, the processing of cached updates will fail with an exception.

The TUpdateErrorEvent type defines the type of method that handles errors during the application of cached updates.


OnUpdateRecord event

Applies to

TTable, TQuery, TStoredProc components

Declaration

type
  TUpdateRecordEvent = procedure(DataSet: TDataSet; UpdateKind: TUpdateKind;
      var UpdateAction: TUpdateAction) of object;

property OnUpdateRecord: TUpdateRecordEvent;

Description

The OnUpdateRecord event occurs when cached updates are enabled (CachedUpdates is True) and applied (ApplyUpdates). It doesn't indicate an error (if there is an error, the OnUpdateError event occurs). One OnUpdateRecord event occurs for each record being updated. OnUpdateRecord lets you manually perform the updates for a read-only dataset. You can use a TUpdateSQL component (assigned to the dataset's UpdateObject property) to handle the updates; call TUpdateSQL's Apply method, for example, to apply an update based on the SQL statements you provide.

OnUpdateRecord event handlers are supplied with the dataset being updated, a status code indicating the kind of update being performed, and a var parameter that lets you specify how (or whether) the cached update was applied.

The TUpdateRecordEvent type defines the type of method that handles OnUpdateRecord events.


OnValidate event

Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

TFieldNotifyEvent = procedure(Sender: TField) of object;

property OnValidate: TFieldNotifyEvent;

Description

The OnValidate event is activated when a field is modified. If a data-aware control is linked to the field, changes in the control do not activate OnValidate until the control attempts to store the results of those changes into the current record.

By assigning a method to this property, you can perform any special validation required for the field.

The TFieldNotifyEvent type points to a method that handles the validation of data in a field or handles the changing of data in a field.


Example

Field1.OnValidate := ValidateFieldRange;


Open method

Applies to

TClipboard object; TDatabase, TMediaPlayer, TQuery,TSession, TStoredProc, TTable components

Description

Open for Clipboard Objects

Open for Media Player Controls

Open for Databases

Open for Tables, Queries, and Stored Procedures

Open for Sessions


Open method

See also

Applies to

TClipboard objec

Declaration

procedure Open;

Description

The Open method opens the Clipboard and prevents other applications from changing its contents until the Clipboard is closed. If you are adding a single item to the Clipboard, your application doesn't have to call Open. If you want to add a series of items to the Clipboard, however, Open prevents the contents from being overwritten with each addition.

When your application has added all items to the Clipboard, it should call the Close method.


See also

Clear method

Clipboard variable

Close method


Open method

See also	Example

Applies to

TMediaPlayer components

Declaration

procedure Open;

Description

The Open method opens a multimedia device. The multimedia device type must be specified in the DeviceType property before you can open a device.

Upon completion, Open stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Open method is completed. The Notify property determines whether Open generates an OnNotify event.


Example

This example begins playing an audio CD when the application begins running. When the application is closed, the CD automatically stops playing. For this example to run successfully, you must have an audio CD device installed correctly.

procedure TForm1.FormCreate(Sender: TObject);

begin

with MediaPlayer1 do

  begin

    DeviceType := dtCDAudio;

    Visible := False;

    Open;

    Play;

  end;

end;


See also

AutoOpen property

Close method


Open method

See also

Applies to

TSession components

Declaration

procedure Open;

Description

The Open method opens the session and makes it the active one, exactly the same as setting the Active property to True.


See also

Close method

Session variable

Active property


Open method

See also	Example

Applies to

TQuery, TStoredProc, TTable components

Declaration

procedure Open;

Description

The Open method opens the dataset, putting it in Browse state. It is equivalent to setting the Active property to True.

For TQuery, Open executes the SELECT statement in the SQL property. If the statement does not return a result set (for example, an INSERT or UPDATE statement), then use ExecSQL instead of Open.

For TStoredProc, use Open to execute the stored procedure if the procedure returns a result set. If the stored procedure returns a single row, use ExecProc instead.


Example

try

  Table1.Open;

except

  on EDataBaseError do { The dataset could not be opened };

end;


See also

Close method


Open method

Example

Applies to

TDatabase component

Declaration

procedure Open;

Description

The Open method connects the TDatabase component to the server (or BDE for Paradox and dBASE databases). This is the same as setting Connected to True.


Example

Database1.Open;


OpenCurrent method

Example

Applies to

TDirectoryListBox component

Declaration

procedure OpenCurrent;

Description

The OpenCurrent method opens the directory selected in the directory list box, as if the user had double-clicked the directory.


Example

This example uses a directory list box, a button, and a label on a form. When the user selects a directory in the directory list box and clicks the button, the selected directory opens, and the path of the second directory displayed in the list box appears as the caption of the label.

procedure TForm1.Button1Click(Sender: TObject);

begin

  DirectoryListBox1.OpenCurrent;

  Label1.Caption := DirectoryListBox1.GetItemPath(1);

end;


OpenDatabase method

See also	Example

Applies to

TSession component

Declaration

function OpenDatabase(const DatabaseName: string): TDatabase;

Description

The OpenDatabase method attempts to find a TDatabase component with a DatabaseName property matching the DatabaseName parameter by calling the FindDatabase method. If no such database can be found, it creates a new database component. OpenDatabase returns either the found database component or the one created. The database returned will be opened during this process. OpenDatabase increments the Session's reference count of the number of open database connections.

Use OpenDatabase with CloseDatabase in a try...finally block to ensure that database connections are handled properly.


Example

Database := Session.OpenDatabase('DBDEMOS');

try

    {Do Something}

  finally

    Session.CloseDatabase('DBDEMOS');

end;


See also

Session variable


OpenIndexFile method

See also

Applies to

TTable component

Declaration

procedure OpenIndexFile(const IndexName: string);

Description

Opens the specified dBASE non-production index file. While non-production indexes are open, updates made to the table maintain the indexes. You can make one the active index by setting the IndexName property.


See also

CloseIndexFile method

IndexFiles property


OpenLink method

See also	Example

Applies to

TDDEClientConv component

Declaration

function OpenLink: Boolean;

Description

The OpenLink method initiates a new DDE conversation. If the conversation was successfully opened, an OnOpen event occurs and OpenLink returns True. If the conversation wasn't successfully opened, OpenLink returns False.


Example

The following code requests data if a link is open.

if OpenLink then DDEClientConv1.RequestData(DDEClientItem1.DDEItem);


See also

CloseLink method


OpenSession method

See also

Applies to

TSessionList object

Declaration

function OpenSession(const SessionName: string): TSession;

Description

OpenSession searches for a session whose SessionName property matches the name you supply. If it finds a match, it starts that session (if not already started). If it can't find a name match, it creates a new session with the specified name and starts it. In either case, OpenSession returns the session object.


See also

FindSession method

List property

SessionList variable


Options property

Applies to

TIndexDef object; TColorDialog, TDBGrid, TDBLookupCombo, TDBLookupList, TDrawGrid, TFindDialog, TFontDialog, TOpenDialog, TOutline, TPrintDialog, TReplaceDialog, TSaveDialog, TStringGrid components

Description

The Options property is a set of options that affects how dialog boxes, outlines, and grids appear and behave. The possible values contained within the set vary depending on the type of dialog box or if the component is an outline or grid control.

Options for Color dialog boxes

Options for Font dialog boxes

Options for Print dialog boxes

Options for Open and Save dialog boxes

Options for Find and Replace dialog boxes

Options for Outlines

Options for Draw and String Grid Controls

Options for Data Grid Controls

Options for Database Lookup List Boxes and Database Lookup Combo Boxes

Options for TIndexDef Objects


Options property

See also	Example

Applies to

TColorDialog component

Declaration

property Options: TColorDialogOptions;

Description

These are the possible values that can be included in the Options set:

Value	Meaning

cdFullOpen	Displays the custom coloring options when the Color dialog opens

cdPreventFullOpen	Disables the Create Custom Colors button in the Color dialog box so the user cannot create their own custom colors.

cdShowHelp	Adds a Help button to the Color dialog box.

cdSolidColor	Directs the dialog box to display only solid colors.

cdAnyColor	Directs the dialog box to display any color.

The default value is [ ], the empty set, meaning all of these values are False and none of the options are in effect.


Example

This example displays the Color dialog box with a Help button and the Create Custom Colors button dimmed. The form is colored whatever color the user chooses.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ColorDialog1.Options := [cdPreventFullOpen, cdShowHelp];

  if ColorDialog1.Execute then

    Color := ColorDialog1.Color;

end;


See also

Color property

CustomColors property


Options property

See also	Example

Applies to

TFontDialog component

Declaration

property Options: TFontDialogOptions

Description

These are the possible values that can be included in the Options set for the Fonts dialog box:

Value	Meaning

fdAnsiOnly	If True, the user can select fonts that use the Windows character set only; that is, the user can't choose a font that contains only symbols because they aren't displayed in the Font combo box.

fdApplyButton	The apply button appears automatically if there is an event handler for the OnApply event, in which case the flag is ignored. If there is no event handler for OnApply, then the flag controls the appearance of the button.

fdEffects	If True, the Effects check boxes and the Color list box appear in the Font dialog box. The user uses the Effects check boxes to specify strikeout or underlined text and the Color list box to select a color for the selected font. If fdEffects is False, the Effects check boxes and Color list box don't appear in the Font dialog box.

fdFixedPitchOnly	If True, only monospaced fonts are displayed in the Font combo box.

fdForceFontExist	If True and the user enters a font name in the Font combo box and chooses OK, a message dialog box appears informing the user the font name is invalid.

fdLimitSize	If True, the MinFontSize and MaxFontSize properties can limit the number of fonts available in the dialog box.

fdNoFaceSel	If True, when the dialog box appears, no font name is selected in the Font combo box.

fdNoOEMFonts	If True, only fonts that aren't vector fonts are displayed in the Font combo box.

fdScalableOnly	If True, only fonts that can be scaled are displayed in the Font combo box.

fdNoSimulations	If True, only fonts that aren't GDI font simulations are displayed in the Font combo box.

fdNoSizeSel	If True, when the dialog box appears, no size is selected in the Size combo box.

fdNoStyleSel	If True, when the dialog box appears, no style is selected in the Style combo box.

fdNoVectorFonts	Same as fdNoOEMFonts.

fdShowHelp	If True, a Help button appears in the dialog box.

fdTrueTypeOnly	If True, only TrueType fonts are displayed in the Font list box.

fdWysiwyg	If True, only fonts that are available to both the printer and the screen appear in the Font combo box.

The default value is [fdEffects], meaning that only the fdEffects option is in effect.


Example

This example sets the options of the Font dialog box so that when the dialog box displays, only TrueType fonts show in the list of fonts and no font size is selected:

procedure TForm1.Button1Click(Sender: TObject);

begin

  FontDialog1.Options := [fdTrueTypeOnly, fdNoSizeSel];

  if FontDialog1.Execute then

    Memo1.Font := FontDialog1.Font;

end;


See also

Font property


Options property for Print common dialog box
Options property

See also	Example

Applies to

TPrintDialog component

Declaration

property Options: TPrintDialogOptions;

Description

These are the possible values that can be included in the Options set for the Print dialog box:

Value	Meaning

poHelp	If True, a Help button appears in the dialog box.

poPageNums	If True, the Pages radio button is enabled and the user can specify a range of pages to print.

poPrintToFile	If True, a Print to File check box appears in the dialog box and reflects the state of the checkbox when the dialog box is dispatched by the user.

poSelection	If True, the Selection radio button is enabled and the user can choose to print selected text.

poWarning	If True and if no printer is installed, a warning message appears when the user chooses OK.

poDisablePrintToFile	If True and poPrintToFile is True, the Print to File check box is dimmed when the dialog box appears. If poPrintToFile is False, setting poDisablePrintToFile to True has no effect because the dialog box won't have a Print to File check box.

The default value is [ ], the empty set, meaning that none of the possible options are in effect.


Example

This example displays the Printer dialog box that includes a Help button. If users try to print when no printer is installed, they will see a warning message.

procedure TForm1.Button1Click(Sender: TObject);

begin

  PrinterDialog1.Options := [poHelp, poWarning];

  if PrinterDialog1.Execute then

    ...

end;


See also

PrintRange property

PrintToFile property


Options property for Open and Save common dialog boxes
Options property

Example

Applies to

TOpenDialog, TSaveDialog component

Declaration

property Options: TOpenOptions;

Description

These are the possible values that can be included in the Options set for the Open and Save dialog boxes:

Value	Meaning

ofAllowMultiSelect	When True, this option allows users to select more than one file in the File Name list box.

ofCreatePrompt	When True, this option displays a dialog box with a message if the user enters a filename that doesn't exist in the File Name edit box and chooses OK. The message tells the user the file doesn't exist and asks if the user wants to create a new file with that name.

ofExtensionDifferent	This option is set when the filename returned from the dialog box has an extension that differs from the default file extension, the value in the DefaultExt property. Your application can then use this information. Setting an ofExtensionDifferent value with the Object Inspector has no meaning.

ofFileMustExist	If True, this option displays a dialog box with a message if the user enters a file that doesn't exist in the File Name edit box and chooses OK. The message informs the user the file can't be found and asks the user to make sure they entered the correct path and filename.

ofHideReadOnly	If True, this option hides the Read Only check box in the dialog box.

ofNoChangeDir	If True, this option sets the current directory to whatever the current directory was when the dialog box first appeared and ignores any directory changes the user made while using the dialog box.

ofNoDereferenceLinks	If True, directs the dialog box to return the path and filename of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut.

ofNoLongNames	Specifies that the abbreviated file names are displayed rather than the long filenames in the File Name list box. This value is ignored if ofOldStyleDialog is True.

ofNoNetworkButton	If True, hides and disables the Network button.

ofNoReadOnlyReturn	If True, a message box appears informing the user if the selected file is read-only.

ofNoTestFileCreate	This option applies only when the user wants to save a file on a create-no-modify network share point, which can't be opened again once it has been opened. If ofNoTestFileCreate is True, your application won't check for write protection, a full disk, an open drive door, or network protection when saving the file because doing so creates a test file. Your application will then have to handle file operations carefully so that a file isn't closed until you really want it to be.

ofNoValidate	If True, this option doesn't prevent the user from entering invalid characters in a filename. If ofNoValidate is False and the user enters invalid characters for a filename in the File Name edit box, a message dialog box appears informing the user the filename contains invalid characters.

ofOldStyleDialog	The option, if present, causes the open/save as dialogs to be drawn in the Windows 3.1/NT style.

ofOverwritePrompt	If True, this option displays a message dialog box if the user attempts to save a file that already exists. The message informs the user the file exists and lets the user choose to overwrite the existing file or not.

ofReadOnly	If True, the Read Only check box is checked when the dialog box is displayed.

ofPathMustExist	If this option is True, the user can type only existing path names as part of the filename in the File Name edit box. If the user enters a path name that doesn't exist, a message box appears informing the user that the path name is invalid.

ofShareAware	If True, the dialog box ignores all sharing errors and returns the name of the selected file even though a sharing violation occurred. If ofShareAware is False, a sharing violation results in a message box informing the user of the problem.

ofShowHelp	If True, this option displays a Help button in the dialog box.

The default value is [ ], the empty set, meaning that none of the options are in effect.


Example

This example uses an Open dialog box and a button on a form. The code forces the user to enter valid filename characters, prevents the read-only check box from appearing in the dialog box, and let's the user choose to overwrite a file if the user selects a file that doesn't exist; the selected filename appears in a label on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  OpenDialog1.Options := [ofNoValidate, ofHideReadOnly, ofCreatePrompt];

  if OpenDialog1.Execute then

    Label1.Caption := OpenDialog1.FileName;

end;


Options property

Example

Applies to

TFindDialog, TReplaceDialog component

Declaration

property Options: TFindOptions

Description

The value of the Options property is the selected set of options that determine how the Find and Replace dialog boxes appear and behave. These are the possible values that can be contained in the Options set:

Value	Meaning

frDisableMatchCase	When True, the Match Case check box is dimmed and users cannot check it. When it is False, users can check the Match Case check box.

frDisableUpDown	When True, the Direction Up and Down buttons are dimmed and the user cannot select either of them. When it is False, users can select one of the Direction Up and Down buttons. Only affects the Find dialog box.

frDisableWholeWord	When True, the Match Whole Word check box is dimmed and user cannot select it. When it is False, users can check the check box.

frDown	When True, the Down button is selected in the dialog box and the search direction is down. When frDown is False, the Up button is selected, and the search direction is up. frDown can be set a design time, or users can change its value at run time when they use the dialog box.

frFindNext	This is a flag that is set when the user chooses the Find Next button. When frFindNext is True, your application should search for the string in the FindText property.

frHideMatchCase	When True, the Match Case check box is not visible in the dialog box. When it is False, the Match Case check box is visible.

frHideWholeWord	When True, the Match Whole Word check box is not visible in the dialog box. When it is False, the Match Whole Word check box is visible.

frHideUpDown	When True, the Direction Up and Down buttons are not visible in the dialog box. When it is False, the Direction Up and Down buttons are visible. Only affects the Find dialog box.

frMatchCase	When True, the Match Case check box is checked. When it is False, the Match Case check box is unchecked. You can set frMatchCase at design time, or users can change the value at run time.

frReplace	frReplace is a flag set by the system that indicates your application should replace the current occurrence of the FindText string with the ReplaceText string. frReplace applies only to the Replace dialog box.

frReplaceAll	frReplaceAll is a flag set by the system that indicates your application should replace all occurrences of the FindText string with the ReplaceText string. frReplaceAll applies only to the Replace dialog box.

frShowHelp	When True, a Help button appears in the dialog box when the dialog box displays. When frShowHelp is False, no Help button is present.

frWholeWord	When True, the Match Whole Word check box is checked in the dialog box. You can set frWholeWord at design time, or users can change its value at run time as they use the dialog box.

The default value is [frDown], meaning that only the frDown option is in effect.


Example

The following code calls the user-defined routine SearchDown if the Down button is selected in FindDialog1 or it calls the user-defined routine SearchUp if the Up button is selected.

if (FindDialog1.Options*[frDown])=[frDown] then SearchDown

else SearchUp;


Options property for outlines
Options property

See also	Example

Applies to

TOutline component

Declaration

property Options: TOutlineOptions;

Description

The Options property determines how the items in an outline are drawn. These are the possible values that can be contained in the Options set:

Value	Meaning

ooDrawTreeRoot	The first item (Index value of 1) is connected to the root item by the outline tree. This means that the tree will extend from the top of the outline to all the first level items. Without ooDrawTreeRoot, all first level items appear leftmost in the outline, not connected by the tree.

ooDrawFocusRect	The outline draws a focus rectangle around the selected item.

ooStretchBitmaps	The outline stretches the standard bitmaps (PictureLeaf, PictureOpen, PictureClosed, PicturePlus, PictureMinus) to fit in the size of the item, determined by the size of the Font of the Text. Without ooStretchBitmap, the bitmaps won't be stretched. They will be cropped if larger than the height of the item text, or won't fill up the entire item space if smaller than the text.


Example

The following code draws the tree of the outline to the root (extending from the first level items to the top of the outline).

Outline1.Options := [ooDrawTreeRoot];


See also

OutlineStyle property

Style property


Options property for grid controls
Options property

Example

Applies to

TDrawGrid, TStringGrid component

Declaration

property Options: TGridOptions;

Description

These are the possible values that can be included in the Options set for the draw and string grid controls:

Value	Meaning

goFixedHorzLine	When True, horizontal lines appear between the rows within nonscrolling regions.

goFixedVertLine	When True, vertical lines appear between the columns within nonscrolling regions.

goHorzLine	When True, horizontal lines appear between the rows.

goVertLine	When True, vertical lines appear between the columns.

goRangeSelect	When True, the user can select a range of cells at one time. When goEditing is True, the user can no longer select a range of cells.

goDrawFocusSelected	When True, the cell with the focus is colored the same as other cells in a selected block are colored. When False, the cell with the focus remains the color of all unselected cells, the color specified with the grid Color property.

goRowSizing	When True, rows can be resized individually except for fixed or nonscrolling rows.

goColSizing	When True, columns can be resized individually except for fixed or nonscrolling columns.

goRowMoving	When True, the user can move a row to a new location in the grid using the mouse.

goColMoving	When True, the user can move a column to a new location in the grid using the mouse.

goEditing	When True, the user can edit the text in the grid. When goEditing is True, the user cannot select a range of cells at one time.

goAlwaysShowEditor	When True, the grid is in automatic edit mode if goEditing is also True. When the grid is in automatic edit mode, the user does not have to press Enter or F2 before editing the contents of a cell. When goAlwaysShowEditor is False and goEditing is True, the user must press Enter or F2 before editing the contents of a cell. If goEditing is False, setting goAlwaysShowEditor to True has no effect. Mutually exclusive with goRowSelect.

goTabs	When True, the user can use the Tab and Shift-Tab keys to move from column to column in the grid.

goRowSelect	When True, the user can select only whole rows at a time instead of individual cells. Mutually exclusive with goAlwaysShowEditor.

goThumbTracking	When True, the contents of the grid scrolls while the user is moving the thumb tab of the grid scroll bar. When False, the contents of the grid doesn't scroll until the user releases the thumb tab in its new position.


Example

This code changes the look of the grid; only horizontal lines appear in both the body of the grid and in the nonscrolling regions when the user clicks the ChangeGridStyle button:

procedure TForm1.ChangeGridStyleClick(Sender: TObject);

begin

  DrawGrid1.Options := [goFixedHorzLine, goHorzLine];

end;


Options property for data grids
Options property

See also	Example

Applies to

TDBGrid component

Declaration

property Options: TDBGridOptions;

Description

These are the possible values that can be included in the Options set for the data grid control:

Value	Meaning

dgEditing	When True, allows the user to edit data in the data grid.

dgAlwaysShowEditor	When True, the grid is in automatic edit mode as long as gdEditing is also True. When the grid is in automatic edit mode, the user does not have to press Enter or F2 before editing the contents of a cell. When gdAlwaysShowEditor is False and gdEditing is True, the user must press Enter or F2 before editing the contents of a cell. If gdEditing is False, setting gdAlwaysShowEditor to True has no effect. Mutually exclusive with dgRowSelect

dgTitles	When True, the column titles are visible.

dgIndicator	When True, a small pointer is visible that indicates which row is the current one.

dgColumnResize	When True, the columns can be resized. A column can't be resized, however, until its field has been added to the grid. To add a field to the grid, choose Add from the Fields editor.

dgColLines	When True, lines between the columns appear.

dgRowLines	When True, lines between the rows appear.

dgTabs	When True, users press the Tab key and the Shift-Tab keys to move among the columns of the data grid.

dgRowSelect	When True, the user can select whole rows only instead of individual cells. Mutually exclusive with dgAlwaysShowEditor.

dgAlwaysShowSelection	When True, the cell selected in the grid continues to display as selected even if the data grid doesn't have the focus.

dgConfirmDelete	When True, a message box appears if the user uses Ctrl+Delete to delete a row in the grid. The message box asks for confirmation that the row should really be deleted.

dgCancelOnExit	When True, if an insert is pending and no modifications were made by the user, the insert will be cancelled when the user exits the grid. This prevents the inadvertent posting of partial or blank records.

dgMultiSelect	When True, the user can select multiple, non-contiguous rows using Ctrl+click or Shift+arrow keys. The behavior is similar to a multi-select list box.


Example

This line of code displays column titles, makes the column indicator visible, and permits the user to edit the data displayed in the data grid:

procedure TForm1.FormClick(Sender: TObject);

begin

  DBGrid1.Options := [dgIndicator, dgEditing, dgTitles];

end;


See also

ReadOnly property


Options property

See also	Example

Applies to

TDBLookupCombo, TDBLookupList components

Declaration

property Options: TDBLookupListOptions;

Description

The Options property determines how multiple columns in database lookup combo boxes and database lookup list boxes appear. These are the possible values that can be part of the Options set:

Value	Meaning

loColLines	When True, lines separate the columns displayed in the control. When False, no lines appear between the columns.

loRowLines	When True, lines separate the rows displayed in the control. When False, no lines appear between the rows.

loTitles	When True, the field names appear as titles above the columns in the control. When False, no titles appear.

To display multiple columns, use the LookupDisplay property.


Example

This code displays three fields in a database lookup list box, displays the field names as titles for the columns, and separates the columns with lines:

procedure TForm1.FormCreate(Sender: TObject);

begin

  DBLookupList1.LookupDisplay := 'Company;City;Country';

  DBLookupList1.Options := [loColLines,loTitles];

end;


See also

LookupDisplay property


Options property

Applies to

TIndexDef object

Declaration

property Options: TIndexOptions;

Description

Run-time and read-only. Options is the set of characteristics of the index. Possible elements are those of the TIndexOptions type: ixPrimary, ixUnique, ixDescending, ixNonMaintained, and ixCaseInsensitive.


Orientation property

Applies to

TPrinter object;TDBCtrlGrid, TTrackBar, TUpDown components

Description

Orientation property for printer objects

Orientation property for track bars

Orientation property for TUpDown components

Orientation property for TDBCtrlGrid


Orientation property for printer objects
Orientation property

See also	Example

Applies to

TPrinter object;

Declaration

property Orientation: TPrinterOrientation;

Description

Run-time only. The value of the Orientation property determines if the print job prints vertically or horizontally on a page. These are the possible values:

Value	Meaning

poPortrait	The print job prints vertically on the page.

poLandscape	The print job prints horizontally on the page.


Example

This example uses two radio buttons on a form named Landscape and Portrait. The form also includes a button. When the user selects an orientation by clicking one of the radio buttons and then clicks the button to print one line of text, the print job prints using the selected orientation:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Printer.BeginDoc;

  Printer.Canvas.TextOut(100,100,'Hi there');

  Printer.EndDoc;

end;

procedure TForm1.PortraitClick(Sender: TObject);

begin

  Printer.Orientation := poPortrait;

end;

procedure TForm1.LandscapeClick(Sender: TObject);

begin

  Printer.Orientation := poLandscape;

end;


See also

Printer variable


Orientation property for DBCtrlGrids
Orientation property

Applies to

TDBCtrlGrid components

Declaration

property Orientation: TDBCtrlGridOrientation;

Description

Determines how multiple records wrap within the grid. Set Orientation to roVertical (the default) to have the panels ordered across, then down (in rows with a vertical scroll bar). When you set Orientation to roHorizontal, panels go down, then across (in columns with a horizontal scroll bar).


Orientation property for track bars
Orientation property

See also

Applies to

TTrackBar components

Declaration

property Orientation: TTrackBarOrientation;

Description

The Orientation property determines if a TTrackBar is horizontal or vertical. These are the possible values:

Value	Meaning

tbHorizontal	TTrackBar is horizontal.

tbVertical	TTrackBar is vertical.

The default value is tbHorizontal.


See also

TickMarks property


Orientation property for up-down controls
Orientation property

See also

Applies to

TUpDown components

Declaration

property Orientation: TUDOrientation;

Description

The Orientation property sets the position of the Up and Down arrows. These are the possible values:

Value	Meaning

udHorizontal	Arrows on the updown control point to the left and right.

udVertical	Arrows on the updown control point up and down.

The default value is udVertical.


See also

AlignButton property

Associate property


OutlineStyle property

Example

Applies to

TOutline component

Declaration

property OutlineStyle: TOutlineStyle;

Description

The OutlineStyle property determines how the outline structure is displayed within the TOutline component. The following table describes the outline styles.

Style	Description

osPictureText	Displays open picture (specified in PictureOpen), closed picture (specified in PictureClosed), leaf picture (specified in PictureLeaf) and item text (specified in Text).

osPlusMinusPictureText	Displays plus picture (specified in PicturePlus), minus picture (specified in PictureMinus), open picture, closed picture, leaf picture, and item text.

osPlusMinusText	Displays plus picture, minus picture, and item text.

osText	Displays item text.

osTreePictureText	Displays outline tree, open picture, closed picture, leaf picture, and item text.

osTreeText	Displays outline tree and item text.


Example

The following code displays pictures only if they are monochrome. The first choice is Open and Closed pictures. If they aren't monochrome, the code tests Plus and Minus pictures. The final resort is to simply display text.

with Outline1 do

  if (PictureOpen.Monochrome and PictureClosed.Monochrome) then

    OutlineStyle := osPictureText

  else if (PicturePlus.Monochrome and PictureMinus.Monochrome) then

    OutlineStyle := osPlusMinusText

  else OutlineStyle := osText;


Add method for image list objects
Overlay method

See also

Applies to

TImageList component

Declaration

function Overlay(ImageIndex: Integer; Overlay: TOverlay): Boolean;

Description

The Overlay method makes the image at ImageIndex usable as an overlay image. It is referenced as an overlay image by using the Overlay value (0...3) provided.


See also

ImageIndex property, DrawOverlay method


OverlayIndex property for tree nodes
OverlayIndex property

See also

Applies to

TTreeNode, TListItem objects

Declaration

property OverlayIndex: Integer;

Description

Run-time only. The OverlayIndex property for a tree node or list item determines which image from the image list is to be used as an overlay mask. An overlay mask is an image drawn transparently over another image in the tree view or the list view. For example, to indicate that an item is no longer available you could use an overlay image that puts an X over the current item's image.


See also

Images property

ImageIndex property

StateImages property

StateIndex property


Overload property

See also

Applies to

TStoredProc component

Declaration

property Overload: Word;

Description

Oracle servers allow overloading of stored procedures in an Oracle package; that is, different procedures with the same name.

Set the Overload property to specify the procedure to execute on an Oracle server. If Overload is zero (the default), there is assumed to be no overloading. If Overload is one (1), then Delphi will execute the first stored procedure with the overloaded name; if it is two (2), it will execute the second, and so on.


See also

StoredProcName property


Owner property

Applies to

All components; TTreeNodes, TListItem, TListItems, TListColumns objects; TTreeView component

Description

Owner Property for Tree Views

Owner property for Tree Nodes Objects

OwnerProperty for List Item Objects

OwnerProperty for List Items Objects

Owner Property for List Columns

Owner Property for All Other Components


Owner property

See also

Declaration

property Owner: TTreeNodes;

Description

Run-time and read-only. The Owner property indicates which tree nodes object owns the tree node.


See also

Parent property

TreeView property


Owner property

See also

Applies to

TTreeView component

Declaration

property Owner: TCustomTreeView;

Description

Run-time and read-only. The Owner property indicates which tree view object owns the tree nodes object.


See also

Parent property

TreeView property


Owner property for list item objects
Owner property

See also

Applies to

TListItem object

Declaration

property Owner: TListItems;

Description

Run-time and read-only. The Owner property indicates which TListItems object owns the list item.


See also

Parent property

ListView property


Owner property for list items objects
Owner property

See also

Applies to

TListItems object

Declaration

function Owner: TCustomListView;

Description

Run-time and read-only. The Owner property indicates which list view object owns the list items object.


See also

ListView property

Parent property


Owner property for list columns objects
Owner property

See also

Applies to

TListColumns object

Declaration

property Owner: TCustomListView;

Description

Run-time and read-only. The Owner property indicates which list view object owns the list columns object.


See also

Parent property

ListView property


Owner property

See also	Example

Applies to

All components;

Declaration

property Owner: TComponent;

Description

Run-time and read-only. The Owner property indicates which component owns the component.

The form owns all components that are on it. In turn, the form is owned by the application.

When one component is owned by another, the memory for the owned component is freed when its owner's memory is freed. This means that when a form is destroyed, all the components on the form are destroyed also. Finally, when the memory for the application itself is freed, the memory for the form (and all its owned components) is also freed.

Don't confuse ownership of a component with being the parent of a component. A parent is a windowed control that contains a child window. The parent and the owner of a windowed component can be different components.


Example

The example assumes there are two edit box controls on the form. When the form displays, the code inserts the name of the Edit1 control's owner (TForm1) into Edit1 itself, and displays the size of the owner in bytes in the second edit box (Edit2).

procedure TForm1.FormCreate(Sender: TObject);

var

  TC: TComponent;

  Size: Word;

  SizeStr: string;

begin

  TC := Edit1.Owner;

  Edit1.Text := TC.ClassName;

  Size := TC.InstanceSize;

  Str(Size, SizeStr);

  Edit2.Text := SizeStr;

end;


See also

Components property

Destroy method

Free method

Parent property


Pack method

See also	Example

Applies to

TList object

Declaration

procedure Pack;

Description

The Pack method deletes all nil items from the list of pointers kept by the List property of a list object.


Example

This example assumes there are two edit box controls on the form. The code creates a list object and adds two strings to it. The second string in the list is a nil string. The code counts the number of strings in the list and displays the number in the Edit1 control. The code then packs the list, removing the nil string, and counts the strings in the list again. The second count displays in the Edit2 control:

procedure TForm1.FormCreate(Sender: TObject);

var

  MyList: TList;

  I: Integer;

  Buffer: string;

begin

  MyList := TList.Create;              {Create a list of TList}

  MyList.Add(PChar('Another string')); {Add a string}

  MyList.Add(nil);              {Add a Nil string}

  Str(MyList.Count, Buffer);

  Edit1.Text := Buffer;                {Put count into Edit1}

  Mylist.Pack;                         {Pack the list.}

  Str(MyList.Count, Buffer);

  Edit2.Text := Buffer;                {Put count into Edit2}

  MyList.Free;                         {Free memory for list}

end;


See also

Expand method

Remove method

Capacity property


PageControl property

See also	Example

Applies to

TTabSheet component

Declaration

property PageControl: TPageControl;

Description

Run-time only. The PageControl property returns the TPageControl object that is associated with the TTabSheet. Tab sheets represent the individual pages of a page control.


Example

The following code moves TabSheet3 to PageControl2 when the user clicks on a button.

procedure TForm1.Button1Click(Sender: TObject);

begin

  TabSheet3.PageControl := PageControl2;

end;

The following code creates and adds a TTabSheet to a TPageControl.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with TTabSheet.Create(Self) do

  begin

    Caption := 'NewPage';

    {Assign PageControl1 to the newly created TTabSheet's PageControl property}

    PageControl := PageControl1;

  end;

end;


See also

PageIndex property


PageCount property

See also

Applies to

TPageControl component

Declaration

property PageCount: Integer;

Description

Read and run-time only. The PageCount property contains the number of pages in a TPageControl. Each page is a TTabSheet object.


See also

ActivePage property

FindNextPage method

SelectNextPage method


PageHeight property

See also	Example

Applies to

TPrinter object

Declaration

property PageHeight: Integer;

Description

Run-time and read-only. The PageHeight property contains the height of the currently printing page in pixels.


Example

This code displays the page height of the currently printing page in an edit box.

To run this code successfully, you must add Printers to the uses clause of your unit.

Edit1.Text := IntToStr(Printer.PageHeight);


See also

PageNumber property

PageWidth property

Printer variable


PageIndex property

Applies to

TNotebook, TTabbedNotebook, TTabSheet components

Description

PageIndex Property for Notebooks

PageIndex Property for Tab Sheets


PageIndex property for tab sheets
PageIndex property

See also	Example

Applies to

TNotebook, TTabbedNotebook components

Declaration

property PageIndex: Integer;

Description

The value of the PageIndex property determines which page displays in the notebook or tabbed notebook component. Changing the PageIndex value changes the page in the control.

Each string in the Pages property is automatically assigned a PageIndex value when the page is created. The first page receives a value of 0, the second has a value of 1, and so on. If you delete a string from the Pages property, the PageIndex values are reassigned so that the values always begin with 0 and continue to increase without any gaps between values.


Example

This example assumes that a notebook component and a tab set component are on a form. It demonstrates how you can use the tab set and notebook component together to allow the user to click on a tab to access a page in the notebook component.

This code assigns the strings in the Pages property of the notebook component to the Tabs property of the tab set component. Because the code is in the OnCreate event handler when the form first appears, the tab set component has one tab for each page in the notebook component.

procedure TForm1.FormCreate(Sender: TObject);

begin

  TabSet1.Tabs := Notebook1.Pages;

end;

Changing the PageIndex value of a notebook or component changes the page displayed. This code assigns the TabIndex value of the tab the user clicks on to the PageIndex property of the notebook component. When the user clicks the tab labeled with a page name, that page is displayed in the notebook component.

procedure TForm1.TabSet1Click(Sender: TObject);

begin

  Notebook1.PageIndex := TabSet1.TabIndex;

end;


See also

ActivePage property

TTabSet component


PageIndex property for tab sheets
PageIndex property

See also

Applies to

TTabSheet components

Declaration

property PageIndex: Integer;

Description

The PageIndex property contains the index value of the TTabSheet. Tab sheets represent the pages of a TPageControl. Each tab sheet in a page control is automatically assigned a PageIndex when it is created. The first tab sheet receives a value of 0, the second has a value of 1, and so on. PageIndex values are reassigned if tab sheets are deleted.

Use PageIndex to access the index value given the tab sheet. To access a particular tab sheet given its index value, use the indexed Pages property of the TPageControl.


See also

Pages property

TabIndex property


PageNumber property

See also	Example

Applies to

TPrinter object

Declaration

property PageNumber: Integer;

Description

Run-time and read-only. The PageNumber property contains the number of the current page. Each time an application calls the NewPage method, NewPage increments the value of PageNumber.


Example

This example uses a button on a form. When the user clicks the button, one line of text is printed on six separate pages. As each page is printed, a message indicating the number of the page being printed appears on the form.

To run this example successfully, you must add Printers to the uses clause of your unit.

procedure TForm1.Button1Click(Sender: TObject);

var

  I, X, Y: Integer;

begin

  Printer.BeginDoc;

  X := 10;

  Y := 10;

    for I := 1 to 6 do

    begin

      Printer.Canvas.TextOut(100, 100, 'Object Pascal is great');

      Canvas.TextOut(X, Y, 'Printing page ' + IntToStr(Printer.PageNumber));

      Printer.NewPage;

      Y := Y + 20;

    end;

  Printer.EndDoc;

end;


See also

NewPage method

Printer variable


Pages property

Applies to

TNotebook, TPageControl, TTabbedNotebook components

Description

Pages property for TNotebook and TTabbedNotebook components

Pages property for TPageControl components


Pages property

See also	Example

Applies to

TNotebook, TTabbedNotebook components

Declaration

property Pages: TStrings;

Description

The Pages property contains the strings that identify the individual pages of the notebook or tabbed notebook control. Both these controls create a separate page for each string in the Pages property. For example, if Pages contains three strings, First, Second, and Third, the control has three separate pages.

You can access the various pages in a notebook or tabbed notebook control with either the ActivePage or PageIndex property.


Example

The following code ensures that the Pages of Notebook1 correspond with the value of the Tabs property of TabSet1.

Notebook1.Pages := TabSet1.Tabs;


See also

TTabSet component


Pages property for page controls
Pages property

See also	Example

Applies to

TPageControl component

Declaration

property Pages[Index: Integer]: TTabSheet;

Description

Read and run-time only. Pages is an indexed property of the pages in a TPageControl. Each page is a TTabSheet object. Use Pages to access a TTabSheet object specified by its index value.


Example

This example changes the caption of the second tab sheet.

PageControl1.Pages[1].Caption := 'Tools';


See also

ActivePage property

FindNextPage method

PageCount property

SelectNextPage method


PageSize property

See also

Applies to

TTrackBar component

Declaration

property PageSize: Integer;

Description

The PageSize property determines the number of ticks moved using the PgUp and PgDn keys, or by mouse clicks on the bar. Use the LineSize property to set the number of ticks moved using the arrow keys.


See also

LineSize property

Max property

Min property

Position property


PageWidth property

See also	Example

Applies to

TPrinter object

Declaration

property PageWidth: Integer;

Description

Run-time and read-only. The PageWidth property contains the value of width of the currently printing page in pixels.


Example

The code uses an edit box on a form. The code creates a printer object and displays the current width of a page in pixels in the edit box when the form first appears.

To run this example, you must add the Printers unit to the uses clause of your unit.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Edit1.Text := IntToStr(Printer.PageWidth) + ' pixels';

end;


See also

PageHeight property

PageNumber property

Printer variable


Palette property

Applies to

TBitmap object

Declaration

property Palette: HPalette;

Description

The Palette property controls a bitmap's color mapping. The Palette of a bitmap contains up to 256 colors that can be used to display the bitmap on screen.

When running in a 256 color video mode, and if the bitmap is drawn by an application running in the foreground, all colors of Palette will be added to the Windows system palette. If the bitmap is drawn by an application running in the background and another application has loaded the system palette with its own colors, the bitmap's colors will be mapped to the system palette. Palette=0 if the bitmap has no palette. You can assign custom palettes created with CreatePalette to this property.


PanelBorder property

Applies to

TDBCtrlGrid component

Declaration

property PanelBorder: TDBCtrlGridBorder;

Description

Controls the type of border drawn around each panel. The default value of gbRaised draws a raised border. Set PanelBorder to gbNone to eliminate the border.


PanelCount property

Applies to

TDBCtrlGrid component

Declaration

property PanelCount: Integer;

Description

Run-time only and read-only. Indicates the number of panels visible in the grid.


PanelHeight property

Applies to

TDBCtrlGrid component

Declaration

property PanelHeight: Integer;

Description

Represents the height in pixels of each panel. When you set the PanelHeight property, the grid resizes itself to fit the new panel height.


PanelIndex property

Applies to

TDBCtrlGrid component

Declaration

property PanelIndex: Integer;

Description

Run-time only. Indicates which panel (in the range 0..PanelCount - 1) shows the current record. When you set this property, the record displayed in the specified panel is made the current record and the panel is made visible.


Panels property

See also

Applies to

TStatusBar component

Declaration

property Panels: TStatusPanels;

Description

The Panels property contains the panels that appear on the status bar. Individual panels in a TStatusBar are TStatusPanel objects. When setting this property at design-time in the Object Inspector the StatusBar Panels Editor dialog appears. Use this dialog box to add and delete panels, and to edit their properties. Use the Alignment and Text properties to modify what and how text is displayed. You can set the Bevel property to change the edge of the individual panel to appear raised or lowered. For owner-drawn status panels set the Style property to psOwnerDraw and write a handler for the OnDrawPanel event.


See also

Alignment property

Bevel property

Style property

Text property

Width property


PanelWidth property

Applies to

TDBCtrlGrid component

Declaration

property PanelWidth: Integer;

Description

Represents the width in pixels of each panel. When you set the PanelWidth property, the grid resizes itself to fit the new panel width.


Paragraph property

See also	Example

Applies to

TRichEdit component

Declaration

property Paragraph: TParaAttributes;

Description

Run-time and read-only. The Paragraph property contains the paragraph formatting information for the selected paragraphs, meaning either the paragraphs containing selected text, or, if no text is selected, the paragraph containing the cursor. Paragraph is of type TParaAttributes which is an object that contains information on alignment, indentation, numbering, and tabs. You can modify the formatting of the selected paragraph(s) using the properties of the TParaAttributes object.


See also

ConsistentAttributes property

DefAttributes property

OnSelectionChange event

PlainText property

SelAttributes property


ParamBindMode property

Example

Applies to

TStoredProc component

Declaration

property ParamBindMode: TParamBindMode;

Description

ParamBindMode determines how the elements of the Params array will be matched with stored procedure parameters. If ParamBindMode is set to pbByName (the default), parameters will be bound based on their names in the stored procedure. If ParamBindMode is set to pbByNumber, parameters will be bound based on the order in which they are defined in the stored procedure. Use this setting if you are building your parameters list, and you don't want to use the parameter names defined in the stored procedure.


Example

ParamBindMode := pbByName;


ParamByName method

Applies to

TParams object; TQuery, TStoredProc components

Description

ParamByName for TParams Objects

ParamByName for Queries and Stored Procedures


ParamByName method

Example

Applies to

TParams object

Declaration

function ParamByName(const Value: string): TParam;

Description

The ParamByName method finds a parameter with the name passed in Value. If a match is found, ParamByName returns the parameter. Otherwise, an exception is raised. Use this method rather than a direct reference to the Items property if you need to get a specific parameter to avoid depending on the order of the entries.


Example

try

{ Assign a value of 999 to the CustNo parameter }

  Params.ParamByName('CustNo').AsInteger := 999;

except

{ If it doesn't exist, then }

  on EDatabaseError do

{ Create a new parameter for CustNo and assign a value of 999 to it }

  with Params.CreateParam(ftInteger, 'CustNo', ptInput) do

    AsInteger := 999;

  end;


ParamByName method

Example

Applies to

TQuery, TStoredProc components

Declaration

function ParamByName(const Value: string): TParam;

Description

The ParamByName method returns the element of the Params property whose Name property matches Value. Use it to assign values to parameters in a dynamic query by name.


Example

Query1.ParamByName('CustNo').AsString := '1231';


ParamCount property

Applies to

TQuery, TStoredProc component

Description

ParamCount for Queries

ParamCount for Stored Procedures


ParamCount property

See also	Example

Applies to

TQuery component

Declaration

property ParamCount: Word;

Description

Run-time and read-only. The ParamCount property specifies how many entries the TQuery has in its Params array, that is, how many parameters the query has. Adding a new item to Params will automatically increase the value; removing an item will automatically decrease the value.


Example

for I := 0 to Query1.ParamCount - 1 do

  Query1.Params[I].AsInteger := I;


See also

Params property


ParamCount property

Example

Applies to

TStoredProc component

Declaration

property ParamCount: Word;

Description

Run-time and read-only. ParamCount specifies the total number of input and output parameters to the stored procedure, and is automatically maintained by changes to the Params property. Use ParamCount to iterate over the Params.


Example

{ Set all parameters to an empty string }

with StoredProc1 do

  for I := 0 to ParamCount - 1 do

    Param[I].AsString := '';


Params property

Applies to

TDatabase, TQuery, TStoredProc component

Description

Params for Databases

Params for Queries

Params for Stored Procedures


Params property

See also	Example

Applies to

TStoredProc component

Declaration

property Params: TParams;

Description

The Params property holds the parameters to be passed to the stored procedure.


Example

{ Copy all parameters from StoredProc1 to StoredProc2 }

StoredProc1.CopyParams(StoredProc2.Params);


See also

CopyParams method

ParamCount property


Params property

Example

Applies to

TQuery component

Declaration

property Params[Index: Word]: TParam;

Description

When you enter a query, Delphi creates a Params array for the parameters of a dynamic SQL statement. Params is a zero-based array of TParam objects with an element for each parameter in the query; that is, the first parameter is Params[0], the second Params[1], and so on. The number of parameters is specified by ParamCount. Read-only and run-time only.

Note:	Use the ParamByName method instead of Params to avoid dependencies on the order of the parameters.


Example

For example, suppose a TQuery component named Query2 has the following statement for its SQL property:

INSERT

  INTO COUNTRY (NAME, CAPITAL, POPULATION)

  VALUES (:Name, :Capital, :Population)

An application could use Params to specify the values of the parameters as follows:

Query2.Params[0].AsString := 'Lichtenstein';

Query2.Params[1].AsString := 'Vaduz';

Query2.Params[2].AsInteger := 420000;

These statements would bind the value "Lichtenstein" to the :Name parameter, "Vaduz" to the :Capital parameter, and 420000 to the :Population parameter.


Params property

Applies to

TDatabase component

Declaration

property Params: TStrings;

Description

The Params property holds the parameters required to open a database on an SQL server. By default, these parameters are specified in the BDE Configuration Utility. You can customize these parameters for an application-specific alias with the Database Parameters Editor.

For desktop databases, Params will specify only the directory path for the database. For server databases, Params will specify a variety of parameters, including the server name, database name, user name, and password.


ParamType property

Example

Applies to

TParam object

Declaration

property ParamType: TParamType;

Description

ParamType is used to identify the type of the parameter for a stored procedure. Possible values are those of the TParamType type: ptUnknown, ptInput, ptOutput, ptInputOutput, or ptResult. Normally Delphi will set this property, but if the server does not provide the necessary information, you may have to set it yourself.


Example

StoredProc1.Params.ParamByName('CustNo').ParamType := ptInput;


Parent property

Applies to

All controls; TMenuItem component; TOutlineNode, TTreeNode objects

Description

There are three different Parent properties: one for windowed controls, one for menu items, and one for outline nodes.

Parent Property for Controls

Parent Property for Menu Items

Parent Property for Outline Nodes and Tree Nodes


Parent property

See also	Example

Applies to

All controls

Declaration

property Parent: TWinControl;

Description

The Parent property contains the name of the parent of the control. The parent of a control is the windowed control that contains the control. If one control (parent) contains others, the contained controls are child controls of the parent. For example, if your application includes three radio buttons in a group box, the group box is the parent of the three radio buttons, and the radio buttons are the child controls of the group box.

Don't confuse the Parent property with the Owner property. A form is the owner of all the components on it, whether or not they are windowed controls. A child control is always a windowed control contained within another windowed control (its parent). If you put three radio buttons in a group box on a form, the owner of the radio buttons is still the form, while the parent is the group box.

If you are creating a new control, you must assign a Parent property value for the new control. Usually, this is a form, panel, group box, or some control that is designed to contain another. It is possible to assign any windowed control as the parent, but the contained control is likely to be painted over.

When the parent of a control is destroyed, all controls that are its children are also destroyed.


Example

To set up the form for this example, put a group box on the form and add a radio button to the group box. Put two labels and a button on the form. This code displays the name of the parent of the radio button and the class name of the owner of the radio button in the captions of the two labels when the user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := RadioButton1.Parent.Name + ' is the parent';

  Label2.Caption := RadioButton1.Owner.ClassName +

    ' is the class name of the owner';

end;

This example uses a button and a group box on a form. When the user clicks the button, the button moves inside the group box, because the group box is now the parent of the button.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Parent := GroupBox1;

end;


See also

Controls property

Owner property


Parent property

Example

Applies to

TMenuItem component

Declaration

property Parent: TMenuItem;

Description

Run-time and read-only. The Parent property of a menu item identifies the parent menu item of this menu item.


Example

This example assumes there are two edit boxes on a form as well as a main menu that contains menu items. One of the menu items has Save as the value of its Caption property, so the value of its Name property is Save1. The code displays the name of the parent of the Save1 menu item in the Edit1 control, and it displays the class name of the parent in the Edit2 control when the form first appears.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Edit1.Text := Save1.Parent.Name;

  Edit2.Text := Save1.Parent.ClassName;

end;


Parent property

See also	Example

Applies to

TOutlineNode, TTreeNode objects

Declaration

property Parent: TOutlineNode;

property Parent: TTreeNode;

Description

The Parent property of an outline node and a tree node identifies the parent item of this node. A parent item is one level higher and contains the child item as a subitem.


Example

The following code tests to see if the currently selected item has a sibling. True will be assigned to HasSibling if so.

var

  HasSibling: Boolean;

begin

  with Outline1[Outline1.SelectedItem] do

    HasSibling := (Parent.GetPrevChild <> -1) or (Parent.GetNextChild <> -1);

end;


See also

TopItem property


ParentColor property

See also	Example

Applies to

TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBText, TDBListBox, TDBLookupCombo, TDBLookupList, TDBMemo, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TGroupBox, TLabel, TListBox, TMaskEdit, TMemo, TNotebook, TOutline, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBox, TStringGrid components

Declaration

property ParentColor: Boolean;

Description

The ParentColor property determines where a control looks for its color information. If ParentColor is True, the control uses the color in its parent component's Color property. If ParentColor is False, the control uses its own Color property. Except for the radio group, database radio group, label and database text controls, the default value is False.

By using ParentColor, you can ensure that all the controls on a form have a uniform appearance. For example, if you change the background color of your form to gray, by default, the controls on the form will also have a gray background.

To specify a different color for a particular control, specify the desired color as the value of that control's Color property, and ParentColor becomes False automatically.


Example

This code uses a label control and a timer component on the form. When the OnTimer event occurs, the label turns red if the label's ParentColor property is True. If the ParentColor property is False, ParentColor is set to True. The result is the label flashes red on and off. Every other time an OnTimer event occurs, the label turns red. The other times, the label assumes the color of its parent, Form1.

procedure TForm1.Timer1Timer(Sender: TObject);

begin

 if Label1.ParentColor then

   Label1.Color := clRed

 else

   Label1.ParentColor := True;

end;


See also

Color property

Parent property

ParentFont property


ParentCtl3D property

See also	Example

Applies to

TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBLookupCombo, TDBLookupList, TDBListBox, TDBNavigator, TDBMemo, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TGroupBox, TListBox, TMaskEdit, TMemo, TNotebook, TOutline, TPanel, TRadioButton, TRichEdit, TScrollBox, TStringGrid, TTrackBar, TTreeView components

Declaration

property ParentCtl3D: Boolean;

Description

The ParentCtl3D property determines where a component looks to determine if it should appear three dimensional. If ParentCtl3D is True, the component uses the dimensionality of its parent component's Ctl3D property. If ParentCtl3D is False, the control uses its own Ctl3D property. The default value is True.

By using ParentCtl3D, you can ensure that all the components on a form have a uniform appearance. For example, if you want all components on a form to appear three dimensional, set the form's Ctl3D property to True and each component's ParentCtl3D property to True. Not only will all components have a three-dimensional appearance, but if you decide you prefer a two-dimensional appearance, you only have to change the Ctl3D property of the form and all the components will become two dimensional.

To specify a different dimensionality for a particular component, specify the dimensionality (True for 3D or False for 2D) as the value of that control's Ctl3D property, and ParentCtl3D becomes False automatically.


Example

This code uses a group box and a button on a form. The code displays the group box in two dimensions when the user clicks the button:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if GroupBox1.ParentCtl3d = True then

  begin

    GroupBox1.ParentCtl3d := False;

    GroupBox1.Ctl3d := False;

  end;

end;


See also

Ctl3D property

Parent property

ParentColor property

ParentFont property


ParentFont property

See also	Example

Applies to

TBitBtn, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBLookupCombo, TDBLookupList, TDBListBox, TDBMemo, TDBRadioGroup, TDBText, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TFilterComboBox, TForm, TGroupBox, THeader, THeaderControl, TListBox, TMaskEdit, TMemo, TNotebook, TOutline, TPaintBox, TPanel, TRadioButton, TRichEdit, TScrollBox, TSpeedButton, TStatusBar, TStringGrid, TTreeView components

Declaration

property ParentFont: Boolean;

Description

The ParentFont property determines where a control looks for its font information. If ParentFont is True, the control uses the font in its parent component's Font property. If ParentFont is False, the control uses its own Font property.

By using ParentFont, you can ensure that all the controls on a form have a uniform appearance. For example, if you want all the controls in a form to use 12-point Courier for their font, you can set the form's Font property to that font. By default, all the controls on that form will use the same font.

To specify a different font for a particular control, specify the desired font as the value of the control's Font property, and ParentFont becomes False automatically.

When the ParentFont is True for a form, the form uses the value of the application's Font property.


Example

This example uses a timer component and a label control. When an OnTimer event occurs and the label uses its parent's font, the code changes the label's ParentFont property to False and changes the label's font size to 30 points. When an OnTimer event occurs and the label doesn't use its parent's font, the code sets its ParentFont to True. The result is that the label's font grows and shrinks alternately, each time an OnTimer event occurs.

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  if Label1.ParentFont = True then

    Label1.Font.Size := 30

  else

    Label1.ParentFont := True;

end;

This example uses a button on a form. When the user clicks the button, the font type and color change for all components on all forms in the application.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ParentFont := True;

  if Application.Font.Name = 'System' then

  begin

    Application.Font.Color := clNavy;

    Application.Font.Name := 'New Times Roman';

  end

  else

  begin

    Application.Font.Color := clBlack;

    Application.Font.Name := 'System'

  end;

end;


See also

Application variable

Font property

Parent property

ParentColor property

ParentCtl3D property

TApplication component


ParentShowHint property

See also	Example

Applies to

All controls

Declaration

property ParentShowHint: Boolean;

Description

The ParentShowHint property determines where a control looks to find out if Help Hint, specified as the value of the Hint property for the control, should be shown. If ParentShowHint is True, the control uses the ShowHint property value of its parent. If ParentShowHint is False, the control uses its own ShowHint property.

By using ParentShowHint, you can ensure that all the controls on a form either show their Help Hints or don't show them. By default, ParentShowHint is True.

If don't want all the controls to have Help Hints, set the ShowHint property for those controls you do want to have Help Hints to True, and ParentShowHint becomes False automatically.

You can enable or disable all Help Hints for the entire application using the ShowHint property of the application.


Example

This example uses an edit box, a memo, and a check box on a form. For each of these controls, the ParentShowHint property is True, the default value. When the code runs, the ShowHint property of the form is set to True and hints are assigned to each control. Because each control looks to its parent, the form, to find out whether to display a Help Hint, and because the form's ShowHint property is True, the Help Hints are available.

procedure TForm1.FormCreate(Sender: TObject);

begin

  ShowHint := True;

  Edit1.Hint := 'Enter text';

  Memo1.Hint := 'Enter lots of text';

  CheckBox1.Hint := 'Check or uncheck me';

end;


See also

Hint property

ParentColor property

ParentCtl3D property

ParentFont property


PasswordChar property

Example

Applies to

TDBEdit, TEdit, TMaskEdit components

Declaration

property PasswordChar: Char;

Description

The PasswordChar property lets you create an edit box that displays special characters in place of the entered text. By default, PasswordChar is the null character (ANSI character zero), meaning that the control displays its text normally. If you set PasswordChar to any other character, the control displays that character in place of each character in the control's text.


Example

The following code displays asterisks for each character in an edit box called PasswordField:

PasswordField.PasswordChar := '*';


PassWordDialog method

Unit

DBPWDlg

Example

Declaration

function PasswordDialog(ASession: TComponent): Boolean;

Description

The PasswordDialog function displays a dialog box that prompts a user for a password prior to your application opening a password-protected Paradox table.

ASession is the name of the session instance to which the password is passed. If the user clicks OK in the dialog box, PasswordDialog returns True. Otherwise it returns False.

Note:	When an application opens a Paradox table that requires a password, the user is prompted to enter a password unless the Session component already has a valid password for that table.


Example

procedure TForm1.Button1Click(Sender: TObject);

begin

  if PasswordDialog(Session) then

    Table1.Active := True;

end;


PasteFromClipboard method

See also	Example

Applies to

TDBEdit, TDBImage, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

procedure PasteFromClipboard;

Description

The PasteFromClipboard method copies the contents of the Clipboard to the control, inserting the contents where the cursor is positioned.


Example

This example uses two edit boxes and a button on a form. When the user clicks the button, text is cut from the Edit1 edit box and pasted into the Edit2 edit box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.SelectAll;

  Edit1.CutToClipboard;

  Edit2.Clear;

  Edit2.PasteFromClipboard;

  Edit1.SetFocus;

end;


See also

Clear method

ClearSelection method

CopyToClipboard method

CutToClipboard method


PasteLink method

Applies to

TDdeClientConv

Declaration

function PasteLink: Boolean;

Description

The PasteLink function creates a DDE link to the current clipboard object. PasteLink returns True if the link is successfully established.


Pause method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Pause;

Description

The Pause method pauses the open multimedia device. If the device is already paused when Pause is called, the device resumes playing or recording by calling the Resume method. Pause is called when the Pause button on the media player control is clicked at run time.

Upon completion, Pause stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Pause method has completed. The Notify property determines whether Pause generates an OnNotify event.


Example

This example uses a media player, a timer, and a button on a form. Only the button is visible when the application runs. When the user clicks the button, the .WAV file plays. When the user clicks the button again, the .WAV file pauses. The caption of the button changes, depending on whether the .WAV file is playing, paused, or stopped.

To run this example, you must have the CHIMES.WAV file in your Windows directory and have a device that plays WAV audio files:

procedure TForm1.FormActivate(Sender: TObject);

var

  WinDir: PChar;

begin

  MediaPlayer1.Visible := False;

  GetMem(WinDir, 144);

  GetWindowsDirectory(WinDir, 144);

  StrCat(WinDir, '\chimes.wav');

  MediaPlayer1.FileName := StrPas(WinDir);

  MediaPlayer1.Open;

  FreeMem(WinDir, 144);

  Button1.Caption := 'Play';

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  if Button1.Caption = 'Play' then

  begin

    Button1.Caption := 'Pause';

    MediaPlayer1.Play;

  end

  else

  begin

    Button1.Caption := 'Play';

    MediaPlayer1.Pause;

  end;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  if MediaPlayer1.Mode = mpStopped then

    Button1.Caption := 'Play';

end;


See also

PauseOnly method

Play method

StartRecording method

Stop method


PauseOnly method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure PauseOnly;

Description

The PauseOnly method only pauses the open multimedia device. If the device is already paused when PauseOnly is called, the device will remain paused.

Upon completion, PauseOnly stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the PauseOnly method has completed. The Notify property determines whether PauseOnly generates an OnNotify event.


Example

The following code illustrates the difference between Pause and PauseOnly. After the second call to Pause, MediaPlayer1 resumes playing. After the second call to PauseOnly, MediaPlayer1 is still paused.

with MediaPlayer1 do begin

  MediaPlayer1.Play;

  MediaPlayer1.Pause;

    { Now its paused }

  MediaPlayer1.Pause;

    { Now its playing }

  MediaPlayer1.PauseOnly;

    { Now its paused }

  MediaPlayer1.PauseOnly;

    { Now its still paused }

end;


See also

Pause method

Play method

Resume method

StartRecording method

Stop method


Pen property

See also	Example

Applies to

TCanvas object; TShape component

Declaration

property Pen: TPen;

Description

A canvas object's Pen property determines what kind of pen the canvas uses for drawing lines and shape outlines.


Example

The following code prints a rectangle that uses a pen 40 pixels wide when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Printer.Canvas.Pen.Width := 40;

  Printer.BeginDoc;

  Printer.Canvas.Rectangle(30, 30, 400, 600);

  Printer.EndDoc;

end;

Before running this code, you must add the Printers unit to the uses clause of your unit.


See also

TBrush object

TFont object


PenPos property

See also

Applies to

TCanvas object

Declaration

property PenPos: TPoint;

Description

The PenPos property is the current drawing position of the pen. You should use the MoveTo method to set the drawing position, rather than changing PenPos directly.


See also

MoveTo method


PickList property

Applies to

TColumn object

Declaration

property PickList: TStrings;

Description

The PickList property lets you specify a list of strings the user can choose from for the column in a TDBGrid. When the user chooses from the list, the corresponding field's value is set to what the user chose. PickList is similar to using a lookup field, but is more useful for lists of items that rarely change or are fixed in the application.


Picture property

See also	Example

Applies to

TDBImage, TImage components

Declaration

property Picture: TPicture;

Description

The Picture property determines the image that appears on the image control. The property value is a TPicture object which can contain an icon, metafile, bitmap graphic, or user-defined graphic object.


Example

This example uses two picture components. When the form first appears, two bitmaps are loaded into the picture components and stretched to fit the size of the components. To try this code, substitute names of bitmaps you have available.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Image1.Stretch := True;

  Image2.Stretch := True;

  Image1.Picture.LoadFromFile('BITMAP1.BMP');

  Image2.Picture.LoadFromFile('BITMAP2.BMP');

end;


See also

Bitmap property

Icon property

Metafile property

LoadFromFile method

SaveToFile method


PictureClosed property

See also	Example

Applies to

TOutline component

Declaration

property PictureClosed: TBitmap;

Description

The PictureClosed property determines the picture displayed in the TOutline component that represents an item, which contains subitems but is not expanded. By default, the PictureClosed property contains a picture of a closed file folder. The OutlineStyle property must be set to osPictureText, osPlusMinusPictureText, or osTreePictureText to display the PictureClosed picture.


Example

The following code loads a new bitmap for the PictureClosed property of Outline1.

Outline1.PictureClosed.LoadFromFile('C:\closed.bmp');


See also

PictureLeaf property

PictureMinus property

PictureOpen property

PicturePlus property


PictureLeaf property

See also	Example

Applies to

TOutline component

Declaration

property PictureLeaf: TBitmap;

Description

The PictureLeaf property determines the picture displayed in the TOutline component that represents an item that contains no subitems. By default, the PictureLeaf property contains a bitmap of a document. The OutlineStyle property must be set to osPictureText, osPlusMinusPictureText, or osTreePictureText to display the PictureLeaf picture.


Example

The following code tests the Width of the leaf picture. If it is wider than ten pixels, the OutlineStyle is changed so that the leaf picture is not displayed.

if Outline1.PictureLeaf.Width > 10 then

  Outline1.OutlineStyle := osTreeText;


See also

PictureClosed property

PictureMinus property

PictureOpen property

PicturePlus property


PictureMinus property

See also	Example

Applies to

TOutline component

Declaration

property PictureMinus: TBitmap;

Description

The PictureMinus property determines the picture displayed in the TOutline component that represents an item, which contains subitems and is expanded. By default, the PictureMinus property contains a bitmap of a minus sign. The OutlineStyle property must be set to osPlusMinusPictureText or osPlusMinusText to display the PictureMinus picture.


Example

The following code displays the same picture for the plus and minus states of Outline1. The same graphic appears whether an item is expanded or collapsed.

Outline1.PictureMinus := Outline1.PicturePlus;


See also

PictureClosed property

PictureLeaf property

PictureOpen property

PicturePlus property


PictureOpen property

See also	Example

Applies to

TOutline component

Declaration

property PictureOpen: TBitmap;

Description

The PictureOpen property determines the picture displayed in the TOutline component that represents an item, which contains subitems and is expanded. By default, the PictureOpen property contains a bitmap of an open file folder. The OutlineStyle property must be set to osPictureText, osPlusMinusPictureText, or osTreePictureText to display the PictureOpen picture.


Example

The following code copies text ('Hello world') into the PictureOpen bitmap.

Outline1.PictureOpen.Canvas.TextOut(0, 0, 'Hello world');


See also

PictureClosed property

PictureLeaf property

PictureMinus property

PicturePlus property


PicturePlus property

See also	Example

Applies to

TOutline component

Declaration

property PicturePlus: TBitmap;

Description

The PicturePlus property determines the bitmap displayed in the TOutline component that represents an item, which contains subitems but is not expanded. By default, the PicturePlus property contains a bitmap of a plus sign. The OutlineStyle property must be set to osPlusMinusPictureText or osPlusMinusText to display the PicturePlus picture.


Example

The following code allows the user to specify the graphic for the PicturePlus property of Outline1 by using the Open dialog box .

if OpenDialog1.Execute then

  Outline1.PicturePlus.LoadFromFile(OpenDialog1.FileName);


See also

PictureClosed property

PictureLeaf property

PictureMinus property

PictureOpen property


Pie method

See also	Example

Applies to

TCanvas object

Declaration

procedure Pie(X1, Y1, X2, Y2, X3, Y3, X4, Y4: Longint);

Description

The Pie method draws the section of an ellipse bounded by the rectangle (X1, Y1) and (X2, Y2) on the canvas. The section drawn is determined by two lines radiating from the center of the ellipse through the points (X3, Y3) and (X4, Y4).


Example

This code draws a section of an ellipse on the form's canvas when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form1.Canvas.Pie(10, 10, 200, 200, 61, 3, 200, 61);

end;


See also

Ellipse method


Pitch property

See also	Example

Applies to

TFont and TTextAttributes objects

Declaration

property Pitch: TFontPitch;

Description

The Pitch property specifies the pitch or width of the characters of a font. Characters with variable pitch can have varying widths. For example, the following characters are in a variable pitch font. Note that the width of ten 'i' characters is less than the width of ten 'M' characters.

iiiiiiiiii

MMMMMMMMMM

The following characters are in a fixed-pitch font. Note that ten 'i' characters are the same width as ten 'M' characters:

iiiiiiiiii

MMMMMMMMMM

Here are the possible values for Pitch:

Value	Meaning

fpDefault	The font pitch is set to the default value, which depends on the font specified in the Name property.

fpFixed	The font pitch is set to fixed. All characters in the font have the same width.

fpVariable	The font pitch is set to variable. The characters in the font have different widths.

Note:	Setting the Pitch of a fixed-width font to fpVariable or a variable-width font to fpFixed might have no effect on the appearance of a font, or might cause Windows to substitute a different font. For example, setting the pitch of MS Serif (a variable-pitch font) to fpFixed causes Courier to be displayed.


Example

The following code toggles the pitch of the Font of Label1 from variable to fixed or from fixed to variable.

if Label1.Font.Pitch = fpFixed then

  Label1.Font.Pitch := fpVariable

else

  if Label1.Font.Pitch = fpVariable then

    Label1.Font.Pitch := fpFixed;


See also

Font property


Pixels property

Example

Applies to

TCanvas object

Declaration

property Pixels[X, Y: Longint]: TColor;

Description

The Pixels array enables you to access any pixel on the canvas directly, to either set or read the color there. Each element in Pixels contains the color of the corresponding pixel in the canvas. The array indexes, X and Y, specify the horizontal and vertical coordinates of the pixel, respectively.

Note:	This is the slowest way to draw an image.


Example

This example draws a red line (very slowly) when the form becomes active. Attach the following code to the OnActivate event handler:

procedure TForm1.FormActivate(Sender: TObject);

var

  W: Word;

begin

  for W := 10 to 200 do

    Canvas.Pixels[W, 10] := clRed;

end;


PixelsPerInch property

Applies to

TFont object; TForm, TScreen components

Description

There are three different properties called PixelsPerInch: one for forms, one for the screen, and one for fonts.

PixelsPerInch Property for Forms

PixelsPerInch Property for the Screen

PixelsPerInch Property for Fonts


PixelsPerInch property

See also

Applies to

TForm components

Declaration

property PixelsPerInch: Integer;

Description

The PixelsPerInch property for a form indicates the system font proportions of the system used to design the form. The PixelsPerInch property has nothing to do with screen resolution. This property is used when Scaled is True to determine whether and/or how much to scale the form so that the form's controls have the same proportions as when they were designed. In general, you should not modify the PixelsPerInch property; it is updated automatically when a form is saved at design-time.

Note:	Although you can change the PixelsPerInch value with the Object Inspector, you won't see the results until you run your application. Also, you must set the Scaled property to be True, or a change in the PixelsPerInch value has no effect.


See also

Scaled property


PixelsPerInch property

See also	Example

Applies to

TScreen components

Declaration

property PixelsPerInch: Integer;

Description

Read and run-time only. Windows PixelsPerInch is a misnomer: it tells you nothing about the pixel resolution or aspect ratio of the video screen. All PixelsPerInch tells you is the relative size of the Windows system font. The value in PixelsPerInch is retrieved from Windows when Delphi loads.


Example

This example adds 30 to the form's PixelsPerInch property if the screen's PixelsPerInch property is greater than 100:

procedure TForm1.FormActivate(Sender: TObject);

begin

  Form1.Scaled := True;

  if PixelsPerInch > 100 then

    Form1.PixelsPerInch := Form1.PixelsPerInch + 30;

end;


See also

Screen variable


PixelsPerInch property

See also

Applies to

TFont object components

Declaration

property PixelsPerInch: Integer;

Description

The PixelsPerInch property affects printer fonts only and should not be modified. Delphi uses the PixelsPerInch property to ensure that when a font is copied from the form's canvas to the printer, the font is the same size in points. For example, if the font is 8 points on the screen, Delphi makes sure the font is 8 points when it is printed.

If you want to modify the size of a font, use the Size or Height properties.


See also

Height property

Size property


PlainText property

See also

Applies to

TRichEdit component

Declaration

property PlainText: Boolean;

Description

The PlainText property controls whether the TRichEdit treats its text as plain text or rich text. The default is False. You can use this option when saving files or loading files to or from an RTF format or a text format.


See also

ConsistentAttributes property

DefAttributes property

SelAttributes property

DefaultConverter property


Play method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Play;

Description

The Play method plays the media loaded in the open multimedia device. Play is called when the Play button on the media player control is clicked at run time.

Upon completion, Play stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Play method has completed. The Notify property determines whether Play generates an OnNotify event.

If the StartPos property is set, playing starts at the position specified in StartPos. Otherwise, playing starts at the current position, specified in the Position property. Similarly, if the EndPos property is set, playing stops at the position specified in EndPos. Otherwise, playing stops at the end of the medium.

Whether the medium (specified in the Position property) is rewound before playing starts depends on the AutoRewind property.


Example

This example uses a media player and a button on a form. When the application runs, only the button is visible. When the user clicks the button, the .WAV file plays.

To run this example, the file CHIMES.WAV must be in your Windows directory.

procedure TForm1.FormActivate(Sender: TObject);

var

  WinDir: PChar;

begin

  MediaPlayer1.Visible := False;

  GetMem(WinDir, 144);

  GetWindowsDirectory(WinDir, 144);

  StrCat(WinDir, '\CHIMES.WAV');

  MediaPlayer1.FileName := StrPas(WinDir);

  MediaPlayer1.Open;

  FreeMem(WinDir, 144);

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  MediaPlayer1.Play;

end;


See also

Capabilities property

Pause method

PauseOnly method

StartRecording method

Stop method


Point function

See also	Example

Declaration

function Point(AX, AY: Integer): TPoint;

Description

The Point function takes the x- and y-coordinates passed in AX and AY and returns a TPoint record. You'll most often use Point to construct a parameter for a function that requires one or more TPoint.


Example

The following code uses the Polygon method to draw a right triangle on a form called Form1:

Polygon([Point(10, 10), Point(10, 20), Point(20, 20)]);


See also

Rect function


PokeData method

See also	Example

Applies to

TDDEClientConv component

Declaration

function PokeData(Item: string; Data: PChar): Boolean;

Description

The PokeData method sends data to a DDE server application. Text data from a linked control in the DDE client application is transferred to the linked section of the DDE server application. Item specifies the linked item in the DDE server. Data is a null-terminated string that specifies the text data to transfer to the DDE server.

The usual direction of data flow is from the DDE server to the DDE client application. Some DDE server applications won't accept poked data. PokeData returns True if the data was successfully transferred, or False if the data was not successfully transferred.

If you need to poke a string list rather than a single string, use the PokeDataLines method.

Note:	If either the ExecuteMacro or ExecuteMacroLines method was called with its WaitFlg parameter set to True prior to calling PokeData, you must wait until the server application has completed executing the macro before calling PokeData. Depending on the DDE server application, calling PokeData before the DDE server application has completed executing the macro might cause the macro to execute unsuccessfully or produce unpredictable results.


Example

The following code pokes the data that is in Edit1 to the DDE server. The DDE item of the conversation is specified in the DDEItem property of DDEClientItem1. TheData is a PChar variable.

DDEClientConv1.PokeData(DDEClientItem1.DDEItem, StrPCopy(TheData, Edit1.Text));


See also

PokeDataLines method

StrPCopy function


PokeDataLines method

See also	Example

Applies to

TDDEClientConv component

Declaration

function PokeDataLines(Item: string; Data: TStrings): Boolean;

Description

The PokeDataLines method sends data to a DDE server application. Text data from a linked control in the DDE client application is transferred to the linked section of the DDE server application. Item specifies the linked item in the DDE server. Data is a TStrings object that specifies the text data to transfer to the DDE server.

The usual direction of data flow is from the DDE server to the DDE client application. Some DDE server applications won't accept poked data. PokeDataLines returns True if the data was successfully transferred, or False if the data was not successfully transferred.

If you need to poke a single string rather than a string list, use the PokeData method.

Note:	If either the ExecuteMacro or ExecuteMacroLines method was called with its WaitFlg parameter set to True prior to calling PokeDataLines, you must wait until the server application has completed executing the macro before calling PokeDataLines. Depending on the DDE server application, calling PokeDataLines before the DDE server application has completed executing the macro might cause the macro to execute unsuccessfully or produce unpredictable results.


Example

The following code pokes the data that is in Memo1 to the DDE server. The DDE item of the conversation is specified in the DDEItem property of DDEClientItem1. TheData is a PChar variable.

DDEClientConv1.PokeData(DDEClientItem1.DDEItem, Memo1.Lines));


See also

PokeData method


Polygon method

See also	Example

Applies to

TCanvas object

Declaration

procedure Polygon(Points: array of TPoint);

Description

The Polygon method draws a series of lines on the canvas, connecting the points passed to it in Points (much as the PolyLine method would), then closes the shape by drawing a line from the last point to the first point. After drawing the complete shape, Polygon fills the shape using the current brush.

The Slice function can be used to pass a portion of an array of points to the Polygon method. For example, if you have an array that can hold 100 points, but you only wish to form a polygon with the first 10, you can use the slice function such as:

Canvas.Polygon.(Slice(PointArray, 10));


Example

This example draws a polygon in the specified shape, and fills it with the color teal:

procedure TForm1.FormActivate(Sender: TObject);

begin

  Canvas.Brush.Color := clTeal;

  Canvas.Polygon([Point(10, 10), Point(30, 10),

    Point(130, 30), Point(240, 120)]);

end;


See also

PolyLine method

Slice function


PolyLine method

See also	Example

Applies to

TCanvas object

Declaration

procedure Polyline(Points: array of TPoint);

Description

The PolyLine method draws a series of lines on the canvas with the current pen, connecting each of the points passed to it in Points.

The Slice function can be used to pass a portion of an array of points to the Polyline method. For example, if you have an array that can hold 100 points, but you only wish to form a polyline with the first 10, you can use the slice function such as:

Canvas.Polyline.(Slice(PointArray, 10));


Example

This example paints a series of connected lines in the color red:

procedure TForm1.FormPaint(Sender: TObject);

begin

  Canvas.Pen.Color := clRed;

  Canvas.PolyLine([Point(5, 5), Point(100, 40), Point(150, 120),

    Point(140, 200), Point(80, 100), Point(5, 5)]);

end;


See also

Pen property

Polygon method

Slice function


Popup method

See also	Example

Applies to

TPopupMenu component

Declaration

procedure Popup(X, Y: Integer);

Description

The Popup method displays a pop-up menu on screen at the coordinates indicated by the values (in pixels) of X and Y.


Example

This example uses a pop-up menu. When the user presses the mouse button, the pop-up menu appears near the upper left corner of the form:

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  PopupMenu1.AutoPopup := False;

  PopupMenu1.Popup(Form1.Left + 10, Form1.Top + 40);

end;


See also

AutoPopup property

OnPopup event

PopupMenu property


PopupComponent property

See also	Example

Applies to

TPopupMenu component

Declaration

property PopupComponent: TComponent;

Description

Run-time only. The PopupComponent property refers to of the component the user clicked on to display the pop-up menu. If your application has multiple controls that share the same pop-up menu, you can use PopupComponent to determine which of them displayed the menu.

If you activate a pop-up menu by explicitly calling PopupMenu1.Popup, and you want that pop-up menu invocation associated with a particular component, you should assign the component to the pop-up's PopupComponent property before calling Popup.


Example

This example uses two edit boxes, two memos, and one pop-up menu on a form. The pop-up menu contains Cut, Copy, and Paste commands. This code makes the pop-up menu available to both edit boxes and both memos:

procedure TForm1.FormCreate(Sender: TObject);

begin

  PopupMenu1.AutoPopup := True;

  Edit1.PopupMenu := PopupMenu1;

  Edit2.PopupMenu := PopupMenu1;

  Memo1.PopupMenu := PopupMenu1;

  Memo2.PopupMenu := PopupMenu1;

end;

These are the cut, copy, and paste OnClick events for the commands on the pop-up menu. The code only allows the user to cut and copy text from the edit boxes, and to paste text into the memo boxes.

procedure TForm1.Copy1Click(Sender: TObject);

begin

  if PopupMenu1.PopupComponent = Edit1 then

   Edit1.CopyToClipboard

  else

    if PopupMenu1.PopupComponent = Edit2 then

    Edit2.CopyToClipboard;

end;

procedure TForm1.Cut1Click(Sender: TObject);

begin

  if PopupMenu1.PopupComponent = Edit1 then

    Edit1.CutToClipboard

  else

    if PopupMenu1.PopupComponent = Edit2 then

    Edit2.CutToClipboard;

end;

procedure TForm1.Paste1Click(Sender: TObject);

begin

  if PopupMenu1.PopupComponent = Memo1 then

    Memo1.PasteFromClipboard

  else

    if PopupMenu1.PopupComponent = Memo2 then

      Memo2.PasteFromClipboard;

end;


See also

AutoPopup property

OnPopup event

PopupMenu property


PopupMenu property

See also	Example

Applies to

TBitBtn, TButton, TCheckBox, TComboBox, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBLookupCombo, TDBLookupList, TDBListBox, TDBMemo, TDBNavigator, TDBText, TDBRadioGroup, TDirectoryListBox, TDrawGrid, TDriveComboBox, TEdit, TFileListBox, TForm, TGroupBox, THeaderControl, TImage, TLabel, TListBox, TListView, TMaskEdit, TMemo, TNotebook, TPageControl, TPanel, TPaintBox, TRadioButton, TRichEdit, TScrollBar, TScrollBox, TStatusBar, TStringGrid, TTabControl, TTabSheet, TTrackBar , TTreeView components

Declaration

property PopupMenu: TPopupMenus;

Description

The PopupMenu property identifies the pop-up menu that appears when the user selects the component and presses the right mouse button (if the pop-up menu's AutoPopup property is True), or when the Popup method of the pop-up menu is called.


Example

This example assigns the pop-up menu named MyPopupMenu to the form:

procedure TForm1.FormActivate(Sender: TObject);

begin

  PopupMenu := MyPopupMenu;

end;


See also

OnPopup event


Position property

Applies to

TControlScrollBar, TForm, TMediaPlayer, TProgressBar, TScrollBar, TTrackBar, TUpDown components

Description

Position Property for Forms

Position Property for scroll bars

Position Property for progress bars

Position Property for track bars

Position Property for Media Players

Position Property for Find and Replace Dialog Boxes

Position Property for TUpDown Components


Position property for forms
Position property

Applies to

TForm component

Declaration

property Position: TPosition;

Description

The Position property determines the size and placement of the form when it appears in your application. These are the possible values:

Value	Meaning

poDesigned	The form appears positioned on the screen and with the same height and width as it had at design time.

poDefault	The form appears in a position on the screen and with a height and width determined by Windows. Each time you run the application, the form moves slightly down and to the right. The right side of the form is always near the far right side of the screen, and the bottom of the form is always near the bottom of the screen, regardless of the screen's resolution.

poDefaultPosOnly	The form displays with the size you created it at design time, but Windows chooses its position on the screen. Each time you run the application, the form moves slightly down and to the right. When the form can no longer move down and to the right and keep the same size while remaining entirely visible on the screen, the form displays at the top-left corner of the screen.

poDefaultSizeOnly	The form appears in the position you left it at design time, but Windows chooses its size. The right side of the form is always near the far right side of the screen, and the bottom of the form is always near the bottom of the screen, regardless of the screen's resolution.

poScreenCenter	The form remains the size you left it at design time, but is positioned in the center of the screen.

The default value is poDesigned.


Position property

See also	Example

Applies to

TControlScrollBar, TScrollBar components

Declaration

property Position: Integer;

Description

The Position property determines the position of the thumb tab on a scroll bar. When the user scrolls the scroll bar, the value of Position changes. You can also change where the thumb tab appears on the scroll bar by changing the value of Position.

For TControlScrollBar components, the value of the Range property determines the number of possible positions on a scroll bar that a thumb tab can assume. The default value is 0, which positions the thumb tab at the far left.

For TScrollBar components, the number of possible positions on the scroll bar is determined by the difference between the Max property and the Min property. If the Min and Position values are both 0, the thumb tab is positioned to the far left on a horizontal scroll bar and to the top of a vertical scroll bar. If Min is 10, Position can be no less than 10.


Example

This code places the thumb tab in the middle of the scroll bar:

ScrollBar1.Max := 1000;

ScrollBar1.Min := 500;

ScrollBar1.Position := 750;


See also

HorzScrollBar property

Increment property

LargeChange property

SmallChange property

VertScrollBar property


Position property

See also	Example

Applies to

TMediaPlayer component

Declaration

property Position: Longint;

Description

Run-time only. The Position property specifies the current position within the currently loaded medium. The value of Position is specified according to the current time format, which is specified in the TimeFormat property.

Position defaults to the beginning of the medium. If the medium supports multiple tracks, Position defaults to the beginning of the first track.


Example

The following code shows the position of the currently playing .WAV audio file (CARTOON.WAV in this example) in the Caption of a label. The current position is updated by Timer1.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    DeviceType := dtWaveAudio;

    FileName := 'CARTOON.WAV';

    Open;

    TimeFormat := tfMilliseconds;

    Label1.Caption := IntToStr(Position);

    Play;

  end;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  Label1.Caption := IntToStr(MediaPlayer1.Position);

end;


See also

Length property

Start property

TrackPosition property

Tracks property


Position property

See also	Example

Applies to

TFindDialog, TReplaceDialog component

Declaration

property Position: TPoint;

Description

The Position property determines where the Find or Replace dialog box appears onscreen.


Example

This example uses a Find dialog box and a button on a form. When the user clicks the button, the Find dialog box appears on screen at location 100, 200.

procedure TForm1.Button1Click(Sender: TObject);

begin

  FindDialog1.Position := Point(100, 200);

  if FindDialog1.Execute then ;

end;


See also

CloseDialog method


Position property for track bars
Position property

See also

Applies to

TTrackBar component

Declaration

property Position: Integer;

Description

The Position property is a value, in a range between Min and Max, that indicates the current position of a TTrackBar. Use the mouse to move the slider which marks this Position. Use the LineSize and PageSize properties to set the number of ticks the slider will move Position either on mouse clicks or by using the arrow and paging keys.


See also

LineSize property

Max property

Min property

PageSize property

SelEnd property

SelStart property

TickStyle property


Position property for progress bars
Position property

See also

Applies to

TProgressBar component

Declaration

property Position: Integer;

Description

The Position property sets the current position in tracking the progress of an application toward completing an operation. The range of values for Position are between Min and Max.


See also

Max property

Min property

Step property


Orientation property for updown controls
Position property

See also	Example

Applies to

TUpDown component

Declaration

property Position: SmallInt;

Description

The Position property contains the numeric value to adjust up or down by clicking on the TUpDown arrow buttons. Specifying an edit control, for example, with the Associate property automatically sets its text to the value of Position.

If Associate is not specified Position can be used as an assigned value.


Example

This example demonstrates how to use Position with a control that was not selected as a companion window of the TUpDown control. It uses the value in Position to tab through pages of a TTabbedNotebook component by clicking on the Up and Down arrows of the TUpDown control:

procedure TForm1.UpDown1Changing(Sender: TObject; var AllowChange: Boolean);

begin

  TabbedNotebook1.PageIndex := UpDown1.Position;

end;


See also

Associate property

Max property

Min property

Thousands property

Wrap property


Post method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure Post;

Description

The Post method writes the current record to the database. Post should be called after calling Append or Insert and making any desired changes to the fields of the current record.

Post behaves differently depending on a dataset's state.

In Edit state, Post modifies the current record.

In Insert state, Post inserts or appends a new record.

In SetKey state, Post commits the changes to the search key buffer, and returns the dataset to Browse state.

Posting can be done explicitly, or implicitly as part of another procedure. When an application moves off the current record, Delphi calls Post implicitly. Calls to the Next, MoveBy, Prior, First, and Last methods perform a Post if the table is in Edit or Insert state. The Append, AppendRecord, Insert, and InsertRecord methods also implicitly perform a Post of any pending data.

Note:	If the record can not be written to the database for some reason, the dataset will remain in Edit state.


Example

with Table1 do

  begin

  Append;

  FieldByName('CustNo').AsString := '9999';

  { Fill in other fields here }

  if { you are sure you want to do this} then Post

  else { if you changed your mind } Cancel;

  end.


See also

Cancel method


Precision property

Applies to

TBCDField, TCurrencyField, TFloatField components

Declaration

property Precision: Integer;

Description

The Precision property is used in formatting numeric fields. The value of Precision is the number of digits the numeric value should be formatted to before rounding begins. The default value is 15 decimal places.


Prepare method

Applies to

TQuery, TStoredProc components

Description

Prepare Method for Queries

Prepare Method for Stored Procedures


Prepare method

See also	Example

Applies to

TStoredProc components

Declaration

procedure Prepare;

Description

The Prepare method prepares the stored procedure to be executed. This allows the server to load the procedure and otherwise prepare for execution.


Example

StoredProc1.Params[0].AsString := Edit1.Text;

StoredProc1.Prepare;

StoredProc1.ExecProc;


See also

Prepared property

UnPrepare method


Prepare method

See also

Applies to

TQuery components

Declaration

procedure Prepare;

Description

The Prepare method sends a parameterized query to the database engine for parsing and optimization. A call to Prepare is not required to use a parameterized query. However, it is strongly recommended, because it will improve performance for dynamic queries that will be executed more than once. If a query is not explicitly prepared, each time it is executed, Delphi automatically prepares it.

Prepared is a Boolean property of TQuery that indicates if a query has been prepared.

If a query has been executed, an application must call Close before calling Prepare again. Generally, an application should call Prepare once--for example, in the OnCreate event of the form--then set parameters using the Params property, and finally call Open or ExecSQL to execute the query. Each time the query is to be executed with different parameter values, an application must call Close, set the parameter values, and then execute the query with Open or ExecSQL.


See also

Text property


Prepared property

Applies to

TQuery, TStoredProc components

Description

Prepared property for Queries

Prepared property for Stored Procedures


Prepared property

See also	Example

Applies to

TStoredProc components

Declaration

property Prepared: Boolean;

Description

Run-time only. The Prepared property is True if the stored procedure has been submitted to the server for optimization purposes. Setting Prepared to True will not execute the procedure; it simply advises the server that the procedure will need to be executed at some future time. Setting Prepared to True is equivalent to calling the Prepare method; setting it to False is equivalent to calling the UnPrepare method.


Example

{ Make sure that the server is aware that we will be executing the procedure }

with StoredProc1 do

  if not Prepared then Prepared := True;


See also

Prepare method

UnPrepare method


Prepared property

See also	Example

Applies to

TQuery components

Declaration

property Prepared: Boolean;

Description

Run-time only. The Prepared property specifies if the Prepare method has been called to prepare the TQuery. While preparing a query is not required, it is highly recommended in most cases.

Note:	Close the TQuery by setting the Active property to False before changing Prepared.


Example

if not Query1.Prepared then

  begin

  Query1.Close;

  Query1.Prepared := True;

  end;


See also

Params property

UnPrepare method


Preview property

See also	Example

Applies to

TReport component

Declaration

property Preview: Boolean;

Description

The Preview property determines whether a report should be viewed onscreen or printed. If Preview is True, the report appears onscreen when the report is run. If Preview is False, the report is printed.


Example

This example uses a report component and a button on a form. When the user clicks the button, a message appears if the Preview property is True. If Preview is True, the MyReport report is sent to the screen; if Preview is False, the report prints on the printer.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Report1.ReportName := 'MyReport';

  if Report1.Preview then

    Application.MessageBox('Sending the report to the screen', 'Message box', MB_OK);

  Report1.Run;

end;


See also

ReportName property

Run method


Previous method

Applies to

TForm, TMediaPlayer components

Description

The Previous method activates the previous form or media player track.

Previous Method for Forms

Previous Method for Media Players


Previous method

See also	Example

Applies to

TForm components

Declaration

procedure Previous;

Description

The Previous method makes the previous MDI child form in the form sequence the active form.

For example, if you have three child forms within a parent form in your MDI application and Form4 is the active form, the Previous method makes Form3 the active form. Calling Previous again makes Form2 active. The next time your application calls Previous, the sequence starts over again and Form4 becomes the active form once again.

The Previous method applies only to forms that are MDI parent forms (have a FormStyle property value of fsMDIForm).


Example

This code sample activates the previous child window of the parent (Form1) when the user selects a menu item named Previous on a menu.

procedure TForm1.Previous1Click(Sender: TObject);

begin

  Previous;

end;


See also

ArrangeIcons method

Cascade method

Next method

Tile method


Previous method

See also	Example

Applies to

TMediaPlayer components

Declaration

procedure Previous;

Description

The Previous method sets the current position to the beginning of the previous track if the position was at the beginning of a track when Previous was called. If the position is at the first track or somewhere other than the beginning of a track when Previous was called, Previous sets the current position to the beginning of the current track. If the device doesn't use tracks, Previous sets the current position to the beginning of the medium, which is specified in the Start property. Previous is called when the Previous button on the media player control is clicked at run time.

Upon completion, Previous stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Previous method has completed. The Notify property determines whether Previous generates an OnNotify event.


Example

The following code rewinds the media after playing has completed. Normally, setting AutoRewind to True would accomplish the same result, but if EndPos is set, AutoRewind has no effect. This code is essentially an AutoRewind for media with EndPos set.

with MediaPlayer1 do

begin

  EndPos := 3000;

  Play;

  Previous;

end;


See also

AutoRewind property

Next method

Position property

Tracks property


Print method

Applies to

TForm, TReport, TRichEdit components

The Print method prints either a form or a report.

Print Method for Forms

Print Method for TRichEdit Components

Print Method for Reports


Print method

See also	Example

Applies to

TForm component

Declaration

procedure Print;

Description

The Print method prints the form.


Example

This example uses a button named PrintButton on a form. When the user chooses the button, the form prints.

procedure TForm1.PrintButtonClick(Sender: TObject);

begin

  Print;

end;


See also

PrintScale property


Print method

See also	Example

Applies to

TReport component

Declaration

function Print: Boolean;

Description

The Print method determines whether a ReportSmith report prints. Print sends a DDE message to ReportSmith Runtime and looks for a DDE message from ReportSmith Runtime in return. If Print returns True, ReportSmith Runtime received the message to print the report. If Print returns False, ReportSmith Runtime could not receive the DDE message at the current time.


Example

This example notifies the user if the report is being printed:

procedure TForm1.Button1Click(Sender: TObject);

begin

  if Report1.Print = True then

    MessageDlg('Printing the report', mtInformation, [mbOK], 0) ;

end;


See also

Preview property

PrintCopies property

Run method


Print method for rich edit controls
Print method

Applies to

TRichEdit component

Declaration

procedure Print(const Caption: string);

Description

Run-time only. The Print method prints the contents of the TRichEdit. Caption is used as the title of the printed document.


PrintCopies property

See also	Example

Applies to

TReport component

Declaration

property PrintCopies: Word;

Description

The value of the PrintCopies property determines how many copies of the report are printed when you run a report. Specify the number of copies you want printed when your report runs. The default value is 1.


Example

The following code reads the number of copies to print from an edit box.

Report1.PrintCopies := StrToInt(Edit1.Text);


See also

EndPage property

StartPage property


Printer function

Example

Unit

Printers

Declaration

function Printer: TPrinter;

Description

The Printer function creates an instance of a global TPrinter object the first time it is called. Use the Printer function when you want to print using the TPrinter object.

Printer is declared in the Printers unit. Whenever you use the Printer function and the TPrinter object, you must add Printers to the uses clause of your unit.

Note: :	Code which assigned to the Printer global variable in Delphi 1.0 will need to be changed to call the SetPrinter method instead.  This allows the entire contents of the Printers unit to be smart linked out if nothing in the program explicitly uses printers or calls Form.Print.


Example

This example prints a one-line print job when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Printer.BeginDoc;

  Printer.NewPage;

  Printer.Canvas.TextOut(100,100, 'Programming is easy');

  Printer.EndDoc;

end;


PrinterIndex property

See also	Example

Applies to

TPrinter object

Declaration

property PrinterIndex: Integer;

Description

Run-time only property. The PrinterIndex property specifies which printer listed in the Printers property is the currently selected printer.

To select the default printer, set the value of PrinterIndex to -1.


Example

The following code asks the user if they want to use the default printer. If they choose yes, PrinterIndex specifies the default printer. The code assumes that Printer is a TPrinter object.

if (MessageDlg('Do you want to use the default printer',

    mtInformation, mbYesNoCancel,0)=idYes) then

      Printer.PrinterIndex := -1;


See also

Printers property


Printers property

See also	Example

Applies to

TPrinter object

Declaration

property Printers: TStrings;

Description

Run-time and read-only. The Printers property is a list of all printers installed in Windows.


Example

The following code displays the names of all printers in ListBox1.

begin

  ListBox1.Items := Printer1.Printers;

end;


See also

Printer variable


Printing property

See also	Example

Applies to

TPrinter object

Declaration

property Printing: Boolean;

Description

Run-time and read-only. The Printing property determines whether a print job is printing. Printing is True when your application has called the BeginDoc method, but the EndDoc method (or the Abort method) hasn't been called yet.


Example

This code terminates the print job if the job is currently printing:

if Printer.Printing then

  Abort;


See also

Aborted property


PrintRange property

See also	Example

Applies to

TPrintDialog component

Declaration

property PrintRange: TPrintRange;

Description

The PrintRange property determines the type of print range the application uses to print a file. These are the possible settings:

Value	Meaning

prAllPages	If set at run time, the user chose to print all pages of the print job. If you set the PrintRange value to prAllPages at design time, the All Pages radio button is selected when the Print dialog box first appears.

prSelection	If set at run time, the user chose to print only selected text. If you set the PrintRange value to prSelection at design time, the Selection radio button is selected when the Print dialog box first appears.

prPageNums	If set at run time, the user chose to specify a range of pages to print. If you set the PrintRange value to prPageNum at design time, the Pages radio button is selected when the Print dialog box first appears, and the user can specify a print range by page numbers. The page numbers are set through the MinPage and MaxPage properties.

The default value is prAllPages.

Note:	The PrintRange property can have the value prSelection only if the Options property set includes poSelection. Also, the PrintRange property can have the value prPageNums only if the Options property set includes poPageNums. If you select either of these PrintRange values at design time, but neglect to set the corresponding Options values to True, only the All Pages option will be enabled when your application displays the Print dialog box.


Example

The following code allows the printing of selected text.

PrintDialog1.Options := PrintDialog1.Options + [poSelection];

PrintDialog1.PrintRange := prSelection;


See also

Options property

PrintToFile property


PrintScale property

See also	Example

Applies to

TForm component

Declaration

property PrintScale: TPrintScale;

Description

The PrintScale property determines the proportions of a printed form. These are the possible values:

Value	Meaning

poNone	No special scaling occurs; therefore, the printed form and how the form appears onscreen may appear squished or stretched.

poProportional	The form is printed so that the printed image is approximately the same visible size as on the screen (WYSIWYG). The form image is scaled so that the printed image is approximately the same visible size as on the screen.

poPrintToFit	The form is printed using the same screen proportions, but in a size that just fits the printed page.

The default value is poProportional.


Example

The following code maintains the proportions of the form when it is printed.

Form1.PrintScale := poProportional;

Form1.Print;


See also

Print method


PrintToFile property

Example

Applies to

TPrintDialog component

Declaration

property PrintToFile: Boolean;

Description

The PrintToFile property determines if the user has chosen to print the print job to a file rather than to a printer. If True, the user has checked the Print to File check box. If False, the user has unchecked the Print to File check box. If PrintToFile is set to True at design time, the Print to File check box is checked when the Print dialog box appears in your application. The default value is False.

Note:	The Print to File check box appears in the Print dialog box, only if the Options property set includes poPrintToFile. Otherwise, your users won't have the option of choosing to print to a file.


Example

This example displays a print dialog box with its Print to File check box checked:

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

with PrintDialog1 do

  begin

    Options := [poPrintToFile];

    PrintToFile := True;

    if Execute then

      ...;

  end;

end;


Prior method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure Prior;

Description

The Prior method moves the current record position of the dataset backward by one record. If the dataset is in Insert or Edit state, Prior will perform an implicit Post of any pending data.


Example

{ Move to the previous record }

Table1.Prior;

if Table1.BOF then { No more records };


See also

First method

Last method

MoveBy method

Next method


PrivateDir property

See also

Applies to

TSession component

Declaration

property PrivateDir: string;

Description

PrivateDir specifies the path of the directory in which to store temporary files (for example, files used to process local SQL statements). You should set this property if there will be only one instance of the application running at a time. Otherwise, the temporary files from multiple application instances will interfere with each other.


See also

Active property

NetFileDir property

Session variable


ProblemCount property

See also	Example

Applies to

TBatchMove component

Declaration

property ProblemCount: Longint;

Description

Run-time and read-only. ProblemCount is the number of records which could not be added to Destination without loss of data due to field width constraints. If AbortOnProblem is True, then this number will be one, since the operation will be aborted when the problem occurs.


Example

MessageDlg(IntToStr(BatchMove1.ProblemCount) + ' records had problems',

  mtInformation, [mbOK], 0);


See also

ProblemTableName property


ProblemTableName property

Example

Applies to

TBatchMove component

Declaration

property ProblemTableName: TFileName;

Description

If the Execute method is unable to move a record to Destination without data loss (caused by a field width conflict), the record will be placed in a new table with the name supplied in ProblemTableName. If AbortOnProblem is True, then there will be at most one record in this table since the operation will be aborted with that first record. ProblemCount will have the number of records placed in the new table. If ProblemTableName is not specified, the data in the record will still be trimmed and placed in the destination table.


Example

BatchMove1.ProblemTableName := 'PROB.DB';


ProcessMessages method

Example

Applies to

TApplication component

Declaration

procedure ProcessMessages;

Description

The ProcessMessages method interrupts the execution of your application so that Windows can respond to events. In Win32, neglecting message processing doesn't affect other applications, it only affects the responsiveness of your own process. By calling ProcessMessages, your application permits Windows to process these events at the time ProcessMessages is called. The ProcessMessages method cycles the Windows message loop until it is empty and then returns control to your application.


Example

This example uses two buttons that are long enough to accommodate lengthy captions on a form. When the user clicks the button with the caption Ignore Messages, the code begins to generate a long series of random numbers. If the user tries to resize the form while the handler is running, nothing happens until the handler is finished. When the user clicks the button with the caption Process Messages, more random numbers are generated, but Windows can still respond to a series of mouse events, such as resizing the form.

Note:	How quickly these event handlers run depends on the microprocessor of your computer. A message appears on the form informing you when the handler has finished executing.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Button1.Caption := 'Ignore Messages';

  Button2.Caption := 'Process Messages';

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  I, J, X, Y: Word;

begin

  I := 0;

  J := 0;

  while I < 64000 do

  begin

    Randomize;

    while J < 64000 do

    begin

      Y := Random(J);

      Inc(J);

     end;

    X := Random(I);

    Inc(I);

  end;

  Canvas.TextOut(10, 10, 'The Button1Click handler is finished');

end;

procedure TForm1.Button2Click(Sender: TObject);

var

  I, J, X, Y: Word;

begin

  I := 0;

  J := 0;

  while I < 64000 do

  begin

    Randomize;

    while J < 64000 do

    begin

      Y := Random(J);

      Inc(J);

      Application.ProcessMessages;

    end;

  X := Random(I);

  Inc(I);

  end;

  Canvas.TextOut(10, 10, 'The Button2Click handler is finished');

end;


Protected property

See also

Applies to

TTextAttributes object

Declaration

property Protected: Boolean;

Description

Run-time only. The Protected property indicates whether the selected text in a rich edit control is protected, meaning read-only.

TTextAttributes is the type of the DefAttributes and SelAttributes properties of TRichEdit.


See also

OnProtectChange event

DefAttributes property

SelAttributes property


Query property

Applies to

TUpdateSQL component

Declaration

property Query[UpdateKind: TUpdateKind]: TQuery;

Description

Run-time and read-only. The Query property returns a TQuery component for the SQL statement corresponding to the UpdateKind index. (For example, Query[ukModify] has the ModifySQL SQL statement.)


QuickDraw property

Applies to

TDBImage component

Declaration

property QuickDraw: Boolean;

Description

The QuickDraw property indicates whether the image is displayed using a palette. If False, a palette is used, to provide the best possible image quality at the expense of additional processing time. If True, no special palette is used, which is faster, but results in poorer picture quality, especially with 256-color images on a 256-color video driver.


RadioItem property

See also

Applies to

TMenuItem component

Declaration

property RadioItem: Boolean;

Description

The RadioItem property determines appearance of the check on the menu item. When RadioItem is True, the check is a round dot instead of a check mark and checking the item unchecks any menu items with the same GroupIndex value.

Note:	The dot will only show up under Windows 95 and under Windows NT 3.51 if the "new shell" has been installed.


See also

GroupIndex property

MenuIndex property


Range property

See also	Example

Applies to

TControlScrollBar component

Declaration

property Range: Integer;

Description

The value of the Range property determines how far a horizontal or vertical form scroll bar can be scrolled. It also represents the virtual size of the form. For example, if the Range value of a horizontal scroll bar is 500, and the client width of the form is 200, the scroll bar position can range from 0 to 300. While the client width of the form is 200, the virtual client width of the form is 500, because the user can scroll the form that far.

If the value of Range for a horizontal scroll bar is less than the client width of the form or scroll box, no horizontal scroll bar appears on the form. Likewise, if the value of Range for a vertical scroll bar is less than the client height of the form or scroll box, no vertical scroll bar appears.

For a horizontal scroll bar, the Range is calculated to be the distance of the right edge of the control that is the farthest to the right in the scroll bar or form from the left edge of the scroll box or form plus an amount specified as the value of the Margin property. If the form or scroll box contains one or more controls that are right-aligned (their Align value is alRight), the width of these controls is also added to the Range calculation.

For a vertical scroll bar, the Range is calculated to be the distance of the bottom edge of the control farthest away from the top edge of the scroll box or form from the top of the scroll box or form plus an amount specified as the value of the Margin property. If the form or scroll box contains one or more controls that are bottom-aligned (their Align value is alBottom), the height of these controls is also added to the Range calculation.


Example

This example uses a button on a form. When the user clicks the button, a vertical scroll bar alternately appears and disappears on the form, because the value of the Range property changes with each click.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ClientHeight := 300;

  VertScrollBar.Visible := True;

  if VertScrollBar.Range = 290 then

    VertScrollBar.Range := 500

  else

    VertScrollBar.Range := 290;

end;


See also

ClientHeight property

ClientWidth property

HorzScrollBar property

VertScrollBar property

Visible property


Read method

See also	Example

Applies to

TBlobStream object

Declaration

function Read(var Buffer; Count: Longint): Longint;

Description

The Read method copies up to Count bytes from the current position in the field to Buffer. Buffer must have at least Count bytes allocated for it. Read returns the number of bytes transferred (which may be less than the number requested in Count.) Transfers which require crossing a selector boundary in the destination will be handled correctly.


Example

The following example reads reads the data from a memo field into a blob stream and displays it in a memo control.

procedure TForm1.Button2Click(Sender: TObject);

var

  Buffer: PChar;

  MemSize: Integer;

  Stream: TBlobStream;

begin

   Stream := TBlobStream.Create(query1.FieldByName('Notes') as TBlobField, bmRead);

   try

     MemSize := Stream.Size;

     Inc(MemSize); {Make room for the buffer's null terminator.}

     Buffer := AllocMem(MemSize);     {Allocate the memory.}

     try

      Stream.Read(Buffer^, MemSize); {Read directly into the buffer.}

      Memo1.SetTextBuf(Buffer);      {Display the buffer's contents.}

    finally

      FreeMem(Buffer, MemSize);

    end;

  finally

    Stream.Free;

  end;

end;


See also

TBlobField component

TBytesField component

TVarBytesField component


ReadBool method

See also	Example

Applies to

TIniFile object

Declaration

function ReadBool (const Section, Ident: string; Default: Boolean): Boolean;

Description

The ReadBool method retrieves a Boolean value in an .INI file.

The Section constant identifies the section of the .INI file in which to search for the value. For example, the WIN.INI for Windows contains a [Desktop] section.

The Ident parameter is the name of the identifier of which you want the value.

The Default parameter is the default value.


Example

This example reads the DELPHI.INI file and displays on the form the status of your auto save options.

To run this application, you must add the IniFiles unit to the uses clause of your unit.

procedure TForm1.FormActivate(Sender: TObject);

var

  DelphiIni: TIniFile;

begin

  DelphiIni := TIniFile.Create('Delphi.Ini');

  with DelphiIni do

  begin

    if ReadBool('AutoSave', 'EditorFiles', True) = True then

      Canvas.TextOut(10, 10, 'Auto saving editor files.')

    else

      Canvas.TextOut(10, 10, 'Not auto saving editor files.');

    if ReadBool('AutoSave', 'DesktopFile', True) = True then

      Canvas.TextOut(10, 50, 'Auto saving desktop file.')

    else

      Canvas.TextOut(10, 50, 'Not auto saving desktop file.');

  end;

  DelphiIni.Free;

end;


See also

ReadInteger method

ReadSection method

ReadString method

WriteBool method


ReadInteger method

See also	Example

Applies to

TIniFile object

Declaration

function ReadInteger(const Section, Ident: string; Default: Longint): Longint;

Description

The ReadInteger method retrieves an integer value in an .INI file.

The Section constant identifies the section of the .INI file in which to search for the value. For example, the WIN.INI for Windows contains a [Desktop] section.

The Ident parameter is the name of the identifier of which you want the value.

The Default parameter is the default value.


Example

This example reads settings in the WIN.INI file and displays on the form the value of a few settings.

Before you run this example, you must add the IniFiles unit to the uses clause of your unit.

procedure TForm1.FormActivate(Sender: TObject);

var

  WinIni: TIniFile;

begin

  Canvas.TextOut(20, 10, 'VARIOUS WINDOWS SETTINGS');

  WinIni := TIniFile.Create('Win.Ini');

  with WinIni do

  begin

    Canvas.TextOut(10, 45, 'Border Width = ' +

      IntToStr(ReadInteger('Windows', 'BorderWidth', -1)));

    Canvas.TextOut(10, 65, 'Icon Spacing = ' +

       IntToStr(ReadInteger('Desktop', 'IconSpacing', -1)));

    Canvas.TextOut(10, 85, 'Grid Granularity = ' +

       IntToStr(ReadInteger('Desktop', 'GridGranularity', -1)));

    Canvas.TextOut(10, 105, 'Cursor Blink Rate = ' +

       IntToStr(ReadInteger('Windows', 'CursorBlinkRate', -1)));

    Canvas.TextOut(10, 125, 'Double Click Speed = ' +

       IntToStr(ReadInteger('Windows', 'DoubleClickSpeed', -1)));

  end;

  WinIni.Free;

end;


See also

ReadBool method

ReadSection method

ReadString method

WriteBool method


ReadOnly property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupComboBox, TDBLookupList, TDBLookupListBox, TDBMemo, TDBRadioGroup, TEdit, TFloatField, TGraphicField, TIntegerField, TListView, TMaskEdit, TMemo, TMemoField, TRichEdit, TSmallintField, TStringField, TTable, TTimeField, TTreeView, TVarBytesField, TWordField components

Description

ReadOnly for Data-aware Controls, Edit Boxes, Memos, Tree Views, List Views and Rich Edits

ReadOnly for Tables

ReadOnly for Field Components


ReadOnly property for data-aware controls, edit boxes, memos, list views, tree views, and rich edit controls
ReadOnly property

See also	Example

Applies to

TDBCheckBox, TDBComboBox, TDBEdit, TDBGrid, TDBImage, TDBListBox, TDBLookupCombo, TDBLookupComboBox, TDBLookupList, TDBLookupListBox, TDBMemo, TDBRadioGroup, TEdit, TListView, TMaskEdit, TMemo, TRichEdit, TTable, TTreeView components

Declaration

property ReadOnly: Boolean;

Description

The ReadOnly property determines if the user can change the contents of the control. If ReadOnly is True, the user can't change the contents. If ReadOnly is False, the user can modify the contents. The default value is False.

For data-aware controls, the ReadOnly property determines whether the user can use the data-aware control to change the value of the field of the current record, or if the user can use the control only to display data. If ReadOnly is False, the user can change the field's value as long as the dataset is in edit mode.

When the ReadOnly property of a data grid is True, the user can no longer use the Insert key to insert a new row in the grid, nor can the user append a new row at the end of the data grid with the Down Arrow key.


Example

This code toggles the read-only state of an edit box each time the user double-clicks the form:

procedure TForm1.FormActivate(Sender: TObject);

begin

  Edit1.Left := 2;

  Edit1.Top := 2;

  Edit1.ReadOnly := True;

  Edit1.Text := 'Change Me';

  Canvas.TextOut(10, 40, 'Double-click form to toggle read-only state');

end;

procedure TForm1.FormDblClick(Sender: TObject);

begin

  Edit1.ReadOnly := not Edit1.ReadOnly;

end;


See also

Alignment property

EditMask property

Options property

Visible property


ReadOnly property for tables
ReadOnly property

See also	Example

Applies to

TTable components

Declaration

property ReadOnly: Boolean;

Description

Use the ReadOnly property to prevent users from changing data in the table.

Note:	Set the Active property to False before changing ReadOnly.


Example

Table1.Active := False;

Table1.ReadOnly := True;

Table1.Active := True;


See also

Exclusive property


ReadOnly property for fields
ReadOnly property

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property ReadOnly: Boolean;

Description

ReadOnly enables or disables modification of a field. If set to False, the default, a field can be modified. To prevent a field from being modified, set ReadOnly to True. In a TDBGrid, tabbing from field to field skips over ReadOnly fields.


ReadSection method

See also

Applies to

TIniFile object

Declaration

procedure ReadSection (const Section: string; Strings: TStrings);

Description

The ReadSection method reads all the variables of a section of an .INI file into a string object. The Strings parameter specifies the string list object. If you want to use a string list that is maintained by a component such as a list box, Strings should specify the property of the component that contains the string list. If you want to maintain the string list independent of any components, use a TStringList object.

The Section constant identifies the section of the .INI file that is read.


See also

EraseSection method

ReadBool method

ReadInteger method

ReadSectionValues method

ReadString method

WriteBool method

WriteInteger method

WriteString method


ReadSectionValues method

See also	Example

Applies to

TIniFile object

Declaration

procedure ReadSectionValues(const Section: string; Strings: TStrings);

Description

The ReadSectionValues method reads all the variables and their values of an entire section of an .INI file into a string object. You can then use the Values property of string and string list objects to access a specific string in the list of strings.


Example

This example reads the Transfer section of the DELPHI32.INI file into a memo and changes one of the strings:

procedure TForm1.Button1Click(Sender: TObject);

var

  DelphiIni: TIniFile;

begin

  DelphiIni := TIniFile.Create('c:\windows\delphi32.ini');

  Memo1.Clear;

  DelphiIni.ReadSectionValues('Transfer', Memo1.Lines);

  Memo1.Lines.Values['Title1'] := 'Picture Painter';

  DelphiIni.Free;

end;

Although this example doesn't do so, your code could then write the new value to the DELPHI.INI file.


See also

EraseSection method

ReadBool method

ReadInteger method

ReadSection method

ReadString method

Values property

WriteBool method

WriteInteger method

WriteString method


ReadString method

See also	Example

Applies to

TIniFile object

Declaration

function ReadString(const Section, Ident, Default: string): string;

Description

The ReadString method retrieves a string in an .INI file. The Section constant identifies the section of the .INI file in which to search for the value. The Ident constant is the name of the identifier of which you want the value. The Default constant is the default string value.


Example

This example reads strings in the DELPHI32.INI file and displays them on the form.

Before you run this application, you must add the IniFiles unit to the uses clause of your unit.

procedure TForm1.FormActivate(Sender: TObject);

var

  DelphiIni: TIniFile;

begin

  Canvas.TextOut(20, 10, 'VARIOUS DELPHI SETTINGS');

  DelphiIni := TIniFile.Create('Delphi32.Ini');

  with DelphiIni do

  begin

    with Canvas do

    begin

      TextOut(10, 50, 'Editor Font = ' +

        ReadString('Editor', 'FontName', 'ERROR'));

      TextOut(10, 70, 'Search Path = ' +

        ReadString('Library', 'SearchPath', 'ERROR'));

      TextOut(10, 90, 'Component Library = ' +

        ReadString('Library', 'ComponentLibrary', 'ERROR'));

      TextOut(10, 110, 'VBX Directory = ' +

        ReadString('VBX', 'VBXDir', 'ERROR'));

      TextOut(10, 130, 'VBX Unit Directory = ' +

        ReadString('VBX', 'UnitDir', 'ERROR'));

    end;

  end;

  DelphiIni.Free;

end;


See also

ReadBool method

ReadInteger method

ReadSection method

WriteBool method

WriteInteger method

WriteString method


RebuildColumns method

Applies to

TDBGridColumns object

Declaration

procedure RebuildColumns;

Description

Initializes the collection of TColumn objects by deleting any existing column objects, then copying field information from the dataset attached to the data source attached to TDBGrid component. If the grid isn't attached to a dataset, RebuildColumns removes all column information.


RecalcReport method

See also	Example

Applies to

TReport component

Declaration

function RecalcReport: Boolean;

Description

The RecalcReport method recalculates and reprints the report with the new value for the report variable previously changed with the SetVariable method.

RecalcReport sends a message to ReportSmith and looks for confirmation in return. If RecalcReport returns True, the message to recalculate the report was sent successfully to ReportSmith. If it returns False, ReportSmith could not recalculate the report at the current time.

For more information about report variables, see your ReportSmith documentation.


Example

The following code sets the 'FirstName' report variable to 'Marty', then recalculates the report.

Report1.SetVariable('FirstName', 'Marty');

if not (Report1.RecalcReport) then

  MessageDlg('Unable to recalculate', mtInformation, [mbOK] 0);


See also

Preview property

Print method

Run method

SetVariable method

SetVariableLines method


RecNo property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property RecNo: Longint;

Description

Run-time and read-only. The RecNo property returns a record number for the current record in the dataset. Record numbers are only available for Paradox and dBASE tables; the concept isn't supported by most SQL servers so a table in a SQL database always returns -1 for RecNo.


RecordCount property

Applies to

TBatchMove, TQuery, TStoredProc, TTable components

Description

RecordCount for Batch Move Components

Record Count for Queries, Tables, and Stored Procedures


RecordCount property

Example

Applies to

TBatchMove component

Declaration

property RecordCount: Longint;

Description

The RecordCount property is used to control the maximum number of records that will be moved. If zero, all records are moved, beginning with the first record in Source. If RecordCount is not zero, a maximum of RecordCount records will be moved, beginning with the current record. If RecordCount exceeds the number of records remaining in Source, no wraparound occurs; the operation is terminated.


Example

{ Limit the move to the first 1000 records }

BatchMove1.RecordCount := 1000;


RecordCount property

Applies to

TQuery, TStoredProc, TTable components

Declaration

property RecordCount: Longint;

Description

Run-time and read-only. The RecordCount property specifies the number of records in the dataset. The number of records reported may depend on the server and whether a range limitation is in effect.

Note:	If the TTable is connected to a dBASE table, RecordCount only reports the total number of records in the table. If you try to limit the number of records in the dataset by calling SetRange, RecordCount will be unaffected; RecordCount reports the total number of records, not the number of records in the limited range.


Rect function

See also	Example

Declaration

function Rect(ALeft, ATop, ARight, ABottom: Integer): TRect;

Description

The Rect function returns a TRect record built from the individual coordinates passed in ALeft, ATop, ARight, and ABottom. You'll usually use Rect to construct parameters for functions that require TRect, rather than setting up local variables for each one.


Example

The following code defines the display rectangle for a media player component to be 100 pixels wide, 200 pixels tall, with a top-left corner at coordinates (10, 10);

MediaPlayer1.DisplayRect := Rect(10, 10, 110, 210);


See also

Point function


Rectangle method

See also	Example

Applies to

TCanvas object

Declaration

procedure Rectangle(X1, Y1, X2, Y2: Integer);

Description

The Rectangle method draws a rectangle on the canvas with its upper left corner at the point (X1, Y1) and its lower right corner at the point (X2, Y2). Rectangle draws the rectangle using the current brush (TBrush) and pen (TPen) attributes.


Example

This example draws many rectangles of various sizes and colors on a form maximized to fill the entire screen:

var

  X, Y: Integer;

procedure TForm1.FormActivate(Sender: TObject);

begin

  WindowState := wsMaximized;

  Canvas.Pen.Width := 5;

  Canvas.Pen.Style := psDot;

  Timer1.Interval := 50;

  Randomize;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  X := X + 4;

  Y := Y + 4;

  Canvas.Pen.Color := Random(65535);

  Canvas.Rectangle(X, Y, X + Random(400), Y + Random(400));

  if X > 700 then

    Timer1.Enabled := False;

end;


See also

RoundRect method


Refresh method

Applies to

All controls; TTable, TQuery, TStoredProc components

Description

Refresh for Tables, Stored Procedures and Queries

Refresh for All Other Controls


Refresh method

See also	Example

Applies to

All controls components

Declaration

procedure Refresh;

Description

The Refresh method erases whatever image is on the screen and then repaints the entire control. Within the implementation of Refresh, the Invalidate and then the Update methods are called.


Example

The following code refreshes all windowed controls of Form1, then refreshes Form1.

var

  I: Integer;

begin

  for I := 0 to Form1.ComponentCount-1 do

    if Form1.Components[i] is TWinControl then

      with Form1.Components[i] as TWinControl do

        Refresh;

  Form1.Refresh;

end;


See also

Repaint method


Refresh method

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure Refresh;

Description

The Refresh method rereads all records from the dataset. Use Refresh to be certain that data controls display the latest information from the dataset.  If used with a TTable, the corresponding table must have a unique index.  If used with a TQuery, the result set  must be live, the tables must be local (Paradox or dBASE) and have a unique index.


Add method for image list objects
RegisterChanges method

See also

Applies to

TImageList component

Declaration

procedure RegisterChanges(Value: TChangeLink);

Description

The RegisterChanges method is called by an object that wants to be informed when changes occur in the ImageList. The TChangeLink's OnChange event will be called whenever a change in the ImageList occurs.


See also

OnChange event, UnRegisterChanges method


Add method for image list objects
RegisterClipboardFormat method

Applies to

TPicture object

Declaration

class procedure RegisterClipboardFormat(AFormat: Word; AGraphicClass: TGraphicClass);

Description

The RegisterClipboardFormat method registers a new TGraphic class for use in the LoadFromClipboardFormat method.


Add method for image list objects
RegisterFileFormat method

Applies to

TPicture object

Declaration

class procedure RegisterFileFormat(const AExtension, ADescription: String; AGraphicClass:   TGraphicClass);

Description

The RegisterFileFormat method registers a new TGraphic class for use in the LoadFromFile method.


Add method for image list objects
RegisterFileFormatRes method

Applies to

TPicture object

Declaration

class procedure RegisterFileFormatRes(const AExtension: String; ADescriptionResID: Integer;   AGraphicClass: TGraphicClass);

Description

The RegisterFileFormat method registers a new TGraphic class for use in the LoadFromFile method and takes a string resource id in the ADescriptionResID parameter.


Release method

See also	Example

Applies to

TForm component

Declaration

procedure Release;

Description

The Release method destroys the form and releases its associated memory. It is much like the Free method except that it does not destroy the form until all event handlers of the form or event handlers of components on the form have finished executing.


Example

This example displays a message box about the form going away, calls Release, and terminates the application.

procedure TForm1.Button1Click(Sender: TObject);

begin

  MessageDlg('This form is going away forever', mtInformation, [mbOK], 0);

  Release;

  Application.Terminate;

end;


See also

Free method

Destroy method


ReleaseHandle method

See also	Example

Applies to

TBitmap ,TIcon object

Declaration

function ReleaseHandle: HBitmap;

Description

The ReleaseHandle method returns the handle to the bitmap so that the TBitmap object no longer knows about the handle.


Example

The following code release the handle to the bitmap in MyBitmap.

MyBitmap.ReleaseHandle;


See also

ReleasePalette method


ReleasePalette method

See also	Example

Applies to

TBitmap object

Declaration

function ReleasePalette: HPalette;

Description

The ReleasePalette method returns the handle to the bitmap's palette and disassociates the palette from the TBitmap object.


Example

The following code release the palette of the bitmap in MyBitmap.

MyBitmap.ReleasePalette;


See also

ReleaseHandle method


Remove method

See also	Example

Applies to

TList object

Declaration

function Remove(Item: Pointer): Integer;

Description

The Remove method deletes the item referenced in the Item parameter from the list of pointers stored in the List property of a list object. The value returned is the position of the item in the list of pointers before it was removed. After an item is removed, all of the items that follow it are moved up in index position and the number of items in the list is reduced by one.


Example

The following code adds a new object to a list in a list object and then removes it:

type

  TMyClass = class

    MyString: string;

    constructor Create(S: string);

  end;

constructor TMyClass.Create(S: string);

begin

  MyString := S;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  MyList: TList;

  MyObject, SameObject: TMyClass;

begin

  MyList := TList.Create;                             { create the list }

  try

    MyObject := TMyClass.Create('Semper Fidelis!');  { create a class instance }

    try

      MyList.Add(MyObject);                            { add instance to list }

      SameObject := TMyClass(MyList.Items[0]);  { get first element in list }

      MessageDlg(SameObject.MyString, mtInformation, [mbOk], 0); { show it }

      MyList.Remove(MyObject);

      MessageDlg('Removing the object', mtInformation, [mbOk], 0);

    finally

      MyObject.Free;

    end;                                      { don't forget to clean up! }

  finally

    MyList.Free;

  end;

end;


See also

Delete method


RemoveAllPasswords method

See also	Example

Applies to

TSession component

Declaration

procedure RemoveAllPasswords;

Description

The RemoveAllPasswords method causes all previously entered password information to be discarded. Any future access will require that new password information be supplied before the table can be opened. This method affects Paradox databases only.


Example

Session.RemoveAllPasswords;


See also

RemovePassword method

Session variable


RemoveComponent method

See also	Example

Applies to

All components

Declaration

procedure RemoveComponent(AComponent: TComponent);

Description

The RemoveComponent method removes the component specified in the AComponent parameter from the component's Components list.


Example

The following code removes Button2 from the Components list of Form1.

Form1.RemoveComponent(Button2);


See also

InsertComponent method


RemoveControl method

See also	Example

Applies to

All controls

Declaration

procedure RemoveControl(AControl: TControl);

Description

The RemoveControl method removes the control specified with the AControl parameter from the Controls array of this control. The result is that this control is no longer the parent of the removed control.


Example

This example uses a button placed alongside a group box. When the user clicks the button, the group box becomes the parent of the button, so the button moves inside the group box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  RemoveControl(Button1);

  GroupBox1.InsertControl(Button1);

end;

Note that it was necessary to remove the button from the Controls property of the form before the button actually appears to move into the group box.

This code accomplishes the same thing:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Parent := GroupBox1;

end;


See also

Controls property

InsertControl method


RemoveParam method

See also	Example

Applies to

TParams object

Declaration

procedure RemoveParam(Value: TParam);

Description

RemoveParam removes Value from the Items property.


Example

{ Move all parameter info from Params2 to Params1 }

while Params2.Count <> 0 do

begin

{ Grab the first parameter from Params2 }

  TempParam := Params2[0];

{ Remove it from Params2 }

  Params2.RemoveParam(TempParam);

{ And add it to Params1 }

  Params1.AddParam(TempParam);

end;


See also

AddParam method


RemovePassword method

See also	Example

Applies to

TSession component

Declaration

procedure RemovePassword(const Password: string);

Description

The RemovePassword method removes Password from the known set of authorizations. Any future access will require that new password information be supplied before the table can be opened. This method affects Paradox databases only.


Example

Session.RemovePassword('MySecret');


See also

RemoveAllPasswords method

Session variable


Repaint method

See also	Example

Applies to

All controls

Declaration

procedure Repaint;

Description

The Repaint method forces the control to repaint its image on the screen, but without erasing what already appears there. To erase before repainting, call the Refresh method instead of Repaint.


Example

The following code repaints all windowed controls of Form1, then repaints Form1.

var

  I: Integer;

begin

  for I := 0 to Form1.ComponentCount-1 do

    if Form1.Components[I] is TWinControl then

      with Form1.Components[I] as TWinControl do

        Repaint;

  Form1.Repaint;

end;


See also

Refresh method


Add method for image list objects
Replace method

See also

Applies to

TImageList component

Declaration

procedure Replace(Index: Integer; Image, Mask: TBitmap);

Description

The Replace method replaces the image at the Index position in the image list with a new Image and transparent Mask.


See also

ReplaceIcon method, ReplaceMasked method, Add method, Insert method


Add method for image list objects
ReplaceIcon method

See also

Applies to

TImageList object

Declaration

procedure ReplaceIcon(Index: Integer; Image: TIcon);

Description

The ReplaceIcon method replaces the Image at the Index position in the image list with a new icon.


See also

Replace method, ReplaceMasked method, AddIcon method


Add method for image list objects
ReplaceMasked method

See also

Applies to

TImageList object

Declaration

procedure ReplaceMasked(Index: Integer; NewImage: TBitmap; MaskColor: TColor);

Description

The ReplaceMasked method replaces the image at Index position within the image list with a new image and creates a mask using the MaskColor for transparency.


See also

ReplaceIcon method, Replace method, AddMasked method, Masked property


ReplaceText property

See also	Example

Applies to

TReplaceDialog component

Declaration

property ReplaceText: string;

Description

The ReplaceText property contains the string your application can use to replace the string specified in the FindText property when the FindText value is found during a search.


Example

The following code replaces the selected text in Memo1 with the value of ReplaceText.

Memo1.SelText := ReplaceDialog1.ReplaceText;


See also

FindText property


ReportDir property

See also	Example

Applies to

TReport component

Declaration

property ReportDir: string;

Description

The value of the ReportDir is the directory where ReportSmith stores its reports and expects to find saved reports. By specifying a report directory, you won't have to include a path when specifying a report name.


Example

The following text lets the user use the Save dialog box component to specify where ReportSmith saves its reports.

if SaveDialog1.Execute then

  Report1.ReportDir := SaveDialog1.FileName;


See also

ReportName property


ReportHandle property

Example

Applies to

TReport component

Declaration

property ReportHandle: HWND;

Description

Run-time and read-only. The value of the ReportHandle property is a Windows handle to ReportSmith.


Example

The following code retrieves the window placement information for ReportSmith, assuming Report1 is a valid TReport component.

var

  RSWinPlacement: PWindowPlacement;

begin

  GetWindowPlacement(Report1.ReportHandle, RSWinPlacement);

end;


ReportName property

See also	Example

Applies to

TReport component

Declaration

property ReportName: string;

Description

The value of the ReportName property determines which report you want to run. You can include a full path name as part of the report name if you have not specified a ReportDir property value or want to run a report that is stored elsewhere. If you have specified a ReportDir value, omit the path name and simply specify the name of the report.


Example

The following code lets users use the Open dialog box component to specify the report they want to run.

if OpenDialog1.Execute then

  Report1.ReportName := OpenDialog1.FileName;


See also

ReportDir property


RequestData method

See also	Example

Applies to

TDDEClientConv component

Declaration

function RequestData(const Item: string): PChar;

Description

The RequestData method requests data from a DDE server. Call RequestData when you want your DDE client application to receive data from the server once, instead of being updated continually. Another reason to use RequestData is that some DDE servers contain DDE items that can't be continually updated; the only way for your client to access these items is to explicitly request the data.

Item specifies the DDE server item you want data from. The value of the DDE item depends on the linked DDE server application. Item is typically a selectable portion of text, such as a spreadsheet cell or a database field in an edit box. If the DDE server is an Delphi application, Item is the name of the linked DDE server component.

Note:	See the documentation for the DDE server application for the specific information about specifying DDEItem.

RequestData returns a null-terminated PChar string which contains the value of the item requested of the DDE server. RequestData automatically allocates memory to store this data, but you must dispose of the PChar string returned by RequestData after you have finished processing it. This is done with the StrDispose function.


Example

The following code requests data from the DDE server and displays it in Label1. The DDE item of the conversation is specified in the DDEItem property of DDEClientItem1.

var

  TheData: PChar;

begin

  TheData := DDEClientConv1.RequestData(DDEClientItem1.DDEItem);

  Label1.Caption := StrPas(TheData);

end;


See also

StrPas function


RequestLive property

See also

Applies to

TQuery component

Declaration

property RequestLive: Boolean;

Description

By default, a TQuery always returns a read-only result set. Set RequestLive to True to request a live result set. The BDE will then return a live result set if the SELECT syntax of the query conforms to the syntax requirements for a live result set. If RequestLive is True, but the syntax does not conform to the requirements, the BDE returns a read-only result set (for local SQL) or an error return code (for passthrough SQL). If a query returns a live result set, Delphi will set the CanModify property to True.

RequestLive	CanModify	Type of result set

False	False	Read-only result set

True--SELECT syntax meets requirements	True	Live result set

True--SELECT syntax does not meet requirements	False	Read-only result set


See also

Local property


Required property

Applies to

TFieldDef object; TBCDField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TIntegerField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

Required for Field Components

Required for TFieldDef Objects


Required property

Applies to

TBCDField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TIntegerField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property Required: Boolean;

Description

Specifies whether a non-nil value for a field is required. The default value is False, meaning a field does not require a value. If a field is created with the Fields Editor, then this property is set based on the underlying table. Set Required to True for fields that must get values (for example, a password or part number), and write an OnValidate event handler for the field. Before a record is posted, exceptions are raised for any required fields that have nil values.


Required property

See also	Example

Applies to

TFieldDef object

Declaration

property Required: Boolean;

Description

Run-time and read-only. Reports whether a value for a physical field in an underlying table is required.


Example

{ Is field required? }

if FieldDef1.Required) then

  MessageDlg(Name 'is a required field' , mtInformation, [mbOK], 0);


See also

TField component


Add method for image list objects
ResourceLoad method

See also

Applies to

TImageList component

Declaration

function ResourceLoad(ResType: TResType; Name: string; MaskColor: TColor): Boolean;

Description

The ResourceLoad method loads a resource of type TResType into the ImageList. The MaskColor is used to create the mask for the resulting image.


See also

FileLoad method, GetResource method, AddMasked method, AddIcon method, AddImages method


Restore method

See also	Example

Applies to

TApplication component

Declaration

procedure Restore;

Description

The Restore method returns your application to its previous size before it was maximized or minimized.

Don't confuse the Restore method with restoring a form or window to its original size. To minimize, maximize, and restore a window or form, you change the value of the WindowState property.


Example

This example uses a timer on a form. When the application runs and the user minimizes the application, the application returns to its normal size when an OnTimer event occurs:

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  Application.Restore;

end;


See also

BorderIcons property

BorderStyle property

Minimize method


RestoreDefaults method

Applies to

TColumn, TColumnTitle, TDBGridColumns objects

Description

RestoreDefaults Method for Columns

RestoreDefaults Method for Column Titles

RestoreDefaults Method for DBGrid Columns


RestoreDefaults method for column objects
RestoreDefaults method

See also

Applies to

TColumn object

Declaration

procedure RestoreDefaults;

Description

Removes all changes made to the properties of the column object, which revert to their default values.


See also

DefaultAlignment method

DefaultColor method

DefaultFont method

DefaultReadOnly method

DefaultWidth method


RestoreDefaults method

See also

Applies to

TColumnTitle object

Declaration

procedure RestoreDefaults;

Description

Removes any changes made to the Alignment, Caption, Color, or Font properties. The default values (see DefaultAlignment, DefaultCaption, DefaultColor, and DefaultFont) will be used instead.


See also

DefaultAlignment method

DefaultCaption method

DefaultColor method

DefaultFont method


RestoreDefaults method

Applies to

TDBGridColumns object

Declaration

procedure RestoreDefaults;

Description

Removes all changes made to the properties of the column objects owned by this collection, by calling the column objects' RestoreDefaults method.


RestoreTopMosts method

Example

Applies to

TApplication component

Declaration

procedure RestoreTopMosts;

Description

The RestoreTopMosts method restores forms that were originally designated as topmost forms (FormStyle is fsStayOnTop) and then temporarily changed to be non-topmost forms with the NormalizeTopMosts method call. After a call to RestoreTopMosts, the topmost forms move on top of other forms again.


Example

The following code normalizes topmost forms before calling the MessageBox function in the WinProcs unit. After the message box is closed, the topmost forms are restored.

begin

  Application.NormalizeTopMosts;

  MessageBox(Form1.Handle, 'This should be on top.', 'Message Box', MB_OK);

  Application.RestoreTopMosts;

end;


RevertRecord method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure RevertRecord;

Description

RevertRecord discards any changes you posted to the current record when cached updates are enabled. Use this method to discard changes from a record before you call ApplyUpdates. Use the UpdateRecordTypes property to be able to revert the deletion of a record.


See also

ApplyUpdates method

CachedUpdates property

CancelUpdates method

UpdateStatus method

UpdateRecordTypes property


Resume method

Applies to

TMediaPlayer component, TThread object

Description

Resume method for Media Players

Resume method for Thread objects


Resume method for TThread objects
Resume method

See also

Applies to

TThread object

Declaration

procedure Resume;

Description

The Resume method resumes execution of a suspended thread. Calls to Resume can be nested; you must call Resume as many times as you called Suspend before the thread will actually be resumed.


See also

Suspend method


Resume method for Media Players
Resume method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Resume;

Description

The Resume method resumes playing or recording the currently paused multimedia device. Resume is called when the Pause button on the media player control is clicked at run time, when the device is paused.

Upon completion, Resume stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Resume method has completed. The Notify property determines whether Resume generates an OnNotify event.


Example

The following code resumes the playing or recording of MediaPlayer1.

MediaPlayer1.Resume;


See also

Pause method

PauseOnly method


Rewind method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Rewind;

Description

The Rewind method sets the current position to the beginning of the medium, which is stored in the Start property.

Upon completion, Rewind stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Rewind method has completed. The Notify property determines whether Rewind generates an OnNotify event.


Example

This example uses a media player and a button on a form. When the user clicks the button, the WAV audio media rewinds and begins playing. To run this example successfully, you must have installed a WAV audio device correctly.

procedure TForm1.FormClick(Sender: TObject);

begin

  MediaPlayer1.DeviceType := dtWaveAudio;

  FileName := 'CHIMES.WAV';

  Button1.Caption := 'Rewind and Play';

  Button1.Width := 130;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  MediaPlayer1.Rewind;

  MediaPlayer1.Play;

end;


See also

AutoRewind property

Back method


Right property

See also

Applies to

THeaderSection object

Declaration

property Right: Interger;

Description

Run-time and read-only. The Right property specifies the position of the left border of the header section in pixels in the parent form. The Left value is essentially the Left property plus the Width of the header section.


See also

Left property


RightIndent property

See also

Applies to

TParaAttributes object

Declaration

property RightIndent: Longint;

Description

The RightIndent property contains the size in pixels of the right indentation relative to the right margin in the currently selected paragraph in a TRichEdit control.


See also

FirstIndent property

LeftIndent property

Paragraph property


Rollback method

See also	Example

Applies to

TDataBase component

Declaration

procedure Rollback;

Description

The Rollback method undoes any modifications made within the current transaction, those changes made since the last call to StartTransaction. If a transaction is not active when this method is called, an exception is raised.


Example

with Database1 do

  begin

    StartTransaction;

  { Update one or more records in tables linked to Database1 }

...

    Rollback;

  end;


See also

Commit method

TransIsolation property

InTransaction property


RoundRect method

See also	Example

Applies to

TCanvas object

Declaration

procedure RoundRect(X1, Y1, X2, Y2, X3, Y3: Integer);

Description

The RoundRect method draws a rectangle on a canvas with the upper left corner at (X1, Y1) and the lower right corner at (X2, Y2), much as the Rectangle method does. However, RoundRect draws the corners as quarters of an ellipse with the width of X3 and a height of Y3.


Example

This example draws many rectangles of various sizes and colors on a form maximized to fill the entire screen:

var

  X, Y: Integer;

procedure TForm1.FormActivate(Sender: TObject);

begin

  WindowState := wsMaximized;

  Canvas.Pen.Width := 5;

  Canvas.Pen.Style := psDot;

  Timer1.Interval := 50;

  Randomize;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  X := X + 4;

  Y := Y + 4;

  Canvas.Pen.Color := Random(65535);

  Canvas.RoundRect(X, Y, X + Random(400), Y + Random(400), 10, 10);

  if X > 700 then

    Timer1.Enabled := False;

end;


See also

Ellipse method

Rectangle method


Row property

See also	Example

Applies to

TDrawGrid, TOutline, TStringGrid components

Declaration

property Row: Longint;

Description

Run-time only. The value of the Row property indicates which row of the control has focus. For outlines, you can use the Row property to determine which item is selected at run time. For the grid components, you can use Row along with the Col property to determine which cell is selected.


Example

This examples uses a string grid with a label above it on a form. When the user clicks a cell in the grid, the location of the cursor is displayed in the caption of the label.

procedure TForm1.StringGrid1Click(Sender: TObject);

begin

  Label1.Caption := 'The cursor is in column ' + IntToStr(StringGrid1.Col + 1)

     +  ', row ' + IntToStr(StringGrid1.Row + 1);

end;


See also

DefaultRowHeight property

RowCount property

RowHeights property


RowCount property

Applies to

TDBCtrlGrid, TDBLookupListBox, TDrawGrid, TStringGrid components

Description

RowCount Property for Grid Components

RowCount Property for TDBCtrl grids

RowCount Property for Database Lookup List Boxes


RowCount property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property RowCount: Longint;

Description

The value of the RowCount property determines the number of rows that appear in the grid.


Example

This example uses a string grid and a button. When the user clicks the button, the number of columns and rows change:

procedure TForm1.Button1Click(Sender: TObject);

begin

  StringGrid1.ColCount := 7;

  StringGrid1.RowCount := 11;

end;


See also

ColCount property

Row property

RowHeights property


RowCount property

Applies to

TDBCtrlGrid component

Declaration

property RowCount: Integer;

Description

Represents the number of rows of panels displayed in the grid. When you set the RowCount property, the grid resizes itself to fit the new number of rows; PanelHeight doesn't change.


RowCount property

Applies to

TDBLookupListBox component

Declaration

property RowCount: Integer;

Description

The RowCount property determines how many rows are visible in the list box. If you set this property, the list box is resized to match the specified number or rows. Likewise, if you resize the list box (such as by changing its Height property), the RowCount property is adjusted to match the new height.


RowHeights property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property RowHeights[Index: Longint]: Integer;

Description

Run-time only. The RowHeights property determines the height in pixels of all the cells within the row referenced by the Index parameter.

By default, all the rows are the same height, the value found in the DefaultRowHeight property. To change the height of all rows within a grid, change the DefaultRowHeight property value.

To change the height of one row without affecting any others, change the RowHeights property. Specify the row you want to change as the value of the Index parameter. Remember, the first row always has an Index value of 0.


Example

This example uses a string grid and a button. When the user clicks the button, the number of columns and rows change, and the first column and row in the grid are sized differently from the rest of the columns and rows:

procedure TForm1.Button1Click(Sender: TObject);

begin

with StringGrid1 do

  begin

    ColCount := 7;

    RowCount := 11;

    RowHeights[0] := 35;

    ColWidths[0] := 90;

  end;

end;


See also

ColWidths property

DefaultColWidth property

Row property


Rows property

See also	Example

Applies to

TStringGrid component

Declaration

property Rows[Index: Integer]: TStrings;

Description

Run-time only. The Rows property is an array of the strings and their associated objects in a row. The number of strings and associated objects is always the value of the RowCount property, the number of rows in the grid. Use the Rows property to access the strings and their associated objects within a particular row in the grid. The Index parameter is the number of the row you want to access, with the first row having an Index value of zero.


Example

This example displays a string grid, a list box, and a button on a form. When the application runs, strings are put in the cells of row 1 of the string grid. When the user clicks the button, each string in row 1 appears as an item in the list box.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items := StringGrid1.Rows[1];

  Button1.Enabled := False;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  with StringGrid1 do

  begin

    Cells[1,1] := 'Object';

    Cells[2,1] := 'Pascal';

    Cells[3,1] := 'is';

    Cells[4,1] := 'excellent';

  end;

end;

Note that the first position of the list box is empty, because there is no string in the cell referenced by Cells[0, 1].


See also

Cells property

Cols property

Objects property

TStrings object


Run method

Applies to

TApplication, TReport components

Description

There are two Run methods: one for Delphi applications and one for ReportSmith reports.

Run method for Delphi Applications

Run method for Reports


Run method

See also	Example

Applies to

TApplication object

Declaration

procedure Run;

Description

The Run method executes the application.

When you create a new project, Delphi automatically creates a main program block in the project file that calls the Run method.


Example

The main program block of a Delphi project always looks like this, by default:

begin

  Application.CreateForm(TForm1, Form1);

  Application.Run;

end.


See also

CreateForm method

MainForm property


Run method

See also	Example

Applies to

TReport component

Declaration

procedure Run;

Description

The Run method loads ReportSmith Runtime, runs the report specified as the value of the ReportName property, and prints the report.


Example

The following code allows the user to specify the report with the Open dialog box and then runs the report.

if OpenDialog1.Execute then

begin

  Report1.ReportName := OpenDialog1.FileName;

  Report1.Run;

end;


See also

Preview property

Print method

ReportName property


RunMacro method

See also	Example

Applies to

TReport component

Declaration

function RunMacro(Macro: PChar): Boolean;

Description

The RunMacro method runs the ReportBasic macro specified as the value of the Macro parameter.

The RunMacro method sends a DDE message to ReportSmith Runtime to run the specified macro and looks for a DDE message from ReportSmith Runtime in return. If RunMacro returns True, the message to run the macro was sent successfully to ReportSmith Runtime. If it returns False, ReportSmith Runtime could not receive the DDE message at the current time.

For information about ReportBasic macros, refer to your ReportSmith documentation.


Example

The following code runs the macro "SELALL.MAC".

Report1.RunMacro('SELALL.MAC');


See also

Run method


Save method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Save;

Description

The Save method saves the currently loaded medium to the file specified in the FileName property. Save is ignored for devices that don't use media stored in files (videodiscs, for example).

Upon completion, Save stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Save method has completed. The Notify property determines whether Save generates an OnNotify event.


Example

The following code saves to a file when the SaveButton is clicked, assuming that FileName has been specified.

procedure TForm1.SaveButtonClick(Sender: TObject);

begin

  MediaPlayer1.Save;

end;


See also

Close method

Open method


SaveConfigFile method

See also

Applies to

TSession component

Declaration

procedure SaveConfigFile;

Description

The SaveConfigFile method writes the Borland Database Engine configuration file to disk, saving all persistent changes you've made. Aliases created with the ConfigMode property set to cmSession cannot be saved to the BDE configuration file.


See also

Session variable

ConfigMode property

AddAlias method

AddStandardAlias method

DeleteAlias method


Add method for image list objects
SaveToClipboardFormat method

Applies to

TPicture object

Declaration

procedure SaveToClipboardFormat(var AFormat: Word; var AData: THandle; var APalette: HPALETTE);

Description

The SaveToClipboardFormat method allocates a global handle and writes the picture in its native Clipboard format (CF_BITMAP for bitmaps, CF_METAFILE for metafiles, etc.).  Formats will contain the formats written. Returns the number of Clipboard items written to the array pointed to by AFormat and AData or would be written if either AFormat or AData are nil.


SaveToFile method

Applies to

TBitmap, TBlobField, TGraphic, TGraphicField, TIcon, TMemoField, TMetafile, TPicture, TStringList, TStrings objects; TOutline, TTreeView, TOleContainer components

Description

SaveToFile method for OleConainers

SaveToFile method for all other objects


SaveToFile method

See also

Applies to

TOleContainer component

Declaration

procedure SaveToFile(const FileName: string);

Description

Saves the OLE object to the specified file. An OLE object must already be loaded in the container before calling SaveToFile. If CopyOnSave is True, SaveToFile writes a temporary OLE object storage, compressing redundant data and saving space. If OldStreamFormat is True, SaveToFile writes a file compatible with Delphi 1.0's TOLEContainer component; if OldStreamFormat is False, SaveToFile writes a file compatible with Delphi 2.0's TOleContainer component.


See also

CopyOnSave property

OldStreamFormat property


SaveToFile method

See also	Example

Applies to

TBitmap, TBlobField, TGraphic, TGraphicField, TIcon, TMemoField, TMetafile, TPicture, TStringList, TStrings objects; TOutline, TTreeView components

Declaration

procedure SaveToFile(const FileName: string);

Description

The SaveToFile method saves an object to the file specified in FileName. The graphic objects save a graphic to the file, the outline, tree view and string objects save text to the file, and the field components save the contents of the field to the file.


Example

This example uses a memo control and two buttons on a form. When the application runs, the code attempts to load text in a text file named SOMETEXT.TXT into the memo control. If the attempt fails, a message box appear, prompting the user to enter text in the memo.

The user must choose one of the two buttons, as there is no System menu (also called a Control menu) on the form to close the form. If the user chooses the button labeled Save, the contents of the memo control is saved in a file named SOMETEXT.TXT, and the form closes. If the user chooses the button labeled Discard, the lines in the memo control are not saved, and the form closes.

procedure TForm1.FormCreate(Sender: TObject);

begin

  BorderIcons := [];

  Button1.Caption := 'Save';

  Button2.Caption := 'Discard';

  try

    Memo1.Lines.LoadFromFile('SOMETEXT.TXT');

  except

    Memo1.Lines.Clear;

    MessageDlg('When form appears, type in the memo control',

      mtInformation, [mbOk], 0);

  end;

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Memo1.Lines.SaveToFile('SOMETEXT.TXT');

  Close;

end;

procedure TForm1.Button2Click(Sender: TObject);

begin

  Close;

end;

This example stores a blob field into a file:

{ Store a blob field into a temporary file }

BlobField1.SaveToFile('c:\windows\temp\myblob.blb');


See also

LoadFromFile method

LoadFromStream method

SaveToStream method


SaveToStream method

Applies to

TBlobField, TGraphicField, TMemoField, TOutLine, TOleContainer components; TStrings, TStringList, TMetaFile, TIcon, TBitMap objects

Description

SaveToFile method for OleConainers

SaveToFile method for all other objects


SaveToStream method

See also	Example

Applies to

TBlobField, TGraphicField, TMemoField, TOutLine components; TStrings, TStringList, TMetaFile, TIcon, TBitMap objects

Declaration

procedure SaveToStream(Stream: TStream);

Description

The SaveToStream method writes a stream with the name passed in Stream with the contents of the object.


Example

This example stores a blob field into a stream:

BlobField1.SaveToStream(Stream1);


See also

LoadFromFile method

LoadFromStream method

SaveToFile method


SaveToStream method

See also

Applies to

TOleContainer component

Declaration

procedure SaveToStream(Stream: TStream);

Description

Saves the OLE object to the specified stream. An OLE object must already be loaded in the container before calling SaveToStream. If CopyOnSave is True, SaveToStream writes a temporary OLE object storage, compressing redundant data and saving space. If OldStreamFormat is True, SaveToStream writes a stream compatible with Delphi 1.0's TOLEContainer component; if OldStreamFormat is False, SaveToStream writes a stream compatible with Delphi 2.0's TOleContainer component.


See also

CopyOnSave property

OldStreamFormat property


ScaleBy method

See also	Example

Applies to

All controls

Declaration

procedure ScaleBy(M, D: Integer);

Description

The ScaleBy method scales a control to a percentage of its former size. The M parameter is the multiplier and the D parameter is the divisor. For example, if you want a control to be 75% of its original size, specify the value of M as 75, and the value of D as 100 (75/100). You could also obtain the same results by specifying the value of M as 3, and the value of D as 4 (3/4). Both fractions are equal and result in the control being scaled by the same amount, 75%.

If you want the control to be 33% larger than its previous size, specify the value of M as 133, and the value of D as 100 (133/100). You can also obtain the same results by specifying the value of M as 4, and the value of D as 3 (4/3), as the fraction 133/100 is approximately equal to 4/3.


Example

This example makes your form 50 percent larger:

procedure TForm1.Button1Click(Sender: TObject);

begin

  ScaleBy(150, 100);

end;


See also

Scaled property


Scaled property

See also

Applies to

TForm component

Declaration

property Scaled: Boolean;

Description

The Scaled property determines if the form is resized to the value in the PixelsPerInch property. If Scaled is True and the value of PixelsPerInch differs from it current system settings, the form is scaled to a new size. If Scaled is False, no scaling occurs, regardless of the PixelsPerInch value. The default value is True.


See also

PixelsPerInch property

ScaleBy method


Screen variable

Example

Unit

Forms

Declaration

Screen: TScreen;

Description

The Screen variable is a TScreen component that normally represents your screen device. By default, your application creates a screen component based on information from Windows about the current screen device and assigns it to Screen.


Example

The following code sets the width of a form called Form1 to half the width of the screen:

Form1.Width := Screen.Width div 2;


ScreenToClient method

See also	Example

Applies to

All controls

Declaration

function ScreenToClient(Point: TPoint): TPoint;

Description

The ScreenToClient method is used to determine the control coordinates in pixels of a point on the screen. ScreenToClient returns X and Y coordinates in a record of type TPoint.


Example

The following code converts the origin of the screen (0, 0) to the client coordinates of Button2.

var

  ScreenOrgin, ClientPoint: TPoint;

begin

  ScreenOrgin.X := 0;

  ScreenOrgin.Y := 0;

  ClientPoint := Button2.ScreenToClient(ScreenOrgin);

end;


See also

ClientToScreen method


Scroll method

See also

Applies to

TListView component

Declaration

procedure Scroll(DX, DY: Integer);

Description

Run-time only. The Scroll method scrolls the content of a list view control. DX and DY specify the amount of horizontal and vertical scrolling respectively.


See also

MakeVisible method

VisibleRowCount property


ScrollBars property

See also	Example

Applies to

TDBMemo, TDrawGrid, TMemo, TRichEdit, TStringGrid components

Declaration

property ScrollBars: TScrollStyle;

Description

The ScrollBars property controls whether a memo control, a rich edit control, or a grid control has any scroll bars. You can set ScrollBars to any of the following values:

Value	Meaning

ssNone	No scroll bar

ssHorizontal	Puts a scroll bar on the right edge

ssVertical	Puts a scroll bar on the bottom edge

ssBoth	Puts a scroll bar on both the right and bottom edges

By default, grids have both vertical and horizontal scroll bars, while memo controls have none.


Example

The following example adds a scroll bar to the bottom of memo control Memo1:

Memo1.ScrollBars := scHorizontal;


See also

HorzScrollBar property

VertScrollBar property


ScrollBy method

See also	Example

Applies to

All controls; TForm component

Declaration

procedure ScrollBy(DeltaX, DeltaY: Integer);

Description

The ScrollBy method scrolls the contents of a form or windowed control. You will seldom need to call the ScrollBy method unless you want to write your own scrolling logic rather than use a scroll bar.

The DeltaX parameter is the change in pixels along the X axis. A positive DeltaX value scrolls the contents to the right; a negative value scrolls the contents to the left. The DeltaY parameter is the change in pixels along the Y axis. A positive DeltaY value scrolls the contents down; a negative value scrolls the contents up.


Example

This example uses a timer and several controls of your choosing on a form. When the application runs, the controls on the form appear to slide down and off to the right. This is because the contents of the form are scrolling both down and to the right by one pixel each time a timer event occurs:

procedure TForm1.FormActivate(Sender: TObject);

begin

  Timer1.Interval := 1;

end;

procedure TForm1.Timer1Timer(Sender: TObject);

begin

  ScrollBy(1,1);

end;


See also

HorzScrollBar property

ScrollBars property

ScrollInView method

TScrollBox component

VertScrollBar property


ScrollInView method

See also	Example

Applies to

TForm, TScrollBox components

Declaration

procedure ScrollInView(AControl: TControl);

Description

The ScrollInView method scrolls the form or scroll box so that of the control specified as the AControl parameter is in view.


Example

This example uses two buttons on a form. Place each button on opposite sides of the form. When the user runs the application and resizes the form so that it is smaller, clicking either of the buttons scrolls the form so that the other button is visible:

procedure TForm1.Button1Click(Sender: TObject);

begin

  ScrollInView(Button2);

end;

procedure TForm1.Button2Click(Sender: TObject);

begin

  ScrollInView(Button1);

end;


See also

HorzScrollBar property

VertScrollBar property


ScrollPos property

See also	Example

Applies to

TControlScrollBar component

Declaration

property ScrollPos: Integer

Description

Run-time and read-only. The value of the ScrollPos property is the current Position value of a horizontal or vertical scroll bar on a form or scroll box.


Example

This example uses a label on a form. When the application runs, resize the form so a horizontal scroll bar appears. You can use the scroll bar to scroll the form. Each time you click the label, it reports the current position of the scroll bar:

procedure TForm1.Label1Click(Sender: TObject);

begin

  Label1.Caption := 'Scroll bar position is ' + IntToStr(HorzScrollBar.ScrollPos);

end;


See also

HorzScrollBar property

Position property

VertScrollBar property


Sections property

Applies to

THeader, THeaderControl components

Description

Sections property for THeader components

Sections property for THeaderControl components


Sections property

See also	Example

Applies to

THeader component

Declaration

property Sections: TStrings

Description

The Sections property is a list of strings that contain the text for the sections of a header. The number of lines of the string list determines the number of sections of the header. If the string list is empty, the header will have one blank section. If this string list contains one or more lines, the text of each line will be in its own section. The first line will be in the leftmost section, the second line will be in the next section to the right, and so on.


Example

The following code adds 'Schaeferle' to the header sections list.

Header1.Sections.Add('Schaeferle');


See also

SectionWidth property


Sections property for header controls
Sections property

See also

Applies to

THeaderControl component

Declaration

property Sections: THeaderSection;

Description

The Sections property is used to insert a new item, called a section, into a header control. Sections in a THeaderControl are THeaderSection objects. When setting this property at design-time a HeaderControl Sections Editor dialog appears. Use this dialog box to Add, delete, and edit the sections.


See also

Add property


SectionWidth property

See also	Example

Applies to

THeader component

Declaration

property SectionWidth[X: Integer]: Integer;

Description

Run-time only. The SectionWidth array property determines the width in pixels of the sections of a header. X is an index into the sections, from 0 to the number of sections - 1. For example, the index of the first section is 0, the second section is 1, and so on.


Example

The following code doubles the width of all the sections of a header.

var

  I: Integer;

begin

  with Header1 do

    for I := Sections.Count-1 do

    SectionWidth[I] := SectionWidth[I] * 2;

end;


See also

Sections property


Seek method

See also	Example

Applies to

TBlobStream object

Declaration

function Seek(Offset: Longint; Origin: Word): Longint;

Description

The Seek function resets the current position within the TBlobStream. If Origin is soFromBeginning, the new position is Offset (seek absolute). If Origin is soFromCurrent, the new position is Position + Offset (seek relative). If Origin is soFromEnd, the new position is Size + Offset (seek absolute from end of data). Seek returns the new position, relative to the beginning of the BLOB stream.

Note:	When Origin is 0, Offset must be >= 0. When Origin is 2, Offset must be <= 0.


Example

The following example deletes the stream from position 60 within the blob stream to the end.

procedure TForm1.Button1Click(Sender: TObject);

var

  Stream1: TBlobStream;

begin

  Table1.Edit;

  Stream1 := TBlobStream.create(Table1Notes, bmReadWrite);

  try

    Stream1.Seek(60, 0); { Move to byte #20}

    Stream1.Truncate;    { Delete from current position (60) to end of stream.}

  finally

    Stream1.Free;

  end;

  Table1.Post;

end;


See also

TBlobField component

TBytesField component

TVarBytesField component


SelAttributes property

See also	Example

Applies to

TRichEdit component

Declaration

property SelAttributes: TTextAttributes;

Description

Run-time only. The SelAttributes property contains the description of the attributes of the selected text.  SelAttributes and DefAttributes are both objects of type TTextAttributes. SelAttributes can also be used to set the current selection.


Example

The following example sets the shortcut buttons on the format bar of a form that contains a rich edit to reflect the formatting of the selected text.

with RichEdit1.Paragraph do begin

  BoldButton.Down := fsBold in RichEdit1.SelAttributes.Style;

  ItalicButton.Down := fsItalic in RichEdit1.SelAttributes.Style;

  UnderlineButton.Down := fsUnderline in RichEdit1.SelAttributes.Style;

  BulletsButton.Down := Boolean(Numbering);

  FontSize.Text := IntToStr(RichEdit1.SelAttributes.Size);

  FontName.Text := RichEdit1.SelAttributes.Name;

  case Ord(Alignment) of

    0: LeftAlign.Down := True;

    1: RightAlign.Down := True;

    2: CenterAlign.Down := True;

  end;

end;


See also

ConsistentAttributes property

DefAttributes property

OnSelectionChange event

Paragraph property

PlainText property


SelCount property

Applies to

TDBListBox, TDirectoryListBox, TFileListBox, TListBox, TListView components

Description

SelCount property for list boxes

SelCount property for list views


SelCount property for list views
SelCount property

See also	Example

Applies to

TDBListBox, TDirectoryListBox, TFileListBox, TListBox components

Declaration

property SelCount: Integer;

Description

Run-time and read-only. The SelCount property reports the number of items that are selected in a list box when the value of the MultiSelect property is True. When MultiSelect property is False, only one item can be selected. If no items are selected, the value of SelCount is 0.


Example

This example uses a list box, a label, and a button on a form. Enter several strings in the list box as the value of the Items property. When the user selects items in the list box and clicks the button, the number of items selected in the list box is displayed in the caption of the label:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := IntToStr(ListBox1.SelCount) + ' items are selected';

end;


See also

ExtendedSelect property

MultiSelect property

Selected property


SelCount property for list views
SelCount property

See also

Applies to

TListView component

Declaration

property SelCount: Integer;

Description

Run-time and read-only. The SelCount property returns the number of selected items in a list view control.


See also

Selected property

Items property

MultiSelect property


SelectAll method

See also	Example

Applies to

TComboBox, TDBComboBox, TDBEdit, TDBMemo, TDriveComboBox, TEdit, TFilterComboBox, TMaskEdit, TMemo components

Declaration

procedure SelectAll;

Description

The SelectAll method selects the entire block of text in the control. If you want to select only part of the text, use the SelStart and SelLength properties.


Example

The following code selects all the text in Memo1.

Memo1.SelectAll;


 See also

SelLength property

SelStart property

SelText property

Text property


SelectDirectory function

See also	Example

Unit

FileCtrl

Declaration

function SelectDirectory(var Directory: string; Options: TSelectDirOpts; HelpCtx: Longint): Boolean;

Description

The SelectDirectory function lets the user enter a directory name into the application using a Select Directory dialog box. Calling the SelectDirectory function displays the Select Directory dialog box. The directory passed to the function with the Directory parameter is the currently selected directory when the dialog box appears. The name of the directory the user selects becomes the value of Directory when the function returns.

The Options parameter is a set of values. These are the possible values of the Options set:

Value	Meaning

[ ], the empty set	The user can select a directory that currently exists only. The user cannot specify a directory that does not exist as there is no edit box to type in a new directory name.

sdAllowCreate	An edit box appears in the dialog box so that the user can type in the name of a directory that does not exist. This option does not create a directory, but the application can access the Directory parameter to create the directory selected if desired.

sdPerformCreate	Used only when the Options set contains sdAllowCreate. If the user enters a directory name that does not exist, the function creates the directory.

sdPrompt	Used when the Options set contains sdAllowCreate. Displays a message box the informs the user the entered directory does not exist and asks the user if the directory should be created. If the user chooses OK, the directory is created only if the Options set contains the sdPerformCreate value. If only sdAllowCreate is True, the directory is not actually created, but the application can create it if desired.

The function returns True if the user selected a directory and chose OK, and False if the user chose Cancel or closed the dialog box without selecting a directory.

The HelpCtx parameter is the help context ID number.


Example

This example uses a button on a form. When the user clicks the button, a Select Directory dialog box appears. The current directory displayed in the dialog box is       C:\LINDA. The user can select a directory from the directory list, or enter a new directory in the edit box. If the user enters a new directory, a message box asks the user if the directory should be created. If the user chooses Yes, the directory is created. If the user chooses No, the message box goes away and the user can use the dialog box again to select a directory. The name of the directory the user selects appears as the caption of the label:

uses FileCtrl;

procedure TForm1.Button1Click(Sender: TObject);

var

  Dir: string;

begin

  Dir := 'C:\LINDA';

  if SelectDirectory(Dir, [sdAllowCreate, sdPerformCreate, sdPrompt]) then

    Label1.Caption := Dir;

end;


See also

DirectoryExists function

ForceDirectories procedure


Selected property

Applies to

TDBListBox, TDirectoryListBox, TFileListBox, TListBox, TListView components; TTreeNode, TListItem objects

Description

Selected property for list boxes

Selected property for list views

Selected property for tree nodes and list items

Selected property for tree views


Selected property

See also	Example

Applies to

TDBListBox, TDirectoryListBox, TFileListBox components

Declaration

property Selected[X: Integer]: Boolean;

Description

The Selected property determines whether a particular item is selected in the list box. The X parameter is the item referenced by its position in the list box, with the first item having an X value of 0. If the specified item is selected in the list box, the value of the Selected property is True. If the specified item is not selected, Selected is False.

If you want the user to be able to select more than one item in the list box, use the MultiSelect property


Example

This example uses a list box on a form. When the form is first created, 3 items are added to the list box. When the user selects an item in the list box, the list box color changes to reflect the item selected:

procedure TForm1.FormCreate(Sender: TObject);

var

  I: Integer;

begin

  ListBox1.Items.Add('Blue');

  ListBox1.Items.Add('Yellow');

  ListBox1.Items.Add('Red');

end;

procedure TForm1.ListBox1Click(Sender: TObject);

begin

  if ListBox1.Selected[0] then

    ListBox1.Color := clBlue;

  if ListBox1.Selected[1] then

    ListBox1.Color := clYellow;

  if ListBox1.Selected[2] then

    ListBox1.Color := clRed;

end;


See also

ExtendedSelect property

MultiSelect property

SelCount property


Selected property for tree nodes
Selected property

See also

Applies to

TTreeNode, TListItem objects

Declaration

property Selected: Boolean;

Description

Run-time only. The Selected property determines whether the item is selected. Setting Selected to True selects the item. The appearance of a selected item depends on whether it has the focus and on whether the system colors are used for selection. If an item becomes selected, the tree view's or list view's OnChanging and OnChanged events are triggered.


See also

OnChange event

OnChanging event

SelectedIndex property

OnGetSelectedIndex event

Focused property


Selected property for list views
Selected property

See also	Example

Applies to

TListView component

Declaration

property Selected: TListItem;

Description

Run-time only. The Selected property for a list view returns the first selected item in the list view. If an item becomes selected, the list view's OnChanging and OnChange events will be triggered.


Example

The following code deletes the selected item in the list view.

with ListView1 do

   if Selected <> nil then Selected.Delete;


See also

SelCount property

Focused property

MultiSelect property


Selected property for tree views
Selected property

See also	Example

Applies to

TTreeView component

Declaration

property Selected: TTreeNode;

Description

Run-time only. The Selected property for tree views returns the item in the tree view that is selected. If an item becomes selected, the tree view's OnChanging and OnChanged events will be triggered. Also, if the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the tree views OnExpanded and OnExpanding events are triggered.


Example

The following code deletes the selected item in the tree view.

TreeView1.Selected.Delete;


See also

OnChange event

OnChanging event

SelectedIndex property

OnGetSelectedIndex event

Focused property


SelectedColor property

See also	Example

Applies to

TTabSet component

Declaration

property SelectedColor: TColor;

Description

The SelectedColor property determines the color of the selected tab in the tab set control. To view a list of available color values, see the Color property.


Example

This code changes the color of selected tabs:

TabSet11.SelectedColor := clPurple;


See also

UnselectedColor property


SelectedField property

See also	Example

Applies to

TDBGrid, TDBLookupList components

Declaration

property SelectedField: TField;

Description

Run-time only. The value of the SelectedField property indicates which field is selected in the data grid. Can be nil.


Example

The following code displays the name of the selected field in a label if the selected field is 'CustNo'.

if DBGrid1.SelectedField.FieldName = 'CustNo' then

  Label1.Caption := DBGrid1.SelectedField.FieldName;


See also

SelectedIndex property


SelectedIndex property

Applies to

TDBGrid, TDBLookupList components; TTreeNode object

Description

SelectedIndex property for grids and lookup lists

Selected property for tree nodes


SelectedIndex property

See also	Example

Applies to

TDBGrid, TDBLookupList components

Declaration

property SelectedIndex: Integer;

Description

Run-time only. The value of the SelectedIndex property returns the index value of the currently selected field in the displayed dataset. A value of 0 indicates the first field of the displayed dataset, 1 is the second field, and so on. Returns -1 if currently selected column has no field or if dataset is not open.

SelectedIndex can be used as an index to Fields property array to access a field in the dataset.


Example

The following code makes all the fields up to the selected field of the dataset of DBGrid1 read-only. I is an integer variable.

for I := 0 to DBGrid1.SelectedIndex do

  DBGrid1.Fields[I].ReadOnly := True;


See also

SelectedField property


SelectedIndex property for tree nodes
SelectedIndex property

See also

Applies to

TTreeNode object

Declaration

property SelectedIndex: Integer;

Description

Run-time only. The SelectedIndex property for a tree node contains the index in the image list (TImageList) to be used when the item is selected.


See also

Images property

OnGetSelectedIndex event

ImageIndex property

StateImages property

StateIndex property

OnGetImageIndex event


SelectedItem property

See also	Example

Applies to

TOutline component

Declaration

property SelectedItem: Longint;

Description

Run-time only. The SelectedItem property determines which item of the outline currently has focus. SelectedItem contains the Index value of the selected item. If no item is selected, SelectedItem contains 0.


Example

The following code expands the selected item of Outline1.

Outline1.Items[Outline1.SelectedItem].FullExpand;


See also

Items property


Selection property

Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property Selection: TGridRect;

Description

The Selection property contains the column and row coordinates of the cell or cells selected in the grid.


Example

The following code selects the rectangle containing rows 1 and 2, and columns 3 and 4.

StringGrid1.Selection := Rect(3,1,2,4);


SelectNext method

See also	Example

Applies to

TTabSet component

Declaration

procedure SelectNext(Direction: Boolean);

Description

The SelectNext method selects the next tab in a tab set control, and scrolls that tab set control if necessary to bring the selected tab into view.

The value of the Direction parameters determines if the tab to the left or right is selected. If Direction is True, the tab to the right is selected. If Direction is False, the tab to the left is selected. When the last tab in either direction is selected, calling SelectNext using the same direction wraps around to the beginning of the tab order. For example, if your application has three tabs, First, Second, and Third, and Third is the current tab, calling SelectNext(True) selects First. Likewise, if First is the current tab, SelectNext(False) selects Third.

When SelectNext is called, the OnClick event of the tab set occurs, followed by the OnChange event, just as if the user had clicked on a new tab.


Example

The following code selects the next tab to the left of the current tab (or selects the last tab if the first tab is currently selected).

TabSet1.SelectNext(False);


See also

TabIndex property


SelectNextPage method

See also

Applies to

TPageControl component

Declaration

procedure SelectNextPage(GoForward: Boolean);

Description

The SelectNextPage method allows the user to select the next page previous to or after the ActivePage in the TPageControl. It the GoForward parameter is True, FindNextPage will find the next page in the page control after ActivePage; if GoForward is False, FindNextPage will find the page previous to ActivePage. SelectNextPage will only find pages with their TabVisible property set to True.

To select a page at design-time, right-click the TPageControl and choose Previous Page or Next Page.


See also

ActivePage property

FindNextPage method

Pages property

PageCount property


SelEnd property

See also

Applies to

TTrackBar component

Declaration

property SelEnd: Integer;

Description

A track bar can display a selection range specified by the SelStart and SelEnd properties. The SelEnd property indicates the end point of the selection range of a TTrackBar.


See also

Position property

SelStart property

TickStyle property


SelLength property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBEdit, TDBMemo, TDriveComboBox, TEdit, TFilterComboBox, TMaskEdit, TMemo components

Declaration

property SelLength: Integer;

Description

The SelLength property returns the length (in characters) of the control's selected text. By using SelLength along with the SelStart property, you specify which part of the text in the control is selected. You can change the number of selected characters by changing the value of SelLength. When the SelStart value changes, the SelLength value changes accordingly.

The edit box or memo must be the active control when you change the value of SelLength, or nothing appears to happen.


Example

This example uses an edit box and a label on a form. When the user selects text in the edit box, the number of selected characters is reported in the caption of the label:

procedure TForm1.Edit1MouseUp(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Label1.Caption := 'Selected length = ' +

    IntToStr(Edit1.SelLength);

end;


See also

SelStart property

SelText property

Text property


SelStart property

Applies to

TComboBox, TDBComboBox, TDBEdit, TDBMemo, TDriveComboBox, TEdit, TFilterComboBox, TMaskEdit, TMemo, TTrackBar components

Description

SelStart property for edit boxes, memos, and combo boxes

SelStart property for track bars


SelStart property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBEdit, TDBMemo, TDriveComboBox, TEdit, TFilterComboBox, TMaskEdit, TMemo components

Declaration

property SelStart: Integer;

Description

The SelStart property returns the starting position of the selected part of the control's text, with the first character in the text having a value of 0. You can use SelStart along with the SelLength property to select a portion of the text. Specify the character you want the selected text to start with by its position in the text as the value of SelStart.

When the SelStart value changes, the SelLength value changes accordingly.

The edit box or memo must be the active control when you change the value of SelStart, or nothing appears to happen.


Example

This example uses an edit box and a label on a form. When the user selects text in the edit box, the starting position of the selected text is reported in the caption of the label:

procedure TForm1.Edit1MouseUp(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Label1.Caption := 'Selected text starts at character ' +

    IntToStr(Edit1.SelStart + 1);

end;

Note that if all the text in the edit box is selected, the value of the SelStart property is 0, the index value of the first item in the string array. Therefore, this example uses the expression SelStart + 1 to make the result reported more understandable to most people.


See also

SelectAll method

SelLength property

SelText property

Text property


SelStart property for track bars
SelStart property

See also

Applies to

TTrackBar component

Declaration

property SelStart: Integer;

Description

A track bar can display a selection range specified by the SelStart and SelEnd properties. The starting and ending positions of the selection are marked by triangular ticks instead of vertical dashes, and the selection range is filled with the system highlight color. The SelStart property indicates the start point of selection range.


See also

Position property

SelEnd property

TickStyle property


SelText property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBEdit, TDriveComboBox, TEdit, TFilterComboBox, TMaskEdit components

Declaration

property SelText: string;

Description

The SelText property contains the selected part of the control's text. You can use it to determine what the selected text is, or you can change the contents of the selected text by specifying a new string. If no text is currently selected, the SelText string is inserted in the text at the cursor.


Example

This example uses an edit box and a label on a form. When the user selects text in the edit box, the selected text is reported in the caption of the label.

procedure TForm1.Edit1MouseUp(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Label1.Caption := 'Selected string =  ' + Edit1.SelText;

end;


See also

SelLength property

SelStart property

Text property


SendToBack method

See also	Example

Applies to

All controls; TForm component

Declaration

procedure SendToBack;

Description

The SendToBack method puts a windowed component behind all other windowed components within its parent component or form, or it puts a non-windowed component behind all other non-windowed components within its parent component or form. If the component has the input focus when the SendToBack method executes, it loses the input focus.

SendToBack is useful for changing the order of overlapping controls or forms.

The order in which controls stack on top of each order (also called the Z order) depends on whether the controls are windowed or non-windowed. For example, if you put a label and an image on a form so that one is on top of the other, the first one you placed on the form is the one on the bottom. Because both the label and the image are non-windowed controls, they "stack" as you would expect them to. Suppose that the image is on the top. If you call the SendToBack method for the image, the label then appears on top of the image.

The stacking order of windowed controls is the same. For example, if you put a memo on a form, then put a check box on top of it, the memo remains on the bottom. If you call SendToBack for the check box, the memo appears on top.

The stacking order of windowed and non-windowed controls cannot be mingled. For example, if you put a memo, a windowed control, on a form, and then put a label, a non-windowed control, on top of it, the label disappears behind the memo. Windowed controls always "stack" on top of non-windowed controls. In this example, if you call the SendToBack method of the memo, it remains on top of the label.


Example

This example uses two forms. When the user clicks the button on Form2, it moves Form2 behind the other form and is no longer the active form:

procedure TForm2.Button1Click(Sender: TObject);

begin

  SendToBack;

end;

In this example, the parent of the two forms is the application itself.


See also

BringToFront method


ServerConv property

See also	Example

Applies to

TDDEServerItem component

Declaration

property ServerConv: TDdeServerConv;

Description

The ServerConv property specifies the DDE server conversation component to associate with the DDE server item component. The value of ServerConv is the name of the DDE server conversation component that defines the DDE conversation.


Example

The following code sets DDEServerConv1 to be the server conversation for DDEServerItem1.

DDEServerItem1.ServerConv := DDEServerConv1;


See also

Name property


ServiceApplication property

Example

Applies to

TDDEClientConv component

Declaration

property ServiceApplication: string;

Description

The ServiceApplication property specifies the main executable file name (and path, if necessary) of a DDE server application, without the .EXE extension. Typically, this is the same value as the DDEService property. Sometimes, however, DDEService is a value other than the DDE server application's executable file name. In either case, ServiceApplication must be specified for Delphi to run an inactive DDE server to establish a DDE conversation.


Example

The following code sets the service application to 'ReportSmith'.

DDEClientConv1.ServiceApplication := 'ReportSmith';


Session variable

Unit

DB

Declaration

Session: TSession;

Description

The Session variable is responsible for maintaining all of the database components used by your application. It is created automatically as part of your application's initialization and destroyed as part of your application's termination. The Session variable must remain active at all times; it can not be destroyed and recreated.


SessionName property

Applies to

TDatabase, TSession, TTable, TQuery, TStoredProc components

Description

There are several very similar properties names SessionName. Each represents the name of a session.

For database components

For sessions

For tables, queries, and stored procedures


SessionName property

See also

Applies to

TDatabase component

Declaration

property SessionName: string;

Description

The SessionName property is a string that uniquely identifies a session component you want this database to use. The SessionName you supply must match the SessionName of some TSession component you've created (such as by calling TSessionList.OpenSession), or be an empty string (which indicates the default session). The database component automatically opens the session when needed, automatically getting all of the property settings of the session.


See also

Session variable


SessionName property for session components
SessionName property

See also

Applies to

TSession components

Declaration

property SessionName: string;

Description

The SessionName property is a string you assign to uniquely identify a session You refer to a session in other contexts (such as from a TDatabase or TTable component) by the session's SessionName property, so it's best to give meaningful names to your session components.


See also

Session variable


SessionName property for tables, queries, and stored procedures
SessionName property

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property SessionName: string;

Description

The SessionName property is a string that uniquely identifies a session component you want this data set to use. The SessionName you supply must match the SessionName of some TSession component you've created (such as by calling TSessionList.OpenSession) or be an empty string (which indicates the default session). The data set opens the session when needed, automatically getting all of the property settings of the session.


See also

Session variable


Sessions property

Applies to

TSessionList object

Declaration

property Sessions[Index: Integer]: TSession; default;

Description

The Sessions array property returns the TSession component with the given index. If the index is invalid (outside the range of 0..Count - 1), raises an EListError exception with a message describing the out of bounds condition.


Sessions variable

Unit

DB

Declaration

var
  Sessions: TSessionList;

Description

The Sessions variable is a way for you to access TSessionList methods and properties for manipulating sessions. The DB unit automatically creates and destroys Sessions for you; you don't need to do anything but use it.

The Session variable, on the other hand, is responsible for maintaining all of the database components used by your application. It is created automatically as part of your application's initialization and destroyed as part of your application's termination. The Session variable must remain active at all times; it can not be destroyed and recreated.


SetAsHandle method

See also	Example

Applies to

TClipboard object

Declaration

procedure SetAsHandle (Format: Word; Value: THandle);

Description

The SetAsHandle method places the data in the given format as a Windows handle. Once your application gives the handle to the Clipboard, it should not delete the handle Value. Instead, the Clipboard will delete the handle.

For more information, see the Win32 Developer's Reference (WIN32.HLP) for information about the available formats for Format parameter.


Example

The following code gives the handle of bitmap graphic data to the Clipboard.

Clipboard.SetAsHandle(CF_BITMAP, Data);


See also

FormatCount property

Formats property

GetAsHandle method

HasFormat method


SetBounds method

See also	Example

Applies to

All controls

Declaration

procedure Setbounds(ALeft, ATop, AWidth, AHeight: Integer);

Description

The SetBounds method sets the component's boundary properties, Left, Top, Width, and Height, to the values passed in ALeft, ATop, AWidth, and AHeight, respectively.

SetBounds enables you to set more than one of the component's boundary properties at a time. Although you can always set the individual boundaries, using SetBounds enables you to make several changes at once without repainting the control for each change.


Example

The following code doubles the size of a button control when the user clicks it:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.SetBounds(Left, Top, Height * 2, Width * 2);

end;

Note that you could use the following code instead, but each click would result in the button being redrawn twice: once to change the height, and once to change the width:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Height := Button1.Height * 2;

  Button1.Width := Button1.Width * 2;

end;


See also

Height property

Left property

Top property

Width property


SetComponent method

See also	Example

Applies to

TClipboard object

Declaration

procedure SetComponent(Component: TComponent);

Description

The SetComponent method copies a component to the Clipboard. Specify the component you want copied as the value of the Component parameter.


Example

This example uses a button and a group box on a form. When the user clicks the button, the button is copied to the Clipboard and then retrieved from the Clipboard and placed in the new parent of the button, the group box. The name of the original button is changed to an empty string to avoid having two components with the same name at the same time.

implementation

uses Clipbrd;

{$R *.DFM}

procedure TForm1.Button1Click(Sender: TObject);

begin

  Clipboard.SetComponent(Button1);                { copies button to the Clipboard }

  Button1.Name := '';          { prevents having two components with the same name }

  Clipboard.GetComponent(Self, GroupBox1);   { retrieves button from Clipboard and }

end;                                                  { places it in the group box }

initialization

  RegisterClasses([TButton]);                        { registers the TButton class }

end.


See also

AsText property

GetComponent method

Owner property

Parent property


SetData method

Applies to

TParam object; TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Description

SetData for TParam Objects

SetData for Field Components


SetData method

Example

Applies to

TParam object

Declaration

procedure SetData(Buffer: Pointer);

Description

The SetData method copies a new value for the parameter in native format from Buffer.


Example

var I: Longint;

begin

  I := 1221;

  { Set the data }

  Query1.ParamByName('CustNo').SetData(@I);

end;


SetData method

See also	Example

Applies to

TBCDField, TBlobField, TBooleanField, TBytesField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TGraphicField, TIntegerField, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

procedure SetData(Buffer: Pointer);

Description

SetData is the method used to assign "raw" data to the field. Unlike the AsString or Text properties, SetData performs no translation or interpretation of the data. Buffer must have sufficient space allocated for the data. Use the DataSize property to determine the space required. To set the data to NULL, pass nil for the Buffer parameter.


Example

{ Assign "raw" data to Field1 }

with Field1 do

  begin

{ Allocate space }

  GetMem(Buffer, DataSize);

{ Fill Buffer with the desired data }

  ...

{ Do the assignment }

  Field1.SetData(Buffer)

{ Free the space }

  FreeMem(Buffer, DataSize);

  end;


See also

FieldDefs property

TFieldDef object


Add method for image list objects
SetDragImage method

See also

Applies to

TImageList component

Declaration

function SetDragImage(Index, HotSpotX, HotSpotY: Integer): Boolean;

Description

The SetDragImage method sets the image specified by Index within the image list to be shown when the ImageList is being used for drag and drop. The hot spot of the image is specified by HotSpotX and HotSpotY.


See also

ShowDragImage method, DragMove method, DragCursor property


SetFields method

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure SetFields(const Values: array of const);

Description

SetFields assigns the values specified in the Values array parameter to the fields in the dataset. If Values has fewer elements than there are fields, the remaining elements are unchanged. To assign a null value to a field, use the keyword null. To not assign any value to a field, use nil; the field will then get its default value.

Before calling this method, an application must first call Edit to put the dataset in Edit state. To then modify the current record in the database, it must then call Post.

Because this method depends explicitly on the structure of the underlying table, an application should use it only if the table structure will not change.


Example

Table1.SetFields([208, 23.1]);


See also

Fields property


SetFieldType method

Applies to

All field components

Declaration

procedure SetFieldType(Value: TFieldType);

Description

SetFieldType allows you to override TField's normal determination of what the field type of a field object should do. Normally, TField checks the type of the physical database field and picks a TFieldType that matches most closely. However, if you're using a TBlobField, for example, you might want to be more specific about what kind of blob field is in the database. SetFieldType lets you do so.


SetFocus method

See also	Example

Applies to

All controls; TForm component

Declaration

procedure SetFocus;

Description

The SetFocus method gives the input focus to the control. If the control is a form, the form calls the SetFocus method of its active control.


Example

When the user clicks the button on this form, the list box becomes the active control and receives the input focus:

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.SetFocus;

end;


See also

ActiveControl property

OnEnter event


SetIndexFiles method

See also

Applies to

TTable component

Declaration

procedure SetIndexFiles(Value: TStrings);

Description

Opens the specified dBASE non-production index file names. While non-production indexes are open, updates made to the table maintain the indexes. You can make one the active index by setting the IndexName property.


See also

CloseIndexFile method

OpenIndexFile method

IndexFiles property


SetKey method

See also	Example

Applies to

TTable component

Declaration

procedure SetKey;

Description

The SetKey method puts the TTable in SetKey state (the State property is set to dsSetKey). This enables an application to search for values in database tables. In SetKey state, you can set the values of the search key buffer. The search key buffer is a set of fields corresponding to the table's key fields. After setting the values of the search key buffer fields, call GotoKey, GotoNearest, FindKey, or FindNearest to move the cursor to the matching record.

SetKey differs from EditKey in that the former clears all the elements of the search key buffer. EditKey leaves the elements of the search key buffer with their current values, but enables you to edit them.


Example

with Table1 do

  begin

    SetKey;

    FieldByName('State').AsString := 'CA';

    FieldByName('City').AsString := 'Scotts Valley';

    GotoKey;

  end;


See also

IndexFields property

State property

TDataSetState type


SetLink method

See also	Example

Applies to

TDDEClientConv component

Declaration

function SetLink(Service: string; Topic: string): Boolean;

Description

The SetLink method specifies the service and topic of a DDE conversation and attempts to open the link if ConnectMode is ddeAutomatic. The Service parameter defines the DDE service and is assigned to the DDEService property. The Topic parameter defines the DDE topic and is assigned to the DDETopic property.

If ConnectMode is ddeManual, you must call OpenLink to initiate the conversation after calling SetLink.


Example

The following code establishes a link with a DDE server. The service is specified in the DDEService property of DDEClientConv1, and the topic is specified in the DDETopic property of DDEClientConv1. If the link is established, a message is displayed.

with DDEClientConv1 do

  if SetLink(DDEService, DDETopic) then

    MessageDlg('Link established.', mtInformation, [mbOK], 0);


See also

CloseLink method

OpenLink method


SetParams method

Applies to

TUpdateSQL component

Declaration

procedure SetParams(UpdateKind: TUpdateKind);

Description

The SetParams method replaces parameters (indicated by leading colons) in the SQL statement associated with the UpdateKind parameter with the value of the field with the same name as the parameter. For example, a parameter named :Sequence would be replaced by the value of the field named Sequence. If the parameter name has OLD_ in front, it is replaced the "old" value of the corresponding field, before any updates were made. For example, :OLD_Name would be replaced by the previous value of the Name field.

SetParams is called automatically when you use the Apply method.


SetPosition method

See also	Example

Applies to

TListItem object

Declaration

procedure SetPosition(const Value: TPoint);

Description

The SetPosition method moves a list item to a specified position in a list view control, which must be have its ViewStyle property set to either vsIcon or vsSmallIcon. The Value parameter specifies where to move the list item to.

Example

The following position moves the selected list item to the point 5,5 in the list view.

ListView1.Selected.SetPosition(Point(5,5));


See also

GetPosition method

GetItemAt method


SetPrinter method

Applies to

TPrinter object

Declaration

procedure SetPrinter(ADevvice, ADriver, APort: PChar; ADeviceMode: THandle);

Description

The SetPrinter method specifies a printer as the current printer. You should seldom, if ever, need to call this method, but instead should access the printer you want in the Printers property array. For more information, see the Windows API CreateDC function.


SetRange method

See also	Example

Applies to

TTable component

Declaration

procedure SetRange(const StartValues, EndValues: array of const);

Description

The SetRange method combines the functionality of the SetRangeStart, SetRangeEnd, and ApplyRange methods. SetRange assigns the elements of StartValues to the beginning index key, the elements of EndValues to the ending index key, and then calls ApplyRange. This enables an application to filter the data visible to the dataset.

If either StartValues or EndValues has fewer elements than the number of fields in the current index, then the remaining entries are set to NULL.

Note:	With Paradox or dBASE tables, these methods work only with indexed fields. With SQL databases, they can work with any columns specified in the IndexFieldNames property.


Example

Table1.SetRange([1000], [2000]);


See also

KeyExclusive property


SetRangeEnd method

See also	Example

Applies to

TTable component

Declaration

procedure SetRangeEnd;

Description

SetRangeEnd indicates that subsequent assignments to field values will specify the end of the range of rows to include in the dataset. This enables an application to filter the data that is visible to it. Any column values not specified are not considered. The corresponding method EditRangeEnd indicates to keep existing range values and update with the succeeding assignments.

Call ApplyRange to apply the range filter defined with SetRangeEnd and SetRangeStart.

SetRangeEnd differs from EditRangeEnd in that it clears all the elements of the range filter to the default values (or NULL). EditRangeEnd leaves the elements of the range filter with their current values.

Note:	With Paradox or dBASE tables, these methods work only with indexed fields. With SQL databases, they can work with any columns specified in the IndexFieldNames property.


Example

with Table1 do

  begin

    SetRangeStart; { Set the beginning key }

    FieldByName('City').AsString := 'Felton';

    SetRangeEnd; { Set the ending key }

    FieldByName('City').AsString := 'Scotts Valley';

    ApplyRange; { Tell the dataset to establish the range }

  end;


See also

CancelRange method

KeyExclusive property

EditRangeStart method

SetRange method

SetRangeStart method


SetRangeStart method

See also	Example

Applies to

TTable component

Declaration

procedure SetRangeStart;

Description

SetRangeStart indicates that subsequent assignments to field values will specify the start of the range of rows to include in the dataset. This enables an application to filter the data that is visible to it. Any column values not specified are not considered. The corresponding method EditRangeStart indicates to keep existing range values and update with the succeeding assignments.

Call ApplyRange to apply the range filter defined with SetRangeEnd and SetRangeStart.

SetRangeStart differs from EditRangeStart in that it clears all the elements of range filter to the default values (or NULL). EditRangeStart leaves the elements of range filter with their current values.

Note:	With Paradox or dBASE tables, these methods work only with indexed fields. With SQL databases, they can work with any columns specified in the IndexFieldNames property.


Example

with Table1 do

  begin

    SetRangeStart; { Set the beginning key }

    FieldByName('City').AsString := 'Ben Lomond';

    SetRangeEnd; { Set the ending key }

    FieldByName('City').AsString := 'Scotts Valley';

    ApplyRange; { Tell the dataset to establish the range }

  end;


See also

EditRangeEnd method

KeyExclusive property

SetRangeEnd method


SetSelTextBuf method

See also	Example

Applies to

TComboBox, TDBComboBox, TDBEdit, TDBMemo, TEdit, TMaskEdit, TMemo components

Declaration

procedure SetSelTextBuf(Buffer: PChar);

Description

The SetSelTextBuf method sets the selected text in the edit box or memo control to the text in the null-terminated string pointed to by Buffer.


Example

This example uses a button and an edit box on a form. When the user selects text in the edit box and clicks the button, new text replaces the selected text. The string specified as the parameter of the SetSelTextBuf is a null-terminated string of type PChar.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Button1.Caption := 'Click me';

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.SetSelTextBuf('You clicked the button');

end;


See also

GetSelTextBuf method

SetTextBuf method


SetTextBuf method

See also	Example

Applies to

All controls; TClipboard object

Declaration

procedure SetTextBuf(Buffer: PChar);

Description

The SetTextBuf method sets the control's text to the text in the buffer pointed to by Buffer. Buffer must point to a null-terminated string.


Example

This example uses a button and an edit box on a form. When the user clicks the button, text appears in the edit box. The string specified as the parameter of the SetTextBuf is a null-terminated string, as it is of type PChar.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Button1.Caption := 'Click me';

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Edit1.SetTextBuf('You clicked the button');

end;


See also

GetTextBuf method

SetSelTextBuf method


SetTick method

See also

Applies to

TTrackBar component

Declaration

procedure SetTick(Value: Integer);

Description

The SetTick method is a write-only method that allows you to set a tick at any position. To use this method you must set the TickStyle of the TickMarks property to tsManual.


See also

TickMarks property


SetUpdateState method

Example

Applies to

TOutline component

Declaration

procedure SetUpdateState(Value: Boolean);

Description

The SetUpdateState method sets the update state of the outline component. If you add or delete an item from the outline, by default the outline component reindexes the subsequent items that have indexes changed by the addition or deletion. For a large outline, this can slow processing and consume a large amount of processing time. If you have a large outline, or plan to add many items, you can turn off automatic reindexing to speed up processing. You can quickly add items, but the indexes of all subsequent items will no longer be valid. When you finish adding items, you should turn on reindexing so the index values of the subsequent items are made valid again.

By passing True in the Value property of SetUpdateState, you turn off automatic reindexing. This is functionally the same as calling the BeginUpdate method. By passing False in the Value property of SetUpdateState, you turn on automatic indexing. This is functionally the same as calling the EndUpdate method.


Example

The following code turns off automatic reindexing on Outline1.

Outline1.SetUpdateState(True);


SetVariable method

See also	Example

Applies to

TReport component

Declaration

function SetVariable(Name, Value: string): Boolean;

Description

The SetVariable method changes the value of a report variable. The Name parameter specifies which report variable changes, and the Value parameter specifies the new value. Once the SetVariable method has been called, your application can call the RecalcReport method, which recalculates the report using the new value for the specified report variable.

The SetVariable method sends a message to ReportSmith to change the specified report variable with the new value, and looks for confirmation from ReportSmith in return. If SetVariable returns True, the message was sent to ReportSmith successfully. If it returns False, ReportSmith could not receive the message or set the variable at the current time.

To learn more about report variables, see your ReportSmith documentation.

Note:	Before calling SetVariable, you must load a report by specifying the ReportName property.


Example

The following code attempts to set the 'LastName' report variable to 'Schaeferle'. If successful, it then recalculates the report.

if Report1.SetVariable('LastName', 'Schaeferle') then

  Report1.RecalcReport;


See also

RecalcReport method

SetVariableLines method


SetVariableLines method

See also

Applies to

TReport component

Declaration

function SetVariableLines(Name, Value: TStrings): Boolean;

Description

The SetVariableLines method changes the value of a report variable. The Name parameter specifies which report variable changes, and the Value parameter specifies the new value, which is a list of strings. Once the SetVariableLines method has been called, your application can call the RecalcReport method, which recalculates the report using the new value for the specified report variable.

The SetVariableLines method sends a message to ReportSmith to change the specified report variable with the new value, and looks for confirmation from ReportSmith in return. If SetVariableLines returns True, the message was sent to ReportSmith successfully. If it returns False, ReportSmith could not receive the message or set the variable at the current time.

To learn more about report variables, see your ReportSmith documentation.

Note:	Before calling SetVariable, you must load a report by specifying the ReportName property.


See also

RecalcReport method

SetVariable method


Shape property

Applies to

TBevel, TShape components

Description

The Shape property determines the visual shape of the component.

Shape property for bevel controls

Shape property for shape controls


Shape property

Example

Applies to

TBevel component

Declaration

property Shape: TBevelShape;

Description

The Shape property determines the shape the bevel control assumes. These are the possible values:

Value	Meaning

bsBox	The bevel assumes a box shape.

bsFrame	The bevel assumes a frame shape.

bsTopLine	The bevel becomes a line at the top of the bevel control.

bsBottomLine	The bevel becomes a line at the bottom of the bevel control.

bsLeftLine	The bevel becomes a line at the left side of the bevel control.

bsRightLine	The bevel becomes a line at the right side of the bevel control.


Example

This code uses a bevel control and a button. When the user clicks the button, the bevel becomes a raised frame:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Bevel1.Shape := bsFrame;

  Bevel1.Style := bsRaised;

end;


Shape property

Example

Applies to

TShape components

Declaration

property Shape: TShapeType;

Description

The Shape property determines how a TShape component appears on a form. These are the possible values and their meanings:

Value	Meaning

stEllipse	The shape is an ellipse.

stRectangle	The shape is a rectangle.

stRoundRect	The shape is a rectangle with rounded corners.

stRoundSquare	The shape is a square with rounded corners.

stSquare	The shape is a square.

stCircle	The shape is a circle.


Example

This example uses a shape component on a form. When the user clicks the shape, it becomes a ball with red stripes:

procedure TForm1.Shape1MouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

with Shape1 do

  begin

    Shape := stCircle;

    Brush.Color := clRed;

    Brush.Style := bsVertical;

  end;

end;


Shareable property

Example

Applies to

TMediaPlayer component

Declaration

property Shareable: Boolean;

Description

The Shareable property determines whether more than one application can share a multimedia device. If Shareable is False, no other components or applications can access the device. If True, more than one component or application can access the device. Shareable defaults to False.

You should set Shareable before opening a device. Some devices aren't shareable. If you set Shareable to True and try to open a device that isn't shareable by more than one application, the Open method fails and the error code is returned to the Error property.


Example

The following code sets the Shareable property of a media player named MediaPlayer1 to True before attempting to open the Microsoft Video for Windows device. Attach this code to the OnClick event handler of a bitmap button named BitBtn1. If an exception occurs when the Open method is called, a message dialog box displays the error. Note that this example assumes that C:\KA-BAR.AVI is a valid video filename.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do

  begin

    try

      FileName := 'c:\Ka-Bar.AVI';

      Shareable := True;

     Open;

    except

      MessageDlg(MediaPlayer1.ErrorMessage, mtError, [mbOk], 0);

    end;

  end;

end;


ShareImages property

See also

Applies to

TImageList component

Declaration

property ShareImages: Boolean;

Description

The ShareImages property determines whether the ImageList destroys its handle when the image list is destroyed.


See also

AllocBy property


ShortCut function

See also	Example

Unit

Menus

Declaration

function ShortCut(Key: Word; Shift: TShiftState): TShortCut;

Description

The ShortCut function creates a menu shortcut at run time. Specify a Key value by using a virtual key code. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

Specify a Shift value by using a set of type TShiftState. For example, to specify the Shift key, use the set [ssShift]. To specify a Shift and Ctrl key combination, use the set [ssShift, ssCtrl].

Once you create a shortcut, you can assign it to the ShortCut property of a menu item.

The TextToShortCut function can also create a shortcut. This function converts a string to a shortcut; therefore, it's useful when you want to let the user specify the shortcut. TextToShortCut executes much more slowly, however, so you should use the ShortCut function whenever possible.


Example

This code creates a shortcut, Ctrl+O, at run time and assigns it to the Open command on a File menu.

begin

  OpenCommand.ShortCut := ShortCut(Word('O'), [ssCtrl]);

end;


See also

ShortCut property

ShortCutToKey procedure

ShortCutToText function

TextToShortCut function


ShortCut property

Example

Applies to

TMenuItem component

Declaration

property ShortCut: TShortCut;

Description

The ShortCut property determines the key strokes users can use to access a menu item. The key combination the user can use appears to the right of the menu item in the menu. To see an example of menu shortcuts, pull down the Delphi Edit menu and note the menu shortcuts on the right side of some of the editing commands.

Usually you set menu shortcuts for menu items in the Object Inspector, which gives you a long list to choose from. If you create menu items at run time, however, you can create shortcuts for them too. Choose from these functions and procedures for more information about working with shortcuts at run time:

Routine	Purpose

ShortCut function	Creates a shortcut for a menu item programmatically.

ShortCutToKey procedure	Obtains the virtual key code and shift state of an existing shortcut.

ShortCutToText function	Returns the text string of an existing shortcut. Use this function to display a shortcut you created at run time on a menu item.

TextToShortCut function	Converts a text string to a shortcut. Use this function to allow users to specify the shortcut characters.


Example

This code creates a shortcut, Ctrl+C, at run time and assigns it to the Close command on a File menu.

begin

  CloseCommand.ShortCut := ShortCut(Word('C'), [ssCtrl]);

end;


ShortCutToKey procedure

See also	Example

Unit

Menus

Declaration

procedure ShortCutToKey(ShortCut: TShortCut; var Key: Word; var Shift: TShiftState);

The ShortCutToKey procedure breaks a menu shortcut apart into its virtual key code and shift state parts.


Example

The following code redefines the ShortCut of CloseCommand if the original short cut used the [ssCtrl] shift state.

var

  TheKey: Word;

  TheShiftState: TShiftState;

begin

  ShortCutToKey(CloseCommand.ShortCut, TheKey, TheShiftState);

  if TheShiftState = [ssCtrl] then

    CloseCommand.ShortCut := ShortCut(Word('C'), [ssShift]);

end;


See also

ShortCut function

ShortCut property

ShortCutToText function

TextToShortCut function


ShortCutToText function

See also	Example

Unit

Menus

Declaration

function ShortCutToText(ShortCut: TShortCut): string;

Description

The ShortCutToText function converts a shortcut into a string. Your application can use this function any time it needs to display a menu shortcut as a string.

Note:	The ShortCut property of a menu item is of type TShortCut, so you can assign a shortcut you create at run time using either the ShortCut function or the TextToShortCut function directly to the menu item's ShortCut property. You don't need to use ShortCutToText to convert the shortcut to a text string first.


Example

This code converts the menu shortcut assigned to the OpenCommand ShortCut property to a string and displays it in an edit box:

Edit1.Text := ShortCutToText(OpenCommand.ShortCut);


See also

ShortCut function

ShortCut property

ShortCutToKey procedure

TextToShortCut function


Show method

See also	Example

Applies to

All controls; TForm component

Declaration

procedure Show;

Description

The Show method makes a form or control visible by setting its Visible property to True. If the Show method of a form is called and the form is somehow obscured, Show tries to make the form visible by bringing it to the front with the BringToFront method.

If the control is in an auto-scrolling control, such as a TForm or TScrollBox, Show will make sure that the form is also scrolled into view. If the control is contained in a pages control such as the TPageControl, the page the control is contained on will be brought to the front.


Example

This code puts away the current form and displays another:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form1.Hide;

  Unit2.Form2.Show;

end;


See also

Hide method

ShowModal method

Visible property


ShowAccelChar property

See also	Example

Applies to

TLabel component

Declaration

property ShowAccelChar: Boolean;

Description

The ShowAccelChar property determines how an ampersand in the caption of a label appears. If ShowAccelChar is True, an ampersand appears as an underline under the character to its right in the caption indicating the underlined character is an accelerator character. If ShowAccelChar is False, the ampersand character appears as an ampersand.


Example

This example uses two labels on a form. The first label has a caption with an accelerator character in it. The second label also includes an ampersand, but it does not appear as an accelerator character.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Label1.ShowAccelChar := True;

  Label1.Caption := 'An &Underlined character appears here';

  Label2.ShowAccelChar := False;

  Label2.Caption := 'An ampersand (&) appears here';

end;


See also

Caption property

FocusControl property


ShowButtons property

See also

Applies to

TTreeView component

Declaration

property ShowButtons: Boolean;

Description

The ShowButtons property specifies whether to display plus (+) and minus (-) buttons to the left side of each parent item. If ShowButtons is set to True, a button will appear to the left of each parent item. The user can click the button to expand or collapse the child items as an alternative to double-clicking the parent item.


See also

ShowLines property

ShowRoot property


ShowColumnHeaders property

See also	Example

Applies to

TListView component

Declaration

property ShowColumnHeaders: Boolean;

Description

The ShowColumnHeaders property determines whether the column headers on a list view are displayed. A column header is a panel with a caption that identifies the category of its list of items. Headers are useful for labeling the columns of subitems that provide additional information in a list view.

Use the Columns property to create or add headers. To display the headers the ShowColumnHeaders property must be set to True and the ViewStyle property must be set to vsReport.


Example

The following example will hide the column headers of the list view.

ListView1.ShowColumnHeaders := False;


See also

Columns property

ViewStyle property


ShowDragImage method for TImageList
ShowDragImage method

See also

Applies to

TImageList component

Declaration

procedure ShowDragImage;

Description

The ShowDragImage method shows the current drag image if it was previously hidden.


See also

SetDragImage method, DragMove method, DragCursor property


ShowException method

Applies to

TApplication component

Declaration

procedure ShowException(E: Exception);

Description

The ShowException method displays an exception that occurred in your application in a message box.


ShowFocus property

Applies to

TDBCtrlGrid component

Declaration

property ShowFocus: Boolean;

Description

Indicates whether to draw a focus rectangle inside the panel containing the current record.


ShowGlyphs property

Example

Applies to

TFileListBox component

Declaration

property ShowGlyphs: Boolean;

Description

The value of the ShowGlyphs property determines whether glyphs (bitmaps) appear next to the file names listed in the file list box. If ShowGlyphs is True, the glyphs appear; if ShowGlyphs is False, the glyphs don't appear. The default value is False.


Example

If the files in the list box don't have the glyphs next to them, this line of code redisplays the files with the glyphs included:

FileListBox1.ShowGlyphs := True;


ShowHint property

Applies to

All controls, TApplication component

The ShowHint property is used at both the control and the application level.

Description

For all controls

For the application


ShowHint property

See also	Example

Applies to

All controls component

Declaration

property ShowHint: Boolean;

Description

The ShowHint property determines if the control should display a Help Hint when the user's mouse pointer rests momentarily on the control. The Help Hint is the value of the Hint property, which is displayed in a box just beneath the control. If ShowHint property is True, the Help Hint will appear.

If ShowHint is False, the Help Hint may or may not appear. If ParentShowHint is False also, the Help Hint won't appear. If, however, ParentShowHint is True, whether or not the Help Hint appears depends on the setting of the ShowHint property of the control's parent. For example, imagine a check box within a group box. If the ShowHint property of the group box is True and the ParentShowHint property of the check box is True, but the ShowHint property of the check box is False, the check box will still display its Help Hint.

The default value is False.

Changing the ShowHint value to True automatically sets the ParentShowHint property to False.


Example

This example uses an edit box on a form. When the application runs and the user places the mouse pointer over the edit box, a Help Hint in an aqua box appears:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.ShowHint := True;

  Application.HintColor := clAqua;

  Application.HintPause := 1000;

  Edit1.ShowHint := True;

  Edit1.Hint := 'Enter your name';

end;


See also

HintColor property

HintPause property

ParentShowHint property

ShowHint for the application


ShowHint property

See also	Example

Applies to

TApplication component

Declaration

property ShowHint: Boolean;

Description

Run-time only. The ShowHint property determines whether Help Hints are enabled or disabled for the entire application. If ShowHint is True, Help Hints are enabled; if ShowHint is False, Help Hints are disabled. The default value is True.

Even if ShowHint is True, a Help Hint won't appear for a particular control unless its own ShowHint property is True, or its ParentShowHint property is True and its parent's ShowHint property is True.

Setting ShowHint for the application to False disables all Help Hints, regardless of the value of the ShowHint properties for individual controls.


Example

This example includes an control that has a Hint property value and has its ShowHint property value set to True. When the application runs and the user places the mouse cursor over the control, a Help Hint appears for the control in a red hint box after a delay of 1000 milliseconds:

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.ShowHint := True;

  Application.HintColor := clAqua;

  Application.HintPause := 1000;

end;


See also

Hint property

HintColor property

HintPause property


Showing property

See also	Example

Applies to

All controls

Declaration

property Showing: Boolean;

Description

Run-time and read-only. The Showing property specifies whether a component is currently showing on the screen. If the Visible properties of a component and all the parents in its parent hierarchy are True, Showing is True. If one of the ancestors of the component has a Visible property value of False, Showing is False.


Example

The following code adds the name of all controls in a form for which Showing is False to a list box. When Button2 is clicked, ListBox1 is filled with the names of all windowed controls that aren't showing in Form1.

procedure TForm1.Button2Click(Sender: TObject);

var

  I: Integer;

begin

  for I := 0 to ComponentCount -1 do

    if Components[I] is TWinControl then

     if not TWinControl(Components[I]).Showing then

         ListBox1.Items.Add(Components[I].Name);

end;


See also

Hide method

Show method


ShowLines property

See also

Applies to

TTreeView component

Declaration

property ShowLines: Boolean;

Description

The ShowLines property specifies whether lines that link child items to their corresponding parent items are displayed. If ShowLines is set to True, lines linking child items to their parent items will be displayed. Items at the root of the hierarchy are not automatically linked. To link items at the root, the ShowRoot property must also be set to True.


See also

ShowButtons property

ShowRoot property


ShowMessage procedure

See also	Example

Unit

Dialogs

Declaration

procedure ShowMessage(const Msg: string);

Description

The ShowMessage procedure displays a message box with an OK button. The Msg parameter is the message string that appears within the message box. The name of your application's executable file appears as the caption of the message box.


Example

This example uses a button on a form. When the user clicks the button, a message dialog box appears with instructions to push the OK button.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ShowMessage('Push this button');

end;


See also

MessageBox method

MessageDlg function

MessageDlgPos function

ShowMessagePos procedure


ShowMessagePos procedure

See also	Example

Unit

Dialogs

Declaration

procedure ShowMessagePos(const Msg: string; X, Y: Integer);

Description

The ShowMessagePos procedure displays a message box with an OK button at a specified screen location. The Msg parameter is the message string that appears within the message box. The X and Y parameters are the screen coordinates for the upper left corner of the message box. The name of your application's executable file appears as the caption of the message box.


Example

This example uses a button on a form. When the user clicks the button, a message dialog box appears with a comment about Delphi programmers. The upper left corner of the message box appears at screen location 100, 100.

procedure TForm1.Button1Click(Sender: TObject);

begin

  ShowMessagePos('Delphi programmers are more productive', 100, 100);

end;


See also

MessageBox method

MessageDlg function

MessageDlgPos function

ShowMessage procedure


ShowModal method

See also	Example

Applies to

TForm component

Declaration

function ShowModal: Integer;

Description

The ShowModal method makes a form the active form, just like Show, but also makes the form modal; therefore the user must put the form away before the application can continue to run.

When the user chooses to close the form in some manner, the value of the form's ModalResult property changes to a nonzero value. When ModalResult has a nonzero value, the form terminates, and the ModalResult value is passed as the result of the ShowModal method.


Example

The following code displays a message box after BtnBottomDlg is shown modally and is closed by an OK button.

BtnBottomDlg.ShowModal;

if BtnBottomDlg.ModalResult=mrOK then

  MessageDlg('OK!', mtInformation, [mbOK], 0);

This code uses two forms and a button on the first form. The user must close Form2 before the focus returns to Form1.

uses Unit2;

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form2.ShowModal;

end;


See also

ModalResult property

Show method


ShowRoot property

See also

Applies to

TTreeView component

Declaration

property ShowRoot: Boolean;

Description

The ShowRoot property specifies whether lines connecting root (top-level) items are displayed. To show lines connecting root items, set the tree view's ShowRoot and ShowLines properties to True.


See also

ShowLines property


SimplePanel property

See also

Applies to

TStatusBar component

Declaration

property SimplePanel: Boolean;

Description

The SimplePanel property, which may be toggled on and off, determines whether the status bar displays one panel with SimpleText or multiple panel sections. To add multiple panel sections to a status bar in the Object Inspector, use the Panels property to bring up the StatusBar Panels Editor. To display these multiple panels set SimplePanel to False. To display only the string held in the SimpleText property set SimplePanel to True.

Note::	Owner-draw panels are not supported on status bars when the SimplePanel property is set to True.


See also

Panels property

SimpleText property


SimpleText property

See also

Applies to

TStatusBar component

Declaration

property SimpleText: string;

Description

The SimpleText property contains the string that is displayed in the status bar when the SimplePanel property is True. When the SimplePanel property is False multiple status panels are displayed, if they exist, each with its own Text.


See also

SimplePanel property


Size property

Applies to

TFieldDef, TFont, TTextAttributes, TBits object; TBCDField, TBlobField, TBytesField, TGraphicField, TIntegerField, TMemoField, TStringField, TTimeField, TVarBytesField components

Description

Size for Fonts

Size for TFieldDef Objects

Size for Field Components

Size for TBits objects

Size for TBlobStream objects


Size property

Applies to

TBits object

Declaration

property Integer

Description

The Size property represents the number of Boolean values the TBits object can hold. You can set Size to expand or shrink the number of values being held. If you expand the size, the new entries are set to False. If you shrink the size, values whose indexes are less than or equal to the new size are preserved; entries whose indexes are greater than the new size are lost.


Size property

See also	Example

Applies to

TFont component

Declaration

property Size: Integer;

Description

The Size property is the size of the font in points. It is the height of the font plus the font's excluding internal leading. If you are concerned with the height of the font on the screen--the number of pixels the font needs--use the Height property instead. If you want to specify a font's height using pixels, use the Size property.

Delphi calculates Size using this formula:

Font.Size = -Font.Height * Font.PixelsPerInch / 72

Therefore, whenever you enter a point size in the Size property, you'll notice the Height property changes to a negative value. Conversely, if you enter a positive Height value, the Size property value changes to a negative value.


Example

This examples uses a button on a form. When the user clicks the button, the size of the font used by the button changes to 24 points.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Font.Size := 24;

end;


See also

Font property

Height property

PixelsPerInch property


Size property for TFieldDef objects
Size property

See also	Example

Applies to

TFieldDef objects;

Declaration

property Size: Integer;

Description

Run-time and read-only. Reports the size of the TFieldDef object. Size is meaningful only for a TFieldDef object with one of the following TFieldType values: ftString, ftBCD, ftBytes, ftVarBytes, ftBlob, ftMemo or ftGraphic. For string and byte fields, Size is the number of bytes reserved in the table for the field. For a BCD field, it is the number of digits following the decimal point. For a BLOB, memo, or graphic field it is the number of bytes in the field.


Example

{ Allocate enough memory to make a copy of the BLOB }

GetMem(PBlob, BlobFieldDef.Size);


See also

TField component


Size property

Applies to

TBCDField, TBlobField, TBytesField, TGraphicField, TIntegerField, TMemoField, TStringField, TTimeField, TVarBytesField components

Declaration

property Size: Integer;

Description

For a TStringField, Size is the number of bytes reserved for the field in the dataset. For a TBCDField, it is the number of digits following the decimal point. For a TBlobField, TBytesField, TVarBytesField, TMemoField, or TGraphicField, it is the size of the field as stored in the table.


Size Property for Blob Streams
Size property

See also

Applies to

TBlobStream object

Declaration

property Size: Longint;

Description

The Size property indicates the size in bytes of the data contained in the blob field assocated with the blob stream. Size is read-only.


See also

Create method


SizeGrip property

See also

Applies to

TStatusBar component

Declaration

property SizeGrip: Boolean;

Description

The SizeGrip property determines whether the status bar has a triangular corner sizing grip, which functions like a sizing border. Click on the sizing grip and drag it to resize the parent window. The SizeGrip property is True by default but is only useful when the TStatusBar has the alTop or alBottom value set for the Align property.


See also

Align property


SmallChange property

See also	Example

Applies to

TScrollBar component

Declaration

property SmallChange: TScrollBarInc;

Description

The SmallChange property determines how far the thumb tab moves when the user clicks the arrows at the end of the scroll bar to scroll or uses the arrow keys on the keyboard. The default value is 1.

For example, if SmallChange is 1000, each time the user clicks an arrow on the scroll bar, the thumb tab moves 1000 positions. The number of positions is determined by the difference between the Max property value and the Min property value. If the Max property is 30000 and the Min property is 0, the user would need to click an arrow on the scroll bar 30 times to move the thumb tab from one end of the scroll bar to the other.


Example

This code determines that when the user clicks an arrow on the scroll bar, the thumb tab moves 10 positions on the scroll bar:

ScrollBar1.SmallChange := 10;


See also

LargeChange property

Max property

Position property


SmallImages property

See also 	Example

Applies to

TListView component

Declaration

property SmallImages: TImageList;

Description

The SmallImages property determines which image list (TImageList) is used by the list view when the list view has a ViewStyle property of vsSmallIcon. An image list contains a list of bitmaps that can be displayed next to the item's label.

Example

The following example sets the list view's SmallImages property to ImageList1.

ListView1.SmallImages := ImageList1;


See also

TImageList object

ImageIndex property

IconOptions property

ViewStyle property

Items property


Sort method

Applies to

TStringList, TList objects

Description

Sort method for string list objects

Sort method for list objects


Sort method

See also	Example

Applies to

TStringList objects

Declaration

procedure Sort;

Description

The Sort method sorts the strings in a string list object in alphabetical order.


Example

The following code sorts MyStringList.

MyStringList.Sort;


See also

Sorted property


Sort method

Applies to

TList objects

Declaration

procedure Sort(Compare: TListSortCompare);

TListSortCompare = function (Item1, Item2: Pointer): Integer;

Description

The Sort method performs a Quick Sort on the list based on the return results of Compare.  Compare will return < 0 if Item1 is less and Item2, 0 if they are equal and > 0 if Item1 is greater than Item2.


Sorted property

Applies to

TStringList object; TComboBox, TDBComboBox, TDBListBox, TListBox components

Description

The Sorted property determines whether a list will be sorted in alphabetical order.

Sorted property for combo boxes and list boxes

Sorted property for string list objects


Sorted property

See also	Example

Applies to

TComboBox, TDBComboBox, TDBListBox, TListBox components

Declaration

property Sorted: Boolean;

Description

The Sorted property indicates whether the items in a list box or combo box are arranged alphabetically. To sort the items, set the Sorted value to True. If Sorted is False, the items are unsorted.

If you add or insert items when Sorted is True, Delphi automatically places them in alphabetical order.


Example

This example uses an edit box, a list box, and two buttons on a form. The buttons are named Add and Sort. When the user clicks the Add button, the text in the edit box is added to the list in the list box. When the user clicks the Sort button, the list in the list box is sorted and remains sorted, even if additional strings are added:

procedure TForm1.FormCreate(Sender: TObject);

begin

  ListBox1.Items.Add('Not');

  Listbox1.Items.Add('In');

  ListBox1.Items.Add('Alphabetical');

  ListBox1.Items.Add('Order');

end;

procedure TForm1.AddClick(Sender: TObject);

begin

  ListBox1.Items.Add(Edit1.Text);

end;

procedure TForm1.SortClick(Sender: TObject);

begin

  ListBox1.Sorted := True;

end;


See also

Add method

Insert method

Items property


Sorted property

See also	Example

Applies to

TStringList object

Declaration

property Sorted: Boolean;

Description

The value of the Sorted property for a string list determines the order of the strings in the list of strings maintained by the string list. If Sorted is True, the strings are sorted in ascending order. If Sorted is False, the strings are unsorted.


Example

This example uses a list box on a form. When the application runs, a string list object is created and three strings are added to it. The strings are sorted and added to the list box, where they appear in their sorted order:

procedure TForm1.FormCreate(Sender: TObject);

var

  MyList: TStringList;

begin

  MyList := TStringList.Create;

  MyList.Add('Plants');

  MyList.Add('Animals');

  MyList.Add('Minerals');

  MyList.Sorted := True;

  ListBox1.Items.AddStrings(MyList);

  MyList.Free;

end;


See also

Add method

IndexOf method

Items property

Sort method

Strings property


Sort method for list views
SortType property

See also

Applies to

TListView, TTreeView components

Declaration

property SortType: TSortType;

Description

The SortType property determines if and how the items in a tree view or list view are automatically sorted. The default is stNone.

Once a list view or tree view is sorted, the original hierarchy is lost. That is, setting the SortType back to stNone will not restore the original order of items. These are the possible values:

Value	Meaning

nsNone	No sorting is done.

nsData	The items are sorted when the Data object or SortType is changed.

nsText	The items are sorted when the Caption or SortType is changed.

nsBoth	The items are sorted when either the Data object, the Caption or SortType is changed


See also

Caption property

Data property

Text property


Source property

Applies to

TBatchMove component; TIndexDef object

Description

Source property for batch move components

Source property for index definition objects


Source property for batch move components
Source property

Example

Applies to

TBatchMove component

Declaration

property Source: TDataSet;

Description

Source specifies a data set (a TQuery or TTable component) corresponding to an existing source table.


Example

BatchMove1.Source := Table1;


Source property for index defs
Source property

Applies to

TIndexDef object

Declaration

property Source: string;

Description

Run-time and read-only. The Source property holds the index tag name, if applicable. Only available on dBASE table indexes.


Spacing property

See also	Example

Applies to

TBitBtn, TSpeedButton components

Declaration

property Spacing: Integer;

Description

The Spacing property determines where the image and text appear on a bitmap or speed button. Spacing determines the number of pixels between the image (specified in the Glyph property) and the text (specified in the Caption property). The default value is 4 pixels.

If Spacing is a positive number, its value is the number of pixels between the image and text. If Spacing is 0, no pixels will be between the image and text. If Spacing is -1, the text appears centered between the image and the button edge. The number of pixels between the image and text is equal to the number of pixels between the text and the button edge opposite the glyph.


Example

This example loads a bitmap from a file when the form is created and places the bitmap 20 pixels from the right side of the button text:

procedure TForm1.FormCreate(Sender: TObject);

begin

  BitBtn1.Glyph.LoadFromFile('c:\delphi\bin\mybitmap.bmp');

  BitBtn1.Layout := blGlyphLeft;

  BitBtn1.Spacing := 20;

end;


See also

Caption property

Layout property

Margin property


SQL property

Applies to

TUpdateSQL, TQuery components

Description

SQL Property for TQuery Components

SQL Property for TUpdateSQL Components


SQL property

Applies to

TUpdateSQL component

Declaration

property SQL[UpdateKind: TUpdateKind]: TStrings;

Description

Run-time only. The SQL property returns the string list containing the SQL statement corresponding to the UpdateKind index. (For example, SQL[ukModify] is the same as ModifySQL.)


SQL property

See also

Applies to

TQuery component

Declaration

property SQL: TStrings;

Description

The SQL property holds the text of the SQL statement that will be executed when Open or ExecSQL is called. Once a query has been executed by Open, you must call the Close method before you can change the SQL text.

You can create the text for the SQL property:

At design time, by choosing the SQL property in the Object Inspector, and entering the SQL statements in the String List Editor dialog box. With Delphi Client/Server, you can also use the Visual Query Builder to construct SQL syntax.

At run time, by closing any current query with Close, clearing the SQL property with Clear, and then specifying the SQL text with the Add method.

You can also use the LoadFromFile method to assign the text in an SQL script file to the SQL property.

A TQuery component can use SQL to access data from:

Paradox or dBASE tables, using local SQL. The allowable syntax is a subset of ANSI-standard SQL and includes basic SELECT, INSERT, UPDATE, and DELETE statements.

Databases on the Local InterBase Server, using InterBase SQL. For information on syntax and limitations, see the InterBase Language Reference.

Databases on remote database servers (Delphi Client/Server only). You must have installed the appropriate SQL Link. Any standard statement in the server's SQL is allowed. For information on SQL syntax and limitations, see your server documentation.

Delphi also supports heterogeneous queries against more than one server or table type (for example, data from an Oracle table and a Paradox table). For more information see the Database Application Developers Guide, Chapter 9, "Creating heterogenous queries" .

Note:	The SQL property may contain only one complete SQL statement at a time. In general, multiple statements are not allowed. Some servers support multiple statement "batch" syntax; if the server supports this, then such statements are allowed.


See also

Text property


Start property

See also	Example

Applies to

TMediaPlayer component

Declaration

property Start: Longint;

Description

The Start property specifies the starting position within the currently loaded medium. Start is the beginning of the medium for devices that don't use tracks, or the beginning of the first track for devices that use tracks. Start is defined when a multimedia device is opened with the Open method. Start is specified according to the current time format, which is stored in the TimeFormat property. Start is read-only at run time and is unavailable at design time.


Example

The following code displays the start position of the Microsoft Video for Windows file in an edit box named Edit1. Attach the code to the OnClick event handler of a bitmap button named BitBtn1. The code assumes Video for Windows has been installed and a video file named NOTES.AVI is present.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do

  begin

    try

      FileName := 'NOTES.AVI';

      Open;

      Edit1.Text := IntToStr(MediaPlayer1.Start);

    except

      MessageDlg(MediaPlayer1.ErrorMessage, mtError, [mbOk], 0);

    end;

  end;

end;


See also

Length property


StartAdvise method

Applies to

TDdeClientConv component

Declaration

function StartAd vise: Boolean;

Description

The StartAdvise function starts an advise loop for all of the DdeClientItems associated with the current DDE conversation.  Returns True if loop startup is successful.


StartMargin property

See also	Example

Applies to

TTabSet component

Declaration

property StartMargin: Integer;

Description

The StartMargin property determines how far in pixels the first tab appears from the left edge of the tab set control. The default value is 5. Together with the EndMargin property, StartMargin can play a role in determining how many tabs can fit within the tab set control.


Example

This example displays the tab set control so that the tabs are no closer than 20 pixels from the edge of the tab control on the left and from the scroll buttons on the right:

procedure TForm1.FormCreate(Sender: TObject);

begin

  with TabSet1 do

  begin

    AutoScroll := True;

    StartMargin := 20;

    EndMargin := 20;

  end;

end;


See also

AutoScroll property

EndMargin property


StartPage property

See also	Example

Applies to

TReport component

Declaration

property StartPage: Word;

Description

The value of the StartPage property determines which page you want the report to start printing from. The default value is 1, indicating the first page. You can change that value to begin printing the report on some other page.


Example

The following code determines the page on which to start printing the report from an edit box.

Report1.StartPage := StrToInt(Edit1.Text);


See also

EndPage property

PrintCopies property

Print method


StartPos property

See also	Example

Applies to

TMediaPlayer component

Declaration

property StartPos: Longint;

Description

Run-time only. The StartPos property specifies the position within the currently loaded medium from which to begin playing or recording. StartPos is specified using the current time format, which is specified in the TimeFormat property.

The StartPos property affects only the next Play or StartRecording method called after setting StartPos. You must reset StartPos to affect any subsequent calls to Play or StartRecording.

StartPos does not affect the current position of the medium (specified in the Position property) until the next Play or StartRecording method is called.


Example

The following procedure begins playing the .WAV audio file from the middle of the file.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    FileName := 'd:\winapps\sounds\cartoon.wav';

    Open;

    StartPos := TrackLength[1] div 2;

    Play;

  end;

end;


See also

EndPos property


StartRecording method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure StartRecording;

Description

The StartRecording method begins recording from the current Position or from the position specified in StartPos. StartRecording is called when the Record button on the media player control is clicked at run time.

Upon completion, StartRecording stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the StartRecording method has completed. The Notify property determines whether StartRecording generates an OnNotify event.

By default, the Notify property becomes True, and the Wait property becomes False upon completion of the StartRecording method. However, if you've set these properties to specific values prior to calling StartRecording, they remain unchanged.


Example

The following code tells MediaPlayer1 to start recording.

MediaPlayer1.StartRecording;


See also

Capabilities property

Pause method

PauseOnly method

Play method

Stop method


StartTransaction method

Example

Applies to

TDataBase component

Declaration

procedure StartTransaction;

Description

The StartTransaction method begins a transaction at the isolation level specified by the TransIsolation property. If a transaction is currently active, Delphi raises an exception.

Modifications made to the database are not stored permanently until the Commit method is called to commit the changes. Modifications are discarded if the Rollback method is called to cancel the changes.

Note:	Before an application starts a transaction against a Paradox or DBASE table, the TransIsolation propertymust be set to tiDirtyRead.


Example

with Database1 do

  begin

    StartTransaction;

  { Update one or more records in tables linked to Database1 }

...

    Commit;

  end;


State property

Applies to

TCheckBox, TDBCheckBox, TDataSource, TDBGridColumns objects; TTable, TQuery, TStoredProc, TTreeView, TOleContainer components

Description

State Property for Grid Column Objects

State Property for Check Boxes

State Property for Data Source Components

State Property for Tables, Queries, and Stored Procedures

State Property for Tree Views

State Property for Ole Containers


State property

Applies to

TOleContainer component

Declaration

property State: TObjectState;

Description

Runtime and readonly. Returns the state of the OLE object. See TObjectState for possible values.


State property

See also	Example

Applies to

TTreeView components

Declaration

property Selected: TTreeNode;

Description

Run-time only. The Selected property for tree views returns the item in the tree view that is selected. If an item becomes selected, the tree view's OnChanging and OnChanged events will be triggered. Also, if the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the tree views OnExpanded and OnExpanding events are triggered.


Example

The following code deleted the selected item in the tree view.

TreeView1.Selected.Delete;


See also

OnChange event

OnChanging event

SelectedIndex property

OnGetSelectedIndex event

Focused property


State property

Applies to

TDBGridColumns objects

Declaration

property State: TDBGridColumnsState;

Description

The State property indicates whether the column objects stored in the TDBGridColumns collection are the default column objects created from the dataset's field information (csDefault) or whether they're persistent and standalone from the dataset's fields (csCustomized). If you use the Columns Editor to set up column properties, the column objects are persistent.


State property

See also	Example

Applies to

TCheckBox, TDBCheckBox objects

Declaration

property State: TCheckBoxState;

Description

The State property determines the various states a check box control can have. These are the possible values:

Value	Meaning

cbUnchecked	The check box has no check mark indicating the user hasn't selected the option.

cbChecked	The check box has a check mark in it indicating the user has selected the option.

cbGrayed	The check box is gray indicating a third state that is neither checked nor unchecked. Your application determines the meaning of a grayed check box.

State is a run-time only property of a database check box component.


Example

This code examples uses three check boxes on a form. When the form is created, the code sets the initial state of each of the check boxes: the first check box is checked, the second check box is dimmed (or grayed), and the third check box is unchecked:

procedure TForm1.FormCreate(Sender: TObject);

begin

  CheckBox1.State := cbChecked;

  CheckBox2.State := cbGrayed;

  CheckBox3.State := cbUnChecked;

end;


See also

AllowGrayed property

Checked property


State property

Example

Applies to

TDataSource objects

Declaration

property State: TDataSetState;

Description

State reads the current status of the dataset component. Possible values are those of the TDataSetState type: dsInactive, dsBrowse, dsEdit, dsInsert, dsSetKey, or dsCalcFields. The value of State is the same as that of the State property of DataSet, except that when Enabled is False or DataSet has not been assigned a value, State will be dsInactive.


Example

if DataSource1.Dataset <> nil then

  PostButton.Enabled := DataSource1.State in [dsEdit, dsInsert];


State property

Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property State: TDataSetState;

Description

Run-time and read-only. The State property specifies the current state of the dataset. The possible values are those of the TDataSetState type:

dsInactive when the dataset is closed

dsBrowse when the dataset is in Browse state

dsEdit when the dataset is in Edit state

dsInsert when the dataset is in Insert state

dsSetKey when the dataset is in SetKey state

dsCalcFields when the OnCalcFields event is called.


Example

{ Open the dataset if it is not already }

if Table1.State = dsInactive then Table1.Active := True;


StateImages property for tree views
StateImages property

See also	Example

Applies to

TListView, TTreeView components

Declaration

property StateImages: TImageList;

Description

Run-time only. The StateImages property for tree views and list views determines which image list (TImageList component) to use for state images. A state image is for when you want to display an additional image to the left of the item's icon.


Example

The following example sets the StateImages property of the tree view to ImageList2.

TreeView1.StateImages := ImageList2;


See also

StateIndex property

OnGetImageIndex event

SelectedIndex property

OnGetSelectedIndex event

Images property

OverlayIndex property


StateIndex property for tree nodes
StateIndex property

See also	Example

Applies to

TListItem, TTreeNode objects

Declaration

property StateIndex: Integer;

Description

Run-time only. The StateIndex property indicates which image from the StateImages image list to display for the item. If the StateIndex is -1, then no state image is drawn.


Example

The following example changes the selected items state index.

TreeView1.Selected.StateIndex := 2;


See also

Images property

OnGetSelectedIndex event

Images property

ImageIndex property

StateImages property

SelectedIndex property

OnGetImageIndex event

OverlayIndex property


Step method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Step;

Description

The Step method steps forward a number of frames (determined by the Frames property) in the currently loaded medium. Step is called when the Step button on the media player control is clicked at run time.

Upon completion, Step stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Step method has completed. The Notify property determines whether Step generates an OnNotify event.


Example

The following example lets the user pick an .AVI video file using OpenDialog1 and opens that file in MediaPlayer1. The 'Step' button can then be used to step forward through the .AVI clip. This could be used to hide MediaPlayer1 if you wanted to design your own user interface for the media player.

procedure TForm1.FormClick(Sender: TObject);

begin

  OpenDialog1.Filename := '*.*';

  if OpenDialog1.Execute then begin

    MediaPlayer1.Filename := OpenDialog1.Filename;

    MediaPlayer1.Open;

  end;

end;

procedure TForm1.BackClick(Sender: TObject);

begin

  MediaPlayer1.Step;

end;


See also

Back method

Capabilities property


Step property

See also

Applies to

TProgressBar component

Declaration

property Step: Integer;

Description

The Step property indicates the amount that the Position increases with the StepIt method. The default is 10.


See also

Max property

Min property

Position property

StepIt method


StepBy method

See also

Applies to

TProgressBar component

Declaration

procedure StepBy(Delta: Integer);

Description

Run-time only. The StepBy method modifies the Position of the track bar by the specified amount Delta.


See also

Max property

Min property

Position property

StepIt method


StepIt method

See also	Example

Applies to

TProgressBar component

Declaration

procedure StepIt;

Description

Run-time only. The StepIt method modifies Position by the amount specified by the Step property.


Example

The following example opens a file chosen from an open dialog and reads each line while showing how far along the process is with the progress bar.

procedure TForm1.Button1Click(Sender: TObject);

var

  fb: file of byte;

  f: TextFile;

  TotalBytes: Longint;

  s: String;

begin

  if OpenDialog1.Execute then begin

    {find the total number of bytes in the file}

    AssignFile(fb, OpenDialog1.FileName);

    reset(fb);

    TotalBytes := FileSize(fb);

    CloseFile(fb);

    {open the file again as text and read each line showing the progress

    with the progress bar}

    AssignFile(f, OpenDialog1.FileName);

    reset(f);

    with ProgressBar1 do begin

      {Max is assigned the approximate # of lines}

      {lines in the file, 25 is the avg. # of char's per line}

      Max := TotalBytes div 25;

      Step := 1;

      application.ProcessMessages;

      while not eof(f) do begin

        readln(f, s);

        StepIt;

      end;

      Caption := 'Done';

    end;

    CloseFile(f);

  end;

end;


See also

Max property

 Min property

Position property

Step property

StepBy method


StmtHandle property

Applies to

TQuery, TStoredProc component

Declaration

property StmtHandle: HDBIStmt;

Description

Run-time and read-only. The StmtHandle property enables an application to make direct calls to the Borland Database Engine (BDE) API using the result of the last query. Under most circumstances you should not need to use this property, unless your application requires some functionality not encapsulated in the VCL.


Stop method

See also	Example

Applies to

TMediaPlayer component

Declaration

procedure Stop;

Description

The Stop method stops playing or recording. Stop is called when the Stop button on the media player control is clicked at run time.

Upon completion, Stop stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Stop method has completed. The Notify property determines whether Stop generates an OnNotify event.


Example

The following procedure stops the currently playing multimedia device when Button2 is clicked.

procedure TForm1.Button2Click(Sender: TObject);

begin

  MediaPlayer1.Stop;

end;


See also

Pause method

PauseOnly method

Play method

StartRecording method


StoredProcName property

Example

Applies to

TStoredProc component

Declaration

property StoredProcName: string;

Description

StoredProcName is the name of the stored procedure on the server.

Oracle servers allow more than one stored procedure with the same name. Set the Overload property to specify the procedure to execute on an Oracle server.


Example

StoredProc1.StoredProcName := 'FOO';


Stretch property

See also	Example

Applies to

TImage, TDBImage components

Declaration

property Stretch: Boolean;

Description

Setting the Stretch property to True permits bitmaps and metafiles to assume the size and shape of the image control. When the image control is resized, the image resizes also. Stretch will also resize an image to fit into a smaller TImage control. The Stretch property has no affect on icons.

If you prefer to have the image control resize to fit the native size of the image, set the AutoSize property to True.


Example

This example uses an image component on a form. When the form is created, the specified image is loaded and stretched to fit the boundaries of the image component.

procedure TForm1.FormCreate(Sender: TObject);

begin

  Image1.Stretch := True;

  Image1.Picture.LoadFromFile('C:\DELPHI\DEMOS\GRAPHEX\PASTE.BMP');

end;


See also

AutoSize property

LoadFromFile method

Picture property


StretchDraw method

Example

Applies to

TCanvas object

Declaration

procedure StretchDraw(const Rect: TRect; Graphic: TGraphic);

Description

This method draws the graphic specified by the Graphic parameter in the rectangle specified by the Rect parameter. Use this method to stretch or resize a graphic to the size of the rectangle.


Example

The following code stretches the bitmap to fill the client area of Form1.

Form1.Canvas.StretchDraw(Form1.ClientRect, TheGraphic);


Strings property

See also	Example

Applies to

TStringList, TStrings objects

Declaration

property Strings[Index: Integer]: string;

Description

Run-time only. With the Strings property, you can access a specific string of a string or string list object. Specify the position of the string in the string list as the value of the Index parameter. The index of the Strings property is zero-based, so the first string has an Index value of 0, the second has an Index value of 1, and so on. To find out what the index of a particular string is, call the IndexOf method.

Strings is the default property of string objects. Therefore, you can safely omit the reference to the Strings identifier and just the treat the string object itself as an indexed array of strings. In the following example, Lines is a string object property of a memo component (TMemo). These two lines of code are both acceptable and do the same thing:

Memo1.Lines.Strings[0] := 'This is the first line';

Memo1.Lines[0] := 'This is the first line';


Example

This example uses a list box and a button on a form. When the form is created, three string are added to the list box. When the user clicks the button, each of the strings of the Items property, a TStrings object, changes:

procedure TForm1.FormCreate(Sender: TObject);

begin

  ListBox1.Items.Add('One');

  ListBox1.Items.Add('Two');

  ListBox1.Items.Add('Three');

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items.Strings[0] := 'First';

  ListBox1.Items.Strings[1] := 'Second';

  ListBox1.Items.Strings[2] := 'Third';

end;

Because Strings is the default property of a string object, you can omit the reference to Strings in the preceding code. For example, you can write the code like this:

procedure TForm1.FormCreate(Sender: TObject);

begin

  ListBox1.Items.Add('One');

  ListBox1.Items.Add('Two');

  ListBox1.Items.Add('Three');

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.Items[0] := 'First';

  ListBox1.Items[1] := 'Second';

  ListBox1.Items[2] := 'Third';

end;


See also

Add method

AddObject method

AddStrings method

Assign method

Clear method

Count property

Delete method

Exchange method

IndexOf method

LoadFromFile method

Objects property

SaveToFile method


StringWidth method

See also

Applies to

TListView component

Declaration

function StringWidth(S: string); Integer;

Description

Run-time only. The StringWidth method returns the width of a specified string, using the specified list view control's current font.


See also

Font property

Caption property


Style property

Applies to

TFont, TPen, TTextAttributes objects; TBevel, TBitBtn, TComboBox, TDBComboBox, TDBListBox, TDBLookupCombo, THeaderSection, TListBox, TOutline, TStatusPanel, TTabSet components

Description

Style property for pen objects

Style property for brush objects

Style property for font and text attributes objects

Style property for combo boxes

Style property for list boxes

Style property for bitmap buttons

Style property for tab set controls

Style property for outlines

Style property for bevel controls

Style property for database lookup combo boxes

Style property for status panels

Style property for header sections


Style property for pen objects
Style property

Example

Applies to

TPen objects

Declaration

property Style: TPenStyle;

Description

The Style property determines the style in which the pen draws lines. The following table shows the different style values and what they produce:.

Style	Meaning

psSolid	The pen draws a solid line.

psDash	The pen draws a line made up of a series of dashes.

psDot	The pen draws a line made up of a series of dots.

psDashDot	The pen draws a line made up of alternating dashes and dots.

psDashDotDot	The pen draws a line made up of a series of dash-dot-dot combinations.

psClear	The pen draws lines made up no visible marks.

psInsideFrame	The pen draws lines within the frame of closed shapes that specify a bounding rectangle.


Example

This example uses two radio buttons on a form. When the user drags the mouse pointer across the form, lines are drawn. The user can use the two radio buttons to choose between two pen styles. Selecting the first radio button draws a dotted line. Selecting the second radio button draws a solid line.

var

  Drawing: Boolean;

procedure TForm1.FormMouseDown(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Drawing := True;

  Canvas.MoveTo(X, Y);

end;

procedure TForm1.FormMouseMove(Sender: TObject; Shift: TShiftState; X,

  Y: Integer);

begin

  if Drawing then

    Canvas.LineTo(X, Y);

end;

procedure TForm1.FormMouseUp(Sender: TObject; Button: TMouseButton;

  Shift: TShiftState; X, Y: Integer);

begin

  Canvas.LineTo(X, Y);

  Drawing := False;

end;

procedure TForm1.RadioButton1Click(Sender: TObject);

begin

  Canvas.Pen.Style := psDot;

end;

procedure TForm1.RadioButton2Click(Sender: TObject);

begin

  Canvas.Pen.Style := psSolid;

end;


Style property for brush objects
Style property

Example

Applies to

TBrush objects

Declaration

property Style: TBrushStyle;

Description

The Style property of a brush determines the brush's pattern for painting backgrounds of windows or graphic shapes. The following table shows the different values for Style and the resulting patterns:

Hatch	Pattern	Hatch	Pattern

bsSolid	bsCross

bsClear	bsDiagCross

bsBDiagonal	bsHorizontal

bsFDiagonal	bsVertical


Example

This example displays a rectangle filled with red horizontal stripes whenever a form OnPaint event occurs.

procedure TForm1.FormPaint(Sender: TObject);

begin

  with Canvas do

  begin

    Brush.Style := bsHorizontal;

    Brush.Color := clRed;

    Rectangle(12, 50, 100, 200);

  end;

end;


Style property for font objects
Style property

Example

Applies to

TFont objecs

Declaration

property Style: TFontStyles;

Description

The Style property determines whether the font is normal, italic, underlined, bold, and so on. These are the possible values:

Value	Meaning

fsBold	The font is boldfaced.

fsItalic	The font is italicized.

fsUnderline	The font is underlined.

fsStrikeout	The font is displayed with a horizontal line through it.

The Style property is a set, so it can contain multiple values. For example, a font could be both boldfaced and italicized.


Example

The following code boldfaces the font used in the memo..

Memo1.Font.Style := [fsBold];


Style property for combo boxes
Style property

See also	Example

Applies to

TComboBox, TDBComboBox components

Declaration

property Style: TComboBoxStyle;

Description

The Style property determines how a combo box displays its items. By default, Style is csDropDown, meaning that the combo box displays each item as a string in a drop-downthat items can be graphical of either fixed or varying height. You can set Style to any of list. By changing the value of Style, you can create owner-draw combo boxes, meaning the following values:

Value	Meaning

csDropDown	Creates a drop-down list with an edit box in which the user can enter text. All items are strings, with each item having the same height.For database combo boxes, the combo box displays the contents of the field of the current records. The user can choose another item from the drop-down list and change the value of the field or type a new value in the edit box.

csSimple	Creates an edit box with no list. For database combo boxes, the current contents of the linked field displays in the combo box. The user can change the contents of the field by typing in a new value.

csDropDownList	Creates a drop-down list with no attached edit box, so the user can't edit an item or type in a new item. All items are strings, with each item having the same height.For database combo boxes, the edit box is blank unless the current contents of the field matches one of the specified Items in the drop-down list. The user can change the contents of the field only by selecting one of the strings from the drop-down list.

csOwnerDrawFixed	Each item in the combo box is the height specified by the ItemHeight property.For database combo boxes, the combo box is blank unless the current contents of the field matches one of the specified Items in the drop-down list. The user can change the contents of the field only by selecting one of the strings from the drop-down list.

csOwnerDrawVariable	Items in the combo box can be of varying heights.For database combo boxes, the combo box is blank unless the current contents of the field matches one of the specified Items in the drop-down list. The user can change the contents of the field only by selecting one of the strings from the drop-down list.

Owner-draw combo boxes can display items other than strings. For example, a combo box could display graphical images along with or instead of its strings. Owner-draw combo boxes require more programming, however, as the application needs information on how to render the image for each item in the list.

Each time an item is displayed in an csOwnerDrawFixed combo box, the OnDrawItem event occurs. The event handler for OnDrawItem draws the specified item. The ItemHeight property determines the height of all the items.

Each time an item is displayed in an csOwnerDrawVariable combo box, two events occur. The first is the OnMeasureItem event. The event handler for OnMeasureItem can set the height of each item. Then the OnDrawItem event occurs. The OnDrawItem handler draws each item in the list box using the size specified by the OnMeasureItem handler.


Example

This example uses a combo box and a check box on a form. If the user checks the check box, the combo box becomes a drop-down list. When the user unchecks the check box, the combo box becomes a simple combo box:

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    ComboBox1.Style := csDropDownList

  else

    ComboBox1.Style := csSimple;

end;


See also

ReadOnly property

Creating an owner-draw control


Style property for list boxes
Style property

See also	Example

Applies to

TListBox components

Declaration

property Style: TListBoxStyle

Description

The Style property determines how a list box displays its items. By default, Style is lbStandard, meaning that the list box displays each item as a string. By changing the value of Style, you can create owner-draw list boxes, meaning that items can be graphical and of either fixed or varying height. These are the possible values for Style:

Value	Meaning

lbStandard	All items are strings, with each item the same height.

lbOwnerDrawFixed	Each item in the list box is the height specified by the ItemHeight property.

lbOwnerDrawVariable	Items in the list box can be of varying heights.

Owner-draw list boxes can display items other than strings. For example, a list box could display graphical images along with or instead of its strings. Owner-draw list boxes require more programming, however, because the application needs information on how to render the image for each item in the list.

Each time an item is displayed in an lbOwnerDrawFixed list box, the OnDrawItem event occurs. The event handler for OnDrawItem draws the specified item. The ItemHeight' property determines the height of all the items.

Each time an item is displayed in an lbOwnerDrawVariable list box, two events occur. The first is the OnMeasureItem event. The code you write for the OnMeasureItem handler can set the height of each item. Then the OnDrawItem event occurs. The code you write for the OnDrawItem handler draws each item in the list box using the size specified by the OnMeasureItem handler.


Example

This example uses a list box and a check box. When the user checks the check box, the list box becomes an fixed owner-draw list box. When the user unchecks the check box, the list box becomes a standard list box:

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    ListBox1.Style := lbOwnerDrawFixed

  else

ListBox1.Style := lbStandard;

end;


See also

Creating an owner-draw control


Style property

See also	Example

Applies to

TBitBtn components

Declaration

property Style: TButtonStyle;

Description

The Style property of a bitmap button determines the appearance of a bitmap button. These are the possible values:

Value	Meaning

bsAutoDetect	When you are using Windows 3.x, the bitmap button uses the standard Windows 3.x look. When you are using a later version of Windows, the bitmap button uses a newer look.

bsWin31	Uses the standard Windows 3.1 look, regardless of which version of Windows you are running.

bsNew	Uses a new bitmap button look, regardless of which version of Windows you are running.


Example

This example uses a bitmap button and a check box on a form. When the user checks the check box, the bitmap button assumes the new bitmap style. When the user unchecks the check box, the bitmap button takes on the Windows 3.1 look:

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    BitBtn1.Style := bsNew

  else

    BitBtn1.Style := bsWin31;

end;


See also

Kind property


Style property

See also	Example

Applies to

TTabSet component

Declaration

property Style: TTabStyle;

Description

The Style property of a tab set control (TTabSet component) determines how a tab appears. These are the possible values:

Value	Meaning

tsStandard	Each tab has the standard size and look.

tsOwnerDraw	Each tab has the height specified with the TabHeight property and width needed to hold the text or glyph.

Owner-draw tabs can display objects other than strings, such as graphical images. Owner-draw tabs require more programming, however, as the application needs information on how to render the image for each tab in the tab set control.

Each time an item is displayed in an tsOwnerDraw tab, two events occur. The first is the OnMeasureTab event. In the OnMeasureTab event handler, you write the code that calculates the width of the tab needed to hold the text or graphical image. After the OnMeasureTab event, the OnDrawTab event occurs. The code you write for the OnDrawTab event draws the tab and its contents using the width found with the OnMeasureTab event and the height specified as the value of the TabHeight property.


Example

When this example runs, the tab set on the form becomes an owner-draw tab set:

procedure TForm1.FormCreate(Sender: TObject);

begin

  TabSet1.Style := tsOwnerDraw;

end;


See also

Creating an owner-draw control

TTabStyle type


Style property for outlines
Style property

Example

Applies to

TOutline components

Declaration

property Style: TOutlineType;

Description

The Style property determines how a outline displays its items. By default, Style is osStandard, meaning that the outline displays items in the style determined by the OutlineStyle property. By changing the value of Style to otOwnerDraw, you can create owner-draw outlines, meaning that items are drawn on the Canvas of the TOutline component by code that you write. These are the possible values for Style:

Value	Meaning

otStandard	Items are drawn according to the setting of OutlineStyle.

otOwnerDraw	Items are drawn on the Canvas by your code.

Owner-draw outlines can display items other than the Text of an item and the standard bitmaps specified in the PictureClosed, PictureOpen, PictureMinus, PicturePlus, and PictureLeaf properties. Owner-draw outlines require more programming, however, as the application needs information on how to render the image for each item in the list.

Each time an item is displayed in an otOwnerDraw outline, the OnDrawItem event occurs. The event handler for OnDrawItem draws the specified item. The ItemHeight property determines the height of all the items.


Example

The following code sets the style of Outline1 to owner-draw.

Outline1.Style := otOwnerDraw;


Style property

Example

Applies to

TBevel components

Declaration

property Style: TBevelStyle;

Description

The value of the Style property determines if the bevel is raised or lowered. These are the possible values:

Value	Meaning

bsLowered	The bevel is lowered.

bsRaised	The bevel is raised.


Example

This example uses a bevel and a check box on a form. When the check box is checked, the bevel is raised. When the check box is unchecked, the bevel is lowered:

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    Bevel1.Style := bsRaised

  else

    Bevel1.Style := bsLowered;

end;


Style property

Example

Applies to

TDBLookupCombo components

Declaration

property Style: TDBLookupComboStyle;

Description

The Style property determines how a database lookup combo box displays its items. These are the possible values:

Value	Meaning

csDropDown	Creates a drop-down list with an edit box in which the user can enter text.

csDropDownList	Creates a drop-down list with no attached edit box, so the user can't edit an item or type in a new item.

The default value is csDropDown.

Note:	If the value of the LookupDisplay property differs from the value of the LookupField property, the database lookup combo box will function as if its Style is csDropDownList, regardless of the value of the Style property.


\Example

The following code sets the style of DBLookupCombo1 to have a drop-down list with no edit box.

DBLookupCombo1.Style := csDropDownList;


Style property for status panels
Style property

See also

Applies to

TStatusPanel object

Declaration

property Style: TStatusPanelStyle;

Description

The Style property of the TStatusPanel determines how a status bar displays its panels. The individual items or panels in a status bar are TStatusPanel objects. These are added by using the Panels property and are displayed by setting the SimplePanel property to False. By default, their Style is psText, meaning that the panel displays a string. By changing the value of Style to psOwnerDraw, you can create owner-draw status bar panels in which what is drawn on the Canvas of the TStatusBar is determined by code that you write for the OnDrawPanel event handler.

Value	Meaning

psText	Items are strings.

psOwnerDraw	Items are drawn on the Canvas by your code.

Each time an item is displayed in an psOwnerDraw status bar control, the OnDrawPanel event occurs.


See also

Canvas property

OnDrawPanel event

Panels property

SimplePanel property


Style property for header sections
Style property

See also

Applies to

THeaderSection object

Declaration

property Style: THeaderSectionStyle;

Description

The Style property determines how a header control displays its items. By default, Style is hsText, meaning that the header control displays each item as a string. By changing the value of Style to hsOwnerDraw, you can create owner-draw header controls in which items are drawn on the Canvas of the THeaderControl by code that you write. These are the possible values:

Value	Meaning

hsText	Items are strings.

hsOwnerDraw	Items are drawn on the Canvas by your code.

Each time an item is displayed in an hsOwnerDraw header control, the OnDrawSection event occurs. The event handler for OnDrawSection draws the specified item. Individual items in a header control are THeaderSection objects.


See also

Canvas property

OnDrawSection event


SubItems property

See also	Example

Applies to

TListItem object

Declaration

property SubItems: TStrings;

Description

Run-time only. The SubItems property contains the strings that appear as sub items to the list items in the list view control. To add a new subitem, use the SubItem's Add method. SubItems are only visible when the list view's ViewStyle property is set to vsReport


Example

The following example adds a new sub item to the selected list item in the list view control.

ListView1.Selected.SubItems.Add('OK!!!');


See also

Items property

ViewStyle property

Add method


Add method for image list objects
SupportsClipboardFormat method

Applies to

TPicture object

Declaration

class function SupportsClipboardFormat(AFormat: Word): Boolean;

Description

The SupportsClipboardFormat method returns True if the given Clipboard format is supported by the LoadFromClipboardFormat method.


Tab property

See also	Example

Applies to

TParaAttributes object

Declaration

property Tab[Index: Byte]: Longint;

Description

Tab is an indexed property that is array of absolute tab stop positions. It is one of the properties of a TParaAttributes object that contains information about the currently selected paragraph in a TRichEdit control. To change a tab stop, select the index of the tab to change and assign a new value to it.


Example

procedure TForm1.Button1Click(Sender: TObject);

begin

  RichEdit1.Paragraph.Tab[2] := 5;

end;


See also

Paragraph property

TabCount property


TabCount property

See also

Applies to

TParaAttributes object

Declaration

property TabCount: Integer;

Description

The TabCount property contains the number of tab stops in the currently selected paragraph in a TRichEdit control. It is one of the properties of a TParaAttributes object that contains information about the currently selected paragraph in a TRichEdit. To change an individual tab stop use the indexed Tab property.


See also

Paragraph property

Tab property


TabFont property

See also	Example

Applies to

TTabbedNotebook component

Declaration

property TabFont: TFont;

Description

The TabFont property determines the font used on the tabs of the tabbed notebook control. The text on the selected tab is boldfaced if the selected font for the TabFont property is not also boldfaced.


Example

This example uses a tabbed notebook on a form. When the application runs, four pages are added to the tabbed notebook and the font used for the text on the tabs is colored blue.

procedure TForm1.FormCreate(Sender: TObject);

begin

  TabbedNotebook1.Pages.Clear;

  TabbedNotebook1.Pages.Add('Styles');

  TabbedNotebook1.Pages.Add('Colors');

  TabbedNotebook1.Pages.Add('Fonts');

  TabbedNotebook1.Pages.Add('Edit options');

  TabbedNotebook1.TabsPerRow := 4;

  TabbedNotebook1.TabFont.Color := clNavy;

end;


See also

Font property


TabHeight property

Applies to

TTabSet, TPageControl, TTabControl components

Description

TabHeight property for tab sets

TabHeight property for page and tab controls


TabHeight property

See also	Example

Applies to

TTabSet components

Declaration

property TabHeight: Integer;

Description

The TabHeight property determines the height of the tabs in a tab set control when the tab set control's Style property value is tsOwnerDraw. If the Style property value is tsStandard, the TabHeight property value is ignored.


Example

This example uses a tab set component. When the form is created, the tab set becomes an owner-draw tab set and the tabs are set to 30 pixels in height:

procedure TForm1.FormCreate(Sender: TObject);

begin

  TabSet1.Style := tsOwnerDraw;

  TabSet1.TabHeight := 30;

end;


See also

OnDrawTab event


TabHeight property

See also

Applies to

TPageControl, TTabControl components

Declaration

property TabHeight: Smallint;

Description

The TabHeight property is the vertical size in pixels of the individual tabs. If zero is specified as the TabHeight tabs will automatically size themselves to fit their text.


See also

TTabWidth property


TabIndex property

Applies to

TTabSet, TTabControl, TTabSheet components

Description

TabIndex property for tab sets

TabIndex property for tab controls

TabIndex property for tab sheets


TabIndex property

See also	Example

Applies to

TTabSet components

Declaration

property TabIndex: Integer;

Description

The value of the TabIndex property determines which tab of a tab set control is currently selected. The value can be from -1 to one less than the number of strings in the Tabs property array (Tabs.Count - 1). A value of 0 indicates the first tab in the tab set control, 1 is the second tab, and so on. If no tabs are selected, TabIndex has a value of -1.

TabIndex can be used as an index to the Tabs array property.

When a value is assigned to TabIndex, the OnClick event for the tab set occurs, followed by the OnChange event, just as if the user had clicked on a new tab.


Example

This line of code makes the third tab in the tab set component the selected tab:

TabSet1.TabIndex := 2;


See also

PageIndex property

TNotebook component


TabIndex property

See also

Applies to

TTabControl components

Declaration

property TabIndex: Integer;

Description

The individual tabs on a TTabControl are identified by their zero-based index. The first (leftmost) tab has a TabIndex of 0, the next has 1, and so on. The value of the TabIndex property determines which tab of a tab control is currently selected. If no tabs are selected, TabIndex has a value of -1.


See also

OnChanging event


TabIndex property

See also

Applies to

TTabSheet components

Declaration

property TabIndex: Integer;

Description

Run-time and read only. The TabIndex property returns the index value of a tab sheet according to its index into an array of visible tabs in a TPageControl. For example, a tab sheet may have a PageIndex of 3 but a TabIndex of 2 if one of the previous tab sheets in the page control is not visible. If a tab sheet's TabVisible property is False, the TabIndex property is -1.


See also

PageIndex property

Pages property

TabVisible property


TableName property

Applies to

TTable component

Declaration

property TableName: TFileName;

Description

The TableName property is the name of the database table to which the TTable is linked.

Note:	The TTable must be closed to change this property.


TableType property

See also

Applies to

TTable component

Declaration

property TableType: TTableType

Description

The TableType property specifies the type of the underlying database table. This property is not used for SQL tables.

If TableType is set to Default, the table's file-name extension determines the table type:

Extension of .DB or no filename extension: Paradox table

Extension of .DBF : dBASE table

Extension of .TXT : ASCII table

If the value of TableType is not Default, then the table will always be of the specified TableType, regardless of file-name extension::

ttASCII: Text file

ttDBase: dBASE table

ttParadox: Paradox table

Note:	The TTable must be closed to change this property.


See also

CreateTable method

TableName property


TabOrder property

See also	Example

Applies to

All windowed controls except TForm component

Declaration

property TabOrder: TTabOrder;

Description

The TabOrder property indicates the position of the control in its parent's tab order, the order in which controls receive the focus when the user presses the Tab key.

Initially, the tab order is always the order in which the components were added to the form, but you can change this by changing the TabOrder property. The value of the TabOrder property is unique for each component on the form. The first component added to the form has a TabOrder value of 0, the second is 1, the third is 2, and so on. These values determine where a control is in the tab order.

Each component has a unique tab-order value within its parent. If you change the TabOrder property value of one component to be the same as the value of a second component, Delphi automatically renumbers the TabOrder value for all the other components. For example, suppose a component is sixth in the tab order. If you change the component's TabOrder property value to 3 (making the component fourth in the tab order), the component that was originally fourth in the tab order now becomes fifth, and the component that was fifth becomes sixth.

If you attempt to give a component a TabOrder value greater than the number of components on the form minus one (because numbering starts with 0), Delphi won't accept the new value, but will enter the value that assures the component will be the last in the tab order.

The control with the TabOrder value of 0 is the control that will have the focus when the form first appears.

TabOrder is meaningful only if the TabStop property is True.


Example

This example ensures that the check box on the form is the first in the tab order, and therefore, the active control whenever the form appears, no matter how many other controls are on the form:

procedure TForm1.FormCreate(Sender: TObject);

begin

 CheckBox1.TabStop := True;

 CheckBox1.TabOrder := 0;

end;


See also

TabStop property


Tabs property

See also	Example

Applies to

TTabControl, TTabSet components

Declaration

property Tabs: TStrings;

Description

The Tabs property contains the list of text strings that appear on the tabs. For each string in the Tabs property, a new tab is created to display the text string. At design time, you enter the text strings you want to appear on the tabs using the String List editor. Double-click the value column of the Tabs property to display the String List editor. You can also change strings in the Tabs property at run time.


Example

This example uses a tab set control and a memo control. When the user types a line in the memo control, the line is added as a new tab on the tab set control. Each time the user presses Enter in the memo control, a new tab is created in the tab set control:

procedure TForm1.Memo1Change(Sender: TObject);

begin

  TabSet1.Tabs := Memo1.Lines;

end;


See also

TabIndex property

TabHeight property


TabsPerRow property

See also	Example

Applies to

TTabbedNotebook component

Declaration

property TabsPerRow: Integer;

Description

The TabsPerRow property is obsolete and retained only for backwards compatibility.

The TabsPerRow property determines the number of tabs that can appear in a row at the top of the tabbed notebook control. If there are more tabbed pages in the control than can fit in one row, multiple rows are displayed. The number of tabs you specify affects the size of the tabs--the more tabs per row--the smaller the tabs.


Example

This example uses a tabbed notebook on a form. When the application runs, four pages are added to the tabbed notebook, the number of tabs per row is set at 4, and the font used for the text on the tabs is colored blue.

procedure TForm1.FormCreate(Sender: TObject);

begin

  TabbedNotebook1.Pages.Clear;

  TabbedNotebook1.Pages.Add('Styles');

  TabbedNotebook1.Pages.Add('Colors');

  TabbedNotebook1.Pages.Add('Fonts');

  TabbedNotebook1.Pages.Add('Edit options');

  TabbedNotebook1.TabsPerRow := 4;

  TabbedNotebook1.TabFont.Color := clNavy;

end;


See also

Pages property

TabFont property


TabStop property

See also	Example

Applies to

All windowed controls except TForm component

Declaration

property TabStop: Boolean;

Description

The TabStop property determines if the user can tab to a control. If TabStop is True, the control is in the tab order. If TabStop is False, the control is not in the tab order; therefore, the user can't press the Tab key to move to the control. The default value for most controls is True.


Example

This code removes ListBox1 from the tab order, so that the user can't use the Tab key to get to the list box:

ListBox1.TabStop := False;


See also

TabOrder property


TabStops property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property TabStops[Index: Longint]: Boolean;

Description

Run-time only. The TabStops property lets you specify which columns in the grid you want the user to be able to move to using the Tab and Shift+Tab keys. By default, all columns in a grid are tab stops; in other words, TabStops is True for all columns initially. To prevent a user from being able to press Tab or Shift+Tab to move to a column, change the TabStops property value to False, specifying the column as the value of the Index parameter. The first column in a grid has an index value of 0.

The user can use the Tab and Shift+Tab keys only if the Options property set of the grid includes the value goEditing. If goEditing is False, the user can't tab to any column.


Example

This example uses a string grid on a form. This code prevents the user from using the Tab key to move to the third column in the grid. When the user presses Tab to move out of second column, the cursor jumps to the fourth column:

procedure TForm1.FormActivate(Sender: TObject);

begin

  StringGrid1.Options := [goFixedHorzLine,goFixedVertLine,goHorzLine,goVertLine,

    goEditing,goTabs];

  StringGrid1.TabStops[2] := False;

end;


See also

Options property

TabStop property


TabVisible property

See also

Applies to

TTabSheet component

Declaration

property TabVisible Boolean;

Description

The TabVisible property determines whether the tab of a TTabSheet object is visible in a TPageControl. TabVisible is True by default. If TabVisible is False, its TabIndex property is -1. Clicking on a tab activates the tab sheet. If TabVisible is False, the tab does not appear; in which case, you can use FindNextPage with the CheckTabVisble set to False to increment through both visible and non-visible page controls and activate the tab sheet. For example, to hide a tab at run time, you could use the following code:

TabSheet1.TabVisible : = False;


See also

FindNextPage method

SelectNextPage method

TabIndex property


TabWidth property

See also

Applies to

TPageControl, TTabControl component

Declaration

property TabWidth: Smallint;

Description

The TabWidth property is the horizontal size in pixels of the individual tabs. If zero is specified as the TabWidth tabs will automatically size themselves to fit their text.


See also

TabHeight property


Tag property

Example

Applies to

All components

Declaration

property Tag: Longint;

Description

The Tag property is available to store an integer value as part of a component. While the Tag property has no meaning to Delphi, your application can use the property to store a value for its special needs.


Example

The following code assumes that the OnClick event handlers of more than one button point to the TForm1.Button1Click method. When a button is clicked, the procedure checks to see if the value of the Tag of the clicked button is 42. If so, the caption of that button is changed.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if (Sender as TButton).Tag = 42 then

    (Sender as TButton).Caption := 'A-Ha!';

end;


TAlign type

Unit

Controls

Declaration

TAlign = (alNone, alTop, alBottom, alLeft, alRight, alClient);

Description

TAlign defines the possible values of the Align property.


TAlignment type

Unit

Classes

Declaration

TAlignment = (taLeftJustify, taRightJustify, taCenter);

Description

TAlignment is the type of the Alignment property.


TApplication component

Properties	Methods	Events

Unit

Forms

Description

Each Delphi application automatically uses a TApplication component, which encapsulates your application. Delphi declares an Application variable of type TApplication that is an instance of your application.

When you execute your application, the application's Run method is called. The Terminate method ends application execution. The name of your application's executable file is the value of the ExeName property.

The main form of your application is the form specified as the value of the MainForm property. By default, Delphi will use the first form created in the main program block of the .DPR file. If you want to make another form the main form, the form that is created first, use the Forms page of the Options|Project Options dialog box to do so.

When the user minimizes the application, the Minimize method is called. When the user restores the application to normal size, the Restore method is called. Your application can call these methods programmatically as well.

A minimized application appears as an icon on the Windows desktop or the task bar in Windows 95. You can assign the icon of your choice to represent your application using the Icon property. The text that appears below the icon is the value of the Title property. If your application has a help file, specify its name as the value of the HelpFile property, and the Windows Help system can display help for your application. You can specify an icon, a help file, and the title of the application in the Options|Project dialog box on the Application page.

To display the help file for your application, call the HelpContext method.

You can specify how exceptions are handled for your application using the HandleException method, the OnException event, and the ShowException method.

To display a message to the user, you can use the MessageBox method.

TApplication has several events that let you specify how your application processes the occurrence of special events. The code you write in the OnActivate and OnDeactivate event handlers specifies what happens when your application becomes active and inactive. You specify how help hints appear in the OnHint and OnShowHint event handlers. The OnIdle event handler is used to determine what happens as your application becomes idle, and the OnMessage event handler is used to process Windows messages your application receives. See Search help for "Handling Application Events" for more information about creating event handlers for application events.

In addition to these properties, methods, and events, TApplication component also has the properties and methods that apply to all components and is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Active	Hint	Name

ComponentCount	HintColor	Owner

ComponentIndex	HintHidePause	ShowHint

Components	HintPause	Tag

ExeName	HintShortPause	Terminated

Handle	Icon	Title

HelpFile	MainForm	UpdateFormatSettings


Methods

 Key methods

Create	HelpCommand	ProcessMessages

CreateForm	HelpContext	RemoveComponent

Destroy	HelpJump	Restore

FindComponent	InsertComponent	RestoreTopMosts

Free	MessageBox	Run

HandleException	Minimize	ShowException

HandleMessage	NormalizeTopMosts	Terminate


Events

 Run-time only          [image] Key events

OnActivate	OnHelp	OnMessage

OnDeactivate	OnHint

OnException	OnIdle


TAttachMode type

Unit

Outline

Declaration

TAttachMode = (oaAdd, oaAddChild, oaInsert);

Description

TAttachMode is the type of the AttachMode parameter of the MoveTo method. TAttachMode specifies the different ways which an outline item can attach to the new position when moved in an outline.


TAutoIncField component

Properties	Methods	Events

Unit

DBTables

Description

TAutoIncField represents a field of a record in a dataset. It is represented as a binary value with a range from -2,147,483,648 to 2,147,483,647. Use TAutoIncField for auto-incrementing fields that hold large, signed whole numbers.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value. Set the MinValue or the MaxValue property to limit the smallest or largest value permitted in a field.

The TAutoIncField component has the properties, methods, and events of the TField component. TAutoIncField is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayFormat	MaxValue

AsBoolean	DisplayLabel	MinValue

AsDateTime	DisplayName	Name

AsFloat	DisplayText	Owner

AsInteger	DisplayWidth	ReadOnly

AsString	EditFormat	Required

Calculated	FieldName	Size

CanModify	FieldNo	Tag

DataSet	Index	Text

DataSize	IsIndexField	Value

DataType	IsNull	Visible


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TBatchMode type

Unit

DBTables

Declaration

TBatchMode = (batAppend, batUpdate, batAppendUpdate, batDelete, batCopy);

Description

The TBatchMode type is the set of values which are passed to the BatchMove method of a TTable or the Mode property of a TBatchMove component. batAppend appends all records. (The destination must not have any records with the key of the any of the records in the source.) batUpdate replaces all existing records with the new versions. (Each record in the source must have a record in the destination with the same key.) batAppendUpdate appends any records which do not already exist and replaces those which do. batDelete deletes the records in the source from the destination. (Each source record must have a key which is also found in the destination.) batCopy makes an exact duplicate of the source table.


TBatchMove component

Properties	Methods

Unit

DBTables

Description

TBatchMove enables you to perform operations on groups of records or entire tables. Set the Source property to specify a dataset (a TQuery or TTable component) corresponding to an existing source table. Set the Destination property to specify a TTable component corresponding to a database table. The destination table may or may not already exist.

Use the Mode property to specify the operations to perform. Set the Mappings property if the Source and Destination have different column names and you want to control how those fields are transferred.

Set AbortOnProblem to specify whether to abort the operation when a data type conversion error occurs. Set the AbortOnKeyViol property to specify whether to abort the operation when an integrity (key) violation occurs. Set KeyViolTableName and ProblemTableName to create Paradox tables to hold records that caused errors. Set the ChangedTableName property to save the replaced or deleted records from Destination.

Set the Transliterate property to specify whether to transliterate character data to the preferred character set for the destination table.

In addition to these properties and methods, the TBatchMove component also has the properties and methods that apply to all components and is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

AbortOnKeyViol	KeyViolTableName	ProblemCount

AbortOnProblem	Mappings	ProblemTableName

ChangedCount	Mode	RecordCount

ChangedTableName	MovedCount	Source

CommitCount	Name	Transliterate

Destination	Owner 	Tag

KeyViolCount


Methods

 Key methods

Create	Execute

Destroy	Free


TBCDField component

Properties	Methods	Events

Unit

DBTables

Description

A TBCDField represents a field of a record in a dataset. It is represented as a Binary Coded Decimal (BCD) value. Use TBCDField for a floating-point number with a fixed number of digits following the decimal point. The range depends on the number of digits after the decimal point, since the accuracy is 18 digits.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Set the Size property to define the number of BCD digits following the decimal point. Use the Value property to access or change the current field value.

The TBCDField component has the properties, methods, and events of the TField component and is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Owner

AsBoolean	DisplayName	Precision

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditFormat	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Value

Currency	IsIndexField	Visible

DataSet	IsNull

DataSize	MaxValue

DataType	MinValue

DisplayFormat	Name


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


Bevel component
 TBevel component

Properties	Methods	Tasks

Unit

ExtCtrls

Description

TBevel lets you put beveled lines, boxes, or frames on the forms in your application.

You determine if the bevel appears as a box, frame, or line using the Shape property. The bevel can appear raised or lowered, depending on the value selected for the Style property.

To keep the bevel aligned within the form so that even if the user resizes the form, the bevel remains in the same relative position, set the Align property.

In addition to these properties and methods, the TBevel component also has the properties and methods that apply to all controls and component is a direct descendent of TGraphicControl.


Properties

 Run-time only          [image] Key properties

Align	Height	Shape

BoundsRect	Hint	ShowHint

ComponentIndex	Left	Style

Components	Name	Tag

ControlCount	Owner	Top

Controls	Parent	Visible

Handle	ParentShowHint	Width


Methods

 Key methods

BeginDrag	EndDrag	SendToBack

BringToFront	Free	SetBounds

ClientToScreen	Hide	Show

Create	Refresh	Update

Destroy	Repaint

Dragging	ScreenToClient


TBevelShape type

Unit

StdCtrls

Declaration

TBevelShape = (bsBox, bsFrame, bsTopLine, bsBottomLine, bsLeftLine, bsRightLine);

Description

The TBevelShape type defines the possible values of the Shape property of the TBevel component.


TBevelStyle type

Unit

ExtCtrls

Declaration

TBevelStyle = (bsLowered, bsRaised);

Description

The TBevelStyle type defines the possible values of the Style property of the TBevel component.


TBevelWidth type

Unit

ExtCtrls

Declaration

TBevelWidth: 1..MaxInt;

Description

The TBevelWidth type defines the possible values of the BevelWidth property for a panel component (TPanel).


 TBitBtn component

Properties	Methods	Events	Tasks

Unit

Buttons

Description

It is a push button control that can include a bitmap on its button face. You can choose from predefined bitmap buttons styles or specify your own bitmap for the button. Users use bitmap buttons as they would use a TButton component--to initiate actions.

Like buttons, bitmap buttons are frequently used within dialog boxes. A default bitmap button is the button whose OnClick event handler runs whenever the user presses the Enter key while using the dialog box. To make a bitmap button a default button, set the button's Default property to True.

A Cancel bitmap button is the button whose OnClick event handler runs whenever the user presses the Esc key while using the dialog box. To make a bitmap button a Cancel button, set the button's Cancel property to True.

You can have a bitmap button close a modal form without writing an event handler that includes code specifically to close the form. Set the button's ModalResult property to a value other than 0.

You can select from several predefined bitmap buttons. Specify the kind of bitmap button you want with the Kind property.

To create a customized bitmap button, use the Glyph property to specify the bitmap you want to appear on the button, and use the Layout, Margin, and Spacing properties to specify how to arrange the caption and bitmap on the button. You can use different images to represent the different states of the bitmap button. For example, you can use one image when the button is unselected, another when it is selected, and another when it is disabled. Use the NumGlyphs property to specify multiple images.

In addition to these properties, methods, and events, the TBitBtn component also has the properties, methods, and events that apply to all windowed controls and is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	HelpContext	PopupMenu

BoundsRect	Hint	ShowHint

Cancel	Kind	Showing

Caption	Layout	Spacing

ComponentIndex	Left	Style

Cursor	Margin	TabOrder

Default	ModalResult	TabStop

DragCursor	Name	Tag

DragMode	NumGlyphs	Top

Enabled	Owner	Visible

Font	Parent	Width

Glyph	ParentFont

Height	ParentShowHint


Methods

 Key methods

BeginDrag	Focused	ScrollBy

BringToFront	Free	SendToBack

CanFocus	GetTextBuf	SetBounds

Click	GetTextLen	SetFocus

ClientToScreen	Hide	SetTextBuf

Create	Refresh	Show

Destroy	Repaint	Update

Dragging	ScaleBy

EndDrag	ScreenToClient


Events

 Key events

OnClick	OnEnter	OnKeyUp

OnDragDrop	OnExit	OnMouseDown

OnDragOver	OnKeyDown	OnMouseMove

OnEndDrag	OnKeyPress	OnMouseUp


TBitBtnKind type

Unit

Buttons

Declaration

TBitBtnKind = (bkCustom, bkOK, bkCancel, bkHelp, bkYes, bkNo, bkClose, bkAbort, bkRetry, bkIgnore, bkAll);

Description

The TBitBtnKind type contains the values the Kind property of a TBitBtn bitmap button can assume.


TBitmap object

Properties	Methods	Events

Unit

Graphics

Description

A TBitmap object contains a bitmap graphic (.BMP file format). A TBitmap encapsulates a Windows HBITMAP and an HPALETTE and manages the realizing of the palette automatically.

The canvas of the TBitmap is a TCanvas object specified by the Canvas property. The palette of the TBitmap is specified by the Palette property.

The height and width in pixels of the bitmap are specified by the Height and Width properties, respectively.

If the Monochrome property is set to False, the bitmap is displayed in color. If Monochrome is set to True, the bitmap is converted to a monochrome format.

To load a bitmap from a file, call the LoadFromFile method. To load a bitmap from a resource along with palette information by name or resource ID, use LoadFromResourceName or LoadFromResourceID. To save a bitmap to a file, call SaveToFile.

To draw a bitmap on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TBitmap as a parameter.

When the bitmap is modified, an OnChange event occurs.

In addition to these properties, methods, and events, the TBitmap object also has the methods that apply to all objects and is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Canvas	Height	Palette

Empty	IgnorePalette	TransparentColor

Handle	Monochrome	Width


Methods

 Key methods

Assign	Destroy	ReleaseHandle

ClassName	Free	ReleasePalette

ClassParent	LoadFromFile	SaveToFile

ClassType	LoadFromResourceName

Create	LoadFromResourceID


Events

 Key events

OnChange


TBlobField component

Properties	Methods	Events

Unit

DBTables

Description

The TBlobField component represents a field of a record in a dataset. It is represented by a value consisting of an arbitrary set of bytes of indefinite size.

Use the Assign method to copy values from another field to a TBlobField. Use the LoadFromFile method to load a field's contents from a file. Use LoadFromStream method to load a field from a Stream. Use SaveToFile method to write a field's contents to a file. Use SaveToStream method to write a field's contents to a Stream.

The TBlobField component has the properties, methods, and events of the TField component and is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DataType	Name

AsBoolean	DisplayLabel	Owner

AsDateTime	DisplayName	ReadOnly

AsFloat	DisplayText	Required

AsInteger	DisplayWidth

AsString	IsIndexField	Size

Calculated	FieldName	Tag

CanModify	FieldNo	Text

DataSet	Index	Visible

DataSize	IsNull


Methods

 Key methods

Assign	FocusControl	LoadFromStream

AssignValue	Free	SaveToFile

Clear	GetData	SaveToStream

Create	IsValidChar	SetData

Destroy	LoadFromFile


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


TBlobStream object

Properties	Methods

Unit

DBTables

Description

The TBlobStream object provides a simple technique to access or modify a TBlobField, TMemoField or TGraphicField by allowing you to "read" from or "write" to the field as if it were a file or stream.

Use the Create constructor to link the field to the BLOB stream. Call the Read or Write methods to access or change the contents of the field. Use Seek to position within the field. Call the Truncate method to delete all information in the field from the current position on.

In addition to these methods, the TBlobStream object also has the methods that apply to all objects and is an indirect descendent of TObject.


Properties

 Run-time only          [image] Key properties

Position	Size


Methods

 Key methods

ClassName	Destroy	Truncate

ClassParent	Free	Write

ClassType	Read

Create	Seek


TBlobStreamMode type

Unit

DBTables

Declaration

TBlobStreamMode = (bmRead, bmWrite, bmReadWrite);

Description

The TBlobStreamMode type is the set of values which are passed to the Create method of a TBlobStream object. Use bmRead to access an existing TBlobField, TMemoField or TGraphicField. Use bmWrite to clear the contents of the field and assign a new value. Use bmReadWrite to modify an existing value.


TBlobType type

Unit

DBTables

Declaration

TBlobType = ftBlob..ftTypedBinary;

Description

The TBlobType type is the subset of values of the TFieldType type that are blob fields. TBlobType is the type of the BlobType property for TBlobField components.


TBookmark type

See also

Unit

DB

Declaration

TBookmark = Pointer;

Description

The TBookmark type is the type of the Bookmark parameter you use to call the GetBookmark, GotoBookmark, and FreeBookmark methods of a dataset component.


See also

Bookmark property


TBooleanField component

Properties	Methods	Events

Unit

DBTables

Description

A TBooleanField component represents a field of a record in a dataset. A Boolean field is either True or False, but the display string in a data-aware control can be varied.

Set the DisplayValues property to control the formatting of the field for display purposes or input recognition. Use the Value property to access or change the current field value.

The TBooleanField component has the properties, methods, and events of the TField component and is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Owner

AsBoolean	DisplayName	ReadOnly

AsDateTime	DisplayText	Required

AsFloat	DisplayValues	Size

AsInteger	DisplayWidth	Tag

AsString	FieldName	Text

Calculated	FieldNo	Value

CanModify	Index	Visible

DataSet	IsIndexField

DataSize	IsNull

DataType	Name


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TBorderIcons type

Unit

Forms

Declaration

TBorderIcon = (biSystemMenu, biMinimize, biMaximize, biHelp);

TBorderIcons = set of TBorderIcon;

Description

The TBorderIcons type defines which icons appear in a form's title bar. TBorderIcons is the type of the BorderIcons property.


TBorderStyle type

Unit

Forms

Declaration

TBorderStyle = bsNone..bsSingle;

Description

TBorderStyle is the type of the BorderStyle property for controls.

The BorderStyle property for forms and windows uses the type TFormBorderStyle.


TBorderWidth type

Unit

ExtCtrls

Declaration

TBorderWidth: 0..MaxInt;

Description

The TBorderWidth type defines the possible values for the BorderWidth property of a panel component (TPanel).


TBrush object

Properties	Methods	Events

Unit

Graphics

Description

A TBrush object is used when filling solid shapes, such as rectangles and ellipses. The interior of the shape is filled with a color or pattern. TBrush encapsulates a Windows HBRUSH.

The color of the brush is specified by the Color property. The pattern is specified by the Style property. If a bitmap is specified by the Bitmap property, the pattern of the brush is defined by the bitmap rather than the Style property.

If the brush is modified, an OnChange event occurs.

In addition to these properties, methods, and events, the TBrush object also has the methods that apply to all objects and is an indirect descendent of TPersistent.

Properties

 Run-time only          [image] Key properties

Bitmap	Handle

Color	Style


Methods

 Key methods

Assign	ClassType	Free

ClassName	Create

ClassParent	Destroy


Events

 Key events

OnChange


TBrushStyle type

Unit

Graphics

Declaration

TBrushStyle = (bsSolid, bsClear, bsHorizontal, bsVertical, bsFDiagonal, bsBDiagonal, bsCross, bsDiagCross);

Description

The TBrushStyle type is used by the Style property to determine the pattern of a TBrush object.


 TButton component

Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

A TButton component is a push button control. Users choose button controls to initiate actions. Buttons are most commonly used in dialog boxes.

A default button is the button whose OnClick event handler runs whenever the user presses the Enter key while using the dialog box. To make a button a default button, set the button's Default property to True.

A Cancel button is the button whose OnClick event handler runs whenever the user presses the Esc key while using the dialog box. To make a button a Cancel button, set the button's Cancel property to True.

You can have a button close a modal form without writing an event handler that includes code to specifically close the form. Set the button's ModalResult property to one of the values other than 0.

In addition to these properties, methods, and events, the TButton component also has the properties, methods, and events that apply to all windowed controls and is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	Font	ParentShowHint

BoundsRect	Height	PopupMenu

Cancel	HelpContext	ShowHint

Caption	Hint	Showing

ComponentIndex	Left	TabOrder

Cursor	ModalResult	TabStop

Default	Name	Tag

DragCursor	Owner	Top

DragMode	Parent	Visible

Enabled	ParentFont	Width


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

Create	Hide	SetFocus

Destroy	Refresh	SetTextBuf

Dragging	Repaint	Show

EndDrag	ScaleBy	Update


Events

 Key events

OnClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnEndDrag	OnKeyUp

OnEnter	OnMouseDown


TButtonLayout type

Unit

Buttons

Declaration

TButtonLayout = (blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom);

Description

The TButtonLayout type defines the values the Layout property of a bitmap button (TBitBtn) or speed button (TSpeedButton) can assume.


TButtonSet type

Applies to

TMediaPlayer, TDBNavigator components

Description

There are two different TButtonSet types: one for media player components and one for the database navigator components.

TButtonSet type for media player components

TButtonSet type for database navigator components


TButtonSet type

Declaration

TButtonSet = set of TMPBtnType;

Description

The TButtonSet type is a set of the buttons of the media player component. This set is used with the ColoredButtons, EnabledButtons, and VisibleButtons properties to determine how the buttons are displayed.


TButtonSet type

Declaration

TNavigateBtn = (nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh);

TButtonSet = set of TNavigateBtn;

Description

The TButtonSet type defines the possible values of the VisibleButtons property for the database navigator control.


TButtonStyle type

Unit

Buttons

Declaration

TButtonStyle = (bsAutoDetect, bsWin31, bsNew);

Description

The TButtonStyle type contains the values the Style property of bitmap buttons (TBitBtn) and speed buttons (TSpeedButton) can assume.


TBytesField component

Properties	Methods	Events

Unit

DBTables

Description

A TBytesField component represents a field of a record in a dataset. It is represented by a value consisting of an arbitrary set of bytes with indefinite size.

Use the Assign method to copy values from another field to a TBytesField.

The TBytesField component has the properties, methods, and events of the TField component and is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DataType	Name

AsBoolean	DisplayLabel	Owner

AsDateTime	DisplayName	ReadOnly

AsFloat	DisplayText	Required

AsInteger	DisplayWidth	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Visible

DataSet	IsIndexField

DataSize	IsNull


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


TCanvas object

Properties	Methods	Events

Unit

Graphics

Description

The TCanvas object is a drawing surface. It represents an area in which your application can draw. A TCanvas object encapsulates a Windows HDC display context.

The brush, pen, and font used to draw on the canvas are specified by the Brush, Pen, and Font properties.

The current drawing position is specified by the PenPos property. To move the drawing position, call the MoveTo method.

To output text, call the TextOut method. To determine if text fits in a particular area, use TextHeight and TextWidth.

To draw a straight line, call LineTo. To draw a series of straight lines, call PolyLine. To draw curved lines, use the Arc or Chord methods.

You can draw a variety of shapes on a canvas. To draw a rectangle, call Rectangle. To draw a rectangle with rounded corners, call RoundRect. To draw an ellipse, call Ellipse. To draw a pie slice, call Pie. To draw a polygon defined by a series of points, call Polygon.

To fill a rectangular area with the pattern defined by Brush, call FillRect. To fill an entire area until boundaries are encountered, call FloodFill.

To output a graphic on a canvas, such as a bitmap or metafile, call Draw. To resize the graphic to a particular shape when drawn, call StretchDraw. To make a copy of a rectangular area of the canvas, use CopyRect.

When a canvas is modified, an OnChange event occurs. Immediately prior to the modification of the canvas, an OnChanging event occurs.

In addition to these properties, methods, and events, the TCanvas object also has the methods that apply to all objects and is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Brush	Font	PenPos

ClipRect	Handle	Pixels

CopyMode	Pen


Methods

 Key methods

Arc	DrawFocusRect	PolyLine

BrushCopy	Ellipse	Rectangle

Chord	FillRect	RoundRect

ClassName	FloodFill	StretchDraw

ClassParent	FrameRect	TextHeight

ClassType	Free	TextOut

CopyRect	LineTo	TextRect

Create	MoveTo	TextWidth

Destroy	Pie

Draw	Polygon


Events

 Key events

OnChange	OnChanging


TCaption type

Unit

Controls

Declaration

TCaption = string;

Description

The TCaption type defines the string type used for control captions. TCaption is the type of the Caption property and the Text property.


TChangeRange type

Unit

Outline

Declaration

TChangeRange = -1..1;

Description

TChangeRange specifies the valid values that can be passed to the ChangeLevelBy method. -1 moves an outline item up one level, and 1 moves an outline item down one level. 0 has no effect.


 TCheckBox component

See also	Properties	Methods	Events	Tasks

Unit

StrCtrls

Description

A TCheckBox component presents an option for the user; the user can check it to select the option, or uncheck it to deselect the option.

When the user checks or unchecks a check box, the value of the Checked property changes. The OnClick event also occurs. The text associated with the check box that identifies its purpose is the value of the Caption property.

If you want the user to be able to dim or gray the check box, set the AllowGrayed property to True. Whether the check box is checked, unchecked, or grayed is determined by the value of the State property. You can change value of State to change the check box's appearance.


In addition to these properties, methods, and events, the TCheckBox component also has the properties, methods, and events that apply to all windowed controlsvclAllWindowedControls and is an indirect descendent of TWinControl. Properties
In addition to these properties, methods, and events, the TCheckBox component also has the properties, methods, and events that apply to all windowed controls and is an indirect descendent of TWinControl. Properties

 Run-time only          [image] Key properties

Align	Font	PopupMenu

Alignment	Height	ShowHint

AllowGrayed	HelpContext	Showing

Caption	Hint	State

Checked	Left	TabOrder

Color	Name	TabStop

ComponentIndex	Owner	Tag

Ctl3D	Parent	Top

Cursor	ParentColor	Visible

DragCursor	ParentCtl3D	Width

DragMode	ParentFont

Enabled	ParentShowHint


Methods

 Key methods

BeginDrag	FindComponent	ScaleBy

BringToFront	Focused	ScrollBy

CanFocus	Free	ScreenToClient

ClientToScreen	GetTextBuf	SendToBack

Create	GetTextLen	SetBounds

Destroy	Hide	SetTextBuf

Dragging	Refresh	Show

EndDrag	Repaint	Update


Events

 Key events

OnClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnEndDrag	OnKeyUp

OnEnter	OnMouseDown


See also

TDBCheckBox component

TRadioButton component


TCheckBoxState type

Unit

StdCtrls

Declaration

TCheckBoxState = (cbUnchecked, cbChecked, cbGrayed);

Description

The TCheckBoxState type defines the different types of states the check box can assume. TCheckBoxState is the type of the State property of a TCheckBox check box control.


TClipboard object

Properties	Methods

Unit

Clipbrd

Description

The TClipboard object encapsulates the Windows Clipboard. Whenever you cut, copy, or paste text or graphics objects within a Delphi application or between a Delphi application and another Windows application, you are using the TClipboard object.

The Clipbrd unit declares the variable Clipboard as an instance of TClipboard. Use the Clipboard function instead of creating your own instance of TClipboard.

You can place text in and retrieve text from the Clipboard using the AsText property. If you want to place pictures in and retrieve pictures from the Clipboard, use the Assign property. To add or retrieve a component object to the Clipboard, call the GetComponent and SetComponent methods.

The list of all the current formats on the Clipboard is found in the Formats property. The number of formats is the value of the FormatCount property. To find out if a specific format is on the Clipboard, call the HasFormat method.

Calling the Clear method clears the contents of the Clipboard.

Each time you add an item to the Clipboard, the previous contents are cleared automatically. To add multiple items, you should use the Open method to prevent the contents from being overwritten or being changed by another application. Call Close when you are finished adding items to the Clipboard.

You can add and other formats to the Clipboard using Windows handles with the GetAsHandle and SetAsHandle methods.

In addition to these properties and methods, the TClipboard object also has the methods that apply to all objects and is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

AsText	FormatCount	Formats


Methods

 Key methods

Assign	Free	SetAsHandle

Clear	GetAsHandle	SetComponent

Close	GetComponent	SetTextBuf

Create	HasFormat

Destroy	Open


TCollection object

Properties	Methods

Unit

Classes

Description

The TCollection object is used to maintain a collection of TCollectionItem objects. TCollection maintains an index of the collection items in its Items array. The Count property contains the number of items in the collection. Use the Add and Clear properties to add new items to the collection or to delete items from the collection. Objects descended from TCollection can contain objects descended from TCollectionItem. Examples are in the TStatusBar and THeaderControl controls which use TStatusPanels and THeaderSections collection objects to contain TStatusPanel and THeaderSection collection items.

In addition to these properties, methods, and events, the TCollection object also has the methods that apply to all objects and is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Count	Items


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


TCollectionItem object

Properties	Methods

Unit

Classes

Description

The TCollectionItem object is the type of item of a TCollection object. An array of collection items is maintained in the Items array of the TCollection. The collection item Index property uniquely identifies each item and corresponds to the order of the item in the Items array. The Collection property contains the TCollection object to which the collection item is associated. You can add, assign, and delete collection items in a TCollection object by using the Add, Assign, and Clear methods. TCollection objects can also contain objects descended from TCollectionItem. TStatusPanel and THeaderSection are examples of objects that are descended from TCollectionItem.

In addition to these properties, methods, and events, the TCollectionItem object also has the methods that apply to all objects and is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Collection	Index

Count	Items


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


TColor type

Unit

Graphics

Declaration

TColor = -(COLOR_ENDCOLORS + 1)..$02FFFFFF;

Description

The TColor type is used to specify the color of an object. It is used by the Color property of many components and the BackgroundColor of a tab set (TTabSet).

The Graphics unit contains definitions of useful constants for TColor. These constants map either directly to the closest matching color in the system palette (for example, clBlue maps to blue) or to the corresponding system screen element color defined in the Color section of the Windows Control panel (for example, clBtnFace maps to the system color for button faces).

The constants that map to the closest matching system colors are clAqua, clBlack, clBlue, clDkGray, clFuchsia, clGray, clGreen, clLime, clLtGray, clMaroon, clNavy, clOlive, clPurple, clRed, clSilver, clTeal, clWhite, and clYellow.

The constants that map to the system screen element colors are clActiveBorder, clActiveCaption, clAppWorkSpace, clBackground, clBtnFace, clBtnHighlight, clBtnShadow, clBtnText, clCaptionText, clGrayText, clHighlight, clHighlightText, clInactiveBorder, clInactiveCaption, clInactiveCaptionText, clMenu, clMenuText, clScrollBar, clWindow, clWindowFrame, and clWindowText.

If you specify TColor as a specific 4-byte hexadecimal number instead of using the constants defined in the Graphics unit, the low three bytes represent RGB color intensities for blue, green, and red, respectively. The value $00FF0000 represents full-intensity, pure blue, $0000FF00 is pure green, and $000000FF is pure red. $00000000 is black and $00FFFFFF is white.

If the highest-order byte is zero ($00), the color obtained is the closest matching color in the system palette. If the highest-order byte is one ($01), the color obtained is the closest matching color in the currently realized palette. If the highest-order byte is two ($02), the value is matched with the nearest color in the logical palette of the current device context.


 TColorDialog component

Properties	Methods	Tasks

Unit

Dialogs

Description

The TColorDialog component makes a Color dialog box available to your application. The purpose of the dialog box is to allow a user to select a color. When the user selects a color and chooses OK in the dialog box, the user's color selection is stored in the dialog box's Color property, which you can then use to process as you want.

Display the Color dialog box by calling the Execute method.

You can use the Options property to customize how the Color dialog box appears. For example, you can specify that a Help button be included in the dialog box.

In addition to these properties and methods, the TColorDialog component also has the properties and methods that apply to all components and is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Color	HelpContext	Owner

ComponentIndex	Name	Tag

Ctl3D	Options	Top

CustomColors


Methods

 Key methods

Create	Execute	Free

Destroy


TColorDialogOptions type

Unit

Dialogs

Declaration

TColorDialogOption = (cdFullOpen, cdPreventFullOpen, cdShowHelp, cdSolidColor, cdAnyColor);

TColorDialogOptions = set of TColorDialogOption;

Description

The TColorDialogOptions type declares the three options enumerated in the TColorDialogOption type as members of a set used by the Options property of the TColorDialog component.


TColumn object

Properties	Methods

Unit

DBGrids

Description

The TColumn object holds information about how a column in a TDBGrid should look, such as its color, font, and width. TColumn is an item stored in a TDBGridColumns collection.

You don't need to create TColumn objects explicitly, because a column object always recreates its corresponding title object. You can, of course, manipulate TColumn objects at run time if you want to dynamically change the appearance of a TDBGrid. Set the Color property to change the color of the column's contents. Use the Title property to access the TColumnTitle object which has attributes for the column's title. Set the Width property to change the width of the column. Check the AssignedValues property to see which properties have been set.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Alignment	DropDownRows	PickList

ButtonStyle	Field	ReadOnly

Color	FieldName	Title

Font	Width


Methods

 Key methods

Assign	DefaultFont	RestoreDefaults

DefaultAlignment	DefaultReadOnly

DefaultColor	DefaultWidth


TColumnButtonStyle type

Unit

DBGrids

Declaration

type
  TColumnButtonStyle = (cbsAuto, cbsEllipsis, cbsNone);

Description

The TColumnButtonStyle type defines the possible values for the ButtonStyle property of TColumn. It lists the different ways the user can choose values for that column, as described in the following table:

Value	Description

cbsAuto	If the column's field is a lookup field or has a pick list assigned to it, TDBGrid will show a combo box in the column, so the user can drop-down the list to choose a value.

cbsEllipsis	The column will always show an ellipsis button that the user can click to choose a value. Clicking the ellipsis button triggers an OnEditButtonClick event.

cbsNone	Even if the column's field is a lookup field or has a pick list assigned to it, no combo box or ellipsis button is provided to let the user choose a value from a list.


TColumnTitle object

Properties	Methods

Unit

DBGrids

Description

The TColumnTitle object holds information about how the title of a column in a TDBGrid should look, such as its color, font, and caption. TColumnTitle is an item stored in the Title property of a TColumn object.

You don't need to create TColumnTitle objects explicitly, as Delphi will do so for you when you use the Columns Editor at design time. You can, of course, manipulate TColumnTitle objects at run time if you want to dynamically change the appearance of a TDBGrid. Set the Color property to change the color of the title. Change the Alignment property if you don't want titles left-aligned. Change the Caption property to change the title text. Change the Font property to change the font the title is drawn with.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Alignment	Color

Caption	Font


Methods

 Key methods

Assign	DefaultFont	DefaultColor

DefaultAlignment	DefaultCaption	RestoreDefaults


TColumnValues type

Unit

DBGrids

Declaration

type
  TColumnValue = (cvColor, cvWidth, cvFont, cvAlignment, cvReadOnly, cvTitleColor,
                  cvTitleCaption, cvTitleAlignment, cvTitleFont);
  TColumnValues = set of TColumnValue;

Description

The TColumnValues type defines the possible values for the AssignedValues property of TColumn. It lists the possible attributes you can set for the column and its title (TColumnTitle object), as described in the following table:

Value	Description

cvColor	If present in AssignedValues, the column's Color property has been changed from its default value.

cvWidth	If present in AssignedValues, the column's Width property has been changed from its default value.

cvFont	If present in AssignedValues, the column's Font property has been changed from its default value.

cvAlignment	If present in AssignedValues, the column's Alignment property has been changed from its default value.

cvReadOnly	If present in AssignedValues, the column's ReadOnly property has been changed from its default value.

cvTitleColor	If present in AssignedValues, the column title's Color property has been changed from its default value.

cvTitleCaption	If present in AssignedValues, the column title's Caption property has been changed from its default value.

cvTitleAlignment	If present in AssignedValues, the column title's Alignment property has been changed from its default value.

cvTitleFont	If present in AssignedValues, the column title's Font property has been changed from its default value.


 TComboBox component

See also	Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

A TComboBox component is a control that combines an edit box with a list, much like that of a list box. Users can either type text in the edit box or select an item from the list.

When users enter data into the combo box, either by typing text or selecting an item from the list, the value of the Text property changes. Your application can also change the Text property by displaying text for the user in the edit box of the combo box.

The list of items in the list is the value of the Items property. The ItemIndex property indicates which item in the list is selected.

You can add, delete, insert, and move items in the list using the Add, Delete, and Insert methods of the Items object, which is of type TStrings. For example, to add a string to the list, you could write this line of code:

ComboBox1.Items.Add('New item');

Sort the items in the list with the Sorted property.

At run time, you can select all the text in the edit box with the SelectAll method. To find out which text the user selected, or to replace selected text, use the SelText property. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

You can change the style of the combo box or make it an owner-draw control by changing the value of the Style property.

In addition to these properties, methods, and events, the TComboBox component also has the properties, methods, and events that apply to all windowed controls and is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	Hint	SelLength

BoundsRect	ItemHeight	SelStart

Canvas	ItemIndex	SelTSelStartext

Color	Items	ShowHint

ComponentIndex	Left	Showing

Ctl3D	MaxLength	Sorted

Cursor	Name	Style

DragCursor	Owner	TabOrder

DragMode	Parent	TabStop

DropDownCount	ParentColor	Tag

Enabled	ParentCtl3D	Text

Font	ParentFont	Top

Height	ParentShowHint	Visible

HelpContext	PopupMenu	Width


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetTextBuf	SelectAll

Clear	GetTextLen	SendToBack

ClientToScreen	Hide	SetBounds

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy


Events

 Key events

OnChange	OnDrawItem	OnKeyDown

OnClick	OnDropDown	OnKeyPress

OnDblClick	OnEndDrag	OnKeyUp

OnDragDrop	OnEnter	OnMeasureItem

OnDragOver	OnExit	OnStartDrag


See also

Creating an owner-draw control


TComboBoxStyle type

Unit

StdCtrls

Declaration

TComboBoxStyle = (csDropDown, csSimple, csDropDownList, csOwnerDrawFixed, csOwnerDrawVariable);

Description

The TComboBoxStyle type defines the styles of combo boxes. TComboBoxStyle is the type of the combo box control's Style property.


TComponentName type

Unit

Classes

Declaration

TComponentName: string;

Description

The TComponentName type is the type of the Name property for all components.


TConfigMode type

Unit

DB

Declaration

TConfigMode = (cmPersistent, cmSession, cmAll);

Description

The TConfigMode type defines the possible values of the ConfigMode property of the TSession and TDatabase components, as described in the following table:

Value	Description

cmPersistent	Aliases you add are global. (Call SaveConfigFile to make permanent.) GetAliasNames returns only global aliases.

cmSession	Aliases you add are local and can't be saved. (Local aliases are lost when the session ends.) GetAliasNames returns only local aliases.

cmAll	Aliases you add are global. (Call SaveConfigFile to make permanent.) GetAliasNames returns both global and local aliases.


TConsistentAttributes type

Unit

ComCtrls

Declaration

TConsistentAttribute = (caBold, caColor, caFace, caItalic, caSize, caStrikeout, caUnderline, caProtected);

TConsistentAttributes = set of TConsistentAttribute;

Description

The TConsistentAttributes type defines the possible values of the ConsistentAttributes property of the TTextAttributes object. It contains character formatting information for default and selected text of a rich edit control.

TTextAttributes is the type of the DefAttributes and SelAttributes properties of the TRichEdit component.


TControlScrollBar component
TControlScrollBar object

Properties	Methods

Unit

Forms

Description

The TControlScrollBar object is used by the HorzScrollBar and VertScrollBar properties of a form or scroll box to display horizontal and vertical scroll bars users can use to scroll the form or scroll box.

The HorzScrollBar and VertScrollBar objects have nested properties that determine how these scroll bars behave. The Range property determines how far a user can scroll a form or scroll box. Increment determines how many positions the thumb tab on a scroll bar moves when the user clicks on the scroll bar arrows. You can set the position of the thumb tab with the Position property. If you don't want a scroll bar to appear, set the Visible property to False.

If you want to prevent controls from scrolling partially off screen so the user can't scroll them back into view, use the Margin property.

In addition to these properties, the TControlScrollBar object also has the methods that apply to all objects and is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Align	Margin	Range

ComponentIndex	Name	ScrollPos

Increment	Owner	Tag

Kind	Position	Visible


Methods

 Key methods

Create	Destroy	Free


TCopyMode type

Unit

Graphics

Declaration

TCopyMode = Longint;

Description

TCopyMode is the type of the CopyMode property of a TCanvas object.


TCurrencyField component

Properties	Methods	Events

Unit

DBTables

Description

A TCurrencyField component represents a field of a record in a dataset. It is represented as a binary value with a range from (positive or negative) 5.0 * 10-324 to 1.7 * 10308. It has an accuracy of 15 to 16 digits. Use TCurrencyField for fields that hold currency values.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value.

The TCurrencyField component has the properties, methods, and events of the TField component and is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Owner

AsBoolean	DisplayName	Precision

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditFormat	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Value

Currency	IsIndexField	Visible

DataSet	IsNull

DataSize	MaxValue

DataType	MinValue

DisplayFormat	Name


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TCursor type

Unit

Controls

Declaration

TCursor = -32768..32767;

Description

The TCursor type defines the different kinds of standard cursors a component can have. TCursor is the type of the Cursor property and the DragCursor property.


TCustomColors type

Unit

Dialogs

Declaration

TCustomColors = array[0..MaxCustomColors - 1] of LongInt;

Description

The TCustomColors type is an array that holds the color values for the custom colors the user can create using the Color dialog box (TColorDialog component). The MaxCustomColors constant is defined as 16.


TDataAction type

Unit

DB

Declaration

TDataAction = (daFail, daAbort, daRetry);

Description

The TDataAction type defines the possible values you can assign to the Action parameter in the OnDeleteError, OnEditError, and OnPostError events, as described in the following table:

Value	Description

daFail	(The default value of Action.) The error is reported as an exception, as it normally would be.

daAbort	The error is discarded by raising a "silent" EAbort exception.

daRetry	The application goes into a loop, repeating the delete, edit, or post operation until it succeeds or you assign Action daFail or daAbort.


 TDatabase component

Properties	Methods	Events	Tasks

Unit

DB

Description

The TDatabase component is not required for database access, but it provides additional control over factors that are important for client/server applications. If you do not create an explicit TDatabase component for a database, and an application opens a table in the database, then Delphi will create a temporary (virtual) TDatabase component.

DatabaseName is the name of the database connection that can be used by dataset components. In other words, this is the name of the local alias defined by the component that will show up in the DatabaseName drop-down list of dataset components.

AliasName is the name of an existing BDE alias defined with the BDE Configuration Utility. This is where the TDatabase component gets its default parameter settings. This property will be cleared if DriverName is set. The Params property holds the connection parameters for the alias.

DriverName is the name of a BDE driver, such as STANDARD (for dBASE and Paradox), ORACLE, SYBASE, INFORMIX or INTERBASE. This property will be cleared if AliasName is set, because an AliasName specifies a driver type.

The DataSets property of TDatabase is an array of references to the active datasets in the TDatabase. The DatasetCount property is an integer that specifies the number of active datasets.

Set the Connected property to open or close the database. Set KeepConnection to True to avoid having to log in to the server each time the database is opened.

Set LoginPrompt to True to always prompt for user name and password when logging in to the database server.

The TDatabase component controls server transactions. Call StartTransaction to begin a transaction, RollBack to cancel it, or Commit to commit the changes. The TransIsolation property specifies the transaction isolation level to request on the server. The InTransaction property indicates whether a transaction is active (that is, that StartTransaction has been called).

In addition to these properties and methods, this component also has the properties and methods that apply to all components. The TDatabase component is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

AliasName	Handle	Owner

ApplyUpdates	InTransaction	SessionAlias

Connected	IsSQLBased	Params

DatabaseName	KeepConnection	Tag

DatasetCount	Locale	Temporary

Datasets	LoginPrompt	TraceFlags

DriverName	Name	TransIsolation


Methods

 Key methods

Close	Create	Open

CloseDatasets	Destroy	Rollback

Commit	FlushSchemaCache	StartTransaction

Free	ValidateName


Events

 Key events

OnLogin


TDataMode type

Unit

DDEMan

Declaration

TDataMode = (ddeAutomatic, ddeManual);

Description

The TDataMode type contains the types of connect modes used when initiating a DDE conversation. Specify the connect mode in the ConnectMode property.


TDataSetNotifyEvent type

Unit

DB

Declaration

TDataSetNotifyEvent = procedure(DataSet: TDataSet) of object;

Description

The TDataSetNotifyEvent type points to a method that notifies a dataset component that an event has occurred. It is used by all the events of the tables, queries, and stored procedures (TTable, TQuery, and TStoredProc components).


TDataSetState type

Unit

DB

Declaration

TDataSetState = (dsInactive, dsBrowse, dsEdit, dsInsert, dsSetKey, dsCalcFields,
  dsUpdateNew, dsUpdateOld, dsFilter);

Description

The TDataSetState type is the set of values of the State property of a dataset component, as described in the following table:

Value	Description

dsInactive	Dataset not open.

dsBrowse	Navigating between records.

dsEdit	Editing a record.

dsInsert	Inserting or appending a new record.

dsSetKey	Setting key values by manipulating fields for finding records or setting a range.

dsCalcFields	Calculating calculated field values.

dsUpdateNew	Internal state; used when accessing a field's NewValue property.

dsUpdateOld	Internal state; used when accessing a field's OldValue property.

dsFilter	Dataset is processing an OnFilterRecord event.


 TDataSource component

Properties	Methods	Events	Tasks

Unit

DB

Description

TDataSource component is the interface between a dataset component and data-aware controls on forms. TDataSource attaches to a dataset through the Dataset property. Data-aware controls, such as database edit boxes and data grids, attach to a TDataSource through their DataSource properties. Usually there is only one data source for each dataset component, but there can be as many data source components connected to a dataset as you need.

The Dataset property identifies the dataset from which the data is obtained. Set the AutoEdit property to False to prevent the dataset from going into edit mode automatically when the value of an attached data-aware control is modified (you can still call the Edit method to permit modifications). Set the Enabled property to False to clear and disable the data-aware controls. Check the current status of the dataset with the State property. To monitor changes to both the dataset and attached data-aware controls, assign a method to the OnDataChange event. To monitor changes in the dataset's state, assign a method to the OnStateChange event. To update the dataset prior to a post, assign a method to the OnUpdateData event.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components. TDataSource component is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

AutoEdit	Name	Tag

Dataset	Owner

Enabled	State


Methods

 Key methods

Create	Edit

Destroy	Free


Events

 Key events

OnDataChange	OnStateChange	OnUpdateData


TDateField component

Properties	Methods	Events

Unit

DBTables

Description

A TDateField component is an indirect descendent of TComponent. It represents a field of a record in dataset. It represents a value consisting of a date.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value.

The TDateField component has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DataType	IsIndexField

AsBoolean	DisplayLabel	IsNull

AsDateTime	DisplayName	Name

AsFloat	DisplayText	Owner

AsInteger	DisplayWidth	ReadOnly

AsString	EditMask	Required

Calculated	EditMaskPtr	Size

CanModify	FieldName	Tag

DataSet	FieldNo	Text

DataSize	Index	Visible


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TDateTimeField component

Properties	Methods	Events

Unit

DBTables

Description

A TDateTimeField component is an indirect descendent of TComponent. It represents a field of a record in a dataset. It represents a value consisting of a date and time.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value.

The TDateTimeField component has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayFormat	IsNull

AsBoolean	DisplayLabel	Name

AsDateTime	DisplayName	Owner

AsFloat	DisplayText	ReadOnly

AsInteger	DisplayWidth	Required

AsString	EditMask	Size

Calculated	EditMaskPtr	Tag

CanModify	FieldName	Text

DataSet	FieldNo	Value

DataSize	Index	Visible

DataType	IsIndexField


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


 TDBCheckBox component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

TDBCheckBox component is an indirect descendent of TWinControl. A check box presents an option to the user; the user can check it to select the option, or uncheck it to deselect the option. A database check box (TDBCheckBox) is much like an ordinary check box (TCheckBox), except that it is aware of the data in a particular field of a dataset.

You can link a database check box with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the check box's DataSource property. Specify the field in the dataset you want to access as the value of the check box's DataField property.

If the contents of a field in the current record of the dataset equals the string of the ValueChecked property, the database check box is checked. If the contents matches the string specified as the value of the ValueUnchecked property, the check box is unchecked.

When the user checks or unchecks a database check box, the string specified as the value of the ValueChecked or ValueUnchecked property becomes the value of the field in the dataset, as long as the value of the ReadOnly property is False and the dataset is in edit mode. If you want the user to be able to view the data in the field but not modify it, set ReadOnly to True. For more information, see Updating Fields.

If your application doesn't require the data-aware capabilities of TDBCheckBox, use the check box (TCheckBox) component instead to conserve system resources.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Enabled	PopupMenu

Alignment	Font	ReadOnly

AllowGrayed	Height	ShowHint

Caption	HelpContext	Showing

Checked	Hint	State

Color	Left	TabOrder

ComponentIndex	Name	TabStop

Ctl3D	Owner	Tag

Cursor	Parent	Top

DataField	ParentColor	ValueChecked

DataSource	ParentCtl3D	ValueUnchecked

DragCursor	ParentFont	Visible

DragMode	ParentShowHint	Width


Methods

 Key methods

BeginDrag	Focused	ScaleBy

BringToFront	Free	ScreenToClient

CanFocus	GetTextBuf	ScrollBy

ClientToScreen	GetTextLen	SendToBack

Create	Hide	SetBounds

Destroy	Invalidate	SetTextBuf

Dragging	Refresh	Show

EndDrag	Repaint	Update


Events

 Key events

OnClick	OnEnter	OnKeyUp

OnDragDrop	OnExit	OnMouseDown

OnDragOver	OnKeyDown	OnMouseMove

OnEndDrag	OnKeyPress	OnMouseUp


 TDBComboBox component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

A TDBComboBox component is an indirect descendent of TWinControl. It is a data-aware combo box control. It allows the user to change the value of the field of the current record in a dataset either by selecting an item from a list or by typing in the edit box part of the control. The selected item or entered text becomes the new value of the field if the database combo box's ReadOnly property is False. For more information about editing field values, see Updating Fields.

How a database combo box appears and behaves depends on the value of its Style property.

You can link the database combo box with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the combo box's DataSource property. Specify the field in the dataset you want to access as the value of the DataField property.

You specify the values the user can choose from in the combo box with the Items property. For example, if you want the user to choose from five different values in the combo box list, specify five strings as the value of Items. Just as with an ordinary combo box, you can add, delete, and insert items to it using the Add, Delete, and Insert methods of the Items object, which is of type TStrings. For example, to add a string to a database combo box, you could write this line of code:

DBComboBox1.Items.Add('New item');

The ItemIndex property indicates which item in the database combo box is selected.

Sort the items in the list with the Sorted property.

At run time, you can select all the text in the edit box of the database combo box with the SelectAll method. To find out which text the user selected, or to replace selected text, use the SelText property. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Height	ReadOnly

BoundsRect	HelpContext	SelLength

Color	Hint	SelStart

ComponentIndex	ItemHeight	SelText

Ctl3D	ItemIndex	ShowHint

Cursor	Items	Showing

DataField	Left	Sorted

DataSource	Name	Style

DragCursor	Owner	TabOrder

DragMode	Parent	TabStop

DropDownCount	ParentColor	Tag

Enabled	ParentCtl3D	Text

Fields	ParentFont	Top

Font	ParentShowHint	Visible

Handle	PopupMenu	Width


Methods

 Key methods

BeginDrag	EndDrag	ScaleBy

BringToFront	Focused	ScreenToClient

CanFocus	Free	ScrollBy

Clear	GetTextBuf	SelectAll

ClientToScreen	GetTextLen	SendToBack

CopyToClipboard	Hide	SetBounds

Create	Invalidate	SetFocus

CutToClipboard	PasteFromClipboard	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update


Events

 Key events

OnChange	OnDrawItem	OnKeyDown

OnClick	OnDropDown	OnKeyPress

OnDblClick	OnEndDrag	OnKeyUp

OnDragDrop	OnEnter	OnMeasureItem

OnDragOver	OnExit	OnStartDrag


{bml dbctrlgd.bmp} TDBCtrlGrid component
 TDBCtrlGrid component

Properties	Methods	Events

Unit

DBCtrls

Description

TDBCtrlGrid displays multiple records from a data source. Unlike the TDBGrid component, which displays each record in a single row, you control the layout and appearance of each record in a TDBCtrlGrid. Each record is displayed in its own panel; you design one panel at design time and TDBCtrlGrid replicates that panel for each record displayed.

Like all data-aware controls, TDBCtrlGrid's DataSource property tells it where to get the data it displays.

You can resize the panels by setting the PanelHeight and PanelWidth properties. Set the ColCount and RowCount properties to change the dimensions of the grid.

If you want records to be displayed across columns, then wrap to multiple rows, set the grid's Orientation property to roHorizontal. The default of roVertical displays records down then across (in columns).

By default, each record's panel has a raised border. If you don't want a border, set the PanelBorder property to rbNone.

By default, when the grid gets the focus, it shows a dotted focus rectangle around the panel containing the current record. If you don't want a focus rectangle, set the ShowFocus property to False.

If you don't want the user to be able to insert or delete records into the attached dataset, set the AllowInsert or AllowDelete properties to False.

Call the DoKey method to simulate a key press. Add an OnPaintPanel event handler if you want to customize how a panel is painted. TDBCtrlGrid is a direct descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

AllowDelete	DataSource	PanelHeight

AllowInsert	EditMode	PanelIndex

Canvas	Orientation	PanelWidth

ColCount	PanelBorder	RowCount

Columns	PanelCount	ShowFocus


Methods

 Key methods

Create	DoKey	KeyDown

Destroy	GetTabOrderList


Events

 Run-time only          [image] Key events

OnPaintPanel


TDBCtrlGridBorder type

Unit

DBCtrls

Declaration

TDBCtrlGridBorder = (gbNone, gbRaised);

Description

The TDBCtrlGridBorder type defines the possible values for the PanelBorder property of the TDBCtrlGrid component, as described in the following table:

Value	Description

gbNone	No border

gbRaised	Raised border


TDBCtrlGridKey type

Unit

DBCtrls

Declaration

TDBCtrlGridKey = (gkNull, gkEditMode, gkPriorTab, gkNextTab, gkLeft, gkRight, gkUp, gkDown,
  gkScrollUp, gkScrollDown, gkPageUp, gkPageDown, gkHome, gkEnd, gkInsert, gkAppend,   gkDelete, gkCancel);

Description

The TDBCtrlGridKey type defines the possible values for the Key parameter passed to the DoKey method of the TDBCtrlGrid component, as described in the following table:

Value	Description

gkNull	No action

gkEditMode	Toggles EditMode.

gkPriorTab	Moves focus to the control previous in the tab order.

gkNextTab	Moves focus to the control next in the tab order.

gkLeft	Moves one column to the left, scrolling as needed.

gkRight	Moves one column to the right, scrolling as needed.

gkUp	Moves to the previous row, scrolling as needed.

gkDown	Moves to the next row, scrolling as needed.

gkScrollUp	Makes the record in the previous row the current record, without changing position in the grid.

gkScrollDown	Makes the record in the next row the current record, without changing position in the grid.

gkPageUp	Moves to the previous page in the grid.

gkPageDown	Moves to the next page in the grid.

gkHome	Moves to the first record.

gkEnd	Moves to the last record.

gkInsert	Inserts a new record (if AllowInsert is True).

gkAppend	Appends a new record (if AllowInsert is True).

gkDelete	Deletes the current record (if AllowDelete is True).

gkCancel	Cancels any pending changes to an existing or new record.


TDBCtrlGridOrientation type

Unit

DBCtrls

Declaration

TDBCtrlGridOrientation = (goVertical, goHorizontal);

Description

The TDBCtrlGridOrientation type defines the possible values for the Orientation property of the TDBCtrlGrid component, which are described in the following table:

Value	Description

goVertical	Panels go down, then across (in columns)

goHorizontal	Panels go across, then down (in rows)


 TDBEdit component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

A TDBEdit component is an indirect descendent of TWinControl. It is a data-aware edit box with all the capabilities of an ordinary edit box (a TEdit component).

Unlike an ordinary edit box, you can use the database edit box to enter data into a field, or to simply display data from a field in a dataset. Link the database edit box with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the edit box's DataSource property. Specify the field in the dataset you want to access as the value of the DataField property.

Your application can tell if the text displayed in the edit box changed by checking the value of the Modified property. To limit the number of characters users can enter into the edit box, use the MaxLength property.

If you want to prevent the user from modifying the contents of the field linked to the edit box, set the ReadOnly property to True. For more information about editing field values, see Updating Fields.

You can choose to have the text in an edit box automatically selected whenever it becomes the active control with the AutoSelect property. At run time, you can select all the text in the edit box with the SelectAll method. To find out which text in the edit box the user has selected or to replace selected text, use the SelText property. To clear selected text, call the ClearSelection method. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

You can cut, copy, and paste text in an edit box using the CutToClipboard, CopyToClipboard, and PasteFromClipboard methods.

Your application can use an edit box that displays a specified character rather than the actual character typed into it. If the edit box is used to enter a password, onlookers won't be able to read the typed text. Specify the special character with the PasswordChar property.

If you want the edit box to automatically resize to accommodate a change in font size, use the AutoSize property.

If your application doesn't require the data-aware capabilities of TDBEdit, use the TEdit component instead to conserve system resources.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Fields	PasswordChar

AutoSelect	Font	PopupMenu

AutoSize	Height	ReadOnly

BorderStyle	HelpContext	SelLength

BoundsRect	Hint	SelStart

CharCase	IsMasked	SelText

Color	Left	ShowHint

ComponentIndex	MaxLength	Showing

Ctl3D	Modified	TabOrder

Cursor	Name	TabStop

DataField	Owner	Tag

DataSource	Parent	Text

DragCursor	ParentColor	Top

DragMode	ParentCtl3D	Visible

EditText	ParentFont	Width

Enabled	ParentShowHint


Methods

 Key methods

BeginDrag	Focused	ScrollBy

BringToFront	Free	SelectAll

CanFocus	GetSelTextBuf	SendToBack

Clear	GetTextBuf	SetBounds

ClearSelection	GetTextLen	SetFocus

ClientToScreen	Hide	SetSelTextBuf

CopyToClipboard	Invalidate	SetTextBuf

Create	PasteFromClipboard	Show

CutToClipboard	Refresh	Update

Destroy	Repaint	ValidateEdit

Dragging	ScaleBy

EndDrag	ScreenToClient


Events

 Key events

OnChange	OnEndDrag	OnKeyUp

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag


 TDBGrid component

Properties	Methods	Events	Tasks

Unit

DBGrids

Description

The TDBGrid component is an indirect descendent of TWinControl. It can access the data in a database table or query and display it in a grid. Your application can use the data grid to insert, delete, or edit data in the database, or simply to display it.

The most convenient way to move through data in a data grid and to insert, delete, and edit data is to use the database navigator (TDBNavigator) with the data grid.

The Fields property is an array of all the fields in the dataset displayed in the data grid. To determine which field is the currently selected field, use the SelectedField property. Use the FieldCount property to find out how many fields in the dataset are displayed in the data grid.

You can change the appearance and behavior of a data grid by changing the value of the Options property. For example, you can choose to allow the user to use the Tab key to move to a new column, or you can decide to display grid lines between columns, but not between rows.

If you want the user to be able only to view the data and not to edit it, set the ReadOnly property to True. If you want the user to be able to edit the data, set ReadOnly to False. Also, the dataset must be in Edit state, and the ReadOnly property of the data must be False. The user can cancel an edit by pressing Esc.

Users don't really insert or edit the data in a field using the data grid until they move to a different record or close the application. Your application can also post edits using code within event handlers such as OnColExit or OnColEnter.

The value of the TitleFont property determines which font is used to display the column headings.

To customize the order the fields appear in the grid, use the Fields editor.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	DragMode	ParentFont

BorderStyle	EditorMode	ParentShowHint

BoundsRect	Enabled	PopupMenu

Brush	FieldCount	ReadOnly

Canvas	Fields	SelectedField

ClientHeight	FixedColor	SelectedIndex

ClientOrigin	Font	ShowHint

ClientRect	Height	Showing

ClientWidth	HelpContext	TabOrder

Color	Hint	TabStop

Columns	Left	Tag

ComponentIndex	Name	TitleFont

Ctl3D	Options	Top

Cursor	Owner	TopRow

DataSource	Parent	Visible

DefaultDrawing	ParentColor	Width

DragCursor	ParentCtl3D


Methods

 Key methods

BeginDrag	FindComponent	ScreenToClient

BringToFront	Focused	ScrollBy

CanFocus	Free	SendToBack

ClientToScreen	GetTextBuf	SetBounds

Create	GetTextLen	SetFocus

DefaultDrawColumnCell	Hide	SetTextBuf

Destroy	Invalidate	Show

Dragging	Refresh	Update

EndDrag	Repaint	ValidFieldIndex

ScaleBy


Events

 Key events

OnColEnter	OnDrawColumnCell	OnKeyDown

OnColExit	OnDrawDataCell	OnKeyPress

OnColumnMoved	OnEditButtonClick	OnKeyUp

OnDblClick	OnEndDrag	OnStartDrag

OnDragDrop	OnEnter

OnDragOver	OnExit


TDBGridColumns object

Properties	Methods

Unit

DBGrids

Description

The TDBGridColumns object holds a collection of TColumn objects representing all of the columns in a TDBGrid component. Every TDBGrid owns a TDBGridColumns object and exposes it via the Columns property. You can use the Columns Editor to set up column attributes at design time or the Columns property to access TDBGridColumns methods and properties, which in turn expose TColumn objects representing individual columns.

Use the Add method to add new columns at run time. Call the RestoreDefaults method to remove changes from all of the columns. Use the Grid property to see which TDBGrid component owns the object. Use the Items array property to access individual TColumn objects.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Grid	Items	State

Count


Methods

 Key methods

Add	Clear	RebuildColumns

BeginUpdate	EndUpdate	RestoreDefaults


TDBGridColumnsState type

Unit

DBGrids

Declaration

type
  TDBGridColumnsState = (csDefault, csCustomized);

Description

The TDBGridColumnsState type defines the possible values for the State property of TDBGridColumns, as described in the following table:

Value	Description

csDefault	The grid's column objects are the default column objects created using the properties of the dataset's field objects. Changes you make to the column objects are reflected in the field objects, and vice-versa.

csCustomized	The grid's column objects are persistent, which means that they're separate from the dataset's field properties. (You can make changes to persistent columns without affecting any of the corresponding fields.)


TDBGridOptions type

Unit

DBGrids

Declaration

TDBGridOption = (dgEditing, dgAlwaysShowEditor, dgTitles, dgIndicator,   dgColumnResize,dgColLines, dgRowLines, dgTabs, dgRowSelect, dgAlwaysShowSelection,   dgConfirmDelete, dgCancelOnExit);

TDBGridOptions = set of TDBGridOption;

Description

The TDBGridOptions type is a set that defines the possible values of the Options property of the data grid (TDBGrid).


 TDBImage component

Properties	Methods	Events	Tasks

Unit

DBCtrls unit

Description

The TDBImage component is an indirect descendent of TWinControl. It displays a graphic image from a BLOB (binary large object) stored in a field of the current record of a dataset. You can also modify the image if the ReadOnly property is set to False. For more information about editing field values, see Updating Fields

You can link the database image with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the image's DataSource property. Specify the field in the dataset you want to access as the value of the image's DataField property.

You can control when the image appears in the database control with the AutoDisplay property.

You can change the size at which the BLOB is displayed by using the Stretch property.

You can cut, copy, and paste images in the database image control. While your application is running and the database image control has the focus, use the Windows cut, copy, and paste keys (Ctrl+X, Ctrl+C, and Ctrl+V). If you change your mind, you can return to the original state of the database image control by pressing Esc before moving to another record.

If your application doesn't require the data-aware capabilities of TDBImage, use a image control (TImage) instead to conserve system resources.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Font	PopupMenu

AutoDisplay	Handle	ReadOnly

BorderStyle	Height	ShowHint

Center	HelpContext	Stretch

Color	Hint	TabOrder

ComponentIndex	Left	TabStop

Ctl3D	Name	Tag

Cursor	Owner	Top

DataField	Parent	Visible

DataSource	ParentColor	Width

DragCursor	ParentCtl3D

DragMode	ParentFont

Enabled	ParentShowHint


Methods

 Key methods

BeginDrag	EndDrag	Repaint

BringToFront	Focused	ScreenToClient

ClientToScreen	Free	SendToBack

CopyToClipboard	Hide	SetBounds

Create	Invalidate	Show

CutToClipboard	LoadPicture	Update

Destroy	PasteFromClipboard

Dragging	Refresh


Events

 Key events

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnEndDrag	OnKeyUp


 TDBListBox component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

The TDBListBox component is an indirect descendent of TWinControl. It is a data-aware list box. It allows the user to change the value of the field of the current record in a dataset by selecting an item from a list. The selected item becomes the new value of the field. For more information about editing field values, see Updating Fields.

Link the database list box with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the list box's DataSource property. Specify the field in the dataset you want to access as the value of the DataField property.

You specify the values the user can choose from in the list box with the Items property. For example, if you want the user to choose from five different values in the list box, specify five strings as the value of Items. Just as with an ordinary list box, you can add, delete, and insert items in the list box using the Add, Delete, and Insert methods of the Items object, which is of type TStrings. For example, to add a string to a database list box, you could write this line of code:

DBListBox1.Items.Add('New item');

The ItemIndex property indicates which item in the list box is selected. If you want to prevent the user from being able to select an item in the list box, set the ReadOnly property to False.

If your application doesn't require the data-aware capabilities of TDBListBox, use a list box (TListBox) instead to conserve system resources.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Font	ParentFont

BorderStyle	Handle	PopupMenu

BoundsRect	Height	ReadOnly

Brush	HelpContext	SelCount

Canvas	Hint	Selected

Color	ItemIndex	Showing

ComponentIndex	IntegralHeight	Sorted

Ctl3D	ItemHeight	Style

Cursor	Items	TabOrder

DataField	Left	TabStop

DataSource	Name	Tag

DragCursor	Owner	Top

DragMode	Parent	TopIndex

Enabled	ParentColor	Visible

Fields	ParentCtl3D	Width


Methods

 Key methods

BeginDrag	Free	ScreenToClient

BringToFront	GetTextBuf	ScrollBy

CanFocus	GetTextLen	SendToBack

Clear	Hide	SetBounds

ClientToScreen	ItemAtPos	SetFocus

Create	ItemRect	SetTextBuf

Destroy	Invalidate	Show

Dragging	Refresh	Update

EndDrag	Repaint

Focused	ScaleBy


Events

 Key events

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnDrawItem	OnKeyUp

OnEndDrag	OnMeasureItem


 TDBLookupCombo component

Properties	Methods	Events	Tasks

Unit

DBLookup

Description

The DBLookupCombo is a data-aware combo box that "looks up" a value in a lookup table. TDBLookupCombo is provided for backward compatibility. Use TDBLookupComboBox component in Microsoft Windows 95 and Windows NT applications.

For example, imagine that DataSource1 identifies the table called Customers, and DataSource2 identifies the table called Orders. The Orders table contains a CustNo field which has a number that identifies the customer who placed the order. When the user moves through the records of the Orders table, you want the database lookup combo box to display the name of the customer, and you want the drop-down list of the combo box to display all the customer names. You can do this, because Customers also contains a field that identifies the customer by number (CustNo), as well as the customer's name.

To have the combo box look up the customer name, set the DataSource property value of the combo box to DataSource2, which refers to the Orders table. Set the DataField property value to CustNo. The LookupSource is the data source that refers to the table the combo box uses to look up the name of the customer--in this case, DataSource1--because the Customers table contains the name of the customer.

Set the LookupField property to CustNo. LookupField links the two tables on the value that identifies the customer by number. In this example, both the DataField value and the LookupField value have the same field name, but this isn't required. If the Active property of both tables is True, the database combo box displays the value of the CustNo field. You want to see the customer's name--not the customer number--so set the LookupDisplay property to Name, the field that contains the full name of the customer. Now as you move through the records in the Orders table, the name of the customer who placed the order appears in the database lookup combo box.

You can choose to display multiple fields in the drop-down list of the combo box by entering a list of fields to display as the value of the LookupDisplay property. To display the resulting columns the way you want, use the Options property.

If the ReadOnly property is False, the user can select a displayed value in the database lookup combo box and the corresponding value in current record of the primary dataset updates with a new value. Using the Customers and Orders example, when the user selects a customer name in the lookup table using the database lookup combo box, the value of the CustNo field in the primary dataset updates accordingly.

The Style property determines whether the user can edit a selected item in the combo box or enter a new value and therefore change the value in the lookup table, or simply select items without being able to edit them.

The DropDownCount and DropDownWidth properties determine how long and how wide the drop-down list of the combo box is.

The Value property is the string the combo box uses to identify which record in the lookup table to display; it is the contents of the DataField for the current record. The DisplayValue is the actual displayed string in the combo box.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Height	PopupMenu

AutoSelect	HelpContext	ReadOnly

BoundsRect	Hint	SelLength

Color	Left	SelStart

ComponentIndex	LookupDisplay	SelText

Ctl3D	LookupField	ShowHint

Cursor	LookupSource	Showing

DataField	MaxLength	Style

DataSource	Name	TabOrder

DisplayValue	Options	TabStop

DragCursor	Owner	Tag

DragMode	Parent	Text

DropDownCount	ParentColor	Top

DropDownWidth	ParentCtl3D	Value

Enabled	ParentFont	Visible

Font	ParentShowHint	Width


Methods

 Key methods

BeginDrag	EndDrag	ScreenToClient

BringToFront	Focused	ScrollBy

CanFocus	Free	SelectAll

Clear	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

CloseUp	Hide	SetTextBuf

Create	Invalidate	Show

Destroy	Refresh	Update

Dragging	Repaint

DropDown	ScaleBy


Events

 Key events

OnChange	OnEndDrag	OnMouseDown

OnClick	OnEnter	OnMouseMove

OnDblClick	OnExit	OnMouseUp

OnDragDrop	OnKeyDown	OnStartDrag

OnDragOver	OnKeyPress

OnDropDown	OnKeyUp


{bml dbluplt.bmp} TDBLookupComboBox component
 TDBLookupComboBox component

Properties	Methods	Events

Unit

DBCtrls

Description

TDBLookupComboBox lets you provide the user with a convenient drop-down list of lookup items for filling in fields that require data from another dataset.

Set the DataSource property to the data source that will receive the user's selection. Set the DataField to either the field to receive the user's selection or a lookup field. If you set DataField to a lookup field, you don't need to set any other properties, as TDBLookupComboBox is smart enough to pick up the settings it needs from the lookup field.

Set the ListSource property to the data source of the table holding the lookup items. Set KeyField to the field you want copied into DataField. Set ListField to display a field other than KeyField in the combo box.

In addition to these properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Color	ListFieldIndex

Ctl3D	ListSource

DataField	ListVisible

DataSource	ParentColor

DragCursor	ParentCtl3D

DragMode	ParentFont

DropDownAlign	ParentShowHint

DropDownRows	PopupMenu

DropDownWidth	ReadOnly

Enabled	ShowHint

Font	TabOrder

KeyField	TabStop

KeyValue	Text

ListField	Visible


Methods

 Key methods

CloseUp	DropDown


Events

 Key events

OnClick	OnEndDrag	OnKeyUp

OnCloseUp	OnEnter	OnMouseDown

OnDragDrop	OnExit	OnMouseMove

OnDragOver	OnKeyDown	OnMouseUp

OnDropDown	OnKeyPress	OnStartDrag


TDBLookupComboStyle type

Unit

DBLookup

Declaration

TDBLookupComboStyle = (csDropDown, csDropDownList);

Description

The TDBLookupComboStyle determines the kind of combo box. It is the type of the Style property for a database lookup combo box (TDBLookupCombo).


 TDBLookupList component

Properties	Methods	Events	Tasks

Unit

DBLookup

Description

A TDBLookupList component is a data-aware list box that "looks up" a value in a lookup table. TDBLookupList is provided for backward compatibility. Use TDBLookupListBox component in Microsoft Windows 95 and Windows NT applications.

For example, imagine that DataSource1 identifies the table called Books, and DataSource2 identifies the table called BookOrders. The BookOrders table contains a Volume field that use a number to identify the book the customer ordered. When the user moves through the records of the BookOrders table, you want the database lookup list box to display the titles of the books. You can do this, because Books also contains a field that identifies the book by number (Volume), as well as the title of the book.

For the database lookup list box to look up the title of the book, set the DataSource property value of the list box to DataSource2, which refers to the BookOrders table. Set the DataField property value to Volume. The LookupSource is the data source that refers to the table the combo box uses to look up the title of the book--in this case, DataSource1--because the Books table contains the book's title.

Set the LookupField property to Volume. LookupField links the two tables on the value that identifies the book by number. In this example, both the DataField value and the LookupField value have the same field name, but this isn't required. If the Active property of both tables is True, the database list box now displays the value of the Volume field. You want to see the title of the book--not the volume number--so set the LookupDisplay property to Title, the field that contains the title of the book. Now as you move through the records in the BookOrders table, the title of the ordered book appears in the database lookup list box.

You can choose to display multiple fields in the list box by entering the list of fields to display as the value of the LookupDisplay property, separating each field with a semicolon. To display the resulting columns the way you want, use the Options property.

If the ReadOnly property is False, the user can select a displayed value in the database lookup list box and the corresponding value in current record of the primary dataset updates with a new value. Using the Books and BookOrders example, when the user selects a title in the lookup table using the database lookup list box, the value of the CustNo field in the primary dataset updates accordingly.

The Value property is the string the combo box uses to identify which record in the lookup table to display. The DisplayValue is the actual displayed string in the list box.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Fields	ParentFont

BorderStyle	Font	ParentShowHint

BoundsRect	Height	PopupMenu

Color	HelpContext	ReadOnly

ComponentIndex	Hint	SelectedField

Ctl3D	Left	SelectedIndex

Cursor	LookupDisplay	ShowHint

DataField	LookupField	TabOrder

DataSource	LookupSource	TabStop

DisplayValue	Name	Tag

DragCursor	Options	Value

DragMode	Owner	Visible

EditorMode	Parent	Width

Enabled	ParentColor

FieldCount	ParentCtl3D


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

Create	Hide	SetFocus

DefaultDrawColumnCell	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy	ValidFieldIndex

FindComponent


Events

 Key events

OnClick	OnEndDrag	OnKeyPress

OnDblClick	OnEnter	OnKeyUp

OnDragDrop	OnExit	OnStartDrag

OnDragOver	OnKeyDown


{bml dblup.bmp}TDBLookupListBox component
TDBLookupListBox component

Properties	Events

Unit

DBCtrls

Description

TDBLookupListBox is an indirect descendent of TWinControl. It lets you provide the user with a convenient list of lookup items for filling in fields that require data from another dataset.

Set the DataSource property to the data source that will receive the user's selection. Set the DataField to either the field to receive the user's selection or a lookup field. If you set DataField to a lookup field, you don't need to set any other properties, as TDBLookupListBox is smart enough to pick up the settings it needs from the lookup field.

Set the ListSource property to the data source of the table holding the lookup items. Set KeyField to the field you want copied into DataField. Set ListField to display a field other than KeyField in the list box.

In addition to these properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Align	ListFieldIndex

BorderStyle	ListSource

Color	ParentColor

Ctl3D	ParentCtl3D

DataField	ParentFont

DataSource	ParentShowHint

DragCursor	PopupMenu

DragMode	ReadOnly

Enabled	RowCount

Font	ShowHint

KeyField	TabOrder

KeyValue	TabStop

ListField	Visible


Events

 Key events

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnEndDrag	OnKeyUp


TDBLookupListOptions type

Unit

DBLookup

Declaration

TDBLookupListOption = (loColLines, loRowLines, loTitles);

TDBLookupListOptions = set of TDBLookupListOption;

Description

The TDBLookupListOptions type defines the possible values contained in the Options set of a database lookup combo box (TDBLookupCombo) or database lookup list box (TDBLookupList).


 TDBMemo component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

A TDBMemo component is an indirect descendent of TWinControl. It displays text for the user and permits the user display and enter data into a field much like a TDBEdit component. The TDBMemo component permits multiple lines to be entered or displayed, including text BLOBs (binary large objects).

Unlike an ordinary memo control, you can use the database memo to enter data into a field, or to simply display data from a field of the current record in a dataset. Link the database memo with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the memo's DataSource property. Specify the field in the dataset you want to access as the value of the DataField property.

The text in the database memo is the value of the Text property. When the value of Text changes, the new Text value becomes the value of the field for the current record in the dataset. If you just want the user to be able only to view the data in the field and not to change it, set the ReadOnly property to True. For more information about editing field values, see Updating Fields.

Your application can tell if the value of Text changes by checking the value of the Modified property. To limit the number of characters users can enter into the database memo, use the MaxLength property.

You can access the text by line using the Lines property. If you want to work with the text as one chunk, use the Text property. If you want to work with individual lines of text, the Lines property will better suit your needs.

You can add, delete, insert, and move lines in a database memo control using the Add, Delete, and Insert methods of the Lines object, which is of type TStrings. For example, to add a line to a memo, you could write this line of code:

Memo1.Items.Add('Another line is added');

You can cut, copy, and paste text to and from a database memo control using the CutToClipboard, CopyToClipboard, and PasteFromClipboard methods.

If the memo displays a BLOB field, you can control when the text appears in the memo with the AutoDisplay property. You can also load the text using the LoadMemo method.

Several properties affect how the database memo appears and how text is entered. You can choose to supply scroll bars in the memo with the ScrollBars property. If you want the text to break into lines, set WordWrap to True. If you want the user to be able to use tabs in the text, set WantTabs to True.

At run time, you can select all the text in the memo with the SelectAll method. To find out which text in the memo the user has selected, or to replace selected text, use the SelText property. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

If your application doesn't require the data-aware capabilities of TDBMemo, use a memo control (TMemo) instead to conserve system resources.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	HelpContext	SelLength

Alignment	Hint	SelStart

AutoDisplay	Left	SelText

BorderStyle	Lines	ShowHint

Color	MaxLength	Showing

ComponentIndex	Modified	TabOrder

Ctl3D	Name	TabStop

Cursor	Owner	Tag

DataField	Parent	Text

DataSource	ParentColor	Top

DragCursor	ParentCtl3D	Visible

DragMode	ParentFont	WantTabs

Enabled	ParentShowHint	Width

Fields	PopupMenu	WordWrap

Font	ReadOnly

Height	ScrollBars


Methods

 Key methods

BeginDrag	Free	ScreenToClient

BringToFront	GetSelTextBuf	ScrollBy

CanFocus	GetTextBuf	SelectAll

ClientToScreen	GetTextLen	SendToBack

Clear	Hide	SetBounds

Create	Invalidate	SetFocus

Destroy	LoadMemo	SetSelTextBuf

Dragging	Refresh	SetTextBuf

EndDrag	Repaint	Show

Focused	ScaleBy	Update


Events

 Key events

OnChange	OnEndDrag	OnKeyUp

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag


 TDBNavigator component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

The TDBNavigator component (a database navigator) is an indirect descendent of TWinControl. It is used to move through the data in a database table or query, and perform operations on the data, such as inserting a blank record or posting a record. It is used in conjunction with the data-aware controls, such as the data grid, which give you access to the data, either for editing the data, or for simply displaying it.

You link the database navigator with a dataset when you specify a data source component that identifies the dataset as the value of navigator's DataSource property.

The database navigator consists of multiple buttons.

When the user chooses one of the navigator buttons, the appropriate action occurs on the dataset the navigator is linked to. For example, if the user clicks the Insert button, a blank record is inserted in the dataset.

This table describes the buttons on the navigator:

Button	Purpose

First	Sets the current record to the first record in the dataset, disables the First and Prior buttons, and enables the Next and last buttons if they are disabled.

Prior	Sets the current record to the previous record and enables the Last and Next buttons if they are disabled.

Next	Sets the current record to the next record and enables the First and Prior buttons if they are disabled.

Last	Sets the current record to the last record in the dataset, disables the Last and Next buttons, and enables the First and Prior buttons if they are disabled.

Insert	Inserts a new record before the current record, and sets the dataset into Insert and Edit states.

Delete	Deletes the current record and makes the next record the current record.

Edit	Puts the dataset into Edit state so that the current record can be modified.

Post	Writes changes in the current record to the database.

Cancel	Cancels edits to the current record, restores the record display to its condition prior to editing, and turns off Insert and Edit states if they are active.

Refresh	Redisplays the current record from the dataset, thereby updating the display of the record on the form.

Using the VisibleButtons property, you can decide which operations are allowed on the data and when.

You can customize the Help Hints available for the buttons on the database navigator by specifying values in the Hints property.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Height	PopupMenu

BoundsRect	HelpContext	Showing

ComponentIndex	Hint	ShowHint

ConfirmDelete	Hints	TabOrder

Ctl3D	Left	TabStop

Cursor	Name	Tag

DataSource	Owner	Top

DragCursor	Parent	Visible

DragMode	ParentCtl3D	VisibleButtons

Enabled	ParentShowHint	Width


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

BtnClick	GetTextBuf	SendToBack

CanFocus	GetTextLen	SetBounds

ClientToScreen	Hide	SetFocus

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy


Events

 Key events

OnClick	OnEndDrag	OnMouseMove

OnDblClick	OnEnter	OnMouseUp

OnDragDrop	OnExit	OnResize

OnDragOver	OnMouseDown	OnStartDrag


 TDBRadioGroup component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

The TDBRadioGroup component is an indirect descendent of TWinControl. It displays a group of data-aware radio buttons. Only one of the radio buttons can be selected at a time, so the radio buttons present a set of mutually exclusive choices. Using a database radio button group box, you can ensure that the user must enter one of the presented options in a field, or the database radio group box can display the value of data in a field when the field is limited to a few possible values. For example, if only the values Red, Green, and Blue are valid in the field, the group box can have Red, Green, and Blue radio buttons.

Link the database radio group box with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the group box's DataSource property. Specify the field in the dataset you want to access as the value of the group box's DataField property.

The radio buttons are added to the group box when strings are entered as the value of the Items property. The strings entered in the Items property become the captions of the radio buttons if there are no strings in the Values property. If there are strings in the Values property, the first string is associated with the first radio button, the second with the second radio button, and so on. The Values string for a radio button is the value in the field of the current record that selects the radio button.

If the user selects a radio button and the ReadOnly property is False, the Values string for the radio button becomes the contents of the field for the current record in the dataset.

The Value property contains the contents of the field of the current record in the dataset.

You can display the radio buttons in a single column or in multiple columns by setting the value of the Columns property.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Font	ParentShowHint

Caption	Height	PopupMenu

Color	HelpContext	ReadOnly

Columns	Hint	ShowHint

ComponentIndex	ItemIndex	Showing

Ctl3D	Items	TabOrder

Cursor	Left	TabStop

DataField	Name	Tag

DataSource	Owner	Top

DragCursor	Parent	Value

DragMode	ParentColor	Values

Enabled	ParentCtl3D	Visible

Fields	ParentFont	Width


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

ContainsControl	Hide	SetFocus

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy


Events

 Key events

OnChange	OnDragDrop	OnEnter

OnClick	OnDragOver	OnExit

OnDblClick	OnEndDrag	OnStartDrag


{bml tdblabel.bmp} TDBText component
 TDBText component

Properties	Methods	Events	Tasks

Unit

DBCtrls

Description

The TDBText component is an indirect descendent of TGraphicControl. It is a data-aware control that displays text on a form. Your application can display the contents of a field in the current record of a dataset in a database text control, but the user won't be able to modify the field's contents.

Link the database text control with a dataset by specifying the data source component (TDataSource) that identifies the dataset as the value of the label's DataSource property. Specify the field in the dataset you want to access as the value of the label's DataField property.

How the text of the caption aligns within the label is determined by the value of the Alignment property. You can have the text control resize automatically to fit a changing caption if you set the AutoSize property to True. If you prefer to have the text wrap, set WordWrap to True.

If you want a database text control to appear on top of a graphic, but you want to be able to see through the control so that part of the graphic isn't hidden, set the Transparent property to True.

If your application doesn't require the data-aware capabilities of TDBText, you should use the label component (TLabel) instead to conserve system resources.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all controls.


Properties

 Run-time only          [image] Key properties

Align	Enabled	ParentShowHint

Alignment	Fields	PopupMenu

AutoSize	Font	ShowHint

BoundsRect	Height	Tag

Color	Hint	Top

ComponentIndex	Left	Transparent

Cursor	Name	Visible

DataField	Owner	Width

DataSource	Parent	WordWrap

DragCursor	ParentColor

DragMode	ParentFont


Methods

 Key methods

BeginDrag	EndDrag	Repaint

BringToFront	Free	ScreenToClient

CanFocus	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

Create	Hide	SetTextBuf

Destroy	Invalidate	Show

Dragging	Refresh	Update


Events

 Key events

OnClick	OnDragOver	OnMouseMove

OnDblClick	OnEndDrag	OnMouseUp

OnDragDrop	OnMouseDown	OnStartDrag


 TDdeClientConv component

Properties	Methods	Events	Tasks

Unit

DDEMan

Description

A TDdeClientConv component establishes a DDE conversation with a DDE server application. Use it in conjunction with a TDDEClientItem component to make your application a DDE client.

To link to a DDE server application, define the DDE conversation by specifying the server application name in the DDEService property and the topic of the DDE conversation in the DDETopic property. To establish a link at design time, click the ellipsis (...) button for DDEService or DDETopic in the Object Inspector and choose Paste Link in the DDE Info dialog box. To establish a link at run time, specify the service and topic with the Setlink method.

To send data to the DDE server, use the PokeData or ExecuteMacro methods. PokeData sends a text string to the linked item in the DDE server. ExecuteMacro sends a text string containing a macro command to be processed by the DDE server.

You can change the way a DDE conversation is established by specifying the ConnectMode property. If ConnectMode is ddeAutomatic, the client attempts to establish the conversation when the TDdeClientConv component is created at run time. If ConnectMode is ddeManual, you must write code that executes the OpenLink method to establish the DDE conversation.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components. A TDdeClientConv component is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

ComponentIndex	DDEService	Owner

ConnectMode	DDETopic	ServiceApplication

Conv	FormatChars	Tag

DdeFmt	Name


Methods

 Key methods

CloseLink	Free	RequestData

Create	OpenLink	StartAdvise

Destroy	PasteLink	SetLink

ExecuteMacro	PokeData

ExecuteMacroLines	PokeDataLines


Events

 Key events

OnClose	OnOpen


 TDDEClientItem component

Properties	Methods	Events	Tasks

Unit

DDEMan

Description

A TDDEClientItem component defines the item of a DDE conversation. Use it in conjunction with a TDdeClientConv component to make your application a DDE client.

To link to a DDE conversation, specify the name of a TDdeClientConv component in the DDEConv property. The DDE item of the conversation should be specified in the DDEItem property. If the TDdeClientConv component has established a link with a DDE server, the server will automatically and continually update the client until the conversation is terminated.

The actual text data to exchange with the DDE server is specified in the Text property. When the server updates your DDE client, the new data will be automatically stored in the Text property. Whenever Text is updated, an OnChange event occurs. For text data longer than the 255 character limit of Text, use the Lines property to specify the text data to exchange.

In addition to these properties and events, this component also has the properties and methods that apply to all components. A TDDEClientItem component is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Destroy	Tag

Create	Lines	Text

DDEConv	Name

DDEItem	Owner


Methods

 Key methods

Create	Destroy	Free


Events

 Key events

OnChange


 TDDEServerConv component

Properties	Methods	Events	Tasks

Unit

DDEMan

Description

A TDDEServerConv component establishes a DDE conversation with a DDE client application. Use it in conjunction with a TDDEServerItem component to make your application a DDE server.

If the DDE client sends a macro to your DDE server application, an OnExecuteMacro event occurs. You should write code in the OnExecuteMacro event handler to process this macro.

Using a TDDEServerConv component is optional. If you don't use a TDDEServerConv component, the client can still request an update directly from the TDDEServerItem component.

If you use a TDDEServerConv component, the DDE topic of the conversation is the value of the Name property of the TDDEServerConv component. If you don't use a TDDEServerConv component, the DDE topic of the conversation is the value of the Caption property of the form containing the TDDEServerItem component.

You should use a TDDEServerConv component with a TDDEServerItem component when the client might send a macro, or when the Caption of the form containing the TDDEServerItem might not be unique or constant at run time.

In addition to these properties and events, this component also has the properties and methods that apply to all components. A TDDEServerConv component is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Owner

Name	Tag


Methods

 Key methods

Create	Destroy	Free


Events

 Key events

OnClose	OnExecuteMacro	OnOpen


 TDDEServerItem component

Properties	Methods	Events	Tasks

Unit

DDEMan

Description

A TDDEServerItem component defines the item of a DDE conversation. Use it by itself, or optionally, with a TDDEServerConv component to make your application a DDE server.

To use a TDDEServerItem component with a TDDEServerConv component, specify the name of a TDDEServerConv component in the ServerConv property.

The actual text data to exchange with the DDE client is specified in the Text property. When the client requests an update, your server sends the contents of the Text property to the client. When the Text property is modified, either by your own application or when the client pokes data, an OnChange event occurs. For text data longer than the 255-character limit of Text, use the Lines property to specify the data to exchange.

To test a link with a DDE client, use the CopyToClipboard method. This method will copy the contents of Text (or Lines), as well as DDE link information to the Clipboard. Then, if the DDE client can paste links, you can activate the client and paste the DDE data into the client application.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components. A TDDEServerItem component is a direct descendent of TComponent.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Owner	Text

Lines	ServerConv

Name	Tag


Methods

 Key methods

CopyToClipboard	Destroy

Create	Free


Events

 Key events

OnChange	OnPokeData


 TDirectoryListBox component

Properties	Methods	Events	Tasks

Unit

FileCtrl

Description

The TDirectoryListBox component is an indirect descendent of TWinControl. It is a specialized list box that is aware of the directory structure of the current drive. When the application runs, the user can use the directory list box to change directories, which changes the value of the Directory property.

The Drive property determines on which drive the list box displays the directory structure. When the value of Drive changes, the Directory value also changes to the current directory on the specified drive.

You can synchronize a directory list box with a file list box (TFileListBox), so that when the user uses a directory list box to change directories, the file list box displays the files in the new directory. This is the event handler for the OnChange event for the directory list box:

procedure TForm1.DirectoryListBox1Change(Sender: TObject);

begin

  FileListBox1.Directory := DirectoryListBox1.Directory;

end;

Note:	An OnChange event for a directory list box occurs when the user selects a new directory with the mouse or when the user move the selection bar and presses enter.

Another way to accomplish the same thing is to assign a file list box as the value of the FileList property. If you use the DirLabel property, you can have the caption of the label display the current directory.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Font	ParentShowHint

BoundsRect	Handle	PopupMenu

Color	Height	Selected

Columns	HelpContext	ShowHint

ComponentIndex	Hint	Showing

Ctl3D	IntegralHeight	Tag

Cursor	ItemHeight	Top

Directory	Left	TabOrder

DirLabel	Name	TabStop

DragCursor	Owner	TopIndex

DragMode	Parent	Visible

Drive	ParentColor	Width

Enabled	ParentCtl3D

FileList	ParentFont


Methods

 Key methods

BeginDrag	Free	ScaleBy

BringToFront	GetItemPath	ScreenToClient

CanFocus	GetTextBuf	ScrollBy

Clear	GetTextLen	SendToBack

ClientToScreen	Hide	SetBounds

Create	Invalidate	SetFocus

Destroy	ItemAtPos	SetTextBuf

Dragging	ItemRect	Show

EndDrag	Refresh	Update

Focused	Repaint


Events

 Key events

OnClick	OnEndDrag	OnKeyUp

OnDblClick	OnEnter	OnMouseDown

OnDragDrop	OnExit	OnMouseMove

OnDragOver	OnKeyDown	OnMouseUp

OnDropDown	OnKeyPress	OnStartDrag


TDisplayCode type

Unit

ComCtrls

Declaration

TDisplayCode = (drBounds, drIcon, drLabel, drSelectBounds);

Description

The TDisplayCode type is used to specify the display type when using the DisplayRect method to retrieve the bounding rectangle for all or part of an item in the current list view.


TDragMode type

Unit

Controls

Declaration

TDragMode = (dmManual, dmAutomatic);

Description

The TDragMode type defines the values for the DragMode property of controls.


TDragState type

See also	Example

Unit

Controls

Declaration

TDragState = (dsDragEnter, dsDragLeave, dsDragMove);

Description

The TDragState type specifies the drag state of a dragged control in relationship to another control. It is the type of the State parameter used in OnDragOver event handlers. These are the possible states:

Value	Meaning

dsDragEnter	The state a drag object is in when it enters a control that allows the drag object to be dropped. dsDragEnter is the default state.

dsDragMove	The state a drag object is in when it is moved within a control that allows the drag object to be dropped.

dsDragLeave	The state a drag object is in when it leaves a control that would allow the drag object to be dropped


Example

This code is a OnDragOver event handler that won't allow a label control to be dropped on a panel control and stops the dragging of the label as soon as the user drags the label onto the panel:

procedure TForm1.Panel1DragOver(Sender, Source: TObject; X, Y: Integer;

  State: TDragState; var Accept: Boolean);

begin

  Accept := False;

  if (Source is TLabel) and (State = dsDragEnter) then

    (Source as TLabel).EndDrag(False);

end;

The Source parameter is the label being dragged, the Sender parameter is the panel control, and the State parameter is the drag state.


See also

TDragOverEvent type


 TDrawGrid component

Properties	Methods	Events	Tasks

Unit

Grids

A TDrawGrid component is an indirect descendent of TWinControl. It is a grid control that permits the display of an existing data structure in column and row format.

The grid uses the OnDrawCell event to fill in the cells of the grid. If the DefaultDrawing property is False, the code you write in the OnDrawCell event handler draws in the cells. If DefaultDrawing is True, the contents of the cells are automatically drawn using the default background and the Canvas of the grid and is initialized so that the background color is the brush color and the font has the default font color. If the cell is part of the selection, the background color is changed to the selection color and the pen color is changed to the selected text color.

You can obtain the drawing area of a cell with the CellRect method. The MouseToCell method returns the column and row coordinates of the cell the mouse cursor is in.

You can determine which cell is selected in the grid by checking the value of the Selection property.

You can change the appearance and behavior of a data grid by changing the value of the Options property. For example, you can choose to allow the user to use the Tab key to move to a new column, you can decide to display grid lines between columns but not between rows, or let the user edit the data displayed in the grid.

Several properties affect the appearance of the grid. The DefaultColWidth and DefaultRowHeight properties determine the default widths and heights of the columns and rows. You can change the width or height of a specific column or row with the ColWidths and RowHeights properties. You can choose to have fixed or nonscrolling columns and rows with the FixedCols and FixedRows properties, and you can assign the color of the fixed columns and rows with the FixedColor property. Set the width of the grid lines with the GridLineWidth property. Add scroll bars to the grid with the ScrollBars property.

You can determine which row is currently the top row in the grid, or set a specified row to be the top row with the TopRow property. To determine which column is the first visible column in the grid, use the LeftCol property. The values of the VisibleColCount and VisibleRowCount properties are the number of columns and rows visible in the grid.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	FixedColor	ParentShowHint

BorderStyle	FixedCols	PopupMenu

BoundsRect	FixedRows	Row

Brush	Font	RowCount

Canvas	GridHeight	RowHeights

Col	GridLineWidth	ScrollBars

ColCount	GridWidth	Selection

Color	Height	ShowHint

ColWidths	HelpContext	Showing

ComponentIndex	Hint	TabOrder

Ctl3D	Left	TabStop

Cursor	LeftCol	TabStops

DefaultColWidth	Name	Tag

DefaultDrawing	Options	Top

DefaultRowHeight	Owner	TopRow

DragCursor	Parent	Visible

DragMode	ParentColor	VisibleColCount

EditorMode	ParentCtl3D	VisibleRowCount

Enabled	ParentFont	Width


Methods

 Key methods

BeginDrag	Dragging	Repaint

BringToFront	EndDrag	ScaleBy

CanFocus	Focused	ScreenToClient

CellRect	Free	ScrollBy

ClassName	GetTextBuf	SendToBack

ClassParent	GetTextLen	SetBounds

ClassType	Hide	SetFocus

ClientToScreen	Invalidate	SetTextBuf

Create	MouseToCell	Show

Destroy	Refresh	Update


Events

 Key events

OnClick	OnExit	OnMouseUp

OnColumnMoved	OnGetEditMask	OnRowMoved

OnDblClick	OnGetEditText	OnSelectCell

OnDragDrop	OnKeyDown	OnSetEditText

OnDragOver	OnKeyPress	OnStartDrag

OnDrawCell	OnKeyUp	OnTopLeftChanged

OnEndDrag	OnMouseDown

OnEnter	OnMouseMove


 TDriveComboBox component

See also	Properties	Methods	Events	Tasks

Unit

FileCtrl

Description

The TDriveComboBox component is an indirect descendent of TWinControl. It is a specialized combo box that displays all the drives available when the application runs. When the user uses the combo box to select another drive, the value of the Drive property changes.

You can specify whether the text in the drive combo box is uppercase or lowercase with the TextCase property.

If your application uses the drive combo box with a directory list box and a file list box, you can synchronize them with this code written in the drive combo box OnChange event handler and in the directory list box OnChange event handler:

procedure TForm1.DriveComboBox1Change(Sender: TObject);

begin

  DirectoryListBox1.Drive := DriveComboBox1.Drive;

end;

procedure TForm1.DirectoryListBox1Change(Sender: TObject);

begin

  FileListBox1.Directory := DirectoryListBox1.Directory;

end;

Now when the user selects a new drive using the drive combo box, the directory list box and the file list box are updated also.

Another way to accomplish the same task is to set the DirList property of the drive combo box and the FileList property of the directory list box.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	HelpContext	SelStart

BoundsRect	Hint	SelText

Color	ItemIndex	Showing

ComponentIndex	Items	TabOrder

Ctl3D	Left	TabStop

Cursor	Name	Tag

DirList	Owner	Text

DragCursor	Parent	TextCase

DragMode	ParentColor	Top

Drive	ParentCtl3D	Visible

Enabled	ParentFont	Width

Font	PopupMenu

Height	SelLength


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetTextBuf	SelectAll

Clear	GetTextLen	SendToBack

ClientToScreen	Hide	SetBounds

Create	Invalidate	SetFocus

Destroy	Refresh	SetTextBuf

Dragging	Repaint	Show

EndDrag	ScaleBy	Update


Events

 Key events

OnChange	OnDragOver	OnExit

OnClick	OnDropDown	OnKeyDown

OnDblClick	OnEndDrag	OnKeyPress

OnDragDrop	OnEnter	OnKeyUp

OnStartDrag


See also

TDirectoryListBox component

TFileListBox component


TDuplicates type

Unit

Classes

Declaration

TDuplicates = (dupIgnore, dupAccept, dupError);

Description

The TDuplicates type defines the possible values of the Duplicates property of a string list object (TStringList).


 TEdit component

See also	Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

TEdit component is an indirect descendent of TWinControl. Use a TEdit component to put a standard Windows edit box control on your form. Edit boxes are used to retrieve information from the user, because the user can type data into an edit box. Edit boxes can also display information to the user.

When users enter data into an edit box or the application displays information to the user in the edit box, the value of the edit box's Text property changes. Your application or OnChange event can tell if the value of Text changes by checking the value of the Modified property. To limit the number of characters users can enter into the edit box, use the MaxLength property.

You can specify whether the text in the edit box is uppercase and lowercase with the CharCase property.

If you want to prevent the user from changing the value of the Text property, set the ReadOnly property to True.

You can choose to have the text in an edit box automatically selected whenever it becomes the active control with the AutoSelect property. At run time, you can select all the text in the edit box with the SelectAll method. To find out which text in the edit box the user has selected or to replace selected text, use the SelText property. To clear selected text, call the ClearSelection method. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

You can cut, copy, and paste text to and from an edit box using the CutToClipboard, CopyToClipboard, and PasteFromClipboard methods.

Your application can replace the characters typed into the edit box with another specified character. If the edit box is used to enter a password, for example, onlookers won't be able to read the typed characters. Specify the replacement character with the PasswordChar property.

If you want the edit box to automatically resize to accommodate a change in font size, use the AutoSize property.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	HideSelection	ReadOnly

AutoSelect	Hint	SelLength

AutoSize	Left	SelStart

BorderStyle	MaxLength	SelText

CharCase	Modified	ShowHint

Color	Name	Showing

ComponentIndex	OEMConvert	TabOrder

Ctl3D	Owner	TabStop

Cursor	Parent	Tag

DragCursor	ParentColor	Text

DragMode	ParentCtl3D	Top

Enabled	ParentFont	Visible

Font	ParentShowHint	Width

Height	PasswordChar

HelpContext	PopupMenu


Methods

 Key methods

BeginDrag	FindComponent	ScreenToClient

BringToFront	Free	ScrollBy

ClientToScreen	GetSelTextBuf	SelectAll

Clear	GetTextBuf	SendToBack

ClearSelection	GetTextLen	SetBounds

CopyToClipboard	Hide	SetFocus

CutToClipboard	Invalidate	SetSelTextBuf

Create	PasteFromClipboard	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy


Events

 Key events

OnChange	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnEndDrag	OnKeyUp


See also

TDBEdit component

TComboBox component


TEditCharCase type

Unit

StdCtrls

Declaration

TEditCharCase = (ecNormal, ecUpperCase, ecLowerCase);

Description

The TEditCharCase type defines the possible values for the CharCase property of an edit box (TEdit).


Temporary property

See also	Example

Applies to

TDataBase component

Declaration

property Temporary: Boolean;

Description

Run-time only. The Temporary property is True if the TDatabase component was created because none existed when a database table was opened. Such a database will automatically be destroyed when the table or query is closed. You can set Temporary to False so that it will be preserved until you explicitly free it with Free. If you explicitly created the TDatabase component, then Temporary will be False, but you can set it to be True and it will automatically be freed when the last dataset linked to it is closed.


Example

Table1.Database.Temporary := False;


See also

Database property


Terminate method

Applies to

TApplication component, TThread object

Description

Terminate method for Applications

Terminate method for Threads


Terminate method for TThread objects
Terminate method

See also

Applies to

TThread object

Declaration

procedure Terminate;

Description

The Terminate method signals your thread to terminate by setting the Terminated property to True. (Your thread's Execute method or methods Execute calls should check Terminated and exit when it's True.)


See also

Execute method

Terminated property


Terminate method for Applications
Terminate method

See also	Example

Applies to

TApplication component

Declaration

procedure Terminate;

Description

The Terminate method performs an orderly shutdown of the application. Terminate is not immediate.


Example

This example uses a button on a form. When the user clicks the button, a message box appears, asking the user if the application should terminate. If the user chooses Yes, the application ends.

procedure TForm1.Button1Click(Sender: TObject);

begin

  if MessageDlg('Ternminate the application?', mtConfirmation,

    [mbYes, mbNo], 0) = mrYes then

      Application.Terminate;

end;


See also

Run method

Terminated property


Terminated property

See also	Example

Applies to

TApplication component

Declaration

property Terminated: Boolean;

Description

Read and run-time only. The Terminated property determines whether the application has received the Windows WM_QUIT message, which then terminates the application. Your Delphi application receives this message usually because the main window of the application has closed, or the Terminate method has been called, thereby requiring windows to quit the application.

The Terminated property is usually used when calling the ProcessMessages method so that your application doesn't attempt to process Windows messages after the application has quit.


Example

The application calls the ProcessMessages method if the application has not received the message from Windows to quit executing:

if Application.Terminated = False then

  Application.ProcessMessages;

  ...


See also

ProcessMessages method

Run method

Terminate method


Text property

Applies to

TOutlineNode, TParam ,TTreeNode, TStrings, TStringList, THeaderSection objects; TComboBox, TDBComboBox, TDBEdit, TDBMemo, TDDEClientItem, TDDEServerItem, TDriveComboBox, TEdit, TFilterComboBox, TMaskEdit, TMemo, TQuery, TBCDField, TBooleanField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TIntegerField, TSmallintField, TStringField, TTimeField, TWordField component

Description

The Text property specifies a text string to appear in a component or object.

Text Property for Edit Boxes and Memo Controls

Text Property for Combo Boxes

Text Property for Outline Nodes and Tree Nodes

Text Property for DDE Items

Text Property for Query Components

Text Property for TParam Objects

Text Property for Field Components

Text Property for TStrings and TStringList Objects

Text Property for Header Sections

Text Property for Status Panels


Text property

See also	Example

Applies to

TDBEdit, TDBMemo, TEdit, TMaskEdit component

Declaration

property Text: TCaption;

Description

The Text property of a component determines the text that appears within an edit box or memo control. The default text is the name of the control. Your application can use the value of Text as input into the application, or to display data to the user.

The value of the Text property of a mask edit box (TMaskEdit) or database edit box (TDBEdit) or database memo (TDBMemo) includes the text and the literal mask characters specified with the EditText property if the user chooses to save the mask characters with the text. If the mask characters are not saved, the text does not include them.

The Text property of a database edit box or database memo is available at run time only. You should seldom assign a new value to the Text property of a database edit box or memo. If the dataset is read only when the new value is assigned to Text, the contents of the field won't change. Instead, you should change the value of the underlying field by using the Fields property of the edit box. For example,

DBEdit1.Field.AsString := 'New value';


Example

This example uses an edit box, a list box, and a button named Add on a form. Each time the user clicks the Add button, the text in the edit box is added to the list in the list box:

procedure TForm1.AddClick(Sender: TObject);

begin

  ListBox1.Items.Add(Edit1.Text);

end;


See also

GetSelTextBuf method

GetTextBuf method

SetTextBuf method

SetSelTextBuf method


Text property

See also	Example

Applies to

TComboBox, TDBComboBox component

Declaration

property Text: string;

Description

The value of the Text property is the first item that appears in the combo box when the application runs. For simple combo boxes, the user can change the value of Text by entering a new value.

For other types of combo boxes, the value of Text is read only and accessible only at run time. The value of the Drive property determines the value of the Text property in a drive combo box. The value of the Filter property determines the value of the Text property in a filter combo box. If the Filter property specifies multiple filters, the first filter in the Filter string appears first in the filter combo box.

For the database lookup combo box, Text is the value of the field of the current record.


Example

The following code stores the value of the first item of a combo box in the Text property in the OnCreate event handler of the form containing the combo box. The first item will be displayed in the combo box at run time.

procedure TForm1.FormCreate(Sender: TObject);

begin

  ComboBox1.Text := ComboBox1.Items[0];

end;


See also

Drive property

Filter property


Text property

See also	Example

Applies to

TOutlineNode, TTreeNode objects;

Declaration

property Text: string;

Description

The Text property contains the string that identifies an outline item or a tree node. This string is displayed in the outline or tree view. For an outline node, the value of Text can be assigned directly or can be set by the Lines property of the TOutline component. If set with the Lines property, each line, minus any leading spaces or tabs, is assigned to the Text property of an individual TOutlineNode object. For tree nodes, the value of Text can be assigned directly or can be set by the Items property of the TTreeView component.


Example

The following code should be attached to the OnClick event handler of an TOutline component. When the value of the Text of the SelectedItem is 'Aqua', the Color of the outline becomes clAqua.

procedure TForm1.Outline1Click(Sender: TObject);

begin

  if Outline1.Items[Outline1.SelectedItem].Text = 'Aqua' then

    Outline1.Color := clAqua;

end;


See also

Data property


Text property

Applies to

TDDEClientItem, TDDEServerItem component

Declaration

property Text: string;

Description

The Text property contains the text data to exchange in a DDE conversation. For TDDEClientItem components, Text specifies the text that is updated by the DDE server application. For TDDEServerItem components, Text specifies the text that is sent to any DDE clients when the value of Text changes or when a client requests an update. When Text is changed, an OnChange event occurs.

Text corresponds to the Lines property. Whenever the value of Text or Lines is changed, the other is updated so that the first line of Lines is always equal to Text.

If the Text property is of a TDDEClientItem component, you can also send the text in Text directly to the DDE server by poking data with the PokeData method.

If the Text property is of a TDDEServerItem component, the DDE client can change Text by poking data. The poked data replaces the contents of Text and an OnChange event occurs.


Example

The following code assigns the value to the Text property of DDEClientItem1 to the Caption of Label1. This code is executed in the OnChange event handler of DDEClientItem1, so whenever the client is updated, the new data from the server is displayed.

procedure TForm1.DdeClientItem1Change(Sender: TObject);

begin

  Label1.Caption := DDEClientItem1.Text

end;


Text property

See also	Example

Applies to

TQuery component

Declaration

property Text: PChar;

Description

Run-time and read only. The Text property holds the actual text of the SQL query sent to the Borland Database Engine. In general, you should not need to examine this property. However, if you encounter problems with an SQL statement, you may want to inspect the Text property to be sure that the statement is as expected.


Example

var

  ActualText: PChar;

  Buf: array [0..20] of Char;

...

  ActualText := Query1.Text;

  repeat

    StrLCopy(Buf, ActualText, SizeOf(Buf));

    WriteLn(Buf);

    if StrLen(ActualText) > 20 then Inc(ActualText, 20)

    else Break;

  until False;


See also

SQL property


Text property

Example

Applies to

TBCDField, TBooleanField, TCurrencyField, TDateField, TDateTimeField, TFloatField, TIntegerField, TSmallintField, TStringField, TTimeField, TWordField component

Declaration

property Text: string;

Description

Run-time only. Text contains the string value of the field a data-aware control uses for display when the control is in edit mode. Data-aware controls such as TDBEdit rely on Text to provide the editing format for each field.

You can control the strings returned by Text by assigning an OnGetText event handler, or you can accept Delphi defaults, which depend on the field's data type.

For TStringField, the AsString property is returned.

For TIntegerField, TSmallintField, and TWordField, if EditFormat or DisplayFormat (in that order) is assigned a value, FloatToTextFmt is called. Otherwise, Str is called.

For TBCDField and TFloatField, FloatToTextFmt is called with value of EditFormat or DisplayFormat (in that order).

For a TCurrencyField, if EditFormat or DisplayFormat (in that order) is assigned a value, FloatToTextFmt is called. Otherwise, FloatToTextFmt is called with the ffCurrency flag and CurrencyDecimals variable.

For a TDateTimeField, DateTimeToStr is called with the value of DisplayFormat.

For a TDateField, DateTimeToStr is called with the DisplayFormat property, except that the ShortDateFormat variable is substituted if DisplayFormat is unassigned. For a TTimeField, DateTimeToStr is called with the DisplayFormat property, except that the LongTimeFormat variable is substituted if DisplayFormat is unassigned.


Example

Edit.Text := Field1.Text;


Text property

See also	Example

Applies to

TParam objects

Declaration

property Text: string;

Description

The Text property is similar to the AsString property. Accessing the Text property attempts to convert the current data to a string value and returns that value. If the current data is NULL, the value is an empty string.


Example

{ Assign '1221' to the CustNo parameter }

Parameters.ParamByName('CustNo').Text := '1221';


See also

TFieldType type

AsString property

DateToStr function

TimeToStr function

DateTimeToStr function

IntToStr function

FloatToStr function

StrToInt function

StrToFloat function

StrToDate function

StrToTime function

StrToDateTime function

TDateTime type


Text property for header sections
Text property

See also

Applies to

THeaderSection object

Declaration

property Text: string;

Description

The Text property contains the string that identifies a particular header in a THeaderControl. The value of Text can be assigned directly or set under the Sections property of the header control. Sections brings up dialog box in which to add, delete, or edit header sections.


See also

Sections property


Text property for status panels
Text property

See also

Applies to

TStatusPanel object

Declaration

property Text: string;

Description

The Text property contains the string that identifies a particular panel in a TStatusBar control. The value of Text can be assigned directly or can be set under the Panels property of the status bar. In the Object Inspector, Panels brings up dialog box in which to add, delete, or edit status panels. If the SimplePanel property of the status bar is set to True then the status bar displays the string contained in its SimpleText property. If SimplePanel is False then the multiple panels are displayed along with the Text for each.


See also

Panels property

SimplePanel property

SimpleText property

Items property


Text property for status panels
Text property

See also

Applies to

TStringList, TStrings objects

Declaration

property Text: string;

Description

The Text property gets and sets the strings of the string list separated by #13, #10 or #0 (carriage return, line feed and null). When getting the list of strings from the string list, each string is separated by a #13 and #10 (carriage return and line feed). When setting Text, a string is added at the beginning and when a #13, #10 or #0 is encountered.


See also

Values property

Names property

CommaText property


TextCase property

Example

Applies to

TDriveComboBox component

Declaration

property TextCase: TTextCase;

Description

The TextCase property determines if the volume name in the Text property appears in uppercase or lowercase. These are the possible values:

Value	Meaning

tcLowerCase	The volume name specified in the Text property is displayed in lowercase letters.

tcUpperCase	The volume name specified in the Text property is displayed in uppercase letters.

The default value is tcLowerCase. If you use the Object Inspector to change the value to tcUpperCase, you won't see the results until your application runs.


Example

Assuming a drive combo box exists on the form, this code displays the volume name in the drive combo box in uppercase letters when the form appears:

procedure TForm1.FormCreate(Sender: TObject);

begin

  DriveComboBox1.TextCase := tcUpperCase;

end;


TextHeight method

See also	Example

Applies to

TCanvas object

Declaration

function TextHeight(const Text: string): Integer;

Description

TextHeight returns the height in pixels of the string passed in Text when rendered in the current font. You can use TextHeight to specify whether the entire string will appear in a given space.


Example

This example displays the height of a text string in the current font of the canvas in an edit box on the form:

procedure TForm1.FormCreate(Sender: TObject);

var

  L: LongInt;

begin

  L := Canvas.TextHeight('Object Pascal is the best');

  Edit1.Text := IntToStr(L) + ' pixels in height';

end;


See also

Font property

TextWidth method


TextOut method

See also	Example

Applies to

TCanvas object

Declaration

procedure TextOut(X, Y: Integer; const Text: string);

Description

TextOut draws the string contained in Text on the canvas using the current font, with the upper left corner of the text at the point (X, Y).


Example

This example displays a text string at a specified position on the form when the user clicks the button on the form:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Canvas.TextOut(20, 20, 'Delphi makes Windows programming easy');

end;


See also

TextRect method


TextRect method

See also	Example

Applies to

TCanvas object

Declaration

procedure TextRect(Rect: TRect; X, Y: Integer; const Text: string);

Description

The TextRect method displays text inside a clipping rectangle. Any portions of the text passed in the Text parameter that fall outside the rectangle passed in the Rect parameter are clipped and don't appear on screen. The upper left corner of the text is placed at the point (X, Y).


Example

The following code outputs the text "Hello, world!" in a rectangle defined by the coordinates (10, 10) and (100, 100). By passing 0 for X and 0 for Y, the top and left edges of the text will be clipped by the rectangle.

var

  TheRect: TRect;

begin

  TheRect.Top := 10;

  TheRect.Left := 10;

  TheRect.Bottom := 100;

  TheRect.Right := 100;

  Form1.Canvas.TextRect(TheRect,0,0,'Hello, world!');

end;


See also

TextOut method


TextToShortCut function

See also	Example

Unit

Menus

Declaration

function TextToShortCut(Text: string): TShortCut;

Description

The TextToShortCut function creates a menu shortcut from a text string. For example, your application can allow the user to specify what they want the shortcut to be in an edit box control, then TextToShortCut can use that string to create a menu shortcut.

Note:	The TextToShortCut function executes slowly. Unless you are getting input from the user, your application should use the ShortCut function to create a menu shortcut.


Example

This example uses a main menu that contains an Open command, an edit box, and a button. Delphi automatically names the menu item for the Open command Open1. When the user enters the desired shortcut text in the edit box and clicks the button, a shortcut is created and the shortcut text appears next to the Open menu item.

procedure TForm1.Button1Click(Sender: TObject);

var

  NewShortCut: TShortCut;

begin

  NewShortCut := TextToShortCut(Edit1.Text);

  Open1.ShortCut := NewShortCut;

end;


See also

ShortCut function

ShortCut property

ShortCutToKey procedure

ShortCutToText function


TextWidth method

See also	Example

Applies to

TCanvas object

Declaration

function TextWidth(const Text: string): Integer;

Description

The TextWidth method returns the width in pixels of the string passed in Text when rendered in the current font. You can use TextWidth to determine whether a given string will fit in a particular space.


Example

This example determines the width of a specified string, and if the string is too wide to display in an edit box, the edit box is widened to accommodate the string. The string displays in the edit box.

procedure TForm1.Button1Click(Sender: TObject);

var

  T: Longint;

  S: string;

begin

  S := 'Object Pascal is the language for me';

  T := Canvas.TextWidth(S);

  if T > Edit1.Width then

    Edit1.Width := T + 10;

  Edit1.Text := S;

end;


See also

TextRect method


TField component

Properties	Methods	Events

Unit

DB

Description

TField components are used to access fields in a record. By default, a set of TField components is created automatically each time a dataset component is activated; the resulting set of TField components is dynamic, mirroring the actual columns in an underlying physical table at that time.

At design time, you can use the Fields editor to create a persistent, unchanging set of TField components for a dataset. Creating TField components with the Fields Editor provides efficient, readable, and type-safe programmatic access to underlying data. It guarantees that each time your application runs, it uses and displays the same columns, in the same order, every time, even if the physical structure of the underlying database has changed. Creating TField components at design time guarantees that data-aware components and program code that rely on specific fields always work as expected. If a column on which a persistent TField component is based is deleted or changed, then Delphi generates an exception rather than running the application against a nonexistent column or mismatched data.

A TField component is an abstract object. The Fields property of a dataset is always one of the following TField descendants:

Component:	Used for:

TStringField	Fixed length text data up to 255 characters

TIntegerField	Whole numbers in the range -2,147,483,648 to 2,147,483,647

TSmallintField	Whole numbers in the range -32,768 to 32,767

TWordField	Whole numbers in the range 0 to 65,535

TFloatField	Real numbers with absolute magnitudes from 5.0*10-324 to 1.7*10+308 accurate to 15-16 digits

TCurrencyField	Currency values. The range and accuracy is the same as TFloatField

TBCDField	Real numbers with a fixed number of digits after the decimal point. Accurate to 18 digits. Range depends on the number of digits after the decimal point. [Paradox only]

TBooleanField	True or False values

TDateTimeField	Date and time value

TDateField	Date value

TTimeField	Time value

TBlobField	Arbitrary data field without a size limit

TBytesField	Arbitrary data field without a size limit

TVarBytesField	Arbitrary data field up to 65,535 characters, with the actual length stored in the first two bytes

TMemoField	Arbitrary length text

TGraphicField	Arbitrary length graphic, such as a bitmap

Each TField component and its properties, methods, and events can be accessed programmatically. At run time, dynamically created components can be accessed through the Fields property of the dataset; at design time, use the Fields Editor to select a field component and use the Object Inspector to modify the field's properties.

Most TField descendants have the same properties, but some properties, such as AsBoolean or EditMask only apply to some fields. Use the AsBoolean, AsDateTime, AsFloat, AsInteger, or AsString properties as appropriate to access or modify the current value of the field. Test the CanModify property to see if the field can be changed. Use the DataSet property to reference the dataset of the field. Use the DataType property to test the type of the field. Set the DisplayLabel property to a column heading for a data grid(TDBGrid). The DisplayText property will format the field for display purposes; Text will format it for editing purposes. Set the DisplayWidth to control the column width in a data grid. Set the EditMask property to limit the characters entered to a selected set. Use the FieldName property to get the name of the field in the dataset. Test the IsNull property to see if the field has been assigned a value. Set the ReadOnly property to prevent or allow the user to change the value. Set the Visible property to control whether the field appears in a data grid. Call the Clear method to erase any data assigned. Call the GetData method to access the data in native format, or SetData to assign new data. Use the OnChange event to be notified when the value of the field is changed. Use the OnGetText event to do your own formatting of the data for display or edit purposes, and the OnSetText event to convert the edited data back to native format. Use the OnValidate event to validate the data before it is stored into the record.

Delphi 2.0 adds a new kind of field support. In addition to data fields and calculated fields, you can now have lookup fields. Lookup fields are much like calculated fields, but their "calculation" is a lookup in another table. Lookup fields are always read-only.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components. TField component is a direct descendent of TComponent


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Name

AsBoolean	DisplayName	Owner

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditMask	Size

AsString	EditMaskPtr	Tag

BDECalcField	FieldName	Text

Calculated	FieldNo	Visible

CanModify	Index	LookupDataSet

DataSet	IsIndexField	LookupKeyFields

DataSize	IsNull	LookupResultField

DataType	KeyFields


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TFieldClass type

Unit

DB

Declaration

TFieldClass = class of TField;

Description

The TFieldClass type is the object type of TField. Use it to create an object reference to a TField.


TFieldDef object

Properties	Methods

Unit

DB

Description

The TFieldDef object corresponds to a physical field of a record in a table underlying a dataset. TFieldDef objects are created automatically for dataset components. A field definition has a corresponding TField component, but not all TField components have a corresponding TFieldDef objects. For example, calculated field do not have TFieldDef objects.

In addition to these properties and methods, this object also has the methods that apply to all objects. The TFieldDef object is a direct descendent of TObject.


Properties

 Run-time only          [image] Key properties

BDECalcField	FieldNo	Required

DataType	Name	Size

FieldClass


Methods

 Key methods

ClassName	Create	Free

ClassParent	CreateField

ClassType	Destroy


TFieldDefs object

Properties	Methods

Unit

DB

Description

A TFieldDefs object holds the TFieldDef objects that represent the physical fields underlying a dataset.

The Count property is the total number of TFieldDef objects in TFieldDefs. The Items property is an array of pointers to the TFieldDef objects.

Use the Find or IndexOf methods to locate an entry in Items by name. Call Clear to remove all TFieldDef objects from TFieldDefs. Call Update to obtain information about the fields in a dataset without opening it.

In addition to these properties and methods, this object also has the methods that apply to all objects. A TFieldDefs object is a direct descendent of TObject.


Properties

 Run-time only          [image] Key properties

Count	Items


Methods

 Key methods

Add	ClassType	Free

AddFieldDesc	Clear	IndexOf

Assign	Create	Update

ClassName	Destroy

ClassParent	Find


TFieldKind type

Unit

DB

Declaration

TFieldKind = (fkData, fkCalculated, fkLookup);

Description

The TFieldKind type is the set of values of the FieldKind property of a TField component . The following table describes each value:

Value	Description

fkData	Field represents a physical field in a database table

fkCalculated	Field is calculated

fkLookup	Field is a lookup field


TFieldType type

Unit

DB

Declaration

TFieldType = (ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat,
  ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc,
  ftBlob, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary);

Description

The TFieldType type is the set of values of the DataType property of a TField component or TFieldDef component. The following table describes each value:

Value	Description

ftUnkown	Unknown or undetermined

ftString	Character or string field

ftSmallint	16-bit integer field

ftInteger	32-bit integer field

ftWord	16-bit unsigned integer field

ftBoolean	Boolean field

ftFloat	Floating-point numeric field

ftCurrency	Money field

ftBCD	Binary-Coded Decimal field

ftDate	Date field

ftTime	Time field

ftDateTime	Date and time field

ftBytes	Fixed number of bytes (binary storage)

ftVarBytes	Variable number of bytes (binary storage)

ftAutoInc	Auto-incrementing 32-bit integer counter field

ftBlob	Binary Large OBject field

ftMemo	Text memo field

ftGraphic	Bitmap field

ftFmtMemo	Formatted text memo field

ftParadoxOle	Paradox OLE field

ftDBaseOle	dBASE OLE field

ftTypedBinary	Typed binary field


TFileEditStyle type

Unit

Dialogs

Declaration

TFileEditStyle = (fsEdit, fsComboBox);

Description

The TFileEditStyle type contains the possible values of the FileEditStyle property used by the Open (TOpenDialog) and Save (TSaveDialog) dialog boxes.


TFileExt type

Unit

Dialogs

Declaration

TFileExt = string[3];

Description

The TFileExt type is used to hold the three characters of a file-name extension. TFileExt is used by the DefaultExt property of the Open and Save dialog boxes (TOpenDialog and TSaveDialog).


 TFileListBox component

See also	Properties	Methods	Events	Tasks

Unit

FileCtrl

Description

TFileListBox is a specialized list box that lists all the files in the current directory. To display files in a different directory, change the value of the Directory property.

You can have icons next to the filenames to help identify the type of file. For example, an executable file displays a different icon than a word processing document. To make the icons appear, set ShowGlyphs to True.

You decide which file types you want to appear in the list box using the Mask property, which displays only the files that match the Mask string. For example, you can choose to display only executable files and source code files.

You can also decide which files display in the file list box by their file attributes. For example, you can choose to display hidden and system files as well as regular files, or you can choose to see read-only files only. Use the FileType property to select the file types according to their file attributes.

You can have the file selected in the file list box appear as the text of an edit box if you specify a value for the FileEdit property.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls. The TFileListBox component is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	Handle	ParentFont

BoundsRect	Height	ParentShowHint

Canvas	HelpContext	PopupMenu

ComponentIndex	Hint	Selected

Color	IntegralHeight	ShowGlyphs

Controls	ItemHeight	ShowHint

Ctl3D	ItemIndex	Showing

Cursor	Items	TabOrder

Directory	Left	TabStop

DragCursor	Mask	Tag

DragMode	MultiSelect	Top

Enabled	Name	TopIndex

FileEdit	Owner	Visible

FileName	Parent	Width

FileType	ParentColor

Font	ParentCtl3D


Methods

 Key methods

BeginDrag	Free	ScreenToClient

BringToFront	GetTextBuf	ScrollBy

CanFocus	GetTextLen	SendToBack

Clear	Hide	SetBounds

ClientToScreen	Invalidate	SetFocus

Create	ItemAtPos	SetTextBuf

Destroy	ItemRect	Show

Dragging	Refresh	Update

EndDrag	Repaint

Focused	ScaleBy


Events

 Key events

OnChange	OnEndDrag	OnKeyUp

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag


See also

TDirectoryListBox component

TDriveComboBox component


TFileType type

Unit

FileCtrl

Declaration

TFileAttr = (ftReadonly, ftHidden, ftSystem, ftVolumeID, ftDirectory, ftArchive, ftNormal);

TFileType = set of TFileAttr;

Description

The TFileType type is a set of file attributes. The FileType property of a file list box (TFileListBox) uses the TFileType type.


TFillStyle type

Unit

Graphics

Declaration

TFillStyle = (fsSurface, fsBorder);

Description

The TFillStyle type determines the method of filling used by the FloodFill method of a canvas (TCanvas object).


 TFilterComboBox component

Properties	Methods	Events	Tasks

Unit

FileCtrl

Description

 TFilterComboBox is a specialized combo box that is used to present the user with a choice of file filters. Specify the filters you want to appear in the filter combo box with the Filter property. The filter the user selects is the value of the Mask property.

Most commonly, a filter combo box is used with a file list box (TFileListBox). Your application can have the file filter the user selects in the filter combo box determine which files appear in the file list box. If you place this line of code in an OnChange event handler of the filter combo box, any change in the filter combo box is reflected in the file list box:

FileListBox1.Mask := FilterComboBox1.Filter;

Another way to accomplish the same task is to set the FileList property of the filter combo box to the file list box you want affected with a change of filters.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls. The TFilterComboBox component is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	Height	ParentFont

BoundsRect	HelpContext	SelLength

Color	Hint	SelStart

ComponentIndex	ItemIndex	SelText

Ctl3D	Items	Showing

Cursor	Left	TabOrder

DragCursor	Mask	TabStop

DragMode	Name	Text

Enabled	Owner	Tag

FileList	Parent	Top

Filter	ParentColor	Visible

Font	ParentCtl3D	Width


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetTextBuf	SelectAll

Clear	GetTextLen	SendToBack

ClientToScreen	Hide	SetBounds

Create	Invalidate	SetFocus

Destroy	Refresh	SetTextBuf

Dragging	Repaint	Show

EndDrag	ScaleBy	Update


Events

 Key events

OnChange	OnDragOver	OnExit

OnClick	OnDropDown	OnKeyDown

OnDblClick	OnEndDrag	OnKeyPress

OnDragDrop	OnEnter	OnKeyUp

OnStartDrag


TFilterOptions type

Unit

DB

Declaration

type
  TFilterOption = (foCaseInsensitive, foNoPartialCompare);
  TFilterOptions = set of TFilterOption;

Description

The TFilterOptions type defines the possible values for the FilterOptions property of the TTable, TQuery, and TStoredProc components, as described in the following table:

Value	Description

foCaseInsensitive	The filter is processed without regard to case in the dataset's data.

foNoPartialCompare	String matches must be exact over the length of the data in the dataset; partial matches aren't allowed.


TFilterRecordEvent type

Unit

DB

Declaration

TFilterRecordEvent = procedure(DataSet: TDataSet; var Accept: Boolean) of object;

Description

The TFilterRecordEvent type points to a method that responds to an OnFilterRecord event, for including or excluding records from being visible in a dataset.


 TFindDialog component

Properties	Methods	Events	Tasks

Unit

Dialogs

Description

The TFindDialog component is an indirect descendent of TComponent. It provides a Find dialog box to your application. Users can use the Find dialog box to search for text in a file.

Display the Find dialog box by calling the Execute method.

The text your application is searching for is the value of the FindText property.

To determine which search options are available in the Find dialog box, use the Options property. For example, you can have a Match Case check box appear in the dialog box or hide it, and you can disable or enable the Whole Word check box.

When the user enters the text to search for in the dialog box and chooses Find Next, the OnFind event occurs. Within the OnFind event handler, write the code that searches for the text specified as the value of FindText. Your code should use the Options values to determine how the user wants the search conducted.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components. The TFindDialog component is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

ComponentIndex	HelpContext	Owner

Ctl3D	Left	Position

FindText	Name	Tag

Handle	Options	Top


Methods

 Key methods

CloseDialog	Destroy	Free

Create	Execute


Events

 Key events

OnFind


TFindItemKind type

Unit

Menus

Declaration

TFindItemKind = (fkCommand, fkHandle, fkShortCut);

Description

The TFindItemKind defines the possible values of the Kind parameter in the FindItem method of a menu component.


TFindOptions type

Unit

Dialogs

Declaration

TFindOption = (frDown, frFindNext, frHideMatchCase, frHideWholeWord, frHideUpDown, frMatchCase, frDisableMatchCase, frDisableUpDown, frDisableWholeWord, frReplace, frReplaceAll, frWholeWord, frShowHelp);

TFindOptions = set of TFindOption;

Description

The TFindOptions type defines the set of possible values for the Options property of the Find and Replace dialog boxes (TFindDialog and TReplaceDialog components).


TFloatField component

Properties	Methods	Events

Unit

DBTables

Description

The TFloadField component represents a field of a record in a dataset. It is represented as a binary value with a range from (positive or negative) 5.0 * 10-324 to 1.7 * 10308. It has an accuracy of 15 to 16 digits. Use TFloatField for fields that hold floating-point numbers.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value.

The TFloatField component has the properties, methods, and events of the TField component. The TFloatField component is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Owner

AsBoolean	DisplayName	Precision

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditFormat	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Value

Currency	IsIndexField	Visible

DataSet	IsNull

DataSize	MaxValue

DataType	MinValue

DisplayFormat	Name


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TFont object

Properties	Methods	Events

Unit

Graphics

Description

A TFont object defines the appearance of text. TFont encapsulates a Windows HFONT.

A TFont object defines a set of characters by specifying their height, font family (typeface) name, and so on. The height is specified by the Height property. The typeface is specified by the Name property. The size in points is specified by the Size property. The color is specified by the Color property. The attributes of the font (bold, italic, and so on) are specified by the Style property.

When a font is modified, an OnChange event occurs.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. A TFont object is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Color	Name	Size

Handle	Pitch	Style

Height	PixelsPerInch


Methods

 Key methods

Assign	Destroy

Create	Free


Events

 Key events

OnChange


 TFontDialog component

Properties	Methods	Events	Tasks

Unit

Dialogs

Description

The TFontDialog component makes a Font dialog box available to your application. The purpose of the dialog box is to allow a user to select a font and set attributes of that font. When the user selects a font and chooses OK in the dialog box, the user's font selection is stored in the dialog box's Font property, which you can then process as you want.

Display the Font dialog box by calling the Execute method.

You choose which device you want a font change to affect with the Device property.

You can use the Options property to customize how the Font dialog box appears and behaves. For example, you can specify that a Help button be included in the dialog box or that only True Type fonts appear in the list of fonts.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components. The TFontDialog component is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

ComponentIndex	HelpContext	Options

Ctl3D	MaxFontSize	Owner

Device	MinFontSize	Tag

Font	Name


Methods

 Key methods

Create	Execute

Destroy	Free


Events

 Key events

OnApply


TFontDialogDevice type

Unit

Dialogs

Declaration

TFontDialogDevice = (fdScreen, fdPrinter, fdBoth);

Description

The TFontDialogDevice type lists the values the Device property of the Font dialog box (TFontDialog) can assume.


TFontDialogOptions type

Unit

Dialogs

Declaration

TFontDialogOption = (fdAnsiOnly, fdTrueTypeOnly, fdEffects, fdFixedPitchOnly, fdForceFontExist, fdNoFaceSel, fdNoOEMFonts, fdNoSimulations, fdNoSizeSel, fdNoStyleSel, fdNoVectorFonts, fdShowHelp, fdWysiwyg, fdLimitSize, fdScalableOnly, fdApplyButton);

TFontDialogOptions = set of TFontDialogOption;

Description

The TFontDialogOptions type is the set of values the Options property of the Font dialog box (TFontDialog) can have.


TFontName type

Unit

Graphics

Declaration

TFontName = string(LF_FACESIZE - 1);

Description

The TFontName type is used by the Name property of a font object (TFont). The maximum number of characters is 32, so font names longer than 32 characters are truncated.


TFontPitch type

Unit

Graphics

Declaration

TFontPitch = (fpDefault, fpVariable, fpFixed);

Description

The TFontPitch type is used by the Pitch property of a font object (TFont).


TFontStyles type

Unit

Graphics

Declaration

TFontStyle = (fsBold, fsItalic, fsUnderline, fsStrikeOut);

TFontStyles = set of TFontStyle;

Description

The TFontStyles type is the set of font styles the Style property of a font object (TFont) can assume.


 TForm component

See also	Properties	Methods	Events	Tasks

Unit

Forms

Description

The Form component is at the center of Delphi applications. You design your application by putting other components on a form. Forms can be used as windows, dialog boxes, or simply as forms, such as data-entry forms.

To display a form that isn't currently active in your application, call either the Show or ShowModal method. To close a form, call either Close or CloseQuery, or use the ModalResult property with the ShowModal method.

You determine the behavior of the horizontal and vertical scroll bars on the form by setting the properties of the HorzScrollBar and VertScrollBar objects, which are properties of a form.

You can decide how your form first appears--maximized, minimized, or normal--with the WindowState property. You can customize the appearance of your form and determine how the user interacts with it by setting the BorderStyle and BorderIcons properties. Use the Icon property to control the system menu icon and the icon that shows in the task bar or in the "icon window" for the form when it is minimized. Under Windows NT 3.51, the icon property only controls the appearance of the form when it is minimized.

To find out which control is the active control on the form, use the ActiveControl property. To assure that a particular control on the form is in view, use the ScrollInView method.

Forms have a number of properties and methods that make it simple to create Multiple Document Interface (MDI) applications. You specify which form is the parent form for your application and which forms are the child forms with the FormStyle property. Once you have designated a form as a parent and others as children, you can access a child form with the MDIChildren property. The number of child forms open in your application is the value of the MDIChildCount property. You can determine which form is the active child form with the ActiveMDIChild property.

Most MDI applications have a Window menu that lists the open child forms or windows at the bottom of the menu. You can specify which item on the main menu of your application is the Window menu as the value of the WindowMenu property, and at run time, the open child forms are automatically listed at the bottom of the specified menu. Usually, Window menus have commands that allow the user to manage the windows or forms in the running application. You can call the Cascade, Tile, Previous, Next, and ArrangeIcons methods in the OnClick event handlers for the appropriate menu commands, which make it very easy to give your users this capability.

If you want your form to display different menus at various times while your application runs, you specify the menu you want to use with the Menu property. If you want your application to be able to process key events rather than have them go immediately to the selected control on the form, set the form's KeyPreview property to True.

You can use the OnCreate event handler of the form to set initial values for properties and do any processing you want to occur before the user begins interacting with the form.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls. The Form component is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Active	Controls	Owner

ActiveControl	Ctl3D	Parent

ActiveMDIChild	Cursor	PixelsPerInch

Align	Enabled	PopupMenu

AutoScroll	Font	Position

BorderIcons	FormStyle	PrintScale

BorderStyle	Handle	Scaled

Brush	Height	ShowHint

Caption	HelpContext	Showing

Canvas	Hint	TabOrder

ClientHandle	HorzScrollBar	TabStop

ClientHeight	Icon	Tag

ClientOrigin	KeyPreview	TileMode

ClientRect	Left	Top

ClientWidth	MDIChildCount	VertScrollBar

Color	MDIChildren	Visible

ComponentCount	Menu	Width

ComponentIndex	ModalResult	WindowMenu

Components	Name	WindowState

ControlCount	ObjectMenuItem


Methods

 Key methods

ArrangeIcons	GetFormImage	RemoveComponent

BringToFront	GetTextBuf	Repaint

CanFocus	GetTextLen	ScaleBy

Cascade	Hide	ScreenToClient

ClientToScreen	HandleAllocated	ScrollBy

Close	HandleNeeded	ScrollInView

CloseQuery	Hide	SendToBack

ContainsControl	InsertComponent	SetBounds

Create	InsertControl	SetFocus

CreateNew	Invalidate	SetTextBuf

Destroy	Next	Show

Dragging	Previous	ShowModal

FindComponent	Print	Tile

Focused	Refresh	Update

Free	Release


Events

 Key events

OnActivate	OnDragDrop	OnMouseDown

OnClick	OnDragOver	OnMouseMove

OnClose	OnEnter	OnMouseUp

OnCloseQuery	OnExit	OnPaint

OnCreate	OnHide	OnResize

OnDestroy	OnKeyDown	OnShow

OnDblClick	OnKeyPress

OnDeactivate	OnKeyUp


See also

Multiple Document Interface applications


TFormBorderStyle type

Unit

Forms

Declaration

TFormBorderStyle = (bsNone, bsSingle, bsSizeable, bsDialog);

Description

The TFormBorderStyle type defines the possible border styles of a form. It is the type of the form's BorderStyle property.


TFormStyle type

Unit

Forms

Declaration

TFormStyle = (fsNormal, fsMDIChild, fsMDIForm, fsStayOnTop);

Description

The TFormStyle type defines the possible values of the FormStyle property of a form (TForm).


TGraphic object

Properties	Methods	Events

Unit

Graphics

Description

The TGraphic object is the abstract foundation class for the TBitmap, TIcon, and TMetafile objects. If you know which type of graphic (bitmap, icon, or metafile) you will be using, you should store the graphic in its specific type object (TBitmap, TIcon, or TMetafile, respectively). Otherwise, you should use a TPicture object which can hold any type of TGraphic.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. The TGraphic object is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Height	Empty	Width


Methods

 Key methods

ClassName	Create	LoadFromFile

ClassParent	Destroy	SaveToFile

ClassType	Free


Events

 Key events

OnChange


TGraphicField component

Properties	Methods	Events

Unit

DBTables

Description

A TGraphicField component represents a field of a record which is represented by a value consisting of an arbitrary set of bytes with indefinite size. The bytes should correspond to graphics data.

Use the Assign method to transfer another component to a TGraphicField. Use the LoadFromFile method to load a field's contents from a file. Use LoadFromStream method to load a field from a Stream. Use SaveToFile method to write a field's contents to a file. Use SaveToStream method to write a field's contents to a Stream.

The TGraphicField component has the properties, methods, and events of the TField component. A TGraphicField component is an indirect descendent of TComponent.


Properties

 Run-time only          [image] Key properties

Alignment	DataType	Name

AsBoolean	DisplayLabel	Owner

AsDateTime	DisplayName	ReadOnly

AsFloat	DisplayText	Required

AsInteger	DisplayWidth	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Visible

DataSet	IsIndexField

DataSize	IsNull


Methods

 Key methods

Assign	FocusControl	LoadFromStream

AssignValue	Free	SaveToFile

Clear	GetData	SaveToStream

Create	IsValidChar	SetData

Destroy	LoadFromFile


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TGraphicsObject object

Methods	Events

Unit

Graphics

Description

A TGraphicsObject object is the abstract base class for the Delphi encapsulation of the three main Windows graphics tools: the TBrush, TFont, and TPen objects.

In addition to these methods and events, this object also has the methods that apply to all objects. A TGraphicsObject object is a direct descendent of TPersistent.


Methods

 Key methods

ClassName	ClassType	Destroy

ClassParent	Create	Free


Events

 Key events

OnChange


TGridDrawState type

Unit

Grids

Declaration

TGridDrawState = set of (gdSelected, gdFocused, gdFixed);

Description

The TGridDrawState type defines the possible states of cell when drawing occurs. The TGridDrawState is the type of the AState parameter used in the TDrawCellEvent method pointer.


TGridOptions type

Unit

Grids

Declaration

TGridOption = (goFixedVertLine, goFixedHorzLine, goVertLine, goHorzLine, goRangeSelect, goDrawFocusSelected, goRowSizing, goColSizing, goRowMoving, goColMoving, goEditing, goTabs, goRowSelect, goAlwaysShowEditor, goThumbTracking);

TGridOptions = set of TGridOption;

Description

TGridOptions is the set of values the Options property of a TDrawGrid or TStringGrid component can have.


TGridRect type

Unit

Grids

Declaration

TGridRect = record
  case Integer of
    0: (Left, Top, Right, Bottom: Longint);
    1: (TopLeft, BottomRight: TGridCoord);
end;

Description

TGridRect defines a rectangular area within a grid control. It is the type of the Selection property of the TDrawGrid and TStringGrid components.


 TGroupBox component

Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

The TGroupBox component is a standard Windows group box. Use a group box component to group related controls on a form. The most commonly grouped controls in a group box are radio buttons (TRadioButton).

Place the group box on the form, then select the components you want to appear in the group box from the Component palette, and place them in the group box.

The text that identifies the purpose of the grouping appears as the value of the Caption property.

Once you place another windowed control within a group box, the group box becomes the parent of the control and is the value of that control's Parent property.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls. The TGroupBox component is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	Height	PopupMenu

Caption	HelpContext	Showing

Color	Hint	TabOrder

Controls	Left	TabStop

Ctl3D	Name	Tag

Cursor	Owner	Top

DragCursor	Parent	Visible

DragMode	ParentColor	Width

Enabled	ParentCtl3D

Font	ParentFont


Methods

 Key methods

BeginDrag	EndDrag	Repaint

BringToFront	Focused	ScaleBy

CanFocus	Free	ScreenToClient

ClientToScreen	GetTextBuf	ScrollBy

ContainsControl	GetTextLen	SendToBack

Create	Hide	SetBounds

Destroy	Invalidate	SetFocus

Dragging	Refresh	SetTextBuf


Events

 Key events

OnClick	OnEndDrag	OnMouseMove

OnDblClick	OnEnter	OnMouseUp

OnDragDrop	OnExit	OnStartDrag

OnDragOver	OnMouseDown


THeader component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The THeader component is a sectioned visual control that displays text and allows each section to be resized with the mouse. THeader is provided for backward compatibility.  Use THeaderControl component in Microsoft Windows 95 and Windows NT applications.

At design time, resize a section by clicking the right mouse button on a section border and dragging to the new size. At run time, the user can resize the header by clicking and dragging with the left mouse button. The widths of the other sections that are not resized remain unchanged.

The Sections property specifies the sections of a header. The AllowResize property enables or prevents the user from resizing sections at run time. When a section is resized, an OnSizing event occurs. After a section has been resized, an OnSized event occurs.

To use a header you should attach code to these event handlers. One use would be to align text under a header. When the header is resized, you would realign the text in the OnSized event handler. To move the text as the header is being resized, realign the text in the OnSizing event handler.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	HelpContext	SectionWidth

AllowResize	Hint	ShowHint

BoundsRect	Left	Showing

BorderStyle	Name	TabOrder

ComponentIndex	Owner	TabStop

Cursor	Parent	Tag

Enabled	ParentFont	Top

Font	ParentShowHint	Visible

Height	Sections	Width


Methods

 Key methods

BeginDrag	Free	ScreenToClient

BringToFront	GetTextBuf	SendToBack

CanFocus	GetTextLen	SetBounds

ClientToScreen	Hide	SetFocus

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy

Focused	ScrollBy


Events

 Key events

OnEnter	OnSized

OnExit	OnSizing


{bml dhdctrl.bmp} THeaderControl component
 THeaderControl component

Properties	Methods	Events

Unit

ComCtrls

Description

The THeaderControl component is a control that contains multiple, movable headers and is similar to a THeader component. Each item, called a section, is a THeaderSection object. Typically these are positioned above columns or fields of information indicated by their titles.

To create a new section in a THeaderControl at design-time select Sections. Use this property to edit the title, size, Style, and text Alignment of the section. To move or resize sections, click on the divider between them and drag it to the desired position. The OnSectionTrack event tracks the dragging of the sections.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls. The THeaderControl component is a direct descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	Enabled	ParentShowHint

BoundsRect	Font	Sections

Brush	Handle	ShowHint

ClientHeight	Height	Showing

ClientOrigin	HelpContext	TabOrder

ClientRect	Hint	TabStop

ClientWidth	Left	Tag

ComponentIndex	Name	Top

Cursor	Owner	Visible

DragCursor	Parent	Width

DragMode	ParentFont


Methods

 Key methods

Assign	Dragging	Refresh

BeginDrag	EndDrag	RemoveComponent

BringToFront	FindComponent	RemoveControl

CanFocus	Focused	Repaint

ClassName	Free	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

Invalidate	Update


Events

 Key events

OnDragDrop	OnMouseDown	OnSectionClick

OnDragOver	OnMouseMove	OnSectionResize

OnDrawSection	OnMouseUp	OnSectionTrack

OnEndDrag	OnResize	OnStartDrag


THeaderSection object

Properties	Methods

Unit

ComCtrls

Description

The THeaderSection object is an individual item in a THeaderControl component. To create a new THeaderSection use the Sections property of a header control. Set or edit the section properties in the HeaderControl Sections Editor dialog.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. The THeaderSection object is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Alignment	Items	Right

AllowClick	Left	Style

Count	MinWidth	Width


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


THeaderSections object

Properties	Methods

Unit

ComCtrls

Description

The THeaderSections object is used to maintain a collection of THeaderSection objects in a THeaderControl component. THeaderSections maintain an index of the sections in its Items array. Use the header control Sections property editor dialog to Add or delete sections from the THeaderSections object.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. The THeaderSections object is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Count	Items


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


THeaderSectionStyle type

Unit

ComCtrls

Declaration

THeaderSectionStyle = (hsText, hsOwnerDraw);

Description

The THeaderSectionStyle type defines the possible values of the Style property of the THeaderSection object. THeaderSection objects comprise the headers, which are the individual items, of a THeaderControl component.


THelpContext type

Unit

Classes

Declaration

THelpContext = -MaxLongInt..MaxLongInt;

Description

The THelpContext type is used to define Help context numbers.


THintInfo type

Unit

Forms

Declaration

THintInfo = record
  HintControl: TControl;
  HintPos: TPoint;
  HintMaxWidth: Integer;
  HintColor: TColor;
  CursorRect: TRect;
  CursorPos: TPoint;
end;

Description

The THintInfo type is used to define the appearance and behavior of the Help window in a TShowHintEvent type OnShowHint event handler.


THitTests type

Unit

ComCtrls

Declaration

THitTest = (htAbove, htBelow, htNowhere, htOnItem, htOnButton, htOnIcon, htOnIndent, htOnLabel, htOnRight, htOnStateIcon, htToLeft, htToRight);

THitTests = set of THitTest;

The THitTests type determines the location of the specified point relative to the client area of a tree view control. It defines the set of possible values returned by the GetHitTestInfoAt method of the TTreeView component.


THKModifiers type

Unit

ComCtrls

Declaration

THKModifier = (hkShift, hkCtrl, hkAlt, hkExt);

THKModifiers = set of THKModifier;

Description

The THKModifiers type defines the set of values the Modifiers property of the THotKey component.


THKInvalidKeys type

Unit

ComCtrls

Declaration

THKInvalidKey = (hcNone, hcShift, hcCtrl, hcAlt, hcShiftCtrl, hcShiftAlt, hcCtrlAlt, hcShiftCtrlAlt);

THKInvalidKeys = set of THKInvalidKey;

Description

The THKInvalidKeys type defines the set of values the InvalidKeys property of the THotKey component can have.


{bml dhtky.bmp} THotKey component
 THotKey component

Properties	Methods	Events

Unit

ComCtrls

Description

The THotKey component is used to set a shortcut property at run time. The user can enter a key combination, typically consisting of a modifier key (such as Ctrl, Alt, or Shift) and an accompanying key (such as a character key, an arrow key, a function key, etc.), into the hot-key control. The hot key is associated with another control by assigning its HotKey property to the desired control's shortcut property.

To select a key combination at design-time use the HotKey and Modifiers properties. The names of the keys will appear in the hot-key control. To invalidate specific modifier keys use the InvalidKeys property. To change the key combination at run-time hold down the Alt, Ctrl or Shift keys or combinations of them and type a letter or number. The HotKey property can then be assigned to the shortcut property of a menu item, for example.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls. The THotKey component is an indirect descendent of TWinControl.


Properties

 Run-time only          [image] Key properties

Align	ControlCount	Name

AutoSize	Controls	Owner

BoundsRect	Cursor	Parent

Brush	Enabled	ShowHint

ClientHeight	Handle	Showing

ClientOrigin	Height	TabOrder

ClientRect	HelpContext	TabStop

ClientWidth	HotKey	Tag

ComponentCount	InvalidKeys	Top

ComponentIndex	Left	Visible

Components	Modifiers	Width


Methods

 Key methods

Assign	EndDrag	Refresh

BeginDrag	FindComponent	RemoveComponent

BringToFront	Focused	RemoveControl

CanFocus	Free	Repaint

ClassName	GetAssigned	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

Dragging	Invalidate	Update


Events

 Key events

OnEnter	OnMouseDown	OnMouseUp

OnExit	OnMouseMove


vclPositionPropertyUpDownThousands property
Thousands property

See also

Applies to

TUpDown component

Declaration

property Thousands: Boolean;

Description

Inserts a thousands separator between every three digits of a decimal string if set to True. The default value is True. The decimal value is held in the Position property.


See also

Position property


TickMarks property

See also

Applies to

TTrackBar component

Declaration

property TickMarks: TTickMark;

Description

The TickMarks property sets the position of tick marks on a TTrackBar. Horizontal track bars can have tick marks on either the top or bottom. Vertical track bars can have tick marks on either the left or right. The tmBoth style displays tick marks on both sides of the track bar. These are the possible values:

Value	Meaning

tmBottomRight	Tick marks are on either the bottom or the right of the track bar.

tmTopLeft	Tick marks are on either the top or the left of the track bar.

tmBoth	Tick marks are on both sides of the track bar. The default setting is tmBottomRight.


See also

Orientation property

Position property

TickStyle property


TickStyle property

See also

Applies to

TTrackBar component

Declaration

property TickStyle: TTickStyle;

Description

The TickStyle property controls the tick mark styles. Use it to customize the number of tick marks on the track bar. These are the possible values:

Value	Meaning

tsAuto	Track bar displays tick marks automatically for each increment in its range. To use the Frequency property you must set this style.

tsManual	Track bar displays a tick mark at either end. You can also use this style with the SetTick method to set a tick at any position.

tsNone	Track bar displays no tick marks.

The default setting is tsAuto.


See also

Frequency property

Max property

Min property

Orientation property

Position property

SetTick method

TickMarks property


TIcon object

Properties	Methods	Events

Unit

Graphics

Description

The TIcon object contains an icon graphic (.ICO file format). TIcon encapsulates a Windows HICON.

The height and width in pixels of the icon are specified by the Height and Width properties, respectively.

To load an icon from a file, call the LoadFromFile method. To save an icon to a file, call SaveToFile.

To draw an icon on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TIcon as a parameter.

When the icon is modified, an OnChange event occurs.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. A TIcon object is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Empty	Height	Width

Handle


Methods

 Key methods

Assign	Create	ReleaseHandle

ClassName	Destroy	SaveToFile

ClassParent	Free

ClassType	LoadFromFile


Events

 Key events

OnChange


TIconArrangement type

Unit

ComCtrls

Declaration

TIconArrangment = (iaTop, iaLeft);

Description

The TIconArrangement type is used to specify where the items are to be aligned in the list view. The Arrangement property of the IconOptions object for the list view allows you to specify a TIconArrangement value. The list view must have a ViewStyle of vsIcon or vsSmallIcon to have an alignment for icons to have affect.


TIconOptions object

Properties	Methods

Unit

ComCtrls

Description

The TIconOptions object contains properties pertaining to the icons displayed in a list view. The ViewStyle of the list view must be set to either vsIcon or vsSmallIcons for these options to pertain. Use the Arrangement property to have the icons align at the top or the left of the list view. Set AutoArrange to True to have the icons arranged automatically when icons are added, moved, deleted or otherwise redrawn. Set WrapText to True to have the caption of the item wrap rather than display on one line when it exceeds the width of the icon.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Arrangement	AutoArrange	WrapText


Methods

 Key methods

Assign	ClassType	Destroy

ClassName	Create	Free

ClassParent


Tile method

See also	Example

Applies to

TForm component

Declaration

procedure Tile;

Description

The Tile method arranges the child forms of a parent form in your application so that the forms are all the same size. At the same time, all the forms together completely fill up the client area of the parent form. How the forms arrange themselves depends upon the value of the TileMode property.

The Tile method applies only to forms that are MDI parent forms (have a FormStyle property value of fsMDIForm).


Example

This example uses three forms. The first form has its FormStyle property set to MDIForm. The other two have their FormStyle properties set to MDIChild and their Visible properties set to True. Add a main menu component and name one of the menu items TileForms. This is code for the TileFormsClick handler:

procedure TForm1.TileForms1Click(Sender: TObject);

begin

  TileMode := tbVertical;

  Tile;

end;

When the user chooses the TileForms command, the child forms tile vertically within the MDI frame form.


See also

ArrangeIcons method

Cascade method

Next method

Previous method


TileMode property

See also	Example

Applies to

TForm component

Declaration

property TileMode: TTileMode;

Description

Run-time only. The TileMode property determines how the child forms within a parent form arrange themselves when the application calls the Tile method. These are the possible values the TileMode property can have:

Value	Meaning

tbHorizontal	Each form stretches across the width of the parent form

tbVertical	Each form stretches along the height of the parent form

Setting the TileMode property is meaningful only in an MDI parent form (has a FormStyle property value of fsMDIForm).


Example

This example uses three forms. The first form has its FormStyle property set to MDIForm. The other two have their FormStyle properties set to MDIChild and their Visible properties set to True. Add a main menu component and name one of the menu items TileForms. This is code for the TileFormsClick handler:

procedure TForm1.TileForms1Click(Sender: TObject);

begin

  TileMode := tbHorizontal;

  Tile;

end;

When the application runs and the user chooses the TileForms command, the child forms tile horizontally within the MDI frame form.


See also

Tile method


 TImage component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The TImage component displays a graphical image on a form. The image that appears is the value of the Picture property. If you want the image control to resize to fit the current image, set the AutoSize property to True. If you want to resize the image to completely fill an image control when the control is larger than the native size of the image, use the Stretch property.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all controls.


Properties

 Run-time only          [image] Key properties

Align	Height	ShowHint

Autosize	HelpContext	Showing

BoundsRect	Hint	Stretch

Canvas	Left	TabOrder

Center	Name	TabStop

ComponentIndex	Owner	Tag

Cursor	Parent	Top

DragCursor	ParentShowHint	Visible

DragMode	Picture	Width

Enabled	PopupMenu


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	SendToBack

ClientToScreen	Hide	SetBounds

Create	Invalidate	Show

Destroy	Refresh	Update

Dragging	Repaint

EndDrag	ScaleBy


Events

 Key events

OnClick	OnDragOver	OnMouseMove

OnDblClick	OnEndDrag	OnMouseUp

OnDragDrop	OnMouseDown	OnStartDrag


{bml dimg.bmp} TImageList component
 TImageList component

Properties	Methods	Events	Components

Unit

Controls

Description

The TImageList component is a container for a group of graphic images. The image list is capable of holding a large number of same sized images and retrieving them via their index within the range 0 to n - 1. The image list also has methods to facilitate storing, retrieving, and drawing of the stored images.

To create an image list with a size other than the default of 16x16, use the CreateSize constructor. To draw an image in the image list onto a specified canvas, use the Draw method. To draw and image and an overlay from an image list onto a specified canvas, use the DrawOverlay method. To specify how an image is to appear, set the DrawingStyle property.

To add an image to the image list, use the Add method. To generate a mask, or overlay image from a bitmap and add it to the image list, use the AddMasked method. To add an icon or cursor to the image list, use the AddIcon method. To add images from another image list, use the AddImages method. To load a bitmap, cursor or icon file into an image list, use the FileLoad method. To load a resource into the image list, use the ResourceLoad method.

To insert a bitmap into a specified location in the image list, use the Insert method. To insert an icon into a specified location in the image list, use the InsertIcon method. To generate a mask from a bitmap and insert it into a specified location in the image list, use the InsertMasked method.

To retrieve a bitmap by its index from the image list, use the GetBitmap method. To retrieve an image as an icon by its index from the image list, use the GetIcon method. To retrieve a handle for a bitmap containing all the images in the image list, use the GetImageBitmap method.

To use an image as a drag image and associate it with a window handle while in drag mode, use the DragLock method. To move the drag image to a new location, use the DragMove method. To set an image in the image list to be used as the drag and drop image for the image list, use the SetDragImage method.

To make an image in the image list usable as an overlay image, use the Overlay method. To specify how an image is to appear, set the DrawingStyle property. The Masked property determines whether the image list contains transparent images.


Properties

 Run-time only          [image] Key properties

AllocBy	Dragging	Masked

BkColor	DrawingStyle	Name

BlendColor	Enabled	Owner

ComponentIndex	Handle	ShareImages

Count	Height	Tag

DragCursor	ImageType	Width


Methods

 Key events

Add	Draw	Insert

AddIcon	DrawOverlay	InsertIcon

AddMasked	EndDrag	InsertMasked

Assign	FileLoad	Move

BeginDrag	Free	Overlay

Clear	GetBitmap	RegisterChanges

Create	GetHotspot	Replace

CreateSize	GetIcon	ReplaceIcon

Delete	GetImageBitmap	ReplaceMasked

Destroy	GetMaskBitmap	ResourceLoad

DragLock	GetResource	SetDragImage

DragMove	HandleAllocated	ShowDragImage

DragUnlock	HideDragImage	UnregisterChanges


Event

 Key events

OnChange


TImageType type

Unit

Controls

Declaration

TImageType = (itImage, itMask);

Description

The TImageType type contains the possible values for the ImageType property. The ImageList uses the ImageType setting when drawing either the image or the associated mask.


TimeFormat property

Example

Applies to

TMediaPlayer component

Declaration

property TimeFormat: TMPTimeFormats;

Description

Run-time only. The TimeFormat property determines the format used to specify position information.

TimeFormat determines how the StartPos, Length, Position, Start, and EndPos properties are interpreted. For example, if Position is 180 and TimeFormat is tfMilliseconds, the current position is 180 milliseconds into the medium. If Position is 180 and TimeFormat is tfMSF, the current position is 180 minutes into the medium.

Not all formats are supported by every device. If you try to set an unsupported format, the assignment is ignored.

The current timing information is always passed in a 4-byte integer. In some formats, the timing information returned is not really one integer, but single bytes of information packed in the long integer.

The following table lists the possible values for the TimeFormat property:

Value	Time format

tfMilliseconds	Milliseconds are stored as a 4-byte integer variable.

tfHMS	Hours, minutes, and seconds packed into a 4-byte integer. From least significant to most significant byte, the data values are
  Hours (least significant byte)
  Minutes
  Seconds
  Unused (most significant byte)

tfMSF	Minutes, seconds, and frames packed into a 4-byte integer. From least significant to most significant byte, the data values are
  Minutes (least significant byte)
  Seconds
  Frames
  Unused (most significant byte)

tfFrames	Frames are stored as a 4-byte integer variable.

tfSMPTE24	24-frame SMPTE packs values in a 4-byte variable. From least significant to most significant byte, the data values are
  Hours (least significant byte)
  Minutes
  Seconds
  Frames (most significant byte)
SMPTE (Society of Motion Picture and Television Engineers) time is an absolute time format expressed in hours, minutes, seconds, and frames. The standard SMPTE division types are 24, 25, and 30 frames per second.

tfSMPTE25	25-frame SMPTE packs data into a 4-byte variable in the same order as 24-frame SMPTE.

tfSMPTE30	30-frame SMPTE packs data into the 4-byte variable in the same order as 24-frame SMPTE.

tfSMPTE30Drop	30-drop-frame SMPTE packs data into the 4-byte variable in the same order as 24-frame SMPTE.

tfBytes	Bytes are stored as a 4-byte integer variable.

tfSamples	Samples are stored as a 4-byte integer variable.

tfTMSF	Tracks, minutes, seconds, and frames are packed in the 4-byte variable. From least significant to most significant byte, the data values are
  Tracks (least significant byte)
  Minutes
  Seconds
  Frames (most significant byte)
Note that MCI uses continuous track numbering.

Note:	Functions provided with MCI to help you decode the 4-byte integer specified in a given time format are documented under MCI Macros for Encoding and Decoding Time Data in the MMSYSTEM.HLP Help file.


Example

The following code declares a HMSRec record with four byte fields. If TimeFormat is tfHMS, the first field specifies hours, the second field specifies minutes, the third field specifies seconds, and the fourth field corresponds to the unused most-significant byte of the tfHMS time format. A LongInt variable is typecast to an HMSRec record, then the hours, minutes, and seconds of the Length of the loaded media are displayed in labels when the user clicks a button.

type

  HMSRec = record

    Hours: byte;

    Minutes: byte;

    Seconds: byte;

    NotUsed: byte;

  end;

procedure TForm1.Button1Click(Sender: TObject);

var

  TheLength: LongInt;

begin

  TimeFormat := tfHMS; { Set time format - note that some devices don't support tfHMS }

  TheLength := MediaPlayer1.Length; { Store length of currently loaded media in var }

  with HMSRec(TheLength) do { Typecast TheLength as a HMSRec record }

  begin

    Label1.Caption := IntToStr(Hours);   { Display Hours in Label1 }

    Label2.Caption := IntToStr(Minutes); { Display Minutes in Label2 }

    Label3.Caption := IntToStr(Seconds); { Display Seconds in Label3 }

  end;

end;


TIndexDef object

Properties	Methods

Unit

DBTables

Description

The TIndexDef object describes the index for a table.

Use the Fields property to get a list of the fields in the index. Use the Name property to get the name of the index. Test the flags in the Options property for a specific characteristic of the index.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Expression	Name

Fields	Options


Methods

 Key methods

ClassName	ClassType	Destroy

ClassParent	Create	Free


TIndexDefs object

Properties	Methods

Unit

DBTables

Description

The TIndexDefs object holds the set of available indexes for a table.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Count	Items


Methods

 Key methods

Add	ClassType	FindIndexForFields

Assign	Clear	Free

ClassName	Create	IndexOf

ClassParent	Destroy	Update


TIndexOptions type

Unit

DB

Declaration

TIndexOptions = set of (ixPrimary, ixUnique, ixDescending, ixExpression,
  ixCaseInsensitive);

Description

The TIndexOptions type is the set of values that can be used in creating a new index. It is used by the AddIndex method of a dataset component.

Note	 :	For dBASE tables, ixCaseInsensitive is not supported.


TIniFile object

Methods

Unit

IniFiles

Description

The TIniFile object permits your application to write and read an .INI file.

Your application can retrieve all the strings in a section of an .INI file by calling the ReadSection method; or it can retrieve a single Boolean, integer, or string value by calling the ReadBool, ReadInteger, or ReadString methods.

To erase an entire section of an .INI file, use the EraseSection method.

Your application can change the settings in an existing .INI file. To change a Boolean value, call the WriteBool method. To change an integer value, call the WriteInteger method. Finally, to change a string value, call the WriteString method.

In addition to these methods, this object also has the methods that apply to all objects.


Methods

 Key methods

ClassName	FileName	ReadString

ClassParent	Free	WriteBool

ClassType	ReadBool	WriteInteger

Create	ReadInteger	WriteString

Destroy	ReadSection

EraseSection	ReadSectionValues


TIntegerField component

Properties	Methods	Events

Unit

DBTables

Description

It represents a field of a record in a dataset. It is represented as a binary value with a range from -2,147,483,648 to 2,147,483,647. Use TIntegerField for fields that hold large, signed whole numbers.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value. Set the MinValue or the MaxValue property to limit the smallest or largest value permitted in a field.

A TIntegerField component is an indirect descendent of TComponent. TIntegerField has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayFormat	MinValue

AsBoolean	DisplayLabel	Name

AsDateTime	DisplayName	Owner

AsFloat	DisplayText	ReadOnly

AsInteger	DisplayWidth	Required

AsString	EditFormat	Size

Calculated	FieldName	Tag

CanModify	FieldNo	Text

DataSet	Index	Value

DataSize	IsIndexField	Visible

DataType	IsNull

MaxValue


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TItemStates type

Unit

ComCtrls

Declaration

TItemState = (isNone, isCut, isDropHilited, isFocused, isSelected);

TItemStates = set of TItemState;

Description

The TItemStates type is a set of the possible states that determine a list item's appearance and functionality. A parameter of this type is used by the GetNextItem method of the list view to get the next item in the list view with the specified state.


Title property

Applies to

TColumn, TPrinter objects; TApplication, TOpenDialog, TSaveDialog components

Description

The Title property specifies the text used to title an object, component, or application.

Title property for applications

Title property for Open and Save dialog boxes

Title property for printer objects

Title property for column objects


Title property

See also	Example

Applies to

TApplication component

Declaration

property Title: string;

Description

The Title property determines the text that appears with an icon representing your application when it is minimized. The default value is the project name (the name of the project file without the .PRJ file extension).

You can set the title at run time, or you can enter the value of the Title property on the Application page of the Options|Project Options dialog box.


Example

procedure TForm1.FormCreate(Sender: TObject);

begin

  Application.Title := 'My Incredible Application';

end;


See also

Application variable

Caption property

Icon property

Minimize method


Title property

Example

Applies to

TOpenDialog, TSaveDialog components

Declaration

property Title: string;

Description

The Title property determines the text that appears in the dialog box's title bar.


Example

This code displays the Open dialog box with the text "Open Pascal files" in its title bar and lists only Pascal files in the list box:

procedure TForm1.Button1Click(Sender: TObject);

begin

  OpenDialog1.Filter := 'Pascal files (*.PAS)|*.PAS';

  OpenDialog1.Title := 'Open Pascal files';

  OpenDialog1.Execute;

end;


Title Property for Printer Objects
Title property

See also	Example

Applies to

TPrinter objects

Declaration

property Title: string;

Description

Run-time only. The Title property determines the text that appears listed in the Print Manager and on network header pages.


Example

This line of code sets the value of the Title property for the printer object:

Printer.Title := 'My incredible application';


See also

Printer variable


Title property for columns
Title property

Applies to

TColumn objects

Declaration

property Title: TColumnTitle;

Description

The Title property returns a TColumnTitle object representing the title of the column. You can change the title's appearance by changing the TColumnTitle's properties.


 TLabel component

Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

 The TLabel component is a nonwindowed control that displays text on a form. Usually this text labels some other control.

The text of a label is the value of its Caption property. Within the caption, you can include an accelerator key. When the user presses the accelerator key, the control that is the value of the label's FocusControl becomes the active control on the form.

How the text of the caption aligns within the label is determined by the value of the Alignment property. You can have the label resize automatically to fit a changing caption if you set the AutoSize property to True. If you prefer to have the text wrap, set WordWrap to True.

If you want a label to appear on top of a graphic, but you want to be able to see through the label so that part of the graphic isn't hidden, set the Transparent property to True.

The TLabel component is an indirect descendent of TGraphicControl. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all controls.


Properties

 Run-time only          [image] Key properties

Align	FocusControl	PopupMenu

Alignment	Font	ShowAccelChar

AutoSize	Height	ShowHint

BoundsRect	Hint	Tag

Caption	Left	Top

Color	Name	Transparent

ComponentIndex	Owner	Visible

Cursor	Parent	Width

DragCursor	ParentColor	WordWrap

DragMode	ParentFont

Enabled	ParentShowHint


Methods

 Key methods

BeginDrag	Free	ScaleBy

BringToFront	GetTextBuf	ScreenToClient

ClientToScreen	GetTextLen	SendToBack

Create	Hide	SetBounds

Destroy	Invalidate	SetTextBuf

Dragging	Refresh	Show

EndDrag	Repaint	Update


Events

 Key events

OnClick	OnDragOver	OnMouseMove

OnDblClick	OnEndDrag	OnMouseUp

OnDragDrop	OnMouseDown	OnStartDrag


TLeftRight type

Unit

Classes

Declaration

TAlignment = (taLeftJustify, taRightJustify, taCenter);

TLeftRight = taLeftJustify..taRightJustify;

Description

TLeftRight is the type of the Alignment property of check boxes and radio buttons.


TList object

Properties	Methods

Unit

Classes

Description

The TList object is used to maintain lists of objects.

The List property is a list of pointers to all the objects in the list. You can access a particular item referenced in the list using the Items property. To find the position of an item in the list, use the IndexOf method.

You can add, delete, insert, remove, move, and exchange items in the list using the Add, Delete, Insert, Remove, Move, and Exchange methods. Use the Count property to determine how many items are in the list.

Use the Sort method to perform a Quick Sort on the list. Use the First method to move to the beginning of the list, and use the Last method to move to the end of the list.

The number of items the list can maintain is determined by the value of the Capacity property. If you need to increase the size of the list, call the Expand method. You can remove all nil pointers in the list with the Pack method.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Capacity	Items

Count	List


Methods

 Key methods

Add	Delete	IndexOf

ClassName	Destroy	Insert

ClassParent	Exchange	Last

ClassType	Expand	Pack

Create	First	Remove

Clear	Free	Sort


TListArrangement type

Unit

ComCtrls

Declaration

TListArrangement = (arAlignBottom, arAlignLeft, arAlignRight, arAlignTop, arDefault, arSnapToGrid);

Description

The TListArrangement type defines the possible values of the Code parameter for the Arrange method of the TListView component. These values are used to specify how items are to be arranged in a list view.


 TListBox component

See also	Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

The TListBox component is a Windows list box. A list box displays a list from which users can select one or more items.

The list of items in the list box is the value of the Items property. The ItemIndex property indicates which item in the list box is selected.

You can add, delete, and insert items in the list box using the Add, Delete, and Insert methods of the Items object, which is of type TStrings. For example, to add a string to a list box, you could write this line of code:

ListBox1.Items.Add('New item');

You can change how the list box appears. If you want the list box to have multiple columns, change the value of the Columns property. Sort the list box items with the Sorted property.

You can allow users to select more than one item at a time by setting the MultiSelect property to True. The ExtendedSelect property determines how multiple items can be selected. To determine whether a particular item is selected and how many items are selected, check the values of the Selected and SelCount properties, respectively.

You can make the list box an owner-draw list box by changing the Style property.

You can drag and drop objects into a list box. For more information, see Dragging and Dropping.

The TListBox component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Hint	SelCount

BorderStyle	IntegralHeight	Selected

Canvas	ItemIndex	ShowHint

Color	ItemHeight	Showing

Columns	Items	Sorted

ComponentIndex	Left	Style

Ctl3D	MultiSelect	TabOrder

Cursor	Name	TabStop

DragCursor	Owner	Tag

DragMode	Parent	Top

Enabled	ParentColor	TopIndex

ExtendedSelect	ParentCtl3D	Visible

Font	ParentFont	Width

Height	ParentShowHint

HelpContext	PopupMenu


Methods

 Key methods

BeginDrag	GetTextBuf	ScrollBy

BringToFront	GetTextLen	SendToBack

Clear	Hide	SetBounds

ClientToScreen	ItemAtPos	SetFocus

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy

Free	ScreenToClient


Events

 Key events

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag

OnDrawItem	OnKeyUp

OnEndDrag	OnMeasureItem


See also

Creating an owner-draw control

TComboBox component

TDBListBox component


TListBoxStyle type

Unit

StdCtrls

Declaration

TListBoxStyle = (lbStandard, lbOwnerDrawFixed, lbOwnerDrawVariable);

Description

The TListBoxStyle type is the type of the Style property for a list box (TListBox component).


TListColumn object

Properties	Methods

Unit

ComCtrls

Description

The TListColumn object is an individual column in a list view control. To display columns in a list view, use the Items property of the list view to Add columns and set the ViewStyle property to vsReport. The ShowColumnHeaders property must also be set to True. Use the Caption property to set the label for the column.

The TListColumn object is an indirect descendent of TPersistent. In addition to the following properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Alignment	Count	Items

Caption	Index	Width


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


TListColumns object

Properties	Methods

Unit

ComCtrls

Description

It maintains a list of columns (TListColumn object). The Columns property of the list view control which is of type TListColumns maintains the columns in the list view. To add a column to the list columns object, use its Add method. To access an individual column, use the list column's Items property along with the index of the column.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. The TListColumns object is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Count	Items	Owner


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


TListItem object

Properties	Methods

Unit

ComCtrls

Description

The TListItem object is an individual item of a TListView control. A list view item is represented as a line, or row of the list view.

A list item contains a Caption and Data defined by your application. Caption contains a string, and Data contains a pointer to a data structure to be associated with each list item. Use the Delete method to delete a list item. If the ReadOnly property is False, the user is allowed to edit the Caption.

Each item is identified by a unique Index. Index corresponds to the index of the Items property of the TListView control. The MakeVisible method scrolls a list item into view if the item is not in view. The ListView property specifies the list view that is the owner of the item. The SubItems property gives access to the sub items of the list item.

The Focused property determines whether the item has the focus, that is, it's surrounded by a standard focus rectangle. Only one item can have the focus. The Selected property determines whether the list item is selected. The DropTarget property specifies if the item is the target of a drag and drop operation.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Caption	ImageIndex	ReadOnly

Cut	Index	Selected

Data	ListView	StateIndex

DropTarget	Owner	SubItems

Focused	OverlayIndex

Handle	Position


Methods

 Key methods

Assign	Create	EditCaption

CancelEdit	Delete	Free

ClassName	Destroy	MakeVisible

ClassParent	DisplayRect	Update

ClassType


TListItems object

Properties	Methods

Unit

ComCtrls

Description

The TListItems object maintains a list of list items (TListItem object). The Items property of the list view is of type TListItems and contains the list items for the list view control.

The TListItems object has methods to Add and Insert a list item into the list view control. The Count property returns the number of list items in the list view, and the IndexOf method returns the index of the specified item. Use the Item property along with the list item's index to access the list item.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Count	Item

Handle	Owner


Methods

 Key methods

Add	ClassType	Destroy

Assign	Clear	Free

ClassName	Create	IndexOf

ClassParent	Delete	Insert


{bml dlistvw.bmp} TListView component
 TListView component

Properties	Methods	Events

Unit

ComCtrls

Description

The TListView component is a list of items that can be displayed in a variety of ways. The ViewStyle property determines whether items are displayed in columns with column headers and sub-items, or vertically or horizontally, with small or large icons.

The Items property allows you to Add, Delete, modify the Caption, add SubItems, and pick icon images for the items in the list view. Use the Columns property to add columns to the list view. To see the column headers, set the ViewStyle to vsReport and set the ShowColumnHeaders property to True. The ColumnClick property specifies whether the column header behaves like a button. The OnColumnClick event occurs when the user has clicked on a column heading and ColumnClick is set to True.

When using the list view with a ViewStyle of vsIcon, icons from the image list specified in the LargeImages property are used. In the IconOptions property, the AutoArrange property arranges the icons in the list view automatically as needed, the Arrangement property specifies where the icons are aligned in the list view, and the WrapText property specifies whether to wrap the text of the item's Caption if it would go beyond the width of the icon. When using a ViewStyle of vsSmallIcon, icons from the image list specified in the SmallImages property are used.

To allow editing of the caption of a list item, set ReadOnly to False. The OnEditing and OnEdited events occur when the user begins and finishes editing the caption, respectively.

The TListView component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	DragCursor	ReadOnly

AllocBy	DragMode	SelCount

BorderStyle	DropTarget	Selected

BoundingRect	Focused	ShowColumnHeaders

BoundsRect	Font	ShowHint

Brush	Handle	Showing

ClientHeight	Height	SmallImages

ClientOrigin	HelpContext	SortType

ClientRect	HideSelection	StateImages

ClientWidth	IconOptions	TabOrder

Color	ItemFocused	TabStop

Column	Items	Tag

Columns	LargeImages	Top

ComponentCount	Left	TopItem

ComponentIndex	MultiSelect	ViewOrigin

Components	Name	ViewStyle

ControlCount	Owner	Visible

Controls	Parent	VisibleRowCount

Ctl3D	ParentShowHint	Width

Cursor	PopupMenu


Methods

 Key methods

AlphaSort	FindComponent	RemoveComponent

Arrange	FindData	RemoveControl

Assign	Focused	Repaint

BeginDrag	Free	ScaleBy

BringToFront	FindCaption	Refresh

CanFocus	GetItemAt	ScreenToClient

ClassName	GetNearestItem	Scroll

ClassParent	GetNextItem	ScrollBy

ClassType	GetSearchString	SendToBack

ClientToScreen	GetTextBuf	SetBounds

ContainsControl	GetTextLen	SetFocus

ControlAtPos	HandleAllocated	SetTextBuf

Create	HandleNeeded	Show

CustomSort	Hide	Sort

Destroy	InsertComponent	StringWidth

InsertControl	Update

Dragging	Invalidate	UpdateItems

EndDrag	IsEditing


Events

 Key events

OnChange	OnDragOver	OnKeyPress

OnChanging	OnEdited	OnKeyUp

OnClick	OnEditing	OnMouseDown

OnColumnClick	OnEndDrag	OnMouseMove

OnCompare	OnEnter	OnMouseUp

OnDblClick	OnExit	OnStartDrag

OnDeletion	OnInsert

OnDragDrop	OnKeyDown


TLoadResource type

Unit

Controls

Declaration

TLoadResource = (lrDefaultColor, lrDefaultSize, lrFromFile, lrMap3DColors, lrTransparent, lrMonoChrome);

Description

The TLoadResource type is used to specify the resource flags for the GetResource method.


TLocale type

Unit

DB

Declaration

TLocale = Pointer;

Description

The TLocale type is the type of a Locale or DBLocale property. These properties are only used or needed when making direct calls to the Borland Database Engine.


TLocateOptions type

Unit

DB

Declaration

type
  TLocateOption = (loCaseInsensitive, loPartialKey);
  TLocateOptions = set of TLocateOption;

Description

The TLocateOptions type defines the possible values for the Options parameter of the Locate method of the TTable, TQuery, and TStoredProc components, as described in the following table:

Value	Description

loCaseInsensitive	Key fields and key values are matched without regard to case.

loPartialKey	Key values can include only part of the matching key field value; for example, 'HAM' would match both 'HAMM' and 'HAMMER.'


 TMainMenu component

See also	Properties	Methods	Tasks

Unit

Menus

Description

The MainMenu component encapsulates a menu bar and its accompanying drop-down menus for a form. To begin designing a menu, add a main menu component to your form, and double-click the component. See the topic Menu Designer.

The items on the menu bar and in its drop-down menus are specified with the Items object, a property of a main menu. The Items object is of type TMenuItem. Your application can use the Items property to access a particular command on the menu. To find out how many itmes a MainMenu or MenuItem contains use Menu.Items.Count.

You can choose to have the menus of one form merge with those of another using the AutoMerge property and the Merge and Unmerge methods.

The MainMenu component is an indirect descendent of TComponent. In addition to the following properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

AutoMerge	Items	Owner

ComponentIndex	Name	Tag


Methods

 Key methods

Create	Free	Unmerge

Destroy	GetHelpContext

FindItem	Merge


See also

ShortCut function

ShortCutToKey procedure

ShortCutToText function

TextToShortCut function

TPopupMenu component


TMaskEdit component

See also	Properties	Methods	Events	Tasks

Unit

Mask

Description

 A mask edit box is much like an ordinary edit box (TEdit component), except you can require the user to enter only valid characters through the use of an EditMask property. You can also use the mask to format the display of data.

The text the user enters in the edit box is the value of the Text property, just as it is with any edit box. The text of the edit box with the mask specified in the EditMask property applied to it is the value of the EditText property.

Your application can tell if the value of Text changes by checking the value of the Modified property. To limit the number of characters users can enter into the mask edit box, use the MaxLength property.

If you want to prevent the user from changing the value of the Text property by typing in the edit box, set the ReadOnly property to True.

You can choose to have the text in a mask edit box automatically selected whenever it becomes the active control with the AutoSelect property. At run time, you can select all the text in the edit box with the SelectAll method. To find out which text in the edit box the user has selected or to replace selected text, use the SelText property. To clear selected text, call the ClearSelection method. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

You can cut, copy, and paste text to and from a mask edit box using the CutToClipboard, CopyToClipboard, and PasteFromClipboard methods.

Your application can display a specified character rather than the actual character typed into an edit box. If the edit box is used to enter a password, onlookers won't be able to read the typed text. Specify the special character with the PasswordChar property.

If you want the edit box to automatically resize to accommodate a change in font size, use the AutoSize property.

A mask edit box is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Height	ReadOnly

AutoSelect	HelpContext	SelLength

AutoSize	Hint	SelStart

BorderStyle	IsMasked	SelText

CharCase	Left	ShowHint

Color	MaxLength	Showing

ComponentIndex	Modified	TabOrder

Ctl3D	Name	TabStop

Cursor	Owner	Tag

DragCursor	Parent	Text

DragMode	ParentColor	Top

EditMask	ParentCtl3D	Visible

EditText	ParentFont	Width

Enabled	ParentShowHint

Font	PasswordChar


Methods

 Key methods

BeginDrag	Focused	ScrollBy

BringToFront	Free	SelectAll

CanFocus	GetSelTextBuf	SendToBack

Clear	GetTextBuf	SetBounds

ClearSelection	GetTextLen	SetFocus

ClientToScreen	Hide	SetSelTextBuf

CopyToClipboard	Invalidate	SetTextBuf

Create	PasteFromClipboard	Show

CutToClipboard	Refresh	Update

Destroy	Repaint	ValidateEdit

Dragging	ScaleBy

EndDrag	ScreenToClient


Events

 Key events

OnChange	OnEndDrag	OnKeyUp

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag


See also

TDBEdit component

TEdit component


 TMediaPlayer component

Properties	Methods	Events	Tasks

Unit

MPlayer

Description

A TMediaPlayer component icontrols devices that provide a Media Control Interface (MCI) driver. The component is a set of buttons (Play, Stop, Eject, and so on) that controls a multimedia device such as a CD-ROM drive, a MIDI sequencer, or a VCR. A multimedia device may be hardware or software.

The media player component consists of multiple buttons. These buttons can be clicked with the mouse, but are not separate objects or button components.

Button	Value	Action

Play	btPlay	Plays the media player

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Stop	btStop	Stops playing or recording

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks

Step	btStep	Moves forward a number of frames

Back	btBack	Moves backward a number of frames

Record	btRecord	Starts recording

Eject	btEject	Ejects the medium

The multimedia device is played, paused, stopped, and so on when the user clicks the corresponding button on the TMediaPlayer component. The device can also be controlled by the control methods that correspond to the buttons (Play, Pause, Stop, Next, Previous, Step, Back, StartRecording, and Eject).

The type of multimedia device (such as dtWaveAudio or dtVideodisc) is specified by the DeviceType property. If the device stores its media in a file, the name of the media file is specified by the FileName property. If DeviceType is dtAutoSelect, the media player attempts to determine the type of device from the extension of the file specified by FileName.

To open a multimedia device, call the Open method. To have the media player attempt to open the device specified by DeviceType automatically when the media player component is created at run time, set the AutoOpen property to True.

A TMediaPlayer component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	ErrorMessage	ShowHint

AutoEnable	FileName	Showing

AutoOpen	Frames	Start

AutoRewind	Height	StartPos

BoundsRect	HelpContext	TabOrder

Capabilities	Hint	TabStop

ColoredButtons	Left	Tag

ComponentIndex	Length	TimeFormat

Cursor	Mode	Top

DeviceID	Name	TrackLength

DeviceType	Notify	TrackPosition

Display	NotifyValue	Tracks

DisplayRect	Owner	Visible

Enabled	Parent	VisibleButtons

EnabledButtons	ParentShowHint	Wait

EndPos	Position	Width

Error	Shareable


Methods

 Key methods

Back	GetTextBuf	Rewind

BeginDrag	GetTextLen	Save

BringToFront	Hide	ScaleBy

CanFocus	Invalidate	ScreenToClient

ClientToScreen	Next	SendToBack

Close	Open	SetBounds

Create	Pause	SetFocus

Destroy	PauseOnly	SetTextBuf

Dragging	Play	Show

Eject	Previous	StartRecording

EndDrag	Refresh	Step

Focused	Repaint	Stop

Free	Resume	Update


Events

 Key events

OnClick	OnExit	OnPostClick

OnEnter	OnNotify


 TMemo component

Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

 A TMemo component displays text to the user and permits the user to enter text into the application much like a TEdit component. The TMemo component permits multiple lines to be entered or displayed, unlike TEdit.

The text in the memo is the value of the Text property. Your application can tell if the value of Text changes by checking the value of the Modified property. To limit the number of characters users can enter into the memo, use the MaxLength property

You can also access the text line by line using the Lines property. If you want to work with the text as one chunk, use the Text property. If you want to work with individual lines of text, the Lines property will suit your needs better.

You can add, delete, insert, and move lines in a memo control using the Add, Delete, and Insert methods of the Lines object, which is of type TStrings. For example, to add a line to a memo, you could write this line of code:

Memo1.Lines.Add('Another line is added');

You can cut, copy, and paste text to and from a memo control using the CutToClipboard, CopyToClipboard, and PasteFromClipboard methods.

If you want the user to be able to read the text in the memo but not to change it, set the ReadOnly property to True.

Several properties affect how the memo appears and how text is entered. You can choose to supply scroll bars in the memo with the ScrollBars property. If you want the text to break into lines, set WordWrap to True. If you want the user to be able to use tabs in the text, set WantTabs to True.

At run time, you can select all the text in the memo with the SelectAll method. To find out which text in the memo the user has selected, or to replace selected text, use the SelText property. To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

A TMemo component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Left	SelStart

Alignment	Lines	SelText

BorderStyle	MaxLength	ShowHint

Color	Modified	Showing

ComponentIndex	Name	TabOrder

Ctl3D	Owner	TabStop

Cursor	Parent	Tag

DragCursor	ParentColor	Text

DragMode	ParentCtl3D	Top

Enabled	ParentFont	Visible

Font	ParentShowHint	WantReturns

Height	PopupMenu	WantTabs

HelpContext	ReadOnly	Width

HideSelection	ScrollBars	WordWrap

Hint	SelLength


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	ScrollBy

CanFocus	GetSelTextBuf	SelectAll

Clear	GetTextBuf	SendToBack

ClearSelection	GetTextLen	SetBounds

ClientToScreen	Hide	SetFocus

CopyToClipboard	Invalidate	SetSelTextBuf

Create	PasteFromClipboard	SetTextBuf

CutToClipboard	Refresh	Show

Destroy	RemoveComponent	Update

Dragging	Repaint

EndDrag	ScaleBy


Events

 Key events

OnChange	OnEndDrag	OnKeyUp

OnClick	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnKeyDown	OnMouseUp

OnDragOver	OnKeyPress	OnStartDrag


TMemoField component

Properties	Methods	Events

Unit

DBTables

Description

A TMemoField component represents a field of a record in a dataset. It is represented by a value consisting of an arbitrary set of bytes with indefinite size. The bytes should correspond to text data.

Use the Assign method to transfer another component to a TMemoField. Use the LoadFromFile method to load a field's contents from a file. Use LoadFromStream method to load a field from a Stream. Use SaveToFile method to write a field's contents to a file. Use SaveToStream method to write a field's contents to a Stream.

A TMemoField component is an indirect descendent of TComponent. TMemoField has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Name

AsBoolean	DisplayName	Owner

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditMask	Size

AsString	EditMaskPtr	Tag

Calculated	FieldName	Text

CanModify	FieldNo	Transliterate

DataSet	Index	Visible

DataSize	IsIndexField

DataType	IsNull


Methods

 Key methods

Assign	FocusControl	LoadFromStream

AssignValue	Free	SaveToFile

Clear	GetData	SaveToStream

Create	IsValidChar	SetData

Destroy	LoadFromFile


Events

 Key events

OnChange	OnSetText

OnGetText	OnValidate


TMenuBreak type

Unit

Menus

Declaration

TMenuBreak = (mbNone, mbBreak, mbBarBreak);

Description

The TMenuBreak type defines the values the Break property of a menu item can have.


TMenuItem component

See also	Properties	Methods	Events	Tasks

Unit

Menus

Description

A TMenuItem component contains the properties, methods, and events for each menu item on a menu (TMainMenu or TPopupMenu). Each TMainMenu or TPopupMenu component may contain multiple menu items. As you design a menu with the Menu Designer, you are creating a menu item object for each command on the menu.

When the user chooses a command on a menu, that menu item's OnClick event occurs.

The text that appears on a menu is the Caption of a menu item. You can also use the caption of the menu item to specify an accelerator key for a menu item or to provide a line that separates a menu into parts. You can assign a shortcut key to a menu item with the ShortCut property.

You can use the Items property to access a subitem of the current menu item.

If you want a check mark to alternately appear and disappear next to a menu item when the user has selected it, use the Checked property. If you want to disable a menu item (make it dim and unavailable to the user), set the Enabled property to False. You can simulate a user clicking a menu item with the Click method. If you are working with a lengthy menu, you can break the menu into two or more columns with the Break property.

When you want to merge menus of one form with those of another, use the GroupIndex property of menu items, and either the AutoMerge property or the Merge and Unmerge methods of a main menu (TMainMenu).

You can insert and delete menu items from a menu at run time with the Insert and Remove methods.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Break	Enabled	Owner

Caption	GroupIndex	Parent

Checked	HelpContext	RadioItem

Command	Hint	ShortCut

ComponentIndex	Items	Tag

Count	MenuIndex	Visible

Default	Name


Methods

 Key methods

Add	Delete	IndexOf

Click	Destroy	Insert

Create	Free	Remove


Events

 Key events

OnClick


See also

ShortCut function

ShortCutToKey procedure

ShortCutToText function

TextToShortCut function

TMainMenu component

TPopupMenu component


TMetafile object

Properties	Methods	Events

Unit

Graphics

Description

The TMetafile object encapsulates the Win32 Enhanced Metafile graphic (EMF file format).

The height and width in pixels of the metafile are specified by the Height and Width properties, respectively.

To load a metafile from a file, call the LoadFromFile method. To save a metafile to a file, call SaveToFile.

To draw a metafile on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TMetafile as a parameter. The Enhanced property determines how the metafile will be stored on disk. If Enhanced is True, the metafile is stored as an .EMF (Win32 Enhanced Metafile). If Enhanced is False, the metafile is stored as a .WMF (Windows 3.1 Metafile, with Aldus header).

The MMWidth and MMHeight properties are the width and height, respectively, of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles. The Inch property is the units per inch assumed by a WMF metafile. Used to alter scale when writing as WMF, but otherwise this property is obsolete. Enhanced metafiles maintain complete scale information internally.

The CreatedBy property is the optional name of the author or application used to create the metafile, embedded in the metafile. The Description property is the optional text description embedded in the metafile. To set the CreatedBy and Description strings of a new metafile, use the TMetafileCanvas' CreateWithComment method.

When the metafile is modified, an OnChange event occurs.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects. A TMetafile object is an indirect descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

CreatedBy	Handle	MMWidth

Description	Height	Palette

Enhanced	Inch	Width

Empty	MMHeight


Methods

 Key methods

Assign	Destroy	SaveToFile

Create	LoadFromFile


Events

 Key events

OnChange


TMetafileCanvas object

Methods

Unit

Graphics

Description

The TMetafileCanvas object allows you to create a metafile image from scratch, but you must draw the image in a metafile canvas first.  When the canvas is destroyed, it transfers the image into the metafile object provided to the canvas constructor. After the image is drawn on the canvas and the canvas is destroyed, the image is 'playable' in the metafile object. For example:

MyMetafile := TMetafile.Create;

with TMetafileCanvas.Create(MyMetafile, 0) do

  try

    Brush.Color := clRed;

    Ellipse(0,0,100,100);

    ...

  finally

    Free;

  end;

Form1.Canvas.Draw(0,0,MyMetafile); {1 red circle }

To add to an existing metafile image, create a metafile canvas and play the source metafile into the metafile canvas. For example:

{continued from previous example, so MyMetafile contains an image }

with TMetafileCanvas.Create(MyMetafile, 0) do

  try

    Draw(0,0,MyMetafile);

    Brush.Color := clBlue;

    Ellipse(100,100,200,200);

    ...

  finally

    Free;

  end;

Form1.Canvas.Draw(0,0,MyMetafile); {1 red circle and 1 blue circle }

In addition to these methods, this object also has the properties, methods, and events that apply to the TCanvas object.


Methods

 Key methods

CreateWithComment method


TModalResult type

Unit

Forms

Declaration

TModalResult = Low(Integer)..High(Integer);

Description

The TModalResult type is the type of the ModalResult property.


TMouseButton type

See also

Unit

Controls

Declaration

TMouseButton = (mbLeft, mbRight, mbMiddle);

Description

The TMouseButton type defines the mouse-button constants used by mouse-event handlers to distinguish which button generated the mouse event.


See also

TMouseEvent type


TMPBtnType type

Unit

MPlayer

Declaration

TMPBtnType = (btPlay, btPause, btStop, btNext, btPrev, btStep, btBack, btRecord, btEject);

Description

The TMPBtnType type defines the buttons of a TMediaPlayer component. The buttons are included in a set of the TButtonSet type of the ColoredButtons, EnabledButtons, and VisibleButtons properties. TMPBtnType is also used for the Button parameter of the OnClick and OnPostClick events of a media player.


TMPDevCapsSet type

Unit

MPlayer

Declaration

TMPDevCaps = (mpCanStep, mpCanEject, mpCanPlay, mpCanRecord, mpUsesWindows);

TMPDevCapsSet = set of TMPDevCaps;

Description

The TMPDevCapsSet type is a set of the capabilities of the open multimedia device used with a TMediaPlayer component. TMPDevCapsSet is the type of the Capabilities property.


TMPDeviceTypes type

Unit

MPlayer

Declaration

TMPDeviceTypes = (dtAutoSelect, dtAVIVideo, dtCDAudio, dtDAT, dtDigitalVideo, dtMMMovie,
dtOther, dtOverlay, dtScanner, dtSequencer, dtVCR, dtVideodisc, dtWaveAudio);

Description

The TMPDeviceTypes type contains the multimedia device types that can be opened by a TMediaPlayer component. TMPDeviceTypes is the type of the DeviceType property.


TMPModes type

Unit

MPlayer

Applies to

TMediaPlayer component

Declaration

TMPModes = (mpNotReady, mpStopped, mpPlaying, mpRecording, mpSeeking, mpPaused, mpOpen);

Description

The TMPModes type defines the modes for a multimedia device used with a TMediaPlayer component. TMPModes is the type of the Mode property.


TMPNotifyValues type

Unit

MPlayer

Declaration

TMPNotifyValues = (nvSuccessful, nvSuperseded, nvAborted, nvFailure);

Description

The TMPNotifyValues type defines the notification values for a multimedia device used with a TMediaPlayer component. TMPNotifyValues is the type of the NotifyValue property.


TMPTimeFormats type

Unit

MPlayer

Declaration

TMPTimeFormats = (tfMilliseconds, tfHMS, tfMSF, tfFrames, tfSMPTE24, tfSMPTE25, tfSMPTE30,
  tfSMPTE30Drop, tfBytes, tfSamples, tfTMSF);

Description

The TMPTimeFormats type defines the time formats for a multimedia device used with a TMediaPlayer component. TMPTimeFormats is the type of the TimeFormat property.


TMsgDlgButtons type

Unit

Dialogs

Declaration

TMsgDlgBtn = (mbYes, mbNo, mbOK, mbCancel, mbAbort, mbRetry, mbIgnore, mbAll, mbHelp);

TMsgDlgButtons = set of TMsgDlgBtn;

Description

The TMsgDlgButtons type defines the set of values a button in a message box can have. The TMsgDlgButtons type is used by the MessageDlg and MessageDlgPos functions.


TMsgDlgType type

Unit

Dialogs

Declaration

TMsgDlgType = (mtWarning, mtError, mtInformation, mtConfirmation, mtCustom);

Description

The TMsgDlgType type defines the values describing the type of message box. The TMsgDlgType is used by the MessageDlg and MessageDlgPos functions.


TNavigateBtn type

Unit

DBCtrls

Declaration

TNavigateBtn = (nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh);

Description

The TNavigateBtn type defines the possible values in the TButtonSet type. It is also used in the Click method and the ENavClick type.


TNodeAttachMode type

Unit

ComCtrls

Declaration

TNodeAttachMode = (naAdd, naAddFirst, naAddChild, naAddChildFirst, naInsert);

Description

The TNodeAttachMode type is the set of the possible ways in which an item can be attached to a tree view control. A variable of this type is passed to the tree views MoveTo method to specify how an item is reattached to the tree view in relation to a destination node when the item is moved.


 TNotebook component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The TNotebook component is a component that can display multiple pages, each with its own set of controls. Notebook components are frequently used with tab set controls (TTabSet) to let the user select pages in the notebook by clicking a tab. TNotebook is provided for backward compatibility.

The TTabbedNoteBook control is included primarily for backwards compatibility with Delphi 1.0 applications. It is recommended that new Delphi 2.0 applications use the TPageControl instead.

The pages available in the notebook control are the strings specified as the value of the Pages property. You can access a particular page in the notebook either with the PageIndex property or the ActivePage property.

If you are using a notebook with a tab set, this is the code that connects the pages of the notebook with the tabs in the tab set, displaying the page strings as the text of the tabs:

TabSet1.Tabs := Notebook1.Pages;

Then, in the OnClick event handler of the tabset, this line of code changes the current page in the notebook control when the user clicks a tab:

Notebook1.PageIndex := TabSet1.TabIndex;

If you are using a notebook and a tab set together, you usually want the tab set at the bottom of the form and the notebook to take up the remaining space on the form. To align the components this way, use their Align properties.

The TNotebook component is an indirect descendent of TWinControl. In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.

Note:	The TTabbedNotebook cannot be used in form inheritance. If a TTabbedNotebook is included in a form, that form cannot be used as the base class for other forms. It is recommended that you use a TPageControl instead, which does support form inheritance.


Properties

 Run-time only          [image] Key properties

ActivePage	Enabled	ParentFont

Align	Font	ParentShowHint

BoundsRect	Handle	PopupMenu

Color	Height	ShowHint

ComponentCount	HelpContext	Showing

ComponentIndex	Left	TabOrder

Components	Name	TabStop

ControlCount	Owner	Tag

Controls	PageIndex	Top

Ctl3D	Pages	Visible

Cursor	Parent	Width

DragCursor	ParentColor

DragMode	ParentCtl3D


Methods

 Key methods

BeginDrag	Focused	Repaint

BringToFront	Free	ScaleBy

CanFocus	GetTextBuf	ScreenToClient

ClientToScreen	GetTextLen	ScrollBy

ContainsControl	Hide	SendToBack

Create	InsertComponent	SetBounds

Destroy	InsertControl	SetTextBuf

Dragging	Invalidate	Show

EndDrag	Refresh	Update

FindComponent	RemoveComponent


Events

 Key events

OnClick	OnEndDrag	OnMouseMove

OnDblClick	OnEnter	OnMouseUp

OnDragDrop	OnExit	OnPageChanged

OnDragOver	OnMouseDown	OnStartDrag


TNotifyEvent type

Unit

Classes

Declaration

TNotifyEvent = procedure (Sender: TObject) of object;

Description

The TNotifyEvent type is the type for events that have no parameters. These events simply notify the component that a specific event occurred. For example, OnClick, which is type TNotifyEvent, notifies the control that a click event occurred on the control.


TNumberingStyle type

Unit

ComCtrls

Declaration

TNumberingStyle = (nsNone, nsBullet);

Description

The TNumberingStyle type defines the possible values of the Numbering property of the TParaAttributes object. TParaAttributes is the type of the Paragraph property of the TRichEdit component.


TNumericField component

Unit

DBTables

Declaration

TNumericField = class(TField);

Description

The TNumericField component is the ancestor component class for all field components that represent numeric data types.  The TNumericField component sets Alignment to right justification and defines the DisplayFormat and EditFormat properties.  TNumericField inherits the properties, methods, and events of the TField component.

You never use TNumericField directly in your applications. It serves only as a common class from which specific numeric field types are derived.


TNumGlyphs type

Unit

Buttons

Declaration

TNumGlyphs: 1..4;

Description

The TNumGlyphs type defines the range of values (1-4) the NumGlyphs property of a bitmap button (TBitBtn) or speed button (TSpeedButton) can assume.


TOleControl component

Unit

OleCtrls

Description

The TOleControl component is the base class from which all wrappers for OCX controls descend.  This class descends from TWinControl and handles the interactions with OLE necessary for using OCX controls in the Delphi environment.  It is unlikely that you will ever need to derive a component from this class.


Top property

Applies to

TListItem object; all controls; TFindDialog, TReplaceDialog components

Description

Top Property for all Controls and Find and Replace Dialogs

Top Property for List Items


Top property for list item objects
Top property

See also	Example

Applies to

All controls, TFindDialog, TReplaceDialog components

Declaration

property Top: Integer;

Description

The Top property determines the Y coordinate of the top left corner of a control, relative to its parent or containing control in pixels. If the control is contained in a TPanel, the Left and Top properties will be relative to the panel. If the control is contained directly by the form, it will be relative to the form. For forms, the value of the Top property is relative to the screen in pixels.

For the Find and Replace dialog boxes, Top is a run-time only property. The default value is -1.


Example

The following code moves a button 10 pixels up each time a user clicks it:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Button1.Top := Button1.Top - 10;

end;


See also

Left property

SetBounds method


Top property for list item objects
Top property

See also	Example

Applies to

TListItem object

Declaration

property Top: Integer;

Description

Run-time only. The Top property moves an item vertically to a specified position in pixels within the list view control's client area. The ViewStyle of the list view must be set to vsIcon or vsSmallIcons

Example

The following example sets the top of the selected list item to 5.

ListView1.Selected.Top := 5;


See also

TopItem property

ViewStyle property


ToPage property

See also	Example

Applies to

TPrintDialog component

Declaration

property ToPage: Integer;

Description

The value of the ToPage property determines on which page the print job ends. The default value is 0, which means no ending page is specified.


Example

This example uses a print dialog box on a form. The code sets up the print dialog box so that when it appears, the default values of 1 and 1 are the default starting and ending values for the Pages From and To edit boxes:

PrintDialog1.Options := [poPageNums];

PrintDialog1.FromPage := 1;

PrintDialog1.ToPage := 1;


See also

FromPage property

Options property


 TOpenDialog component

Properties	Methods	Tasks

Unit

Dialogs

Description

The TOpenDialog component makes an Open dialog box available to your application. The purpose of the dialog box is to let a user specify a file to open. Use the Execute method to display the Open dialog box.

When the user chooses OK in the dialog box, the user's filename selection is stored in the dialog box's FileName property, which you can then use to process as you want.

You can let the user decide which files to make visible in the list box of the Open dialog box with the Filter property. The user can then use the List Files of Type combo box to determine which files display in the list box. You set the default filter using the FilterIndex property.

You can permit the user to choose multiple filenames with the Options property so that the Files property contains a list of all the selected filenames in the list box. You can customize how the Open dialog box appears and behaves with the Options property.

If you want a file extension automatically appended to the filename typed in the File Name edit box of the Open dialog box, use the DefaultExt property.

The TOpenDialog component is an indirect descendent of TComponent. In addition to the following properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Filter	Options

Ctl3D	FilterIndex	Owner

DefaultExt	HelpContext	Tag

FileEditStyle	HistoryList	Title

FileName	InitialDir

Files	Name


Methods

 Key methods

Create	Execute

Destroy	Free


TOpenOptions type

Declaration

TOpenOption = (ofReadOnly, ofOverwritePrompt, ofHideReadOnly, ofNoChangeDir,

ofShowHelp, ofNoValidate, ofAllowMultiSelect, ofExtensionDifferent,

ofPathMustExist, ofFileMustExist, ofCreatePrompt, ofShareAware, ofNoReadOnlyReturn,

ofNoTestFileCreate, ofNoNetworkButton, ofNoLongNames, ofOldStyleDialog, ofNoDereferenceLinks);

TOpenOptions = set of TOpenOption;

Description

The TOpenOptions type contains the set of values the Options property of the Open dialog box (TOpenDialog) can assume.


TopIndex property

See also	Example

Applies to

TDirectoryListBox, TFileListBox, TListBox components

Declaration

property TopIndex: Integer;

Description

The TopIndex property is the index number of the item that appears at the top of the list box. You can use the TopIndex property to determine which item is the first item displayed at the top of the list box and to set it to the item of your choosing.


Example

This example uses a list box containing a list of strings, a button, and an edit box on a form. When the user runs the application and clicks the button, the third item in the list becomes the first item, and the index value of that item appears in the edit box. The index value displayed is 2, indicating the third item in the list (the first item in the list has an index value of 0):

procedure TForm1.FormCreate(Sender: TObject);

var

  Number: Integer;

begin

  for Number := 1 to 20 do

    ListBox1.Items.Add('Item ' + IntToStr(Number));

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  ListBox1.TopIndex := 2;

  Edit1.Text := IntToStr(ListBox1.TopIndex);

end;


See also

ItemIndex property

Items property

Sorted property


TopItem property

Applies to

TOutlineNode object; TTreeView, TListView component

Description

TopItem property for outline nodes

TopItem property for tree views

TopItem property for list views


TopItem property

See also

Applies to

TTreeView component

Declaration

property TopItem: TTreeNode;

Description

Run-time only. The TopItem property for tree views returns the topmost item in the tree view, and when changed, scrolls the tree view vertically so that the given item is topmost in the list view.


See also

GetFirstNode method

Level property

IndexOf method


TopItem property for list views
TopItem property

See also	Example

Applies to

TListView component

Declaration

property TopItem: TListItem;

Description

Run-time and read-only. The TopItem property returns the topmost visible item in the list view control. This information can be useful when a list view the scrolled to show more items than can fit in the client area of the control. TopItem should only be used when ViewStyle is vsReport or vsList. For vsIcon and vsSmall Icon view styles, use the ViewOrigin property to determine the scroll position of the list view. If ViewStyle is set to vsIcon or vsSmallIcon, an access violation exception will be returned when retrieving TopItem.

Example

The following example adds the caption for the first item in the list view to the list box.

ListBox1.Items.Add(ListView1.TopItem.Caption);


See also

Top property

Items property


TopItem property

See also	Example

Applies to

TOutlineNode object

Declaration

property TopItem: LongInt;

Description

The TopItem property specifies the Index value of the level 1 parent of the outline item. For an item on level 1, TopItem is the same as its index. For an item that is farther down the outline tree than level 1, TopItem specifies the index value of the parent at the top of its outline tree branch.


Example

The following code expands the top-level parent of the selected item.

with Outline1 do

  if not Items[Items[SelectedItem].TopItem].Expanded then

    Items[Items[SelectedItem].TopItem].Expanded := True;


See also

Level property


TopRow property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

property TopRow: Longint;

Description

Run-time only. The TopRow property determines which row in the grid appears at the top of the grid.

If you have one or more nonscrolling rows in the grid, they remain at the top, regardless of the value of the TopRow property. In this case, the row you specify as the top row will be the first row below the nonscrolling rows.


Example

This code uses a string grid and a button on a form. When the user clicks the button, the last row of the string grid becomes the top row:

procedure TForm1.Button1Click(Sender: TObject);

begin

  StringGrid1.TopRow := StringGrid1.RowCount;

end;


See also

FixedRows property

LeftCol property

OnTopLeftChanged event


 TOutline component

Properties	Methods	Events	Tasks

Unit

Outline

Description

The TOutline component is used for multilevel outlines of data. Use an outline to visually organize information in a hierarchical tree. Each item in an outline is contained in a TOutlineNode object.

An item in an outline can be accessed by the Items property. The items are indexed from 1 to the number of items. For example, Items[1] refers to the first (topmost) item. Since Items is the default array property of TOutline, an item can also be accessed immediately following the outline name. For example, Outline1.Items[1] and Outline1[1] refer to the same outline item.

Use the Add or AddObject methods to add a subitem to an outline. Use the Insert or InsertObject methods to replace an existing item in the outline. Use AddChild and AddChildObject to add a child item to the outline. Use Delete to remove items.

When adding, removing, or moving outline items, processing time can be sped up by calling BeginUpdate first. This prevents the outline items from being reindexed until EndUpdate is called.

The currently selected item is specified by the SelectedItem property. When the user selects a new item of the outline (by clicking with the mouse or pressing an Arrow key), the newly selected item is specified by SelectedItem.

The outline items can be represented within an outline by pictures that identify each item. The OutlineStyle property determines what type of pictures are used in the outline. You can also choose to display the outline tree with the OutlineStyle property.

The pictures displayed in an outline can be specified in the PictureLeaf, PictureMinus, PicturePlus, PictureOpen, and PictureClosed properties. If you don't specify these properties, an outline displays default pictures.

To display other items than the default pictures and text, set the Style property to otOwnerDraw and then draw the item in the OnDrawItem event handler.

The TOutline component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	ItemHeight	PictureMinus

BorderStyle	Items	PictureOpen

BoundsRect	Hint	PictureLeaf

Canvas	ItemCount	PicturePlus

Color	ItemSeparator	PopupMenu

ComponentIndex	Left	Row

Create	Lines	ScrollBars

Ctl3D	Name	SelectedItem

Cursor	Options	ShowHint

Destroy	OutlineStyle	Showing

DragCursor	Owner	Style

DragMode	Parent	TabOrder

Enabled	ParentColor	TabStop

Font	ParentCtl3D	Tag

Height	ParentFont	Top

PictureClosed	Width


Methods

 Key methods

Add	EndUpdate	LoadFromFile

AddChild	Focused	Refresh

AddChildObject	Free	Repaint

AddObject	FullCollapse	SaveToFile

BeginDrag	FullExpand	ScaleBy

BeginUpdate	GetDataItem	ScreenToClient

BringToFront	GetItem	ScrollBy

CanFocus	GetTextBuf	SendToBack

Clear	GetTextItem	SetBounds

ClientToScreen	GetTextLen	SetFocus

Create	Hide	SetTextBuf

Delete	Insert	SetUpdateState

Destroy	InsertObject	Show

Dragging	Invalidate	Update

EndDrag


Events

 Key events

OnClick	OnEndDrag	OnKeyUp

OnCollapse	OnEnter	OnMouseDown

OnDblClick	OnExit	OnMouseMove

OnDragDrop	OnExpand	OnMouseUp

OnDragOver	OnKeyDown	OnStartDrag

OnDrawItem	OnKeyPress


TOutlineNode object

Properties	Methods

Unit

Outline

Description

The TOutlineNode object contains an item of an TOutline component. An outline item is represented as a line, or row, of the outline.

An outline node contains Text and Data defined by your application. Text contains a string, and Data contains a pointer to a data structure to be associated with each outline item.

Each item can have from 0 to 16368 subitems, which are subordinate to the parent item in the outline structure.

Each item is identified by a unique Index. Index corresponds to the index of the Items property of the TOutline component. The children of an item are indexed sequentially, first child of an item having an Index value of one greater than its parent. For example, if the parent item has an Index of 7, its first child has an Index of 8, its second child has an Index of 9, and so on.

To move an item to a new location within the outline, call the MoveTo method.

The Expanded property determines if the item is currently expanded. If expanded, all children of an item are displayed in the outline. To set Expanded to True, call Expand. To set Expanded to False, call Collapse.

The Level property specifies the level, or column of an item in an outline. The items on the top level have a Level of 0. Their children have a level of 1, and so on. To change the level of an item, call the ChangeLevelBy method.

The HasItems property specifies whether an item has any children or subitems. GetFirstChild returns the Index value of the first child of an item. Likewise, GetLastChild, GetPrevChild, and GetNextChild return the index values of the last, previous, and next child items respectively.

The IsVisible property specifies whether an item is visible in an outline. An item is visible if all of its parents are expanded. You can expand all parents of an item with the FullExpand method.

The TopItem property specifies the Index value of the top-level parent of an item. The Parent property returns the actual immediate parent outline node of an item.

The FullPath property specifies the full path of parents down to an item. The path consists of the Text values of the parents separated by the ItemSeparator string specified for the TOutline component.

In addition to these properties and methods, this object also has the methods that apply to all objects. The TOutlineNode object is a direct descendent of TPersistent.


Properties

 Run-time only          [image] Key properties

Data	Index	Text

Expanded	IsVisible	TopItem

FullPath	Level

HasItems	Parent


Methods

 Key methods

ChangeLevelBy	Create	GetFirstChild

ClassType	Free	GetPrevChild

Collapse	FullExpand	MoveTo


TOutlineOptions type

Unit

Outline

Declaration

TOutlineOption = (ooDrawTreeRoot, ooDrawFocusRect, ooStretchBitmaps);

TOutlineOptions = set of TOutlineOption;

Description

The TOutlineOptions type determines the display options for a TOutline component. TOutlineStyle is the type of the Options property.


TOutlineStyle type

Unit

Outline

Declaration

TOutlineStyle = (osText, osPlusMinusText, osPictureText, osPlusMinusPictureText,osTreeText, osTreePictureText);

Description

The TOutlineStyle type determines how the items of a TOutline component are drawn if the Style property is set to osStandard. TOutlineStyle is the type of the OutlineStyle property.


TOutlineType type

Unit

Outline

Declaration

TOutlineType = (otStandard, otOwnerDraw);

Description

The TOutlineType type determines whether a TOutline component draws itself the standard way, or requires you to write code to draw its items. TOutlineType is the type of the Style property.


TOwnerDrawState type

Unit

StdCtrls

Declaration

TOwnerDrawState = set of (odSelected, odGrayed, odDisabled, odChecked, odFocused);

Description

The TOwnerDrawState type defines the possible values for the State parameter in the TDrawItemEvent method pointer of an owner-draw list box.


{bml dpgctrl.bmp} TPageControl component
 TPageControl component

Properties	Methods	Events

Unit

ComCtrls

Description

The TPageControl component is a page set which is used to make a multiple page dialog box.  It displays multiple overlapping pages which are TTabSheet objects, and replaces the TTabbedNotebook component. The user selects a page by clicking the page's tab that appears at the top of the control.

To create a new page in a TPageControl at design time, right-click the TPageControl and choose New Page. Each page in a page control is a tab sheet object. You can access a particular page in the page control by either clicking on its tab or by setting the ActivePage property. The PageIndex property of the tab sheet control contains the index of the page in the page control.

By default, a tab control displays only one row of tabs. If not all tabs can be shown at once, the tab control displays an up-down control so that the user can scroll additional tabs into view. Use the MultiLine property to display multiple rows of tabs, if necessary, so that all tabs are visible at once.

The TPageControl component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

ActivePage	Font	PopupMenu

Align	Handle	ShowHint

BoundsRect	Height	Showing

Brush	HelpContext	TabHeight

ClientHeight	Left	TabOrder

ClientOrigin	MultiLine	TabStop

ClientRect	Name	TabWidth

ClientWidth	Owner	Tag

ComponentIndex	Pages	Top

Cursor	Parent	Visible

DragCursor	ParentFont	Width

DragMode	ParentShowHint

Enabled


Methods

 Key methods

Assign	EndDrag	RemoveComponent

BeginDrag	FindComponent	RemoveControl

BringToFront	FindNextPage	Repaint

CanFocus	Focused	ScaleBy

ClassName	Free	ScreenToClient

ClassParent	GetTextBuf	ScrollBy

ClassType	GetTextLen	SelectNextPage

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

Invalidate	Update	Dragging

Refresh


Events

 Key events

OnChange	OnEndDrag	OnMouseMove

OnChanging	OnEnter	OnMouseUp

OnDragDrop	OnExit	OnStartDrag

OnDragOver	OnMouseDown


 TPaintBox component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The TPaintBox component provides a way for your application to draw on the form in a specified rectangular area, preventing drawing outside of the boundaries of the paint box. Once a paint box is added to your form, your application can use the OnPaint event handler to draw on the paint box's Canvas, the drawing surface of the paint box The Color and Font properties are used to initialize the Canvas (TCanvas) for the OnPaint event handler. The Brush.Color is set to the Color property value.

If you want to draw on the entire form, you can just use the OnPaint event of the form itself. If you want to confine your drawing to rectangular area, you'll find a paint box convenient.

You can align a paint box so that it remains in its relative position on the form, even when the user resizes the form. Use the Align property.

The TPaintBox component is a direct descendent of TGraphicControl. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all controls.


Properties

 Run-time only          [image] Key properties

Align	Font	ParentShowHint

BoundsRect	Height	PopupMenu

Canvas	Hint	ShowHint

ComponentIndex	Left	Tag

Color	Name	Top

Cursor	Owner	Visible

DragCursor	Parent	Width

DragMode	ParentColor

Enabled	ParentFont


Methods

 Key methods

BeginDrag	Focused	ScreenToClient

BringToFront	Free	SendToBack

ClientToScreen	GetTextBuf	SetBounds

Create	GetTextLen	SetTextBuf

EndDrag	Repaint


Events

 Key events

OnClick	OnEndDrag	OnPaint

OnDblClick	OnMouseDown	OnStartDrag

OnDragDrop	OnMouseMove

OnDragOver	OnMouseUp


 TPanel component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The TPanel component is used to place panels on a form on which other controls can be placed.

Panels can be aligned with the form so that they maintain the same relative position to the form even when the form is resized. Align a panel with the Align property. Once a panel is aligned with the form, you can use the panel as the foundation of a tool bar, tool palette, or status bar. To make a tool bar or tool palette, add speed buttons (TSpeedButton) to the panel along with other controls you find useful.

The text that appears on a panel is the value of the Caption property. Align the caption to the left, right, or center of the panel with the Alignment property. You can use a panel as a status bar for your application, displaying help hints on it. See the OnHint event and the Hint property for more information.

To customize the appearance of a panel, use panel's BevelInner, BevelOuter, BevelWidth, and BorderWidth properties.

The TPanel component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Controls	Parent

Alignment	Ctl3D	ParentColor

BevelInner	Cursor	ParentCtl3D

BevelOuter	DragCursor	ParentFont

BevelWidth	DragMode	ParentShowHint

BorderStyle	Enabled	PopupMenu

BorderWidth	Font	ShowHint

BoundsRect	Height	Showing

Caption	HelpContext	TabOrder

Color	Hint	TabStop

ComponentCount	Left	Tag

ComponentIndex	Name	Visible

Components	Owner	Width

ControlCount	Top


Methods

 Key methods

BeginDrag	Focused	Repaint

BringToFront	Free	ScaleBy

CanFocus	GetTextBuf	ScreenToClient

ClientToScreen	GetTextLen	ScrollBy

ContainsControl	Hide	SendToBack

Create	InsertComponent	SetBounds

Destroy	InsertControl	SetFocus

Dragging	Invalidate	SetTextBuf

EndDrag	Refresh	Show

FindComponent	RemoveComponent	Update


Events

 Key events

OnClick	OnEndDrag	OnResize

OnDblClick	OnMouseDown	OnStartDrag

OnDragDrop	OnMouseMove

OnDragOver	OnMouseUp


TPanelBevel type

Unit

StdCtrls

Declaration

TPanelBevel = (bvNone, bvLowered, bvRaised);

Description

The TPanelBevel type contains the values the BevelInner and BevelOuter properties can assume.


TParaAttributes object

See also	Properties	Methods

Unit

ComCtrls

Description

The TParaAttributes object is the type of the Paragraph property of the TRichEdit component. The TParaAttributes object returned by the Paragraph property holds information about the currently selected paragraphs in a rich edit. You can modify paragraphs by selecting them with the Paragraph property. Then you can change the formatting of the paragraphs by modifying the properties (Alignment, FirstIndent, LeftIndent, Numbering, RightIndent, Tab array, and TabCount) of the TParaAttributes object.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Alignment	Numbering	TabCount

FirstIndent	RightIndent

LeftIndent	Tab


Methods

 Key methods

Assign	ClassType	Destroy

ClassName	Create	Free

ClassParent

See also

ConsistentAttributes property

DefAttributes property

Paragraph property

SelAttributes property

OnSelectionChange event


TParam object

Properties	Methods

Unit

DBTables

Description

The TParam object holds information about a parameter of a TQuery or TStoredProc. In addition to the parameter value, TParam stores the field type, name, and (for a stored procedure) the parameter type.

You generally do not need to create a TParam explicitly, since TQuery or TStoredProc will create it as an element of its Params property as needed. All you have to do is assign values to the parameters by assigning one of the properties: AsBCD, AsBoolean, AsCurrency, AsDate, AsDateTime, AsFloat, AsInteger, AsSmallint, AsString, AsTime, or AsWord.

The TParam object is a direct descendent of TObject. In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

AsBCD	AsInteger	DataType

AsBoolean	AsSmallInt	IsNull

AsCurrency	AsString	Name

AsDate	AsTime	ParamType

AsDateTime	AsWord	Text

AsFloat	Bound


Methods

 Key methods

Assign	ClassType	Free

AssignField	Clear	GetData

ClassName	Create	GetDataSize

ClassParent	Destroy	SetData


TParamBindMode type

Unit

DBTables

Declaration

TParamBindMode = (pbByName, pbByNumber);

Description

The TParamBindMode type defines the possible values of the ParamBindMode property of a stored procedure (TStoredProc).


TParams object

Properties	Methods

Unit

DBTables

Description

The TParams object holds the parameters for a stored procedure (TStoredProc) or parameterized query (TQuery) and provides the methods to create and access those parameters. Each parameter is a TParam object.

Use the Items property to access individual parameters. Call CreateParam to create a new parameter. Call AddParam to add a new parameter or RemoveParam to take one out of the set. Call Clear to delete all parameters. Use the ParamByName method to find a parameter with a particular name.

The TParams object is a direct descendent of TPersistent. In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Items


Methods

 Key methods

AddParam	ClassType	Destroy

Assign	Clear	Free

AssignValues	Count	ParamByName

ClassName	Create	RemoveParam

ClassParent	CreateParam


TParamType type

Unit

DBTables

Declaration

TParamType = (ptUnknown, ptInput, ptOutput, ptInputOutput, ptResult);

Description

The TParamType type is the set of values of the ParamType property of a TParam object


TPen object

Properties	Methods	Events

Unit

Graphics

Description

A TPen object is used to draw lines on a canvas (TCanvas). The TPen object encapsulates the Windows HPEN.

The color of the pen is specified by the Color property. The width in pixels of the line drawn is specified by the Width property. The pattern of the line (solid, dotted, and so on) is specified by the Style property.

The Mode property specifies the color of the line, as it relates to the pixels the line is drawn over. For example, to color the line the color specified by the Color property, set Mode to pmCopy. To color the line the inverse of the screen color, set Mode to pmNot.

If the pen is modified, an OnChange event occurs.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Color	Mode	Width

Handle	Style


Methods

 Key methods

Assign	ClassType	Free

ClassName	Create

ClassParent	Destroy


Events

 Key events

OnChange


TPenMode type

Unit

Graphics

Declaration

TPenMode = (pmBlack, pmWhite, pmNop, pmNot, pmCopy, pmNotCopy,pmMergePenNot, pmMaskPenNot, pmMergeNotPen, pmMaskNotPen, pmMerge,pmNotMerge, pmMask, pmNotMask, pmXor, pmNotXor);

Description

The TPenMode type specifies the values the Mode property of pen object (TPen) can assume.


TPenStyle type

Unit

Graphics

Declaration

TPenStyle = (psSolid, psDash, psDot, psDashDot, psDashDotDot, psClear, psInsideFrame);

Description

The TPenStyle type specifies the values the Style property of pen object (TPen) can assume.


TPicture object

Properties	Methods	Events

Unit

Graphics

Description

The TPicture object contains a bitmap, icon, metafile graphic, or user-defined graphic. The type of graphic contained by the TPicture is specified in the Graphic property.

If the TPicture contains a bitmap graphic, the Bitmap property specifies the graphic. If the TPicture contains an icon graphic, the Icon property specifies the graphic. If the TPicture contains a metafile graphic, the Metafile property specifies the graphic.

The height and width in pixels of the graphic are specified by the Height and Width properties, respectively.

To load a graphic from a file, call the LoadFromFile method. To save a bitmap to a file, call SaveToFile. To load or save a picture to the Clipboard, use the Assign method of a TClipboard object.

To draw a picture on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing the Graphic property of a TPicture as a parameter.

When the graphic is modified, an OnChange event occurs.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Bitmap	Height	Metafile

Graphic	Icon	Width


Methods

 Key methods

Assign	Destroy	RegisterFileFormat

ClassName	Free	RegisterFileFormatRes

ClassParent	LoadFromClipboardFormat	SaveToClipboardFormat

ClassType	LoadFromFile	SaveToFile

Create	RegisterClipboardFormat	SupportsClipboardFormat


Events

 Key events

OnChange


TPoint type

Unit

Windows

Declaration

TPoint = record
  X: Longint;
  Y: Longint;
end;

Description

The TPoint type defines a pixel location onscreen, with the origin in the top left corner. X specifies the horizontal coordinate of the point, Y specifies the vertical coordinate.


TPopupAlignment type

Unit

Menus

Declaration

TPopupAlignment = (paLeft, paRight, paCenter);

Description

The PopupAlignment type determines where a pop-up menu (TPopupMenu) appears. The Alignment property of a pop-up menu is of type TPopupAlignment.


 TPopupMenu component

See also	Properties	Methods	Events	Tasks

Unit

Menus

Description

The TPopupMenu component encapsulates the properties, methods, and events of a pop-up menu, the menu available to forms and controls when the user selects the component and clicks the right mouse button. To make a pop-up menu available, assign a TPopupMenu component to the form's or control's PopupMenu property.

To begin designing a pop-up menu, add a pop-up menu component to your form, and double-click the component. For more information, see the topic Menu Designer.

The items on the pop-up menu are specified with the Items object, a property of a pop-up menu. The Items object is of type TMenuItem. Your application can use the Items property to access a particular item on the menu.

If you want the pop-up menu to appear when the user clicks the right mouse button on the control to which the pop-up menu is assigned, set the AutoPopup property to True. If you want to use code to control when a pop-up menu appears, use the Popup method.

Pop-up menus have an OnPopup event handler you can use to specify special processing you want to occur in your application just before a pop-up menu appears.

TPopupMenu is an indirect descendent of TComponent. In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Alignment	Components	Name

AutoPopup	Handle	Owner

ComponentCount	HelpContext	PopupComponent

ComponentIndex	Items	Tag


Methods

 Key methods

Create	FindComponent	Free

Destroy	FindItem	Popup


Events

 Key events

OnPopup


See also

ShortCut function

ShortCutToKey procedure

ShortCutToText function

TextToShortCut function

TMainMenu component

TMenuItem component


TPosition type

Unit

Forms

Declaration

TPosition = (poDesigned, poDefault, poDefaultPosOnly, poDefaultSizeOnly, poScreenCenter);

Description

The TPosition type enumerates the values the Position property of a form can have.


 TPrintDialog component

Properties	Methods	Tasks

Unit

Dialogs

Description

The TPrintDialog component displays a Print dialog box that permits the user to select which printer to print to, which pages to print, how many copies to print, and if the print job should be collated. If the user chooses the Setup button in the Print dialog box, the Print Setup dialog (TPrinterSetupDialog component) appears.

Display the Print dialog box by calling the Execute method.

You can customize how the Print dialog box appears and behaves using the Options property. For example, you can determine which print options are enabled or disabled, or you can decide whether the option to print to a file appears.

The range of pages to be printed is specified with the PrintRange property. If the value of PrintRange is prPageNums, which allows users to specify a page range, the pages they specify are the values of the FromPage and ToPage properties. With the MinPage and MaxPage, your application can limit the range of pages the user can select.

If the user chooses to print to a file, the PrintToFile property is True. If the user wants the print job to be collated, the Collate property is True.

The TPrintDialog component is an indirect descendent of TComponent. In addition to the following properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Collate	MaxPage	PrintRange

ComponentIndex	MinPage	PrintToFile

Copies	Name	Tag

FromPage	Options	ToPage

HelpContext	Owner


Methods

 Key methods

Create	Execute

Destroy	Free


TPrintDialogOptions type

Unit

Dialogs

Declaration

TPrintDialogOption = (poPrintToFile, poPageNums, poSelection, poWarning, poHelp, poDisablePrintToFile);

TPrintDialogOptions = set of TPrintDialogOption;

Description

The TPrintDialogOptions type defines the set of values the Options property of the Print dialog box (TPrintDialog) can have.


TPrinter object

Properties	Methods

Unit

Printers

Description

The TPrinter object encapsulates the printer interface of Windows. Within the Printers unit, the Printer function will create an instance of TPrinter, ready for you to use.

To start a print job, call the BeginDoc method. To end a print job that is sent successfully to the printer, call the EndDoc method. If a problem occurs and you need to terminate a print job that was not sent to the printer successfully, call the Abort method.

You can determine if a job is printing by checking the value of the Printing property. If the job aborted, the Aborted property is True.

The printing surface of a page is represented by the Canvas property. You can use the Brush, Font, and Pen properties of the Canvas object to determine how drawing or text appears on the page.

The list of installed printers is found in the Printers property. The value of the PrinterIndex property is the currently selected printer. The list of fonts supported by the current printer is found in the Fonts property.

You can determine if a print job prints in landscape or portrait orientation using the Orientation property.

You height and width of the current page is found in the PageHeight and PageWidth properties. The current page is the value of the PageNumber property.

The Title property determines the text that appears listed in the Print Manager and on network header pages.

Using the PrintScale property of a TForm component, you determine how the printed image of the form appears.

Whenever you use a TPrinter object, you must add Printers to the uses clause of the unit that implements the properties or methods of a TPrinter object.

The TPrinter object is a direct descendent of TObject. In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Aborted	Orientation	PrinterIndex

Canvas	PageHeight	Printers

Fonts	PageNumber	Printing

Handle	PageWidth	Title


Methods

 Key methods

Abort	ClassType	Free

BeginDoc	Create	GetPrinter

ClassName	Destroy	NewPage

ClassParent	EndDoc	SetPrinter


TPrinterOrientation type

Unit

Printers

Declaration

TPrinterOrientation = (poPortrait, poLandscape);

Description

The TPrinterOrientation type defines the possible values of the Orientation property of the printer object (TPrinter).


 TPrinterSetupDialog component

Properties	Methods	Tasks

Unit

Dialogs

Description

The TPrinterSetupDialog component displays a Printer Setup dialog box in your application. Users can use the dialog box to setup their printer before printing a job.

Display the Printer Setup dialog box by calling the Execute method. The Printer Setup dialog box also appears when the user chooses the Setup button in the Print dialog box (TPrintDialog).

The TPrinterSetupDialog component is an indirect descendent of TComponent. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Name	Tag

HelpContext	Owner


Methods

 Key methods

Create	Execute

Destroy	Free


TPrintRange type

Unit

Dialogs

Declaration

TPrintRange = (prAllPages, prSelection, prPageNums);

Description

The TPrintRange type defines the values the PrintRange property can have in the Print dialog box (TPrintDialog).


TPrintScale type

Unit

Forms

Declaration

TPrintScale = (poNone, poProportional, poPrintToFit);

Description

The TPrintScale type defines the possible values of the PrintScale property of the form.


{bml dprgbr.bmp} TProgressBar component
 TProgressBar component

Properties	Methods	Events

Unit

ComCtrls

Description

A TProgressBar component tracks the progress of a procedure within an application. As the procedure progresses, the rectangular TProgressBar gradually fills from left to right with the system highlight color. The Step property determines how much to increment Position each time it changes.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Cursor	Parent

BoundsRect	Enabled	Position

Brush	Handle	ShowHint

ClientHeight	Height	Showing

ClientOrigin	HelpContext	Step

ClientRect	Hint	TabOrder

ClientWidth	Left	TabStop

ComponentCount	Min	Tag

ComponentIndex	Max	Top

Components	Name	Visible

ControlCount	Owner	Width

Controls


Methods

 Key methods

Assign	EndDrag	RemoveControl

BeginDrag	FindComponent	Repaint

BringToFront	Focused	ScaleBy

CanFocus	Free	ScreenToClient

ClassName	GetTextBuf	ScrollBy

ClassParent	GetTextLen	SendToBack

ClassType	HandleAllocated	SetBounds

ClientToScreen	HandleNeeded	SetFocus

ContainsControl	Hide	SetTextBuf

ControlAtPos	InsertComponent	Show

Create	InsertControl	StepBy

Destroy	Invalidate	StepIt

Refresh	Update

Dragging	RemoveComponent


Events

 Key events

OnEnter	OnMouseDown	OnMouseUp

OnExit	OnMouseMove


 TQuery component

Properties	Methods	Events	Tasks

Unit

DBTables

Description

TQuery component enables Delphi applications to issue SQL statements to a database engine--either the BDE or an SQL server. TQuery provides the interface between an SQL server (or the BDE) and TDataSource components. TDataSource components then provide the interface to data-aware controls such as TDBGrid.

Set the DatabaseName property to specify the database to query. Enter a single SQL statement to execute in the SQL property. To query dBASE or Paradox tables, use local SQL. To query SQL server tables, use passthrough SQL. The SQL statement can be a static SQL statement or a dynamic SQL statement.

At run time, an application can supply parameter values for dynamic queries with the Params property, the ParamByName method, or the DataSource property. Use the Prepare method to optimize a dynamic query. The ParamCheck property determines whether the query fill the Params array.

A result set is the group of records returned by a query to an application. A TQuery can return two kinds of result sets:

"Live" result sets: As with TTable components, users can edit data in the result set with data controls. The changes are sent to the database when a Post occurs, or when the user tabs off a control.

"Read-only" result sets: Users cannot edit data in the result set with data controls.

If you want the query to provide a live result set, the SQL must conform to certain syntax requirements. If the SQL syntax does not conform to these requirements, the query will provide a read-only result set.

Execute the SQL statement at design time by setting the Active property to True . Execute the SQL statement at run time with the Open or ExecSQL methods.

Call the First, Next, Prior, Last, and MoveBy methods to navigate through the result set. Test the BOF and EOF properties to determine if the cursor is at the beginning or end of the result set, respectively. Call the Append, Insert, AppendRecord or InsertRecord methods to add a record to the underlying database table. Call the Delete method to delete the current record. Call the Edit method to allow modification of the fields of the current record, and Post to post the changes or Cancel to discard them.

The OnServerYieldEvent occurs periodically during a query executing on a Sybase server. Setting the parameter AbortQuery to False will cancel the query during execution.

The TQuery component is an indirect descendent of TComponent. In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Active	FieldDefs	RecNo

AutoCalcFields	Fields	RecordCount

BOF	FieldValues	RecordSize

Bookmark	Filter	RequestLive

CachedUpdates	Filtered	RowsAffected

CanModify	FilterOptions	SessionName

Constrained	Found	SQL

Database	Handle	State

DatabaseName	KeySize	StmtHandle

DataSource	Local	Tag

DBHandle	Locale	Text

DBLocale	Modified	UniDirectional

DBSession	Name	UpdateMode

DefaultFields	Owner	UpdateObject

ParamCheck	UpdateRecordTypes

EOF	ParamCount	UpdatesPending

ExpIndex	Params

FieldCount	Prepared


Methods

 Key methods

ActiveBuffer	FetchAll	Lookup

Append	FieldByName	MoveBy

AppendRecord	FindField	Next

ApplyUpdates	FindFirst	Open

Cancel	FindLast	ParamByName

CancelUpdates	FindNext	Post

CheckBrowseMode	FindPrior	Prepare

CheckOpen	First	Prior

ClearFields	Free	Refresh

Close	FreeBookmark	RenameTable

CommitUpdates	GetBookmark

ControlsDisabled	GetCurrentRecord	RevertRecord

Create	GetFieldList

CursorPosChanged	GetFieldNames	SetFields

Delete	GotoBookmark	UnPrepare

Destroy	Insert	UpdateCursorPos

DisableControls	InsertRecord	UpdateRecord

Edit	IsLinkedTo	UpdateStatus

EnableControls	Last

ExecSQL	Locate


Events

 Key events

AfterCancel	BeforeClose	OnEditError

AfterClose	BeforeDelete	OnFilterRecord

AfterDelete	BeforeEdit	OnNewRecord

AfterEdit	BeforeInsert	OnPostError

AfterInsert	BeforeOpen	OnServerYield

AfterOpen	BeforePost	OnUpdateError

AfterPost	OnCalcFields	OnUpdateRecord

BeforeCancel	OnDeleteError


Tracking property

Applies to

TControlScrollBar component

Declaration

property Tracking: Boolean;

Description

The Tracking property determines whether the form or scroll box will scroll when the scroll bar thumb tab is being dragged or will wait for the tab to be dropped.


TrackLength property

See also	Example

Applies to

TMediaPlayer component

Declaration

property TrackLength[TrackNum: Integer]: Longint;

Description

Run-time and read-only. The TrackLength property reports the length of the track specified by the TrackNum index. The value of TrackLength is specified according to the current time format, which is specified in the TimeFormat property.


Example

The following code shows the length of the currently playing .WAV audio file (CARTOON.WAV in this example) in the Caption of a label.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    TimeFormat := tfMilliseconds;

    DeviceType := dtWaveAudio;

    FileName := 'cartoon.wav';

    Open;

    Label1.Caption := IntToStr(TrackLength[1]);

  end;

end;


See also

Length property

TrackPosition property

Tracks property


TrackPosition property

See also	Example

Applies to

TMediaPlayer component

Declaration

property TrackPosition[TrackNum: Integer]: Longint;

Description

Run-time and read-only. The TrackPosition property reports the starting position of the track specified by the TrackNum index. The value of TrackPosition is specified according to the current time format, which is specified in the TimeFormat property.


Example

The following code shows the starting position of the first track of the currently loaded audio CD in the Caption of a label.

procedure TForm1.BitBtn1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    TimeFormat := tfMilliseconds;

    DeviceType := dtCDAudio;

    Open;

    Label1.Caption := IntToStr(TrackPosition[1]);

  end;

end;


See also

Position property

TrackLength property

Tracks property


Tracks property

See also	Example

Applies to

TMediaPlayer component

Declaration

property Tracks: Longint;

Description

Run-time and read-only. The Tracks property specifies the number of playable tracks on the open multimedia device. Tracks is undefined for devices that don't use tracks.


Example

The following code skips to the beginning of the last track on a CD audio device. You must declare the integer variable I to run this code.

with MediaPlayer1 do

if DeviceType = dtCDAudio then

begin

  Seek(TrackPosition[1]);

  for I := 1 to Tracks-1 do

    Next;

end;


See also

Next method

Previous method

TrackLength property

TrackPosition property


 TRadioButton component

See also	Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

The TRadioButton component is a Windows radio button. Use radio buttons to present a set of mutually exclusive options to the user--that is, only one radio button in a set can be selected at any time. When the user selects a radio button, the previously selected radio button becomes unselected.

Radio buttons are frequently grouped in a group box (TGroupBox). Add the group box to the form first, then choose the radio buttons from the Component palette and put them in the group box.

The text associated with the radio button that identifies its purpose is the value of the Caption property.

When the user selects a radio button, the value of the Checked property changes. Also, the OnClick event occurs. If you check a radio button, all other radio buttons in the same group become unchecked. By default, all radio buttons that are directly contained by the same windowed control container, such as a TForm, TGroupBox, or TPanel, are grouped. For example, two radio buttons on a form can be checked at the time only if they are contained in separate containers, such as two different group boxes.

The TRadioButton component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Font	ParentFont

Alignment	Handle	ParentShowHint

Caption	Height	PopupMenu

Checked	HelpContext	ShowHint

Color	Hint	Showing

ComponentIndex	Left	TabOrder

Ctl3D	Name	TabStop

Cursor	Owner	Tag

DragCursor	Parent	Top

DragMode	ParentColor	Visible

Enabled	ParentCtl3D	Width


Methods

 Key methods

BeginDrag	Free	ScrollBy

BringToFront	GetTextBuf	SendToBack

CanFocus	GetTextLen	SetBounds

ClientToScreen	Hide	SetFocus

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy

Focused	ScreenToClient


Events

 Key events

OnClick	OnEnter	OnMouseMove

OnDblClick	OnExit	OnMouseUp

OnDragDrop	OnKeyDown	OnStartDrag

OnEndDrag	OnMouseDown

OnDragOver	OnKeyPress

OnEndDrag	OnKeyUp


See also

TDBRadioGroup component


 TRadioGroup component

See also	Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

TRadioGroup component is a group box that contains radio buttons. A radio group box simplifies the task of grouping radio buttons and getting them to work together as a group.

The radio buttons are added to the group box when strings are entered as the value of the Items property. Each string in Items makes a radio button appear in the group box with the string appearing as the caption of the radio button. The value of the ItemIndex property determines which radio button is currently selected.

You can choose to display the radio buttons in a single column or in multiple columns by setting the value of the Columns property.

When the user selects a radio button in the radio button group box, the previously selected radio button is unselected automatically.

You can place other types of controls in a radio group box besides radio buttons.

TRadioGroup component is an indirect descendent of TWinControl. In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Height	ParentShowHint

Caption	HelpContext	PopupMenu

Color	Hint	ShowHint

Columns	Items	Showing

ComponentIndex	ItemIndex	TabOrder

Ctl3D	Left	TabStop

Cursor	Name	Tag

DragCursor	Owner	Top

DragMode	Parent	Visible

Enabled	ParentColor	Width

Font	ParentCtl3D

Handle	ParentFont


Methods

 Key methods

BeginDrag	FindComponent	ScaleBy

BringToFront	Focused	ScreenToClient

CanFocus	Free	ScrollBy

ClientToScreen	GetTextBuf	SendToBack

ContainsControl	GetTextLen	SetBounds

Create	Hide	SetFocus

Destroy	Invalidate	SetTextBuf

Dragging	Refresh

EndDrag	Repaint


Events

 Key events

OnClick	OnEndDrag	OnStartDrag

OnDragDrop	OnEnter

OnDragOver	OnExit


See also

TDBRadioGroup component

TGroupBox component

TRadioButton component


TransIsolation property

See also	Example

Applies to

TDataBase component

Declaration

property TransIsolation: TTransIsolation;

Description

The TransIsolation property specifies the transaction isolation level used by an SQL server. tiDirtyRead causes any change to be returned, regardless of whether the record has been committed. tiReadCommitted will return only committed versions of the record; uncommitted changes will not be reflected in the result. tiRepeatableRead will return only the original record for the duration of the transaction, even if another application has committed a change.

Database servers may support these isolation levels differently or not at all. If the requested isolation level is not supported by the server, then Delphi will use the next highest isolation level, as shown in the following table. For a detailed description of how each isolation level is implemented, see your server documentation.

TransIsolation setting 	Paradox anddBASE	Oracle

Dirty read	Dirty read	Read committed

Read committed (Default)	Not supported	Read committed

Repeatable read	Not supported	Repeatable read (READ ONLY)

TransIsolation setting 	Sybase, Microsoft SQL servers	InterBase

Dirty read	Read committed	Read committed

Read committed (Default)	Read committed	Read committed

Repeatable read	Not supported	Repeatable Read

Note:	When using transactions with local Paradox and dBASE tables, set TransIsolation to tiDirtyRead instead of using the default value of tiReadCommitted. A BDE error is returned if TransIsolation is set to anything but tiDirtyRead for local tables.

If an application is using ODBC to interface with a server, the ODBC driver must also support the isolation level. For more information, see your ODBC driver documentation.


Example

Database1.TransIsolation := tiReadCommitted;


See Also

InTransaction property, RollBack method, StartTransaction method


Transliterate property

See also	Example

Applies to

TBatchMove, TMemoField, TStringField component

Declaration

property Transliterate: Boolean;

Description

The Transliterate property controls whether translations to and from the respective locales of the Source and Destination properties will be done. Transliterate is True by default.


Example

{ Suppress translations }

BatchMove1.Transliterate := False;


See also

DBLocale property


Transparent property

See also	Example

Applies to

TLabel, TDBText components

Declaration

property Transparent: Boolean;

Description

The Transparent property determines if a label or database text control is transparent. You could place a transparent label or text control on top of a bitmap, and the control won't hide part of the bitmap. For example, if you have placed a bitmap of the world on a form, you could label the South American continent with a label control, and you would still see the continent in the label space.


Example

This code makes a label transparent:

Label1.Transparent := True;


See also

BorderStyle property


TransparentColor property

Applies to

TBitmap object

Declaration

property TransparentColor: TColor;

Description

Read-only. The TransparentColor property returns the color of the bitmap when it is transparent.


TRect type

Unit

Windows

Declaration

TRect = record
  case Integer of
    0: (Left, Top, Right, Bottom: Integer);
    1: (TopLeft, BottomRight: TPoint);
end;

Description

The TRect type defines a rectangle. The coordinates are specified either as four separate integers representing the pixel locations of the left, top, right, and bottom sides, or as two points representing the pixel locations of the top left and bottom right corners. The origin of the pixel coordinate system is in the top left corner of the screen.


TreeView property for tree nodes
TreeView property

See also

Applies to

TTreeNode object

Declaration

property TreeView: TCustomTreeView;

Description

Run-time and read-only. The TreeView property for a tree node specifies the tree view that is the owner of the item (TTreeNode).


See also

Owner property, Parent property


 TReplaceDialog component

Properties	Methods	Events	Tasks

Unit

Dialogs

Description

The TReplaceDialog component provides a Replace dialog box your application can use. TReplaceDialog contains all the capabilities of the TFindDialog component, but it also allows the user to replace found text with a replacement string.

Display the Replace dialog box by calling the Execute method.

The text your application is searching for is the value of the FindText property. The text that is to replace the found text is the value of the ReplaceText property.

To determine which search and replace options are available in the Find dialog box, use the Options property. For example, you can have a Match Case check box appear in the dialog box or hide it, and you can disable or enable the Whole Word check box.

When the user enters the text to search for in the dialog box and chooses Find Next, the OnFind event occurs. Within the OnFind event handler, write the code that searches for the text specified as the value of the FindText. Your code can use the Options values to determine how the user wants the search conducted.

When the user chooses the Replace or Replace All button in the Replace dialog box, the OnReplace event occurs. Within the OnReplace event handler, write the code that replaces the found text specified as the value of ReplaceText. Your code can use the Options values to determine how the user wants the text replaced.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Left	ReplaceText

Ctl3D	Name	Tag

FindText	Options	Top

HelpContext	Owner


Methods

 Key methods

CloseDialog	Destroy	Free

Create	Execute


Events

 Key events

OnFind	OnReplace


 TReport component

Properties	Methods	Tasks

Unit

Report

Description

The TReport component is an interface to Borland's ReportSmith application. Once you place the TReport component on a form, you can double-click it to begin running ReportSmith. If you specify an existing report name using the Object Inspector, choose Cancel when the Open Report dialog box appears and ReportSmith minimizes. When you click the ReportSmith icon to restore it, the specified report displays.

You can also control the running of ReportSmith at run time. Specify the report you want to run as the value of the ReportName property. You can include the path where the report is located as part of the ReportName property, or you can specify the directory with the ReportDir property. Call the Run method to run the report. To print an existing report, call the Print method.

The report component lets you specify several report parameters. You can choose the starting and ending page of the report with the StartPage and EndPage properties. To limit the size of the report, you can specify a maximum number of records for the report with the MaxRecords property. Choose how many copies of the report you want with the PrintCopies property.

Specify the report variables you want the report to use with the InitialValues property. You can change a report variable with the SetVariable and SetVariableLines methods, and then recalculate the report and run it using the new report variable by calling the RecalcReport method.

You can run a ReportBasic macro using the RunMacro method. You can see if ReportSmith is ready to perform another operation by checking the status of the Busy property.

To terminate the running of a report, call the CloseReport method. You can choose to automatically unload ReportSmith when a report finishes running if you set the AutoUnload property to True. If AutoUnload is False, you must call the CloseApplication method to unload ReportSmith.

For information about using ReportSmith, see the ReportSmith documentation.

The TReport component is a direct descendent of TComponent. In addition to the following properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

AutoUnload	MaxRecords	ReportDir

Busy	Name	ReportName

ComponentIndex	Owner	StartPage

EndPage	Preview	Tag

InitialValues	PrintCopies	VersionMajor

LaunchType	ReportHandle	VersionMinor


Methods

 Key methods

CloseApplication	Destroy	Run

CloseReport	Free	RunMacro

Connect	Print	SetVariable

Create	RecalcReport	SetVariableLines


TResType type

Unit

Controls

Declaration

TResType = (rtBitmap, rtCursor, rtIcon);

Description

TResTypes is used by the image list methods ResourceLoad, GetResource and FileLoad to specify the type of graphical resource that is to be loaded or retrieved from the ImageList

Value	Meaning

rtBitmap	Loads or retrieves a bitmap

rtCursor	Loads or retrieves a cursor

rtIcon	Loads or retrieves an icon


TRichEdit component

Properties	Methods	Events

Unit

ComCtrls

Description

The TRichEdit component is a Rich Text Format memo control. As such it includes the properties of a memo such as HideSelection, HideScrollBars, Lines, ScrollBars, WantReturn, WantTabs, and WordWrap. To set character formatting at design-time use the Font and PlainText properties.

At run-time information about default and selected character formatting is available in the DefAttributes and SelAttributes properties. Similarly the Paragraph property contains information on the paragraph formatting. TRichEdit also has printing and text searching capabilites. For these use the Print and FindText run-time methods.

The TRichEdit component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Handle	PlainText

Alignment	Height	PopupMenu

BorderStyle	HelpContext	ReadOnly

BoundsRect	HideScrollBars	ScrollBars

Brush	HideSelection	SelAttributes

ClientHeight	Hint	ShowHint

ClientOrigin	Left	Showing

ClientRect	Lines	TabOrder

ClientWidth	MaxLength	TabStop

Color	Name	Tag

ComponentIndex	Owner	Top

Ctl3D	Paragraph	Visible

Cursor	Parent	WantTabs

DefaultConverter	ParentColor	WantReturns

DragMode	ParentCtl3D	Width

Enabled	ParentFont	WordWrap

Font


Methods

 Key methods

Assign	EndDrag	Refresh

BeginDrag	FindComponent	RegisterConversionFormat

BringToFront	FindText	RemoveComponent

CanFocus	Focused	RemoveControl

ClassName	Free	Repaint

ClassParent	GetTextBuf	ScaleBy

ClassType	GetTextLen	ScreenToClient

ClientToScreen	HandleAllocated	ScrollBy

ContainsControl	HandleNeeded	SendToBack

ControlAtPos	Hide	SetBounds

Create	InsertComponent	SetFocus

Destroy	InsertControl	SetTextBuf

DragDrop	Invalidate	Show

Dragging	Print	Update


Events

 Key events

OnChange	OnKeyDown	OnProtectChange

OnDragDrop	OnKeyPress	OnResizeRequest

OnDragOver	OnKeyUp	OnSaveClipboard

OnEndDrag	OnMouseDown	OnSelectionChange

OnEnter	OnMouseMove	OnStartDrag

OnExit	OnMouseUp


Truncate method

Example

Applies to

TBlobStream object

Declaration

procedure Truncate;

Description

The Truncate method discards all data in the TBlobField, TBytesField or TVarBytesField from the current position.


Example

{ Discard all data after the first 1000 bytes }

with BlobStream1 do

 begin

    Seek(0, 1000);

    Truncate;

end;


 TSaveDialog component

See also	Properties	Methods	Tasks

Unit

Dialogs

Description

The TSaveDialog component makes a Save dialog box available to your application. The purpose of the dialog box is to allow a user to specify a file to save. Use the Execute method to display the Save dialog box.

When the user chooses OK in the dialog box, the user's filename selection is stored in the dialog box's FileName property, which you can then use to process as you want.

You can let the user decide which set of files are visible in the list box of the Save dialog box with the Filter property. The user can then use the List Files of Type combo box to determine which files display in the list box. You set the default filter using the FilterIndex property.

You can permit the user to choose multiple filenames with the Options property so that the Files property contains a list of all the selected filenames in the list box. You can customize how the Save dialog box appears and behaves with the Options property.

If you want a file extension automatically appended to the filename typed in the File Name edit box of the Save dialog box, use the DefaultExt property.

The TSaveDialog component is an indirect descendent of TComponent. In addition to the following properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Filter	Options

Ctl3D	FilterIndex	Owner

DefaultExt	HelpContext	Tag

FileEditStyle	HistoryList	Title

FileName	InitialDir

Files	Name


Methods

 Key methods

Create	Execute	Free

Destroy


See also

TOpenDialog component


TScreen component

Properties	Methods	Events

Unit

Forms

Description

The TScreen component represents the state of the screen as your application runs. A Screen variable of type TScreen is already declared, ready for you to use as an instance of TScreen.

The screen component lists all forms displayed on the screen in the Forms property array. The number of forms is kept as the value of the FormCount property. You can find out which form currently has the focus by checking the value of the ActiveForm property. Similarly, the control that has the focus is the value of the ActiveControl property.

The screen component lists all data modules that are currently created in the application in the DataModules property. The number of created data modules is kept as the value of the DataModuleCount property.

The height and width of the screen device in pixels are the value of the Height and Width properties. The PixelsPerInch property indicates the system font proportions of the system used to design the form.

All the fonts supported by the screen are listed in the Fonts property. Similarly, all the cursors available are in the Cursors property. Using Cursors, you can make a custom cursor available to your application.

The TScreen component is a direct descendent of TComponent. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

ActiveControl	Cursors	Height

ActiveForm	DataModules	Name

ComponentCount	DataModuleCount	Owner

ComponentIndex	FormCount	PixelsPerInch

Components	Forms	Tag

Cursor	Fonts	Width


Methods

 Key methods

Create	FindComponent	InsertComponent

Destroy	Free	RemoveComponent


Events

 Key events

OnActiveControlChange	OnActiveFormChange


 TScrollBar component

See also	Properties	Methods	Events	Tasks

Unit

StdCtrls

Description

The TScrollBar component is a Windows scroll bar, which is used to scroll the contents of a window, form, or control. In the OnScroll event handler, you write the code that determines how the window, form, or control behaves in response to the user scrolling the scroll bar.

You determine how far a thumb tab moves when the user clicks the scroll bar on either side of the thumb tab with the value of the LargeChange property. The value of the SmallChange property determines how far the thumb tab moves when the user clicks the arrows at the end of the scroll bar or scrolls the scroll bar using the arrow keys on the keyboard.

The Min and Max property values together determine how many positions are available on the scroll bar for the thumb tab to move when the user scrolls the scroll bar. Your application can set the position of the thumb tab with the Position property, or use the property to determine how far the scroll bar has scrolled. You can use the SetParams method to set the Min, Max, and Position properties all at once.

To cause the form or scroll box to scroll while the scroll bar thumb tab is being dragged instead of waiting for the tab to be dropped, set the Tracking property to True.

The TScrollBar component is a direct descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Kind	Position

ComponentIndex	LargeChange	ShowHint

Ctl3D	Left	Showing

Cursor	Max	SmallChange

DragCursor	Min	TabOrder

DragMode	Name	TabStop

Enabled	Owner	Tag

Handle	Parent	Top

Height	ParentCtl3D	Visible

HelpContext	ParentShowHint	Width

Hint	PopupMenu


Methods

 Key methods

BeginDrag	Free	SendToBack

BringToFront	GetTextBuf	SetBounds

CanFocus	GetTextLen	SetFocus

ClientToScreen	Hide	SetParams

Create	Invalidate	SetTextBuf

Destroy	Refresh	Show

Dragging	Repaint	Update

EndDrag	ScaleBy

Focused	ScreenToClient


Events

 Key events

OnChange	OnEndDrag	OnKeyPress

OnClick	OnEnter	OnKeyUp

OnDragDrop	OnExit	OnScroll

OnDragOver	OnKeyDown	OnStartDrag


See also

TScrollBox component

TForm component


TScrollBarInc type

Unit

Forms

Declaration

TScrollBarInc = 1..32767;

Description

The TScrollBarInc type defines the possible values of the SmallChange and LargeChange properties of a scroll bar (TScrollBar).


TScrollBarKind type

Unit

Forms

Declaration

TScrollBarKind = (sbHorizontal, sbVertical);

Description

The TScrollBarKind type defines the two different orientations a scroll bar can have: horizontal and vertical. TScrollBarKind is the type of the scroll bar control's Kind property.


 TScrollBox component

Properties	Methods	Events	Tasks

Unit

Forms

Description

TScrollBox components make it possible to create scrolling areas on a form that are smaller than the entire form. For example, your form might contain a panel component used as a speed bar that is aligned with the top of the form, and a panel component used as a status bar that is aligned with the bottom of the form. You would not want these panel components to scroll when the user scrolls the form. By placing a scroll box between the two panels and aligning it so that it fills the remaining client area, you can place components on the scroll box and then allow the user to scroll only the scroll box on the form.

You determine the behavior of the horizontal and vertical scroll bars on the scroll box by setting the properties of the HorzScrollBar and VertScrollBar objects, which are properties of a scroll box.

To assure that a particular control on the scroll box is in view, use the ScrollInView method.

The TScrollBar component is a direct descendent of TWinControl. In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Enabled	ParentShowHint

BorderStyle	Font	PopupMenu

Brush	Height	ShowHint

Color	HelpContext	Showing

ComponentCount	Hint	TabOrder

ComponentIndex	HorzScrollBar	TabStop

Components	Left	Tag

ControlCount	Name	Top

Controls	Owner	VertScrollBar

Ctl3D	Parent	Visible

Cursor	ParentColor	Width

DragCursor	ParentCtl3D

DragMode	ParentFont


Methods

 Key methods

BeginDrag	Free	ScreenToClient

BringToFront	GetTextBuf	ScrollBy

CanFocus	GetTextLen	ScrollInView

ClientToScreen	Hide	SendToBack

ContainsControl	InsertComponent	SetBounds

Create	InsertControl	SetFocus

Destroy	Invalidate	SetTextBuf

Dragging	Refresh	Show

EndDrag	RemoveComponent	Update

FindComponent	Repaint

Focused	ScaleBy


Events

 Key events

OnClick	OnEndDrag	OnMouseMove

OnDblClick	OnEnter	OnMouseUp

OnDragDrop	OnExit	OnResize

OnDragOver	OnMouseDown


TScrollCode type

Unit

StdCtrls

Declaration

TScrollCode = (scLineUp, scLineDown, scPageUp, scPageDown, scPosition, scTrack, scTop, scBottom, scEndScroll);

Description

The TScrollCode type defines the possible states of a scroll bar. It is used by the TScrollEvent method pointer.


TScrollStyle type

Unit

StdCtrls

Declaration

TScrollStyle = (ssNone, ssHorizontal, ssVertical, ssBoth);

Description

The TScrollStyle type defines the different combinations of scroll bars a memo control or a grid can have. TScrollStyle is the type of the ScrollBars property of TMemo, TDBMemo, TDrawGrid, and TStringGrid.


TSearchDirection type

Unit

ComCtrls

Declaration

TSearchDirection = (sdLeft, sdRight, sdAbove, sdBelow, sdAll);

Description

The TSearchDirection type is used to specify which direction to search for a list item when using the GetNextItem and GetNearestItem methods.

Value	Meaning

sdLeft	Searches for a list item to the left of the specified list item

sdRight	Searches for a list item to the right of the specified list item

sdAbove	Searches for a list item that is above the specified list item

sdBelow	Searches for a list item that is below the specified list item

sdAll	Searches for a subsequent list item by index (the default value)


TSearchTypes type

Unit

ComCtrls

Declaration

TSearchType = set of (stWholeWord, stMatchCase);

TSearchTypes = set of TSearchType;

Description

The TSearchTypes type defines the possible values of the Options parameter of the FindText method of the TRichEdit component.


TSelectDirOpts type

Unit

FileCtrl

Declaration

TSelectDirOpt = (sdAllowCreate, sdPerformCreate, sdPrompt);

TSelectDirOpts = set of TSelectDirOpt;

Description

The TSelectDirOpts type defines the possible values of the Options parameter in the SelectDirectory function.


TSession component

Properties	Methods	Events

Unit

DB

Description

The TSession component provides global control over database connections for an application. Delphi automatically creates a default TSession component at runtime for applications which use database controls.  This component may be accessed at runtime through the global variable Session.  Do not close or destroy the default session.

There is also a TSession component on the data access page of the component palette.  This component is only needed if you are writing a multi-threaded application which will perform simultaneous data access (such as running two queries at the same time).  The global variable Sessions is a TSessionList which provides a way to manage applications which use multiple sessions.

TSession provides global control over database connections for an application. The Databases property of TSession is an array of all the active databases in the session. The DatabaseCount property is an integer specifying the number of active databases in the Session.

KeepConnections is a Boolean property that specifies whether to keep inactive database connections for temporary TDatabase components. The DropConnections method will drop all inactive database connections.

The NetFileDir property specifies the directory path of the BDE network control directory. The PrivateDir property specifies the path of the directory in which to store temporary files.

The TSession component is a direct descendent of TComponent. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Active	KeepConnections	PrivateDir

ConfigMode	Locale	SessionName

DatabaseCount	Name	Tag

Databases	NetFileDir	TraceFlags

Handle	Owner


Methods

 Key methods

AddAlias	FindDatabase	IsAlias

AddPassword	GetAliasParams	ModifyAlias

AddStandardAlias	GetConfigParams	Open

Close	GetDatabaseNames	OpenDatabase

CloseDatabase	GetDriverNames	RemoveAllPasswords

DeleteAlias	GetDriverParams	SaveConfigFile

GetAliasDriverName	GetPassword

GetAliasNames	GetTableNames

DropConnections	GetStoredProcNames


Events

 Key events

OnPassword	OnStartup


TSessionList object

Properties	Methods

Unit

DB

Description

The TSessionList object holds a list of TSession components representing Borland Database Engine (BDE) sessions. The Sessions variables is of type TSessionList. The DB unit automatically creates and destroys it for you, so you don't need to worry about doing so--just use Sessions. Multiple sessions are required only for applications that use multiple threads of execution.

Use the FindSession method or List array property to return a TSession component matching the name you supply. Use GetSessionNames to get a list of all session names.

Use the Count property to return the number of sessions TSessionList knows about. Use the Sessions array property to return a session based on its index in the list.

Use OpenSession to either create a new session or return an existing session and make it active.

In addition to these properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Count	List	Sessions

CurrentSession


Methods

 Key methods

FindSession	GetSessionNames	OpenSession


TShape component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The TShape component displays a geometric shape on the form. It is a nonwindowed component.

You determine which geometric shape the shape control assumes by setting the Shape property. How the shape is painted depends on the two nested properties of the Brush object, Color and Style.

The TShape component is a direct descendent of TGraphicControl. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all controls.


Properties

 Run-time only          [image] Key properties

Align	Height	Shape

BoundsRect	Hint	ShowHint

Brush	Left	Tag

ComponentIndex	Name	Top

Cursor	Owner	Visible

DragCursor	Parent	Width

DragMode	ParentShowHint

Enabled	Pen


Methods

 Key methods

BeginDrag	EndDrag	ScaleBy

BringToFront	Free	ScreenToClient

ClientToScreen	Hide	SendToBack

Create	Invalidate	SetBounds

Destroy	Refresh	Show

Dragging	Repaint	Update


Events

 Key events

OnDragDrop	OnMouseDown	OnStartDrag

OnDragOver	OnMouseMove

OnEndDrag	OnMouseUp


TShapeType type

Unit

StdCtrls

Declaration

TShapeType = (stRectangle, stSquare, stRoundRect, stRoundSquare, stEllipse, stCircle);

Description

The TShapeType type is used by the Shape property of the TShape component to determine if the TShape component appears as a rectangle, square, rounded rectangle, rounded square, ellipse, or circle.


TShiftState type

See also

Unit

Classes

Declaration

TShiftState = set of (ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble);

Description

The TShiftState type is used by key-event and mouse-event handlers to determine the state of the Alt, Ctrl, and Shift keys and the state of the mouse buttons when the event occurred.


See also

TKeyEvent type

TMouseEvent type


TShortCut type

Unit

Menus

Declaration

TShortCut = Low(Word) .. High(Word);

Description

TShortCut types are the menu shortcuts that appear on menus and give the user an alternate way to select a menu commands using the keyboard. The ShortCut property is of type TShortCut, and the ShortCutToText and ShortCutToKey routines use parameters of type TShortCut.


TSmallIntField component

Properties	Methods	Events

Unit

DBTables

Description

A TSmallintField component represents a field of a record in a dataset. It is represented as a binary value with a range from -32,768 to 32,767. Use TSmallintField for fields that hold signed whole numbers.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value. Set the MinValue or the MaxValue property to limit the smallest or largest value permitted in a field.

The TSmallintField component is an indirect descendent of TComponent and has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayFormat	MinValue

AsBoolean	DisplayLabel	Name

AsDateTime	DisplayName	Owner

AsFloat	DisplayText	ReadOnly

AsInteger	DisplayWidth	Required

AsString	EditFormat	Size

Calculated	FieldName	Tag

CanModify	FieldNo	Text

DataSet	Index	Value

DataSize	IsIndexField	Visible

DataType	IsNull

MaxValue


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


TSortType type

Unit

ComCtrls

Declaration

TSortType = (stNone, stData, stText, stBoth);

The TSortType type defines the set of the possible ways that items in a tree view and list view component can be sorted. The SortType property of the list view and tree view components is of this type.


 TSpeedButton component

Properties	Methods	Events	Tasks

Unit

Buttons

Description

TSpeedButton components are buttons that usually have graphical images on their faces that users use to execute commands or set modes. They have some unique capabilities that allow them to work as a set. Speed buttons are commonly used with panels (TPanel) to create tool bars and tool palettes.

The graphical image that appears on a speed button is the value of its Glyph property. You can use different images to represent the different states of the speed button. For example, you can use one image when the speed button is unselected, another when it is selected, and another when it is disabled. Use the NumGlyphs property to specify multiple images.

Use the Layout, Margin, and Spacing properties to arrange the image and text on the speed button.

Speed buttons can work together as a group if you set the GroupIndex property. If you want all speed buttons in a group to be able to appear in their "up" state, set the AllowAllUp property to True. If you want a speed button to initially appear as if it is selected, set its Down property to True.

TSpeedButton components are direct descendents of TGraphicControl. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all controls.


Properties

 Run-time only          [image] Key properties

Align	GroupIndex	ParentFont

AllowAllUp	Height	ParentShowHint

BoundsRect	Hint	ShowHint

Caption	Layout	Showing

ComponentIndex	Left	Spacing

Cursor	Margin	Tag

Down	Name	Top

Enabled	NumGlyphs	Visible

Font	Owner	Width

Glyph	Parent


Methods

 Key methods

BeginDrag	EndDrag	ScaleBy

BringToFront	Free	ScreenToClient

CanFocus	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

Click	Hide	SetTextBuf

Create	Invalidate	Show

Destroy	Refresh	Update

Dragging	Repaint


Events

 Key events

OnClick	OnMouseDown	OnMouseUp

OnDblClick	OnMouseMove


{bml dstat.bmp} TStatusBar component
 TStatusBar component

Properties	Methods	Events

Unit

ComCtrls

Description

The TStatusBar component is a window, always horizontal and aligned along the bottom edge of an application frame, that displays status information about the application. Status bars can display either SimpleText information in a single SimplePanel or they can display various types of information in multiple panels each with its own Text. The default position of a status bar is along the bottom of the parent window, but you can set the Align property to have it appear elsewhere in the window.

The Panels property (TStatusPanels) contains a collection of the individual panels (TStatusPanel) in the status bar, each having its own Text, Width, Style, Bevel, and Alignment property value. By default, text is left-aligned within the specified part of a panel. To access these properties at design-time, use the Panels property to bring up the StatusBar Panels Editor.

To find the number of panels in the status bar use the Count property of the TStatusPanels. To access the properties of the individual panels at run-time, use the Items property of the Panels property; for example, to change the text displayed in the second panel, you could write this line of code:

Panels.Items[1].Text := 'Searching...';

You can set the SizeGrip property to True to include a sizing grip at the right end of the status window. A sizing grip is similar to a sizing border; it is a rectangular area that the user can click and drag to resize the parent window.

You can define individual panels of a status bar to be owner-drawn panels. Using this technique gives you more control than you would otherwise have over the appearance of the status bar. For example, you can display a bitmap rather than text in a panel or draw text using a different font. To handle drawing within the panels, set the Style property to hsOwnerDraw and put the code for drawing in the OnDrawPanel event handler. A simple panel status bar does not support owner drawing.

The TStatusBar component is a direct descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	DragCursor	PopupMenu

BoundsRect	DragMode	ShowHint

Brush	Font	SimplePanel

ClientHeight	Handle	SimpleText

ClientOrigin	Height	SizeGrip

ClientRect	HelpContext	TabOrder

ClientWidth	Left	TabStop

ComponentCount	Name	Tag

ComponentIndex	Owner	Top

Components	Panels	Visible

ControlCount	Parent	Width

Controls	ParentFont

Cursor	ParentShowHint


Methods

 Key methods

Assign	Dragging	Refresh

BeginDrag	EndDrag	RemoveComponent

BringToFront	FindComponent	RemoveControl

CanFocus	Focused	Repaint

ClassName	Free	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

DragDrop	Invalidate	Update


Events

 Key events

OnClick	OnDrawPanel	OnMouseUp

OnDblClick	OnEndDrag	OnResize

OnDragDrop	OnMouseDown	OnStartDrag

OnDragOver	OnMouseMove


TStatusPanel object

Properties	Methods

Unit

ComCtrls

Description

The TStatusPanel object is an individual item or panel in a TStatusBar component. Status bars can have either a single SimplePanel with SimpleText or they can have multiple panels. To create multiple panels at design time use the Panels property to bring up the StatusBar Panels Editor dialog. Use this dialog to Add new panels and to edit the Bevel, Style and Text properties of the individual panels. An array of these panels is maintained in the Items array of the TStatusPanels object. Use the Panels property to access the TStatusPanels container object.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Alignment	Count	Style

Bevel	Index	Text


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


TStatusPanelBevel type

Unit

ComCtrls

Declaration

TStatusPanelBevel = (pbNone, pbLowered, pbRaised);

Description

The TStatusPanelBevel type defines the values of the Bevel property of the TStatusPanel object. TStatusPanel objects comprise the panels of TStatusBar components.


TStatusPanels object

Properties	Methods

Unit

ComCtrls

Description

The TStatusPanels object is used to maintain a collection of TStatusPanel objects in a TStatusBar component. TStatusPanel objects are the individual panels that are displayed on a status bar if the SimplePanel property is set to False. A TStatusPanels object maintains an index of these panels in its Items array. In the Object Inspector, use the status bar Panels property to display the StatusBar Panels Editor dialog. From this dialog box, you can Add, delete, and edit individual panels.

TheTStatusPanels object is an indirect descendent of TPersistent. In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Count	Items


Methods

 Key methods

Add	ClassParent	Destroy

Assign	Clear	EndUpdate

BeginUpdate	ClassType	Free

ClassName	Create


TStatusPanelStyle type

See also

Unit

ComCtrls

Declaration

TStatusPanelStyle = (psText, psOwnerDraw);

Description

The TStatusPanelStyle type defines the different types of the Style property of the TStatusPanel object. TStatusPanel objects comprise the panels of TStatusBar components. Use their Text property to set the text on a psText style panel. For psOwnerDraw style panels write a handler for the OnDrawPanel event.


See also

OnDrawPanel event

Text property


TStoredProc component

Properties	Methods	Events

Unit

DBTables

Description

The TStoredProc component enables Delphi applications to execute server stored procedures. Set the DatabaseName property to specify the database in which the stored procedure is defined. Set the StoredProcName to the name of the stored procedure on the server.

A stored procedure has a Params array for its input and output parameters, similar to a TQuery component. The order of the parameters in the Params array is determined by the stored procedure definition. An application can set the values of input parameters and get the values of output parameters in the array similar to TQuery parameters. You can also use ParamByName to access the parameters by name. If you are not sure of the ordering of the input and output parameters for a stored procedure, use the Parameters Editor.

Before an application can execute a stored procedure, you must prepare the stored procedure, which can be done:

At design time with the Parameters Editor.

At run time with the Prepare method.

A stored procedure can return either a singleton result or a result set with a cursor, if the server supports it. Execute a stored procedure with the ExecProc method, if the stored procedure returns a singleton result (one row), or Open method, if the stored procedure returns a result set (multiple rows).

Note:	InterBase "select procedures" are called with the SELECT statement as if querying a table. To get output from such procedures, use a TQuery component with the appropriate SELECT syntax.

The OnServerYieldEvent occurs periodically during a query executing on a Sybase server. Setting the parameter AbortQuery to False will cancel the query during execution.

The TStoredProc component is an indirect descendent of TComponent. In addition to the following properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Active	EOF	ParamCount

AutoCalcFields	FieldDefs	Params

BOF	Fields	Prepared

Bookmark	FieldValues	RecNo

CachedUpdates	Filter	RecordCount

CanModify	Filtered	RecordSize

Database	FilterOptions	SessionName

DatabaseName	Found	State

DBSession	Handle	StmtHandle

ExpIndex	KeySize	StoredProcName

FieldCount	Locale	Tag

DataSource	Modified	UpdateMode

DBHandle	Name	UpdateObject

DBLocale	Owner	UpdateRecordTypes

DefaultFields	Overload	UpdatesPending

ParamBindMode


Methods

 Key methods

ActiveBuffer	ExecProc	Locate

Append	FetchAll	Lookup

AppendRecord	FieldByName	MoveBy

ApplyUpdates	FindField	Next

Cancel	FindFirst	Open

CancelUpdates	FindLast	ParamByName

CheckBrowseMode	FindNext	Post

CheckOpen	FindPrior	Prepare

ClearFields	First	Prior

Close	Free	Refresh

CopyParams	FreeBookmark	RenameTable

CommitUpdates	GetBookmark

ControlsDisabled	GetCurrentRecord	RevertRecord

Create	GetFieldList

CursorPosChanged	GetFieldNames	SetFields

Delete	GetResults	UnPrepare

DescriptionsAvailable	GotoBookmark	UpdateCursorPos

Destroy	Insert	UpdateRecord

DisableControls	InsertRecord	UpdateStatus

Edit	IsLinkedTo

EnableControls	Last


Events

 Key events

AfterCancel	BeforeClose	OnEditError

AfterClose	BeforeDelete	OnFilterRecord

AfterDelete	BeforeEdit	OnNewRecord

AfterEdit	BeforeInsert	OnPostError

AfterInsert	BeforeOpen	OnServerYield

AfterOpen	BeforePost	OnUpdateError

AfterPost	OnCalcFields	OnUpdateRecord

BeforeCancel	OnDeleteError


TStringField component

Properties	Methods	Events

Unit

DBTables

Description

A TStringField component represents a field of a record in a dataset. A field of TStringField is physically stored as a sequence of up to 255 characters. Use TStringField for fields that contain text, such as names and addresses.

Use the Value property to access or change the current field value.

The TStringField component is an indirect descendent of TComponent and has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Name

AsBoolean	DisplayName	Owner

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditMask	Size

AsString	EditMaskPtr	Tag

Calculated	FieldName	Text

CanModify	FieldNo	Transliterate

DataSet	Index	Value

DataSize	IsIndexField	Visible

DataType	IsNull


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


 TStringGrid component

Properties	Methods	Events	Tasks

Unit

Grids

Description

The TStringGrid component is a grid control designed to simplify the handling of strings and associated objects while maintaining all the functionality of the TDrawGrid component.

All the strings within a string grid are contained in the Cells property, which you can use to access a particular string within the grid. All the objects associated with the strings in a string grid are contained in the Objects property. Use Objects to access a particular object.

All the strings and their associated objects for a particular column can be accessed using the Cols property. The Rows property gives you access to all the strings and their associated objects for a particular row.

In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	DefaultRowHeight	ParentColor

BorderStyle	DragCursor	ParentCtl3D

BoundsRect	DragMode	ParentFont

Canvas	EditorMode	ParentShowHint

Cells	Enabled	PopupMenu

ClientHeight	FixedColor	Row

ClientOrigin	FixedCols	RowCount

ClientRect	FixedRows	RowHeights

ClientWidth	Font	Rows

Col	GridHeight	ScrollBars

ColCount	GridLineWidth	Selection

Color	GridWidth	ShowHint

Cols	Handle	Showing

ColWidths	Height	TabOrder

ComponentCount	HelpContext	TabStop

ComponentIndex	Hint	TabStops

Components	Left	Tag

ControlCount	LeftCol	Top

Controls	Name	TopRow

Ctl3D	Objects	Visible

Cursor	Options	VisibleColCount

DefaultColWidth	Owner	VisibleRowCount

DefaultDrawing	Parent	Width


Methods

 Key methods

BeginDrag	Focused	Repaint

BringToFront	Free	ScaleBy

CanFocus	GetTextBuf	ScreenToClient

CellRect	GetTextLen	SendToBack

ClientToScreen	Hide	SetBounds

Create	Invalidate	SetFocus

Destroy	MouseToCell	SetTextBuf

Dragging	Refresh	Show

EndDrag	RemoveComponent	Update


Events

 Key events

OnClick	OnExit	OnMouseUp

OnColumnMoved	OnGetEditMask	OnRowMoved

OnDblClick	OnGetEditText	OnSelectCell

OnDragDrop	OnKeyDown	OnSetEditText

OnDragOver	OnKeyPress	OnStartDrag

OnDrawCell	OnKeyUp	OnTopLeftChanged

OnEndDrag	OnMouseDown

OnEnter	OnMouseMove


TStringList object

Properties	Methods	Events

Unit

Classes

Description

The TStringList object maintains a list of strings. Use a string list object when you are managing a list of strings that is not maintained by a control.

You can add, delete, insert, move, and exchange strings using the Add, Append, Delete, Insert, Move, and Exchange methods. The Clear method clears all the strings in the list of strings. The Count property contains the number of strings in the list. Each string list object has a Strings property that lets you access a particular string by its position in the list of strings. To find the position of a string in the list, use the IndexOf method.

If you want to add several strings at once to a list of strings, use the AddStrings method. You can assign one strings object to another using the Assign method.

To determine if a particular string exists in the list of strings, call the Find method. To sort the list of strings, use the Sort method. To determine if the list is sorted, check the value of the Sorted property. You can decide whether the list can contain duplicate strings using the Duplicates property.

Each string can be associated with an object. The objects associated with strings are commonly used to place a bitmap in an owner-draw control. If you want to add a string and an object to string list at the same time, use the AddObject method. You can access a particular object by its position in the list of objects using the Objects property. To find the position of the object in the list, use the IndexOfObject method. To insert an object, call the InsertObject method. The Delete, Move, Clear, and Exchange methods operate on the object associated with a string as well as on the string itself. For example, calling Clear removes all strings and all their associated objects.

You can store strings in a file and then load them all at one using the LoadFromFile method. To save the strings to a file, use the SaveToFile method.

The TStringList object is an indirect descendent of TPersistent. In addition to these properties, methods, and events, this object also has the methods that apply to the TStrings object and to all objects.


Properties

 Run-time only          [image] Key properties

Count	Objects	Strings

Duplicates	Sorted	Values


Methods

 Key methods

Add	Clear	IndexOf

AddObject	Create	IndexOfObject

AddStrings	Delete	Insert

Assign	Destroy	InsertObject

BeginUpdate	EndUpdate	LoadFromFile

ClassName	Exchange	SaveToFile

ClassParent	Find	Sort

ClassType	Free


Events

 Key events

OnChange	OnChanging


TStrings object

Properties	Methods	Tasks

Unit

Classes

Description

TStrings objects are used by various components to manipulate strings. A string object has no way to store a string, but instead uses the native storage ability of the control that uses it.

For example, the Items property of a list box control is of type TStrings. The strings that appear in a list box control are stored in a list box string object (TListBoxStrings), which is derived from TStrings. When you add or delete items in a list box, you are adding and deleting them from a list box string object.

To maintain a list of strings outside of a control, use a string list object (TStringList).

You can add, delete, insert, move, and exchange strings using the Add, Append, Delete, Insert, Move, and Exchange methods of a string object. The Clear method clears all the strings in the list of strings. The Count property contains the number of strings in the list. Each string object has a Strings property that lets you access a particular string by its position in the list of strings. The Names property lets you access the name part of a string at a particular position in the list of strings when the string is of the form Name=Value. To find the position of a string in the list, use either the IndexOf or the IndexOfName method.

To add several strings at once to a list of strings, use the AddStrings method. Use the Text and CommaText properties to add to and retrieve the list of strings in the strings object. You can assign one string object to another using the Assign method.

To compare two lists of strings, use the Equals method.

Each string can be associated with an object. The objects associated with strings are commonly used to place a bitmap in an owner-draw control. If you want to add a string and an object to string list at the same time, use the AddObject method. You can access a particular object by its position in the list of objects using the Objects property. To find the position of the object in the list, use the IndexOfObject method. To insert an object, call the InsertObject method. The Delete, Move, Clear, and Exchange methods operate on the object associated with a string as well as on the string itself. For example, calling Clear removes all strings and all their associated objects.

You can store strings in a file and then load them all at one using either the LoadFromFile or LoadFromStream method. To save the strings to a file or stream, use the SaveToFile method and the SaveToStream method.

The TStrings object is a direct descendent of TPersistent. In addition to the following properties and methods, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

CommaText	Names	Text

Count	Strings	Values

Objects


Methods

 Key methods

Add	Clear	IndexOf

AddObject	Create	IndexOfObject

AddStrings	Delete	Insert

Append	Destroy	InsertObject

Assign	EndUpdate	LoadFromFile

BeginUpdate	Equals	LoadFromStream

ClassName	Exchange	Move

ClassParent	Free	SaveToFile

ClassType	IndexOfName	SaveToStream


TSymbolStr type

Unit

DB

Declaration

TSymbolStr = string[DBIMAXNAMELEN];

Description

The TSymbolStr type is the type of a string of the correct length for a database object name, such as a Locale property, a field name, or a password.


 TTabbedNotebook component

Properties	Methods	Events	Tasks

Unit

TabNotBk

Description

The TTabbedNotebook component contains multiple pages, each with its own set of controls. The user selects a page by clicking the page's tab that appears at the top of the control. TTabbedNotebook is provided for backward compatibility. Use TPageControl component in Microsoft Windows 95 and Windows NT applications.

The pages available in the tabbed notebook control are the strings specified as the value of the Pages property. You can access a particular page in the notebook either with the PageIndex property or the ActivePage property.

If you need to determine the PageIndex value of a particular page, call the GetIndexForPage method.

You determine how many tabs appear in a row by setting the TabsPerRow property. If there are more pages than there are tabs in one row, multiple rows automatically appear in the control. You can specify the font of the text on the tabs with the TabFont property.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

ActivePage	Handle	Parent

Align	Height	TabOrder

BoundsRect	HelpContext	TabsPerRow

ComponentIndex	Hint	TabStop

ControlCount	Left	Tag

Controls	Name	Top

Cursor	Owner	Visible

Enabled	PageIndex	Width

Font	Pages


Methods

 Key methods

BeginDrag	Free	ScreenToClient

BringToFront	GetIndexForPage	ScrollBy

CanFocus	GetTextBuf	SendToBack

ClientToScreen	GetTextLen	SetBounds

ContainsControl	Hide	SetFocus

Create	InsertControl	SetTextBuf

Destroy	Invalidate	Show

Dragging	Refresh	Update

EndDrag	Repaint

Focused	ScaleBy


Events

 Key events

OnEnter	OnExit


{bml dtbctrl.bmp}TTabControl component
TTabControl component

Properties	Methods	Events

Unit

ComCtrls

Description

The TTabControl component is a tab set which functions similar to a TTabSet and has the appearance of notebook dividers.  To create a multiple page dialog box, use a TPageControl. To use simply a tab set, use the TTabControl. Disabling a TTabControl will disable all tabs because it is one control. To disable individual tabs use a TPageControl and disable the individual TTabSheet controls that represent the pages.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	DisplayRect	PopupMenu

BoundsRect	Enabled	ShowHint

Brush	Font	Showing

ClientHeight	Handle	TabHeight

ClientOrigin	Height	TabIndex

ClientRect	HelpContext	TabOrder

ClientWidth	Left	Tabs

ComponentCount	MultiLine	TabStop

ComponentIndex	Name	TabWidth

Components	Owner	Tag

ControlCount	Parent	Top

Controls	ParentFont	Visible

Cursor	ParentShowHint	Width


Methods

 Key methods

Assign	Dragging	Refresh

BeginDrag	EndDrag	RemoveComponent

BringToFront	FindComponent	RemoveControl

CanFocus	Focused	Repaint

ClassName	Free	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

Invalidate	Update


Events

 Key events

OnChange	OnEndDrag	OnMouseMove

OnChanging	OnEnter	OnMouseUp

OnDragDrop	OnExit	OnStartDrag

OnDragOver	OnMouseDown


 TTable component

Properties	Methods	Events	Tasks

Unit

DBTables

Description

The TTable component provides live access to database tables through the Borland Database Engine. TTable is the interface between the Borland Database Engine and TDataSource components. The TDataSource components then provide the interface to data-aware controls such as TDBGrid.

Set the DatabaseName property to specify the database to access. Set the TableName property to the table to access. Set the ReadOnly property to True unless you want to change the contents of the table. Set the Exclusive property to True if you do not want any other application to access the table while you are using it. Use the IndexName property to use the table with a secondary index. Use the MasterFields and MasterSource properties to create a link to a master table in a master-detail relationship. Call the GotoCurrent method to move the cursor to the same position as another TTable linked to the same database table.

Set the Active property to True or call the Open method to open a TTable, putting it in Browse mode. Set Active to False or call Close close the TTable. Call the First, Next, Prior, Last, and MoveBy, methods to navigate through the table. Call the SetKey, FindKey, FindNearest, GotoKey, and GotoNearest methods to search the database table for specific values.

Test the BOF and EOF properties to determine if the cursor has reached the beginning or end of the table, respectively. Call the Append, Insert, AppendRecord or InsertRecord methods to add a record to the table. Call the Delete method to delete the current record. Call the Edit method to allow an application to modify records in the table, and Post to send the changes to the database or Cancel to discard them.

Use the EditRangeStart, EditRangeEnd, SetRangeStart, SetRangeEnd, ApplyRange and SetRange methods to limit the range of records returned to the application and the CancelRange method to remove the limit.

The OnServerYieldEvent occurs periodically during a query executing on a Sybase server. Setting the parameter AbortQuery to False will cancel the query during execution.

In addition to these properties, methods, and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

Active	FieldDefs	MasterFields

AutoCalcFields	Fields	MasterSource

BOF	FieldValues	Modified

Bookmark	Filter	Name

CachedUpdates	Filtered	Owner

CanModify	FilterOptions	RecNo

Database	Found	RecordCount

DatabaseName	Handle	RecordSize

DataSource	IndexDefs	SessionName

DBHandle	IndexFieldCount	State

DBLocale	IndexFieldNames	TableName

DBSession	IndexFiles	TableType

DefaultFields	IndexName	Tag

EOF	IndexFields	UpdateMode

Exclusive	KeyExclusive	UpdateObject

ExpIndex	KeyFieldCount	UpdateRecordTypes

FieldCount	KeySize	UpdatesPending

Locale


Methods

 Key methods

ActiveBuffer	EditRangeEnd	IsLinkedTo

AddIndex	EditRangeStart	Last

ApplyRange	EmptyTable	Locate

ApplyUpdates	EnableControls	LockTable

Append	FetchAll	Lookup

AppendRecord	FieldByName	MoveBy

BatchMove	FindField	Next

Cancel	FindFirst	Open

CancelRange	FindKey	OpenIndexFile

CancelUpdates	FindLast	Post

CheckBrowseMode	FindNearest	Prior

CheckOpen	FindNext	Refresh

ClearFields	FindPrior	RenameTable

Close	First

CloseIndexFile	Free	RevertRecord

CommitUpdates	FreeBookmark

ControlsDisabled	GetBookmark	SetFields

Create	GetCurrentRecord	SetKey

CreateTable	GetFieldList	SetRange

CursorPosChanged	GetFieldNames	SetRangeEnd

Delete	GetIndexNames	SetRangeStart

DeleteIndex	GotoBookmark	UnlockTable

DeleteTable	GotoCurrent	UpdateCursorPos

Destroy	GotoKey	UpdateRecord

DisableControls	GotoNearest	UpdateStatus

Edit	Insert

EditKey	InsertRecord


Events

 Key events

AfterCancel	BeforeClose	OnEditError

AfterClose	BeforeDelete	OnFilterRecord

AfterDelete	BeforeEdit	OnNewRecord

AfterEdit	BeforeInsert	OnPostError

AfterInsert	BeforeOpen	OnServerYield

AfterOpen	BeforePost	OnUpdateError

AfterPost	OnCalcFields	OnUpdateRecord

BeforeCancel	OnDeleteError


TTableType type

Unit

DBTables

Declaration

TTableType = (ttDefault, ttParadox, ttDBase, ttASCII);

Description

The TTableType type is the set of values of the TableType property of a TTable component.


TTabOrder type

Unit

Controls

Declaration

TTabOrder = -1..32767;

Description

The TTabOrder type defines a subrange of integers that can be used as values for the TabOrder property.


 TTabSet component

Properties	Methods	Events	Tasks

Unit

Tabs

Description

The TTabSet component presents horizontal tabs users can click to initiate actions. Tab set controls are commonly used with TNotebook controls to display pages within the same dialog box. TTabSet is provided for backward compatibility. Use TTabControl component in Microsoft Windows 95 and Windows NT applications.

You create a set of tabs for the tab set control when you specify a list of strings as the value of the Tabs property. One tab is created for each string. If you are using a tab set control to work with a notebook control (TNotebook), this line of code creates a tab for each page of the notebook control:

TabSet1.Tabs := Notebook1.Pages;

Then, in the OnClick event handler of the tab set control, this line of code changes the current page in the notebook control when the user clicks a tab:

Notebook1.PageIndex := TabSet1.TabIndex;

To determine which tab is currently selected or to use code to select a tab, use the TabIndex property. To find out which tab is the first visible tab in the tab set control or to make a tab the first visible tab, use the FirstIndex property.

Several properties affect the appearance of the tab set control. Tabs are usually displayed at the bottom of a form. To display the tabs at the bottom of the form, choose alBottom as the Align property value. Set the SelectedColor and UnselectedColor properties to help the user tell the difference between a selected and an unselected tab. The BackgroundColor and the DitherBackground properties determine how the background of the tab set appears. You can determine how far from the edge of the control the tabs are positioned with the StartMargin and EndMargin properties. If you want scroll buttons to appear automatically when the tab set control doesn't have enough room to display all the tabs, set AutoScroll to True.

You can display graphics on tabs as well as text. Use the Style property select an owner-draw tab style.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Height	Style

AutoScroll	HelpContext	TabHeight

BackgroundColor	Hint	TabIndex

Canvas	Left	Tabs

ComponentIndex	Name	Tag

Cursor	Owner	Top

DitherBackground	Parent	UnselectedColor

DragMode	ParentShowHint	Visible

Enabled	SelectedColor	VisibleTabs

EndMargin	ShowHint	Width

FirstIndex	Showing

Font	StartMargin


Methods

 Key methods

BeginDrag	Free	ScaleBy

BringToFront	GetTextBuf	ScreenToClient

CanFocus	GetTextLen	ScrollBy

ClientToScreen	Hide	SelectNext

Create	Invalidate	SendToBack

Destroy	ItemAtPos	SetBounds

Dragging	ItemRect	SetFocus

EndDrag	Refresh	SetTextBuf

Focused	Repaint	Update


Events

 Key events

OnChange	OnDragOver	OnEnter

OnClick	OnDrawTab	OnExit

OnDragDrop	OnEndDrag	OnMeasureTab


TTabSheet component

Properties	Methods	Events	Example

Unit

ComCtrls

Description

The TTabSheet component is an individual page in a TPageControl component. Tab sheets are typically referred to as pages. The TPageControl maintains a zero-based indexed array of its tab sheets in its Pages property. The page control's PageCount property specifies the number of tab sheets in the page control and its ActivePage property indicates the currently active tab sheet. Click on a tab to activate the tab sheet or use FindNextPage and SelectNextPage to sequentially page through the tab sheets in the page control.

At design-time a tab sheet is automatically assigned a PageIndex value according to a zero-based index and the TabVisible property is True by default. At run-time use the read-only TabIndex property to return the index of the tab in the page control; if TabIndex is -1 the tab is not visible. The PageControl property determines to which page control the tab sheet is associated.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	Controls	ParentShowHint

BoundsRect	Cursor	PopupMenu

Brush	Enabled	ShowHint

Caption	Handle	Showing

ClientHeight	Height	TabIndex

ClientOrigin	HelpContext	TabOrder

ClientRect	Left	TabStop

ClientWidth	Name	TabVisible

ComponentCount	Owner	Tag

ComponentIndex	PageControl	Top

Components	PageIndex	Visible

ControlCount	Parent	Width


Methods

 Key methods

Assign	Dragging	Refresh

BeginDrag	EndDrag	RemoveComponent

BringToFront	FindComponent	RemoveControl

CanFocus	Focused	Repaint

ClassName	Free	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

DragDrop	Invalidate	Update


Events

 Key events

OnEnter	OnExit


TTabStyle type

Unit

Tabs

Declaration

TTabStyle = (tsStandard, tsOwnerDraw);

Description

The TTabStyle type defines the style of the tabs in a tab set control. TTabStyle is the type of the a tab set control's Style property.


TTextAttributes object

Properties	Methods

Unit

ComCtrls

Description

The TTextAttributes object is the type of the DefAttributes and the SelAttributes properties of the TRichEdit component. TTextAttributes has properties named Color, Name, Pitch, Size, Style, and Height, which are identical to the like-named properties of TFont. You can assign fonts to text attributes and vice versa. Note that the foreground color is a character attribute and should be set in the TTextAttribute Color property. The background color is a property of the rich edit control and should be set in the Color property of the TRichEdit.

TTextAttributes also has a read-only ConsistentAttributes property that includes information on: typeface, size, color, and effects such as bold, italic, strikeout, and underline.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Color	Name	Size

ConsistentAttributes	Pitch	Style

Height	Protected


Methods

 Key methods

Assign	ClassType	Destroy

ClassName	Create	Free

ClassParent


TTextCase type

Unit

FileCtrl

Declaration

TTextCase = (tcLowerCase, tcUpperCase);

Description

The TTextCase type defines the values available to the Text property of a drive combo box (TDriveComboBox).


TTickMark type

Unit

ComCtrls

Declaration

TTickMark = (tmBottomRight, tmTopLeft, tmBoth);

Description

TTickMark type defines the possible values of the TickMarks property of the TTrackBar component.


TTickStyle type

Unit

ComCtrls

Declaration

TTickStyle = (tsNone, tsAuto, tsManual);

Description

TTickMark type defines the possible values of the TickMarks property of the TTrackBar component.


TTileMode type

Unit

Forms

Declaration

TTileMode = (tbHorizontal, tbVertical);

Description

The TTileMode type defines the values the TileMode property of a form can have.


TTimeField component

Properties	Methods	Events

Unit

DBTables

Description

A TTimeField component represents a field of a record in a dataset. It represents a value consisting of a time.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value.

The TTimeField component has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DataType	IsIndexField

AsBoolean	DisplayLabel	IsNull

AsDateTime	DisplayName	Name

AsFloat	DisplayText	Owner

AsInteger	DisplayWidth	ReadOnly

AsString	EditMask	Required

Calculated	EditMaskPtr	Size

CanModify	FieldName	Tag

DataSet	FieldNo	Text

DataSize	Index	Visible


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


 TTimer component

Properties	Methods	Events	Tasks

Unit

ExtCtrls

Description

The TTimer component causes an OnTimer event to occur whenever a specified period of time passes. Within that OnTimer event handler, your code specifies what you want to happen each time the OnTimer event occurs.

You use the Interval property to control the amount of time between timer events.

To activate or deactivate a timer, use its Enabled property.

In addition to these properties and events, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

ComponentIndex	Interval	Owner

Enabled	Name	Tag


Methods

 Key events

Create	Destroy	Free


Events

 Key events

OnTimer


{bml dtrackb.bmp} TTrackBar component
 TTrackBar component

Properties	Methods	Events

Unit

ComCtrls

Description

A TTrackBar component is an optionally-ticked bar control that contains a slider which marks a current Position. Move the slider to the desired Position on the bar by dragging it with the mouse or by clicking the mouse on the bar. To use the keyboard to move the slider, press the arrow keys or the PgUp and PgDn keys. The LineSize property specifies the number of ticks moved by arrow keys. The PageSize property specifies the number of ticks moved by the PageUp and PageDown keys, or by mouse clicks on the bar.

To customize the number and placement of tick marks use the TickStyle and TickMarks properties. A TTrackBar can also display a selected range marked by triangular ticks at the starting and ending positions of the selection range. Set the selection range using the SelStart and SelEnd properties.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	DragMode	ParentShowHint

BoundsRect	Enabled	PopupMenu

Brush	Frequency	Position

ClientHeight	Handle	SelEnd

ClientOrigin	Height	SelStart

ClientRect	HelpContext	ShowHint

ClientWidth	Left	Showing

ComponentCount	LineSize	TabOrder

ComponentIndex	Max	TabStop

Components	Min	Tag

ControlCount	Name	TickMarks

Controls	Orientation	TickStyle

Ctl3D	Owner	Top

Cursor	PageSize	Visible

DragCursor	Parent	Width

ParentCtl3D


Methods

 Key methods

Assign	Dragging	Refresh

BeginDrag	EndDrag	RemoveComponent

BringToFront	FindComponent	RemoveControl

CanFocus	Focused	Repaint

ClassName	Free	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

DragDrop	Invalidate	Update


Events

 Key events

OnChange	OnEndDrag	OnKeyDown

OnDragDrop	OnEnter	OnKeyPress

OnDragOver	OnExit	OnKeyUp

OnStartDrag


TTrackBarOrientation type

Unit

ComCtrls

Declaration

TTrackBarOrientation = (tbHorizontal, tbVertical);

Description

TTrackBarOrientation type defines the possible values of the Orientation property of the TTrackBar component.


TTransIsolation type

Unit

DB

Declaration

TTransIsolation = (tiDirtyRead, tiReadCommitted, tiRepeatableRead);

Description

The TTransIsolation type is used by the TransIsolation property and it is the set of values that can be used to start a transaction. They control how records which have been modified by another application will be returned to your application by the server.


TTreeNode object

Properties	Methods

Unit

ComCtrls

Description

The TTreeNode object is an individual item of a TTreeView control. A tree view item is represented as a line, or row, of the tree view.

A tree node contains Text and Data defined by your application. Text contains a string, and Data contains a pointer to a data structure to be associated with each tree view item. The EditText method puts the node into edit mode.

Each item is identified by a unique Index. Index corresponds to the index of the Items property of the TTreeView control. The children of an item are indexed sequentially, the first child of an item having an Index value of 0, its second child has an Index of 1, and so on. The IndexOf method returns the position of an immediate child item. The AbsoluteIndex property returns the Index of the item relative to the first item in the tree view. The first item has an index of 0, and subsequent items are numbered sequentially.

The Item property returns the item at the Index position in the tree view. Count returns the number of subitems belonging to the item in the tree view.

To move an item to a new location within the tree view, call the MoveTo method.

The Expanded property determines if the item is currently expanded. If Expanded is True, all children of an item are displayed in the tree view. The IsVisible property specifies whether an item is visible in a tree view. An item is visible if all its parents are expanded.

The Level property specifies the level of an item in an outline. The items on the top level have a Level of 0. Their children have a Level of 1, and so on.The HasChildren property specifies whether an item has any children or subitems.

The GetFirstChild method returns the first child of the item. Likewise, GetLastChild, GetPrevChild, and GetNextChild return the last, previous and next child items respectively. GetNextSibling and GetPrevSibling return the next and previous items at the same level respectively as the item. GetNextVisible and GetPrevVisible return the next and previous visible items respectively.

The HasAsParent method returns True if the item passed is a parent of the item. The Parent property returns the parent tree node of the item. The TreeView property specifies the tree view that is the owner of the item.

The Focused property determines whether the item has the focus, that is it's surrounded by a standard focus rectangle. Only one item can have the focus. The Selected property determines whether the node is selected. In the TTreeView control, only one item can be selected. The DropTarget property specifies if the item is the target of a drag and drop operation.

The SelectedIndex property contains the index of the icon in the image list (TImageList object) used when the item is selected.

The OverlayIndex property determines which image from the tree view's Images image list is to be used as an overlay mask, an image drawn transparently over another image in the tree view. The ImageIndex property determines which image is displayed when an item is in it's normal state. The StateIndex property determines which image to display from the tree view's StateImages image list.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Count	ImageIndex	Owner

Data	Index	Parent

DropTarget	IsVisible	SelectedIndex

Focused	Item	StateIndex

Handle	Index


Methods

bmc keyprp1.bmp} Key methods

AlphaSort	Destroy	GetNextSibling

Assign	DisplayRect	GetNextVisible

CancelEdit	EditText	GetPrev

ClassName	Expand	GetPrevChild

ClassParent	Free	GetPrevSibling

ClassType	GetFirstChild	GetPrevVisible

Collapse	HasAsParent

Create	GetLastChild	IndexOf

CustomSort	GetNext	MakeVisible

Delete	GetNextChild	MoveTo

DeleteChildren


TTreeNodes object

Properties	Methods

Unit

ComCtrls

Description

The TTreeNodes object maintains a list of items (TTreeNode objects). The Items property of the tree view control (TTreeView component) which is of type TTreeNodes maintains the items in the tree view.

The TTreeNodes object has methods to add items and child items to a tree view, such as Add, AddFirst, AddChild, AddChildFirst. Add will add the item to the end of a list, AddFirst will add the item at the beginning of the items list. AddChild adds an item at the end of the items child list, AddChildFirst will add the item to the beginning of the items child list. There are also methods to add items containing data, such as AddObject, AddObjectFirst, AddChildObject and AddChildObjectFirst. AddObject adds an item containing data to the end of the items list in the tree view, AddObjectFirst adds to the beginning of the list. AddChildObject adds an item containing data at the end of the items child list, AddChildObjectFirst adds to the beginning of the child list.

Clear removes all items from the tree view. Delete removes one item from the tree view. Insert inserts an item into the tree view, InsertObject inserts an item containing data. The BeginUpdate method prevents the display of the tree view until the EndUpdate method is called.

GetFirstNode returns the first item in the tree view. GetNode returns the item given the ItemId. Item[Index] returns the item at the given Index in the tree node. The first item has an index of 0, and subsequent items are numbered sequentially.

The Owner property specifies the tree view that owns the TTreeNodes object. Count returns the number of items in the TTreeNodes object.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Count	Item	Owner

Handle


Methods

 Key methods

Add	AddObjectFirst	Delete

AddChild	Assign	Destroy

AddChildFirst	ClassName	Free

AddChildObject	ClassParent	GetFirstNode

AddChildObjectFirst	ClassType	GetNode

AddFirst	Clear	Insert

AddObject	Create	InsertObject


{bml dtreevw.bmp}TTreeView component
TTreeView component

Properties	Methods	Events	Example

Unit

ComCtrls

Description

TreeView components are indirect descendents of TWinControl. They are windows that display a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and a number of optional bitmapped images, and each item can have a list of subitems associated with it. By clicking on an item, the user can expand and collapse the associated list of subitems. This control can be seen as the left pane of the Database Explorer.

The Items property refers to a TTreeNodes object, a container class for TTreeNode objects, and contains the individual items that appear in the tree view control. Individual nodes are TTreeNode objects. Items can be added and inserted by using TTreeNodes methods AddChildFirst, AddChild, AddChildObjectFirst, AddChildObject, AddFirst, Add, AddObjectFirst, AddObject, Insert.and InsertObject.

The ShowLines property, when True, will draw lines to link child items to their corresponding parent item. The user can expand or collapse a parent item's list of child items by double-clicking the parent item. The ShowButtons property determines whether a button appears to the left side of each parent item. The user can click the button to expand or collapse the child items as an alternative to double-clicking the parent item. To show buttons at the root of the hierachy, set the ShowRoot property to True.

When a list of child items is expanded, it is indented relative to the parent item. You can set the amount of indentation with the Indent property. To keep each parent item's list of child items in alphabetical order set the SortType property to stText. To allow direct editing of the item labels, set the ReadOnly property to False.

In addition to these properties, methods, and events, this object also has the methods that apply to all objects.


Properties

 Run-time only          [image] Key properties

Align	DropTarget	PopupMenu

BorderStyle	Enabled	ReadOnly

BoundsRect	Font	Selected

Brush	Handle	ShowButtons

ClientHeight	Height	ShowHint

ClientOrigin	HelpContext	Showing

ClientRect	HideSelection	ShowLines

ClientWidth	Images	ShowRoot

Color	Indent	SortType

ComponentCount	Items	StateImages

ComponentIndex	Left	TabOrder

Components	Name	TabStop

ControlCount	Owner	Tag

Controls	Parent	Top

Ctl3D	ParentColor	TopItem

Cursor	ParentCtl3D	Visible

DragCursor	ParentFont	Width

DragMode	ParentShowHint


Methods

 Key methods

AlphaSort	FindComponent	LoadFromStream

Assign	Focused	Refresh

BeginDrag	Free	RemoveComponent

BringToFront	FullCollapse	RemoveControl

CanFocus	FullExpand	Repaint

ClassName	GetHitTestInfoAt	SaveToFile

ClassParent	GetNodeAt	SaveToStream

ClassType	GetTextBuf	ScaleBy

ClientToScreen	GetTextLen	ScreenToClient

ContainsControl	HandleAllocated	ScrollBy

ControlAtPos	HandleNeeded	SendToBack

Create	Hide	SetBounds

CustomSort	InsertComponent	SetFocus

Destroy	InsertControl	SetTextBuf

DragDrop	Invalidate	Show

Dragging	IsEditing	Update

EndDrag	LoadFromFile


Events

 Key events

OnChange	OnEdited	OnGetSelectedIndex

OnChanging	OnEditing	OnKeyDown

OnClick	OnEndDrag	OnKeyPress

OnCollapsed	OnEnter	OnKeyUp

OnCollapsing	OnExit	OnMouseDown

OnDblClick	OnExpanded	OnMouseMove

OnDeletion	OnExpanding	OnMouseUp

OnDragDrop	OnGetImageIndex	OnStartDrag

OnDragOver


TUDAlignButton type

Unit

ComCtrls

Declaration

TUDAlignButton = (udLeft, udRight);

Description

TUDAlignButton type defines the possible values of the AlignButton property of the TUpDown component.


TUDBtnType type

Unit

ComCtrls

Declaration

TUDBtnType = (btNext, btPrev);

Description

TUDBtnType defines the possible values of the Button parameter for the TUDClickEvent type, which is the return type of the OnClick event for a TUpDown component. The btNext value indicates that the right or up arrow key was clicked. The btPrev value indicates that the left or down arrow was clicked.


TUDOrientation type

Unit

ComCtrls

Declaration

TUDOrientation = (udHorizontal, udVertical);

Description

TUDOrientation type defines the possible values of the Orientation property of the TUpDown component.


TUpdateAction type

Unit

DB

Declaration

type
  TUpdateAction = (uaFail, uaAbort, uaSkip, uaRetry, uaApplied);

Description

The TUpdateAction type defines the possible values for the UpdateAction parameter of the OnUpdateError and OnUpdateRecord events of the TTable, TQuery, and TStoredProc components, as described in the following table:

Value	Description

uaFail	Fail the application of cached updates by raising an exception

uaAbort	Abort the application of cached updates by raising an EAbort exception

uaSkip	Skip this particular cached update; all others continue to be processed.

uaRetry	Retry applying this record's cached update.

uaApplied	Update was applied during the OnUpdateRecord event


TUpdateKind type

Unit

DB

Declaration

type
  TUpdateKind = (ukModify, ukInsert, ukDelete);

Description

The TUpdateKind type defines the possible values for the UpdateKind parameter of the OnUpdateError and OnUpdateRecord events of the TTable, TQuery, and TStoredProc components, as described in the following table:

Value	Description

ukModify	The cached update to the record is a modification to the record's contents.

ukInsert	The cached update is the insertion of a new record.

ukDelete	The cached update is the deletion of a record.


TUpdateRecordTypes type

Unit

DB

Declaration

TUpdateRecordTypes = set of (rtModified, rtInserted, rtDeleted, rtUnModified);

Description

The TUpdateRecordTypes type is the return value of the UpdateRecordTypes property of the dataset components, as described in the following table:

Value	Description

rtModified	Modified records

rtInserted	Inserted records

rtDeleted	Deleted records

rtUnmodified	Unmodified records


TUpdateSQL component

Properties	Methods

Unit

DB

Description

The TUpdateSQL component provides a way to use Delphi's cached updates support with read-only datasets. For example, you could use a TUpdateSQL component with a "canned" query to provide a way of updating the underlying datasets, essentially giving you the ability to post updates to a read-only dataset. You associate a TUpdateSQL component with a dataset by setting the dataset's UpdateObject property. The dataset automatically uses the TUpdateSQL component when cached updates are applied.

The ModifySQL property is an SQL statement that is executed when the cached update is a modification of an existing record. The InsertSQL property is an SQL statement that is executed when the cached update is the insertion of a new record. DeleteSQL is an SQL statement that is executed when the cached update is the deletion of a record. All three properties support an extension to normal parameter binding for cached updates: You can prefix any field name with 'OLD_' to retrieve the value of the field as it was before cached updates were enabled. This extension lets you access the old field values, generally for use in creating the WHERE clause of the SQL statement.

The Apply method is useful for manually executing the SQL statements (such as from an OnUpdateRecord event handler). It combines a call to SetParams to perform the special parameter binding discussed in the previous paragraph and a call to ExecSQL to execute the SQL statement.

The Query array property returns a TQuery object for the SQL statement corresponding to the TUpdateKind index. Likewise, the SQL array property returns the string list representing the SQL statement corresponding to the index. Note that SQL returns the same string lists used in the ModifySQL, InsertSQL, and DeleteSQL properties. For example, SQL[ukInsert] is the same as InsertSQL.

In addition to these properties and methods, this component also has the properties and methods that apply to all components.


Properties

 Run-time only          [image] Key properties

DataSet	InsertSQL	Query

DeleteSQL	ModifySQL	SQL


Methods

 Key methods

Apply	ExecSQL	SetParams


TUpdateStatus type

Unit

DB

Declaration

TUpdateStatus = (usUnmodified, usModified, usInserted, usDeleted);

Description

The TUpdateStatus type is the return value of the UpdateStatus method of the dataset components, as described in the following table:

Value	Description

usUnmodified	Record contents haven't been changed

usModified	Record contents have been changed

usInserted	Record has been inserted

usDeleted	Record has been deleted


{bml dupdwn.bmp} TUpDown component
 TUpDown component

Properties	Methods	Events

Unit

ComCtrls

Description

The TUpDown component consists of a pair of Up and Down arrow buttons. Clicking on these buttons increments and decrements a numeric value held in the Position property. TUpDown is typically used with a companion control, called a buddy window. Use the Associate property to specify the buddy window.

When associated with an edit control, the value of Position sets the text of the edit as a formatted string.  This combination is similar to using a TSpinButton or spinner control and is convenient for prompting numeric user input. If Associate is not specified, Position can be used as an assigned numeric value.

The TUpDown component is an indirect descendent of TWinControl. In addition to the following properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Properties

 Run-time only          [image] Key properties

Align	ControlCount	Parent

AlignButton	Controls	Position

Associate	Cursor	ShowHint

ArrowKeys	Enabled	Showing

BoundsRect	Handle	TabOrder

Brush	Height	TabStop

ClientHeight	HelpContext	Tag

ClientOrigin	Left	Thousands

ClientRect	Min	Top

ClientWidth	Max	Visible

ComponentCount	Name	Width

ComponentIndex	Orientation	Wrap

Components	Owner


Methods

 Key methods

Assign	Dragging	Refresh

BeginDrag	EndDrag	RemoveComponent

BringToFront	FindComponent	RemoveControl

CanFocus	Focused	Repaint

ClassName	Free	ScaleBy

ClassParent	GetTextBuf	ScreenToClient

ClassType	GetTextLen	ScrollBy

ClientToScreen	HandleAllocated	SendToBack

ContainsControl	HandleNeeded	SetBounds

ControlAtPos	Hide	SetFocus

Create	InsertComponent	SetTextBuf

Destroy	InsertControl	Show

DragDrop	Invalidate	Update


Events

 Key events

OnChanging	OnExit	OnMouseMove

OnClick	OnMouseDown	OnMouseUp

OnEnter


TVarBytesField component

Properties	Methods	Events

Unit

DBTables

Description

A TVarBytesField component represents a field of a record which is represented by a value consisting of an arbitrary set of up to 65535 bytes. The first two bytes are a binary value defining the actual length.

Use the Assign method to copy values from another field to a TVarBytesField.

The TVarBytesField component has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DataType	Name

AsBoolean	DisplayLabel	Owner

AsDateTime	DisplayName	ReadOnly

AsFloat	DisplayText	Required

AsInteger	DisplayWidth	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Visible

DataSet	IsIndexField

DataSize	IsNull


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


TViewStyle type

Unit

ComCtrls

Declaration

TViewStyle = (vsIcon, vsSmallIcon, vsList, vsReport);

Description

The ViewStyle contains the possible values for the visual display of items in a list view. vsIcon displays each item as a full-sized icon, vsList displays items in columns and each item as a small icon with the label to the right of it , vsSmallIcon displays each item as a small icon with the label to the right of it, vsReport displays each item on its own line with information arranged in columns, the leftmost column contains the small icon and label, and subsequent columns contain subitems.


TWidth type

Unit

ComCtrls

Declaration

TWidth = ColumnHeaderWidth..MaxInt;

Description

The TWidth type is the type of the Width and WidthType properties which determine the width of the column header in the list view component.


TWindowState type

Unit

Forms

Declaration

TWindowState = (wsNormal, wsMinimized, wsMaximized);

Description

The TWindowState type defines the three possible states of a form: normal, minimized, or maximized. TWindowState is the type of the WindowState property of a form.


TWordField component

Properties	Methods	Events

Unit

DBTables

Description

A TWordField component represents a field of a record in a dataset. It is represented as a binary value with a range from 0 to 65,535. Use TWordField for fields that hold unsigned whole numbers.

Set the DisplayFormat property to control the formatting of the field for display purposes, and the EditFormat property for editing purposes. Use the Value property to access or change the current field value. Set the MinValue or the MaxValue property to limit the smallest or largest value permitted in a field.

The TWordField component has the properties, methods, and events of the TField component.


Properties

 Run-time only          [image] Key properties

Alignment	DisplayLabel	Name

AsBoolean	DisplayName	Owner

AsDateTime	DisplayText	ReadOnly

AsFloat	DisplayWidth	Required

AsInteger	EditFormat	Size

AsString	FieldName	Tag

Calculated	FieldNo	Text

CanModify	Index	Value

DataSet	IsIndexField	Visible

DataSize	IsNull

DataType	MaxValue

DisplayFormat	MinValue


Methods

 Key methods

Assign	Destroy	IsValidChar

AssignValue	FocusControl	SetData

Clear	Free

Create	GetData


Events

 Key events

OnChange	OnSetText	OnValidate

OnGetText


UniDirectional property

Applies to

TQuery component

Declaration

property UniDirectional: Boolean;

Description

If an application only needs to be able to move forward in the result set of a TQuery component, set the UniDirectional property to True. When UniDirectional is True, an application requires less memory (because the records do not have to be cached), but the application cannot move backwards in the result set.

UniDirectional is False by default.


Unmerge method

See also	Example

Applies to

TMainMenu component

Declaration

procedure Unmerge(Menu: TMainMenu);

Description

The Unmerge method reverses the merging of two menus into one in a non-MDI application. The Menu parameter is the merged menu that you no longer want to be merged.


Example

This example uses two forms, each containing a main menu created with the Menu Designer. It also uses a button on Form1. When the user clicks the button, Form2 appears and the main menu of Form2 merges with that of Form1.

procedure TForm1.Button1Click(Sender: TObject);

begin

  Form2.Show;

  MainMenu1.Merge(Form2.MainMenu1);

end;

bo

Form2 also has a button. When the user clicks the button on Form2, the menu of Form2 is no longer merged with the menu on Form1:

procedure TForm2.Button1Click(Sender: TObject);

begin

  Form1.MainMenu1.Unmerge(MainMenu1);

end;

To run this example, create a uses clause in the implementation section of each unit and add the other unit to it. For example, the uses clause in the implementation section of Unit1 would look like this:

uses Unit2;


See also

AutoMerge property

Merge method


UnPrepare method

Applies to

TQuery, TStoredProc component

Description

UnPrepare for Queries

UnPrepare for Stored Procedures


Unprepare method

See also	Example

Applies to

TStoredProc component

Declaration

procedure UnPrepare;

Description

The UnPrepare method notifies the server that the stored procedure will no longer be needed, allowing the server to release any resources allocated to the stored procedure.


Example

StoredProc1.UnPrepare;


See also

Prepared property

Prepare method


Unprepare method

See also

Applies to

TQuery component

Declaration

procedure UnPrepare;

Description

The UnPrepare method sets the Prepared property to False. This ensures that the SQL property will be translated again before the request is submitted to the server. In addition, the server is notified that it can release any resources allocated for optimization purposes, since a new request will be sent before (or in conjunction with) a call to the Open or ExecSQL method.

Preparing a query consumes some database resources, so it is good practice for an application to unprepare a query once it is done using it. The UnPrepare method unprepares a query. When you change the text of a query at run time, Delphi automatically closes and unprepares the query.


See also

Prepare method


UnRegisterChanges method

See also

Applies to

TImageList component

Declaration

procedure UnRegisterChanges(Value: TChangeLink);

Description

The UnRegisterChanges method unregisters the TChangeLink object. The caller will no longer receive notification when the image list changes.


See also

RegisterChanges method, OnChange event


UnselectedColor property

See also	Example

Applies to

TTabSet component

Declaration

property UnselectedColor: TColor;

Description

The UnselectedColor property determines the color of the tabs that aren't currently selected in the tab set control.


Example

This code changes the color of the unselected tabs:

TabSet11.UnselectedColor := clSilver;


See also

SelectedColor property


Update method

Applies to

All controls; TFieldDefs, TIndexDefs, TListItem objects; TDirectoryListBox, TFileListBox components

The Update method repaints or refreshes a component.

Update Method for All Controls

Update Method for Directory and File List Boxes

Update Method for Field Definitions

Update Method for Index Definitions

Update Method for List Items


Update method

Example

Applies to

TDirectoryListBox, TFileListBox components

Declaration

procedure Update;

Description

The Update method updates and refreshes the directory list for the directory and file list box controls.


Example

The following sample code sets the directory of DirectoryListBox1 to C:\TEMP when the form is created. When Button1 is pressed, a subdirectory called MYDIR is added to C:\TEMP, but note that it is not updated in DirectoryListBox1 until Button2 is pressed and Update is called.

procedure TForm1.Button1Click(Sender: TObject);

begin

  MkDir('c:\temp\mydir');

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  DirectoryListBox1.Directory := 'c:\temp';

end;

procedure TForm1.Button2Click(Sender: TObject);

begin

  DirectoryListBox1.Update;

end;


Update method

Applies to

TFieldDefs objects

Declaration

procedure Update;

Description

Update refreshes the TFieldDef entries in Items to reflect the current state of the fields underlying the dataset. It does so without opening the dataset.


Update method

See also

Applies to

TIndexDefs object

Declaration

procedure Update;

Description

The Update method will refresh the entries in Items to reflect the current dataset. Use this method to obtain index information without opening the dataset.


See also

Items property


Update method for list item objects
Update method

See also

Applies to

TListItem object

Declaration

procedure Update;

Description

The Update method updates a list view item display and returns True if successful.


See also

UpdateItems method

Items property


Update method

See also	Example

Applies to

All controls

Declaration

procedure Update;

Description

The Update method calls the Windows API UpdateWindow function, which processes any pending paint messages. For more information, see the Win32 Developer's Reference (WIN32.HLP).


Example

When this line of code runs, Windows repaints EditBox1:

Edit1.Update;


See also

Invalidate method

Refresh method


UpdateCursorPos method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure UpdateCursorPos;

Description

UpdateCursorPos sets the current position of the dataset's underlying BDE cursor to the current cursor position of the dataset. The UpdateCursorPos method is useful if you make direct calls to the Borland Database Engine.


See also

CursorPosChanged method


UpdateFormatSettings property

Applies to

TApplication component

Declaration

property UpdateFormatSettings: Boolean;

Description

The UpdateFormatSettings property specifies whether the format settings are updated automatically when the user alters the system configuration. Set UpdateFormatSettings to False at application startup to not have format setting s update automatically.


UpdateItems method

See also

Applies to

TListView component

Declaration

procedure UpdateItems(FirstIndex, LastIndex: Integer);

Description

The UpdateItems method causes the list view control to redraw a range of items, starting at FirstIndex and ending at LastIndex.


See also

Index property

Items property


UpdateMode property

Example

Applies to

TTable, TQuery components (live result sets only)

Declaration

TUpdateMode = (upWhereAll, upWhereChanged, upWhereKeyOnly);

property UpdateMode: TUpdateMode;

Description

The UpdateMode property determines how Delphi will find records being updated in a SQL database. This property is important in a multi-user environment when users may retrieve the same records and make conflicting changes to them.

When a user posts an update, Delphi uses the original values in the record to find the record in the database. This approach is similar to an optimistic locking scheme. UpdateMode specifies which columns Delphi uses to find the record. In SQL terms, UpdateMode specifies which columns are included in the WHERE clause of an UPDATE statement. If Delphi cannot find a record with the original values in the columns specified (if another user has changed the values in the database), Delphi will not make the update and will generate an exception.

The UpdateMode property may have the following values:

WhereAll (the default): Delphi uses every column to find the record being updated. This is the most restrictive mode.

WhereKeyOnly: Delphi uses only the key columns to find the record being updated. This is the least restrictive mode and should be used only if other users will not be changing the records being updated.

WhereChanged: Delphi uses key columns and columns that have changed to find the record being updated.


Example

Consider a COUNTRY table with columns for NAME (the key), CAPITAL, and CONTINENT. Suppose you and another user simultaneously retrieve a record with the following values:

NAME = "Philippines"

CAPITAL = "Nairobi"

CONTINENT = "Africa"

Both you and the other user notice that the information in this record is incorrect and should be changed. Now, suppose the other user changes CONTINENT to "Asia", CAPITAL to "Manila", and posts the change to the database. A few seconds later, you change NAME to "Kenya" and post your change to the database.

If your application has UpdateMode set to WhereKey on the dataset, Delphi compares the original value of the key column (NAME = "Philippines") to the current value in the database. Since the other user did not change NAME, your update occurs. You think the record is now ["Kenya", "Nairobi", "Africa"] and the other users thinks it is ["Philippines", "Manila", "Asia"]. Unfortunately, it is actually ["Kenya", "Manila", "Asia"], which is still incorrect, even though both you and the other user think you have corrected the mistake. This problem occurred because you had UpdateMode set to its least restrictive level, which does not protect against such occurrences.

If your application had UpdateMode set to WhereAll, the Delphi would check all the columns when you attempt to make your update. Since the other user changed CAPITAL and CONTINENT, Delphi would not let you make the update. When you retrieved the record again, you would see the new values entered by the other user and realize that the mistake had already been corrected.


UpdateRecord method

Applies to

TTable, TQuery, TStoredProc components

Declaration

procedure UpdateRecord;

Description

The UpdateRecord method notifies each TDataSource component that the current record is about to be posted to the dataset. Each data source in turn notifies all data controls so that they can update the fields of the record from the current values displayed in the controls. UpdateRecord is called automatically by Post, but an application can also use it separately to bring the current record up to date without posting it.


UpdateRecordTypes property

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property UpdateRecordTypes: TUpdateRecordTypes;

Description

The UpdateRecordTypes property lets you determine how a record's status affects its visibility in a dataset when cached updates are enabled. Normally, modified, unmodified, and newly inserted records are all visible, but deleted records are not. Adding the rtDeleted set member to UpdateRecordTypes lets deleted records be visible, so you can call RevertRecord to undelete them.


See also

ApplyUpdates method

CachedUpdates property

CancelUpdates method

RevertRecord method

UpdateStatus method


UpdateStatus method

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

function UpdateStatus: TUpdateStatus;

Description

The UpdateStatus property returns the TUpdateStatus value corresponding to the most recent cached update.


See also

ApplyUpdates method

CachedUpdates property

CancelUpdates method

CancelCurrentUpdate method

UpdateRecordTypes property


Updating fields

Most data-aware controls can update the data of a field, by default. Whether or not a field can be updated depends on the settings of the ReadOnly property of the data-aware control and the ReadOnly property of the dataset. By default, the values are False; therefore, the user can modify the data field.

Also, the dataset must also be in Edit state or the data cannot be changed. By setting the AutoEdit property of a dataset to True, the dataset will be in Edit state so that the user can use the data-aware control to edit the field's contents.

For all controls except the data grid (TDBGrid), any modifications to the data made with the control are posted to the dataset when the user presses Tab to move to another control. If the user presses Esc, Delphi abandons the modifications, and the field reverts to the value it held before the user began modifying it.


ValidateEdit method

See also	Example

Applies to

TDBEdit, TMaskEdit components

Declaration

procedure ValidateEdit;

Description

The ValidateEdit method checks the value of the EditText property for blank required characters in the edit box. If one is found, the EDBEditError exception is raised. If no exception occurs, you can be sure all required characters have been entered in the edit box.


Example

The following code calls ValidateEdit from the default OnExit event handler of DBEdit1.

procedure TForm1.DBEdit1Exit(Sender: TObject);

begin

  ValidateEdit;

end;


See also

EditText property


ValidateName method

Example

Applies to

TDatabase component

Declaration

procedure ValidateName(const Name: string);

Description

The ValidateName procedure checks to see if the active session is already using a specified database.  If so, an EDatabaseError is raised.  If not, your application continues to execute. You might use this method to prevent duplicate access to a database.


Example

The following example searches all sessions for an open session with the DBDEMOS directory.

function TForm1.IsDuplicate(DBName: string): string;

var

  SessionCount: Integer;

  SessionNames: TStrings;

begin

  Result:= '';

  SessionNames:= TStringList.Create;

  try

    Sessions.GetSessionNames(SessionNames);

    for SessionCount:= 0 to (Sessions.Count - 1) do

      with TDatabase.Create(nil) do

      try

        SessionName:= SessionNames[SessionCount];

        try

          ValidateName(DBName);

        except

          on EDatabaseError do

            Result:= SessionNames[SessionCount];

        end;

      finally

        Free;

      end;

  finally

    SessionNames.Free;

  end;

end;

procedure TForm1.Button1Click(Sender: TObject);

var

  Duplicate: string;

begin

  Duplicate:=

    IsDuplicate('c:\program files\borland\delphi 2.0\demos\data');

  if Duplicate <> '' then

    ShowMessage(Format('Duplicate found in %s Session', [Duplicate]))

  else

    ShowMessage('Not A Duplicate');

end;


ValidFieldIndex method

Applies to

TDBGrid component

Declaration

function ValidFieldIndex(FieldIndex: Integer): Boolean;

Description

Returns True if the specified FieldIndex identifies a field displayed in the grid or False if the index is out of range. The valid range for a field index is 0..FieldCount - 1.


ValidParentForm function

Example

Unit

Forms

Declaration

function ValidParentForm(Control: TControl): TForm;

Description

The ValidParentForm function returns the form that contains the control specified in the Control parameter. If the specified control is not on a form, ValidParentForm generates an EInvalidOperation exception.

If you prefer that the function return nil when the specified control is not on a form, use the GetParentForm function.


Example

The following code calls ValidParentForm to find the parent form of the MyForm.MyButton control. If found, that form is shown modally. If not, an exception occurs.

procedure TForm1.Button3Click(Sender: TObject);

begin

  ValidParentForm(MyForm.MyButton).ShowModal;

end;


Value property

Applies to

TDBLookupCombo, TDBLookupList, TDBRadioGroup components; All field components

Description

The Value property specifies a text value associated with a component that is linked to a field in a data set record.

Value Property for Database Radio Groups

Value property for Database Lookup Combo and List Boxes

Value Property for Fields

Value property for TParam objects


Value property

See also	Example

Applies to

TDBRadioGroup components

Declaration

property Value: string;

Description

The value of the Value property is the current contents of the field for the current record in the dataset. When the user selects a radio button, the value of the Value property changes to the value of the Items string for the radio button. The new value of the Value property becomes the value of the field for the current record in the dataset.

If the ReadOnly property of the database radio group box is True, the user won't be able to select a button or change the contents of the field.


Example

The following code concatenates some text to the string in the Value property. When the user chooses a radio button in DBRadioGroup1, the value of Value is stored in the corresponding field in the DataSource (if ReadOnly is False). In the OnChange event handler, a label is updated, indicating to the user that this change has occurred.

procedure TForm1.DBRadioGroup1Change(Sender: TObject);

begin

  Label1.Caption := 'Field ' + DBRadioGroup1.DataField + ' has changed to ' +     DBRadioGroup1.Value;

end;


See also

ItemIndex property


Value property

See also	Example

Applies to

TDBLookupCombo, TDBLookupList components

Declaration

property Value: string;

Description

Run-time only. The value of the Value property is the contents of the DataField for the current record in the primary dataset. As the user moves through the primary dataset, the value of the Value property changes.

By explicitly changing the Value property value at run time, you change the contents of the field.


Example

The following code changes the Value property, and thus, the value of the field in the connected dataset to 'Green'.

DBLookupCombo1.Value := 'Green';


See also

DisplayValue property


Value property

Example

Applies to

All field components

Declaration

property Value: Variant      {All field components}

property Value: string;      {TStringField, TBlobField}

property Value: Longint;     {TAutoIncField, TIntegerField, TSmallintField, TWordField}

property Value: Double;      {TBCDField, TCurrencyField, TFloatField}

property Value: Boolean;     {TBooleanField}

property Value: TDateTime    {TDateField, TDateTimeField, TTimeField}

Description

Run-time only. Value is the actual data in a TField. Use Value to read data directly from and write data directly to a TField.


Examples

StringField1.Value := 'Delphi';

DateField1.Value := StrToDateTime('02/14/95 00:00:00');


Value property for TParam objects
Value property

See also

Applies to

TParam object

Declaration

property Value: Variant;

Description

The Value property returns the value of a parameter as a variant. Using a variant is useful if you don't know the type of a parameter.


See also

AsBCD property

AsBoolean property

AsCurrency property

AsDate property

AsDateTime property

AsFloat property

AsInteger property

AsSmallInt property

AsString property

AsTime property

AsWord property

DataType property

Text property


ValueChecked property

See also	Example

Applies to

TDBCheckBox component

Declaration

property ValueChecked: string;

Description

If the value of the ValueChecked property is equal to the data in the field of the current record of the dataset, the database check box is checked.

You also can enter a semicolon-delimited list of items as the value of ValueChecked. If any of the items matches the contents of the field of the current record in the dataset, the check box is checked. For example, you can specify a ValueChecked string like this:

DBCheckBox1.ValueChecked := 'True;Yes;On';

If the string True, Yes, or On is the contents of the field specified as the database check box's DataField, the check box is checked. The case of the specified strings is not checked.

If the contents of the field of the current record matches a string specified as the value of the ValueUnchecked property, the check box is unchecked. If the contents of the field matches no string in either ValueChecked or ValueUnchecked, the check box appears gray.

If the DataField of the database check box is a logical field, the check box is always checked if the contents of the field is True, and it is always unchecked if the contents of the field is False. The values of the ValueChecked and ValueUnchecked properties have no affect on logical fields.

If the user checks a database check box, the string that is the value of the ValueChecked property is placed in the database field, as long as the ReadOnly property is False. If the value is a semicolon-delimited list of items, the first item in the list is inserted as the contents of the field of the current record.

The default value of ValueChecked is the string 'True'.


Example

The following code toggles the value of the ValueChecked property of DBCheckBox1 from 'True' to 'False' or from 'False' to 'True'.

with DBCheckBox1 do

if (ValueChecked = 'True') or (ValueChecked = 'False') then

  if ValueChecked = 'True' then ValueChecked := 'False'

  else ValueChecked := 'True';


See also

ValueUnchecked property


Values property

Applies to

TStrings, TStringList objects; TDBRadioGroup component

Description

Values Property for String Objects

Values Property for Database RadioGroup Boxes


Values property

Example

Applies to

TStrings, TStringList objects

Declaration

property Values[const Name: string]: string;

Description

The Values property gives you access to a specific string in a list of strings. The strings must have a unique structure before you can use the Values property array to access them:

Name=Value

The Name that identifies the string is to the left of the equal sign (=), and the current Value of the Name identifier is on the right side of the equal sign. There should be no spaces present before and after the equal sign.

Such strings are commonly found in .INI files. For example, here are a few strings taken from a DELPHI.INI file:

DisplayGrid=1

SnapToGrid=1

GridSizeX=8

GridSizeY=8

The strings that make up the Params property of a database component (TDatabase) have the same format. The most common use of the Values property is to modify a string within the Params property array.

To modify a string in a list of strings that have the required format, identify the string to modify with the Name constant parameter, which serves as an index into the list of strings, and assign a new value.


Example

Assume that a string that identifies the password needed to access a database exists in the Params string list. You can change the acceptable password using this code:

Database1.Params.Values['Password'] := 'TopSecret';

If there is no password string, the same code creates one at the bottom of the list of strings and assigns the 'TopSecret' string as its value.

You can also assign the value of the string to a variable. For example, this code assigns the current value of the password string to a variable called StringValue:

var

  StringValue: string;

StringValue := Database1.Params.Values['Password'];


Values property

See also	Example

Applies to

TDBRadioGroup component

Declaration

property Values: TStrings;

Description

Each string in the Items property for a database radio group box places a radio button in the group box with an accompanying caption. If the contents of a field for the current record is the same as one of the strings in Items, the corresponding radio button is selected. If the user selects one of the radio group buttons and the ReadOnly property of the database radio group is False, the contents of the field changes to the corresponding Items string.

Often, you might not want the same string that serves as the caption of a radio button to become the contents of the field. Or, you might want a different value in the data field (other than the caption of a radio button) to select a radio button. In this case, use the Values property. You can specify a string in the Value property for each string in the Items list. The first string in Values corresponds to the first string in the Items, and therefore, the first radio button in the group box.

For example, suppose you have two strings in the Items property for a database radio group: Yes and No. If there are no strings in the Values property, the data field must contain either the value Yes or No to select one of the radio buttons. If the user selects one of these buttons, the string Yes or No becomes the contents of the data field.

If the data field contains values such as Y or N, rather than Yes or No, you can specify Y or N as Values strings. This way, the Yes or No radio buttons are selected when a Y or N value appears in the data field. When the user selects one of the radio buttons, Y or N becomes the value of the field of the current record.


Example

This example uses a database radio group box connected to field in a dataset. The field contains the values 'Y', 'N', or 'M'. You want the captions of the radio buttons to be 'Yes', 'No', or 'Maybe', so the code adds these three strings to the Items property array. The actual values that are in the field and that can entered into the field are the 'Y', 'N', and 'M' strings, so these are added to the Values property array.

procedure TForm1.FormCreate(Sender: TObject);

begin

  with DBRadioGroup1 do

  begin

    Items.Add('Yes');

    Items.Add('No');

    Items.Add('Maybe');

    Values.Add('Y');

    Values.Add('N');

    Values.Add('M');

  end;

end;

When the code runs, three radio buttons appear in the group box. If the current record in the dataset contains any of the values contained in the Values property, the appropriate radio button is checked. When the user selects a radio button, the corresponding string in the Values property is entered into the field.


See also

ItemIndex property

Items property


ValueUnchecked property

See also	Example

Applies to

TDBCheckBox component

Declaration

property ValueUnchecked: string;

Description

If the value of the ValueUnchecked property is equal to the data in the field of the current record of the dataset, the database check box is unchecked.

You also can enter a semicolon-delimited list of items as the value of ValueUnchecked. If any of the items matches the contents of the field of the current record in the dataset, the check box is unchecked. For example, you can specify a ValueUnchecked string like this:

DBCheckBox1.ValueUnchecked := 'False;No;Off';

If the string False, No, or Off is the contents of the field specified as the database check box's DataField, the check box is unchecked.

If the contents of the field of the current record matches a string specified as the value of the ValueChecked property, the check box is checked. If the contents of the field matches no string in either ValueChecked or ValueUnchecked, the check box appears gray.

If the DataField of the database check box is a logical field, the check box is always checked if the contents of the field is True, and it is always unchecked if the contents of the field is False. The values of the ValueChecked and ValueUnchecked properties have no affect on logical fields.

If the user checks a database check box, the string that is the value of the ValueUnchecked property is placed in the database field, as long as the ReadOnly property is False. If the value is a semicolon-delimited list of items, the first item in the list is inserted as the contents of the field of the current record.

The default value of ValueUnchecked is the string 'False'.


Example

The following code changes ValueUnchecked to 'NO'. When the value of the linked field is 'NO', DBCheckBox1 is unchecked.

DBCheckBox1.ValueUnchecked := 'NO';


See also

ValueChecked property


VersionMajor property

See also

Applies to

TReport component

Declaration

property VersionMajor: Integer;

Description

Run-time and read-only. The value of the VersionMajor property identifies which major version of ReportSmith you are running. For example, if you are using ReportSmith 3.0, the value of VersionMajor is 3. The minor version value is reported in the VersionMinor property.


See also

VersionMinor property


VersionMinor property

See also

Applies to

TReport component

Declaration

property VersionMajor: Integer;

Description

Run-time and read-only. The value of the VersionMinor property identifies which minor version of ReportSmith you are running. For example, if you are using ReportSmith 3.0, the value of VersionMinor is 0. The major version value is reported in the VersionMajor property.


See also

VersionMajor property


VertScrollBar property

See also	Example

Applies to

TForm, TScrollBox components

Declaration

property VertScrollBar: TControlScrollBar;

Description

The VertScrollBar property is the form's or scroll box's vertical scroll bar. The values of VertScrollBar's nested properties determines how the vertical scroll bar behaves.

To make a vertical scroll bar appear on a form or scroll box, these nested properties of VertScrollBar must be set like this:

Visible must be True.

The value of the Range property must be greater than the value of the ClientHeight property of the form or the Height property of the scroll box.


Example

This example places a vertical scroll bar on the form, as long as the ClientHeight of the form is not greater than 500:

procedure TForm1.FormCreate(Sender: TObject);

begin

  with VertScrollBar do

  begin

    Range := 500;

    Visible := True;

  end;

end;


See also

HorzScrollBar property

Increment property

Position property

Range property

ScrollPos property

Visible property


ViewOrigin property

See also

Applies to

TListView component

Declaration

property ViewOrigin: TPoint;

Description

Run-time and read-only. ViewOrigin returns the set of coordinates, relative to the visible area of the list view control, that correspond to the view coordinates (0, 0). This information can be useful when the list view is scrolled to show more items than can fit in the client area of the control. ViewOrigin should be used only when ViewStyle is vsIcon or vsSmallIcon; it returns random data when ViewStyle is vsReport or vsList. In list or report view, the current scroll position is determined by the TopItem property.


See also

ViewStyle property

BoundingRect property

DisplayRect property


ViewStyle property

See also

Applies to

TListView component

Declaration

property ViewStyle: TViewStyle;

Description

The ViewStyle property controls the visual display of items in a list view. The ViewStyle can be vsList, vsIcon, vsReport or vsSmallIcon. vsIcon displays each item as a full-sized icon, vsList diplays items in columns and each item as a small icon with the label to the right of it , vsSmallIcon displays each item as a small icon with the label to right of it, vsReport displays each item on its own line with information arranged in columns, the leftmost column contains the small icon and label, and subsequent columns contain subitems. These are the possible values:

Value	Meaning

vsIcon	Each item appears as a full-sized icon with a label below it. The user can drag the items to any location in the list view window.

vsSmallIcon	Each item appears as a small icon with the label to the right of it. The user can drag the items to any location.

vsList	Each item appears as a small icon with a label to the right of it. Items are arranged in columns and cannot be dragged to any arbitrary location by the user.

vsReport	Each item appears on its own line with information arranged in columns. The leftmost column contains the small icon and label, and subsequent columns contain subitems as specified by the application. Unless ShowColumnHeaders is False, each column has a header.


See also

SmallImages property

Largemages property

Columns property

ShowColumnHeaders property


Visible property

See also	Example

Applies to

All controls; TBCDField, TBlobField, TBooleanField, TBytesField, TControlScrollBar, TCurrencyField, TDateField, TDateTimeField, TFloatField, TForm, TGraphicField, TIntegerField, TMenuItem, TMemoField, TSmallintField, TStringField, TTimeField, TVarBytesField, TWordField components

Declaration

property Visible: Boolean;

Description

The Visible property determines whether the component appears onscreen. If Visible is True, the component appears. If Visible is False, the component is not visible.

For controls, calling the Show method makes the control's Visible property True, but it also performs other actions to ensure that the user can see the control.

For field components, the Visible property determines if a field can be displayed in a TDBGrid component. If Visible is False, the field is not displayed.

The default value is True for all components except for forms.

Note:	For tab sheets, changing this property at run time has no effect. Use TabVisible to show and hide a page. For fields the Visible property has no effect if there is an explicit TDBGrid.Columns for a field. In Delphi 1.0 the field's Visible property controlled whether or not a field column would appear in a DBGrid. In Delphi 2.0 the TDBGrid.Columns property will ignore the Visible property if there are explicit columns.


Example

The following code shows how to make a button invisible:

Button1.Visible := False;


See also

Hide method

HorzScrollBar property

Show method

VertScrollBar property


VisibleButtons property

Applies to

TDBNavigator, TMediaPlayer components

Description

The VisibleButtons property determines which buttons of a component are visible, and therefore, which operations the user can perform.

VisibleButtons Property for Media Player Components

VisibleButtons Property for Database Navigator Components


VisibleButtons property

See also	Example

Applies to

TMediaPlayer component

Declaration

property VisibleButtons: TButtonSet;

Description

The VisibleButtons property determines which of the buttons on the media player are visible. If a button is not made visible with VisibleButtons, it does not appear on the media player control. By default, all buttons are visible when a media player component is added to a form.

Button	Value	Action

Play	btPlay	Plays the media player

Record	btRecord	Starts recording

Stop	btStop	Stops playing or recording

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks

Step	btStep	Moves forward a number of frames

Back	btBack	Moves backward a number of frames

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium


Example

The following line of code causes only the Play and Stop buttons of MediaPlayer1 to be displayed:

MediaPlayer1.VisibleButtons := [btPlay, btStop];


See also

ColoredButtons property

EnabledButtons property


VisibleButtons property

Example

Applies to

TDBNavigator component

Declaration

property VisibleButtons: TButtonSet;

Description

The value of the VisibleButtons property determines which buttons appear on the database navigator component. By default, all the buttons are visible. By changing the value of the VisibleButtons set, you can hide some of the buttons, and therefore, prevent the user from performing certain operations. For example, if you only want the user to view the records in the dataset, you would include only the nbFirst, nbPrior, nbNext, and nbLast values in the VisibleButtons set.

Button	Value	Action

First	nbFirst	Go to the first record

Prior	nbPrior	Go to the previous record

Next	nbNext	Go to the next record

Last	nbLast	Go to the last record

Insert	nbInsert	Insert a blank record

Delete	nbDelete	Deletes the current record

Edit	nbEdit	Permits editing of the current record

Post	nbPost	Posts the current record

Cancel	nbCancel	Cancels the current edit

Refresh	nbRefresh	Refreshes the data in the dataset

The default value is all of these values in the Options set.


Example

The following line of code displays only the Prior and Next buttons of DBNavigator1:

DBNavigator1.VisibleButtons := [nbPrior, nbNext];


VisibleColCount property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

function VisibleColCount: Integer;

Description

Run-time and read-only. The VisibleColCount contains the number of columns, other than fixed or nonscrolling columns, that are fully displayed in the grid. If another column is partially displayed in the grid, it won't be part of the count.


Example

This example uses a draw grid, two labels, and a button on a form. When the user clicks the button, the number of rows and columns, excluding partial and fixed ones, are reported in the captions of the two labels:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := IntToStr(DrawGrid1.VisibleRowCount) + ' rows';

  Label2.Caption := IntToStr(DrawGrid1.VisibleColCount) + ' columns';

end;


See also

ColCount property

VisibleRowCount property


VisibleRowCount property

Applies to

TDrawGrid, TListView, TStringGrid components

Description

VisibleRowCount property for Draw and String Grids

VisibleRowCount property for List Views


VisibleRowCount property

See also	Example

Applies to

TDrawGrid, TStringGrid components

Declaration

function VisibleRowCount: Integer;

Description

Run-time and read-only. The VisibleRowCount contains the number of rows, other than fixed or nonscrolling rows, that are fully displayed in the grid. If another row is partially displayed in the grid, it won't be part of the count.


Example

This example uses a draw grid, two labels, and a button on a form. When the user clicks the button, the number of rows and columns, excluding partial and fixed ones, are reported in the captions of the two labels:

procedure TForm1.Button1Click(Sender: TObject);

begin

  Label1.Caption := IntToStr(DrawGrid1.VisibleRowCount) + ' rows';

  Label2.Caption := IntToStr(DrawGrid1.VisibleColCount) + ' columns';

end;


See also

RowCount property

VisibleColCount property


VisibleRowCount property for list views
VisibleRowCount property

See also

Applies to

TListView components

Declaration

function VisibleRowCount: Integer;

Description

Run-time and read-only. The VisibleRowCount property returns the number of items that can fit vertically in the visible area of a list view control when the ViewStyle is either vsList or vsReport. Only fully-visible items are counted.


See also

MakeVisible method

ViewStyle property

SelCount property


VisibleTabs property

Example

Applies to

TTabSet component

Declaration

property VisibleTabs: Integer;

Description

Read-only. The value of the VisibleTabs property contains the number of tabs currently visible in the tab set control.


Example

This example queries the VisibleTabs property to find out how many tabs are visible in the tab set control and assigns the number to a variable:

SeeTabs := TabSet11.VisibleTabs;


Wait property

Example

Applies to

TMediaPlayer component

Declaration

property Wait: Boolean;

Description

The Wait property determines whether a media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop) returns control to the application only after it has been completed. Wait is unavailable at design time.

If Wait is True, the media player component waits until the next media control method has completed before returning control to the application. If Wait is False, the application won't wait for the next media control method to finish before continuing.

Wait affects only the next media control method called after setting Wait. You must reset Wait to affect any subsequent call to a media control method.

By default, Play and StartRecording function as if Wait is False. You must set Wait to True before calling Play or StartRecording to prevent control from returning to the application before playing or recording has finished. By default, all other media control methods function as if Wait is True.

Note:	Usually you would set Wait to False only if the next media control is expected to take a long time, so that your application can execute other code before the media control method has completed. If you set Wait to False, you might want to set Notify to True so the application is notified when the media control method completes.


Example

The following code plays a .WAV audio file named NI!.WAV twice. The first call to play doesn't return control to the application until the file is done playing. Note that if you remove the line of code that sets wait to true, the sound is only played once.

procedure TForm1.Button1Click(Sender: TObject);

begin

  with MediaPlayer1 do begin

    FileName := 'ni!.wav';

    AutoRewind := True;

    try

      Open;              { Open Media Player }

      Wait := True;      { Waits until sounds is done playing to return }

      Play;              { Play sound }

      Play;              { Play again }

    finally

      Close;             { Close media player }

    end;

  end;

end;


WantReturns property

See also	Example

Applies to

TDBMemo, TMemo, TRichEdit components

Declaration

property WantReturns: Boolean;

Description

The WantReturns property determines whether return characters the user enters in the memo or rich edit by pressing Enter affect the text in the controls or go to the form. If WantReturns is True and the user presses Enter, a return character is entered in the memo or rich edit. If WantReturns is False and the user presses Enter, a return is not entered in the memo or rich edit, but instead goes to the form. For example, if there is a default button on a form, pressing Enter would choose the button instead of affecting the text in the memo or rich edit.

To enter return characters in a memo when WantReturns is False, press Ctrl+Enter.


Example

This example uses a memo and a check box on a form. If the check box is checked, the user can enter return characters into text entered in the memo. If the check box is unchecked, return characters aren't entered into the memo, but go to the form.

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    Memo1.WantReturns := True

  else

    Memo1.WantReturns := False;

end;


See also

KeyPreview property

WantTabs property

WordWrap property


WantTabs property

See also	Example

Applies to

TDBMemo, TMemo, TRichEdit components

Declaration

property WantTabs: Boolean;

Description

The WantTabs property determines if tabs are enabled in a memo or rich edit control. To enable tabs for those controls set WantTabs to True. To turn tabs off, set WantTabs to False.

Caution:	If WantTabs is True, the user can't use the Tab key to select the next control on the form. The user can tab into a memo control, but can't tab out.


Example

This example uses a memo and a check box on a form. When the check box is checked, the user can enter tab characters into the memo's text. When the check box is unchecked, the user can't enter tab characters into the text, but can use the Tab key to move between the memo and the check box controls.

procedure TForm1.CheckBox1Click(Sender: TObject);

begin

  if CheckBox1.Checked then

    Memo1.WantTabs := True

  else

    Memo1.WantTabs := False;

end;


See also

KeyPreview property

TabStop property

WantReturns property

WordWrap property


Width property

Applies to

All controls; TBitmap, TGraphic, TIcon, TImageList, TMetafile, TPen, TPicture, TListItem, TListColumn, TColumn objects; TForm, TScreen components

Description

The Width property determines horizontal size

Width Property for List Columns

Width Property for Forms and All Controls

Width Property for Screen Components

Width Property for Graphics Objects

Width Property for Image Lists

Width Property for Columns

Width Property for List Items


Width property

See also

Applies to

TImageList object

Declaration

property Width: Integer;

Description

The Width property sets the width for an image within the ImageList. Note that the image list will be cleared if this value changes.


See also

Height property, CreateSize contructor


Width property

See also	Example

Applies to

All controls; TForm component

Declaration

property Width: Integer;

The Width property determines the horizontal size of the control or form in pixels. When you increase the Width property value, the form or control becomes wider. If you decrease the value, the form or control becomes narrower.

Note:	For tab sheets, changing this property at run time will have no effect. For header controls, if the width is set to a value too narrow to show even one character of text then the first character and the ellipsis will appear to the right of the section boundary of that header section.


Example

The following code doubles the width of a button:

Button1.Width := Button1.Width * 2;


See also

ClientWidth property

Height property

SetBounds method


Width Property for Graphic Objects
Width property

See also	Example

Applies to

TBitmap, TGraphic, TIcon, TImageList, TMetafile, TPen, TPicture objects

Declaration

property Width: Integer;

Description

The Width property determines the maximum width of the graphics object in pixels.


Example

To set the pen width to a random value from 1 to 10,

Canvas.Pen.Width := 1 + Random(10);


See also

Height property


Width property

See also	Example

Applies to

TScreen components

Declaration

property Width: Integer;

Description

Run-time and read-only. The Width property is the horizontal size of the screen device in pixels.


Example

The following component determines the width of all the forms on the screen and resizes the ones that are wider than the screen width. To run this code, the integer variable I must be declared.

with Screen do

  for I := 0 to FormCount-1 do

  if Forms[I].Width > Width than Forms[I].Width := Width;


See also

Height property


Top property for list item objects
Width property

See also	Example

Applies to

TListItem object

Declaration

property Width: TWidth;

Description

The Width property specifies the width of the column header in the TreeView when the tree view's ViewStyle property is set to vsReport and the ShowColumnHeaders property is set to True. This property can be set a design time in the ListView Columns Editor dialog or at run time.


Example

The following example sets the width of the selected list item to 5.

ListView1.Columns[1].Width := 5;


See also

Height property


Width property

See also

Applies to

TColumn object

Declaration

property Width: Integer;

Description

The width in pixels of a column in a TDBGrid component.


See also

DefaultWidth method


Sort method for list views
Width property

See also

Applies to

TListColumn object

Declaration

property Width: TWidth;

Description

The Width property returns and sets the width of the column header of the list view control. The list view must have its ShowColumnHeaders property set and its ViewStyle property must be vsReport to see column headers. If Width is set to one of the values below, the column header will be automatically sized. If Width is set to 0 or greater, the width of the column header will be the value in pixels. The Width can be set to one of the values below and from 0 to MaxInt. Width always returns the width of the column in pixels. To see if the column is automatically sized, see what is stored in the WidthType property.

Value	Meaning

ColumnTextWidth	Sizes the column header to fit the text contained in the column.

ColumnHeaderWidth	Sizes the column header to fit the text contained in the column header.

The Width property can be set at design time by bringing up the ListView Columns Editor dialog from the list view controls Columns property and choosing from Width Value, Header Width and ItemWidth. WidthValue sets the column header width to the value specified, Header Width sizes the column header to the text contained in the column header and Item Width sizes the column header to the text contained in the column.


See also

WidthType property

Columns property


WidthType property

See also

Applies to

TListColumn object

Declaration

property WidthType: TWidth;

Description

Run-time and read-only. The WidthType property returns whether the width of the column header is sized automatically or has a specified width. If WidthType returns ColumnTextWidth, then the column header is sized automatically to fit the text contained in the columns. If WidthType returns ColumnHeaderWidth, then the column header is sized automatically to fit the text in the column header. If WidthType is 0 or greater, the column header width will be the WidthType value in pixels. The list view must have its ShowColumnHeaders property set and its ViewStyle property must be vsReport to see column headers. To set the column width or to have the column automatically sized, use the Width property.


See also

Width property

Text property


WindowMenu property

See also	Example

Applies to

TForm component

Declaration

property WindowMenu: TMenuItem;

Description

Most Windows MDI applications contain a Window menu that contains menu items such as Cascade, Arrange Icons, Tile, and so on that let the user manage the windows in the application. Usually this menu lists (at the bottom) the child windows that are currently open in the application. When the user selects one of these windows from the menu, the window becomes the active window in the application.

The WindowMenu property determines which menu includes the open child windows (or forms) in your application. Although this menu is commonly called the Window menu, it can be any name of your choosing. It must be an existing menu item, however, and it should be one of the menu items that appears in the menu bar or the child forms won't be included in a menu.


Example

For this code to run, a menu item called MyWindows must exist on an MDI form parent form. This line of code designates the MyWindows menu to be the Window menu, the menu that lists all open child windows in an MDI application:

WindowMenu := MyWindows;


See also

FormStyle property

TMenuItem component


WindowState property

See also	Example

Applies to

TForm component

Declaration

property WindowState: TWindowState

Description

The WindowState determines the initial state of the form. These are the possible values:

Value	Meaning

wsNormal	The form appears neither maximized nor minimized

wsMaximized	The form is maximized

wsMinimized	The form is minimized

The default value is wsNormal.


Example

The following code responds to the user clicking a button named Shrink by minimizing the form:

procedure TForm1.ShrinkClick(Sender: TObject);

begin

  WindowState := wsMinimized;

end;


See also

TWindowState type


WordWrap property

See also	Example

Applies to

TDBMemo, TDBText, TLabel, TMemo, TRichEdit components

Declaration

property WordWrap: Boolean;

Description

The WordWrap property determines if text in a label, memo, or rich edit control wraps at the right margin so that it fits in the control. You can give the user access to the lines which aren't visible in a memo or rich edit control by setting its ScrollBars property to add horizontal, vertical, or both scrollbars to the memo control. There should be no reason to use a horizontal scroll bar if WordWrap is True.

The memo or rich edit control must be tall enough to display at least one line of text to allow the user to edit its contents, even if WordWrap is True.

The default value is False.


Example

This example allows text a user enters in the Memo1 control to wrap to the next line, if the control is large enough to hold the text:

Memo1.WordWrap := True;


See also

ScrollBars property

Text property

AutoSize property


Wrap property

See also

Applies to

TUpDown component

Declaration

property Wrap: Boolean;

Description

Specifies whether to wrap Position. If Wrap is true incrementing past the Max value resets Position to the Min value.


See also

Max property, Min property, Position property


WrapText property

See also

Applies to

TIconOptions object

Declaration

property WrapText: Boolean;

Description

The WrapText property specifies whether the items caption will wrap around or be displayed all on one line. This only applies if the list view has its ViewStyle property set to vsIcon or vsSmallIcon.


See also

ViewStyle property

Items property

Caption property


Write method

See also	Example

Applies to

TBlobStream object

Declaration

function Write(const Buffer; Count: Longint): Longint; override;

Description

The Write method copies up to Count bytes from Buffer to the current position in the field. Buffer must have at least Count bytes allocated for it. Write returns the number of bytes transferred (which may be less than the number requested in Count.) Transfers which require crossing a selector boundary in the source will be handled correctly.


Example

The following example writes a string to the end of a blob stream.

procedure TForm1.Button3Click(Sender: TObject);

var

  Stream: TBlobStream;

  S: string;

begin

  Table1.edit;

  Stream := TBlobStream.Create(Table1Notes, bmReadWrite);

  try

    Stream.Seek(0, 2); {Seek 0 bytes from the stream's end point}

    S :=' This line will be added to the end.';

    Stream.Write(S[1], Length(S));

  finally

    Stream.Free;

  end;

  Table1.Post;

end;


See also

TBlobField component

TBytesField component

TVarBytesField component


WriteBool method

See also	Example

Applies to

TIniFile object

Declaration

procedure WriteBool(const Section, Ident: string; Value: Boolean);

Description

The WriteBool method writes a Boolean value in an .INI file.

The Section constant identifies the section of the .INI file where the value is written.

The Ident parameter is the name of the identifier for which you want to change the value. The Value parameter contains the new value.


Example

This example creates an .INI file for a game with two entries in the Options section, and one entry in the Configuration section.

Before you try this example, you must add IniFiles to the uses clause of your unit.

var

  GameIni: TIniFile;

begin

  Gamini := TIniFile.Create('FUNGAME.INI');

  with GameIni do

  begin

    WriteBool('Options', 'Sound', True);

    WriteInteger('Options', 'Level', 3);

    WriteString('Configuration', 'Name', 'Teresa Ace');

    Free;

  end;

end;


See also

ReadBool method

WriteInteger method

WriteString method


WriteInteger method

See also	Example

Applies to

TIniFile object

Declaration

procedure WriteInteger(const Section, Ident: string; Value: Longint);

Description

The WriteInteger method writes an integer value in an .INI file.

The Section constant identifies the section of the .INI file where the value is written.

The Ident constant is the name of the identifier for which you want to change the value. The Value parameter contains the new value.


Example

This example creates an .INI file for a game with two entries in the Options section, and one entry in the Configuration section.

Before you try this example, you must add IniFiles to the uses clause of your unit.

var

  GameIni: TIniFile;

begin

  GameIni := TIniFile.Create('FUNGAME.INI');

  GameIni.WriteBool('Options', 'Sound', True);

  GameIni.WriteInteger('Options', 'Level', 3);

  GameIni.WriteString('Configuration', 'Name', 'Teresa Ace');

  GameIni.Free;

end;


See also

ReadInteger method

WriteBool method

WriteString method


WriteString method

See also	Example

Applies to

TIniFile object

Declaration

procedure WriteString(const Section, Ident, Value: string);

Description

The WriteString method writes a string in an .INI file.

The Section constant identifies the section of the .INI file where the string is written. For example, the WIN.INI for Windows contains a [Desktop] section.

The Ident constant is the name of the identifier for which you want to change the value. The Value constant holds the new string value.


Example

This example creates an .INI file for a game with two entries in the Options section, and one entry in the Configuration section.

Before you try this example, you must add IniFiles to the uses clause of your unit.

var

  GameIni: TIniFile;

begin

  GameIni := TIniFile.Create('FUNGAME.INI');

  GameIni.WriteBool('Options', 'Sound', True);

  GameIni.WriteInteger('Options', 'Level', 3);

  GameIni.WriteString('Configuration', 'Name', 'Teresa Ace');

  GameIni.Free;

end;


See also

ReadSection method

ReadString method

WriteBool method

WriteInteger method


  Topic Not Found

The topic you are looking for was not found. The problem might be with the Help file or it might be with the link to the topic. You may be able to find this topic by using the Contents, Index or Search tab.

To search for a topic,

1	Click the Contents tab to browse through topics by category.

2	Click the Index tab to see a list of index entries.

Either type the word you're looking for or scroll through the list.

3	Click the Find tab to search for words or phrases


Welcome to RoboHELP. Click Topic (Ctrl+T) to add your first Help topic.

This is associated with the Delphi 95 project file document.


OLEAuto unit

See also

The OLEAuto unit contains all the declarations of items needed to create OLE automation controllers and servers.

The following items are declared in the OLEAuto unit:

Objects

EOleError

TAutomation

TAutoObject

Types

TAutoClass

TAutoClassInfo

TAutoClassInstancing

TLastReleaseEvent

TStartMode

Routines

CreateOleObject

DllCanUnloadNow

DllGetClassObject

DllRegisterServer

DllUnRegisterServer

GetActiveOleObject


See also

OLE automation


AddRef method

See also

Applies to

TAutoObject

Declaration

function AddRef: Integer;

Description

The AddRef method increments the reference count for an OLE automation object and returns the current reference count.


See also

RefCount property

Release method


AutoDispatch property

See also

Applies to

TAutoObject

Declaration

property AutoDispatch: TAutoDispatch;

Description

The AutoDispatch property provides an IDispatch interface to the automation object, suitable for passing to OLE API functions.


See also

VarToInterface function


Automation variable

See also

Unit

OLEAuto

Declaration

var
  Automation: TAutomation

Description

The Automation variable is a global instance of the automation manager class. It serves as the Automation manager for an OLE automation server written with Delphi.

When you create an OLE automation object (an object derived from TAutoObject), the unit that defines that object must call Automation.RegisterClass, passing a record of type TAutoClassInfo. The Automation manager then handles all interactions between your automation object and the OLE automation API.


See also

TAutoObject object

RegisterClass method

TAutoClassInfo type


AutoObjectCount property

See also

Applies to

TAutomation

Declaration

property AutoObjectCount: Integer;

Description

The AutoObjectCount property indicates how many OLE automation object instances the Automation manager is currently managing.

Each time the Automation manager creates an instance of one of the server objects it manages, it increments its internal count, which your application can read through the read-only property AutoObjectCount.


See also

Automation variable


Create method for OLE automation objects
Create method

See also

Applies to

TAutoObject

Declaration

constructor Create; virtual;

Description

The Create method for OLE automation objects constructs an instance of an OLE automation object for export from an automation server. Create increments the object count for the Automation manager, sets its own reference count to 1, and constructs its IDispatch interface.


See also

AutoObjectCount property

Automation variable


Create method for OLE automation managers
Create method

See also

Applies to

TAutomation

Declaration

constructor Create;

Description

The Create method for OLE automation managers constructs the instance of the automation manager, then determines whether it is running in a DLL. If it is, it sets its IsInprocServer property to True. Finally, Create searches for the standard OLE automation command-line switches and sets the corresponding StartMode value.


See also

IsInprocServer property

StartMode property


CreateOleObject function

See also

Unit

OLEAuto

Declaration

function CreateOleObject(const ClassName: string): Variant;

Description

The CreateOleObject function creates an OLE automation object of the specified class and returns it in a variant. This is the way to get a new instance of an OLE automation server object for your automation controller.


See also

Creating OLE Automation controllers

Variants and OLE automation

GetActiveOleObject function


DllCanUnloadNow function

See also

Unit

OLEAuto

Declaration

function DllCanUnloadNow: HResult; stdcall;

Description

The DllCanUnloadNow function indicates to Windows whether it can unload an in-process automation server.

DllCanUnloadNow is one of four functions in the OleAuto unit that every in-process server must export so that Windows can manage the server resources properly. The others are DllGetClassObject, DllRegisterServer, and DllUnregisterServer. You should never need to call or alter any of these functions.


See also

DllGetClassObject function

DllRegisterServer function

DllUnregisterServer function


DllGetClassObject function

See also

Unit

OLEAuto

Declaration

function DllGetClassObject(const CLSID: TCLSID; const IID: TIID; var Obj): HResult; stdcall;

Description

The DllGetClassObject function returns an OLE automation object to Windows based on IDs from the internal OLE manager.

DllGetClassObject is one of four functions in the OleAuto unit that every in-process server must export so that Windows can manage the server resources properly. The others are DllCanUnloadNow, DllRegisterServer, and DllUnregisterServer. You should never need to call or alter any of these functions.


See also

DllCanUnloadNow function

DllRegisterServer function

DllUnregisterServer function


DllRegisterServer function

See also

Unit

OLEAuto

Declaration

function DllRegisterServer: HResult;

Description

The DllRegisterServer function registers an OLE automation server in the current module in response to a request from Windows.

DllRegisterServer is one of four functions in the OleAuto unit that every in-process server must export so that Windows can manage the server resources properly. The others are DllCanUnloadNow, DllGetClassObject, and DllUnregisterServer. You should never need to call or alter any of these functions.


See also

DllCanUnloadNow function

DllGetClassObject function

DllUnregisterServer function


DllUnregisterServer function

See also

Unit

OLEAuto

Declaration

function DllUnregisterServer: HResult;

Description

The DllUnregisterServer function unregisters an OLE automation server in the current module in response to a request from Windows.

DllUnregisterServer is one of four functions in the OleAuto unit that every in-process server must export so that Windows can manage the server resources properly. The others are DllCanUnloadNow, DllGetClassObject, and DllRegisterServer. You should never need to call or alter any of these functions.


See also

DllCanUnloadNow function

DllGetClassObject function

DllRegisterServer function


EOLEError object

Unit

OLEAuto

Declaration

type
  EOleError = class(Exception);

Description

The EOleError object is the exception class for OLE automation errors.


GetActiveOleObject function

See also

Unit

OLEAuto

Declaration

function GetActiveOleObject(const ClassName: string): Variant;

Description

The GetActiveOleObject function returns the active object for the specified class.


See also

CreateOleObject function


IsInprocServer property

See also

Applies to

TAutomation

Declaration

property IsInprocServer: Boolean;

Description

The IsInprocServer property indicates whether the OLE automation server is an in-process server. Delphi assumes that all OLE automation servers in DLLs are in-process servers, and that those in applications are not.


See also

In-process automation servers

IsLibrary variable


  OleObject property

See also

Applies to

TAutoObject

Declaration

property OleObject: Variant;

Description

For TAutoObject, the OleObject property provides a variant containing the automation object. When your server needs to pass an OLE object to a controller, the controller expects it in the form of a variant. You should therefore always references to an automation object's OleObject property, rather than references to the object itself.

For TOleContainer (runtime and readonly) the OleObject property returns an OLE Automation object for the OLE object. If the OLE object doesn't support OLE Automation, an exception is raised. An OLE object must already be loaded in the container before accessing the OleObject property.


See also

Variants and OLE automation


OnLastRelease event

See also

Applies to

TAutomation

Declaration

property OnLastRelease: TLastReleaseEvent;

Description

The OnLastRelease event occurs when the automation manager releases the last instance of an OLE automation object. OnLastRelease does not occur for in-process servers.

The Shutdown parameter of the event is a var parameter, so an event handler can force or prevent the shutdown of the automation manager by setting Shutdown to True or False, respectively. By default, Shutdown is True only for servers with a StartMode of smAutomation; that is, shutdown is only automatic for servers started expressly for automation.


See also

Release method

StartMode property


RefCount property

See also

Applies to

TAutoObject

Declaration

property RefCount: Integer;

Description

The RefCount property holds the current reference count of the OLE automation object.

RefCount is read-only. To increment or decrement the reference count, call the AddRef or Release methods.


See also

AddRef method

Release method


RegisterClass method

See also

Applies to

TAutomation

Declaration

procedure RegisterClass(const AutoClassInfo: TAutoClassInfo);

Description

The RegisterClass method registers an OLE automation server class with the OLE automation manager (Automation).

Every unit that defines an OLE automation server class (an object derived from TAutoObject) must include a call in its initialization section to Automation.RegisterClass, passing a record of class-registration information.


See also

Automation variable

TAutoObject object


Release method for OLE automation objects
Release method

See also

Applies to

TAutoObject

Declaration

function Release: Integer;

Description

The Release method decrements the OLE automation object's reference count and returns the current count. If the new count is zero, Release destroys the object by calling Free.


See also

RefCount property

AddRef method

Free method


ServerRegistration method

See also

Applies to

TAutomation

Declaration

function ServerRegistration: Boolean;

Description

The ServerRegistration method registers or unregisters the server class in the system registry, returning a Boolean value indicating whether it has done so.

If the server was started to register or unregister the server class (StartMode is smRegServer or smUnregServer), ServerRegistration calls UpdateRegistry to register or unregister, as appropriate, then returns True. Otherwise, ServerRegistration does nothing, and returns False.


See also

StartMode property

UpdateRegistry method


StartMode property

See also

Applies to

TAutomation

Declaration

property StartMode: TStartMode;

Description

The StartMode property indicates the reason an OLE automation server was started: as a standalone, interactive application, as an embedded object, or for registration or unregistration.

The Automation manager decides what, if anything, to do with the server when its controller applications have finished with it based on the value of StartMode, as described under OnLastRelease.


See also

Automation variable


TAutoClass type

Unit

OLEAuto

Declaration

type
  TAutoClass = class of TAutoObject;

Description

The TAutoClass type is the class-reference type for OLE automation objects.


TAutoClassInfo type

See also

Unit

OLEAuto

Declaration

type
  TAutoClassInfo = record
    AutoClass: TAutoClass;
    ProgID: string;
    ClassID: string;
    Description: string;
    Instancing: TAutoClassInstancing;
  end;

Description

The TAutoClassInfo type is the information record used for registering OLE Automation objects.


See also

RegisterClass method


TAutoClassInstancing type

See also

Unit

OLEAuto

Declaration

type
  TAutoClassInstancing = (acInternal, acSingleInstance, acMultiInstance);

Description

The TAutoClassInstancing defines the available instancing modes for local server automation classes.


See also

TAutoClassInfo type


TAutomation object

See also	Properties	Methods	Events

Unit

OLEAuto

Description

The TAutomation object is the OLE automation manager object.


Properties

AutoObjectCount	IsInprocServer	StartMode


Methods

Create	RegisterClass	UpdateRegistry

Destroy	ServerRegistration


Event

OnLastRelease


See also

Automation variable


TAutoObject object

See also	Properties	Methods

Unit

OLEAuto

Description

The TAutoObject object is the base class for all objects in Delphi automation servers. When you create a new automation object, you derive it from TAutoObject, then declare properties and methods in an automated section of the new class.

To expose an automation object to external OLE automation controllers, the unit that implements the automation object must call Automation.RegisterClass in its initialization section, passing in a TAutoClassInfo record.Once you register your automation object, the global Automation object automatically manages all aspects of the object's interface with the OLE automation APIs.

When an external OLE automation controller requests an instance of the automation object, the Automation manager calls the Create constructor to construct the instance. When all external references to the object disappear, the Automation manager calls the Destroy method to destroy the instance. The automation object maintains a reference count to determine when all references are gone.


Properties

AutoDispatch	OleObject	RefCount


Methods

AddRef	Destroy	Release

Create


See also

Automation variable

TAutomation object


TLastReleaseEvent type

See also

Unit

OLEAuto

Declaration

type
  TLastReleaseEvent = procedure(var Shutdown: Boolean) of object;

Description

The TLastReleaseEvent type is a method-pointer type used for the OnLastRelease event. The variable parameter Shutdown enables the application to override the default behavior for whether to shut down the server application when all instances are released.


See also

OnLastRelease event


TStartMode type

See also

Unit

OLEAuto

Declaration

type
  TStartMode = (smStandalone, smAutomation, smRegServer, smUnregServer);

Description

The TStartMode type specifies the possible values for the StartMode property, indicating the different reasons why an OLE automation server can be started.

The following table explains each of the possible start-mode values and the command-line switch that corresponds to each.

Start mode	Switch	Meaning

smAutomation	embedding	The application was started by Windows in response to a request from an automation controller.

smRegServer	regserver	The application was started only to add the server to the system registry.

smStandalone	---	The user started the application as a standalone, interactive application.

smUnregServer	unregserver	The application was started only to remove the server from the system registry.


See also

StartMode property


UpdateRegistry method

See also

Applies to

TAutomation

Declaration

procedure UpdateRegistry(Register: Boolean);

Description

The UpdateRegistry method updates the system registry for all the OLE automation objects handled by the OLE automation manager (that is, all the OLE automation objects in a particular server application). If the Register parameter is True, UpdateRegistry registers the servers. Otherwise, it unregisters them.

The ServerRegistration method calls UpdateRegistry automatically, so you should never need to call it yourself.


See also

ServerRegistration method


VarFromInterface function

See also

Unit

OLEAuto

Declaration

function VarFromInterface(Unknown: IUnknown): Variant;

Description

The VarFromInterface function returns a variant containing a reference to the IDispatch interface of the passed IUnknown interface. If Unknown is nil, the result is Unassigned.


See also

VarToInterface function


VarToAutoObject function

See also

Unit

OLEAuto

Declaration

function VarToAutoObject(const V: Variant): TAutoObject;

Description

The VarToAutoObject function returns a Delphi class instance for an IDispatch interface reference that arrives in variant form. Use VarToAutoObject when an external source provides an automation object in variant form that is supposed to contain a Delphi object. If the object is, in fact, a Delphi automation class, VarToAutoObject returns an instance of that class. If it is not, the funciton raises an EOleError exception.


See also

EOLEError object


VarToInterface function

See also

Unit

OLEAuto

Declaration

function VarToInterface(const V: Variant): IDispatch;

Description

The VarToInterface function converts an OLE object in a variant (such as one obtained from an external server) into an IDispatch object you can pass to an OLE API function. If V does not contain an IDispatch interface reference, VarToInterface raises an EOLEError exception.

VarToInterface does not affect the reference count of the returned IDispatch. The routine that calls VarToInterface is responsible for calling AddRef and Release on the returned interface.

To obtain an IDispatch from a locally-produced automation object, reference that object's AutoDispatch property.


See also

VarFromInterface function

AutoDispatch property


Initialize method

Applies to

TApplication

Declaration

procedure Initialize;

Description

The Initialize method is the first thing called for every Delphi project. In most cases, Initialize does nothing.

For OLE automation servers (projects that contain objects derived from TAutoObject), Initialize:

1	Automatically registers the OLE automation server class in the system registry (unless the instancing attribute is set to acInternal)

2	Checks for the following command-line switches:

/regserver
-regserver
/unregserver
-unregserver

If a regserver switch is found, Initialize immediately terminates the application after updating the system registry.

If an unregserver switch is found, Initialize removes the OLE automation server classes defined by the application from the system registry, then terminates the application.

For projects that do not contain OLE automation servers, you can safely delete the call to Initialize.


ShowMainForm property

See also

Applies to

TApplication

Declaration

property ShowMainForm: Boolean;

Description

The ShowMainForm property determines whether the application shows its main form on startup. The default value is True, meaning the main window shows.

By setting ShowMainForm to False in the main project file before the call to Application.Run, you can manually control whether the application shows its main form. This is mostly useful for implemention OLE automation servers, since you might not want the server's main form to show when started for automation purposes.


See also

Run method


ArcCos function

Unit

Math

Declaration

function ArcCos(X: Extended): Extended;

Description

The ArcCos function returns the inverse cosine of X. X must be betwen -1 and 1. The return value will be in the range [0..PI], in radians.

{ IN: |X| <= 1 OUT: [0..PI] radians }


ArcSin function

Unit

Math

Declaration

function ArcSin(X: Extended): Extended;

Description

The ArcSin function returns the inverse sine of X. X must be betwen -1 and 1. The return value will be in the range [-PI/2..PI/2], in radians.

{ IN: |X| <=1 OUT: [-PI/2..PI/2] radians }


ArcTan2 function

Unit

Math

Declaration

function ArcTan2(Y, X: Extended): Extended;

Description

The ArcTan2 function calculates ArcTan(Y/X), and returns an angle in the correct quadrant.

{   IN: |Y| < 2^64, |X| < 2^64, X <> 0   OUT: [-PI..PI] radians }


SinCos procedure

Unit

Math

Declaration

procedure SinCos(Theta: Extended; var Sin, Cos: Extended) register;

Description

The SinCos procedure is twice as fast as calling Sin and Cos separately for the same angle.


Tan function

Unit

Math

Declaration

function Tan(X: Extended): Extended;

Description

The Tan function returns the tangent of X. Tan(X) = Sin(X) / Cos(X).


Cotan function

Unit

Math

Declaration

function Cotan(X: Extended): Extended;

Description

{ 1 / Tan(X), X <> 0 }


Hypot function

Unit

Math

Declaration

function Hypot(X, Y: Extended): Extended;

Description

The Hypot function returns the length of the hypotenuse of a right triangle, given lengths of the other two sides in X and Y.

{ Sqrt(X**2 + Y**2) }


DegToRad function

Unit

Math

Declaration

function DegToRad(Degrees: Extended): Extended;

Description

The DegToRad function converts degree angles to radians. 360 degrees sweep a circle, 2PI radians in a circle.

{ Radians := Degrees * PI / 180}


RadToDeg function

Unit

Math

Declaration

function RadToDeg(Radians: Extended): Extended;

Description

The RadToDeg function converts angles of radian measure into degrees.

{ Degrees := Radians * 180 / PI }


GradToRad function

Unit

Math

Declaration

function GradToRad(Grads: Extended): Extended;

Description

The GradToRad function converts angles of grad measure into radians. 400 grads sweep a complete circle.

{ Radians := Grads * PI / 200 }


RadToGrad function

Unit

Math

Declaration

function RadToGrad(Radians: Extended): Extended;

Description

The RadToGrad function converts angles of radian measure into grads.

{ Grads := Radians * 200 / PI }


CycleToRad function

Unit

Math

Declaration

function CycleToRad(Cycles: Extended): Extended;

Description

The CycleToRad function converts angles measured in cycles into radians. One cycle sweeps a complete circle.

{ Radians := Cycles * 2PI }


RadToCycle function

Unit

Math

Declaration

function RadToCycle(Radians: Extended): Extended;

Description

The RadToCycle function converts angles measured in radians into cycles.

{ Cycles := Radians / 2PI }


Cosh function

Unit

Math

Declaration

function Cosh(X: Extended): Extended;

Description

The Cosh function calculates the hyperbolic cosine of X.


Sinh function

Unit

Math

Declaration

function Sinh(X: Extended): Extended;

Description

The Sinh function calculates the hyperbolic sine of X.


Tanh function

Unit

Math

Declaration

function Tanh(X: Extended): Extended;

Description

The Tanh function calculates the hyperbolic tangent of X.


ArcCosh function

Unit

Math

Declaration

function ArcCosh(X: Extended): Extended;

Description

The ArcCosh function calculates the inverse hyperbolic cosine of X.

{ IN: X >= 1 }


ArcSinh function

Unit

Math

Declaration

function ArcSinh(X: Extended): Extended;

Description

The ArcSinh function calculates the inverse hyperbolic sine of X.


ArcTanh function

Unit

Math

Declaration

function ArcTanh(X: Extended): Extended;

Description

The ArcTanh function calculates the inverse hyperbolic tangent of X.

{ IN: |X| <= 1 }


LnXP1 function

Unit

Math

Declaration

function LnXP1(X: Extended): Extended;

Description

The LnXP1 function returns the natural logarithm of (X+1).

{ Ln(X + 1), accurate for X near zero }


Log10 function

Unit

Math

Declaration

function Log10(X: Extended): Extended;

Description

The Log10 function returns the log base 10 of X.


Log2 function

Unit

Math

Declaration

function Log2(X: Extended): Extended;

Description

The Log2 function returns the log base 2 of X.


LogN function

Unit

Math

Declaration

function LogN(Base, X: Extended): Extended;

Description

The LogN function returns the log base N of X.


IntPower function

Unit

Math

Declaration

function IntPower(Base: Extended; Exponent: Integer): Extended register;

Description

The IntPower function raises Base to an integral power. For example, BaseExponent.


Power function

Unit

Math

Declaration

function Power(Base, Exponent: Extended): Extended;

Description

The Power function raises Base to any power. For example, BaseExponent. For fractional exponents or exponents greater than MaxInt, Base must be greater than 0.


Frexp procedure

Unit

Math

Declaration

procedure Frexp(X: Extended; var Mantissa: Extended; var Exponent: Integer) register;

Description

The Frexp procedure separates the Mantissa and Exponent of X.


Ldexp function

Unit

Math

Declaration

function Ldexp(X: Extended; P: Integer): Extended register;

Description

The Ldexp function returns X times (2 to the power of P).


Ceil function

Unit

Math

Declaration

function Ceil(X: Extended):Integer;

Description

The Ceil function rounds toward positive infinity. For example:

Ceil(-2.8) = -2

Ceil(2.8) = 3

Ceil(-1.0) = -1

{ Ceil: Smallest integer >= X, |X| < MaxInt }


Floor function

Unit

Math

Declaration

function Floor(X: Extended): Integer;

Description

The Floor function rounds toward negative infinity. For example:

Floor(-2.8) = -3

Floor(2.8) = 2

Floor(-1.0) = -1

{ Floor: Largest integer <= X,  |X| < MaxInt }


Mean function

Unit

Math

Declaration

function Mean(const Data: array of Double): Extended;

Description

The Mean function calculates the arithmetic average of all the values in the Data array parameter.

{ (AVG):  SUM / N }


Sum function

Unit

Math

Declaration

function Sum(const Data: array of Double): Extended

Description

The Sum function calculates the sum of all the values in the Data array parameter.


SumOfSquares function

Unit

Math

Declaration

function SumOfSquares(const Data: array of Double): Extended;

Description

The SumOfSquares function returns the sum of the squares of the Data values: Data[0]2 + Data[1]2 + Data[2]2 ...


SumsAndSquares procedure

Unit

Math

Declaration

procedure SumsAndSquares(const Data: array of Double;

  var Sum, SumOfSquares: Extended) register;

Description

The SumsAndSquares procedure returns the sum of the Data values in Sum and the sum of the squares in SumOfSquares. This function is faster than calculating the sums separately.


MinValue function

Unit

Math

Declaration

function MinValue(const Data: array of Double): Double;

Description

The MinValue function returns the smallest signed value in the Data array (MIN).


MaxValue function

Unit

Math

Declaration

function MaxValue(const Data: array of Double): Double;

Description

The MaxValue function returns the largest signed value in the Data array (MAX).


StdDev function

Unit

Math

Declaration

function StdDev(const Data: array of Double): Extended;

Description

The StdDev function calculates the sample standard deviation (the square root of the sample variance) of all values in the Data array parameter.


MeanAndStdDev procedure

Unit

Math

Declaration

procedure MeanAndStdDev(const Data: array of Double; var Mean, StdDev: Extended);

Description

The MeanAndStdDev procedure calculates Mean and StdDev in one pass, which is twice as fast as calculating them separately. You may lose precision when the Mean is very large (> 10e7) or the variance is very small.


PopnStdDev function

Unit

Math

Declaration

function PopnStdDev(const Data: array of Double): Extended;

Description

The PopnStdDev function calculates the population standard deviation (the square root of the population variance) of all values in the Data array parameter. This function is used in some business and financial calculations.


Variance function

Unit

Math

Declaration

function Variance(const Data: array of Double): Extended;

Description

The Variance function calculates the sample variance of all values in the Data array parameter, using the n-1 method (unbiased): TotalVariance / (n-1).


PopnVariance function

Unit

Math

Declaration

function PopnVariance(const Data: array of Double): Extended;

Description

The PopnVariance function calculates the population variance of all values in the Data array parameter, using the n method (biased): TotalVariance / n.


TotalVariance function

Unit

Math

Declaration

function TotalVariance(const Data: array of Double): Extended;

Description

The TotalVariance function returns the sum of the squares of the difference between each Data value and the mean of the data values.

{ Total Variance: SUM(i=1,N)[(X(i) - Mean)**2] }


Norm function

Unit

Math

Declaration

function Norm(const Data: array of Double): Extended;

Description

The Norm function returns the Euclidean 'L-2' norm.

{ Norm:  Sqrt(SumOfSquares) }


MomentSkewKurtosis procedure

Unit

Math

Declaration

procedure MomentSkewKurtosis(const Data: array of Double;

  var M1, M2, M3, M4, Skew, Kurtosis: Extended);

Description

The MomentSkewKurtosis procedure calculates the core factors of statistical analysis: the first four moments plus the coefficients of skewness and kurtosis. M1 is the mean.  M2 is the variance. Skew reflects symmetry of distribution. Kurtosis reflects flatness of distribution.


RandG function

Unit

Math

Declaration

function RandG(Mean, StdDev: Extended): Extended;

Description

The RandG function produces random numbers with Gaussian distribution about the Mean. This is useful for simulating data with sampling errors and expected deviations from the Mean.


TPaymentTime type

Unit

Math

Declaration

TPaymentTime = (ptEndOfPeriod, ptStartOfPeriod);

Description

TPaymentTime is an enumerated type used as a parameter in many of the financial functions. For example, if interest is calculated on the principle balance at the beginning of the payment period, pass in ptStartOfPeriod.


DoubleDecliningBalance function

Unit

Math

Declaration

function DoubleDecliningBalance(Cost, Salvage: Extended;

  Life, Period: Integer): Extended;

Description

The DoubleDecliningBalance function determines accelerated depreciation values for an asset, given the initial cost, life expectancy, end value, and depreciation period. It calculates depreciation using the double-declining balance method.


FutureValue function

Unit

Math

Declaration

function FutureValue(Rate: Extended; NPeriods: Integer; Payment, PresentValue:

  Extended; PaymentTime: TPaymentTime): Extended;

Description

The FutureValue function returns the future value of an investment of PresentValue where Payment is invested for NPeriods at the rate of Rate per period. The PaymentTime parameter indicates whether the investment is an ordinary annuity or an annuity due (enter 0 if payments are at the end of each period, 1 if they are at the beginning).


InterestPayment function

Unit

Math

Declaration

function InterestPayment(Rate: Extended; Period, NPeriods: Integer; PresentValue,

  FutureValue: Extended; PaymentTime: TPaymentTime): Extended;

Description

The InterestPayment function calculates what portion of a loan payment is interest. Rate represents the fixed periodic interest rate, Period identifies the payment period, NPeriods is the number of periods of the loan, PresentValue represents the amount borrowed (the principal), FutureValue is the future value of the investment, and PaymentTime indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1 or 0, respectively).


InterestRate function

Unit

Math

Declaration

function InterestRate(NPeriods: Integer;

  Payment, PresentValue, FutureValue: Extended; PaymentTime: TPaymentTime): Extended;

Description

The InterestRate function calculates the interest rate required in order for an investment of PresentValue, with periodic payments of Payment, to be worth FutureValue within NPeriods compounding periods. If NPeriods represents years, an annual interest rate results; if NPeriods represents months, a monthly interest rate results, and so on. The PaymentTime parameter indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1or 0, respectively).


InternalRateOfReturn function

Unit

Math

Declaration

function InternalRateOfReturn(Guess: Extended;

  const CashFlows: array of Double): Extended;

Description

The InternalRateOfReturn function determines the internal rate of return on an investment. It references an array that contains cash flow information and uses the supplied internal rate of return estimate to calculate results.

Before you use this function, define an array containing expected cash flow amounts over a period of time. It is assumed that the amounts are received at regular intervals. Negative amounts are interpreted as cash outflows, and positive amounts as inflows. The first amount must be a negative number, to reflect the initial investment. The following amounts can all be the same for each time period, or they can be different (including a mixture of negatives, positives, or zeros).


NumberOfPeriods function

Unit

Math

Declaration

function NumberOfPeriods(Rate, Payment, PresentValue, FutureValue: Extended;

  PaymentTime: TPaymentTime): Extended;

Description

The NumberOfPeriods function computes the number of payment periods required for an investment of PresentValue to reach a value of FutureValue, while making regular payments of Payment and accruing interest at the rate of Rate per compounding period. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1or 0, respectively).


NetPresentValue function

Unit

Math

Declaration

function NetPresentValue(Rate: Extended; const CashFlows: array of Double;

  PaymentTime: TPaymentTime): Extended;

Description

The NetPresentValue function calculates the current value of an array of estimated cash flow values, discounted at the given interest rate of Rate. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1or 0, respectively). NetPresentValue helps you determine how much an investment is currently worth, based on expected earnings, although its accuracy depends on the accuracy of the cash flows in the array.


Payment function

Unit

Math

Declaration

function Payment(Rate: Extended; NPeriods: Integer;

  PresentValue, FutureValue: Extended; PaymentTime: TPaymentTime): Extended;

Description

The Payment function calculates the fully amortized payment of borrowing PresentValue dollars at Rate percent per period over NPeriods. It assumes that interest is paid at the end of each period.

FutureValue is the value that the investment will reach at some point. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (enter a value of 1 for the beginning or 0 for the end).


PeriodPayment function

Unit

Math

Declaration

function PeriodPayment(Rate: Extended; Period, NPeriods: Integer;

  PresentValue, FutureValue: Extended; PaymentTime: TPaymentTime): Extended;

Description

The PeriodPayment function gives the part of the payment that is principal. The InterestPayment function gives the part of the payment that is interest.

The Rate parameter is the interest rate. Period is the number of periods into the loan for which the principal is desired, and NPeriods is the number of periods of the loan. FutureValue is the value the investment will reach at some point. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (enter a value of 1 for the beginning or 0 for the end).


PresentValue function

Unit

Math

Declaration

function PresentValue(Rate: Extended; NPeriods: Integer;

  Payment, FutureValue: Extended; PaymentTime: TPaymentTime): Extended;

Description

The PresentValue function calculates the present value of an investment where Payment is received for NPeriods and is discounted at the rate of Rate per period. FutureValue is the value the investment may reach at some point. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (enter a value of 1 for the beginning or 0 for the end).


SLNDepreciation function

Unit

Math

Declaration

function SLNDepreciation(Cost, Salvage: Extended; Life: Integer): Extended;

Description

The SLNDepreciation function calculates the straight-line depreciation allowance for an asset over one period of its life. The function divides the Cost minus the Salvage by the number of years of useful Life of the asset. Cost is the amount initially paid for the asset. Salvage is the value of the asset at the end of its useful life.

To compute accelerated depreciation (allowing higher depreciation values in the first years of the assets life), use the SYDDepreciation function.


SYDDepreciation function

Unit

Math

Declaration

function SYDDepreciation(Cost, Salvage: Extended; Life, Period: Integer): Extended;

Description

The SYDDepreciation function (for "sum-of-years-digits depreciation") calculates depreciation amounts for an asset using an accelerated depreciation method. This allows for higher depreciation in the earlier years of an asset's life.

Cost is the initial cost of the asset. Salvage is the value of the asset at the end of its life expectancy. Life is the length of the asset's life expectancy. Period is the period for which you want to calculate the depreciation.


EInvalidArgument object

Unit

Math

Declaration

EInvalidArgument = class(EMathError) end;

Description

Some functions in the math unit, such as the financial functions, will raise an EInvalidArgument exception if one of the parameters to the routine is out of range or makes the calculation unsolvable.


System unit

The System unit is the Delphi run-time library.

It implements low-level run-time support routines for all built-in features, such as file I/O, string handling, floating-point routines, and dynamic memory allocation.

All units and programs automatically use the System unit, so you never need to reference it in a uses clause.

The elements of the System unit are:

Procedures and functions

Variables and typed constants


System unit procedures and functions

This is an alphabetical listing of all the procedures and functions in the System unit.

Arithmetic routines

Concat	Concatenates a sequence of strings

Copy	Returns a substring of a string

Delete	Deletes a substring from a string

Dynamic allocation routines

Finalize	Uninitializes a dynamically allocated variable.

Flow-control routines

Initialize	Initializes a dynamically allocated variable.

Insert	Inserts a substring into a string

I/O routines

Length	Returns the dynamic length of a string

Miscellaneous routines

Ole string support routines

Ordinal routines

Pointer and address routines

Pos	Searches for a substring in a string

Ptr	Converts a given address to a pointer.

SetLength	Sets the dynamic length of a string variable.

SetString	Sets the contents and  length of a given string.

Slice	Allows passing a sub-secton of an array as an array parameter.

Str	Converts a numeric value to a string

StringOfCharS	Returns a string of a given number of characters.

Text-file routines

Thread support routines

Transfer routines

TypeInfo	Returns run-time type information for a given identifier.

UniqueString	Makes a given string unique, with a reference count of one.

Untyped-file routines

Val	Converts a string value to its numeric representation

Variant support routines

Wide character routines


System unit variables and typed constants

Variables (uninitialized)

Variable	Type	Description

DLLProc	Pointer	Specifies a procedure invoked on calling the DLL’s entry point.

Input	Text	Input standard file.

IsConsole	Boolean	Returns whether or not a module is a console app.

IsLibrary	Boolean	Returns whether or not a module is a DLL.

Output	Text	Output standard file.

Unassigned	Variant	Indicates if a variable has not been assigned a value.

Constants

Initial

Constant	type	value	Description

CmdLine	PChar	nil	Command line pointer

CmdShow	Integer	0	CmdShow parameter for

ErrorAddr	Pointer	nil	Run-time error address

ErrorProc	Pointer	nil	Error handler procedure

ExceptionClass	TClass 	nil	Exception base class (must be Exception)

ExceptProc	Pointer 	nil	Unhandled exception handler

ExitCode	Integer	0	Exit code

ExitProc	Pointer	nil	Exit procedure

FileMode	Byte	2	File open mode

HInstance	Longint	0	Handle of this instance

InOutRes	Integer	0	I/O result buffer

NULL	Variant	nil	Indicates that a variant has no value.

RandSeed	LongInt	0	Random seed


Units
RTL units

Here is a listing of the standard units for the RTL that are shipped with Delphi.

Math unit

System unit

SysUtils unit


SysUtils unit

The SysUtils unit contains the declarations for exception classes, string routines, date and time routines and utility routines.

The SysUtils unit is automatically added to the uses clause whenever you create a new form.

The following items are declared in the SysUtils unit:

Objects

Exception

Types

LongRec

TFileName

TFloatFormat

TFloatValue

TFileRec

TFloatRec

THeapStatus

TMethod

TSearchRec

TTextRec

WordRec

Exceptions

EAbort

EAccessViolation

EControlC

EConvertError

EDivByZero

EExternalException

EInOutError

EIntError

EIntOverFlow

EInvalidCast

EInvalidOp

EInvalidPointer

EMathError

EOutOfMemory

EOverflow

EPrivilege

EPropReadOnly

EPropWriteOnly

ERangeError

EStackOverflow

EUnderflow

EVariantError

EZeroDivide

Constants

File attribute constants

File open modes constants

File mode constants

Variables

Currency and Date/Time formatting variables

Routines

AddExitProc

AdjustLineBreaks

AllocMem

AnsiCompareStr

AnsiCompareText

AnsiLowerCase

AnsiUpperCase

Beep

CompareStr

CompareText

CreateDir

Date/time routines

DisposeStr

Exception-handling routines

File management routines

Floating-point conversion routines

FmtLoadStr

GetCurrentDir

GetFormatSetting

IntToHex

IntToStr

IsValidIdent

LoadStr

LowerCase

NewStr

RemoveDir

SetCurrentDir

String formatting routines

String-handling routines (null terminated)

StrToInt

StrToIntDef

SysErrorMessage

Trim

TrimLeft

TrimRight

UpperCase

To see a listing of items declared in this unit including their declarations, use the ObjectBrower.


Math unit

Objects

EInvalidArgument

Type

TPaymentTime

Routines

ArcCos

ArcCosh

ArcSin

ArcSinh

ArcTan2

ArcTanh

Ceil

Cosh

Cotan

CycleToRad

DegToRad

DoubleDecliningBalance

Floor

Frexp

FutureValue

GradToRad

Hypot

InterestPayment

InterestRate

InternalRateOfReturn

IntPower

Ldexp

LnXP1

Log2

Log10

LogN

MaxValue

Mean

MeanAndStdDev

MinValue

MomentSkewKurtosis

NetPresentValue

Norm

NumberOfPeriods

Payment

PeriodPayment

PopnStdDev

PopnVariance

Power

PresentValue

RadToCycle

RadToDeg

RadToGrad

RandG

SinCos

Sinh

SLNDepreciation

StdDev

Sum

SumOfSquares

SumsAndSquares

SYDDepreciation

Tan

Tanh

TotalVariance

Variance


Visual Component Library objects

See also	Methods

Objects are the fundamental elements of the VCL. In fact, all components and controls are based on objects.

Objects differ from controls in that you can access them only at run time. Unlike most components, objects do not appear on the Component palette. Instead, a default instance variable is declared in the unit of the object or you have to declare one yourself.

For example, the Clipboard function is declared in the Clipbrd unit. To use a TClipboard object, add the Clipbrd unit to the uses clause of the unit, then refer to the Clipboard variable. However, to use a TBitmap object, add the Graphics unit to the uses clause of the unit, then execute the following code at run time to declare an instance variable:

var

  Bitmap1: TBitmap;

begin

  Bitmap1 := TBitmap.Create;

end;

The properties, methods, and events that all objects have in common are inherited from an abstract object type called TObject. You need to understand the internal details of TObject only if you are creating a new object based on TObject.

The following is a list of all objects in the VCL that descend from TObject.:

TBitmap	TGraphic	TOutlineNode

TBlobStream	TGraphicsObject	TParam

TBrush	THeaderSection	TParams

TCanvas	THeaderSections	TPen

TChangeLink	TIcon	TPicture

TClipboard	TIconOptions	TPrinter

TCollection	TIndexDef	TRegistry

TCollectionItem	TIndexDefs	TRegIniFile

TColumn	TIniFile	TStatusPanel

TColumnTitle	TList	TStatusPanels

TControlScrollBar	TListColumn	TStringList

TDragObject	TListItem	TStrings

TDragControlObject	TListItems	TTextAttributesg

TFieldDef	TMetafile	TThread

TFieldDefs	TMetafileCanvas	TTreeNode

TFont	TParaAttributes	TTreeNodesT

In addition to these objects, all VCL components also descend from TObject, although not directly.


Methods

The TObject object introduces the following methods that all objects and components inherit:

ClassName	ClassType	Destroy

ClassParent	Create	Free


See also

VCL components

VCL controls

VCL nonwindowed controls

VCL windowed controls


Visual Component Library components

See also	Properties	Methods

Components are the building blocks of Delphi applications. You build an application by adding components to forms and using the properties, methods, and events of the components.

The properties, methods, and events that all components have in common are inherited from an abstract component type called TComponent. You need to understand the internal details of TComponent only if you are writing a component based on TComponent.

The following is a list of all components in the VCL:

TApplication	TDDEServerItem	TPanel

TAutoIncField	TDirectoryListBox	TPopupMenu

TBatchMove	TDrawGrid	TPrintDialog

TBCDField	TDriveComboBox	TPrinterSetupDialog

TBevel	TEdit	TProgressBar

TBitBtn	TField	TQuery

TBlobField	TFileListBox	TRadioButton

TBooleanField	TFilterComboBox	TRadioGroup

TButton	TFindDialog	TReplaceDialog

TBytesField	TFloatField	TReport

TCheckBox	TFontDialog	TRichEdit

TColorDialog	TForm	TSaveDialog

TComboBox	TGraphicField	TScreen

TCurrencyField	TGroupBox	TScrollBar

TDatabase	THeader	TScrollBox

TDataSource	THeaderControl	TSession

TDateField	THotKey	TShape

TDateTimeField	TImage	TSmallIntField

TDBCheckBox	TImageList	TSpeedButton

TDBComboBox	TIntegerField	TStatusBar

TDBCtrlGrid	TLabel	TStoredProc

TDBEdit	TListBox	TStringField

TDBGrid	TListView	TStrringGrid

TDBImage	TMainMenu	TTabbedNotebook

TDBListBox	TMaskEdit	TTabControl

TDBLookupCombo	TMediaPlayer	TTable

TDBLookupComboBox	TMemo	TTabSet

TDBLookupList	TMemoField	TTabSheet

TDBLookupListBox	TMenuItem	TTimeField

TDBMemo	TNotebook	TTable

TDBNavigator	TOleContainer	TTimer

TDBRadioGroup	TOpenDialog	TTrackBar

TDBText	TOutline	TTreeView

TDDEClientConv	TOutline	TUpdateSQL

TDDEClientItem	TPageControl	TUpDown

TDDEServerConv	TPaintBox	TVarBytesField

TWordField

Most components are available from the Component palette. You will not find the following components on the Component palette, however:

TApplication	TDateTimeField	TScreen

TBCDField	TField	TSmallIntField

TBlobField	TFloatField	TStringField

TBooleanField	TGraphicField	TTimeField

TBytesField	TIntegerField	TVarBytesField

TCurrencyField	TMemoField	TWordField

TDateField	TMenuItem


Properties

The TComponent component introduces the following properties that all components inherit:

 Run-time only

ComponentCount	Components	Owner

ComponentIndex	Name	Tag


Methods

In addition to the methods components inherit from the TObject object, the TComponent component introduces the following:

DestroyComponents	FreeNotification	InsertComponent

Destroying	GetParentComponent	RemoveComponent

FindComponent	HasParent


See also

VCL controls

VCL nonwindowed controls

VCL objects

VCL windowed controls


Visual Component Library controls

See also	Properties	Methods

Controls are visual components: that is, they are components you can see when your application is running. All controls have properties in common that specify the visual attributes of controls, such as Left, Top, Height, Width, Cursor, and Hint.

The properties, methods, and events that all controls have in common are inherited from an abstract component type called TControl. You need to understand the internal details of TControl only if you are writing a component based on TControl.

The following is a list of all controls in the VCL.

TBevel	TDirectoryListBox	TPageControl

TBitBtn	TDrawGrid	TPaintBox

TButton	TDriveComboBox	TPanel

TCheckBox	TEdit	TProgressBar

TComboBox	TFileListBox	TRadioButton

TDBCheckBox	TFilterComboBox	TRadioGroup

TDBComboBox	TForm	TRichEdit

TDBCtrlGrid	TGroupBox	TScrollBar

TDBEdit	THeader	TScrollBox

TDBGrid	THeaderControl	TShape

TDBImage	THotKey	TSpeedButton

TDBListBox	TImage	TStatusBar

TDBLookupCombo	TLabel	TStringGrid

TDBLookupComboBox	TListBox	TTabbedNotebook

TDBLookupList	TListView	TTabControl

TDBLookupListBox	TMaskEdit	TTabSet

TDBMemo	TMediaPlayer	TTabSheet

TDBNavigator	TMemo	TTrackBar

TDBRadioGroup	TNotebook	TTreeView

TDBText	TOleContainer	TUpDown

TOutline


Properties

In addition to the properties controls inherit from the TComponent component, the TControl component introduces the following:

Align	Cursor	Parent

BoundsRect	Left	ShowHint

ClientHeight

ClientOrigin	Enabled	Top

ClientRect	Height	Visible

ClientWidth	Hint	Width


Methods

In addition to the methods controls inherit from the TComponent component, the TControl component introduces the following methods:

BeginDrag	GetTextLen	ScreenToClient

BringToFront	Hide	SendToBack

ClientToScreen	Invalidate	SetBounds

DragDrop	Perform	SetTextBuf

Dragging	Refresh	Show

EndDrag	Repaint	Update

GetTextBuf


See also

VCL components

VCL nonwindowed controls

VCL objects

VCL windowed controls


Visual Component Library nonwindowed controls

See also

Nonwindowed controls are controls that:

Cannot receive focus while your application is running

Cannot contain other controls

Do not have a window handle

The properties, methods, and events that all windowed controls have in common are inherited from an abstract component type called TGraphicControl. You need to understand the internal details of TGraphicControl only if you are writing a component based on TGraphicControl.

The following is a list of all nonwindowed controls in the VCL:

TBevel	TLabel	TShape

TDBText	TPaintBox	TSpeedButton

TImage


See also

VCL components

VCL controls

VCL objects

VCL windowed controls


Visual Component Library windowed controls

See also	Properties	Methods	Events

Windowed controls are controls that:

Can receive focus while your application is running

Can contain other controls

Have a window handle

All windowed controls have properties in common that specify their focus attributes, such as HelpContext, TabStop, and TabOrder. Windowed controls also provide the OnEnter and OnExit events.

The properties, methods, and events that all windowed controls have in common are inherited from an abstract component type called TWinControl. You need to understand the internal details of TWinControl only if you are writing a component based on TWinControl.

The following is a list of all windowed controls in the Visual Component Library:

TBitBtn	TDirectoryListBox	TOutline

TButton	TDrawGrid	TPageControl

TCheckBox	TDriveComboBox	TPanel

TComboBox	TEdit	TProgressBar

TDBCheckBox	TFileListBox	TRadioButton

TDBComboBox	TFilterComboBox	TRadioGroup

TDBCtrlGrid	TForm	TRichEdit

TDBEdit	TGroupBox	TScrollBar

TDBGrid	THeader	TScrollBox

TDBImage	THeaderControl	TStatusBar

TDBListBox	THotKey	TStringGrid

TDBLookupCombo	TListBox	TTabbedNotebook

TDBLookupComboBox	TListView	TTabControl

TDBLookupList	TMaskEdit	TTabSet

TDBLookupListBox	TMediaPlayer	TTabSheet

TDBMemo	TMemo	TTrackBar

TDBNavigator	TNotebook	TTreeView

TDBRadioGroup	TOleContainer	TUpDown


Properties

In addition to the properties windowed controls inherit from the TControl component, the TWinControl component introduces the following properties:

Brush	Handle	TabOrder

Controls	HelpContext	TabStop

ControlCount	Showing


Methods

In addition to the methods windowed controls inherit from the TControl component, the TWinControl component introduces the following methods:

Broadcast	Focused	Realign

CanFocus	GetTabOrderList	Repaint

ContainsControl	HandleAllocated	ScaleBy

ControlAtPos	HandleNeeded	ScrollBy

Create	InsertControl	SetBounds

Destroy	Invalidate	SetFocus

DisableAlign	RemoveControl	Update

EnableAlign


Events

The TWinControl component does not introduce any events


See also

VCL components

VCL controls

VCL objects

VCL nonwindowed controls


About the Run-Time Library

About the Run-Time Library describes the various elements that make up the Delphi Run-Time Library (RTL). The RTL contains

The routines included in the Delphi's System, SysUtils, and Math units

The variables and constants used with these routines and their data types

The exception objects the RTL uses to report RTL errors back to your application

The applications you build with Delphi call RTL procedures and functions to perform a variety of fundamental programming tasks, from memory management to arithmetic calculations. As for the RTL exception objects, you use them if you want to define your own exception handlers to handle RTL exceptions, instead of letting the default RTL error message be displayed by your application.

The procedures and functions in the RTL should not be confused with the Visual Component Library procedures and functions. In contrast to the object-oriented VCL routines, RTL routines are defined in the System and SysUtils files buried deep in the Delphi system. RTL routines provide basic, low-level functionality required by virtually every Delphi program you write, which is why the System unit file is automatically linked into all Delphi programs.

Note:	The Run-Time Library focuses exclusively on the RTL and does not document any of the base elements of the Object Pascal language. For definitions of these elements and explanations of how to use them, see the Object Pascal Language Guide included in the Delphi documentation set, or search online Help.


About the Visual Component Library

About the Visual Component Library describes the objects and components in the Delphi 2.0 Visual Component Library (VCL). Part I also documents the properties, methods, and events associated with each VCL object or component, as well property and method types.

The complete list of VCL elements documented in Part I is as follows:

VCL objects and components, including both visual and nonvisual objects, windowed and nonwindowed controls, and VCL exception objects

Attributes of these objects and components, including properties, methods, and events

The types associated with all the VCL objects and components and their attributes

VCL procedures and functions--that is, routines that are used with VCL objects but that are not methods of any object

Note:	The base classes that are the shared ancestors of every object and component in the VCL are not documented in the VCL documentation. Because you use these base objects--including TObject, TPersistent, TComponent, TControl , TWinControl, and TGraphicControl--to create your own custom components, they are documented in the Component Writer's Guide. This book documents only those objects and components that

Can be used as components in their own right, rather than as base classes for objects you derive

Have an access control level of either public or published

For a discussion of Delphi's the four access control levels, including public and published, and how they specify the code that can access the parts of an object, see the section, "Controlling access," in Chapter 2 of the Component Writer's Guide.


Introduction To VCL
Introduction to Visual Component Library

The Visual Component Library (VCL) is Delphi's framework of prebuilt objects and components. Objects and components are the heart of the Delphi 2.0 programming environment, and the VCL is where all of Delphi's objects and components--and the properties, methods, and events associated with them--are collected.

You can use the various elements defined in the VCL to build Delphi applications. Or you can use the objects and components in the VCL to derive your own custom components.


The VCL object hierarchy

When you use the VCL, it's helpful to be familiar with the VCL object hierarchy, the tree-like structure of ancestor-descendent relationships between objects.

The ancestor-descendent relationships that make up the object hierarchy explain a lot about the basic identity and purpose of each component. In Delphi, components inherit all the features of their ancestors. Each generation of descendent objects inherits everything that its ancestors contain, and then adds its own new properties, methods, and events, or modifies the ones it inherits. Thus if you know the base object or component that a component is derived from, you already know quite a bit about how that component behaves.

The figure below illustrates the core of the VCL object hierarchy, the six critical classes from which all the objects and components in the VCL descend. The entry for each VCL object and component documented in Part I indicates which of these six core classes the object descends from, and whether it descends directly or indirectly.

Note:	The figure presents only these six core classes and omits their other descendents. You can see a detailed outline of the whole object hierarchy for any particular project by opening the Object Browser. To access the Object Browser, create and compile a project, and then choose Browser from the View menu.

TObject and TPersistent

As the figure shows, TObject is the base class from which everything in the VCL descends. All components and controls are also objects because TObject is the ultimate ancestor of every object, component, and control in the VCL.

TObject provides some methods that every object in the VCL inherits--in particular, the Create and Free methods that are responsible for allocating and deallocating memory for all object instances. Apart from these methods and a few others that provide information about an object's type, class name, and ancestors, you won't generally use TObject directly, unless you need to create a noncomponent object type. For a complete list of the TObject's methods and of the objects that descend directly TObject, see online Help.

Descending directly from TObject is TPersistent, an abstract class whose special contribution to its descendents is the ability to read and write properties to and from a stream, a file-like location in memory. For a list of TPersistent's attributes and the objects that descend directly from it, use the Help Index to search for online information about TPersistent.

TComponent

TComponent, which descends directly from TPersistent, is the common ancestor of every component in the VCL. TComponent defines the most basic behavior that all components have, such as the ability to appear on the Component palette and the ability to operate in the Forms Designer and to own other components. For a complete list TComponent's attributes and direct descendents, see online Help.

Although TComponent is the default ancestor of every component in the VCL, the only components you'll create directly from TComponent are nonvisual components such as timers and data source components. This is because all visual components descend from the next component down in the hierarchy, TControl. A control is a component that's visible at run time. Most of the components you'll use or create will probably be various kinds of visual controls. TControl defines the most basic properties, methods, and events that all controls have. For a complete list of these and the objects that descend from TControl, see online Help.

TWinControl and TGraphicControl

Finally, at the bottom of the core object hierarchy shown in the figure, are the two direct descendents of TControl--TWinControl and TGraphicControl. VCL users should be familiar with the important differences between these two object classes.

As its name implies, TWinControl is the ancestor of all windowed controls, including the standard Windows controls, such as edit boxes, list boxes, and buttons. Windowed controls have three main characteristics: they can receive input focus while your application is running; they have a window handle, defined in the Handle property that all windowed controls inherit from TWinControl; and they can visually contain other controls. Although a large family of commonly used controls descends directly from TWinControl, TWinControl itself is the starting point for any component that users will interact with in your application. TWinControl introduces the majority of properties, methods, and events that all controls inherit.

In contrast to TWinControl, the descendents of TGraphicControl don't have the Handle property and therefore don't have a window handle. They can't receive input focus or contain other controls. The advantage of these nonwindowed controls is that because they don't have window handles, they don't use up Windows resources. To save system resources and make your application run faster, it's a good idea to use TGraphicControl or its descendents as a starting point for any component that end-users don't need to interact with.

Note:	The six core object classes described in this section are not documented in this version of the Delphi Library Reference. For more information about TObject, TPersistent, TComponent, TControl, TWinControl, or TGraphicControl, see the Component Writer's Guide, or use the Help Index to search for online information about the object class you're interested in.


What's new in the VCL

Delphi 2.0 includes new components for the new Windows 95 common controls, as well as new and modified controls for database applications. There are also some new exception objects.

New Windows 95 controls

The Delphi 2.0 VCL introduces 12 new components that encapsulate the Windows 95 common controls. These new Windows 95 user interface components are:

n	TTabControl, which provides tab sets for containing controls.

n	TPageControl, which is used to make multiple-page dialog boxes.

n	TTreeView, for displaying hierarchical lists of items, such as database tables and fields or the names of directories and files.

n	TListView, for displaying lists of items in different formats--for example, in columns or in small or large icons.

n	TImageList, which provides containers for efficient management of large sets of images.

n	THeaderControl, which provides moveable sections that act as column headers, similar to the Delphi 1.0 THeader component.

n	TRichEdit, which provides Rich Text Format (RTF) memo control.

n	TStatusBar, for status bars that post the status of an action at the bottom of the screen.

n	TTrackBar, for slider and tick-mark controls.

n	TProgressBar, for progress bars that track the progress of a procedure.

n	TUpDown, which provides up and down arrow buttons to increment and decrement values.

n	THotKey, which attaches a hot key to any component.

New and modified database components

The Delphi 2.0 VCL includes three new database application components:

n	TDBCtrlGrid, for customizing the display of data in panels.

n	TDBLookupComboBox, a data-aware combo box component that looks up a value in a lookup table and displays it. TDBLookupComboBox replaces the Delphi 1.0 component TDBLookupCombo.

n	TDBLookupListBox, a data-aware list box component that looks up a value in a lookup table and displays it. TDBLookupListBox is the new version of the Delphi 1.0 component TDBLookupList.

For more information about any of these new components, see the entry for it in Part I of this manual or in online Help.

In addition, the database grid component, TDBGrid, now allows you to specify display properties on a column-by-column basis, independent of the properties of the underlying field. TDBGrid now supports data cell color, width, field name, and title text-column properties.

For details about TDBGrid, see the entry for it in this part of the Delphi Library Reference. Background information about using this important control is available online through the topic "Changes to TDBGrid."

New exception objects

The new VCL includes several additional exception objects, including

n	EBitsError

n	EOLEError

n	EThread

n	ETreeViewError


How to read the entries in the VCL
How to read the entries in the Visual Component Libaray

The entries in this part are organized to give you quick access to the facts you need in order to use objects, components, properties, methods, events, and types defined in the VCL. The following explains the format of the various entries you'll find in Part I.

Component and object entries

An object is a data type that wraps up code and data all in one bundle. Objects in the VCL are often just base classes that serve as ancestors to families of components, providing many of the properties, methods, and events inherited by their descendent objects. Some objects are used in their own right at run-time to perform tasks nonvisually, behind the scenes. TPrinterObject, for instance, encapsulates the printer interface for Windows.

There are very few objects in the VCL that are not also components. A component is simply an object with additional properties, methods, and events that makes it suitable for specialized purposes. Components that descend from TControl are controls--that is, components that are visible at run-time. Some controls are windowed, meaning that they can receive input focus, and some are nonwindowed, meaning that while they are visible, they can't receive input focus. All windowed controls descend from TWinControl, and all nonwindowed controls descend from TGraphicControl.

At the top-right corner of each object or component entry, the unit file in which the object or component is defined is listed. If the component appears on the Component palette, the icon for it is shown in the margin at the beginning of the text description.

The text description explains how you use the component and discusses its important characteristics and features, including which of the six core object classes it descends from, and how you use its properties, methods, and events. The entry for each object or component ends with charts listing the properties, methods, and events that belong to it.

Property, methods, and event entries

Properties are attributes of an object or component that determine how it is initially displayed (design-time properties) and how it functions in the running application (run-time properties). Methods are procedures and functions that are built into an object or component. Events are pieces of code that specify how an object or component should respond to some occurrence, such as user interaction with your application.

Each property, method, and event entry begin with the head "Applies to," which presents a list of the objects and components to which that property, method, or event may belong. No unit file is listed at the top-right corner of a property, method or event: because these attributes usually apply to multiple objects and components, they are not declared in any single unit file.

Next, the formal declaration for the property, method, or event is listed. This is followed by a description of what the property, method, or event does or specifies. The description includes specific information about values set or returned and about related properties, methods, or events.

When a property, method, or event is used differently by different groups of objects and components, the entry is divided into sections. Each section provides a separate declaration and a description of how that group of objects uses the property, method, or event. For instance, the entry for the Prepare method is divided into two sections that document the use of this method "For stored procedures" and "For queries."

Next, a formal example illustrates how the property, method, or event is used.

When appropriate, these entries end with formal cross-references to related entries listed under the head "See also."

Exception object entries

Exception objects are used by VCL components to report errors conditions back to your application.

The unit file in which the exception object is defined is listed at the top-right corner of the entry.

Each entry begins with the declaration for the exception object.

This is followed by a brief description of when and why the exception is raised. In some cases, an informal example illustrates the kind of code that can cause this particular error.

Function and procedure entries

Functions and procedures are routines--modular pieces of code that perform some specific task. The difference between a function and a procedure is that a function returns a value, and a procedure doesn't.

The unit file in which the function or procedure entry is defined is listed at the top-right corner of the entry.

Each entry begins with the declaration for the function or procedure.

This is followed by a description of what the function or procedure does and when you use it. The description includes details about the parameters for the routine and the values returned, if any.

A formal example illustrates the use of the function or procedure.

The entry ends with cross-references to any related routines, listed under the heading "See also."

Type entries

A type in the VCL defines the possible range of values for a property or a method.

The unit file in which the type entry is defined is listed at the top-right corner of the entry.

Each entry begins with the declaration for the type.

This is followed by a descriptive definition explaining what the type is used for, the set of values it defines or can be, and so on.


Introducton to the Run-Time Library
Introduction to the Run-Time Library

The Delphi 2.0 Run-Time Library (RTL) is a fundamental part of Delphi. The procedures and functions in the RTL provide core features required by most Delphi programs.

In addition to procedures and functions, the RTL contains all the types, variables, constants, typed constants, and exception objects used with the various RTL routines. Part I of the Delphi Library Reference presents detailed information about all of these RTL elements.


The RTL units

All the elements in the RTL are defined in the System and SysUtils units and the new Math unit.

The System unit, which includes many low-level routines written in assembly language, is automatically linked into every Delphi program. As a group, the System unit routines provide the minimum set of capabilities that must be available to every Delphi application.

The SysUtils unit contains enhanced versions of many of the System unit routines, as well as additions that Pascal programmers have found useful. Although the SysUtils unit is not automatically linked into Delphi programs, as the System unit is, the routines in SysUtils are often more comprehensive and easier to use. Most Delphi programmers will want to take advantage the SysUtils extensions to the basic RTL found in System.

The new Math file contains high-performance trigonometric, logorithm, statistical, and financial routines that supplement the math routines in the System unit.


Six kinds of RTL routines

 RTL routines are used to perform a wide range of programming tasks. Collectively, these routines fall into six main categories:

 I/O routines

This group includes file-handling routines like BlockRead, FileOpen, and MkDir.

String-handling routines

This category includes string-formatting routines such as UpCase and string-handling routines like StrCopy.

Arithmetic routines

The functions in this category perform integer math, floating-point math, and other arithmetic and advanced math operations.

Date/time routines

Routines in this category include DayOfWeek, EncodeTime, and NowTime.

Type-conversion routines

Routines in this category convert variables from one type to another. Examples include StrToInt and VarAsType.

Memory management routines

This group includes dynamic allocation routines for getting and freeing memory and obtaining the status of available memory. Examples include GetMem, FreeMem, and GetHeapStatus.


Seven kinds of RTL exceptions

The RTL exceptions are defined in the SysUtils unit, and they all descend from a generic exception-object type called Exception.  The Exception  object provides the string for the message that RTL exceptions display by default.

The seven kinds of exceptions raised by the RTL are as follows:

I/O exceptions

Heap exceptions

Integer math exceptions

Floating-point math exceptions

Typecast exceptions

Conversion exceptions

Hardware exceptions


What's new in the RTL

The new RTL reflects many of the changes resulting from the move to a 32-bit environment, including the new flat memory model adopted by Delphi 2.0 and other new features that eliminate limitations set by Windows 3.1.

Here's a summary of what to look for:

New data types

The Delphi 2.0 RTL introduces new  character and string types, and redefines some  old ones. The new RTL also contains a new Variant type and a new Currency type.

Highlights of the changes to data types include the following:

A new 16-bit character type called WideChar to support the use of  Unicode characters frequently used in OLE programming.

The new long string type AnsiString to support strings of nearly unlimited length. (Counted strings with a maximum length of 255 charactres are now supported through ShortString and String[n].)

A new Variant type that allows you to use a variable whose type is not known at compile time or that may change during execution of a program.

A new Currency type, designed to handle large values with great precision.

New routines

The RTL includes  some new memory management routines, as well as a number of routines that support Delphi 2.0's new data types.

The following sets of routines have been added:

Wide-character support routines for working withWideChar types.

Variant support routines for working withVariant types and variant arrays.

New string support routines, including procedures for dealing with long strings and new functions for trimming whitespace from strings.

 New advanced math functions for performing trigonometry and power operations and for making statistical and financial calculations.

Three new memory management functions, including GetMemoryManager and SetMemoryManager for setting your memory management, and GetHeapStatus, which replaces the MemAvail and MaxAvail functions. (MemAvail and MaxAvail  are obsolete, but have been retained in the RTL for backward compatibility.)

Obsolete 16-bit features

Delphi 2.0 omits a number of features that appear in 16-bit versions of Delphi. These include RTL routines for working with segmented memory. With the advent of a flat, 32-bit memory model, segment-offset addressing is no longer relevant.

In addition, exception objects for handling errors that only occur in 16-bit environments have been removed from the RTL.

For a complete list of these obsolete routines and exception objects, see the topic "Obsolete 16-bit features" in online Help.

New exception objects

The new RTL includes eight new exception objects:

EAccessViolation

EControlC

EPrivilege

EStackOverflow

EVariantError

EExternalException

EPropWriteOnly

EPropReadOnly


How to read the entries in the Run-Time Library

The entries in this part are organized to give you quick access to the facts about every part the RTL, whether it's a routine, an exception object, a variable, or a data type. The following explains the format of the various kinds of entries you'll find in the Run-Time Library.

Exception object entries

Exception objects are used by the various RTL routines to report RTL errors back to your application.

The unit file in which all exception objects are defined, SysUtils, is listed at the top-right  corner of the entry.

Each entry begins with the declaration for the exception object.

This is followed by a brief description of when and why the exception object is raised. If the object has any properties, methods, or events, these are listed.  In some cases, an informal example illustrates the kind of code that can cause this particular error.

Function and procedure entries

Functions and procedures are routines--modular pieces of code that perform some specific task. The difference between a function and a procedure is that a function returns a value, and a procedure doesn't.

The unit file in which the function or procedure entry is defined is listed at the top-right corner of the entry.

Each entry begins with the declaration for the function or procedure.

This is followed by a description of what the function or procedure does and when you use it. The description includes details about the parameters for the routine and the values returned, if any.

A formal example illustrates the use of the function or procedure.

The entry ends with cross-references to any related routines, listed under the heading "See also."

Type, variable, constant, and typed constant entries

A type defines the possible range of values of a set of data and the operations that can be performed on those values. A variable is a named storage location containing a certain type of data that can be modified during program execution. A constant is a variable containing a value that can't change. A typed constant is a preinitialized variable--that is, a constant that contains a variable type and that can therefore change as your application runs.

The unit file in which the type, variable, constant, or typed constant entry is defined is listed at the top-right corner of the entry.

Each entry begins with the declaration for the type, variable, constant, or typed constant

This is followed by a descriptive definition explaining what the element is used for, the set of values it defines or can be, and so on.


TBits object

Properties	Methods

Unit

Classes

Description

The TBits class is a direct descendant of TObject. It is used to store an "array" of Boolean values. You can do something similar by using Object Pascal sets or the bitwise "and" and "or" operators against an integer type variable, but that's limited to 32 Boolean values (the maximum number of entries in a set type and bits in the Integer and Longint types). The TBits class can store as many Boolean values as can fit in available memory, automatically expanding its storage space as needed to store additional values.


Properties

 Run-time only          [image] Key properties

Bits	Size


Methods

 Key methods

OpenBit


OpenBit method

Applies to

TBits object

Declaration

function OpenBit: Integer;

Description

The OpenBit method returns the index of the first False value.


Bits property

See also

Applies to

TBits object

Declaration

property Bits[Index: Integer]: Boolean;

Description

The Bits default array property returns or sets the value stored at the specified index. If Index isn't in the range 0..Size  1, an EBitsError exception is raised.


See also

EBitsError object


TChangeLink object

Properties	Methods	Events

Unit

Controls

Description

The TChangeLink object is a direct descendant of TObject. The TImageList component uses it to notify other objects when changes are made to the image list. For example, TTreeView uses it to update the tree view control whenever you make changes to the image list used to hold the images the tree view uses.


Properties

 Run-time only          [image] Key properties

Sender


Methods

 Key methods

Change


Events

 Key events

OnChange


Change method

See also

Applies to

TChangeLink object

Declaration

procedure Change;

Description

The Change method calls the OnChange event handler, if one has been defined.


See also

OnChange event


Sender property

See also

Applies to

TChangeLink object

Declaration

property Sender: TCustomImageList;

Description

Runtime only. The Sender property specifies the associated image list component. TImageList automatically sets this  property when you call its RegisterChanges method.


See also

RegisterChanges method


TConversion object

Methods	Events

Unit

ComCtrls

Description

The TConversion object is a class that allows the TRichEdit component to handle the conversion of a document to a format TRichEdit understands. TRichEdit handles plain ANSI text files and richtext format (.RTF) files. If you wanted to convert text from another format, you'd derive a class from TConversion and call TRichEdit's RegisterConversionFormat method; TRichEdit would automatically use that class when it loaded a file with the specified extension.


Methods

 Key methods

ConvertReadStream	ConvertWriteStream


Events

 Key events

OnChange


ConvertReadStream function

Applies to

TConversion object

Declaration

function ConvertReadStream (Stream: TStream; Buffer: PChar; BufSize: Integer): Integer

Description

The ConvertReadStream method reads BufSize bytes from the  Stream stream into the memory buffer pointed to by Buffer. To convert text from some other format, override this method in a descendant class and convert the format to RTF.


ConvertWriteStream function

Applies to

TConversion object

Declaration

function ConvertWriteStream (Stream: TStream; Buffer: PChar; BufSize: Integer): Integer;

Description

The ConvertWriteStream method writes BufSize bytes to the  Stream stream from the memory buffer pointed to by Buffer. To write text to a format other than RTF, override this method in a descendant class and convert the RTF text to the other  format.


TConversionClass type

See also

Unit

ComCtrls

Applies to

TRichEdit component

Declaration

type

  TConversionClass = class of TConversion;

Description

TConversionClass is a class reference to TConversion. It's used in TRichEdit's RegisterConversionFormat method and DefaultConverter property.


See also

DefaultConverter property

RegisterConversionFormat method


TCreateInfo type

See also

Unit

OleCtnrs

Applies to

TOleContainer component

Declaration

type

  TCreateInfo = record

    CreateType: TCreateType;

    ShowAsIcon: Boolean;

    IconMetaPict: HGlobal;

    ClassID: TCLSID;

    FileName: string;

    DataObject: IDataObject;

  end;

Description

The TCreateInfo type is a record used by TOleContainer's  CreateObjectFromInfo method. TCreateInfo's fields are  described in the following table:

Fields

CreateType	A TCreateType value that describes the source of the object. See TCreateType for details.

ShowAsIcon	Indicates whether the object is shown as an icon (True) or displayed as it would be in the server application (False).

IconMetaPict	Specifies a global memory handle to a metafile picture (TMetaFilePict) to display in place of the OLE object's default icon. IconMetaPict is optional; if you set it to 0, the object's default icon will be used (when ShowAsIcon is True).

ClassID	The class identifier of the OLE object you want to create. ClassID is only used when CreateType is ctNewObject. You can use the ProgIDToClassID function to get the class identifier for an OLE object's class name (or programmatic identifier).

FileName	The name of a file to link or embed as an OLE object. FileName is only used when CreateType is ctFromFile or ctLinkToFile.

DataObject	An OLE data transfer object. DataObject is only used when CreateType is ctFromData or ctLinkFromData.


See also

CreateObjectFromInfo method


TCreateType type

See also

Unit

OleCtnrs

Applies to

TOleContainer component

Declaration

type

  TCreateType = (ctNewObject, ctFromFile, ctLinkToFile,

    ctFromData, ctLinkFromData);

Description

TheTCreateType enumerated type defines the possible values for TCreateInfo's CreateType field for (TOleContainer's  CreateObjectFromInfo method), as defined as follows:

Values

ctNewObject	Creates an embedded OLE object given its class identifier (TCreateInfo.ClassID)

ctFromFile	Creates an embedded OLE object from the contents of the given file (TCreateInfo.FileName).

ctLinkToFile	Creates a linked OLE object from the contents of the given file (TCreateInfo.FileName)

ctFromData	Creates an embedded OLE object from the given data transfer object (TCreateInfo.DataObject)

ctLinkFromData	Creates a linked OLE object from the given data transfer object (TCreateInfo.DataObject)


See also

TCreateInfo type


TraceFlags property

Applies to

TDatabase, TSession components

Declaration

type

  TTraceFlag = (tfQPrepare, tfQExecute, tfError, tfStmt, tfConnect, tfTransact,
  tfBlob, tfMisc, tfVendor);

  TTraceFlags = set of TTraceFlag;

property TraceFlags: TTraceFlag;

Description

Runtime only. The TraceFlags property controls which events  are tracked in the SQL Monitor. TTraceFlags defines the possible values for the TraceFlags property:

Values

tfQPrepare	Prepared statements to be sent to the server.

tfQExecute	Statements to be executed by the server. Note that a single statement may be prepared once and executed several times with different parameter bindings.

tfError	Error messages returned by the server. The error message may include an error code, depending on the server.

tfStmt	Each operation performed such as ALLOCATE, PREPARE, EXECUTE, and FETCH.

tfConnect	Operations associated with connecting and disconnecting to databases, including allocation of connection handles, freeing connection handles, if required by server.

tfTransact	Transaction operations such as BEGIN, COMMIT, and ROLLBACK (ABORT).

tfBlob	Operations on Blob datatypes, including GET BLOB HANDLE, STORE BLOB, and so on.

tfMisc	Operations not covered by other categories.

tfVendor	Actual API function calls to the server. For example, ORLON for Oracle, ISC_ATTACH for InterBase.

Because TTraceFlags is a set type, you can include multiple TTraceFlag values; for example:

TraceFlags := [tfQPrepare..tfStmt];

TDatabase objects, when created, get their initial TraceFlags value from the session that owns them. Setting TraceFlags on a closed database has no effect.

Setting TraceFlags for a session sets TraceFlags for all  TDatabase objects owned by that session.


InTransaction property

See also

Applies to

TDatabase component

Declaration

property InTransaction: Boolean;

Description

Readonly and runtime only. The InTransaction property indicates whether a transaction is active (that is, that StartTransaction has been called).


See also

StartTransaction method


ActiveBuffer method

Applies to

TQuery, TStoredProc, TTable components

Declaration

function ActiveBuffer: PChar;

Description

The ActiveBuffer method returns a pointer to the internal record buffer corresponding to the data set's current record.


FetchAll method

Applies to

TQuery, TStoredProc, TTable components

Declaration

procedure FetchAll;

Description

The FetchAll method, when used with a query against a server database, forces the server to release all intermediate locks and reads the entire result set.


GetCurrentRecord method

See also

Applies to

TQuery, TStoredProc, TTable components

Declaration

function GetCurrentRecord(Buffer: PChar): Boolean;

Description

The GetCurrentRecord method retrieves the current record from the dataset into a memory buffer. Buffer must point to a buffer at least as big as the value of the RecordSize property.


See also

RecordSize property


IsLinkedTo method

Applies to

TQuery, TStoredProc, TTable components

Declaration

function IsLinkedTo(DataSource: TDataSource): Boolean;

Description

The IsLinkedTo method returns True if the dataset is linked to the specified data source, or False otherwise.


DefaultFields property

Applies to

TQuery, TStoredProc, TTable components

Declaration

property DefaultFields: Boolean;

Description

Readonly and runtime only. The DefaultFields property indicates whether the dataset is using the default TField objects or whether you created persistent fields using the fields editor at design time. DefaultFields is True if the field objects are the default ones or False if the field objects are persistent.


RecordSize property

See also

Applies to

TQuery, TStoredProc, TTable components

Declaration

property RecordSize: Word;

Description

Readonly and runtime only. The RecordSize property returns the size in bytes of the physical record buffer. RecordSize is useful when you need to allocate a memory buffer for the GetCurrentRecord method.


See also

GetCurrentRecord method


DefaultDrawColumnCell method

See also

Applies to

TDBGrid component

Declaration

procedure DefaultDrawColumnCell(const Rect: TRect; DataCol: Integer; Column: TColumn; State: TGridDrawState);

Description

The DefaultDrawColumnCell method provides default drawing of the data in a cell of a TDBGrid component. You can call it from an OnDrawColumnCell event handler when the default behavior is sufficient.


See also

OnDrawColumnCell event


TDragObject object

Methods

Unit

Controls

Description

The TDragObject object is a direct descendant of TObject. It is used internally to manage draganddrop and is exposed in OnStartDrag events to let you customize draganddrop behavior and appearance using objects inherited from TDragObject (andTDragControlObject).


Methods

 Key methods

GetName	Instance

HideDragImage	ShowDragImage


Instance method

Applies to

TDragObject object

Declaration

function Instance: THandle;

Description

The Instance method returns the instance handle of the EXE or DLL that created the drag object.


GetName method

Applies to

TDragObject object

Declaration

function GetName: string;

Description

The GetName method returns a name identifying the draganddrop operation. It returns the name of the drag class by default, but you could override it in a descendant class.


HideDragImage method for TDragObject
HideDragImage method

Applies to

TDragObject object

Declaration

procedure HideDragImage;

Description

The HideDragImage method hides the image used in the drag cursor. This is useful when you need to scroll the contents of a control while dragging over it.


ShowDragImage method for TDragObject
ShowDragImage method

Applies to

TDragObject object

Declaration

procedure ShowDragImage;

Description

The HideDragImage method shows the image used in the drag cursor. This is useful when you need to scroll the contents of a control while dragging over it.


TDragControlObject object

Methods

Unit

Controls

The TDragControlObject object is an indirect descendant of TObject. It is used internally to manage draganddrop and is exposed in OnStartDrag events to let you customize draganddrop behavior and appearance using objects inherited from TDragControlObject (or TDragObject).


Methods

 Key methods

Instance	GetDragCursor	GetName

Finished	GetDragImages


GetDragImages method

Applies to

TDragControlObject object

Declaration

function GetDragImages: TCustomImageList;

Description

The GetDragImages method returns the control's image list containing the image to be displayed while dragging. The image list normally contains only one image, and the VCL automatically creates and maintains the image list.


GetDragCursor method

See also

Applies to

TDragControlObject object

Declaration

function GetDragCursor(Accepted: Boolean; X, Y: Integer): TCursor;

Description

The GetDragCursor method returns the drag cursor that should be displayed in the current position. If the control accepts the drag (in an OnDragOver event handler), the drag object sets the drag cursor to the control's DragCursor property; otherwise, it displays the crNoDrop cursor.


See also

DragCursor property

OnDragOver event


Finished method

See also

Applies to

TDragControlObject object

Declaration

procedure Finished(Target: TObject; X, Y: Integer; Accepted: Boolean);

Description

The Finished method ends draganddrop operations, including calling the OnEndDrag event handler.


See also

OnEndDrag event


TLockType type

See also

Unit

DBTables

Applies to

TTable component

Declaration

type

  TLockType = (ltReadLock, ltWriteLock);

Description

TLockType defines the possible values of the parameters to TTable's LockTable and UnlockTable methods, as defined in the following table:

Values

ltReadLock	Other processes are prevented from placing write locks on the table. For dBASE and SQL tables, ltReadLock is equivalent to ltWriteLock.

ltWriteLock	Other processes are prevented from placing any locks on the table.


See also

LockTable method

UnlockTable method


TObjectState type

See also

Unit

OleCtnrs

Applies to

TOleContainer component

Declaration

type

  TObjectState = (osEmpty, osLoaded, osRunning, osOpen,
  osInPlaceActive, osUIActive);

Description

The TObjectState enumerated type defines the possible values for TOleContainer's State property, as defined in the table that follows.

Values

osEmpty	There is no OLE object in the container.

osLoaded	There is an OLE object in the container, but its server application isn't currently running.

osRunning	The OLE object's server is running.

osOpen	The OLE object is open in a separate window.

osInPlaceActive	The OLE object is activated inplace, but  hasn't yet merged its menus or toolbars. This is an intermediate state; the State property will shift to osUIActive as soon as the menus and toolbars have been merged.

osUIActive	The OLE object is activated inplace and menus and toolbars have been merged


See also

State property


TOleContainer component

Properties	Methods	Events

Unit

OleCtnrs

The TOleContainer component lets you embed or link OLE objects in your Delphi 2.0 application. TOleContainer handles many of the complexities of OLE 2.0 for you. Letting the user choose an OLE object to insert is as simple as calling the InsertObjectDialog method. Call the CreateObject or CreateObjectFromFile methods to create an embedded OLE object; use the CreateLinkToFile method to create a linked OLE object.

TOleContainer automatically handles menu merging  the process of combining the container form's menu with that of an inplace activated OLE object's server application. The menu items' GroupIndex property settings control how menus are merged. Those main menu items with GroupIndex values of 0, 2, and 4 remain; TOleContainer merges the server application's menus and replaces the main menu items with GroupIndex values of 1, 3, and 5 (if they exist). So, for example, if you had an MDI form with a traditional main menu, you'd set the menus' GroupIndex properties as follows:

Menu	Group Index Setting

File	0

Edit	1

Object	2

Window	4

Help	5

The File, Object, and Window menus would remain but the Edit and Help menus would be replaced by those of the server application.

Note that there's no menu with a GroupIndex of 3; that's not a problem.

OLE objects that are activated inplace add their servers' toolbars directly into your application's window. Normally, any panels you use for toolbars are replaced by the OLE object's server's toolbars. You can prevent this by setting a panel's

Locked property to True. When Locked is True, TOleContainer won't remove the panel to make room for the server's toolbars.

Note that your application's toolbars must be in panels that aligned to a side of your form (that is, their Align property set to alTop, alBottom, alLeft, or alRight).

If you're using a TOleContainer in an SDI application (your main form's FormStyle property is fsNormal rather than fsMDIForm), you should place the TOleContainer component inside a panel whose Align property is set to alClient. TOleContainer replaces an SDI form's toolbars as described above, and using a panel automatically adjusts the amount of space available to the OLE container.


Properties

 Run-time only          [image] Key properties

Align	Enabled	ParentCtl3D

AllowInPlace	Iconic	ParentShowHint

AutoActivate	Linked	PopupMenu

AutoVerbMenu	Modified	PrimaryVerb

BorderStyle	NewInserted	ShowHint

CanPaste	ObjectVerbs	SizeMode

Caption	OleClassName	SourceDoc

Color	OleObject	State

CopyOnSave	OleObjectInterface	StorageInterface

Ctl3D	OldStreamFormat	TabOrder

DragCursor	ParentColor	TabStop

DragMode	Visible


Methods

 Key methods

ChangeIconDialog	DestroyObject	Paste

Close	DoVerb	PasteSpecialDialog

Copy	GetIconMetaPict	Run

CreateLinkToFile	InsertObjectDialog	SaveToFile

CreateObject	LoadFromFile	SaveToStream

CreateObjectFromFile	LoadFromStream	UpdateObject

CreateObjectFromInfo	ObjectPropertiesDialog	UpdateVerbs


Events

 Key events

OnActivate	OnExit	OnKeyUp

OnDeactivate	OnMouseDown	OnObjectMove

OnDragDrop	OnMouseMove	OnResize

OnDragOver	OnMouseUp	OnStartDrag

OnEndDrag	OnKeyDown

OnEnter	OnKeyPress


See also

Align property

CreateLinkToFile method

CreateObject method

CreateObjectFromFile method

GroupIndex property

InsertObjectDialog method

Locked property


ChangeIconDialog method

Applies to

TOleContainer component

Declaration

function ChangeIconDialog: Boolean;

Description

Executes the Change Icon OLE dialog box, which lets the user choose a different icon (from .ICO, .DLL, and .EXE files) to use when displaying the OLE object as an icon. An OLE object must already be loaded in the container before calling ChangeIconDialog. ChangeIconDialog returns True if the dialog box was successfully display and the user chose the OK button or False otherwise. You can force the container to show the OLE object as an icon by setting Iconic to True.


Copy method

Applies to

TOleContainer component

Declaration

procedure Copy;

Description

Copies the OLE object to the Windows clipboard. There must be an OLE object in the container before calling Copy.


CreateLinkToFile method

Applies to

TOleContainer component

Declaration

procedure CreateLinkToFile(const FileName: string; Iconic: Boolean);

Description

Creates a linked OLE object from the contents of the given file. Iconic indicates whether the object is shown as an icon (True) or displayed as it would be in the server application (False). If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded.


CreateObject method

Applies to

TOleContainer component

Declaration

procedure CreateObject(const OleClassName: string; Iconic: Boolean);

Description

Creates an embedded OLE object given its class name (also known as programmatic identifier). Iconic indicates whether the object is shown as an icon (True) or displayed as it would be in the server application (False). If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded.


CreateObjectFromFile method

Applies to

TOleContainer component

Declaration

procedure CreateObjectFromFile(const FileName: string; Iconic: Boolean);

Description

Creates an embedded OLE object from the contents of the given file. Iconic indicates whether the object is shown as an icon (True) or displayed as it would be in the server application (False). If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded.


CreateObjectFromInfo method

See also

Applies to

TOleContainer component

Declaration

procedure CreateObjectFromInfo(const CreateInfo: TCreateInfo);

Description

Creates an OLE object based on the specifications in a TCreateInfo record. See TCreateInfo and TCreateType for details on TCreateInfo's fields. If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded. The CreateLinkToFile, CreateObject, and CreateObjectFromFile methods are oneline calls for the most common types of OLE objects, instead of filling out the TCreateInfo record.


See also

CreateLinkToFile method

CreateObject method

CreateObjectFromFile method

TCreateInfo type

TCreateType type


DestroyObject method

Applies to

TOleContainer component

Declaration

procedure DestroyObject;

Description

Destroys the container's OLE object, discarding any changes the user made to it.


DoVerb method

See also

Applies to

TOleContainer component

Declaration

procedure DoVerb(Verb: Integer);

Description

Requests the OLE object to perform some action. OLE defines several verbs, such as ovShow (to display the OLE object) and ovPrimary (the default action, usually to activate the OLE object). OLE objects can define their own custom verbs. You can use the ObjectVerbs property to get a list of those custom verbs.


See also

ObjectVerbs property


GetIconMetaPict method

Applies to

TOleContainer component

Declaration

function GetIconMetaPict: HGlobal;

Description

Returns the global memory handle of a metafile containing the OLE object's icon. There must be an OLE object in the container before calling GetIconMetaPict. Use the DestroyMetaPict procedure to destroy the handle.


InsertObjectDialog method

Applies to

TOleContainer component

Declaration

function InsertObjectDialog: Boolean;

Description

Executes the Insert Object OLE dialog box, which lets the user create an OLE object. The OLE object can be embedded or linked. InsertObjectDialog returns True if the dialog box was successfully display and the user chose the OK button or False otherwise. If the user chose OK and there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded.


ObjectPropertiesDialog method

Applies to

TOleContainer component

Declaration

function ObjectPropertiesDialog: Boolean;

Description

Displays the OLE Object Properties property sheet, which lets the user see and edit various properties of the OLE object. Any changes the user makes in the property sheet is automatically made to the OLE object. An OLE object must already be in the container before calling ObjectPropertiesDialog. ObjectPropertiesDialog returns True if the property sheet was successfully display and the user chose the OK button or False otherwise.


Paste method

Applies to

TOleContainer component

Declaration

procedure Paste;

Description

Pastes the contents of the Windows clipboard as an embedded object. If there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded.


PasteSpecialDialog method

Applies to

TOleContainer component

Declaration

function PasteSpecialDialog: Boolean;

Description

Executes the Paste Special OLE dialog to give the user more control over how the contents of the Windows clipboard are pasted into the container. The Paste Special dialog box lets the user select the format of the data, whether it should be embedded or linked, and whether to display the OLE object should be displayed as an icon (and if so, to choose a different icon). PasteSpecialDialog returns True if the dialog box was successfully display and the user chose the OK button or False otherwise. If the user chose the OK button and there's already an OLE object in the container, it's destroyed and any changes the user made to it are discarded.


Run method for TOleContainer
Run method

Applies to

TOleContainer component

Declaration

procedure Run;

Description

Runs the OLE object's server application, but doesn't open or active the OLE object iself. Once the server application is running, opening and activating the OLE object happens much more quickly. An OLE object must already be loaded in the container before calling Run.


UpdateObject for TOleContainer
UpdateObject method

Applies to

TOleContainer component

Declaration

procedure UpdateObject;

Description

Updates the OLE object. Linked OLE objects and embedded objects that contain linked OLE objects get outofdate when the source of the link is updated. UpdateObject rereads the source to ensure that the OLE object has current data. If there is no OLE object loaded into the container, UpdateObject has no effect.


UpdateVerbs method

See also

Applies to

TOleContainer component

Declaration

procedure UpdateVerbs;

Description

Refreshes the list of verbs the OLE object responds to. TOleContainer automatically calls UpdateVerbs when you first access the ObjectVerbs property, but some OLE objects change their verbs as they perform some actions. The Media Clip OLE object, for example, changes its "Play" verb to "Stop" while running. An OLE object must already be loaded in the container before calling UpdateVerbs.


See also

ObjectVerbs property


AllowInPlace property

See also

Applies to

TOleContainer component

Declaration

property AllowInPlace: Boolean;

Description

Determines whether an OLE object can be activated inplace. If AllowInPlace is True and Iconic is False, the OLE object will be activated inplace. Otherwise, it will be activated in a separate window. The default value is True.


See also

Iconic property


AutoActivate property

Applies to

TOleContainer component

Declaration

TAutoActivate = (aaManual, aaGetFocus, aaDoubleClick);

property AutoActivate: TAutoActivate;

Description

The AutoActivate property determines how an object in an OLE container can be activated, as defined in the following table:

Values

aaManual	The user can't activate the object. You can activate the OLE object in code by calling DoVerb(ovShow).

aaGetFocus	The OLE object is activated whenever the OLE container gets the focus (by clicking on it with the mouse or pressing Tab to move the focus to it).

aaDoubleClick	(Default) The OLE object is activated by doubleclicking it or pressing Enter while the container has the focus.


AutoVerbMenu property

See also

Applies to

TOleContainer component

Declaration

property AutoVerbMenu: Boolean;

Description

Determines whether TOleContainer automatically creates a popup menu containing the OLE object's verbs. If AutoVerbMenu is True (the default), TOleContainer replaces any existing PopupMenu property. If AutoVerbMenu is False, no popup menu is automatically created.


See also

PopupMenu property


CanPaste property

Applies to

TOleContainer component

Declaration

property CanPaste: Boolean;

Description

Runtime and readonly. Indicates whether the data in the Windows clipboard is suitable for pasting as an embedded object.


CopyOnSave property

See also

Applies to

TOleContainer component

Declaration

property CopyOnSave: Boolean;

Description

Determines whether the SaveToFile and SaveToStream methods writes a temporary OLE object storage, compressing redundant data and saving space. Set CopyOnSave to False when the container holds very large embedded objects and there might not be enough memory to make the temporary copy. The default value is True.


See also

SaveToFile method

SaveToStream method


Iconic property

Applies to

TOleContainer component

Declaration

property Iconic: Boolean;

Description

Determines how the OLE object is displayed. If Iconic is True, it's displayed as an icon; if False, it's displayed as it would be in the server application.


Linked property

Applies to

TOleContainer component

Declaration

property Linked: Boolean;

Description

Runtime and readonly. Indicates whether the OLE object is linked. If True, the OLE object is linked; if False, it's embedded. An OLE object must already be loaded in the container before accessing the Linked property.


NewInserted property

See also

Applies to

TOleContainer component

Declaration

property NewInserted: Boolean;

Description

Runtime and readonly. Indicates whether the OLE object was newly created (via a call to InsertObjectDialog), rather than pasted in or created as a link to a file. If there is no OLE object loaded into the container, NewInserted returns False. If NewInserted is True after a call to InsertObjectDialog, you can call DoVerb(ovShow) to let the user edit the object.


See also

DoVerb method

InsertObjectDialog method


ObjectVerbs property

Applies to

TOleContainer component

Declaration

property ObjectVerbs: TStrings;

Description

Runtime and readonly. Returns a string list containing the names of the verbs the OLE object supports. The verb names can have embedded ampersand ('&') characters to indicate shortcut keys. An OLE object must already be loaded in the container before accessing the ObjectVerbs property.


OldStreamFormat property

Applies to

TOleContainer component

Declaration

property OldStreamFormat: Boolean;

Description

Determines the format of files and streams saved and loaded. If OldStreamFormat is False (the default), the Delphi 2.0 TOleContainer format is used; if True, the Delphi 1.0 TOLEContainer format is used. The Delphi 2.0 format is preferred, as it contains extra header information that TOleContainer can use to validate a file or stream. This property is provided for backward compatibility with existing files only.


OleClassName property

Applies to

TOleContainer component

Declaration

property OleClassName: string;

Description

Runtime and readonly. Returns the class name of the OLE object. An OLE object must already be loaded in the container before accessing the OleClassName property.


OleObjectInterface property

Applies to

TOleContainer component

Declaration

property OleObjectInterface: IOleObject;

Description

Runtime and readonly. Returns the IOleObject interface for the OLE object, which is useful for lowlevel access to the OLE API. If there is no OLE object loaded into the container, OleObjectInterface returns nil.


PrimaryVerb property

See also

Applies to

TOleContainer component

Declaration

property PrimaryVerb: Integer;

Description

Runtime and readonly. Returns the index of the primary (default) verb for the OLE object. You can use the index in a call to the DoVerb method. [DoVerb(ovPrimary) is the same as DoVerb(PrimaryVerb).] You can also use the index with the ObjectVerbs property to display the name of the primary verb. An OLE object must already be loaded in the container before accessing the OleObject property.


See also

DoVerb method

ObjectVerbs property

OleObject property


SizeMode property

Applies to

TOleContainer component

Declaration

property SizeMode: TSizeMode;

Description

Determines how the OLE object will be sized within the container. See TSizeMode for possible values.


SourceDoc property

Applies to

TOleContainer component

Declaration

property SourceDoc: string;

Description

Runtime and readonly. Returns the name of the source document for a linked OLE object. An OLE object must already be loaded in the container before accessing the SourceDoc property. If the OLE object isn't linked, SourceDoc returns an empty string.


StorageInterface property

Applies to

TOleContainer component

Declaration

property StorageInterface: IStorage;

Description

Runtime and readonly. Returns the IStorage interface for the OLE object, which is useful for lowlevel access to the OLE API. If there is no OLE object loaded into the container, StorageInterface returns nil.


OnObjectMove event

See also

Applies to

TOleContainer component

Declaration

TObjectMoveEvent = procedure(OleContainer: TOleContainer;const Bounds: TRect) of object;

property OnObjectMove: TObjectMoveEvent;

Description

Occurs when the users moves or resizes the OLE object (by moving or sizing the hatched frame around the OLE object). You must handle this event to let the user move or resize the OLE object; you must set the OLE container's BoundsRect to the Bounds parameter of the event handler or the OLE object won't change its location or size. For example:

procedure TMDIChildForm.BobOleContainerObjectMove(OleContainer: TOleContainer;
const Bounds: TRect);

begin

  OleContainer.BoundsRect := Bounds;

end;


See also

BoundsRect property


TSizeMode type

See also

Applies to

TOleContainer component

Declaration

type

  TSizeMode = (smClip, smCenter, smScale, smStretch, smAutoSize);

Description

The TSizeMode enumerated type defines the possible values of TOleContainer's SizeMode property, as defined in the following table:

Values

smClip	(Default)- Displays the OLE object at its normal size, clipping any parts that don't fit within the container.

SmCenter	Displays the OLE object at its normal size, centering it within the container.

SmScale	Scales or shrinks the view of the OLE object to fit within the container, by scaling width and height proportionally.

SmStretch	Scales or shrinks the view of the OLE object to  fill the OLE container, without regard to  preserving the proportions of the OLE object.

SmAutoSize	Same as smClip but also automatically resizes  the container whenever the size of the OLE  object changes.


See also

SizeMode property


Constrained property

Applies to

TQuery component

Declaration

property Constrained: Boolean;

Description

For Local SQL only. The Constrained property, if True, prevents updates and insertions that don't comply with the SELECT statement that produced the result set.


EThread object

See also

Unit

Registry

The EThread exception class is directly derived from Exception. It adds nothing to the functionality inherited from the Exception class, but is provided so you can check for thread-related exceptions in a try..except statement.


See also

TThread object


CurrentSession property

See also

Applies to

TSessionList object

Declaration

property CurrentSession: TSession

Description

Runtime only. The CurrentSession property returns the application's current session. Setting CurrentSession makes the specified session the current one. TSessionList.CurrentSession replaces the Session global variable documented in the printed documentation.


See also

Session variable


LockTable method

See also

Applies to

TTable component

Declaration

procedure LockTable(LockType: TLockType);

Description

The LockTable method locks the table, to prevent other users from being able to place other locks on it. The LockType parameter specifies the type of lock. You can apply more than one lock to a single table. LockTable only works with dBASE and Paradox tables.


See also

UnlockTable method


RenameTable method

Applies to

TTable component

Declaration

procedure RenameTable(const NewTableName: string);

Description

The RenameTable method renames a table, including any  constituent files (for example, Paradox .DB and .MB files).  RenameTable only works with dBASE and Paradox tables.


UnlockTable method

Applies to

TTable component

Declaration

procedure UnlockTable(LockType: TLockType);

Description

The UnlockTable method removes a lock that was applied with the LockTable method. The LockType parameter specifies which type of lock should be removed. UnlockTable only works with dBASE and Paradox tables.


TThread object

Properties	Methods

Unit

Classes

The TThread object is a direct descendant of TObject. It lets you create multiple threads of execution in your Delphi application. Unlike most objects and components in Delphi, TThread can't be used asis. You must derive a new thread class from TThread and override methods to use it. Therefore, both the protected and public methods and properties of TThread are discussed here (unless specified otherwise, methods and properties are public). See the DEMOS/THREADS directory for thread samples.


Properties

 Run-time only          [image] Key properties

FreeOnTerminate	Priority	ThreadID

Handle	Suspended


Methods

 Key methods

Resume	Terminate	WaitFor

Suspend	Execute


DoTerminate method

See also

Applies to

TThread object

Declaration

procedure DoTerminate;

Description

Protected. Synchronizes with the main thread and then calls the OnTerminate event handler, if there is one. DoTerminate is automatically called when the thread terminates. You'd rarely have any need to override this method. Note that DoTerminate is called in the context of the thread object, unlike the OnTerminate event, which is called in the context of the main VCL thread.


See also

OnTerminate event


Suspend method

See also

Applies to

TThread object

Declaration

procedure Suspend;

Description

The Suspend method pauses a running thread. Call Resume to resume execution. Calls to Suspend can be nested; you must call Resume as many times as you called Suspend before the thread will actually be resumed.


See also

Resume method


Synchronize method

Applies to

TThread object

Declaration

procedure Synchronize(Method: TThreadMethod);

Description

Protected. The Synchronize method lets you call a method in your thread object and avoid multithread conflicts with VCL components. (VCL components can only be used from the main VCL thread; Synchronize calls the method you specify from within the main VCL thread so you can freely use properties and call methods of VCL components.)


WaitFor method

See also

Applies to

TThread object

Declaration

function WaitFor: Integer;

Description

The WaitFor method waits for the thread to terminate and then returns the value of the ReturnValue property. WaitFor doesn't return until the thread terminates, so the thread must exit (either by finishing the Execute method or by exiting when the Terminated property is True). Don't call WaitFor in the context of the main VCL thread if your thread uses Synchronize. Doing so will either cause a deadlock, making it appear that your application has hung, or cause an EThread exception to be raised. (Synchronize waits for the main VCL thread to enter the message loop before allowing the method it is trying to synchronize to execute. If the main VCL thread has called WaitFor, it won't enter the message loop and Synchronize will never return. TThread detects that case and will raise an EThread exception in the thread, causing it to terminate and, if not caught in the Execute method, the application will terminate as well. If Synchronize is already waiting on the main VCL thread when WaitFor is called, TThread can't intervene, and your application will deadlock.)


See also

EThread object

Execute method

ReturnValue property

Synchronize method


FreeOnTerminate property

Applies to

TThread object

Declaration

property FreeOnTerminate: Boolean;

Description

Runtime only. The FreeOnTerminate property determines whether the VCL will automatically destroy the thread object when the thread terminates. FreeOnTerminate is False by default, which means you're responsible for destroying the thread object.


Priority property

See also

Applies to

TThread object

Declaration

property Priority: TThreadPriority;

Description

Runtime only. The Priority property represents the thread's scheduling priority. Priority's default is tpNormal; you can adjust the priority up or down as needed. See TThreadPriority type for possible values.


See also

TThreadPriority type


ReturnValue property

Applies to

TThread object

Declaration

property ReturnValue: Integer;

Description

Protected. The ReturnValue property is the thread's equivalent to a function's Result variable. You can use ReturnValue to indicate success or failure to your application or other threads.


Suspended property

Applies to

TThread object

Declaration

property Suspended: Boolean;

Description

Runtime only. The Suspended property indicates whether a thread is suspended. Suspended threads don't execute until they're resumed. Set Suspended to True to suspend a thread; set it to False to resume it.


ThreadID property

See also

Applies to

TThread object

Declaration

property ThreadID: THandle;

Description

Runtime and readonly. The ThreadID property contains the thread's ID (different from its handle in the Handle property). The thread ID is useful if you need to call Win32 API functions for manipulating the thread.


See also

Handle property


OnTerminate event

Applies to

TThread object

Declaration

property OnTerminate: TNotifyEvent;

Description

Runtime only. The OnTerminate event handler is called after the thread's Execute method has returned and just before TThread ends the thread. OnTerminate is called in the context of the main VCL thread, which means you can freely call VCL methods and access VCL properties.


TThreadPriority type

See also

Unit

Classes

Applies to

TThread object

Declaration

type

  TThreadPriority = (tpIdle, tpLowest, tpLower, tpNormal, tpHigher, tpHighest,
  tpTimeCritical);

Description

TThreadPriority defines the possible values for the Priority property of the TThread component, as defined in the following table. Windows schedules threads based on a priority scale; the Priority property lets you adjust a thread's priority higher or lower on the scale.

Values

tpIdle	The thread executes only when the system is idle-Windows won't interrupt other threads to execute a thread with tpIdle priority.

tpLowest	The thread's priority is two points below normal.

tpLower	The thread's priority is one point below normal.

tpNormal	The thread has normal priority.

tpHigher	The thread's priority is one point above normal.

tpHighest	The thread's priority is two points above normal.

tpTimeCritical	The thread gets highest priority.


See also

Priority property


UpdateObject property

Applies to

TTable, TQuery, TStoredProc components

Declaration

property UpdateObject: TDataSetUpdateObject;

Description

The UpdateObject property is an optional reference to a TUpdateObject component. If UpdateObject is set and CachedUpdates is True, calling ApplyUpdates on a read-only dataset will invoke the update object component for each record that requires updating. This allows you to manually update read-only datasets.

For more infomation on updating read-only datasets, see the chapter on "Working with cached updates" in the Database Application Developer's Guide.


UpdatesPending property

See also	Example

Applies to

TTable, TQuery, TStoredProc components

Declaration

property UpdatesPending: Boolean;

Description

Run-time and read only. The UpdatesPending property indicates whether there are any records in the internal cache. Use this when you are using cached updates on a dataset and wish to know if any records are left in the cache. When cached updates are successfully committed, the internal cache is cleared.

For more infomation on cached updates, see the chapter on "Working with cached updates" in the Database Application Developer's Guide.


Example

procedure ApplyButtonClick(Sender: TObject);

begin

  with CustomerQuery do

  begin

    if UpdatesPending then

    begin

      Database1.StartTransaction;

      try

        ApplyUpdates; {try to write the updates to the database}

        Database1.Commit; {on success, commit the changes}

      except

        Database1.Rollback; (on failure, undo any changes}

        raise; {raise the exception again to prevent a call to CommitUpdates}

      end;

      CommitUpdates; {on success, clear the internal cache}

    end;

  end;

end;


See also

CachedUpdates property

ApplyUpdates method


OnServerYield event

Applies to

TTable, TQuery, TStoredProc components

Declaration

TOnServerYieldEvent = procedure(DataSet: TDataSet; var AbortQuery: Boolean) of object;

property OnServerYield: TOnServerYieldEvent;

Description

The OnServerYield event occurs periodically during a query executing on a Sybase server. Setting the parameter AbortQuery to False will cancel the query during execution.


ParamCheck

See also

Applies to

TQuery component

Declaration

property ParamCheck: Boolean;

Description

The ParamCheck property determines whether the query fills the Params array when the SQL property is changed at run time. Default is True.


See also

Params property

TParams object


IsAlias method

See also	Example

Applies to

TSession component

Declaration

function IsAlias(const Name: string): Boolean;

Description

The IsAlias method returns True if the database alias specified by Name exists. Like the GetAliasNames method, the result of this function will be determined by the ConfigMode property.


Example

with Session do

begin

     if not IsAlias('MYALIAS') then

     begin

       AddStandardAlias('MYALIAS', 'C:\MYAPP\DATADIR', 'PARADOX');

       SaveConfigFile;

     end;

   end;


See also

Session variable, AddAlias method, AddStandardAlias method, DeleteAlias method


Bookmark property

See also

Applies to

TTable, TQuery, TStoredProc components

Declaration

property Bookmark: TBookmarkStr;

Description

Run-time only. The Bookmark property returns a bookmark for the current row.  Assigning to the property moves the cursor to the record corresponding to the bookmark.

Note:	The contents of the bookmark string is opaque and volatile:  do not modify the contents of bookmarks or store them beyond the active lifetime of the dataset they refer to.


See also

GotoBookmark method, GetBookmark method


Locked property

See also

Applies to

TPanel component

Declaration

property Locked: Boolean;

Description

The Locked property determines whether a panel that is being used as a toolbar is replaced by the OLE object's server's toolbar. Normally, any panels you use for toolbars are replaced by the OLE object's server's toolbars. You can prevent this by setting the panel'sLocked property to True. When Locked is True, TOleContainer won't remove the panel to make room for the server's toolbars.

Note that your application's toolbars must be in panels aligned to a side of your form (that is, their Align property set to alTop, alBottom, alLeft, or alRight).


See also

TOleContainer component


CommitCount property

See also

Applies to

TBatchMove component

Declaration

property CommitCount: Integer;

Description

The CommitCount property determines how many records are batch moved before a commit is executed.


See also

Execute method


LaunchType property

See also	Example

Applies to

TReport component

Declaration

TLaunchType = (ltDefault, ltRunTime, ltDesignTime);

property LaunchType: TLaunchType;

Description

The LaunchType property specifies whether ReportSmith is to be opened in runtime mode or design mode when the Run method is called. When LauchType is set to ltRunTime or ltDefault, Run starts the runtime version of ReportSmith to print or preview a report. When LaunchType is set to ltDesignTime, Run opens ReportsSmith for modifying and creating reports.

The following table contains a list of possible values of the LauchType property.

Value	Meaning

ltDefault	Launch ReportSmith Runtime for printing and previewing reports.

ltRunTime	Launch ReportSmith Runtime for printing and previewing reports.

ltDesignTime	Launch ReportSmith to modify or create a report.


Example

procedure TForm1.PreviewButton(Sender: TObject);

begin

  with Report1 do

  begin

    Preview := True;

    ReportName := 'Animals.rpt';

    ReportDir := 'c:\program files\borland\Reports';

    LaunchType := ltRunTime;

    Run;

  end;

end;


See also

Run method


TitleFont property

See also

Applies to

TDBGrid component

Declaration

property TitleFont: TFont;

Description

The TitleFont property determines which font and text attributes are used to display the title of a column in a DBGrid component. At design time, the TitleFont property is set by bringing up the Font dialog box. To modify the TitleFont at runtime, change the value of the Color, Name, Size, or Style properties of the font object

At runtime, the DefaultFont method also returns the current TitleFont value.


See also

DefaultFont method


ListFieldIndex property

Applies to

TDBLookupListBox, TDBLookupComboBox components

Declaration

property ListFieldIndex: Integer;

Description

The ListFieldIndex property specifies which field from the ListField property is used for incremental searching. For the DBLookupComboBox, ListFieldIndex also determines which field appears in the edit box portion of the combo box.


DropDownAlign property

Applies to

TDBLookupComboBox component

Declaration

TDropDownAlign = (daLeft, daRight, daCenter);

property DropDownAlign: TDropDownAlign;

Description

The DropDownAlign property specifies how the drop-down list is aligned relative to its edit box.


DropDownRows property

Applies to

TColumn object, TDBLookupComboBox component

Declaration

property DropDownRows: Integer;

Description

The DropDownRows property specifies the number of lines of text to display in the drop-down list of the DBLookupComboBox.


OnCloseUp event

See also

Applies to

TDBLookupComboBox component

Declaration

property OnCloseUp: TNotifyEvent;

Description

The OnCloseUp event occurs when the opened or "dropped-down" DBLookupComboBox is closed.


See also

CloseUp method


RowsAffected property

Applies to

TQuery component

Declaration

property RowsAffected: Integer;

Description

Run-time and read only. This property returns the number of rows affected by the last ExecSQL call.  It is intended to be used with UPDATE and DELETE queries to determine the number of rows updated or deleted.

If the last query never affects rows (such as a transaction operation), the result is -1.


FlushSchemaCache method

Applies to

TDatabase component

Declaration

procedure FlushSchemaCache(const TableName: string);

Description

The FlushSchemaCache method flushes the cached schema information for TableName. Schema information includes field names, field types and index information which is stored in memory when the table is opened. This should be called when any of the schema information for a table has changed, for example, when a field, index or table has been added to or dropped from the database.


BDECalcField property

Applies to

TField component, TFieldDef object

Declaration

property BDECalcField: Boolean

Description

Run-time and read only. The BDECalcField property returns True if the field is a BDE calculated field and the data set is live. For example, the following SQL statement includes a calculated field which will cause BDECalcField for the field to return True when the the query has its RequestLive property set to True.

SELECT PARTNO, DESCRIPTION, ONHAND, COST, (ONHAND * COST) FROM PARTS

When BDECalcField is True, the field will allow editing, but the changes are thrown away. To disallow editing, set ReadOnly for the field toTrue.


SessionAlias property

Applies to

TDatabase component

Declaration

property SessionAlias: Boolean;

Description

Run-time and read only. The SessionAlias property returns True if the database component is using a session alias. A session alias is an alias that exists only while the application is running, is not stored in the BDE configuration file and cannot be accessed from outside the application.


ListVisible property

See also

Applies to

TDBLookupComboBox component

Declaration

property ListVisible: Boolean;

Description

Runtime and read-only. The ListVisible property returns True if the combo box is open or "dropped-down".


See also

CloseUp method


DefaultConverter property

See also

Applies to

TRichEdit component

Declaration

property DefaultConverter: TConversionClass;

Description

Run-time only. The DefaultConvert specifies which TConversion object to automatically use for conversion of documents to rich-text format (.RTF) files.


See also

RegisterConversionFormat method, TConversion object, PlainText property


RegisterConversionFormat method

See also

Applies to

TRichEdit component

Declaration

class procedure RegisterConversionFormat(const AExtension: string; AConversionClass: TConversionClass);

Description

The RegisterConversionFormat method registers a class derived from TConversion for handling conversion of documents to rich-text format (.RTF) files. After the RegisterConversionFormat method is called for a TConversion class, the rich edit component automatically uses that class when loading a file with an extension specified by AExtension.


See also

DefaultConverter property, TConversion object


AppendStr procedure

String formatting routines

Unit

SysUtils

Declaration

procedure AppendStr(var Dest: string; const S: string);

Description

AppendStr appends S to the end of Dest. AppendStr corresponds to the statement "Dest := Dest + S", but is more efficient.


AssignStr procedure

See also	Example	String handling routines (Pascal style)

Unit

SysUtils

Declaration

procedure AssignStr(var P: PString; const S: string);

Description

AssignStr assigns a new dynamically allocated string to the given string pointer. AssignStr corresponds to the statement DisposeStr(P) followed by the statement P := NewStr(S). Note that P must be NIL or contain a valid string pointer before calling AssignStr. In other words, AssignStr cannot be used to initialize a string pointer variable.


Example

var

  P: PString;

begin

  P := NewStr('First string');   { Allocate and point to 'First string' }

  AssignStr(P, 'Second string'); { Dispose of 'First string', allocate and point to }
                                 { 'Second string' }

  DisposeStr(P);    { Dispose of 'Second string' }

end;


See also

DisposeStr procedure


BeginThread function

See also

Unit

SysUtils

Declaration

BeginThread(SecurityAttributes: Pointer; StackSize: Integer; ThreadFunc: TThreadFunc;
Parameter: Pointer; CreationFlags: Integer; var ThreadId: Integer): Integer;

Description

Delphi applications should use this routine or a TThread object to spawn separate threads of execution instead of calling the CreateThread Win32API directly.

BeginThread encapsulates the Win32 CreateThread API call. It functions similarly to CreateThread with the exception that BeginThread takes a normal Pascal function as the thread function. Thread functions should handle all of its own exceptions. BeginThread sets up an exception frame that allows the system's default exception handler to catch any of the thread's unhandled exceptions. The application is terminated if there are any unhandled exceptions in the thread function.


See also

CreateThread procedure

EndThread function

TThreadFunc type


CurrToStr function

See Also

Unit

SysUtils

Declaration

function CurrToStr(Value: Currency): string;

Description

The CurrToStr function converts the currency value given by Value to its string representation. The conversion using the ffGeneral floating point conversion rules . For further details, see the description of the CurrToStrF function.


See also

CurrToStrF function

FormatCurr function

StrToCurr function

TFloatFormat type

FloatToText function


CurrToStrF function

See Also

Unit

SysUtils

Declaration

function CurrToStrF(Value: Currency; Format: TFloatFormat; Digits: Integer): string;

Description

 template

The CurrToStrF function converts the currency value given by Value to its string representation using the indicated float format convention. A call to CurrToStrF corresponds to a call to FloatToStrF with an implied precision of 19 digits.


See also

FormatCurr function

StrToCurr function

FloatToStrF function


EndThread function

See also

Unit

SysUtils

Declaration

EndThread(ExitCode: Integer);

Description

EndThread calls the ExitThread WinAPI with the ExitCode you specify.


See also

CreateThread procedure

BeginThread function

TThreadFunc type


EmptyStr constant

Unit

SysUtils

Declaration

EmptyStr: string = '';

Description

EmptyStr declares an empty string.


ExpandUNCFileName function

See Also	File management routines

Unit

SysUtils

Declaration

function ExpandUNCFileName(const FileName: string): string;

Description

The ExpandUNCFileName function returns a string containing a fully qualified path name for the file passed in the FileName. A fully qualified path name includes the drive portion of the filename in the UNC format '\\<servername>\<sharename>' if the drive letter is mapped to a network resource instead of a local drive and any directory and subdirectories in addition to the file name and extension.

Delphi programs can use this function to store filenames that are independent of a particular user's drive letter mappings.


See also

ExpandFilename function

ExtractFileDrive function


ExtractFileDrive function

See Also	File management routines

Unit

SysUtils

Declaration

function ExtractFileDrive(const FileName: string): string;

Description

The ExtractFileDrive function returns a string containing the 'drive' portion of a fully qualified path name for the file passed in the FileName. For file names with drive letters, the resulting string is in the form '<drive>:'. For file names with a UNC path the resulting string is in the form '\\<servername>\<sharename>'. If the given path contains neither style of path prefix, the result is an empty string.

Delphi programs can use this function to store filenames that are independent of a particular user's drive letter mappings.


See also

ExpandFilename function

ExpandUNCFileName function


FormatCurr function

See Also

Unit

SysUtils

Declaration

function FormatCurr(const Format: string; Value: Currency): string;

Description

FormatCurr formats the currency value given by Value using the format string given by Format. For further details, see the description of the FormatFloat function.


See also

CurrToStr function

CurrToStrF function

StrToCurr function

FormatFloat function


HPrevInst variable

Description

The HPrevInst variable is not supported in the 32bit Windows environment.


See also

HInstance variable


IsMultiThread variable

Unit

System

Declaration

IsMultiThread: Boolean;

Description

IsMultiThread is set to true by BeginThread in order to allow the memory manager to execute safely if a Delphi application has more than one thread. If a second thread attempts to allocate memory, it is blocked until the first thread exits the memory manager.


MSecsPerDay constant

Date and time routines

Unit

SysUtils

Declaration

MSecsPerDay = 24 * 60 * 60 * 1000;

Description

MSecsPerDay declares the number of milliseconds per day.


NullStr constant

See Also

Unit

SysUtils

Declaration

NullStr: PString = @EmptyStr;

NullStr declares a pointer to EmptyStr.

NullStr is the return value for many string handling routines when the string is empty.


See Also

String Handling Routines


OleStrToString function

See Also	Ole string support routines

Unit

System

Declaration

function OleStrToString(Source: PWideChar): string;

Description

The OleStrToString function copies data received from an OLE function or method into a newly allocated native Delphi string.


See also

OleStrToStringVar function

StringToOleStr function


OleStrToStrVar procedure

See Also	Ole string support routines

Unit

System

Declaration

procedure OleStrToStrVar(Source: PWideChar; var Dest: string);

Description

The OleStrToStrVar copies OLE string data into an existing Delphi string variable.


See also

OleStrToString function

StringToOleStr function


MSecsPerDay constant

Date and time routines

Unit

SysUtils

Declaration

MSecsPerDay = 24 * 60 * 60;

Description

SecsPerDay declares the number of seconds per day.


StrToCurr function

See Also

Unit

SysUtils

Declaration

function StrToCurr(const S: string): Currency;

Description

StrToCurr converts floating point number in the given string to a currency value. For further details, see the description of the StrToFloat function.


See also

CurrToStr function

CurrToStrF function

FormatCurr function


StringToOleStr function

See Also	Ole string support routines

Unit

System

Declaration

function StringToOleStr(const Source: string): PWideChar;

Description

The StringToOleStr function allocates memory and copies string data from a native Delphi string into a format that can be passed to OLE functions.


See also

OleStrToString function

OleStrToStringVar function


TByteArray type

Unit

SysUtils

Declaration

PByteArray = ^TByteArray;

TByteArray = array[0..32767] of Byte;

Description

TByteArray declares a general array of type Byte that can be used in typecasting.


Test8086 variable

Description

The Test8086 variable is no longer supported in the 32-bit version of Delphi. Use the GetSystemInfo Windows API function instead.


TWordArray type

Unit

SysUtils

Declaration

PWordArray = ^TWordArray;

TWordArray = array[0..16383] of Word;

Description

TWordArray declares a general array of type Word that can be used in typecasting.


VarToStr function

Unit

System

Declaration

function VarToStr(const V: Variant): string;

Description

The VarToStr function converts the data in a variant to a string.


WideCharToStrVar procedure

See Also	Wide character routines

Unit

System

Declaration

procedure WideCharToStrVar(Source: PWideChar; var Dest: string);

Description

The WideCharToStrVar procedure converts WideChar (Unicode) string data into single byte character data, and copies the result into the provided destination string variable. The source must be null-terminated.


See also

WideCharLenToStrVar function


WideCharLenToStrVar procedure

See Also	Wide character routines

Unit

System

Declaration

procedure WideCharLenToStrVar(Source: PWideChar; SourceLen: Integer; var Dest: string);;

Description

The WideCharLenToStrVar procedure converts WideChar (Unicode) string data into single byte character data, and copies the result into the provided destination string variable. Unlike WideCharToStrVar, the source does not need to be null-terminated.


See also

WideCharToStrVar function


TRegistry object

Properties	Methods

Unit

Registry

Description

A TRegistry object is a low-level wrapper for the Microsoft Windows95/NT system registry and functions that operate on the registry. The registry is a database that your applications can use to store and retrieve configuration information. Configuration information is stored in a hierarchical tree. Each node in the tree is called a key. Every key can contain subkeys and data values that represent part of the configuration information for an application.

All keys that your application creates, opens, reads, or writes are subkeys of  predefined root keys. By default, a TRegistry object is created with a root key of HKEY_CURRENT_USER.

Only one key is accessible at a time in a TRegistry object. To determine the key that is currently accessible, read the value of the CurrentKey property. TRegistry methods enable you to open, close, save, move, copy, and delete keys.

One or more data values containing actual configuration information can be stored in a key. TRegistry methods enable you to query a key to see if it contains data, to read data in a key, and to write data to a key.


Properties

CurrentKey	LazyWrite	RootKey

CurrentPath


Methods

ClassName	HasSubKeys	ReplaceKey

ClassParent	KeyExists	RestoreKey

ClassType	LoadKey	SaveKey

CloseKey	MoveKey	UnLoadKey

Create	OpenKey	ValueExists

CreateKey	ReadBinaryData	WriteBinaryData

DeleteKey	ReadBool	WriteBool

DeleteValue	ReadCurrency	WriteCurrency

Destroy	ReadDate	WriteDate

Free	ReadDateTime	WriteDateTime

GetDataInfo	ReadFloat	WriteFloat

GetDataSize	ReadInteger	WriteInteger

GetDataType	ReadString	WriteString

GetKeyInfo	ReadTime	WriteTime

GetKeyNames	RegistryConnect

GetValueNames	RenameValue


ERegistryException object

Unit

Registry

Declaration

type ERegistryException = class(Exception);

Description

The ERegistryException object is used for internal and protected method errors, and in the CreateKey method when the creation of a registry key fails.


TRegKeyInfo type

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

type

 TRegKeyInfo = record

   NumSubKeys: Integer;

   MaxSubKeyLen: Integer;

   NumValues: Integer;

   MaxValueLen: Integer;

   MaxDataLen: Integer;

   FileTime: TFileTime;

 end;

Description

The TRegKeyInfo type is the parameter type for the Value variable passed to the GetKeyInfo method of the TRegistry and TRegIniFile objects. GetKeyInfo queries the registry for information about the CurrentKey. The variables of the TRegInfo record each contain a specific piece of information about the CurrentKey. Their meanings are as follows:

NumSubKeys indicates the number of subkeys contained by the CurrentKey.

MaxSubKeyLen contains the string length of the subkey with the longest name. This value does not include the terminating null character.

NumValues is the number of values associated with the CurrentKey.

MaxValueLen contains the string length of the CurrentKey's value with the longest name. This value does not include the terminating null character.

MaxDataLen is the length, in bytes, of the longest data component in the CurrentKey's values.

FileTime contains information indicating the last time the CurrentKey or any of its value entries was modified. FileTime is of type TFileTime that maps to the WINAPI FILETIME structure.


See also

GetKeyInfo method


TRegDataType type

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

type

TRegDataType = (rdUnknown, rdString, rdExpandString, rdInteger, rdBinary);

Description

The TRegDataType type is the type of the RegData variable for the TRegDataInfo record. TRegDataInfo is used by the GetDataInfo method of the TRegistry and TRegIniFile objects. TRegDataType is also the return type for the GetDataType method. Here are the possible values for TRegDataType:

Value	Meaning

rdUnknown	Indicates that the data value type is of no defined value type.

rdString	Indicates that the data value type is a null-terminated string. It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.

rdExpandString	Indicates that the data value type is a null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.

rdInteger	Indicates that the data value type is a32-bit number.

rdBinary	Indicates that the data value type is binary data, in any form.


See also

TRegDataInfo type

GetDataInfo method

GetDataType method


TRegDataInfo type

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

type

TRegDataInfo = record

   RegData: TRegDataType;

   DataSize: Integer;

 end;

Description

The TRegDataInfo type is the parameter type for the Value variable passed to the GetDataInfo method for the TRegistry and TRegIniFile objects. RegData is of type TRegDataType. It identifies a data value for a key as one of five types. DataSize contains the size of that data value.


See also

TRegDataType type

GetDataInfo method


CurrentKey property

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

property CurrentKey: HKEY;

Description

Runtime and read only. The CurrentKey property reports the key that is currently open.


See also

CurrentPath property

RootKey property


CurrentPath property

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

property CurrentPath: string;

Description

Runtime and read only. The CurrentPath property returns the registry path associated with the CurrentKey.


See also

CurrentKey property


LazyWrite property

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

property LazyWrite: Boolean;

Description

The LazyWrite property determines how keys are written to the registry when the CloseKey procedure is called. By default, LazyWrite is True.When LazyWrite is True, keys are written to the registry when they are closed, but the CloseKey procedure may return before the write operation takes place.

When LazyWrite is False, keys are written to the registry before CloseKey returns. Set LazyWrite to False only when absolutely necessary. Setting LazyWrite to False guarantees that the changes your application makes to keys are written to the registry before further application processing takes place, but it uses more system resources when keys are closed. When LazyWrite is False, and you are viewing or changing the registry, making repeated calls to CloseKey may also have a negative effect on application performance.


See also

CloseKey method


RootKey property

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

property RootKey: HKEY;

Description

The RootKey property specifies the root key for the TRegistry object in your application. RootKey determines the key and subkeys your application can access.

By default, RootKey is set to HKEY_CURRENT_USER. To change the root key, specify a new value for the RootKey property.


See also

CurrentKey property


CloseKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure CloseKey;

Description

CloseKey closes the current key. Calling CloseKey when there is no current key has no effect.

When an application closes a key, the key is written to the registry. The LazyWrite property determines how the write takes place. If LazyWrite is True (the default), the key is  written to the registry when it is closed, but CloseKey may return before the write operation takes place. When LazyWrite is False, the key is written to the registry before CloseKey returns.


See also

CurrentKey property

LazyWrite property


Create method

See also

Applies to

TRegistry object

Declaration

constructor Create;

Description

This constructor creates a TRegistry object for an application. Create sets the RootKey property of TRegistry to HKEY_CURRENT_USER, and sets the LazyWrite property to True.


See also

RootKey property

LazyWrite property


CreateKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function CreateKey(const Key: string): Boolean;

Description

CreateKey creates a new key in the registry. Attempting to create a key that already exists has no effect.

Key is the name of the key to create. Key can be an absolute or relative name. An absolute key begins with a backslash (\) and is a subkey of the root key. A relative key is a subkey of the current key.

CreateKey returns True if key creation is successful. On error, an exception is raised, and CreateKey returns False.

CreateKey creates only non-volatile keys. If you need to create volatile keys on Windows NT, you must call the Windows API directly.

CreateKey creates keys with a security access of KEY_ALL_ACCESS. If you need to create keys with more restricted access, you must call the Windows API directly.

A key created by CreateKey has no values. To set key values, use the WriteCurrency, WriteBinaryData, WriteBool, WriteDate, WriteDateTime, WriteFloat, WriteInteger, WriteString, or WriteTime procedures.


See also

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDate method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteString method

WriteTime method.


DeleteKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function DeleteKey(const Key: string): Boolean;

Description

DeleteKey removes a specified key and its associated data from the registry. If the key has subkeys, the subkeys and any associated data are also removed.

DeleteKey returns True if key deletion is successful. On error, DeleteKey returns False.


See also

CreateKey method


DeleteValue method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function DeleteValue(const Name: string): Boolean;

Description

DeleteValue erases a data value that is associated with the current key.

Name is string containing the name of the value to delete. Every value associated with a key has a unique name.

DeleteValue returns True if the deletion is successful, False if the deletion fails.


See also

CurrentKey property

DeleteKey method


Destroy method

See also

Applies to

TRegistry object

Declaration

destructor Destroy; override;

Description

This destructor destroys a TRegistry object previously created for an application. Before destroying the object, the current key is written to the registry.


See also

Create method


GetDataInfo method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function GetDataInfo(const ValueName: string; var Value: TRegDataInfo): Boolean;

Description

GetDataInfo returns information about a specified data value associated with the current key. Information is returned in a record of type TRegDataInfo, which you must declare in your application. This record type contains two fields: the data type of the data value; and the size, in bytes, of the data value.

ValueName is a string containing the name of the data value to query. Value is a record of type TRegDataInfo in which information about the data value is returned. If the data value is of type rdString or rdExpandString, the size of the data value includes an extra byte for the terminating null character.

GetDataInfo returns True if data value information is returned. If GetDataInfo fails, it returns False, and the Value record is filled with zeros.


See also

TRegDataInfo type

CurrentKey property

GetDataSize method

GetDataType method

GetKeyInfo method


GetDataSize method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function GetDataSize(const ValueName: string): Integer;

Description

GetDataSize returns the size, in bytes, of a specified data value associated with the current key. If the data value is of type rdString or rdExpandString, size includes an extra byte for the terminating null character.

ValueName is a string containing the name of the data value to query.

On success, GetDataSize returns the size of the data value. On failure, GetDataSize returns -1.


See also

CurrentKey property

GetDataInfo method

GetDataType method

GetKeyInfo method


GetDataType method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function GetDataType(const ValueName: string): TRegDataType;

Description

GetDataType returns the enumerated data type of a specified data value associated with the current key. The enumerated data type is of type TRegDataType and can be one of the following values:

rdUnknown, rdString, rdExpandString, rdInteger, rdBinary


See also

TRegDataType type

CurrentKey property

GetDataInfo method

GetDataSize method

GetKeyInfo method


GetKeyInfo method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function GetKeyInfo(var Value: TRegKeyInfo): Boolean;

Description

GetKeyInfo returns information about the current key. Information is returned in a record of type TRegKeyInfo, declared in your application. Information returned by GetKeyInfo about the current key includes:

Number of subkeys

Longest subkey name length, in characters

Number of data values

Longest data-value name length

Longest data-value length

Time of last write to the key

Value is the declared variable of type TRegKeyInfo in which to return information about the current key.

On success GetKeyInfo returns True, on failure, False.


See also

TRegKeyInfo type

CurrentKey property

GetDataInfo method

GetDataSize method

GetDataType method


GetKeyNames method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure GetKeyNames(Strings: TStrings);

Description

GetKeyNames returns a string list containing the names of all subkeys associated with the current key.

Strings is the declared object of type TStrings in which to return the list of subkey names.


See also

CurrentKey property

TStrings object

GetValueNames method


GetValueNames method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure GetValueNames(Strings: TStrings);

Description

GetValueNames returns a string list containing the names of all data values associated with the current key.

Strings is the declared object of type TString in which to return the list of data-value names.


See also

CurrentKey property

TStrings object

GetKeyNames method


HasSubKeys method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function HasSubKeys: Boolean;

Description

The HasSubKeys function returns True if the current key has at least one subkey.


See also

CurrentKey property

KeyExists method


KeyExists method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function KeyExists(const Key: string): Boolean;

Description

The KeyExists function returns True if a specified Key exists, False if the Key does not exist.


See also

HasSubKeys method


LoadKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function LoadKey(const Key, FileName: string): Boolean;

Description

The LoadKey function creates a subkey under the root key, which is specified by the RootKey property, and then loads registry information from a file into the subkey. The registry information, called a hive, can contain keys, subkeys, and values.

The Key parameter is the name of the subkey to create. The FileName parameter is the address of a filename containing registry information to store in the subkey.

Note:	Before calling LoadKey, the RootKey property must be set HKEY_USER, HKEY_LOCAL_MACHINE, or a key returned by a previous call to RegistryConnect.

The return value of LoadKey is True if the function succeeds in loading the key.

Note:	The file used for the FileName parameter must have been created either with the TRegistry SaveKey function, or by directly calling the RegSaveKey API function. Under the FAT file system this filename cannot have an extension.


See also

RootKey property

RegistryConnect method

SaveKey method

UnLoadKey method


MoveKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure MoveKey(const OldName, NewName: string; Delete: Boolean);

Description

The MoveKey procedure opens the key specified by OldName and copies it to the key specified by NewName. If the key specified by NewName does not exist, MoveKey creates it. If Delete is True, the key specified by OldName is deleted after it is copied. Otherwise it is closed.

Copying is done recursively. If a key contains subkeys and data values, they, too are copied. When the information has been copied the new key is closed.


See also

SaveKey method

ReplaceKey method

RestoreKey method


OpenKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function OpenKey(const Key: string; CanCreate: Boolean): Boolean;

Description

The OpenKey function opens a specified key and sets the CurrentKey property to it. If the specified key does not exist and CanCreate is True, the key is created.

Key is the name of the key to open. If Key is null, the key specified by the RootKey property is opened.

Key is opened or created with the security access value KEY_ALL_ACCESS. If the key is created, it is non-volatile, meaning that the key is stored in the registry and is preserved when the system is restarted.

OpenKey returns True if the key is sucessfully opened or created


See also

CurrentKey property

RootKey property


ReadBinaryData method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadBinaryData(const Name: string; var Buffer; BufSize: Integer): Integer;

Description

The ReadBinaryData function retrieve a binary value from a specified data value associated with the current key. Binary data is typically an Object Pascal record, and not an icon or bitmap because these are not usually stored in the registry.

Name is the name of the data value to read. Buffer is the application variable into which to read the registry data. Buffer must be large enough to hold all of the data returned. BufSize specifies the size of Buffer.

If successful, ReadBinaryData returns the requested data. On error, an exception is raised, and the value returned by this function shoud be discarded.


See also

CurrentKey property

ReadCurrency method

ReadBool method

ReadDate method

ReadDateTime method

ReadFloat method

ReadInteger method

ReadString method

ReadTime method


ReadBool method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadBool(const Name: string): Boolean;

Description

The ReadBool function retrieves a Boolean value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadBool returns a Boolean value. On error, an exception is raised, and the value returned by this function should be discarded.

Note:	A TRegIniFile object overrides this function with its own ReadBool function. To call the ReadBool function belonging to TRegistry, cast the call to ReadBool as TRegistry.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadDate method

ReadDateTime method

ReadFloat method

ReadInteger method

ReadString method

ReadTime method


ReadCurrency method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadCurrency(const Name: string): Currency;

Description

The ReadCurrency function retrieves a currency value from a specified data value associated with the current key. Name is the name of the data vale to read.

If successful, ReadCurrency returns a Currency value. On error, an exception is raised, and the value returned by this function should be discarded.


See also

CurrentKey property, ReadBinaryData method, ReadBool method, ReadDate method, ReadDateTime method, ReadFloat method, ReadInteger method, ReadString method, ReadTime method


ReadDate method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadDate(const Name: string): TDateTime;

Description

The ReadDate function retrieves a date value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadDate returns an Object Pascal TDateTime value. On error, an exception is raised, and the value returned by this function should be discarded.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadBool method

ReadDateTime method

ReadFloat method

ReadInteger method

ReadString method

ReadTime method


ReadDateTime method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadDateTime(const Name: string): TDateTime;

Description

The ReadDateTime function retrieves a date and time value from a specifed data value associated with the current key. Name is the name of the data value to read.

If successful, ReadDateTime returns an Object Pascal TDateTime value. On error, an exception is raised, and the value returned by this function should be discarded.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadBool method

ReadDate method

ReadFloat method

ReadInteger method

ReadString method

ReadTime method


ReadFloat method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadFloat(const Name: string): Double;

Description

The ReadFloat function retrieves a float value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadFloat returns an Object Pascal Double value. On error, an exception is raised, and the value returned by this function should be discarded.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadBool method

ReadDate method

ReadDateTime method

ReadInteger method

ReadString method

ReadTime method


ReadInteger method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadInteger(const Name: string): Integer;

Description

The ReadInteger function retrieves an integer value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadInteger returns an Object Pascal Integer value. On error, an exception is raised, and the value returned by this function should be discarded.

Note:	A TRegIniFile object overrides this function with its own ReadInteger function. To call the ReadInteger function belonging to TRegistry, cast the call to ReadInteger as TRegistry.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadBool method

ReadDate method

ReadDateTime method

ReadFloat method

ReadString method

ReadTime method


ReadString method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadString(const Name: string): string;

Description

The ReadString function retrieves a string value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadString returns an Object Pascal String value. On error, an exception is raised, and the value returned by this function should be discarded.

Note:	A TRegIniFile object overrides this function with its own ReadString function. To call the ReadString function belonging to TRegistry, cast the call to ReadString as TRegistry.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadBool method

ReadDate method

ReadDateTime method

ReadFloat method

ReadInteger method

ReadTime method


ReadTime method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReadTime(const Name: string): TDateTime;

Description

The ReadTime function retrieves a time value from a specifed data value associated with the current key. Name is the name of the data value to read.

If successful, ReadTime returns an Object Pascal TDateTime value. On error, an exception is raised, and the value returned by this function should be discarded.


See also

CurrentKey property

ReadCurrency method

ReadBinaryData method

ReadBool method

ReadDate method

ReadDateTime method

ReadFloat method

ReadInteger method

ReadString method


RegistryConnect method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function RegistryConnect(const UNCName: string): Boolean;

Description

The RegistryConnect function establishes a connection to a registry on another computer. UNCName is the name of the remote computer, and must take the following form:

\\computername

where computername is the name of the remote computer. If UNCName is Null, the local machine name is used.

Note:	Before calling RegistryConnect, your application must set the RootKey property for TRegistry to HKEY_USERS or HKEY_LOCAL_MACHINE.

If connection is successful, RegistryConnect sets the RootKey property to the root key of the remote computer and returns True. If unsuccessful, RegistryConnect returns False, and RootKey remains unchanged.


See also

RootKey property

CurrentKey property


RenameValue method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure RenameValue(const OldName, NewName: string);

Description

The RenameValue procedure changes the name of a data value associated with the current key. OldName is a string containing the current name of the data value. NewName is a string containing the replacement name for the data value.

If OldName is the name of an existing data value for the current key, and NewName is not the name of an existing data value for the current key, RenameValue changes the data value name as specified. Otherwise the current name remains unchanged.


See also

CurrentKey property

GetValueNames method

ValueExists method

MoveKey method


ReplaceKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ReplaceKey(const Key, FileName, BackUpFileName: string): Boolean;

Description

The ReplaceKey function replaces the file backing a key and all its subkeys with another file, so that when the system is next started, the key and subkeys will have the values stored in the new file.

FileName indicates the name of the file containing the new key and subkey information. BackUpFileName is the name of a backup file used to store the current key and subkey information before it is overwritten.

ReplaceKey returns True if it is successful.

Note:	The file specified by FileName parameter must be created with the SaveKey function, or by directly calling the Windows 95/NT RegSaveKey API function. Under the FAT file system FileName cannot have an extension.


See also

RegistryConnect method

SaveKey method


RestoreKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function RestoreKey(const Key, FileName: string): Boolean;

Description

The RestoreKey function reopens the specified key with the security access value KEY_ALL_ACCESS, and overwrites any information contained in this key and its subkeys keys with registry data in the file pointed to by FileName. The information in this file can be in the form of a single key, or multiple levels of subkeys and values.

Key is the name of the key to open. FileName is the name of the file containing the new key and subkey information.

If RestoreKey successfully reads and copies the registry information in FileName to the specified key, the return value of RestoreKey is True and the key is closed.

Note:	The file specified by FileName parameter must be created with the SaveKey function, or by directly calling the Windows 95/NT RegSaveKey API function. Under the FAT file system FileName cannot have an extension.


See also

SaveKey method


SaveKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function SaveKey(const Key, FileName: string): Boolean;

Description

The SaveKey function opens the specified key with the security access value KEY_ALL_ACCESS and saves the specified key and all of its subkeys and values to a file.

Key is the name of the key to save. FileName must be the name of a new file that does not already exist. Files used as parameters for the RestoreKey, ReplaceKey and LoadKey should be created with SaveKey. If SaveKey is successful it returns True and closes the key.

Note:	On FAT file systems FileName cannot include an extension.


See also

LoadKey method

ReplaceKey method

RestoreKey method


UnLoadKey method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function UnLoadKey(const Key: string): Boolean;

Description

The UnLoadKey function removes a hive from the registry but does not modify the file containing the registry information. A hive is a discrete collection of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Key is the name of the key to remove.

Note:	Before calling this function, set RootKey to HKEY_USERS, HKEY_LOCAL_MACHINE, or the key name returned by RegistryConnect.

The return value of UnLoadKey is True if removal is successful.


See also

LoadKey method

RegistryConnect method


ValueExists method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

function ValueExists(const Name: string): Boolean;

Description

The ValueExists function determines if a specified data value exists for the current key. Name is the name of the data value for which to check.

ValueExists returns True if a match if found, False otherwise.


See also

CurrentKey property

GetValueNames method

RenameValue method


WriteBinaryData method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteBinaryData(const Name: string; var Buffer; BufSize: Integer);

Description

The WriteBinaryData procedure stores an Object Pascal record in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteCurrency. If Name does not exist, it is created.

Buffer is an Object Pascal record or data buffer containing the data to store in the registry. BufSize indicates the size of Buffer.

Note:	Data-value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as separate files, and those filenames should be stored in the registry. Application elements such as icons, bitmaps, and executable files should be stored as separate files rather than as values in the registry.

If WriteBinaryData fails, an exception is raised, and the value is not written to the registry.


See also

CurrentKey property

WriteCurrency method

WriteBool method

WriteDate method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteString method

WriteTime method


WriteBool method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteBool(const Name: string; Value: Boolean);

Description

The WriteBool procedure stores a Boolean value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteBool. If Name does not exist, it is created.

Value is an Object Pascal Boolean value to store in the registry.

If WriteBool fails, an exception is raised, and the value is not written to the registry.

Note:	A TRegIniFile object overrides this procedure with its own WriteBool procedure. To call the WriteBool procedure belonging to TRegistry, cast the call to WriteBool as TRegistry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteDate method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteString method

WriteTime method


WriteCurrency method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteCurrency(const Name: string; Value: Currency);

Description

The WriteCurrency procedure stores a currency value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteCurrency. If Name does not exist, it is created.

Value is an Object Pascal Currency value to store in the registry.

If WriteCurrency fails, an exception is raised, and the value is not written to the registry.


See also

CurrentKey property

WriteBinaryData method

WriteBool method

WriteDate method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteString method

WriteTime method


WriteDate method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteDate(const Name: string; Value: TDateTime);

Description

The WriteDate procedure stores a date value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteDate. If Name does not exist, it is created.

Value is an Object Pascal TDateTime value to store in the registry.

If WriteDate fails, an exception is raised, and the value is not written to the registry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteString method

WriteTime method


WriteDateTime method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteDateTime(const Name: string; Value: TDateTime);

Description

The WriteDateTime procedure stores a datetime value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteDateTime. If Name does not exist, it is created.

Value is an Object Pascal TDateTime value to store in the registry.

If WriteDateTime fails, an exception is raised, and the value is not written to the registry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDate method

WriteFloat method

WriteInteger method

WriteString method

WriteTime method


WriteFloat method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteFloat(const Name: string; Value: Double);

Description

The WriteFloat procedure stores a Double value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteFloat. If Name does not exist, it is created.

Value is an Object Pascal Double value to store in the registry.

If WriteFloat fails, an exception is raised, and the value is not written to the registry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDate method

WriteDateTime method

WriteInteger method

WriteString method

WriteTime method


WriteInteger method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteInteger(const Name: string; Value: Integer);

Description

The WriteInteger procedure stores an integer value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteInteger. If Name does not exist, it is created.

Value is an Object Pascal Integer value to store in the registry.

If WriteInteger fails, an exception is raised, and the value is not written to the registry.

Note:	A TRegIniFile object overrides this procedure with its own WriteInteger procedure. To call the WriteInteger procedure belonging to TRegistry, cast the call to WriteInteger as TRegistry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDate method

WriteDateTime method

WriteFloat method

WriteString method

WriteTime method


WriteString method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteString(const Name, Value: string);

Description

The WriteString procedure stores an integer value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteString. If Name does not exist, it is created.

Value is an Object Pascal string value to store in the registry.

If WriteString fails, an exception is raised, and the value is not written to the registry.

Note:	A TRegIniFile object overrides this procedure with its own WriteString procedure. To call the WriteString procedure belonging to TRegistry, cast the call to WriteString as TRegistry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDate method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteTime method


WriteTime method

See also

Applies to

TRegistry object, TRegIniFile object

Declaration

procedure WriteTime(const Name: string; Value: TDateTime);

Description

The WriteTime procedure stores a time value in a specifically named data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteTime. If Name does not exist, it is created.

Value is an Object Pascal TDateTime value to store in the registry.

If WriteTime fails, an exception is raised, and the value is not written to the registry.


See also

CurrentKey property

WriteCurrency method

WriteBinaryData method

WriteBool method

WriteDate method

WriteDateTime method

WriteFloat method

WriteInteger method

WriteString method


TRegIniFile object

See also	Properties	Methods

Unit

Registry

Description

The TRegIniFile object is derived from the TRegistry object. It inherits all of the properties and methods of TRegistry, and adds to them the same properties and methods used by the TIniFile object. Some of the added methods for TRegIniFile, such as ReadBool and WriteBool, override the methods of TRegistry.

TRegIniFile enables you to handle the Windows 95/NT system registry as if it were a Windows 3.x .INI file. Instead of processing an .INI file, however, TRegIniFile reads from and writes to the system registry. The FileName passed to a TRegIniFile object becomes a subkey under the system registry's root key (HKEY_CURRENT_USER by default). What corresponds to a section in an .INI file is treated as a key in the system registry, and what corresponds to data entries under a section in an .INI file are treated as data values under a key in the system registry.

TRegIniFile is particularly useful if you are migrating a 16-bit Windows 3.x application to Windows 95/NT. By finding all references to TIniFile in your source code, replacing them with TRegIniFile, and recompiling your application, you can update your application to use the system registry instead of .INI files without having to code any new logic into your application.

Note:	If you use this method, the information contained in existing users' .INI files is not migrated into the system registry.

Tip:	Because TRegIniFile presents a simple interface to the system registry and hides your need to know about the underlying structure of the registry, you may prefer to use TRegIniFile instead of TRegistry in your applications.


See also

FileName property

TIniFile object


Properties

CurrentKey	FileName	RootKey

CurrentPath	LazyWrite


Methods

ClassName	HasSubKeys	RegistryConnect

ClassParent	KeyExists	RenameValue

ClassType	LoadKey	ReplaceKey

CloseKey	MoveKey	RestoreKey

Create	OpenKey	SaveKey

CreateKey	ReadBinaryData	UnLoadKey

DeleteKey	ReadBool	ValueExists

DeleteValue	ReadCurrency	WriteBinaryData

Destroy	ReadDate	WriteBool

EraseSection	ReadDateTime	WriteCurrency

Free	ReadFloat	WriteDate

GetDataInfo	ReadInteger	WriteDateTime

GetDataSize	ReadSection	WriteFloat

GetDataType	ReadSectionValues	WriteInteger

GetKeyInfo	ReadSections	WriteString

GetKeyNames	ReadString	WriteTime

GetValueNames	ReadTime


FileName property

See also

Applies to

TRegIniFile object

Declaration

property FileName: string;

Description

Run-time and read only. The FileName property contains the name of the key opened or created in the system registry.

Note:	On FAT file systems FileName cannot include an extension.


See also

Create method


Create method

See also

Applies to

TRegIniFile object

Declaration

constructor Create;

Description

This constructor creates a TRegIniFile object for an application. Create inherits Create from TRegistry, and creates an additional property, FileName, which is used to spec ify the name of the key to open or create in the registry.


See also

FileName property


DeleteKey method

See also

Applies to

TRegIniFile object

Declaration

procedure DeleteKey(const Section, Ident: string);

Description

DeleteKey erases a data value that is associated with a key.

Section is string containing the name of the system registry key containing the value to delete. Ident is a string containing the name of the data value to delete.

Note:	DeleteKey for TRegIniFile overrides the DeleteKey method of TRegistry, from which TRegIniFile is descended. You can access TRegistry's DeleteKey method by casting the call to DeleteKey as type TRegistry.


See also

EraseSection method

DeleteKey method for TRegistry


EraseSection method

See also

Applies to

TRegIniFile object

Declaration

procedure EraseSection(const Section: string);

Description

The EraseSection procedure deletes a key and its data values in the system registry.

Section identifies the key to delete.


See also

DeleteKey method


ReadBool method

See also

Applies to

TRegIniFile object

Declaration

function ReadBool(const Section, Ident: string; Default: Boolean): Boolean;

Description

The ReadBool function retrieves a Boolean value from a specified data value (Ident) associated with a key (Section). If the key does not exist, ReadBool returns a default value (Default).

Section is a string that identifies the key from which to retrieve a data value. Ident is a string that identifies the name of the data value to return. Default is a Boolean value to use if there is no corresponding Section and Ident.

Note:	This function overrides the ReadBool function of TRegistry, from which TRegIniFile is derived. To call the ReadBool function of TRegistry instead of this function, cast the call to ReadBool as TRegistry.


See also

ReadInteger method

ReadString method

ReadSection method

ReadSections method


ReadInteger method

See also

Applies to

TRegIniFile object

Declaration

function ReadInteger(const Section, Ident: string; Default: Longint): Longint;

Description

The ReadInteger function retrieves an integer value from a specified data value (Ident) associated with a key (Section). If the key does not exist, ReadInteger returns a default value (Default).

Section is a string that identifies the key from which to retrieve a data value. Ident is a string that identifies the name of the data value to return. Default is an integer value to use if there is no corresponding Section and Ident.

Note:	This function overrides the ReadInteger function of TRegistry, from which TRegIniFile is derived. To call the ReadInteger function of TRegistry instead of this function, cast the call to ReadInteger as TRegistry.


See also

ReadBool method

ReadString method

ReadSection method

ReadSections method


ReadSection method

See also

Applies to

TRegIniFile object

Declaration

procedure ReadSection(const Section: string; Strings: TStrings);

Description

The ReadSection method retrieves the names of all data values associated with a key, and stores the names in a TString object.

Section is a string identifying the key for which to retrieve data-value names.

Strings specifies the string list object to hold the retrieved names. Strings can point to a TString object, or to a component property, such as Items for a TListBox component, that is a TString object itself.


See also

ReadSectionValues method


ReadSections method

See also

Applies to

TRegIniFile object

Declaration

procedure ReadSections(Strings: TStrings);

Description

ReadSections retrieves the names of all subkeys associated with the current key. Strings specifies the string list object to hold the retrieved key names. Strings can point to a TString object, or to a component property, such as Items for a TListBox component, that is a TString object itself.


See also

CurrentKey method

ReadSection method

ReadSectionValues method


ReadSectionValues method

See also

Applies to

TRegIniFile object

Declaration

procedure ReadSectionValues(const Section: string; Strings: TStrings);

Description

The ReadSectionValues procedure retrieves the data-values associated with a specified key, and stores the retrieved values in a string list object.

Section is the name of the key from which to retrieve data-values. Strings specifies the string list object to hold the retrieved values. Strings can point to a TString object, or to a component property, such as Items for a TListBox component, that is a TString object itself. Use the Values property of the string list object to access a specific string in the list.


See also

ReadSection method

ReadSections method


ReadString method

See also

Applies to

TRegIniFile object

Declaration

function ReadString(const Section, Ident, Default: string): string;

Description

The ReadString function retrieves an integer value from a specified data value (Ident) associated with a key (Section). If the key does not exist, ReadString returns a default value (Default).

Section is a string that identifies the key from which to retrieve a data value. Ident is a string that identifies the name of the data value to return. Default is an integer value to use if there is no corresponding Section and Ident.

Note:	This function overrides the ReadString function of TRegistry, from which TRegIniFile is derived. To call the ReadString function of TRegistry instead of this function, cast the call to ReadString as TRegistry.


See also

ReadBool method

ReadInteger method

ReadSection method

ReadSections method


WriteBool method

See also

Applies to

TRegIniFile object

Declaration

procedure WriteBool(const Section, Ident: string; Value: Boolean);

Description

The WriteBool procedure writes a Boolean value to a specified data value associated with a specified key.

Section is a string identifying the key into which to store a data value. Ident is a string identifying the name of the data value into which to write. Value is the Boolean value to write into the data value.

Note:	This function overrides the WriteBool procedure of TRegistry, from which TRegIniFile is derived. To call the WriteBool procedure of TRegistry instead of this procedure, cast the call to WriteBool as TRegistry.


See also

WriteInteger method

WriteString method


WriteInteger method

See also

Applies to

TRegIniFile object

Declaration

procedure WriteInteger(const Section, Ident: string; Value: Longint);

Description

The WriteInteger procedure writes a long integer value to a specified data value associated with a specified key.

Section is a string identifying the key into which to store a data value. Ident is a string identifying the name of the data value into which to write. Value is the integer value to write into the data value.

Note:	This function overrides the WriteInteger procedure of TRegistry, from which TRegIniFile is derived. To call the WriteInteger procedure of TRegistry instead of this procedure, cast the call to WriteInteger as TRegistry.


See also

WriteBool method

WriteString method


WriteString method

See also

Applies to

TRegIniFile object

Declaration

procedure WriteString(const Section, Ident, Value: string);

Description

The WriteString procedure writes a string value to a specified data value associated with a specified key.

Section is a string identifying the key into which to store a data value. Ident is a string identifying the name of the data value into which to write. Value is the string to write into the data value.

Note:	This function overrides the WriteString procedure of TRegistry, from which TRegIniFile is derived. To call the WriteString procedure of TRegistry instead of this procedure, cast the call to WriteString as TRegistry.


See also

WriteBool method

WriteInteger method