KiCad PCB EDA Suite
kiway.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) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
5  * Copyright (C) 2016-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 KIWAY_H_
26 #define KIWAY_H_
27 
98 #include <atomic>
99 #include <wx/defs.h>
100 #include <wx/event.h>
101 #include <import_export.h>
102 #include <search_stack.h>
103 #include <project.h>
104 #include <frame_type.h>
105 #include <mail_type.h>
106 #include <ki_exception.h>
107 
108 
109 #define KIFACE_VERSION 1
110 #define KIFACE_GETTER KIFACE_1
111 
112 // The KIFACE acquisition function is declared extern "C" so its name should not
113 // be mangled.
114 #define KIFACE_INSTANCE_NAME_AND_VERSION "KIFACE_1"
115 
116 #ifndef SWIG
117 #if defined(__linux__) || defined(__FreeBSD__)
118  #define LIB_ENV_VAR wxT( "LD_LIBRARY_PATH" )
119 #elif defined(__WXMAC__)
120  #define LIB_ENV_VAR wxT( "DYLD_LIBRARY_PATH" )
121 #elif defined(_WIN32)
122  #define LIB_ENV_VAR wxT( "PATH" )
123 #else
124  #error Platform support missing
125 #endif
126 #endif // SWIG
127 
128 class wxConfigBase;
129 class wxWindow;
130 class PGM_BASE;
131 class KIWAY;
132 class KIWAY_PLAYER;
133 class wxTopLevelWindow;
134 
135 
148 struct KIFACE
149 {
150  // The order of functions establishes the vtable sequence, do not change the
151  // order of functions in this listing unless you recompile all clients of
152  // this interface.
153 
154  virtual ~KIFACE() throw() {}
155 
156 #define KFCTL_STANDALONE (1<<0)
157 #define KFCTL_CPP_PROJECT_SUITE (1<<1)
158 
159 
174  virtual bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) = 0;
175 
182  virtual void OnKifaceEnd() = 0;
183 
200  virtual wxWindow* CreateWindow( wxWindow* aParent, int aClassId,
201  KIWAY* aKIWAY, int aCtlBits = 0 ) = 0;
202 
208  virtual void SaveFileAs( const wxString& srcProjectBasePath,
209  const wxString& srcProjectName,
210  const wxString& newProjectBasePath,
211  const wxString& newProjectName,
212  const wxString& srcFilePath,
213  wxString& aErrors )
214  {
215  // If a KIFACE owns files then it needs to implement this....
216  }
217 
229  virtual void* IfaceOrAddress( int aDataId ) = 0;
230 };
231 
232 
260 class KIWAY : public wxEvtHandler
261 {
262  friend struct PGM_SINGLE_TOP; // can use set_kiface()
263 
264 public:
266  enum FACE_T
267  {
276 
278  };
279 
280  ~KIWAY() throw () {}
281 
288  static FACE_T KifaceType( FRAME_T aFrameType );
289 
290  // If you change the vtable, recompile all of KiCad.
291 
298  virtual KIFACE* KiFACE( FACE_T aFaceId, bool doLoad = true );
299 
319  virtual KIWAY_PLAYER* Player( FRAME_T aFrameType, bool doCreate = true,
320  wxTopLevelWindow* aParent = nullptr );
321 
330  virtual bool PlayerClose( FRAME_T aFrameType, bool doForce );
331 
341  virtual bool PlayersClose( bool doForce );
342 
349  virtual void ExpressMail( FRAME_T aDestination, MAIL_T aCommand, std::string& aPayload,
350  wxWindow* aSource = nullptr );
351 
358  virtual PROJECT& Prj() const;
359 
363  virtual void SetLanguage( int aLanguage );
364 
370  virtual void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged );
371 
376  virtual void ProjectChanged();
377 
378  KIWAY( PGM_BASE* aProgram, int aCtlBits, wxFrame* aTop = nullptr );
379 
386  void SetTop( wxFrame* aTop );
387  wxFrame* GetTop() { return m_top; }
388 
389  void OnKiCadExit();
390 
391  void OnKiwayEnd();
392 
393  bool ProcessEvent( wxEvent& aEvent ) override;
394 
395 private:
397  const wxString dso_search_path( FACE_T aFaceId );
398 
399 #if 0
400  void player_destroy_handler( wxWindowDestroyEvent& event );
402 #endif
403 
404  bool set_kiface( FACE_T aFaceType, KIFACE* aKiface )
405  {
406  if( (unsigned) aFaceType < (unsigned) KIWAY_FACE_COUNT )
407  {
408  m_kiface[aFaceType] = aKiface;
409  return true;
410  }
411 
412  return false;
413  }
414 
419  KIWAY_PLAYER* GetPlayerFrame( FRAME_T aFrameType );
420 
423 
425  int m_ctl;
426 
427  wxFrame* m_top; // Usually m_top is the Project manager
428 
429  // An array to store the window ID of PLAYER frames which were run.
430  // A non empty name means only a PLAYER was run at least one time.
431  // Empty entries are represented by wxID_NONE.
432  // They can be closed, and the stored window ID may be invalid.
433  // Call: wxWindow::FindWindowById( m_playerFrameId[aFrameType] )
434  // to know if still exists (or GetPlayerFrame( FRAME_T aFrameType )
435  std::atomic<wxWindowID> m_playerFrameId[KIWAY_PLAYER_COUNT];
436 };
437 
438 
439 #ifndef SWIG
440 // provided by single_top.cpp and kicad.cpp;
441 extern KIWAY Kiway;
442 // whereas python launchers: single_top.py and project manager instantiate as a python object
443 #endif
444 
445 
458 typedef KIFACE* KIFACE_GETTER_FUNC( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
459 
460 
461 #ifndef SWIG
462 
464 extern "C" {
465 #if defined(BUILD_KIWAY_DLL)
466  MY_API( KIFACE* ) KIFACE_GETTER( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
467 #else
468  KIFACE* KIFACE_GETTER( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
469 #endif
470 }
471 
472 #endif // SWIG
473 
474 #endif // KIWAY_H_
virtual wxWindow * CreateWindow(wxWindow *aParent, int aClassId, KIWAY *aKIWAY, int aCtlBits=0)=0
Create a wxWindow for the current project.
virtual bool PlayersClose(bool doForce)
Call the KIWAY_PLAYER::Close( bool force ) function on all the windows and if none are vetoed,...
Definition: kiway.cpp:464
A wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of a KiCad project.
Definition: kiway_player.h:64
void OnKiCadExit()
Definition: kiway.cpp:626
Struct PGM_SINGLE_TOP implements PGM_BASE with its own OnPgmInit() and OnPgmExit().
Definition: single_top.cpp:66
std::atomic< wxWindowID > m_playerFrameId[KIWAY_PLAYER_COUNT]
Definition: kiway.h:435
Container for project specific data.
Definition: project.h:62
static FACE_T KifaceType(FRAME_T aFrameType)
A simple mapping function which returns the FACE_T which is known to implement aFrameType.
Definition: kiway.cpp:321
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:365
virtual ~KIFACE()
Definition: kiway.h:154
Container for data for KiCad programs.
Definition: pgm_base.h:93
FRAME_T
The set of EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident.
Definition: frame_type.h:32
virtual PROJECT & Prj() const
Return the PROJECT associated with this KIWAY.
Definition: kiway.cpp:190
PGM_BASE * m_program
Definition: kiway.h:424
virtual KIWAY_PLAYER * Player(FRAME_T aFrameType, bool doCreate=true, wxTopLevelWindow *aParent=nullptr)
Return the KIWAY_PLAYER* given a FRAME_T.
Definition: kiway.cpp:383
virtual void ExpressMail(FRAME_T aDestination, MAIL_T aCommand, std::string &aPayload, wxWindow *aSource=nullptr)
Send aPayload to aDestination from aSource.
Definition: kiway.cpp:477
virtual void SetLanguage(int aLanguage)
Change the language and then calls ShowChangedLanguage() on all #KIWAY_PLAYERs.
Definition: kiway.cpp:486
~KIWAY()
Definition: kiway.h:280
void OnKiwayEnd()
Definition: kiway.cpp:641
wxFrame * GetTop()
Definition: kiway.h:387
bool set_kiface(FACE_T aFaceType, KIFACE *aKiface)
Definition: kiway.h:404
MAIL_T
The set of mail types sendable via KIWAY::ExpressMail() and supplied as the aCommand parameter to tha...
Definition: mail_type.h:37
#define MY_API(rettype)
Definition: import_export.h:55
virtual bool PlayerClose(FRAME_T aFrameType, bool doForce)
Call the KIWAY_PLAYER::Close( bool force ) function on the window and if not vetoed,...
Definition: kiway.cpp:439
bool ProcessEvent(wxEvent &aEvent) override
Definition: kiway.cpp:600
KIFACE * KIFACE_GETTER_FUNC(int *aKIFACEversion, int aKIWAYversion, PGM_BASE *aProgram)
Point to the one and only KIFACE export.
Definition: kiway.h:458
virtual void ProjectChanged()
Calls ProjectChanged() on all KIWAY_PLAYERs.
Definition: kiway.cpp:577
int m_ctl
Definition: kiway.h:425
A minimalistic software bus for communications between various DLLs/DSOs (DSOs) within the same KiCad...
Definition: kiway.h:260
pcbnew DSO
Definition: kiway.h:269
#define KIFACE_GETTER
Definition: kiway.h:110
const wxString dso_search_path(FACE_T aFaceId)
Get the [path &] name of the DSO holding the requested FACE_T.
Definition: kiway.cpp:104
virtual KIFACE * KiFACE(FACE_T aFaceId, bool doLoad=true)
Return the KIFACE* given a FACE_T.
Definition: kiway.cpp:196
void SetTop(wxFrame *aTop)
Tell this KIWAY about the top most frame in the program and optionally allows it to play the role of ...
Definition: kiway.cpp:82
virtual void SaveFileAs(const wxString &srcProjectBasePath, const wxString &srcProjectName, const wxString &newProjectBasePath, const wxString &newProjectName, const wxString &srcFilePath, wxString &aErrors)
Saving a file under a different name is delegated to the various KIFACEs because the project doesn't ...
Definition: kiway.h:208
FACE_T
Known KIFACE implementations.
Definition: kiway.h:266
eeschema DSO
Definition: kiway.h:268
int aKIWAYversion
Definition: cvpcb.cpp:109
virtual void * IfaceOrAddress(int aDataId)=0
Return pointer to the requested object.
Implement a participant in the KIWAY alchemy.
Definition: kiway.h:148
KIWAY(PGM_BASE *aProgram, int aCtlBits, wxFrame *aTop=nullptr)
Definition: kiway.cpp:51
static int m_kiface_version[KIWAY_FACE_COUNT]
Definition: kiway.h:422
virtual void CommonSettingsChanged(bool aEnvVarsChanged, bool aTextVarsChanged)
Call CommonSettingsChanged() on all KIWAY_PLAYERs.
Definition: kiway.cpp:554
wxFrame * m_top
Definition: kiway.h:427
virtual void OnKifaceEnd()=0
Called just once just before the DSO is to be unloaded.
int PGM_BASE * aProgram
Definition: cvpcb.cpp:110
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:421
KIWAY Kiway
virtual bool OnKifaceStart(PGM_BASE *aProgram, int aCtlBits)=0
Called just once shortly after the DSO is loaded.