PCL
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

typedef ProcessParameterType::value_type data_type
 
typedef Array< EnumerationElementenumeration_element_list
 
typedef Array< ProcessParameterparameter_list
 

Public Member Functions

 ProcessParameter (const Process &process, const IsoString &paramId)
 
 ProcessParameter (const ProcessParameter &table, const IsoString &colId)
 
 ProcessParameter (const ProcessParameter &p)
 
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
 
ProcessParentProcess () 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 ProcessParameterNull ()
 

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

typedef ProcessParameterType::value_type pcl::ProcessParameter::data_type

Represents a parameter data type.

Definition at line 198 of file ProcessParameter.h.

◆ enumeration_element_list

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

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
processReference to a the process from which you want to gain access to one of its parameters.
paramIdIdentifier 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
tableReference to a valid table parameter.
colIdIdentifier 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

Destroys this ProcessParameter object.

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]minLengthMinimum valid length of this parameter.
[out]maxLengthMaximum 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]minValueMinimum valid value of this numeric parameter.
[out]maxValueMaximum 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: