pcl::ProcessParameter Class Reference

Identifies and describes a process parameter. More...

#include <ProcessParameter.h>

Classes
struct	EnumerationElement
	Structure used to describe an enumeration element. More...

Public Types
using	data_type = ProcessParameterType::value_type
using	enumeration_element_list = Array< EnumerationElement >
using	parameter_list = Array< ProcessParameter >

Public Member Functions
	ProcessParameter (const Process &process, const IsoString &paramId)
	ProcessParameter (const ProcessParameter &p)
	ProcessParameter (const ProcessParameter &table, const IsoString &colId)
virtual	~ProcessParameter ()
IsoStringList	Aliases () const
String	AllowedCharacters () const
data_type	DataInterpretation () const
Variant	DefaultValue () const
String	Description () const
enumeration_element_list	EnumerationElements () const
void	GetLengthLimits (size_type &minLength, size_type &maxLength) const
void	GetNumericRange (double &minValue, double &maxValue) const
IsoString	Id () const
bool	IsBlock () const
bool	IsBoolean () const
bool	IsEnumeration () const
bool	IsInteger () const
bool	IsNull () const
bool	IsNumeric () const
bool	IsReadOnly () const
bool	IsReal () const
bool	IsRequired () const
bool	IsString () const
bool	IsTable () const
bool	IsVariableLength () const
size_type	MaximumLength () const
double	MaximumValue () const
size_type	MinimumLength () const
double	MinimumValue () const
Process &	ParentProcess () const
ProcessParameter	ParentTable () const
int	Precision () const
bool	ScientificNotation () const
String	ScriptComment () const
parameter_list	TableColumns () const
data_type	Type () const

Static Public Member Functions
static ProcessParameter &	Null ()

Detailed Description

The ProcessParameter class describes and identifies process parameters through intermodule communication with the Process and ProcessInstance classes.

As happens with the Process / MetaProcess and ProcessInstance / ProcessImplementation pairs, ProcessParameter is the concrete counterpart to MetaParameter. ProcessParameter represents a parameter of an already installed process, while MetaParameter is a formal description of a parameter of a process implemented by subclassing MetaProcess and ProcessImplementation.

Note that an instance of ProcessParameter represents an existing parameter of an installed process, so you cannot create or define new parameters using this class. You can only use this class to get a complete description of a parameter, including its identifier, range of valid values, allowed lengths, default values, etc. You can also use ProcessParameter to identify a parameter to get or set its current value in an existing process instance, which you can manipulate with the ProcessInstance class.

See also

Process, ProcessInstance, MetaProcess, MetaParameter, ProcessImplementation

Definition at line 191 of file ProcessParameter.h.

Member Typedef Documentation

data_type

using pcl::ProcessParameter::data_type = ProcessParameterType::value_type

Represents a parameter data type.

Definition at line 198 of file ProcessParameter.h.

enumeration_element_list

using pcl::ProcessParameter::enumeration_element_list = Array<EnumerationElement>

A list of enumeration elements.

This type is returned by the EnumerationElements() member function to describe an enumeration process parameter.

Definition at line 225 of file ProcessParameter.h.

parameter_list

using pcl::ProcessParameter::parameter_list = Array<ProcessParameter>

A list of process parameters.

This type is returned by the TableColumns() member function to describe and identify the set of column parameters of a table process parameter.

Definition at line 206 of file ProcessParameter.h.

Constructor & Destructor Documentation

ProcessParameter() [1/3]

pcl::ProcessParameter::ProcessParameter	(	const Process &	process,
		const IsoString &	paramId
	)

Constructs a ProcessParameter object.

Parameters

process	Reference to a the process from which you want to gain access to one of its parameters.
paramId	Identifier of the process parameter. It can be the primary identifier of a parameter, or one of its alias identifiers.

If successful, this constructor creates a managed alias to a process parameter of an installed process in the PixInsight core application.

If there is no parameter of process with the specified identifier, if paramId is not a valid identifier, or if the alias object cannot be generated for some reason, this constructor throws an Error exception with the corresponding error message. Your code should guarantee that these exceptions are always caught and handled appropriately.

Note

Note that this constructor does not 'create' a new process parameter. It only gives access to a parameter of an existing process.

ProcessParameter() [2/3]

pcl::ProcessParameter::ProcessParameter	(	const ProcessParameter &	table,
		const IsoString &	colId
	)

Constructs a ProcessParameter object that identifies a table column parameter.

Parameters

table	Reference to a valid table parameter.
colId	Identifier of the column parameter. It can be the primary identifier of a column parameter, or one of its alias identifiers.

If successful, this constructor creates a managed alias to a table column parameter of an installed process in the PixInsight core application.

If there is no column parameter of table with the specified identifier, if table is not a table parameter, if colId is not a valid identifier, or if the alias object cannot be generated for some reason, this constructor throws an Error exception with the corresponding error message. Your code should guarantee that these exceptions are always caught and handled appropriately.

Note

Note that this constructor does not 'create' a new process parameter. It only gives access to a parameter of an existing process.

ProcessParameter() [3/3]

pcl::ProcessParameter::ProcessParameter

(

const ProcessParameter &

p

)

Copy constructor. The newly constructed object references the same server-side process parameter as the specified object p.

Note

Note that this constructor does not 'create' a new process parameter. It only gives access to a parameter of an existing process.

~ProcessParameter()

virtual pcl::ProcessParameter::~ProcessParameter ( )

virtual

Virtual destructor.

Member Function Documentation

Aliases()

IsoStringList pcl::ProcessParameter::Aliases

(

)

const

Returns a list of alias identifiers for this process parameter.

A process parameter can have one or more alias identifiers. Aliased parameters are useful to maintain compatibility with previous versions of a process.

When the PixInsight core application imports a process instance (e.g. from a process icon) it automatically replaces alias parameter identifiers with actual (current) identifiers. This allows a developer to change the identifiers of some process parameters without breaking compatibility with process instances in existing icon collections or projects.

This function returns a list of identifiers that are treated as synonyms to the actual identifier of this parameter, which is returned by the Id() member function. If this parameter has no aliases, an empty list is returned. Two parameters of a process can't have the same alias, so each identifier in the list should be unique within its parent process.

See also

Id()

AllowedCharacters()

String pcl::ProcessParameter::AllowedCharacters

(

)

const

Returns a string with the valid characters of this string process parameter.

If this parameter is not of a string type, if this string parameter does not impose a specific set of valid characters, or if this is a null object, this member function returns an empty string.

DataInterpretation()

data_type pcl::ProcessParameter::DataInterpretation

(

)

const

Returns the appropriate data type to interpret this block process parameter.

If this object does not represent a block parameter, or if this is a null object, this member function returns ProcessParameterType::Invalid.

DefaultValue()

Variant pcl::ProcessParameter::DefaultValue

(

)

const

Returns the default value of this process parameter.

This function returns a Variant object with the default parameter value. The type of the Variant object depends on the type of this parameter.

Default values are directly available for Boolean, numeric and string parameters.

For enumerated parameters, this function returns the index of the default enumeration element. The returned integer can be used as an index on the list of elements returned by EnumerationElements().

For a block parameter an empty ByteArray is always returned, since block parameters don't have default values.

For table parameters this function throws an Error exception.

For a null ProcessParameter object, this member function returns an invalid Variant object; see Variant::IsValid().

Description()

String pcl::ProcessParameter::Description

(

)

const

Returns a brief (and hopefully useful) description of this process parameter.

EnumerationElements()

enumeration_element_list pcl::ProcessParameter::EnumerationElements

(

)

const

Returns a list of EnumerationElement structures describing all the elements of this enumeration process parameter.

If this parameter is not of an enumerated type, or if this is a null object, this member function returns an empty list.

GetLengthLimits()

void pcl::ProcessParameter::GetLengthLimits	(	size_type &	minLength,
		size_type &	maxLength
	)		const

Gets the valid range of lengths for this variable length process parameter.

Parameters

[out]	minLength	Minimum valid length of this parameter.
[out]	maxLength	Maximum valid length of this parameter.

If this parameter is not of a variable length type, or if this is a null object, this member function will set both output values to zero.

If this parameter does not impose a specific range of valid lengths, this member function will set the following output values:

minValue = 0
maxValue = ~size_type( 0 ).

See also

MinimumLength(), MaximumLength()

GetNumericRange()

void pcl::ProcessParameter::GetNumericRange	(	double &	minValue,
		double &	maxValue
	)		const

Gets the valid range of values for a numeric process parameter.

Parameters

[out]	minValue	Minimum valid value of this numeric parameter.
[out]	maxValue	Maximum valid value of this numeric parameter.

If this parameter is not of a numeric type, or if this is a null object, this member function will set both output values to zero.

If this numeric parameter does not impose a specific range of valid values, this member function will set the following output values:

minValue = -DBL_MAX
maxValue = +DBL_MAX.

See also

MinimumValue(), MaximumValue()

Id()

IsoString pcl::ProcessParameter::Id

(

)

const

Returns the identifier of this process parameter.

Each process parameter has a valid and unique (within its parent process) identifier. All object identifiers follow the C syntax rules for variable identifiers in PixInsight.

See also

Aliases()

IsBlock()

bool pcl::ProcessParameter::IsBlock ( ) const

inline

Returns true iff this object represents a block process parameter.

Definition at line 494 of file ProcessParameter.h.

IsBoolean()

bool pcl::ProcessParameter::IsBoolean ( ) const

inline

Returns true iff this object represents a Boolean process parameter.

Definition at line 436 of file ProcessParameter.h.

IsEnumeration()

bool pcl::ProcessParameter::IsEnumeration ( ) const

inline

Returns true iff this object represents an enumerated process parameter.

Definition at line 469 of file ProcessParameter.h.

IsInteger()

bool pcl::ProcessParameter::IsInteger ( ) const

inline

Returns true iff this object represents an integer process parameter.

Definition at line 452 of file ProcessParameter.h.

References pcl::ProcessParameterType::IsInteger().

IsNull()

bool pcl::ProcessParameter::IsNull

(

)

const

Returns true iff this is a null ProcessParameter object.

A null ProcessParameter does not correspond to an existing parameter of an installed process in the PixInsight core application.

IsNumeric()

bool pcl::ProcessParameter::IsNumeric ( ) const

inline

Returns true iff this object represents a numeric process parameter.

Definition at line 444 of file ProcessParameter.h.

References pcl::ProcessParameterType::IsNumeric().

IsReadOnly()

bool pcl::ProcessParameter::IsReadOnly

(

)

const

Returns true if this object represents a read-only process parameter. Otherwise full read/write access is granted for this parameter.

Read-only process parameters, also known as output properties, cannot be changed by external processes. For example, a script running on the core application can retrieve an output property from a process instance, but it cannot change its value. The same happens with PCL's implementation represented by the Process and ProcessInstance classes.

Read-only parameters are often used to provide resulting values or process status information after instance execution. For example, the standard ImageIntegration process includes several read-only parameters that can be accessed from a script or module to know the identifiers of the views generated to store the integrated image and the rejection map images. This improves versatility and usability of processes, and provides more accurate and extensive information to developers.

IsReal()

bool pcl::ProcessParameter::IsReal ( ) const

inline

Returns true iff this object represents a floating point real process parameter.

Definition at line 461 of file ProcessParameter.h.

References pcl::ProcessParameterType::IsReal().

IsRequired()

bool pcl::ProcessParameter::IsRequired

(

)

const

Returns true iff this process parameter is required to build new process instances. Returns false if a default value can be valid for this process parameter when an actual value is not available.

When a new instance is being constructed and the process parameter that this object represents is not present (for example, because it is not defined in a serialized representation of the instance), the PixInsight core application has to decide whether a default, automatically generated value may be acceptable, or if the explicit presence of an actual value for this parameter is imprescindible. This member function allows a module to know this in advance.

IsString()

bool pcl::ProcessParameter::IsString ( ) const

inline

Returns true iff this object represents a string process parameter.

Definition at line 486 of file ProcessParameter.h.

IsTable()

bool pcl::ProcessParameter::IsTable ( ) const

inline

Returns true iff this object represents a table process parameter.

Definition at line 502 of file ProcessParameter.h.

IsVariableLength()

bool pcl::ProcessParameter::IsVariableLength ( ) const

inline

Returns true iff this object represents a variable-length process parameter.

Definition at line 478 of file ProcessParameter.h.

References pcl::ProcessParameterType::IsVariableLength().

MaximumLength()

size_type pcl::ProcessParameter::MaximumLength ( ) const

inline

Returns the maximum valid length of a variable length process parameter.

See also

GetLengthLimits(), MinimumLength()

Definition at line 638 of file ProcessParameter.h.

MaximumValue()

double pcl::ProcessParameter::MaximumValue ( ) const

inline

Returns the maximum valid value of a numeric process parameter.

See also

GetNumericRange(), MinimumValue()

Definition at line 564 of file ProcessParameter.h.

MinimumLength()

size_type pcl::ProcessParameter::MinimumLength ( ) const

inline

Returns the minimum valid length of a variable length process parameter.

See also

GetLengthLimits(), MaximumLength()

Definition at line 627 of file ProcessParameter.h.

MinimumValue()

double pcl::ProcessParameter::MinimumValue ( ) const

inline

Returns the minimum valid value of a numeric process parameter.

See also

GetNumericRange(), MaximumValue()

Definition at line 553 of file ProcessParameter.h.

Null()

static ProcessParameter& pcl::ProcessParameter::Null ( )

static

Returns a reference to a null ProcessParameter object. A null ProcessParameter does not correspond to an existing parameter of an installed process in the PixInsight core application.

ParentProcess()

Process& pcl::ProcessParameter::ParentProcess

(

)

const

Returns a reference to a Process object that represents the installed process this parameter belongs to.

ParentTable()

ProcessParameter pcl::ProcessParameter::ParentTable

(

)

const

If this parameter is a table column parameter, this function returns a ProcessParameter object that represents the table process parameter this table column belongs to.

If this parameter is not a table column parameter, this function returns a null ProcessParameter object.

Precision()

int pcl::ProcessParameter::Precision

(

)

const

Returns the number of decimal digits used for literal representations of this floating point process parameter.

If this parameter is not of a floating point numeric type, or if this is a null object, this function returns zero. Otherwise, this function returns a positive or negative integer value with the following meanings:

If a value >= 0 is returned, literal representations are always rounded to the nearest value with the specified amount of decimal digits. If this function returns zero, output values corresponding to this parameter will always be rounded to the nearest integer.

If this function returns a negative integer, literal representations will use the standard printf's g-format. In this format, numerical values are represented in a compact fashion, with automatic selection of exponential or fixed representations, depending on the value's magnitude and fractional accuracy.

See also

ScientificNotation()

ScientificNotation()

bool pcl::ProcessParameter::ScientificNotation

(

)

const

Returns true iff this floating point process parameter requires scientific notation for literal representations. Returns false if this parameter requires fixed point notation, or if this is a null object.

See also

Precision()

ScriptComment()

String pcl::ProcessParameter::ScriptComment

(

)

const

Returns a script comment for this process parameter.

The returned string is intended to be used as a source code comment to document process parameters in automatically generated scripts.

TableColumns()

parameter_list pcl::ProcessParameter::TableColumns

(

)

const

Returns the list of column parameters in this table process parameter.

If this object does not represent a table parameter, or if this is a null object, this member function returns an empty list.

Type()

data_type pcl::ProcessParameter::Type

(

)

const

Returns the data type of this process parameter. For a list of valid parameter types, see the ProcessParameterType namespace.

For a null ProcessParameter object, this member function returns ProcessParameterType::Invalid.

---

The documentation for this class was generated from the following file:

• ProcessParameter.h