haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
kicad/include/kiway.h

474 lines
20 KiB
C++
Raw Blame History

/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2016-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, you may find one here:
* http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
* or you may search the http://www.gnu.org website for the version 2 license,
* or you may write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
*/
#ifndef KIWAY_H_
#define KIWAY_H_
/**
* The KIWAY and KIFACE classes are used to communicate between various process
* modules, all residing within a single process. The program modules are either
* top level like an *.exe or subsidiary like a *.dll. In much of the documentation
* the term DSO is used to refer to the *.dll portions, that is the term used on
* linux. But it should be taken to mean DLL on Windows.
*
* <p>These are a couple of reasons why this design was chosen:
*
* <ol>
*
* <li>By using DSOs within a single process, it is not necessary to use IPC.
* The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in
* a platform independent way. There can also be function calls from one DSO to
* another.</li>
*
* <li>The use of a number of separately linked DSOs closely resembles the original
* KiCad program design, consisting of Eeschema and Pcbnew. But it also allows
* separate compilation and linking of those two DSOs without a ton of inter-DSO
* dependencies and common data structures. Linking smaller, purpose specific DSOs
* is thought to be better for maintenance simplicity than a large single link
* image. </li>
*
* <li>By keeping the core functionality in DSOs rather than EXE tops, it becomes
* possible to re-use the DSOs under different program tops. For example, a DSO
* named _pcbnew.so can be used under a C++ top or under a python top. Only one
* CMake target must be defined to build either. Whether that is a separate build
* or not is not the important thing. Simply having a single CMake target has
* advantages. (Each builder person will have his/her own intentions relative to
* use of python or not.) Once a DSO is python capable, it can be driven by any
* number of python program tops, including demo-ing (automation) and testing
* separately.</li>
*
*
* </ol>
*
* All KiCad source code is UTF8 encoded by law, so make sure your editor is set
* as such! As such, it is OK to use UTF8 characters:
*
* ┏ ┗ ┓ ┛ ━ ┃
*
* <pre>
*
* ┏━━━process top━━━━━┓
* ┃ ┃ wxEvent channels
* ┏━━━━━━━━━━━━━━━━━━━-━[KIWAY project 1]━-━━━━━━━━━━━━━━━━━━━━━━┓
* ┃ ┃ ┃ ┃
* ┃ ┏━━━━━━━━━━━━━-━[KIWAY project 2]━-━━━━━━━━━━┓ ┃
* ┃ ┃ ┃ ┃ ┃ ┃
* ┃ ┃ ┏━-━[KIWAY project 3]━-━┓ ┃ ┃
* ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━┛ ┃ ┃ ┃
* ┃ ┃ ┃ ┃ ┃ ┃
* ┃ ┃ ┃ ┃ ┃ ┃
* ┏━━━━━━━━|━━━━━|━━━━━━━━━━━|━━━━━━━━━┓ ┏━━━━━━━━|━━━━━━━━|━━━━━━━━━━━|━━━━━┓
* ┃ KIFACE ┃ ┃ ┃ ┃ ┃ KIFACE ┃ ┃ ┃ ┃
* ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃
* ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃
* ┃┏━━━━━━━+━┓ ┏━+━━━━━━━┓ ┏━+━━━━━━━┓ ┃ ┃┏━━━━━━━+━┓ ┏━━━━+━━━━┓ ┏━━━━+━━━━┓┃
* ┃┃wxFrame ┃ ┃wxFrame ┃ ┃wxFrame ┃ ┃ ┃┃wxFrame ┃ ┃wxFrame ┃ ┃wxFrame ┃┃
* ┃┃project 1┃ ┃project 2┃ ┃project 3┃ ┃ ┃┃project 3┃ ┃project 2┃ ┃project 1┃┃
* ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┃ ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛┃
* ┃ ┃ ┃ ┃
* ┃ ┃ ┃ ┃
* ┗━━━━━━ eeschema DSO ━━━━━━━━━━━━━━━━┛ ┗━━━━━━ pcbnew DSO ━━━━━━━━━━━━━━━━━┛
*
* </pre>
*
*/
#include <wx/event.h>
#include <wx/dynlib.h>
#include <import_export.h>
#include <search_stack.h>
#include <project.h>
#include <frame_type.h>
#include <mail_type.h>
#include <ki_exception.h>
#define KIFACE_VERSION 1
#define KIFACE_GETTER KIFACE_1
// The KIFACE acquisition function is declared extern "C" so its name should not
// be mangled.
#define KIFACE_INSTANCE_NAME_AND_VERSION "KIFACE_1"
#ifndef SWIG
#if defined(__linux__) || defined(__FreeBSD__)
#define LIB_ENV_VAR wxT( "LD_LIBRARY_PATH" )
#elif defined(__WXMAC__)
#define LIB_ENV_VAR wxT( "DYLD_LIBRARY_PATH" )
#elif defined(_WIN32)
#define LIB_ENV_VAR wxT( "PATH" )
#else
#error Platform support missing
#endif
#endif // SWIG
class wxConfigBase;
class wxWindow;
class PGM_BASE;
class KIWAY;
class KIWAY_PLAYER;
class wxTopLevelWindow;
/**
* Implement a participant in the KIWAY alchemy.
*
* KIWAY is a minimalistic software bus for communications between various DLLs/DSOs
* (DSOs) within the same KiCad process. It makes it possible to call between DSOs
* without having to link them together. Most all calls are via virtual functions
* which means C++ vtables are used to hold function pointers and eliminate the need
* to link to specific object code libraries. There is one KIWAY in the launching
* portion of the process for each open KiCad project. Each project has its own KIWAY.
* Within a KIWAY is an actual PROJECT data structure. A KIWAY also facilitates
* communicating between DSOs on the topic of the project in question.
*/
struct KIFACE
{
// The order of functions establishes the vtable sequence, do not change the
// order of functions in this listing unless you recompile all clients of
// this interface.
virtual ~KIFACE() throw() {}
#define KFCTL_STANDALONE (1<<0) ///< Running as a standalone Top.
#define KFCTL_CPP_PROJECT_SUITE (1<<1) ///< Running under C++ project mgr, possibly with others.
/**
* Called just once shortly after the DSO is loaded.
* It is the second function called, immediately after the KIFACE_GETTER(). However
* before either of those, static C++ constructors are called. The DSO implementation
* should do process level initialization here, not project specific since there will
* be multiple projects open eventually.
*
* @param aProgram is the process block: #PGM_BASE*.
* @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above.
* @return true if DSO initialized OK, false if not. When returning false, the loader
* may optionally decide to terminate the process or not, but will not put out
* any UI because that is the duty of this function to say why it is returning
* false. Never return false without having reported to the UI why.
*/
virtual bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) = 0;
/**
* Called just once just before the DSO is to be unloaded.
*
* It is called before static C++ destructors are called. A default implementation
* is supplied.
*/
virtual void OnKifaceEnd() = 0;
/**
* Create a wxWindow for the current project.
*
* The caller must cast the return value into the known type.
*
* @param aParent may be NULL or is otherwise the parent to connect under. If NULL
* then caller may want to connect the returned wxWindow into some
* hierarchy after this function returns.
* @param aClassId identifies which wxFrame or wxDialog to retrieve, using a value
* known to the implementing KIFACE.
* @param aKIWAY tells the window which KIWAY (and PROJECT) it is a participant in.
* @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above.
* @return the window created and if not NULL, should be cast into the known type using
* and old school cast. dynamic_cast is problematic since it needs typeinfo probably
* not contained in the caller's link image.
*/
virtual wxWindow* CreateWindow( wxWindow* aParent, int aClassId,
KIWAY* aKIWAY, int aCtlBits = 0 ) = 0;
/**
* Saving a file under a different name is delegated to the various KIFACEs because
* the project doesn't know the internal format of the various files (which may have
* paths in them that need updating).
*/
virtual void SaveFileAs( const wxString& srcProjectBasePath,
const wxString& srcProjectName,
const wxString& newProjectBasePath,
const wxString& newProjectName,
const wxString& srcFilePath,
wxString& aErrors )
{
// If a KIFACE owns files then it needs to implement this....
}
/**
* Return pointer to the requested object.
*
* The safest way to use this is to retrieve a pointer to a static instance of an
* interface, similar to how the KIFACE interface is exported. But if you know
* what you are doing use it to retrieve anything you want. Segfaults are your fault.
*
* @param aDataId identifies which object you want the address of, and consists of
* choices known in advance by the implementing KIFACE.
* @return the requested object which must be cast into the known type.
*/
virtual void* IfaceOrAddress( int aDataId ) = 0;
};
/**
* A minimalistic software bus for communications between various DLLs/DSOs (DSOs) within
* the same KiCad process.
*
* It makes it possible to call between DSOs without having to link them together, and
* without having to link to the top process module which houses the KIWAY(s). More
* importantly it makes it possible to send custom wxEvents between DSOs and from the top
* process module down into the DSOs. The latter capability is thought useful for driving
* the lower DSOs from a python test rig or for demo (automation) purposes.
* <p>
* Most all calls are via virtual functions, which means C++ vtables are used to hold
* function pointers and eliminate the need to link to specific object code libraries,
* speeding development and encouraging clearly defined interface design. Unlike Microsoft
* COM, which is a multi-vendor design supporting DLL's built at various points in time,
* the KIWAY alchemy is single project, with all components being built at the same time.
* So one should expect solid compatibility between all KiCad components, as long at they
* are compiled at the same time.
* <p>
* There is one KIWAY in the launching portion of the process for each open KiCad project.
* Each project has its own KIWAY. Available to each KIWAY is an actual PROJECT data
* structure. If you have a KIWAY, you can get to the PROJECT using #KIWAY::Prj().
* <p>
* In summary, a KIWAY facilitates communicating between DSOs, where the topic of the
* communication is project specific. Here a "project" means a #BOARD and a #SCHEMATIC
* and a #NETLIST, (anything relating to production of a single #BOARD and added to class
* #PROJECT.)
*/
class KIWAY : public wxEvtHandler
{
friend struct PGM_SINGLE_TOP; // can use set_kiface()
public:
/// Known KIFACE implementations
enum FACE_T
{
FACE_SCH, ///< eeschema DSO
FACE_PCB, ///< pcbnew DSO
FACE_CVPCB,
FACE_GERBVIEW,
FACE_PL_EDITOR,
FACE_PCB_CALCULATOR,
FACE_BMP2CMP,
FACE_PYTHON,
KIWAY_FACE_COUNT
};
~KIWAY() throw () {}
/**
* A simple mapping function which returns the FACE_T which is known to implement
* @a aFrameType.
*
* @return a valid value #KIWAY::FACE_T or FACE_T(-1) if given a bad @a aFrameType.
*/
static FACE_T KifaceType( FRAME_T aFrameType );
// If you change the vtable, recompile all of KiCad.
/**
* Return the KIFACE* given a FACE_T.
*
* If it is not already loaded, the KIFACE is loaded and initialized with a call to
* KIFACE::OnKifaceStart().
*/
virtual KIFACE* KiFACE( FACE_T aFaceId, bool doLoad = true );
/**
* Return the #KIWAY_PLAYER* given a FRAME_T.
*
* If it is not already created, the required KIFACE is found and loaded and initialized
* if necessary, then the KIWAY_PLAYER window is created but not shown. Caller must
* Show() it. If it is already created, then the existing KIWAY_PLAYER* pointer is
* returned.
*
* @param aFrameType is from enum #FRAME_T.
* @param doCreate when true asks that the player be created if it is not already created,
* false means do not create and maybe return NULL.
* @param aParent is a parent for modal #KIWAY_PLAYER frames, otherwise NULL used only
* when doCreate = true and by KIWAY_PLAYER frames created in modal form
*
* @return a valid opened #KIWAY_PLAYER or NULL if there is something wrong or doCreate
* was false and the player has yet to be created.
*
* @throw IO_ERROR if the *.kiface file could not be found, filled with text saying what.
*/
virtual KIWAY_PLAYER* Player( FRAME_T aFrameType, bool doCreate = true,
wxTopLevelWindow* aParent = nullptr );
/**
* Call the KIWAY_PLAYER::Close( bool force ) function on the window and if not vetoed,
* returns true, else false.
*
* If window actually closes, then this KIWAY marks it as not opened internally.
*
* @return true if the window is closed and not vetoed, else false.
*/
virtual bool PlayerClose( FRAME_T aFrameType, bool doForce );
/**
* Call the KIWAY_PLAYER::Close( bool force ) function on all the windows and if none
* are vetoed, returns true, else false.
*
* If any window actually closes, then* this KIWAY marks it as not opened internally.
*
* @return true indicates that all windows closed because none were vetoed, false means
* at least one cast a veto. Any that cast a veto are still open.
*/
virtual bool PlayersClose( bool doForce );
/**
* Send @a aPayload to @a aDestination from @a aSource.
*
* The recipient receives this in its #KIWAY_PLAYER::KiwayMailIn() function and can
* efficiently switch() based on @a aCommand in there.
*/
virtual void ExpressMail( FRAME_T aDestination, MAIL_T aCommand, std::string& aPayload,
wxWindow* aSource = nullptr );
/**
* Return the #PROJECT associated with this KIWAY.
*
* This is here as an accessor, so that there is freedom to put the actual PROJECT storage
* in a place decided by the implementation, and not known to the caller.
*/
virtual PROJECT& Prj() const;
/**
* Change the language and then calls ShowChangedLanguage() on all #KIWAY_PLAYERs.
*/
virtual void SetLanguage( int aLanguage );
/**
* Call CommonSettingsChanged() on all KIWAY_PLAYERs.
*
* Use after changing suite-wide options such as panning, autosave interval, etc.
*/
virtual void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged );
/**
* Calls ProjectChanged() on all KIWAY_PLAYERs.
* Used after changing the project to ensure all players are updated correctly.
*/
virtual void ProjectChanged();
KIWAY( PGM_BASE* aProgram, int aCtlBits, wxFrame* aTop = nullptr );
/**
* Tell this KIWAY about the top most frame in the program and optionally allows it to
* play the role of one of the KIWAY_PLAYERs if launched from single_top.cpp.
*
* @param aTop is the top most wxFrame in the entire program.
*/
void SetTop( wxFrame* aTop );
wxFrame* GetTop() { return m_top; }
void OnKiCadExit();
void OnKiwayEnd();
bool ProcessEvent( wxEvent& aEvent ) override;
private:
/// Get the [path &] name of the DSO holding the requested FACE_T.
const wxString dso_search_path( FACE_T aFaceId );
#if 0
/// hooked into m_top in SetTop(), marks child frame as closed.
void player_destroy_handler( wxWindowDestroyEvent& event );
#endif
bool set_kiface( FACE_T aFaceType, KIFACE* aKiface )
{
if( (unsigned) aFaceType < (unsigned) KIWAY_FACE_COUNT )
{
m_kiface[aFaceType] = aKiface;
return true;
}
return false;
}
/**
* @return the reference of the KIWAY_PLAYER having the type @a aFrameType if exists,
* or NULL if this KIWAY_PLAYER was not yet created, or was closed
*/
KIWAY_PLAYER* GetPlayerFrame( FRAME_T aFrameType );
static KIFACE* m_kiface[KIWAY_FACE_COUNT];
static int m_kiface_version[KIWAY_FACE_COUNT];
PGM_BASE* m_program;
int m_ctl;
wxFrame* m_top; // Usually m_top is the Project manager
// a string array ( size KIWAY_PLAYER_COUNT ) to Store the frame name
// of PLAYER frames which were run.
// A non empty name means only a PLAYER was run at least one time.
// It can be closed. Call :
// wxWindow::FindWindowByName( m_playerFrameName[aFrameType] )
// to know if still exists (or GetPlayerFrame( FRAME_T aFrameType )
wxArrayString m_playerFrameName;
};
#ifndef SWIG
// provided by single_top.cpp and kicad.cpp;
extern KIWAY Kiway;
// whereas python launchers: single_top.py and project manager instantiate as a python object
#endif
/**
* Point to the one and only KIFACE export.
*
* The export's address is looked up via symbolic string and should be extern "C" to avoid name
* mangling. This function will only be called one time. The DSO itself however may be asked
* to support multiple Top windows, i.e. multiple projects within its lifetime.
*
* @param aKIFACEversion is where to put the API version implemented by the KIFACE.
* @param aKIWAYversion tells the KIFACE what KIWAY version will be available.
* @param aProgram is a pointer to the PGM_BASE for this process.
* @return unconditionally, cannot fail.
*/
typedef KIFACE* KIFACE_GETTER_FUNC( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
#ifndef SWIG
/// No name mangling. Each KIFACE (DSO/DLL) will implement this once.
extern "C" {
#if defined(BUILD_KIWAY_DLL)
MY_API( KIFACE* ) KIFACE_GETTER( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
#else
KIFACE* KIFACE_GETTER( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
#endif
}
#endif // SWIG
#endif // KIWAY_H_
Reference in New Issue View Git Blame Copy Permalink