// ==================================================
// Copyright 2020 Siemens Digital Industries Software
// ==================================================
// Copyright 2013.
// Siemens Product Lifecycle Management Software Inc.
// All Rights Reserved.
// ==================================================
// Copyright 2020 Siemens Digital Industries Software
/*  */
#ifndef TEAMCENTER_PREFERENCE_SCOPE_HXX
#define TEAMCENTER_PREFERENCE_SCOPE_HXX

#include <tc/preferences.h>

#include <tc/libtc_exports.h>

/**
   @file 
   Wrapper class to conveniently set the Preferences search scope and reset it once 
   not needed any more.
*/

/**
    @deprecated #PreferenceScope deprecated in Teamcenter 10.0.
    <br/>This class has become useless since the search scope concept is removed and replaced with the dynamic concept of protection scope. 
    <br/>Any usage of this class is simply ignored (the code is a no-operation).

    @brief Conveniently sets and resets the search scope for Preferences

    The search scope for Preferences is needed to let the Preferences layer know where to start looking for a preference value.
    <br/>It is set using the PREF_set_search_scope ITK. Prior to calling the PREF_set_search_scope, the PREF_ask_search_scope also needs to be called to keep the previous value and reset to it once done.
    <br/>In a nutshell, the setting of search scope through ITK reads like this:
    @code
    TC_preference_search_scope_t old_scope;
    int ifail = PREF_ask_search_scope( &old_scope );
    if( ITK_ok == ifail )
    {
        ifail = PREF_set_search_scope( new_scope );
        if( ITK_ok == ifail )
        {
            ifail = PREF_ask_int_value( "My_Preference", 0, &int_value );
            [...]
        }
        
        ifail = PREF_set_search_scope( old_value );
        [...]
    }
    @endcode

    <br/>This approach can be tedious. Great simplification comes from using the PreferenceScope class:
    @code
    {
        PreferenceScope prefScope( new_scope );
        ifail = PREF_ask_int_value( "My_Preference", 0, &int_value );
        [...]
    } //<-- At the end of the C++ code scope, the destructor of the prefScope object is called, 
      //    effectively resetting the Preferences search scope.
    @endcode

*/

class TC_DEPRECATED_NO_REPLACEMENT( "10.0", "PreferenceScope" ) TC_API PreferenceScope
{
public:
    /** 
        Constructor
        <br/>The current Preferences search scope will be stored and the value set by 
        @p newScope will become the new search scope.
    */
    PreferenceScope( TC_preference_search_scope_t newScope );
  
    /**
       Destructor
       <br/>It will reset the Preferences search scope to its prior value.
    */
    virtual ~PreferenceScope();

private:
    /** Default constructor */
    PreferenceScope();

    /** Copy constructor */
    PreferenceScope( const PreferenceScope& );

    /** Operator = */
    PreferenceScope& operator = ( const PreferenceScope& );

    /** The existing search scope before the replacement by a new scope */
    TC_preference_search_scope_t savedScope;
};

#include <tc/libtc_undef.h>

#endif