#ifndef PROJECT_H_
#define PROJECT_H_
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2014 KiCad Developers, see CHANGELOG.TXT for contributors.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, you may find one here:
* http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
* or you may search the http://www.gnu.org website for the version 2 license,
* or you may write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
*/
#include <vector>
#include <wx/string.h>
#include <wx/filename.h>
#include <search_stack.h>
/// A variable name whose value holds the current project directory.
/// Currently an environment variable, eventually a project variable.
#define PROJECT_VAR_NAME wxT( "KIPRJMOD" )
class wxConfigBase;
class PARAM_CFG_ARRAY;
class FP_LIB_TABLE;
#define VTBL_ENTRY virtual
/**
* Class PROJECT
* holds project specific data. Because it is in the neutral program top, which
* is not linked to by subsidiarly DSOs, any functions in this interface must
* be VTBL_ENTRYs.
*/
class PROJECT
{
public:
/// A PROJECT can hold stuff it knows nothing about, in the form of
/// _ELEM derivatives. Derive PROJECT elements from this, it has a virtual
/// destructor, and Elem*() functions can work with it. Implementation is
/// opaque in class PROJECT. If find you have to include derived class headers
/// in this file, you are doing incompatible with the goal of this class.
/// Keep knowledge of derived classes opaque to class PROJECT please.
class _ELEM
{
public:
virtual ~_ELEM() {}
};
PROJECT();
~PROJECT();
//-----<Cross Module API>----------------------------------------------------
// VTBL_ENTRY bool MaybeLoadProjectSettings( const std::vector<wxString>& aFileSet );
/**
* Function SetProjectFullName
* sets the:
* 1) full directory, 2) basename, and 3) extension of the project. This is
* the name of the *.pro file with full absolute path and it also defines
* the name of the project. The project name and the *.pro file names are
* exactly the same, providing the *.pro filename is absolute.
*/
VTBL_ENTRY void SetProjectFullName( const wxString& aFullPathAndName );
/**
* Function GetProjectFullName
* returns the full path and name of the project. This is the same as the
* name of the *.pro file and will always be an absolute path.
*/
VTBL_ENTRY const wxString GetProjectFullName() const;
/**
* Function FootprintLibTblName
* returns the path and filename of this project's fp-lib-table,
* i.e. the project specific one, not the global one.
*/
VTBL_ENTRY const wxString FootprintLibTblName() const;
/**
* Function ConfigSave
* saves the current "project" parameters into the wxConfigBase* derivative.
* Then the wxConfigBase derivative is written to the *.pro file for the project.
*
* @param aSearchS a SEARCH_STACK
* @param aFileName is where to save the *.pro file.
* @param aGroupName
* @param aParams is a ptr vector of PARAM_CFG_BASE derivatives.
* Saved parameters are the subset in this array having the .m_Setup member
* set to false.
*/
VTBL_ENTRY void ConfigSave( const SEARCH_STACK& aSearchS, const wxString& aFileName,
const wxString& aGroupName, const PARAM_CFG_ARRAY& aParams );
/**
* Function ConfigLoad
* reads a subset of parameters from the "project" file. Parameters are the
* subset of variables given in @a aParams array which have the .m_Setup member
* set to false. The file which is read in and then extracted from is the
* '*.pro' file for the project.
* <p>
* set:
* m_pro_date_and_time
* m_pro_name
*
* @param aSearchS a SEARCH_STACK where a kicad.pro template file may be found.
* @param aLocalConfigFileName
* @param aGroupName
* @param aParams is ptr vector of PARAM_CFG_BASE derivatives.
* @param doLoadOnlyIfNew if true, then this file is read only if it differs from
* the current config on date (different dates), else the *.pro file is read and
* extracted from unconditionally.
*
* @return bool - true if loaded OK.
*/
VTBL_ENTRY bool ConfigLoad( const SEARCH_STACK& aSearchS, const wxString& aLocalConfigFileName,
const wxString& aGroupName, const PARAM_CFG_ARRAY& aParams, bool doLoadOnlyIfNew );
/// Accessor for Eeschema search stack.
VTBL_ENTRY SEARCH_STACK& SchSearchS() { return m_sch_search; }
/// Retain a number of project specific wxStrings, enumerated here:
enum RSTRING_T
{
DOC_PATH,
SCH_LIB_PATH,
PCB_LIB_NICKNAME,
VIEWER_3D_PATH,
PCB_FOOTPRINT,
PCB_FOOTPRINT_VIEWER_FPNAME,
PCB_FOOTPRINT_VIEWER_NICKNAME,
RSTRING_COUNT
};
/**
* Function GetRString
* returns a "retained string", which is any session and project specific string
* identified in enum RSTRING_T. Retained strings are not written to disk, and
* are therefore good only for the current session.
*/
VTBL_ENTRY const wxString& GetRString( RSTRING_T aStringId );
/**
* Function SetRString
* stores a "retained string", which is any session and project specific string
* identified in enum RSTRING_T. Retained strings are not written to disk, and
* are therefore good only for the current session.
*/
VTBL_ENTRY void SetRString( RSTRING_T aStringId, const wxString& aString );
/**
* Enum ELEM_T
* is the set of _ELEMs that a PROJECT can hold.
*/
enum ELEM_T
{
ELEM_FPTBL,
ELEM_COUNT
};
/**
* Typically wrapped somewhere else in a more meaningful function wrapper.
* This is a cross module API, therefore the _ELEM destructor is virtual and
* can point to a destructor function in another link image. Be careful that
* that program module is resident at time of destruction.
* <p>
* Summary: 1) cross module API, 2) PROJECT knows nothing about _ELEM objects,
* except how to delete them and set and get pointers to them.
*/
VTBL_ENTRY _ELEM* GetElem( ELEM_T aIndex );
VTBL_ENTRY void SetElem( ELEM_T aIndex, _ELEM* aElem );
/// Inline, clear the _ELEM at position aIndex
void ElemClear( ELEM_T aIndex )
{
_ELEM* existing = GetElem( aIndex );
delete existing; // virtual
SetElem( aIndex, NULL );
}
/**
* Function ElemsClear
* deletes all the _ELEMs and set their pointers to NULL.
*/
VTBL_ENTRY void ElemsClear();
//-----</Cross Module API>---------------------------------------------------
//-----<KIFACE Specific APIs>------------------------------------------------
// These are the non-virtual DATA LOAD ON DEMAND members. They load project related
// data on demand, and do so typicallly into m_elems[] at a particular index using
// SetElem() & GetElem(). That is, they wrap SetElem() and GetElem().
// To get the data to reload on demand, first SetProjectFullName(),
// then call ElemClear() from client code.
// non-virtuals resident in PCBNEW link image(s). By being non-virtual, these
// functions can get linked into the KIFACE that needs them, and only there.
// In fact, the other KIFACEs don't even know they exist.
#if defined(PCBNEW) || defined(CVPCB)
// These are all prefaced with "Pcb"
FP_LIB_TABLE* PcbFootprintLibs();
#endif
#if defined(EESCHEMA)
// These are all prefaced with "Sch"
#endif
//-----</KIFACE Specific APIs>-----------------------------------------------
private:
/**
* Function configCreate
* creates or recreates the KiCad project file and wxConfigBase:
*
* <project_name>.pro
*
* @param aFilename is a local configuration file path and basename.
*
* Initializes ?
* G_Prj_Config
* G_Prj_Config_LocalFilename
* G_Prj_Default_Config_FullFilename
* :
*/
wxConfigBase* configCreate( const SEARCH_STACK& aSearchS,
const wxString& aFilename, const wxString& aGroupName,
bool aForceUseLocalConfig );
SEARCH_STACK m_sch_search; ///< Eeschema's search paths
SEARCH_STACK m_pcb_search; ///< Pcbnew's obsolete footprint search paths, see comment above.
wxFileName m_project_name; ///< <fullpath>/<basename>.pro
wxString m_pro_date_and_time;
/// @see this::SetRString(), GetRString(), and enum RSTRING_T.
wxString m_rstrings[RSTRING_COUNT];
/// @see this::Elem() and enum ELEM_T.
_ELEM* m_elems[ELEM_COUNT];
};
//-----<possible futures>---------------------------------------------------------
#if 0
/**
* Function Value
* fetches a project variable @a aVariable and returns true if that variable was
* found, else false. If not found, aFetchedValue is not touched. Any environment
* variable is also a project variable.
*
* @param aVariable is the property or option to look for.
* @param aFetchedValue is where to put the value of the property if it exists
* and aFetchedValue is not NULL.
* @return bool - true if variable was found, else false.
*/
VTBL_ENTRY bool Value( const wxString& aVariable, wxString* aFetchedValue = NULL );
/**
* Function Substitute
* replaces any project variable references found within @a aString with their
* values. Any referenced variable is first sought in the PROJECT space, and if
* not found, then sought in the environment.
*/
VTBL_ENTRY const wxString Substitute( const wxString& aString );
/**
* Function SubstituteAndEvaluate
* replaces any project variable references found within @a aString with their
* values, and evaluates aString as an expression.
* Any referenced variable is first sought in the PROJECT space, and if
* not found, then sought in the environment.
*/
VTBL_ENTRY const wxString SubstituteAndEvaluate( const wxString& aString );
#endif
#endif // PROJECT_H_