Table of Contents

Class FormDefinition

Namespace
RDCore.Forms.Model
Assembly
RDCore.Forms.dll

A form's designer: its root component, with every control and menu item placed in it, and what the form declares about itself.

public sealed class FormDefinition
Inheritance
FormDefinition
Inherited Members

Remarks

The form's code is not part of its definition. A control's position and size are in pixels (device-independent pixels, 1/96 inch), whatever its container's ScaleMode; a program's code reads them in its own unit (see CodeUnits). A VB Line's ends are in its container's scale: twips, unless its container (a form, a UserControl, a PropertyPage or a PictureBox) has a ScaleMode of its own. The root's own position and size are its client area's, in pixels.

Constructors

FormDefinition(ComponentInstance)

Creates the definition of a form whose root is root.

public FormDefinition(ComponentInstance root)

Parameters

root ComponentInstance

The form's root component: a form, a UserControl or a PropertyPage.

Exceptions

ArgumentException

root is not of a root class, or is placed in a container.

Properties

Components

The form's root, then every component placed in it, depth first in the order the form's file holds them.

public IEnumerable<ComponentInstance> Components { get; }

Property Value

IEnumerable<ComponentInstance>

ControlLibraries

The control libraries the form's file declares, in its order: the ActiveX controls its components may be instances of.

public List<ControlLibraryReference> ControlLibraries { get; }

Property Value

List<ControlLibraryReference>

Controls

The form's controls and menu items as a program's Controls collection holds them: those of the form's file, depth first in its order, then those added at run time, in the order they were added.

public IReadOnlyList<ComponentInstance> Controls { get; }

Property Value

IReadOnlyList<ComponentInstance>

Name

The form's name: its root's.

public string Name { get; }

Property Value

string

Root

The form's root component.

public ComponentInstance Root { get; }

Property Value

ComponentInstance

Methods

AddControl(ComponentClass, string, ComponentInstance?)

Adds a control to the form, as a program's Controls.Add does, and raises ControlAdded.

public ComponentInstance AddControl(ComponentClass type, string name, ComponentInstance? container = null)

Parameters

type ComponentClass

The control's class.

name string

The control's name.

container ComponentInstance

The component to place it in: the root, or a container control of the form. null places it in the root.

Returns

ComponentInstance

The control added.

Remarks

The control is placed last in its container, so that it is under the controls already there. It is hidden, at 0, 0, and 80 by 32 pixels (1200 by 480 twips) where its class has an extent. Its TabIndex, where its class has one, is the next after the form's others. Its other properties have their class's defaults, so that a caption or a text is "".

A page is shown, as a MultiPage shows its selected page. A MultiPage starts with two pages, captioned as they are named: Page1 and Page2, or the next names no component of the form has.

Any other name is accepted, even one that starts with a digit, holds a space, is a keyword, or is the form's own name.

Exceptions

FormErrorException

type is a menu's or a root's class: 720, not a valid control type. name is empty or white space: 728, not a legal control name. A component of the form other than its root has the name, compared without regard to case: 727. container holds no controls, or none of the class: 721, not a valid control container. A page goes in a MultiPage only, and a MultiPage holds pages only (CanHold(ComponentClass, ComponentClass)).

ArgumentException

container is not a component of this form.

AddControl(string, string, ComponentInstance?)

Adds a control of an RDForms class to the form, as a program's Controls.Add does: the class named by its ProgID, such as RDForms.CommandButton, without regard to case.

public ComponentInstance AddControl(string progId, string name, ComponentInstance? container = null)

Parameters

progId string

The class's ProgID.

name string

The control's name.

container ComponentInstance

The component to place it in: the root, or a container control of the form. null places it in the root.

Returns

ComponentInstance

The control added.

Exceptions

FormErrorException

No RDForms class has that ProgID: 711, Invalid class string. Otherwise as AddControl(ComponentClass, string, ComponentInstance?).

ArgumentException

container is not a component of this form.

ArrayOf(string)

The form's control array of a name, the name compared without regard to case: the controls of that name that have an index. Menu items are in menu arrays (ArrayOf(string)).

public FormControlArray? ArrayOf(string name)

Parameters

name string

The array's name.

Returns

FormControlArray

The array, the same object each time; null when no control of that name has an index.

Copy()

Makes a copy of the form, which has components of its own: each one a copy of one of this form's, with its class, name, index, the values set on it and what it keeps as text, in the same container at the same place. A copy of a control added at run time is one the copy added at run time. The copy declares the same control libraries.

public FormDefinition Copy()

Returns

FormDefinition

The copy. A change to it, or to one of its components, leaves this form as it is, and the other way round.

Remarks

Each UserControl a form places has a copy of its UserControl's definition, so that its controls are its own.

Find(string, int?)

The form's component of a given name and control-array index, the name compared without regard to case.

public ComponentInstance? Find(string name, int? index = null)

Parameters

name string

The component's name.

index int?

The component's index in its control array, or null for a component not in one.

Returns

ComponentInstance

The component, or null when the form has none of that name and index.

IsAddedAtRunTime(ComponentInstance)

Whether a component was added by AddControl(ComponentClass, string, ComponentInstance?) and not removed since.

public bool IsAddedAtRunTime(ComponentInstance component)

Parameters

component ComponentInstance

The component.

Returns

bool

true for a control added at run time.

RemoveControl(ComponentInstance)

Takes a control added at run time out of the form, with the controls it holds, as a program's Controls.Remove does, and raises ControlRemoved.

public void RemoveControl(ComponentInstance control)

Parameters

control ComponentInstance

The control.

Remarks

The form's other TabIndex values close up over those taken out, so that they run on from 0 with no gap.

Exceptions

FormErrorException

The control is not one of the form's: 730, Control not found. It was not added at run time, or is an element of a control array, even one a program's Load added: 729. It holds a control that was not added at run time: 740. Nothing is removed.

RemoveControl(string)

Removes the control that has a name, as a program's Controls.Remove does with a name.

public void RemoveControl(string name)

Parameters

name string

The control's name, compared without regard to case.

Exceptions

FormErrorException

The form has no control of that name: 730, Control not found. The name is a control array's: -2147467262 (&H80004002), No such interface supported. Otherwise as RemoveControl(ComponentInstance).

RenameControl(ComponentInstance, string)

Renames a control, as a program's assignment of its Name does on an RDForms form. Microsoft Forms 2.0 lets a program rename a control it added (AddControl(ComponentClass, string, ComponentInstance?)), and no other.

public void RenameControl(ComponentInstance control, string name)

Parameters

control ComponentInstance

The control.

name string

Its new name. Any name, as Microsoft Forms 2.0 takes it: one taken, one that is not a legal control name, or none.

Remarks

The control is then found by its new name, not by its old one.

Exceptions

FormErrorException

The control is not one of the form's: 730, Control not found. It is one of the form's file, or an element of a control array: 382, "Could not set the Name property. Can not set property at runtime.", as Microsoft Forms 2.0 says it. Its name stays.

ArgumentNullException

control or name is null.

SetContainer(ComponentInstance, ComponentInstance?)

Places a control in another container of the form, with the controls it holds, as a program's Set Control.Container does, and raises ContainerChanged.

public void SetContainer(ComponentInstance control, ComponentInstance? container)

Parameters

control ComponentInstance

The control: one of the form's, whose class HasContainer.

container ComponentInstance

The container: the root, or a control of the form that holds controls.

Remarks

The control keeps its place in pixels in its container's client area, so a program reads its Left and Top in the new container's scale, and the ends of a Line are given again in that scale. It is placed last in the new container's Contents, even where that is the container it was in. Its Visible and every TabIndex are as they were, and a control added at run time can still be removed.

Exceptions

FormErrorException

425, Invalid object use, and nothing changes: container is null, is not the root or a control of this form, holds no controls or none of the control's class (CanHold(ComponentClass, ComponentClass): a page goes in a MultiPage only, and a MultiPage holds pages only), or is control or a control it holds.

ArgumentException

control is not a control of this form, or its class has no Container.

Events

ContainerChanged

Raised after SetContainer(ComponentInstance, ComponentInstance?) places a control, with what it holds, in a container.

public event EventHandler<FormContainerChangedEventArgs>? ContainerChanged

Event Type

EventHandler<FormContainerChangedEventArgs>

ControlAdded

Raised after AddControl(ComponentClass, string, ComponentInstance?) places a control in the form, and after Load(int) loads an element of a control array.

public event EventHandler<FormControlEventArgs>? ControlAdded

Event Type

EventHandler<FormControlEventArgs>

ControlRemoved

Raised after RemoveControl(ComponentInstance) takes a control, and what it holds, out of the form.

public event EventHandler<FormControlEventArgs>? ControlRemoved

Event Type

EventHandler<FormControlEventArgs>