haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Header clean up round 2.

This commit is contained in:
Wayne Stambaugh 2020-12-19 11:00:52 -05:00
parent f1aa82aad6
commit a1fae02427
28 changed files with 1291 additions and 1373 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
common/hotkeys_basic.cpp
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2010-2011 Wayne Stambaugh <stambaughw@verizon.net> * Copyright (C) 2010 Wayne Stambaugh <stambaughw@gmail.com>
* Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -141,13 +141,13 @@ static struct hotkey_name_descr hotkeyNameList[] =
/** /**
* Function KeyNameFromKeyCode * Return the key name from the key code.
* return the key name from the key code *
* Only some wxWidgets key values are handled for function key ( see * Only some wxWidgets key values are handled for function key ( see hotkeyNameList[] )
* hotkeyNameList[] ) *
* @param aKeycode = key code (ascii value, or wxWidgets value for function keys) * @param aKeycode key code (ASCII value, or wxWidgets value for function keys).
* @param aIsFound = a pointer to a bool to return true if found, or false. an be nullptr default) * @param aIsFound a pointer to a bool to return true if found, or false. an be nullptr default).
* @return the key name in a wxString * @return the key name in a wxString.
*/ */
wxString KeyNameFromKeyCode( int aKeycode, bool* aIsFound ) wxString KeyNameFromKeyCode( int aKeycode, bool* aIsFound )
{ {
@ -200,11 +200,10 @@ wxString KeyNameFromKeyCode( int aKeycode, bool* aIsFound )
/** /**
* AddHotkeyName * @param aText the base text on which to append the hotkey.
* @param aText - the base text on which to append the hotkey * @param aHotKey the hotkey keycode.
* @param aHotKey - the hotkey keycode * @param aStyle IS_HOTKEY to add <tab><keyname> (shortcuts in menus, same as hotkeys).
* @param aStyle - IS_HOTKEY to add <tab><keyname> (shortcuts in menus, same as hotkeys) * IS_COMMENT to add <spaces><(keyname)> mainly in tool tips.
* IS_COMMENT to add <spaces><(keyname)> mainly in tool tips
*/ */
wxString AddHotkeyName( const wxString& aText, int aHotKey, HOTKEY_ACTION_TYPE aStyle ) wxString AddHotkeyName( const wxString& aText, int aHotKey, HOTKEY_ACTION_TYPE aStyle )
{ {
@ -219,7 +218,7 @@ wxString AddHotkeyName( const wxString& aText, int aHotKey, HOTKEY_ACTION_TYPE a
{ {
// Don't add a suffix for unassigned hotkeys: // Don't add a suffix for unassigned hotkeys:
// WX spews debug from wxAcceleratorEntry::ParseAccel if it doesn't // WX spews debug from wxAcceleratorEntry::ParseAccel if it doesn't
// recognise the keyname, which is the case for <unassigned>. // recognize the keyname, which is the case for <unassigned>.
if( aHotKey != 0 ) if( aHotKey != 0 )
{ {
msg << wxT( "\t" ) << keyname; msg << wxT( "\t" ) << keyname;
@ -245,8 +244,7 @@ wxString AddHotkeyName( const wxString& aText, int aHotKey, HOTKEY_ACTION_TYPE a
/** /**
* Function KeyCodeFromKeyName * Return the key code from its user-friendly key name (ie: "Ctrl+M").
* return the key code from its user-friendly key name (ie: "Ctrl+M")
*/ */
int KeyCodeFromKeyName( const wxString& keyname ) int KeyCodeFromKeyName( const wxString& keyname )
{ {
@ -312,7 +310,6 @@ int KeyCodeFromKeyName( const wxString& keyname )
/* /*
* DisplayHotkeyList
* Displays the hotkeys registered with the given tool manager. * Displays the hotkeys registered with the given tool manager.
*/ */
void DisplayHotkeyList( EDA_BASE_FRAME* aParent, TOOL_MANAGER* aToolManager ) void DisplayHotkeyList( EDA_BASE_FRAME* aParent, TOOL_MANAGER* aToolManager )
@ -322,8 +319,10 @@ void DisplayHotkeyList( EDA_BASE_FRAME* aParent, TOOL_MANAGER* aToolManager )
} }
void ReadHotKeyConfig( wxString fileName, std::map<std::string, int>& aHotKeys ) void ReadHotKeyConfig( const wxString& aFileName, std::map<std::string, int>& aHotKeys )
{ {
wxString fileName = aFileName;
if( fileName.IsEmpty() ) if( fileName.IsEmpty() )
{ {
wxFileName fn( "user" ); wxFileName fn( "user" );
@ -367,22 +366,19 @@ int WriteHotKeyConfig( const std::map<std::string, TOOL_ACTION*>& aActionMap )
fn.SetPath( SETTINGS_MANAGER::GetUserSettingsPath() ); fn.SetPath( SETTINGS_MANAGER::GetUserSettingsPath() );
// Read the existing config (all hotkeys) // Read the existing config (all hotkeys)
//
ReadHotKeyConfig( fn.GetFullPath(), hotkeys ); ReadHotKeyConfig( fn.GetFullPath(), hotkeys );
// Overlay the current app's hotkey definitions onto the map // Overlay the current app's hotkey definitions onto the map
//
for( const auto& ii : aActionMap ) for( const auto& ii : aActionMap )
hotkeys[ ii.first ] = ii.second->GetHotKey(); hotkeys[ ii.first ] = ii.second->GetHotKey();
// Write entire hotkey set // Write entire hotkey set
//
wxFFileOutputStream outStream( fn.GetFullPath() ); wxFFileOutputStream outStream( fn.GetFullPath() );
wxTextOutputStream txtStream( outStream, wxEOL_UNIX ); wxTextOutputStream txtStream( outStream, wxEOL_UNIX );
for( const auto& ii : hotkeys ) for( const auto& ii : hotkeys )
txtStream << wxString::Format( "%s\t%s", ii.first, KeyNameFromKeyCode( ii.second ) ) << endl; txtStream << wxString::Format( "%s\t%s", ii.first,
KeyNameFromKeyCode( ii.second ) ) << endl;
txtStream.Flush(); txtStream.Flush();
outStream.Close(); outStream.Close();

8
include/filehistory.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2019 Ian McInerney <Ian.S.McInerney@ieee.org> * Copyright (C) 2019 Ian McInerney <Ian.S.McInerney@ieee.org>
* Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -131,7 +131,7 @@ public:
void ClearFileHistory(); void ClearFileHistory();
/** /**
* Create a SELECTION_CONDITION that can be used to enable a menu item when the * Create a #SELECTION_CONDITION that can be used to enable a menu item when the
* file history has items in it. * file history has items in it.
* *
* @param aHistory is the file history to check for items * @param aHistory is the file history to check for items
@ -156,8 +156,8 @@ protected:
private: private:
/** /**
* Test if the file history is empty. This function is designed to be used with a SELECTION_CONDITION * Test if the file history is empty. This function is designed to be used with a
* to enable/disable the file history menu. * #SELECTION_CONDITION to enable/disable the file history menu.
* *
* @param aSelection is unused * @param aSelection is unused
* @param aHistory is the file history to test for items * @param aHistory is the file history to test for items

182
include/filename_resolver.h
View File

@ -2,6 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2015-2016 Cirilo Bernardo <cirilo.bernardo@gmail.com> * Copyright (C) 2015-2016 Cirilo Bernardo <cirilo.bernardo@gmail.com>
* Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -23,11 +24,6 @@
/** /**
* @file filename_resolver.h * @file filename_resolver.h
* provides an extensible class to resolve 3D model paths. Initially
* the legacy behavior will be implemented and an incomplete path
* would be checked against the project directory or the KISYS3DMOD
* environment variable. In the future a configurable set of search
* paths may be specified.
*/ */
#ifndef FILENAME_RESOLVER_H #ifndef FILENAME_RESOLVER_H
@ -48,158 +44,144 @@ struct SEARCH_PATH
wxString m_Description; // description of the aliased path wxString m_Description; // description of the aliased path
}; };
/**
* Provide an extensible class to resolve 3D model paths.
*
* Initially the legacy behavior will be implemented and an incomplete path would be checked
* against the project directory or the KISYS3DMOD environment variable. In the future a
* configurable set of search paths may be specified.
*/
class FILENAME_RESOLVER class FILENAME_RESOLVER
{ {
private:
wxString m_configDir; // 3D configuration directory
std::list<SEARCH_PATH> m_paths; // list of base paths to search from
int m_errflags;
PGM_BASE* m_pgm;
PROJECT* m_project;
wxString m_curProjDir;
/**
* Function createPathList
* builds the path list using available information such as
* KISYS3DMOD and the 3d_path_list configuration file. Invalid
* paths are silently discarded and removed from the configuration
* file.
*
* @return true if at least one valid path was found
*/
bool createPathList( void );
/**
* Function addPath
* checks that a path is valid and adds it to the search list
*
* @param aPath is the alias set to be checked and added
* @return true if aPath is valid
*/
bool addPath( const SEARCH_PATH& aPath );
/**
* Function readPathList
* reads a list of path names from a configuration file
*
* @return true if a file was found and contained at least
* one valid path
*/
bool readPathList( void );
/**
* Function writePathList
* writes the current path list to a configuration file
*
* @return true if the path list was not empty and was
* successfully written to the configuration file
*/
bool writePathList( void );
/**
* Function checkEnvVarPath
* checks the ${ENV_VAR} component of a path and adds
* it to the resolver's path list if it is not yet in
* the list
*/
void checkEnvVarPath( const wxString& aPath );
public: public:
FILENAME_RESOLVER(); FILENAME_RESOLVER();
/** /**
* Function Set3DConfigDir * Set the user's configuration directory for 3D models.
* sets the user's configuration directory
* for 3D models.
* *
* @param aConfigDir * @param aConfigDir
* @return true if the call succeeds (directory exists) * @return true if the call succeeds (directory exists).
*/ */
bool Set3DConfigDir( const wxString& aConfigDir ); bool Set3DConfigDir( const wxString& aConfigDir );
/** /**
* Function SetProjectDir * Set the current KiCad project directory as the first entry in the model path list.
* sets the current KiCad project directory as the first
* entry in the model path list
* *
* @param[in] aProjDir current project directory * @param[in] aProjDir current project directory
* @param[out] flgChanged optional, set to true if directory was changed * @param[out] flgChanged optional, set to true if directory was changed
* @retval true success * @retval true success
* @retval false failure * @retval false failure
*/ */
bool SetProject( PROJECT* aProject, bool* flgChanged = NULL ); bool SetProject( PROJECT* aProject, bool* flgChanged = nullptr );
wxString GetProjectDir( void ); wxString GetProjectDir( void );
/** /**
* Function SetProgramBase * Set a pointer to the application's #PGM_BASE instance used to extract the local env vars.
* sets a pointer to the application's PGM_BASE instance;
* the pointer is used to extract the local env vars.
*/ */
void SetProgramBase( PGM_BASE* aBase ); void SetProgramBase( PGM_BASE* aBase );
/** /**
* Function UpdatePathList * Clear the current path list and substitutes the given path list and update the path
* clears the current path list and substitutes the given path * configuration file on success.
* list, updating the path configuration file on success.
*/ */
bool UpdatePathList( std::vector< SEARCH_PATH >& aPathList ); bool UpdatePathList( std::vector< SEARCH_PATH >& aPathList );
/** /**
* Function ResolvePath * Determines the full path of the given file name.
* determines the full path of the given file name. In the future *
* remote files may be supported, in which case it is best to * In the future remote files may be supported, in which case it is best to require a full
* require a full URI in which case ResolvePath should check that * URI in which case ResolvePath should check that the URI conforms to RFC-2396 and related
* the URI conforms to RFC-2396 and related documents and copies * documents and copies \a aFileName into aResolvedName if the URI is valid.
* aFileName into aResolvedName if the URI is valid.
*/ */
wxString ResolvePath( const wxString& aFileName ); wxString ResolvePath( const wxString& aFileName );
/** /**
* Function ShortenPath * Produce a relative path based on the existing search directories or returns the same path
* produces a relative path based on the existing * if the path is not a superset of an existing search path.
* search directories or returns the same path if
* the path is not a superset of an existing search path.
* *
* @param aFullPathName is an absolute path to shorten * @param aFullPathName is an absolute path to shorten.
* @return the shortened path or aFullPathName * @return the shortened path or \a aFullPathName.
*/ */
wxString ShortenPath( const wxString& aFullPathName ); wxString ShortenPath( const wxString& aFullPathName );
/** /**
* Function GetPaths * Return a pointer to the internal path list; the items in:load.
* returns a pointer to the internal path list; the items in:load
* *
* the list can be used to set up the list of search paths * The list can be used to set up the list of search paths available to a 3D file browser.
* available to a 3D file browser.
* *
* @return pointer to the internal path list * @return pointer to the internal path list.
*/ */
const std::list< SEARCH_PATH >* GetPaths( void ); const std::list< SEARCH_PATH >* GetPaths( void );
/** /**
* Function SplitAlias * Return true if the given name contains an alias and populates the string \a anAlias
* returns true if the given name contains an alias and * with the alias and \a aRelPath with the relative path.
* populates the string anAlias with the alias and aRelPath
* with the relative path.
*/ */
bool SplitAlias( const wxString& aFileName, wxString& anAlias, wxString& aRelPath ); bool SplitAlias( const wxString& aFileName, wxString& anAlias, wxString& aRelPath );
/** /**
* Function ValidateName * Returns true if the given path is a valid aliased relative path.
* returns true if the given path is a valid aliased relative path. *
* If the path contains an alias then hasAlias is set true. * If the path contains an alias then hasAlias is set true.
*/ */
bool ValidateFileName( const wxString& aFileName, bool& hasAlias ); bool ValidateFileName( const wxString& aFileName, bool& hasAlias );
/** /**
* Function GetKicadPaths * Return a list of path environment variables local to KiCad.
* returns a list of path environment variables local to Kicad; *
* this list always includes KISYS3DMOD even if it is not * This list always includes KISYS3DMOD even if it is not defined locally.
* defined locally.
*/ */
bool GetKicadPaths( std::list< wxString >& paths ); bool GetKicadPaths( std::list< wxString >& paths );
private:
/**
* Build the path list using available information such as KISYS3DMOD and the 3d_path_list
* configuration file.
*
* @warning Invalid paths are silently discarded and removed from the configuration file.
*
* @return true if at least one valid path was found.
*/
bool createPathList( void );
/**
* Check that a path is valid and adds it to the search list.
*
* @param aPath is the alias set to be checked and added.
* @return true if aPath is valid.
*/
bool addPath( const SEARCH_PATH& aPath );
/**
* Read a list of path names from a configuration file.
*
* @return true if a file was found and contained at least one valid path.
*/
bool readPathList( void );
/**
* Write the current path list to a configuration file.
*
* @return true if the path list was not empty and was successfully written to the
* configuration file.
*/
bool writePathList( void );
/**
* Check the ${ENV_VAR} component of a path and adds it to the resolver's path list if
* it is not yet in the list.
*/
void checkEnvVarPath( const wxString& aPath );
wxString m_configDir; // 3D configuration directory
std::list<SEARCH_PATH> m_paths; // list of base paths to search from
int m_errflags;
PGM_BASE* m_pgm;
PROJECT* m_project;
wxString m_curProjDir;
}; };
#endif // FILENAME_RESOLVER_H #endif // FILENAME_RESOLVER_H

7
include/fill_type.h
View File

@ -21,10 +21,9 @@
#define FILL_TYPE_H #define FILL_TYPE_H
/** /**
* Enum class FILL_TYPE * The set of fill types used in plotting or drawing enclosed areas.
* is the set of fill types used in plotting or drawing enclosed areas.
* *
* Warning: Do not renumber this enum, the legacy schematic plugin demands on these values * @warning Do not renumber this enum, the legacy schematic plugin demands on these values.
*/ */
enum class FILL_TYPE : int enum class FILL_TYPE : int
{ {
@ -35,4 +34,4 @@ enum class FILL_TYPE : int
FILLED_WITH_COLOR =3 // Fill with a user-defined color (currently sheets only) FILLED_WITH_COLOR =3 // Fill with a user-defined color (currently sheets only)
}; };
#endif #endif

32
include/filter_reader.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2007-2010 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2007-2010 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2007 KiCad Developers, see change_log.txt for contributors. * Copyright (C) 2007-2020 KiCad Developers, see change_log.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -30,19 +30,14 @@
/** /**
* FILTER_READER * Read lines of text from another #LINE_READER but only returns non-comment lines and
* reads lines of text from another LINE_READER, but only returns non-comment * non-blank lines from its ReadLine() function.
* lines and non-blank lines from its ReadLine() function.
*/ */
class FILTER_READER : public LINE_READER class FILTER_READER : public LINE_READER
{ {
LINE_READER& reader;
public: public:
/** /**
* Constructor ( LINE_READER& ) * Does not take ownership over @a aReader so will not destroy it.
* does not take ownership over @a aReader, so will not destroy it.
*/ */
FILTER_READER( LINE_READER& aReader ); FILTER_READER( LINE_READER& aReader );
@ -59,24 +54,22 @@ public:
{ {
return reader.LineNumber(); return reader.LineNumber();
} }
private:
LINE_READER& reader;
}; };
/** /**
* WHITESPACE_FILTER_READER * Read lines of text from another #LINE_READER but only returns non-comment lines and
* reads lines of text from another LINE_READER, but only returns non-comment * non-blank lines with leading whitespace characters (space and tab) removed from its
* lines and non-blank lines with leading whitespace characters (space and tab) * ReadLine() function.
* removed from its ReadLine() function.
*/ */
class WHITESPACE_FILTER_READER : public LINE_READER class WHITESPACE_FILTER_READER : public LINE_READER
{ {
LINE_READER& reader;
public: public:
/** /**
* Constructor ( LINE_READER& ) * Doe not take ownership over @a aReader, so will not destroy it.
* does not take ownership over @a aReader, so will not destroy it.
*/ */
WHITESPACE_FILTER_READER( LINE_READER& aReader ); WHITESPACE_FILTER_READER( LINE_READER& aReader );
@ -93,6 +86,9 @@ public:
{ {
return reader.LineNumber(); return reader.LineNumber();
} }
private:
LINE_READER& reader;
}; };
#endif // FILTER_READER_H_ #endif // FILTER_READER_H_

87
include/footprint_info.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2011 Jean-Pierre Charras, <jp.charras@wanadoo.fr> * Copyright (C) 2011 Jean-Pierre Charras, <jp.charras@wanadoo.fr>
* Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -59,8 +59,6 @@ class wxTextFile;
*/ */
class APIEXPORT FOOTPRINT_INFO : public LIB_TREE_ITEM class APIEXPORT FOOTPRINT_INFO : public LIB_TREE_ITEM
{ {
friend bool operator<( const FOOTPRINT_INFO& item1, const FOOTPRINT_INFO& item2 );
public: public:
virtual ~FOOTPRINT_INFO() virtual ~FOOTPRINT_INFO()
{ {
@ -134,6 +132,9 @@ public:
*/ */
friend bool operator<( const FOOTPRINT_INFO& lhs, const FOOTPRINT_INFO& rhs ); friend bool operator<( const FOOTPRINT_INFO& lhs, const FOOTPRINT_INFO& rhs );
private:
friend bool operator<( const FOOTPRINT_INFO& item1, const FOOTPRINT_INFO& item2 );
protected: protected:
void ensure_loaded() void ensure_loaded()
{ {
@ -159,7 +160,7 @@ protected:
/** /**
* Holds a list of FOOTPRINT_INFO objects, along with a list of IO_ERRORs or * Holds a list of #FOOTPRINT_INFO objects, along with a list of IO_ERRORs or
* PARSE_ERRORs that were thrown acquiring the FOOTPRINT_INFOs. * PARSE_ERRORs that were thrown acquiring the FOOTPRINT_INFOs.
* *
* This is a virtual class; its implementation lives in pcbnew/footprint_info_impl.cpp. * This is a virtual class; its implementation lives in pcbnew/footprint_info_impl.cpp.
@ -167,18 +168,10 @@ protected:
*/ */
class APIEXPORT FOOTPRINT_LIST class APIEXPORT FOOTPRINT_LIST
{ {
friend class FOOTPRINT_ASYNC_LOADER; public:
protected:
FP_LIB_TABLE* m_lib_table; ///< no ownership
typedef std::vector<std::unique_ptr<FOOTPRINT_INFO>> FPILIST; typedef std::vector<std::unique_ptr<FOOTPRINT_INFO>> FPILIST;
typedef SYNC_QUEUE<std::unique_ptr<IO_ERROR>> ERRLIST; typedef SYNC_QUEUE<std::unique_ptr<IO_ERROR>> ERRLIST;
FPILIST m_list;
ERRLIST m_errors; ///< some can be PARSE_ERRORs also
public:
FOOTPRINT_LIST() : m_lib_table( 0 ) FOOTPRINT_LIST() : m_lib_table( 0 )
{ {
} }
@ -225,8 +218,9 @@ public:
/** /**
* Get info for a footprint by index. * Get info for a footprint by index.
* @param aIdx = index of the given item *
* @return the aIdx item in list * @param aIdx index of the given item.
* @return the aIdx item in list.
*/ */
FOOTPRINT_INFO& GetItem( unsigned aIdx ) FOOTPRINT_INFO& GetItem( unsigned aIdx )
{ {
@ -250,13 +244,13 @@ public:
* Read all the footprints provided by the combination of aTable and aNickname. * Read all the footprints provided by the combination of aTable and aNickname.
* *
* @param aTable defines all the libraries. * @param aTable defines all the libraries.
* @param aNickname is the library to read from, or if NULL means read all * @param aNickname is the library to read from, or if NULL means read all footprints
* footprints from all known libraries in aTable. * from all known libraries in aTable.
* @param aProgressReporter is an optional progress reporter. ReadFootprintFiles() * @param aProgressReporter is an optional progress reporter. ReadFootprintFiles() will
* will use 2 phases within the reporter. * use 2 phases within the reporter.
* @return bool - true if it ran to completion, else false if it aborted after * @return true if it ran to completion, else false if it aborted after some number of
* some number of errors. If true, it does not mean there were no errors, check * errors. If true, it does not mean there were no errors, check GetErrorCount()
* GetErrorCount() for that, should be zero to indicate success. * for that, should be zero to indicate success.
*/ */
virtual bool ReadFootprintFiles( FP_LIB_TABLE* aTable, const wxString* aNickname = nullptr, virtual bool ReadFootprintFiles( FP_LIB_TABLE* aTable, const wxString* aNickname = nullptr,
PROGRESS_REPORTER* aProgressReporter = nullptr ) = 0; PROGRESS_REPORTER* aProgressReporter = nullptr ) = 0;
@ -269,17 +263,18 @@ public:
} }
/** /**
* Factory function to return a FOOTPRINT_LIST via Kiway. NOT guaranteed * Factory function to return a #FOOTPRINT_LIST via Kiway.
* to succeed; will return null if the kiface is not available.
* *
* @param aKiway - active kiway instance * This is not guaranteed to succeed and will return null if the kiface is not available.
*
* @param aKiway active kiway instance.
*/ */
static FOOTPRINT_LIST* GetInstance( KIWAY& aKiway ); static FOOTPRINT_LIST* GetInstance( KIWAY& aKiway );
protected: protected:
/** /**
* Launch worker threads to load footprints. Part of the * Launch worker threads to load footprints. Part of the #FOOTPRINT_ASYNC_LOADER
* FOOTPRINT_ASYNC_LOADER implementation. * implementation.
*/ */
virtual void startWorkers( FP_LIB_TABLE* aTable, wxString const* aNickname, virtual void startWorkers( FP_LIB_TABLE* aTable, wxString const* aNickname,
FOOTPRINT_ASYNC_LOADER* aLoader, unsigned aNThreads ) = 0; FOOTPRINT_ASYNC_LOADER* aLoader, unsigned aNThreads ) = 0;
@ -293,24 +288,26 @@ protected:
* Stop worker threads. Part of the FOOTPRINT_ASYNC_LOADER implementation. * Stop worker threads. Part of the FOOTPRINT_ASYNC_LOADER implementation.
*/ */
virtual void stopWorkers() = 0; virtual void stopWorkers() = 0;
private:
friend class FOOTPRINT_ASYNC_LOADER;
protected:
FP_LIB_TABLE* m_lib_table; ///< no ownership
FPILIST m_list;
ERRLIST m_errors; ///< some can be PARSE_ERRORs also
}; };
/** /**
* This class can be used to populate a FOOTPRINT_LIST asynchronously. * Object used to populate a #FOOTPRINT_LIST asynchronously.
* Constructing one, calling .Start(), then waiting until it reports completion *
* is equivalent to calling FOOTPRINT_LIST::ReadFootprintFiles(). * Construct one, calling #Start(), and then waiting until it reports completion. This is
* equivalent to calling #FOOTPRINT_LIST::ReadFootprintFiles().
*/ */
class APIEXPORT FOOTPRINT_ASYNC_LOADER class APIEXPORT FOOTPRINT_ASYNC_LOADER
{ {
friend class FOOTPRINT_LIST;
friend class FOOTPRINT_LIST_IMPL;
FOOTPRINT_LIST* m_list;
std::string m_last_table;
int m_total_libs;
public: public:
/** /**
* Construct an asynchronous loader. * Construct an asynchronous loader.
@ -327,9 +324,10 @@ public:
/** /**
* Launch the worker threads. * Launch the worker threads.
*
* @param aTable defines all the libraries. * @param aTable defines all the libraries.
* @param aNickname is the library to read from, or if NULL means read all * @param aNickname is the library to read from, or if NULL means read all footprints from
* footprints from all known libraries in aTable. * all known libraries in \a aTable.
* @param aNThreads is the number of worker threads. * @param aNThreads is the number of worker threads.
*/ */
void Start( FP_LIB_TABLE* aTable, wxString const* aNickname = nullptr, void Start( FP_LIB_TABLE* aTable, wxString const* aNickname = nullptr,
@ -356,11 +354,20 @@ public:
*/ */
void Abort(); void Abort();
private:
/** /**
* Default number of worker threads. Determined empirically (by dickelbeck): * Default number of worker threads. Determined empirically (by dickelbeck):
* More than 6 is not significantly faster, less than 6 is likely slower. * More than 6 is not significantly faster, less than 6 is likely slower.
*/ */
static constexpr unsigned DEFAULT_THREADS = 6; static constexpr unsigned DEFAULT_THREADS = 6;
friend class FOOTPRINT_LIST;
friend class FOOTPRINT_LIST_IMPL;
FOOTPRINT_LIST* m_list;
std::string m_last_table;
int m_total_libs;
}; };

129
include/fp_lib_table.h
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2012-2017 Wayne Stambaugh <stambaughw@verizon.net> * Copyright (C) 2012-2020 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 2012-2017 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2012-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -34,15 +34,11 @@ class FP_LIB_TABLE_GRID;
/** /**
* FP_LIB_TABLE_ROW * Hold a record identifying a library accessed by the appropriate footprint library #PLUGIN
*
* holds a record identifying a library accessed by the appropriate footprint library #PLUGIN
* object in the #FP_LIB_TABLE. * object in the #FP_LIB_TABLE.
*/ */
class FP_LIB_TABLE_ROW : public LIB_TABLE_ROW class FP_LIB_TABLE_ROW : public LIB_TABLE_ROW
{ {
friend class FP_LIB_TABLE;
public: public:
typedef IO_MGR::PCB_FILE_T LIB_T; typedef IO_MGR::PCB_FILE_T LIB_T;
@ -63,16 +59,12 @@ public:
bool operator!=( const FP_LIB_TABLE_ROW& aRow ) const { return !( *this == aRow ); } bool operator!=( const FP_LIB_TABLE_ROW& aRow ) const { return !( *this == aRow ); }
/** /**
* Function GetType * return the type of footprint library table represented by this row.
*
* returns the type of footprint library table represented by this row.
*/ */
const wxString GetType() const override { return IO_MGR::ShowType( type ); } const wxString GetType() const override { return IO_MGR::ShowType( type ); }
/** /**
* Function SetType * Change the type represented by this row.
*
* changes the type represented by this row.
*/ */
void SetType( const wxString& aType ) override; void SetType( const wxString& aType ) override;
@ -84,7 +76,6 @@ protected:
} }
private: private:
virtual LIB_TABLE_ROW* do_clone() const override virtual LIB_TABLE_ROW* do_clone() const override
{ {
return new FP_LIB_TABLE_ROW( *this ); return new FP_LIB_TABLE_ROW( *this );
@ -95,6 +86,8 @@ private:
plugin.set( aPlugin ); plugin.set( aPlugin );
} }
friend class FP_LIB_TABLE;
PLUGIN::RELEASER plugin; PLUGIN::RELEASER plugin;
LIB_T type; LIB_T type;
}; };
@ -102,8 +95,6 @@ private:
class FP_LIB_TABLE : public LIB_TABLE class FP_LIB_TABLE : public LIB_TABLE
{ {
friend class FP_LIB_TABLE_GRID;
public: public:
KICAD_T Type() override { return FP_LIB_TABLE_T; } KICAD_T Type() override { return FP_LIB_TABLE_T; }
@ -112,42 +103,36 @@ public:
virtual void Format( OUTPUTFORMATTER* aOutput, int aIndentLevel ) const override; virtual void Format( OUTPUTFORMATTER* aOutput, int aIndentLevel ) const override;
/** /**
* Constructor FP_LIB_TABLE * Build a footprint library table by pre-pending this table fragment in front of
*
* builds a footprint library table by pre-pending this table fragment in front of
* @a aFallBackTable. Loading of this table fragment is done by using Parse(). * @a aFallBackTable. Loading of this table fragment is done by using Parse().
* *
* @param aFallBackTable is another FP_LIB_TABLE which is searched only when * @param aFallBackTable is another FP_LIB_TABLE which is searched only when a row
* a row is not found in this table. No ownership is * is not found in this table. No ownership is taken of
* taken of aFallBackTable. * \a aFallBackTable.
*/ */
FP_LIB_TABLE( FP_LIB_TABLE* aFallBackTable = NULL ); FP_LIB_TABLE( FP_LIB_TABLE* aFallBackTable = nullptr );
bool operator==( const FP_LIB_TABLE& aFpTable ) const; bool operator==( const FP_LIB_TABLE& aFpTable ) const;
bool operator!=( const FP_LIB_TABLE& r ) const { return !( *this == r ); } bool operator!=( const FP_LIB_TABLE& r ) const { return !( *this == r ); }
/** /**
* Function FindRow * Return an #FP_LIB_TABLE_ROW if \a aNickName is found in this table or in any chained
* fallBack table fragment.
* *
* returns an FP_LIB_TABLE_ROW if \a aNickName is found in this table or in any chained * The #PLUGIN is loaded and attached to the "plugin" field of the #FP_LIB_TABLE_ROW if
* fallBack table fragment. The #PLUGIN is loaded and attached to the "plugin" field * not already loaded.
* of the #FP_LIB_TABLE_ROW if not already loaded.
* *
* @throw IO_ERROR if \a aNickName cannot be found. * @throw IO_ERROR if \a aNickName cannot be found.
*/ */
const FP_LIB_TABLE_ROW* FindRow( const wxString& aNickName ); const FP_LIB_TABLE_ROW* FindRow( const wxString& aNickName );
//-----<PLUGIN API SUBSET, REBASED ON aNickname>---------------------------
/** /**
* Return a list of footprint names contained within the library given by @a aNickname. * Return a list of footprint names contained within the library given by @a aNickname.
* *
* @param aFootprintNames is the list to fill with the footprint names found in \a aNickname * @param aFootprintNames is the list to fill with the footprint names found in \a aNickname
*
* @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW. * @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW.
* @param aBestEfforts if true, don't throw on errors * @param aBestEfforts if true, don't throw on errors.
* *
* @throw IO_ERROR if the library cannot be found, or footprint cannot be loaded. * @throw IO_ERROR if the library cannot be found, or footprint cannot be loaded.
*/ */
@ -161,7 +146,6 @@ public:
long long GenerateTimestamp( const wxString* aNickname ); long long GenerateTimestamp( const wxString* aNickname );
/** /**
* Function PrefetchLib
* If possible, prefetches the specified library (e.g. performing downloads). Does not parse. * If possible, prefetches the specified library (e.g. performing downloads). Does not parse.
* Threadsafe. * Threadsafe.
* *
@ -174,15 +158,11 @@ public:
void PrefetchLib( const wxString& aNickname ); void PrefetchLib( const wxString& aNickname );
/** /**
* Function FootprintLoad * Load a footprint having @a aFootprintName from the library given by @a aNickname.
*
* loads a footprint having @a aFootprintName from the library given by @a aNickname.
*
* @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW
* *
* @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW.
* @param aFootprintName is the name of the footprint to load. * @param aFootprintName is the name of the footprint to load.
* * @return the footprint if found caller owns it, else NULL if not found.
* @return FOOTPRINT* - if found caller owns it, else NULL if not found.
* *
* @throw IO_ERROR if the library cannot be found or read. No exception * @throw IO_ERROR if the library cannot be found or read. No exception
* is thrown in the case where aFootprintName cannot be found. * is thrown in the case where aFootprintName cannot be found.
@ -190,24 +170,20 @@ public:
FOOTPRINT* FootprintLoad( const wxString& aNickname, const wxString& aFootprintName ); FOOTPRINT* FootprintLoad( const wxString& aNickname, const wxString& aFootprintName );
/** /**
* Function FootprintExists * Indicates whether or not the given footprint already exists in the given library.
*
* indicates whether or not the given footprint already exists in the given library.
*/ */
bool FootprintExists( const wxString& aNickname, const wxString& aFootprintName ); bool FootprintExists( const wxString& aNickname, const wxString& aFootprintName );
/** /**
* Function GetEnumeratedFootprint * A version of #FootprintLoad() for use after #FootprintEnumerate() for more efficient
* cache management.
* *
* a version of FootprintLoad() for use after FootprintEnumerate() for more efficient * The return value is const to allow it to return a reference to a cached item.
* cache management. Return value is const to allow it to return a reference to a cached
* item.
*/ */
const FOOTPRINT* GetEnumeratedFootprint( const wxString& aNickname, const FOOTPRINT* GetEnumeratedFootprint( const wxString& aNickname,
const wxString& aFootprintName ); const wxString& aFootprintName );
/** /**
* Enum SAVE_T * The set of return values from FootprintSave() below.
* is the set of return values from FootprintSave() below.
*/ */
enum SAVE_T enum SAVE_T
{ {
@ -216,20 +192,16 @@ public:
}; };
/** /**
* Function FootprintSave * Write @a aFootprint to an existing library given by @a aNickname.
* *
* will write @a aFootprint to an existing library given by @a aNickname.
* If a footprint by the same name already exists, it is replaced. * If a footprint by the same name already exists, it is replaced.
* *
* @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW * @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW.
*
* @param aFootprint is what to store in the library. The caller continues to own the * @param aFootprint is what to store in the library. The caller continues to own the
* footprint after this call. * footprint after this call.
*
* @param aOverwrite when true means overwrite any existing footprint by the same name, * @param aOverwrite when true means overwrite any existing footprint by the same name,
* else if false means skip the write and return SAVE_SKIPPED. * else if false means skip the write and return SAVE_SKIPPED.
* * @return #SAVE_OK or #SAVE_SKIPPED. If error saving, then #IO_ERROR is thrown.
* @return SAVE_T - SAVE_OK or SAVE_SKIPPED. If error saving, then IO_ERROR is thrown.
* *
* @throw IO_ERROR if there is a problem saving. * @throw IO_ERROR if there is a problem saving.
*/ */
@ -237,12 +209,9 @@ public:
bool aOverwrite = true ); bool aOverwrite = true );
/** /**
* Function FootprintDelete * Delete the @a aFootprintName from the library given by @a aNickname.
*
* deletes the @a aFootprintName from the library given by @a aNickname.
*
* @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW.
* *
* @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW.
* @param aFootprintName is the name of a footprint to delete from the specified library. * @param aFootprintName is the name of a footprint to delete from the specified library.
* *
* @throw IO_ERROR if there is a problem finding the footprint or the library, or deleting it. * @throw IO_ERROR if there is a problem finding the footprint or the library, or deleting it.
@ -250,10 +219,9 @@ public:
void FootprintDelete( const wxString& aNickname, const wxString& aFootprintName ); void FootprintDelete( const wxString& aNickname, const wxString& aFootprintName );
/** /**
* Function IsFootprintLibWritable * Return true if the library given by @a aNickname is writable.
* *
* returns true if the library given by @a aNickname is writable. (Often * Often system libraries are read only because of where they are installed.
* system libraries are read only because of where they are installed.)
* *
* @throw IO_ERROR if no library at aLibraryPath exists. * @throw IO_ERROR if no library at aLibraryPath exists.
*/ */
@ -263,25 +231,20 @@ public:
void FootprintLibCreate( const wxString& aNickname ); void FootprintLibCreate( const wxString& aNickname );
//-----</PLUGIN API SUBSET, REBASED ON aNickname>---------------------------
/** /**
* Function FootprintLoadWithOptionalNickname * Load a footprint having @a aFootprintId with possibly an empty nickname.
* loads a footprint having @a aFootprintId with possibly an empty nickname.
* *
* @param aFootprintId the [nickname] & footprint name of the footprint to load. * @param aFootprintId the [nickname] and footprint name of the footprint to load.
* @return the #FOOTPRINT if found caller owns it, else NULL if not found.
* *
* @return FOOTPRINT* - if found caller owns it, else NULL if not found. * @throw IO_ERROR if the library cannot be found or read. No exception is
* * thrown in the case where \a aFootprintName cannot be found.
* @throw IO_ERROR if the library cannot be found or read. No exception
* is thrown in the case where aFootprintName cannot be found.
* @throw PARSE_ERROR if @a aFootprintId is not parsed OK. * @throw PARSE_ERROR if @a aFootprintId is not parsed OK.
*/ */
FOOTPRINT* FootprintLoadWithOptionalNickname( const LIB_ID& aFootprintId ); FOOTPRINT* FootprintLoadWithOptionalNickname( const LIB_ID& aFootprintId );
/** /**
* Function LoadGlobalTable * Load the global footprint library table into \a aTable.
* loads the global footprint library table into \a aTable.
* *
* This probably should be move into the application object when KiCad is changed * This probably should be move into the application object when KiCad is changed
* to a single process application. This is the least painful solution for the * to a single process application. This is the least painful solution for the
@ -295,22 +258,22 @@ public:
static bool LoadGlobalTable( FP_LIB_TABLE& aTable ); static bool LoadGlobalTable( FP_LIB_TABLE& aTable );
/** /**
* Function GetGlobalTableFileName
*
* @return the platform specific global footprint library path and file name. * @return the platform specific global footprint library path and file name.
*/ */
static wxString GetGlobalTableFileName(); static wxString GetGlobalTableFileName();
/** /**
* Function GlobalPathEnvVarVariableName * Return the name of the environment variable used to hold the directory of
* locally installed "KiCad sponsored" system footprint libraries.
* *
* returns the name of the environment variable used to hold the directory of *These can be either legacy or pretty format. The only thing special about this
* locally installed "KiCad sponsored" system footprint libraries. These can * particular environment variable is that it is set automatically by KiCad on
* be either legacy or pretty format. The only thing special about this * program start up, <b>if</b> it is not set already in the environment.
* particular environment variable is that it is set automatically by
* KiCad on program start up, <b>if</b> it is not set already in the environment.
*/ */
static const wxString GlobalPathEnvVariableName(); static const wxString GlobalPathEnvVariableName();
private:
friend class FP_LIB_TABLE_GRID;
}; };

6
include/frame_type.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2014 CERN * Copyright (C) 2014 CERN
* Copyright (C) 1992-2017 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* @author Maciej Suminski <maciej.suminski@cern.ch> * @author Maciej Suminski <maciej.suminski@cern.ch>
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
@ -27,9 +27,7 @@
#define FRAME_T_H_ #define FRAME_T_H_
/** /**
* Enum FRAME_T * The set of #EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident.
* is the set of EDA_BASE_FRAME derivatives, typically stored in
* EDA_BASE_FRAME::m_Ident.
*/ */
enum FRAME_T enum FRAME_T
{ {

254
include/gbr_metadata.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2018-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -23,9 +23,10 @@
*/ */
/** /**
* a class to handle special data (items attributes) during plot. * Handle special data (items attributes) during plot.
* used in Gerber plotter to generate auxiliary data during plot *
* (for instance info associated to apertures and flashed pads) * Used in Gerber plotter to generate auxiliary data during plot (for instance info associated
* to apertures and flashed pads)
* *
* @file gbr_metadata.h * @file gbr_metadata.h
*/ */
@ -35,18 +36,25 @@
#include <gbr_netlist_metadata.h> #include <gbr_netlist_metadata.h>
/** creates the TF.CreationDate attribute: /**
* The attribute value must conform to the full version of the ISO 8601 * Create a gerber TF.CreationDate attribute.
* date and time format, including time and time zone. Note that this is *
* the date the Gerber file is effectively created, * The attribute value must conform to the full version of the ISO 8601 date and time format,
* not the time the project of PCB was started * including time and time zone.
* @param aFormat = string compatibility: X1, X2, GBRJOB or NC drill synthax. *
* exemple of structured comment (compatible X1 gerber) * Example of structured comment (compatible X1 gerber)
* G04 #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (exemple of X1 attribute) * G04 #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (example of X1 attribute)
* exemple NC drill files *
* ; #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (exemple of NC drill comment) * Example NC drill files
* exemple of X2 attribute: * ; #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (example of NC drill comment)
*
* Example of X2 attribute:
* %TF.CreationDate,2018-11-06T08:25:24+01:00*% * %TF.CreationDate,2018-11-06T08:25:24+01:00*%
*
* @note This is the date the Gerber file is effectively created, not the time the project
* PCB was started.
*
* @param aFormat string compatibility: X1, X2, GBRJOB or NC drill syntax.
*/ */
enum GBR_NC_STRING_FORMAT // Options for string format in some attribute strings enum GBR_NC_STRING_FORMAT // Options for string format in some attribute strings
{ {
@ -58,11 +66,14 @@ enum GBR_NC_STRING_FORMAT // Options for string format in some attribute s
wxString GbrMakeCreationDateAttributeString( GBR_NC_STRING_FORMAT aFormat ); wxString GbrMakeCreationDateAttributeString( GBR_NC_STRING_FORMAT aFormat );
/** A helper function to build a project GUID using format RFC4122 Version 1 or 4 /**
* from the project name, because a kicad project has no specific GUID * Build a project GUID using format RFC4122 Version 1 or 4 from the project name, because
* a KiCad project has no specific GUID.
*
* RFC4122 is used mainly for its syntax, because fields have no meaning for Gerber files * RFC4122 is used mainly for its syntax, because fields have no meaning for Gerber files
* and therefore the GUID generated has no meaning because it do not use any time and time stamp * and therefore the GUID generated has no meaning because it do not use any time and time
* specific to the project, just a random pattern (random is here a pattern specific to a project). * stamp specific to the project, just a random pattern (random is here a pattern specific
* to a project).
* *
* See en.wikipedia.org/wiki/Universally_unique_identifier * See en.wikipedia.org/wiki/Universally_unique_identifier
*/ */
@ -79,41 +90,78 @@ class GBR_APERTURE_METADATA
public: public:
enum GBR_APERTURE_ATTRIB enum GBR_APERTURE_ATTRIB
{ {
GBR_APERTURE_ATTRIB_NONE, ///< uninitialized attribute GBR_APERTURE_ATTRIB_NONE, ///< uninitialized attribute.
GBR_APERTURE_ATTRIB_ETCHEDCMP, ///< aperture used for etched components GBR_APERTURE_ATTRIB_ETCHEDCMP, ///< aperture used for etched components.
GBR_APERTURE_ATTRIB_CONDUCTOR, ///< aperture used for connected items like tracks (not vias)
GBR_APERTURE_ATTRIB_EDGECUT, ///< aperture used for board cutout
GBR_APERTURE_ATTRIB_NONCONDUCTOR, ///< aperture used for not connected items (texts, outlines on copper)
GBR_APERTURE_ATTRIB_VIAPAD, ///< aperture used for vias
GBR_APERTURE_ATTRIB_COMPONENTPAD, ///< aperture used for through hole component on outer layer ///< aperture used for connected items like tracks (not vias).
GBR_APERTURE_ATTRIB_SMDPAD_SMDEF, ///< aperture used for SMD pad. Excluded BGA pads which have their own type GBR_APERTURE_ATTRIB_CONDUCTOR,
GBR_APERTURE_ATTRIB_SMDPAD_CUDEF, ///< aperture used for SMD pad with a solder mask defined by the solder mask GBR_APERTURE_ATTRIB_EDGECUT, ///< aperture used for board cutout,
GBR_APERTURE_ATTRIB_BGAPAD_SMDEF, ///< aperture used for BGA pads with a solder mask defined by the copper shape
GBR_APERTURE_ATTRIB_BGAPAD_CUDEF, ///< aperture used for BGA pad with a solder mask defined by the solder mask
GBR_APERTURE_ATTRIB_CONNECTORPAD, ///< aperture used for edge connector pad (outer layers)
GBR_APERTURE_ATTRIB_WASHERPAD, ///< aperture used for mechanical pads (NPTH)
GBR_APERTURE_ATTRIB_TESTPOINT, ///< aperture used for test point pad (outer layers)
GBR_APERTURE_ATTRIB_FIDUCIAL_GLBL, ///< aperture used for fiducial pad (outer layers), at board level
GBR_APERTURE_ATTRIB_FIDUCIAL_LOCAL, ///< aperture used for fiducial pad (outer layers), at footprint level
GBR_APERTURE_ATTRIB_HEATSINKPAD, ///< aperture used for heat sink pad (typically for SMDs)
GBR_APERTURE_ATTRIB_CASTELLATEDPAD, ///< aperture used for castellated pads in copper layer files
GBR_APERTURE_ATTRIB_CASTELLATEDDRILL, ///< aperture used for castellated pads in drill files
GBR_APERTURE_ATTRIB_VIADRILL, ///< aperture used for via holes in drill files ///< aperture used for not connected items (texts, outlines on copper).
GBR_APERTURE_ATTRIB_CMP_DRILL, ///< aperture used for pad holes in drill files GBR_APERTURE_ATTRIB_NONCONDUCTOR,
GBR_APERTURE_ATTRIB_CMP_OBLONG_DRILL, ///< aperture used for pads oblong holes in drill files GBR_APERTURE_ATTRIB_VIAPAD, ///< aperture used for vias.
GBR_APERTURE_ATTRIB_CMP_POSITION, ///< aperture used for flashed cmp position in placement files
GBR_APERTURE_ATTRIB_PAD1_POSITION, ///< aperture used for flashed pin 1 (or A1 or AA1) position in placement files ///< aperture used for through hole component on outer layer.
GBR_APERTURE_ATTRIB_PADOTHER_POSITION, ///< aperture used for flashed pads position in placement files GBR_APERTURE_ATTRIB_COMPONENTPAD,
GBR_APERTURE_ATTRIB_CMP_BODY, ///< aperture used to draw component physical body outline
///< (without pins) in placement files ///< aperture used for SMD pad. Excluded BGA pads which have their own type.
GBR_APERTURE_ATTRIB_CMP_LEAD2LEAD, ///< aperture used to draw component physical body outline GBR_APERTURE_ATTRIB_SMDPAD_SMDEF,
///< (with pins) in placement files
GBR_APERTURE_ATTRIB_CMP_FOOTPRINT, ///< aperture used to draw component footprint bounding box ///< aperture used for SMD pad with a solder mask defined by the solder mask.
///< in placement files GBR_APERTURE_ATTRIB_SMDPAD_CUDEF,
GBR_APERTURE_ATTRIB_CMP_COURTYARD, ///< aperture used to draw component outline courtyard
///< in placement files ///< aperture used for BGA pads with a solder mask defined by the copper shape.
GBR_APERTURE_ATTRIB_BGAPAD_SMDEF,
///< aperture used for BGA pad with a solder mask defined by the solder mask.
GBR_APERTURE_ATTRIB_BGAPAD_CUDEF,
///< aperture used for edge connector pad (outer layers).
GBR_APERTURE_ATTRIB_CONNECTORPAD,
GBR_APERTURE_ATTRIB_WASHERPAD, ///< aperture used for mechanical pads (NPTH).
GBR_APERTURE_ATTRIB_TESTPOINT, ///< aperture used for test point pad (outer layers).
///< aperture used for fiducial pad (outer layers), at board level.
GBR_APERTURE_ATTRIB_FIDUCIAL_GLBL,
///< aperture used for fiducial pad (outer layers), at footprint level.
GBR_APERTURE_ATTRIB_FIDUCIAL_LOCAL,
///< aperture used for heat sink pad (typically for SMDs).
GBR_APERTURE_ATTRIB_HEATSINKPAD,
///< aperture used for castellated pads in copper layer files.
GBR_APERTURE_ATTRIB_CASTELLATEDPAD,
///< aperture used for castellated pads in drill files.
GBR_APERTURE_ATTRIB_CASTELLATEDDRILL,
GBR_APERTURE_ATTRIB_VIADRILL, ///< aperture used for via holes in drill files.
GBR_APERTURE_ATTRIB_CMP_DRILL, ///< aperture used for pad holes in drill files.
///< aperture used for pads oblong holes in drill files.
GBR_APERTURE_ATTRIB_CMP_OBLONG_DRILL,
///< aperture used for flashed cmp position in placement files.
GBR_APERTURE_ATTRIB_CMP_POSITION,
///< aperture used for flashed pin 1 (or A1 or AA1) position in placement files.
GBR_APERTURE_ATTRIB_PAD1_POSITION,
///< aperture used for flashed pads position in placement files.
GBR_APERTURE_ATTRIB_PADOTHER_POSITION,
///< aperture used to draw component physical body outline without pins in placement files.
GBR_APERTURE_ATTRIB_CMP_BODY,
///< aperture used to draw component physical body outline with pins in placement files.
GBR_APERTURE_ATTRIB_CMP_LEAD2LEAD,
///< aperture used to draw component footprint bounding box in placement files.
GBR_APERTURE_ATTRIB_CMP_FOOTPRINT,
///< aperture used to draw component outline courtyard in placement files.
GBR_APERTURE_ATTRIB_CMP_COURTYARD,
GBR_APERTURE_ATTRIB_END ///< sentinel: max value GBR_APERTURE_ATTRIB_END ///< sentinel: max value
}; };
@ -122,7 +170,7 @@ public:
{} {}
/** /**
* @return the string corresponding to the aperture attribute * @return the string corresponding to the aperture attribute.
*/ */
static std::string GetAttributeName( GBR_APERTURE_ATTRIB aAttribute ); static std::string GetAttributeName( GBR_APERTURE_ATTRIB aAttribute );
std::string GetAttributeName() std::string GetAttributeName()
@ -131,12 +179,11 @@ public:
} }
/** /**
* @param aUseX1StructuredComment false in X2 mode and true in X1 mode to add the net
* attribute inside a compatible X1 structured comment
* starting by "G04 #@! "
* @return the full command string corresponding to the aperture attribute * @return the full command string corresponding to the aperture attribute
* like "%TA.AperFunction,<function>*%" * like "%TA.AperFunction,<function>*%"
* @param aUseX1StructuredComment = false in X2 mode,
* and true in X1 mode to add the net attribut
* inside a compatible X1 structured comment starting by "G04 #@! "
* like "G04 #@! TA.AperFunction,<function>*"
*/ */
static std::string FormatAttribute( GBR_APERTURE_ATTRIB aAttribute, static std::string FormatAttribute( GBR_APERTURE_ATTRIB aAttribute,
bool aUseX1StructuredComment ); bool aUseX1StructuredComment );
@ -150,9 +197,11 @@ public:
GBR_APERTURE_ATTRIB m_ApertAttribute; GBR_APERTURE_ATTRIB m_ApertAttribute;
}; };
// this class handle metadata which can be added in a gerber file as attribute
// in X2 format /**
class GBR_METADATA * Metadata which can be added in a gerber file as attribute in X2 format.
*/
class GBR_METADATA
{ {
public: public:
GBR_METADATA(): m_isCopper( false) {} GBR_METADATA(): m_isCopper( false) {}
@ -195,81 +244,82 @@ public:
} }
/** /**
* Allowed attributes are not the same on board copper layers and on other layers * Allowed attributes are not the same on board copper layers and on other layers.
* Therefore a flag can be set or reset when attributes can be depending on layers *
* A flag can be set or reset when attributes can be depending on layers
*/ */
bool IsCopper() { return m_isCopper; } bool IsCopper() { return m_isCopper; }
void SetCopper( bool aValue ) { m_isCopper = aValue; } void SetCopper( bool aValue ) { m_isCopper = aValue; }
/** /**
* a item to handle aperture attribute: * An item to handle aperture attribute.
*/ */
GBR_APERTURE_METADATA m_ApertureMetadata; GBR_APERTURE_METADATA m_ApertureMetadata;
/** /**
* a item to handle object attribute: * An item to handle object attribute.
*/ */
GBR_NETLIST_METADATA m_NetlistMetadata; GBR_NETLIST_METADATA m_NetlistMetadata;
private: private:
/** /**
* if the metadata is relative to a copper layer or not. This is a flag * If the metadata is relative to a copper layer or not, this flag which can be set/reset
* which can be set/reset when an attribute for a given item depends on the fact * when an attribute for a given item depends on whether a copper layer or a non copper
* a copper layer or a non copper layer is plotted. * layer is plotted. The initial state i false.
* The initial state in false.
*/ */
bool m_isCopper; bool m_isCopper;
}; };
/** /**
* This helper function "normalize" aString and convert it to a Gerber std::string * Normalize \a aString and convert it to a Gerber std::string.
* Normalisation means convert any code > 0x7F and unautorized code to a hexadecimal *
* 16 bits sequence unicode * Normalization means convert any code > 0x7F and unauthorized code to a hexadecimal
* unautorized codes are ',' '*' '%' '\' * 16 bit sequence Unicode. Illegal characters are ',' '*' '%' '\'.
* @param aString = the wxString to convert *
* @return a std::string (ASCII7 coded) compliant with a gerber string * @param aString the string to convert.
* @return an ASCII7 coded compliant gerber string.
*/ */
std::string FormatStringToGerber( const wxString& aString ); std::string FormatStringToGerber( const wxString& aString );
/** /**
* Similar to FormatStringToGerber. * Normalize \a aString and convert it to a Gerber compatible wxString.
* "normalize" aString and convert it to a Gerber compatible wxString *
* Normalisation means unautorized code to a hexadecimal 16 bits sequence unicode * Normalization means convert to a hexadecimal 16 bit sequence Unicode and on request
* and, on request convert any code > 0x7F. * convert any code > 0x7F. Illegal characters are ',' '*' '%' '\'.
* unautorized codes are ',' '*' '%' '\' *
* @param aString = the wxString to convert * @param aString the string to convert.
* @param aAllowUtf8Chars = false to convert non ASCII7 values to unicode sequence * @param aAllowUtf8Chars false to convert non ASCII7 values to Unicode sequence.
* @param aQuoteString = true to double quote the returned string * @param aQuoteString true to double quote the returned string.
* @return a wxString without unautorized chars (and converted non ASCII7 chars on request) * @return a without illegal chars (and converted non ASCII7 chars on request)
*/ */
wxString ConvertNotAllowedCharsInGerber( const wxString& aString, bool aAllowUtf8Chars, bool aQuoteString ); wxString ConvertNotAllowedCharsInGerber( const wxString& aString, bool aAllowUtf8Chars,
bool aQuoteString );
/** /**
* This helper function make the inverse conversion of FormatStringToGerber() * Convert a gerber string into a 16 bit Unicode string.
* It converts a "normalized" gerber string and convert it to a 16 bits sequence unicode *
* @param aString = the wxString compliant with a gerber string format * @param aString the gerber string to format.
* @return a wxString (unicode 16) from the gerber string * @return a 16 bit Unicode string.
*/ */
wxString FormatStringFromGerber( const wxString& aString ); wxString FormatStringFromGerber( const wxString& aString );
/** /**
* Generates the string to print to a gerber file, to set a net attribute * Generate the string to set a net attribute for a graphic object to print to a gerber file.
* for a graphic object. *
* @param aPrintedText is the string to print * @param aPrintedText is the string to print.
* @param aLastNetAttributes is the current full set of attributes. * @param aLastNetAttributes is the current full set of attributes.
* @param aData is the GBR_NETLIST_METADATA associated to the graphic object (can be NULL * @param aData is the #GBR_NETLIST_METADATA associated to the graphic object (can be NULL
* if no associated metadata, and aClearPreviousAttributes will be set to false) * if no associated metadata, and aClearPreviousAttributes will be set to false)
* @param aClearPreviousAttributes returns true if the full set of attributes * @param aClearPreviousAttributes returns true if the full set of attributes must be deleted
* must be deleted from file before adding new attribute (happens when a previous * from file before adding new attribute (happens when a previous
* attribute does not exist no more). * attribute no longer exists).
* @param aUseX1StructuredComment = false in X2 mode, and true in X1 mode to add the net attribut * @param aUseX1StructuredComment false in X2 mode and true in X1 mode to add the net attribute
* in compatible X1 structured comment (i.e. prefixed by "G04 #@! ") * in compatible X1 structured comment (i.e. prefixed by "G04 #@! ")
* @return false if nothing can be done (GBR_NETLIST_METADATA has GBR_APERTURE_ATTRIB_NONE, * @return false if nothing can be done (GBR_NETLIST_METADATA has GBR_APERTURE_ATTRIB_NONE,
* and true if OK * and true if OK. If the new attribute(s) is the same as current attribute(s),
* if the new attribute(s) is the same as current attribute(s), aPrintedText * \a aPrintedText will be empty.
* will be empty
*/ */
bool FormatNetAttribute( std::string& aPrintedText, std::string& aLastNetAttributes, bool FormatNetAttribute( std::string& aPrintedText, std::string& aLastNetAttributes,
const GBR_NETLIST_METADATA* aData, bool& aClearPreviousAttributes, const GBR_NETLIST_METADATA* aData, bool& aClearPreviousAttributes,

142
include/gbr_netlist_metadata.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2016 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2016 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -25,9 +25,10 @@
#ifndef GBR_NETLIST_METADATA_H #ifndef GBR_NETLIST_METADATA_H
#define GBR_NETLIST_METADATA_H #define GBR_NETLIST_METADATA_H
/** this class handle info which can be added in a gerber P&P file as attribute /**
* of a component * Information which can be added in a gerber P&P file as attribute of a component.
* Only applicable to objects having the TA.AperFunction attribute "ComponentMain" *
* This is only applicable to objects having the TA.AperFunction attribute "ComponentMain"
* There are specific attributes defined attached to the component by the %TO command * There are specific attributes defined attached to the component by the %TO command
* %TO.CRot,<angle> The rotation angle of the component. * %TO.CRot,<angle> The rotation angle of the component.
* The rotation angle is consistent with the one for graphics objects. * The rotation angle is consistent with the one for graphics objects.
@ -37,6 +38,7 @@
* Components on the bottom side are of course mirrored. * Components on the bottom side are of course mirrored.
* The base orientation on the bottom side is the one on the top side * The base orientation on the bottom side is the one on the top side
* mirrored around the X axis. * mirrored around the X axis.
*
* %TO.CMfr,<string> Manufacturer * %TO.CMfr,<string> Manufacturer
* %TO.CMPN,<string> Manufacturer part number * %TO.CMPN,<string> Manufacturer part number
* %TO.Cpkg,<string> Package, as per IPC-7351 * %TO.Cpkg,<string> Package, as per IPC-7351
@ -49,8 +51,8 @@
* %TO.CHgt,<string> Height, a decimal, in the unit of the file. * %TO.CHgt,<string> Height, a decimal, in the unit of the file.
* %TO.CLbN,<string> Library name. * %TO.CLbN,<string> Library name.
* %TO.CLbD,<string> Library description. * %TO.CLbD,<string> Library description.
* %TO.Sup,<SN>,<SPN> SN is a field with the supppier name. * %TO.Sup,<SN>,<SPN> SN is a field with the supplier name.
* SPN is a field with the supppier part name * SPN is a field with the supplier part name.
*/ */
class GBR_CMP_PNP_METADATA class GBR_CMP_PNP_METADATA
{ {
@ -62,6 +64,19 @@ public:
MOUNT_TYPE_TH MOUNT_TYPE_TH
}; };
GBR_CMP_PNP_METADATA() :
m_Orientation( 0.0 ),
m_MountType( MOUNT_TYPE_UNSPECIFIED )
{}
void ClearData(); // Clear all strings
/**
* @return a string containing the formatted metadata in X2 syntax.
*/
wxString FormatCmpPnPMetadata();
double m_Orientation; // orientation in degree double m_Orientation; // orientation in degree
wxString m_Manufacturer; // Manufacturer name wxString m_Manufacturer; // Manufacturer name
wxString m_MPN; // Manufacturer part number wxString m_MPN; // Manufacturer part number
@ -71,26 +86,15 @@ public:
wxString m_LibraryDescr; // Library description wxString m_LibraryDescr; // Library description
wxString m_Value; // Component value wxString m_Value; // Component value
MOUNT_TYPE m_MountType; // SMD|TH|Other MOUNT_TYPE m_MountType; // SMD|TH|Other
GBR_CMP_PNP_METADATA() :
m_Orientation( 0.0 ), m_MountType( MOUNT_TYPE_UNSPECIFIED )
{}
void ClearData(); // Clear all strings
/**
* @return a string containing the formated metadata in X2 syntax.
* one line by non empty data
* the orientation is always generated
*/
wxString FormatCmpPnPMetadata();
}; };
/** /**
* This class handle a Gerber data field. * A Gerber data field.
* this is a unicode string with some chars converted in escaped Hexa sequence *
* when creating the file * This is a Unicode string with some chars converted in escaped hexadecimal sequence
* Chars always escaped because they are separator in Gerber files: * , \ % * when creating the file. The following characters are always escaped because they
* non ascii 7 chars can be converted to UTF8 or escaped. * are separator in Gerber files: * , \ %. Non ASCII7 characters can be converted to
* UTF8 or escaped.
*/ */
class GBR_DATA_FIELD class GBR_DATA_FIELD
{ {
@ -120,28 +124,27 @@ public:
std::string GetGerberString() const; std::string GetGerberString() const;
private: private:
wxString m_field; ///< the unicade text to print in Gbr file wxString m_field; ///< the Unicode text to print in Gbr file
///< (after escape and quoting) ///< (after escape and quoting)
bool m_useUTF8; ///< true to use UTF8, false to escape non ascii7 chars bool m_useUTF8; ///< true to use UTF8, false to escape non ASCII7 chars
bool m_escapeString; ///< true to quote the field in gbr file bool m_escapeString; ///< true to quote the field in gbr file
}; };
/** this class handle info which can be added in a gerber file as attribute /**
* of an object * Information which can be added in a gerber file as attribute of an object.
* the GBR_INFO_TYPE types can be OR'ed to add 2 (or more) attributes *
* There are only 3 net attributes defined attached to an object by the %TO command * The #GBR_INFO_TYPE types can be OR'ed to add 2 (or more) attributes. There are only 3
* %TO.P * net attributes defined attached to an object by the %TO command:
* %TO.N * - %TO.P
* %TO.C * - %TO.N
* the .P attribute can be used only for flashed pads (using the D03 command) * - %TO.C
* and only for external copper layers, if the component is on a external copper layer *
* for other copper layer items (pads on internal layers, tracks ... ), only .N and .C * The .P attribute can be used only for flashed pads (using the D03 command) and only for
* can be used * external copper layers, if the component is on a external copper layer for other copper
* layer items (pads on internal layers, tracks ... ), only .N and .C can be used.
*/ */
class GBR_NETLIST_METADATA class GBR_NETLIST_METADATA
{ {
public: public:
@ -156,40 +159,21 @@ public:
GBR_NETINFO_CMP = 4 ///< print info associated to a component (TO.C attribute) GBR_NETINFO_CMP = 4 ///< print info associated to a component (TO.C attribute)
}; };
// these members are used in the %TO object attributes command.
int m_NetAttribType; ///< the type of net info
///< (used to define the gerber string to create)
bool m_NotInNet; ///< true if a pad of a footprint cannot be connected
///< (for instance a mechanical NPTH, ot a not named pad)
///< in this case the pad net name is empty in gerber file
GBR_DATA_FIELD m_Padname; ///< for a flashed pad: the pad name ((TO.P attribute)
GBR_DATA_FIELD m_PadPinFunction; ///< for a pad: the pin function (defined in schematic)
wxString m_Cmpref; ///< the component reference parent of the data
wxString m_Netname; ///< for items associated to a net: the netname
wxString m_ExtraData; ///< a string to print after %TO object attributes, if not empty
///< it is printed "as this"
/** If true, do not clear all attributes when a atribute has changed
* Usefull when some attributes need to be persistant.
* If false, attributes will be cleared if only one attribute cleared
* This is a more secure way to set attributes, when all attribute changess are not safely managed
*/
bool m_TryKeepPreviousAttributes;
GBR_NETLIST_METADATA(): m_NetAttribType( GBR_NETINFO_UNSPECIFIED ), GBR_NETLIST_METADATA(): m_NetAttribType( GBR_NETINFO_UNSPECIFIED ),
m_NotInNet( false ), m_TryKeepPreviousAttributes( false ) m_NotInNet( false ), m_TryKeepPreviousAttributes( false )
{ {
} }
/** Clear the extra data string printed at end of net attributes /**
* Clear the extra data string printed at end of net attributes.
*/ */
void ClearExtraData() void ClearExtraData()
{ {
m_ExtraData.Clear(); m_ExtraData.Clear();
} }
/** Set the extra data string printed at end of net attributes /**
* Set the extra data string printed at end of net attributes
*/ */
void SetExtraData( const wxString& aExtraData) void SetExtraData( const wxString& aExtraData)
{ {
@ -197,9 +181,11 @@ public:
} }
/** /**
* remove the net attribute specified by aName * Remove the net attribute specified by \a aName.
* If aName == NULL or empty, remove all attributes *
* @param aName is the name (.CN, .P .N or .C) of the attribute to remove * If aName == NULL or empty, remove all attributes.
*
* @param aName is the name (.CN, .P .N or .C) of the attribute to remove.
*/ */
void ClearAttribute( const wxString* aName ) void ClearAttribute( const wxString* aName )
{ {
@ -244,11 +230,33 @@ public:
return; return;
} }
} }
// these members are used in the %TO object attributes command.
int m_NetAttribType; ///< the type of net info
///< (used to define the gerber string to create)
bool m_NotInNet; ///< true if a pad of a footprint cannot be connected
///< (for instance a mechanical NPTH, ot a not named pad)
///< in this case the pad net name is empty in gerber file
GBR_DATA_FIELD m_Padname; ///< for a flashed pad: the pad name ((TO.P attribute)
GBR_DATA_FIELD m_PadPinFunction; ///< for a pad: the pin function (defined in schematic)
wxString m_Cmpref; ///< the component reference parent of the data
wxString m_Netname; ///< for items associated to a net: the netname
wxString m_ExtraData; ///< a string to print after %TO object attributes, if not empty
///< it is printed "as this"
/**
* If true, do not clear all attributes when a attribute has changed. This is useful
* when some attributes need to be persistent. If false, attributes will be cleared
* if only one attribute cleared. This is a more secure way to set attributes, when
* all attribute changes are not safely managed.
*/
bool m_TryKeepPreviousAttributes;
}; };
// Flashed pads use the full attribute set: this is a helper for flashed pads // Flashed pads use the full attribute set: this is a helper for flashed pads
#define GBR_NETINFO_ALL (GBR_NETLIST_METADATA::GBR_NETINFO_PAD\ #define GBR_NETINFO_ALL \
| GBR_NETLIST_METADATA::GBR_NETINFO_NET\ ( GBR_NETLIST_METADATA::GBR_NETINFO_PAD | GBR_NETLIST_METADATA::GBR_NETINFO_NET \
| GBR_NETLIST_METADATA::GBR_NETINFO_CMP ) | GBR_NETLIST_METADATA::GBR_NETINFO_CMP )
#endif // GBR_NETLIST_METADATA_H #endif // GBR_NETLIST_METADATA_H

61
include/gestfich.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2009-2014 Jerry Jacobs * Copyright (C) 2009-2014 Jerry Jacobs
* Copyright (C) 1992-2017 KiCad Developers, see CHANGELOG.TXT for contributors. * Copyright (C) 1992-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -48,10 +48,10 @@ class EDA_LIST_DIALOG;
/** /**
* Function OpenPDF * Run the PDF viewer and display a PDF file.
* run the PDF viewer and display a PDF file *
* @param file = PDF file to open * @param file the PDF file to open.
* @return true is success, false if no PDF viewer found * @return true is success or false if no PDF viewer found.
*/ */
bool OpenPDF( const wxString& file ); bool OpenPDF( const wxString& file );
void OpenFile( const wxString& file ); void OpenFile( const wxString& file );
@ -60,17 +60,14 @@ void PrintFile( const wxString& file );
bool CanPrintFile( const wxString& file ); bool CanPrintFile( const wxString& file );
/** /**
* Function CopyFile * @param aSrcPath is the full filename of the source.
* @param aSrcPath is the full filename of the source
* @param aDestPath is the full filename of the target * @param aDestPath is the full filename of the target
* @param aErrors a wxString to *append* any errors to * @param aErrors a wxString to *append* any errors to
*/ */
void KiCopyFile( const wxString& aSrcPath, const wxString& aDestPath, wxString& aErrors ); void KiCopyFile( const wxString& aSrcPath, const wxString& aDestPath, wxString& aErrors );
/** /**
* Function EDA_FILE_SELECTOR * A helper function that wraps a call to wxFileSelector.
*
* is a helper function that wraps a call to wxFileSelector.
* *
* @param aTitle is a string to display in the dialog title bar. * @param aTitle is a string to display in the dialog title bar.
* @param aPath is a string contain the default path for the path dialog. * @param aPath is a string contain the default path for the path dialog.
@ -96,59 +93,57 @@ wxString EDA_FILE_SELECTOR( const wxString& aTitle,
int aStyle, int aStyle,
const bool aKeepWorkingDirectory, const bool aKeepWorkingDirectory,
const wxPoint& aPosition = wxDefaultPosition, const wxPoint& aPosition = wxDefaultPosition,
wxString* aMruPath = NULL ); wxString* aMruPath = nullptr );
EDA_LIST_DIALOG* GetFileNames( char* Directory, char* Mask ); EDA_LIST_DIALOG* GetFileNames( char* Directory, char* Mask );
/** /**
* Function ExecuteFile * Call the executable file \a ExecFile with the command line parameters \a param.
* calls the executable file \a ExecFile with the command line parameters \a param.
*/ */
int ExecuteFile( wxWindow* frame, const wxString& ExecFile, int ExecuteFile( wxWindow* frame, const wxString& ExecFile,
const wxString& param = wxEmptyString, wxProcess *callback = NULL ); const wxString& param = wxEmptyString, wxProcess* callback = nullptr );
/** /**
* Function AddDelimiterString
* Add un " to the start and the end of string (if not already done). * Add un " to the start and the end of string (if not already done).
* @param string = string to modify *
* @param string string to modify.
*/ */
void AddDelimiterString( wxString& string ); void AddDelimiterString( wxString& string );
/** /**
* Function KicadDatasPath * Return the data path common to KiCad.
* returns the data path common to KiCad. *
* If environment variable KICAD is defined (KICAD = path to kicad) * If environment variable KICAD is defined (KICAD = path to KiCad)
* Returns \<KICAD\> /; * Returns \<KICAD\> /;
* Otherwise returns \<path of binaries\> / (if "kicad" is in the path name) * Otherwise returns \<path of binaries\> / (if "kicad" is in the path name)
* Otherwise returns /usr /share/kicad/ * Otherwise returns /usr /share/kicad/
* *
* Note: * @note The \\ path separators are replaced by / (a la Unix).
* The \\ are replaced by / (a la Unix)
*/ */
wxString KicadDatasPath(); wxString KicadDatasPath();
/** /**
* Function FindKicadFile * Search the executable file shortname in KiCad binary path and return full file
* searches the executable file shortname in KiCad binary path and return full file
* name if found or shortname if the kicad binary path is kicad/bin. * name if found or shortname if the kicad binary path is kicad/bin.
* *
* kicad binary path is found from: * The binary path is found from:
* BinDir * - binary path.
* or environment variable KICAD * - KICAD environment variable.
* or (default) c:\\kicad or /usr/local/kicad * - c:\\kicad or /usr/local/kicad (the default).
* or default binary path * - default binary path.
*/ */
wxString FindKicadFile( const wxString& shortname ); wxString FindKicadFile( const wxString& shortname );
/** /**
* Quote return value of wxFileName::GetFullPath(). * Quote return value of wxFileName::GetFullPath().
* *
* This allows file name paths with spaces to be used as parameters to * This allows file name paths with spaces to be used as parameters to ProcessExecute
* ProcessExecute function calls. * function calls.
* @param fn is the filename to wrap *
* @param format if provided, can be used to transform the nature of the * @param fn is the filename to wrap.
* wrapped filename to another platform. * @param format if provided, can be used to transform the nature of the wrapped filename
* to another platform.
*/ */
extern wxString QuoteFullPath( wxFileName& fn, wxPathFormat format = wxPATH_NATIVE ); extern wxString QuoteFullPath( wxFileName& fn, wxPathFormat format = wxPATH_NATIVE );

45
include/gl_context_mgr.h
View File

@ -2,6 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2016 CERN * Copyright (C) 2016 CERN
* Copyright (C) 2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* @author Maciej Suminski <maciej.suminski@cern.ch> * @author Maciej Suminski <maciej.suminski@cern.ch>
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
@ -33,51 +34,53 @@ class GL_CONTEXT_MANAGER
{ {
public: public:
/** /**
* Function Get * Return the GL_CONTEXT_MANAGER instance (singleton).
* returns the GL_CONTEXT_MANAGER instance (singleton).
*/ */
static GL_CONTEXT_MANAGER& Get(); static GL_CONTEXT_MANAGER& Get();
/** /**
* Function CreateCtx * Create a managed OpenGL context.
* creates a managed OpenGL context. It is assured that the created context is freed upon *
* exit. * It is assured that the created context is freed upon exit. See wxGLContext
* See wxGLContext documentation for the parameters description. * documentation for the parameters description.
*
* @return Created OpenGL context. * @return Created OpenGL context.
*/ */
wxGLContext* CreateCtx( wxGLCanvas* aCanvas, const wxGLContext* aOther = NULL ); wxGLContext* CreateCtx( wxGLCanvas* aCanvas, const wxGLContext* aOther = nullptr );
/** /**
* Function DestroyCtx * Destroy a managed OpenGL context.
* destroys a managed OpenGL context. The context to be removed has to be created using *
* GL_CONTEXT_MANAGER::CreateCtx() first. * The context to be removed has to be created using GL_CONTEXT_MANAGER::CreateCtx() first.
*
* @param aContext is the OpenGL context to be destroyed. It will not be managed anymore. * @param aContext is the OpenGL context to be destroyed. It will not be managed anymore.
*/ */
void DestroyCtx( wxGLContext* aContext ); void DestroyCtx( wxGLContext* aContext );
/** /**
* Function DeleteAll * Destroy all managed OpenGL contexts.
* destroys all managed OpenGL contexts. This method should be called in the *
* final deinitialization routine. * This method should be called in the final deinitialization routine.
*/ */
void DeleteAll(); void DeleteAll();
/** /**
* Function LockCtx * Set a context as current and prevents other canvases from switching it.
* sets a context as current and prevents other canvases from switching it. *
* Requires calling UnlockCtx() when there are no more GL calls for the context. * Requires calling UnlockCtx() when there are no more GL calls for the context. If
* If another canvas has already locked a GL context, then the calling process is blocked. * another canvas has already locked a GL context, then the calling process is blocked.
*
* @param aContext is the GL context to be bound. * @param aContext is the GL context to be bound.
* @param aCanvas (optional) allows caller to bind the context to a non-parent canvas * @param aCanvas (optional) allows caller to bind the context to a non-parent canvas
* (e.g. when a few canvases share a single GL context). * (e.g. when a few canvases share a single GL context).
*/ */
void LockCtx( wxGLContext* aContext, wxGLCanvas* aCanvas ); void LockCtx( wxGLContext* aContext, wxGLCanvas* aCanvas );
/** /**
* Function UnlockCtx * Allow other canvases to bind an OpenGL context.
* allows other canvases to bind an OpenGL context. *
* @param aContext is the currently bound context. It is only a check to assure the right * @param aContext is the currently bound context. It is only a check to assure the right
* canvas wants to unlock GL context. * canvas wants to unlock GL context.
*/ */
void UnlockCtx( wxGLContext* aContext ); void UnlockCtx( wxGLContext* aContext );

15
include/gl_utils.h
View File

@ -32,15 +32,16 @@ class GL_UTILS
{ {
public: public:
/** /**
* Attempts to set the OpenGL swap interval * Attempts to set the OpenGL swap interval.
* @param aVal if -1 = try to set adaptive swapping, 0 = sync off, 1 = sync with VSYNC rate *
* @param aVal if -1 = try to set adaptive swapping, 0 = sync off, 1 = sync with VSYNC rate.
* @return actual value set * @return actual value set
*/ */
static int SetSwapInterval( int aVal ) static int SetSwapInterval( int aVal )
{ {
/// This routine is written for Linux using X11 only. The equivalent functions under Windows would /// This routine is written for Linux using X11 only. The equivalent functions under
/// include <wglext.h> and call wglSwapIntervalEXT /// Windows would include <wglext.h> and call wglSwapIntervalEXT
#if defined( __linux__ ) && !defined( KICAD_USE_EGL ) #if defined( __linux__ ) && !defined( KICAD_USE_EGL )
Display *dpy = glXGetCurrentDisplay(); Display *dpy = glXGetCurrentDisplay();
GLXDrawable drawable = glXGetCurrentDrawable(); GLXDrawable drawable = glXGetCurrentDrawable();
@ -74,9 +75,9 @@ public:
} }
return std::numeric_limits<int>::max(); return std::numeric_limits<int>::max();
#else #else
return 0; return 0;
#endif #endif
} }
}; };

86
include/gr_basic.h
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2011 Wayne Stambaugh <stambaughw@verizon.net> * Copyright (C) 2011 Wayne Stambaugh <stambaughw@gmail.com>
* Copyright (C) 1992-2018 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software: you can redistribute it and/or modify it * This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the * under the terms of the GNU General Public License as published by the
@ -48,27 +48,27 @@ enum GR_DRAWMODE {
UNSPECIFIED_DRAWMODE = -1 UNSPECIFIED_DRAWMODE = -1
}; };
inline void DrawModeAddHighlight(GR_DRAWMODE *mode) inline void DrawModeAddHighlight( GR_DRAWMODE* mode )
{ {
*mode = static_cast<GR_DRAWMODE>( int( *mode ) | GR_HIGHLIGHT ); *mode = static_cast<GR_DRAWMODE>( int( *mode ) | GR_HIGHLIGHT );
} }
inline void DrawModeAllowHighContrast(GR_DRAWMODE *mode) inline void DrawModeAllowHighContrast( GR_DRAWMODE* mode )
{ {
*mode = static_cast<GR_DRAWMODE>( int( *mode ) | GR_ALLOW_HIGHCONTRAST ); *mode = static_cast<GR_DRAWMODE>( int( *mode ) | GR_ALLOW_HIGHCONTRAST );
} }
inline GR_DRAWMODE operator ~(const GR_DRAWMODE& a) inline GR_DRAWMODE operator~( const GR_DRAWMODE& a )
{ {
return static_cast<GR_DRAWMODE>( ~int( a ) ); return static_cast<GR_DRAWMODE>( ~int( a ) );
} }
inline GR_DRAWMODE operator |(const GR_DRAWMODE& a, const GR_DRAWMODE& b) inline GR_DRAWMODE operator|( const GR_DRAWMODE& a, const GR_DRAWMODE& b )
{ {
return static_cast<GR_DRAWMODE>( int( a ) | int( b ) ); return static_cast<GR_DRAWMODE>( int( a ) | int( b ) );
} }
inline GR_DRAWMODE operator &(const GR_DRAWMODE& a, const GR_DRAWMODE& b) inline GR_DRAWMODE operator&( const GR_DRAWMODE& a, const GR_DRAWMODE& b )
{ {
return static_cast<GR_DRAWMODE>( int( a ) & int( b ) ); return static_cast<GR_DRAWMODE>( int( a ) & int( b ) );
} }
@ -94,37 +94,35 @@ void GRSetColorPen( wxDC* DC, COLOR4D Color, int width = 1, wxPenStyle stype = w
void GRSetBrush( wxDC* DC, COLOR4D Color, bool fill = false ); void GRSetBrush( wxDC* DC, COLOR4D Color, bool fill = false );
/** /**
* Function GRForceBlackPen * @param flagforce True to force a black pen whenever the asked color.
* @param flagforce True to force a black pen whenever the asked color
*/ */
void GRForceBlackPen( bool flagforce ); void GRForceBlackPen( bool flagforce );
/** /**
* Function GetGRForceBlackPenState * @return True if a black pen was forced or false if not forced.
* @return ForceBlackPen (True if a black pen was forced)
*/ */
bool GetGRForceBlackPenState( void ); bool GetGRForceBlackPenState( void );
void GRLine( EDA_RECT* aClipBox, wxDC* aDC, void GRLine( EDA_RECT* aClipBox, wxDC* aDC, wxPoint aStart, wxPoint aEnd, int aWidth,
wxPoint aStart, wxPoint aEnd, int aWidth, COLOR4D aColor, wxPenStyle aStyle = wxPENSTYLE_SOLID ); COLOR4D aColor, wxPenStyle aStyle = wxPENSTYLE_SOLID );
void GRLine( EDA_RECT* ClipBox, wxDC* DC, void GRLine( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1, int x2, int y2, int width,
int x1, int y1, int x2, int y2, int width, COLOR4D Color, wxPenStyle aStyle = wxPENSTYLE_SOLID ); COLOR4D Color, wxPenStyle aStyle = wxPENSTYLE_SOLID );
void GRMoveTo( int x, int y ); void GRMoveTo( int x, int y );
void GRLineTo( EDA_RECT* ClipBox, wxDC* DC, void GRLineTo( EDA_RECT* ClipBox, wxDC* DC, int x, int y, int width, COLOR4D Color );
int x, int y, int width, COLOR4D Color );
void GRPoly( EDA_RECT* ClipBox, wxDC* DC, int n, const wxPoint* Points, bool Fill, int width, void GRPoly( EDA_RECT* ClipBox, wxDC* DC, int n, const wxPoint* Points, bool Fill, int width,
COLOR4D Color, COLOR4D BgColor ); COLOR4D Color, COLOR4D BgColor );
/** Draw cubic (4 points: start control1, control2, end) bezier curve /**
* Draw cubic (4 points: start control1, control2, end) bezier curve.
*/ */
void GRBezier( EDA_RECT* aClipBox, wxDC* aDC, std::vector<wxPoint>& aPoints, void GRBezier( EDA_RECT* aClipBox, wxDC* aDC, std::vector<wxPoint>& aPoints,
int aWidth, COLOR4D aColor ); int aWidth, COLOR4D aColor );
/** /**
* Function GRClosedPoly * Draw a closed polygon onto the drawing context \a aDC and optionally fills and/or draws
* draws a closed polygon onto the drawing context \a aDC and optionally fills * a border around it.
* and/or draws a border around it. *
* @param ClipBox defines a rectangular boundary outside of which no drawing will occur. * @param ClipBox defines a rectangular boundary outside of which no drawing will occur.
* @param aDC the device context into which drawing should occur. * @param aDC the device context into which drawing should occur.
* @param aPointCount the number of points in the array \a aPoints. * @param aPointCount the number of points in the array \a aPoints.
@ -134,15 +132,15 @@ void GRBezier( EDA_RECT* aClipBox, wxDC* aDC, std::vector<wxPoint>& aPoints,
* @param aFillColor the fill color of the polygon's interior. * @param aFillColor the fill color of the polygon's interior.
*/ */
void GRClosedPoly( EDA_RECT* ClipBox, wxDC* aDC, int aPointCount, const wxPoint* aPoints, void GRClosedPoly( EDA_RECT* ClipBox, wxDC* aDC, int aPointCount, const wxPoint* aPoints,
bool doFill, COLOR4D aPenColor, COLOR4D aFillColor ); bool doFill, COLOR4D aPenColor, COLOR4D aFillColor );
// @todo could make these 2 closed polygons calls a single function and default // @todo could make these 2 closed polygons calls a single function and default
// the aPenWidth argument // the aPenWidth argument
/** /**
* Function GRClosedPoly * Draw a closed polygon onto the drawing context \a aDC and optionally fills and/or draws
* draws a closed polygon onto the drawing context \a aDC and optionally fills * a border around it.
* and/or draws a border around it. *
* @param ClipBox defines a rectangular boundary outside of which no drawing will occur. * @param ClipBox defines a rectangular boundary outside of which no drawing will occur.
* @param aDC the device context into which drawing should occur. * @param aDC the device context into which drawing should occur.
* @param aPointCount the number of points in the array \a aPointArray. * @param aPointCount the number of points in the array \a aPointArray.
@ -153,20 +151,18 @@ void GRClosedPoly( EDA_RECT* ClipBox, wxDC* aDC, int aPointCount, const wxPoint*
* @param aFillColor the fill color of the polygon's interior. * @param aFillColor the fill color of the polygon's interior.
*/ */
void GRClosedPoly( EDA_RECT* ClipBox, wxDC* aDC, int aPointCount, const wxPoint* aPoints, void GRClosedPoly( EDA_RECT* ClipBox, wxDC* aDC, int aPointCount, const wxPoint* aPoints,
bool doFill, int aPenWidth, COLOR4D aPenColor, COLOR4D aFillColor ); bool doFill, int aPenWidth, COLOR4D aPenColor, COLOR4D aFillColor );
/** /**
* Function GRCircle * Draw a circle onto the drawing context \a aDC centered at the user coordinates (x,y).
* draws a circle onto the drawing context \a aDC centered at the user
* coordinates (x,y)
* *
* @param ClipBox defines a rectangular boundary outside of which no drawing will occur. * @param ClipBox defines a rectangular boundary outside of which no drawing will occur.
* @param aDC the device context into which drawing should occur. * @param aDC the device context into which drawing should occur.
* @param x The x coordinate in user space of the center of the circle. * @param x The x coordinate in user space of the center of the circle.
* @param y The y coordinate in user space of the center of the circle. * @param y The y coordinate in user space of the center of the circle.
* @param aRadius is the radius of the circle. * @param aRadius is the radius of the circle.
* @param aColor is the color to draw * @param aColor is the color to draw.
* @see COLOR4D * @see COLOR4D
*/ */
void GRCircle( EDA_RECT* ClipBox, wxDC* aDC, int x, int y, int aRadius, COLOR4D aColor ); void GRCircle( EDA_RECT* ClipBox, wxDC* aDC, int x, int y, int aRadius, COLOR4D aColor );
@ -174,7 +170,8 @@ void GRCircle( EDA_RECT* ClipBox, wxDC* DC, int x, int y, int r, int width, COL
void GRFilledCircle( EDA_RECT* ClipBox, wxDC* DC, int x, int y, int r, int width, void GRFilledCircle( EDA_RECT* ClipBox, wxDC* DC, int x, int y, int r, int width,
COLOR4D Color, COLOR4D BgColor ); COLOR4D Color, COLOR4D BgColor );
void GRFilledCircle( EDA_RECT* aClipBox, wxDC* aDC, wxPoint aPos, int aRadius, COLOR4D aColor ); void GRFilledCircle( EDA_RECT* aClipBox, wxDC* aDC, wxPoint aPos, int aRadius, COLOR4D aColor );
void GRCircle( EDA_RECT* aClipBox, wxDC* aDC, wxPoint aPos, int aRadius, int aWidth, COLOR4D aColor ); void GRCircle( EDA_RECT* aClipBox, wxDC* aDC, wxPoint aPos, int aRadius, int aWidth,
COLOR4D aColor );
void GRArc( EDA_RECT* ClipBox, wxDC* DC, int x, int y, double StAngle, void GRArc( EDA_RECT* ClipBox, wxDC* DC, int x, int y, double StAngle,
double EndAngle, int r, COLOR4D Color ); double EndAngle, int r, COLOR4D Color );
@ -190,7 +187,8 @@ void GRFilledArc( EDA_RECT* ClipBox, wxDC* DC, int x, int y,
double StAngle, double EndAngle, int r, COLOR4D Color, COLOR4D BgColor ); double StAngle, double EndAngle, int r, COLOR4D Color, COLOR4D BgColor );
void GRFilledArc( EDA_RECT* ClipBox, wxDC* DC, int x, int y, double StAngle, void GRFilledArc( EDA_RECT* ClipBox, wxDC* DC, int x, int y, double StAngle,
double EndAngle, int r, int width, COLOR4D Color, COLOR4D BgColor ); double EndAngle, int r, int width, COLOR4D Color, COLOR4D BgColor );
void GRCSegm( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1, int x2, int y2, int width, COLOR4D Color ); void GRCSegm( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1, int x2, int y2, int width,
COLOR4D Color );
void GRFillCSegm( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1, int x2, int y2, void GRFillCSegm( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1, int x2, int y2,
int width, COLOR4D Color ); int width, COLOR4D Color );
@ -221,25 +219,25 @@ void GRSFilledRect( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1,
int x2, int y2, int width, COLOR4D Color, COLOR4D BgColor ); int x2, int y2, int width, COLOR4D Color, COLOR4D BgColor );
/** /**
* Function GRLineArray * Draw an array of lines (not a polygon).
* draws an array of lines (not a polygon). *
* @param aClipBox = the clip box * @param aClipBox the clip box.
* @param aDC = the device context into which drawing should occur. * @param aDC the device context into which drawing should occur.
* @param aLines = a list of pair of coordinate in user space: a pair for each line. * @param aLines a list of pair of coordinate in user space: a pair for each line.
* @param aWidth = the width of each line. * @param aWidth the width of each line.
* @param aColor = the color of the lines * @param aColor the color of the lines.
* @see COLOR4D * @see COLOR4D
*/ */
void GRLineArray( EDA_RECT* aClipBox, wxDC* aDC,std::vector<wxPoint>& aLines, void GRLineArray( EDA_RECT* aClipBox, wxDC* aDC,std::vector<wxPoint>& aLines,
int aWidth, COLOR4D aColor ); int aWidth, COLOR4D aColor );
void GRDrawAnchor( EDA_RECT* aClipBox, wxDC *aDC, int x, int y, int aSize, void GRDrawAnchor( EDA_RECT* aClipBox, wxDC* aDC, int x, int y, int aSize, COLOR4D aColor );
COLOR4D aColor );
/** /**
* Draw text centered on a wxDC with wrapping. * Draw text centered on a wxDC with wrapping.
* @param aDC wxDC instance onto which the text will be drawn *
* @param aText the text to draw * @param aDC wxDC instance onto which the text will be drawn.
* @param aText the text to draw.
*/ */
void GRDrawWrappedText( wxDC& aDC, wxString const& aText ); void GRDrawWrappedText( wxDC& aDC, wxString const& aText );

110
include/gr_text.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2009-2014 Jerry Jacobs * Copyright (C) 2009-2014 Jerry Jacobs
* Copyright (C) 1992-2014 KiCad Developers, see CHANGELOG.TXT for contributors. * Copyright (C) 1992-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -34,11 +34,11 @@
#include <eda_item.h> #include <eda_item.h>
#include <eda_text.h> // EDA_TEXT_HJUSTIFY_T and EDA_TEXT_VJUSTIFY_T #include <eda_text.h> // EDA_TEXT_HJUSTIFY_T and EDA_TEXT_VJUSTIFY_T
/* Minimum dimension in pixel for drawing/no drawing a text /**
* used in Pcbnew to decide to draw (or not) some texts * Minimum dimension in pixel for drawing/no drawing a text used in Pcbnew to decide to
* ( like net names on pads/tracks ) * draw (or not) some texts ( like net names on pads/tracks ).
* When a text height is smaller than MIN_TEXT_SIZE, *
* it is not drawn by Pcbnew * When a text height is smaller than MIN_TEXT_SIZE, it is not drawn by Pcbnew.
*/ */
#define MIN_TEXT_SIZE 5 #define MIN_TEXT_SIZE 5
@ -51,85 +51,83 @@
class PLOTTER; class PLOTTER;
/** /**
* Function Clamp_Text_PenSize * As a rule, pen width should not be >1/4em, otherwise the character will be cluttered up in
*As a rule, pen width should not be >1/4em, otherwise the character * its own fatness.
* will be cluttered up in its own fatness *
* The pen width max is aSize/4 for bold texts, and aSize/6 for normal texts * The pen width max is aSize/4 for bold texts, and aSize/6 for normal texts. The "best" pen
* The "best" pen width is aSize/5 for bold texts, * width is aSize/5 for bold texts so the clamp is consistent with bold option.
* so the clamp is consistant with bold option. *
* @param aPenSize = the pen size to clamp * @param aPenSize the pen size to clamp.
* @param aSize the char size (height or width, od its wxSize) * @param aSize the char size (height or width, or its wxSize).
* @param aBold = true if text accept bold pen size * @param aBold true if text accept bold pen size.
* @return the max pen size allowed * @return the max pen size allowed.
*/ */
int Clamp_Text_PenSize( int aPenSize, int aSize, bool aBold = true ); int Clamp_Text_PenSize( int aPenSize, int aSize, bool aBold = true );
float Clamp_Text_PenSize( float aPenSize, int aSize, bool aBold = true ); float Clamp_Text_PenSize( float aPenSize, int aSize, bool aBold = true );
int Clamp_Text_PenSize( int aPenSize, wxSize aSize, bool aBold = true ); int Clamp_Text_PenSize( int aPenSize, wxSize aSize, bool aBold = true );
/** /**
* Function GetPensizeForBold * @param aTextSize the char size (height or width).
* @return the "best" value for a pen size to draw/plot a bold text * @return the "best" value for a pen size to draw/plot a bold text.
* @param aTextSize = the char size (height or width)
*/ */
int GetPenSizeForBold( int aTextSize ); int GetPenSizeForBold( int aTextSize );
/** /**
* Function GetPensizeForNormal * @param aTextSize = the char size (height or width).
* @return the "best" value for a pen size to draw/plot a non-bold text * @return the "best" value for a pen size to draw/plot a non-bold text.
* @param aTextSize = the char size (height or width)
*/ */
int GetPenSizeForNormal( int aTextSize ); int GetPenSizeForNormal( int aTextSize );
/** /**
* Function GraphicTextWidth * The full X size is GraphicTextWidth + the thickness of graphic lines.
* @return the X size of the graphic text *
* the full X size is GraphicTextWidth + the thickness of graphic lines * @return the X size of the graphic text.
*/ */
int GraphicTextWidth( const wxString& aText, const wxSize& aSize, bool italic, bool bold ); int GraphicTextWidth( const wxString& aText, const wxSize& aSize, bool italic, bool bold );
/** /**
* Function GRText
* Draw a graphic text (like footprint text) * Draw a graphic text (like footprint text)
* @param aClipBox = the clipping rect, or NULL if no clipping *
* @param aDC = the current Device Context. NULL if draw within a 3D GL Canvas * @param aClipBox the clipping rect, or NULL if no clipping.
* @param aPos = text position (according to h_justify, v_justify) * @param aDC the current Device Context. NULL if draw within a 3D GL Canvas.
* @param aColor (COLOR4D) = text color * @param aPos text position (according to h_justify, v_justify).
* @param aText = text to draw * @param aColor (COLOR4D) = text color.
* @param aOrient = angle in 0.1 degree * @param aText text to draw.
* @param aSize = text size (size.x or size.y can be < 0 for mirrored texts) * @param aOrient angle in 0.1 degree.
* @param aH_justify = horizontal justification (Left, center, right) * @param aSize text size (size.x or size.y can be < 0 for mirrored texts).
* @param aV_justify = vertical justification (bottom, center, top) * @param aH_justify horizontal justification (Left, center, right).
* @param aWidth = line width (pen width) (default = 0) * @param aV_justify vertical justification (bottom, center, top).
* if width < 0 : draw segments in sketch mode, width = abs(width) * @param aWidth line width (pen width) (default = 0). If width < 0 : draw segments in
* Use a value min(aSize.x, aSize.y) / 5 for a bold text * sketch mode, width = abs(width). Use a value min(aSize.x, aSize.y) / 5
* @param aItalic = true to simulate an italic font * for a bold text.
* @param aBold = true to use a bold font * @param aItalic true to simulate an italic font.
* @param aCallback( int x0, int y0, int xf, int yf, void* aData ) is a function called * @param aBold true to use a bold font.
* (if non null) to draw each segment. used to draw 3D texts or for plotting. * @param aCallback ( int x0, int y0, int xf, int yf, void* aData ) is a function called
* NULL for normal drawings * (if non null) to draw each segment. used to draw 3D texts or for plotting.
* @param aCallbackData = is the auxiliary parameter aData for the callback function. * NULL for normal drawings.
* can be nullptr if no auxiliary parameter is needed * @param aCallbackData is the auxiliary parameter aData for the callback function.
* This can be nullptr if no auxiliary parameter is needed.
* @param aPlotter = a pointer to a PLOTTER instance, when this function is used to plot * @param aPlotter = a pointer to a PLOTTER instance, when this function is used to plot
* the text. NULL to draw this text. * the text. NULL to draw this text.
*/ */
void GRText( wxDC * aDC, const wxPoint &aPos, COLOR4D aColor, const wxString &aText, void GRText( wxDC* aDC, const wxPoint& aPos, COLOR4D aColor, const wxString& aText,
double aOrient, const wxSize &aSize, enum EDA_TEXT_HJUSTIFY_T aH_justify, double aOrient, const wxSize& aSize, enum EDA_TEXT_HJUSTIFY_T aH_justify,
enum EDA_TEXT_VJUSTIFY_T aV_justify, int aWidth, bool aItalic, bool aBold, enum EDA_TEXT_VJUSTIFY_T aV_justify, int aWidth, bool aItalic, bool aBold,
void (*aCallback)( int x0, int y0, int xf, int yf, void* aData ) = nullptr, void (*aCallback)( int x0, int y0, int xf, int yf, void* aData ) = nullptr,
void* aCallbackData = nullptr, PLOTTER * aPlotter = nullptr ); void* aCallbackData = nullptr, PLOTTER* aPlotter = nullptr );
/** /**
* Draw graphic text with a border, so that it can be read on different * Draw graphic text with a border so that it can be read on different backgrounds.
* backgrounds. See GRText for most of the parameters. *
* If aBgColor is a dark color text is drawn in aColor2 with aColor1 * See GRText for most of the parameters. If \a aBgColor is a dark color text is drawn
* border; otherwise colors are swapped. * in \a aColor2 with \a aColor1 border. Otherwise colors are swapped.
*/ */
void GRHaloText( wxDC * aDC, const wxPoint &aPos, COLOR4D aBgColor, COLOR4D aColor1, void GRHaloText( wxDC* aDC, const wxPoint& aPos, COLOR4D aBgColor, COLOR4D aColor1,
COLOR4D aColor2, const wxString &aText, double aOrient, const wxSize &aSize, COLOR4D aColor2, const wxString& aText, double aOrient, const wxSize &aSize,
enum EDA_TEXT_HJUSTIFY_T aH_justify, enum EDA_TEXT_VJUSTIFY_T aV_justify, enum EDA_TEXT_HJUSTIFY_T aH_justify, enum EDA_TEXT_VJUSTIFY_T aV_justify,
int aWidth, bool aItalic, bool aBold, int aWidth, bool aItalic, bool aBold,
void (*aCallback)( int x0, int y0, int xf, int yf, void* aData ) = nullptr, void (*aCallback)( int x0, int y0, int xf, int yf, void* aData ) = nullptr,
void* aCallbackData = nullptr, PLOTTER * aPlotter = nullptr ); void* aCallbackData = nullptr, PLOTTER* aPlotter = nullptr );
#endif /* __INCLUDE__DRAWTXT_H__ */ #endif /* __INCLUDE__DRAWTXT_H__ */

24
include/grid_tricks.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2012 KiCad Developers, see change_log.txt for contributors. * Copyright (C) 2012-2020 KiCad Developers, see change_log.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -46,25 +46,14 @@ enum
/** /**
* GRID_TRICKS * Add mouse and command handling (such as cut, copy, and paste) to a #WX_GRID instance.
* is used to add mouse and command handling (such as cut, copy, and paste) to a WX_GRID instance.
*/ */
class GRID_TRICKS : public wxEvtHandler class GRID_TRICKS : public wxEvtHandler
{ {
public: public:
explicit GRID_TRICKS( WX_GRID* aGrid ); explicit GRID_TRICKS( WX_GRID* aGrid );
protected: protected:
WX_GRID* m_grid; ///< I don't own the grid, but he owns me
// row & col "selection" acquisition
// selected area by cell coordinate and count
int m_sel_row_start;
int m_sel_col_start;
int m_sel_row_count;
int m_sel_col_count;
/// Puts the selected area into a sensible rectangle of m_sel_{row,col}_{start,count} above. /// Puts the selected area into a sensible rectangle of m_sel_{row,col}_{start,count} above.
void getSelectedArea(); void getSelectedArea();
@ -87,6 +76,15 @@ protected:
virtual void paste_clipboard(); virtual void paste_clipboard();
virtual void paste_text( const wxString& cb_text ); virtual void paste_text( const wxString& cb_text );
virtual void cutcopy( bool doCut ); virtual void cutcopy( bool doCut );
WX_GRID* m_grid; ///< I don't own the grid, but he owns me
// row & col "selection" acquisition
// selected area by cell coordinate and count
int m_sel_row_start;
int m_sel_col_start;
int m_sel_row_count;
int m_sel_col_count;
}; };
#endif // _GRID_TRICKS_H_ #endif // _GRID_TRICKS_H_

75
include/hashtables.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2012 KiCad Developers, see CHANGELOG.TXT for contributors. * Copyright (C) 2012-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -31,7 +31,7 @@
// Two competing strategies for providing portable hashtables are given: // Two competing strategies for providing portable hashtables are given:
// std C++ and boost. // std C++ and boost.
// First some utility classes and functions common to both strategies.. // First some utility classes and functions common to both strategies.
/// Equality test for "const char*" type used in very specialized KEYWORD_MAP below /// Equality test for "const char*" type used in very specialized KEYWORD_MAP below
struct iequal_to : std::binary_function< const char*, const char*, bool > struct iequal_to : std::binary_function< const char*, const char*, bool >
@ -105,35 +105,41 @@ class NETINFO_ITEM;
#ifdef SWIG #ifdef SWIG
/// Declare a std::unordered_map and also the swig %template in unison /// Declare a std::unordered_map and also the swig %template in unison
#define DECL_HASH_FOR_SWIG(TypeName, KeyType, ValueType) namespace std { %template(TypeName) unordered_map<KeyType, ValueType>; } typedef std::unordered_map<KeyType, ValueType> TypeName; #define DECL_HASH_FOR_SWIG( TypeName, KeyType, ValueType ) \
namespace std \
{ \
% template( TypeName ) unordered_map<KeyType, ValueType>; \
} \
typedef std::unordered_map<KeyType, ValueType> TypeName;
#else #else
/// Declare a std::unordered_map but no swig %template /// Declare a std::unordered_map but no swig %template
#define DECL_HASH_FOR_SWIG(TypeName, KeyType, ValueType) typedef std::unordered_map<KeyType, ValueType> TypeName; #define DECL_HASH_FOR_SWIG( TypeName, KeyType, ValueType ) \
typedef std::unordered_map<KeyType, ValueType> TypeName;
#endif #endif
/** /**
* Type KEYWORD_MAP * A hashtable made of a const char* and an int.
* is a hashtable made of a const char* and an int. Note that use of this *
* type outside very specific circumstances is foolish since there is no storage * @note The use of this type outside very specific circumstances is foolish since there is
* provided for the actual C string itself. This type assumes use with type KEYWORD * no storage provided for the actual C string itself.
* that is created by CMake and that table creates *constant* storage for C strings *
* (and pointers to those C strings). Here we are only interested in the C strings * This type assumes use with type #KEYWORD that is created by CMake and that table creates
* themselves and only the pointers are duplicated within the hashtable. * *constant* storage for C strings (and pointers to those C strings). Here we are only
* If the strings were not constant and fixed, this type would not work. * interested in the C strings themselves and only the pointers are duplicated within the
* Also note that normally a hashtable (i.e. unordered_map) using a const char* key * hashtable. If the strings were not constant and fixed, this type would not work. Also
* would simply compare the 32 bit or 64 bit pointers themselves, rather than * note that normally a hashtable (i.e. unordered_map) using a const char* key would simply
* the C strings which they are known to point to in this context. * compare the 32 bit or 64 bit pointers themselves, rather than the C strings which they
* I force the latter behavior by supplying both "hash" and "equality" overloads * are known to point to in this context. I force the latter behavior by supplying both
* to the hashtable (unordered_map) template. * "hash" and "equality" overloads to the hashtable (unordered_map) template.
*
* @author Dick Hollenbeck * @author Dick Hollenbeck
*/ */
typedef std::unordered_map< const char*, int, fnv_1a, iequal_to > KEYWORD_MAP; typedef std::unordered_map< const char*, int, fnv_1a, iequal_to > KEYWORD_MAP;
/// Map a C string to an EDA_RECT. /// Map a C string to an EDA_RECT.
/// The key is the classname of the derived wxformbuilder dialog. /// The key is the classname of the derived wxformbuilder dialog.
typedef std::unordered_map< std::string, EDA_RECT > RECT_MAP; typedef std::unordered_map< std::string, EDA_RECT > RECT_MAP;
#elif 1 // boost::unordered_map #elif 1 // boost::unordered_map
@ -147,25 +153,26 @@ typedef std::unordered_map< std::string, EDA_RECT > RECT_MAP;
/** /**
* Type KEYWORD_MAP * A hashtable made of a const char* and an int.
* is a hashtable made of a const char* and an int. Note that use of this *
* type outside very specific circumstances is foolish since there is no storage * @note The use of this type outside very specific circumstances is foolish since there is
* provided for the actual C string itself. This type assumes use with type KEYWORD * no storage provided for the actual C string itself.
* that is created by CMake and that table creates *constant* storage for C strings *
* (and pointers to those C strings). Here we are only interested in the C strings * This type assumes use with type #KEYWORD that is created by CMake and that table creates
* themselves and only the pointers are duplicated within the hashtable. * *constant* storage for C strings (and pointers to those C strings). Here we are only
* If the strings were not constant and fixed, this type would not work. * interested in the C strings themselves and only the pointers are duplicated within the
* Also note that normally a hashtable (i.e. unordered_map) using a const char* key * hashtable. If the strings were not constant and fixed, this type would not work. Also
* would simply compare the 32 bit or 64 bit pointers themselves, rather than * note that normally a hashtable (i.e. unordered_map) using a const char* key would simply
* the C strings which they are known to point to in this context. * compare the 32 bit or 64 bit pointers themselves, rather than the C strings which they
* I force the latter behavior by supplying both "hash" and "equality" overloads * are known to point to in this context. I force the latter behavior by supplying both
* to the hashtable (unordered_map) template. * "hash" and "equality" overloads to the hashtable (unordered_map) template.
*
* @author Dick Hollenbeck * @author Dick Hollenbeck
*/ */
typedef boost::unordered_map< const char*, int, fnv_1a, iequal_to > KEYWORD_MAP; typedef boost::unordered_map< const char*, int, fnv_1a, iequal_to > KEYWORD_MAP;
/// Map a std::string to an EDA_RECT. /// Map a std::string to an #EDA_RECT.
/// The key is the classname of the derived wxformbuilder dialog. /// The key is the classname of the derived wxformbuilder dialog.
typedef boost::unordered_map< std::string, EDA_RECT > RECT_MAP; typedef boost::unordered_map< std::string, EDA_RECT > RECT_MAP;

77
include/hotkeys_basic.h
View File

@ -1,7 +1,7 @@
/* /*
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2004-2019 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2004-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -52,26 +52,25 @@ class EDA_BASE_FRAME;
#define PSEUDO_WXK_WHEEL 402 #define PSEUDO_WXK_WHEEL 402
/** /**
* Function KeyCodeFromKeyName * Return the key code from its user-friendly key name (ie: "Ctrl+M").
* return the key code from its user-friendly key name (ie: "Ctrl+M")
*/ */
int KeyCodeFromKeyName( const wxString& keyname ); int KeyCodeFromKeyName( const wxString& keyname );
/** /**
* Function KeyNameFromKeyCode * Return the user friendly key name (ie: "Ctrl+M") from the key code.
* return the user-friendly key name (ie: "Ctrl+M") from the key code *
* @param aKeycode = key code (ascii value, or wxWidgets value for function keys) * @param aKeycode key code (ASCII value, or wxWidgets value for function keys).
* @param aIsFound = a pointer to a bool to return true if found, or false * @param aIsFound a pointer to a bool to return true if found, or false.
*/ */
wxString KeyNameFromKeyCode( int aKeycode, bool * aIsFound = nullptr ); wxString KeyNameFromKeyCode( int aKeycode, bool* aIsFound = nullptr );
/** /**
* An helper enum for AddHotkeyName function * In menus we can add a hot key, or an accelerator, or sometimes just a comment. Hot keys
* In menus we can add a hot key, or an accelerator , or sometimes just a comment * can perform actions using the current mouse cursor position and accelerators perform the
* Hot keys can perform actions using the current mouse cursor position * same action as the associated menu.
* Accelerators perform the same action as the associated menu *
* A comment is used in tool tips for some tools (zoom ..) * A comment is used in tool tips for some tools (zoom ..) to show the hot key that performs
* to show the hot key that performs this action * this action
*/ */
enum HOTKEY_ACTION_TYPE enum HOTKEY_ACTION_TYPE
{ {
@ -80,53 +79,49 @@ enum HOTKEY_ACTION_TYPE
}; };
/** /**
* AddHotkeyName * @param aText the base text on which to append the hotkey.
* @param aText - the base text on which to append the hotkey * @param aHotKey the hotkey keycode.
* @param aHotKey - the hotkey keycode * @param aStyle #IS_HOTKEY to add <tab><keyname> (shortcuts in menus, same as hotkeys).
* @param aStyle - IS_HOTKEY to add <tab><keyname> (shortcuts in menus, same as hotkeys) * #IS_COMMENT to add <spaces><(keyname)> mainly in tool tips.
* IS_COMMENT to add <spaces><(keyname)> mainly in tool tips
*/ */
wxString AddHotkeyName( const wxString& aText, int aHotKey, wxString AddHotkeyName( const wxString& aText, int aHotKey,
HOTKEY_ACTION_TYPE aStyle = IS_HOTKEY); HOTKEY_ACTION_TYPE aStyle = IS_HOTKEY);
/** /**
* Function DisplayHotkeyList * Display the current hotkey list.
* Displays the current hotkey list *
* @param aFrame = current active frame * @param aFrame current active frame.
* @param aToolMgr = the tool manager holding the registered actions from which the hotkeys * @param aToolMgr the tool manager holding the registered actions from which the hotkeys
* will be harvested * will be harvested.
*/ */
void DisplayHotkeyList( EDA_BASE_FRAME* aFrame, TOOL_MANAGER* aToolMgr ); void DisplayHotkeyList( EDA_BASE_FRAME* aFrame, TOOL_MANAGER* aToolMgr );
/** /**
* Function ReadotKeyConfig * Reads a hotkey config file into a map.
* Reads a hotkey config file into a map. If aFileName is empty it will read in the defualt *
* hotkeys file. * If \a aFileName is empty it will read in the default hotkeys file.
* @param aHotKeys
*/ */
void ReadHotKeyConfig( wxString aFileName, std::map<std::string, int>& aHotKeys ); void ReadHotKeyConfig( const wxString& aFileName, std::map<std::string, int>& aHotKeys );
/** /**
* Function WriteHotKeyConfig * Update the hotkeys config file with the hotkeys from the given actions map.
* Updates the hotkeys config file with the hotkeys from the given actions map.
*/ */
int WriteHotKeyConfig( const std::map<std::string, TOOL_ACTION*>& aActionMap ); int WriteHotKeyConfig( const std::map<std::string, TOOL_ACTION*>& aActionMap );
/** /**
* Function ReadLegacyHotkeyConfigFile * Read hotkey configuration for a given app.
* Read hotkey configuration for a given app, *
* possibly before the frame for that app has been created * @param aFilename the filename to save the hotkeys as.
* @param aFilename = the filename to save the hotkeys as * @param aMap The list of keycodes mapped by legacy property names.
* @param aMap The list of keycodes mapped by legacy property names * @return 1 on success, 0 on failure.
* @return 1 on success, 0 on failure
*/ */
int ReadLegacyHotkeyConfigFile( const wxString& aFilename, std::map<std::string, int>& aMap ); int ReadLegacyHotkeyConfigFile( const wxString& aFilename, std::map<std::string, int>& aMap );
/** /**
* Function ReadLegacyHotkeyConfig * Read configuration data and fill the current hotkey list with hotkeys.
* Read configuration data and fill the current hotkey list with hotkeys *
* @param aAppname = the value of the app's m_FrameName * @param aAppname the value of the app's m_FrameName.
* @param aMap The list of keycodes mapped by legacy property names * @param aMap The list of keycodes mapped by legacy property names.
*/ */
int ReadLegacyHotkeyConfig( const wxString& aAppname, std::map<std::string, int>& aMap ); int ReadLegacyHotkeyConfig( const wxString& aAppname, std::map<std::string, int>& aMap );

55
include/ki_exception.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2007-2016 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2007-2016 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -38,9 +38,8 @@
#define THROW_IO_ERROR( msg ) throw IO_ERROR( msg, __FILE__, __FUNCTION__, __LINE__ ) #define THROW_IO_ERROR( msg ) throw IO_ERROR( msg, __FILE__, __FUNCTION__, __LINE__ )
/** /**
* KI_PARAM_ERROR * Hold a translatable error message and may be used when throwing exceptions containing a
* is a class used to hold a translatable error message and may be used when throwing exceptions * translated error message.
* containing a translated error message.
*/ */
class KI_PARAM_ERROR // similar to std::invalid_argument for instance class KI_PARAM_ERROR // similar to std::invalid_argument for instance
{ {
@ -68,29 +67,25 @@ private:
/** /**
* Struct IO_ERROR * Hold an error message and may be used when throwing exceptions containing meaningful
* is a class used to hold an error message and may be used when throwing exceptions * error messages.
* containing meaningful error messages. *
* @author Dick Hollenbeck * @author Dick Hollenbeck
*/ */
class IO_ERROR // : std::exception class IO_ERROR // : std::exception
{ {
public: public:
/** /**
* Constructor * Use macro #THROW_IO_ERROR() to wrap a call to this constructor at the call site.
* *
* @param aProblem is Problem() text. * @param aProblem is Problem() text.
* * @param aThrowersFile is the __FILE__ preprocessor macro but generated at the source
* @param aThrowersFile is the __FILE__ preprocessor macro but generated * file of thrower.
* at the source file of thrower.
*
* @param aThrowersFunction is the function name at the throw site. * @param aThrowersFunction is the function name at the throw site.
* @param aThrowersLineNumber is the source code line number of the throw. * @param aThrowersLineNumber is the source code line number of the throw.
*
* Use macro THROW_IO_ERROR() to wrap a call to this constructor at the call site.
*/ */
IO_ERROR( const wxString& aProblem, const char* aThrowersFile, IO_ERROR( const wxString& aProblem, const char* aThrowersFile,
const char* aThrowersFunction, int aThrowersLineNumber ) const char* aThrowersFunction, int aThrowersLineNumber )
{ {
init( aProblem, aThrowersFile, aThrowersFunction, aThrowersLineNumber ); init( aProblem, aThrowersFile, aThrowersFunction, aThrowersLineNumber );
} }
@ -98,7 +93,7 @@ public:
IO_ERROR() {} IO_ERROR() {}
void init( const wxString& aProblem, const char* aThrowersFile, void init( const wxString& aProblem, const char* aThrowersFile,
const char* aThrowersFunction, int aThrowersLineNumber ); const char* aThrowersFunction, int aThrowersLineNumber );
virtual const wxString Problem() const; ///< what was the problem? virtual const wxString Problem() const; ///< what was the problem?
virtual const wxString Where() const; ///< where did the Problem() occur? virtual const wxString Where() const; ///< where did the Problem() occur?
@ -114,10 +109,10 @@ protected:
/** /**
* Struct PARSE_ERROR * A filename or source description, a problem input line, a line number, a byte
* contains a filename or source description, a problem input line, a line number, * offset, and an error message which contains the the caller's report and his call
* a byte offset, and an error message which contains the the caller's report and his * site information: CPP source file, function, and line number.
* call site information: CPP source file, function, and line number. *
* @author Dick Hollenbeck * @author Dick Hollenbeck
*/ */
struct PARSE_ERROR : public IO_ERROR struct PARSE_ERROR : public IO_ERROR
@ -132,19 +127,17 @@ struct PARSE_ERROR : public IO_ERROR
std::string inputLine; std::string inputLine;
/** /**
* Constructor * Normally called via the macro #THROW_PARSE_ERROR so that __FILE__, __FUNCTION__,
* which is normally called via the macro THROW_PARSE_ERROR so that * and __LINE__ can be captured from the call site.
* __FILE__ and __FUNCTION__ and __LINE__ can be captured from the call site.
*/ */
PARSE_ERROR( const wxString& aProblem, const char* aThrowersFile, PARSE_ERROR( const wxString& aProblem, const char* aThrowersFile,
const char* aThrowersFunction, int aThrowersLineNumber, const char* aThrowersFunction, int aThrowersLineNumber,
const wxString& aSource, const wxString& aSource, const char* aInputLine,
const char* aInputLine,
int aLineNumber, int aByteIndex ) : int aLineNumber, int aByteIndex ) :
IO_ERROR() IO_ERROR()
{ {
init( aProblem, aThrowersFile, aThrowersFunction, aThrowersLineNumber, init( aProblem, aThrowersFile, aThrowersFunction, aThrowersLineNumber,
aSource, aInputLine, aLineNumber, aByteIndex ); aSource, aInputLine, aLineNumber, aByteIndex );
} }
void init( const wxString& aProblem, const char* aThrowersFile, void init( const wxString& aProblem, const char* aThrowersFile,
@ -168,14 +161,14 @@ protected:
}; };
#define THROW_PARSE_ERROR( aProblem, aSource, aInputLine, aLineNumber, aByteIndex ) \ #define THROW_PARSE_ERROR( aProblem, aSource, aInputLine, aLineNumber, aByteIndex ) \
throw PARSE_ERROR( aProblem, __FILE__, __FUNCTION__, __LINE__, aSource, aInputLine, aLineNumber, aByteIndex ) throw PARSE_ERROR( aProblem, __FILE__, __FUNCTION__, __LINE__, aSource, aInputLine, \
aLineNumber, aByteIndex )
/** /**
* Struct FUTURE_FORMAT_ERROR * Variant of #PARSE_ERROR indicating that a syntax or related error was likely caused
* variant of PARSE_ERROR indicating that a syntax or related error was likely caused * by a file generated by a newer version of KiCad than this. This can be used to generate
* by a file generated by a newer version of KiCad than this. Can be used to generate
* more informative error messages. * more informative error messages.
*/ */
struct FUTURE_FORMAT_ERROR : public PARSE_ERROR struct FUTURE_FORMAT_ERROR : public PARSE_ERROR

54
include/kicad_string.h
View File

@ -1,7 +1,7 @@
/* /*
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2004, 2019 KiCad Developers, see change_log.txt for contributors. * Copyright (C) 2004-2020 KiCad Developers, see change_log.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -40,14 +40,13 @@
/** /**
* Converts curly quotes and em/en dashes to straight quotes and dashes. * Converts curly quotes and em/en dashes to straight quotes and dashes.
* @param aString *
* @return true if any characters required conversion. * @return true if any characters required conversion.
*/ */
bool ConvertSmartQuotesAndDashes( wxString* aString ); bool ConvertSmartQuotesAndDashes( wxString* aString );
/** /**
* Escape/Unescape routines to safely encode reserved-characters in various * Escape/Unescape routines to safely encode reserved-characters in various contexts.
* contexts.
*/ */
enum ESCAPE_CONTEXT enum ESCAPE_CONTEXT
{ {
@ -76,8 +75,8 @@ wxString PrettyPrintForMenu( const wxString& aString );
* @param aDest is the destination byte buffer. * @param aDest is the destination byte buffer.
* @param aSource is the source bytes as a C string. * @param aSource is the source bytes as a C string.
* @param aDestSize is the size of the destination byte buffer. * @param aDestSize is the size of the destination byte buffer.
* @return int - the number of bytes read from source, which may be more than * @return the number of bytes read from source, which may be more than the number copied,
* the number copied, due to escaping of double quotes and the escape byte itself. * due to escaping of double quotes and the escape byte itself.
* @deprecated should use the one which fetches a wxString, below. * @deprecated should use the one which fetches a wxString, below.
*/ */
int ReadDelimitedText( char* aDest, const char* aSource, int aDestSize ); int ReadDelimitedText( char* aDest, const char* aSource, int aDestSize );
@ -85,21 +84,21 @@ int ReadDelimitedText( char* aDest, const char* aSource, int aDestSize );
/** /**
* Copy bytes from @a aSource delimited string segment to @a aDest wxString. * Copy bytes from @a aSource delimited string segment to @a aDest wxString.
* *
* @param aDest is the destination wxString * @param aDest is the destination wxString.
* @param aSource is the source C string holding utf8 encoded bytes. * @param aSource is the source C string holding utf8 encoded bytes.
* @return int - the number of bytes read from source, which may be more than * @return the number of bytes read from source, which may be more than the number copied,
* the number copied, due to escaping of double quotes and the escape byte itself. * due to escaping of double quotes and the escape byte itself.
*/ */
int ReadDelimitedText( wxString* aDest, const char* aSource ); int ReadDelimitedText( wxString* aDest, const char* aSource );
/** /**
* Function EscapedUTF8 * Return an 8 bit UTF8 string given aString in Unicode form.
* returns an 8 bit UTF8 string given aString in unicode form. *
* Any double quoted or back slashes are prefixed with a '\\' byte and the form * Any double quoted or back slashes are prefixed with a '\\' byte and the form
* of this UTF8 byte string is compatible with function ReadDelimitedText(). * of this UTF8 byte string is compatible with function ReadDelimitedText().
* *
* @param aString is the input string to convert. * @param aString is the input string to convert.
* @return std::string - the escaped input text, without the wrapping double quotes. * @return the escaped input text, without the wrapping double quotes.
*/ */
std::string EscapedUTF8( wxString aString ); std::string EscapedUTF8( wxString aString );
@ -113,7 +112,7 @@ wxString EscapeHTML( const wxString& aString );
* *
* @return a pointer the first useful line read by eliminating blank lines and comments. * @return a pointer the first useful line read by eliminating blank lines and comments.
*/ */
char* GetLine( FILE* aFile, char* Line, int* LineNum = NULL, int SizeLine = 255 ); char* GetLine( FILE* aFile, char* Line, int* LineNum = nullptr, int SizeLine = 255 );
/** /**
* Return true if the string is empty or contains only whitespace. * Return true if the string is empty or contains only whitespace.
@ -180,8 +179,8 @@ int SplitString( wxString strToSplit,
/** /**
* Gets the trailing int, if any, from a string. * Gets the trailing int, if any, from a string.
* *
* @param aStr the string to check * @param aStr the string to check.
* @return the trailing int or 0 if none found * @return the trailing int or 0 if none found.
*/ */
int GetTrailingInt( const wxString& aStr ); int GetTrailingInt( const wxString& aStr );
@ -214,8 +213,9 @@ extern "C" char* strtok_r( char* str, const char* delim, char** nextp );
/** /**
* A helper for sorting strings from the rear. Useful for things like 3d model names * A helper for sorting strings from the rear.
* where they tend to be largely repetitious at the front. *
* Useful for things like 3D model names where they tend to be largely repetitious at the front.
*/ */
struct rsort_wxString struct rsort_wxString
{ {
@ -264,10 +264,10 @@ struct rsort_wxString
/** /**
* Splits the input string into a vector of output strings * Splits the input string into a vector of output strings
* *
* @param aStr - Input string with 0 or more delimiters
* @param aDelim - The string of delimiter. Multiple characters here denote alternate delimiters
*
* @note Multiple delimiters are considered to be separate records with empty strings * @note Multiple delimiters are considered to be separate records with empty strings
*
* @param aStr Input string with 0 or more delimiters.
* @param aDelim The string of delimiter. Multiple characters here denote alternate delimiters.
* @return a vector of strings * @return a vector of strings
*/ */
static inline std::vector<std::string> split( const std::string& aStr, const std::string& aDelim ) static inline std::vector<std::string> split( const std::string& aStr, const std::string& aDelim )
@ -309,17 +309,17 @@ inline void AccumulateDescription( wxString& aDesc, const wxString& aItem )
/** /**
* Split \a aString to a string list separated at \a aSplitter. * Split \a aString to a string list separated at \a aSplitter.
* *
* @param aText is the text to split * @param aText is the text to split.
* @param aStrings will contain the splitted lines * @param aStrings will contain the split lines.
* @param aSplitter is the 'split' character * @param aSplitter is the 'split' character.
*/ */
void wxStringSplit( const wxString& aText, wxArrayString& aStrings, wxChar aSplitter ); void wxStringSplit( const wxString& aText, wxArrayString& aStrings, wxChar aSplitter );
/** /**
* Function StripTrailingZeros * Remove trailing zeros from a string containing a converted float number.
* Remove trailing 0 from a string containing a converted float number. *
* The trailing 0 are removed if the mantissa has more * The trailing zeros are removed if the mantissa has more than \a aTrailingZeroAllowed
* than aTrailingZeroAllowed digits and some trailing 0 * digits and some trailing zeros.
*/ */
void StripTrailingZeros( wxString& aStringValue, unsigned aTrailingZeroAllowed = 1 ); void StripTrailingZeros( wxString& aStringValue, unsigned aTrailingZeroAllowed = 1 );

66
include/kiface_i.h
View File

@ -1,7 +1,7 @@
/* /*
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 1992-2014 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -29,51 +29,37 @@
/** /**
* KIFACE_I * A #KIFACE (I)mplementation.
* is a KIFACE (I)mplementation, *
* with some features useful for DSOs which implement a KIFACE. * This has useful for DSOs which implement a #KIFACE. It is abstract so a few functions
* It is abstract, a few functions must be implemented in derivations. * must be implemented in derivations.
*/ */
class KIFACE_I : public KIFACE class KIFACE_I : public KIFACE
{ {
public: public:
/**
* Typically #start_common() is called from here.
*/
virtual bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) override = 0;
//-----<KIFACE API>---------------------------------------------------------- virtual void OnKifaceEnd() override
// see base class KIFACE in kiway.h for doxygen docs
VTBL_ENTRY bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) override = 0;
/*
{
typically call start_common() in your overload
return start_common();
}
*/
VTBL_ENTRY void OnKifaceEnd() override
{ {
// overload this if you want, end_common() may be handy. // overload this if you want, end_common() may be handy.
end_common(); end_common();
} }
VTBL_ENTRY wxWindow* CreateWindow( wxWindow* aParent, virtual wxWindow* CreateWindow( wxWindow* aParent, int aClassId, KIWAY* aKIWAY,
int aClassId, KIWAY* aKIWAY, int aCtlBits = 0 ) override = 0; int aCtlBits = 0 ) override = 0;
VTBL_ENTRY void* IfaceOrAddress( int aDataId ) override = 0; virtual void* IfaceOrAddress( int aDataId ) override = 0;
//-----</KIFACE API>---------------------------------------------------------
// The remainder are DSO specific helpers, not part of the KIFACE API
/** /**
* Constructor * @param aKifaceName should point to a C string in permanent storage which contains the
* * name of the DSO. Examples: "eeschema", "pcbnew", etc. This controls
* @param aKifaceName should point to a C string in permanent storage, * the name of the wxConfigBase established in m_bm, so it should be
* which contains the name of the DSO. Examples: "eeschema", "pcbnew", etc. * lowercase.
* This controls the name of the wxConfigBase established in m_bm, * @param aId is the type of DSO ( #FACE_SCH, #FACE_PCB, #FACE_CVPCB, #FACE_GERBVIEW,
* so it should be lowercase. * #FACE_PL_EDITOR, #FACE_PCB_CALCULATOR, #FACE_BMP2CMP)
* @param aId is the type of DSO ( FACE_SCH, FACE_PCB, FACE_CVPCB,
* FACE_GERBVIEW, FACE_PL_EDITOR, FACE_PCB_CALCULATOR, FACE_BMP2CMP)
*/ */
KIFACE_I( const char* aKifaceName, KIWAY::FACE_T aId ) : KIFACE_I( const char* aKifaceName, KIWAY::FACE_T aId ) :
m_id( aId ), m_id( aId ),
@ -98,27 +84,27 @@ protected:
public: public:
const wxString Name() { return wxString::FromUTF8( m_bm.m_name ); } const wxString Name()
{
return wxString::FromUTF8( m_bm.m_name );
}
APP_SETTINGS_BASE* KifaceSettings() const { return m_bm.m_config; } APP_SETTINGS_BASE* KifaceSettings() const { return m_bm.m_config; }
void InitSettings( APP_SETTINGS_BASE* aSettings ) { m_bm.InitSettings( aSettings ); } void InitSettings( APP_SETTINGS_BASE* aSettings ) { m_bm.InitSettings( aSettings ); }
/** /**
* Function StartFlags * Return whatever was passed as @a aCtlBits to OnKifaceStart().
* returns whatever was passed as @a aCtlBits to OnKifaceStart()
*/ */
int StartFlags() const { return m_start_flags; } int StartFlags() const { return m_start_flags; }
/** /**
* Function IsSingle * Is this KIFACE_I running under single_top?
* is this KIFACE_I running under single_top?
*/ */
bool IsSingle() const { return m_start_flags & KFCTL_STANDALONE; } bool IsSingle() const { return m_start_flags & KFCTL_STANDALONE; }
/** /**
* Function GetHelpFileName * Return just the basename portion of the current help file.
* returns just the basename portion of the current help file.
*/ */
const wxString& GetHelpFileName() const { return m_bm.m_help_file; } const wxString& GetHelpFileName() const { return m_bm.m_help_file; }

445
include/kiway.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2016 KiCad Developers, see CHANGELOG.TXT for contributors. * Copyright (C) 2016-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -25,75 +25,74 @@
#ifndef KIWAY_H_ #ifndef KIWAY_H_
#define KIWAY_H_ #define KIWAY_H_
/* /**
* The KIWAY and KIFACE classes are used to communicate between various process
The KIWAY and KIFACE classes are used to communicate between various process * modules, all residing within a single process. The program modules are either
modules, all residing within a single process. The program modules are either * top level like an *.exe or subsidiary like a *.dll. In much of the documentation
top level like an *.exe or subsidiary like a *.dll. In much of the documentation * the term DSO is used to refer to the *.dll portions, that is the term used on
the term DSO is used to refer to the *.dll portions, that is the term used on * linux. But it should be taken to mean DLL on Windows.
linux. But it should be taken to mean DLL on Windows. *
* <p>These are a couple of reasons why this design was chosen:
<p>These are a couple of reasons why this design was chosen: *
* <ol>
<ol> *
* <li>By using DSOs within a single process, it is not necessary to use IPC.
<li>By using DSOs within a single process, it is not necessary to use IPC. * The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in
The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in * a platform independent way. There can also be function calls from one DSO to
a platform independent way. There can also be function calls from one DSO to * another.</li>
another.</li> *
* <li>The use of a number of separately linked DSOs closely resembles the original
<li>The use of a number of separately linked DSOs closely resembles the original * KiCad program design, consisting of Eeschema and Pcbnew. But it also allows
KiCad program design, consisting of Eeschema and Pcbnew. But it also allows * separate compilation and linking of those two DSOs without a ton of inter-DSO
separate compilation and linking of those two DSOs without a ton of inter-DSO * dependencies and common data structures. Linking smaller, purpose specific DSOs
dependencies and common data structures. Linking smaller, purpose specific DSOs * is thought to be better for maintenance simplicity than a large single link
is thought to be better for maintenance simplicity than a large single link * image. </li>
image. </li> *
* <li>By keeping the core functionality in DSOs rather than EXE tops, it becomes
<li>By keeping the core functionality in DSOs rather than EXE tops, it becomes * possible to re-use the DSOs under different program tops. For example, a DSO
possible to re-use the DSOs under different program tops. For example, a DSO * named _pcbnew.so can be used under a C++ top or under a python top. Only one
named _pcbnew.so can be used under a C++ top or under a python top. Only one * CMake target must be defined to build either. Whether that is a separate build
CMake target must be defined to build either. Whether that is a separate build * or not is not the important thing. Simply having a single CMake target has
or not is not the important thing. Simply having a single CMake target has * advantages. (Each builder person will have his/her own intentions relative to
advantages. (Each builder person will have his/her own intentions relative to * use of python or not.) Once a DSO is python capable, it can be driven by any
use of python or not.) Once a DSO is python capable, it can be driven by any * number of python program tops, including demo-ing (automation) and testing
number of python program tops, including demo-ing (automation) and testing * separately.</li>
separately.</li> *
*
* </ol>
</ol> *
* All KiCad source code is UTF8 encoded by law, so make sure your editor is set
All KiCad source code is UTF8 encoded by law, so make sure your editor is set * as such! As such, it is OK to use UTF8 characters:
as such! As such, it is OK to use UTF8 characters: *
* ┏ ┗ ┓ ┛ ━ ┃
┏ ┗ ┓ ┛ ━ ┃ *
* <pre>
<pre> *
* ┏━━━process top━━━━━┓
┏━━━process top━━━━━┓ * ┃ ┃ wxEvent channels
┃ ┃ wxEvent channels * ┏━━━━━━━━━━━━━━━━━━━-━[KIWAY project 1]━-━━━━━━━━━━━━━━━━━━━━━━┓
┏━━━━━━━━━━━━━━━━━━━-━[KIWAY project 1]━-━━━━━━━━━━━━━━━━━━━━━━┓ * ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ * ┃ ┏━━━━━━━━━━━━━-━[KIWAY project 2]━-━━━━━━━━━━┓ ┃
┃ ┏━━━━━━━━━━━━━-━[KIWAY project 2]━-━━━━━━━━━━┓ ┃ * ┃ ┃ ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ ┃ ┃ * ┃ ┃ ┏━-━[KIWAY project 3]━-━┓ ┃ ┃
┃ ┃ ┏━-━[KIWAY project 3]━-━┓ ┃ ┃ * ┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━┛ ┃ ┃ ┃
┃ ┃ ┃ ┗━━━━━━━━━━━━━━━━━━━┛ ┃ ┃ ┃ * ┃ ┃ ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ ┃ ┃ * ┃ ┃ ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ ┃ ┃ * ┏━━━━━━━━|━━━━━|━━━━━━━━━━━|━━━━━━━━━┓ ┏━━━━━━━━|━━━━━━━━|━━━━━━━━━━━|━━━━━┓
┏━━━━━━━━|━━━━━|━━━━━━━━━━━|━━━━━━━━━┓ ┏━━━━━━━━|━━━━━━━━|━━━━━━━━━━━|━━━━━┓ * ┃ KIFACE ┃ ┃ ┃ ┃ ┃ KIFACE ┃ ┃ ┃ ┃
┃ KIFACE ┃ ┃ ┃ ┃ ┃ KIFACE ┃ ┃ ┃ ┃ * ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ * ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ * ┃┏━━━━━━━+━┓ ┏━+━━━━━━━┓ ┏━+━━━━━━━┓ ┃ ┃┏━━━━━━━+━┓ ┏━━━━+━━━━┓ ┏━━━━+━━━━┓┃
┃┏━━━━━━━+━┓ ┏━+━━━━━━━┓ ┏━+━━━━━━━┓ ┃ ┃┏━━━━━━━+━┓ ┏━━━━+━━━━┓ ┏━━━━+━━━━┓┃ * ┃┃wxFrame ┃ ┃wxFrame ┃ ┃wxFrame ┃ ┃ ┃┃wxFrame ┃ ┃wxFrame ┃ ┃wxFrame ┃┃
┃┃wxFrame ┃ ┃wxFrame ┃ ┃wxFrame ┃ ┃ ┃┃wxFrame ┃ ┃wxFrame ┃ ┃wxFrame ┃┃ * ┃┃project 1┃ ┃project 2┃ ┃project 3┃ ┃ ┃┃project 3┃ ┃project 2┃ ┃project 1┃┃
┃┃project 1┃ ┃project 2┃ ┃project 3┃ ┃ ┃┃project 3┃ ┃project 2┃ ┃project 1┃┃ * ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┃ ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛┃
┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┃ ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛┃ * ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ * ┃ ┃ ┃ ┃
┃ ┃ ┃ ┃ * ┗━━━━━━ eeschema DSO ━━━━━━━━━━━━━━━━┛ ┗━━━━━━ pcbnew DSO ━━━━━━━━━━━━━━━━━┛
┗━━━━━━ eeschema DSO ━━━━━━━━━━━━━━━━┛ ┗━━━━━━ pcbnew DSO ━━━━━━━━━━━━━━━━━┛ *
* </pre>
</pre> *
*/
*/
#include <wx/event.h> #include <wx/event.h>
@ -106,12 +105,10 @@ as such! As such, it is OK to use UTF8 characters:
#include <ki_exception.h> #include <ki_exception.h>
#define VTBL_ENTRY virtual
#define KIFACE_VERSION 1 #define KIFACE_VERSION 1
#define KIFACE_GETTER KIFACE_1 #define KIFACE_GETTER KIFACE_1
// The KIFACE acquistion function is declared extern "C" so its name should not // The KIFACE acquisition function is declared extern "C" so its name should not
// be mangled. // be mangled.
#define KIFACE_INSTANCE_NAME_AND_VERSION "KIFACE_1" #define KIFACE_INSTANCE_NAME_AND_VERSION "KIFACE_1"
@ -136,16 +133,16 @@ class wxTopLevelWindow;
/** /**
* KIFACE * Implement a participant in the KIWAY alchemy.
* is used by a participant in the KIWAY alchemy. KIWAY is a minimalistic *
* software bus for communications between various DLLs/DSOs (DSOs) within the same * KIWAY is a minimalistic software bus for communications between various DLLs/DSOs
* KiCad process. It makes it possible to call between DSOs without having to link * (DSOs) within the same KiCad process. It makes it possible to call between DSOs
* them together. Most all calls are via virtual functions which means C++ vtables * without having to link them together. Most all calls are via virtual functions
* are used to hold function pointers and eliminate the need to link to specific * which means C++ vtables are used to hold function pointers and eliminate the need
* object code libraries. There is one KIWAY in the launching portion of the process * to link to specific object code libraries. There is one KIWAY in the launching
* for each open KiCad project. Each project has its own KIWAY. Within a KIWAY * portion of the process for each open KiCad project. Each project has its own KIWAY.
* is an actual PROJECT data structure. A KIWAY also facilitates communicating * Within a KIWAY is an actual PROJECT data structure. A KIWAY also facilitates
* between DSOs on the topic of the project in question. * communicating between DSOs on the topic of the project in question.
*/ */
struct KIFACE struct KIFACE
{ {
@ -155,120 +152,110 @@ struct KIFACE
virtual ~KIFACE() throw() {} virtual ~KIFACE() throw() {}
#define KFCTL_STANDALONE (1<<0) ///< Am running as a standalone Top. #define KFCTL_STANDALONE (1<<0) ///< Running as a standalone Top.
#define KFCTL_CPP_PROJECT_SUITE (1<<1) ///< Am running under C++ project mgr, possibly with others #define KFCTL_CPP_PROJECT_SUITE (1<<1) ///< Running under C++ project mgr, possibly with others.
#define KFCTL_PY_PROJECT_SUITE (1<<2) ///< Am running under python project mgr, possibly with others #define KFCTL_PY_PROJECT_SUITE (1<<2) ///< Running under python project mgr, possibly with others.
/** /**
* Function OnKifaceStart * Called just once shortly after the DSO is loaded.
* is called just once shortly after the DSO is loaded. It is the second * It is the second function called, immediately after the KIFACE_GETTER(). However
* function called, immediately after the KIFACE_GETTER(). However before * before either of those, static C++ constructors are called. The DSO implementation
* either of those, static C++ constructors are called. The DSO implementation * should do process level initialization here, not project specific since there will
* should do process level initialization here, not project specific since there * be multiple projects open eventually.
* will be multiple projects open eventually.
*
* @param aProgram is the process block: PGM_BASE*
* *
* @param aProgram is the process block: #PGM_BASE*.
* @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above. * @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above.
* * @return true if DSO initialized OK, false if not. When returning false, the loader
* @return bool - true if DSO initialized OK, false if not. When returning * may optionally decide to terminate the process or not, but will not put out
* false, the loader may optionally decide to terminate the process or not, * any UI because that is the duty of this function to say why it is returning
* but will not put out any UI because that is the duty of this function to say * false. Never return false without having reported to the UI why.
* why it is returning false. Never return false without having reported
* to the UI why.
*/ */
VTBL_ENTRY bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) = 0; virtual bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) = 0;
/** /**
* Function OnKifaceEnd * Called just once just before the DSO is to be unloaded.
* is called just once just before the DSO is to be unloaded. It is called *
* before static C++ destructors are called. A default implementation is supplied. * It is called before static C++ destructors are called. A default implementation
* is supplied.
*/ */
VTBL_ENTRY void OnKifaceEnd() = 0; virtual void OnKifaceEnd() = 0;
/** /**
* Function CreateWindow * Create a wxWindow for the current project.
* creates a wxWindow for the current project. The caller
* must cast the return value into the known type.
* *
* @param aParent may be NULL, or is otherwise the parent to connect under. If NULL * The caller must cast the return value into the known type.
* then caller may want to connect the returned wxWindow into some hierarchy after
* this function returns.
* *
* @param aParent may be NULL or is otherwise the parent to connect under. If NULL
* then caller may want to connect the returned wxWindow into some
* hierarchy after this function returns.
* @param aClassId identifies which wxFrame or wxDialog to retrieve, using a value * @param aClassId identifies which wxFrame or wxDialog to retrieve, using a value
* known to the implementing KIFACE. * known to the implementing KIFACE.
*
* @param aKIWAY tells the window which KIWAY (and PROJECT) it is a participant in. * @param aKIWAY tells the window which KIWAY (and PROJECT) it is a participant in.
*
* @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above. * @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above.
* * @return the window created and if not NULL, should be cast into the known type using
* @return wxWindow* - and if not NULL, should be cast into the known type using * and old school cast. dynamic_cast is problematic since it needs typeinfo probably
* and old school cast. dynamic_cast is problematic since it needs typeinfo probably * not contained in the caller's link image.
* not contained in the caller's link image.
*/ */
VTBL_ENTRY wxWindow* CreateWindow( wxWindow* aParent, int aClassId, virtual wxWindow* CreateWindow( wxWindow* aParent, int aClassId,
KIWAY* aKIWAY, int aCtlBits = 0 ) = 0; KIWAY* aKIWAY, int aCtlBits = 0 ) = 0;
/** /**
* Function SaveFileAs
* Saving a file under a different name is delegated to the various KIFACEs because * Saving a file under a different name is delegated to the various KIFACEs because
* the project doesn't know the internal format of the various files (which may have * the project doesn't know the internal format of the various files (which may have
* paths in them that need updating). * paths in them that need updating).
*/ */
VTBL_ENTRY void SaveFileAs( const wxString& srcProjectBasePath, virtual void SaveFileAs( const wxString& srcProjectBasePath,
const wxString& srcProjectName, const wxString& srcProjectName,
const wxString& newProjectBasePath, const wxString& newProjectBasePath,
const wxString& newProjectName, const wxString& newProjectName,
const wxString& srcFilePath, const wxString& srcFilePath,
wxString& aErrors ) wxString& aErrors )
{ {
// If a KIFACE owns files then it needs to implement this.... // If a KIFACE owns files then it needs to implement this....
} }
/** /**
* Function IfaceOrAddress * Return pointer to the requested object.
* returns a pointer to the requested object. The safest way to use this
* is to retrieve a pointer to a static instance of an interface, similar to
* how the KIFACE interface is exported. But if you know what you are doing
* use it to retrieve anything you want. Segfaults are your fault.
* *
* @param aDataId identifies which object you want the address of, and consists * The safest way to use this is to retrieve a pointer to a static instance of an
* of choices known in advance by the implementing KIFACE. * interface, similar to how the KIFACE interface is exported. But if you know
* what you are doing use it to retrieve anything you want. Segfaults are your fault.
* *
* @return void* - and must be cast into the known type. * @param aDataId identifies which object you want the address of, and consists of
* choices known in advance by the implementing KIFACE.
* @return the requested object which must be cast into the known type.
*/ */
VTBL_ENTRY void* IfaceOrAddress( int aDataId ) = 0; virtual void* IfaceOrAddress( int aDataId ) = 0;
}; };
/** /**
* KIWAY * A minimalistic software bus for communications between various DLLs/DSOs (DSOs) within
* is a minimalistic software bus for communications between various * the same KiCad process.
* DLLs/DSOs (DSOs) within the same KiCad process. It makes it possible *
* to call between DSOs without having to link them together, and without * It makes it possible to call between DSOs without having to link them together, and
* having to link to the top process module which houses the KIWAY(s). More importantly * without having to link to the top process module which houses the KIWAY(s). More
* it makes it possible to send custom wxEvents between DSOs and from the top * 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 * process module down into the DSOs. The latter capability is thought useful for driving
* for driving the lower DSOs from a python test rig or for demo (automation) purposes. * the lower DSOs from a python test rig or for demo (automation) purposes.
* <p> * <p>
* Most all calls are via virtual functions, which means C++ vtables * Most all calls are via virtual functions, which means C++ vtables are used to hold
* are used to hold function pointers and eliminate the need to link to specific * function pointers and eliminate the need to link to specific object code libraries,
* object code libraries, speeding development and encouraging clearly defined * speeding development and encouraging clearly defined interface design. Unlike Microsoft
* interface design. Unlike Microsoft COM, which is a multi-vendor design supporting * COM, which is a multi-vendor design supporting DLL's built at various points in time,
* DLL's built at various points in time, the KIWAY alchemy is single project, with * the KIWAY alchemy is single project, with all components being built at the same time.
* all components being built at the same time. So one should expect solid compatibility * So one should expect solid compatibility between all KiCad components, as long at they
* between all KiCad components, as long at they are compiled at the same time. * are compiled at the same time.
* <p> * <p>
* There is one KIWAY in the launching portion of the process * There is one KIWAY in the launching portion of the process for each open KiCad project.
* for each open KiCad project. Each project has its own KIWAY. Available to * Each project has its own KIWAY. Available to each KIWAY is an actual PROJECT data
* each KIWAY is an actual PROJECT data structure. If you have a KIWAY, you * structure. If you have a KIWAY, you can get to the PROJECT using #KIWAY::Prj().
* can get to the PROJECT using KIWAY::Prj().
* <p> * <p>
* In summary, a KIWAY facilitates communicating between DSOs, where the topic * In summary, a KIWAY facilitates communicating between DSOs, where the topic of the
* of the communication is project specific. Here a "project" means a BOARD * communication is project specific. Here a "project" means a #BOARD and a #SCHEMATIC
* and a SCHEMATIC and a NETLIST, (anything relating to production of a single BOARD * and a #NETLIST, (anything relating to production of a single #BOARD and added to class
* and added to class PROJECT.) * #PROJECT.)
*/ */
class KIWAY : public wxEvtHandler class KIWAY : public wxEvtHandler
{ {
@ -292,109 +279,106 @@ public:
~KIWAY() throw () {} ~KIWAY() throw () {}
/** /**
* Function KifaceType * A simple mapping function which returns the FACE_T which is known to implement
* is a simple mapping function which returns the FACE_T which is known to * @a aFrameType.
* implement @a aFrameType.
* *
* @return KIWAY::FACE_T - a valid value or FACE_T(-1) if given a bad aFrameType. * @return a valid value #KIWAY::FACE_T or FACE_T(-1) if given a bad @a aFrameType.
*/ */
static FACE_T KifaceType( FRAME_T aFrameType ); static FACE_T KifaceType( FRAME_T aFrameType );
// If you change the vtable, recompile all of KiCad. // If you change the vtable, recompile all of KiCad.
/** /**
* Function KiFACE * Return the KIFACE* given a FACE_T.
* 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() * If it is not already loaded, the KIFACE is loaded and initialized with a call to
* KIFACE::OnKifaceStart().
*/ */
VTBL_ENTRY KIFACE* KiFACE( FACE_T aFaceId, bool doLoad = true ); virtual KIFACE* KiFACE( FACE_T aFaceId, bool doLoad = true );
/** /**
* Function Player * Return the #KIWAY_PLAYER* given a FRAME_T.
* 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 * If it is not already created, the required KIFACE is found and loaded and initialized
* the KIWAY_PLAYER window is created but not shown. Caller must Show() it. * if necessary, then the KIWAY_PLAYER window is created but not shown. Caller must
* If it is already created, then the existing KIWAY_PLAYER* pointer is returned. * Show() it. If it is already created, then the existing KIWAY_PLAYER* pointer is
* returned.
* *
* @param aFrameType is from enum #FRAME_T. * @param aFrameType is from enum #FRAME_T.
* @param doCreate when true asks that the player be created if it is not * @param doCreate when true asks that the player be created if it is not already created,
* already created, false means do not create and maybe return NULL. * false means do not create and maybe return NULL.
* @param aParent is a parent for modal KIWAY_PLAYER frames, otherwise NULL * @param aParent is a parent for modal #KIWAY_PLAYER frames, otherwise NULL used only
* used only when doCreate = true and by KIWAY_PLAYER frames created in modal form * when doCreate = true and by KIWAY_PLAYER frames created in modal form
* because the are using the wxFLOAT_ON_PARENT style
* *
* @return KIWAY_PLAYER* - a valid opened KIWAY_PLAYER or NULL if there * @return a valid opened #KIWAY_PLAYER or NULL if there is something wrong or doCreate
* is something wrong or doCreate was false and the player has yet to be created. * was false and the player has yet to be created.
* *
* @throw IO_ERROR if the *.kiface file could not be found, filled with text saying what. * @throw IO_ERROR if the *.kiface file could not be found, filled with text saying what.
*/ */
VTBL_ENTRY KIWAY_PLAYER* Player( FRAME_T aFrameType, bool doCreate = true, virtual KIWAY_PLAYER* Player( FRAME_T aFrameType, bool doCreate = true,
wxTopLevelWindow* aParent = NULL ); wxTopLevelWindow* aParent = nullptr );
/** /**
* Function PlayerClose * Call the KIWAY_PLAYER::Close( bool force ) function on the window and if not vetoed,
* calls the KIWAY_PLAYER::Close( bool force ) function on the window and * returns true, else false.
* if not vetoed, returns true, else false. If window actually closes, then
* this KIWAY marks it as not opened internally.
* *
* @return bool - true the window is closed and not vetoed, else false. * If window actually closes, then this KIWAY marks it as not opened internally.
*/
VTBL_ENTRY bool PlayerClose( FRAME_T aFrameType, 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.
* *
* @return bool - true indicates that all windows closed because none were vetoed, * @return true if the window is closed and not vetoed, else false.
* false means at least one cast a veto. Any that cast a veto are still open.
*/ */
VTBL_ENTRY bool PlayersClose( bool doForce ); virtual bool PlayerClose( FRAME_T aFrameType, bool doForce );
/** /**
* Function ExpressMail * Call the KIWAY_PLAYER::Close( bool force ) function on all the windows and if none
* send aPayload to aDestination from aSource. Recipient receives this in its * are vetoed, returns true, else false.
* KIWAY_PLAYER::KiwayMailIn() function and can efficiently switch() based on *
* aCommand in there. * If any window actually closes, then* this KIWAY marks it as not opened internally.
*
* @return true indicates that all windows closed because none were vetoed, false means
* at least one cast a veto. Any that cast a veto are still open.
*/ */
VTBL_ENTRY void ExpressMail( FRAME_T aDestination, MAIL_T aCommand, virtual bool PlayersClose( bool doForce );
std::string& aPayload, wxWindow* aSource = NULL );
/** /**
* Function Prj * Send @a aPayload to @a aDestination from @a aSource.
* returns the PROJECT associated with this KIWAY. This is here as an *
* accessor, so that there is freedom to put the actual PROJECT storage * The recipient receives this in its #KIWAY_PLAYER::KiwayMailIn() function and can
* efficiently switch() based on @a aCommand in there.
*/
virtual void ExpressMail( FRAME_T aDestination, MAIL_T aCommand, std::string& aPayload,
wxWindow* aSource = nullptr );
/**
* Return the #PROJECT associated with this KIWAY.
*
* This is here as an accessor, so that there is freedom to put the actual PROJECT storage
* in a place decided by the implementation, and not known to the caller. * in a place decided by the implementation, and not known to the caller.
*/ */
VTBL_ENTRY PROJECT& Prj() const; virtual PROJECT& Prj() const;
/** /**
* Function SetLanguage * Change the language and then calls ShowChangedLanguage() on all #KIWAY_PLAYERs.
* changes the language and then calls ShowChangedLanguage() on all KIWAY_PLAYERs.
*/ */
VTBL_ENTRY void SetLanguage( int aLanguage ); virtual void SetLanguage( int aLanguage );
/** /**
* Function CommonSettingsChanged * Call CommonSettingsChanged() on all KIWAY_PLAYERs.
* Calls CommonSettingsChanged() on all KIWAY_PLAYERs. *
* Used after changing suite-wide options such as panning, autosave interval, etc. * Use after changing suite-wide options such as panning, autosave interval, etc.
*/ */
VTBL_ENTRY void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged ); virtual void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged );
/** /**
* Calls ProjectChanged() on all KIWAY_PLAYERs. * Calls ProjectChanged() on all KIWAY_PLAYERs.
* Used after changing the project to ensure all players are updated correctly. * Used after changing the project to ensure all players are updated correctly.
*/ */
VTBL_ENTRY void ProjectChanged(); virtual void ProjectChanged();
KIWAY( PGM_BASE* aProgram, int aCtlBits, wxFrame* aTop = NULL ); KIWAY( PGM_BASE* aProgram, int aCtlBits, wxFrame* aTop = nullptr );
/** /**
* Function SetTop * Tell this KIWAY about the top most frame in the program and optionally allows it to
* tells this KIWAY about the top most frame in the program and optionally * play the role of one of the KIWAY_PLAYERs if launched from single_top.cpp.
* allows it to play the role of one of the KIWAY_PLAYERs if launched from
* single_top.cpp.
* *
* @param aTop is the top most wxFrame in the entire program. * @param aTop is the top most wxFrame in the entire program.
*/ */
@ -407,7 +391,6 @@ public:
bool ProcessEvent( wxEvent& aEvent ) override; bool ProcessEvent( wxEvent& aEvent ) override;
private: private:
/// Get the [path &] name of the DSO holding the requested FACE_T. /// Get the [path &] name of the DSO holding the requested FACE_T.
const wxString dso_search_path( FACE_T aFaceId ); const wxString dso_search_path( FACE_T aFaceId );
@ -423,12 +406,13 @@ private:
m_kiface[aFaceType] = aKiface; m_kiface[aFaceType] = aKiface;
return true; return true;
} }
return false; return false;
} }
/** /**
* @return the reference of the KIWAY_PLAYER having the type aFrameType * @return the reference of the KIWAY_PLAYER having the type @a aFrameType if exists,
* if exists, or NULL if this KIWAY_PLAYER was not yet created, or was closed * or NULL if this KIWAY_PLAYER was not yet created, or was closed
*/ */
KIWAY_PLAYER* GetPlayerFrame( FRAME_T aFrameType ); KIWAY_PLAYER* GetPlayerFrame( FRAME_T aFrameType );
@ -458,19 +442,18 @@ extern KIWAY Kiway;
/** /**
* Function Pointer KIFACE_GETTER_FUNC * Point to the one and only KIFACE export.
* points to the one and only KIFACE export. The export's address *
* is looked up via symbolic string and should be extern "C" to avoid name * The export's address is looked up via symbolic string and should be extern "C" to avoid name
* mangling. This function will only be called one time. The DSO itself however * mangling. This function will only be called one time. The DSO itself however may be asked
* may be asked to support multiple Top windows, i.e. multiple projects * to support multiple Top windows, i.e. multiple projects within its lifetime.
* within its lifetime.
* *
* @param aKIFACEversion is where to put the API version implemented by the KIFACE. * @param aKIFACEversion is where to put the API version implemented by the KIFACE.
* @param aKIWAYversion tells the KIFACE what KIWAY version will be available. * @param aKIWAYversion tells the KIFACE what KIWAY version will be available.
* @param aProgram is a pointer to the PGM_BASE for this process. * @param aProgram is a pointer to the PGM_BASE for this process.
* @return KIFACE* - unconditionally, cannot fail. * @return unconditionally, cannot fail.
*/ */
typedef KIFACE* KIFACE_GETTER_FUNC( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram ); typedef KIFACE* KIFACE_GETTER_FUNC( int* aKIFACEversion, int aKIWAYversion, PGM_BASE* aProgram );
#ifndef SWIG #ifndef SWIG

29
include/kiway_express.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2014 KiCad Developers, see CHANGELOG.TXT for contributors. * Copyright (C) 2014-202 KiCad Developers, see CHANGELOG.TXT for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -33,21 +33,18 @@
/** /**
* KIWAY_EXPRESS * Carry a payload from one #KIWAY_PLAYER to another within a #PROJECT.
* carries a payload from one KIWAY_PLAYER to another within a PROJECT.
*/ */
class KIWAY_EXPRESS : public wxEvent class KIWAY_EXPRESS : public wxEvent
{ {
public: public:
/** /**
* Function Dest * Return the destination player id of the message.
* returns the destination player id of the message.
*/ */
FRAME_T Dest() { return m_destination; } FRAME_T Dest() { return m_destination; }
/** /**
* Function Command * Returns the #MAIL_T associated with this mail.
* returns the MAIL_T associated with this mail.
*/ */
MAIL_T Command() MAIL_T Command()
{ {
@ -55,19 +52,17 @@ public:
} }
/** /**
* Function Payload * Return the payload, which can be any text but it typically self identifying s-expression.
* returns the payload, which can be any text but it typicall self
* identifying s-expression.
*/ */
std::string& GetPayload() { return m_payload; } std::string& GetPayload() { return m_payload; }
void SetPayload( const std::string& aPayload ) { m_payload = aPayload; } void SetPayload( const std::string& aPayload ) { m_payload = aPayload; }
KIWAY_EXPRESS* Clone() const override { return new KIWAY_EXPRESS( *this ); } KIWAY_EXPRESS* Clone() const override { return new KIWAY_EXPRESS( *this ); }
//KIWAY_EXPRESS() {} //KIWAY_EXPRESS() {}
KIWAY_EXPRESS( FRAME_T aDestination, MAIL_T aCommand, std::string& aPayload, KIWAY_EXPRESS( FRAME_T aDestination, MAIL_T aCommand, std::string& aPayload,
wxWindow* aSource = NULL ); wxWindow* aSource = nullptr );
KIWAY_EXPRESS( const KIWAY_EXPRESS& anOther ); KIWAY_EXPRESS( const KIWAY_EXPRESS& anOther );
@ -79,8 +74,8 @@ public:
//DECLARE_DYNAMIC_CLASS( KIWAY_EXPRESS ) //DECLARE_DYNAMIC_CLASS( KIWAY_EXPRESS )
private: private:
FRAME_T m_destination; ///< could have been a bitmap indicating multiple recipients FRAME_T m_destination; ///< could have been a bitmap indicating multiple recipients.
std::string& m_payload; ///< very often s-expression text, but not always std::string& m_payload; ///< very often s-expression text, but not always.
// possible new ideas here. // possible new ideas here.
}; };

30
include/kiway_holder.h
View File

@ -1,7 +1,7 @@
/* /*
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -32,9 +32,9 @@ class PROJECT;
/** /**
* KIWAY_HOLDER * A mix in class which holds the location of a wxWindow's KIWAY.
* is a mix in class which holds the location of a wxWindow's KIWAY. It allows calls to *
* Kiway() and SetKiway(). * It allows calls to Kiway() and SetKiway().
*/ */
class KIWAY_HOLDER class KIWAY_HOLDER
{ {
@ -47,11 +47,11 @@ public:
{} {}
HOLDER_TYPE GetType() const { return m_type; } HOLDER_TYPE GetType() const { return m_type; }
/** /**
* Function Kiway * Return a reference to the #KIWAY that this object has an opportunity to participate in.
* returns a reference to the KIWAY that this object has an opportunity *
* to participate in. A KIWAY_HOLDER is not necessarily a KIWAY_PLAYER. * A KIWAY_HOLDER is not necessarily a KIWAY_PLAYER.
*/ */
KIWAY& Kiway() const KIWAY& Kiway() const
{ {
@ -60,19 +60,16 @@ public:
} }
/** /**
* Function Prj * Return a reference to the #PROJECT associated with this #KIWAY.
* returns a reference to the PROJECT "associated with" this KIWAY.
*/ */
PROJECT& Prj() const; PROJECT& Prj() const;
/** /**
* Function SetKiway * It is only used for debugging, since "this" is not a wxWindow*. "this" is
* a KIWAY_HOLDER mix-in.
* *
* @param aDest is the recipient of aKiway pointer. * @param aDest is the recipient of \a aKiway pointer.
* It is only used for debugging, since "this" is not a wxWindow*. "this" is * @param aKiway is often from a parent window or from #KIFACE::CreateWindow().
* a KIWAY_HOLDER mix-in.
*
* @param aKiway is often from a parent window, or from KIFACE::CreateWindow().
*/ */
void SetKiway( wxWindow* aDest, KIWAY* aKiway ); void SetKiway( wxWindow* aDest, KIWAY* aKiway );
@ -83,5 +80,4 @@ private:
}; };
#endif // KIWAY_HOLDER_H_ #endif // KIWAY_HOLDER_H_

10
include/kiway_mgr.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2014 KiCad Developers, see CHANGELOG.TXT for contributors. * Copyright (C) 2014-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -30,10 +30,10 @@
/** /**
* KIWAY_MGR * A container for all KIWAYS and PROJECTS.
* is a container for all KIWAYS [and PROJECTS]. This class needs to work both *
* for a C++ project manager and an a wxPython one (after being moved into a * This class needs to work both for a C++ project manager and an a wxPython one (after
* header later). * being moved into a header later).
*/ */
class KIWAY_MGR class KIWAY_MGR
{ {

148
include/kiway_player.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2017 KiCad Developers, see change_log.txt for contributors. * Copyright (C) 2017-2020 KiCad Developers, see change_log.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -45,15 +45,15 @@ class WX_EVENT_LOOP;
/** /**
* KIWAY_PLAYER * A wxFrame capable of the OpenProjectFiles function, meaning it can load a portion of
* is a wxFrame capable of the OpenProjectFiles function, meaning it can load * a KiCad project.
* a portion of a KiCad project. Because this class provides a dummy implementation, *
* it is not a certainty that all classes which inherit from this clas intend to * Because this class provides a dummy implementation,it is not a certainty that all
* participate in a KIWAY. Those that do must actually interact with the provided * classes which inherit from this class intend to participate in a #KIWAY. Those that
* KIWAY*. * do must actually interact with the provided #KIWAY.
* <p> *
* EDA_BASE_FRAME would not have sufficed because BM2CMP_FRAME_BASE is not * #EDA_BASE_FRAME would not have sufficed because #BM2CMP_FRAME_BASE is not derived
* derived from it. * from it.
*/ */
#ifdef SWIG #ifdef SWIG
class KIWAY_PLAYER : public wxFrame, public KIWAY_HOLDER class KIWAY_PLAYER : public wxFrame, public KIWAY_HOLDER
@ -63,59 +63,53 @@ class KIWAY_PLAYER : public EDA_BASE_FRAME
{ {
public: public:
KIWAY_PLAYER( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType, KIWAY_PLAYER( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType,
const wxString& aTitle, const wxPoint& aPos, const wxSize& aSize, const wxString& aTitle, const wxPoint& aPos, const wxSize& aSize,
long aStyle, const wxString& aWdoName = wxFrameNameStr ); long aStyle, const wxString& aWdoName = wxFrameNameStr );
/// Don't use this one, only wxformbuilder uses it, and it must be augmented with /// Don't use this one, only wxformbuilder uses it, and it must be augmented with
/// a SetKiway() early in derived constructor. /// a SetKiway() early in derived constructor.
KIWAY_PLAYER( wxWindow* aParent, wxWindowID aId, const wxString& aTitle, KIWAY_PLAYER( wxWindow* aParent, wxWindowID aId, const wxString& aTitle,
const wxPoint& aPos, const wxSize& aSize, long aStyle, const wxPoint& aPos, const wxSize& aSize, long aStyle,
const wxString& aWdoName = wxFrameNameStr ); const wxString& aWdoName = wxFrameNameStr );
~KIWAY_PLAYER() throw(); ~KIWAY_PLAYER() throw();
//----<Cross Module API>-----------------------------------------------------
// For the aCtl argument of OpenProjectFiles() // For the aCtl argument of OpenProjectFiles()
#define KICTL_EAGLE_BRD (1<<0) ///< chosen *.brd file is Eagle according to user. #define KICTL_EAGLE_BRD (1<<0) ///< chosen *.brd file is Eagle according to user.
#define KICTL_CREATE (1<<1) ///< caller thinks requested project files may not exist #define KICTL_CREATE (1<<1) ///< caller thinks requested project files may not exist.
/** /**
* Function OpenProjectFiles * Open a project or set of files given by @a aFileList.
* is abstract, and opens a project or set of files given by @a aFileList.
* This is generalized in the direction of worst case. In a typical case
* @a aFileList will only hold a single file, like "myboard.kicad_pcb",
* because any KIWAY_PLAYER is only in one KIWAY and the KIWAY owns the
* PROJECT. Therefore opening files from multiple projects into the same
* KIWAY_PLAYER is precluded.
* <p>
* Each derived class should handle this in a way specific to its needs.
* No filename prompting is done inside here for any file or project. There should
* be no need to call this with aFileList which is empty. However, calling it with
* a single filename which does not exist should indicate to the implementor
* that a new session is being started and that the given name is the desired
* name for the data file at time of save.
* <p>
* This function does not support "appending". Use a different function for that.
* Any prior project data tree should be cleared before loading the new stuff.
* <p>
* Therefore, one of the first things an implementation should do is test for
* existence of the first file in the list, and if it does not exist, treat
* it as a new session, possibly with a UI notification to that effect.
* <p>
* After loading the window should update its Title as part of this operation.
* If the KIWAY_PLAYER needs to, it can load the *.pro file as part of this operation.
* <p>
* If the KIWAY_PLAYER cannot load any of the file(s) in the list, then it
* should say why through some GUI interface, and return false.
* *
* @param aFileList includes files that this frame should open * This is generalized in the direction of worst case. In a typical case @a aFileList
* according to the knowledge in the derived wxFrame. In almost every case, * will only hold a single file, like "myboard.kicad_pcb" because any #KIWAY_PLAYER
* the list will have only a single file in it. * is only in one #KIWAY and the #KIWAY owns the #PROJECT. Therefore opening files
* from multiple projects into the same #KIWAY_PLAYER is precluded.
* *
* Each derived class should handle this in a way specific to its needs. No filename
* prompting is done inside here for any file or project. There should be no need to
* call this with \a aFileList which is empty. However, calling it with a single
* filename which does not exist should indicate to the implementer that a new session
* is being started and that the given name is the desired name for the data file at
* time of save.
*
* This function does not support "appending". Use a different function for that. Any
* prior project data tree should be cleared before loading the new stuff. Therefore,
* one of the first things an implementation should do is test for existence of the first
* file in the list, and if it does not exist, treat it as a new session, possibly with
* a UI notification to that effect.
*
* After loading the window should update its Title as part of this operation. If the
* #KIWAY_PLAYER needs to, it can load the *.pro file as part of this operation.
*
* If the KIWAY_PLAYER cannot load any of the file(s) in the list, then it should say
* why through some GUI interface, and return false.
*
* @param aFileList includes files that this frame should open according to the knowledge
* in the derived wxFrame. In almost every case, the list will have only
* a single file in it.
* @param aCtl is a set of bit flags ORed together from the set of KICTL_* \#defined above. * @param aCtl is a set of bit flags ORed together from the set of KICTL_* \#defined above.
* * @return true if all requested files were opened OK, else false.
* @return bool - true if all requested files were opened OK, else false.
*/ */
virtual bool OpenProjectFiles( const std::vector<wxString>& aFileList, int aCtl = 0 ) virtual bool OpenProjectFiles( const std::vector<wxString>& aFileList, int aCtl = 0 )
{ {
@ -130,7 +124,8 @@ public:
} }
/** /**
* Handles command-line arguments in a frame-specific way. * Handle command-line arguments in a frame-specific way.
*
* The given argument parser has already been initialized with the command line and any * The given argument parser has already been initialized with the command line and any
* options/switches that are handled by the top-level launcher before passing control to * options/switches that are handled by the top-level launcher before passing control to
* the child frame. * the child frame.
@ -144,34 +139,30 @@ public:
/** /**
* Function ShowModal * Show this wxFrame as if it were a modal dialog, with all other instantiated wxFrames
* puts up this wxFrame as if it were a modal dialog, with all other instantiated * disabled until this #KIWAY_PLAYER derivative calls DismissModal().
* wxFrames disabled until this KIWAY_PLAYER derivative calls DismissModal(). *
* That is, behavior is similar to a modal dialog window. Not all KIWAY_PLAYERs * This is behavior is similar to a modal dialog window. Not all KIWAY_PLAYERs use this
* use this interface, so don't call this unless the implementation knows how * interface, so don't call this unless the implementation knows how to call DismissModal()
* to call DismissModal() on a button click or double click or some special * on a button click or double click or some special event which ends the modal behavior.
* event which ends the modal behavior.
* *
* @param aResult if not NULL, indicates a place to put a resultant string. * @param aResult if not NULL, indicates a place to put a resultant string.
* @param aResultantFocusWindow if not NULL, indicates what window to pass focus to on return. * @param aResultantFocusWindow if not NULL, indicates what window to pass focus to on return.
* * @return true if frame implementation called KIWAY_PLAYER::DismissModal() with aRetVal
* @return bool - true if frame implementation called KIWAY_PLAYER::DismissModal() * of true.
* with aRetVal of true.
*/ */
virtual bool ShowModal( wxString* aResult = NULL, wxWindow* aResultantFocusWindow = NULL ); virtual bool ShowModal( wxString* aResult = nullptr,
wxWindow* aResultantFocusWindow = nullptr );
//----</Cross Module API>----------------------------------------------------
/** /**
* Function KiwayMailIn * Receive #KIWAY_EXPRESS messages from other players.
* receives KIWAY_EXPRESS messages from other players. Merely override it *
* in derived classes. * Override it in derived classes.
*/ */
virtual void KiwayMailIn( KIWAY_EXPRESS& aEvent ); virtual void KiwayMailIn( KIWAY_EXPRESS& aEvent );
/** /**
* Our version of Destroy() which is virtual from wxWidgets * Our version of Destroy() which is virtual from wxWidgets.
*/ */
bool Destroy() override; bool Destroy() override;
@ -179,10 +170,9 @@ public:
void SetModal( bool aIsModal ) { m_modal = aIsModal; } void SetModal( bool aIsModal ) { m_modal = aIsModal; }
/** /**
* Function IsDismissed * @return false only if both the frame is acting in modal mode and it has not been
* returns false only if both the frame is acting in modal mode and it has not been * dismissed yet with DismissModal(). True if the dialog is not modal or if
* dismissed yet with DismissModal(). IOW, it will return true if the dialog is * it is modal and has been dismissed.
* not modal or if it is modal and has been dismissed.
*/ */
bool IsDismissed(); bool IsDismissed();
@ -194,14 +184,15 @@ protected:
void kiway_express( KIWAY_EXPRESS& aEvent ); void kiway_express( KIWAY_EXPRESS& aEvent );
/** /**
* Function language_change * An event handler called on a language menu selection.
* is an event handler called on a language menu selection.
*/ */
void language_change( wxCommandEvent& event ); void language_change( wxCommandEvent& event );
// variables for modal behavior support, only used by a few derivatives. // variables for modal behavior support, only used by a few derivatives.
bool m_modal; // true if frame is intended to be modal, not modeless bool m_modal; // true if frame is intended to be modal, not modeless
WX_EVENT_LOOP* m_modal_loop; // points to nested event_loop, NULL means not modal and dismissed
///< Points to nested event_loop. NULL means not modal and dismissed.
WX_EVENT_LOOP* m_modal_loop;
wxWindow* m_modal_resultant_parent; // the window caller in modal mode wxWindow* m_modal_resultant_parent; // the window caller in modal mode
wxString m_modal_string; wxString m_modal_string;
bool m_modal_ret_val; // true if a selection was made bool m_modal_ret_val; // true if a selection was made
@ -269,11 +260,6 @@ bool OpenProjectFiles( const std::vector<wxString>& aFileList, int aCtl = 0 )
show contents. show contents.
} }
#endif #endif
#endif // KIWAY_PLAYER_H_ #endif // KIWAY_PLAYER_H_

231
include/pgm_base.h
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2004-2015 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2004-2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2008-2015 Wayne Stambaugh <stambaughw@verizon.net> * Copyright (C) 2008-2015 Wayne Stambaugh <stambaughw@gmail.com>
* Copyright (C) 1992-2017 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -48,11 +48,11 @@ class COMMON_SETTINGS;
class SETTINGS_MANAGER; class SETTINGS_MANAGER;
/** /**
* A small class to handle the list of existing translations. * A small class to handle the list of existing translations.
* The locale translation is automatic. *
* The selection of languages is mainly for maintainer's convenience * The locale translation is automatic. The selection of languages is mainly for
* To add a support to a new translation: * maintainer's convenience. To add a support to a new translation add a new item
* add a new item to LanguagesList[]. * to #LanguagesList[].
*/ */
struct LANGUAGE_DESCR struct LANGUAGE_DESCR
{ {
@ -69,21 +69,17 @@ struct LANGUAGE_DESCR
bool m_DoNotTranslate; bool m_DoNotTranslate;
}; };
/** /**
* An array containing all the languages that KiCad supports. * An array containing all the languages that KiCad supports.
*/ */
extern LANGUAGE_DESCR LanguagesList[]; extern LANGUAGE_DESCR LanguagesList[];
// inter program module calling
#define VTBL_ENTRY virtual
/** /**
* ENV_VAR_ITEM * A simple helper class to store environment variable values and the status of whether
* * or not they were defined externally to the process created when any of the KiCad
* is a simple helper class to store environment variable values and the status of whether * applications was launched.
* or not they were defined externally to the process created when any of the KiCad applications
* was launched.
*/ */
class ENV_VAR_ITEM class ENV_VAR_ITEM
{ {
@ -110,7 +106,7 @@ private:
wxString m_value; wxString m_value;
/// Flag to indicate if the environment variable was defined externally to the process. /// Flag to indicate if the environment variable was defined externally to the process.
bool m_isDefinedExternally; bool m_isDefinedExternally;
}; };
@ -120,19 +116,17 @@ typedef std::map<wxString, ENV_VAR_ITEM>::const_iterator ENV_VAR_MAP_CITER;
/** /**
* PGM_BASE * Container for data for KiCad programs.
* keeps program (whole process) data for KiCad programs. *
* The VTBL_ENTRY functions are VTBL_ENTRY so we can do cross module calls * The functions are virtual so we can do cross module calls without linking to them. This
* without linking to them. This used to be a wxApp derivative, but that * used to be a wxApp derivative, but that is difficult under wxPython which shapes the wxApp.
* is difficult under wxPython which shapes the wxApp. So now this is a "side-car" * So now this is a "side-car" (like a motorcycle side-car) object with a back pointer into
* (like a motorcycle side-car) object with a back pointer into the wxApp * the wxApp which initializes it.
* which initializes it. *
* <p> * - OnPgmStart() is virtual, may be overridden, and parallels wxApp::OnInit(), from where it
* OnPgmStart() is virtual, may be overridden, and parallels * should called.
* wxApp::OnInit(), from where it should called. * - OnPgmEnd() is virtual, may be overridden, and parallels wxApp::OnExit(), from where it
* <p> * should be called.
* OnPgmEnd() is virtual, may be overridden, and parallels wxApp::OnExit(),
* from where it should be called.
*/ */
class PGM_BASE class PGM_BASE
{ {
@ -162,31 +156,30 @@ public:
virtual void OnPgmExit() = 0; // call this from wxApp::OnExit() virtual void OnPgmExit() = 0; // call this from wxApp::OnExit()
#endif #endif
//----<Cross Module API>-----------------------------------------------------
/** /**
* Function MacOpenFile * Specific to MacOSX (not used under Linux or Windows).
* is specific to MacOSX (not used under Linux or Windows). *
* MacOSX requires it for file association. * MacOSX requires it for file association.
* @see http://wiki.wxwidgets.org/WxMac-specific_topics * @see http://wiki.wxwidgets.org/WxMac-specific_topics
*/ */
VTBL_ENTRY void MacOpenFile( const wxString& aFileName ) = 0; virtual void MacOpenFile( const wxString& aFileName ) = 0;
VTBL_ENTRY SETTINGS_MANAGER& GetSettingsManager() const { return *m_settings_manager; } virtual SETTINGS_MANAGER& GetSettingsManager() const { return *m_settings_manager; }
VTBL_ENTRY COMMON_SETTINGS* GetCommonSettings() const; virtual COMMON_SETTINGS* GetCommonSettings() const;
VTBL_ENTRY void SetEditorName( const wxString& aFileName ); virtual void SetEditorName( const wxString& aFileName );
/** /**
* Return the preferred editor name. * Return the preferred editor name.
*
* @param aCanShowFileChooser If no editor is currently set and this argument is * @param aCanShowFileChooser If no editor is currently set and this argument is
* 'true' then this method will show a file chooser dialog asking for the * 'true' then this method will show a file chooser dialog asking for the
* editor's executable. * editor's executable.
* @return Returns the full path of the editor, or an empty string if no editor has * @return Returns the full path of the editor, or an empty string if no editor has
* been set. * been set.
*/ */
VTBL_ENTRY const wxString& GetEditorName( bool aCanShowFileChooser = true ); virtual const wxString& GetEditorName( bool aCanShowFileChooser = true );
/** /**
* Shows a dialog that instructs the user to select a new preferred editor. * Shows a dialog that instructs the user to select a new preferred editor.
@ -195,82 +188,75 @@ public:
* @return Returns the full path of the editor, or an empty string if no editor was * @return Returns the full path of the editor, or an empty string if no editor was
* chosen. * chosen.
*/ */
VTBL_ENTRY const wxString AskUserForPreferredEditor( virtual const wxString AskUserForPreferredEditor(
const wxString& aDefaultEditor = wxEmptyString ); const wxString& aDefaultEditor = wxEmptyString );
VTBL_ENTRY bool IsKicadEnvVariableDefined() const { return !m_kicad_env.IsEmpty(); } virtual bool IsKicadEnvVariableDefined() const { return !m_kicad_env.IsEmpty(); }
VTBL_ENTRY const wxString& GetKicadEnvVariable() const { return m_kicad_env; } virtual const wxString& GetKicadEnvVariable() const { return m_kicad_env; }
VTBL_ENTRY const wxString& GetExecutablePath() const { return m_bin_dir; } virtual const wxString& GetExecutablePath() const { return m_bin_dir; }
VTBL_ENTRY wxLocale* GetLocale() { return m_locale; } virtual wxLocale* GetLocale() { return m_locale; }
VTBL_ENTRY const wxString& GetPdfBrowserName() const { return m_pdf_browser; } virtual const wxString& GetPdfBrowserName() const { return m_pdf_browser; }
VTBL_ENTRY void SetPdfBrowserName( const wxString& aFileName ) { m_pdf_browser = aFileName; } virtual void SetPdfBrowserName( const wxString& aFileName ) { m_pdf_browser = aFileName; }
/** /**
* Function UseSystemPdfBrowser * @return true if the PDF browser is the default (system) PDF browser and false if the
* returns true if the PDF browser is the default (system) PDF browser * PDF browser is the preferred (selected) browser, else returns false if there
* and false if the PDF browser is the preferred (selected) browser, else * is no selected browser.
* returns false if there is no selected browser
*/ */
VTBL_ENTRY bool UseSystemPdfBrowser() const virtual bool UseSystemPdfBrowser() const
{ {
return m_use_system_pdf_browser || m_pdf_browser.IsEmpty(); return m_use_system_pdf_browser || m_pdf_browser.IsEmpty();
} }
/** /**
* Function ForceSystemPdfBrowser * Force the use of system PDF browser, even if a preferred PDF browser is set.
* forces the use of system PDF browser, even if a preferred PDF browser is set.
*/ */
VTBL_ENTRY void ForceSystemPdfBrowser( bool aFlg ) { m_use_system_pdf_browser = aFlg; } virtual void ForceSystemPdfBrowser( bool aFlg ) { m_use_system_pdf_browser = aFlg; }
/** /**
* sets the dictionary file name for internationalization. * Set the dictionary file name for internationalization.
* <p> *
* The files are in kicad/internat/xx or kicad/internat/xx_XX and are named kicad.mo * The files are in kicad/internat/xx or kicad/internat/xx_XX and are named kicad.mo
* </p>
* @param aErrMsg is the string to return the error message it
* @param first_time must be set to true the first time this function is
* called, false otherwise
* @return false if there was an error setting the language
*/
VTBL_ENTRY bool SetLanguage( wxString& aErrMsg, bool first_time = false );
/**
* Function SetLanguageIdentifier
* sets in .m_language_id member the wxWidgets language identifier Id from
* the KiCad menu id (internal menu identifier).
* *
* @param menu_id The KiCad menuitem id (returned by Menu Event, when * @param aErrMsg is the string to return the error message it.
* clicking on a menu item) * @param first_time must be set to true the first time this function is called,
* false otherwise.
* @return false if there was an error setting the language.
*/ */
VTBL_ENTRY void SetLanguageIdentifier( int menu_id ); virtual bool SetLanguage( wxString& aErrMsg, bool first_time = false );
/** /**
* @return the wxWidgets language identifier Id of the language currently selected * Set in .m_language_id member the wxWidgets language identifier ID fromthe KiCad
*/ * menu id (internal menu identifier).
VTBL_ENTRY int GetSelectedLanguageIdentifier() const { return m_language_id; }
VTBL_ENTRY void SetLanguagePath();
/**
* Function ReadPdfBrowserInfos
* reads the PDF browser choice from the common configuration.
*/
VTBL_ENTRY void ReadPdfBrowserInfos();
/**
* Function WritePdfBrowserInfos
* saves the PDF browser choice to the common configuration.
*/
VTBL_ENTRY void WritePdfBrowserInfos();
/**
* Function SetLocalEnvVariable
* *
* @param menu_id The KiCad menuitem id (returned by Menu Event, when clicking on a
* menu item)
*/
virtual void SetLanguageIdentifier( int menu_id );
/**
* @return the wxWidgets language identifier Id of the language currently selected.
*/
virtual int GetSelectedLanguageIdentifier() const { return m_language_id; }
virtual void SetLanguagePath();
/**
* Read the PDF browser choice from the common configuration.
*/
virtual void ReadPdfBrowserInfos();
/**
* Save the PDF browser choice to the common configuration.
*/
virtual void WritePdfBrowserInfos();
/**
* Sets the environment variable \a aName to \a aValue. * Sets the environment variable \a aName to \a aValue.
* *
* This function first checks to see if the environment variable \a aName is already * This function first checks to see if the environment variable \a aName is already
@ -282,45 +268,42 @@ public:
* @param aValue is a wxString containing the environment variable value. * @param aValue is a wxString containing the environment variable value.
* @return true if the environment variable \a Name was set to \a aValue. * @return true if the environment variable \a Name was set to \a aValue.
*/ */
VTBL_ENTRY bool SetLocalEnvVariable( const wxString& aName, const wxString& aValue ); virtual bool SetLocalEnvVariable( const wxString& aName, const wxString& aValue );
/** /**
* Function SetLocalEnvVariables * Set the internal local environment variable map to \a aEnvVarMap, updates the entries
* * in the .kicad_common configuration file and sets the environment variable to the new
* sets the internal local environment variable map to \a aEnvVarMap, updates the entries
* in the .kicad_common configuration file, and sets the environment variable to the new
* settings. * settings.
* *
* @param aEnvVarMap is a ENV_VAR_MAP object containing the new environment variables. * @param aEnvVarMap is a #ENV_VAR_MAP object containing the new environment variables.
*/ */
VTBL_ENTRY void SetLocalEnvVariables( const ENV_VAR_MAP& aEnvVarMap ); virtual void SetLocalEnvVariables( const ENV_VAR_MAP& aEnvVarMap );
VTBL_ENTRY const ENV_VAR_MAP& GetLocalEnvVariables() const virtual const ENV_VAR_MAP& GetLocalEnvVariables() const
{ {
return m_local_env_vars; return m_local_env_vars;
} }
/** /**
* Function App * Returns a bare naked wxApp which may come from wxPython, SINGLE_TOP, or kicad.exe.
* returns a bare naked wxApp, which may come from wxPython, SINGLE_TOP, or kicad.exe. *
* Should return what wxGetApp() returns. * This should return what wxGetApp() returns.
*/ */
VTBL_ENTRY wxApp& App(); virtual wxApp& App();
//----</Cross Module API>----------------------------------------------------
static const wxChar workingDirKey[]; static const wxChar workingDirKey[];
/** /**
* Function initPgm * Initialize this program.
* initializes this program (process) in a KiCad standard way, *
* using some generalized techniques. * Initialize the process in a KiCad standard way using some generalized techniques:
* - Default paths (help, libs, bin) and configuration file names * - Default paths (help, libs, bin) and configuration file names
* - Language and locale * - Language and locale
* - fonts * - fonts
* <p> *
* But nothing relating to DSOs or projects. * @note Do not initialize anything relating to DSOs or projects.
* @return bool - true if success, false if failure and program is to terminate. *
* @return true if success, false if failure and program is to terminate.
*/ */
bool InitPgm(); bool InitPgm();
@ -330,8 +313,7 @@ public:
void Destroy(); void Destroy();
/** /**
* Function saveCommonSettings * Save the program (process) settings subset which are stored .kicad_common.
* saves the program (process) settings subset which are stored .kicad_common
*/ */
void SaveCommonSettings(); void SaveCommonSettings();
@ -343,10 +325,19 @@ public:
int m_ModalDialogCount; int m_ModalDialogCount;
protected: protected:
/// Loads internal settings from COMMON_SETTINGS /// Loads internal settings from COMMON_SETTINGS
void loadCommonSettings(); void loadCommonSettings();
/// Trap all changes in here, simplifies debugging
void setLanguageId( int aId ) { m_language_id = aId; }
/**
* Find the path to the executable and stores it in PGM_BASE::m_bin_dir.
*
* @return true if success, else false.
*/
bool setExecutablePath();
std::unique_ptr<SETTINGS_MANAGER> m_settings_manager; std::unique_ptr<SETTINGS_MANAGER> m_settings_manager;
/// prevents multiple instances of a program from being run at the same time. /// prevents multiple instances of a program from being run at the same time.
@ -367,16 +358,6 @@ protected:
/// true to use the selected PDF browser, if exists, or false to use the default /// true to use the selected PDF browser, if exists, or false to use the default
bool m_use_system_pdf_browser; bool m_use_system_pdf_browser;
/// Trap all changes in here, simplifies debugging
void setLanguageId( int aId ) { m_language_id = aId; }
/**
* Function setExecutablePath
* finds the path to the executable and stores it in PGM_BASE::m_bin_dir
* @return bool - true if success, else false.
*/
bool setExecutablePath();
/// The file name of the the program selected for browsing pdf files. /// The file name of the the program selected for browsing pdf files.
wxString m_pdf_browser; wxString m_pdf_browser;
wxString m_editor_name; wxString m_editor_name;
@ -394,7 +375,7 @@ protected:
/// Implemented in: 1) common/single_top.cpp, 2) kicad/kicad.cpp, and 3) scripting/kiway.i /// Implemented in: 1) common/single_top.cpp, 2) kicad/kicad.cpp, and 3) scripting/kiway.i
extern PGM_BASE& Pgm(); extern PGM_BASE& Pgm();
/// similat to PGM_BASE& Pgm(), but return a reference that can be nullptr /// similar to PGM_BASE& Pgm(), but return a reference that can be nullptr
/// when running a shared lib from a script, not from a kicad appl /// when running a shared lib from a script, not from a kicad appl
extern PGM_BASE* PgmOrNull(); extern PGM_BASE* PgmOrNull();

212
include/project.h
View File

@ -1,7 +1,7 @@
/* /*
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2014-2017 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2014-2020 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -52,27 +52,24 @@ class FILENAME_RESOLVER;
class PROJECT_FILE; class PROJECT_FILE;
class PROJECT_LOCAL_SETTINGS; class PROJECT_LOCAL_SETTINGS;
#define VTBL_ENTRY virtual
/** /**
* PROJECT * Container for project specific data.
* holds project specific data. Because it is in the neutral program top, which *
* is not linked to by subsidiarly DSOs, any functions in this interface must * Because it is in the neutral program top, which is not linked to by subsidiarly DSOs,
* be VTBL_ENTRYs. * any functions in this interface must be virtual.
*/ */
class PROJECT class PROJECT
{ {
friend class SETTINGS_MANAGER; // so that SM can set project path
friend class TEST_NETLISTS_FIXTURE; // TODO(JE) make this not required
public: public:
/**
/// A PROJECT can hold stuff it knows nothing about, in the form of * A #PROJECT can hold stuff it knows nothing about, in the form of _ELEM derivatives.
/// _ELEM derivatives. Derive PROJECT elements from this, it has a virtual *
/// destructor, and Elem*() functions can work with it. Implementation is * Derive #PROJECT elements from this, it has a virtual destructor, and Elem*() functions
/// opaque in class PROJECT. If find you have to include derived class headers * can work with it. Implementation is opaque in class #PROJECT. If find you have to
/// in this file, you are doing incompatible with the goal of this class. * include derived class headersin this file, you are doing incompatible with the goal
/// Keep knowledge of derived classes opaque to class PROJECT please. * of this class. Keep knowledge of derived classes opaque to class PROJECT please.
*/
class _ELEM class _ELEM
{ {
public: public:
@ -82,71 +79,76 @@ public:
}; };
PROJECT(); PROJECT();
VTBL_ENTRY ~PROJECT(); virtual ~PROJECT();
//-----<Cross Module API>---------------------------------------------------- //-----<Cross Module API>----------------------------------------------------
VTBL_ENTRY bool TextVarResolver( wxString* aToken ) const; virtual bool TextVarResolver( wxString* aToken ) const;
VTBL_ENTRY std::map<wxString, wxString>& GetTextVars() const; virtual std::map<wxString, wxString>& GetTextVars() const;
/** /**
* Function GetProjectFullName * Return the full path and name of the project.
* returns the full path and name of the project. This is the same as the *
* name of the *.pro file and will always be an absolute path. * This is the same as the name of the project file (.pro prior to version 6 and .kicad_prj
* from version 6 onwards) and will always be an absolute path.
*/ */
VTBL_ENTRY const wxString GetProjectFullName() const; virtual const wxString GetProjectFullName() const;
/** /**
* Function GetProjectPath * Return the full path of the project.
* returns the full path of the project. This is the path *
* of the *.pro file and will always be an absolute path, ending by a dir separator. * This is the path of the project file and will always be an absolute path, ending with
* a path separator.
*/ */
VTBL_ENTRY const wxString GetProjectPath() const; virtual const wxString GetProjectPath() const;
/** /**
* Function GetProjectName * Return the short name of the project.
* returns the short name of the project. This is the file name without *
* extension or path. * This is the file name without extension or path.
*/ */
VTBL_ENTRY const wxString GetProjectName() const; virtual const wxString GetProjectName() const;
/** /**
* Checks if this project is a null project (i.e. the default project object created when * Check if this project is a null project (i.e. the default project object created when
* no real project is open). The null project still presents all the same project interface, * no real project is open).
* but is not backed by any files, so saving it makes no sense. *
* @return true if this is a bull project * The null project still presents all the same project interface, but is not backed by
* any files, so saving it makes no sense.
*
* @return true if this is an empty project.
*/ */
VTBL_ENTRY bool IsNullProject() const; virtual bool IsNullProject() const;
VTBL_ENTRY bool IsReadOnly() const { return m_readOnly || IsNullProject(); } virtual bool IsReadOnly() const { return m_readOnly || IsNullProject(); }
VTBL_ENTRY void SetReadOnly( bool aReadOnly = true ) { m_readOnly = aReadOnly; } virtual void SetReadOnly( bool aReadOnly = true ) { m_readOnly = aReadOnly; }
/** /**
* Return the name of the sheet identified by the given UUID. * Return the name of the sheet identified by the given UUID.
*/ */
VTBL_ENTRY const wxString GetSheetName( const KIID& aSheetID ); virtual const wxString GetSheetName( const KIID& aSheetID );
/** /**
* Function FootprintLibTblName * Returns the path and filename of this project's footprint library table.
* returns the path and filename of this project's fp-lib-table, *
* i.e. the project specific one, not the global one. * This project specific footprint library table not the global one.
*/ */
VTBL_ENTRY const wxString FootprintLibTblName() const; virtual const wxString FootprintLibTblName() const;
/** /**
* Return the path and file name of this projects symbol library table. * Return the path and file name of this projects symbol library table.
*/ */
VTBL_ENTRY const wxString SymbolLibTableName() const; virtual const wxString SymbolLibTableName() const;
VTBL_ENTRY PROJECT_FILE& GetProjectFile() const virtual PROJECT_FILE& GetProjectFile() const
{ {
wxASSERT( m_projectFile ); wxASSERT( m_projectFile );
return *m_projectFile; return *m_projectFile;
} }
VTBL_ENTRY PROJECT_LOCAL_SETTINGS& GetLocalSettings() const virtual PROJECT_LOCAL_SETTINGS& GetLocalSettings() const
{ {
wxASSERT( m_localSettings ); wxASSERT( m_localSettings );
return *m_localSettings; return *m_localSettings;
@ -175,24 +177,25 @@ public:
}; };
/** /**
* Function GetRString * Return a "retained string", which is any session and project specific string
* returns a "retained string", which is any session and project specific string * identified in enum #RSTRING_T.
* identified in enum RSTRING_T. Retained strings are not written to disk, and *
* are therefore good only for the current session. *Retained strings are not written to disk, and are therefore good only for the current
* session.
*/ */
VTBL_ENTRY const wxString& GetRString( RSTRING_T aStringId ); virtual const wxString& GetRString( RSTRING_T aStringId );
/** /**
* Function SetRString * Store a "retained string", which is any session and project specific string
* stores a "retained string", which is any session and project specific string * identified in enum #RSTRING_T.
* identified in enum RSTRING_T. Retained strings are not written to disk, and *
* are therefore good only for the current session. * Retained strings are not written to disk, and are therefore good only for the current
* session.
*/ */
VTBL_ENTRY void SetRString( RSTRING_T aStringId, const wxString& aString ); virtual void SetRString( RSTRING_T aStringId, const wxString& aString );
/** /**
* Enum ELEM_T * The set of #_ELEMs that a #PROJECT can hold.
* is the set of _ELEMs that a PROJECT can hold.
*/ */
enum ELEM_T enum ELEM_T
{ {
@ -207,26 +210,27 @@ public:
}; };
/** /**
* Typically wrapped somewhere else in a more meaningful function wrapper. * Get and set the elements for this project.
* This is a cross module API, therefore the _ELEM destructor is virtual and *
* This is a cross module API, therefore the #_ELEM destructor is virtual and
* can point to a destructor function in another link image. Be careful that * can point to a destructor function in another link image. Be careful that
* that program module is resident at time of destruction. * that program module is resident at time of destruction.
* <p> *
* Summary: 1) cross module API, 2) PROJECT knows nothing about _ELEM objects, * Summary:
* except how to delete them and set and get pointers to them. * -#) cross module API.
* -#) #PROJECT knows nothing about #_ELEM objects except how to delete them and
* set and get pointers to them.
*/ */
VTBL_ENTRY _ELEM* GetElem( ELEM_T aIndex ); virtual _ELEM* GetElem( ELEM_T aIndex );
VTBL_ENTRY void SetElem( ELEM_T aIndex, _ELEM* aElem ); virtual void SetElem( ELEM_T aIndex, _ELEM* aElem );
/** /**
* Function ElemsClear * Delete all the _ELEMs and set their pointers to NULL.
* deletes all the _ELEMs and set their pointers to NULL.
*/ */
VTBL_ENTRY void ElemsClear(); virtual void ElemsClear();
/** /**
* Function Clear * Clear the _ELEMs and RSTRINGs.
* clears the _ELEMs and RSTRINGs.
*/ */
void Clear() // inline not virtual void Clear() // inline not virtual
{ {
@ -237,22 +241,18 @@ public:
} }
/** /**
* Function AbsolutePath * Fix up @a aFileName if it is relative to the project's directory to be an absolute
* fixes up @a aFileName if it is relative to the project's directory to * path and filename.
* be an absolute path and filename. This intends to overcome the now missing *
* chdir() into the project directory. * This intends to overcome the now missing chdir() into the project directory.
*/ */
VTBL_ENTRY const wxString AbsolutePath( const wxString& aFileName ) const; virtual const wxString AbsolutePath( const wxString& aFileName ) const;
/** /**
* Return the table of footprint libraries. Requires an active Kiway as * Return the table of footprint libraries. Requires an active Kiway as this is fetched
* this is fetched from pcbnew. * from Pcbnew.
*/ */
VTBL_ENTRY FP_LIB_TABLE* PcbFootprintLibs( KIWAY& aKiway ); virtual FP_LIB_TABLE* PcbFootprintLibs( KIWAY& aKiway );
//-----</Cross Module API>---------------------------------------------------
//-----<KIFACE Specific APIs>------------------------------------------------
// These are the non-virtual DATA LOAD ON DEMAND members. They load project related // These are the non-virtual DATA LOAD ON DEMAND members. They load project related
// data on demand, and do so typicallly into m_elems[] at a particular index using // data on demand, and do so typicallly into m_elems[] at a particular index using
@ -263,19 +263,18 @@ public:
// non-virtuals resident in PCBNEW link image(s). By being non-virtual, these // non-virtuals resident in PCBNEW link image(s). By being non-virtual, these
// functions can get linked into the KIFACE that needs them, and only there. // functions can get linked into the KIFACE that needs them, and only there.
// In fact, the other KIFACEs don't even know they exist. // In fact, the other KIFACEs don't even know they exist.
#if defined(PCBNEW) || defined(CVPCB) #if defined( PCBNEW ) || defined( CVPCB )
/** /**
* Return the table of footprint libraries without Kiway, only from within * Return the table of footprint libraries without Kiway, only from within Pcbnew.
* pcbnew.
*/ */
FP_LIB_TABLE* PcbFootprintLibs(); FP_LIB_TABLE* PcbFootprintLibs();
/** /**
* Function Get3DCacheManager * Return a pointer to an instance of the 3D cache manager.
* returns a pointer to an instance of the 3D cache manager;
* an instance is created and initialized if appropriate.
* *
* @return a pointer to an instance of the 3D cache manager or NULL on failure * An instance is created and initialized if appropriate.
*
* @return a pointer to an instance of the 3D cache manager or NULL on failure.
*/ */
S3D_CACHE* Get3DCacheManager( bool updateProjDir = false ); S3D_CACHE* Get3DCacheManager( bool updateProjDir = false );
@ -284,7 +283,7 @@ public:
#endif #endif
#if defined(EESCHEMA) #if defined( EESCHEMA )
// These are all prefaced with "Sch" // These are all prefaced with "Sch"
PART_LIBS* SchLibs(); PART_LIBS* SchLibs();
@ -298,34 +297,39 @@ public:
FILENAME_RESOLVER* Get3DFilenameResolver() { return nullptr; } FILENAME_RESOLVER* Get3DFilenameResolver() { return nullptr; }
#endif #endif
//-----</KIFACE Specific APIs>-----------------------------------------------
private: private:
friend class SETTINGS_MANAGER; // so that SM can set project path
friend class TEST_NETLISTS_FIXTURE; // TODO(JE) make this not required
/** /**
* Sets the: * Set the full directory, basename, and extension of the project.
* 1) full directory, 2) basename, and 3) extension of the project. This is *
* the name of the *.pro file with full absolute path and it also defines * This is the name of the project file with full absolute path and it also defines
* the name of the project. The project name and the *.pro file names are * the name of the project. The project name and the project file names are exactly
* exactly the same, providing the *.pro filename is absolute. * the same, providing the project filename is absolute.
*/ */
VTBL_ENTRY void setProjectFullName( const wxString& aFullPathAndName ); virtual void setProjectFullName( const wxString& aFullPathAndName );
/** /**
* Sets the backing store file for this project * Set the backing store file for this project.
* Should only be called by SETTINGS_MANGER on load. *
* @param aFile is a loaded PROJECT_FILE * This should only be called by #SETTINGS_MANGER on load.
*
* @param aFile is a loaded PROJECT_FILE.
*/ */
VTBL_ENTRY void setProjectFile( PROJECT_FILE* aFile ) virtual void setProjectFile( PROJECT_FILE* aFile )
{ {
m_projectFile = aFile; m_projectFile = aFile;
} }
/** /**
* Sets the local settings backing store. Should only be called by SETTINGS_MANAGER on load. * Set the local settings backing store.
*
* This should only be called by #SETTINGS_MANAGER on load.
*
* @param aSettings is the local settings object (may or may not exist on disk at this point) * @param aSettings is the local settings object (may or may not exist on disk at this point)
*/ */
VTBL_ENTRY void setLocalSettings( PROJECT_LOCAL_SETTINGS* aSettings ) virtual void setLocalSettings( PROJECT_LOCAL_SETTINGS* aSettings )
{ {
m_localSettings = aSettings; m_localSettings = aSettings;
} }