gov.cca.ports.ParameterPortFactory Interface Reference

This interface supercedes the ccaffeine ConfigurableParameterPortFactory, the parameters library, and all the associated cruft that gunked up a component. More...

Inheritance diagram for gov.cca.ports.ParameterPortFactory:

Inheritance graph
[legend]
Collaboration diagram for gov.cca.ports.ParameterPortFactory:

Collaboration graph
[legend]

List of all members.

Public Member Functions

void initParameterData (inout gov.cca.TypeMap portData, in string portName)
 Initialize the portData for use in a ParameterPort with name portName.
void setBatchTitle (in gov.cca.TypeMap portData, in string title)
 Define the window title for the parameter UI dialog.
void setGroupName (in gov.cca.TypeMap portData, in string newGroupName)
 Define the next tab/group title to use.
void setGroupName (in gov.cca.TypeMap portData, in string newGroupName, in string groupTitle)
 Define the next tab/group title to use.
void addRequestBoolean (in gov.cca.TypeMap portData, in string name, in string help, in string prompt, in bool bdefault) throws gov.cca.CCAException
 Define a boolean parameter and its default state.
void addRequestInt (in gov.cca.TypeMap portData, in string name, in string help, in string prompt, in int idefault, in int low, in int high) throws gov.cca.CCAException
 Define a int parameter and its default state.
void addRequestLong (in gov.cca.TypeMap portData, in string name, in string help, in string prompt, in long ldefault, in long low, in long high) throws gov.cca.CCAException
 Define a long parameter and its default state.
void addRequestFloat (in gov.cca.TypeMap portData, in string name, in string help, in string prompt, in float fdefault, in float low, in float high) throws gov.cca.CCAException
 Define a float parameter and its default state.
void addRequestDouble (in gov.cca.TypeMap portData, in string name, in string help, in string prompt, in double ddefault, in double low, in double high) throws gov.cca.CCAException
 Define a double parameter and its default state.
void addRequestString (in gov.cca.TypeMap portData, in string name, in string help, in string prompt, in string sdefault) throws gov.cca.CCAException
 Define a string parameter and its default state.
void addRequestStringChoice (in gov.cca.TypeMap portData, in string key, in string choice) throws gov.cca.CCAException
 Define a new choice for a string parameter.
void addStringChoices (in gov.cca.TypeMap portData, in string name, in array< string > choices) throws gov.cca.CCAException
 As addRequestStringChoice, but in bulk.
void addIntChoices (in gov.cca.TypeMap portData, in string name, in array< int > choices) throws gov.cca.CCAException
 Replace the bounds on the named parameter by a list.
void addLongChoices (in gov.cca.TypeMap portData, in string name, in array< long > choices) throws gov.cca.CCAException
 Replace the bounds on the named parameter by a list.
void addFloatChoices (in gov.cca.TypeMap portData, in string name, in array< float > choices) throws gov.cca.CCAException
 Replace the bounds on the named parameter by a list.
void addDoubleChoices (in gov.cca.TypeMap portData, in string name, in array< double > choices) throws gov.cca.CCAException
 Replace the bounds on the named parameter by a list.
void addFcomplexChoices (in gov.cca.TypeMap portData, in string name, in array< fcomplex > choices) throws gov.cca.CCAException
 Replace the bounds on the named parameter by a list.
void addDcomplexChoices (in gov.cca.TypeMap portData, in string name, in array< dcomplex > choices) throws gov.cca.CCAException
 Replace the bounds on the named parameter by a list.
void clearRequests (in gov.cca.TypeMap portData)
 Clear all previously added requests, titles, groups.
void registerUpdater (in gov.cca.TypeMap portData, in ParameterGetListener powner)
 Register listener (the component) that wishes to have a chance to change the contents of its ParameterPort just before the parameters TypeMap, portData, is read.
void registerUpdatedListener (in gov.cca.TypeMap portData, in ParameterSetListener powner)
 Register listener (the component) if it wishes to be informed when an parameter is changed via writeConfigurationMap.
void addParameterPort (in gov.cca.TypeMap portData, in gov.cca.Services services)
 Signal that the ParameterPort is fully defined and should now pop out on the component.
void removeParameterPort (in gov.cca.TypeMap portData, in gov.cca.Services services)
 Cause a previously defined parameter port to go away.


Detailed Description

This interface supercedes the ccaffeine ConfigurableParameterPortFactory, the parameters library, and all the associated cruft that gunked up a component.

The component writer now just needs to use this port and one or more typemaps.

All the function names and meanings are as identical to the existing ccaffeine interfaces as possible. Most just have a TypeMap argument added and modernized (stl) string usage. Additional functions to support the full generality of TypeMap have been added.

Each ParameterPort is defined on a typemap the component owns. A component writer can define more than one such port for a component, and each will show up as a ParameterPort for UI agents. The component writer can choose to be notified of parameter reads and writes using the related Listener interfaces.

All strings (help, prompt, value, etc) passed to this interface must be free of
and other line-breaking characters if certain ancient gui clients are going to be used. This limitation is in the clients rather than the ParameterPort implementation. Those clients are prone to compressing redundant whitespace as well. In a rosy future, these client limitations will go away.


Member Function Documentation

void gov.cca.ports.ParameterPortFactory.addDcomplexChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< dcomplex >  choices 
) throws gov.cca.CCAException

Replace the bounds on the named parameter by a list.

void gov.cca.ports.ParameterPortFactory.addDoubleChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< double >  choices 
) throws gov.cca.CCAException

Replace the bounds on the named parameter by a list.

void gov.cca.ports.ParameterPortFactory.addFcomplexChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< fcomplex >  choices 
) throws gov.cca.CCAException

Replace the bounds on the named parameter by a list.

void gov.cca.ports.ParameterPortFactory.addFloatChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< float >  choices 
) throws gov.cca.CCAException

Replace the bounds on the named parameter by a list.

void gov.cca.ports.ParameterPortFactory.addIntChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< int >  choices 
) throws gov.cca.CCAException

Replace the bounds on the named parameter by a list.

void gov.cca.ports.ParameterPortFactory.addLongChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< long >  choices 
) throws gov.cca.CCAException

Replace the bounds on the named parameter by a list.

void gov.cca.ports.ParameterPortFactory.addParameterPort ( in gov.cca.TypeMap  portData,
in gov.cca.Services  services 
)

Signal that the ParameterPort is fully defined and should now pop out on the component.

The component is free to hold the portData map internally without adding it until some desired time. The Services passed here must be the component's own Services handle. The ParameterPortFactory takes care of addProvidesPort.

void gov.cca.ports.ParameterPortFactory.addRequestBoolean ( in gov.cca.TypeMap  portData,
in string  name,
in string  help,
in string  prompt,
in bool  bdefault 
) throws gov.cca.CCAException

Define a boolean parameter and its default state.

The configured value is always available by portData.getBool(name, ...);

Exceptions:
gov.cca.CCAException if key is known and mistyped.

void gov.cca.ports.ParameterPortFactory.addRequestDouble ( in gov.cca.TypeMap  portData,
in string  name,
in string  help,
in string  prompt,
in double  ddefault,
in double  low,
in double  high 
) throws gov.cca.CCAException

Define a double parameter and its default state.

The configured value is always available by portData.getDouble(name, ...) and it will be in the range [low, high]. The initially given bounds can be replaced with a choice list later.

Exceptions:
gov.cca.CCAException if key is unknown or mistyped.

void gov.cca.ports.ParameterPortFactory.addRequestFloat ( in gov.cca.TypeMap  portData,
in string  name,
in string  help,
in string  prompt,
in float  fdefault,
in float  low,
in float  high 
) throws gov.cca.CCAException

Define a float parameter and its default state.

The configured value is always available by portData.getFloat(name, ...) and it will be in the range [low, high]. The initially given bounds can be replaced with a choice list later.

Exceptions:
gov.cca.CCAException if key is unknown or mistyped.

void gov.cca.ports.ParameterPortFactory.addRequestInt ( in gov.cca.TypeMap  portData,
in string  name,
in string  help,
in string  prompt,
in int  idefault,
in int  low,
in int  high 
) throws gov.cca.CCAException

Define a int parameter and its default state.

The configured value is always available by portData.getInt(name, ...) and it will be in the range [low, high]. The initially given bounds can be replaced with a choice list later.

Exceptions:
gov.cca.CCAException if key is known and mistyped.

void gov.cca.ports.ParameterPortFactory.addRequestLong ( in gov.cca.TypeMap  portData,
in string  name,
in string  help,
in string  prompt,
in long  ldefault,
in long  low,
in long  high 
) throws gov.cca.CCAException

Define a long parameter and its default state.

The configured value is always available by portData.getLong(name, ...) and it will be in the range [low, high]. The initially given bounds can be replaced with a choice list later.

Exceptions:
gov.cca.CCAException if key is unknown or mistyped.

void gov.cca.ports.ParameterPortFactory.addRequestString ( in gov.cca.TypeMap  portData,
in string  name,
in string  help,
in string  prompt,
in string  sdefault 
) throws gov.cca.CCAException

Define a string parameter and its default state.

The configured value is always available by portData.getString(name, ...). If no addRequestStringChoice calls are made, the user input may be any string. If addRequestStringChoice is used, the value will be one among the choices. If addRequestStringChoice is used, deflt must be among the choices defined.

Exceptions:
gov.cca.CCAException if key is unknown or mistyped.

void gov.cca.ports.ParameterPortFactory.addRequestStringChoice ( in gov.cca.TypeMap  portData,
in string  key,
in string  choice 
) throws gov.cca.CCAException

Define a new choice for a string parameter.

If no calls to this function are made for a given name, then any form of string will be acceptable input.

Exceptions:
gov.cca.CCAException if key is unknown or mistyped.

void gov.cca.ports.ParameterPortFactory.addStringChoices ( in gov.cca.TypeMap  portData,
in string  name,
in array< string >  choices 
) throws gov.cca.CCAException

As addRequestStringChoice, but in bulk.

void gov.cca.ports.ParameterPortFactory.clearRequests ( in gov.cca.TypeMap  portData  ) 

Clear all previously added requests, titles, groups.

After this call, it is as if the ParameterPort has seen initParameterData but otherwise never configured. The values of previously defined parameters (but not bounds, etc) remain in the TypeMap. Typically, this is used only by someone implementing the updateParameterPort function from interface ParameterGetListener.

void gov.cca.ports.ParameterPortFactory.initParameterData ( inout gov.cca.TypeMap  portData,
in string  portName 
)

Initialize the portData for use in a ParameterPort with name portName.

More than one such port can be defined. The given string portName will be cached in the TypeMap as the result of this function and must not be changed by the component henceforth.

Parameters:
portData the user-supplied TypeMap associated with the port; It is somehow shared between the ParameterPortFactory and the component. The ParameterPortFactory will not read or change preexisting values in portData except those requested via the addRequest functions and those keys starting with the reserved prefix "gcpPPF.".
portName The name of the ParameterPort to appear in the component. It must not conflict with other port names in the same component. The port name "CONFIG" is recommended if only one ParameterPort is being defined.

void gov.cca.ports.ParameterPortFactory.registerUpdatedListener ( in gov.cca.TypeMap  portData,
in ParameterSetListener  powner 
)

Register listener (the component) if it wishes to be informed when an parameter is changed via writeConfigurationMap.

Listeners are called after values are set.

void gov.cca.ports.ParameterPortFactory.registerUpdater ( in gov.cca.TypeMap  portData,
in ParameterGetListener  powner 
)

Register listener (the component) that wishes to have a chance to change the contents of its ParameterPort just before the parameters TypeMap, portData, is read.

Parameters:
powner a pointer to the listener that will be forgotten when it is no longer needed.
portData the hash-table being accessed.

void gov.cca.ports.ParameterPortFactory.removeParameterPort ( in gov.cca.TypeMap  portData,
in gov.cca.Services  services 
)

Cause a previously defined parameter port to go away.

This function should be called at component shutdown (setService(0)) time for any parameter ports that have been added but not yet removed. The ParameterPortFactory takes care of removeProvidesPort. This does not change the parameter values in the TypeMap.

void gov.cca.ports.ParameterPortFactory.setGroupName ( in gov.cca.TypeMap  portData,
in string  newGroupName,
in string  groupTitle 
)

Define the next tab/group title to use.

All addRequest subsequent calls will add to this group. Multiple dialog tabs/groups can be defined in this way.

Parameters:
portData the hash-table which we're subsetting with a tab notation.
newGroupName a one-word name for the group.
groupTitle an optional title for the group.

void gov.cca.ports.ParameterPortFactory.setGroupName ( in gov.cca.TypeMap  portData,
in string  newGroupName 
)

Define the next tab/group title to use.

All addRequest subsequent calls will add to this group. Multiple dialog tabs/groups can be defined in this way.

Parameters:
newGroupName a one-word name for the group.
portData the hash-table which we're subsetting with a tab notation.


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

Generated on Thu Mar 17 09:40:09 2011 for cca-spec-babel by  doxygen 1.5.9