Suggestions for changes in behaviors of symbol browser (derived symbols)

[Steve Bollinger]

short title:

Symbol Editor: I don't think making a new derived symbol works the way it should.

Summary of issues:

1. If you make a derived symbol from an existing symbol the VALUE field will generally be the one from the symbol you are deriving from (parent symbol). It should be the same as the name of the new symbol.

2. A new derived symbol has blank FOOTPRINT and DATASHEET fields. FOOTPRINT should be copied over. Maybe DATASHEET too.

3. If you double-click a symbol to look at it to confirm it is the right one then select "new symbol" you get an error saying "No symbol library selected." It should instead offer to make a symbol in the library of the symbol you are viewing.

Long-winded reasoning and arguments:

1. While there are other conventions for drawing symbols the typical way of doing it should be probably be considered to be the way that the KiCAD library conventions describes. And convention S6.2 item 2 says: 'Value field contains the name of the symbol and is visible'. Contains here is not defined but seems from the other rules to mean "has the value of" instead of "has a value which includes the substring of". Hence we should expect the value field to be the same as the name of the symbol you are creating. If using the new derived symbol functionality currently the value field will likely be the same as the name of the parent symbol, not the symbol you are creating. And in fact I made this error multiple times when creating new symbols for the KiCAD library. The checker script found the errors for me.

The existing implementation does this to set the VALUE field in the new symbol:

    case VALUE_FIELD:
        if( parent->IsPower() )
            field->SetText( name );
        break;

So only for power symbols does the derived symbol take the new name. I suggest that the field should always be set to the new name. Another alternative is to set the VALUE field to the new name if the VALUE field is currently set to the name of the parent symbol.

2. The existing implementation includes this argument for these fields:

    case FOOTPRINT_FIELD:
    case DATASHEET_FIELD:
        // - footprint might be the same as parent, but might not
        // - datasheet is most likely different
        // - probably best to play it safe and copy neither
        field->SetText( wxEmptyString );
        break;

When considering this it is important to note that the pins values cannot differ for the derived symbol. The symbol itself is not editable and the "Pin Table..." button in the editor is greyed out. A message even comes up indicating the symbol is not editable and suggests opening the parent. Given this the pins mappings must be identical in the derived symbol. This does not mean the footprint must be the same. However I indicate that this means that the footprint is most likely to be the same. In fact a major reason to copy symbols instead of deriving from them is to change the pin mappings and footprint. I therefore suggest that the FOOTPRINT field should be set the same as the parent symbol.

Whether the DATASHEET should be identical is a bit less obvious. I can say it would have saved me a lot of time when making symbol libraries if it was identical. The only strong reason I can think to erase it is so that the creator of the new symbol does not forget. And given that there is no real good reason to leave this blank (the guidelines suggest a value of "~" for generic symbols) I don't see a lot of value in a blank field. However I leave this up to others to argue more about as I don't feel strongly about this.

3. This issue arises because when you double-click a symbol it becomes unselected in the browser list. It is selected on the first click and unselected on the second. It no longer is drawn in the highlight color but instead now has a box around it. If you double-click and then single click and then select "new symbol" it works fine. I can see no reason that double-clicking a symbol should leave you with no symbol (nor library) selected. I propose that double-clicking should leave the displayed symbol selected. This will change the behavior of selecting copy after double-clicking, as currently selecting copy does nothing since nothing is selected. Also deleting the currently displayed symbol will operate differently, as it is not possible to delete the currently displayed symbol without selecting it again.

Another possibility would be to leave this behavior as it currently is. It is something you can "work around" once you see it. It's just that it feels unnatural.

I am willing to do the work on this change, I am looking essentially for some behavioral "rulings" from those who define such things. How do the project leaders feel this should work?

[Steve Bollinger]

For number 1 I realized that renaming a symbol changes the VALUE field. So I decided to see how that is implemented. And while looking I found that also saving a copy of a symbol (saveSymbolCopyAs) changes the VALUE field if it was previously the same as the name of the symbol. This is not my favorite way to do it but I think given it works that way I think that deriving a symbol should work the same way.

    wxString symbolName = old_lib_id.GetLibItemName();
    [..]
    bool valueFollowsName = symbol->GetValueField().GetText() == symbolName;
    [..]
    if( valueFollowsName )
        new_symbol.GetValueField().SetText( symbolName );

Similar code is in void SYMBOL_EDIT_FRAME::UpdateAfterSymbolProperties( wxString* aOldName ) which I believe is what is used when renaming symbol.

So I think that pretty much nails down what 1. should do.

I have no updates on 2 or 3.

[Steve Bollinger]

I'm trying to pretend I'm not working on this as much as I am. But with some looking I have determined that 3 likely stems from a difference in behavior since 7.X which also shows in other ways. The item should not be becoming unselected. And it does not in 7.X. I have a better characterization of the problem which I will write up as an issue because while I can tell what is happening I cannot understand what is causing it and someone who knows wxWidgets even a little probably can move forward on  the issue 50x faster than me.

So I am retiring number 3 from this post/email. This leaves really agreements/clarifications on my proposed number 1 and 2 behaviors before I can start to consider submitting changes.