From a1fae02427509d3aa30808efbdcde3baaa381cdc Mon Sep 17 00:00:00 2001 From: Wayne Stambaugh Date: Sat, 19 Dec 2020 11:00:52 -0500 Subject: [PATCH] Header clean up round 2. --- common/hotkeys_basic.cpp | 44 ++-- include/filehistory.h | 8 +- include/filename_resolver.h | 182 ++++++-------- include/fill_type.h | 7 +- include/filter_reader.h | 32 ++- include/footprint_info.h | 87 ++++--- include/fp_lib_table.h | 129 ++++------ include/frame_type.h | 6 +- include/gbr_metadata.h | 254 +++++++++++-------- include/gbr_netlist_metadata.h | 142 ++++++----- include/gestfich.h | 61 +++-- include/gl_context_mgr.h | 45 ++-- include/gl_utils.h | 15 +- include/gr_basic.h | 86 ++++--- include/gr_text.h | 110 ++++---- include/grid_tricks.h | 24 +- include/hashtables.h | 75 +++--- include/hotkeys_basic.h | 77 +++--- include/ki_exception.h | 55 ++-- include/kicad_string.h | 54 ++-- include/kiface_i.h | 66 ++--- include/kiway.h | 445 ++++++++++++++++----------------- include/kiway_express.h | 29 +-- include/kiway_holder.h | 30 +-- include/kiway_mgr.h | 10 +- include/kiway_player.h | 148 +++++------ include/pgm_base.h | 231 ++++++++--------- include/project.h | 212 ++++++++-------- 28 files changed, 1291 insertions(+), 1373 deletions(-) diff --git a/common/hotkeys_basic.cpp b/common/hotkeys_basic.cpp index 2c615b8313..7013679240 100644 --- a/common/hotkeys_basic.cpp +++ b/common/hotkeys_basic.cpp @@ -2,8 +2,8 @@ * 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) 2010-2011 Wayne Stambaugh - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2010 Wayne Stambaugh + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * 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 - * Only some wxWidgets key values are handled for function key ( see - * hotkeyNameList[] ) - * @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) - * @return the key name in a wxString + * Return the key name from the key code. + * + * Only some wxWidgets key values are handled for function key ( see hotkeyNameList[] ) + * + * @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). + * @return the key name in a wxString. */ 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 aHotKey - the hotkey keycode - * @param aStyle - IS_HOTKEY to add (shortcuts in menus, same as hotkeys) - * IS_COMMENT to add <(keyname)> mainly in tool tips + * @param aText the base text on which to append the hotkey. + * @param aHotKey the hotkey keycode. + * @param aStyle IS_HOTKEY to add (shortcuts in menus, same as hotkeys). + * IS_COMMENT to add <(keyname)> mainly in tool tips. */ 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: // WX spews debug from wxAcceleratorEntry::ParseAccel if it doesn't - // recognise the keyname, which is the case for . + // recognize the keyname, which is the case for . if( aHotKey != 0 ) { 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 ) { @@ -312,7 +310,6 @@ int KeyCodeFromKeyName( const wxString& keyname ) /* - * DisplayHotkeyList * Displays the hotkeys registered with the given tool manager. */ 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& aHotKeys ) +void ReadHotKeyConfig( const wxString& aFileName, std::map& aHotKeys ) { + wxString fileName = aFileName; + if( fileName.IsEmpty() ) { wxFileName fn( "user" ); @@ -367,22 +366,19 @@ int WriteHotKeyConfig( const std::map& aActionMap ) fn.SetPath( SETTINGS_MANAGER::GetUserSettingsPath() ); // Read the existing config (all hotkeys) - // ReadHotKeyConfig( fn.GetFullPath(), hotkeys ); // Overlay the current app's hotkey definitions onto the map - // for( const auto& ii : aActionMap ) hotkeys[ ii.first ] = ii.second->GetHotKey(); // Write entire hotkey set - // - wxFFileOutputStream outStream( fn.GetFullPath() ); wxTextOutputStream txtStream( outStream, wxEOL_UNIX ); 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(); outStream.Close(); diff --git a/include/filehistory.h b/include/filehistory.h index cc22bc51fd..cd1daac902 100644 --- a/include/filehistory.h +++ b/include/filehistory.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 Ian McInerney - * 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 * modify it under the terms of the GNU General Public License @@ -131,7 +131,7 @@ public: 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. * * @param aHistory is the file history to check for items @@ -156,8 +156,8 @@ protected: private: /** - * Test if the file history is empty. This function is designed to be used with a SELECTION_CONDITION - * to enable/disable the file history menu. + * Test if the file history is empty. This function is designed to be used with a + * #SELECTION_CONDITION to enable/disable the file history menu. * * @param aSelection is unused * @param aHistory is the file history to test for items diff --git a/include/filename_resolver.h b/include/filename_resolver.h index 8c2f220853..fb1d2a4afb 100644 --- a/include/filename_resolver.h +++ b/include/filename_resolver.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015-2016 Cirilo Bernardo + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -23,11 +24,6 @@ /** * @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 @@ -48,158 +44,144 @@ struct SEARCH_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 { -private: - wxString m_configDir; // 3D configuration directory - std::list 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: FILENAME_RESOLVER(); /** - * Function Set3DConfigDir - * sets the user's configuration directory - * for 3D models. + * Set the user's configuration directory for 3D models. * * @param aConfigDir - * @return true if the call succeeds (directory exists) + * @return true if the call succeeds (directory exists). */ bool Set3DConfigDir( const wxString& aConfigDir ); /** - * Function SetProjectDir - * sets the current KiCad project directory as the first - * entry in the model path list + * Set the current KiCad project directory as the first entry in the model path list. * * @param[in] aProjDir current project directory * @param[out] flgChanged optional, set to true if directory was changed * @retval true success * @retval false failure */ - bool SetProject( PROJECT* aProject, bool* flgChanged = NULL ); + bool SetProject( PROJECT* aProject, bool* flgChanged = nullptr ); wxString GetProjectDir( void ); /** - * Function SetProgramBase - * sets a pointer to the application's PGM_BASE instance; - * the pointer is used to extract the local env vars. + * Set a pointer to the application's #PGM_BASE instance used to extract the local env vars. */ void SetProgramBase( PGM_BASE* aBase ); /** - * Function UpdatePathList - * clears the current path list and substitutes the given path - * list, updating the path configuration file on success. + * Clear the current path list and substitutes the given path list and update the path + * configuration file on success. */ bool UpdatePathList( std::vector< SEARCH_PATH >& aPathList ); /** - * Function ResolvePath - * determines the full path of the given file name. In the future - * remote files may be supported, in which case it is best to - * require a full URI in which case ResolvePath should check that - * the URI conforms to RFC-2396 and related documents and copies - * aFileName into aResolvedName if the URI is valid. + * Determines the full path of the given file name. + * + * In the future remote files may be supported, in which case it is best to require a full + * URI in which case ResolvePath should check that the URI conforms to RFC-2396 and related + * documents and copies \a aFileName into aResolvedName if the URI is valid. */ wxString ResolvePath( const wxString& aFileName ); /** - * Function ShortenPath - * produces a relative path based on the existing - * search directories or returns the same path if - * the path is not a superset of an existing search path. + * Produce a relative path based on the existing 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 - * @return the shortened path or aFullPathName + * @param aFullPathName is an absolute path to shorten. + * @return the shortened path or \a aFullPathName. */ wxString ShortenPath( const wxString& aFullPathName ); /** - * Function GetPaths - * returns a pointer to the internal path list; the items in:load + * Return a pointer to the internal path list; the items in:load. * - * the list can be used to set up the list of search paths - * available to a 3D file browser. + * The list can be used to set up the list of search paths 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 ); /** - * Function SplitAlias - * returns true if the given name contains an alias and - * populates the string anAlias with the alias and aRelPath - * with the relative path. + * Return true if the given name contains an alias and populates the string \a anAlias + * with the alias and \a aRelPath with the relative path. */ 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. */ bool ValidateFileName( const wxString& aFileName, bool& hasAlias ); /** - * Function GetKicadPaths - * returns a list of path environment variables local to Kicad; - * this list always includes KISYS3DMOD even if it is not - * defined locally. + * Return a list of path environment variables local to KiCad. + * + * This list always includes KISYS3DMOD even if it is not defined locally. */ 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 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 diff --git a/include/fill_type.h b/include/fill_type.h index ee54a87865..bfe1b5a959 100644 --- a/include/fill_type.h +++ b/include/fill_type.h @@ -21,10 +21,9 @@ #define FILL_TYPE_H /** - * Enum class FILL_TYPE - * is the set of fill types used in plotting or drawing enclosed areas. + * 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 { @@ -35,4 +34,4 @@ enum class FILL_TYPE : int FILLED_WITH_COLOR =3 // Fill with a user-defined color (currently sheets only) }; -#endif \ No newline at end of file +#endif diff --git a/include/filter_reader.h b/include/filter_reader.h index 30c9009573..177b2b2bb2 100644 --- a/include/filter_reader.h +++ b/include/filter_reader.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2007-2010 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -30,19 +30,14 @@ /** - * FILTER_READER - * reads lines of text from another LINE_READER, but only returns non-comment - * lines and non-blank lines from its ReadLine() function. + * Read lines of text from another #LINE_READER but only returns non-comment lines and + * non-blank lines from its ReadLine() function. */ class FILTER_READER : public LINE_READER { - LINE_READER& reader; - 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 ); @@ -59,24 +54,22 @@ public: { return reader.LineNumber(); } + +private: + LINE_READER& reader; }; /** - * WHITESPACE_FILTER_READER - * reads lines of text from another LINE_READER, but only returns non-comment - * lines and non-blank lines with leading whitespace characters (space and tab) - * removed from its ReadLine() function. + * Read lines of text from another #LINE_READER but only returns non-comment lines and + * non-blank lines with leading whitespace characters (space and tab) removed from its + * ReadLine() function. */ class WHITESPACE_FILTER_READER : public LINE_READER { - LINE_READER& reader; - public: - /** - * Constructor ( LINE_READER& ) - * does not take ownership over @a aReader, so will not destroy it. + * Doe not take ownership over @a aReader, so will not destroy it. */ WHITESPACE_FILTER_READER( LINE_READER& aReader ); @@ -93,6 +86,9 @@ public: { return reader.LineNumber(); } + +private: + LINE_READER& reader; }; #endif // FILTER_READER_H_ diff --git a/include/footprint_info.h b/include/footprint_info.h index 2a50625496..63a2663752 100644 --- a/include/footprint_info.h +++ b/include/footprint_info.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2011 Jean-Pierre Charras, - * 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 * 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 { - friend bool operator<( const FOOTPRINT_INFO& item1, const FOOTPRINT_INFO& item2 ); - public: virtual ~FOOTPRINT_INFO() { @@ -134,6 +132,9 @@ public: */ friend bool operator<( const FOOTPRINT_INFO& lhs, const FOOTPRINT_INFO& rhs ); +private: + friend bool operator<( const FOOTPRINT_INFO& item1, const FOOTPRINT_INFO& item2 ); + protected: 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. * * This is a virtual class; its implementation lives in pcbnew/footprint_info_impl.cpp. @@ -167,18 +168,10 @@ protected: */ class APIEXPORT FOOTPRINT_LIST { - friend class FOOTPRINT_ASYNC_LOADER; - -protected: - FP_LIB_TABLE* m_lib_table; ///< no ownership - +public: typedef std::vector> FPILIST; typedef SYNC_QUEUE> ERRLIST; - FPILIST m_list; - ERRLIST m_errors; ///< some can be PARSE_ERRORs also - -public: FOOTPRINT_LIST() : m_lib_table( 0 ) { } @@ -225,8 +218,9 @@ public: /** * 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 ) { @@ -250,13 +244,13 @@ public: * Read all the footprints provided by the combination of aTable and aNickname. * * @param aTable defines all the libraries. - * @param aNickname is the library to read from, or if NULL means read all - * footprints from all known libraries in aTable. - * @param aProgressReporter is an optional progress reporter. ReadFootprintFiles() - * will use 2 phases within the reporter. - * @return bool - true if it ran to completion, else false if it aborted after - * some number of errors. If true, it does not mean there were no errors, check - * GetErrorCount() for that, should be zero to indicate success. + * @param aNickname is the library to read from, or if NULL means read all footprints + * from all known libraries in aTable. + * @param aProgressReporter is an optional progress reporter. ReadFootprintFiles() will + * use 2 phases within the reporter. + * @return true if it ran to completion, else false if it aborted after some number of + * errors. If true, it does not mean there were no errors, check GetErrorCount() + * for that, should be zero to indicate success. */ virtual bool ReadFootprintFiles( FP_LIB_TABLE* aTable, const wxString* aNickname = nullptr, PROGRESS_REPORTER* aProgressReporter = nullptr ) = 0; @@ -269,17 +263,18 @@ public: } /** - * Factory function to return a FOOTPRINT_LIST via Kiway. NOT guaranteed - * to succeed; will return null if the kiface is not available. + * Factory function to return a #FOOTPRINT_LIST via Kiway. * - * @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 ); protected: /** - * Launch worker threads to load footprints. Part of the - * FOOTPRINT_ASYNC_LOADER implementation. + * Launch worker threads to load footprints. Part of the #FOOTPRINT_ASYNC_LOADER + * implementation. */ virtual void startWorkers( FP_LIB_TABLE* aTable, wxString const* aNickname, FOOTPRINT_ASYNC_LOADER* aLoader, unsigned aNThreads ) = 0; @@ -293,24 +288,26 @@ protected: * Stop worker threads. Part of the FOOTPRINT_ASYNC_LOADER implementation. */ 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. - * Constructing one, calling .Start(), then waiting until it reports completion - * is equivalent to calling FOOTPRINT_LIST::ReadFootprintFiles(). + * Object used to populate a #FOOTPRINT_LIST asynchronously. + * + * Construct one, calling #Start(), and then waiting until it reports completion. This is + * equivalent to calling #FOOTPRINT_LIST::ReadFootprintFiles(). */ 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: /** * Construct an asynchronous loader. @@ -327,9 +324,10 @@ public: /** * Launch the worker threads. + * * @param aTable defines all the libraries. - * @param aNickname is the library to read from, or if NULL means read all - * footprints from all known libraries in aTable. + * @param aNickname is the library to read from, or if NULL means read all footprints from + * all known libraries in \a aTable. * @param aNThreads is the number of worker threads. */ void Start( FP_LIB_TABLE* aTable, wxString const* aNickname = nullptr, @@ -356,11 +354,20 @@ public: */ void Abort(); +private: /** * Default number of worker threads. Determined empirically (by dickelbeck): * More than 6 is not significantly faster, less than 6 is likely slower. */ 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; }; diff --git a/include/fp_lib_table.h b/include/fp_lib_table.h index 6272f37f52..89dc8638e3 100644 --- a/include/fp_lib_table.h +++ b/include/fp_lib_table.h @@ -2,8 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2012-2017 Wayne Stambaugh - * Copyright (C) 2012-2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2012-2020 Wayne Stambaugh + * Copyright (C) 2012-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -34,15 +34,11 @@ class FP_LIB_TABLE_GRID; /** - * FP_LIB_TABLE_ROW - * - * holds a record identifying a library accessed by the appropriate footprint library #PLUGIN + * Hold a record identifying a library accessed by the appropriate footprint library #PLUGIN * object in the #FP_LIB_TABLE. */ class FP_LIB_TABLE_ROW : public LIB_TABLE_ROW { - friend class FP_LIB_TABLE; - public: 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 ); } /** - * Function GetType - * - * returns the type of footprint library table represented by this row. + * return the type of footprint library table represented by this row. */ const wxString GetType() const override { return IO_MGR::ShowType( type ); } /** - * Function SetType - * - * changes the type represented by this row. + * Change the type represented by this row. */ void SetType( const wxString& aType ) override; @@ -84,7 +76,6 @@ protected: } private: - virtual LIB_TABLE_ROW* do_clone() const override { return new FP_LIB_TABLE_ROW( *this ); @@ -95,6 +86,8 @@ private: plugin.set( aPlugin ); } + friend class FP_LIB_TABLE; + PLUGIN::RELEASER plugin; LIB_T type; }; @@ -102,8 +95,6 @@ private: class FP_LIB_TABLE : public LIB_TABLE { - friend class FP_LIB_TABLE_GRID; - public: KICAD_T Type() override { return FP_LIB_TABLE_T; } @@ -112,42 +103,36 @@ public: virtual void Format( OUTPUTFORMATTER* aOutput, int aIndentLevel ) const override; /** - * Constructor FP_LIB_TABLE - * - * builds a footprint library table by pre-pending this table fragment in front of + * Build 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(). * - * @param aFallBackTable is another FP_LIB_TABLE which is searched only when - * a row is not found in this table. No ownership is - * taken of aFallBackTable. + * @param aFallBackTable is another FP_LIB_TABLE which is searched only when a row + * is not found in this table. No ownership is taken of + * \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& 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 - * fallBack table fragment. The #PLUGIN is loaded and attached to the "plugin" field - * of the #FP_LIB_TABLE_ROW if not already loaded. + * The #PLUGIN is loaded and attached to the "plugin" field of the #FP_LIB_TABLE_ROW if + * not already loaded. * * @throw IO_ERROR if \a aNickName cannot be found. */ const FP_LIB_TABLE_ROW* FindRow( const wxString& 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 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. */ @@ -161,7 +146,6 @@ public: long long GenerateTimestamp( const wxString* aNickname ); /** - * Function PrefetchLib * If possible, prefetches the specified library (e.g. performing downloads). Does not parse. * Threadsafe. * @@ -174,15 +158,11 @@ public: void PrefetchLib( const wxString& aNickname ); /** - * Function FootprintLoad - * - * 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 + * Load 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 aFootprintName is the name of the footprint to load. - * - * @return FOOTPRINT* - if found caller owns it, else NULL if not found. + * @return the 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 aFootprintName cannot be found. @@ -190,24 +170,20 @@ public: 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 ); /** - * 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 - * cache management. Return value is const to allow it to return a reference to a cached - * item. + * The return value is const to allow it to return a reference to a cached item. */ const FOOTPRINT* GetEnumeratedFootprint( const wxString& aNickname, const wxString& aFootprintName ); /** - * Enum SAVE_T - * is the set of return values from FootprintSave() below. + * The set of return values from FootprintSave() below. */ 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. * - * @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 * footprint after this call. - * * @param aOverwrite when true means overwrite any existing footprint by the same name, * else if false means skip the write and return SAVE_SKIPPED. - * - * @return SAVE_T - SAVE_OK or SAVE_SKIPPED. If error saving, then IO_ERROR is thrown. + * @return #SAVE_OK or #SAVE_SKIPPED. If error saving, then #IO_ERROR is thrown. * * @throw IO_ERROR if there is a problem saving. */ @@ -237,12 +209,9 @@ public: bool aOverwrite = true ); /** - * Function FootprintDelete - * - * 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. + * Delete 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 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. @@ -250,10 +219,9 @@ public: 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 - * system libraries are read only because of where they are installed.) + * Often system libraries are read only because of where they are installed. * * @throw IO_ERROR if no library at aLibraryPath exists. */ @@ -263,25 +231,20 @@ public: void FootprintLibCreate( const wxString& aNickname ); - //-------------------------------- - /** - * Function FootprintLoadWithOptionalNickname - * loads a footprint having @a aFootprintId with possibly an empty nickname. + * Load 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 aFootprintName cannot be 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 PARSE_ERROR if @a aFootprintId is not parsed OK. */ FOOTPRINT* FootprintLoadWithOptionalNickname( const LIB_ID& aFootprintId ); /** - * Function LoadGlobalTable - * loads the global footprint library table into \a aTable. + * Load the global footprint library table into \a aTable. * * 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 @@ -295,22 +258,22 @@ public: static bool LoadGlobalTable( FP_LIB_TABLE& aTable ); /** - * Function GetGlobalTableFileName - * * @return the platform specific global footprint library path and file name. */ 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 - * locally installed "KiCad sponsored" system footprint libraries. These can - * be either legacy or pretty format. The only thing special about this - * particular environment variable is that it is set automatically by - * KiCad on program start up, if it is not set already in the environment. + *These can be either legacy or pretty format. The only thing special about this + * particular environment variable is that it is set automatically by KiCad on + * program start up, if it is not set already in the environment. */ static const wxString GlobalPathEnvVariableName(); + +private: + friend class FP_LIB_TABLE_GRID; }; diff --git a/include/frame_type.h b/include/frame_type.h index d488ec292a..b3ce8c86e4 100644 --- a/include/frame_type.h +++ b/include/frame_type.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * 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 * * This program is free software; you can redistribute it and/or @@ -27,9 +27,7 @@ #define FRAME_T_H_ /** - * Enum FRAME_T - * is the set of EDA_BASE_FRAME derivatives, typically stored in - * EDA_BASE_FRAME::m_Ident. + * The set of #EDA_BASE_FRAME derivatives, typically stored in EDA_BASE_FRAME::m_Ident. */ enum FRAME_T { diff --git a/include/gbr_metadata.h b/include/gbr_metadata.h index c289c6e052..be99309c52 100644 --- a/include/gbr_metadata.h +++ b/include/gbr_metadata.h @@ -2,7 +2,7 @@ * 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 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 * 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. - * used in Gerber plotter to generate auxiliary data during plot - * (for instance info associated to apertures and flashed pads) + * 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) * * @file gbr_metadata.h */ @@ -35,18 +36,25 @@ #include -/** creates the TF.CreationDate attribute: - * The attribute value must conform to the full version of the ISO 8601 - * date and time format, including time and time zone. Note that this is - * the date the Gerber file is effectively created, - * not the time the project of PCB was started - * @param aFormat = string compatibility: X1, X2, GBRJOB or NC drill synthax. - * exemple of structured comment (compatible X1 gerber) - * G04 #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (exemple of X1 attribute) - * exemple NC drill files - * ; #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (exemple of NC drill comment) - * exemple of X2 attribute: +/** + * Create a gerber TF.CreationDate attribute. + * + * The attribute value must conform to the full version of the ISO 8601 date and time format, + * including time and time zone. + * + * Example of structured comment (compatible X1 gerber) + * G04 #@! TF.CreationDate,2018-11-21T08:49:16+01:00* (example of X1 attribute) + * + * Example NC drill files + * ; #@! 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*% + * + * @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 { @@ -58,11 +66,14 @@ enum GBR_NC_STRING_FORMAT // Options for string format in some attribute s 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 - * and therefore the GUID generated has no meaning because it do not use any time and time stamp - * specific to the project, just a random pattern (random is here a pattern specific to a project). + * and therefore the GUID generated has no meaning because it do not use any time and time + * 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 */ @@ -79,41 +90,78 @@ class GBR_APERTURE_METADATA public: enum GBR_APERTURE_ATTRIB { - GBR_APERTURE_ATTRIB_NONE, ///< uninitialized attribute - 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_NONE, ///< uninitialized attribute. + GBR_APERTURE_ATTRIB_ETCHEDCMP, ///< aperture used for etched components. - GBR_APERTURE_ATTRIB_COMPONENTPAD, ///< aperture used for through hole component on outer layer - GBR_APERTURE_ATTRIB_SMDPAD_SMDEF, ///< aperture used for SMD pad. Excluded BGA pads which have their own type - GBR_APERTURE_ATTRIB_SMDPAD_CUDEF, ///< aperture used for SMD pad with a solder mask defined by the solder mask - 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 + ///< aperture used for connected items like tracks (not vias). + GBR_APERTURE_ATTRIB_CONDUCTOR, + GBR_APERTURE_ATTRIB_EDGECUT, ///< aperture used for board cutout, - 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 - GBR_APERTURE_ATTRIB_CMP_OBLONG_DRILL, ///< aperture used for pads oblong holes in drill files - 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 - GBR_APERTURE_ATTRIB_PADOTHER_POSITION, ///< aperture used for flashed pads position in placement files - GBR_APERTURE_ATTRIB_CMP_BODY, ///< aperture used to draw component physical body outline - ///< (without pins) in placement files - GBR_APERTURE_ATTRIB_CMP_LEAD2LEAD, ///< aperture used to draw component physical body outline - ///< (with pins) in placement files - GBR_APERTURE_ATTRIB_CMP_FOOTPRINT, ///< aperture used to draw component footprint bounding box - ///< in placement files - GBR_APERTURE_ATTRIB_CMP_COURTYARD, ///< aperture used to draw component outline courtyard - ///< in placement files + ///< aperture used for not connected items (texts, outlines on copper). + GBR_APERTURE_ATTRIB_NONCONDUCTOR, + GBR_APERTURE_ATTRIB_VIAPAD, ///< aperture used for vias. + + ///< aperture used for through hole component on outer layer. + GBR_APERTURE_ATTRIB_COMPONENTPAD, + + ///< aperture used for SMD pad. Excluded BGA pads which have their own type. + GBR_APERTURE_ATTRIB_SMDPAD_SMDEF, + + ///< aperture used for SMD pad with a solder mask defined by the solder mask. + GBR_APERTURE_ATTRIB_SMDPAD_CUDEF, + + ///< 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 }; @@ -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 ); 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 - * like "%TA.AperFunction,*%" - * @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,*" + * like "%TA.AperFunction,*%" */ static std::string FormatAttribute( GBR_APERTURE_ATTRIB aAttribute, bool aUseX1StructuredComment ); @@ -150,9 +197,11 @@ public: 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: GBR_METADATA(): m_isCopper( false) {} @@ -195,81 +244,82 @@ public: } /** - * 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 + * Allowed attributes are not the same on board copper layers and on other layers. + * + * A flag can be set or reset when attributes can be depending on layers */ bool IsCopper() { return m_isCopper; } void SetCopper( bool aValue ) { m_isCopper = aValue; } /** - * a item to handle aperture attribute: + * An item to handle aperture attribute. */ GBR_APERTURE_METADATA m_ApertureMetadata; /** - * a item to handle object attribute: + * An item to handle object attribute. */ GBR_NETLIST_METADATA m_NetlistMetadata; private: /** - * if the metadata is relative to a copper layer or not. This is a flag - * which can be set/reset when an attribute for a given item depends on the fact - * a copper layer or a non copper layer is plotted. - * The initial state in false. + * If the metadata is relative to a copper layer or not, this flag which can be set/reset + * when an attribute for a given item depends on whether a copper layer or a non copper + * layer is plotted. The initial state i false. */ bool m_isCopper; }; /** - * This helper function "normalize" 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 - * unautorized codes are ',' '*' '%' '\' - * @param aString = the wxString to convert - * @return a std::string (ASCII7 coded) compliant with a gerber string + * Normalize \a aString and convert it to a Gerber std::string. + * + * Normalization means convert any code > 0x7F and unauthorized code to a hexadecimal + * 16 bit sequence Unicode. Illegal characters are ',' '*' '%' '\'. + * + * @param aString the string to convert. + * @return an ASCII7 coded compliant gerber string. */ std::string FormatStringToGerber( const wxString& aString ); /** - * Similar to FormatStringToGerber. - * "normalize" aString and convert it to a Gerber compatible wxString - * Normalisation means unautorized code to a hexadecimal 16 bits sequence unicode - * and, on request convert any code > 0x7F. - * unautorized codes are ',' '*' '%' '\' - * @param aString = the wxString to convert - * @param aAllowUtf8Chars = false to convert non ASCII7 values to unicode sequence - * @param aQuoteString = true to double quote the returned string - * @return a wxString without unautorized chars (and converted non ASCII7 chars on request) + * Normalize \a aString and convert it to a Gerber compatible wxString. + * + * Normalization means convert to a hexadecimal 16 bit sequence Unicode and on request + * convert any code > 0x7F. Illegal characters are ',' '*' '%' '\'. + * + * @param aString the string to convert. + * @param aAllowUtf8Chars false to convert non ASCII7 values to Unicode sequence. + * @param aQuoteString true to double quote the returned string. + * @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() - * 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 - * @return a wxString (unicode 16) from the gerber string + * Convert a gerber string into a 16 bit Unicode string. + * + * @param aString the gerber string to format. + * @return a 16 bit Unicode string. */ wxString FormatStringFromGerber( const wxString& aString ); /** - * Generates the string to print to a gerber file, to set a net attribute - * for a graphic object. - * @param aPrintedText is the string to print + * Generate the string to set a net attribute for a graphic object to print to a gerber file. + * + * @param aPrintedText is the string to print. * @param aLastNetAttributes is the current full set of attributes. - * @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) - * @param aClearPreviousAttributes returns true if the full set of attributes - * must be deleted from file before adding new attribute (happens when a previous - * attribute does not exist no more). - * @param aUseX1StructuredComment = false in X2 mode, and true in X1 mode to add the net attribut - * in compatible X1 structured comment (i.e. prefixed by "G04 #@! ") + * @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) + * @param aClearPreviousAttributes returns true if the full set of attributes must be deleted + * from file before adding new attribute (happens when a previous + * attribute no longer exists). + * @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 #@! ") * @return false if nothing can be done (GBR_NETLIST_METADATA has GBR_APERTURE_ATTRIB_NONE, - * and true if OK - * if the new attribute(s) is the same as current attribute(s), aPrintedText - * will be empty + * and true if OK. If the new attribute(s) is the same as current attribute(s), + * \a aPrintedText will be empty. */ bool FormatNetAttribute( std::string& aPrintedText, std::string& aLastNetAttributes, const GBR_NETLIST_METADATA* aData, bool& aClearPreviousAttributes, diff --git a/include/gbr_netlist_metadata.h b/include/gbr_netlist_metadata.h index 623946cace..00631a6063 100644 --- a/include/gbr_netlist_metadata.h +++ b/include/gbr_netlist_metadata.h @@ -2,7 +2,7 @@ * 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 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 * modify it under the terms of the GNU General Public License @@ -25,9 +25,10 @@ #ifndef 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 - * Only applicable to objects having the TA.AperFunction attribute "ComponentMain" +/** + * Information which can be added in a gerber P&P file as attribute of a component. + * + * 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 * %TO.CRot, The rotation angle of the component. * The rotation angle is consistent with the one for graphics objects. @@ -37,6 +38,7 @@ * Components on the bottom side are of course mirrored. * The base orientation on the bottom side is the one on the top side * mirrored around the X axis. + * * %TO.CMfr, Manufacturer * %TO.CMPN, Manufacturer part number * %TO.Cpkg, Package, as per IPC-7351 @@ -49,8 +51,8 @@ * %TO.CHgt, Height, a decimal, in the unit of the file. * %TO.CLbN, Library name. * %TO.CLbD, Library description. - * %TO.Sup,, SN is a field with the supppier name. - * SPN is a field with the supppier part name + * %TO.Sup,, SN is a field with the supplier name. + * SPN is a field with the supplier part name. */ class GBR_CMP_PNP_METADATA { @@ -62,6 +64,19 @@ public: 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 wxString m_Manufacturer; // Manufacturer name wxString m_MPN; // Manufacturer part number @@ -71,26 +86,15 @@ public: wxString m_LibraryDescr; // Library description wxString m_Value; // Component value 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. - * this is a unicode string with some chars converted in escaped Hexa sequence - * when creating the file - * Chars always escaped because they are separator in Gerber files: * , \ % - * non ascii 7 chars can be converted to UTF8 or escaped. + * A Gerber data field. + * + * This is a Unicode string with some chars converted in escaped hexadecimal sequence + * when creating the file. The following characters are always escaped because they + * are separator in Gerber files: * , \ %. Non ASCII7 characters can be converted to + * UTF8 or escaped. */ class GBR_DATA_FIELD { @@ -120,28 +124,27 @@ public: std::string GetGerberString() const; - 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) - 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 }; -/** this class handle info 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 - * %TO.P - * %TO.N - * %TO.C - * the .P attribute can be used only for flashed pads (using the D03 command) - * 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 - * can be used +/** + * 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: + * - %TO.P + * - %TO.N + * - %TO.C + * + * The .P attribute can be used only for flashed pads (using the D03 command) 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 can be used. */ - class GBR_NETLIST_METADATA { public: @@ -156,40 +159,21 @@ public: 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 ), 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() { 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) { @@ -197,9 +181,11 @@ public: } /** - * remove the net attribute specified by aName - * If aName == NULL or empty, remove all attributes - * @param aName is the name (.CN, .P .N or .C) of the attribute to remove + * 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. */ void ClearAttribute( const wxString* aName ) { @@ -244,11 +230,33 @@ public: 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 -#define GBR_NETINFO_ALL (GBR_NETLIST_METADATA::GBR_NETINFO_PAD\ - | GBR_NETLIST_METADATA::GBR_NETINFO_NET\ - | GBR_NETLIST_METADATA::GBR_NETINFO_CMP ) +#define GBR_NETINFO_ALL \ + ( GBR_NETLIST_METADATA::GBR_NETINFO_PAD | GBR_NETLIST_METADATA::GBR_NETINFO_NET \ + | GBR_NETLIST_METADATA::GBR_NETINFO_CMP ) #endif // GBR_NETLIST_METADATA_H diff --git a/include/gestfich.h b/include/gestfich.h index 6cd1761be5..638d28cd4c 100644 --- a/include/gestfich.h +++ b/include/gestfich.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * 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 * 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 - * @param file = PDF file to open - * @return true is success, false if no PDF viewer found + * Run the PDF viewer and display a PDF file. + * + * @param file the PDF file to open. + * @return true is success or false if no PDF viewer found. */ bool OpenPDF( const wxString& file ); void OpenFile( const wxString& file ); @@ -60,17 +60,14 @@ void PrintFile( 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 aErrors a wxString to *append* any errors to */ void KiCopyFile( const wxString& aSrcPath, const wxString& aDestPath, wxString& aErrors ); /** - * Function EDA_FILE_SELECTOR - * - * is a helper function that wraps a call to wxFileSelector. + * A helper function that wraps a call to wxFileSelector. * * @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. @@ -96,59 +93,57 @@ wxString EDA_FILE_SELECTOR( const wxString& aTitle, int aStyle, const bool aKeepWorkingDirectory, const wxPoint& aPosition = wxDefaultPosition, - wxString* aMruPath = NULL ); + wxString* aMruPath = nullptr ); EDA_LIST_DIALOG* GetFileNames( char* Directory, char* Mask ); /** - * Function ExecuteFile - * calls the executable file \a ExecFile with the command line parameters \a param. + * Call the executable file \a ExecFile with the command line parameters \a param. */ 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). - * @param string = string to modify + * + * @param string string to modify. */ void AddDelimiterString( wxString& string ); /** - * Function KicadDatasPath - * returns the data path common to KiCad. - * If environment variable KICAD is defined (KICAD = path to kicad) + * Return the data path common to KiCad. + * + * If environment variable KICAD is defined (KICAD = path to KiCad) * Returns \ /; * Otherwise returns \ / (if "kicad" is in the path name) * Otherwise returns /usr /share/kicad/ * - * Note: - * The \\ are replaced by / (a la Unix) + * @note The \\ path separators are replaced by / (a la Unix). */ wxString KicadDatasPath(); /** - * Function FindKicadFile - * searches the executable file shortname in KiCad binary path and return full file + * Search 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. * - * kicad binary path is found from: - * BinDir - * or environment variable KICAD - * or (default) c:\\kicad or /usr/local/kicad - * or default binary path + * The binary path is found from: + * - binary path. + * - KICAD environment variable. + * - c:\\kicad or /usr/local/kicad (the default). + * - default binary path. */ wxString FindKicadFile( const wxString& shortname ); /** * Quote return value of wxFileName::GetFullPath(). * - * This allows file name paths with spaces to be used as parameters to - * ProcessExecute function calls. - * @param fn is the filename to wrap - * @param format if provided, can be used to transform the nature of the - * wrapped filename to another platform. + * This allows file name paths with spaces to be used as parameters to ProcessExecute + * function calls. + * + * @param fn is the filename to wrap. + * @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 ); diff --git a/include/gl_context_mgr.h b/include/gl_context_mgr.h index b5812d263f..38a6d0d41c 100644 --- a/include/gl_context_mgr.h +++ b/include/gl_context_mgr.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 CERN + * Copyright (C) 2020 KiCad Developers, see CHANGELOG.TXT for contributors. * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -33,51 +34,53 @@ class GL_CONTEXT_MANAGER { public: /** - * Function Get - * returns the GL_CONTEXT_MANAGER instance (singleton). + * Return the GL_CONTEXT_MANAGER instance (singleton). */ static GL_CONTEXT_MANAGER& Get(); /** - * Function CreateCtx - * creates a managed OpenGL context. It is assured that the created context is freed upon - * exit. - * See wxGLContext documentation for the parameters description. + * Create a managed OpenGL context. + * + * It is assured that the created context is freed upon exit. See wxGLContext + * documentation for the parameters description. + * * @return Created OpenGL context. */ - wxGLContext* CreateCtx( wxGLCanvas* aCanvas, const wxGLContext* aOther = NULL ); + wxGLContext* CreateCtx( wxGLCanvas* aCanvas, const wxGLContext* aOther = nullptr ); /** - * Function DestroyCtx - * destroys a managed OpenGL context. The context to be removed has to be created using - * GL_CONTEXT_MANAGER::CreateCtx() first. + * Destroy a managed OpenGL context. + * + * 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. */ void DestroyCtx( wxGLContext* aContext ); /** - * Function DeleteAll - * destroys all managed OpenGL contexts. This method should be called in the - * final deinitialization routine. + * Destroy all managed OpenGL contexts. + * + * This method should be called in the final deinitialization routine. */ void DeleteAll(); /** - * Function LockCtx - * 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. - * If another canvas has already locked a GL context, then the calling process is blocked. + * Set a context as current and prevents other canvases from switching it. + * + * Requires calling UnlockCtx() when there are no more GL calls for the context. If + * another canvas has already locked a GL context, then the calling process is blocked. + * * @param aContext is the GL context to be bound. * @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 ); /** - * Function UnlockCtx - * allows other canvases to bind an OpenGL context. + * Allow other canvases to bind an OpenGL context. + * * @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 ); diff --git a/include/gl_utils.h b/include/gl_utils.h index a067f2b4f3..bb7853b986 100644 --- a/include/gl_utils.h +++ b/include/gl_utils.h @@ -32,15 +32,16 @@ class GL_UTILS { public: /** - * Attempts to set the OpenGL swap interval - * @param aVal if -1 = try to set adaptive swapping, 0 = sync off, 1 = sync with VSYNC rate + * Attempts to set the OpenGL swap interval. + * + * @param aVal if -1 = try to set adaptive swapping, 0 = sync off, 1 = sync with VSYNC rate. * @return actual value set */ static int SetSwapInterval( int aVal ) { - /// This routine is written for Linux using X11 only. The equivalent functions under Windows would - /// include and call wglSwapIntervalEXT - #if defined( __linux__ ) && !defined( KICAD_USE_EGL ) + /// This routine is written for Linux using X11 only. The equivalent functions under + /// Windows would include and call wglSwapIntervalEXT +#if defined( __linux__ ) && !defined( KICAD_USE_EGL ) Display *dpy = glXGetCurrentDisplay(); GLXDrawable drawable = glXGetCurrentDrawable(); @@ -74,9 +75,9 @@ public: } return std::numeric_limits::max(); - #else +#else return 0; - #endif +#endif } }; diff --git a/include/gr_basic.h b/include/gr_basic.h index 56457c5cd6..51240f9759 100644 --- a/include/gr_basic.h +++ b/include/gr_basic.h @@ -2,8 +2,8 @@ * 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) 2011 Wayne Stambaugh - * Copyright (C) 1992-2018 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2011 Wayne Stambaugh + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * 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 @@ -48,27 +48,27 @@ enum GR_DRAWMODE { UNSPECIFIED_DRAWMODE = -1 }; -inline void DrawModeAddHighlight(GR_DRAWMODE *mode) +inline void DrawModeAddHighlight( GR_DRAWMODE* mode ) { *mode = static_cast( int( *mode ) | GR_HIGHLIGHT ); } -inline void DrawModeAllowHighContrast(GR_DRAWMODE *mode) +inline void DrawModeAllowHighContrast( GR_DRAWMODE* mode ) { *mode = static_cast( int( *mode ) | GR_ALLOW_HIGHCONTRAST ); } -inline GR_DRAWMODE operator ~(const GR_DRAWMODE& a) +inline GR_DRAWMODE operator~( const GR_DRAWMODE& a ) { return static_cast( ~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( 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( 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 ); /** - * 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 ); /** - * Function GetGRForceBlackPenState - * @return ForceBlackPen (True if a black pen was forced) + * @return True if a black pen was forced or false if not forced. */ bool GetGRForceBlackPenState( void ); -void GRLine( EDA_RECT* aClipBox, wxDC* aDC, - wxPoint aStart, wxPoint aEnd, int aWidth, COLOR4D aColor, wxPenStyle aStyle = wxPENSTYLE_SOLID ); -void GRLine( EDA_RECT* ClipBox, wxDC* DC, - int x1, int y1, int x2, int y2, int width, COLOR4D Color, wxPenStyle aStyle = wxPENSTYLE_SOLID ); +void GRLine( EDA_RECT* aClipBox, wxDC* aDC, wxPoint aStart, wxPoint aEnd, int aWidth, + COLOR4D aColor, wxPenStyle aStyle = wxPENSTYLE_SOLID ); +void GRLine( EDA_RECT* ClipBox, wxDC* DC, int x1, int y1, int x2, int y2, int width, + COLOR4D Color, wxPenStyle aStyle = wxPENSTYLE_SOLID ); void GRMoveTo( int x, int y ); -void GRLineTo( EDA_RECT* ClipBox, wxDC* DC, - int x, int y, int width, COLOR4D Color ); +void GRLineTo( EDA_RECT* ClipBox, wxDC* DC, int x, int y, int width, COLOR4D Color ); 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& aPoints, int aWidth, COLOR4D aColor ); /** - * Function GRClosedPoly - * draws a closed polygon onto the drawing context \a aDC and optionally fills - * and/or draws a border around it. + * Draw a closed polygon onto the drawing context \a aDC and optionally fills and/or draws + * a border around it. + * * @param ClipBox defines a rectangular boundary outside of which no drawing will occur. * @param aDC the device context into which drawing should occur. * @param aPointCount the number of points in the array \a aPoints. @@ -134,15 +132,15 @@ void GRBezier( EDA_RECT* aClipBox, wxDC* aDC, std::vector& aPoints, * @param aFillColor the fill color of the polygon's interior. */ 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 // the aPenWidth argument /** - * Function GRClosedPoly - * draws a closed polygon onto the drawing context \a aDC and optionally fills - * and/or draws a border around it. + * Draw a closed polygon onto the drawing context \a aDC and optionally fills and/or draws + * a border around it. + * * @param ClipBox defines a rectangular boundary outside of which no drawing will occur. * @param aDC the device context into which drawing should occur. * @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. */ 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 - * draws a circle onto the drawing context \a aDC centered at the user - * coordinates (x,y) + * Draw 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 aDC the device context into which drawing should occur. * @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 aRadius is the radius of the circle. - * @param aColor is the color to draw + * @param aColor is the color to draw. * @see COLOR4D */ 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, COLOR4D Color, COLOR4D BgColor ); 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, 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 ); void GRFilledArc( EDA_RECT* ClipBox, wxDC* DC, int x, int y, double StAngle, 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, 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 ); /** - * Function GRLineArray - * draws an array of lines (not a polygon). - * @param aClipBox = the clip box - * @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 aWidth = the width of each line. - * @param aColor = the color of the lines + * Draw an array of lines (not a polygon). + * + * @param aClipBox the clip box. + * @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 aWidth the width of each line. + * @param aColor the color of the lines. * @see COLOR4D */ void GRLineArray( EDA_RECT* aClipBox, wxDC* aDC,std::vector& aLines, int aWidth, COLOR4D aColor ); -void GRDrawAnchor( EDA_RECT* aClipBox, wxDC *aDC, int x, int y, int aSize, - COLOR4D aColor ); +void GRDrawAnchor( EDA_RECT* aClipBox, wxDC* aDC, int x, int y, int aSize, COLOR4D aColor ); /** * 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 ); diff --git a/include/gr_text.h b/include/gr_text.h index f7c7979c62..6352a303a4 100644 --- a/include/gr_text.h +++ b/include/gr_text.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * 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 * modify it under the terms of the GNU General Public License @@ -34,11 +34,11 @@ #include #include // 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 - * ( like net names on pads/tracks ) - * When a text height is smaller than MIN_TEXT_SIZE, - * it is not drawn by Pcbnew +/** + * Minimum dimension in pixel for drawing/no drawing a text used in Pcbnew to decide to + * 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. */ #define MIN_TEXT_SIZE 5 @@ -51,85 +51,83 @@ class PLOTTER; /** - * Function Clamp_Text_PenSize - *As a rule, pen width should not be >1/4em, otherwise the character - * 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 "best" pen width is aSize/5 for bold texts, - * so the clamp is consistant with bold option. - * @param aPenSize = the pen size to clamp - * @param aSize the char size (height or width, od its wxSize) - * @param aBold = true if text accept bold pen size - * @return the max pen size allowed + * As a rule, pen width should not be >1/4em, otherwise the character 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 "best" pen + * width is aSize/5 for bold texts so the clamp is consistent with bold option. + * + * @param aPenSize the pen size to clamp. + * @param aSize the char size (height or width, or its wxSize). + * @param aBold true if text accept bold pen size. + * @return the max pen size allowed. */ int Clamp_Text_PenSize( int 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 ); /** - * Function GetPensizeForBold - * @return the "best" value for a pen size to draw/plot a bold text - * @param aTextSize = the char size (height or width) + * @param aTextSize the char size (height or width). + * @return the "best" value for a pen size to draw/plot a bold text. */ int GetPenSizeForBold( int aTextSize ); /** - * Function GetPensizeForNormal - * @return the "best" value for a pen size to draw/plot a non-bold text - * @param aTextSize = the char size (height or width) + * @param aTextSize = the char size (height or width). + * @return the "best" value for a pen size to draw/plot a non-bold text. */ int GetPenSizeForNormal( int aTextSize ); /** - * Function GraphicTextWidth - * @return the X size of the graphic text - * the full X size is GraphicTextWidth + the thickness of graphic lines + * 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 ); /** - * Function GRText * 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 aPos = text position (according to h_justify, v_justify) - * @param aColor (COLOR4D) = text color - * @param aText = text to draw - * @param aOrient = angle in 0.1 degree - * @param aSize = text size (size.x or size.y can be < 0 for mirrored texts) - * @param aH_justify = horizontal justification (Left, center, right) - * @param aV_justify = vertical justification (bottom, center, top) - * @param aWidth = line width (pen width) (default = 0) - * if width < 0 : draw segments in sketch mode, width = abs(width) - * Use a value min(aSize.x, aSize.y) / 5 for a bold text - * @param aItalic = true to simulate an italic font - * @param aBold = true to use a bold font - * @param aCallback( int x0, int y0, int xf, int yf, void* aData ) is a function called - * (if non null) to draw each segment. used to draw 3D texts or for plotting. - * NULL for normal drawings - * @param aCallbackData = is the auxiliary parameter aData for the callback function. - * can be nullptr if no auxiliary parameter is needed + * + * @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 aPos text position (according to h_justify, v_justify). + * @param aColor (COLOR4D) = text color. + * @param aText text to draw. + * @param aOrient angle in 0.1 degree. + * @param aSize text size (size.x or size.y can be < 0 for mirrored texts). + * @param aH_justify horizontal justification (Left, center, right). + * @param aV_justify vertical justification (bottom, center, top). + * @param aWidth line width (pen width) (default = 0). If width < 0 : draw segments in + * sketch mode, width = abs(width). Use a value min(aSize.x, aSize.y) / 5 + * for a bold text. + * @param aItalic true to simulate an italic font. + * @param aBold true to use a bold font. + * @param aCallback ( int x0, int y0, int xf, int yf, void* aData ) is a function called + * (if non null) to draw each segment. used to draw 3D texts or for plotting. + * NULL for normal drawings. + * @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 - * 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, - double aOrient, const wxSize &aSize, enum EDA_TEXT_HJUSTIFY_T aH_justify, +void GRText( wxDC* aDC, const wxPoint& aPos, COLOR4D aColor, const wxString& aText, + 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, 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 - * backgrounds. See GRText for most of the parameters. - * If aBgColor is a dark color text is drawn in aColor2 with aColor1 - * border; otherwise colors are swapped. + * Draw graphic text with a border so that it can be read on different backgrounds. + * + * See GRText for most of the parameters. If \a aBgColor is a dark color text is drawn + * in \a aColor2 with \a aColor1 border. Otherwise colors are swapped. */ -void GRHaloText( wxDC * aDC, const wxPoint &aPos, COLOR4D aBgColor, COLOR4D aColor1, - COLOR4D aColor2, const wxString &aText, double aOrient, const wxSize &aSize, +void GRHaloText( wxDC* aDC, const wxPoint& aPos, COLOR4D aBgColor, COLOR4D aColor1, + COLOR4D aColor2, const wxString& aText, 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, 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__ */ diff --git a/include/grid_tricks.h b/include/grid_tricks.h index 7dffd38941..b5d80f76a5 100644 --- a/include/grid_tricks.h +++ b/include/grid_tricks.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -46,25 +46,14 @@ enum /** - * GRID_TRICKS - * is used to add mouse and command handling (such as cut, copy, and paste) to a WX_GRID instance. + * Add mouse and command handling (such as cut, copy, and paste) to a #WX_GRID instance. */ class GRID_TRICKS : public wxEvtHandler { public: - explicit GRID_TRICKS( WX_GRID* aGrid ); 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. void getSelectedArea(); @@ -87,6 +76,15 @@ protected: virtual void paste_clipboard(); virtual void paste_text( const wxString& cb_text ); 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_ diff --git a/include/hashtables.h b/include/hashtables.h index 6fe2549a0f..a1c9b5eecb 100644 --- a/include/hashtables.h +++ b/include/hashtables.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -31,7 +31,7 @@ // Two competing strategies for providing portable hashtables are given: // 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 struct iequal_to : std::binary_function< const char*, const char*, bool > @@ -105,35 +105,41 @@ class NETINFO_ITEM; #ifdef SWIG /// 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; } typedef std::unordered_map TypeName; +#define DECL_HASH_FOR_SWIG( TypeName, KeyType, ValueType ) \ + namespace std \ + { \ + % template( TypeName ) unordered_map; \ + } \ + typedef std::unordered_map TypeName; #else /// Declare a std::unordered_map but no swig %template -#define DECL_HASH_FOR_SWIG(TypeName, KeyType, ValueType) typedef std::unordered_map TypeName; +#define DECL_HASH_FOR_SWIG( TypeName, KeyType, ValueType ) \ + typedef std::unordered_map TypeName; #endif - /** - * Type KEYWORD_MAP - * 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 - * provided for the actual C string itself. This type assumes use with type KEYWORD - * 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 - * themselves and only the pointers are duplicated within the hashtable. - * If the strings were not constant and fixed, this type would not work. - * Also note that normally a hashtable (i.e. unordered_map) using a const char* key - * would simply compare the 32 bit or 64 bit pointers themselves, rather than - * the C strings which they are known to point to in this context. - * I force the latter behavior by supplying both "hash" and "equality" overloads - * to the hashtable (unordered_map) template. + * A hashtable made of a const char* and an int. + * + * @note The use of this type outside very specific circumstances is foolish since there is + * no storage provided for the actual C string itself. + * + * This type assumes use with type #KEYWORD 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 themselves and only the pointers are duplicated within the + * hashtable. If the strings were not constant and fixed, this type would not work. Also + * note that normally a hashtable (i.e. unordered_map) using a const char* key would simply + * compare the 32 bit or 64 bit pointers themselves, rather than the C strings which they + * are known to point to in this context. I force the latter behavior by supplying both + * "hash" and "equality" overloads to the hashtable (unordered_map) template. + * * @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. /// 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 @@ -147,25 +153,26 @@ typedef std::unordered_map< std::string, EDA_RECT > RECT_MAP; /** - * Type KEYWORD_MAP - * 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 - * provided for the actual C string itself. This type assumes use with type KEYWORD - * 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 - * themselves and only the pointers are duplicated within the hashtable. - * If the strings were not constant and fixed, this type would not work. - * Also note that normally a hashtable (i.e. unordered_map) using a const char* key - * would simply compare the 32 bit or 64 bit pointers themselves, rather than - * the C strings which they are known to point to in this context. - * I force the latter behavior by supplying both "hash" and "equality" overloads - * to the hashtable (unordered_map) template. + * A hashtable made of a const char* and an int. + * + * @note The use of this type outside very specific circumstances is foolish since there is + * no storage provided for the actual C string itself. + * + * This type assumes use with type #KEYWORD 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 themselves and only the pointers are duplicated within the + * hashtable. If the strings were not constant and fixed, this type would not work. Also + * note that normally a hashtable (i.e. unordered_map) using a const char* key would simply + * compare the 32 bit or 64 bit pointers themselves, rather than the C strings which they + * are known to point to in this context. I force the latter behavior by supplying both + * "hash" and "equality" overloads to the hashtable (unordered_map) template. + * * @author Dick Hollenbeck */ 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. typedef boost::unordered_map< std::string, EDA_RECT > RECT_MAP; diff --git a/include/hotkeys_basic.h b/include/hotkeys_basic.h index abb98d5336..8134be31e2 100644 --- a/include/hotkeys_basic.h +++ b/include/hotkeys_basic.h @@ -1,7 +1,7 @@ /* * 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 * modify it under the terms of the GNU General Public License @@ -52,26 +52,25 @@ class EDA_BASE_FRAME; #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 ); /** - * Function KeyNameFromKeyCode - * 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 aIsFound = a pointer to a bool to return true if found, or false + * 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 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 can perform actions using the current mouse cursor position - * Accelerators perform the same action as the associated menu - * A comment is used in tool tips for some tools (zoom ..) - * to show the hot key that performs this action + * In menus we can add a hot key, or an accelerator, or sometimes just a comment. Hot keys + * can perform actions using the current mouse cursor position and accelerators perform the + * same action as the associated menu. + * + * A comment is used in tool tips for some tools (zoom ..) to show the hot key that performs + * this action */ 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 aHotKey - the hotkey keycode - * @param aStyle - IS_HOTKEY to add (shortcuts in menus, same as hotkeys) - * IS_COMMENT to add <(keyname)> mainly in tool tips + * @param aText the base text on which to append the hotkey. + * @param aHotKey the hotkey keycode. + * @param aStyle #IS_HOTKEY to add (shortcuts in menus, same as hotkeys). + * #IS_COMMENT to add <(keyname)> mainly in tool tips. */ wxString AddHotkeyName( const wxString& aText, int aHotKey, HOTKEY_ACTION_TYPE aStyle = IS_HOTKEY); /** - * Function DisplayHotkeyList - * Displays the current hotkey list - * @param aFrame = current active frame - * @param aToolMgr = the tool manager holding the registered actions from which the hotkeys - * will be harvested + * Display the current hotkey list. + * + * @param aFrame current active frame. + * @param aToolMgr the tool manager holding the registered actions from which the hotkeys + * will be harvested. */ void DisplayHotkeyList( EDA_BASE_FRAME* aFrame, TOOL_MANAGER* aToolMgr ); /** - * Function ReadotKeyConfig - * Reads a hotkey config file into a map. If aFileName is empty it will read in the defualt - * hotkeys file. - * @param aHotKeys + * Reads a hotkey config file into a map. + * + * If \a aFileName is empty it will read in the default hotkeys file. */ -void ReadHotKeyConfig( wxString aFileName, std::map& aHotKeys ); +void ReadHotKeyConfig( const wxString& aFileName, std::map& aHotKeys ); /** - * Function WriteHotKeyConfig - * Updates the hotkeys config file with the hotkeys from the given actions map. + * Update the hotkeys config file with the hotkeys from the given actions map. */ int WriteHotKeyConfig( const std::map& aActionMap ); /** - * Function ReadLegacyHotkeyConfigFile - * 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 aMap The list of keycodes mapped by legacy property names - * @return 1 on success, 0 on failure + * Read hotkey configuration for a given app. + * + * @param aFilename the filename to save the hotkeys as. + * @param aMap The list of keycodes mapped by legacy property names. + * @return 1 on success, 0 on failure. */ int ReadLegacyHotkeyConfigFile( const wxString& aFilename, std::map& aMap ); /** - * Function ReadLegacyHotkeyConfig - * Read configuration data and fill the current hotkey list with hotkeys - * @param aAppname = the value of the app's m_FrameName - * @param aMap The list of keycodes mapped by legacy property names + * Read configuration data and fill the current hotkey list with hotkeys. + * + * @param aAppname the value of the app's m_FrameName. + * @param aMap The list of keycodes mapped by legacy property names. */ int ReadLegacyHotkeyConfig( const wxString& aAppname, std::map& aMap ); diff --git a/include/ki_exception.h b/include/ki_exception.h index 9c9c52ffed..35dfef6131 100644 --- a/include/ki_exception.h +++ b/include/ki_exception.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2007-2016 SoftPLC Corporation, Dick Hollenbeck - * 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 * 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__ ) /** - * KI_PARAM_ERROR - * is a class used to hold a translatable error message and may be used when throwing exceptions - * containing a translated error message. + * Hold a translatable error message and may be used when throwing exceptions containing a + * translated error message. */ class KI_PARAM_ERROR // similar to std::invalid_argument for instance { @@ -68,29 +67,25 @@ private: /** - * Struct IO_ERROR - * is a class used to hold an error message and may be used when throwing exceptions - * containing meaningful error messages. + * Hold an error message and may be used when throwing exceptions containing meaningful + * error messages. + * * @author Dick Hollenbeck */ class IO_ERROR // : std::exception { public: /** - * Constructor + * Use macro #THROW_IO_ERROR() to wrap a call to this constructor at the call site. * * @param aProblem is Problem() text. - * - * @param aThrowersFile is the __FILE__ preprocessor macro but generated - * at the source file of thrower. - * + * @param aThrowersFile is the __FILE__ preprocessor macro but generated at the source + * file of thrower. * @param aThrowersFunction is the function name at the throw site. * @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, - const char* aThrowersFunction, int aThrowersLineNumber ) + const char* aThrowersFunction, int aThrowersLineNumber ) { init( aProblem, aThrowersFile, aThrowersFunction, aThrowersLineNumber ); } @@ -98,7 +93,7 @@ public: IO_ERROR() {} 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 Where() const; ///< where did the Problem() occur? @@ -114,10 +109,10 @@ protected: /** - * Struct PARSE_ERROR - * contains a filename or source description, a problem input line, a line number, - * a byte offset, and an error message which contains the the caller's report and his - * call site information: CPP source file, function, and line number. + * A filename or source description, a problem input line, a line number, a byte + * offset, and an error message which contains the the caller's report and his call + * site information: CPP source file, function, and line number. + * * @author Dick Hollenbeck */ struct PARSE_ERROR : public IO_ERROR @@ -132,19 +127,17 @@ struct PARSE_ERROR : public IO_ERROR std::string inputLine; /** - * Constructor - * which is normally called via the macro THROW_PARSE_ERROR so that - * __FILE__ and __FUNCTION__ and __LINE__ can be captured from the call site. + * Normally called via the macro #THROW_PARSE_ERROR so that __FILE__, __FUNCTION__, + * and __LINE__ can be captured from the call site. */ PARSE_ERROR( const wxString& aProblem, const char* aThrowersFile, const char* aThrowersFunction, int aThrowersLineNumber, - const wxString& aSource, - const char* aInputLine, + const wxString& aSource, const char* aInputLine, int aLineNumber, int aByteIndex ) : IO_ERROR() { init( aProblem, aThrowersFile, aThrowersFunction, aThrowersLineNumber, - aSource, aInputLine, aLineNumber, aByteIndex ); + aSource, aInputLine, aLineNumber, aByteIndex ); } void init( const wxString& aProblem, const char* aThrowersFile, @@ -168,14 +161,14 @@ protected: }; -#define THROW_PARSE_ERROR( aProblem, aSource, aInputLine, aLineNumber, aByteIndex ) \ - throw PARSE_ERROR( aProblem, __FILE__, __FUNCTION__, __LINE__, aSource, aInputLine, aLineNumber, aByteIndex ) +#define THROW_PARSE_ERROR( aProblem, 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 - * by a file generated by a newer version of KiCad than this. Can be used to generate + * 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 * more informative error messages. */ struct FUTURE_FORMAT_ERROR : public PARSE_ERROR diff --git a/include/kicad_string.h b/include/kicad_string.h index c9afd6a036..ab9962300b 100644 --- a/include/kicad_string.h +++ b/include/kicad_string.h @@ -1,7 +1,7 @@ /* * 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 * 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. - * @param aString + * * @return true if any characters required conversion. */ bool ConvertSmartQuotesAndDashes( wxString* aString ); /** - * Escape/Unescape routines to safely encode reserved-characters in various - * contexts. + * Escape/Unescape routines to safely encode reserved-characters in various contexts. */ enum ESCAPE_CONTEXT { @@ -76,8 +75,8 @@ wxString PrettyPrintForMenu( const wxString& aString ); * @param aDest is the destination byte buffer. * @param aSource is the source bytes as a C string. * @param aDestSize is the size of the destination byte buffer. - * @return int - the number of bytes read from source, which may be more than - * the number copied, due to escaping of double quotes and the escape byte itself. + * @return the number of bytes read from source, which may be more than the number copied, + * due to escaping of double quotes and the escape byte itself. * @deprecated should use the one which fetches a wxString, below. */ 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. * - * @param aDest is the destination wxString + * @param aDest is the destination wxString. * @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 - * the number copied, due to escaping of double quotes and the escape byte itself. + * @return the number of bytes read from source, which may be more than the number copied, + * due to escaping of double quotes and the escape byte itself. */ int ReadDelimitedText( wxString* aDest, const char* aSource ); /** - * Function EscapedUTF8 - * returns an 8 bit UTF8 string given aString in unicode form. + * Return an 8 bit UTF8 string given aString in Unicode 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(). * * @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 ); @@ -113,7 +112,7 @@ wxString EscapeHTML( const wxString& aString ); * * @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. @@ -180,8 +179,8 @@ int SplitString( wxString strToSplit, /** * Gets the trailing int, if any, from a string. * - * @param aStr the string to check - * @return the trailing int or 0 if none found + * @param aStr the string to check. + * @return the trailing int or 0 if none found. */ 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 - * where they tend to be largely repetitious at the front. + * A helper for sorting strings from the rear. + * + * Useful for things like 3D model names where they tend to be largely repetitious at the front. */ struct rsort_wxString { @@ -264,10 +264,10 @@ struct rsort_wxString /** * 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 + * + * @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 */ static inline std::vector 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. * - * @param aText is the text to split - * @param aStrings will contain the splitted lines - * @param aSplitter is the 'split' character + * @param aText is the text to split. + * @param aStrings will contain the split lines. + * @param aSplitter is the 'split' character. */ void wxStringSplit( const wxString& aText, wxArrayString& aStrings, wxChar aSplitter ); /** - * Function StripTrailingZeros - * Remove trailing 0 from a string containing a converted float number. - * The trailing 0 are removed if the mantissa has more - * than aTrailingZeroAllowed digits and some trailing 0 + * Remove trailing zeros from a string containing a converted float number. + * + * The trailing zeros are removed if the mantissa has more than \a aTrailingZeroAllowed + * digits and some trailing zeros. */ void StripTrailingZeros( wxString& aStringValue, unsigned aTrailingZeroAllowed = 1 ); diff --git a/include/kiface_i.h b/include/kiface_i.h index 888fe042a2..9f8f5587c3 100644 --- a/include/kiface_i.h +++ b/include/kiface_i.h @@ -1,7 +1,7 @@ /* * 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 * modify it under the terms of the GNU General Public License @@ -29,51 +29,37 @@ /** - * KIFACE_I - * is a KIFACE (I)mplementation, - * with some features useful for DSOs which implement a KIFACE. - * It is abstract, a few functions must be implemented in derivations. + * A #KIFACE (I)mplementation. + * + * This has useful for DSOs which implement a #KIFACE. It is abstract so a few functions + * must be implemented in derivations. */ class KIFACE_I : public KIFACE { public: + /** + * Typically #start_common() is called from here. + */ + virtual bool OnKifaceStart( PGM_BASE* aProgram, int aCtlBits ) override = 0; - //--------------------------------------------------------------- - - // 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 + virtual void OnKifaceEnd() override { // overload this if you want, end_common() may be handy. end_common(); } - VTBL_ENTRY wxWindow* CreateWindow( wxWindow* aParent, - int aClassId, KIWAY* aKIWAY, int aCtlBits = 0 ) override = 0; + virtual wxWindow* CreateWindow( wxWindow* aParent, int aClassId, KIWAY* aKIWAY, + int aCtlBits = 0 ) override = 0; - VTBL_ENTRY void* IfaceOrAddress( int aDataId ) override = 0; - - //-------------------------------------------------------------- - - // The remainder are DSO specific helpers, not part of the KIFACE API + virtual void* IfaceOrAddress( int aDataId ) override = 0; /** - * 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 the name of the wxConfigBase established in m_bm, - * so it should be lowercase. - * @param aId is the type of DSO ( FACE_SCH, FACE_PCB, FACE_CVPCB, - * FACE_GERBVIEW, FACE_PL_EDITOR, FACE_PCB_CALCULATOR, FACE_BMP2CMP) + * @param aKifaceName should point to a C string in permanent storage which contains the + * name of the DSO. Examples: "eeschema", "pcbnew", etc. This controls + * the name of the wxConfigBase established in m_bm, so it should be + * lowercase. + * @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 ) : m_id( aId ), @@ -98,27 +84,27 @@ protected: 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; } void InitSettings( APP_SETTINGS_BASE* aSettings ) { m_bm.InitSettings( aSettings ); } /** - * Function StartFlags - * returns whatever was passed as @a aCtlBits to OnKifaceStart() + * Return whatever was passed as @a aCtlBits to OnKifaceStart(). */ 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; } /** - * Function GetHelpFileName - * returns just the basename portion of the current help file. + * Return just the basename portion of the current help file. */ const wxString& GetHelpFileName() const { return m_bm.m_help_file; } diff --git a/include/kiway.h b/include/kiway.h index c26436cbf2..15dc235511 100644 --- a/include/kiway.h +++ b/include/kiway.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -25,75 +25,74 @@ #ifndef KIWAY_H_ #define KIWAY_H_ -/* - -The KIWAY and KIFACE classes are used to communicate between various process -modules, all residing within a single process. The program modules are either -top level like an *.exe or subsidiary like a *.dll. In much of the documentation -the term DSO is used to refer to the *.dll portions, that is the term used on -linux. But it should be taken to mean DLL on Windows. - -

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

    - -
  1. By using DSOs within a single process, it is not necessary to use IPC. -The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in -a platform independent way. There can also be function calls from one DSO to -another.
    2. - -
  2. The use of a number of separately linked DSOs closely resembles the original -KiCad program design, consisting of Eeschema and Pcbnew. But it also allows -separate compilation and linking of those two DSOs without a ton of inter-DSO -dependencies and common data structures. Linking smaller, purpose specific DSOs -is thought to be better for maintenance simplicity than a large single link -image.
    3. - -
  3. By keeping the core functionality in DSOs rather than EXE tops, it becomes -possible to re-use the DSOs under different program tops. For example, a DSO -named _pcbnew.so can be used under a C++ top or under a python top. Only one -CMake target must be defined to build either. Whether that is a separate build -or not is not the important thing. Simply having a single CMake target has -advantages. (Each builder person will have his/her own intentions relative to -use of python or not.) Once a DSO is python capable, it can be driven by any -number of python program tops, including demo-ing (automation) and testing -separately.
    4. - - -
- -All KiCad source code is UTF8 encoded by law, so make sure your editor is set -as such! As such, it is OK to use UTF8 characters: - -┏ ┗ ┓ ┛ ━ ┃ - -
-
-                             ┏━━━process top━━━━━┓
-                             ┃                   ┃       wxEvent channels
-         ┏━━━━━━━━━━━━━━━━━━━-━[KIWAY project 1]━-━━━━━━━━━━━━━━━━━━━━━━┓
-         ┃                   ┃                   ┃                      ┃
-         ┃     ┏━━━━━━━━━━━━━-━[KIWAY project 2]━-━━━━━━━━━━┓           ┃
-         ┃     ┃             ┃                   ┃          ┃           ┃
-         ┃     ┃           ┏━-━[KIWAY project 3]━-━┓        ┃           ┃
-         ┃     ┃           ┃ ┗━━━━━━━━━━━━━━━━━━━┛ ┃        ┃           ┃
-         ┃     ┃           ┃                       ┃        ┃           ┃
-         ┃     ┃           ┃                       ┃        ┃           ┃
-┏━━━━━━━━|━━━━━|━━━━━━━━━━━|━━━━━━━━━┓    ┏━━━━━━━━|━━━━━━━━|━━━━━━━━━━━|━━━━━┓
-┃ KIFACE ┃     ┃           ┃         ┃    ┃ KIFACE ┃        ┃           ┃     ┃
-┃        ┃     ┃           ┃         ┃    ┃        ┃        ┃           ┃     ┃
-┃        ┃     ┃           ┃         ┃    ┃        ┃        ┃           ┃     ┃
-┃┏━━━━━━━+━┓ ┏━+━━━━━━━┓ ┏━+━━━━━━━┓ ┃    ┃┏━━━━━━━+━┓ ┏━━━━+━━━━┓ ┏━━━━+━━━━┓┃
-┃┃wxFrame  ┃ ┃wxFrame  ┃ ┃wxFrame  ┃ ┃    ┃┃wxFrame  ┃ ┃wxFrame  ┃ ┃wxFrame  ┃┃
-┃┃project 1┃ ┃project 2┃ ┃project 3┃ ┃    ┃┃project 3┃ ┃project 2┃ ┃project 1┃┃
-┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┃    ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛┃
-┃                                    ┃    ┃                                   ┃
-┃                                    ┃    ┃                                   ┃
-┗━━━━━━ eeschema DSO ━━━━━━━━━━━━━━━━┛    ┗━━━━━━ pcbnew DSO ━━━━━━━━━━━━━━━━━┛
-
-
- -*/ +/** + * The KIWAY and KIFACE classes are used to communicate between various process + * modules, all residing within a single process. The program modules are either + * top level like an *.exe or subsidiary like a *.dll. In much of the documentation + * the term DSO is used to refer to the *.dll portions, that is the term used on + * linux. But it should be taken to mean DLL on Windows. + * + *

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

    + * + *
  1. By using DSOs within a single process, it is not necessary to use IPC. + * The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in + * a platform independent way. There can also be function calls from one DSO to + * another.
    2. + * + *
  2. The use of a number of separately linked DSOs closely resembles the original + * KiCad program design, consisting of Eeschema and Pcbnew. But it also allows + * separate compilation and linking of those two DSOs without a ton of inter-DSO + * dependencies and common data structures. Linking smaller, purpose specific DSOs + * is thought to be better for maintenance simplicity than a large single link + * image.
    3. + * + *
  3. By keeping the core functionality in DSOs rather than EXE tops, it becomes + * possible to re-use the DSOs under different program tops. For example, a DSO + * named _pcbnew.so can be used under a C++ top or under a python top. Only one + * CMake target must be defined to build either. Whether that is a separate build + * or not is not the important thing. Simply having a single CMake target has + * advantages. (Each builder person will have his/her own intentions relative to + * use of python or not.) Once a DSO is python capable, it can be driven by any + * number of python program tops, including demo-ing (automation) and testing + * separately.
    4. + * + * + *
+ * + * All KiCad source code is UTF8 encoded by law, so make sure your editor is set + * as such! As such, it is OK to use UTF8 characters: + * + * ┏ ┗ ┓ ┛ ━ ┃ + * + * 
+ *
+ *                              ┏━━━process top━━━━━┓
+ *                              ┃                   ┃       wxEvent channels
+ *          ┏━━━━━━━━━━━━━━━━━━━-━[KIWAY project 1]━-━━━━━━━━━━━━━━━━━━━━━━┓
+ *          ┃                   ┃                   ┃                      ┃
+ *          ┃     ┏━━━━━━━━━━━━━-━[KIWAY project 2]━-━━━━━━━━━━┓           ┃
+ *          ┃     ┃             ┃                   ┃          ┃           ┃
+ *          ┃     ┃           ┏━-━[KIWAY project 3]━-━┓        ┃           ┃
+ *          ┃     ┃           ┃ ┗━━━━━━━━━━━━━━━━━━━┛ ┃        ┃           ┃
+ *          ┃     ┃           ┃                       ┃        ┃           ┃
+ *          ┃     ┃           ┃                       ┃        ┃           ┃
+ * ┏━━━━━━━━|━━━━━|━━━━━━━━━━━|━━━━━━━━━┓    ┏━━━━━━━━|━━━━━━━━|━━━━━━━━━━━|━━━━━┓
+ * ┃ KIFACE ┃     ┃           ┃         ┃    ┃ KIFACE ┃        ┃           ┃     ┃
+ * ┃        ┃     ┃           ┃         ┃    ┃        ┃        ┃           ┃     ┃
+ * ┃        ┃     ┃           ┃         ┃    ┃        ┃        ┃           ┃     ┃
+ * ┃┏━━━━━━━+━┓ ┏━+━━━━━━━┓ ┏━+━━━━━━━┓ ┃    ┃┏━━━━━━━+━┓ ┏━━━━+━━━━┓ ┏━━━━+━━━━┓┃
+ * ┃┃wxFrame  ┃ ┃wxFrame  ┃ ┃wxFrame  ┃ ┃    ┃┃wxFrame  ┃ ┃wxFrame  ┃ ┃wxFrame  ┃┃
+ * ┃┃project 1┃ ┃project 2┃ ┃project 3┃ ┃    ┃┃project 3┃ ┃project 2┃ ┃project 1┃┃
+ * ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┃    ┃┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛┃
+ * ┃                                    ┃    ┃                                   ┃
+ * ┃                                    ┃    ┃                                   ┃
+ * ┗━━━━━━ eeschema DSO ━━━━━━━━━━━━━━━━┛    ┗━━━━━━ pcbnew DSO ━━━━━━━━━━━━━━━━━┛
+ *
+ *
+ * + */ #include @@ -106,12 +105,10 @@ as such! As such, it is OK to use UTF8 characters: #include -#define VTBL_ENTRY virtual - #define KIFACE_VERSION 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. #define KIFACE_INSTANCE_NAME_AND_VERSION "KIFACE_1" @@ -136,16 +133,16 @@ class wxTopLevelWindow; /** - * KIFACE - * 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 - * KiCad process. It makes it possible to call between DSOs without having to link - * them together. Most all calls are via virtual functions which means C++ vtables - * are used to hold function pointers and eliminate the need to link to specific - * object code libraries. There is one KIWAY in the launching portion of the process - * for each open KiCad project. Each project has its own KIWAY. Within a KIWAY - * is an actual PROJECT data structure. A KIWAY also facilitates communicating - * between DSOs on the topic of the project in question. + * Implement a participant in the KIWAY alchemy. + * + * KIWAY is a minimalistic software bus for communications between various DLLs/DSOs + * (DSOs) within the same KiCad process. It makes it possible to call between DSOs + * without having to link them together. Most all calls are via virtual functions + * which means C++ vtables are used to hold function pointers and eliminate the need + * to link to specific object code libraries. There is one KIWAY in the launching + * portion of the process for each open KiCad project. Each project has its own KIWAY. + * Within a KIWAY is an actual PROJECT data structure. A KIWAY also facilitates + * communicating between DSOs on the topic of the project in question. */ struct KIFACE { @@ -155,120 +152,110 @@ struct KIFACE virtual ~KIFACE() throw() {} -#define KFCTL_STANDALONE (1<<0) ///< Am running as a standalone Top. -#define KFCTL_CPP_PROJECT_SUITE (1<<1) ///< Am 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_STANDALONE (1<<0) ///< Running as a standalone Top. +#define KFCTL_CPP_PROJECT_SUITE (1<<1) ///< Running under C++ project mgr, possibly with others. +#define KFCTL_PY_PROJECT_SUITE (1<<2) ///< Running under python project mgr, possibly with others. /** - * Function OnKifaceStart - * is called just once shortly after the DSO is loaded. It is the second - * function called, immediately after the KIFACE_GETTER(). However before - * either of those, static C++ constructors are called. The DSO implementation - * should do process level initialization here, not project specific since there - * will be multiple projects open eventually. - * - * @param aProgram is the process block: PGM_BASE* + * Called just once shortly after the DSO is loaded. + * It is the second function called, immediately after the KIFACE_GETTER(). However + * before either of those, static C++ constructors are called. The DSO implementation + * should do process level initialization here, not project specific since there will + * be multiple projects open eventually. * + * @param aProgram is the process block: #PGM_BASE*. * @param aCtlBits consists of bit flags from the set of KFCTL_* \#defines above. - * - * @return bool - true if DSO initialized OK, false if not. When returning - * false, the loader may optionally decide to terminate the process or not, - * but will not put out any UI because that is the duty of this function to say - * why it is returning false. Never return false without having reported - * to the UI why. + * @return true if DSO initialized OK, false if not. When returning false, the loader + * may optionally decide to terminate the process or not, but will not put out + * any UI because that is the duty of this function to say 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 - * 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. + * 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. */ - VTBL_ENTRY void OnKifaceEnd() = 0; + virtual void OnKifaceEnd() = 0; /** - * Function CreateWindow - * creates a wxWindow for the current project. The caller - * must cast the return value into the known type. + * Create a wxWindow for the current project. * - * @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. + * 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 + * 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 - * 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 aCtlBits consists of bit flags from the set of KFCTL_* \#defines above. - * - * @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 - * not contained in the caller's link image. + * @return the window created 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 + * not contained in the caller's link image. */ - VTBL_ENTRY wxWindow* CreateWindow( wxWindow* aParent, int aClassId, - KIWAY* aKIWAY, int aCtlBits = 0 ) = 0; + virtual wxWindow* CreateWindow( wxWindow* aParent, int aClassId, + KIWAY* aKIWAY, int aCtlBits = 0 ) = 0; /** - * Function SaveFileAs * 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 * paths in them that need updating). */ - VTBL_ENTRY void SaveFileAs( const wxString& srcProjectBasePath, - const wxString& srcProjectName, - const wxString& newProjectBasePath, - const wxString& newProjectName, - const wxString& srcFilePath, - wxString& aErrors ) + virtual void SaveFileAs( const wxString& srcProjectBasePath, + const wxString& srcProjectName, + const wxString& newProjectBasePath, + const wxString& newProjectName, + const wxString& srcFilePath, + wxString& aErrors ) { // If a KIFACE owns files then it needs to implement this.... } /** - * Function IfaceOrAddress - * 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. + * Return pointer to the requested object. * - * @param aDataId identifies which object you want the address of, and consists - * of choices known in advance by the implementing KIFACE. + * 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. * - * @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 - * is a minimalistic software bus for communications between various - * DLLs/DSOs (DSOs) within the same KiCad process. It makes it possible - * to call between DSOs without having to link them together, and without - * having to link to the top process module which houses the KIWAY(s). More importantly - * it makes it possible to send custom wxEvents between DSOs and from the top - * process module down into the DSOs. The latter capability is thought useful - * for driving the lower DSOs from a python test rig or for demo (automation) purposes. + * A minimalistic software bus for communications between various DLLs/DSOs (DSOs) within + * the same KiCad process. + * + * It makes it possible to call between DSOs without having to link them together, and + * without having to link to the top process module which houses the KIWAY(s). More + * importantly it makes it possible to send custom wxEvents between DSOs and from the top + * process module down into the DSOs. The latter capability is thought useful for driving + * the lower DSOs from a python test rig or for demo (automation) purposes. *

- * Most all calls are via virtual functions, which means C++ vtables - * are used to hold function pointers and eliminate the need to link to specific - * object code libraries, speeding development and encouraging clearly defined - * interface design. Unlike Microsoft COM, which is a multi-vendor design supporting - * DLL's built at various points in time, the KIWAY alchemy is single project, with - * all components being built at the same time. So one should expect solid compatibility - * between all KiCad components, as long at they are compiled at the same time. + * Most all calls are via virtual functions, which means C++ vtables are used to hold + * function pointers and eliminate the need to link to specific object code libraries, + * speeding development and encouraging clearly defined interface design. Unlike Microsoft + * COM, which is a multi-vendor design supporting DLL's built at various points in time, + * the KIWAY alchemy is single project, with all components being built at the same time. + * So one should expect solid compatibility between all KiCad components, as long at they + * are compiled at the same time. *

- * There is one KIWAY in the launching portion of the process - * for each open KiCad project. Each project has its own KIWAY. Available to - * each KIWAY is an actual PROJECT data structure. If you have a KIWAY, you - * can get to the PROJECT using KIWAY::Prj(). + * There is one KIWAY in the launching portion of the process for each open KiCad project. + * Each project has its own KIWAY. Available to each KIWAY is an actual PROJECT data + * structure. If you have a KIWAY, you can get to the PROJECT using #KIWAY::Prj(). *

- * In summary, a KIWAY facilitates communicating between DSOs, where the topic - * of the communication is project specific. Here a "project" means a BOARD - * and a SCHEMATIC and a NETLIST, (anything relating to production of a single BOARD - * and added to class PROJECT.) + * In summary, a KIWAY facilitates communicating between DSOs, where the topic of the + * communication is project specific. Here a "project" means a #BOARD and a #SCHEMATIC + * and a #NETLIST, (anything relating to production of a single #BOARD and added to class + * #PROJECT.) */ class KIWAY : public wxEvtHandler { @@ -292,109 +279,106 @@ public: ~KIWAY() throw () {} /** - * Function KifaceType - * is a simple mapping function which returns the FACE_T which is known to - * implement @a aFrameType. + * A simple mapping function which returns the FACE_T which is known to 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 ); // If you change the vtable, recompile all of KiCad. /** - * Function KiFACE - * returns the KIFACE* given a FACE_T. If it is not already loaded, the - * KIFACE is loaded and initialized with a call to KIFACE::OnKifaceStart() + * Return the KIFACE* given a FACE_T. + * + * 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 - * returns the KIWAY_PLAYER* given a FRAME_T. If it is not already created, - * the required KIFACE is found and loaded and initialized if necessary, then - * the KIWAY_PLAYER window is created but not shown. Caller must Show() it. - * If it is already created, then the existing KIWAY_PLAYER* pointer is returned. + * Return the #KIWAY_PLAYER* given a FRAME_T. + * + * If it is not already created, the required KIFACE is found and loaded and initialized + * if necessary, then the KIWAY_PLAYER window is created but not shown. Caller must + * Show() it. If it is already created, then the existing KIWAY_PLAYER* pointer is + * returned. * * @param aFrameType is from enum #FRAME_T. - * @param doCreate when true asks that the player be created if it is not - * already created, false means do not create and maybe return NULL. - * @param aParent is a parent for modal KIWAY_PLAYER frames, otherwise NULL - * used only when doCreate = true and by KIWAY_PLAYER frames created in modal form - * because the are using the wxFLOAT_ON_PARENT style + * @param doCreate when true asks that the player be created if it is not already created, + * false means do not create and maybe return NULL. + * @param aParent is a parent for modal #KIWAY_PLAYER frames, otherwise NULL used only + * when doCreate = true and by KIWAY_PLAYER frames created in modal form * - * @return KIWAY_PLAYER* - a valid opened KIWAY_PLAYER or NULL if there - * is something wrong or doCreate was false and the player has yet to be created. + * @return a valid opened #KIWAY_PLAYER or NULL if there is something wrong or doCreate + * 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. */ - VTBL_ENTRY KIWAY_PLAYER* Player( FRAME_T aFrameType, bool doCreate = true, - wxTopLevelWindow* aParent = NULL ); + virtual KIWAY_PLAYER* Player( FRAME_T aFrameType, bool doCreate = true, + wxTopLevelWindow* aParent = nullptr ); /** - * Function PlayerClose - * calls the KIWAY_PLAYER::Close( bool force ) function on the window and - * if not vetoed, returns true, else false. If window actually closes, then - * this KIWAY marks it as not opened internally. + * Call the KIWAY_PLAYER::Close( bool force ) function on the window and if not vetoed, + * returns true, else false. * - * @return bool - true the window is closed and not vetoed, else false. - */ - 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. + * If window actually closes, then this KIWAY marks it as not opened internally. * - * @return bool - true indicates that all windows closed because none were vetoed, - * false means at least one cast a veto. Any that cast a veto are still open. + * @return true if the window is closed and not vetoed, else false. */ - VTBL_ENTRY bool PlayersClose( bool doForce ); + virtual bool PlayerClose( FRAME_T aFrameType, bool doForce ); /** - * Function ExpressMail - * send aPayload to aDestination from aSource. Recipient receives this in its - * KIWAY_PLAYER::KiwayMailIn() function and can efficiently switch() based on - * aCommand in there. + * Call 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 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, - std::string& aPayload, wxWindow* aSource = NULL ); + virtual bool PlayersClose( bool doForce ); /** - * Function Prj - * returns the PROJECT associated with this KIWAY. This is here as an - * accessor, so that there is freedom to put the actual PROJECT storage + * Send @a aPayload to @a aDestination from @a aSource. + * + * 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. */ - VTBL_ENTRY PROJECT& Prj() const; + virtual PROJECT& Prj() const; /** - * Function SetLanguage - * changes the language and then calls ShowChangedLanguage() on all KIWAY_PLAYERs. + * Change the language and then calls ShowChangedLanguage() on all #KIWAY_PLAYERs. */ - VTBL_ENTRY void SetLanguage( int aLanguage ); + virtual void SetLanguage( int aLanguage ); /** - * Function CommonSettingsChanged - * Calls CommonSettingsChanged() on all KIWAY_PLAYERs. - * Used after changing suite-wide options such as panning, autosave interval, etc. + * Call CommonSettingsChanged() on all KIWAY_PLAYERs. + * + * 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. * 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 - * tells this KIWAY about the top most frame in the program and optionally - * allows it to play the role of one of the KIWAY_PLAYERs if launched from - * single_top.cpp. + * Tell this KIWAY about the top most frame in the program and optionally allows it to + * play the role of one of the KIWAY_PLAYERs if launched from single_top.cpp. * * @param aTop is the top most wxFrame in the entire program. */ @@ -407,7 +391,6 @@ public: bool ProcessEvent( wxEvent& aEvent ) override; private: - /// Get the [path &] name of the DSO holding the requested FACE_T. const wxString dso_search_path( FACE_T aFaceId ); @@ -423,12 +406,13 @@ private: m_kiface[aFaceType] = aKiface; return true; } + return false; } /** - * @return the reference of the KIWAY_PLAYER having the type aFrameType - * if exists, or NULL if this KIWAY_PLAYER was not yet created, or was closed + * @return the reference of the KIWAY_PLAYER having the type @a aFrameType if exists, + * or NULL if this KIWAY_PLAYER was not yet created, or was closed */ KIWAY_PLAYER* GetPlayerFrame( FRAME_T aFrameType ); @@ -458,19 +442,18 @@ extern KIWAY Kiway; /** - * Function Pointer KIFACE_GETTER_FUNC - * 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 - * mangling. This function will only be called one time. The DSO itself however - * may be asked to support multiple Top windows, i.e. multiple projects - * within its lifetime. + * Point to the one and only KIFACE export. + * + * The export's address is looked up via symbolic string and should be extern "C" to avoid name + * mangling. This function will only be called one time. The DSO itself however may be asked + * to support multiple Top windows, i.e. multiple projects within its lifetime. * * @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 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 diff --git a/include/kiway_express.h b/include/kiway_express.h index 77b692d11f..cc18bc8aec 100644 --- a/include/kiway_express.h +++ b/include/kiway_express.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -33,21 +33,18 @@ /** - * KIWAY_EXPRESS - * carries a payload from one KIWAY_PLAYER to another within a PROJECT. + * Carry a payload from one #KIWAY_PLAYER to another within a #PROJECT. */ class KIWAY_EXPRESS : public wxEvent { public: /** - * Function Dest - * returns the destination player id of the message. + * Return 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() { @@ -55,19 +52,17 @@ public: } /** - * Function Payload - * returns the payload, which can be any text but it typicall self - * identifying s-expression. + * Return the payload, which can be any text but it typically self identifying s-expression. */ - std::string& GetPayload() { return m_payload; } - void SetPayload( const std::string& aPayload ) { m_payload = aPayload; } + std::string& GetPayload() { return m_payload; } + 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( FRAME_T aDestination, MAIL_T aCommand, std::string& aPayload, - wxWindow* aSource = NULL ); + wxWindow* aSource = nullptr ); KIWAY_EXPRESS( const KIWAY_EXPRESS& anOther ); @@ -79,8 +74,8 @@ public: //DECLARE_DYNAMIC_CLASS( KIWAY_EXPRESS ) private: - FRAME_T m_destination; ///< could have been a bitmap indicating multiple recipients - std::string& m_payload; ///< very often s-expression text, but not always + FRAME_T m_destination; ///< could have been a bitmap indicating multiple recipients. + std::string& m_payload; ///< very often s-expression text, but not always. // possible new ideas here. }; diff --git a/include/kiway_holder.h b/include/kiway_holder.h index 202ff25aa4..3d1eaad566 100644 --- a/include/kiway_holder.h +++ b/include/kiway_holder.h @@ -1,7 +1,7 @@ /* * 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 * modify it under the terms of the GNU General Public License @@ -32,9 +32,9 @@ class PROJECT; /** - * KIWAY_HOLDER - * is a mix in class which holds the location of a wxWindow's KIWAY. It allows calls to - * Kiway() and SetKiway(). + * A mix in class which holds the location of a wxWindow's KIWAY. + * + * It allows calls to Kiway() and SetKiway(). */ class KIWAY_HOLDER { @@ -47,11 +47,11 @@ public: {} HOLDER_TYPE GetType() const { return m_type; } - + /** - * Function Kiway - * returns a reference to the KIWAY that this object has an opportunity - * to participate in. A KIWAY_HOLDER is not necessarily a KIWAY_PLAYER. + * Return a reference to the #KIWAY that this object has an opportunity to participate in. + * + * A KIWAY_HOLDER is not necessarily a KIWAY_PLAYER. */ KIWAY& Kiway() const { @@ -60,19 +60,16 @@ public: } /** - * Function Prj - * returns a reference to the PROJECT "associated with" this KIWAY. + * Return a reference to the #PROJECT associated with this #KIWAY. */ 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. - * It is only used for debugging, since "this" is not a wxWindow*. "this" is - * a KIWAY_HOLDER mix-in. - * - * @param aKiway is often from a parent window, or from KIFACE::CreateWindow(). + * @param aDest is the recipient of \a aKiway pointer. + * @param aKiway is often from a parent window or from #KIFACE::CreateWindow(). */ void SetKiway( wxWindow* aDest, KIWAY* aKiway ); @@ -83,5 +80,4 @@ private: }; - #endif // KIWAY_HOLDER_H_ diff --git a/include/kiway_mgr.h b/include/kiway_mgr.h index 4baaec09d6..0ceb64ac5b 100644 --- a/include/kiway_mgr.h +++ b/include/kiway_mgr.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -30,10 +30,10 @@ /** - * KIWAY_MGR - * 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 - * header later). + * 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 header later). */ class KIWAY_MGR { diff --git a/include/kiway_player.h b/include/kiway_player.h index 1ac7eabaeb..640aeeaf58 100644 --- a/include/kiway_player.h +++ b/include/kiway_player.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck - * 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 * modify it under the terms of the GNU General Public License @@ -45,15 +45,15 @@ class WX_EVENT_LOOP; /** - * KIWAY_PLAYER - * is a wxFrame capable of the OpenProjectFiles function, meaning it can load - * 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 - * participate in a KIWAY. Those that do must actually interact with the provided - * KIWAY*. - *

- * EDA_BASE_FRAME would not have sufficed because BM2CMP_FRAME_BASE is not - * derived from it. + * A wxFrame capable of the OpenProjectFiles function, meaning it can load 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 class intend to participate in a #KIWAY. Those that + * do must actually interact with the provided #KIWAY. + * + * #EDA_BASE_FRAME would not have sufficed because #BM2CMP_FRAME_BASE is not derived + * from it. */ #ifdef SWIG class KIWAY_PLAYER : public wxFrame, public KIWAY_HOLDER @@ -63,59 +63,53 @@ class KIWAY_PLAYER : public EDA_BASE_FRAME { public: KIWAY_PLAYER( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType, - const wxString& aTitle, const wxPoint& aPos, const wxSize& aSize, - long aStyle, const wxString& aWdoName = wxFrameNameStr ); + const wxString& aTitle, const wxPoint& aPos, const wxSize& aSize, + long aStyle, const wxString& aWdoName = wxFrameNameStr ); /// Don't use this one, only wxformbuilder uses it, and it must be augmented with /// a SetKiway() early in derived constructor. KIWAY_PLAYER( wxWindow* aParent, wxWindowID aId, const wxString& aTitle, - const wxPoint& aPos, const wxSize& aSize, long aStyle, - const wxString& aWdoName = wxFrameNameStr ); + const wxPoint& aPos, const wxSize& aSize, long aStyle, + const wxString& aWdoName = wxFrameNameStr ); ~KIWAY_PLAYER() throw(); - //--------------------------------------------------------- - // For the aCtl argument of OpenProjectFiles() -#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_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. /** - * Function OpenProjectFiles - * 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. - *

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

- * 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. + * Open a project or set of files given by @a aFileList. * - * @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. + * 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. * + * 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. - * - * @return bool - true if all requested files were opened OK, else false. + * @return true if all requested files were opened OK, else false. */ virtual bool OpenProjectFiles( const std::vector& 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 * options/switches that are handled by the top-level launcher before passing control to * the child frame. @@ -144,34 +139,30 @@ public: /** - * Function ShowModal - * puts up this wxFrame as if it were a modal dialog, with all other instantiated - * wxFrames disabled until this KIWAY_PLAYER derivative calls DismissModal(). - * That is, behavior is similar to a modal dialog window. Not all KIWAY_PLAYERs - * use this interface, so don't call this unless the implementation knows how - * to call DismissModal() on a button click or double click or some special - * event which ends the modal behavior. + * Show this wxFrame as if it were a modal dialog, with all other instantiated wxFrames + * disabled until this #KIWAY_PLAYER derivative calls DismissModal(). + * + * This is behavior is similar to a modal dialog window. Not all KIWAY_PLAYERs use this + * interface, so don't call this unless the implementation knows how to call DismissModal() + * on a button click or double click or some special event which ends the modal behavior. * * @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. - * - * @return bool - true if frame implementation called KIWAY_PLAYER::DismissModal() - * with aRetVal of true. + * @return true if frame implementation called KIWAY_PLAYER::DismissModal() with aRetVal + * of true. */ - virtual bool ShowModal( wxString* aResult = NULL, wxWindow* aResultantFocusWindow = NULL ); - - //-------------------------------------------------------- - + virtual bool ShowModal( wxString* aResult = nullptr, + wxWindow* aResultantFocusWindow = nullptr ); /** - * Function KiwayMailIn - * receives KIWAY_EXPRESS messages from other players. Merely override it - * in derived classes. + * Receive #KIWAY_EXPRESS messages from other players. + * + * Override it in derived classes. */ 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; @@ -179,10 +170,9 @@ public: void SetModal( bool aIsModal ) { m_modal = aIsModal; } /** - * Function IsDismissed - * returns false only if both the frame is acting in modal mode and it has not been - * dismissed yet with DismissModal(). IOW, it will return true if the dialog is - * not modal or if it is modal and has been dismissed. + * @return 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 + * it is modal and has been dismissed. */ bool IsDismissed(); @@ -194,14 +184,15 @@ protected: void kiway_express( KIWAY_EXPRESS& aEvent ); /** - * Function language_change - * is an event handler called on a language menu selection. + * An event handler called on a language menu selection. */ void language_change( wxCommandEvent& event ); // variables for modal behavior support, only used by a few derivatives. 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 wxString m_modal_string; bool m_modal_ret_val; // true if a selection was made @@ -269,11 +260,6 @@ bool OpenProjectFiles( const std::vector& aFileList, int aCtl = 0 ) show contents. } - - #endif - - - #endif // KIWAY_PLAYER_H_ diff --git a/include/pgm_base.h b/include/pgm_base.h index 5d4980b7d3..847854ad74 100644 --- a/include/pgm_base.h +++ b/include/pgm_base.h @@ -2,8 +2,8 @@ * 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) 2008-2015 Wayne Stambaugh - * Copyright (C) 1992-2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2008-2015 Wayne Stambaugh + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -48,11 +48,11 @@ class COMMON_SETTINGS; class SETTINGS_MANAGER; /** - * 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 - * To add a support to a new translation: - * add a new item to LanguagesList[]. + * 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. To add a support to a new translation add a new item + * to #LanguagesList[]. */ struct LANGUAGE_DESCR { @@ -69,21 +69,17 @@ struct LANGUAGE_DESCR bool m_DoNotTranslate; }; + /** * An array containing all the languages that KiCad supports. */ extern LANGUAGE_DESCR LanguagesList[]; -// inter program module calling -#define VTBL_ENTRY virtual - /** - * ENV_VAR_ITEM - * - * is 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 applications - * was launched. + * 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 + * applications was launched. */ class ENV_VAR_ITEM { @@ -110,7 +106,7 @@ private: wxString m_value; /// 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::const_iterator ENV_VAR_MAP_CITER; /** - * PGM_BASE - * keeps program (whole process) data for KiCad programs. - * The VTBL_ENTRY functions are VTBL_ENTRY so we can do cross module calls - * without linking to them. This used to be a wxApp derivative, but that - * is difficult under wxPython which shapes the wxApp. So now this is a "side-car" - * (like a motorcycle side-car) object with a back pointer into the wxApp - * which initializes it. - *

- * OnPgmStart() is virtual, may be overridden, and parallels - * wxApp::OnInit(), from where it should called. - *

- * OnPgmEnd() is virtual, may be overridden, and parallels wxApp::OnExit(), - * from where it should be called. + * Container for data for KiCad programs. + * + * The functions are virtual so we can do cross module calls without linking to them. This + * used to be a wxApp derivative, but that is difficult under wxPython which shapes the wxApp. + * So now this is a "side-car" (like a motorcycle side-car) object with a back pointer into + * the wxApp which initializes it. + * + * - OnPgmStart() is virtual, may be overridden, and parallels wxApp::OnInit(), from where it + * should called. + * - OnPgmEnd() is virtual, may be overridden, and parallels wxApp::OnExit(), from where it + * should be called. */ class PGM_BASE { @@ -162,31 +156,30 @@ public: virtual void OnPgmExit() = 0; // call this from wxApp::OnExit() #endif - //--------------------------------------------------------- - /** - * Function MacOpenFile - * is specific to MacOSX (not used under Linux or Windows). + * Specific to MacOSX (not used under Linux or Windows). + * * MacOSX requires it for file association. * @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. + * * @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 * editor's executable. * @return Returns the full path of the editor, or an empty string if no editor has * 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. @@ -195,82 +188,75 @@ public: * @return Returns the full path of the editor, or an empty string if no editor was * chosen. */ - VTBL_ENTRY const wxString AskUserForPreferredEditor( - const wxString& aDefaultEditor = wxEmptyString ); + virtual const wxString AskUserForPreferredEditor( + 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 - * returns true if the PDF browser is the default (system) PDF browser - * and false if the PDF browser is the preferred (selected) browser, else - * returns false if there is no selected browser + * @return true if the PDF browser is the default (system) PDF browser and false if the + * PDF browser is the preferred (selected) browser, else 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(); } /** - * Function ForceSystemPdfBrowser - * forces the use of system PDF browser, even if a preferred PDF browser is set. + * Force 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. + * * The files are in kicad/internat/xx or kicad/internat/xx_XX and are named kicad.mo - *

- * @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 - * clicking on a menu item) + * @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 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 - */ - 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 + * Set in .m_language_id member the wxWidgets language identifier ID fromthe KiCad + * menu id (internal menu identifier). * + * @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. * * 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. * @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 - * - * 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 + * 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 * 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; } /** - * Function App - * returns a bare naked wxApp, which may come from wxPython, SINGLE_TOP, or kicad.exe. - * Should return what wxGetApp() returns. + * Returns a bare naked wxApp which may come from wxPython, SINGLE_TOP, or kicad.exe. + * + * This should return what wxGetApp() returns. */ - VTBL_ENTRY wxApp& App(); - - //-------------------------------------------------------- + virtual wxApp& App(); static const wxChar workingDirKey[]; /** - * Function initPgm - * initializes this program (process) in a KiCad standard way, - * using some generalized techniques. + * Initialize this program. + * + * Initialize the process in a KiCad standard way using some generalized techniques: * - Default paths (help, libs, bin) and configuration file names * - Language and locale * - fonts - *

- * But nothing relating to DSOs or projects. - * @return bool - true if success, false if failure and program is to terminate. + * + * @note Do not initialize anything relating to DSOs or projects. + * + * @return true if success, false if failure and program is to terminate. */ bool InitPgm(); @@ -330,8 +313,7 @@ public: void Destroy(); /** - * Function saveCommonSettings - * saves the program (process) settings subset which are stored .kicad_common + * Save the program (process) settings subset which are stored .kicad_common. */ void SaveCommonSettings(); @@ -343,10 +325,19 @@ public: int m_ModalDialogCount; protected: - /// Loads internal settings from COMMON_SETTINGS 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 m_settings_manager; /// 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 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. wxString m_pdf_browser; 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 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 extern PGM_BASE* PgmOrNull(); diff --git a/include/project.h b/include/project.h index 28380d2eb4..bfb700c797 100644 --- a/include/project.h +++ b/include/project.h @@ -1,7 +1,7 @@ /* * 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 * modify it under the terms of the GNU General Public License @@ -52,27 +52,24 @@ class FILENAME_RESOLVER; class PROJECT_FILE; class PROJECT_LOCAL_SETTINGS; -#define VTBL_ENTRY virtual /** - * PROJECT - * 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 - * be VTBL_ENTRYs. + * Container for 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 be virtual. */ 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: - - /// A PROJECT can hold stuff it knows nothing about, in the form of - /// _ELEM derivatives. Derive PROJECT elements from this, it has a virtual - /// destructor, and Elem*() functions can work with it. Implementation is - /// opaque in class PROJECT. If find you have to include derived class headers - /// in this file, you are doing incompatible with the goal of this class. - /// Keep knowledge of derived classes opaque to class PROJECT please. + /** + * A #PROJECT can hold stuff it knows nothing about, in the form of _ELEM derivatives. + * + * Derive #PROJECT elements from this, it has a virtual destructor, and Elem*() functions + * can work with it. Implementation is opaque in class #PROJECT. If find you have to + * include derived class headersin this file, you are doing incompatible with the goal + * of this class. Keep knowledge of derived classes opaque to class PROJECT please. + */ class _ELEM { public: @@ -82,71 +79,76 @@ public: }; PROJECT(); - VTBL_ENTRY ~PROJECT(); + virtual ~PROJECT(); //--------------------------------------------------------- - VTBL_ENTRY bool TextVarResolver( wxString* aToken ) const; + virtual bool TextVarResolver( wxString* aToken ) const; - VTBL_ENTRY std::map& GetTextVars() const; + virtual std::map& GetTextVars() const; /** - * Function GetProjectFullName - * 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. + * Return the full path and name of the project. + * + * 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 - * 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. + * Return the full path of the project. + * + * 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 - * returns the short name of the project. This is the file name without - * extension or path. + * Return the short name of the project. + * + * 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 - * no real project is open). 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 a bull project + * 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, 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. */ - 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 fp-lib-table, - * i.e. the project specific one, not the global one. + * Returns the path and filename of this project's footprint library table. + * + * 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. */ - 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 ); return *m_projectFile; } - VTBL_ENTRY PROJECT_LOCAL_SETTINGS& GetLocalSettings() const + virtual PROJECT_LOCAL_SETTINGS& GetLocalSettings() const { wxASSERT( m_localSettings ); return *m_localSettings; @@ -175,24 +177,25 @@ public: }; /** - * Function GetRString - * returns a "retained string", which is any session and project specific string - * identified in enum RSTRING_T. Retained strings are not written to disk, and - * are therefore good only for the current session. + * Return a "retained string", which is any session and project specific string + * identified in enum #RSTRING_T. + * + *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 - * stores a "retained string", which is any session and project specific string - * identified in enum RSTRING_T. Retained strings are not written to disk, and - * are therefore good only for the current session. + * Store a "retained string", which is any session and project specific string + * identified in enum #RSTRING_T. + * + * 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 - * is the set of _ELEMs that a PROJECT can hold. + * The set of #_ELEMs that a #PROJECT can hold. */ enum ELEM_T { @@ -207,26 +210,27 @@ public: }; /** - * Typically wrapped somewhere else in a more meaningful function wrapper. - * This is a cross module API, therefore the _ELEM destructor is virtual and + * Get and set the elements for this project. + * + * 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 * that program module is resident at time of destruction. - *

- * Summary: 1) cross module API, 2) PROJECT knows nothing about _ELEM objects, - * except how to delete them and set and get pointers to them. + * + * Summary: + * -#) 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 ); - VTBL_ENTRY void SetElem( ELEM_T aIndex, _ELEM* aElem ); + virtual _ELEM* GetElem( ELEM_T aIndex ); + virtual void SetElem( ELEM_T aIndex, _ELEM* aElem ); /** - * Function ElemsClear - * deletes all the _ELEMs and set their pointers to NULL. + * Delete all the _ELEMs and set their pointers to NULL. */ - VTBL_ENTRY void ElemsClear(); + virtual void ElemsClear(); /** - * Function Clear - * clears the _ELEMs and RSTRINGs. + * Clear the _ELEMs and RSTRINGs. */ void Clear() // inline not virtual { @@ -237,22 +241,18 @@ public: } /** - * Function AbsolutePath - * fixes up @a aFileName if it is relative to the project's directory to - * be an absolute path and filename. This intends to overcome the now missing - * chdir() into the project directory. + * Fix up @a aFileName if it is relative to the project's directory to be an absolute + * path and filename. + * + * 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 - * this is fetched from pcbnew. + * Return the table of footprint libraries. Requires an active Kiway as this is fetched + * from Pcbnew. */ - VTBL_ENTRY FP_LIB_TABLE* PcbFootprintLibs( KIWAY& aKiway ); - - //-------------------------------------------------------- - - //----------------------------------------------------- + virtual FP_LIB_TABLE* PcbFootprintLibs( KIWAY& aKiway ); // 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 @@ -263,19 +263,18 @@ public: // 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. // 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 - * pcbnew. + * Return the table of footprint libraries without Kiway, only from within Pcbnew. */ FP_LIB_TABLE* PcbFootprintLibs(); /** - * Function Get3DCacheManager - * 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. * - * @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 ); @@ -284,7 +283,7 @@ public: #endif -#if defined(EESCHEMA) +#if defined( EESCHEMA ) // These are all prefaced with "Sch" PART_LIBS* SchLibs(); @@ -298,34 +297,39 @@ public: FILENAME_RESOLVER* Get3DFilenameResolver() { return nullptr; } #endif - //---------------------------------------------------- - 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: - * 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 - * the name of the project. The project name and the *.pro file names are - * exactly the same, providing the *.pro filename is absolute. + * Set the full directory, basename, and extension of the project. + * + * 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 project file names are exactly + * 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 - * Should only be called by SETTINGS_MANGER on load. - * @param aFile is a loaded PROJECT_FILE + * Set the backing store file for this project. + * + * 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; } /** - * 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) */ - VTBL_ENTRY void setLocalSettings( PROJECT_LOCAL_SETTINGS* aSettings ) + virtual void setLocalSettings( PROJECT_LOCAL_SETTINGS* aSettings ) { m_localSettings = aSettings; }