Audacity  2.2.2
Public Member Functions | Private Member Functions | List of all members
EffectReverse Class Referencefinal

An Effect that reverses the selected audio. More...

#include <Reverse.h>

Inheritance diagram for EffectReverse:
Effect EffectClientInterface EffectUIClientInterface EffectHostInterface EffectDefinitionInterface ConfigClientInterface IdentInterface ParamsInterface

Public Member Functions

 EffectReverse ()
 
virtual ~EffectReverse ()
 
IdentInterfaceSymbol GetSymbol () override
 
wxString GetDescription () override
 
EffectType GetType () override
 
bool IsInteractive () override
 
bool Process () override
 
- Public Member Functions inherited from Effect
 Effect ()
 
virtual ~Effect ()
 
wxString GetPath () override
 
IdentInterfaceSymbol GetVendor () override
 
wxString GetVersion () override
 
IdentInterfaceSymbol GetFamilyId () override
 
bool IsDefault () override
 
bool IsLegacy () override
 
bool SupportsRealtime () override
 
bool SupportsAutomation () override
 
bool SetHost (EffectHostInterface *host) override
 
unsigned GetAudioInCount () override
 
unsigned GetAudioOutCount () override
 
int GetMidiInCount () override
 
int GetMidiOutCount () override
 
sampleCount GetLatency () override
 
size_t GetTailSize () override
 
void SetSampleRate (double rate) override
 
size_t SetBlockSize (size_t maxBlockSize) override
 
bool IsReady () override
 
bool ProcessInitialize (sampleCount totalLen, ChannelNames chanMap=NULL) override
 
bool ProcessFinalize () override
 
size_t ProcessBlock (float **inBlock, float **outBlock, size_t blockLen) override
 
bool RealtimeInitialize () override
 
bool RealtimeAddProcessor (unsigned numChannels, float sampleRate) override
 
bool RealtimeFinalize () override
 
bool RealtimeSuspend () override
 
bool RealtimeResume () override
 
bool RealtimeProcessStart () override
 
size_t RealtimeProcess (int group, float **inbuf, float **outbuf, size_t numSamples) override
 
bool RealtimeProcessEnd () override
 
bool ShowInterface (wxWindow *parent, bool forceModal=false) override
 
bool GetAutomationParameters (CommandParameters &parms) override
 
bool SetAutomationParameters (CommandParameters &parms) override
 
bool LoadUserPreset (const wxString &name) override
 
bool SaveUserPreset (const wxString &name) override
 
wxArrayString GetFactoryPresets () override
 
bool LoadFactoryPreset (int id) override
 
bool LoadFactoryDefaults () override
 
void SetHostUI (EffectUIHostInterface *host) override
 
bool PopulateUI (wxWindow *parent) override
 
bool IsGraphicalUI () override
 
bool ValidateUI () override
 
bool HideUI () override
 
bool CloseUI () override
 
bool CanExportPresets () override
 
void ExportPresets () override
 
void ImportPresets () override
 
bool HasOptions () override
 
void ShowOptions () override
 
double GetDefaultDuration () override
 
double GetDuration () override
 
NumericFormatId GetDurationFormat () override
 
virtual NumericFormatId GetSelectionFormat ()
 
void SetDuration (double duration) override
 
bool Apply () override
 
void Preview () override
 
wxDialog * CreateUI (wxWindow *parent, EffectUIClientInterface *client) override
 
wxString GetUserPresetsGroup (const wxString &name) override
 
wxString GetCurrentSettingsGroup () override
 
wxString GetFactoryDefaultsGroup () override
 
virtual wxString GetSavedStateGroup ()
 
bool HasSharedConfigGroup (const wxString &group) override
 
bool GetSharedConfigSubgroups (const wxString &group, wxArrayString &subgroups) override
 
bool GetSharedConfig (const wxString &group, const wxString &key, wxString &value, const wxString &defval=wxEmptyString) override
 
bool GetSharedConfig (const wxString &group, const wxString &key, int &value, int defval=0) override
 
bool GetSharedConfig (const wxString &group, const wxString &key, bool &value, bool defval=false) override
 
bool GetSharedConfig (const wxString &group, const wxString &key, float &value, float defval=0.0) override
 
bool GetSharedConfig (const wxString &group, const wxString &key, double &value, double defval=0.0) override
 
bool SetSharedConfig (const wxString &group, const wxString &key, const wxString &value) override
 
bool SetSharedConfig (const wxString &group, const wxString &key, const int &value) override
 
bool SetSharedConfig (const wxString &group, const wxString &key, const bool &value) override
 
bool SetSharedConfig (const wxString &group, const wxString &key, const float &value) override
 
bool SetSharedConfig (const wxString &group, const wxString &key, const double &value) override
 
bool RemoveSharedConfigSubgroup (const wxString &group) override
 
bool RemoveSharedConfig (const wxString &group, const wxString &key) override
 
bool HasPrivateConfigGroup (const wxString &group) override
 
bool GetPrivateConfigSubgroups (const wxString &group, wxArrayString &subgroups) override
 
bool GetPrivateConfig (const wxString &group, const wxString &key, wxString &value, const wxString &defval=wxEmptyString) override
 
bool GetPrivateConfig (const wxString &group, const wxString &key, int &value, int defval=0) override
 
bool GetPrivateConfig (const wxString &group, const wxString &key, bool &value, bool defval=false) override
 
bool GetPrivateConfig (const wxString &group, const wxString &key, float &value, float defval=0.0) override
 
bool GetPrivateConfig (const wxString &group, const wxString &key, double &value, double defval=0.0) override
 
bool SetPrivateConfig (const wxString &group, const wxString &key, const wxString &value) override
 
bool SetPrivateConfig (const wxString &group, const wxString &key, const int &value) override
 
bool SetPrivateConfig (const wxString &group, const wxString &key, const bool &value) override
 
bool SetPrivateConfig (const wxString &group, const wxString &key, const float &value) override
 
bool SetPrivateConfig (const wxString &group, const wxString &key, const double &value) override
 
bool RemovePrivateConfigSubgroup (const wxString &group) override
 
bool RemovePrivateConfig (const wxString &group, const wxString &key) override
 
virtual PluginID GetID ()
 
virtual bool Startup (EffectClientInterface *client)
 
virtual bool Startup ()
 
virtual bool GetAutomationParameters (wxString &parms)
 
virtual bool SetAutomationParameters (const wxString &parms)
 
virtual wxArrayString GetUserPresets ()
 
virtual bool HasCurrentSettings ()
 
virtual bool HasFactoryDefaults ()
 
virtual wxString GetPreset (wxWindow *parent, const wxString &parms)
 
virtual wxString ManualPage ()
 
virtual wxString HelpPage ()
 
virtual bool IsBatchProcessing ()
 
virtual void SetBatchProcessing (bool start)
 
void SetPresetParameters (const wxArrayString *Names, const wxArrayString *Values)
 
bool DoEffect (wxWindow *parent, double projectRate, TrackList *list, TrackFactory *factory, SelectedRegion *selectedRegion, bool shouldPrompt=true)
 
bool Delegate (Effect &delegate, wxWindow *parent, bool shouldPrompt)
 
bool RealtimeAddProcessor (int group, unsigned chans, float rate)
 
size_t RealtimeProcess (int group, unsigned chans, float **inbuf, float **outbuf, size_t numSamples)
 
bool IsRealtimeActive ()
 
virtual bool IsHidden ()
 
int MessageBox (const wxString &message, long style=DefaultMessageBoxStyle, const wxString &titleStr=wxString{})
 
- Public Member Functions inherited from EffectClientInterface
virtual ~EffectClientInterface ()
 
- Public Member Functions inherited from EffectDefinitionInterface
virtual ~EffectDefinitionInterface ()
 
- Public Member Functions inherited from IdentInterface
virtual ~IdentInterface ()
 
const wxString & GetTranslatedName ()
 
- Public Member Functions inherited from ParamsInterface
virtual ~ParamsInterface ()
 
virtual bool DefineParams (ShuttleParams &WXUNUSED(S))
 
- Public Member Functions inherited from EffectUIClientInterface
virtual ~EffectUIClientInterface ()
 
- Public Member Functions inherited from EffectHostInterface
virtual ~EffectHostInterface ()
 
- Public Member Functions inherited from ConfigClientInterface
virtual ~ConfigClientInterface ()
 

Private Member Functions

bool ProcessOneClip (int count, WaveTrack *track, sampleCount start, sampleCount len, sampleCount originalStart, sampleCount originalEnd)
 
bool ProcessOneWave (int count, WaveTrack *track, sampleCount start, sampleCount len)
 

Additional Inherited Members

- Public Types inherited from Effect
enum  : long { DefaultMessageBoxStyle = wxOK | wxCENTRE }
 
- Protected Member Functions inherited from Effect
virtual bool Init ()
 
virtual bool PromptUser (wxWindow *parent)
 
virtual bool CheckWhetherSkipEffect ()
 
virtual bool ProcessPass ()
 
virtual bool InitPass1 ()
 
virtual bool InitPass2 ()
 
virtual int GetPass ()
 
virtual void End ()
 
virtual double CalcPreviewInputLength (double previewLength)
 
virtual void Preview (bool dryOnly)
 
virtual void PopulateOrExchange (ShuttleGui &S)
 
virtual bool TransferDataToWindow ()
 
virtual bool TransferDataFromWindow ()
 
virtual bool EnableApply (bool enable=true)
 
virtual bool EnablePreview (bool enable=true)
 
virtual void EnableDebug (bool enable=true)
 
bool TotalProgress (double frac)
 
bool TrackProgress (int whichTrack, double frac, const wxString &=wxEmptyString)
 
bool TrackGroupProgress (int whichGroup, double frac, const wxString &=wxEmptyString)
 
int GetNumWaveTracks ()
 
int GetNumWaveGroups ()
 
void GetSamples (const WaveTrack *track, sampleCount *start, sampleCount *len)
 
void SetLinearEffectFlag (bool linearEffectFlag)
 
void SetPreviewFullSelectionFlag (bool previewDurationFlag)
 
bool IsPreviewing ()
 
void IncludeNotSelectedPreviewTracks (bool includeNotSelected)
 
void CopyInputTracks ()
 
void CopyInputTracks (int trackType)
 
std::shared_ptr
< AddedAnalysisTrack
AddAnalysisTrack (const wxString &name=wxString())
 
ModifiedAnalysisTrack ModifyAnalysisTrack (const LabelTrack *pOrigTrack, const wxString &name=wxString())
 
void ReplaceProcessedTracks (const bool bGoodResult)
 
TrackAddToOutputTracks (std::unique_ptr< Track > &&t)
 
TrackListinputTracks () const
 
- Protected Attributes inherited from Effect
ProgressDialogmProgress
 
double mProjectRate
 
double mSampleRate
 
SelectedRegionmpSelectedRegion {}
 
TrackFactorymFactory
 
std::shared_ptr< TrackListmOutputTracks
 
double mT0
 
double mT1
 
double mF0
 
double mF1
 
wxArrayString mPresetNames
 
wxArrayString mPresetValues
 
int mPass
 
wxDialog * mUIDialog
 
wxWindow * mUIParent
 
int mUIResultID
 
sampleCount mSampleCnt
 
int mOutputTracksType
 

Detailed Description

An Effect that reverses the selected audio.

Definition at line 22 of file Reverse.h.

Constructor & Destructor Documentation

EffectReverse::EffectReverse ( )

Definition at line 31 of file Reverse.cpp.

32 {
33 }
EffectReverse::~EffectReverse ( )
virtual

Definition at line 35 of file Reverse.cpp.

36 {
37 }

Member Function Documentation

wxString EffectReverse::GetDescription ( )
overridevirtual

Reimplemented from Effect.

Definition at line 46 of file Reverse.cpp.

References _().

47 {
48  return _("Reverses the selected audio");
49 }
_("Move Track &Down")+wxT("\t")+(GetActiveProject() -> GetCommandManager() ->GetKeyFromName(wxT("TrackMoveDown")).Raw()), OnMoveTrack) POPUP_MENU_ITEM(OnMoveTopID, _("Move Track to &Top")+wxT("\t")+(GetActiveProject() ->GetCommandManager() ->GetKeyFromName(wxT("TrackMoveTop")).Raw()), OnMoveTrack) POPUP_MENU_ITEM(OnMoveBottomID, _("Move Track to &Bottom")+wxT("\t")+(GetActiveProject() ->GetCommandManager() ->GetKeyFromName(wxT("TrackMoveBottom")).Raw()), OnMoveTrack)#define SET_TRACK_NAME_PLUGIN_SYMBOLclass SetTrackNameCommand:public AudacityCommand
IdentInterfaceSymbol EffectReverse::GetSymbol ( )
overridevirtual

Reimplemented from Effect.

Definition at line 41 of file Reverse.cpp.

References REVERSE_PLUGIN_SYMBOL.

42 {
43  return REVERSE_PLUGIN_SYMBOL;
44 }
#define REVERSE_PLUGIN_SYMBOL
Definition: Reverse.h:20
EffectType EffectReverse::GetType ( )
overridevirtual

Reimplemented from Effect.

Definition at line 53 of file Reverse.cpp.

References EffectTypeProcess.

54 {
55  return EffectTypeProcess;
56 }
bool EffectReverse::IsInteractive ( )
overridevirtual

Reimplemented from Effect.

Definition at line 58 of file Reverse.cpp.

59 {
60  return false;
61 }
bool EffectReverse::Process ( )
overridevirtual

Reimplemented from Effect.

Definition at line 65 of file Reverse.cpp.

References Track::All, LabelTrack::ChangeLabelsOnReverse(), Effect::CopyInputTracks(), Track::Label, Effect::mOutputTracks, Effect::mT0, Effect::mT1, ProcessOneWave(), Effect::ReplaceProcessedTracks(), WaveTrack::TimeToLongSamples(), and Track::Wave.

66 {
67  //Track::All is needed because Reverse should move the labels too
68  this->CopyInputTracks(Track::All); // Set up mOutputTracks.
69  bool bGoodResult = true;
70 
71  TrackListIterator iter(mOutputTracks.get());
72  Track *t = iter.First();
73  int count = 0;
74  while (t) {
75  if (t->GetKind() == Track::Wave &&
76  (t->GetSelected() || t->IsSyncLockSelected()))
77  {
78  WaveTrack *track = (WaveTrack*)t;
79 
80  if (mT1 > mT0) {
81  auto start = track->TimeToLongSamples(mT0);
82  auto end = track->TimeToLongSamples(mT1);
83  auto len = end - start;
84 
85  if (!ProcessOneWave(count, track, start, len))
86  {
87  bGoodResult = false;
88  break;
89  }
90  }
91  }
92  else if (t->GetKind() == Track::Label &&
93  (t->GetSelected() || t->IsSyncLockSelected()))
94  {
95  LabelTrack *track = (LabelTrack*)t;
96  track->ChangeLabelsOnReverse(mT0, mT1);
97  }
98  t = iter.Next();
99  count++;
100  }
101 
102  this->ReplaceProcessedTracks(bGoodResult);
103  return bGoodResult;
104 }
double mT1
Definition: Effect.h:461
void ChangeLabelsOnReverse(double b, double e)
Definition: LabelTrack.cpp:213
void CopyInputTracks()
Definition: Effect.cpp:2036
bool ProcessOneWave(int count, WaveTrack *track, sampleCount start, sampleCount len)
Definition: Reverse.cpp:106
void ReplaceProcessedTracks(const bool bGoodResult)
Definition: Effect.cpp:2162
A LabelTrack is a Track that holds labels (LabelStruct).
Definition: LabelTrack.h:113
A Track that contains audio waveform data.
Definition: WaveTrack.h:60
Fundamental data object of Audacity, placed in the TrackPanel. Classes derived form it include the Wa...
Definition: Track.h:102
An iterator for a TrackList.
Definition: Track.h:402
sampleCount TimeToLongSamples(double t0) const
Convert correctly between an (absolute) time in seconds and a number of samples.
Definition: WaveTrack.cpp:1843
std::shared_ptr< TrackList > mOutputTracks
Definition: Effect.h:459
double mT0
Definition: Effect.h:460
bool EffectReverse::ProcessOneClip ( int  count,
WaveTrack track,
sampleCount  start,
sampleCount  len,
sampleCount  originalStart,
sampleCount  originalEnd 
)
private

Definition at line 215 of file Reverse.cpp.

References floatSample, WaveTrack::Get(), WaveTrack::GetBestBlockSize(), WaveTrack::GetMaxBlockSize(), limitSampleBufferSize(), WaveTrack::Set(), and Effect::TrackProgress().

Referenced by ProcessOneWave().

218 {
219  bool rc = true;
220  // keep track of two blocks whose data we will swap
221  auto first = start;
222 
223  auto blockSize = track->GetMaxBlockSize();
224  float tmp;
225  Floats buffer1{ blockSize };
226  Floats buffer2{ blockSize };
227 
228  auto originalLen = originalEnd - originalStart;
229 
230  while (len > 1) {
231  auto block =
232  limitSampleBufferSize( track->GetBestBlockSize(first), len / 2 );
233  auto second = first + (len - block);
234 
235  track->Get((samplePtr)buffer1.get(), floatSample, first, block);
236  track->Get((samplePtr)buffer2.get(), floatSample, second, block);
237  for (decltype(block) i = 0; i < block; i++) {
238  tmp = buffer1[i];
239  buffer1[i] = buffer2[block-i-1];
240  buffer2[block-i-1] = tmp;
241  }
242  track->Set((samplePtr)buffer1.get(), floatSample, first, block);
243  track->Set((samplePtr)buffer2.get(), floatSample, second, block);
244 
245  len -= 2 * block;
246  first += block;
247 
248  if( TrackProgress(count, 2 * ( first - originalStart ).as_double() /
249  originalLen.as_double() ) ) {
250  rc = false;
251  break;
252  }
253  }
254 
255  return rc;
256 }
bool TrackProgress(int whichTrack, double frac, const wxString &=wxEmptyString)
Definition: Effect.cpp:1985
size_t GetBestBlockSize(sampleCount t) const
Definition: WaveTrack.cpp:1607
size_t limitSampleBufferSize(size_t bufferSize, sampleCount limit)
Definition: Types.h:178
void Set(samplePtr buffer, sampleFormat format, sampleCount start, size_t len)
Definition: WaveTrack.cpp:2052
char * samplePtr
Definition: Types.h:203
size_t GetMaxBlockSize() const
Definition: WaveTrack.cpp:1625
bool Get(samplePtr buffer, sampleFormat format, sampleCount start, size_t len, fillFormat fill=fillZero, bool mayThrow=true, sampleCount *pNumCopied=nullptr) const
Definition: WaveTrack.cpp:1971
bool EffectReverse::ProcessOneWave ( int  count,
WaveTrack track,
sampleCount  start,
sampleCount  len 
)
private

Definition at line 106 of file Reverse.cpp.

References WaveTrack::AddClip(), WaveTrack::GetClips(), WaveClip::GetEndSample(), WaveClip::GetStartSample(), WaveTrack::LongSamplesToTime(), ProcessOneClip(), WaveTrack::RemoveAndReturnClip(), WaveTrack::SortedClipArray(), WaveTrack::SplitAt(), and WaveTrack::TimeToLongSamples().

Referenced by Process().

107 {
108  bool rValue = true; // return value
109 
110  auto end = start + len; // start, end, len refer to the selected reverse region
111 
112  // STEP 1:
113  // If a reverse selection begins and/or ends at the inside of a clip
114  // perform a split at the start and/or end of the reverse selection
115  const auto &clips = track->GetClips();
116  // Beware, the array grows as we loop over it. Use integer subscripts, not iterators.
117  for (size_t ii = 0; ii < clips.size(); ++ii) {
118  const auto &clip = clips[ii].get();
119  auto clipStart = clip->GetStartSample();
120  auto clipEnd = clip->GetEndSample();
121  if (clipStart < start && clipEnd > start && clipEnd <= end) { // the reverse selection begins at the inside of a clip
122  double splitTime = track->LongSamplesToTime(start);
123  track->SplitAt(splitTime);
124  }
125  else if (clipStart >= start && clipStart < end && clipEnd > end) { // the reverse selection ends at the inside of a clip
126  double splitTime = track->LongSamplesToTime(end);
127  track->SplitAt(splitTime);
128  }
129  else if (clipStart < start && clipEnd > end) { // the selection begins AND ends at the inside of a clip
130  double splitTime = track->LongSamplesToTime(start);
131  track->SplitAt(splitTime);
132  splitTime = track->LongSamplesToTime(end);
133  track->SplitAt(splitTime);
134  }
135  }
136 
137  //STEP 2:
138  // Individually reverse each clip inside the selected region
139  // and apply the appropriate offset after detaching them from the track
140 
141  bool checkedFirstClip = false;
142 
143  // used in calculating the offset of clips to rearrange
144  // holds the NEW end position of the current clip
145  auto currentEnd = end;
146 
147  WaveClipHolders revClips; // holds the reversed clips
148  WaveClipHolders otherClips; // holds the clips that appear after the reverse selection region
149  auto clipArray = track->SortedClipArray();
150  size_t i;
151  for (i=0; i < clipArray.size(); i++) {
152 
153  WaveClip *clip = clipArray[i];
154  auto clipStart = clip->GetStartSample();
155  auto clipEnd = clip->GetEndSample();
156 
157  if (clipStart >= start && clipEnd <= end) { // if the clip is inside the selected region
158 
159  // this is used to check if the selected region begins with a whitespace.
160  // if yes then clipStart (of the first clip) and start are not the same.
161  // adjust currentEnd accordingly and set endMerge to false
162  if(checkedFirstClip == false && clipStart > start) {
163  checkedFirstClip = true;
164  if(i > 0) {
165  if (clipArray[i-1]->GetEndSample() <= start) {
166  currentEnd -= (clipStart - start);
167  }
168  }
169  else {
170  currentEnd -= (clipStart - start);
171  }
172  }
173 
174  auto revStart = (clipStart >= start)? clipStart: start;
175  auto revEnd = (clipEnd >= end)? end: clipEnd;
176  auto revLen = revEnd - revStart;
177  if (revEnd >= revStart) {
178  if(!ProcessOneClip(count, track, revStart, revLen, start, end)) // reverse the clip
179  {
180  rValue = false;
181  break;
182  }
183 
184  auto clipOffsetStart = currentEnd - (clipEnd - clipStart); // calculate the offset required
185  double offsetStartTime = track->LongSamplesToTime(clipOffsetStart);
186  if(i+1 < clipArray.size()) // update currentEnd if there is a clip to process next
187  {
188  auto nextClipStart = clipArray[i+1]->GetStartSample();
189  currentEnd = currentEnd - (clipEnd - clipStart) - (nextClipStart - clipEnd);
190  }
191 
192  revClips.push_back(track->RemoveAndReturnClip(clip)); // detach the clip from track
193  revClips.back()->SetOffset(track->LongSamplesToTime(track->TimeToLongSamples(offsetStartTime))); // align time to a sample and set offset
194  }
195  }
196  else if (clipStart >= end) { // clip is after the selection region
197  otherClips.push_back(track->RemoveAndReturnClip(clip)); // simply remove and append to otherClips
198  }
199  }
200 
201  // STEP 3: Append the clips from
202  // revClips and otherClips back to the track
203  // the last clip of revClips is appended to the track first
204  // PRL: I don't think that matters, the sequence of storage of clips in the track
205  // is not elsewhere assumed to be by time
206  for (auto it = revClips.rbegin(), end = revClips.rend(); it != end; ++it)
207  track->AddClip(std::move(*it));
208 
209  for (auto &clip : otherClips)
210  track->AddClip(std::move(clip));
211 
212  return rValue;
213 }
void SplitAt(double t)
Definition: WaveTrack.cpp:2383
WaveClipPointers SortedClipArray()
Definition: WaveTrack.cpp:2576
std::vector< WaveClipHolder > WaveClipHolders
Definition: WaveClip.h:122
std::shared_ptr< WaveClip > RemoveAndReturnClip(WaveClip *clip)
Definition: WaveTrack.cpp:990
bool ProcessOneClip(int count, WaveTrack *track, sampleCount start, sampleCount len, sampleCount originalStart, sampleCount originalEnd)
Definition: Reverse.cpp:215
sampleCount GetEndSample() const
Definition: WaveClip.cpp:443
This allows multiple clips to be a part of one WaveTrack.
Definition: WaveClip.h:176
WaveClipHolders & GetClips()
Definition: WaveTrack.h:364
sampleCount GetStartSample() const
Definition: WaveClip.cpp:438
void AddClip(std::shared_ptr< WaveClip > &&clip)
Definition: WaveTrack.cpp:1003
sampleCount TimeToLongSamples(double t0) const
Convert correctly between an (absolute) time in seconds and a number of samples.
Definition: WaveTrack.cpp:1843
double LongSamplesToTime(sampleCount pos) const
Convert correctly between an number of samples and an (absolute) time in seconds. ...
Definition: WaveTrack.cpp:1848

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