DisplayParameter.h

DisplayParameter(const String name, const String description, const String help, const String context = "", const Bool allowunset = False, const Bool editable = True)

DisplayParameter(const DisplayParameter &other)

DisplayParameter()

DisplayParameter &operator=(const DisplayParameter &other)

Record baseDescription()

const DisplayOptions &displayOptions() const

Description

Prerequisite

DisplayOptions

Etymology

DisplayParameter is a base class which provides services for conveniently storing and parsing parameters relevant to the display classes.

Synopsis

DisplayParameter defines a relatively simple interface for writing small containers for the various types of parameters used throughout the display classes. The required interface consists of methods to update the parameter value from an incoming RecordInterface-type object, and to add the description of the parameter to a provided RecordInterface object.

Other than this, all parameters share these common elements:

name, a short String uniquely identifiying the parameter.

description, a slightly longer String which offers a description of the parameter, suitably short for display in a graphical user interface, for example.

help, an even longer String (!) which should be filled in with text describing the option in more detail than can be given in description

context, which if provided (ie. context != String("")) gives a category name for this parameter, and is used, for example, by the autogui to place the parameter in an appropriately named roll-up.

allowunset, which indicates whether this parameter can be "unset" or not. An "unset" parameter is one for which a sensible (perhaps context sensitive) default can be determined and used. Derived classes need not provide this option in their constructor.

editable, which indicates whether this parameter is allowed to be modified by the user.

DisplayParameter makes use of the DisplayOptions class to parse Records containing parameter descriptions. Derived classes must implement the two virtual methods toRecord and fromRecord, which respectively store a description of the DisplayParameter in a sub-field of the provided RecordInterface, and extract the value of the DisplayParameter from a sub-field in the provided record. The sub-field is identified by the name of the DisplayParameter.

Derived classes should also add utility functions which return the various aspects of the DisplayParameter to the programmer. Most importantly, a value() function should be provided to enable the user to easily retrieve the current value of the parameter.

Motivation

To avoid littering many of the display classes with code fragments for constructing and parsing Records.

Thrown Exceptions

None.

To Do

Provide base class support for unset values.

Member Description

virtual ~DisplayParameter()

Destructor.

virtual Bool fromRecord(const RecordInterface &record) = 0

Parse record, and update this parameter if a field exists whose name matches that of this parameter. Return True if the parameter is changed, otherwise return False.

virtual void toRecord(RecordInterface &record, const Bool fullrecord = True, const Bool overwrite = False) = 0

Place a record describing this parameter in a sub-field of record with name matching that of this parameter. If overwrite is True, then any existing field with matching name will be overwritten. If fullrecord is True, then a complete description of the parameter is given, otherwise just its current value is stored in record.

String name() const

Return the name of this parameter.

String description() const

Return the description of this parameter.

String help() const

Return the help for this parameter.

String context() const

Return the context of this parameter.

Bool allowUnset() const

Return whether this parameter can be unset.

Bool editable() const

Return whether this parameter is editable.

void setName(const String name)

Set or change the name of this parameter to that specified.

void setDescription(const String description)

Set or change the description of this parameter to what is specified.

void setHelp(const String help)

Set or change the help for this parameter to what is specified.

void setContext(const String context)

Set or change the context of this parameter to what is specified.

void setAllowUnset(const Bool allowunset)

Set or change whether this parameter may be unset, according to the function argument value.

void setEditable(const Bool editable)

Set or change whether this parameter is editable according to the function argument.

DisplayParameter(const String name, const String description, const String help, const String context = "", const Bool allowunset = False, const Bool editable = True)

Constructor taking the name of the parameter, a short description, some help text, and flags indicating whether the parameter can be unset and is editable.

DisplayParameter(const DisplayParameter &other)

Copy constructor using copy semantics.