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-2017 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 
69 #define CTL_STD_LAYER_NAMES (1 << 0)
70 #define CTL_OMIT_NETS (1 << 1)
71 #define CTL_OMIT_TSTAMPS (1 << 2)
72 #define CTL_OMIT_INITIAL_COMMENTS (1 << 3)
73 #define CTL_OMIT_PATH (1 << 4)
74 #define CTL_OMIT_AT (1 << 5)
75  // (always saved with potion 0,0 and rotation = 0 in library)
76 //#define CTL_OMIT_HIDE (1 << 6) // found and defined in eda_text.h
77 
78 
79 // common combinations of the above:
80 
82 #define CTL_FOR_CLIPBOARD (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS)
83 
85 #define CTL_FOR_LIBRARY (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS|CTL_OMIT_TSTAMPS|CTL_OMIT_PATH|CTL_OMIT_AT)
86 
89 #define CTL_FOR_BOARD (CTL_OMIT_INITIAL_COMMENTS)
90 
91 
98 class PCB_IO : public PLUGIN
99 {
100  friend class FP_CACHE;
101 
102 public:
103 
104  //-----<PLUGIN API>---------------------------------------------------------
105 
106  const wxString PluginName() const override
107  {
108  return wxT( "KiCad" );
109  }
110 
111  const wxString GetFileExtension() const override
112  {
113  // Would have used wildcards_and_files_ext.cpp's KiCadPcbFileExtension,
114  // but to be pure, a plugin should not assume that it will always be linked
115  // with the core of the pcbnew code. (Might someday be a DLL/DSO.) Besides,
116  // file extension policy should be controlled by the plugin.
117  return wxT( "kicad_pcb" );
118  }
119 
120  virtual void Save( const wxString& aFileName, BOARD* aBoard,
121  const PROPERTIES* aProperties = NULL ) override;
122 
123  BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
124  const PROPERTIES* aProperties = NULL ) override;
125 
126  void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
127  bool aBestEfforts, const PROPERTIES* aProperties = NULL ) override;
128 
129  const MODULE* GetEnumeratedFootprint( const wxString& aLibraryPath,
130  const wxString& aFootprintName,
131  const PROPERTIES* aProperties = NULL ) override;
132 
133  bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
134  const PROPERTIES* aProperties = NULL ) override;
135 
136  MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
137  const PROPERTIES* aProperties = NULL ) override;
138 
139  void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
140  const PROPERTIES* aProperties = NULL ) override;
141 
142  void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
143  const PROPERTIES* aProperties = NULL ) override;
144 
145  long long GetLibraryTimestamp( const wxString& aLibraryPath ) const override;
146 
147  void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL) override;
148 
149  bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL ) override;
150 
151  bool IsFootprintLibWritable( const wxString& aLibraryPath ) override;
152 
153  //-----</PLUGIN API>--------------------------------------------------------
154 
155  PCB_IO( int aControlFlags = CTL_FOR_BOARD );
156 
157  ~PCB_IO();
158 
167  void Format( BOARD_ITEM* aItem, int aNestLevel = 0 ) const;
168 
169  std::string GetStringOutput( bool doClear )
170  {
171  std::string ret = m_sf.GetString();
172  if( doClear )
173  m_sf.Clear();
174 
175  return ret;
176  }
177 
178  void SetOutputFormatter( OUTPUTFORMATTER* aFormatter ) { m_out = aFormatter; }
179 
180  BOARD_ITEM* Parse( const wxString& aClipboardSourceInput );
181 
182 protected:
183 
184  wxString m_error;
186 
187  const
190 
192  wxString m_filename;
193 
195 
198  int m_ctl;
201 
203  void validateCache( const wxString& aLibraryPath, bool checkModified = true );
204 
205  const MODULE* getFootprint( const wxString& aLibraryPath, const wxString& aFootprintName,
206  const PROPERTIES* aProperties, bool checkModified );
207 
208  void init( const PROPERTIES* aProperties );
209 
211  void formatSetup( BOARD* aBoard, int aNestLevel = 0 ) const;
212 
214  void formatDefaults( const BOARD_DESIGN_SETTINGS& aSettings, int aNestLevel ) const;
215 
217  void formatGeneral( BOARD* aBoard, int aNestLevel = 0 ) const;
218 
220  void formatBoardLayers( BOARD* aBoard, int aNestLevel = 0 ) const;
221 
223  void formatNetInformation( BOARD* aBoard, int aNestLevel = 0 ) const;
224 
226  void formatHeader( BOARD* aBoard, int aNestLevel = 0 ) const;
227 
228 private:
229  void format( BOARD* aBoard, int aNestLevel = 0 ) const;
230 
231  void format( DIMENSION* aDimension, int aNestLevel = 0 ) const;
232 
233  void format( EDGE_MODULE* aModuleDrawing, int aNestLevel = 0 ) const;
234 
235  void format( DRAWSEGMENT* aSegment, int aNestLevel = 0 ) const;
236 
237  void format( PCB_TARGET* aTarget, int aNestLevel = 0 ) const;
238 
239  void format( MODULE* aModule, int aNestLevel = 0 ) const;
240 
241  void format( D_PAD* aPad, int aNestLevel = 0 ) const;
242 
243  void format( TEXTE_PCB* aText, int aNestLevel = 0 ) const;
244 
245  void format( TEXTE_MODULE* aText, int aNestLevel = 0 ) const;
246 
247  void format( TRACK* aTrack, int aNestLevel = 0 ) const;
248 
249  void format( ZONE_CONTAINER* aZone, int aNestLevel = 0 ) const;
250 
251  void formatLayer( const BOARD_ITEM* aItem ) const;
252 
253  void formatLayers( LSET aLayerMask, int aNestLevel = 0 ) const;
254 };
255 
256 #endif // KICAD_PLUGIN_H_
Class ZONE_CONTAINER handles a list of polygons defining a copper zone.
Definition: class_zone.h:60
OUTPUTFORMATTER * m_out
output any Format()s to this, no ownership
Class LINE_READER is an abstract class from which implementation specific LINE_READERs may be derived...
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)
Class 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
Class 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.
Class PCB_PARSER reads a Pcbnew s-expression formatted LINE_READER object and returns the appropriate...
Definition: pcb_parser.h:67
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
Class OUTPUTFORMATTER is an important interface (abstract class) used to output 8 bit text in a conve...
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
Class 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.
Class LSET is a set of PCB_LAYER_IDs.
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.
Class BOARD holds information pertinent to a Pcbnew printed circuit board.
Definition: class_board.h:161
Class PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:271
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 formatDefaults(const BOARD_DESIGN_SETTINGS &aSettings, int aNestLevel) const
formats the defaults subsection of the board setup
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,...
Class 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
Class 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
Class BOARD_DESIGN_SETTINGS contains design settings for a BOARD object.