Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
gattrib: removed interfering "\mainpage" tag and added to "what-is-ga…
…ttrib" page. Signed-off-by: Bert Timmerman <bert.timmerman@xs4all.nl>
- Loading branch information
Showing
with
86 additions
and 81 deletions.
- +84 −2 gattrib/docs/what-is-gattrib.html
- +2 −79 gattrib/src/gattrib.c
| @@ -1,5 +1,87 @@ | ||
| <body> | ||
| What is gAttrib? | ||
| <p/> | ||
| gattrib is the attribute editor for gschem, the schematic capture program/tool which is part of gEDA. gattrib's sole purpose is to facilitate the editing of attributes of components. | ||
| <p> | ||
| gattrib is the attribute editor for gschem, the schematic capture program/tool | ||
| which is part of gEDA. gattrib's sole purpose is to facilitate the editing of | ||
| attributes of components. | ||
| <p> | ||
| <h3>sdb_notes SDB's original comment in gattrib.c</h3> | ||
| In the spirit of open source/free software, major sections of gattrib's code | ||
| were borrowed from other sources, and hacked together by SDB in Dec. 2003.<br> | ||
| Particularly rich sources for code were gEDA/gnetlist, and the gtkextra program | ||
| testgtksheet.c.<br> | ||
| <br> | ||
| Thanks to their authors for providing the foundation upon which this is built.<br> | ||
| Of course, I <b>*did*</b> write major portions of the code too . . . . .<br> | ||
| Some documentation about the internal operation of this program can be found in | ||
| the "NOTES" file in the gattrib top-level directory.<br> | ||
| -- SDB December 2003 --<br> | ||
| <br> | ||
| <h3>Architecture</h3> | ||
| Extracted from SDB's mailing list posting: | ||
| <a href="http://osdir.com/ml/cad.geda.devel/2007-06/msg00282.html"> | ||
| http://osdir.com/ml/cad.geda.devel/2007-06/msg00282.html</a> | ||
| - believed to still be relevant.<br> | ||
| <p> | ||
| gattrib has three major components:<br> | ||
| <ul> | ||
| <li>It manipulates objects held in the TOPLEVEL data structure.<br> | ||
| It does this by importing structs and functions from libgeda. | ||
| <li>Gattrib defines its own layer of structs, notably SHEET_DATA, which holds a | ||
| table of attrib name=value pairs, and also holds a couple of linked lists | ||
| corresponding to all component's refdeses, and to all attribute names found | ||
| in the design.<br> | ||
| This stuff is native to gattrib. | ||
| <li>Gattrib uses a spreadsheet widget called GtkSheet.<br> | ||
| This stuff came from the GtkExtra project, which at one time offered a bunch | ||
| of interesting widgets for graphing and visualization.<br> | ||
| I think they're still around; you can do a Google search for them.<br> | ||
| I stole the two .h files defining the spreadsheet widgets, and also stole | ||
| code from the program itself to implement the run-time functions which deal | ||
| with the spreadsheet. | ||
| </ul> | ||
| </p> | ||
| <p> | ||
| When run, gattrib does this:<br> | ||
| <ul> | ||
| <li>It uses libgeda functions to read in your design, and fill up the TOPLEVEL | ||
| struct. | ||
| <li>It then loops over everything in TOPLEVEL and fills out the refdes list and | ||
| the attribute name list. It sticks these into a STRING_LIST which is | ||
| associated with the SHEET_DATA struct. | ||
| <li>Then, knowing all the refdeses and all the attribute names, it creates a | ||
| TABLE data struct (a member of SHEET_DATA), and loops over each cell in the | ||
| TABLE.<br> | ||
| For each cell, it queries TOPLEVEL for the corresponding name=value pair, | ||
| and sticks the value in the TABLE. | ||
| <li>When done with that, it then creates a GtkSheet and populates it by looping | ||
| over TABLE. | ||
| <li>Then it turns over control to the user, who can manipulate the GtkSheet.<br> | ||
| As the user adds and deletes values from the GtkSheet, the values are stored | ||
| locally there.<br> | ||
| The GtkSheet is the master repository of all attributes at that point; the | ||
| other data structures are not updated. | ||
| </ul> | ||
| Saving out a design is similar, except the process runs in reverse:<br> | ||
| <ul> | ||
| <li>The program loops over all cells in GtkSheet, and sticks the values found | ||
| into SHEET_DATA.<br> | ||
| Handling issues like added/deleted columns happens first at the GtkSheet, | ||
| and then to SHEET_DATA and TOPLEVEL.<br> | ||
| I've kind of forgotten how I implemented these feaures, however. :-S | ||
| <li>Then, the program loops over the cells in SHEET_DATA, and updates the | ||
| attributes in TOPLEVEL using functions from libgeda, as well as by reaching | ||
| directly into the TOPLEVEL data structure (a software engineering no-no).<br> | ||
| If a previously existing attrib has been removed, then it is removed from | ||
| TOPLEVEL.<br> | ||
| If a new attrib has been attached to a component, then it is added to | ||
| TOPLEVEL. | ||
| <li>Then the design is saved out using the save function from libgeda. | ||
| </ul> | ||
| <p> | ||
| Therefore, think of SHEET_DATA and the other gattrib data structures as a thin | ||
| layer between GtkSheet and TOPLEVEL.<br> | ||
| The gattrib data structures are used basically for convenience while trying to | ||
| build or update either of the two other, more important data structures. | ||
| </p> | ||
| </body> |