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

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 ( )
throw (
)
inline

Definition at line 277 of file kiway.h.

References aProgram, Prj(), PGM_BASE::SetLanguage(), and VTBL_ENTRY.

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

Definition at line 44 of file kiway.cpp.

References KIWAY_PLAYER_COUNT, m_playerFrameName, and SetTop().

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

Member Function Documentation

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

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

432 {
433 #if 1
435  {
436  // A dynamic_cast could be better, but creates link issues
437  // (some basic_frame functions not found) on some platforms,
438  // so a static_cast is used.
439  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
440 
441  if( top )
442  top->CommonSettingsChanged();
443  }
444 #endif
445 
446  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
447  {
448  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
449 
450  if( frame )
451  frame->CommonSettingsChanged();
452  }
453 }
#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:120
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:291
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
Class EDA_BASE_FRAME is the base frame for deriving all KiCad main window classes.
size_t i
Definition: json11.cpp:597
virtual void CommonSettingsChanged()
Function CommonSettingsChanged Notification event that some of the common (suite-wide) settings have ...
wxFrame * m_top
Definition: kiway.h:418
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 94 of file kiway.cpp.

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

95 {
96  const char* name;
97 
98  switch( aFaceId )
99  {
100  case FACE_SCH: name = KIFACE_PREFIX "eeschema"; break;
101  case FACE_PCB: name = KIFACE_PREFIX "pcbnew"; break;
102  case FACE_CVPCB: name = KIFACE_PREFIX "cvpcb"; break;
103  case FACE_GERBVIEW: name = KIFACE_PREFIX "gerbview"; break;
104  case FACE_PL_EDITOR: name = KIFACE_PREFIX "pl_editor"; break;
105  case FACE_PCB_CALCULATOR: name = KIFACE_PREFIX "pcb_calculator"; break;
106  case FACE_BMP2CMP: name = KIFACE_PREFIX "bitmap2component"; break;
107 
108  default:
109  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFaceId" ) );
110  return wxEmptyString;
111  }
112 
113 #ifndef __WXMAC__
114  wxString path;
115 
117  {
118  // The 2 *.cpp program launchers: single_top.cpp and kicad.cpp expect
119  // the *.kiface's to reside in same diretory as their binaries do.
120  // Not so for python launcher, identified by KFCTL_PY_PROJECT_SUITE
121  path = wxStandardPaths::Get().GetExecutablePath();
122  }
123 
124  wxFileName fn = path;
125 #else
126  // we have the dso's in main OSX bundle kicad.app/Contents/PlugIns
127  wxFileName fn = Pgm().GetExecutablePath();
128  fn.AppendDir( wxT( "Contents" ) );
129  fn.AppendDir( wxT( "PlugIns" ) );
130 #endif
131 
132  fn.SetName( name );
133 
134  // Here a "suffix" == an extension with a preceding '.',
135  // so skip the preceding '.' to get an extension
136  fn.SetExt( KIFACE_SUFFIX + 1 ); // + 1 => &KIFACE_SUFFIX[1]
137 
138  return fn.GetFullPath();
139 }
#define KFCTL_CPP_PROJECT_SUITE
Am running under C++ project mgr, possibly with others.
Definition: kiway.h:160
VTBL_ENTRY const wxString & GetExecutablePath() const
Definition: pgm_base.h:215
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
#define KFCTL_STANDALONE
Am running as a standalone Top.
Definition: kiway.h:159
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 386 of file kiway.cpp.

References ProcessEvent().

Referenced by TREEPROJECT_ITEM::Activate(), SCH_EDIT_FRAME::doUpdatePcb(), PCB_EDIT_FRAME::importFile(), SCH_EDIT_FRAME::KiwayMailIn(), KICAD_MANAGER_FRAME::OnImportEagleFiles(), PCB_EDIT_FRAME::OnUpdatePCBFromSch(), LIB_EDIT_FRAME::refreshSchematic(), CVPCB_MAINFRAME::SaveFootprintAssociation(), SCH_EDIT_FRAME::SendCrossProbeNetName(), PCB_EDIT_FRAME::SendCrossProbeNetName(), CVPCB_MAINFRAME::SendMessageToEESCHEMA(), PCB_EDIT_FRAME::SendMessageToEESCHEMA(), SCH_EDIT_FRAME::SendMessageToPCBNEW(), and SCH_EDIT_FRAME::sendNetlist().

388 {
389  KIWAY_EXPRESS mail( aDestination, aCommand, aPayload, aSource );
390 
391  ProcessEvent( mail );
392 }
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:456
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 291 of file kiway.cpp.

References m_playerFrameName.

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

292 {
293  if( m_playerFrameName[aFrameType].IsEmpty() )
294  return NULL;
295 
296  return static_cast<KIWAY_PLAYER*>( wxWindow::FindWindowByName( m_playerFrameName[aFrameType] ) );
297 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:120
wxArrayString m_playerFrameName
Definition: kiway.h:426
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 148 of file kiway.cpp.

References DIM, dso_search_path(), Format(), GetChars(), kiface, KIFACE_INSTANCE_NAME_AND_VERSION, KIFACE_VERSION, m_ctl, m_kiface, m_kiface_version, m_program, KIFACE::OnKifaceStart(), and THROW_IO_ERROR.

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

149 {
150  // Since this will be called from python, cannot assume that code will
151  // not pass a bad aFaceId.
152  if( unsigned( aFaceId ) >= DIM( m_kiface ) )
153  {
154  // @todo : throw an exception here for python's benefit, at least that
155  // way it gets some explanatory text.
156 
157  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFaceId" ) );
158  return NULL;
159  }
160 
161  // return the previously loaded KIFACE, if it was.
162  if( m_kiface[aFaceId] )
163  return m_kiface[aFaceId];
164 
165  wxString msg;
166 
167  // DSO with KIFACE has not been loaded yet, does caller want to load it?
168  if( doLoad )
169  {
170  wxString dname = dso_search_path( aFaceId );
171 
172  wxDynamicLibrary dso;
173 
174  void* addr = NULL;
175 
176  if( !dso.Load( dname, wxDL_VERBATIM | wxDL_NOW | wxDL_GLOBAL ) )
177  {
178  // Failure: error reporting UI was done via wxLogSysError().
179  // No further reporting required here. Apparently this is not true on all
180  // platforms and/or wxWidgets builds and KiCad will crash. Throwing the exception
181  // here and catching it in the KiCad launcher resolves the crash issue. See bug
182  // report https://bugs.launchpad.net/kicad/+bug/1577786.
183 
184  msg.Printf( _( "Failed to load kiface library \"%s\"." ), GetChars( dname ) );
185  THROW_IO_ERROR( msg );
186  }
187  else if( ( addr = dso.GetSymbol( wxT( KIFACE_INSTANCE_NAME_AND_VERSION ) ) ) == NULL )
188  {
189  // Failure: error reporting UI was done via wxLogSysError().
190  // No further reporting required here. Assume the same thing applies here as
191  // above with the Load() call. This has not been tested.
192  msg.Printf(
193  _( "Could not read instance name and version symbol form kiface library \"%s\"." ),
194  GetChars( dname ) );
195  THROW_IO_ERROR( msg );
196  }
197  else
198  {
199  KIFACE_GETTER_FUNC* getter = (KIFACE_GETTER_FUNC*) addr;
200 
201  KIFACE* kiface = getter( &m_kiface_version[aFaceId], KIFACE_VERSION, m_program );
202 
203  // KIFACE_GETTER_FUNC function comment (API) says the non-NULL is unconditional.
204  wxASSERT_MSG( kiface,
205  wxT( "attempted DSO has a bug, failed to return a KIFACE*" ) );
206 
207  // Give the DSO a single chance to do its "process level" initialization.
208  // "Process level" specifically means stay away from any projects in there.
209  if( kiface->OnKifaceStart( m_program, m_ctl ) )
210  {
211  // Tell dso's wxDynamicLibrary destructor not to Unload() the program image.
212  (void) dso.Detach();
213 
214  return m_kiface[aFaceId] = kiface;
215  }
216  }
217 
218  // In any of the failure cases above, dso.Unload() should be called here
219  // by dso destructor.
220  // However:
221 
222  // There is a file installation bug. We only look for KIFACE_I's which we know
223  // to exist, and we did not find one. If we do not find one, this is an
224  // installation bug.
225 
226  msg = wxString::Format( _(
227  "Fatal Installation Bug. File:\n"
228  "\"%s\"\ncould not be loaded\n" ), GetChars( dname ) );
229 
230  if( ! wxFileExists( dname ) )
231  msg << _( "It is missing.\n" );
232  else
233  msg << _( "Perhaps a shared library (.dll or .so) file is missing.\n" );
234 
235  msg << _( "From command line: argv[0]:\n'" );
236  msg << wxStandardPaths::Get().GetExecutablePath() << wxT( "'\n" );
237 
238  // This is a fatal error, one from which we cannot recover, nor do we want
239  // to protect against in client code which would require numerous noisy
240  // tests in numerous places. So we inform the user that the installation
241  // is bad. This exception will likely not get caught until way up in the
242  // wxApp derivative, at which point the process will exit gracefully.
243  THROW_IO_ERROR( msg );
244  }
245 
246  return NULL;
247 }
#define DIM(x)
of elements in an array
Definition: macros.h:98
#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:94
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:92
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
VTBL_ENTRY bool OnKifaceStart(PGM_BASE *aProgram, int aCtlBits)=0
Function OnKifaceStart is called just once shortly after the DSO is loaded.
return & kiface
Definition: pcbnew.cpp:219
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:412
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 250 of file kiway.cpp.

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

251 {
252  switch( aFrameType )
253  {
254  case FRAME_SCH:
256  case FRAME_SCH_VIEWER:
258  case FRAME_SIMULATOR:
259  return FACE_SCH;
260 
261  case FRAME_PCB:
266  case FRAME_PCB_DISPLAY3D:
267  return FACE_PCB;
268 
269  case FRAME_CVPCB:
270  case FRAME_CVPCB_DISPLAY:
271  return FACE_CVPCB;
272 
273  case FRAME_GERBER:
274  return FACE_GERBVIEW;
275 
276  case FRAME_PL_EDITOR:
277  return FACE_PL_EDITOR;
278 
279  case FRAME_CALC:
280  return FACE_PCB_CALCULATOR;
281 
282  case FRAME_BM2CMP:
283  return FACE_BMP2CMP;
284 
285  default:
286  return FACE_T( -1 );
287  }
288 }
pcbnew DSO
Definition: kiway.h:267
FACE_T
Known KIFACE implementations.
Definition: kiway.h:264
eeschema DSO
Definition: kiway.h:266
void KIWAY::OnKiwayEnd ( )

Definition at line 482 of file kiway.cpp.

References DIM, i, m_kiface, and KIFACE::OnKifaceEnd().

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

483 {
484  for( unsigned i=0; i < DIM( m_kiface ); ++i )
485  {
486  if( m_kiface[i] )
487  m_kiface[i]->OnKifaceEnd();
488  }
489 }
#define DIM(x)
of elements in an array
Definition: macros.h:98
VTBL_ENTRY void OnKifaceEnd()=0
Function OnKifaceEnd is called just once just before the DSO is to be unloaded.
size_t i
Definition: json11.cpp:597
static KIFACE * m_kiface[KIWAY_FACE_COUNT]
Definition: kiway.h:412
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 300 of file kiway.cpp.

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

Referenced by PCB_BASE_EDIT_FRAME::AddLibrary(), CVPCB_MAINFRAME::CreateScreenCmp(), FIELDS_GRID_TRICKS::doPopupSelection(), FIELDS_EDITOR_GRID_TRICKS::doPopupSelection(), SCH_EDIT_FRAME::doUpdatePcb(), EDIT_TOOL::editFootprintInFpEditor(), FOOTPRINT_EDIT_FRAME::GetPlotSettings(), PCB_EDIT_FRAME::InstallFootprintPropertiesDialog(), InvokePcbLibTableEditor(), InvokeSchEditSymbolLibTable(), FOOTPRINT_EDIT_FRAME::Load_Module_From_BOARD(), FOOTPRINT_PREVIEW_PANEL::New(), TEXT_BUTTON_SYMBOL_CHOOSER::OnButtonClick(), TEXT_BUTTON_FP_CHOOSER::OnButtonClick(), SCH_EDIT_FRAME::OnCloseWindow(), KICAD_MANAGER_FRAME::OnImportEagleFiles(), SCH_EDIT_FRAME::OnLeftClick(), SCH_EDIT_FRAME::OnOpenCvpcb(), SCH_EDIT_FRAME::OnOpenLibraryEditor(), SCH_BASE_FRAME::OnOpenLibraryViewer(), SCH_EDIT_FRAME::OnOpenPcbModuleEditor(), SCH_EDIT_FRAME::OnOpenPcbnew(), PGM_SINGLE_TOP::OnPgmInit(), 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(), PCB_EDIT_FRAME::OnUpdatePCBFromSch(), FOOTPRINT_EDIT_FRAME::Process_Special_Functions(), PCB_EDIT_FRAME::Process_Special_Functions(), ProcessEvent(), FOOTPRINT_WIZARD_FRAME::ReCreateVToolbar(), 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().

301 {
302  // Since this will be called from python, cannot assume that code will
303  // not pass a bad aFrameType.
304  if( unsigned( aFrameType ) >= KIWAY_PLAYER_COUNT )
305  {
306  // @todo : throw an exception here for python's benefit, at least that
307  // way it gets some explanatory text.
308 
309  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFrameType" ) );
310  return NULL;
311  }
312 
313  // return the previously opened window
314  KIWAY_PLAYER* frame = GetPlayerFrame( aFrameType );
315 
316  if( frame )
317  return frame;
318 
319  if( doCreate )
320  {
321  FACE_T face_type = KifaceType( aFrameType );
322  wxASSERT( face_type != FACE_T(-1) );
323 
324  KIFACE* kiface = KiFACE( face_type );
325  wxASSERT( kiface );
326 
327  if( kiface )
328  {
329  frame = (KIWAY_PLAYER*) kiface->CreateWindow(
330  aParent, // Parent window of frame in modal mode, NULL in non modal mode
331  aFrameType,
332  this,
333  m_ctl // questionable need, these same flags where passed
334  // to the KIFACE::OnKifaceStart()
335  );
336  wxASSERT( frame );
337 
338  m_playerFrameName[aFrameType] = frame->GetName();
339 
340  return frame;
341  }
342  }
343 
344  return NULL;
345 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:120
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:250
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:291
VTBL_ENTRY wxWindow * CreateWindow(wxWindow *aParent, int aClassId, KIWAY *aKIWAY, int aCtlBits=0)=0
Function CreateWindow creates a wxWindow for the current project.
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:148
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:219
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 348 of file kiway.cpp.

References GetPlayerFrame(), and KIWAY_PLAYER_COUNT.

Referenced by PlayersClose().

349 {
350  // Since this will be called from python, cannot assume that code will
351  // not pass a bad aFrameType.
352  if( unsigned( aFrameType ) >= KIWAY_PLAYER_COUNT )
353  {
354  // @todo : throw an exception here for python's benefit, at least that
355  // way it gets some explanatory text.
356 
357  wxASSERT_MSG( 0, wxT( "caller has a bug, passed a bad aFrameType" ) );
358  return false;
359  }
360 
361  KIWAY_PLAYER* frame = GetPlayerFrame( aFrameType );
362 
363  if( frame == NULL ) // Already closed
364  return true;
365 
366  if( frame->Close( doForce ) )
367  return true;
368 
369  return false;
370 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:120
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:291
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 373 of file kiway.cpp.

References i, KIWAY_PLAYER_COUNT, and PlayerClose().

Referenced by KICAD_MANAGER_FRAME::LoadProject().

374 {
375  bool ret = true;
376 
377  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
378  {
379  ret = ret && PlayerClose( FRAME_T( i ), doForce );
380  }
381 
382  return ret;
383 }
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:348
size_t i
Definition: json11.cpp:597
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 142 of file kiway.cpp.

References m_project.

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

143 {
144  return *(PROJECT*) &m_project; // strip const-ness, function really is const.
145 }
Class PROJECT holds project specific data.
Definition: project.h:57
PROJECT m_project
Definition: kiway.h:428
bool KIWAY::ProcessEvent ( wxEvent &  aEvent)
override

Definition at line 456 of file kiway.cpp.

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

Referenced by ExpressMail().

457 {
458  KIWAY_EXPRESS* mail = dynamic_cast<KIWAY_EXPRESS*>( &aEvent );
459 
460  if( mail )
461  {
462  FRAME_T dest = mail->Dest();
463 
464  // see if recipient is alive
465  KIWAY_PLAYER* alive = Player( dest, false );
466 
467  if( alive )
468  {
469 #if 1
470  return alive->ProcessEvent( aEvent );
471 #else
472  alive->KiwayMailIn( *mail );
473  return true;
474 #endif
475  }
476  }
477 
478  return false;
479 }
Class KIWAY_PLAYER is a wxFrame capable of the OpenProjectFiles function, meaning it can load a porti...
Definition: kiway_player.h:120
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:300
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
Function ProcessEvent overrides the default process event handler to implement the auto save feature...
bool KIWAY::set_kiface ( FACE_T  aFaceType,
KIFACE aKiface 
)
inlineprivate

Definition at line 396 of file kiway.h.

Referenced by PGM_SINGLE_TOP::OnPgmInit().

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
void KIWAY::SetLanguage ( int  aLanguage)

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

Definition at line 395 of file kiway.cpp.

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

396 {
397  Pgm().SetLanguageIdentifier( aLanguage );
398  Pgm().SetLanguage();
399 
400 #if 1
401  // This is a risky hack that goes away if we allow the language to be
402  // set only from the top most frame if !Kiface.IsSingle()
403 
404  // Only for the C++ project manager, and not for the python one and not for
405  // single_top do we look for the EDA_BASE_FRAME as the top level window.
406  // For single_top this is not needed because that window is registered in
407  // the array below.
409  {
410  // A dynamic_cast could be better, but creates link issues
411  // (some basic_frame functions not found) on some platforms,
412  // so a static_cast is used.
413  EDA_BASE_FRAME* top = static_cast<EDA_BASE_FRAME*>( m_top );
414 
415  if( top )
416  top->ShowChangedLanguage();
417  }
418 #endif
419 
420  for( unsigned i=0; i < KIWAY_PLAYER_COUNT; ++i )
421  {
422  KIWAY_PLAYER* frame = GetPlayerFrame( ( FRAME_T )i );
423 
424  if( frame )
425  {
426  frame->ShowChangedLanguage();
427  }
428  }
429 }
#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:120
KIWAY_PLAYER * GetPlayerFrame(FRAME_T aFrameType)
Definition: kiway.cpp:291
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:749
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:657
Class EDA_BASE_FRAME is 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()
Function ShowChangedLanguage redraws the menus and what not in current language.
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 76 of file kiway.cpp.

References m_top.

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

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

Friends And Related Function Documentation

friend struct PGM_SINGLE_TOP
friend

Definition at line 260 of file kiway.h.

Member Data Documentation

int KIWAY::m_ctl
private

Definition at line 416 of file kiway.h.

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

KIFACE * KIWAY::m_kiface
staticprivate

Definition at line 412 of file kiway.h.

Referenced by KiFACE(), and OnKiwayEnd().

int KIWAY::m_kiface_version
staticprivate

Definition at line 413 of file kiway.h.

Referenced by KiFACE().

wxArrayString KIWAY::m_playerFrameName
private

Definition at line 426 of file kiway.h.

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

PGM_BASE* KIWAY::m_program
private

Definition at line 415 of file kiway.h.

Referenced by KiFACE().

PROJECT KIWAY::m_project
private

Definition at line 428 of file kiway.h.

Referenced by Prj().

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: