Navigation: TextEd > Extension and Scripts > Visual components >

TForm

 

 

 

A form can represent the application's main window, dialog boxes, or MDI children. A form can contain other objects, such as TButton, TCheckBox, and TComboBox objects.


In all examples we assume a form has been created and is named "form".


TForm form = new TForm(nil);

 


Properties



 

property TWinControl ActiveControl;

Specifies the control that has focus on the form.

 

Ex. form.ActiveControl.Left = 10;

 

 

property TAlign Align;

Determines how the control aligns within its container (parent control).

 

enum TAlign {

  alNone,

  alTop,

  alBottom,

  alLeft,

  alRight,

  alClient,

  alCustom

};

 

Ex. form.Align = alClient;


 

property TAnchors Anchors;

Specifies how the control is anchored to its parent.

 

enum TAnchorKind {

  akLeft,

  akTop,

  akRight,

  akBottom

};


Ex. form.Anchors = akLeft+akTop+akRight+akBottom;


 

property Bool AutoScroll;

Indicates whether scroll bars appear automatically on the scrolling windowed control if it is not large enough to display all of its controls.


 

property Bool AutoSize;

Specifies whether the control sizes itself automatically to accommodate its contents.


 

property TFormBorderStyle BorderStyle;

Specifies the appearance and behavior of the form border.

 

enum TFormBorderStyle {

  bsNone,

  bsSingle,

  bsSizeable,

  bsDialog,

  bsToolWindow,

  bsSizeToolWin

};

 

Ex. form.BorderStyle = bsDialog;


 

property Int BorderWidth;

Specifies the width of the control's border.


 

property String Caption;

Specifies a text string that identifies the control to the user.  It can be the text label of a radio button or the title text in a form. To underline a character in a Caption, include an ampersand (&) before the character.


 

property Int ClientHeight;

Specifies the height (in pixels) of the form's client area.


 

property Int ClientWidth;

Specifies the width (in pixels) of the form's client area.


 

property TColor Color;

Specifies the background color of the control. The color value can be an hexadecimal or a color constant.


 

Defined color constants are:

clAqua, clBlack, clBlue, clCream, clDkGray, clFuchsia, clGray, clGreen, clLime, clLtGray, clMaroon, clMedGray, clMoneyGreen, clNavy, clOlive, clPurple, clRed, clSilver, clSkyBlue, clTeal, clWhite, clYellow.


 

Defined system color constants:

clNone                     White on Windows 9x, Black on NT.

clScrollBar                Current color for the of scroll bar track.

clBackground               Current background color of the Windows desktop

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 or NT 4.0 only: Dark shadow for three-dimensional display elements

cl3DLight                  Windows 95 or NT 4.0 only: Light color for three-dimensional display elements (for edges facing the light source)

clInfoText                 Windows 95 or NT 4.0 only: Text color for tool tip controls

clInfoBk                   Windows 95 or NT 4.0 only: Background color for tool tip controls

clGradientActiveCaption    Windows 98 or Windows 2000: Right side color in the color gradient of an active window's title bar.

clActiveCaption            specifies the left side color.

clGradientInactiveCaption  Windows 98 or Windows 2000: Right side color in the color gradient of an inactive window's title bar. clInactiveCaption          specifies the left side color.

clDefault                  The default color for the control to which the color is assigned.

 

Ex. form.Color = 0x0000FF00;

Ex. form.Color = clGreen;


 

property Bool Enabled;

Controls whether the control responds to mouse, keyboard, and timer events.


 

property TFont Font;

Controls the attributes of text written on or in the control. To change to a new font, specify a new TFont object. To modify a font, change the value of the Charset, Color, Height, Name, Pitch, Size, or Style of the TFont object.

 

Ex. form.Font.Size = 12;


 

property TFormStyle FormStyle;

Determines the form's style.

 

enum TFormStyle {

  fsNormal,

  fsMDIChild,

  fsMDIForm,

  fsStayOnTop

};

 

Ex. form.FormStyle = fsNormal;


 

property int Height;

Specifies the vertical size of the control in pixels.

 

Ex. form.Height = 400;


 

property String Hint;

Contains the text string that can appear when the user moves the mouse over the control.


 

property TControlScrollBar HorzScrollBar;

Represents the horizontal scroll bar for the scrolling windowed control. Use HorzScrollBar to hide, show, or manipulate the horizontal scroll bar for the scrolling windowed control.


 

property TIcon Icon;

Specifies the icon that appears when the form is minimized.


Ex. form.Icon.LoadFronFile("MyIcon.ICO");


 

property Bool KeyPreview;

Specifies whether the form should receive keyboard events before the active control.

If KeyPreview is true, keyboard events occur on the form before they occur on the active control.

If KeyPreview is false, keyboard events occur only on the active control.


 

property int Left;

Specifies the horizontal coordinate of the left edge of a component relative to its parent.


 

property TMargins Margins;

Specifies the margins for the control. TMargins help define the relative position between components on a form, and between the edges of the form and the component. For example, when you set a left margin for a component to 10 pixels, the component will not come closer than 10 pixels to the edge of the container, or to another component on the left edge. The number of pixels by which two components are separated is the sum of the pixels of both components.

TMargins have the class members top, bottom, left and right.

 

Ex. form.Margins.Left = 10;


 

property TMainMenu Menu;

Specifies the form's main menu, if any.


 

property String Name;

Specifies the name of the component as referenced in code.


 

property TPadding Padding;

Specifies the padding of a control. Padding works similar to margins.

 

Ex. form.Padding.Left = 10;


 

property Bool ParentFont;

Determines where a control looks for its font information.

To have a control use the same font as its parent control, set ParentFont to true. If ParentFont is false, the control uses its own Font property.


 

property Int PixelsPerInch;

Represents the proportion of the font on the system on which the form was designed. Use PixelsPerInch at runtime to change how the form is scaled to the current screen resolution. If PixelsPerInch is changed from its default value, the form will not have the same proportion on every screen resolution.

The form's Scaled property must be true for PixelsPerInch to have an effect.


 

property TPopupMenu PopupMenu;

Identifies the pop-up menu associated with the control.


 

property TPosition Position;

Represents the size and placement of the form.

 

Position can have one of the following TPosition values:

 

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 the operating system. Each time you run the application, the form moves slightly down and to the right.

 

poDefaultPosOnly 

The form displays with the size you created it at design time, but the operating system chooses its position on the screen. Each time you run the application, the form moves slightly down and to the right.

 

poDefaultSizeOnly 

The form appears in the position you left it at design time, but the operating system chooses its size.

 

poScreenCenter 

The form remains the size you left it at design time, but is positioned in the center of the screen.

 

poDesktopCenter 

The form remains the size you left it at design time, but is positioned in the center of the screen.

 

poMainFormCenter 

The form remains the size you left it at design time, but is positioned in the center of the application's main form. This position should only be used with secondary forms. If set for a main form, it acts like poScreenCenter.

 

poOwnerFormCenter 

The form remains the size you left it at design time, but is positioned in the center of the form specified by the Owner property. If the Owner property does not specify a form, this position acts like poMainFormCenter.

 

Ex. form2.Position = poMainFormCenter;


 

property Bool Scaled;

Specifies whether the form is sized according to the value of the PixelsPerInch property.


 

property Bool ScreenSnap;

Specifies whether form snaps to edge of screen.


 

property Bool ShowHint;

Determines whether the control displays a Help Hint when the mouse pointer rests momentarily on the control.


 

property int SnapBuffer;

Specifies distance for screen snap. If ScreenSnap is true, SnapBuffer determines the maximum number of pixels that be between the form edge and the screen edge before the form snaps to the screen edge.


 

property int Tag;

Stores an integer value as part of a component.


 

property int Top;

Specifies the Y coordinate of the top left corner of a control, relative to its parent or containing control in pixels.


 

property Bool TransparentColor;

Specifies whether a color on the form appears transparent. Use TransparentColor to indicate that one of the colors on the form should be treated as transparent, allowing windows behind the form to completely show through. The TransparentColorValue property indicates the color that appears completely transparent.


 

property TColor TransparentColorValue;

Indicates the color on the form that appears transparent when TransparentColor is true.


 

property TControlScrollBar VertScrollBar;

Represents the vertical scroll bar for the scrolling windowed control. Use VertScrollBar to hide, show, or manipulate the vertical scroll bar for the scrolling windowed control.


 

property Boolean Visible;

Indicates whether the form is visible.


 

property int Width;

Specifies the horizontal size of the control or form in pixels.


 

property TWindowState WindowState;

Represents how the form appears on the screen. Set WindowState to minimize, maximize, or restore the form window. Read WindowState to determine whether the form is minimized, maximized, or in a normal state.

 

enum TWindowState {

  wsNormal,

  wsMinimized,

  wsMaximized

};


 


Methods



 

constructor Create(TComponent AOwner) 

Creates and initializes a new TForm object.


Ex. TForm form = TForm.Create(nil);

Ex. TForm form = new TForm(nil);


 

procedure Free;

Destroys an object and frees its associated memory, if necessary.


Ex.

TForm form2 = new TForm(nil);

...

form2.Free;


 

procedure Close;

Closes the form.

When the main form of the application closes, the application terminates.


 

procedure Hide;

Hides the form.


 

procedure Show;

Shows the form. Use Show to set the form's Visible property to true and to bring the form to the front of other forms on the screen.


 

function int ShowModal();

Shows a form as a modal dialog. Use ShowModal to show a form as a modal form. A modal form is one where the application can't continue to run until the form is closed. Thus, ShowModal does not return until the form closes. When the form closes, it returns the value of the ModalResult property.


The return value can be one of the following:

 

mrNone, mrOk, mrCancel, mrAbort, mrRetry, mrIgnore, mrYes, mrNo, mrAll, mrNoToAll, mrYesToAll  


 


Events



 

OnActivate 

Occurs when the form becomes active.


Ex.

 

TForm form;

void FormActivate(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnActivate = &FormActivate;

}


 

OnClick 

Occurs when the user clicks the control.

 

Ex.

 

TForm form;

void FormClick(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnClick = &FormClick;

}


 

OnClose 

Occurs when the form closes.

 

Ex.

 

TForm form;

void FormClose(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnClose = &FormClose;

}


 

OnCloseQuery 

Occurs when close is attempted.

 

Ex.

 

TForm form;

void FormCloseQuery(TObject Sender, bool &CanClose)

{

  // Do some work here

  CanClose = true; // Allow the form to close

}

 

{

  form = new TForm(nil);

  form.OnCloseQuery = &FormCloseQuery;

}

 

 

OnCreate 

Occurs when the form is created.


Ex.

 

TForm form;

void FormCreate(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnCreate = &FormCreate;

}


 

OnDblClick 

Occurs when the user double-clicks the left mouse button when the mouse pointer is over the control.

 

Ex.

 

TForm form;

void FormDblClick(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnDblClick = &FormDblClick;

}

 

 

OnDeactivate 

Occurs when the form loses focus.

 

Ex.

 

TForm form;

void FormDeactivate(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnDeactivate = &FormDeactivate;

}


 

OnDestroy 

Occurs when the form is destroyed.


Ex.

 

TForm form;

void FormDestroy(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnDestroy = &FormDestroy;

}


 

OnHide 

Occurs when the form is hidden (that is, when its Visible property is set to false).

 

Ex.

 

TForm form;

void FormHide(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnHide = &FormHide;

}


 

OnKeyDown 

Occurs when a user presses any key while the control has focus.


(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;

 

Ex.

 

TForm form;

void FormKeyDown(TObject Sender, WORD &Key, TShiftState Shift)

{

  // Do some work here

  if (Key == VK_F1) {

    // F1 was pressed, lets do something...

 

  }

}

 

{

  form = new TForm(nil);

  form.KeyPreview = true;

  form.OnKeyDown = &FormKeyDown;

}


 

OnKeyPress 

Occurs when a key is pressed.

 

Ex.

 

TForm form;

void FormKeyPress(TObject Sender, char &Key)

{

  // Do not allow numbers

  if ((Key >= 48) && (Key <= 57)) {

    Key = 0;

  }

}

 

{

  form = new TForm(nil);

  form.OnKeyPress = &FormKeyPress;

}


 

OnKeyUp 

Occurs when the user releases a key that has been pressed.

 

(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;


Ex.

 

TForm form;

void FormKeyUp(TObject Sender, WORD &Key, TShiftState Shift)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnKeyUp = &FormKeyUp;

}


 

OnMouseDown 

Occurs when the user presses a mouse button with the mouse pointer over a control.

 

(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;

 

enum TMouseButton {

  mbLeft,

  mbRight,

  mbMiddle

};


Ex.

 

TForm form;

void FormMouseDown(TObject Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  // Do some work here if left mouse button was pressed

  if (Button == mbLeft) {

    // Left mouse button was pressed. Lets do something...

 

  }

}

 

{

  form = new TForm(nil);

  form.OnMouseDown = &FormMouseDown;

}


 

OnMouseEnter 

Occurs when the user moves the mouse into a control.

 

Ex.

 

TForm form;

void FormMouseEnter(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnMouseEnter = &FormMouseEnter;

}


 

OnMouseLeave 

Occurs when the user moves the mouse outside of a control.

 

Ex.

 

TForm form;

void FormMouseLeave(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnMouseLeave = &FormMouseLeave;

}


 

OnMouseMove 

Occurs when the user moves the mouse pointer while the mouse pointer is over a control.

 

Ex.

 

int FMouseX,FMouseY;

TForm form;

void FormMouseMove(TObject Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  // Do some work here

  FMouseX = X;

  FMouseY = Y;

}

 

{

  form = new TForm(nil);

  form.OnMouseMove = &FormMouseMove;

}


 

OnMouseUp 

Occurs when the user releases a mouse button that was pressed with the mouse pointer over a component.

 

Ex.

 

TForm form;

void FormMouseUp(TObject Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnMouseUp = &FormMouseUp;

}


 

OnMouseWheel 

Occurs when the mouse wheel is rotated. Write code in the OnMouseWheel event handler to respond to mouse wheel messages. If there is no OnMouseWheel event handler, or if the mouse wheel message is not handled in the OnMouseWheel event handler, then an OnMouseWheelUp or OnMouseWheelDown event occurs, depending on the direction the mouse wheel was rotated.

 

(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;

 

struct TPoint {

  int X;

  int Y;

};

 

Ex.

 

TForm form;

void FormMouseWheel(TObject Sender, TShiftState Shift, int WheelDelta, TPoint MousePos, bool &Handled)

{

  // Do some work here

  if ((MousePos.X > form.Left) && (MousePos.Y > form.Top) && (WheelDelta > 3)) { 

    // Do some work

    Handled = true; // We have handled the message

  }

}

 

{

  form = new TForm(nil);

  form.OnMouseWheel = &FormMouseWheel;

}

 

 

OnMouseWheelDown 

Occurs when the mouse wheel is rotated downward. Write code in the OnMouseWheelDown event handler to perform actions when the mouse wheel is rotated downward. OnMouseWheelDown occurs only if the message is not already handled in an OnMouseWheel event handler.


Ex.

 

TForm form;

void FormMouseWheelDown(TObject Sender, TShiftState Shift, TPoint MousePos, bool &Handled)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnMouseWheelDown = &FormMouseWheelDown;

}


 

OnMouseWheelUp 

Occurs when the mouse wheel is rotated upward. Write code in the OnMouseWheelUp event handler to perform actions when the mouse wheel is rotated upward. OnMouseWheelUp occurs only if the message is not already handled in an OnMouseWheel event handler.

 

Ex.

 

TForm form;

void FormMouseWheelUp(TObject Sender, TShiftState Shift, TPoint MousePos, bool &Handled)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnMouseWheelUp = &FormMouseWheelUp;

}


 

OnPaint 

Occurs when the form is redrawn.


Ex.

 

TForm form;

void FormPaint(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnPaint = &FormPaint;

}


 

OnResize 

Occurs immediately after the control is resized.

 

Ex.

 

TForm form;

void FormResize(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnResize = &FormResize;

}


 

OnShow 

Occurs when the form is shown (that is, when its Visible property is set to true).

 

Ex.

 

TForm form;

void FormShow(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

  form.OnShow = &FormShow;

}


 


 


 


 


 


 

 

 

 

 

Copyright © 2022 Rickard Johansson