Class ReportDetail

Instances of this class are generic report details, with labels and formats for printing them.

Inheritance

System.Object

ReportDetail

Namespace: WizardWrx

Assembly: WizardWrx.Core.dll

Syntax

public class ReportDetail : System.IComparable

Constructors

ReportDetail()

The default constructor creates an empty ReportDetail.

Declaration

public ReportDetail()

ReportDetail(String)

Create a ReportDetail, and set its Label property.

Declaration

public ReportDetail(string label)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.

ReportDetail(String, Object)

Create a ReportDetail, and set its Label and Value properties.

Declaration

public ReportDetail(string label, object pobjValue)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	pobjValue	Initial data value, as an Object, which MAY be a null reference.

ReportDetail(String, Object, String)

Create a ReportDetail, and set its Label. native value, and DisplayValue properties.

Declaration

public ReportDetail(string label, object pobjValue, string displayvalue)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	pobjValue	Initial data value, as an Object, which MAY be a null reference.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.

ReportDetail(String, Object, String, ReportDetail.ItemDisplayOrder)

Create a ReportDetail, and set its Label. native value, DisplayValue, and DisplayOrder properties.

Declaration

public ReportDetail(string label, object pobjValue, string displayvalue, ReportDetail.ItemDisplayOrder itemdisplayorder)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	pobjValue	Initial data value, as an Object, which MAY be a null reference.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.

ReportDetail(String, Object, String, ReportDetail.ItemDisplayOrder, String)

Create a ReportDetail, and set its Label. native value, DisplayValue, DisplayOrder, and DisplayFormat properties.

Declaration

public ReportDetail(string label, object pobjValue, string displayvalue, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	pobjValue	Initial data value, as an Object, which MAY be a null reference.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.

ReportDetail(String, Object, String, ReportDetail.ItemDisplayOrder, String, Object[])

Create a ReportDetail, and set its Label. native value, DisplayValue, DisplayOrder, DisplayFormat, and SupplementaryDetails properties.

Declaration

public ReportDetail(string label, object pobjValue, string displayvalue, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat, object[] supplementarydetails)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	pobjValue	Initial data value, as an Object, which MAY be a null reference.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.
System.Object[]	supplementarydetails	Override the default SupplementaryDetails property.

ReportDetail(String, Object, ReportDetail.ItemDisplayOrder)

Create a ReportDetail, and set its Label and Value properties.

Declaration

public ReportDetail(string label, object value, ReportDetail.ItemDisplayOrder itemdisplayorder)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	value	Initial data value, as an Object, which MAY be a null reference.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.

ReportDetail(String, Object, ReportDetail.ItemDisplayOrder, String)

Create a ReportDetail, and set its Label, Value, DisplayOrder, and DisplayFormat properties.

Declaration

public ReportDetail(string label, object value, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	value	Initial data value, as an Object, which MAY be a null reference.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.

ReportDetail(String, Object, ReportDetail.ItemDisplayOrder, String, Object[])

Create a ReportDetail, and set its Label, Value, DisplayOrder, DisplayFormat, and SupplementaryDetails properties.

Declaration

public ReportDetail(string label, object value, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat, object[] supplementarydetails)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.Object	value	Initial data value, as an Object, which MAY be a null reference.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.
System.Object[]	supplementarydetails	Override the default SupplementaryDetails property.

ReportDetail(String, String)

Create a ReportDetail, and set its Label and DisplayValue properties.

Declaration

public ReportDetail(string label, string displayvalue)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.

ReportDetail(String, String, ReportDetail.ItemDisplayOrder)

Create a ReportDetail, and set its Label and DisplayValue properties.

Declaration

public ReportDetail(string label, string displayvalue, ReportDetail.ItemDisplayOrder itemdisplayorder)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.

ReportDetail(String, String, ReportDetail.ItemDisplayOrder, String)

Create a ReportDetail, and set its Label, DisplayValue, DisplayOrder, and DisplayFormat properties.

Declaration

public ReportDetail(string label, string displayvalue, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.

ReportDetail(String, String, ReportDetail.ItemDisplayOrder, String, Object[])

Create a ReportDetail, and set its Label, DisplayValue, DisplayOrder, DisplayFormat, and SupplementaryDetails properties.

Declaration

public ReportDetail(string label, string displayvalue, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat, object[] supplementarydetails)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
System.String	displayvalue	Initial string representation of data value, which MAY be a null reference or an empty string.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.
System.Object[]	supplementarydetails	Override the default SupplementaryDetails property.

ReportDetail(String, ReportDetail.ItemDisplayOrder)

Create a ReportDetail, and set its Label and DisplayOrder properties.

Declaration

public ReportDetail(string label, ReportDetail.ItemDisplayOrder itemdisplayorder)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.

ReportDetail(String, ReportDetail.ItemDisplayOrder, String)

Create a ReportDetail, and set its Label, DisplayOrder, and DisplayFormat, and SupplementaryDetails properties.

Declaration

public ReportDetail(string label, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.

ReportDetail(String, ReportDetail.ItemDisplayOrder, String, Object[])

Create a ReportDetail, and set its Label, DisplayOrder, DisplayFormat properties.

Declaration

public ReportDetail(string label, ReportDetail.ItemDisplayOrder itemdisplayorder, string displayformat, object[] supplementarydetails)

Parameters

Type	Name	Description
System.String	label	Initial value for label, which can be neither null, nor empty.
ReportDetail.ItemDisplayOrder	itemdisplayorder	DisplayOrder must be greater than zero.
System.String	displayformat	Override the default DisplayFormat property.
System.Object[]	supplementarydetails	Override the default SupplementaryDetails property.

Fields

DEFAULT_FORMAT

Use this format for reports, unless the caller overrides it.

Declaration

public const string DEFAULT_FORMAT = null

Field Value

Type	Description
System.String

RETURN_ON_INVALID_STATE

When the FormatDetail method is called before the object is fully initialized, return an error message. Since the returned value is expected to go into a file of some kind (which may be a print file), this is a much cheaper way of handling the exception. However, as is almost always true, there is a cost, because throwing an exception typically causes the application to return a nonzero exit code, but writing it into a file yields an exit code of zero.

Declaration

public const bool RETURN_ON_INVALID_STATE = null

Field Value

Type	Description
System.Boolean

THROW_ON_INVALID_STATE

When the FormatDetail method is called before the object is fully initialized, throw an System.InvalidOperationException exception.

Declaration

public const bool THROW_ON_INVALID_STATE = null

Field Value

Type	Description
System.Boolean

Properties

DetailFormat

This property gives read/write access to the DetailFormat property, a string that is shared by all instances. See remarks for critical information.

Declaration

public static string DetailFormat { get; set; }

Property Value

Type	Description
System.String

Remarks

The first two format items, {0} and {1}, are reserved for the label and value properties. Additional format items, if any, may be filled from the DetailFormatItems array.

DetailFormatItems

This property gives read/write access to the DetailFormatItems property, an array of Objects that is shared by all instances. See remarks for critical information.

Declaration

public static object[] DetailFormatItems { get; set; }

Property Value

Type	Description
System.Object[]

Remarks

The first two format items, {0} and {1}, are reserved for the label and value properties. Additional format items, if any, may be filled from this array.

The instance message formatter takes items from this array as needed to fill the remaining format items.

DetailState

Report on the state of the instance, for evaluating its readiness for use on a report.

Declaration

public ReportDetail.State DetailState { get; }

Property Value

Type	Description
ReportDetail.State

DisplayFormat

Get or set the default format string to use with the label and value to display an item on a report. See remarks for critical information.

Declaration

public string DisplayFormat { get; set; }

Property Value

Type	Description
System.String

Remarks

The first three format items, {0}, {1}, and {2} are reserved for the label, value, and item number. Additional format items, if any, are populated from the objects in the SupplementaryDetails array.

The FormatDetail method creates a new object array with enough room to hold the SupplementaryDetails array, plus three, fills it by inserting the label, value, and item number into the first three slots, and appending the SupplementaryDetails array, if it exists, and passes the whole array to string.Format.

Unless its value differs from the current static (default) value, this property stays NULL. When callers query this property, the static property is returned if the instance property is null. Hence, the property behaves like a instance property, without wasting space to store duplicates of the default value. Hence, output routines need not check both properties.

DisplayOrder

Get or set the unsigned integer that determines the order in which this item is returned from a sorted collection.

Declaration

public ReportDetail.ItemDisplayOrder DisplayOrder { get; set; }

Property Value

Type	Description
ReportDetail.ItemDisplayOrder

DisplayValue

Get or set the string representation of data value, which MAY be a null reference or an empty string.

Declaration

public string DisplayValue { get; set; }

Property Value

Type	Description
System.String

Label

New value for label, which can be neither null, nor empty.

Declaration

public string Label { get; set; }

Property Value

Type	Description
System.String

SupplementaryDetails

This property gives read/write access to the SupplementaryDetails property, an array of Objects for use with the DisplayFormat property. See remarks for critical information.

Declaration

public object[] SupplementaryDetails { get; set; }

Property Value

Type	Description
System.Object[]

See Also

DisplayFormat

ThrowOnInvalidState

The state of this flag determines what happens when FormatDetail is called when the object is partially initialized.

The default action, False (RETURN_ON_INVALID_STATE) is the behavior originally programmed into it.

When set to True, (THROW_ON_INVALID_STATE), the message that would have been returned becomes the Message property of an System.InvalidOperationException exception.

Declaration

public static bool ThrowOnInvalidState { get; set; }

Property Value

Type	Description
System.Boolean

Value

Gets or sets the data value, as an Object, which MAY be a null reference.

Please see Remarks for important details.

Declaration

public object Value { get; set; }

Property Value

Type	Description
System.Object

Remarks

To make the class a tad more robust, if the rhe property is null, the DisplayValue is returned, unless it is also null. This gets around an ambiguity that causes the constructor to put a String into the DisplayValue property, unless it is downcast to Object.

Methods

FormatDetail()

Return a formatted detail record, ready to print.

Declaration

public string FormatDetail()

Returns

Type	Description
System.String	The return value is a formatted string, if a label and value are present. Otherwise, an error message is returned for printing.

FormatDetail(Int32)

Return a formatted detail record, ready to print.

Declaration

public string FormatDetail(int pintWidthOfWidestLabel)

Parameters

Type	Name	Description
System.Int32	pintWidthOfWidestLabel	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestLabel property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.

Returns

Type	Description
System.String	The return value is a string that can be fed directly to a WriteLine method.

FormatDetail(Int32, UInt32)

Return a formatted detail record, ready to print.

Declaration

public string FormatDetail(int pintWidthOfWidestLabel, uint puintTotalitems)

Parameters

Type	Name	Description
System.Int32	pintWidthOfWidestLabel	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestLabel property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.
System.UInt32	puintTotalitems	Specify the total number of items in the list, which becomes part of the third format item, {2}, in the detail item format string.

Returns

Type	Description
System.String	The return value is a string that can be fed directly to a WriteLine method.

FormatDetail(UInt32)

Return a formatted detail record, ready to print.

Declaration

public string FormatDetail(uint puintWidthOfWidestLabel)

Parameters

Type	Name	Description
System.UInt32	puintWidthOfWidestLabel	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestLabel property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.

Returns

Type	Description
System.String	The return value is a string that can be fed directly to a WriteLine method.

FormatDetail(UInt32, UInt32)

Return a formatted detail record, ready to print.

Declaration

public string FormatDetail(uint puintWidthOfWidestLabel, uint puintTotalitems)

Parameters

Type	Name	Description
System.UInt32	puintWidthOfWidestLabel	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestLabel property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.
System.UInt32	puintTotalitems	Specify the total number of items in the list, which becomes part of the third format item, {2}, in the detail item format string.

Returns

Type	Description
System.String	The return value is a string that can be fed directly to a WriteLine method.

GetPaddedLabel(Int32)

Return a padded label string.

Declaration

public string GetPaddedLabel(int pintWidthOfWidestLabel)

Parameters

Type	Name	Description
System.Int32	pintWidthOfWidestLabel	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestLabel property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.

Returns

Type	Description
System.String	If this instance has a label, pad it as indicated, otherwise, behave as if FormatDetail got the call.

GetPaddedLabel(UInt32)

Return a padded label string.

Declaration

public string GetPaddedLabel(uint puintWidthOfWidestLabel)

Parameters

Type	Name	Description
System.UInt32	puintWidthOfWidestLabel	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestLabel property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.

Returns

Type	Description
System.String	If this instance has a label, pad it as indicated, otherwise, behave as if FormatDetail got the call.

GetPaddedValue(Int32, FormatItem.Alignment, String)

Return an aligned field item string.

Declaration

public string GetPaddedValue(int pintWidthOfWidestValue, FormatItem.Alignment penmAlignment, string pstrFormatString)

Parameters

Type	Name	Description
System.Int32	pintWidthOfWidestValue	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestValue property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.
FormatItem.Alignment	penmAlignment	Specify Left or Right. Format items, per se, don't support center alignment.
System.String	pstrFormatString	Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.

Returns

Type	Description
System.String	The returned string is ready to insert into a complete format string for use with string.Format, Console.WriteLine, and their numerous cousins.

GetPaddedValue(UInt32, FormatItem.Alignment, String)

Return an aligned field item string.

Declaration

public string GetPaddedValue(uint puintWidthOfWidestValue, FormatItem.Alignment penmAlignment, string pstrFormatString)

Parameters

Type	Name	Description
System.UInt32	puintWidthOfWidestValue	Specify the length, in characters, of the longest string representation of all items in a collection. The intent is that the details for a report go into a ReportDetails collection, which has a WidthOfWidestValue property that was originally acquired indirectly, through a reference to the collection that originally occupied this slot in the argument list.
FormatItem.Alignment	penmAlignment	Specify Left or Right. Format items don't support center alignment.
System.String	pstrFormatString	Specify a Standard Numeric, Date, or Text format string or a custom string composed around a standard string.

Returns

Type	Description
System.String	The returned string is ready to insert into a complete format string for use with string.Format, Console.WriteLine, and their numerous cousins.

OnLabelChanged(ReportDetail.LabelChangedEventArgs)

Raise this event to signal listeners that the length of the label changed.

Declaration

protected virtual void OnLabelChanged(ReportDetail.LabelChangedEventArgs e)

Parameters

Type	Name	Description
ReportDetail.LabelChangedEventArgs	e	The LabelChangedEventArgs method is populated with the new and old label length, so that only the difference is added to the total.

TestState(ReportDetail.State)

Determine whether the condition represented by a member of the State enumeration is true.

Declaration

public bool TestState(ReportDetail.State penmState)

Parameters

Type	Name	Description
ReportDetail.State	penmState	The member of the State enumeration to evaluate.

Returns

Type	Description
System.Boolean	True if State is true, else False.

Events

LabelChanged

Delegates register here.

Declaration

public event EventHandler LabelChanged

Event Type

Type	Description
EventHandler