kicad/include/fpid.h

199 lines
6.8 KiB
C
Raw Normal View History

2013-02-16 01:09:53 +00:00
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2012 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 2010 KiCad Developers, see change_log.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
*/
#ifndef _FPID_H_
#define _FPID_H_
#include <richio.h>
2014-01-02 02:17:07 +00:00
#include <utf8.h>
2013-02-16 01:09:53 +00:00
/**
* Class FPID
* is a Logical Footprint ID and consists of various portions much like a URI.
* It is a container for the separated portions of a logical footprint id so they
* can be accessed individually. The various portions of an FPID are:
* logicalLibraryName (nick name), footprint name, and revision. The logical library
* name and the footprint name are mandatory. The revision is optional and currently is
* not used.
*
* Example FPID string:
* "smt:R_0805/rev0".
*
* <p>
* <ul>
* <li> "smt" is the logical library name used to look up library information saved in the
* #FP_LIB_TABLE.
* <li> "R" is the name of the footprint within the library.
* <li> "rev0" is the revision, which is optional. If missing then its
* / delimiter should also not be present. A revision must begin with
* "rev" and be followed by at least one or more decimal digits.
* </ul>
*
* @author Dick Hollenbeck
*/
2014-01-02 02:17:07 +00:00
class FPID
2013-02-16 01:09:53 +00:00
{
public:
FPID() {}
/**
* Constructor FPID
* takes \a aId string and parses it. A typical FPID string consists of a
* library nickname followed by a footprint name.
* e.g.: "smt:R_0805", or
* e.g.: "mylib:R_0805"
*
* @param aId is a string to be parsed into the FPID object.
*/
FPID( const std::string& aId ) throw( PARSE_ERROR );
2013-02-16 01:09:53 +00:00
FPID( const wxString& aId ) throw( PARSE_ERROR );
2013-02-16 01:09:53 +00:00
/**
* Function Parse
* [re-]stuffs this FPID with the information from @a aId.
*
* @param aId is the string to populate the #FPID object.
* @return int - minus 1 (i.e. -1) means success, >= 0 indicates the character offset into
* aId at which an error was detected.
*/
Modular-Kicad milestone B), major portions: *) Rework the set language support, simplify it by using KIWAY. Now any major frame with a "change language" menu can change the language for all KIWAY_PLAYERs in the whole KIWAY. Multiple KIWAYs are not supported yet. *) Simplify "modal wxFrame" support, and add that support exclusively to KIWAY_PLAYER where it is inherited by all derivatives. The function KIWAY_PLAYER::ShowModal() is in the vtable and so is cross module capable. *) Remove the requirements and assumptions that the wxFrame hierarchy always had PCB_EDIT_FRAME and SCH_EDIT_FRAME as immediate parents of their viewers and editors. This is no longer the case, nor required. *) Use KIWAY::Player() everywhere to make KIWAY_PLAYERs, this registers the KIWAY_PLAYER within the KIWAY and makes it very easy to find an open frame quickly. It also gives control to the KIWAY as to frame hierarchical relationships. *) Change single_top to use the KIWAY for loading a KIFACE and instantiating the single KIWAY_PLAYER, see bullet immediately above. *) Add KIWAY::OnKiwayEnd() and call it from PGM_BASE at program termination, this gives the KIFACEs a chance to save their final configuration dope to disk. *) Add dedicated FRAME_T's for the modal frames, so m_Ident can be tested and these modal frames are distinctly different than their non-modal equivalents. KIWAY_PLAYER::IsModal() is !not! a valid test during the wxFrame's constructor, so this is another important reason for having a dedicated FRAME_T for each modal wxFrame. On balance, more lines were deleted than were added to achieve all this.
2014-05-03 17:40:19 +00:00
int Parse( const UTF8& aId );
2013-02-16 01:09:53 +00:00
/**
* Function GetLibNickname
* returns the logical library name portion of a FPID.
*/
2014-01-02 02:17:07 +00:00
const UTF8& GetLibNickname() const
2013-02-16 01:09:53 +00:00
{
return nickname;
2013-02-16 01:09:53 +00:00
}
/**
* Function SetLibNickname
* overrides the logical footprint library name portion of the FPID to @a aNickname.
* @return int - minus 1 (i.e. -1) means success, >= 0 indicates the character offset
* into the parameter at which an error was detected, usually because it
* contained '/' or ':'.
*/
Modular-Kicad milestone B), major portions: *) Rework the set language support, simplify it by using KIWAY. Now any major frame with a "change language" menu can change the language for all KIWAY_PLAYERs in the whole KIWAY. Multiple KIWAYs are not supported yet. *) Simplify "modal wxFrame" support, and add that support exclusively to KIWAY_PLAYER where it is inherited by all derivatives. The function KIWAY_PLAYER::ShowModal() is in the vtable and so is cross module capable. *) Remove the requirements and assumptions that the wxFrame hierarchy always had PCB_EDIT_FRAME and SCH_EDIT_FRAME as immediate parents of their viewers and editors. This is no longer the case, nor required. *) Use KIWAY::Player() everywhere to make KIWAY_PLAYERs, this registers the KIWAY_PLAYER within the KIWAY and makes it very easy to find an open frame quickly. It also gives control to the KIWAY as to frame hierarchical relationships. *) Change single_top to use the KIWAY for loading a KIFACE and instantiating the single KIWAY_PLAYER, see bullet immediately above. *) Add KIWAY::OnKiwayEnd() and call it from PGM_BASE at program termination, this gives the KIFACEs a chance to save their final configuration dope to disk. *) Add dedicated FRAME_T's for the modal frames, so m_Ident can be tested and these modal frames are distinctly different than their non-modal equivalents. KIWAY_PLAYER::IsModal() is !not! a valid test during the wxFrame's constructor, so this is another important reason for having a dedicated FRAME_T for each modal wxFrame. On balance, more lines were deleted than were added to achieve all this.
2014-05-03 17:40:19 +00:00
int SetLibNickname( const UTF8& aNickname );
2013-02-16 01:09:53 +00:00
/**
* Function GetFootprintName
* returns the footprint name, i.e. footprintName.
*/
2014-01-02 02:17:07 +00:00
const UTF8& GetFootprintName() const { return footprint; }
2013-02-16 01:09:53 +00:00
/**
* Function SetFootprintName
* overrides the footprint name portion of the FPID to @a aFootprintName
* @return int - minus 1 (i.e. -1) means success, >= 0 indicates the character offset
* into the parameter at which an error was detected, usually because it
* contained '/'.
2013-02-16 01:09:53 +00:00
*/
Modular-Kicad milestone B), major portions: *) Rework the set language support, simplify it by using KIWAY. Now any major frame with a "change language" menu can change the language for all KIWAY_PLAYERs in the whole KIWAY. Multiple KIWAYs are not supported yet. *) Simplify "modal wxFrame" support, and add that support exclusively to KIWAY_PLAYER where it is inherited by all derivatives. The function KIWAY_PLAYER::ShowModal() is in the vtable and so is cross module capable. *) Remove the requirements and assumptions that the wxFrame hierarchy always had PCB_EDIT_FRAME and SCH_EDIT_FRAME as immediate parents of their viewers and editors. This is no longer the case, nor required. *) Use KIWAY::Player() everywhere to make KIWAY_PLAYERs, this registers the KIWAY_PLAYER within the KIWAY and makes it very easy to find an open frame quickly. It also gives control to the KIWAY as to frame hierarchical relationships. *) Change single_top to use the KIWAY for loading a KIFACE and instantiating the single KIWAY_PLAYER, see bullet immediately above. *) Add KIWAY::OnKiwayEnd() and call it from PGM_BASE at program termination, this gives the KIFACEs a chance to save their final configuration dope to disk. *) Add dedicated FRAME_T's for the modal frames, so m_Ident can be tested and these modal frames are distinctly different than their non-modal equivalents. KIWAY_PLAYER::IsModal() is !not! a valid test during the wxFrame's constructor, so this is another important reason for having a dedicated FRAME_T for each modal wxFrame. On balance, more lines were deleted than were added to achieve all this.
2014-05-03 17:40:19 +00:00
int SetFootprintName( const UTF8& aFootprintName );
Modular-Kicad milestone B), major portions: *) Rework the set language support, simplify it by using KIWAY. Now any major frame with a "change language" menu can change the language for all KIWAY_PLAYERs in the whole KIWAY. Multiple KIWAYs are not supported yet. *) Simplify "modal wxFrame" support, and add that support exclusively to KIWAY_PLAYER where it is inherited by all derivatives. The function KIWAY_PLAYER::ShowModal() is in the vtable and so is cross module capable. *) Remove the requirements and assumptions that the wxFrame hierarchy always had PCB_EDIT_FRAME and SCH_EDIT_FRAME as immediate parents of their viewers and editors. This is no longer the case, nor required. *) Use KIWAY::Player() everywhere to make KIWAY_PLAYERs, this registers the KIWAY_PLAYER within the KIWAY and makes it very easy to find an open frame quickly. It also gives control to the KIWAY as to frame hierarchical relationships. *) Change single_top to use the KIWAY for loading a KIFACE and instantiating the single KIWAY_PLAYER, see bullet immediately above. *) Add KIWAY::OnKiwayEnd() and call it from PGM_BASE at program termination, this gives the KIFACEs a chance to save their final configuration dope to disk. *) Add dedicated FRAME_T's for the modal frames, so m_Ident can be tested and these modal frames are distinctly different than their non-modal equivalents. KIWAY_PLAYER::IsModal() is !not! a valid test during the wxFrame's constructor, so this is another important reason for having a dedicated FRAME_T for each modal wxFrame. On balance, more lines were deleted than were added to achieve all this.
2014-05-03 17:40:19 +00:00
int SetRevision( const UTF8& aRevision );
2014-01-02 02:17:07 +00:00
const UTF8& GetRevision() const { return revision; }
2014-01-02 02:17:07 +00:00
UTF8 GetFootprintNameAndRev() const;
2013-02-16 01:09:53 +00:00
/**
* Function Format
* returns the fully formatted text of the FPID.
*/
2014-01-02 02:17:07 +00:00
UTF8 Format() const;
2013-02-16 01:09:53 +00:00
/**
* Function Format
* returns a wxString in the proper format as an FPID for a combination of
* aLibNickname, aFootprintName, and aRevision.
*
* @throw PARSE_ERROR if any of the pieces are illegal.
Modular-Kicad milestone B), major portions: *) Rework the set language support, simplify it by using KIWAY. Now any major frame with a "change language" menu can change the language for all KIWAY_PLAYERs in the whole KIWAY. Multiple KIWAYs are not supported yet. *) Simplify "modal wxFrame" support, and add that support exclusively to KIWAY_PLAYER where it is inherited by all derivatives. The function KIWAY_PLAYER::ShowModal() is in the vtable and so is cross module capable. *) Remove the requirements and assumptions that the wxFrame hierarchy always had PCB_EDIT_FRAME and SCH_EDIT_FRAME as immediate parents of their viewers and editors. This is no longer the case, nor required. *) Use KIWAY::Player() everywhere to make KIWAY_PLAYERs, this registers the KIWAY_PLAYER within the KIWAY and makes it very easy to find an open frame quickly. It also gives control to the KIWAY as to frame hierarchical relationships. *) Change single_top to use the KIWAY for loading a KIFACE and instantiating the single KIWAY_PLAYER, see bullet immediately above. *) Add KIWAY::OnKiwayEnd() and call it from PGM_BASE at program termination, this gives the KIFACEs a chance to save their final configuration dope to disk. *) Add dedicated FRAME_T's for the modal frames, so m_Ident can be tested and these modal frames are distinctly different than their non-modal equivalents. KIWAY_PLAYER::IsModal() is !not! a valid test during the wxFrame's constructor, so this is another important reason for having a dedicated FRAME_T for each modal wxFrame. On balance, more lines were deleted than were added to achieve all this.
2014-05-03 17:40:19 +00:00
static UTF8 Format( const UTF8& aLibNickname, const UTF8& aFootprintName,
const UTF8& aRevision = "" )
2013-02-16 01:09:53 +00:00
throw( PARSE_ERROR );
Modular-Kicad milestone B), major portions: *) Rework the set language support, simplify it by using KIWAY. Now any major frame with a "change language" menu can change the language for all KIWAY_PLAYERs in the whole KIWAY. Multiple KIWAYs are not supported yet. *) Simplify "modal wxFrame" support, and add that support exclusively to KIWAY_PLAYER where it is inherited by all derivatives. The function KIWAY_PLAYER::ShowModal() is in the vtable and so is cross module capable. *) Remove the requirements and assumptions that the wxFrame hierarchy always had PCB_EDIT_FRAME and SCH_EDIT_FRAME as immediate parents of their viewers and editors. This is no longer the case, nor required. *) Use KIWAY::Player() everywhere to make KIWAY_PLAYERs, this registers the KIWAY_PLAYER within the KIWAY and makes it very easy to find an open frame quickly. It also gives control to the KIWAY as to frame hierarchical relationships. *) Change single_top to use the KIWAY for loading a KIFACE and instantiating the single KIWAY_PLAYER, see bullet immediately above. *) Add KIWAY::OnKiwayEnd() and call it from PGM_BASE at program termination, this gives the KIFACEs a chance to save their final configuration dope to disk. *) Add dedicated FRAME_T's for the modal frames, so m_Ident can be tested and these modal frames are distinctly different than their non-modal equivalents. KIWAY_PLAYER::IsModal() is !not! a valid test during the wxFrame's constructor, so this is another important reason for having a dedicated FRAME_T for each modal wxFrame. On balance, more lines were deleted than were added to achieve all this.
2014-05-03 17:40:19 +00:00
*/
2013-02-16 01:09:53 +00:00
/**
* Function IsValid
* @return true is the #FPID is valid.
*
* A valid #FPID must have both the footprint library nickname and the footprint name
* defined. The revision field is optional.
*
* @note A return value of true does not indicated that the #FPID is a valid #FP_LIB_TABLE
* entry.
*/
bool IsValid() const { return !nickname.empty() && !footprint.empty(); }
/**
* Function IsLegacy
* @return true if the #FPID only has the #footprint name defined.
*/
bool IsLegacy() const { return nickname.empty() && !footprint.empty() && revision.empty(); }
/**
* Function clear
* clears the contents of the library nickname, footprint name, and revision strings.
*/
2013-02-16 01:09:53 +00:00
void clear();
/**
* Function empty
* @return a boolean true value if the FPID is empty. Otherwise return false.
*/
bool empty() const { return nickname.empty() && footprint.empty() && revision.empty(); }
/**
* Function Compare
* compares the contents of FPID objects by performing a std::string comparison of the
* library nickname, footprint name, and revision strings respectively.
*
* @param aFPID is the FPID to compare against.
* @return -1 if less than \a aFPID, 1 if greater than \a aFPID, and 0 if equal to \a aFPID.
*/
int compare( const FPID& aFPID ) const;
2014-01-02 02:17:07 +00:00
bool operator < ( const FPID& aFPID ) const { return this->compare( aFPID ) < 0; }
bool operator > ( const FPID& aFPID ) const { return this->compare( aFPID ) > 0; }
bool operator ==( const FPID& aFPID ) const { return this->compare( aFPID ) == 0; }
bool operator !=( const FPID& aFPID ) const { return !(*this == aFPID); }
2013-02-16 01:09:53 +00:00
#if defined(DEBUG)
static void Test();
#endif
protected:
2014-01-02 02:17:07 +00:00
UTF8 nickname; ///< The nickname of the footprint library or empty.
UTF8 footprint; ///< The name of the footprint in the logical library.
UTF8 revision; ///< The footprint revision.
2013-02-16 01:09:53 +00:00
};
#endif // _FPID_H_