KiCad PCB EDA Suite
kiway.h File Reference
#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>

Go to the source code of this file.

Classes

struct  KIFACE
 Implement a participant in the KIWAY alchemy. More...
 
class  KIWAY
 A minimalistic software bus for communications between various DLLs/DSOs (DSOs) within the same KiCad process. More...
 

Macros

#define KIFACE_VERSION   1
 The KIWAY and KIFACE classes are used to communicate between various process modules, all residing within a single process. More...
 
#define KIFACE_GETTER   KIFACE_1
 
#define KIFACE_INSTANCE_NAME_AND_VERSION   "KIFACE_1"
 
#define KFCTL_STANDALONE   (1<<0)
 Running as a standalone Top. More...
 
#define KFCTL_CPP_PROJECT_SUITE   (1<<1)
 Running under C++ project mgr, possibly with others. More...
 
#define KFCTL_PY_PROJECT_SUITE   (1<<2)
 Running under python project mgr, possibly with others. More...
 

Typedefs

typedef KIFACEKIFACE_GETTER_FUNC(int *aKIFACEversion, int aKIWAYversion, PGM_BASE *aProgram)
 Point to the one and only KIFACE export. More...
 

Functions

KIFACEKIFACE_GETTER (int *aKIFACEversion, int aKIWAYversion, PGM_BASE *aProgram)
 No name mangling. Each KIFACE (DSO/DLL) will implement this once. More...
 

Variables

KIWAY Kiway
 

Macro Definition Documentation

◆ KFCTL_CPP_PROJECT_SUITE

#define KFCTL_CPP_PROJECT_SUITE   (1<<1)

Running under C++ project mgr, possibly with others.

Definition at line 156 of file kiway.h.

◆ KFCTL_PY_PROJECT_SUITE

#define KFCTL_PY_PROJECT_SUITE   (1<<2)

Running under python project mgr, possibly with others.

Definition at line 157 of file kiway.h.

◆ KFCTL_STANDALONE

#define KFCTL_STANDALONE   (1<<0)

Running as a standalone Top.

Definition at line 155 of file kiway.h.

◆ KIFACE_GETTER

#define KIFACE_GETTER   KIFACE_1

Definition at line 109 of file kiway.h.

◆ KIFACE_INSTANCE_NAME_AND_VERSION

#define KIFACE_INSTANCE_NAME_AND_VERSION   "KIFACE_1"

Definition at line 113 of file kiway.h.

◆ KIFACE_VERSION

#define KIFACE_VERSION   1

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.

These are a couple of reasons why this design was chosen:

  1. 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.

  2. 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.

  3. 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.

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:

┏ ┗ ┓ ┛ ━ ┃

                             ┏━━━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 ━━━━━━━━━━━━━━━━━┛
 

Definition at line 108 of file kiway.h.

Typedef Documentation

◆ KIFACE_GETTER_FUNC

typedef KIFACE* KIFACE_GETTER_FUNC(int *aKIFACEversion, int aKIWAYversion, PGM_BASE *aProgram)

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.

Parameters
aKIFACEversionis where to put the API version implemented by the KIFACE.
aKIWAYversiontells the KIFACE what KIWAY version will be available.
aProgramis a pointer to the PGM_BASE for this process.
Returns
unconditionally, cannot fail.

Definition at line 456 of file kiway.h.

Function Documentation

◆ KIFACE_GETTER()

KIFACE* KIFACE_GETTER ( int *  aKIFACEversion,
int  aKIWAYversion,
PGM_BASE aProgram 
)

No name mangling. Each KIFACE (DSO/DLL) will implement this once.

Definition at line 84 of file bitmap2cmp_main.cpp.

85 {
87  return &kiface;
88 }
Container for data for KiCad programs.
Definition: pgm_base.h:131
static PGM_BASE * process
BMP2CMP::IFACE KIFACE_I kiface("BMP2CMP", KIWAY::FACE_BMP2CMP)
int PGM_BASE * aProgram
Definition: cvpcb.cpp:97

References aProgram, BMP2CMP::kiface(), and process.

Variable Documentation

◆ Kiway