KiCad PCB EDA Suite
KIWAY Class Reference

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 (bool aEnvVarsChanged, bool aTextVarsChanged)
 Function CommonSettingsChanged Calls CommonSettingsChanged() on all KIWAY_PLAYERs. More...
 
VTBL_ENTRY void ProjectChanged ()
 Calls ProjectChanged() 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 OnKiCadExit ()
 
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
 

Static Private Attributes

static KIFACEm_kiface [KIWAY_FACE_COUNT]
 
static int m_kiface_version [KIWAY_FACE_COUNT]
 

Friends

struct PGM_SINGLE_TOP
 

Detailed Description

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 273 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 279 of file kiway.h.

Constructor & Destructor Documentation

◆ ~KIWAY()

KIWAY::~KIWAY ( )
throw (
)
inline

Definition at line 292 of file kiway.h.

292 {}

◆ KIWAY()

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

Definition at line 47 of file kiway.cpp.

47  :
48  m_program( aProgram ), m_ctl( aCtlBits ), m_top( 0 )
49 {
50  SetTop( aTop ); // hook player_destroy_handler() into aTop.
51 
52 
53  // Prepare the room to store the frame names, once they will be created
54  // with FRAME_T type as index in this table.
55  // (note this is a list of frame names, but a non empty entry
56  // does not mean the frame still exists. It means only the frame was created
57  // at least once. It can be destroyed after. These entries are not cleared.
58  // the purpose is just to allow a call to wxWindow::FindWindowByName(), from
59  // a FRAME_T frame type
60  m_playerFrameName.Add( wxEmptyString, KIWAY_PLAYER_COUNT );
61 }
PGM_BASE * m_program
Definition: kiway.h:438
int m_ctl
Definition: kiway.h:439
int PGM_BASE * aProgram
Definition: cvpcb/cvpcb.cpp:97
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:79
wxArrayString m_playerFrameName
Definition: kiway.h:449
wxFrame * m_top
Definition: kiway.h:441

References KIWAY_PLAYER_COUNT, m_playerFrameName, and SetTop().

Member Function Documentation

◆ CommonSettingsChanged()

void KIWAY::CommonSettingsChanged ( bool  aEnvVarsChanged,
bool  aTextVarsChanged 
)

Function CommonSettingsChanged Calls CommonSettingsChanged() on all KIWAY_PLAYERs.

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

Definition at line 513 of file kiway.cpp.

514 {
516  {
517  // A dynamic_cast could be better, but creates link issues
518  // (some basic_frame functions not found) on some platforms,
519  // so a static_cast is used.
520  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
521 
522  if( top )
523  top->CommonSettingsChanged( aEnvVarsChanged, aTextVarsChanged );
524  }
525 
526  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
527  {
528  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
529 
530  if( frame )
531  frame->CommonSettingsChanged( aEnvVarsChanged, aTextVarsChanged );
532  }
533 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:159
KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of ...
Definition: kiway_player.h:59
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:334
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:439
void CommonSettingsChanged(bool aEnvVarsChanged, bool aTextVarsChanged) override
Notification event that some of the common (suite-wide) settings have changed.
The base frame for deriving all KiCad main window classes.
wxFrame * m_top
Definition: kiway.h:441

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

Referenced by COMMON_CONTROL::ConfigurePaths(), PCB::IFACE::CreateWindow(), EDA_BASE_FRAME::OnPreferences(), PCB_EDIT_FRAME::ShowBoardSetupDialog(), and SCH_EDIT_FRAME::ShowSchematicSetupDialog().

◆ 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 97 of file kiway.cpp.

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

References FACE_BMP2CMP, FACE_CVPCB, FACE_GERBVIEW, FACE_PCB, FACE_PCB_CALCULATOR, FACE_PL_EDITOR, FACE_SCH, 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 
)

◆ 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 334 of file kiway.cpp.

335 {
336  if( m_playerFrameName[aFrameType].IsEmpty() )
337  return NULL;
338 
339  return static_cast<KIWAY_PLAYER*>( wxWindow::FindWindowByName( m_playerFrameName[aFrameType] ) );
340 }
#define NULL
wxArrayString m_playerFrameName
Definition: kiway.h:449

References m_playerFrameName, and NULL.

Referenced by CommonSettingsChanged(), Player(), PlayerClose(), ProjectChanged(), 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 179 of file kiway.cpp.

180 {
181  // Since this will be called from python, cannot assume that code will
182  // not pass a bad aFaceId.
183  if( (unsigned) aFaceId >= arrayDim( m_kiface ) )
184  {
185  // @todo : throw an exception here for python's benefit, at least that
186  // way it gets some explanatory text.
187 
188  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFaceId" ) );
189  return NULL;
190  }
191 
192  // return the previously loaded KIFACE, if it was.
193  if( m_kiface[aFaceId] )
194  return m_kiface[aFaceId];
195 
196  wxString msg;
197 
198  // DSO with KIFACE has not been loaded yet, does caller want to load it?
199  if( doLoad )
200  {
201  wxString dname = dso_search_path( aFaceId );
202 
203  wxDynamicLibrary dso;
204 
205  void* addr = NULL;
206 
207  // For some reason wxDynamicLibrary::Load() crashes in some languages
208  // (chinese for instance) when loading the dynamic library.
209  // The crash happens for Eeschema.
210  // So switch to "C" locale during loading (LC_COLLATE is enough).
211  int lc_new_type = LC_COLLATE;
212  std::string user_locale = setlocale( lc_new_type, nullptr );
213  setlocale( lc_new_type, "C" );
214 
215  bool success = dso.Load( dname, wxDL_VERBATIM | wxDL_NOW | wxDL_GLOBAL );
216 
217  setlocale( lc_new_type, user_locale.c_str() );
218 
219  if( !success )
220  {
221  // Failure: error reporting UI was done via wxLogSysError().
222  // No further reporting required here. Apparently this is not true on all
223  // platforms and/or wxWidgets builds and KiCad will crash. Throwing the exception
224  // here and catching it in the KiCad launcher resolves the crash issue. See bug
225  // report https://bugs.launchpad.net/kicad/+bug/1577786.
226 
227  msg.Printf( _( "Failed to load kiface library \"%s\"." ), dname );
228  THROW_IO_ERROR( msg );
229  }
230  else if( ( addr = dso.GetSymbol( wxT( KIFACE_INSTANCE_NAME_AND_VERSION ) ) ) == NULL )
231  {
232  // Failure: error reporting UI was done via wxLogSysError().
233  // No further reporting required here. Assume the same thing applies here as
234  // above with the Load() call. This has not been tested.
235  msg.Printf(
236  _( "Could not read instance name and version symbol form kiface library \"%s\"." ),
237  dname );
238  THROW_IO_ERROR( msg );
239  }
240  else
241  {
242  KIFACE_GETTER_FUNC* getter = (KIFACE_GETTER_FUNC*) addr;
243 
244  KIFACE* kiface = getter( &m_kiface_version[aFaceId], KIFACE_VERSION, m_program );
245 
246  // KIFACE_GETTER_FUNC function comment (API) says the non-NULL is unconditional.
247  wxASSERT_MSG( kiface,
248  wxT( "attempted DSO has a bug, failed to return a KIFACE*" ) );
249 
250  // Give the DSO a single chance to do its "process level" initialization.
251  // "Process level" specifically means stay away from any projects in there.
252  if( kiface->OnKifaceStart( m_program, m_ctl ) )
253  {
254  // Tell dso's wxDynamicLibrary destructor not to Unload() the program image.
255  (void) dso.Detach();
256 
257  return m_kiface[aFaceId] = kiface;
258  }
259  }
260 
261  // In any of the failure cases above, dso.Unload() should be called here
262  // by dso destructor.
263  // However:
264 
265  // There is a file installation bug. We only look for KIFACE_I's which we know
266  // to exist, and we did not find one. If we do not find one, this is an
267  // installation bug.
268 
269  msg = wxString::Format( _(
270  "Fatal Installation Bug. File:\n"
271  "\"%s\"\ncould not be loaded\n" ), dname );
272 
273  if( ! wxFileExists( dname ) )
274  msg << _( "It is missing.\n" );
275  else
276  msg << _( "Perhaps a shared library (.dll or .so) file is missing.\n" );
277 
278  msg << _( "From command line: argv[0]:\n'" );
279  msg << wxStandardPaths::Get().GetExecutablePath() << wxT( "'\n" );
280 
281  // This is a fatal error, one from which we cannot recover, nor do we want
282  // to protect against in client code which would require numerous noisy
283  // tests in numerous places. So we inform the user that the installation
284  // is bad. This exception will likely not get caught until way up in the
285  // wxApp derivative, at which point the process will exit gracefully.
286  THROW_IO_ERROR( msg );
287  }
288 
289  return NULL;
290 }
BITMAP2CMP_SETTINGS kiface
#define KIFACE_VERSION
Definition: kiway.h:111
PGM_BASE * m_program
Definition: kiway.h:438
#define KIFACE_INSTANCE_NAME_AND_VERSION
Definition: kiway.h:116
#define NULL
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:473
int m_ctl
Definition: kiway.h:439
const wxString dso_search_path(FACE_T aFaceId)
Get the [path &] name of the DSO holding the requested FACE_T.
Definition: kiway.cpp:97
constexpr std::size_t arrayDim(T const (&)[N]) noexcept
Definition: macros.h:160
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:201
#define _(s)
Definition: 3d_actions.cpp:33
KIFACE is used by a participant in the KIWAY alchemy.
Definition: kiway.h:150
static int m_kiface_version[KIWAY_FACE_COUNT]
Definition: kiway.h:436
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:435

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

Referenced by COMMON_CONTROL::ConfigurePaths(), FOOTPRINT_PREVIEW_PANEL_BASE::Create(), get_instance_from_id(), SAVE_AS_TRAVERSER::OnFile(), PROJECT::PcbFootprintLibs(), Player(), and COMMON_CONTROL::ShowLibraryTable().

◆ 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 293 of file kiway.cpp.

294 {
295  switch( aFrameType )
296  {
297  case FRAME_SCH:
299  case FRAME_SCH_VIEWER:
301  case FRAME_SIMULATOR:
302  return FACE_SCH;
303 
304  case FRAME_PCB_EDITOR:
309  case FRAME_PCB_DISPLAY3D:
310  return FACE_PCB;
311 
312  case FRAME_CVPCB:
313  case FRAME_CVPCB_DISPLAY:
314  return FACE_CVPCB;
315 
316  case FRAME_GERBER:
317  return FACE_GERBVIEW;
318 
319  case FRAME_PL_EDITOR:
320  return FACE_PL_EDITOR;
321 
322  case FRAME_CALC:
323  return FACE_PCB_CALCULATOR;
324 
325  case FRAME_BM2CMP:
326  return FACE_BMP2CMP;
327 
328  default:
329  return FACE_T( -1 );
330  }
331 }
pcbnew DSO
Definition: kiway.h:282
FACE_T
Known KIFACE implementations.
Definition: kiway.h:279
eeschema DSO
Definition: kiway.h:281

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_FOOTPRINT_EDITOR, FRAME_FOOTPRINT_VIEWER, FRAME_FOOTPRINT_VIEWER_MODAL, FRAME_FOOTPRINT_WIZARD, FRAME_GERBER, FRAME_PCB_DISPLAY3D, FRAME_PCB_EDITOR, 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().

◆ OnKiCadExit()

void KIWAY::OnKiCadExit ( )

Definition at line 585 of file kiway.cpp.

586 {
588  {
589  // A dynamic_cast could be better, but creates link issues
590  // (some basic_frame functions not found) on some platforms,
591  // so a static_cast is used.
592  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
593 
594  if( top )
595  top->Close( false );
596  }
597 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:159
int m_ctl
Definition: kiway.h:439
The base frame for deriving all KiCad main window classes.
wxFrame * m_top
Definition: kiway.h:441

References KFCTL_CPP_PROJECT_SUITE, m_ctl, and m_top.

Referenced by PL_EDITOR_FRAME::OnExit(), SCH_EDIT_FRAME::OnExit(), FOOTPRINT_EDIT_FRAME::OnExitKiCad(), FOOTPRINT_VIEWER_FRAME::OnExitKiCad(), LIB_EDIT_FRAME::OnExitKiCad(), and PCB_EDIT_FRAME::OnQuit().

◆ OnKiwayEnd()

void KIWAY::OnKiwayEnd ( )

Definition at line 600 of file kiway.cpp.

601 {
602  for( KIFACE* i : m_kiface )
603  {
604  if( i )
605  i->OnKifaceEnd();
606  }
607 }
KIFACE is used by a participant in the KIWAY alchemy.
Definition: kiway.h:150
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:435

References m_kiface.

Referenced by PGM_KICAD::OnPgmExit(), PGM_SINGLE_TOP::OnPgmExit(), PGM_TEST_FRAME::OnPgmExit(), and PGM_MOCK_EESCHEMA_FRAME::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 343 of file kiway.cpp.

344 {
345  // Since this will be called from python, cannot assume that code will
346  // not pass a bad aFrameType.
347  if( (unsigned) aFrameType >= KIWAY_PLAYER_COUNT )
348  {
349  // @todo : throw an exception here for python's benefit, at least that
350  // way it gets some explanatory text.
351 
352  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFrameType" ) );
353  return NULL;
354  }
355 
356  // return the previously opened window
357  KIWAY_PLAYER* frame = GetPlayerFrame( aFrameType );
358 
359  if( frame )
360  return frame;
361 
362  if( doCreate )
363  {
364  try
365  {
366  FACE_T face_type = KifaceType( aFrameType );
367  KIFACE* kiface = KiFACE( face_type );
368 
369  frame = (KIWAY_PLAYER*) kiface->CreateWindow(
370  aParent, // Parent window of frame in modal mode,
371  // NULL in non modal mode
372  aFrameType,
373  this,
374  m_ctl // questionable need, these same flags
375  // were passed to KIFACE::OnKifaceStart()
376  );
377 
378  m_playerFrameName[aFrameType] = frame->GetName();
379  return frame;
380  }
381  catch( const IO_ERROR& ioe )
382  {
383  DisplayErrorMessage( NULL, _( "Error loading editor" ), ioe.What() );
384  }
385  catch ( const std::exception& e)
386  {
387  DisplayErrorMessage( NULL, _( "Error loading editor" ), e.what() );
388  }
389  catch( ... )
390  {
391  DisplayErrorMessage( NULL, _( "Error loading editor" ) );
392  }
393  }
394 
395  return NULL;
396 }
BITMAP2CMP_SETTINGS kiface
KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of ...
Definition: kiway_player.h:59
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:293
void DisplayErrorMessage(wxWindow *aParent, const wxString &aText, const wxString &aExtraInfo)
Display an error message with aMessage.
Definition: confirm.cpp:252
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:334
#define NULL
virtual const wxString What() const
A composite of Problem() and Where()
Definition: exceptions.cpp:29
int m_ctl
Definition: kiway.h:439
VTBL_ENTRY KIFACE * KiFACE(FACE_T aFaceId, bool doLoad=true)
Function KiFACE returns the KIFACE* given a FACE_T.
Definition: kiway.cpp:179
FACE_T
Known KIFACE implementations.
Definition: kiway.h:279
#define _(s)
Definition: 3d_actions.cpp:33
KIFACE is used by a participant in the KIWAY alchemy.
Definition: kiway.h:150
wxArrayString m_playerFrameName
Definition: kiway.h:449
Struct IO_ERROR is a class used to hold an error message and may be used when throwing exceptions con...
Definition: ki_exception.h:76

References _, DisplayErrorMessage(), GetPlayerFrame(), kiface, KiFACE(), KifaceType(), KIWAY_PLAYER_COUNT, m_ctl, m_playerFrameName, NULL, and IO_ERROR::What().

Referenced by FOOTPRINT_VIEWER_FRAME::AddFootprintToPCB(), PCB_BASE_EDIT_FRAME::AddLibrary(), LIB_CONTROL::AddSymbolToSchematic(), SCH_EDIT_FRAME::canCloseWindow(), FIELDS_GRID_TRICKS::doPopupSelection(), FIELDS_EDITOR_GRID_TRICKS::doPopupSelection(), PCB_EDITOR_CONTROL::EditFpInFpEditor(), SCH_EDITOR_CONTROL::EditWithLibEdit(), BACK_ANNOTATE::FetchNetlistFromPCB(), PCB_EDIT_FRAME::InstallFootprintPropertiesDialog(), InvokePcbLibTableEditor(), InvokeSchEditSymbolLibTable(), DIALOG_CHANGE_SYMBOLS::launchMatchIdSymbolBrowser(), DIALOG_CHANGE_SYMBOLS::launchNewIdSymbolBrowser(), FOOTPRINT_EDIT_FRAME::Load_Module_From_BOARD(), TEXT_BUTTON_SYMBOL_CHOOSER::OnButtonClick(), TEXT_BUTTON_FP_CHOOSER::OnButtonClick(), KICAD_MANAGER_FRAME::OnImportEagleFiles(), SCH_EDIT_FRAME::OnOpenCvpcb(), SCH_EDIT_FRAME::OnOpenPcbnew(), PGM_SINGLE_TOP::OnPgmInit(), EDA_BASE_FRAME::OnPreferences(), DIALOG_SYMBOL_REMAP::OnRemapSymbols(), DIALOG_EDIT_ONE_FIELD::OnTextValueSelectButtonClick(), FOOTPRINT_EDIT_FRAME::OnUpdateInsertModuleInBoard(), FOOTPRINT_EDIT_FRAME::OnUpdateLoadModuleFromBoard(), SCH_EDIT_FRAME::OnUpdatePCB(), FOOTPRINT_EDIT_FRAME::Process_Special_Functions(), ProcessEvent(), SCH_EDIT_TOOL::Properties(), SCH_EDITOR_CONTROL::rescueProject(), PCB_EDIT_FRAME::RunEeschema(), EE_INSPECTION_TOOL::RunSimulation(), FOOTPRINT_EDIT_FRAME::SaveFootprintToBoard(), SCH_BASE_FRAME::SelectComponentFromLibBrowser(), PCB_BASE_FRAME::SelectFootprintFromLibBrowser(), CVPCB_CONTROL::ShowFootprintViewer(), FOOTPRINT_SELECT_WIDGET::ShowPicker(), COMMON_CONTROL::ShowPlayer(), KICAD_MANAGER_CONTROL::ShowPlayer(), SIM_PLOT_FRAME::SIM_PLOT_FRAME(), PCB_EDIT_FRAME::TestStandalone(), PCB_EDITOR_CONTROL::UpdateSchematicFromPCB(), LIB_CONTROL::UpdateSymbolInSchematic(), 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 399 of file kiway.cpp.

400 {
401  // Since this will be called from python, cannot assume that code will
402  // not pass a bad aFrameType.
403  if( (unsigned) aFrameType >= KIWAY_PLAYER_COUNT )
404  {
405  // @todo : throw an exception here for python's benefit, at least that
406  // way it gets some explanatory text.
407 
408  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFrameType" ) );
409  return false;
410  }
411 
412  KIWAY_PLAYER* frame = GetPlayerFrame( aFrameType );
413 
414  if( frame == NULL ) // Already closed
415  return true;
416 
417  if( frame->NonUserClose( doForce ) )
418  return true;
419 
420  return false;
421 }
KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of ...
Definition: kiway_player.h:59
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:334
#define NULL
bool NonUserClose(bool aForce)

References GetPlayerFrame(), KIWAY_PLAYER_COUNT, EDA_BASE_FRAME::NonUserClose(), and NULL.

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 424 of file kiway.cpp.

425 {
426  bool ret = true;
427 
428  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
429  {
430  ret = ret && PlayerClose( FRAME_T( i ), doForce );
431  }
432 
433  return ret;
434 }
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:399

References KIWAY_PLAYER_COUNT, and PlayerClose().

◆ 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 173 of file kiway.cpp.

174 {
175  return Pgm().GetSettingsManager().Prj();
176 }
KIWAY Kiway & Pgm(), KFCTL_STANDALONE
The global Program "get" accessor.
Definition: single_top.cpp:104
VTBL_ENTRY PROJECT & Prj() const
Function Prj returns the PROJECT associated with this KIWAY.
Definition: kiway.cpp:173

References Pgm(), and Prj().

Referenced by PCB::IFACE::CreateWindow(), SYMBOL_PREVIEW_WIDGET::DisplaySymbol(), FOOTPRINT_LIST::GetInstance(), PCB_EDIT_FRAME::importFile(), InvokePcbLibTableEditor(), InvokeSchEditSymbolLibTable(), LIB_TREE_MODEL_ADAPTER::LIB_TREE_MODEL_ADAPTER(), KIWAY_HOLDER::Prj(), Prj(), Prj(), and LIB_TREE_MODEL_ADAPTER::SavePinnedItems().

◆ ProcessEvent()

bool KIWAY::ProcessEvent ( wxEvent &  aEvent)
override

Definition at line 559 of file kiway.cpp.

560 {
561  KIWAY_EXPRESS* mail = dynamic_cast<KIWAY_EXPRESS*>( &aEvent );
562 
563  if( mail )
564  {
565  FRAME_T dest = mail->Dest();
566 
567  // see if recipient is alive
568  KIWAY_PLAYER* alive = Player( dest, false );
569 
570  if( alive )
571  {
572 #if 1
573  return alive->ProcessEvent( aEvent );
574 #else
575  alive->KiwayMailIn( *mail );
576  return true;
577 #endif
578  }
579  }
580 
581  return false;
582 }
KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of ...
Definition: kiway_player.h:59
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:343
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().

◆ ProjectChanged()

void KIWAY::ProjectChanged ( )

Calls ProjectChanged() on all KIWAY_PLAYERs.

Used after changing the project to ensure all players are updated correctly.

Definition at line 536 of file kiway.cpp.

537 {
539  {
540  // A dynamic_cast could be better, but creates link issues
541  // (some basic_frame functions not found) on some platforms,
542  // so a static_cast is used.
543  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
544 
545  if( top )
546  top->ProjectChanged();
547  }
548 
549  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
550  {
551  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
552 
553  if( frame )
554  frame->ProjectChanged();
555  }
556 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:159
KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of ...
Definition: kiway_player.h:59
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:334
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:439
The base frame for deriving all KiCad main window classes.
virtual void ProjectChanged()
Notification event that the project has changed.
wxFrame * m_top
Definition: kiway.h:441

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

Referenced by SETTINGS_MANAGER::LoadProject(), and SETTINGS_MANAGER::UnloadProject().

◆ set_kiface()

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

Definition at line 419 of file kiway.h.

420  {
421  if( (unsigned) aFaceType < (unsigned) KIWAY_FACE_COUNT )
422  {
423  m_kiface[aFaceType] = aKiface;
424  return true;
425  }
426  return false;
427  }
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:435

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 445 of file kiway.cpp.

446 {
447  wxString errMsg;
448  bool ret = false;
449 
450  {
451  // Only allow the traces to be logged by wx. We use our own system to log when the
452  // OS doesn't support the language, so we want to hide the wx error.
453  WX_LOG_TRACE_ONLY logtraceOnly;
454  Pgm().SetLanguageIdentifier( aLanguage );
455  ret = Pgm().SetLanguage( errMsg );
456  }
457 
458  if( !ret )
459  {
460  wxString lang;
461 
462  for( unsigned ii = 0; LanguagesList[ii].m_KI_Lang_Identifier != 0; ii++ )
463  {
464  if( aLanguage == LanguagesList[ii].m_KI_Lang_Identifier )
465  {
466  if( LanguagesList[ii].m_DoNotTranslate )
467  lang = LanguagesList[ii].m_Lang_Label;
468  else
469  lang = wxGetTranslation( LanguagesList[ii].m_Lang_Label );
470 
471  break;
472  }
473  }
474 
475  DisplayErrorMessage( nullptr,
476  wxString::Format( _( "Unable to switch language to %s" ), lang ),
477  errMsg );
478  return;
479  }
480 
481 #if 1
482  // This is a risky hack that goes away if we allow the language to be
483  // set only from the top most frame if !Kiface.IsSingle()
484 
485  // Only for the C++ project manager, and not for the python one and not for
486  // single_top do we look for the EDA_BASE_FRAME as the top level window.
487  // For single_top this is not needed because that window is registered in
488  // the array below.
490  {
491  // A dynamic_cast could be better, but creates link issues
492  // (some basic_frame functions not found) on some platforms,
493  // so a static_cast is used.
494  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
495 
496  if( top )
497  top->ShowChangedLanguage();
498  }
499 #endif
500 
501  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
502  {
503  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
504 
505  if( frame )
506  {
507  frame->ShowChangedLanguage();
508  }
509  }
510 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:159
LANGUAGE_DESCR LanguagesList[]
An array containing all the languages that KiCad supports.
Definition: pgm_base.cpp:71
KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of ...
Definition: kiway_player.h:59
KIWAY Kiway & Pgm(), KFCTL_STANDALONE
The global Program "get" accessor.
Definition: single_top.cpp:104
void DisplayErrorMessage(wxWindow *aParent, const wxString &aText, const wxString &aExtraInfo)
Display an error message with aMessage.
Definition: confirm.cpp:252
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:334
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_KI_Lang_Identifier
KiCad identifier used in menu selection (See id.h)
Definition: pgm_base.h:63
VTBL_ENTRY void SetLanguage(int aLanguage)
Function SetLanguage changes the language and then calls ShowChangedLanguage() on all KIWAY_PLAYERs.
Definition: kiway.cpp:445
int m_ctl
Definition: kiway.h:439
wxString m_Lang_Label
Labels used in menus.
Definition: pgm_base.h:66
A logger class that filters out all log messages that are not generated by wxLogTrace and ignores the...
Definition: logging.h:31
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:201
#define _(s)
Definition: 3d_actions.cpp:33
The base frame for deriving all KiCad main window classes.
wxFrame * m_top
Definition: kiway.h:441
virtual void ShowChangedLanguage()
Redraw the menus and what not in current language.

References _, DisplayErrorMessage(), Format(), GetPlayerFrame(), KFCTL_CPP_PROJECT_SUITE, KIWAY_PLAYER_COUNT, LanguagesList, m_ctl, LANGUAGE_DESCR::m_KI_Lang_Identifier, LANGUAGE_DESCR::m_Lang_Label, m_top, Pgm(), SetLanguage(), and EDA_BASE_FRAME::ShowChangedLanguage().

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

◆ 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 79 of file kiway.cpp.

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

References m_top, and NULL.

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 275 of file kiway.h.

Member Data Documentation

◆ m_ctl

int KIWAY::m_ctl
private

◆ m_kiface

KIFACE * KIWAY::m_kiface
staticprivate

Definition at line 435 of file kiway.h.

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

◆ m_kiface_version

int KIWAY::m_kiface_version
staticprivate

Definition at line 436 of file kiway.h.

Referenced by KiFACE().

◆ m_playerFrameName

wxArrayString KIWAY::m_playerFrameName
private

Definition at line 449 of file kiway.h.

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

◆ m_program

PGM_BASE* KIWAY::m_program
private

Definition at line 438 of file kiway.h.

Referenced by KiFACE().

◆ m_top

wxFrame* KIWAY::m_top
private

Definition at line 441 of file kiway.h.

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


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