KiCad PCB EDA Suite
plugin.cpp
Go to the documentation of this file.
1 /*
2  * This program source code file is part of KiCad, a free EDA CAD application.
3  *
4  * Copyright (C) 2011-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
5  * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.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 #include <io_mgr.h>
26 #include <properties.h>
27 #include <wx/translation.h>
28 
29 
30 #define FMT_UNIMPLEMENTED "Plugin \"%s\" does not implement the \"%s\" function."
31 
38 static void not_implemented( PLUGIN* aPlugin, const char* aCaller )
39 {
41  aPlugin->PluginName(),
42  wxString::FromUTF8( aCaller ) ) );
43 }
44 
45 
46 BOARD* PLUGIN::Load( const wxString& aFileName, BOARD* aAppendToMe, const PROPERTIES* aProperties,
47  PROJECT* aProject )
48 {
49  not_implemented( this, __FUNCTION__ );
50  return nullptr;
51 }
52 
53 
55 {
56  not_implemented( this, __FUNCTION__ );
57  return std::vector<FOOTPRINT*>();
58 }
59 
60 void PLUGIN::Save( const wxString& aFileName, BOARD* aBoard, const PROPERTIES* aProperties )
61 {
62  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
63  not_implemented( this, __FUNCTION__ );
64 }
65 
66 
67 void PLUGIN::FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
68  bool aBestEfforts, const PROPERTIES* aProperties )
69 {
70  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
71  not_implemented( this, __FUNCTION__ );
72 }
73 
74 
75 void PLUGIN::PrefetchLib( const wxString& aLibraryPath, const PROPERTIES* aProperties )
76 {
77  (void) aLibraryPath;
78  (void) aProperties;
79 }
80 
81 
82 const FOOTPRINT* PLUGIN::GetEnumeratedFootprint( const wxString& aLibraryPath,
83  const wxString& aFootprintName,
84  const PROPERTIES* aProperties )
85 {
86  // default implementation
87  return FootprintLoad( aLibraryPath, aFootprintName, aProperties );
88 }
89 
90 
91 bool PLUGIN::FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
92  const PROPERTIES* aProperties )
93 {
94  // default implementation
95  return FootprintLoad( aLibraryPath, aFootprintName, aProperties ) != nullptr;
96 }
97 
98 
99 FOOTPRINT* PLUGIN::FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
100  const PROPERTIES* aProperties )
101 {
102  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
103  not_implemented( this, __FUNCTION__ );
104  return nullptr;
105 }
106 
107 
108 void PLUGIN::FootprintSave( const wxString& aLibraryPath, const FOOTPRINT* aFootprint,
109  const PROPERTIES* aProperties )
110 {
111  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
112  not_implemented( this, __FUNCTION__ );
113 }
114 
115 
116 void PLUGIN::FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
117  const PROPERTIES* aProperties )
118 {
119  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
120  not_implemented( this, __FUNCTION__ );
121 }
122 
123 
124 void PLUGIN::FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties )
125 {
126  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
127  not_implemented( this, __FUNCTION__ );
128 }
129 
130 
131 bool PLUGIN::FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties )
132 {
133  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
134  not_implemented( this, __FUNCTION__ );
135  return false;
136 }
137 
138 
139 bool PLUGIN::IsFootprintLibWritable( const wxString& aLibraryPath )
140 {
141  // not pure virtual so that plugins only have to implement subset of the PLUGIN interface.
142  not_implemented( this, __FUNCTION__ );
143  return false;
144 }
145 
146 
147 void PLUGIN::FootprintLibOptions( PROPERTIES* aListToAppendTo ) const
148 {
149  // disable all these in another couple of months, after everyone has seen them:
150 #if 1
151  (*aListToAppendTo)["debug_level"] = UTF8( _(
152  "Enable <b>debug</b> logging for Footprint*() functions in this PLUGIN."
153  ));
154 
155  (*aListToAppendTo)["read_filter_regex"] = UTF8( _(
156  "Regular expression <b>footprint name</b> filter."
157  ));
158 
159  (*aListToAppendTo)["enable_transaction_logging"] = UTF8( _(
160  "Enable transaction logging. The mere presence of this option turns on the "
161  "logging, no need to set a Value."
162  ));
163 
164  (*aListToAppendTo)["username"] = UTF8( _(
165  "User name for <b>login</b> to some special library server."
166  ));
167 
168  (*aListToAppendTo)["password"] = UTF8( _(
169  "Password for <b>login</b> to some special library server."
170  ));
171 #endif
172 
173 #if 1
174  // Suitable for a C++ to python PLUGIN::Footprint*() adapter, move it to the adapter
175  // if and when implemented.
176  (*aListToAppendTo)["python_footprint_plugin"] = UTF8( _(
177  "Enter the python module which implements the PLUGIN::Footprint*() functions."
178  ));
179 #endif
180 }
181 
virtual const FOOTPRINT * GetEnumeratedFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
A version of FootprintLoad() for use after FootprintEnumerate() for more efficient cache management.
Definition: plugin.cpp:82
An 8 bit string that is assuredly encoded in UTF8, and supplies special conversion support to and fro...
Definition: utf8.h:70
Container for project specific data.
Definition: project.h:62
virtual void FootprintLibCreate(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr)
Create a new empty footprint library at aLibraryPath empty.
Definition: plugin.cpp:124
static void not_implemented(PLUGIN *aPlugin, const char *aCaller)
Throw an IO_ERROR and complains of an API function not being implemented.
Definition: plugin.cpp:38
virtual void FootprintLibOptions(PROPERTIES *aListToAppendTo) const
Append supported PLUGIN options to aListToAppenTo along with internationalized descriptions.
Definition: plugin.cpp:147
A name/value tuple with unique names and optional values.
Definition: properties.h:33
virtual BOARD * Load(const wxString &aFileName, BOARD *aAppendToMe, const PROPERTIES *aProperties=nullptr, PROJECT *aProject=nullptr)
Load information from some input file format that this PLUGIN implementation knows about into either ...
Definition: plugin.cpp:46
virtual bool IsFootprintLibWritable(const wxString &aLibraryPath)
Return true if the library at aLibraryPath is writable.
Definition: plugin.cpp:139
virtual std::vector< FOOTPRINT * > GetImportedCachedLibraryFootprints()
Return a container with the cached library footprints generated in the last call to Load.
Definition: plugin.cpp:54
virtual void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, bool aBestEfforts, const PROPERTIES *aProperties=nullptr)
Return a list of footprint names contained within the library at aLibraryPath.
Definition: plugin.cpp:67
virtual void FootprintDelete(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Delete aFootprintName from the library at aLibraryPath.
Definition: plugin.cpp:116
virtual void Save(const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=nullptr)
Write aBoard to a storage file in a format that this PLUGIN implementation knows about or it can be u...
Definition: plugin.cpp:60
virtual void PrefetchLib(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr)
If possible, prefetches the specified library (e.g.
Definition: plugin.cpp:75
#define FMT_UNIMPLEMENTED
Definition: plugin.cpp:30
virtual const wxString PluginName() const =0
Return a brief hard coded name for this PLUGIN.
virtual void FootprintSave(const wxString &aLibraryPath, const FOOTPRINT *aFootprint, const PROPERTIES *aProperties=nullptr)
Write aFootprint to an existing library located at aLibraryPath.
Definition: plugin.cpp:108
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, const CPTREE &aTree)
Output a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:200
Information pertinent to a Pcbnew printed circuit board.
Definition: board.h:189
#define _(s)
Definition: 3d_actions.cpp:33
A base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:267
virtual FOOTPRINT * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Load a footprint having aFootprintName from the aLibraryPath containing a library format that this PL...
Definition: plugin.cpp:99
virtual bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr)
Delete an existing footprint library and returns true, or if library does not exist returns false,...
Definition: plugin.cpp:131
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38
virtual bool FootprintExists(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Check for the existence of a footprint.
Definition: plugin.cpp:91