Programming Reference:Environment Class - Revision history

Mellinger: /* Access to Parameters and States */

2026-05-12T16:12:37Z

Access to Parameters and States

← Older revision		Revision as of 16:12, 12 May 2026
Line 29:		Line 29:
	==Access to Parameters and States==		==Access to Parameters and States==
	From any code inside <tt>MyClass</tt>, you may then read or set		From any code inside <tt>MyClass</tt>, you may then read or set
	parameter ~~and state~~ values simply by writing		parameter values simply by writing
	<pre>		<pre>
	int numberOfItems = Parameter( "NumberOfItems" );		int numberOfItems = Parameter( "NumberOfItems" );
Line 43:		Line 43:
	Filtering matrix MatrixParamWithLabels= [ myRow1 myRow2 myRow3 ] [ myColumn1 myColumn2 myColumn3 ] 1 2 3 4 5 6 7 8 9 % % % // An example parameter with labels		Filtering matrix MatrixParamWithLabels= [ myRow1 myRow2 myRow3 ] [ myColumn1 myColumn2 myColumn3 ] 1 2 3 4 5 6 7 8 9 % % % // An example parameter with labels
	</pre>		</pre>
			For access to states, you may write
	<pre>		<pre>
	short feedbackState = State( "Feedback" );		short feedbackState = State( "Feedback" );

Mellinger: /* Access to Parameters and States */

2026-05-12T16:06:21Z

Access to Parameters and States

← Older revision		Revision as of 16:06, 12 May 2026
Line 37:		Line 37:
	float nestedMatrixValue		float nestedMatrixValue
	= Parameter( "NestedMatrices" )( index1, index2 )( index3, index4 );		= Parameter( "NestedMatrices" )( index1, index2 )( index3, index4 );
			</pre>
			As you can see, it is possible to use strings as indices into rows and columns of parameters.
			This is possible if the user added row or column names by clicking column or row headings, or if the parameter was defined with row and/or column names (labels):
			<pre>
			Filtering matrix MatrixParamWithLabels= [ myRow1 myRow2 myRow3 ] [ myColumn1 myColumn2 myColumn3 ] 1 2 3 4 5 6 7 8 9 % % % // An example parameter with labels
			</pre>
			<pre>
	short feedbackState = State( "Feedback" );		short feedbackState = State( "Feedback" );
	State( "Feedback" ) = 0;		State( "Feedback" ) = 0;

Mellinger: /* Access to Parameters and States */

2026-05-12T15:59:58Z

Access to Parameters and States

← Older revision		Revision as of 15:59, 12 May 2026
Line 34:		Line 34:
	float listValue = Parameter( "ListParam" )( index );		float listValue = Parameter( "ListParam" )( index );
	float matrixValue = Parameter( "MatrixParam" )( index1, index2 );		float matrixValue = Parameter( "MatrixParam" )( index1, index2 );
			float anotherMatrixValue = Parameter( "MatrixParam" )( "myRow", "myColumn" );
	float nestedMatrixValue		float nestedMatrixValue
	= Parameter( "NestedMatrices" )( index1, index2 )( index3, index4 );		= Parameter( "NestedMatrices" )( index1, index2 )( index3, index4 );

Mellinger: /* Access to Parameters and States */

2012-06-13T11:34:49Z

Access to Parameters and States

← Older revision		Revision as of 11:34, 13 June 2012
Line 73:		Line 73:

	The Environment class imposes [[Programming Reference:GenericFilter Class#Rules_for_Parameter_and_State_access\|rules for parameter and state access]] intended to help avoid parameterization inconsistencies.		The Environment class imposes [[Programming Reference:GenericFilter Class#Rules_for_Parameter_and_State_access\|rules for parameter and state access]] intended to help avoid parameterization inconsistencies.



	==See also==		==See also==

Mellinger: /* Working around Borland VCL Inheritance Restrictions */

2012-06-13T11:34:36Z

Working around Borland VCL Inheritance Restrictions

← Older revision		Revision as of 11:34, 13 June 2012
Line 74:		Line 74:
	The Environment class imposes [[Programming Reference:GenericFilter Class#Rules_for_Parameter_and_State_access\|rules for parameter and state access]] intended to help avoid parameterization inconsistencies.		The Environment class imposes [[Programming Reference:GenericFilter Class#Rules_for_Parameter_and_State_access\|rules for parameter and state access]] intended to help avoid parameterization inconsistencies.

	~~==Working around Borland VCL Inheritance Restrictions==~~
	~~Due to some non-standard conventions in Borland's VCL library, you~~
	~~cannot create a VCL class such as a <tt>TForm</tt> descendant that~~
	~~also~~
	~~inherits from <tt>Environment</tt> -- the compiler will report an~~
	~~error~~
	~~if you try.~~
	~~As a work-around, you might declare an <tt>Environment</tt> subclass~~
	~~''inside'' your VCL <tt>TForm</tt> child declaration,~~
	~~and create a single instance <tt>mEnv</tt> of this subclass as a~~
	~~member~~
	~~of your class, using it to access the <tt>Environment</tt> functions~~
	~~as in~~
	~~<pre>~~
	~~MyForm : public TForm~~
	{
	~~class MyFormEnvironment;~~
	~~friend class MyFormEnvironment;~~
	~~...~~
	~~private:~~
	~~class MyFormEnvironment : private Environment~~
	{
	~~public:~~
	~~MyFormEnvironment( MyForm& parent );~~
	~~void Preflight() const;~~
	~~void Initialize();~~
	~~private:~~
	~~MyForm& mParent;~~
	~~} mEnv;~~
	};

	~~...~~

	~~MyForm::MyFormEnvironment( MyForm& parent )~~
	~~: mParent( parent )~~
	{
	~~BEGIN_PARAMETER_DEFINITIONS~~
	~~"UsrTask int MyParam= 1 1 0 5 // my parameter",~~
	~~END_PARAMETER_DEFINITIONS~~
	}

	~~...~~

	~~void~~
	~~MyForm::Initialize()~~
	{
	~~mEnv.Initialize();~~
	}

	~~void~~
	~~MyForm::MyFormEnvironment::Initialize()~~
	{
	~~mParent.mMyParam = Parameter( "MyParam" );~~
	}
	~~</pre>~~
	~~This should work in situations where your code's class model is~~
	~~centered around~~
	~~VCL form classes.~~
	~~When writing new code, you might consider basing your class model on~~
	~~functionality, and use VCL forms merely for input and output --~~
	~~instantiating,~~
	~~populating, and deleting them as you need them, such that the BCI2000~~
	~~<tt>Environment</tt> interfacing is done from your own classes,~~
	~~independently~~
	~~of the VCL's special requirements.~~

	==See also==		==See also==

Mellinger at 12:17, 23 August 2011

2011-08-23T12:17:47Z

@@ Line 73: / Line 73: @@
 The Environment class imposes [[Programming Reference:GenericFilter Class#Rules_for_Parameter_and_State_access|rules for parameter and state access]] intended to help avoid parameterization inconsistencies.
 ==Working around Borland VCL Inheritance Restrictions==
@@ Line 171: / Line 141: @@
 ==See also==
-[[Programming Reference:Errors and Warnings]]
+[[Programming Reference:Errors and Warnings]], [[Programming Reference:ApplicationWindowClient Class]]
 [[Category:Framework API]][[Category:Development]]

Mellinger at 12:27, 17 August 2011

2011-08-17T12:27:03Z

← Older revision		Revision as of 12:27, 17 August 2011
Line 1:		Line 1:
			<tt>Environment</tt> is a mix-in class that provides access to system-wide parameters and states. Though client classes may directly inherit from it, most do so via interface classes that themselves do inherit from the <tt>Environment</tt> class, most importantly the [[Programming Reference:GenericFilter Class\|GenericFilter]] and [[Programming Reference:EnvironmentExtension Class\|EnvironmentExtension]] classes.

	==Your code's <tt>Environment</tt>==		==Your code's <tt>Environment</tt>==
	In each [[Technical Reference:Core Modules\|BCI2000 core module]], there exist system wide		In each [[Technical Reference:Core Modules\|BCI2000 core module]], there exist system wide

Mellinger: /* Access to Application Windows */

2011-07-11T12:38:17Z

Access to Application Windows

← Older revision		Revision as of 12:38, 11 July 2011
Line 96:		Line 96:
	<tt>ApplicationWindow</tt> instances are created by using the <tt>Environment::Window( name )</tt> function during a module's construction phase, typically from a <tt>GenericFilter</tt> descendant's constructor (for an example, see [[Programming Reference:ApplicationWindow Class#Usage\|the <tt>ApplicationWindow</tt> class page]]. If an application window with that name already exists, it will be shared amongst filters which access it.		<tt>ApplicationWindow</tt> instances are created by using the <tt>Environment::Window( name )</tt> function during a module's construction phase, typically from a <tt>GenericFilter</tt> descendant's constructor (for an example, see [[Programming Reference:ApplicationWindow Class#Usage\|the <tt>ApplicationWindow</tt> class page]]. If an application window with that name already exists, it will be shared amongst filters which access it.

	If you don't want to create an application window, but only access an existing one, you need to ~~test for existence of~~ that window during the preflight phase. In your <tt>Environment</tt> descendant's <tt>Preflight()</tt> member function, write:		If you don't want to create an application window, but only access an existing one, you need to declare access to that window during the preflight phase. In your <tt>Environment</tt> descendant's <tt>Preflight()</tt> member function, write:
	<pre>		<pre>
	Window( "Application" );		Window( "Application" );
	</pre>		</pre>
	When no such window exists, a preflight error will be reported. Unless the window has been accessed during the construction phase, not ~~testing for existence of~~ the window during the preflight phase will result in an error message when calling <tt>Environment::Window()</tt> from elsewhere.		When no such window exists, a preflight error will be reported. Unless the window has been accessed during the construction phase, not declaring access to the window during the preflight phase will result in an error message when calling <tt>Environment::Window()</tt> from elsewhere.

	==Working around Borland VCL Inheritance Restrictions==		==Working around Borland VCL Inheritance Restrictions==

Mellinger: /* Access to Application Windows */

2011-07-11T12:36:23Z

Access to Application Windows

← Older revision		Revision as of 12:36, 11 July 2011
Line 73:		Line 73:

	==Access to Application Windows==		==Access to Application Windows==
	In Application Modules, the Environment class provides access to application windows which are instances of ~~(or descend from)~~ [[Programming Reference:ApplicationWindow Class\|the <tt>ApplicationWindow</tt> class]]. <tt>ApplicationWindow</tt> instances have names, with the default name being "Application". A window's name may be used to obtain a [[Programming Reference:DisplayWindow Class\|<tt>DisplayWindow</tt>]] reference to the window, e.g.		In Application Modules, the Environment class provides access to application windows which are instances of [[Programming Reference:ApplicationWindow Class\|the <tt>ApplicationWindow</tt> class]]. <tt>ApplicationWindow</tt> instances have names, with the default name being "Application". A window's name may be used to obtain a [[Programming Reference:DisplayWindow Class\|<tt>DisplayWindow</tt>]] reference to the window, e.g.
	<pre>		<pre>
	DisplayWindow& applicationWindow = Window( "Application" );		DisplayWindow& applicationWindow = Window( "Application" );

Mellinger: /* Access to Application Windows */

2011-07-07T16:08:36Z

Access to Application Windows

← Older revision		Revision as of 16:08, 7 July 2011
Line 78:		Line 78:
	applicationWindow.SetTop( 15 );		applicationWindow.SetTop( 15 );
	</pre>		</pre>
	Const access to the underlying list of windows is provided via the <tt>Windows()</tt> ~~function~~. This allows to write		Const access to the underlying list of windows is provided via the <tt>Environment::Windows</tt> pointer. This allows to write
	<pre>		<pre>
	if( Windows()->Exists( "Application" ) )		if( Windows->Exists( "Application" ) )
	{		{
	DisplayWindow& applicationWindow = Window( "Application" );		DisplayWindow& applicationWindow = Window( "Application" );
Line 89:		Line 89:
	It also allows to iterate over existing windows:		It also allows to iterate over existing windows:
	<pre>		<pre>
	for( int i = 0; i < Windows()->Size(); ++i )		for( int i = 0; i < Windows->Size(); ++i )
	{		{
	bciout << ( *Windows() )[i].Name() << endl;		bciout << ( *Windows )[i].Name() << endl;
	}		}
	</pre>		</pre>