KWWidgets
|
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