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
rootComponentInstanceThe form's root component: a form, a UserControl or a PropertyPage.
Exceptions
- ArgumentException
rootis 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
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
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
Name
The form's name: its root's.
public string Name { get; }
Property Value
Root
The form's root component.
public ComponentInstance Root { get; }
Property Value
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
typeComponentClassThe control's class.
namestringThe control's name.
containerComponentInstanceThe 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
typeis a menu's or a root's class: 720, not a valid control type.nameis 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.containerholds 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
containeris 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
progIdstringThe class's ProgID.
namestringThe control's name.
containerComponentInstanceThe 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
containeris 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
namestringThe 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
namestringThe component's name.
indexint?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
componentComponentInstanceThe component.
Returns
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
controlComponentInstanceThe 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
Loadadded: 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
namestringThe 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
controlComponentInstanceThe control.
namestringIts 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
controlornameis 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
controlComponentInstanceThe control: one of the form's, whose class HasContainer.
containerComponentInstanceThe 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:
containeris 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 iscontrolor a control it holds.- ArgumentException
controlis not a control of this form, or its class has noContainer.
Events
ContainerChanged
Raised after SetContainer(ComponentInstance, ComponentInstance?) places a control, with what it holds, in a container.
public event EventHandler<FormContainerChangedEventArgs>? ContainerChanged
Event Type
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
ControlRemoved
Raised after RemoveControl(ComponentInstance) takes a control, and what it holds, out of the form.
public event EventHandler<FormControlEventArgs>? ControlRemoved