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 TRACK;
45 class ZONE_CONTAINER;
46 class TEXTE_PCB;
47 
48 
50 
51 //#define SEXPR_BOARD_FILE_VERSION 3 // first s-expression format, used legacy cu stack
52 //#define SEXPR_BOARD_FILE_VERSION 4 // reversed cu stack, changed Inner* to In* in reverse order
53 // // went to 32 Cu layers from 16.
54 //#define SEXPR_BOARD_FILE_VERSION 20160815 // differential pair settings per net class
55 //#define SEXPR_BOARD_FILE_VERSION 20170123 // EDA_TEXT refactor, moved 'hide'
56 //#define SEXPR_BOARD_FILE_VERSION 20170920 // long pad names and custom pad shape
57 //#define SEXPR_BOARD_FILE_VERSION 20170922 // Keepout zones can exist on multiple layers
58 //#define SEXPR_BOARD_FILE_VERSION 20171114 // Save 3D model offset in mm, instead of inches
59 //#define SEXPR_BOARD_FILE_VERSION 20171125 // Locked/unlocked TEXTE_MODULE
60 //#define SEXPR_BOARD_FILE_VERSION 20171130 // 3D model offset written using "offset" parameter
61 //#define SEXPR_BOARD_FILE_VERSION 20190331 // hatched zones and chamfered round rect pads
62 //#define SEXPR_BOARD_FILE_VERSION 20190421 // curves in custom pads
63 //#define SEXPR_BOARD_FILE_VERSION 20190516 // Remove segment count from zones
64 //#define SEXPR_BOARD_FILE_VERSION 20190605 // Add layer defaults
65 //#define SEXPR_BOARD_FILE_VERSION 20190905 // Add board physical stackup info in setup section
66 //#define SEXPR_BOARD_FILE_VERSION 20190907 // Keepout areas in footprints
67 //#define SEXPR_BOARD_FILE_VERSION 20191123 // pin function in pads
68 //#define SEXPR_BOARD_FILE_VERSION 20200104 // pad property for fabrication
69 //#define SEXPR_BOARD_FILE_VERSION 20200119 // arcs in tracks
70 //#define SEXPR_BOARD_FILE_VERSION 20200512 // page -> paper
71 //#define SEXPR_BOARD_FILE_VERSION 20200518 // save hole_to_hole_min
72 //#define SEXPR_BOARD_FILE_VERSION 20200614 // Add support for fp_rects and gr_rects
73 //#define SEXPR_BOARD_FILE_VERSION 20200625 // Multilayer zones, zone names, island controls
74 #define SEXPR_BOARD_FILE_VERSION 20200628 // remove visibility settings
75 
76 #define CTL_STD_LAYER_NAMES (1 << 0)
77 #define CTL_OMIT_NETS (1 << 1)
78 #define CTL_OMIT_TSTAMPS (1 << 2)
79 #define CTL_OMIT_INITIAL_COMMENTS (1 << 3)
80 #define CTL_OMIT_PATH (1 << 4)
81 #define CTL_OMIT_AT (1 << 5)
82  // (always saved with potion 0,0 and rotation = 0 in library)
83 //#define CTL_OMIT_HIDE (1 << 6) // found and defined in eda_text.h
84 
85 
86 // common combinations of the above:
87 
89 #define CTL_FOR_CLIPBOARD (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS)
90 
92 #define CTL_FOR_LIBRARY (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS|CTL_OMIT_TSTAMPS|CTL_OMIT_PATH|CTL_OMIT_AT)
93 
96 #define CTL_FOR_BOARD (CTL_OMIT_INITIAL_COMMENTS)
97 
98 
105 class PCB_IO : public PLUGIN
106 {
107  friend class FP_CACHE;
108 
109 public:
110 
111  //-----<PLUGIN API>---------------------------------------------------------
112 
113  const wxString PluginName() const override
114  {
115  return wxT( "KiCad" );
116  }
117 
118  const wxString GetFileExtension() const override
119  {
120  // Would have used wildcards_and_files_ext.cpp's KiCadPcbFileExtension,
121  // but to be pure, a plugin should not assume that it will always be linked
122  // with the core of the pcbnew code. (Might someday be a DLL/DSO.) Besides,
123  // file extension policy should be controlled by the plugin.
124  return wxT( "kicad_pcb" );
125  }
126 
127  virtual void Save( const wxString& aFileName, BOARD* aBoard,
128  const PROPERTIES* aProperties = NULL ) override;
129 
130  BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
131  const PROPERTIES* aProperties = NULL ) override;
132 
133  void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
134  bool aBestEfforts, const PROPERTIES* aProperties = NULL ) override;
135 
136  const MODULE* GetEnumeratedFootprint( const wxString& aLibraryPath,
137  const wxString& aFootprintName,
138  const PROPERTIES* aProperties = NULL ) override;
139 
140  bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
141  const PROPERTIES* aProperties = NULL ) override;
142 
143  MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
144  const PROPERTIES* aProperties = NULL ) override;
145 
146  void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
147  const PROPERTIES* aProperties = NULL ) override;
148 
149  void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
150  const PROPERTIES* aProperties = NULL ) override;
151 
152  long long GetLibraryTimestamp( const wxString& aLibraryPath ) const override;
153 
154  void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL) override;
155 
156  bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL ) override;
157 
158  bool IsFootprintLibWritable( const wxString& aLibraryPath ) override;
159 
160  //-----</PLUGIN API>--------------------------------------------------------
161 
162  PCB_IO( int aControlFlags = CTL_FOR_BOARD );
163 
164  ~PCB_IO();
165 
174  void Format( BOARD_ITEM* aItem, int aNestLevel = 0 ) const;
175 
176  std::string GetStringOutput( bool doClear )
177  {
178  std::string ret = m_sf.GetString();
179  if( doClear )
180  m_sf.Clear();
181 
182  return ret;
183  }
184 
185  void SetOutputFormatter( OUTPUTFORMATTER* aFormatter ) { m_out = aFormatter; }
186 
187  BOARD_ITEM* Parse( const wxString& aClipboardSourceInput );
188 
189 protected:
190 
191  wxString m_error;
193 
194  const
197 
199  wxString m_filename;
200 
202 
205  int m_ctl;
208 
210  void validateCache( const wxString& aLibraryPath, bool checkModified = true );
211 
212  const MODULE* getFootprint( const wxString& aLibraryPath, const wxString& aFootprintName,
213  const PROPERTIES* aProperties, bool checkModified );
214 
215  void init( const PROPERTIES* aProperties );
216 
218  void formatSetup( BOARD* aBoard, int aNestLevel = 0 ) const;
219 
221  void formatGeneral( BOARD* aBoard, int aNestLevel = 0 ) const;
222 
224  void formatBoardLayers( BOARD* aBoard, int aNestLevel = 0 ) const;
225 
227  void formatNetInformation( BOARD* aBoard, int aNestLevel = 0 ) const;
228 
230  void formatHeader( BOARD* aBoard, int aNestLevel = 0 ) const;
231 
232 private:
233  void format( BOARD* aBoard, int aNestLevel = 0 ) const;
234 
235  void format( DIMENSION* aDimension, int aNestLevel = 0 ) const;
236 
237  void format( EDGE_MODULE* aModuleDrawing, int aNestLevel = 0 ) const;
238 
239  void format( DRAWSEGMENT* aSegment, int aNestLevel = 0 ) const;
240 
241  void format( PCB_TARGET* aTarget, int aNestLevel = 0 ) const;
242 
243  void format( MODULE* aModule, int aNestLevel = 0 ) const;
244 
245  void format( D_PAD* aPad, int aNestLevel = 0 ) const;
246 
247  void format( TEXTE_PCB* aText, int aNestLevel = 0 ) const;
248 
249  void format( TEXTE_MODULE* aText, int aNestLevel = 0 ) const;
250 
251  void format( TRACK* aTrack, int aNestLevel = 0 ) const;
252 
253  void format( ZONE_CONTAINER* aZone, int aNestLevel = 0 ) const;
254 
255  void formatLayer( const BOARD_ITEM* aItem ) const;
256 
257  void formatLayers( LSET aLayerMask, int aNestLevel = 0 ) const;
258 };
259 
260 #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_PARSER reads a Pcbnew s-expression formatted LINE_READER object and returns the appropriate BOARD...
Definition: pcb_parser.h:69
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 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:180
PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:273
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
DIMENSION.
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_DESIGN_SETTINGS contains design settings for a BOARD object.