camerauis/cameraxui/cxengine/inc/cxestatemachinebase.h
changeset 19 d9aefe59d544
child 21 fa6d9f75d6a6
equal deleted inserted replaced
3:8b2d6d0384b0 19:d9aefe59d544
       
     1 /*
       
     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * under the terms of "Eclipse Public License v1.0"
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description:
       
    15 *
       
    16 */
       
    17 #ifndef CXESTATEMACHINEBASE_H
       
    18 #define CXESTATEMACHINEBASE_H
       
    19 
       
    20 #include <QHash>
       
    21 #include <QString>
       
    22 #include "cxeerror.h"
       
    23 
       
    24 class CxeState;
       
    25 
       
    26 /**
       
    27 * CxeStateMachineBase is used as the base class for all finite state machines in the
       
    28 * engine. It's not a fully functional state machine in the sense that it does not provide any
       
    29 * mechanism for handling events that would trigged state changes. Instead,
       
    30 * it relies on the derived class to call setState() whenever the state
       
    31 * should change. The derived class should also provide a list of states
       
    32 * and allowed transitions so that CxeStateMachineBase can verify that each state
       
    33 * change is valid. A pure virtual function, handleStateChanged() should be
       
    34 * implemented by derived classes to handle notifing other interested objects about
       
    35 * the state change. This class cannot emit the signals itself, because it does not
       
    36 * derived from QObject and it handles all state IDs as plain integers instead of the
       
    37 * preferred class specific enumerations.
       
    38 *
       
    39 * CxeStateMachineBase does not derive from QObject to make easier for the engine
       
    40 * control implementation classes to derive from it. Additionally we avoid the overhead
       
    41 * brought by QObject.
       
    42 *
       
    43 * CxeStateMachineBase class is to be used for unit testing. Engine class should derive
       
    44 * from CxeStateMachine class.
       
    45 */
       
    46 
       
    47 class CxeStateMachineBase
       
    48 {
       
    49 public:
       
    50     /**
       
    51     * CxeStateMachine constructor.
       
    52     * @sa addState setInitialState
       
    53     * @param stateMachineName  Name for this state machine (used for debug prints)
       
    54     */
       
    55     CxeStateMachineBase(const char* stateMachineName);
       
    56     virtual ~CxeStateMachineBase();
       
    57 
       
    58 protected:
       
    59     /**
       
    60      * Add a new state to the machine. Takes ownership of state.
       
    61      *
       
    62      * @param state A CxeState object defining a name, ID, and allowed transitions for the
       
    63      * new state. The CxeState ID must be unique and not to contain overlapping bits with other
       
    64      * state ids, since bitwise AND operator is used for the state ids.
       
    65      * @return False if adding failed due to incorrect id.
       
    66      */
       
    67     virtual bool addState(CxeState *state);
       
    68 
       
    69     /**
       
    70      * Initiate a state transition from current state to a given state ID. In cases that
       
    71      * current state is same as the new state, method returns without doing anything. If the state
       
    72      * transition is invalid, this function return false.
       
    73      *
       
    74      * @param stateId State ID of the new state
       
    75      * @param error   Optional error code to be associated with the transition
       
    76      * @return False if state change fails. True if changing is allowed, or the current state is same
       
    77      * as the new state.
       
    78      */
       
    79     virtual bool setState(int stateId, int error = 0);
       
    80 
       
    81     /**
       
    82      * Set the initial state of the state machine. Can be called only once.
       
    83      * This method will panic, if initial state is unknown, or initial state has already
       
    84      * been set.
       
    85      *
       
    86      * @param stateId State ID for the initial state.
       
    87      * @return False if state to be set intial state is not known, or initial
       
    88      * state has already been set.
       
    89      */
       
    90     virtual bool setInitialState(int stateId);
       
    91 
       
    92     /**
       
    93      * Pure virtual function to be implemented by derived classes. Called when state changes.
       
    94      * The implementation should emit a signal informing interested parties of a state change.
       
    95      *
       
    96      * @param newStateId State ID for the new state
       
    97      * @param error      An error code associated with the state transition
       
    98      */
       
    99     virtual void handleStateChanged(int newStateId, CxeError::Id error) = 0;
       
   100 
       
   101     /**
       
   102      * Get current state ID. It is recommended for derived classes to create
       
   103      * a new method (typically called state()) which returns the current state ID
       
   104      * typecasted into a class specific enumeration.
       
   105      * @return Current state ID
       
   106      */
       
   107     int stateId() const;
       
   108 
       
   109     /**
       
   110      * Verify if a state transition is possible.
       
   111      * @param newStateId  State ID of the new state.
       
   112      * @return Whether state transition is possible.
       
   113      */
       
   114     bool verifyStateChange(int newStateId);
       
   115 
       
   116 private:
       
   117 
       
   118     //! Hash table of all states. stateId as key
       
   119     QHash<int, CxeState*> mStates;
       
   120 
       
   121     //! Current state
       
   122     int mStateId;
       
   123 
       
   124     //! Name of this state machine (for debug prints)
       
   125     QString mName;
       
   126 
       
   127 };
       
   128 
       
   129 #endif // CXESTATEMACHINEBASE_H
       
   130 
       
   131