Table of Contents

Class ComponentInstance

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

A component of a form as its designer holds it: a form's root, a control or a menu item, with the properties set on it and the components it contains.

public sealed class ComponentInstance
Inheritance
ComponentInstance
Inherited Members

Remarks

A property that is not set has its class's default (DefaultOf(PropertyDefinition)). Containment is kept in both directions, by SetContainer(ComponentInstance?, int) only, so Container and Contents always agree.

Constructors

ComponentInstance(ComponentClass, string, int?)

Creates an instance of componentClass, with no property set and no container.

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

Parameters

componentClass ComponentClass

The instance's class.

name string

The instance's name.

index int?

The instance's index in its control array, or null when it is not in one.

Exceptions

ArgumentException

name is empty or white space.

Properties

Class

The instance's class.

public ComponentClass Class { get; }

Property Value

ComponentClass

Container

The component this one is placed in, or null for a form's root and for a component placed in none.

public ComponentInstance? Container { get; }

Property Value

ComponentInstance

Contents

The components placed in this one, in the order they were placed (a designer file's order, for a form read from one): controls, which a designer draws in that order, and, for a root or a menu, its menu items.

public IReadOnlyList<ComponentInstance> Contents { get; }

Property Value

IReadOnlyList<ComponentInstance>

Index

The instance's index in its control array, or null when it is not in one.

public int? Index { get; set; }

Property Value

int?

Name

The instance's name, as code refers to it. Every element of a control array has the array's name.

public string Name { get; set; }

Property Value

string

Exceptions

ArgumentException

The name set is empty or white space.

SetValues

The properties set on this instance, with their values.

public IReadOnlyDictionary<PropertyDefinition, object?> SetValues { get; }

Property Value

IReadOnlyDictionary<PropertyDefinition, object>

UnmodelledContents

The components a designer file placed in this one whose class the model does not know, kept as they were read.

public List<UnmodelledComponent> UnmodelledContents { get; }

Property Value

List<UnmodelledComponent>

UnmodelledProperties

The properties a designer file gave this component that its class does not model, kept as they were read.

public List<UnmodelledProperty> UnmodelledProperties { get; }

Property Value

List<UnmodelledProperty>

Methods

Descendants()

Every component in this one's contents, and in theirs, depth first, each component's contents in the order of its Contents.

public IEnumerable<ComponentInstance> Descendants()

Returns

IEnumerable<ComponentInstance>

The descendants of this component, without this component.

GetBoxed(PropertyDefinition)

The value of property, boxed: the value set, the value made from the instance's other properties for a property that has one, or the class's default.

public object? GetBoxed(PropertyDefinition property)

Parameters

property PropertyDefinition

The property.

Returns

object

The property's value.

Remarks

It does not ask whether the instance has the property: see TryGet(PropertyDefinition, out object?).

Exceptions

ArgumentException

The instance's class does not have property.

Get<T>(PropertyDefinition<T>)

The value of property: the value set, the value made from the instance's other properties for a property that has one (a TextBox's SelText), or the class's default.

public T Get<T>(PropertyDefinition<T> property)

Parameters

property PropertyDefinition<T>

The property.

Returns

T

The property's value.

Type Parameters

T

The property's value type.

Remarks

It does not ask whether the instance has the property: see TryGet(PropertyDefinition, out object?).

Exceptions

ArgumentException

The instance's class does not have property.

IsSet(PropertyDefinition)

Whether property is set on this instance, rather than taken from its class's default.

public bool IsSet(PropertyDefinition property)

Parameters

property PropertyDefinition

The property.

Returns

bool

true when the property is set.

Reset(PropertyDefinition)

Clears property, so it has its class's default again.

public bool Reset(PropertyDefinition property)

Parameters

property PropertyDefinition

The property.

Returns

bool

true when the property was set.

SetContainer(ComponentInstance?, int)

Places this component in container, and takes it out of the one it was in.

public void SetContainer(ComponentInstance? container, int index = -1)

Parameters

container ComponentInstance

The new container, or null to take the component out of its container.

index int

Where among the container's contents to place it; a negative index, or one at or past the end, places it last.

Exceptions

InvalidOperationException

The placement is not one a form can hold: a root placed in anything, a menu item placed anywhere but in a root or another menu item, a control placed in a component that holds no controls, a page placed anywhere but in a MultiPage, anything but a page placed in a MultiPage, or a component placed in itself or in its own contents.

Set<T>(PropertyDefinition<T>, T)

Sets property to value.

public ComponentInstance Set<T>(PropertyDefinition<T> property, T value)

Parameters

property PropertyDefinition<T>

The property.

value T

The value.

Returns

ComponentInstance

This instance.

Type Parameters

T

The property's value type.

Remarks

An assignment can set other properties with it: a TextBox's SelText sets its Text, SelStart and SelLength. PropertyChanged is raised for each, once every value of the step is stored, with property as AssignedProperty.

Exceptions

ArgumentException

The instance's class does not have property.

ArgumentNullException

value is null for a property whose assignment sets others, such as SelText.

ToString()

The instance's name, with its index when it is in a control array.

public override string ToString()

Returns

string

The instance's name, such as Command1 or Option1(2).

TryGet(PropertyDefinition, out object?)

The value of property, boxed, where the instance has one.

public bool TryGet(PropertyDefinition property, out object? value)

Parameters

property PropertyDefinition

The property.

value object

The property's value; null where the instance has none.

Returns

bool

false where the class does not have the property, or where the instance's other properties leave it without one: a ComboBox whose style is Dropdown List has no edit box, and no SelStart. VB refuses a program's read of it with 380, Invalid property value.

TrySet(PropertyDefinition, object?)

Sets property to value, when the class has the property, the instance has it, and the property can hold the value.

public bool TrySet(PropertyDefinition property, object? value)

Parameters

property PropertyDefinition

The property.

value object

The value.

Returns

bool

true when the value was set; false, with nothing changed, otherwise. A program's assignment that is refused is VB's 380, Invalid property value.

Remarks

An instance that has no value of the property refuses it (see TryGet(PropertyDefinition, out object?)). The assignment sets other properties as Set<T>(PropertyDefinition<T>, T) does.

Exceptions

ArgumentNullException

value is null for a property whose assignment sets others, such as SelText.

Events

PropertyChanged

Raised after a property is set or reset, whether or not its value differs.

public event EventHandler<ComponentPropertyChangedEventArgs>? PropertyChanged

Event Type

EventHandler<ComponentPropertyChangedEventArgs>