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

Header clean up round 2.

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

44
common/hotkeys_basic.cpp
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2010-2011 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 2010 Wayne Stambaugh <stambaughw@gmail.com>
* 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 <tab><keyname> (shortcuts in menus, same as hotkeys)
* IS_COMMENT to add <spaces><(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 <tab><keyname> (shortcuts in menus, same as hotkeys).
* IS_COMMENT to add <spaces><(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 <unassigned>.
// recognize the keyname, which is the case for <unassigned>.
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<std::string, int>& aHotKeys )
void ReadHotKeyConfig( const wxString& aFileName, std::map<std::string, int>& aHotKeys )
{
wxString fileName = aFileName;
if( fileName.IsEmpty() )
{
wxFileName fn( "user" );
@ -367,22 +366,19 @@ int WriteHotKeyConfig( const std::map<std::string, TOOL_ACTION*>& 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();

8
include/filehistory.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2019 Ian McInerney <Ian.S.McInerney@ieee.org>
* Copyright (C) 2019 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

182
include/filename_resolver.h
View File

@ -2,6 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2015-2016 Cirilo Bernardo <cirilo.bernardo@gmail.com>
* Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* 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<SEARCH_PATH> m_paths; // list of base paths to search from
int m_errflags;
PGM_BASE* m_pgm;
PROJECT* m_project;
wxString m_curProjDir;
/**
* Function createPathList
* builds the path list using available information such as
* KISYS3DMOD and the 3d_path_list configuration file. Invalid
* paths are silently discarded and removed from the configuration
* file.
*
* @return true if at least one valid path was found
*/
bool createPathList( void );
/**
* Function addPath
* checks that a path is valid and adds it to the search list
*
* @param aPath is the alias set to be checked and added
* @return true if aPath is valid
*/
bool addPath( const SEARCH_PATH& aPath );
/**
* Function readPathList
* reads a list of path names from a configuration file
*
* @return true if a file was found and contained at least
* one valid path
*/
bool readPathList( void );
/**
* Function writePathList
* writes the current path list to a configuration file
*
* @return true if the path list was not empty and was
* successfully written to the configuration file
*/
bool writePathList( void );
/**
* Function checkEnvVarPath
* checks the ${ENV_VAR} component of a path and adds
* it to the resolver's path list if it is not yet in
* the list
*/
void checkEnvVarPath( const wxString& aPath );
public:
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<SEARCH_PATH> m_paths; // list of base paths to search from
int m_errflags;
PGM_BASE* m_pgm;
PROJECT* m_project;
wxString m_curProjDir;
};
#endif // FILENAME_RESOLVER_H

7
include/fill_type.h
View File

@ -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
#endif

32
include/filter_reader.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2007-2010 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2007 KiCad Developers, see change_log.txt for contributors.
* Copyright (C) 2007-2020 KiCad Developers, see change_log.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* 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_

87
include/footprint_info.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2011 Jean-Pierre Charras, <jp.charras@wanadoo.fr>
* Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* 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<std::unique_ptr<FOOTPRINT_INFO>> FPILIST;
typedef SYNC_QUEUE<std::unique_ptr<IO_ERROR>> ERRLIST;
FPILIST m_list;
ERRLIST m_errors; ///< some can be PARSE_ERRORs also
public:
FOOTPRINT_LIST() : m_lib_table( 0 )
{
}
@ -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;
};

129
include/fp_lib_table.h
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2012-2017 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 2012-2017 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 2012-2020 Wayne Stambaugh <stambaughw@verizon.net>
* 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 );
//-----<PLUGIN API SUBSET, REBASED ON 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 );
//-----</PLUGIN API SUBSET, REBASED ON 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, <b>if</b> 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, <b>if</b> it is not set already in the environment.
*/
static const wxString GlobalPathEnvVariableName();
private:
friend class FP_LIB_TABLE_GRID;
};

6
include/frame_type.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2014 CERN
* Copyright (C) 1992-2017 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors.
* @author Maciej Suminski <maciej.suminski@cern.ch>
*
* 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
{

254
include/gbr_metadata.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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 <gbr_netlist_metadata.h>
/** 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,<function>*%"
* @param aUseX1StructuredComment = false in X2 mode,
* and true in X1 mode to add the net attribut
* inside a compatible X1 structured comment starting by "G04 #@! "
* like "G04 #@! TA.AperFunction,<function>*"
* like "%TA.AperFunction,<function>*%"
*/
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,

142
include/gbr_netlist_metadata.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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,<angle> 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,<string> Manufacturer
* %TO.CMPN,<string> Manufacturer part number
* %TO.Cpkg,<string> Package, as per IPC-7351
@ -49,8 +51,8 @@
* %TO.CHgt,<string> Height, a decimal, in the unit of the file.
* %TO.CLbN,<string> Library name.
* %TO.CLbD,<string> Library description.
* %TO.Sup,<SN>,<SPN> SN is a field with the supppier name.
* SPN is a field with the supppier part name
* %TO.Sup,<SN>,<SPN> 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

61
include/gestfich.h
View File

@ -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 \<KICAD\> /;
* Otherwise returns \<path of binaries\> / (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 );

45
include/gl_context_mgr.h
View File

@ -2,6 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2016 CERN
* Copyright (C) 2020 KiCad Developers, see CHANGELOG.TXT for contributors.
* @author Maciej Suminski <maciej.suminski@cern.ch>
*
* 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 );

15
include/gl_utils.h
View File

@ -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 <wglext.h> 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 <wglext.h> 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<int>::max();
#else
#else
return 0;
#endif
#endif
}
};

86
include/gr_basic.h
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2011 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 1992-2018 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 2011 Wayne Stambaugh <stambaughw@gmail.com>
* 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<GR_DRAWMODE>( int( *mode ) | GR_HIGHLIGHT );
}
inline void DrawModeAllowHighContrast(GR_DRAWMODE *mode)
inline void DrawModeAllowHighContrast( GR_DRAWMODE* mode )
{
*mode = static_cast<GR_DRAWMODE>( int( *mode ) | GR_ALLOW_HIGHCONTRAST );
}
inline GR_DRAWMODE operator ~(const GR_DRAWMODE& a)
inline GR_DRAWMODE operator~( const GR_DRAWMODE& a )
{
return static_cast<GR_DRAWMODE>( ~int( a ) );
}
inline GR_DRAWMODE operator |(const GR_DRAWMODE& a, const GR_DRAWMODE& b)
inline GR_DRAWMODE operator|( const GR_DRAWMODE& a, const GR_DRAWMODE& b )
{
return static_cast<GR_DRAWMODE>( int( a ) | int( b ) );
}
inline GR_DRAWMODE operator &(const GR_DRAWMODE& a, const GR_DRAWMODE& b)
inline GR_DRAWMODE operator&( const GR_DRAWMODE& a, const GR_DRAWMODE& b )
{
return static_cast<GR_DRAWMODE>( int( a ) & int( b ) );
}
@ -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<wxPoint>& 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<wxPoint>& 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<wxPoint>& 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 );

110
include/gr_text.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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 <eda_item.h>
#include <eda_text.h> // EDA_TEXT_HJUSTIFY_T and EDA_TEXT_VJUSTIFY_T
/* Minimum dimension in pixel for drawing/no drawing a text
* used in Pcbnew to decide to draw (or not) some texts
* ( 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__ */

24
include/grid_tricks.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2012 KiCad Developers, see change_log.txt for contributors.
* Copyright (C) 2012-2020 KiCad Developers, see change_log.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* 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_

75
include/hashtables.h
View File

@ -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 <dick@softplc.com>
* Copyright (C) 2012 KiCad Developers, see CHANGELOG.TXT for contributors.
* Copyright (C) 2012-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
*
* This program is free software; you can redistribute it and/or
* 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<KeyType, ValueType>; } typedef std::unordered_map<KeyType, ValueType> TypeName;
#define DECL_HASH_FOR_SWIG( TypeName, KeyType, ValueType ) \
namespace std \
{ \
% template( TypeName ) unordered_map<KeyType, ValueType>; \
} \
typedef std::unordered_map<KeyType, ValueType> TypeName;
#else
/// Declare a std::unordered_map but no swig %template
#define DECL_HASH_FOR_SWIG(TypeName, KeyType, ValueType) typedef std::unordered_map<KeyType, ValueType> TypeName;
#define DECL_HASH_FOR_SWIG( TypeName, KeyType, ValueType ) \
typedef std::unordered_map<KeyType, ValueType> TypeName;
#endif
/**
* 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;

77
include/hotkeys_basic.h
View File

@ -1,7 +1,7 @@
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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 <tab><keyname> (shortcuts in menus, same as hotkeys)
* IS_COMMENT to add <spaces><(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 <tab><keyname> (shortcuts in menus, same as hotkeys).
* #IS_COMMENT to add <spaces><(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<std::string, int>& aHotKeys );
void ReadHotKeyConfig( const wxString& aFileName, std::map<std::string, int>& 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<std::string, TOOL_ACTION*>& 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<std::string, int>& 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<std::string, int>& aMap );

55
include/ki_exception.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2007-2016 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* 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

54
include/kicad_string.h
View File

@ -1,7 +1,7 @@
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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<std::string> split( const std::string& aStr, const std::string& aDelim )
@ -309,17 +309,17 @@ inline void AccumulateDescription( wxString& aDesc, const wxString& aItem )
/**
* Split \a aString to a string list separated at \a aSplitter.
*
* @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 );

66
include/kiface_i.h
View File

@ -1,7 +1,7 @@
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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;
//-----<KIFACE API>----------------------------------------------------------
// 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;
//-----</KIFACE API>---------------------------------------------------------
// 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; }

445
include/kiway.h
View File

@ -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 <dick@softplc.com>
* Copyright (C) 2016 KiCad Developers, see CHANGELOG.TXT for contributors.
* Copyright (C) 2016-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
*
* This program is free software; you can redistribute it and/or
* 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.
<p>These are a couple of reasons why this design was chosen:
<ol>
<li>By using DSOs within a single process, it is not necessary to use IPC.
The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in
a platform independent way. There can also be function calls from one DSO to
another.</li>
<li>The use of a number of separately linked DSOs closely resembles the original
KiCad program design, consisting of Eeschema and Pcbnew. But it also allows
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. </li>
<li>By keeping the core functionality in DSOs rather than EXE tops, it becomes
possible to re-use the DSOs under different program tops. For example, a DSO
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.</li>
</ol>
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:
┏ ┗ ┓ ┛ ━ ┃
<pre>
┏━━━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 ━━━━━━━━━━━━━━━━━┛
</pre>
*/
/**
* 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.
*
* <p>These are a couple of reasons why this design was chosen:
*
* <ol>
*
* <li>By using DSOs within a single process, it is not necessary to use IPC.
* The DSOs can send wxEvents between themselves using wxEvtHandler interfaces in
* a platform independent way. There can also be function calls from one DSO to
* another.</li>
*
* <li>The use of a number of separately linked DSOs closely resembles the original
* KiCad program design, consisting of Eeschema and Pcbnew. But it also allows
* 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. </li>
*
* <li>By keeping the core functionality in DSOs rather than EXE tops, it becomes
* possible to re-use the DSOs under different program tops. For example, a DSO
* 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.</li>
*
*
* </ol>
*
* 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:
*
* ┏ ┗ ┓ ┛ ━ ┃
*
* <pre>
*
* ┏━━━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 ━━━━━━━━━━━━━━━━━┛
*
* </pre>
*
*/
#include <wx/event.h>
@ -106,12 +105,10 @@ as such! As such, it is OK to use UTF8 characters:
#include <ki_exception.h>
#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.
* <p>
* 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.
* <p>
* 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().
* <p>
* 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

29
include/kiway_express.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2014 KiCad Developers, see CHANGELOG.TXT for contributors.
* Copyright (C) 2014-202 KiCad Developers, see CHANGELOG.TXT for contributors.
*
* This program is free software; you can redistribute it and/or
* 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.
};

30
include/kiway_holder.h
View File

@ -1,7 +1,7 @@
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* 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_

10
include/kiway_mgr.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2014 KiCad Developers, see CHANGELOG.TXT for contributors.
* Copyright (C) 2014-2020 KiCad Developers, see CHANGELOG.TXT for contributors.
*
* This program is free software; you can redistribute it and/or
* 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
{

148
include/kiway_player.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2014 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2017 KiCad Developers, see change_log.txt for contributors.
* Copyright (C) 2017-2020 KiCad Developers, see change_log.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* 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*.
* <p>
* 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();
//----<Cross Module API>-----------------------------------------------------
// 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.
* <p>
* Each derived class should handle this in a way specific to its needs.
* No filename prompting is done inside here for any file or project. There should
* be no need to call this with aFileList which is empty. However, calling it with
* a single filename which does not exist should indicate to the implementor
* that a new session is being started and that the given name is the desired
* name for the data file at time of save.
* <p>
* This function does not support "appending". Use a different function for that.
* Any prior project data tree should be cleared before loading the new stuff.
* <p>
* Therefore, one of the first things an implementation should do is test for
* existence of the first file in the list, and if it does not exist, treat
* it as a new session, possibly with a UI notification to that effect.
* <p>
* After loading the window should update its Title as part of this operation.
* If the KIWAY_PLAYER needs to, it can load the *.pro file as part of this operation.
* <p>
* If the KIWAY_PLAYER cannot load any of the file(s) in the list, then it
* should say why through some GUI interface, and return false.
* 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<wxString>& aFileList, int aCtl = 0 )
{
@ -130,7 +124,8 @@ public:
}
/**
* Handles command-line arguments in a frame-specific way.
* Handle command-line arguments in a frame-specific way.
*
* The given argument parser has already been initialized with the command line and any
* 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 );
//----</Cross Module API>----------------------------------------------------
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<wxString>& aFileList, int aCtl = 0 )
show contents.
}
#endif
#endif // KIWAY_PLAYER_H_

231
include/pgm_base.h
View File

@ -2,8 +2,8 @@
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2004-2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2008-2015 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 1992-2017 KiCad Developers, see AUTHORS.txt for contributors.
* Copyright (C) 2008-2015 Wayne Stambaugh <stambaughw@gmail.com>
* 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<wxString, ENV_VAR_ITEM>::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.
* <p>
* OnPgmStart() is virtual, may be overridden, and parallels
* wxApp::OnInit(), from where it should called.
* <p>
* 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
//----<Cross Module API>-----------------------------------------------------
/**
* 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.
* <p>
* Set the dictionary file name for internationalization.
*
* The files are in kicad/internat/xx or kicad/internat/xx_XX and are named kicad.mo
* </p>
* @param aErrMsg is the string to return the error message it
* @param first_time must be set to true the first time this function is
* called, false otherwise
* @return false if there was an error setting the language
*/
VTBL_ENTRY bool SetLanguage( wxString& aErrMsg, bool first_time = false );
/**
* Function SetLanguageIdentifier
* sets in .m_language_id member the wxWidgets language identifier Id from
* the KiCad menu id (internal menu identifier).
*
* @param menu_id The KiCad menuitem id (returned by Menu Event, when
* 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();
//----</Cross Module API>----------------------------------------------------
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
* <p>
* 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<SETTINGS_MANAGER> 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();

212
include/project.h
View File

@ -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();
//-----<Cross Module API>----------------------------------------------------
VTBL_ENTRY bool TextVarResolver( wxString* aToken ) const;
virtual bool TextVarResolver( wxString* aToken ) const;
VTBL_ENTRY std::map<wxString, wxString>& GetTextVars() const;
virtual std::map<wxString, wxString>& GetTextVars() const;
/**
* Function GetProjectFullName
* 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.
* <p>
* 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 );
//-----</Cross Module API>---------------------------------------------------
//-----<KIFACE Specific APIs>------------------------------------------------
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
//-----</KIFACE Specific APIs>-----------------------------------------------
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;
}