KiCad PCB EDA Suite
KIWAY Class Reference

Class KIWAY is a minimalistic software bus for communications between various DLLs/DSOs (DSOs) within the same KiCad process. More...

#include <kiway.h>

Inheritance diagram for KIWAY:

Public Types

enum  FACE_T {
  FACE_SCH, FACE_PCB, FACE_CVPCB, FACE_GERBVIEW,
  FACE_PL_EDITOR, FACE_PCB_CALCULATOR, FACE_BMP2CMP, KIWAY_FACE_COUNT
}
 Known KIFACE implementations. More...
 

Public Member Functions

 ~KIWAY () throw ()
 
VTBL_ENTRY KIFACEKiFACE (FACE_T aFaceId, bool doLoad=true)
 Function KiFACE returns the KIFACE* given a FACE_T. More...
 
VTBL_ENTRY KIWAY_PLAYERPlayer (FRAME_T aFrameType, bool doCreate=true, wxTopLevelWindow *aParent=NULL)
 Function Player returns the KIWAY_PLAYER* given a FRAME_T. More...
 
VTBL_ENTRY bool PlayerClose (FRAME_T aFrameType, bool doForce)
 Function PlayerClose calls the KIWAY_PLAYER::Close( bool force ) function on the window and if not vetoed, returns true, else false. More...
 
VTBL_ENTRY bool PlayersClose (bool doForce)
 Function PlayersClose calls the KIWAY_PLAYER::Close( bool force ) function on all the windows and if none are vetoed, returns true, else false. More...
 
VTBL_ENTRY void ExpressMail (FRAME_T aDestination, MAIL_T aCommand, std::string &aPayload, wxWindow *aSource=NULL)
 Function ExpressMail send aPayload to aDestination from aSource. More...
 
VTBL_ENTRY PROJECTPrj () const
 Function Prj returns the PROJECT associated with this KIWAY. More...
 
VTBL_ENTRY void SetLanguage (int aLanguage)
 Function SetLanguage changes the language and then calls ShowChangedLanguage() on all KIWAY_PLAYERs. More...
 
VTBL_ENTRY void CommonSettingsChanged ()
 Function CommonSettingsChanged Calls CommonSettingsChanged() on all KIWAY_PLAYERs. More...
 
 KIWAY (PGM_BASE *aProgram, int aCtlBits, wxFrame *aTop=NULL)
 
void SetTop (wxFrame *aTop)
 Function SetTop tells 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. More...
 
void OnKiwayEnd ()
 
bool ProcessEvent (wxEvent &aEvent) override
 

Static Public Member Functions

static FACE_T KifaceType (FRAME_T aFrameType)
 Function KifaceType is a simple mapping function which returns the FACE_T which is known to implement aFrameType. More...
 

Private Member Functions

const wxString dso_search_path (FACE_T aFaceId)
 Get the [path &] name of the DSO holding the requested FACE_T. More...
 
bool set_kiface (FACE_T aFaceType, KIFACE *aKiface)
 
KIWAY_PLAYERGetPlayerFrame (FRAME_T aFrameType)
 

Private Attributes

PGM_BASEm_program
 
int m_ctl
 
wxFrame * m_top
 
wxArrayString m_playerFrameName
 
PROJECT m_project
 

Static Private Attributes

static KIFACEm_kiface [KIWAY_FACE_COUNT]
 
static int m_kiface_version [KIWAY_FACE_COUNT]
 

Friends

struct PGM_SINGLE_TOP
 

Detailed Description

Class 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, 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.

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.

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().

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

Definition at line 258 of file kiway.h.

Member Enumeration Documentation

◆ FACE_T

Known KIFACE implementations.

Enumerator
FACE_SCH 

eeschema DSO

FACE_PCB 

pcbnew DSO

FACE_CVPCB 
FACE_GERBVIEW 
FACE_PL_EDITOR 
FACE_PCB_CALCULATOR 
FACE_BMP2CMP 
KIWAY_FACE_COUNT 

Definition at line 264 of file kiway.h.

Constructor & Destructor Documentation

◆ ~KIWAY()

KIWAY::~KIWAY ( )
throw (
)
inline

Definition at line 277 of file kiway.h.

277 {}

◆ KIWAY()

KIWAY::KIWAY ( PGM_BASE aProgram,
int  aCtlBits,
wxFrame *  aTop = NULL 
)

Definition at line 45 of file kiway.cpp.

45  :
46  m_program( aProgram ), m_ctl( aCtlBits ), m_top( 0 )
47 {
48  SetTop( aTop ); // hook player_destroy_handler() into aTop.
49 
50 
51  // Prepare the room to store the frame names, once they will be created
52  // with FRAME_T type as index in this table.
53  // (note this is a list of frame names, but a non empty entry
54  // does not mean the frame still exists. It means only the frame was created
55  // at least once. It can be destroyed after. These entries are not cleared.
56  // the purpose is just to allow a call to wxWindow::FindWindowByName(), from
57  // a FRAME_T frame type
58  m_playerFrameName.Add( wxEmptyString, KIWAY_PLAYER_COUNT );
59 }
PGM_BASE * m_program
Definition: kiway.h:415
int m_ctl
Definition: kiway.h:416
void SetTop(wxFrame *aTop)
Function SetTop tells this KIWAY about the top most frame in the program and optionally allows it to ...
Definition: kiway.cpp:77
wxArrayString m_playerFrameName
Definition: kiway.h:426
wxFrame * m_top
Definition: kiway.h:418
int PGM_BASE * aProgram
Definition: pcbnew.cpp:210

References KIWAY_PLAYER_COUNT, m_playerFrameName, and SetTop().

Member Function Documentation

◆ CommonSettingsChanged()

void KIWAY::CommonSettingsChanged ( )

Function CommonSettingsChanged Calls CommonSettingsChanged() on all KIWAY_PLAYERs.

Used after changing suite-wide options such as panning, autosave interval, etc.

Definition at line 451 of file kiway.cpp.

452 {
453 #if 1
455  {
456  // A dynamic_cast could be better, but creates link issues
457  // (some basic_frame functions not found) on some platforms,
458  // so a static_cast is used.
459  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
460 
461  if( top )
462  top->CommonSettingsChanged();
463  }
464 #endif
465 
466  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
467  {
468  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
469 
470  if( frame )
471  frame->CommonSettingsChanged();
472  }
473 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:160
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:127
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:312
FRAME_T
Enum FRAME_T is the set of EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident.
Definition: frame_type.h:34
int m_ctl
Definition: kiway.h:416
The base frame for deriving all KiCad main window classes.
size_t i
Definition: json11.cpp:597
virtual void CommonSettingsChanged()
Notification event that some of the common (suite-wide) settings have changed.
wxFrame * m_top
Definition: kiway.h:418

References EDA_BASE_FRAME::CommonSettingsChanged(), GetPlayerFrame(), i, KFCTL_CPP_PROJECT_SUITE, KIWAY_PLAYER_COUNT, m_ctl, and m_top.

Referenced by EDA_BASE_FRAME::ShowPreferences().

◆ dso_search_path()

const wxString KIWAY::dso_search_path ( FACE_T  aFaceId)
private

Get the [path &] name of the DSO holding the requested FACE_T.

Definition at line 95 of file kiway.cpp.

96 {
97  const char* name;
98 
99  switch( aFaceId )
100  {
101  case FACE_SCH: name = KIFACE_PREFIX "eeschema"; break;
102  case FACE_PCB: name = KIFACE_PREFIX "pcbnew"; break;
103  case FACE_CVPCB: name = KIFACE_PREFIX "cvpcb"; break;
104  case FACE_GERBVIEW: name = KIFACE_PREFIX "gerbview"; break;
105  case FACE_PL_EDITOR: name = KIFACE_PREFIX "pl_editor"; break;
106  case FACE_PCB_CALCULATOR: name = KIFACE_PREFIX "pcb_calculator"; break;
107  case FACE_BMP2CMP: name = KIFACE_PREFIX "bitmap2component"; break;
108 
109  default:
110  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFaceId" ) );
111  return wxEmptyString;
112  }
113 
114 #ifndef __WXMAC__
115  wxString path;
116 
118  {
119  // The 2 *.cpp program launchers: single_top.cpp and kicad.cpp expect
120  // the *.kiface's to reside in same diretory as their binaries do.
121  // Not so for python launcher, identified by KFCTL_PY_PROJECT_SUITE
122  path = wxStandardPaths::Get().GetExecutablePath();
123  }
124 
125  wxFileName fn = path;
126 #else
127  // we have the dso's in main OSX bundle kicad.app/Contents/PlugIns
128  wxFileName fn = Pgm().GetExecutablePath();
129  fn.AppendDir( wxT( "Contents" ) );
130  fn.AppendDir( wxT( "PlugIns" ) );
131 #endif
132 
133  fn.SetName( name );
134 
135 #ifdef DEBUG
136  // To speed up development, it's sometimes nice to run kicad from inside
137  // the build path. In that case, each program will be in a subdirectory.
138  // To find the DSOs, we need to go up one directory and then enter a subdirectory
139  // with the same name as the DSO (without the prefix).
140 
141  if( wxGetEnv( wxT( "KICAD_RUN_FROM_BUILD_DIR" ), nullptr ) )
142  {
143 #ifdef __WXMAC__
144  fn = wxStandardPaths::Get().GetExecutablePath();
145  fn.RemoveLastDir();
146  fn.AppendDir( wxT( "PlugIns" ) );
147  fn.SetName( name );
148 #else
149  fn.RemoveLastDir();
150  fn.AppendDir( name + 1 );
151 #endif
152  }
153 #endif
154 
155  // Here a "suffix" == an extension with a preceding '.',
156  // so skip the preceding '.' to get an extension
157  fn.SetExt( KIFACE_SUFFIX + 1 ); // + 1 => &KIFACE_SUFFIX[1]
158 
159  return fn.GetFullPath();
160 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:160
PGM_BASE & Pgm()
The global Program "get" accessor.
Definition: kicad.cpp:66
int m_ctl
Definition: kiway.h:416
pcbnew DSO
Definition: kiway.h:267
eeschema DSO
Definition: kiway.h:266
const char * name
Definition: DXF_plotter.cpp:61
VTBL_ENTRY const wxString & GetExecutablePath() const
Definition: pgm_base.h:218
#define KFCTL_STANDALONE
Am running as a standalone Top.
Definition: kiway.h:159

References FACE_BMP2CMP, FACE_CVPCB, FACE_GERBVIEW, FACE_PCB, FACE_PCB_CALCULATOR, FACE_PL_EDITOR, FACE_SCH, PGM_BASE::GetExecutablePath(), KFCTL_CPP_PROJECT_SUITE, KFCTL_STANDALONE, m_ctl, name, and Pgm().

Referenced by KiFACE().

◆ ExpressMail()

void KIWAY::ExpressMail ( FRAME_T  aDestination,
MAIL_T  aCommand,
std::string &  aPayload,
wxWindow *  aSource = NULL 
)

Function ExpressMail send aPayload to aDestination from aSource.

Recipient receives this in its KIWAY_PLAYER::KiwayMailIn() function and can efficiently switch() based on aCommand in there.

Definition at line 407 of file kiway.cpp.

408 {
409  KIWAY_EXPRESS mail( aDestination, aCommand, aPayload, aSource );
410 
411  ProcessEvent( mail );
412 }
Class KIWAY_EXPRESS carries a payload from one KIWAY_PLAYER to another within a PROJECT.
Definition: kiway_express.h:39
bool ProcessEvent(wxEvent &aEvent) override
Definition: kiway.cpp:476

References ProcessEvent().

Referenced by TREEPROJECT_ITEM::Activate(), PCB_EDIT_FRAME::FetchNetlistFromSchematic(), KICAD_MANAGER_FRAME::OnImportEagleFiles(), SCH_EDIT_FRAME::OnUpdatePCB(), LIB_EDIT_FRAME::refreshSchematic(), CVPCB_MAINFRAME::SaveFootprintAssociation(), SCH_EDIT_FRAME::SendCrossProbeClearHighlight(), SCH_EDIT_FRAME::SendCrossProbeNetName(), PCB_EDIT_FRAME::SendCrossProbeNetName(), CVPCB_MAINFRAME::SendMessageToEESCHEMA(), PCB_EDIT_FRAME::SendMessageToEESCHEMA(), SCH_EDIT_FRAME::SendMessageToPCBNEW(), and SCH_EDIT_FRAME::sendNetlistToCvpcb().

◆ GetPlayerFrame()

KIWAY_PLAYER * KIWAY::GetPlayerFrame ( FRAME_T  aFrameType)
private
Returns
the reference of the KIWAY_PLAYER having the type aFrameType if exists, or NULL if this KIWAY_PLAYER was not yet created, or was closed

Definition at line 312 of file kiway.cpp.

313 {
314  if( m_playerFrameName[aFrameType].IsEmpty() )
315  return NULL;
316 
317  return static_cast<KIWAY_PLAYER*>( wxWindow::FindWindowByName( m_playerFrameName[aFrameType] ) );
318 }
wxArrayString m_playerFrameName
Definition: kiway.h:426

References m_playerFrameName.

Referenced by CommonSettingsChanged(), Player(), PlayerClose(), and SetLanguage().

◆ KiFACE()

KIFACE * KIWAY::KiFACE ( FACE_T  aFaceId,
bool  doLoad = true 
)

Function KiFACE returns the KIFACE* given a FACE_T.

If it is not already loaded, the KIFACE is loaded and initialized with a call to KIFACE::OnKifaceStart()

Definition at line 169 of file kiway.cpp.

170 {
171  // Since this will be called from python, cannot assume that code will
172  // not pass a bad aFaceId.
173  if( (unsigned) aFaceId >= arrayDim( m_kiface ) )
174  {
175  // @todo : throw an exception here for python's benefit, at least that
176  // way it gets some explanatory text.
177 
178  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFaceId" ) );
179  return NULL;
180  }
181 
182  // return the previously loaded KIFACE, if it was.
183  if( m_kiface[aFaceId] )
184  return m_kiface[aFaceId];
185 
186  wxString msg;
187 
188  // DSO with KIFACE has not been loaded yet, does caller want to load it?
189  if( doLoad )
190  {
191  wxString dname = dso_search_path( aFaceId );
192 
193  wxDynamicLibrary dso;
194 
195  void* addr = NULL;
196 
197  if( !dso.Load( dname, wxDL_VERBATIM | wxDL_NOW | wxDL_GLOBAL ) )
198  {
199  // Failure: error reporting UI was done via wxLogSysError().
200  // No further reporting required here. Apparently this is not true on all
201  // platforms and/or wxWidgets builds and KiCad will crash. Throwing the exception
202  // here and catching it in the KiCad launcher resolves the crash issue. See bug
203  // report https://bugs.launchpad.net/kicad/+bug/1577786.
204 
205  msg.Printf( _( "Failed to load kiface library \"%s\"." ), GetChars( dname ) );
206  THROW_IO_ERROR( msg );
207  }
208  else if( ( addr = dso.GetSymbol( wxT( KIFACE_INSTANCE_NAME_AND_VERSION ) ) ) == NULL )
209  {
210  // Failure: error reporting UI was done via wxLogSysError().
211  // No further reporting required here. Assume the same thing applies here as
212  // above with the Load() call. This has not been tested.
213  msg.Printf(
214  _( "Could not read instance name and version symbol form kiface library \"%s\"." ),
215  GetChars( dname ) );
216  THROW_IO_ERROR( msg );
217  }
218  else
219  {
220  KIFACE_GETTER_FUNC* getter = (KIFACE_GETTER_FUNC*) addr;
221 
222  KIFACE* kiface = getter( &m_kiface_version[aFaceId], KIFACE_VERSION, m_program );
223 
224  // KIFACE_GETTER_FUNC function comment (API) says the non-NULL is unconditional.
225  wxASSERT_MSG( kiface,
226  wxT( "attempted DSO has a bug, failed to return a KIFACE*" ) );
227 
228  // Give the DSO a single chance to do its "process level" initialization.
229  // "Process level" specifically means stay away from any projects in there.
230  if( kiface->OnKifaceStart( m_program, m_ctl ) )
231  {
232  // Tell dso's wxDynamicLibrary destructor not to Unload() the program image.
233  (void) dso.Detach();
234 
235  return m_kiface[aFaceId] = kiface;
236  }
237  }
238 
239  // In any of the failure cases above, dso.Unload() should be called here
240  // by dso destructor.
241  // However:
242 
243  // There is a file installation bug. We only look for KIFACE_I's which we know
244  // to exist, and we did not find one. If we do not find one, this is an
245  // installation bug.
246 
247  msg = wxString::Format( _(
248  "Fatal Installation Bug. File:\n"
249  "\"%s\"\ncould not be loaded\n" ), GetChars( dname ) );
250 
251  if( ! wxFileExists( dname ) )
252  msg << _( "It is missing.\n" );
253  else
254  msg << _( "Perhaps a shared library (.dll or .so) file is missing.\n" );
255 
256  msg << _( "From command line: argv[0]:\n'" );
257  msg << wxStandardPaths::Get().GetExecutablePath() << wxT( "'\n" );
258 
259  // This is a fatal error, one from which we cannot recover, nor do we want
260  // to protect against in client code which would require numerous noisy
261  // tests in numerous places. So we inform the user that the installation
262  // is bad. This exception will likely not get caught until way up in the
263  // wxApp derivative, at which point the process will exit gracefully.
264  THROW_IO_ERROR( msg );
265  }
266 
267  return NULL;
268 }
#define KIFACE_VERSION
Definition: kiway.h:111
PGM_BASE * m_program
Definition: kiway.h:415
#define KIFACE_INSTANCE_NAME_AND_VERSION
Definition: kiway.h:116
KIFACE * KIFACE_GETTER_FUNC(int *aKIFACEversion, int aKIWAYversion, PGM_BASE *aProgram)
Function Pointer KIFACE_GETTER_FUNC points to the one and only KIFACE export.
Definition: kiway.h:452
int m_ctl
Definition: kiway.h:416
#define THROW_IO_ERROR(msg)
const wxString dso_search_path(FACE_T aFaceId)
Get the [path &] name of the DSO holding the requested FACE_T.
Definition: kiway.cpp:95
constexpr std::size_t arrayDim(T const (&)[N]) noexcept
Definition: macros.h:107
static const wxChar * GetChars(const wxString &s)
Function GetChars returns a wxChar* to the actual wxChar* data within a wxString, and is helpful for ...
Definition: macros.h:100
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, CPTREE &aTree)
Function Format outputs a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:205
Class KIFACE is used by a participant in the KIWAY alchemy.
Definition: kiway.h:151
static int m_kiface_version[KIWAY_FACE_COUNT]
Definition: kiway.h:413
return & kiface
Definition: pcbnew.cpp:212
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:412

References arrayDim(), dso_search_path(), Format(), GetChars(), kiface, KIFACE_INSTANCE_NAME_AND_VERSION, KIFACE_VERSION, m_ctl, m_kiface, m_kiface_version, m_program, and THROW_IO_ERROR.

Referenced by FOOTPRINT_PREVIEW_PANEL_BASE::Create(), get_instance_from_id(), CVPCB_MAINFRAME::OnEditFootprintLibraryTable(), KICAD_MANAGER_FRAME::OnEditFpLibTable(), KICAD_MANAGER_FRAME::OnEditSymLibTable(), and Player().

◆ KifaceType()

KIWAY::FACE_T KIWAY::KifaceType ( FRAME_T  aFrameType)
static

Function KifaceType is a simple mapping function which returns the FACE_T which is known to implement aFrameType.

Returns
KIWAY::FACE_T - a valid value or FACE_T(-1) if given a bad aFrameType.

Definition at line 271 of file kiway.cpp.

272 {
273  switch( aFrameType )
274  {
275  case FRAME_SCH:
277  case FRAME_SCH_VIEWER:
279  case FRAME_SIMULATOR:
280  return FACE_SCH;
281 
282  case FRAME_PCB:
287  case FRAME_PCB_DISPLAY3D:
288  return FACE_PCB;
289 
290  case FRAME_CVPCB:
291  case FRAME_CVPCB_DISPLAY:
292  return FACE_CVPCB;
293 
294  case FRAME_GERBER:
295  return FACE_GERBVIEW;
296 
297  case FRAME_PL_EDITOR:
298  return FACE_PL_EDITOR;
299 
300  case FRAME_CALC:
301  return FACE_PCB_CALCULATOR;
302 
303  case FRAME_BM2CMP:
304  return FACE_BMP2CMP;
305 
306  default:
307  return FACE_T( -1 );
308  }
309 }
pcbnew DSO
Definition: kiway.h:267
FACE_T
Known KIFACE implementations.
Definition: kiway.h:264
eeschema DSO
Definition: kiway.h:266

References FACE_BMP2CMP, FACE_CVPCB, FACE_GERBVIEW, FACE_PCB, FACE_PCB_CALCULATOR, FACE_PL_EDITOR, FACE_SCH, FRAME_BM2CMP, FRAME_CALC, FRAME_CVPCB, FRAME_CVPCB_DISPLAY, FRAME_GERBER, FRAME_PCB, FRAME_PCB_DISPLAY3D, FRAME_PCB_FOOTPRINT_WIZARD, FRAME_PCB_MODULE_EDITOR, FRAME_PCB_MODULE_VIEWER, FRAME_PCB_MODULE_VIEWER_MODAL, FRAME_PL_EDITOR, FRAME_SCH, FRAME_SCH_LIB_EDITOR, FRAME_SCH_VIEWER, FRAME_SCH_VIEWER_MODAL, and FRAME_SIMULATOR.

Referenced by PGM_SINGLE_TOP::OnPgmInit(), and Player().

◆ OnKiwayEnd()

void KIWAY::OnKiwayEnd ( )

Definition at line 502 of file kiway.cpp.

503 {
504  for( KIFACE* i : m_kiface )
505  {
506  if( i )
507  i->OnKifaceEnd();
508  }
509 }
size_t i
Definition: json11.cpp:597
Class KIFACE is used by a participant in the KIWAY alchemy.
Definition: kiway.h:151
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:412

References i, and m_kiface.

Referenced by PGM_KICAD::OnPgmExit(), and PGM_SINGLE_TOP::OnPgmExit().

◆ Player()

KIWAY_PLAYER * KIWAY::Player ( FRAME_T  aFrameType,
bool  doCreate = true,
wxTopLevelWindow *  aParent = NULL 
)

Function Player returns 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.

Parameters
aFrameTypeis from enum FRAME_T.
doCreatewhen true asks that the player be created if it is not already created, false means do not create and maybe return NULL.
aParentis a parent for modal KIWAY_PLAYER frames, otherwise NULL used only when doCreate = true and by KIWAY_PLAYER frames created in modal form because the are using the wxFLOAT_ON_PARENT style
Returns
KIWAY_PLAYER* - a valid opened KIWAY_PLAYER or NULL if there is something wrong or doCreate was false and the player has yet to be created.
Exceptions
IO_ERRORif the *.kiface file could not be found, filled with text saying what.

Definition at line 321 of file kiway.cpp.

322 {
323  // Since this will be called from python, cannot assume that code will
324  // not pass a bad aFrameType.
325  if( (unsigned) aFrameType >= KIWAY_PLAYER_COUNT )
326  {
327  // @todo : throw an exception here for python's benefit, at least that
328  // way it gets some explanatory text.
329 
330  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFrameType" ) );
331  return NULL;
332  }
333 
334  // return the previously opened window
335  KIWAY_PLAYER* frame = GetPlayerFrame( aFrameType );
336 
337  if( frame )
338  return frame;
339 
340  if( doCreate )
341  {
342  FACE_T face_type = KifaceType( aFrameType );
343  wxASSERT( face_type != FACE_T(-1) );
344 
345  KIFACE* kiface = KiFACE( face_type );
346  wxASSERT( kiface );
347 
348  if( kiface )
349  {
350  frame = (KIWAY_PLAYER*) kiface->CreateWindow(
351  aParent, // Parent window of frame in modal mode, NULL in non modal mode
352  aFrameType,
353  this,
354  m_ctl // questionable need, these same flags where passed
355  // to the KIFACE::OnKifaceStart()
356  );
357  wxASSERT( frame );
358 
359  m_playerFrameName[aFrameType] = frame->GetName();
360 
361  return frame;
362  }
363  }
364 
365  return NULL;
366 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:127
static FACE_T KifaceType(FRAME_T aFrameType)
Function KifaceType is a simple mapping function which returns the FACE_T which is known to implement...
Definition: kiway.cpp:271
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:312
int m_ctl
Definition: kiway.h:416
VTBL_ENTRY KIFACE * KiFACE(FACE_T aFaceId, bool doLoad=true)
Function KiFACE returns the KIFACE* given a FACE_T.
Definition: kiway.cpp:169
FACE_T
Known KIFACE implementations.
Definition: kiway.h:264
Class KIFACE is used by a participant in the KIWAY alchemy.
Definition: kiway.h:151
wxArrayString m_playerFrameName
Definition: kiway.h:426
return & kiface
Definition: pcbnew.cpp:212

References GetPlayerFrame(), kiface, KiFACE(), KifaceType(), KIWAY_PLAYER_COUNT, m_ctl, and m_playerFrameName.

Referenced by FOOTPRINT_VIEWER_FRAME::AddFootprintToPCB(), PCB_BASE_EDIT_FRAME::AddLibrary(), CVPCB_MAINFRAME::CreateScreenCmp(), FIELDS_GRID_TRICKS::doPopupSelection(), FIELDS_EDITOR_GRID_TRICKS::doPopupSelection(), EDIT_TOOL::editFootprintInFpEditor(), SCH_EDITOR_CONTROL::EditWithSymbolEditor(), PCB_EDIT_FRAME::FetchNetlistFromSchematic(), FOOTPRINT_EDIT_FRAME::GetPlotSettings(), PCB_EDIT_FRAME::InstallFootprintPropertiesDialog(), InvokePcbLibTableEditor(), InvokeSchEditSymbolLibTable(), FOOTPRINT_EDIT_FRAME::Load_Module_From_BOARD(), FOOTPRINT_PREVIEW_PANEL::New(), LIB_VIEW_FRAME::OnAddPartToSchematic(), LIB_EDIT_FRAME::OnAddPartToSchematic(), TEXT_BUTTON_SYMBOL_CHOOSER::OnButtonClick(), TEXT_BUTTON_FP_CHOOSER::OnButtonClick(), SCH_EDIT_FRAME::OnCloseWindow(), KICAD_MANAGER_FRAME::OnImportEagleFiles(), SCH_EDIT_FRAME::OnOpenCvpcb(), SCH_EDIT_FRAME::OnOpenLibraryEditor(), SCH_BASE_FRAME::OnOpenLibraryViewer(), SCH_EDIT_FRAME::OnOpenPcbModuleEditor(), SCH_EDIT_FRAME::OnOpenPcbnew(), PGM_SINGLE_TOP::OnPgmInit(), DIALOG_SYMBOL_REMAP::OnRemapSymbols(), PCB_EDIT_FRAME::OnRunEeschema(), KICAD_MANAGER_FRAME::OnRunPcbFpEditor(), KICAD_MANAGER_FRAME::OnRunSchLibEditor(), SCH_EDIT_FRAME::OnSimulate(), DIALOG_EDIT_ONE_FIELD::OnTextValueSelectButtonClick(), FOOTPRINT_EDIT_FRAME::OnUpdateInsertModuleInBoard(), FOOTPRINT_EDIT_FRAME::OnUpdateLoadModuleFromBoard(), FOOTPRINT_EDIT_FRAME::Process_Special_Functions(), PCB_EDIT_FRAME::Process_Special_Functions(), ProcessEvent(), SCH_EDIT_FRAME::rescueProject(), KICAD_MANAGER_FRAME::RunEeschema(), KICAD_MANAGER_FRAME::RunPcbNew(), FOOTPRINT_EDIT_FRAME::SaveFootprintToBoard(), SCH_BASE_FRAME::SelectComponentFromLibBrowser(), PCB_BASE_FRAME::SelectFootprintFromLibBrowser(), FOOTPRINT_EDIT_FRAME::SetPlotSettings(), FOOTPRINT_SELECT_WIDGET::ShowPicker(), EDA_BASE_FRAME::ShowPreferences(), SIM_PLOT_FRAME::SIM_PLOT_FRAME(), and DIALOG_EXCHANGE_FOOTPRINTS::ViewAndSelectFootprint().

◆ PlayerClose()

bool KIWAY::PlayerClose ( FRAME_T  aFrameType,
bool  doForce 
)

Function PlayerClose calls 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.

Returns
bool - true the window is closed and not vetoed, else false.

Definition at line 369 of file kiway.cpp.

370 {
371  // Since this will be called from python, cannot assume that code will
372  // not pass a bad aFrameType.
373  if( (unsigned) aFrameType >= KIWAY_PLAYER_COUNT )
374  {
375  // @todo : throw an exception here for python's benefit, at least that
376  // way it gets some explanatory text.
377 
378  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFrameType" ) );
379  return false;
380  }
381 
382  KIWAY_PLAYER* frame = GetPlayerFrame( aFrameType );
383 
384  if( frame == NULL ) // Already closed
385  return true;
386 
387  if( frame->Close( doForce ) )
388  return true;
389 
390  return false;
391 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:127
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:312

References GetPlayerFrame(), and KIWAY_PLAYER_COUNT.

Referenced by PlayersClose().

◆ PlayersClose()

bool KIWAY::PlayersClose ( bool  doForce)

Function PlayersClose calls 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.

Returns
bool - 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.

Definition at line 394 of file kiway.cpp.

395 {
396  bool ret = true;
397 
398  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
399  {
400  ret = ret && PlayerClose( FRAME_T( i ), doForce );
401  }
402 
403  return ret;
404 }
FRAME_T
Enum FRAME_T is the set of EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident.
Definition: frame_type.h:34
VTBL_ENTRY bool PlayerClose(FRAME_T aFrameType, bool doForce)
Function PlayerClose calls the KIWAY_PLAYER::Close( bool force ) function on the window and if not ve...
Definition: kiway.cpp:369
size_t i
Definition: json11.cpp:597

References i, KIWAY_PLAYER_COUNT, and PlayerClose().

Referenced by KICAD_MANAGER_FRAME::LoadProject().

◆ Prj()

PROJECT & KIWAY::Prj ( ) const

Function Prj returns 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.

Definition at line 163 of file kiway.cpp.

164 {
165  return *(PROJECT*) &m_project; // strip const-ness, function really is const.
166 }
Class PROJECT holds project specific data.
Definition: project.h:57
PROJECT m_project
Definition: kiway.h:428

References m_project.

Referenced by SYMBOL_PREVIEW_WIDGET::DisplaySymbol(), SCH_LEGACY_PLUGIN::Format(), FOOTPRINT_LIST::GetInstance(), PCB_EDIT_FRAME::importFile(), SCH_EDIT_FRAME::importFile(), InvokePcbLibTableEditor(), InvokeSchEditSymbolLibTable(), SCH_LEGACY_PLUGIN::Load(), KIWAY_HOLDER::Prj(), and Prj().

◆ ProcessEvent()

bool KIWAY::ProcessEvent ( wxEvent &  aEvent)
override

Definition at line 476 of file kiway.cpp.

477 {
478  KIWAY_EXPRESS* mail = dynamic_cast<KIWAY_EXPRESS*>( &aEvent );
479 
480  if( mail )
481  {
482  FRAME_T dest = mail->Dest();
483 
484  // see if recipient is alive
485  KIWAY_PLAYER* alive = Player( dest, false );
486 
487  if( alive )
488  {
489 #if 1
490  return alive->ProcessEvent( aEvent );
491 #else
492  alive->KiwayMailIn( *mail );
493  return true;
494 #endif
495  }
496  }
497 
498  return false;
499 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:127
Class KIWAY_EXPRESS carries a payload from one KIWAY_PLAYER to another within a PROJECT.
Definition: kiway_express.h:39
FRAME_T
Enum FRAME_T is the set of EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident.
Definition: frame_type.h:34
VTBL_ENTRY KIWAY_PLAYER * Player(FRAME_T aFrameType, bool doCreate=true, wxTopLevelWindow *aParent=NULL)
Function Player returns the KIWAY_PLAYER* given a FRAME_T.
Definition: kiway.cpp:321
virtual void KiwayMailIn(KIWAY_EXPRESS &aEvent)
Function KiwayMailIn receives KIWAY_EXPRESS messages from other players.
FRAME_T Dest()
Function Dest returns the destination player id of the message.
Definition: kiway_express.h:46
bool ProcessEvent(wxEvent &aEvent) override
Override the default process event handler to implement the auto save feature.

References KIWAY_EXPRESS::Dest(), KIWAY_PLAYER::KiwayMailIn(), Player(), and EDA_BASE_FRAME::ProcessEvent().

Referenced by ExpressMail().

◆ set_kiface()

bool KIWAY::set_kiface ( FACE_T  aFaceType,
KIFACE aKiface 
)
inlineprivate

Definition at line 396 of file kiway.h.

397  {
398  if( (unsigned) aFaceType < (unsigned) KIWAY_FACE_COUNT )
399  {
400  m_kiface[aFaceType] = aKiface;
401  return true;
402  }
403  return false;
404  }
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:412

References KIWAY_FACE_COUNT, and m_kiface.

Referenced by PGM_SINGLE_TOP::OnPgmInit().

◆ SetLanguage()

void KIWAY::SetLanguage ( int  aLanguage)

Function SetLanguage changes the language and then calls ShowChangedLanguage() on all KIWAY_PLAYERs.

Definition at line 415 of file kiway.cpp.

416 {
417  Pgm().SetLanguageIdentifier( aLanguage );
418  Pgm().SetLanguage();
419 
420 #if 1
421  // This is a risky hack that goes away if we allow the language to be
422  // set only from the top most frame if !Kiface.IsSingle()
423 
424  // Only for the C++ project manager, and not for the python one and not for
425  // single_top do we look for the EDA_BASE_FRAME as the top level window.
426  // For single_top this is not needed because that window is registered in
427  // the array below.
429  {
430  // A dynamic_cast could be better, but creates link issues
431  // (some basic_frame functions not found) on some platforms,
432  // so a static_cast is used.
433  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
434 
435  if( top )
436  top->ShowChangedLanguage();
437  }
438 #endif
439 
440  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
441  {
442  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
443 
444  if( frame )
445  {
446  frame->ShowChangedLanguage();
447  }
448  }
449 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:160
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:127
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:312
FRAME_T
Enum FRAME_T is the set of EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident.
Definition: frame_type.h:34
PGM_BASE & Pgm()
The global Program "get" accessor.
Definition: kicad.cpp:66
VTBL_ENTRY void SetLanguageIdentifier(int menu_id)
Function SetLanguageIdentifier sets in .m_language_id member the wxWidgets language identifier Id fro...
Definition: pgm_base.cpp:764
int m_ctl
Definition: kiway.h:416
VTBL_ENTRY bool SetLanguage(bool first_time=false)
Function SetLanguage sets the dictionary file name for internationalization.
Definition: pgm_base.cpp:672
The base frame for deriving all KiCad main window classes.
size_t i
Definition: json11.cpp:597
wxFrame * m_top
Definition: kiway.h:418
virtual void ShowChangedLanguage()
Redraw the menus and what not in current language.

References GetPlayerFrame(), i, KFCTL_CPP_PROJECT_SUITE, KIWAY_PLAYER_COUNT, m_ctl, m_top, Pgm(), PGM_BASE::SetLanguage(), PGM_BASE::SetLanguageIdentifier(), and EDA_BASE_FRAME::ShowChangedLanguage().

Referenced by KIWAY_PLAYER::language_change(), and KICAD_MANAGER_FRAME::language_change().

◆ SetTop()

void KIWAY::SetTop ( wxFrame *  aTop)

Function SetTop tells 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.

Parameters
aTopis the top most wxFrame in the entire program.

Definition at line 77 of file kiway.cpp.

78 {
79 #if 0
80  if( m_top )
81  {
82  m_top->Disconnect( wxEVT_DESTROY, wxWindowDestroyEventHandler( KIWAY::player_destroy_handler ), NULL, this );
83  }
84 
85  if( aTop )
86  {
87  aTop->Connect( wxEVT_DESTROY, wxWindowDestroyEventHandler( KIWAY::player_destroy_handler ), NULL, this );
88  }
89 #endif
90 
91  m_top = aTop;
92 }
wxFrame * m_top
Definition: kiway.h:418

References m_top.

Referenced by KIWAY(), PGM_KICAD::OnPgmInit(), and PGM_SINGLE_TOP::OnPgmInit().

Friends And Related Function Documentation

◆ PGM_SINGLE_TOP

friend struct PGM_SINGLE_TOP
friend

Definition at line 260 of file kiway.h.

Member Data Documentation

◆ m_ctl

int KIWAY::m_ctl
private

Definition at line 416 of file kiway.h.

Referenced by CommonSettingsChanged(), dso_search_path(), KiFACE(), Player(), and SetLanguage().

◆ m_kiface

KIFACE * KIWAY::m_kiface
staticprivate

Definition at line 412 of file kiway.h.

Referenced by KiFACE(), OnKiwayEnd(), and set_kiface().

◆ m_kiface_version

int KIWAY::m_kiface_version
staticprivate

Definition at line 413 of file kiway.h.

Referenced by KiFACE().

◆ m_playerFrameName

wxArrayString KIWAY::m_playerFrameName
private

Definition at line 426 of file kiway.h.

Referenced by GetPlayerFrame(), KIWAY(), and Player().

◆ m_program

PGM_BASE* KIWAY::m_program
private

Definition at line 415 of file kiway.h.

Referenced by KiFACE().

◆ m_project

PROJECT KIWAY::m_project
private

Definition at line 428 of file kiway.h.

Referenced by Prj().

◆ m_top

wxFrame* KIWAY::m_top
private

Definition at line 418 of file kiway.h.

Referenced by CommonSettingsChanged(), SetLanguage(), and SetTop().


The documentation for this class was generated from the following files: