gattrib/docs/what-is-gattrib.html

   1 <body>
   2   What is gAttrib?
   3 <p>
   4 gattrib is the attribute editor for gschem, the schematic capture program/tool
   5 which is part of gEDA. gattrib's sole purpose is to facilitate the editing of
   6 attributes of components.
   7 <p>
   8 <h3>sdb_notes SDB's original comment in gattrib.c</h3>
   9 In the spirit of open source/free software, major sections of gattrib's code
  10 were borrowed from other sources, and hacked together by SDB in Dec. 2003.<br>
  11 Particularly rich sources for code were gEDA/gnetlist, and the gtkextra program
  12 testgtksheet.c.<br>
  13 <br>
  14 Thanks to their authors for providing the foundation upon which this is built.<br>
  15 Of course, I <b>*did*</b> write major portions of the code too . . . . .<br>
  16 Some documentation about the internal operation of this program can be found in
  17 the "NOTES" file  in the gattrib top-level directory.<br>
  18 -- SDB  December 2003 --<br>
  19 <br>
  20 <h3>Architecture</h3>
  21 Extracted from SDB's mailing list posting:
  22 <a href="http://osdir.com/ml/cad.geda.devel/2007-06/msg00282.html">
  23 http://osdir.com/ml/cad.geda.devel/2007-06/msg00282.html</a>
  24 - believed to still be relevant.<br>
  25 <p>
  26 gattrib has three major components:<br>
  27 <ul>
  28 <li>It manipulates objects held in the TOPLEVEL data structure.<br>
  29     It does this by importing structs and functions from libgeda.
  30 <li>Gattrib defines its own layer of structs, notably SHEET_DATA, which holds a
  31     table of attrib name=value pairs, and also holds a couple of linked lists
  32     corresponding to all component's refdeses, and to all attribute names found
  33     in the design.<br>
  34     This stuff is native to gattrib.
  35 <li>Gattrib uses a spreadsheet widget called GtkSheet.<br>
  36     This stuff came from the GtkExtra project, which at one time offered a bunch
  37     of interesting widgets for graphing and visualization.<br>
  38     I think they're still around; you can do a Google search for them.<br>
  39     I stole the two .h files defining the spreadsheet widgets, and also stole
  40     code from the program itself to implement the run-time functions which deal
  41     with the spreadsheet.
  42 </ul>
  43 </p>
  44 <p>
  45 When run, gattrib does this:<br>
  46 <ul>
  47 <li>It uses libgeda functions to read in your design, and fill up the TOPLEVEL
  48     struct.
  49 <li>It then loops over everything in TOPLEVEL and fills out the refdes list and
  50     the attribute name list. It sticks these into a STRING_LIST which is
  51     associated with the SHEET_DATA struct.
  52 <li>Then, knowing all the refdeses and all the attribute names, it creates a
  53     TABLE data struct (a member of SHEET_DATA), and loops over each cell in the
  54     TABLE.<br>
  55     For each cell, it queries TOPLEVEL for the corresponding name=value pair,
  56     and sticks the value in the TABLE.
  57 <li>When done with that, it then creates a GtkSheet and populates it by looping
  58     over TABLE.
  59 <li>Then it turns over control to the user, who can manipulate the GtkSheet.<br>
  60     As the user adds and deletes values from the GtkSheet, the values are stored
  61     locally there.<br>
  62     The GtkSheet is the master repository of all attributes at that point; the
  63     other data structures are not updated.
  64 </ul>
  65     Saving out a design is similar, except the process runs in reverse:<br>
  66 <ul>
  67 <li>The program loops over all cells in GtkSheet, and sticks the values found
  68     into SHEET_DATA.<br>
  69     Handling issues like added/deleted columns happens first at the GtkSheet,
  70     and then to SHEET_DATA and TOPLEVEL.<br>
  71     I've kind of forgotten how I implemented these feaures, however. :-S
  72 <li>Then, the program loops over the cells in SHEET_DATA, and updates the
  73     attributes in TOPLEVEL using functions from libgeda, as well as by reaching
  74     directly into the TOPLEVEL data structure (a software engineering no-no).<br>
  75     If a previously existing attrib has been removed, then it is removed from
  76     TOPLEVEL.<br>
  77     If a new attrib has been attached to a component, then it is added to
  78     TOPLEVEL.
  79 <li>Then the design is saved out using the save function from libgeda.
  80 </ul>
  81 <p>
  82 Therefore, think of SHEET_DATA and the other gattrib data structures as a thin
  83 layer between GtkSheet and TOPLEVEL.<br>
  84 The gattrib data structures are used basically for convenience while trying to
  85 build or update either of the two other, more important data structures.
  86 </p>
  87 </body>