KiCad PCB EDA Suite
pcbnew/plugins/kicad/kicad_plugin.h
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) 2012 CERN.
5  * Copyright (C) 1992-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 #ifndef KICAD_PLUGIN_H_
26 #define KICAD_PLUGIN_H_
27 
28 #include <io_mgr.h>
29 #include <string>
31 
32 class BOARD;
33 class BOARD_ITEM;
34 class FP_CACHE;
35 class PCB_PARSER;
36 class NETINFO_MAPPING;
38 class DIMENSION_BASE;
39 class FP_SHAPE;
40 class PCB_SHAPE;
41 class PCB_TARGET;
42 class PAD;
43 class FP_TEXT;
44 class PCB_GROUP;
45 class TRACK;
46 class ZONE;
47 class PCB_TEXT;
48 
49 
51 
52 //#define SEXPR_BOARD_FILE_VERSION 3 // first s-expression format, used legacy cu stack
53 //#define SEXPR_BOARD_FILE_VERSION 4 // reversed cu stack, changed Inner* to In* in reverse order
54 // // went to 32 Cu layers from 16.
55 //#define SEXPR_BOARD_FILE_VERSION 20160815 // differential pair settings per net class
56 //#define SEXPR_BOARD_FILE_VERSION 20170123 // EDA_TEXT refactor, moved 'hide'
57 //#define SEXPR_BOARD_FILE_VERSION 20170920 // long pad names and custom pad shape
58 //#define SEXPR_BOARD_FILE_VERSION 20170922 // Keepout zones can exist on multiple layers
59 //#define SEXPR_BOARD_FILE_VERSION 20171114 // Save 3D model offset in mm, instead of inches
60 //#define SEXPR_BOARD_FILE_VERSION 20171125 // Locked/unlocked FP_TEXT
61 //#define SEXPR_BOARD_FILE_VERSION 20171130 // 3D model offset written using "offset" parameter
62 //#define SEXPR_BOARD_FILE_VERSION 20190331 // hatched zones and chamfered round rect pads
63 //#define SEXPR_BOARD_FILE_VERSION 20190421 // curves in custom pads
64 //#define SEXPR_BOARD_FILE_VERSION 20190516 // Remove segment count from zones
65 //#define SEXPR_BOARD_FILE_VERSION 20190605 // Add layer defaults
66 //#define SEXPR_BOARD_FILE_VERSION 20190905 // Add board physical stackup info in setup section
67 //#define SEXPR_BOARD_FILE_VERSION 20190907 // Keepout areas in footprints
68 //#define SEXPR_BOARD_FILE_VERSION 20191123 // pin function in pads
69 //#define SEXPR_BOARD_FILE_VERSION 20200104 // pad property for fabrication
70 //#define SEXPR_BOARD_FILE_VERSION 20200119 // arcs in tracks
71 //#define SEXPR_BOARD_FILE_VERSION 20200512 // page -> paper
72 //#define SEXPR_BOARD_FILE_VERSION 20200518 // save hole_to_hole_min
73 //#define SEXPR_BOARD_FILE_VERSION 20200614 // Add support for fp_rects and gr_rects
74 //#define SEXPR_BOARD_FILE_VERSION 20200625 // Multilayer zones, zone names, island controls
75 //#define SEXPR_BOARD_FILE_VERSION 20200628 // remove visibility settings
76 //#define SEXPR_BOARD_FILE_VERSION 20200724 // Add KIID to footprints
77 //#define SEXPR_BOARD_FILE_VERSION 20200807 // Add zone hatch advanced settings
78 //#define SEXPR_BOARD_FILE_VERSION 20200808 // Add properties to footprints
79 //#define SEXPR_BOARD_FILE_VERSION 20200809 // Add REMOVE_UNUSED_LAYERS option to vias and THT pads
80 //#define SEXPR_BOARD_FILE_VERSION 20200811 // Add groups
81 //#define SEXPR_BOARD_FILE_VERSION 20200818 // Remove Status flag bitmap and setup counts
82 //#define SEXPR_BOARD_FILE_VERSION 20200819 // Add board-level properties
83 //#define SEXPR_BOARD_FILE_VERSION 20200825 // Remove host information
84 //#define SEXPR_BOARD_FILE_VERSION 20200828 // Add new fabrication attributes
85 //#define SEXPR_BOARD_FILE_VERSION 20200829 // Remove library name from exported footprints
86 //#define SEXPR_BOARD_FILE_VERSION 20200909 // Change DIMENSION format
87 //#define SEXPR_BOARD_FILE_VERSION 20200913 // Add leader dimension
88 //#define SEXPR_BOARD_FILE_VERSION 20200916 // Add center dimension
89 //#define SEXPR_BOARD_FILE_VERSION 20200921 // Add orthogonal dimension
90 //#define SEXPR_BOARD_FILE_VERSION 20200922 // Add user name to layer definition.
91 //#define SEXPR_BOARD_FILE_VERSION 20201002 // Add groups in footprints (for footprint editor).
92 //#define SEXPR_BOARD_FILE_VERSION 20201114 // Add first-class support for filled shapes.
93 //#define SEXPR_BOARD_FILE_VERSION 20201115 // module -> footprint and change fill syntax.
94 //#define SEXPR_BOARD_FILE_VERSION 20201116 // Write version and generator string in footprint files.
95 //#define SEXPR_BOARD_FILE_VERSION 20201220 // Add free via token
96 //#define SEXPR_BOARD_FILE_VERSION 20210108 // Pad locking moved from footprint to pads
97 #define SEXPR_BOARD_FILE_VERSION 20210126 // Store pintype alongside pinfunction (in pads).
98 
99 #define BOARD_FILE_HOST_VERSION 20200825
100 
101 #define CTL_OMIT_PAD_NETS (1 << 1)
102 #define CTL_OMIT_TSTAMPS (1 << 2)
103 #define CTL_OMIT_INITIAL_COMMENTS (1 << 3)
104 #define CTL_OMIT_PATH (1 << 4)
105 #define CTL_OMIT_AT (1 << 5)
106 //#define CTL_OMIT_HIDE (1 << 6) // found and defined in eda_text.h
108 #define CTL_OMIT_LIBNAME (1 << 7)
109 #define CTL_OMIT_FOOTPRINT_VERSION (1 << 8)
111 
113 // common combinations of the above:
114 
116 #define CTL_FOR_CLIPBOARD (CTL_OMIT_INITIAL_COMMENTS) // (CTL_OMIT_NETS)
117 
119 #define CTL_FOR_LIBRARY \
120  ( CTL_OMIT_PAD_NETS | CTL_OMIT_TSTAMPS | CTL_OMIT_PATH | CTL_OMIT_AT | CTL_OMIT_LIBNAME )
121 
124 #define CTL_FOR_BOARD (CTL_OMIT_INITIAL_COMMENTS|CTL_OMIT_FOOTPRINT_VERSION)
125 
126 
132 class PCB_IO : public PLUGIN
133 {
134 public:
135  const wxString PluginName() const override
136  {
137  return wxT( "KiCad" );
138  }
139 
140  const wxString GetFileExtension() const override
141  {
142  // Would have used wildcards_and_files_ext.cpp's KiCadPcbFileExtension,
143  // but to be pure, a plugin should not assume that it will always be linked
144  // with the core of the Pcbnew code. (Might someday be a DLL/DSO.) Besides,
145  // file extension policy should be controlled by the plugin.
146  return wxT( "kicad_pcb" );
147  }
148 
149  virtual void Save( const wxString& aFileName, BOARD* aBoard,
150  const PROPERTIES* aProperties = nullptr ) override;
151 
152  BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
153  const PROPERTIES* aProperties = nullptr, PROJECT* aProject = nullptr ) override;
154 
155  BOARD* DoLoad( LINE_READER& aReader, BOARD* aAppendToMe, const PROPERTIES* aProperties );
156 
157  void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
158  bool aBestEfforts, const PROPERTIES* aProperties = nullptr ) override;
159 
160  const FOOTPRINT* GetEnumeratedFootprint( const wxString& aLibraryPath,
161  const wxString& aFootprintName,
162  const PROPERTIES* aProperties = nullptr ) override;
163 
164  bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
165  const PROPERTIES* aProperties = nullptr ) override;
166 
167  FOOTPRINT* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
168  const PROPERTIES* aProperties = nullptr ) override;
169 
170  void FootprintSave( const wxString& aLibraryPath, const FOOTPRINT* aFootprint,
171  const PROPERTIES* aProperties = nullptr ) override;
172 
173  void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
174  const PROPERTIES* aProperties = nullptr ) override;
175 
176  long long GetLibraryTimestamp( const wxString& aLibraryPath ) const override;
177 
178  void FootprintLibCreate( const wxString& aLibraryPath,
179  const PROPERTIES* aProperties = nullptr) override;
180 
181  bool FootprintLibDelete( const wxString& aLibraryPath,
182  const PROPERTIES* aProperties = nullptr ) override;
183 
184  bool IsFootprintLibWritable( const wxString& aLibraryPath ) override;
185 
186  PCB_IO( int aControlFlags = CTL_FOR_BOARD );
187 
188  virtual ~PCB_IO();
189 
197  void Format( const BOARD_ITEM* aItem, int aNestLevel = 0 ) const;
198 
199  std::string GetStringOutput( bool doClear )
200  {
201  std::string ret = m_sf.GetString();
202 
203  if( doClear )
204  m_sf.Clear();
205 
206  return ret;
207  }
208 
209  void SetOutputFormatter( OUTPUTFORMATTER* aFormatter ) { m_out = aFormatter; }
210 
211  BOARD_ITEM* Parse( const wxString& aClipboardSourceInput );
212 
213 protected:
214  void validateCache( const wxString& aLibraryPath, bool checkModified = true );
215 
216  const FOOTPRINT* getFootprint( const wxString& aLibraryPath, const wxString& aFootprintName,
217  const PROPERTIES* aProperties, bool checkModified );
218 
219  void init( const PROPERTIES* aProperties );
220 
222  void formatSetup( const BOARD* aBoard, int aNestLevel = 0 ) const;
223 
225  void formatGeneral( const BOARD* aBoard, int aNestLevel = 0 ) const;
226 
228  void formatBoardLayers( const BOARD* aBoard, int aNestLevel = 0 ) const;
229 
231  void formatNetInformation( const BOARD* aBoard, int aNestLevel = 0 ) const;
232 
234  void formatProperties( const BOARD* aBoard, int aNestLevel = 0 ) const;
235 
237  void formatHeader( const BOARD* aBoard, int aNestLevel = 0 ) const;
238 
239 private:
240  void format( const BOARD* aBoard, int aNestLevel = 0 ) const;
241 
242  void format( const DIMENSION_BASE* aDimension, int aNestLevel = 0 ) const;
243 
244  void format( const FP_SHAPE* aFPShape, int aNestLevel = 0 ) const;
245 
246  void format( const PCB_GROUP* aGroup, int aNestLevel = 0 ) const;
247 
248  void format( const PCB_SHAPE* aSegment, int aNestLevel = 0 ) const;
249 
250  void format( const PCB_TARGET* aTarget, int aNestLevel = 0 ) const;
251 
252  void format( const FOOTPRINT* aFootprint, int aNestLevel = 0 ) const;
253 
254  void format( const PAD* aPad, int aNestLevel = 0 ) const;
255 
256  void format( const PCB_TEXT* aText, int aNestLevel = 0 ) const;
257 
258  void format( const FP_TEXT* aText, int aNestLevel = 0 ) const;
259 
260  void format( const TRACK* aTrack, int aNestLevel = 0 ) const;
261 
262  void format( const ZONE* aZone, int aNestLevel = 0 ) const;
263 
264  void formatLayer( const BOARD_ITEM* aItem ) const;
265 
266  void formatLayers( LSET aLayerMask, int aNestLevel = 0 ) const;
267 
268  friend class FP_CACHE;
269 
270 protected:
271  wxString m_error;
273 
274  const
277 
279  wxString m_filename;
280 
283  int m_ctl;
286 };
288 
289 #endif // KICAD_PLUGIN_H_
void format(const BOARD *aBoard, int aNestLevel=0) const
FOOTPRINT * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr) override
Load a footprint having aFootprintName from the aLibraryPath containing a library format that this PL...
OUTPUTFORMATTER * m_out
output any Format()s to this, no ownership
An abstract class from which implementation specific LINE_READERs may be derived to read single lines...
Definition: richio.h:80
bool FootprintExists(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr) override
Check for the existence of a footprint.
LINE_READER * m_reader
no ownership here.
BOARD_ITEM * Parse(const wxString &aClipboardSourceInput)
A PLUGIN derivation for saving and loading Pcbnew s-expression formatted files.
Container for project specific data.
Definition: project.h:62
void formatBoardLayers(const BOARD *aBoard, int aNestLevel=0) const
formats the board layer information
void formatLayer(const BOARD_ITEM *aItem) const
const FOOTPRINT * getFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties, bool checkModified)
BOARD * Load(const wxString &aFileName, BOARD *aAppendToMe, const PROPERTIES *aProperties=nullptr, PROJECT *aProject=nullptr) override
Load information from some input file format that this PLUGIN implementation knows about into either ...
A base class for any item which can be embedded within the BOARD container class, and therefore insta...
Definition: board_item.h:82
virtual ~PCB_IO()
FP_CACHE * m_cache
Footprint library cache.
A set of BOARD_ITEMs (i.e., without duplicates).
Definition: pcb_group.h:50
Read a Pcbnew s-expression formatted LINE_READER object and returns the appropriate BOARD_ITEM object...
Definition: pcb_parser.h:68
const PROPERTIES * m_props
passed via Save() or Load(), no ownership, may be NULL.
void init(const PROPERTIES *aProperties)
void formatProperties(const BOARD *aBoard, int aNestLevel=0) const
formats the Nets and Netclasses
An interface used to output 8 bit text in a convenient way.
Definition: richio.h:306
bool IsFootprintLibWritable(const wxString &aLibraryPath) override
Return true if the library at aLibraryPath is writable.
wxString m_error
for throwing exceptions
A name/value tuple with unique names and optional values.
Definition: properties.h:33
long long GetLibraryTimestamp(const wxString &aLibraryPath) const override
Generate a timestamp representing all the files in the library (including the library directory).
const wxString GetFileExtension() const override
Returns the file extension for the PLUGIN.
void SetOutputFormatter(OUTPUTFORMATTER *aFormatter)
void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, bool aBestEfforts, const PROPERTIES *aProperties=nullptr) override
Return a list of footprint names contained within the library at aLibraryPath.
PCB_IO(int aControlFlags=CTL_FOR_BOARD)
LSET is a set of PCB_LAYER_IDs.
std::string GetStringOutput(bool doClear)
void formatHeader(const BOARD *aBoard, int aNestLevel=0) const
writes everything that comes before the board_items, like settings and layers etc
void formatGeneral(const BOARD *aBoard, int aNestLevel=0) const
formats the General section of the file
void validateCache(const wxString &aLibraryPath, bool checkModified=true)
void formatNetInformation(const BOARD *aBoard, int aNestLevel=0) const
formats the Nets and Netclasses
ZONE handles a list of polygons defining a copper zone.
Definition: zone.h:57
const std::string & GetString()
Definition: richio.h:435
void formatSetup(const BOARD *aBoard, int aNestLevel=0) const
formats the board setup information
NETINFO_MAPPING * m_mapping
mapping for net codes, so only not empty net codes are stored with consecutive integers as net codes
#define CTL_FOR_BOARD
The zero arg constructor when PCB_IO is used for PLUGIN::Load() and PLUGIN::Save()ing a BOARD file un...
void FootprintLibCreate(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr) override
Create a new empty footprint library at aLibraryPath empty.
void Format(const BOARD_ITEM *aItem, int aNestLevel=0) const
Output aItem to aFormatter in s-expression format.
Board layer functions and definitions.
Information pertinent to a Pcbnew printed circuit board.
Definition: board.h:189
bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr) override
Delete an existing footprint library and returns true, or if library does not exist returns false,...
A base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:267
BOARD * m_board
which BOARD, no ownership here
const wxString PluginName() const override
Return a brief hard coded name for this PLUGIN.
virtual void Save(const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=nullptr) override
Write aBoard to a storage file in a format that this PLUGIN implementation knows about or it can be u...
void formatLayers(LSET aLayerMask, int aNestLevel=0) const
void FootprintDelete(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr) override
Delete aFootprintName from the library at aLibraryPath.
Definition: pad.h:60
const FOOTPRINT * GetEnumeratedFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr) override
A version of FootprintLoad() for use after FootprintEnumerate() for more efficient cache management.
Abstract dimension API.
Definition: dimension.h:95
Implement an OUTPUTFORMATTER to a memory buffer.
Definition: richio.h:411
void FootprintSave(const wxString &aLibraryPath, const FOOTPRINT *aFootprint, const PROPERTIES *aProperties=nullptr) override
Write aFootprint to an existing library located at aLibraryPath.
wxString m_filename
for saves only, name is in m_reader for loads
Definition: track.h:83
void Clear()
Clear the buffer and empties the internal string.
Definition: richio.h:425
BOARD * DoLoad(LINE_READER &aReader, BOARD *aAppendToMe, const PROPERTIES *aProperties)
Container for design settings for a BOARD object.