KWWidgets
vtkKWStateMachine.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWStateMachine.h,v $
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWStateMachine - a state machine.
15 // .SECTION Description
16 // This class is the basis for a state machine framework.
17 // A state machine is defined by a set of states, a set of inputs and a
18 // transition matrix that defines for each pair of (state,input) what is
19 // the next state to assume.
20 // .SECTION Thanks
21 // This work is part of the National Alliance for Medical Image
22 // Computing (NAMIC), funded by the National Institutes of Health
23 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
24 // Information on the National Centers for Biomedical Computing
25 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
26 // .SECTION See Also
27 // vtkKWStateMachineInput vtkKWStateMachineState vtkKWStateMachineTransition
28 
29 #ifndef __vtkKWStateMachine_h
30 #define __vtkKWStateMachine_h
31 
32 #include "vtkKWObject.h"
33 
37 class vtkKWStateMachineInternals;
39 
41 {
42 public:
43  static vtkKWStateMachine* New();
44  vtkTypeRevisionMacro(vtkKWStateMachine, vtkKWObject);
45  void PrintSelf(ostream& os, vtkIndent indent);
46 
47  // Description:
48  // Add a state.
49  // Return 1 on success, 0 otherwise.
50  virtual int AddState(vtkKWStateMachineState *state);
51  virtual int HasState(vtkKWStateMachineState *state);
52  virtual int GetNumberOfStates();
53  virtual vtkKWStateMachineState* GetNthState(int rank);
54 
55  // Description:
56  // Add an input.
57  // Return 1 on success, 0 otherwise.
58  virtual int AddInput(vtkKWStateMachineInput *input);
59  virtual int HasInput(vtkKWStateMachineInput *input);
60  virtual int GetNumberOfInputs();
61  virtual vtkKWStateMachineInput* GetNthInput(int rank);
62 
63  // Description:
64  // Add a transition. The transition must be complete, i.e. its originating
65  // and destination states must be set, as well as its input. Furthermore,
66  // said parameters must be known to the state machine, i.e. one should
67  // make sure the states and input have been added to the state machine first.
68  // Return 1 on success, 0 otherwise.
69  virtual int AddTransition(vtkKWStateMachineTransition *transition);
70  virtual int HasTransition(vtkKWStateMachineTransition *transition);
71  virtual int GetNumberOfTransitions();
72  virtual vtkKWStateMachineTransition* GetNthTransition(int rank);
73 
74  // Description:
75  // Create and add a new transition. If a transition object has already
76  // been added with the same parameters, it will be used instead.
77  // Return transition on success, NULL otherwise.
78  virtual vtkKWStateMachineTransition* CreateTransition(
79  vtkKWStateMachineState *origin,
81  vtkKWStateMachineState *destination);
82 
83  // Description:
84  // Find a transition.
85  // Return transition on success, NULL otherwise.
86  virtual vtkKWStateMachineTransition* FindTransition(
87  vtkKWStateMachineState *origin,
88  vtkKWStateMachineInput *input);
89  virtual vtkKWStateMachineTransition* FindTransition(
90  vtkKWStateMachineState *origin,
92  vtkKWStateMachineState *destination);
93 
94  // Description:
95  // Set/Get the initial state.
96  // IMPORTANT: This call bootstraps/starts the state machine, it should
97  // therefore be the *last* method you call after setting up the whole state
98  // machine. No input, state or transition can be added afterwards.
99  // Note that the initial state can not be reset.
100  // Note that setting the initial state is actually the same as entering
101  // it (i.e. the state's Enter() method will be called).
102  // Return 1 on success, 0 otherwise.
103  vtkGetObjectMacro(InitialState, vtkKWStateMachineState);
104  virtual int SetInitialState(vtkKWStateMachineState*);
105 
106  // Description:
107  // Get if the state machine is actually running.
108  // At the moment, this is done by checking if InitialState has been set.
109  virtual int IsRunning();
110 
111  // Description:
112  // Get the current and previous state.
113  vtkGetObjectMacro(CurrentState, vtkKWStateMachineState);
114  vtkKWStateMachineState* GetPreviousState();
115 
116  // Description:
117  // Push a new input in the queue of inputs to be processed.
118  virtual void PushInput(vtkKWStateMachineInput *input);
119 
120  // Description:
121  // Perform the state transition and invoke the corresponding action for
122  // every pending input stored in the input queue.
123  // For each input in the queue:
124  // - a transition T is searched accepting the current state C and the input,
125  // - if found:
126  // - T's Start() method is triggered,
127  // - C's Leave() method is triggered,
128  // - T is pushed to the history (see GetNthTransitionInHistory),
129  // - C becomes T's DestinationState (i.e. current state = new state),
130  // - CurrentStateChangedCommand and CurrentStateChangedEvent are invoked,
131  // - C (i.e. T's DestinationState)'s Enter() method is triggered,
132  // - T's End() method is triggered.
133  virtual void ProcessInputs();
134 
135  // Description:
136  // The state machine keeps an history of all the transitions that were
137  // applied so far.
138  virtual int GetNumberOfTransitionsInHistory();
139  virtual vtkKWStateMachineTransition* GetNthTransitionInHistory(int rank);
140 
141  // Description:
142  // Add a cluster. Clusters are not used by the state machine per se, they
143  // are just a convenient way to group states logically together, and can
144  // be used by state machine writers (see vtkKWStateMachineDOTWriter)
145  // to display clusters as groups.
146  // Return 1 on success, 0 otherwise.
147  virtual int AddCluster(vtkKWStateMachineCluster *cluster);
148  virtual int HasCluster(vtkKWStateMachineCluster *cluster);
149  virtual int GetNumberOfClusters();
150  virtual vtkKWStateMachineCluster* GetNthCluster(int rank);
151 
152  // Description:
153  // Specifies a command to associate with this state machine. This command is
154  // invoked when the state machine current state has changed.
155  // The 'object' argument is the object that will have the method called on
156  // it. The 'method' argument is the name of the method to be called and any
157  // arguments in string form. If the object is NULL, the method is still
158  // evaluated as a simple command.
159  virtual void SetCurrentStateChangedCommand(
160  vtkObject *object, const char *method);
161  virtual void InvokeCurrentStateChangedCommand();
162  virtual int HasCurrentStateChangedCommand();
163 
164  // Description:
165  // Events. The CurrentStateChangedCommand is invoked when the state machine
166  // current state has changed.
167  //BTX
168  enum
169  {
170  CurrentStateChangedEvent = 10000
171  };
172  //ETX
173 
174 protected:
177 
178  vtkKWStateMachineState *InitialState;
179  vtkKWStateMachineState *CurrentState;
180 
181  // Description:
182  // Remove state(s).
183  virtual void RemoveState(vtkKWStateMachineState *state);
184  virtual void RemoveAllStates();
185 
186  // Description:
187  // Remove input(s).
188  virtual void RemoveInput(vtkKWStateMachineInput *input);
189  virtual void RemoveAllInputs();
190 
191  // Description:
192  // Remove transition(s).
193  virtual void RemoveTransition(vtkKWStateMachineTransition *transition);
194  virtual void RemoveAllTransitions();
195 
196  // Description:
197  // Remove cluster(s).
198  virtual void RemoveCluster(vtkKWStateMachineCluster *cluster);
199  virtual void RemoveAllClusters();
200 
201  // PIMPL Encapsulation for STL containers
202  //BTX
203  vtkKWStateMachineInternals *Internals;
204  //ETX
205 
206  // Description:
207  // Process one input.
208  virtual void ProcessInput(vtkKWStateMachineInput *input);
209 
210  char *CurrentStateChangedCommand;
211 
212  // Description:
213  // Push transition to the history.
214  virtual void PushTransitionToHistory(vtkKWStateMachineTransition*);
215 
216 private:
217 
218  vtkKWStateMachine(const vtkKWStateMachine&); // Not implemented
219  void operator=(const vtkKWStateMachine&); // Not implemented
220 };
221 
222 #endif