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;
37 
38 
40 
41 //#define SEXPR_BOARD_FILE_VERSION 3 // first s-expression format, used legacy cu stack
42 //#define SEXPR_BOARD_FILE_VERSION 4 // reversed cu stack, changed Inner* to In* in reverse order
43 // // went to 32 Cu layers from 16.
44 //#define SEXPR_BOARD_FILE_VERSION 20160815 // differential pair settings per net class
45 //#define SEXPR_BOARD_FILE_VERSION 20170123 // EDA_TEXT refactor, moved 'hide'
46 //#define SEXPR_BOARD_FILE_VERSION 20170920 // long pad names and custom pad shape
47 //#define SEXPR_BOARD_FILE_VERSION 20170922 // Keepout zones can exist on multiple layers
48 //#define SEXPR_BOARD_FILE_VERSION 20171114 // Save 3D model offset in mm, instead of inches
49 //#define SEXPR_BOARD_FILE_VERSION 20171125 // Locked/unlocked TEXTE_MODULE
50 #define SEXPR_BOARD_FILE_VERSION 20171130 // 3D model offset written using "offset" parameter
51 
52 #define CTL_STD_LAYER_NAMES (1 << 0)
53 #define CTL_OMIT_NETS (1 << 1)
54 #define CTL_OMIT_TSTAMPS (1 << 2)
55 #define CTL_OMIT_INITIAL_COMMENTS (1 << 3)
56 #define CTL_OMIT_PATH (1 << 4)
57 #define CTL_OMIT_AT (1 << 5)
58  // (always saved with potion 0,0 and rotation = 0 in library)
59 //#define CTL_OMIT_HIDE (1 << 6) // found and defined in eda_text.h
60 
61 
62 // common combinations of the above:
63 
65 #define CTL_FOR_CLIPBOARD (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS)
66 
68 #define CTL_FOR_LIBRARY (CTL_STD_LAYER_NAMES|CTL_OMIT_NETS|CTL_OMIT_TSTAMPS|CTL_OMIT_PATH|CTL_OMIT_AT)
69 
72 #define CTL_FOR_BOARD (CTL_OMIT_INITIAL_COMMENTS)
73 
74 
75 class DIMENSION;
76 class EDGE_MODULE;
77 class DRAWSEGMENT;
78 class PCB_TARGET;
79 class D_PAD;
80 class TEXTE_MODULE;
81 class TRACK;
82 class ZONE_CONTAINER;
83 class TEXTE_PCB;
84 
85 
86 
93 class PCB_IO : public PLUGIN
94 {
95  friend class FP_CACHE;
96 
97 public:
98 
99  //-----<PLUGIN API>---------------------------------------------------------
100 
101  const wxString PluginName() const override
102  {
103  return wxT( "KiCad" );
104  }
105 
106  const wxString GetFileExtension() const override
107  {
108  // Would have used wildcards_and_files_ext.cpp's KiCadPcbFileExtension,
109  // but to be pure, a plugin should not assume that it will always be linked
110  // with the core of the pcbnew code. (Might someday be a DLL/DSO.) Besides,
111  // file extension policy should be controlled by the plugin.
112  return wxT( "kicad_pcb" );
113  }
114 
115  virtual void Save( const wxString& aFileName, BOARD* aBoard,
116  const PROPERTIES* aProperties = NULL ) override;
117 
118  BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
119  const PROPERTIES* aProperties = NULL ) override;
120 
121  void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
122  const PROPERTIES* aProperties = NULL ) override;
123 
124  const MODULE* GetEnumeratedFootprint( const wxString& aLibraryPath,
125  const wxString& aFootprintName,
126  const PROPERTIES* aProperties = NULL ) override;
127 
128  MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
129  const PROPERTIES* aProperties = NULL ) override;
130 
131  void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
132  const PROPERTIES* aProperties = NULL ) override;
133 
134  void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
135  const PROPERTIES* aProperties = NULL ) override;
136 
137  long long GetLibraryTimestamp( const wxString& aLibraryPath ) const override;
138 
139  void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL) override;
140 
141  bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL ) override;
142 
143  bool IsFootprintLibWritable( const wxString& aLibraryPath ) override;
144 
145  //-----</PLUGIN API>--------------------------------------------------------
146 
147  PCB_IO( int aControlFlags = CTL_FOR_BOARD );
148 
149  ~PCB_IO();
150 
159  void Format( BOARD_ITEM* aItem, int aNestLevel = 0 ) const;
160 
161  std::string GetStringOutput( bool doClear )
162  {
163  std::string ret = m_sf.GetString();
164  if( doClear )
165  m_sf.Clear();
166 
167  return ret;
168  }
169 
170  void SetOutputFormatter( OUTPUTFORMATTER* aFormatter ) { m_out = aFormatter; }
171 
172  BOARD_ITEM* Parse( const wxString& aClipboardSourceInput );
173 
174 protected:
175 
176  wxString m_error;
178 
179  const
182 
184  wxString m_filename;
185 
187 
190  int m_ctl;
193 
195  void validateCache( const wxString& aLibraryPath, bool checkModified = true );
196 
197  const MODULE* getFootprint( const wxString& aLibraryPath, const wxString& aFootprintName,
198  const PROPERTIES* aProperties, bool checkModified );
199 
200  void init( const PROPERTIES* aProperties );
201 
203  void formatSetup( BOARD* aBoard, int aNestLevel = 0 ) const;
204 
206  void formatGeneral( BOARD* aBoard, int aNestLevel = 0 ) const;
207 
209  void formatBoardLayers( BOARD* aBoard, int aNestLevel = 0 ) const;
210 
212  void formatNetInformation( BOARD* aBoard, int aNestLevel = 0 ) const;
213 
215  void formatHeader( BOARD* aBoard, int aNestLevel = 0 ) const;
216 
217 private:
218  void format( BOARD* aBoard, int aNestLevel = 0 ) const;
219 
220  void format( DIMENSION* aDimension, int aNestLevel = 0 ) const;
221 
222  void format( EDGE_MODULE* aModuleDrawing, int aNestLevel = 0 ) const;
223 
224  void format( DRAWSEGMENT* aSegment, int aNestLevel = 0 ) const;
225 
226  void format( PCB_TARGET* aTarget, int aNestLevel = 0 ) const;
227 
228  void format( MODULE* aModule, int aNestLevel = 0 ) const;
229 
230  void format( D_PAD* aPad, int aNestLevel = 0 ) const;
231 
232  void format( TEXTE_PCB* aText, int aNestLevel = 0 ) const;
233 
234  void format( TEXTE_MODULE* aText, int aNestLevel = 0 ) const;
235 
236  void format( TRACK* aTrack, int aNestLevel = 0 ) const;
237 
238  void format( ZONE_CONTAINER* aZone, int aNestLevel = 0 ) const;
239 
240  void formatLayer( const BOARD_ITEM* aItem ) const;
241 
242  void formatLayers( LSET aLayerMask, int aNestLevel = 0 ) const;
243 };
244 
245 #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.
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...
Class BOARD_ITEM is a base class for any item which can be embedded within the BOARD container class...
void formatGeneral(BOARD *aBoard, int aNestLevel=0) const
formats the General section of the file
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:65
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 formatLayer(const BOARD_ITEM *aItem) const
void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL) override
Return a list of footprint names contained within the library at aLibraryPath.
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)
void formatBoardLayers(BOARD *aBoard, int aNestLevel=0) const
formats the board layer information
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)
void formatNetInformation(BOARD *aBoard, int aNestLevel=0) const
formats the Nets and Netclasses
int m_loading_format_version
which SEXPR_BOARD_FILE_VERSION should be Load()ed?
const std::string & GetString()
Definition: richio.h:475
PCB_PARSER * m_parser
void formatSetup(BOARD *aBoard, int aNestLevel=0) const
formats the board setup information
void Format(BOARD_ITEM *aItem, int aNestLevel=0) const
Function Format outputs aItem to aFormatter in s-expression format.
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 formatHeader(BOARD *aBoard, int aNestLevel=0) const
writes everything that comes before the board_items, like settings and layers etc ...
#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:170
Class PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:266
void format(BOARD *aBoard, int aNestLevel=0) const
BOARD * m_board
which BOARD, no ownership here
const wxString PluginName() const override
Function PluginName returns a brief hard coded name for this PLUGIN.
void formatLayers(LSET aLayerMask, int aNestLevel=0) const
bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL) override
Function FootprintLibDelete deletes an existing footprint library and returns true, or if library does not exist returns false, or throws an exception if library exists but is read only or cannot be deleted for some other reason.
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