Superclass for all Display plugins. Users writing Displays should subclass from this directly, not from VCDataConsumerController. More...
Public Member Functions | |
Display Functionality Methods | |
These methods are specific displays and provide functionality only open to Displays, and are intended to be called by subclasses. They should not be overridden. | |
(BOOL) | - shouldUpdate |
Determine whether or not sufficient time has passed since the last update to justify a redraw. | |
(void) | - didUpdate |
Record that a redraw has ocurred. | |
(void) | - setViewFrame: |
Change the frame for the display's view. | |
(NSRect) | - visibleViewFrame |
Retrieve the current frame for the display's view. | |
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. | |
Display Methods For Override | |
These methods are specific to Displays, and should be overridden by subclasses as necessary to customize specific functionality of the display. | |
(NSSize) | + initialSize |
Provide an initial size for newly instantiated displays for this plugin. | |
(void) | - displayShouldRedraw |
Called to indicate that the display should redraw itself. | |
(NSView *) | - view |
Provide the view into which the display will draw. | |
(float) | - displayRatio |
Define the optimal height/width ratio. | |
(NSView *) | - showHelpIndicator |
Provide a custom help indicator. | |
(void) | - hideHelpIndicator |
Hide a custom help indicator. |
Display plugins are a subset of Data Consumer plugins that also provide a view into which some data visualization (or some other UI) is drawn. This view is then placed within a page in VisualCommander and controlled by the user. Other than the functionality related to dealing with this view, a display is simply a data consumer. Please see the VCDataConsumer documentation for details of functionality shared between Displays and Processors.
- (NSSet *) allCommandOutlets |
Retrieve a set containing all command outlets at this data consumer
- (NSSet *) allInputs |
Retrieve a set containing all inputs at the data consumer
- (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.
- (NSSet *) allInputSets |
Retrieve all input sets at this data consumer
- (NSSet *) allInputsInSet: | (VCInputSet *) | inputSet |
Retrieve all inputs in the provided input set.
inputSet | The for which inputs should be returned, or nil to retrieve all inputs that are not in an input set. |
- (NSSet *) allOutputs |
Retrieve a set containing all outputs at this data consumer.
- (VCCommandOutlet *) anyCommandOutlet |
Retrieve a single command outlet connected to this data consumer.
- (VCInput *) anyInput |
Retrieve a single input attached to this data consumer.
+ (NSString *) category |
Provide an optional category for this plugin. Plugins that return the same category will be grouped together in the tools palette.
- (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.
name | The name to match. |
- (VCCommandOutlet *) commandOutletWithName: | (NSString *) | name |
Returns a single command outlet with the given name.
name | The name to match |
- (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.
- (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.
- (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.
- (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.
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.
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. |
- (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.
outlet | The command outlet to which the command should be connected |
command | The command to connect to the outlet. |
+ (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:
- (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.)
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. |
- (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.
name | The name for the new command outlet. |
- (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.
name | The name to give the new input set. |
- (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.
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. |
- (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.
name | The name for the new output. |
dataType | The data type of the data produced by the output |
- (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.
output | The output of interest. |
- (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.
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. |
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.
output | The output of interest. |
- (void) destroyCommandOutlet: | (VCCommandOutlet *) | outlet |
Destroy a command outlet object and remove it from this data consumer.
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.
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.
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.
output | The output to destroy |
- (void) didUpdate |
Call this function at the end of any displayShouldRedraw call that does not terminate early due to shouldUpdate returning NO. This call records the current time as the time of the most recent redraw.
- (void) disconnectCommandOutlet: | (VCCommandOutlet *) | outlet |
Disconnect a command outlet from the command that it is currently connected to, if any.
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.
input | The input to be disconnected. |
- (float) displayRatio |
Subclasses may override to supply an optimal display ratio - for instance, the same ratio as an enclosed image. Views resize to this ratio when the view is shift-dragged.
- (void) displayShouldRedraw |
VisualCommander will call this method on the data consumer controller when the display should redraw itself to respond to newly available data or a change in the current time or current run number that the user is viewing. The default implementation does nothing.
It is important to note that this is not equivalent to a drawRect call; the display's view is not given focus and no drawing commands should ocurr here. However, this would be the appropriate place to call setNeedsDisplay on the display's view.
Reimplemented from VCDataConsumerController.
- (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.
- (void) hideHelpIndicator |
Overridden from VCDataConsumerController to hide the visible help indicator button shown by showHelpIndicator. If showHelpIndicator is overridden, this method must also be overridden.
Reimplemented from VCDataConsumerController.
+ (NSSize) initialSize |
Subclasses should override to return the prefered initial size of the display view. This is used to calculate the initial frame for the display.
- (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.
anEntity | The entity for this data consumer controller. |
- (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.
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.
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.
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.
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.
elementPath | the path to search for |
- (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.
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. |
- (NSSet *) inputSetsWithName: | (NSString *) | name |
Retrieve all inputs matching the provided name.
name | The name to search for. |
- (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.
referencePath | The path to search for |
- (NSSet *) inputsWithName: | (NSString *) | name |
Retrieve all inputs with a name that matches the provided string
name | The name to match. |
- (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.
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. |
- (VCInput *) inputWithName: | (NSString *) | name | |
inSet: | (VCInputSet *) | inputSet | |
Returns a single VCInput with the given name in the given set.
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. |
- (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.
nibName | The name of the nib to load. |
+ (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.
- (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.
output | The output of interest. |
- (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.
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.
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.
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 |
- (NSSet *) outputsWithName: | (NSString *) | name |
Retrieve the set of outputs with a name that matches the provided string.
name | The name to match. |
- (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.
- (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.
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.
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.
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. |
- (void) setViewFrame: | (NSRect) | newFrame |
To change the size of the view programmatically, use this function; don't change your view's size directly.
newFrame | The new frame to set for the display. |
- (BOOL) shouldUpdate |
This method can be used to throttle the rate of draw updates. Displays have a general property allowing the user to specificy a maximum update rate; by checking with shouldUpdate and returning prematurely from a call to displayShouldRedraw if it returns NO, the display can obey the user's expressed update rate throttle. This method should be paired with a call to didUpdate at the end of any displayShouldRedraw call that is not exited early.
- (NSView *) showHelpIndicator |
Overridden from VCDataConsumerController to show a visible help indicator button in an overlay window. The view containing the button is returned for additional cursor tracking. Subclasses can override this method to provide a different way for the user to access help, but this is generally not recommended.
Reimplemented from VCDataConsumerController.
+ (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.
+ (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.
- (VCValue *) valueAtTime: | (VCTimestamp *) | timestamp | |
forOutput: | (VCOutput *) | output | |
Calculate the value of an output at the specified time. The default implementation returns nil.
timestamp | The timestamp for which a value should be calculated. |
output | The output of interest. |
- (NSView *) view |
Subclasses must override this method to return the display's view. This method may be invoked multiple times, so care should be taken that any resources loaded in this method are not unnecessarily reloaded in case of multiple invokations.
Reimplemented from VCDataConsumerController.
- (NSRect) visibleViewFrame |
Retrieve the current saved frame for this Display
- (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.
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) |
- (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
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) |
- (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.
output | The output of interest. |