• Main Page
  • Classes
  • Files
  • Directories
  • File List
  • File Members

vtkKWStateMachine.h

Go to the documentation of this file.
00001 /*=========================================================================
00002 
00003   Module:    $RCSfile: vtkKWStateMachine.h,v $
00004 
00005   Copyright (c) Kitware, Inc.
00006   All rights reserved.
00007   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
00008 
00009      This software is distributed WITHOUT ANY WARRANTY; without even
00010      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
00011      PURPOSE.  See the above copyright notice for more information.
00012 
00013 =========================================================================*/
00014 // .NAME vtkKWStateMachine - a state machine.
00015 // .SECTION Description
00016 // This class is the basis for a state machine framework. 
00017 // A state machine is defined by a set of states, a set of inputs and a
00018 // transition matrix that defines for each pair of (state,input) what is
00019 // the next state to assume.
00020 // .SECTION Thanks
00021 // This work is part of the National Alliance for Medical Image
00022 // Computing (NAMIC), funded by the National Institutes of Health
00023 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
00024 // Information on the National Centers for Biomedical Computing
00025 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
00026 // .SECTION See Also
00027 // vtkKWStateMachineInput vtkKWStateMachineState vtkKWStateMachineTransition
00028 
00029 #ifndef __vtkKWStateMachine_h
00030 #define __vtkKWStateMachine_h
00031 
00032 #include "vtkKWObject.h"
00033 
00034 class vtkKWStateMachineState;
00035 class vtkKWStateMachineTransition;
00036 class vtkKWStateMachineInput;
00037 class vtkKWStateMachineInternals;
00038 class vtkKWStateMachineCluster;
00039 
00040 class KWWidgets_EXPORT vtkKWStateMachine : public vtkKWObject
00041 {
00042 public:
00043   static vtkKWStateMachine* New();
00044   vtkTypeRevisionMacro(vtkKWStateMachine, vtkKWObject);
00045   void PrintSelf(ostream& os, vtkIndent indent);
00046 
00047   // Description:
00048   // Add a state.
00049   // Return 1 on success, 0 otherwise.
00050   virtual int AddState(vtkKWStateMachineState *state);
00051   virtual int HasState(vtkKWStateMachineState *state);
00052   virtual int GetNumberOfStates();
00053   virtual vtkKWStateMachineState* GetNthState(int rank);
00054 
00055   // Description:
00056   // Add an input.
00057   // Return 1 on success, 0 otherwise.
00058   virtual int AddInput(vtkKWStateMachineInput *input);
00059   virtual int HasInput(vtkKWStateMachineInput *input);
00060   virtual int GetNumberOfInputs();
00061   virtual vtkKWStateMachineInput* GetNthInput(int rank);
00062 
00063   // Description:
00064   // Add a transition. The transition must be complete, i.e. its originating
00065   // and destination states must be set, as well as its input. Furthermore,
00066   // said parameters must be known to the state machine, i.e. one should
00067   // make sure the states and input have been added to the state machine first.
00068   // Return 1 on success, 0 otherwise.
00069   virtual int AddTransition(vtkKWStateMachineTransition *transition);
00070   virtual int HasTransition(vtkKWStateMachineTransition *transition);
00071   virtual int GetNumberOfTransitions();
00072   virtual vtkKWStateMachineTransition* GetNthTransition(int rank);
00073 
00074   // Description:
00075   // Create and add a new transition. If a transition object has already
00076   // been added with the same parameters, it will be used instead.
00077   // Return transition on success, NULL otherwise.
00078   virtual vtkKWStateMachineTransition* CreateTransition(
00079     vtkKWStateMachineState *origin,
00080     vtkKWStateMachineInput *input,
00081     vtkKWStateMachineState *destination);
00082 
00083   // Description:
00084   // Find a transition.
00085   // Return transition on success, NULL otherwise.
00086   virtual vtkKWStateMachineTransition* FindTransition(
00087     vtkKWStateMachineState *origin,
00088     vtkKWStateMachineInput *input);
00089   virtual vtkKWStateMachineTransition* FindTransition(
00090     vtkKWStateMachineState *origin,
00091     vtkKWStateMachineInput *input,
00092     vtkKWStateMachineState *destination);
00093   
00094   // Description:
00095   // Set/Get the initial state.
00096   // IMPORTANT: This call bootstraps/starts the state machine, it should
00097   // therefore be the *last* method you call after setting up the whole state
00098   // machine. No input, state or transition can be added afterwards.
00099   // Note that the initial state can not be reset.
00100   // Note that setting the initial state is actually the same as entering
00101   // it (i.e. the state's Enter() method will be called).
00102   // Return 1 on success, 0 otherwise.
00103   vtkGetObjectMacro(InitialState, vtkKWStateMachineState);
00104   virtual int SetInitialState(vtkKWStateMachineState*);
00105 
00106   // Description:
00107   // Get if the state machine is actually running.
00108   // At the moment, this is done by checking if InitialState has been set.
00109   virtual int IsRunning();
00110 
00111   // Description:
00112   // Get the current and previous state.
00113   vtkGetObjectMacro(CurrentState, vtkKWStateMachineState);
00114   vtkKWStateMachineState* GetPreviousState();
00115 
00116   // Description:
00117   // Push a new input in the queue of inputs to be processed. 
00118   virtual void PushInput(vtkKWStateMachineInput *input);
00119 
00120   // Description:
00121   // Perform the state transition and invoke the corresponding action for
00122   // every pending input stored in the input queue.
00123   // For each input in the queue:
00124   // - a transition T is searched accepting the current state C and the input,
00125   // - if found:
00126   //    - T's Start() method is triggered,
00127   //    - C's Leave() method is triggered,
00128   //    - T is pushed to the history (see GetNthTransitionInHistory),
00129   //    - C becomes T's DestinationState (i.e. current state = new state),
00130   //    - CurrentStateChangedCommand and CurrentStateChangedEvent are invoked,
00131   //    - C (i.e. T's DestinationState)'s Enter() method is triggered,
00132   //    - T's End() method is triggered.
00133   virtual void ProcessInputs();
00134 
00135   // Description:
00136   // The state machine keeps an history of all the transitions that were 
00137   // applied so far.
00138   virtual int GetNumberOfTransitionsInHistory();
00139   virtual vtkKWStateMachineTransition* GetNthTransitionInHistory(int rank);
00140 
00141   // Description:
00142   // Add a cluster. Clusters are not used by the state machine per se, they
00143   // are just a convenient way to group states logically together, and can
00144   // be used by state machine writers (see vtkKWStateMachineDOTWriter)
00145   // to display clusters as groups.
00146   // Return 1 on success, 0 otherwise.
00147   virtual int AddCluster(vtkKWStateMachineCluster *cluster);
00148   virtual int HasCluster(vtkKWStateMachineCluster *cluster);
00149   virtual int GetNumberOfClusters();
00150   virtual vtkKWStateMachineCluster* GetNthCluster(int rank);
00151 
00152   // Description:
00153   // Specifies a command to associate with this state machine. This command is 
00154   // invoked when the state machine current state has changed.
00155   // The 'object' argument is the object that will have the method called on
00156   // it. The 'method' argument is the name of the method to be called and any
00157   // arguments in string form. If the object is NULL, the method is still
00158   // evaluated as a simple command. 
00159   virtual void SetCurrentStateChangedCommand(
00160     vtkObject *object, const char *method);
00161   virtual void InvokeCurrentStateChangedCommand();
00162   virtual int HasCurrentStateChangedCommand();
00163 
00164   // Description:
00165   // Events. The CurrentStateChangedCommand is invoked when the state machine 
00166   // current state has changed.
00167   //BTX
00168   enum
00169   {
00170     CurrentStateChangedEvent = 10000
00171   };
00172   //ETX
00173 
00174 protected:
00175   vtkKWStateMachine();
00176   ~vtkKWStateMachine();
00177 
00178   vtkKWStateMachineState *InitialState;
00179   vtkKWStateMachineState *CurrentState;
00180 
00181   // Description:
00182   // Remove state(s).
00183   virtual void RemoveState(vtkKWStateMachineState *state);
00184   virtual void RemoveAllStates();
00185 
00186   // Description:
00187   // Remove input(s).
00188   virtual void RemoveInput(vtkKWStateMachineInput *input);
00189   virtual void RemoveAllInputs();
00190 
00191   // Description:
00192   // Remove transition(s).
00193   virtual void RemoveTransition(vtkKWStateMachineTransition *transition);
00194   virtual void RemoveAllTransitions();
00195 
00196   // Description:
00197   // Remove cluster(s).
00198   virtual void RemoveCluster(vtkKWStateMachineCluster *cluster);
00199   virtual void RemoveAllClusters();
00200 
00201   // PIMPL Encapsulation for STL containers
00202   //BTX
00203   vtkKWStateMachineInternals *Internals;
00204   //ETX
00205 
00206   // Description:
00207   // Process one input.
00208   virtual void ProcessInput(vtkKWStateMachineInput *input);
00209 
00210   char *CurrentStateChangedCommand;
00211 
00212   // Description:
00213   // Push transition to the history.
00214   virtual void PushTransitionToHistory(vtkKWStateMachineTransition*);
00215 
00216 private:
00217 
00218   vtkKWStateMachine(const vtkKWStateMachine&); // Not implemented
00219   void operator=(const vtkKWStateMachine&); // Not implemented
00220 };
00221 
00222 #endif

Generated on Mon Aug 16 2010 18:58:47 for KWWidgets by  doxygen 1.7.1