KiCad PCB EDA Suite
pcbnew/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;
39 class EDGE_MODULE;
40 class DRAWSEGMENT;
41 class PCB_TARGET;
42 class D_PAD;
43 class TEXTE_MODULE;
44 class PCB_GROUP;
45 class TRACK;
46 class ZONE_CONTAINER;
47 class TEXTE_PCB;
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 TEXTE_MODULE
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 module components
77 //#define SEXPR_BOARD_FILE_VERSION 20200807 // Add zone hatch advanced settings
78 //#define SEXPR_BOARD_FILE_VERSION 20200808 // Add properties to modules
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 
91 #define BOARD_FILE_HOST_VERSION 20200825
92 
93 #define CTL_STD_LAYER_NAMES (1 << 0)
94 #define CTL_OMIT_NETS (1 << 1)
95 #define CTL_OMIT_TSTAMPS (1 << 2)
96 #define CTL_OMIT_INITIAL_COMMENTS (1 << 3)
97 #define CTL_OMIT_PATH (1 << 4)
98 #define CTL_OMIT_AT (1 << 5)
99  // (always saved with potion 0,0 and rotation = 0 in library)
100 //#define CTL_OMIT_HIDE (1 << 6) // found and defined in eda_text.h
101 #define CTL_OMIT_LIBNAME (1 << 7)
102 
103 
104 // common combinations of the above:
105 
107 #define CTL_FOR_CLIPBOARD (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS)
108 
110 #define CTL_FOR_LIBRARY (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS|CTL_OMIT_TSTAMPS|CTL_OMIT_PATH|CTL_OMIT_AT|CTL_OMIT_LIBNAME)
111 
114 #define CTL_FOR_BOARD (CTL_OMIT_INITIAL_COMMENTS)
115 
116 
123 class PCB_IO : public PLUGIN
124 {
125  friend class FP_CACHE;
126 
127 public:
128 
129  //-----<PLUGIN API>---------------------------------------------------------
130 
131  const wxString PluginName() const override
132  {
133  return wxT( "KiCad" );
134  }
135 
136  const wxString GetFileExtension() const override
137  {
138  // Would have used wildcards_and_files_ext.cpp's KiCadPcbFileExtension,
139  // but to be pure, a plugin should not assume that it will always be linked
140  // with the core of the pcbnew code. (Might someday be a DLL/DSO.) Besides,
141  // file extension policy should be controlled by the plugin.
142  return wxT( "kicad_pcb" );
143  }
144 
145  virtual void Save( const wxString& aFileName, BOARD* aBoard,
146  const PROPERTIES* aProperties = NULL ) override;
147 
148  BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
149  const PROPERTIES* aProperties = NULL ) override;
150 
151  BOARD* DoLoad( LINE_READER& aReader, BOARD* aAppendToMe, const PROPERTIES* aProperties );
152 
153  void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
154  bool aBestEfforts, const PROPERTIES* aProperties = NULL ) override;
155 
156  const MODULE* GetEnumeratedFootprint( const wxString& aLibraryPath,
157  const wxString& aFootprintName,
158  const PROPERTIES* aProperties = NULL ) override;
159 
160  bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
161  const PROPERTIES* aProperties = NULL ) override;
162 
163  MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
164  const PROPERTIES* aProperties = NULL ) override;
165 
166  void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
167  const PROPERTIES* aProperties = NULL ) override;
168 
169  void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
170  const PROPERTIES* aProperties = NULL ) override;
171 
172  long long GetLibraryTimestamp( const wxString& aLibraryPath ) const override;
173 
174  void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL) override;
175 
176  bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL ) override;
177 
178  bool IsFootprintLibWritable( const wxString& aLibraryPath ) override;
179 
180  //-----</PLUGIN API>--------------------------------------------------------
181 
182  PCB_IO( int aControlFlags = CTL_FOR_BOARD );
183 
184  ~PCB_IO();
185 
194  void Format( BOARD_ITEM* aItem, int aNestLevel = 0 ) const;
195 
196  std::string GetStringOutput( bool doClear )
197  {
198  std::string ret = m_sf.GetString();
199  if( doClear )
200  m_sf.Clear();
201 
202  return ret;
203  }
204 
205  void SetOutputFormatter( OUTPUTFORMATTER* aFormatter ) { m_out = aFormatter; }
206 
207  BOARD_ITEM* Parse( const wxString& aClipboardSourceInput );
208 
209 protected:
210 
211  wxString m_error;
213 
214  const
217 
219  wxString m_filename;
220 
222 
225  int m_ctl;
228 
230  void validateCache( const wxString& aLibraryPath, bool checkModified = true );
231 
232  const MODULE* getFootprint( const wxString& aLibraryPath, const wxString& aFootprintName,
233  const PROPERTIES* aProperties, bool checkModified );
234 
235  void init( const PROPERTIES* aProperties );
236 
238  void formatSetup( BOARD* aBoard, int aNestLevel = 0 ) const;
239 
241  void formatGeneral( BOARD* aBoard, int aNestLevel = 0 ) const;
242 
244  void formatBoardLayers( BOARD* aBoard, int aNestLevel = 0 ) const;
245 
247  void formatNetInformation( BOARD* aBoard, int aNestLevel = 0 ) const;
248 
250  void formatProperties( BOARD* aBoard, int aNestLevel = 0 ) const;
251 
253  void formatHeader( BOARD* aBoard, int aNestLevel = 0 ) const;
254 
255 private:
256  void format( BOARD* aBoard, int aNestLevel = 0 ) const;
257 
258  void format( DIMENSION* aDimension, int aNestLevel = 0 ) const;
259 
260  void format( EDGE_MODULE* aModuleDrawing, int aNestLevel = 0 ) const;
261 
262  void format( PCB_GROUP* aGroup, int aNestLevel = 0 ) const;
263 
264  void format( DRAWSEGMENT* aSegment, int aNestLevel = 0 ) const;
265 
266  void format( PCB_TARGET* aTarget, int aNestLevel = 0 ) const;
267 
268  void format( MODULE* aModule, int aNestLevel = 0 ) const;
269 
270  void format( D_PAD* aPad, int aNestLevel = 0 ) const;
271 
272  void format( TEXTE_PCB* aText, int aNestLevel = 0 ) const;
273 
274  void format( TEXTE_MODULE* aText, int aNestLevel = 0 ) const;
275 
276  void format( TRACK* aTrack, int aNestLevel = 0 ) const;
277 
278  void format( ZONE_CONTAINER* aZone, int aNestLevel = 0 ) const;
279 
280  void formatLayer( const BOARD_ITEM* aItem ) const;
281 
282  void formatLayers( LSET aLayerMask, int aNestLevel = 0 ) const;
283 };
284 
285 #endif // KICAD_PLUGIN_H_
ZONE_CONTAINER handles a list of polygons defining a copper zone.
Definition: class_zone.h:61
OUTPUTFORMATTER * m_out
output any Format()s to this, no ownership
LINE_READER is an abstract class from which implementation specific LINE_READERs may be derived to re...
Definition: richio.h:81
LINE_READER * m_reader
no ownership here.
void formatGeneral(BOARD *aBoard, int aNestLevel=0) const
formats the General section of the file
BOARD_ITEM * Parse(const wxString &aClipboardSourceInput)
PCB_IO is a PLUGIN derivation for saving and loading Pcbnew s-expression formatted files.
BOARD * Load(const wxString &aFileName, BOARD *aAppendToMe, const PROPERTIES *aProperties=NULL) override
Function Load loads information from some input file format that this PLUGIN implementation knows abo...
void formatLayer(const BOARD_ITEM *aItem) const
BOARD_ITEM is a base class for any item which can be embedded within the BOARD container class,...
FP_CACHE * m_cache
Footprint library cache.
PCB_GROUP is a set of BOARD_ITEMs (i.e., without duplicates)
PCB_PARSER reads a Pcbnew s-expression formatted LINE_READER object and returns the appropriate BOARD...
Definition: pcb_parser.h:70
const PROPERTIES * m_props
passed via Save() or Load(), no ownership, may be NULL.
const MODULE * GetEnumeratedFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL) override
Function GetEnumeratedFootprint a version of FootprintLoad() for use after FootprintEnumerate() for m...
void init(const PROPERTIES *aProperties)
void formatNetInformation(BOARD *aBoard, int aNestLevel=0) const
formats the Nets and Netclasses
OUTPUTFORMATTER is an important interface (abstract class) used to output 8 bit text in a convenient ...
Definition: richio.h:327
bool IsFootprintLibWritable(const wxString &aLibraryPath) override
Function IsFootprintLibWritable returns true iff the library at aLibraryPath is writable.
wxString m_error
for throwing exceptions
PROPERTIES is a name/value tuple with unique names and optional values.
Definition: properties.h:34
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
Function GetFileExtension returns the file extension for the PLUGIN.
void formatProperties(BOARD *aBoard, int aNestLevel=0) const
formats the Nets and Netclasses
void SetOutputFormatter(OUTPUTFORMATTER *aFormatter)
PCB_IO(int aControlFlags=CTL_FOR_BOARD)
void FootprintLibCreate(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL) override
Function FootprintLibCreate creates a new empty footprint library at aLibraryPath empty.
LSET is a set of PCB_LAYER_IDs.
#define NULL
void FootprintSave(const wxString &aLibraryPath, const MODULE *aFootprint, const PROPERTIES *aProperties=NULL) override
Function FootprintSave will write aModule to an existing library located at aLibraryPath.
std::string GetStringOutput(bool doClear)
MODULE * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL) override
Function FootprintLoad loads a footprint having aFootprintName from the aLibraryPath containing a lib...
void validateCache(const wxString &aLibraryPath, bool checkModified=true)
int m_loading_format_version
which SEXPR_BOARD_FILE_VERSION should be Load()ed?
const std::string & GetString()
Definition: richio.h:475
void formatSetup(BOARD *aBoard, int aNestLevel=0) const
formats the board setup information
PCB_PARSER * m_parser
NETINFO_MAPPING * m_mapping
mapping for net codes, so only not empty net codes are stored with consecutive integers as net codes
void FootprintDelete(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL) override
Function FootprintDelete deletes aFootprintName from the library at aLibraryPath.
void formatBoardLayers(BOARD *aBoard, int aNestLevel=0) const
formats the board layer information
#define CTL_FOR_BOARD
The zero arg constructor when PCB_IO is used for PLUGIN::Load() and PLUGIN::Save()ing a BOARD file un...
STRING_FORMATTER m_sf
const MODULE * getFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties, bool checkModified)
Board layer functions and definitions.
BOARD holds information pertinent to a Pcbnew printed circuit board.
Definition: class_board.h:178
PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:274
void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, bool aBestEfforts, const PROPERTIES *aProperties=NULL) override
Return a list of footprint names contained within the library at aLibraryPath.
BOARD * m_board
which BOARD, no ownership here
bool FootprintExists(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL) override
Function FootprintExists check for the existence of a footprint.
void format(BOARD *aBoard, int aNestLevel=0) const
const wxString PluginName() const override
Function PluginName returns a brief hard coded name for this PLUGIN.
void formatHeader(BOARD *aBoard, int aNestLevel=0) const
writes everything that comes before the board_items, like settings and layers etc
void formatLayers(LSET aLayerMask, int aNestLevel=0) const
void Format(BOARD_ITEM *aItem, int aNestLevel=0) const
Function Format outputs aItem to aFormatter in s-expression format.
bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL) override
Function FootprintLibDelete deletes an existing footprint library and returns true,...
STRING_FORMATTER implements OUTPUTFORMATTER to a memory buffer.
Definition: richio.h:445
wxString m_filename
for saves only, name is in m_reader for loads
Abstract dimension API.
virtual void Save(const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=NULL) override
Function Save will write aBoard to a storage file in a format that this PLUGIN implementation knows a...
void Clear()
Function Clear clears the buffer and empties the internal string.
Definition: richio.h:464
BOARD * DoLoad(LINE_READER &aReader, BOARD *aAppendToMe, const PROPERTIES *aProperties)
BOARD_DESIGN_SETTINGS contains design settings for a BOARD object.