pcl::MetaParameter Class Reference

Root base class for PCL classes providing formal descriptions of process parameters. More...

#include <MetaParameter.h>

Inheritance diagram for pcl::MetaParameter:

Public Member Functions
	MetaParameter (MetaProcess *P)
	MetaParameter (MetaTable *T)
	~MetaParameter () noexcept(false) override
virtual IsoString	Aliases () const
virtual String	Comment () const
virtual String	Description () const
virtual IsoString	Id () const =0
virtual bool	IsBlock () const
virtual bool	IsBoolean () const
virtual bool	IsEnumeration () const
virtual bool	IsNumeric () const
virtual bool	IsReadOnly () const
virtual bool	IsRequired () const
virtual bool	IsString () const
virtual bool	IsTable () const
virtual bool	IsVariableLength () const
virtual bool	NeedsUnlocking () const
virtual bool	NeedsValidation () const
Public Member Functions inherited from pcl::MetaObject
	MetaObject (const MetaObject &)=delete
	MetaObject (MetaObject &&x)=delete
	MetaObject (MetaObject *parent)
virtual	~MetaObject () noexcept(false)
size_type	Length () const
MetaObject &	operator= (const MetaObject &)=delete
MetaObject &	operator= (MetaObject &&x)=delete
const MetaObject *	operator[] (size_type i) const
MetaObject *	Parent ()
const MetaObject *	Parent () const

Additional Inherited Members
Public Types inherited from pcl::MetaObject
using	children_list = IndirectArray< MetaObject >

Detailed Description

MetaParameter represents a process parameter. This is an abstract base class providing fundamental functionality common to all process parameters available in PCL. Derived classes implement and extended that functionality to represent a wide variety of process parameter types.

Process parameters can be numerical values (MetaInteger and MetaReal, and their derived classes with different ranges), Boolean values (MetaBoolean), enumerated types (MetaEnumeration), and dynamic strings (MetaString).

In addition, a set of arbitrary process parameters can be organized to define the columns of a table parameter (MetaTable). A table parameter can have an unlimited, variable number of rows.

Finally, block parameters (MetaBlock) can also be defined to store arbitrary data as memory blocks of variable size.

See also

MetaProcess, ProcessImplementation

Definition at line 99 of file MetaParameter.h.

Constructor & Destructor Documentation

MetaParameter() [1/2]

pcl::MetaParameter::MetaParameter

(

MetaProcess *

P

)

Constructs a metaparameter representing a parameter of the specified process class *P.

MetaParameter() [2/2]

pcl::MetaParameter::MetaParameter

(

MetaTable *

T

)

Constructs a metaparameter representing a column of a table process parameter represented by the metatable *T. The new metaparameter is appended to the list of existing columns in the metatable *T.

~MetaParameter()

pcl::MetaParameter::~MetaParameter ( )

inlineoverridenoexcept

Destroys a MetaParameter object.

Definition at line 119 of file MetaParameter.h.

Member Function Documentation

Aliases()

virtual IsoString pcl::MetaParameter::Aliases ( ) const

inlinevirtual

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.

The returned string is a comma-separated list of identifiers that will be treated as synonyms to the actual identifier of this parameter, which is returned by the Id() member function. Two parameters of a process can't have the same alias, so each identifier included in the list must be unique within its parent process.

Note

The default implementation of this member function returns an empty string (no aliases).

See also

Id()

Definition at line 159 of file MetaParameter.h.

Comment()

virtual String pcl::MetaParameter::Comment ( ) const

inlinevirtual

Returns a script comment for the process parameter represented by this metaparameter.

For the sake of compatibility, the returned string should contain only valid ISO-8859-1 characters (represented as UTF-16 since the return value is a String object). No special characters, control tags or character entities are supported. This string will be used as a source code comment to document process parameters in automatically generated scripts.

If this member function is not reimplemented for a table parameter (see MetaTable), PCL automatically generates a script comment including the identifiers of all table column parameters.

Definition at line 303 of file MetaParameter.h.

Description()

virtual String pcl::MetaParameter::Description ( ) const

inlinevirtual

Returns a brief description of the process parameter represented by this metaparameter.

The returned string will be used on the Process Explorer window, which gives a summary of the parameters of each installed process. The information will be written to a console, so you can use the whole functionality of Console to format the text given here.

Try to write succinct but meaningful parameter descriptions.

Definition at line 284 of file MetaParameter.h.

Id()

virtual IsoString pcl::MetaParameter::Id ( ) const

pure virtual

Returns the identifier of the process parameter that this metaparameter represents.

Each process parameter must have a valid, unique (within its parent process) C identifier.

See also

Aliases()

Implemented in pcl::MetaBlock, pcl::MetaTable, pcl::MetaString, pcl::MetaVariableLengthParameter, pcl::MetaEnumeration, pcl::MetaBoolean, pcl::MetaDouble, pcl::MetaFloat, pcl::MetaReal, pcl::MetaInt64, pcl::MetaInt32, pcl::MetaInt16, pcl::MetaInt8, pcl::MetaUInt64, pcl::MetaUInt32, pcl::MetaUInt16, pcl::MetaUInt8, pcl::MetaSignedInteger, pcl::MetaUnsignedInteger, pcl::MetaInteger, and pcl::MetaNumeric.

IsBlock()

virtual bool pcl::MetaParameter::IsBlock ( ) const

inlinevirtual

Returns true iff this metaparameter represents a block process parameter. Block process parameters are represented as subclasses of MetaBlock.

Reimplemented in pcl::MetaBlock.

Definition at line 370 of file MetaParameter.h.

IsBoolean()

virtual bool pcl::MetaParameter::IsBoolean ( ) const

inlinevirtual

Returns true iff this metaparameter represents a Boolean process parameter. Boolean process parameters are represented as subclasses of MetaBoolean.

Reimplemented in pcl::MetaBoolean.

Definition at line 323 of file MetaParameter.h.

IsEnumeration()

virtual bool pcl::MetaParameter::IsEnumeration ( ) const

inlinevirtual

Returns true iff this metaparameter represents an enumerated process parameter. Enumerated process parameters are represented as subclasses of MetaEnumeration.

Reimplemented in pcl::MetaEnumeration.

Definition at line 333 of file MetaParameter.h.

IsNumeric()

virtual bool pcl::MetaParameter::IsNumeric ( ) const

inlinevirtual

Returns true iff this metaparameter represents a numeric process parameter. Numeric process parameters are represented as subclasses of MetaNumeric.

Reimplemented in pcl::MetaNumeric.

Definition at line 313 of file MetaParameter.h.

IsReadOnly()

virtual bool pcl::MetaParameter::IsReadOnly ( ) const

inlinevirtual

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

Read-only parameters or properties cannot be changed by external processes. For example, a script running on the core application can retrieve a read-only property from a process instance, but it cannot change its value.

Read-only properties are often used to provide resulting values or process status information after instance execution. For example, the standard ImageIntegration process includes several read-only properties that can be accessed from a script 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 from scripts, and provides more accurate and extensive information to the users.

Note

The default implementation of this function returns false, so process parameters allow normal read/write access by default.

Definition at line 268 of file MetaParameter.h.

IsRequired()

virtual bool pcl::MetaParameter::IsRequired ( ) const

inlinevirtual

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

When a new instance is being constructed and the represented process parameter is not present, this function is called to decide whether a default, automatically generated value may be acceptable, or if the explicit presence of an actual value for the represented parameter is imprescindible.

For example, if you implement a new version of an existing process, perhaps you will define new parameters as well. The new parameters will not be available in existing stored instances (e.g., in PSM files, or scripts) of previous versions. In this case, if you can provide plausible default values for the new parameters, and you don't reimplement this function for them, then the old process instances will still be reusable.

Note

The default implementation of this function returns false, so actual parameter values are not strictly required by default.

Definition at line 242 of file MetaParameter.h.

IsString()

virtual bool pcl::MetaParameter::IsString ( ) const

inlinevirtual

Returns true iff this metaparameter represents a string process parameter. String process parameters are represented as subclasses of MetaString.

Reimplemented in pcl::MetaString.

Definition at line 352 of file MetaParameter.h.

IsTable()

virtual bool pcl::MetaParameter::IsTable ( ) const

inlinevirtual

Returns true iff this metaparameter represents a table process parameter. Table process parameters are represented as subclasses of MetaTable.

Reimplemented in pcl::MetaTable.

Definition at line 361 of file MetaParameter.h.

IsVariableLength()

virtual bool pcl::MetaParameter::IsVariableLength ( ) const

inlinevirtual

Returns true iff this metaparameter represents a variable-length process parameter. Variable-length process parameters are represented as subclasses of MetaVariableLengthParameter.

Reimplemented in pcl::MetaVariableLengthParameter.

Definition at line 343 of file MetaParameter.h.

NeedsUnlocking()

virtual bool pcl::MetaParameter::NeedsUnlocking ( ) const

inlinevirtual

Returns true iff actual process parameters represented by this metaparameter require explicit unlock calls.

An explicit unlock is a call to ProcessImplementation::UnlockParameter(), which always happens after an initial call to ProcessImplementation::LockParameter().

Note

The default implementation of this function returns false, so a process parameter is not explicitly unlocked by default.

Definition at line 175 of file MetaParameter.h.

NeedsValidation()

virtual bool pcl::MetaParameter::NeedsValidation ( ) const

inlinevirtual

Returns true iff actual process parameters represented by this metaparameter require explicit validation.

An explicit validation occurs when the PixInsight core application performs a call to ProcessImplementation::ValidateParameter(), either as part of a process instance execution, or indirectly because a module has requested it by calling ProcessInstance::Validate().

For example, suppose that you define an integer parameter for a process. The MetaInteger class is a descendant of MetaNumeric, which allows you to define a valid range of values. This is sufficient to automatically reject any actual parameter value outside the declared range. But suppose that only odd integer values (1, 3, 5, 7 ...) are valid values for the parameter in question. The only way to impose such restriction is reimplementing this function to return true, and the corresponding ProcessImplementation::ValidateParameter() function to reject any even integer value.

Note

The default implementation of this function returns false, so a process parameter is never validated by default, unless a module explicitly requests validation of a process instance.

Definition at line 203 of file MetaParameter.h.

---

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

• MetaParameter.h