VCDataConsumerController Class Reference

Primary client plugin class for the development of Displays and Processors. Do not subclass directly. More...

Inheritance diagram for VCDataConsumerController:

List of all members.

Public Member Functions
Data Consumer Lifecycle - Override
(id)	- initWithEntity:
	Standard data consumer initializer.
(void)	- invalidated
	Data consumer teardown prior to dealloc.
Utility Methods
(NSNib *)	- loadNibWithName:
	Load a nib from the plugin's bundle, or return the pre-loaded nib.
Configuration
These methods are called by VisualCommander to handle configuration of the data consumer. At a minimum, configurationWindow and configurationDoneButton should be overridden if the data consumer allows configuration (alternately, configureInWindow: may be overridden; see its detailed documentation for specifics).
(NSString *)	- configurationNibName
	Provide the name of a nib that should be loaded prior to attempting to configure the data consumer.
(NSWindow *)	- configurationWindow
	Provide the configuration window to be displayed at user request.
(NSButton *)	- configurationDoneButton
	Provide the button in the configuration window that should be used to end configuration of the data consumer and dismiss the configuration window.
(void)	- configurationNibHasLoaded
	Called after the configuration nib provided by configurationNibName has been automatically loaded.
(void)	- configurationBeginning
	Called just before the configuration sheet is shown.
(void)	- configurationEnded
	Called after the button provided by configurationDoneButton has been clicked by the user.
(void)	- closeConfigurationWindow
	Dismiss the configuration window if it's presently displayed.
(void)	- configureInWindow:
	Display the configuration window as a sheet in the requested window, or as a standalone window.
Input Set Management
The inputs for a data consumer can be grouped into various input sets. These methods provide functionality to manage input sets, including the ability to create, delete sets, add look up sets. Input sets, just as with the data consumer controller's entity, can store arbitrary key-value pairs of configuration data.
(VCInputSet *)	- createInputSetWithName:
	Create a new input set.
(VCInputSet *)	- inputSetWithReferencePath:
	Look up the input set with the provided reference path.
(NSSet *)	- inputSetsWithName:
	Get all of the input sets with a specific name.
(NSSet *)	- allInputSets
	Get all of the input sets at this data consumer.
(void)	- destroyInputSet:
	Delete an input set.
Input Management
These methods provide functionality to manage inputs at the data consumer, including the ability to create, delete, and modify inputs. Inputs, just as with the data consumer controller's entity, can store arbitrary key-value pairs of configuration data.
(VCInput *)	- createInputWithName:inSet:
	Create a new input with the provided name and set.
(NSSet *)	- inputsWithName:
	Retrieve all inputs with a matching name, regardless of the set that they're in.
(NSSet *)	- allInputs
	Retrieve all inputs at the data consumer.
(NSSet *)	- inputsWithName:inSet:
	Retrieve all inputs with a matching name in a specific input set.
(VCInput *)	- inputWithName:inSet:
	Return a single input that matches the name, input set criteria.
(NSSet *)	- allInputsInSet:
	Retrieve all inputs in the given set.
(VCInput *)	- anyInput
	Retrieve a single input from the data consumer.
(VCInputElement *)	- inputElementForElementPath:
	Look up an input element based on its path.
(BOOL)	- allInputsConnected
	Check to see if all inputs currently return YES to isConnected.
(VCValue *)	- currentValueForInputWithName:inSet:
	Retrieve the current value for an input with the given name and input set.
(void)	- destroyInput:
	Destroy an input.
(void)	- disconnectInput:
	The input to be disconnected.
(void)	- placeInput:inSet:
	Change the input set that an input is in.
(BOOL)	- connectInput:withSource:
	Programmatically connect an input to a specific source.
Input Handling
These methods are called by VisualCommander in response to events involving inputs connected to this data consumer. They should be overridden as needed by subclasses to customize the data consumer's behavior.
(BOOL)	- willAcceptSource:forInput:withTooltip:
	Indicate whether or not the provided data point will be accepted by this data consumer.
(VCInput *)	- inputForDataPoint:
	Provide the input that a data point should be connected to when the user has not specified.
(void)	- inputDidGainSource:
	Take any action necessary to respond to an input becoming connected.
(void)	- inputDidLoseSource:
	Take any action necessary to respond to an input becoming disconnected.
(void)	- inputDidBecomeActive:
	Take any action necessary to respond to an input becoming active.
(void)	- inputDidBecomeInactive:
	Take any action necessary to respond to an input becoming inactive.
Command Outlet Management
These methods provide command outlet management functionality to the data consumer- creation, destruction, and lookup of command outlets. Command outlets allow the data consumer to send data back sessions; individual commands at those sessions can have a wide variety of potential results.
(VCCommandOutlet *)	- createCommandOutletWithName:
	Create a new command outlet.
(NSSet *)	- commandOutletsWithName:
	Retrieve all command outlets with a specific name.
(VCCommandOutlet *)	- commandOutletWithName:
	Retrieve a single command outlets with a specific name.
(NSSet *)	- allCommandOutlets
	Retrieve the set of all command outlets.
(VCCommandOutlet *)	- anyCommandOutlet
	Retrieves a single command outlet.
(void)	- destroyCommandOutlet:
	Destroy a command outlet and remove it from this data consumer.
(void)	- disconnectCommandOutlet:
	Disconnect a command outlet from its command.
(BOOL)	- connectOutlet:withCommand:
	Programmatically connect a command outlet to a source command.
Command Handling
These methods are called by VisualCommander in response to events involving commands connected to this data consumer. Subclasses should override these methods to provide custom handling of these events.
(BOOL)	- willAcceptCommand:forOutlet:withTooltip:
	Determine whether or not a command can be connected to the specified command outlet.
(VCCommandOutlet *)	- outletForCommand:
	Determine the most appropriate command outlet for a command.
(void)	- outletDidGainCommand:
	Take any action necessary to respond to a command outlet becoming connected.
(void)	- outletDidLoseCommand:
	Take any action necessary to respond to a command outlet becoming disconnected.
Output Management
These methods provide output related functionality to the data consumer- creation, destruction, and lookup of outputs.
(VCOutput *)	- createOutputWithName:dataType:
	Create a new output with the specified name and data type.
(NSSet *)	- outputsWithName:
	Retrieve the set of outputs that matches the provided name.
(NSSet *)	- allOutputs
	Retrieve the set of all outputs at this data consumer.
(void)	- destroyOutput:
	Destroy an output object.
(void)	- notifyForNewData
	Notify any data consumers using this data consumer's outputs that new or changed data can now be computed.
(void)	- setValue:forAttribute:ofOutput:
	Set the value of an attribute for this output.
(void)	- removeAttribute:fromOutput:
	Remove an attribute from this output.
Output Data Production
These methods are called by VisualCommander when other portions of the system need data from the outputs that this data consumer manages. They should be overridden by any data consumers that provide outputs.
(VCTimestamp *)	- youngestDataTimestampForOutput:
	Find the youngest time for which data can be calculated.
(VCTimestamp *)	- oldestDataTimestampForOutput:
	Find the oldest time for which data can be calculated.
(VCTimestamp *)	- currentTimestampForOutput:
	Find the current timestamp for data from an output.
(VCValue *)	- currentValueForOutput:
	Calculate the current value of an output.
(VCValue *)	- valueAtTime:forOutput:
	Calculate the value of an output at a specific time.
(NSArray *)	- count:fromTime:to:forOutput:
	Retrieve a set of calculated values for an output, evenly distributed between two timestamps.
Plugin Help
These methods are called by VisualCommander to facilitate providing help documentation to the user for this plugin.
(NSString *)	- pathToHelpFile
	Provide a path to a help file for this plugin.
(BOOL)	- hasHelp
	Indicate whether or not help is available for this plugin.
Static Public Member Functions
Plugin Information
These methods provide information about the data consumer plugin. Subclasses should override them to return appropriate values.
(BOOL)	+ storesPerElementConfiguration
	Subclasses should override this method if they need to store configuration for every element of matrix inputs (ie, line color for a plot)
(NSString *)	+ name
	Provide a name for this plugin.
(NSString *)	+ tooltip
	Provide a tooltip describing the plugin.
(NSString *)	+ category
	Provide the category into which the plugin should be organized for display.
(NSDictionary *)	+ consumerDefaults
	Provide default values to be stored into the data consumer's entity.

---

Detailed Description

VCDataConsumerController provides most of the base functionality related to data management for both Processors and Displays. Plugins should not, however, subclass from VCDataConsummerController directly- instead, subclass VCProcessorController or VCDisplayController as appropriate.

Data Consumer plugins (both Displays and Processors; from here on we'll refer to them simply as Data Consumers) act as controllers for a Core Data managed object. The controller provides necessary functionality for interacting with inputs, outputs, commands, and user inputs.

The Core Data managed object that represents the data consumer in the interface has been extended to allow arbitrary key-value pairs to be stored in it with setValue:forKey:. Some keys are reserved, as they refer to core data properties or relationships. The values stored must conform to the NSCoder protocol to be saved with the interface.

When storing data in the entity, be aware that setValue:forKey: calls on the entity will mark the interface as dirty (needing to be saved). Transient values that do not need to be saved with the interface should be stored normally in member variables at the controller rather than being stored in the entity, and spurious changes (where the value does not actually change) should be avoided when possible to prevent unnecessarily marking the doucment as dirty.

Arbitrary key-value storage at the entity also works for bindings, so user interface elements can be bound to key paths on the entity.

To avoid memory issues related to nibs, there are some best practices that should be followed for all nibs used by the data consumer.

1. The File's Owner of the nib should be the data consumer controller.
2. The nib should contain an NSObjectController instance. The data consumer controller should have an outlet to which this object controller is connected, and the object controller's content outlet should be set to the File's Owner.
4. The data consumer controller's -(void)invalidated method should first send "[objectController unbind:@"contentObject"]" (if bound to the File Owner) followed by "[objectController setContent:nil]".
5. All bindings from objects within the nib to either the data consumer controller or its entity should go through the object controller. This ensures that they are properly unbound when the data consumer is invalidated and clears the content of the object controller.

---

Member Function Documentation

- (NSSet *) allCommandOutlets

Retrieve a set containing all command outlets at this data consumer

Returns:

The set of all command outlets

- (NSSet *) allInputs

Retrieve a set containing all inputs at the data consumer

Returns:

A set with all inputs

- (BOOL) allInputsConnected

Check to see if all inputs are currently connected- that is, all inputs return YES for the isConnected property. This method is often useful for determining whether or not the data consumer has the data it needs to work properly.

Returns:

YES if all inputs return YES to isConnected; NO if any of them return NO.

- (NSSet *) allInputSets

Retrieve all input sets at this data consumer

Returns:

A set containing all input sets at this data consumer

- (NSSet *) allInputsInSet:

(VCInputSet *)

inputSet

Retrieve all inputs in the provided input set.

Parameters:

inputSet

The for which inputs should be returned, or nil to retrieve all inputs that are not in an input set.

Returns:

The set of matching inputs.

- (NSSet *) allOutputs

Retrieve a set containing all outputs at this data consumer.

Returns:

The set of all outputs at this data consumer.

- (VCCommandOutlet *) anyCommandOutlet

Retrieve a single command outlet connected to this data consumer.

Returns:

A command outlet connected to this data consumer. If this data consumer has no command outlets, nil is returned. If this data consumer has more than one command outlet, one will be chosen in a nondeterministic fashion and returned.

- (VCInput *) anyInput

Retrieve a single input attached to this data consumer.

Returns:

eturns a single VCInput attached to this data consumer. If no inputs exist, returns nil. If more than one input exists, one of them will be chosen in a nondeterministic fashion.

+ (NSString *) category

Provide an optional category for this plugin. Plugins that return the same category will be grouped together in the tools palette.

Returns:

The category, or nil to be placed in the General category. The default implementation returns nil.

- (void) closeConfigurationWindow

Hide (either as a sheet or as a standard window) the configuration window provided by configurationWindow, and then call configurationEnded.

- (NSSet *) commandOutletsWithName:

(NSString *)

name

Retrieve a set of all command outlets that have a specific name.

Parameters:

name	The name to match.

Returns:

A set containing the matching command outlets.

- (VCCommandOutlet *) commandOutletWithName:

(NSString *)

name

Returns a single command outlet with the given name.

Parameters:

name	The name to match

Returns:

If no outlets with that name exist, returns nil. If more than one outlet with that name exists, one of them will be chosen in a nondeterministic fashion.

- (void) configurationBeginning

Called by configureInWindow just before the configuration sheet is shown. The configuration sheet is not yet showing when this is called.

If configureInWindow is overridden, this function is not necessary.

- (NSButton *) configurationDoneButton

When the default implementation of -(void)configureInWindow:window is used, the button provided as the return value to this function has its target and action changed to inform the data consumer controller that configuration is over and cause the configureInWindow to dismiss the configuration window.

If configureInWindow is overridden, this function is not necessary.

Returns:

The button to use to indicate configuration completion, or nil if no such button exists. The default implementation returns nil.

- (void) configurationEnded

After the default implementation of configureInWindow is notified that the user has clicked on the button returned from configurationDoneButton, the configuration window will be hidden and this function will be called to give the data consumer controller a chance to perform any post-configuration actions necessary.

If configureInWindow is overridden, this function is not necessary.

- (void) configurationNibHasLoaded

After the default implementation of configureInWindow automatically loads the configuration nib provided by configurationNibName, it will call this method to give the data consumer controller a chance to handle any post-load setup required. The default implementation does nothing.

If configureInWindow is overridden, this function is not necessary.

- (NSString *) configurationNibName

VisualCommander provides support for loading configuration nibs on-demand for data consumer plugins. If this method is overridden to return the name of a nib available in the data consumer plugin's bundle, that nib will be loaded with the data consumer as the File's Owner if -(NSWindow *)configurationWindow returns nil; configurationWindow will then be called again to try to get the configuration window that should be shown.

If configureInWindow is overridden, this function is not necessary.

Please see the best practices note in the VCDataConsumerController documentation related to nibs.

Returns:

The name of the nib (without extension) to load when configuration is required, or nil if no nib should be loaded on demand. The default implementation returns nil.

- (NSWindow *) configurationWindow

Provide a configuration window to be displayed when the user attempts to configure the data consumer.

If configureInWindow is overridden, this function is not necessary.

Returns:

The window to be displayed, or nil if no configuration window is available. The default implementation returns nil.

- (void) configureInWindow:

(NSWindow *)

window

VisualCommander will call this function to request that the data consumer controller present its configuration window as a sheet for the provided window. The default implementation uses configurationWindow and configurationDoneButton to look up the window and button to be used for indicating configuration completion and then begins a sheet modal for the specified window. If the configurationWindow returns nil on the first call, the nib (if any) specified with configurationNibName will be loaded and the call retried.

If more complex configuration handling is desired, this function can be overridden without the need to call the superclass implementation.

Parameters:

window

The window to which the configuration window should be attached as a sheet.

- (BOOL) connectInput:		(VCInput *)	input
withSource:		(id)	source

In most situations, inputs will automatically become connected in response to user actions. However, some data consumers may do automatic data discovery by looking through the data tree, and in those cases the input can manually hook inputs to sources with this method.

Most data consumers will not need to call this function; it is called automatically in response to user action.

Parameters:

input	The input to connect.
source	The source to connect the input to, either a data from from the data tree or an Output from another data consumer in this interface.

Returns:

YES if the connection was successful, or NO if an error ocurred.

- (BOOL) connectOutlet:		(VCCommandOutlet *)	outlet
withCommand:		(id)	command

In most cases, a command outlet is connected to a command through user action. However, some data consumers may monitor the available data tree to find appropriate commands; these data consumers may call this method to programmatically connect a command outlet with a command object retrieved from the data tree.

Parameters:

outlet	The command outlet to which the command should be connected
command	The command to connect to the outlet.

Returns:

YES if the connection was successful; NO if an error occured.

+ (NSDictionary *) consumerDefaults

Provide a set of default values that will be stored in the consumer's entity before it is instantiated for the first time, allowing the code to rely on their presence in the entity.

If this data consumer is a Display, the following keys may be used to provide initial defaults for its appearance:

• VCDisplayDefaultPadding - default 5.0f
• VCDisplayDefaultBorderWidth - default 1.0f
• VCDisplayDefaultBorderColor - default [NSColor blackColor]
• VCDisplayDefaultBackgroundColor - default [NSColor grayColor]

- (NSArray *) count:		(int)	numberOfPoints
fromTime:		(VCTimestamp *)	start
to:		(VCTimestamp *)	stop
forOutput:		(VCOutput *)	output

Return an array of calculated values for an output at a set of times evenly distributed between a start and end, inclusive. The default implementation simply interpolates the appropriate number of timestamps and calls valueAtTime:forOutput: for each one. Subclasses may override this function to provide improved performance. (This function may be called very frequently by other data consumers collecting historical data.)

Parameters:

numberOfPoints	The number of calculated data points to return. This number is a maximum; if fewer points (or no points) are available, return only the number available.
start	The first timestamp for which the calculation should be returned.
stop	The last timestamp for which the calculation should be returned.
output	The output of interest.

Returns:

An array of calculated values, ordered from oldest to youngest. If no values can be calculated, an empty array should b returned- under no circumstances should nil be returned from this function.

- (VCCommandOutlet *) createCommandOutletWithName:

(NSString *)

name

Create a new command outlet with the specified name. The command outlet's index is chosen to be the lowest integer greater than 0 such that the tuple (name,index) is unique at this data consumer.

Parameters:

name	The name for the new command outlet.

Returns:

The newly created command outlet object.

- (VCInputSet *) createInputSetWithName:

(NSString *)

name

Create a new input set with the provided name. If no other input sets with that name exist, the input set will have an index of 1. If other input sets with that name exist, the new set's index will be chosen so that the name and the index together uniquely identify the input set.

Parameters:

name	The name to give the new input set.

Returns:

The newly created input set object

- (VCInput *) createInputWithName:		(NSString *)	name
inSet:		(VCInputSet *)	inputSet

Create a new input with a specific name, placed in a specific input set. The new input's index will be chose so as to be the lowest integer greater than zero that causes the (name,inputSet,index) tuple to be unique.

Parameters:

name	The name for the new input.
inputSet	The input set that the new input should be placed in, or nil if the input should not be assigned to an input set.

Returns:

The newly created input object.

- (VCOutput *) createOutputWithName:		(NSString *)	name
dataType:		(enum VCDataTypes)	dataType

Create a new output with the specified name and data type. The output's index is chosen to be the lowest integer greater than 0 such that the tuple (name,index) is unique among outputs at this data consumer.

Parameters:

name	The name for the new output.
dataType	The data type of the data produced by the output

Returns:

The newly created output object.

- (VCTimestamp *) currentTimestampForOutput:

(VCOutput *)

output

Sessions have a notion of current time, which changes as new data arrives or the Session Time Control interface is used to scrub through historical times. Data Consumers can also have a notion of current time for their outputs, generally based on the currentTime reported by their inputs. This function should return the current time associated with a specific output, which should generally be the current time associated with the inputs used to calculate that output.

The default implementation picks the youngest of all timestamps returned from currentTimestamp on each input connected to this data consumer.

Parameters:

output

The output of interest.

Returns:

The timestamp to be used as current for the output.

- (VCValue *) currentValueForInputWithName:		(NSString *)	name
inSet:		(VCInputSet *)	set

Retrieve the current value of an input with the provided name, in the provided set. If more than one input that matches this criteria exists, the result will be nondeterministic.

Parameters:

name	The name of the input to look up.
set	The input set to look in for the input, or nil to look for inputs that are not in an input set.

Returns:

If an input that matches the criteria is found, return the result of calling currentValue on that input. If currentValue returns nil or no matching input is found, return nil.

- (VCValue *) currentValueForOutput:

(VCOutput *)

output

Return the current value for an output- that is, the value at the the time returned by a call to currentTimestamp for the provided output. The default implementation calls currentTimestampForOutput: and then returns the result of valueAtTime:forOutput: with the appropriate timestamp and output.

Parameters:

output

The output of interest.

Returns:

The value calculated for the output at the current time.

- (void) destroyCommandOutlet:

(VCCommandOutlet *)

outlet

Destroy a command outlet object and remove it from this data consumer.

Parameters:

outlet

The command outlet to destroy.

- (void) destroyInput:

(VCInput *)

input

Destroy an input object and remove it from the set (if it is in one) and from this data consumer.

Parameters:

input

The input to be destroyed.

- (void) destroyInputSet:

(VCInputSet *)

inputSet

Destroy an input set. Any inputs in the set will be reassigned to the base (nil) input set; their indices may be changed to ensure that name+index+set continues to uniquely define inputs.

Parameters:

inputSet

the input set to destroy

- (void) destroyOutput:

(VCOutput *)

output

Destroy an output object and remove it from this consumer. Any inputs connected to the output will be disconnected.

Parameters:

output

The output to destroy

- (void) disconnectCommandOutlet:

(VCCommandOutlet *)

outlet

Disconnect a command outlet from the command that it is currently connected to, if any.

Parameters:

outlet

The command outlet to disconnect.

- (void) disconnectInput:

(VCInput *)

input

Disconnect the input from any source (either a data point or an output) that it is currently connected to. If the input is not connected to a source, has no effect.

Parameters:

input

The input to be disconnected.

- (BOOL) hasHelp

Subclasses can override this method to return YES if this object has a specific help file or NO if not. If not overridden, the default method will call pathToHelpFile: and return YES if a non-nil non-empty path string is returned.

- (id) initWithEntity:

(VCExtendedManagedObject *)

anEntity

All data consumers are initialized via a call to initWithEntity. Generally, the nib for the data consumer's view is loaded, if necessary, and any basic inputs, outputs and command outlets are set up. Remember that the data consumer may not be starting for the first time, if the interface is being loaded or a deletion of the data consumer is being undone; the values stored in the entity should be checked, and the absence of inputs/outputs/commands verified, to ensure that setup is not erroneously performed more than once.

Parameters:

anEntity

The entity for this data consumer controller.

Returns:

As with any init method, this method should always return self

- (void) inputDidBecomeActive:

(VCInput *)

input

VisualCommander will call this function when an input becomes active. Override if the plugin should take action in response to such an event.

Parameters:

input

The Input that has become active.

- (void) inputDidBecomeInactive:

(VCInput *)

input

VisualCommander will call this function when an input becomes inactive. Override if the plugin should take action in response to such an event.

Parameters:

input

The Input that has become inactive.

- (void) inputDidGainSource:

(VCInput *)

input

VisualCommander will call this function when an input becomes connected. Override if the plugin should take action in response to such an event.

Parameters:

input

The Input that has become connected.

- (void) inputDidLoseSource:

(VCInput *)

input

VisualCommander will call this function when an input becomes disconnected. Override if the plugin should take action in response to such an event.

Parameters:

input

The Input that has become disconnected.

- (VCInputElement *) inputElementForElementPath:

(NSString *)

elementPath

Retrieve an input element object given its element path. All elements have a path that uniquely identifies them; this method can be used to look up a method by that path. Element paths, rather than elements themselves, should be used when configuration data needs to refer to a specific element.

This method will fail if the plugin does not return YES for +(BOOL)storesPerElementConfiguration.

Parameters:

elementPath

the path to search for

Returns:

The matching input element object, if one exists; nil if one could not be found.

- (VCInput *) inputForDataPoint:

(id)

dataPoint

After willAcceptSource:forInput returns YES for a data point and a nil input, if the operation completes successfully this method will be called to return or create the VCInput to which the data point should be connected. The default implementation always returns nil.

Parameters:

dataPoint

The dataPoint object responds to valueForKey: for the keys: "type", "units", "attributes", "path", "numberOfRows" and "numberOfColumns". The "numberOfRows" and "numberOfColumns" values are NSNumbers. The value for "type" is an NSNumber whose integer value is one of the VCDataTypes enumeration. The "units" and "path" values are NSString objects and the "attributes" value is an NSDictionary. These values should be sufficient to determine whether or not the data point should be used as an input.

Returns:

This method should return the input appropriate for the provided dataPoint. To cancel the operation, return nil.

- (NSSet *) inputSetsWithName:

(NSString *)

name

Retrieve all inputs matching the provided name.

Parameters:

name	The name to search for.

Returns:

A set containing all input sets with the matching name.

- (VCInputSet *) inputSetWithReferencePath:

(NSString *)

referencePath

Find the input set whose reference path matches the provided string. All input sets have a unique reference path based on their name and index. Input sets cannot be directly stored as configuration data, but their reference path can be; the reference path can subsequently be used to look the input set up with this method.

Parameters:

referencePath

The path to search for

Returns:

If an input set with that reference path exists, it will be returned. If not, nil will be returned.

- (NSSet *) inputsWithName:

(NSString *)

name

Retrieve all inputs with a name that matches the provided string

Parameters:

name	The name to match.

Returns:

A set containing all inputs with a matching name.

- (NSSet *) inputsWithName:		(NSString *)	name
inSet:		(VCInputSet *)	inputSet

Retrieve a set containing all inputs with a name that matches the provided string that are in the provided input set.

Parameters:

name	The name to match.
inputSet	The input set to check for matching inputs, or nil to check inputs that are not in an input set.

Returns:

The set of matching inputs.

- (VCInput *) inputWithName:		(NSString *)	name
inSet:		(VCInputSet *)	inputSet

Returns a single VCInput with the given name in the given set.

Parameters:

name	The name to match
inputSet	The input set to check for matching inputs, or nil to check inputs that are not in a set.

Returns:

If no inputs with that name in that set exist, returns nil. If more than one input with that name exist in the set, one of them will be chosen in a nondeterministic fashion.

- (void) invalidated

When the data consumer is no longer needed (it has been deleted, the interface is being closed, etc), this method is first called to give it the opportunity to clean up any resources. Of particular note is the need to remove bindings that are attached directly to the controller, as these bindings retain the controller and will prevent it from being deallocated. Observations for key-value changes and notifications should also be unregistered here.

NOTE: It is critically important that, before returning, subclass implementations call their superclass's invalidated method. Failure to do so will lead to memory corruption.

- (NSNib *) loadNibWithName:

(NSString *)

nibName

Load a nib with a given name from the bundle containing this object's class. If the nib has already been loaded, this function will avoid the need to re-load the nib and will simply return the previously loaded copy, speeding up subsequent loads of plugins.

Parameters:

nibName

The name of the nib to load.

Returns:

The loaded nib, or nil if a nib with the specified name was not found.

+ (NSString *) name

Provide a human-readable name for this plugin. The name will be used to represent the data consumer in the tools palette; it will also be used as the default name for new instances of the data consumer.

Returns:

The plugin's name.

- (void) notifyForNewData

Notify all data consumers with inputs connected to an output at this data consumer that the data computable by this consumer has changed. This is often called in response to a connection or disconnection of an input (such that calculation becomes possible, or ceases to be possible) or to a configuration data change that would change how output values are calculated.

- (VCTimestamp *) oldestDataTimestampForOutput:

(VCOutput *)

output

Return the oldest (smallest numerically) timestamp for which data can be produced for the provided output. The default implementation returns the oldest date for which all inputs connected to the data consumer have data available.

Parameters:

output

The output of interest.

Returns:

The oldest possible timestamp for which data can be produced. If data cannot be produced at this time for the output, return nil. An older timestamp is one that occurs earlier chronologically- 2000-01-01 is older than 2009-01-01.

- (void) outletDidGainCommand:

(VCCommandOutlet *)

outlet

VisualCommander will call this function when a command is connected to a command outlet. Override if the plugin should take action in response to such an event.

Parameters:

outlet

The command outlet that has become connected.

- (void) outletDidLoseCommand:

(VCCommandOutlet *)

outlet

VisualCommander will call this function when a command outlet loses its connection to a command. Override if the plugin should take action in response to such an event.

Parameters:

outlet

The command outlet that has become connected.

- (VCCommandOutlet *) outletForCommand:

(id)

command

After willAcceptCommand:forOutlet returns YES for a command and a nil outlet, if the operation completes successfully this method will be called to return or create the command outlet to which the data point should be connected. The default implementation always returns nil.

Parameters:

command

The command object responds to valueForKey: for the keys: "type", "units", "attributes", "path", "numberOfRows" and "numberOfColumns". The "numberOfRows" and "numberOfColumns" values are NSNumbers. The value for "type" is an NSNumber whose integer value is one of the VCDataTypes enumeration. The "units" and "path" values are NSString objects and the "attributes" value is an NSDictionary. These values should be sufficient to determine which command outlet should be used

Returns:

This method should return the command outlet appropriate for the provided command. To cancel the operation, return nil.

- (NSSet *) outputsWithName:

(NSString *)

name

Retrieve the set of outputs with a name that matches the provided string.

Parameters:

name	The name to match.

Returns:

A set containing the matching outputs.

- (NSString *) pathToHelpFile

Subclasses can override this method to return the path of a help file specific to this object. If not overridden, the default method will attempt to find a file named "help.html" in the bundle's Resources directory. If found, the path to that file will be returned. If not, nil is returned. The default implementations of hasHelp: and showHelp: both call this method if helpAnchor: doesn't return anything.

Returns:

The path to the help file.

- (void) placeInput:		(VCInput *)	input
inSet:		(VCInputSet *)	inputSet

Move an input from one input set to another. An input can only be in one input set at a time. If the new input set would cause the (name,input set,index) tuple to no longer be unique, the input's index will be updated to the lowest index that will ensure uniqueness.

Parameters:

input	The input to modify
inputSet	the input set that the input should be placed in, or nil if the input should be removed from any input set.

- (void) removeAttribute:		(NSString *)	attribute
fromOutput:		(VCOutput *)	output

Remove an attribute from an output. Attributes are frequently used by receiving data consumers to determine whether or not they should accept the output as an input. Be aware that changing the attributes of an input will not cause other data consumers to re-validate their usage of the output; it is best to set the attributes when the output is created and then not change them in the future. Instead, destroy and re-create the output to ensure that existing connections are broken and new ones properly validated.

Parameters:

attribute	The attribute for which the value should be set. Must not be nil.
output	The output to modify. Must not be nil

- (void) setValue:		(NSString *)	value
forAttribute:		(NSString *)	attribute
ofOutput:		(VCOutput *)	output

Set the value of an attribute of an output of this data consumer. Attributes are frequently used by receiving data consumers to determine whether or not they should accept the output as an input. Be aware that changing the attributes of an input will not cause other data consumers to re-validate their usage of the output; it is best to set the attributes when the output is created and then not change them in the future. Instead, destroy and re-create the output to ensure that existing connections are broken and new ones properly validated.

Parameters:

value	The value to set for the attribute. Must not be nil.
attribute	The attribute for which the value should be set. Must not be nil.
output	The output to modify. Must not be nil.

+ (BOOL) storesPerElementConfiguration

If the data consumer needs to store separate configuration information for each element of matrix inputs (eg, line color information for a plot), this method can be overridden to return YES (the default is NO). If this method returns YES, all elements for any matrix inputs (and a single element for each double and integer input) will have corresponding VCInputElement objects created for them, which allow arbitrary key-value storage in the same way the data consumer's entity does.

Returns:

YES to create per-element configuration objects; NO otherwise. Default implementation returns NO.

+ (NSString *) tooltip

Provide a tooltip that will be shown when the user hovers the mouse over the plugin's name in the tools palette; should provide a brief description of the plugin.

Returns:

The plugin's tooltip.

- (VCValue *) valueAtTime:		(VCTimestamp *)	timestamp
forOutput:		(VCOutput *)	output

Calculate the value of an output at the specified time. The default implementation returns nil.

Parameters:

timestamp	The timestamp for which a value should be calculated.
output	The output of interest.

Returns:

The calculated value, or nil if the value cannot be calculated.

- (BOOL) willAcceptCommand:		(id)	command
forOutlet:		(VCCommandOutlet *)	outlet
withTooltip:		(NSString **)	tooltip

Subclasses should override this method to perform custom logic determining whether or not a given command will be accepted as a source for the specified command outlet. The default implementation always returns NO.

Parameters:

command	The command object responds to valueForKey: for the keys: "type", "units", "attributes", "path", "numberOfRows" and "numberOfColumns". The "numberOfRows" and "numberOfColumns" values are NSNumbers. The value for "type" is an NSNumber whose integer value is one of the VCDataTypes enumeration. The "units" and "path" values are NSString objects and the "attributes" value is an NSDictionary. These values should be sufficient to determine whether or not the command should be used for a command outlet.
outlet	The command outlet that the command may be connected to. If the command outlet is nil, the user has not specified the command outlet, and should this method return YES and a subsequent drop occur commandOutletForCommand: will be called to determine which command outlet should be connected. In this case the consumer should decide if any of the available command outlets are appropriate (or if it is possible to create a new appropriate command outlet).
tooltip	The implementation may set this to point to an NSString giving a tooltip to show as drag feedback (a reason for rejecting, or a detail regarding what the command will be used for, for instance)

Returns:

This method should return YES if the command should be accepted, or NO if it should not.

- (BOOL) willAcceptSource:		(id)	dataPoint
forInput:		(VCInput *)	input
withTooltip:		(NSString **)	tooltip

Subclasses should override this method to perform custom logic determining whether or not a given data point will be accepted as a source for the specified input. The default implementation always returns NO

Parameters:

dataPoint	The dataPoint object responds to valueForKey: for the keys: "type", "units", "attributes", "path", "numberOfRows" and "numberOfColumns". The "numberOfRows" and "numberOfColumns" values are NSNumbers. The value for "type" is an NSNumber whose integer value is one of the VCDataTypes enumeration. The "units" and "path" values are NSString objects and the "attributes" value is an NSDictionary. These values should be sufficient to determine whether or not the data point should be used as an input.
input	The input that the data point may be connected to. If the input is nil, the user has not specified the input, and should this method return YES and a subsequent drop occur inputForDataPoint: will be called to determine which input should be connected. In this case the consumer should decide if any of the available inputs are appropriate (or if it is possible to create a new appropriate input).
tooltip	The implementation may set this to point to an NSString giving a tooltip to show as drag feedback (a reason for rejecting, or a detail regarding what the input will be used for, for instance)

Returns:

This method should return YES if the data point should be accepted, or NO if it should not.

- (VCTimestamp *) youngestDataTimestampForOutput:

(VCOutput *)

output

Return the youngest (largest numerically) timestamp for which data can be produced for the provided output. The default implementation returns the youngest date for which all inputs connected to the data consumer have data available.

Parameters:

output

The output of interest.

Returns:

The youngest possible timestamp for which data can be produced. If data cannot be produced at this time for the output, return nil. A younger timestamp is one that occurs later chronologically- 2009-01-01 is younger than 2000-01-01.

---

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

• VCDataConsumerController.h
• VCDataConsumerController.m