Overview

Aggregate objects into an ensemble for batch opertaions.

topsEnsemble groups together other objects and can access their properties or methods all at once. Individual objects in the ensemble can be accessed or removed by index. The order of objects in the ensemble, can be specified as they're added to the ensemble. This affects the order in which properties and methods will be accessed.

Any objects can be added to an ensemble. The objects should have at least one property name or methods in common, so that they can respond in concert to the same property access or method calls.

topsEnsemble is expected to work with "handle" objects (objects that inherit from the built-in handle class). Other objects or data types may be added, but these may behave poorly:

Non-handle objects may not reflect property changes correctly.
Non-object data types may cause errors when the ensemble attempts to access their properties or methods.

topsEnsemble extends topsCall list. Where topsCall list is able to call arbitrary functions, topsEnsemble can also call arbitrary methods on its aggrigated objects.

Inheritance diagram for topsEnsemble:

[legend]

Protected Properties
Property	objects = {}
	array of objects in the ensemble More...

Property	objectNames = {}
	optional array of object names, for convenience

Methods
self	topsEnsemble (varargin)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

index	addObject (self, object, index)
	Add one object to the ensemble. More...

object	removeObject (self, index)
	Remove one or more objects from the ensemble. More...

object	getObject (self, index)
	Get one or more objects in the ensemble. More...

isMember index	containsObject (self, object)
	Is the given object a member of the ensemble? More...

	assignObject (self, innerIndex, outerIndex, varargin)
	Assign one object to a property of one other object. More...

	passObject (self, innerIndex, outerIndex, method, args, argIndex)
	Pass one object to a method of another object. More...

	setObjectProperty (self, property, value, index)
	Set a property for one or more objects. More...

result	callObjectMethod (self, method, args, index, isCell)
	Call a method for one or more objects. More...

Methods inherited from topsCallList
self	topsCallList (varargin)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

index	addCall (self, fevalable, name)
	Add an "fevalable" to the call list. More...

	setActiveByName (self, isActive, name)
	Toggle whether a call is active. More...

result	callByName (self, name, isActive)
	Invoke a call now, whether or not it's active. More...

	runBriefly (self)
	Invoke active calls in a batch.

Methods inherited from topsConcurrent
self	topsConcurrent (varargin)
	Constuct with name optional. More...

	run (self, duration)
	Do flow control. More...

	runBriefly (self)
	Do a little flow control and return as soon as possible. More...

Methods inherited from topsRunnable
self	topsRunnable (varargin)
	Constuct with name optional. More...

	run (self)
	Do flow control. More...

g	gui (self)
	Show heirarchy of topsRunnable[Composite] objects.

	start (self)
	Log action and prepare to do flow control. More...

	finish (self)
	Log, action and finish doing flow control. More...

	logAction (self, actionName, actionData)
	Log an event of interest with topsDataLog. More...

	logFeval (self, fevalName, fevalable)
	Log a function call with topsDataLog. More...

Methods inherited from topsFoundation
self	topsFoundation (name)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

p	guiPanel (self, varargin)
	Make a topsDetailPanel with details about this object. More...

name string name given to this automated method call

Prepare to repeatedly call a method, for one or more objects.

Parameters

method	function_handle of an ensemble object method
args	optional cell array of arguments to pass to method
index	optional ensemble object index or indexes
isCell	optional whether to pass objects in one cell array
isActive	whether the named method call should be active

Defines an automated method call, with the given name. Any existing call with name will be replaced. The automated call can be treated like other topsCallList calls: it may be invoked by the user with callByName(), or automatically during runBriefly().

By default, automated method calls will be invoked during runBriefly(). If isActive is provided and false, runBriefly() will ignore the named call. Calls may be activated or deactivated later with setActiveByName() or callByName() with the isActive flag.

Prepares to call method, which ensemble objects have in common. If args is provided, the elements of args will be passed as arguments to method.

By default, calls method once per object in the ensemble. If index is provided, it may specify particular ensemble objects. For example, index may specify a subset of objects, or the order in which objects should have method invoked.

By default, iterates through objects, invoking method once per object. If isCell is true, invokes method only once, passing a cell array of objects as the first argument. This assumes that method is a static class method that operates on multiple objects at once. method could also be a regular function.

Returns the index into the calls struct array where the automated method call was appended or inserted.

index automateObjectMethod (self, name, method, args, index, isCell, isActive)

static ensemble makeEnsemble (name, objects)

Convenient utility for combining a bunch of objects into an ensemble. More...

Additional Inherited Members
Properties and Events inherited from topsCallList
	calls
	struct array with fevalable cell arrays to call as a batch

Property	alwaysRunning = true
	true or false, whether to run indefinitely

Property	invertOrder = false
	true or false, invert order of calls

Properties and Events inherited from topsConcurrent
Property	runBrieflyString = 'runBriefly'
	string used for topsDataLog entry just before runBriefly()

Properties and Events inherited from topsRunnable
Property	startFevalable = {}
	optional fevalable cell array to invoke just before running

Property	finishFevalable = {}
	optional fevalable cell array to invoke just after running

Property	isRunning = false
	true or false, whether this object is currently busy running

Property	caller
	topsRunnable that invoked run() on this object, or empty

Property	startString = 'start'
	string used for topsDataLog entry just before run()

Property	finishString = 'finish'
	string used for topsDataLog entry just after run()

Properties and Events inherited from topsFoundation
Property	name = ''
	a string name to indentify the object

Property	clockFunction =@topsClock
	clock function, to standardize

Static Methods inherited from topsCallList
static fevalable	makeFevalable (invertOrder)
	Utility to make a call list as an fevalable. More...

Static Methods inherited from topsFoundation
static c index	cellAdd (c, item, index)
	Add an item to a cell array. More...

static selector	cellContains (c, item)
	Does a cell array conatin an item? More...

static c	cellRemoveItem (c, item)
	Remove an item from a cell array. More...

static c	cellRemoveElement (c, index)
	Remove indexed elements from a cell array. More...

static index selector	findStructName (s, name)
	Where is the given name in the given struct array? More...

Constructor

◆ topsEnsemble()

self topsEnsemble ( varargin )

Constuct with name optional.

Parameters

name	optional name for this object

If name is provided, assigns name to this object.

Methods

◆ gui()

fig gui ( self )

Open a GUI to view object details.

Opens a new GUI with components suitable for viewing objects of this class. Returns a topsFigure object which contains the GUI.

◆ addObject()

index addObject	(	self	,
		object	,
		index
	)

Add one object to the ensemble.

Parameters

object	any object to add to the ensemble
index	optional index where to insert the object

Adds the given object to this ensemble. By default, adds object at the end of the ensemble, so it will be accessed after any other objects. If index is provided it must be a positive integer specifying where to insert object in the ensemble. Any existing object with the same index will be replaced.

topsEnsemble assumes that objects are packed without gaps into its objects array. This will always be the case if index is omitted. If index is provided, care must be taken to pack objects into the ensemble.

Returns the index where object was appended or inserted into the ensemble, which may be the same as the given index.

◆ removeObject()

object removeObject	(	self	,
		index
	)

Remove one or more objects from the ensemble.

Parameters

index ensemble object index or indexes

Removes the indicated object or objects from this ensemble. Since removal changes the size of the ensemble, previously used indexes may become invalid. Returns the object that was removed, or a cell array of removed objects.

◆ getObject()

object getObject	(	self	,
		index
	)

Get one or more objects in the ensemble.

Parameters

index ensemble object index or indexes

Returns the indexed object from this ensemble, or a cell array containing multiple objects.

◆ containsObject()

isMember index containsObject	(	self	,
		object
	)

Is the given object a member of the ensemble?

Parameters

object an object that might be in the ensemble

Returns true if the given object is equal to an object in this ensemble, otherwise returns false. Also returns as a second output the index of the first object found to be equal to the given object. If no object is found to be equal, the returned index will be empty.

◆ assignObject()

assignObject	(	self	,
		innerIndex	,
		outerIndex	,
		varargin
	)

Assign one object to a property of one other object.

Parameters

innerIndex	ensemble index of the object to be assigned
outerIndex	ensemble index of the object that will receive
varargin	asignment specification pased to substruct()

"Wires up" an aggregation relationship between two ensemble objects. innerIndex specifies the inner object which will be assigned to an outer object. outerObject specifies the outer object. Both objects must belong to this ensemble.

varargin specifies how to assign the inner object to the outer object. These trailing arguments will be passed to Matlab's built-in substruct() function. varargin could specify a property of the outer object, or drill down to specify a sub-field or element of a property.

For example, to specify the 'data' property of the outer object, use the following "dot" reference to the 'data' property:

assignObject(@a innerIndex, @a outerIndex, '.', 'data');

The result would be the same as

outerObject.data = innerObject;

Assignment can be undone by passing an empty innerIndex.

◆ passObject()

passObject	(	self	,
		innerIndex	,
		outerIndex	,
		method	,
		args	,
		argIndex
	)

Pass one object to a method of another object.

Parameters

innerIndex	ensemble index of the object to pass
outerIndex	ensemble index of the receiving object
method	function_handle of a receiving object method
args	optional cell array of arguments to pass to method
argIndex	optional index into args of the object to pass

Passes one ensemble object to a method of another ensmble object. innerIndex specifies the inner object which will be passed as an argument. outerObject specifies the outer object which will have its method invoked, and the inner object passed to it. Both objects must belong to this ensemble.

By default, the inner object is passed as the first and only argument to the outer object's method. This case would be equivalent to

outerObject.method(innerObject);

args may contain additional arguments to pass to method. argIndex may specify where in the args to place the inner object. This case would be equivalent to

args{argIndex} = innerObject;

outerObject.method(args{:});

Any value at args{argIndex} will be replaced with the inner object. If argIndex is omitted, it defaults to 1.

◆ setObjectProperty()

setObjectProperty	(	self	,
		property	,
		value	,
		index
	)

Set a property for one or more objects.

Parameters

property	string name of an ensemble object property
value	one value to assign to property
index	optional ensemble object index or indexes

Sets the value of the named property, which ensemble objects have in common. value can be any value to set to all objects.

By default, sets value to all objects in the ensemble. If index is provided, it may specify a subset of ensemble objects.

◆ callObjectMethod()

result callObjectMethod	(	self	,
		method	,
		args	,
		index	,
		isCell
	)

Call a method for one or more objects.

Parameters

method	function_handle of an ensemble object method
args	optional cell array of arguments to pass to method
index	optional ensemble object index or indexes
isCell	optional whether to pass objects in one cell array

Calls the given method, which ensemble objects have in common. If args is provided, passes the elements of args as arguments to method. Returns a cell array with one element per object, containing the first method result from each object. If there is only one object, returns the result without enclosing it in a cell array.

By default, calls method once per object in the ensemble. If index is provided, it may specify particular ensemble objects. For example, index may specify a subset of objects, or the order in which objects should have method invoked.

By default, iterates through objects, invoking method once per object. If isCell is true, invokes method only once, passing a cell array of objects as the first argument. This assumes that method is a static class method that operates on multiple objects at once. method could also be a regular function.

◆ makeEnsemble()

static ensemble makeEnsemble	(	name	,
		objects
	)

static

Convenient utility for combining a bunch of objects into an ensemble.

Aguments: name ... optional <string> name of the ensemble/composite objects ... cell array of objects

Properties and Events

◆ objects

which ensemble objects = {}

protected

array of objects in the ensemble

Get a property value for one or more objects.

Parameters

property	string name of an ensemble object property
index	optional ensemble object index or indexes

Gets the value of the named have in common. Returns a cell array with one element per object, containing each property value. If there is only one object, returns the value without enclosing it in a cell array.

By default, gets a value from each each ensemble object. If index is provided, it may specify a subset of ensemble objects.

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

topsEnsemble.m

Overview

Protected Properties

Methods

name string name given to this automated method call

Additional Inherited Members

Constructor

◆ topsEnsemble()

Methods

◆ gui()

◆ addObject()

◆ removeObject()

◆ getObject()

◆ containsObject()

◆ assignObject()

◆ passObject()

◆ setObjectProperty()

◆ callObjectMethod()

◆ makeEnsemble()

Properties and Events

◆ objects