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

Add support to resolve schematic symbol links using symbol library table. 

Add Resolve() and ResolveAll() methods the SCH_COMPONENT object to use the
symbol library table to obtain links to the library symbols.

Add LoadAlias() method to SYMBOL_LIB_TABLE to find an alias by it's LIB_ID.

Clean up Doxygen comments to match coding policy changes.
This commit is contained in:
Wayne Stambaugh 2017-06-27 11:22:25 -04:00
parent 1e87ae6c50
commit 85a0a371b1
3 changed files with 286 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
eeschema/sch_component.cpp
View File

@ -295,10 +295,7 @@ void SCH_COMPONENT::SetLibId( const LIB_ID& aLibId, SYMBOL_LIB_TABLE* aSymLibTab
}
}
/**
* Function GetAliasDescription
* Return the description text for the given part alias
*/
wxString SCH_COMPONENT::GetAliasDescription() const
{
if( PART_SPTR part = m_part.lock() )
@ -314,10 +311,7 @@ wxString SCH_COMPONENT::GetAliasDescription() const
return wxEmptyString;
}
/**
* Function GetAliasDocumentation
* Return the documentation text for the given part alias
*/
wxString SCH_COMPONENT::GetAliasDocumentation() const
{
if( PART_SPTR part = m_part.lock() )
@ -333,6 +327,7 @@ wxString SCH_COMPONENT::GetAliasDocumentation() const
return wxEmptyString;
}
bool SCH_COMPONENT::Resolve( PART_LIBS* aLibs )
{
// I've never been happy that the actual individual PART_LIB is left up to
@ -346,6 +341,21 @@ bool SCH_COMPONENT::Resolve( PART_LIBS* aLibs )
return false;
}
bool SCH_COMPONENT::Resolve( SYMBOL_LIB_TABLE& aLibTable )
{
LIB_ALIAS* alias = aLibTable.LoadSymbol( m_lib_id );
if( alias && alias->GetPart() )
{
m_part = alias->GetPart()->SharedPtr();
return true;
}
return false;
}
// Helper sort function, used in SCH_COMPONENT::ResolveAll, to sort
// sch component by lib_id
static bool sort_by_libid( const SCH_COMPONENT* ref, SCH_COMPONENT* cmp )
@ -353,8 +363,8 @@ static bool sort_by_libid( const SCH_COMPONENT* ref, SCH_COMPONENT* cmp )
return ref->GetLibId() < cmp->GetLibId();
}
void SCH_COMPONENT::ResolveAll(
const SCH_COLLECTOR& aComponents, PART_LIBS* aLibs )
void SCH_COMPONENT::ResolveAll( const SCH_COLLECTOR& aComponents, PART_LIBS* aLibs )
{
// Usually, many components use the same part lib.
// to avoid too long calculation time the list of components is grouped
@ -398,6 +408,44 @@ void SCH_COMPONENT::ResolveAll(
}
void SCH_COMPONENT::ResolveAll( const SCH_COLLECTOR& aComponents, SYMBOL_LIB_TABLE& aLibTable )
{
std::vector<SCH_COMPONENT*> cmp_list;
for( int i = 0; i < aComponents.GetCount(); ++i )
{
SCH_COMPONENT* cmp = dynamic_cast<SCH_COMPONENT*>( aComponents[i] );
wxCHECK2_MSG( cmp, continue, "Invalid SCH_COMPONENT pointer in list." );
cmp_list.push_back( cmp );
}
// sort it by lib part. Cmp will be grouped by same lib part.
std::sort( cmp_list.begin(), cmp_list.end(), sort_by_libid );
LIB_ID curr_libid;
for( unsigned ii = 0; ii < cmp_list.size (); ++ii )
{
SCH_COMPONENT* cmp = cmp_list[ii];
cmp->Resolve( aLibTable );
// Propagate the m_part pointer to other members using the same lib_id
for( unsigned jj = ii+1; jj < cmp_list.size (); ++jj )
{
SCH_COMPONENT* next_cmp = cmp_list[jj];
if( curr_libid != next_cmp->m_lib_id )
break;
next_cmp->m_part = cmp->m_part;
ii = jj;
}
}
}
void SCH_COMPONENT::SetUnit( int aUnit )
{
if( m_unit != aUnit )
@ -407,6 +455,7 @@ void SCH_COMPONENT::SetUnit( int aUnit )
}
}
void SCH_COMPONENT::UpdateUnit( int aUnit )
{
m_unit = aUnit;
@ -589,12 +638,6 @@ const wxString SCH_COMPONENT::GetRef( const SCH_SHEET_PATH* sheet )
}
/* Function IsReferenceStringValid (static function)
* Tests for an acceptable reference string
* An acceptable reference string must support unannotation
* i.e starts by letter
* returns true if OK
*/
bool SCH_COMPONENT::IsReferenceStringValid( const wxString& aReferenceString )
{
wxString text = aReferenceString;
@ -771,6 +814,7 @@ SCH_FIELD* SCH_COMPONENT::GetField( int aFieldNdx ) const
return (SCH_FIELD*) field;
}
wxString SCH_COMPONENT::GetFieldText( wxString aFieldName, bool aIncludeDefaultFields ) const
{
// Field name for comparison
@ -824,11 +868,7 @@ SCH_FIELD* SCH_COMPONENT::AddField( const SCH_FIELD& aField )
return &m_Fields[newNdx];
}
/*
* Find and return compnent field with the given name
* @aFieldName is the name of the field to search for
* @aIncludeDefaultFields excludes default fields from search if set to false
*/
SCH_FIELD* SCH_COMPONENT::FindField( const wxString& aFieldName, bool aIncludeDefaultFields )
{
unsigned start = aIncludeDefaultFields ? 0 : MANDATORY_FIELDS;

301
eeschema/sch_component.h
View File

@ -98,8 +98,8 @@ private:
/**
* A temporary sheet path is required to generate the correct reference designator string
* in complex heirarchies. Hopefully this is only a temporary hack to decouple schematic
* objects from the drawing window until a better design for handling complex heirarchies
* in complex hierarchies. Hopefully this is only a temporary hack to decouple schematic
* objects from the drawing window until a better design for handling complex hierarchies
* can be implemented.
*/
const SCH_SHEET_PATH* m_currentSheetPath;
@ -135,11 +135,13 @@ public:
bool setNewItemFlag = false );
/**
* Copy Constructor
* clones \a aComponent into a new object. All fields are copied as is except
* for the linked list management pointers which are set to NULL, and the
* SCH_FIELD's m_Parent pointers which are set to the new parent,
* i.e. this new object.
* Clones \a aComponent into a new schematic symbol object.
*
* All fields are copied as is except for the linked list management pointers
* which are set to NULL, and the SCH_FIELD's m_Parent pointers which are set
* to the new object.
*
* @param aComponent is the schematic symbol to clone.
*/
SCH_COMPONENT( const SCH_COMPONENT& aComponent );
@ -153,12 +155,13 @@ public:
const wxArrayString& GetPathsAndReferences() const { return m_PathsAndReferences; }
/**
* Virtual function IsMovableFromAnchorPoint
* Return true for items which are moved with the anchor point at mouse cursor
* and false for items moved with no reference to anchor
* Usually return true for small items (labels, junctions) and false for
* items which can be large (hierarchical sheets, compoments)
* @return false for a componant
* and false for items moved with no reference to anchor.
*
* Usually return true for small items (labels, junctions) and false for items which can
* be large (hierarchical sheets, components).
*
* @return false for a component
*/
bool IsMovableFromAnchorPoint() override { return false; }
@ -173,34 +176,45 @@ public:
* Return information about the aliased parts
*/
wxString GetAliasDescription() const;
/**
* Return the documentation text for the given part alias
*/
wxString GetAliasDocumentation() const;
/**
* Function Resolve
* [re-]assigns the current LIB_PART from aLibs which this component
* is based on.
* Assigns the current #LIB_PART from \a aLibs which this symbol is based on.
*
* @param aLibs is the current set of LIB_PARTs to choose from.
*/
bool Resolve( PART_LIBS* aLibs );
bool Resolve( SYMBOL_LIB_TABLE& aLibTable );
static void ResolveAll( const SCH_COLLECTOR& aComponents, PART_LIBS* aLibs );
static void ResolveAll( const SCH_COLLECTOR& aComponents, SYMBOL_LIB_TABLE& aLibTable );
int GetUnit() const { return m_unit; }
/**
* change the unit id to aUnit
* has maening only for multiple parts per package
* Also set the modified flag bit
* @param aUnit = the new unit Id
* Change the unit number to \a aUnit
*
* This has meaning only for symbols made up of multiple units per package.
*
* @note This also set the modified flag bit
*
* @param aUnit is the new unit to select.
*/
void SetUnit( int aUnit );
/**
* change the unit id to aUnit
* has maening only for multiple parts per package
* Do not change the modified flag bit, and should be used when
* change is not due to an edition command
* @param aUnit = the new unit Id
* Change the unit number to \a aUnit without setting any internal flags.
* This has meaning only for symbols made up of multiple units per package.
*
* @note This also set the modified flag bit
*
* @param aUnit is the new unit to select.
*/
void UpdateUnit( int aUnit );
@ -217,10 +231,9 @@ public:
void SetTransform( const TRANSFORM& aTransform );
/**
* Function GetUnitCount
* returns the number of parts per package of the component.
* Return the number of units per package of the symbol.
*
* @return The number of parts per package or zero if the library entry cannot be found.
* @return the number of units per package or zero if the library entry cannot be found.
*/
int GetUnitCount() const;
@ -229,34 +242,37 @@ public:
bool Load( LINE_READER& aLine, wxString& aErrorMsg ) override;
/**
* Function SetOrientation
* computes the new transform matrix based on \a aOrientation for the component which is
* Compute the new transform matrix based on \a aOrientation for the symbol which is
* applied to the current transform.
* @param aOrientation The orientation to apply to the transform.
*
* @param aOrientation is the orientation to apply to the transform.
*/
void SetOrientation( int aOrientation );
/**
* Function GetOrientation
* Used to display component orientation (in dialog editor or info)
* @return the orientation and mirror
* Note: Because there are different ways to have a given orientation/mirror,
* the orientation/mirror is not necessary what the used does
* (example : a mirrorX then a mirrorY give no mirror but rotate the
* component).
* So this function find a rotation and a mirror value
* ( CMP_MIRROR_X because this is the first mirror option tested)
* but can differs from the orientation made by an user
* ( a CMP_MIRROR_Y is find as a CMP_MIRROR_X + orientation 180, because
* they are equivalent)
* Get the display symbol orientation.
*
* Because there are different ways to have a given orientation/mirror,
* the orientation/mirror is not necessary what the user does. For example:
* a mirrorX then a mirrorY returns no mirror but a rotate. This function finds
* a rotation and a mirror value #CMP_MIRROR_X because this is the first mirror
* option tested. This can differs from the orientation made by an user. A
* #CMP_MIRROR_Y is returned as a #CMP_MIRROR_X with an orientation 180 because
* they are equivalent.
*
* @sa COMPONENT_ORIENTATION_T
*
* @return the orientation and mirror of the symbol.
*/
int GetOrientation();
/**
* Function GetScreenCoord
* Returns the coordinated point relative to the orientation of the component of \a aPoint.
* Returns the coordinate points relative to the orientation of the symbol to \a aPoint.
*
* The coordinates are always relative to the anchor position of the component.
*
* @param aPoint The coordinates to transform.
*
* @return The transformed point.
*/
wxPoint GetScreenCoord( const wxPoint& aPoint );
@ -264,17 +280,20 @@ public:
void GetMsgPanelInfo( std::vector< MSG_PANEL_ITEM >& aList ) override;
/**
* Function ClearAnnotation
* clears exiting component annotation ( i.i IC23 changed to IC? and part reset to 1)
* @param aSheetPath: SCH_SHEET_PATH value: if NULL remove all annotations,
* else remove annotation relative to this sheetpath
* Clear exiting component annotation.
*
* For example, IC23 would be changed to IC? and unit number would be reset.
*
* @param aSheetPath is the hierarchical path of the symbol to clear or remove all
* annotations for this symbol if NULL.
*/
void ClearAnnotation( SCH_SHEET_PATH* aSheetPath );
/**
* Function SetTimeStamp
* changes the time stamp to \a aNewTimeStamp updates the reference path.
* Change the time stamp to \a aNewTimeStamp and updates the reference path.
*
* @see m_PathsAndReferences
*
* @param aNewTimeStamp = new time stamp
*/
void SetTimeStamp( time_t aNewTimeStamp );
@ -282,8 +301,7 @@ public:
const EDA_RECT GetBoundingBox() const override;
/**
* Function GetBodyBoundingBox
* Return a bounding box for the component body but not the fields.
* Return a bounding box for the symbol body but not the fields.
*/
EDA_RECT GetBodyBoundingBox() const;
@ -291,83 +309,92 @@ public:
//-----<Fields>-----------------------------------------------------------
/**
* Function GetField
* returns a field.
* @param aFieldNdx An index into the array of fields, not a field id.
* @return SCH_FIELD* - the field value or NULL if does not exist
* Returns a field in this symbol.
*
* @param aFieldNdx is the index into the array of fields, not a field id.
*
* @return is the field at \a aFieldNdx or NULL if the field does not exist.
*/
SCH_FIELD* GetField( int aFieldNdx ) const;
/**
* Search for a field named aFieldName and returns text associated with this field
* (if such a field exists)
* Search for a field named \a aFieldName and returns text associated with this field.
*
* @param aFieldName is the name of the field
* @param aIncludeDefaultFields = true (default) to include default fields in search
* (default fields are the mandatory fields ref, value, fooprint and doc)
* @param aIncludeDefaultFields is used to search the default library symbol fields in the
* search.
*/
wxString GetFieldText( wxString aFieldName, bool aIncludeDefaultFields = true ) const;
/**
* Function GetFields
* populates a std::vector with SCH_FIELDs.
* @param aVector - vector to populate.
* @param aVisibleOnly - if true, only get fields that are visible and contain text.
* Populates a std::vector with SCH_FIELDs.
*
* @param aVector is the vector to populate.
* @param aVisibleOnly is used to add only the fields that are visible and contain text.
*/
void GetFields( std::vector<SCH_FIELD*>& aVector, bool aVisibleOnly );
/**
* Function AddField
* adds a field to the component. The field is copied as it is put into
* the component.
* @param aField A const reference to the SCH_FIELD to add.
* @return SCH_FIELD* - the newly inserted field.
* Add a field to the symbol.
*
* @param aField is the field to add to this symbol.
*
* @return the newly inserted field.
*/
SCH_FIELD* AddField( const SCH_FIELD& aField );
/**
* Function FindField
* searches for SCH_FIELD with \a aFieldName and returns it if found, else NULL.
* Search for a #SCH_FIELD with \a aFieldName
*
* @param aFieldName is the name of the field to find.
* @param aIncludeDefaultFields searches the library symbol default fields if true.
*
* @return the field if found or NULL if the field was not found.
*/
SCH_FIELD* FindField( const wxString& aFieldName, bool aIncludeDefaultFields = true );
/**
* Set multiple schematic fields.
*
* @param aFields are the fields to set in this symbol.
*/
void SetFields( const SCH_FIELDS& aFields )
{
m_Fields = aFields; // vector copying, length is changed possibly
}
/**
* Function GetFieldCount
* returns the number of fields in this component.
* Return the number of fields in this symbol.
*/
int GetFieldCount() const { return (int)m_Fields.size(); }
/**
* Function GetFieldsAutoplaced
* returns whether the fields are autoplaced.
* Return whether the fields have been automatically placed.
*/
AUTOPLACED GetFieldsAutoplaced() const { return m_fieldsAutoplaced; }
/**
* Function ClearFieldsAutoplaced
* Set fields autoplaced flag false.
* Set fields automatically placed flag false.
*/
void ClearFieldsAutoplaced() { m_fieldsAutoplaced = AUTOPLACED_NO; }
/**
* Function AutoplaceFields
* Automatically orient all the fields in the component.
* @param aScreen - the SCH_SCREEN associated with the current instance of the
*
* @param aScreen is the SCH_SCREEN associated with the current instance of the
* component. This can be NULL when aManual is false.
* @param aManual - True if the autoplace was manually initiated (e.g. by a hotkey
* @param aManual should be true if the autoplace was manually initiated (e.g. by a hotkey
* or a menu item). Some more 'intelligent' routines will be used that would be
* annoying if done automatically during moves.
*/
void AutoplaceFields( SCH_SCREEN* aScreen, bool aManual );
/**
* Function AutoAutoplaceFields
* Autoplace fields only if correct to do so automatically. That is, do not
* autoplace if fields have been moved by hand.
* @param aScreen - the SCH_SCREEN associated with the current instance of the
* Autoplace fields only if correct to do so automatically.
*
* Fields that have been moved by hand are not automatically placed.
*.
* @param aScreen is the SCH_SCREEN associated with the current instance of the
* component.
*/
void AutoAutoplaceFields( SCH_SCREEN* aScreen )
@ -381,23 +408,21 @@ public:
/**
* Function GetPin
* finds a component pin by number.
* Find a symbol pin by number.
*
* @param number is the number of the pin to find.
*
* @param number - The number of the pin to find.
* @return Pin object if found, otherwise NULL.
*/
LIB_PIN* GetPin( const wxString& number );
/**
* Function GetPins
* populate a vector with all the pins.
* Populate a vector with all the pins.
*
* @param aPinsList is the list to populate with all of the pins.
*/
void GetPins( std::vector<LIB_PIN*>& aPinsList );
/**
* Virtual function, from the base class SCH_ITEM::Draw
*/
void Draw( EDA_DRAW_PANEL* aPanel, wxDC* aDC, const wxPoint& aOffset,
GR_DRAWMODE aDrawMode, COLOR4D aColor = COLOR4D::UNSPECIFIED ) override
{
@ -405,16 +430,17 @@ public:
}
/**
* Function Draw, specific to components.
* Draw a component, with or without pin texts.
* @param aPanel DrawPanel to use (can be null) mainly used for clipping purposes.
* @param aDC Device Context (can be null)
* @param aOffset drawing Offset (usually wxPoint(0,0),
* Draw a component with or without pin text
*.
* @param aPanel is the panel to use (can be null) mainly used for clipping purposes.
* @param aDC is the device context (can be null)
* @param aOffset is the drawing offset (usually wxPoint(0,0),
* but can be different when moving an object)
* @param aDrawMode GR_OR, GR_XOR, ...
* @param aColor COLOR4D::UNSPECIFIED to use the normal body item color, or use this color if >= 0
* @param aDrawPinText = true to draw pin texts, false to draw only the pin shape
* usually false to draw a component when moving it, and true otherwise.
* @param aDrawMode is the drawing mode, GR_OR, GR_XOR, ...
* @param aColor use COLOR4D::UNSPECIFIED for the normal body item color or use this
* color if >= 0
* @param aDrawPinText use true to draw pin texts, false to draw only the pin shape
* usually false to draw a component when moving it and true otherwise.
*/
void Draw( EDA_DRAW_PANEL* aPanel, wxDC* aDC, const wxPoint& aOffset,
GR_DRAWMODE aDrawMode, COLOR4D aColor,
@ -426,12 +452,13 @@ public:
wxString GetPath( const SCH_SHEET_PATH* sheet ) const;
/**
* Function IsReferenceStringValid (static)
* Tests for an acceptable reference string
* An acceptable reference string must support unannotation
* i.e starts by letter
* @param aReferenceString = the reference string to validate
* @return true if OK
* Tests for an acceptable reference string.
*
* An acceptable reference string must support unannotation i.e starts by letter
*
* @param aReferenceString is the reference string to validate
*
* @return true if reference string is valid.
*/
static bool IsReferenceStringValid( const wxString& aReferenceString );
@ -441,23 +468,27 @@ public:
}
/**
* Function GetRef
* returns the reference, for the given sheet path.
* Return the reference for the given sheet path.
*
* @return the reference for the sheet.
*/
const wxString GetRef( const SCH_SHEET_PATH* sheet );
const wxString GetRef( const SCH_SHEET_PATH* aSheet );
/**
* Set the reference, for the given sheet path.
* Set the reference for the given sheet path for this symbol.
*
* @param aSheet is the hierarchical path of the reference.
* @param aReference is the new reference for the symbol.
*/
void SetRef( const SCH_SHEET_PATH* sheet, const wxString& ref );
void SetRef( const SCH_SHEET_PATH* aSheet, const wxString& aReference );
/**
* Function AddHierarchicalReference
* adds a full hierarchical reference (path + local reference)
* @param aPath Hierarchical path (/&ltsheet timestamp&gt/&ltcomponent
* Add a full hierarchical reference to this symbol.
*
* @param aPath is the hierarchical path (/&ltsheet timestamp&gt/&ltcomponent
* timestamp&gt like /05678E50/A23EF560)
* @param aRef :local reference like C45, R56
* @param aMulti Part selection, used in multi part per package (0 or 1 for non multi)
* @param aRef is the local reference like C45, R56
* @param aMulti is the unit selection used for symbols with multiple units per package.
*/
void AddHierarchicalReference( const wxString& aPath,
const wxString& aRef,
@ -495,29 +526,37 @@ public:
void GetEndPoints( std::vector<DANGLING_END_ITEM>& aItemList ) override;
/**
* Test if the component's dangling state has changed for one given pin index. As
* a side effect, actually update the dangling status for that pin.
* Test if the symbol's dangling state has changed for one given pin index.
*
* @param aItemList - list of all DANGLING_END_ITEMs to be tested
* @param aLibPins - list of all the LIB_PIN items in this component's symbol
* @param aPin - index into aLibPins that identifies the pin to test
* As a side effect, the actually updates the dangling status for that pin.
*
* @param aItemList is list of all #DANGLING_END_ITEMs to be tested.
* @param aLibPins is list of all the #LIB_PIN items in this symbol
* @param aPin is the index into \a aLibPins that identifies the pin to test
* @return true if the pin's state has changed.
*/
bool IsPinDanglingStateChanged( std::vector<DANGLING_END_ITEM>& aItemList,
LIB_PINS& aLibPins, unsigned aPin );
/**
* Test if the component's dangling state has changed for all pins. As a side
* effect, actually update the dangling status for all pins (does not short-circuit).
* Test if the component's dangling state has changed for all pins.
*
* As a side effect, actually update the dangling status for all pins.
*
* @note This does not test for short circuits.
*
* @param aItemList is list of all #DANGLING_END_ITEMs to be tested.
*
* @param aItemList - list of all DANGLING_END_ITEMs to be tested
* @return true if any pin's state has changed.
*/
bool IsDanglingStateChanged( std::vector<DANGLING_END_ITEM>& aItemList ) override;
/**
* Return whether any pin has dangling status. Does NOT update the internal status,
* only checks the existing status.
* Return whether any pin in this symbol is dangling.
*
* @note This does not update the internal status. It only checks the existing status.
*
* @return true if any pins of this symbol are not connect otherwise false.
*/
bool IsDangling() const override;
@ -539,12 +578,12 @@ public:
SEARCH_RESULT Visit( INSPECTOR inspector, void* testData, const KICAD_T scanTypes[] ) override;
/**
* Function GetDrawItem().
* Return the component library item at \a aPosition that is part of this component.
*
* @param aPosition - Schematic position of the component library object.
* @param aType - Type of component library object to find or any if set to TYPE_NOT_INIT.
* @return A pointer to the component library object if found, otherwise NULL.
* @param aPosition is the schematic position of the component library object.
* @param aType is the type of symbol library object to find or any if set to TYPE_NOT_INIT.
*
* @return is the symbol library object if found otherwise NULL.
*/
LIB_ITEM* GetDrawItem( const wxPoint& aPosition, KICAD_T aType = TYPE_NOT_INIT );

107
eeschema/symbol_lib_table.h
View File

@ -31,10 +31,8 @@
class LIB_PART;
/**
* Class SYMBOL_LIB_TABLE_ROW
*
* holds a record identifying a library accessed by the appropriate footprint library #PLUGIN
* object in the #SYMBOL_LIB_TABLE.
* Hold a record identifying a symbol library accessed by the appropriate symbol library
* #SCH_PLUGIN object in the #SYMBOL_LIB_TABLE.
*/
class SYMBOL_LIB_TABLE_ROW : public LIB_TABLE_ROW
{
@ -61,16 +59,12 @@ public:
bool operator!=( const SYMBOL_LIB_TABLE_ROW& aRow ) const { return !( *this == aRow ); }
/**
* Function GetType
*
* returns the type of symbol library table represented by this row.
* Return the type of symbol library table represented by this row.
*/
const wxString GetType() const override { return SCH_IO_MGR::ShowType( type ); }
/**
* Function SetType
*
* changes the type represented by this row.
* Change the schematic plugin type represented by this row.
*/
void SetType( const wxString& aType ) override;
@ -107,9 +101,7 @@ public:
virtual void Format( OUTPUTFORMATTER* aOutput, int aIndentLevel ) const override;
/**
* Constructor SYMBOL_LIB_TABLE
*
* builds a footprint library table by pre-pending this table fragment in front of
* Build a symbol 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 SYMBOL_LIB_TABLE which is searched only when
@ -119,11 +111,15 @@ public:
SYMBOL_LIB_TABLE( SYMBOL_LIB_TABLE* aFallBackTable = NULL );
/**
* Function FindRow
* Return an SYMBOL_LIB_TABLE_ROW if \a aNickName is found in this table or in any chained
* fallBack table fragment.
*
* returns an SYMBOL_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 #SYMBOL_LIB_TABLE_ROW if not already loaded.
* The #SCH_PLUGIN is loaded and attached to the "plugin" fieldf the #SYMBOL_LIB_TABLE_ROW if
* not already loaded.
*
* @param aNickName is the name of the row to find.
*
* @return the row found or NULL if \a aNickName was not found.
*
* @throw IO_ERROR if \a aNickName cannot be found.
*/
@ -132,9 +128,7 @@ public:
//-----<PLUGIN API SUBSET, REBASED ON aNickname>---------------------------
/**
* Function EnumerateSymbolLib
*
* returns a list of symbol alias names contained within the library given by @a aNickname.
* Return a list of symbol alias names contained within the library given by @a aNickname.
*
* @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW.
* @param aAliasNames is a reference to an array for the alias names
@ -144,26 +138,27 @@ public:
void EnumerateSymbolLib( const wxString& aNickname, wxArrayString& aAliasNames );
/**
* Function LoadSymbol
* Load a #LIB_ALIAS having @a aAliasName from the library given by @a aNickname.
*
* loads a #LIB_ALIAS having @a aAliasName from the library given by @a aNickname.
* The actual symbol can be retreaved from the LIB_ALIAS::GetPart() method.
*
* @param aNickname is a locator for the "library", it is a "name" in #LIB_TABLE_ROW
*
* @param aAliasName is the name of the #LIB_ALIAS to load.
*
* @return LIB_ALIAS* - if found we own it, else NULL if not found.
* @return the symbol alias if found or NULL if not found.
*
* @throw IO_ERROR if the library cannot be found or read. No exception
* is thrown in the case where aAliasName cannot be found.
*/
LIB_ALIAS* LoadSymbol( const wxString& aNickname, const wxString& aAliasName );
LIB_ALIAS* LoadSymbol( const LIB_ID& aLibId )
{
return LoadSymbol( aLibId.GetLibNickname(), aLibId.GetLibItemName() );
}
/**
* Enum SAVE_T
*
* is the set of return values from SaveSymbol() below.
* The set of return values from SaveSymbol() below.
*/
enum SAVE_T
{
@ -172,33 +167,28 @@ public:
};
/**
* Function SaveSymbol
* Write @a aSymbol to an existing library given by @a aNickname.
*
* will write @a aSymbol to an existing library given by @a aNickname. If a #LIB_PART
* by the same name already exists or there are any conflicting alias names, the new
* #LIB_PART will silently overwrite any existing aliases and/or part becaue libraries
* cannot have duplicate alias names. It is the responsibility of the caller to check
* the library for conflicts before saving.
* If a #LIB_PART by the same name already exists or there are any conflicting alias
* names, the new #LIB_PART will silently overwrite any existing aliases and/or part
* becaue libraries cannot have duplicate alias names. It is the responsibility of
* the caller to check the library for conflicts before saving.
*
* @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW
*
* @param aSymbol is what to store in the library. The library owns the symbol after this
* call.
*
* @param aOverwrite when true means overwrite any existing symbol 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.
*
* @throw IO_ERROR if there is a problem saving.
* @throw IO_ERROR if there is a problem saving the symbol.
*/
SAVE_T SaveSymbol( const wxString& aNickname, const LIB_PART* aSymbol,
bool aOverwrite = true );
/**
* Function DeleteSymbol
*
* deletes the @a aSymbolName from the library given by @a aNickname.
* Deletes the @a aSymbolName from the library given by @a aNickname.
*
* @param aNickname is a locator for the "library", it is a "name" in LIB_TABLE_ROW.
*
@ -209,9 +199,7 @@ public:
void DeleteSymbol( const wxString& aNickname, const wxString& aSymbolName );
/**
* Function DeleteAlias
*
* deletes @a aAliasName from the library at @a aLibraryPath.
* Delete @a aAliasName from the library at @a aLibraryPath.
*
* If @a aAliasName refers the the root #LIB_PART object, the part is renamed to
* the next or previous #LIB_ALIAS in the #LIB_PART if one exists. If the #LIB_ALIAS
@ -227,10 +215,12 @@ public:
void DeleteAlias( const wxString& aNickname, const wxString& aAliasName );
/**
* Function IsSymbolLibWritable
* 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.)
* It is possible that some symbols libraries are read only because of where they are
* installed.
*
* @param aNickname is the library nickname in the symbol library table.
*
* @throw IO_ERROR if no library at @a aNickname exists.
*/
@ -243,49 +233,48 @@ public:
//-----</PLUGIN API SUBSET, REBASED ON aNickname>---------------------------
/**
* Function LoadSymboldWithOptionalNickname
* loads a #LIB_PART having @a aFootprintId with possibly an empty librarynickname.
* Load a #LIB_PART having @a aFootprintId with possibly an empty library nickname.
*
* @param aId the library nickname and name of the symbol to load.
*
* @return LIB_PART* - if found the library owns it, else NULL if not found.
* @return the library symbol if found (the library owns it) or NULL if not found.
*
* @throw IO_ERROR if the library cannot be found or read. No exception
* is thrown in the case where aId cannot be found.
* @throw PARSE_ERROR if @a atId is not parsed OK.
* @throw PARSE_ERROR if @a aId is not parsed OK.
*/
LIB_ALIAS* LoadSymbolWithOptionalNickname( const LIB_ID& aId );
/**
* Function LoadGlobalTable
*
* loads the global symbol library table into \a aTable.
* Load the global symbol 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
* time being.
*
* @param aTable the #SYMBOL_LIB_TABLE object to load.
*
* @return true if the global library table exists and is loaded properly.
*
* @throw IO_ERROR if an error occurs attempting to load the symbol library table.
*/
static bool LoadGlobalTable( SYMBOL_LIB_TABLE& aTable );
/**
* Function GetGlobalTableFileName
*
* Fetch the global symbol library table file name.
*
* @return the platform specific global symbol 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 symbol libraries.
*
* returns the name of the environment variable used to hold the directory of locally
* installed "KiCad sponsored" system symbol libraries. These can be either legacy
* or sweet 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 sweet 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();