camerauis/cameraxui/cxengine/inc/cxestatemachine.h
branchRCL_3
changeset 24 bac7acad7cb3
parent 23 61bc0f252b2b
child 25 2c87b2808fd7
equal deleted inserted replaced
23:61bc0f252b2b 24:bac7acad7cb3
     1 /*
       
     2 * Copyright (c) 2009-2010 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 
       
    18 #ifndef CXESTATEMACHINE_H
       
    19 #define CXESTATEMACHINE_H
       
    20 
       
    21 #include "cxestatemachinebase.h"
       
    22 
       
    23 class CxeState;
       
    24 
       
    25 /**
       
    26  * CxeStateMachine extends CxeStateMachineBase functionality. All methods call base class
       
    27  * implementation, and will panic if the base class return value indicates failure.
       
    28  *
       
    29  * Engine classes should derive from CxeStateMachine. CxeStateMachineBase is for situations where
       
    30  * asserts can't be used, like unit testing.
       
    31  *
       
    32  * CxeStateMachine is internal to the engine and is not visible in the engine API.
       
    33 */
       
    34 class CxeStateMachine : public CxeStateMachineBase
       
    35 {
       
    36 public:
       
    37     /**
       
    38     * CxeStateMachine constructor. After construction, the derived class should
       
    39     * add all the defined states and call setInitialState().
       
    40     *
       
    41     * @sa addState setInitialState
       
    42     * @param stateMachineName  Name for this state machine (used for debug prints)
       
    43     */
       
    44     CxeStateMachine(const char *stateMachineName);
       
    45     virtual ~CxeStateMachine();
       
    46 
       
    47 protected:
       
    48     /**
       
    49      * Add a new state to the machine. Takes ownership of state. This function will
       
    50      * panic, if new state id is incorrect.
       
    51      *
       
    52      * @param state A CxeState object defining a name, ID, and allowed transitions for
       
    53      * the new state. The CxeState ID must be unique and not to contain overlapping bits
       
    54      * with other state ids, since bitwise AND operator is used for the state ids.
       
    55      * @return True if adding was successful, false if adding failed
       
    56      */
       
    57     bool addState(CxeState *state);
       
    58 
       
    59     /**
       
    60      * Initiate a state transition from current state to a given state ID. If the state
       
    61      * transition is invalid, this function will panic.
       
    62      *
       
    63      * @param stateId State ID of the new state
       
    64      * @param error   Optional error code to be associated with the transition
       
    65      */
       
    66     bool setState(int stateId, CxeError::Id error = CxeError::None);
       
    67 
       
    68     /**
       
    69      * Set the initial state of the state machine. Can be called only once.
       
    70      * This method will panic, if initial state to be set is unknown, or initial
       
    71      * state has already been set.
       
    72      *
       
    73      * @param stateId State ID for the initial state.
       
    74      */
       
    75     bool setInitialState(int stateId);
       
    76 
       
    77     /**
       
    78      * Pure virtual function to be implemented by derived classes. Called when state changes.
       
    79      * The implementation should emit a signal informing interested parties of a state change.
       
    80      *
       
    81      * @param newStateId State ID for the new state
       
    82      * @param error      An error code associated with the state transition
       
    83      */
       
    84     virtual void handleStateChanged(int newStateId, CxeError::Id error) = 0;
       
    85 
       
    86 private:
       
    87 
       
    88 };
       
    89 
       
    90 #endif // CXESTATEMACHINE_H