diff --git a/eeschema/sch_component.cpp b/eeschema/sch_component.cpp index 8f249c915c..d226598dbc 100644 --- a/eeschema/sch_component.cpp +++ b/eeschema/sch_component.cpp @@ -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 cmp_list; + + for( int i = 0; i < aComponents.GetCount(); ++i ) + { + SCH_COMPONENT* cmp = dynamic_cast( 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; diff --git a/eeschema/sch_component.h b/eeschema/sch_component.h index 5091c0d332..6c16b0a092 100644 --- a/eeschema/sch_component.h +++ b/eeschema/sch_component.h @@ -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,84 +309,93 @@ public: //---------------------------------------------------------------- /** - * 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& 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 - * component. This can be NULL when aManual is false. - * @param aManual - True if the autoplace was manually initiated (e.g. by a hotkey + * + * @param aScreen is the SCH_SCREEN associated with the current instance of the + * component. This can be NULL when aManual is false. + * @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 - * component. + * 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& 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 (/<sheet timestamp>/<component + * Add a full hierarchical reference to this symbol. + * + * @param aPath is the hierarchical path (/<sheet timestamp>/<component * timestamp> 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& 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& 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& 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 ); diff --git a/eeschema/symbol_lib_table.h b/eeschema/symbol_lib_table.h index 4d1a4bf57a..e64ca7281e 100644 --- a/eeschema/symbol_lib_table.h +++ b/eeschema/symbol_lib_table.h @@ -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: //-------------------------------- /** - * 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. + * @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: //-------------------------------- /** - * 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. + * @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 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 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, if 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, if it is not set already in the environment. */ static const wxString GlobalPathEnvVariableName();