1 /* 2 * This program source code file is part of KiCad, a free EDA CAD application. 3 * 4 * Copyright (C) 2016 Wayne Stambaugh <stambaughw@gmail.com> 5 * Copyright (C) 2016-2021 KiCad Developers, see change_log.txt for contributors. 6 * 7 * This program is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU General Public License 9 * as published by the Free Software Foundation; either version 2 10 * of the License, or (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, you may find one here: 19 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html 20 * or you may search the http://www.gnu.org website for the version 2 license, 21 * or you may write to the Free Software Foundation, Inc., 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 23 */ 24 25 #ifndef _SYMBOL_LIB_TABLE_H_ 26 #define _SYMBOL_LIB_TABLE_H_ 27 28 #include <lib_table_base.h> 29 #include <sch_io_mgr.h> 30 #include <lib_id.h> 31 32 //class LIB_SYMBOL; 33 class SYMBOL_LIB_TABLE_GRID; 34 class DIALOG_SYMBOL_LIB_TABLE; 35 36 37 /** 38 * Hold a record identifying a symbol library accessed by the appropriate symbol library 39 * #SCH_PLUGIN object in the #SYMBOL_LIB_TABLE. 40 */ 41 class SYMBOL_LIB_TABLE_ROW : public LIB_TABLE_ROW 42 { 43 public: 44 typedef SCH_IO_MGR::SCH_FILE_T LIB_T; 45 46 SYMBOL_LIB_TABLE_ROW( const wxString& aNick, const wxString& aURI, const wxString& aType, 47 const wxString& aOptions = wxEmptyString, 48 const wxString& aDescr = wxEmptyString ) : LIB_TABLE_ROW(aNick,aURI,aOptions,aDescr)49 LIB_TABLE_ROW( aNick, aURI, aOptions, aDescr ) 50 { 51 SetType( aType ); 52 SetEnabled( true ); 53 } 54 SYMBOL_LIB_TABLE_ROW()55 SYMBOL_LIB_TABLE_ROW() : 56 type( SCH_IO_MGR::SCH_KICAD ) 57 { 58 SetEnabled( true ); 59 } 60 61 bool operator==( const SYMBOL_LIB_TABLE_ROW& aRow ) const; 62 63 bool operator!=( const SYMBOL_LIB_TABLE_ROW& aRow ) const { return !( *this == aRow ); } 64 65 /** 66 * Return the type of symbol library table represented by this row. 67 */ GetType()68 const wxString GetType() const override { return SCH_IO_MGR::ShowType( type ); } 69 70 /** 71 * Change the schematic plugin type represented by this row. 72 */ 73 void SetType( const wxString& aType ) override; 74 75 /** 76 * Attempt to reload the library. 77 * 78 * @return true if a reload was required. 79 * @throw IO_ERROR if the reload was unsuccessful. 80 */ 81 bool Refresh(); 82 83 protected: SYMBOL_LIB_TABLE_ROW(const SYMBOL_LIB_TABLE_ROW & aRow)84 SYMBOL_LIB_TABLE_ROW( const SYMBOL_LIB_TABLE_ROW& aRow ) : 85 LIB_TABLE_ROW( aRow ), 86 type( aRow.type ) 87 { 88 SetEnabled( aRow.GetIsEnabled() ); 89 } 90 91 private: 92 friend class SYMBOL_LIB_TABLE; 93 do_clone()94 virtual LIB_TABLE_ROW* do_clone() const override 95 { 96 return new SYMBOL_LIB_TABLE_ROW( *this ); 97 } 98 setPlugin(SCH_PLUGIN * aPlugin)99 void setPlugin( SCH_PLUGIN* aPlugin ) 100 { 101 plugin.set( aPlugin ); 102 } 103 104 SCH_PLUGIN::SCH_PLUGIN_RELEASER plugin; 105 LIB_T type; 106 }; 107 108 109 class SYMBOL_LIB_TABLE : public LIB_TABLE 110 { 111 public: Type()112 KICAD_T Type() override { return SYMBOL_LIB_TABLE_T; } 113 114 static const char* PropPowerSymsOnly; 115 static const char* PropNonPowerSymsOnly; 116 117 virtual void Parse( LIB_TABLE_LEXER* aLexer ) override; 118 119 virtual void Format( OUTPUTFORMATTER* aOutput, int aIndentLevel ) const override; 120 121 /** 122 * Build a symbol library table by pre-pending this table fragment in front of 123 * @a aFallBackTable. Loading of this table fragment is done by using Parse(). 124 * 125 * @param aFallBackTable is another SYMBOL_LIB_TABLE which is searched only when 126 * a row is not found in this table. No ownership is 127 * taken of aFallBackTable. 128 */ 129 SYMBOL_LIB_TABLE( SYMBOL_LIB_TABLE* aFallBackTable = nullptr ); 130 131 /** 132 * Return an SYMBOL_LIB_TABLE_ROW if \a aNickName is found in this table or in any chained 133 * fallBack table fragment. 134 * 135 * The #SCH_PLUGIN is loaded and attached to the "plugin" fieldf the #SYMBOL_LIB_TABLE_ROW if 136 * not already loaded. 137 * 138 * @param aNickName is the name of the row to find. 139 * @param aCheckIfEnabled is a flag to verify if the table entry is enabled or disabled. 140 * @return the row found or NULL if \a aNickName was not found. 141 */ 142 SYMBOL_LIB_TABLE_ROW* FindRow( const wxString& aNickName, bool aCheckIfEnabled = false ); 143 144 int GetModifyHash(); 145 146 //-----<PLUGIN API SUBSET, REBASED ON aNickname>--------------------------- 147 148 /** 149 * Return a list of symbol alias names contained within the library given by @a aNickname. 150 * 151 * @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW. 152 * @param aAliasNames is a reference to an array for the alias names. 153 * @param aPowerSymbolsOnly is a flag to enumerate only power symbols. 154 * @throw IO_ERROR if the library cannot be found or loaded. 155 */ 156 void EnumerateSymbolLib( const wxString& aNickname, wxArrayString& aAliasNames, 157 bool aPowerSymbolsOnly = false ); 158 159 void LoadSymbolLib( std::vector<LIB_SYMBOL*>& aAliasList, const wxString& aNickname, 160 bool aPowerSymbolsOnly = false ); 161 162 /** 163 * Load a #LIB_SYMBOL having @a aName from the library given by @a aNickname. 164 * 165 * @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW 166 * @param aName is the name of the #LIB_SYMBOL to load. 167 * @param aFlatten set to true to flatten derived parts. 168 * @return the symbol alias if found or NULL if not found. 169 * @throw IO_ERROR if the library cannot be found or read. No exception 170 * is thrown in the case where \a aNickname cannot be found. 171 */ 172 LIB_SYMBOL* LoadSymbol( const wxString& aNickname, const wxString& aName ); 173 LoadSymbol(const LIB_ID & aLibId)174 LIB_SYMBOL* LoadSymbol( const LIB_ID& aLibId ) 175 { 176 return LoadSymbol( aLibId.GetLibNickname(), aLibId.GetLibItemName() ); 177 } 178 179 /** 180 * The set of return values from SaveSymbol() below. 181 */ 182 enum SAVE_T 183 { 184 SAVE_OK, 185 SAVE_SKIPPED, 186 }; 187 188 /** 189 * Write @a aSymbol to an existing library given by @a aNickname. 190 * 191 * If a #LIB_SYMBOL by the same name already exists or there are any conflicting alias 192 * names, the new #LIB_SYMBOL will silently overwrite any existing aliases and/or part 193 * because libraries cannot have duplicate alias names. It is the responsibility of 194 * the caller to check the library for conflicts before saving. 195 * 196 * @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW 197 * @param aSymbol is what to store in the library. The library owns the symbol after this 198 * call. 199 * @param aOverwrite when true means overwrite any existing symbol by the same name, 200 * else if false means skip the write and return SAVE_SKIPPED. 201 * @return SAVE_T - SAVE_OK or SAVE_SKIPPED. If error saving, then IO_ERROR is thrown. 202 * @throw IO_ERROR if there is a problem saving the symbol. 203 */ 204 SAVE_T SaveSymbol( const wxString& aNickname, const LIB_SYMBOL* aSymbol, 205 bool aOverwrite = true ); 206 207 /** 208 * Deletes the @a aSymbolName from the library given by @a aNickname. 209 * 210 * @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW. 211 * @param aSymbolName is the name of a symbol to delete from the specified library. 212 * @throw IO_ERROR if there is a problem finding the footprint or the library, or deleting it. 213 */ 214 void DeleteSymbol( const wxString& aNickname, const wxString& aSymbolName ); 215 216 /** 217 * Return true if the library given by @a aNickname is writable. 218 * 219 * It is possible that some symbols libraries are read only because of where they are 220 * installed. 221 * 222 * @param aNickname is the library nickname in the symbol library table. 223 * @throw IO_ERROR if no library at @a aNickname exists. 224 */ 225 bool IsSymbolLibWritable( const wxString& aNickname ); 226 227 /** 228 * Return true if the library given by @a aNickname was successfully loaded. 229 * 230 * @param aNickname is the library nickname in the symbol library table. 231 * @throw IO_ERROR if no library at @a aNickname exists. 232 */ 233 bool IsSymbolLibLoaded( const wxString& aNickname ); 234 235 void DeleteSymbolLib( const wxString& aNickname ); 236 237 void CreateSymbolLib( const wxString& aNickname ); 238 239 //-----</PLUGIN API SUBSET, REBASED ON aNickname>--------------------------- 240 241 /** 242 * Load a #LIB_SYMBOL having @a aFootprintId with possibly an empty library nickname. 243 * 244 * @param aId the library nickname and name of the symbol to load. 245 * @return the library symbol if found (the library owns it) or NULL if not found. 246 * @throw IO_ERROR if the library cannot be found or read. No exception 247 * is thrown in the case where aId cannot be found. 248 * @throw PARSE_ERROR if @a aId is not parsed OK. 249 */ 250 LIB_SYMBOL* LoadSymbolWithOptionalNickname( const LIB_ID& aId ); 251 252 /** 253 * Load the global symbol library table into \a aTable. 254 * 255 * This probably should be move into the application object when KiCad is changed 256 * to a single process application. This is the least painful solution for the 257 * time being. 258 * 259 * @param aTable the #SYMBOL_LIB_TABLE object to load. 260 * @return true if the global library table exists and is loaded properly. 261 * @throw IO_ERROR if an error occurs attempting to load the symbol library table. 262 */ 263 static bool LoadGlobalTable( SYMBOL_LIB_TABLE& aTable ); 264 265 /** 266 * 267 * Fetch the global symbol library table file name. 268 * 269 * @return the platform specific global symbol library path and file name. 270 */ 271 static wxString GetGlobalTableFileName(); 272 273 /** 274 * Return the name of the environment variable used to hold the directory of locally 275 * installed "KiCad sponsored" system symbol libraries. 276 * 277 * These can be either legacy or sweet format. The only thing special about this 278 * particular environment variable is that it is set automatically by KiCad on 279 * program start up, <b>if</b> it is not set already in the environment. 280 */ 281 static const wxString GlobalPathEnvVariableName(); 282 283 static SYMBOL_LIB_TABLE& GetGlobalLibTable(); 284 285 static const wxString& GetSymbolLibTableFileName(); 286 287 private: 288 friend class SYMBOL_LIB_TABLE_GRID; 289 friend class PANEL_SYM_LIB_TABLE; 290 291 static int m_modifyHash; ///< helper for GetModifyHash() 292 }; 293 294 295 #endif // _SYMBOL_LIB_TABLE_H_ 296