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 //#define SEXPR_BOARD_FILE_VERSION 20210228 // Move global margins back to board file
99 #define SEXPR_BOARD_FILE_VERSION 20210424 // Correct locked flag syntax (remove parens).
100 
101 #define BOARD_FILE_HOST_VERSION 20200825
102 
103 #define CTL_OMIT_PAD_NETS (1 << 1)
104 #define CTL_OMIT_TSTAMPS (1 << 2)
105 #define CTL_OMIT_INITIAL_COMMENTS (1 << 3)
106 #define CTL_OMIT_PATH (1 << 4)
107 #define CTL_OMIT_AT (1 << 5)
108 //#define CTL_OMIT_HIDE (1 << 6) // found and defined in eda_text.h
110 #define CTL_OMIT_LIBNAME (1 << 7)
111 #define CTL_OMIT_FOOTPRINT_VERSION (1 << 8)
113 
115 // common combinations of the above:
116 
118 #define CTL_FOR_CLIPBOARD (CTL_OMIT_INITIAL_COMMENTS) // (CTL_OMIT_NETS)
119 
121 #define CTL_FOR_LIBRARY \
122  ( CTL_OMIT_PAD_NETS | CTL_OMIT_TSTAMPS | CTL_OMIT_PATH | CTL_OMIT_AT | CTL_OMIT_LIBNAME )
123 
126 #define CTL_FOR_BOARD (CTL_OMIT_INITIAL_COMMENTS|CTL_OMIT_FOOTPRINT_VERSION)
127 
128 
134 class PCB_IO : public PLUGIN
135 {
136 public:
137  const wxString PluginName() const override
138  {
139  return wxT( "KiCad" );
140  }
141 
142  const wxString GetFileExtension() const override
143  {
144  // Would have used wildcards_and_files_ext.cpp's KiCadPcbFileExtension,
145  // but to be pure, a plugin should not assume that it will always be linked
146  // with the core of the Pcbnew code. (Might someday be a DLL/DSO.) Besides,
147  // file extension policy should be controlled by the plugin.
148  return wxT( "kicad_pcb" );
149  }
150 
151  virtual void Save( const wxString& aFileName, BOARD* aBoard,
152  const PROPERTIES* aProperties = nullptr ) override;
153 
154  BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
155  const PROPERTIES* aProperties = nullptr, PROJECT* aProject = nullptr ) override;
156 
157  BOARD* DoLoad( LINE_READER& aReader, BOARD* aAppendToMe, const PROPERTIES* aProperties );
158 
159  void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
160  bool aBestEfforts, const PROPERTIES* aProperties = nullptr ) override;
161 
162  const FOOTPRINT* GetEnumeratedFootprint( const wxString& aLibraryPath,
163  const wxString& aFootprintName,
164  const PROPERTIES* aProperties = nullptr ) override;
165 
166  bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
167  const PROPERTIES* aProperties = nullptr ) override;
168 
169  FOOTPRINT* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
170  bool aKeepUUID = false,
171  const PROPERTIES* aProperties = nullptr ) override;
172 
173  void FootprintSave( const wxString& aLibraryPath, const FOOTPRINT* aFootprint,
174  const PROPERTIES* aProperties = nullptr ) override;
175 
176  void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
177  const PROPERTIES* aProperties = nullptr ) override;
178 
179  long long GetLibraryTimestamp( const wxString& aLibraryPath ) const override;
180 
181  void FootprintLibCreate( const wxString& aLibraryPath,
182  const PROPERTIES* aProperties = nullptr) override;
183 
184  bool FootprintLibDelete( const wxString& aLibraryPath,
185  const PROPERTIES* aProperties = nullptr ) override;
186 
187  bool IsFootprintLibWritable( const wxString& aLibraryPath ) override;
188 
189  PCB_IO( int aControlFlags = CTL_FOR_BOARD );
190 
191  virtual ~PCB_IO();
192 
200  void Format( const BOARD_ITEM* aItem, int aNestLevel = 0 ) const;
201 
202  std::string GetStringOutput( bool doClear )
203  {
204  std::string ret = m_sf.GetString();
205 
206  if( doClear )
207  m_sf.Clear();
208 
209  return ret;
210  }
211 
212  void SetOutputFormatter( OUTPUTFORMATTER* aFormatter ) { m_out = aFormatter; }
213 
214  BOARD_ITEM* Parse( const wxString& aClipboardSourceInput );
215 
216 protected:
217  void validateCache( const wxString& aLibraryPath, bool checkModified = true );
218 
219  const FOOTPRINT* getFootprint( const wxString& aLibraryPath, const wxString& aFootprintName,
220  const PROPERTIES* aProperties, bool checkModified );
221 
222  void init( const PROPERTIES* aProperties );
223 
225  void formatSetup( const BOARD* aBoard, int aNestLevel = 0 ) const;
226 
228  void formatGeneral( const BOARD* aBoard, int aNestLevel = 0 ) const;
229 
231  void formatBoardLayers( const BOARD* aBoard, int aNestLevel = 0 ) const;
232 
234  void formatNetInformation( const BOARD* aBoard, int aNestLevel = 0 ) const;
235 
237  void formatProperties( const BOARD* aBoard, int aNestLevel = 0 ) const;
238 
240  void formatHeader( const BOARD* aBoard, int aNestLevel = 0 ) const;
241 
242 private:
243  void format( const BOARD* aBoard, int aNestLevel = 0 ) const;
244 
245  void format( const DIMENSION_BASE* aDimension, int aNestLevel = 0 ) const;
246 
247  void format( const FP_SHAPE* aFPShape, int aNestLevel = 0 ) const;
248 
249  void format( const PCB_GROUP* aGroup, int aNestLevel = 0 ) const;
250 
251  void format( const PCB_SHAPE* aSegment, int aNestLevel = 0 ) const;
252 
253  void format( const PCB_TARGET* aTarget, int aNestLevel = 0 ) const;
254 
255  void format( const FOOTPRINT* aFootprint, int aNestLevel = 0 ) const;
256 
257  void format( const PAD* aPad, int aNestLevel = 0 ) const;
258 
259  void format( const PCB_TEXT* aText, int aNestLevel = 0 ) const;
260 
261  void format( const FP_TEXT* aText, int aNestLevel = 0 ) const;
262 
263  void format( const TRACK* aTrack, int aNestLevel = 0 ) const;
264 
265  void format( const ZONE* aZone, int aNestLevel = 0 ) const;
266 
267  void formatLayer( const BOARD_ITEM* aItem ) const;
268 
269  void formatLayers( LSET aLayerMask, int aNestLevel = 0 ) const;
270 
271  friend class FP_CACHE;
272 
273 protected:
274  wxString m_error;
276 
277  const
280 
282  wxString m_filename;
283 
286  int m_ctl;
289 };
291 
292 #endif // KICAD_PLUGIN_H_
void format(const BOARD *aBoard, int aNestLevel=0) const
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.
FOOTPRINT * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, bool aKeepUUID=false, const PROPERTIES *aProperties=nullptr) override
Load a footprint having aFootprintName from the aLibraryPath containing a library format that this PL...
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
Handle 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:190
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.