docs/wiki/geda-pcb_action_traces.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h2 id="traceanaction">Trace an action</h2>
  14 <div class="level2">
  15
  16 <p>
  17 Here is a short introduction where to start if you want to trace an action down into the source code:
  18 Lets draw a line in the (GTK) GUI.
  19 </p>
  20
  21 <p>
  22 If we start pcb the default mode is the select mode, in order to draw a trace we need to switch to the LINE mode. We do that by pressing <kbd>F2</kbd>. Next we use the mouse to select a starting point and do a left click of the mouse button. Now we can start drawing a trace.
  23 </p>
  24
  25 <p>
  26 So what happens in the source code? PCB uses a flexible way of implementing menu structures and it uses a flexible way to implement actions the program should do. All this flexibility made it a bit difficult for me to see where to start.
  27 </p>
  28
  29 </div>
  30
  31 <h3 id="f2key">F2 key</h3>
  32 <div class="level3">
  33
  34 <p>
  35 First let&#039;s trace the LINE mode selecting by pressing <kbd>F2</kbd>.
  36 </p>
  37
  38 <p>
  39 In the file <em><strong>gpcb-menu.res</strong></em> we look for our <kbd>F2</kbd> key and we find
  40 </p>
  41 <pre class="code">{&quot;Line&quot; checked=linemode,1 Mode(Line) a={&quot;F2&quot; &quot;&lt;Key&gt;F2&quot;}}</pre>
  42
  43 <p>
  44 In the file <em><strong>action.c</strong></em> we find
  45 </p>
  46 <pre class="code">HID_Action action_action_list[] {&quot;Mode&quot;, 0, ActionMode, mode_help, mode_syntax}</pre>
  47
  48 <p>
  49 The action_action_list defines that the <strong>Mode</strong> event is translated into the <em class="u">ActionMode</em> function. So the function called when we press <kbd>F2</kbd> is <code>ActionMode(Line)</code>.
  50 </p>
  51
  52 <p>
  53 ActionMode is a generic function and therefore it will need to find what to do.
  54 </p>
  55 <pre class="code c">ActionMode <span class="br0">&#40;</span><span class="kw4">int</span> argc<span class="sy0">,</span> <span class="kw4">char</span> <span class="sy0">**</span>argv<span class="sy0">,</span> Coord x<span class="sy0">,</span> Coord y<span class="br0">&#41;</span></pre>
  56
  57 <p>
  58 It will do that by calling <code>GetFunctionID (AGV[0])</code> in this example AGV[0] = Line. The function ID will tell it to do the function <code>SetMode (LINE_MODE);</code>
  59 </p>
  60
  61 <p>
  62 That function will set the variable <strong>Settings.Mode</strong> to LINE_MODE
  63 </p>
  64
  65 <p>
  66 <a href="media/devel_intro/set_mode.png" class="media" target="_blank" title="devel_intro:set_mode.png">devel_intro:set_mode.png</a>
  67 </p>
  68
  69 </div>
  70
  71 <h3 id="mouseclick">Mouse click</h3>
  72 <div class="level3">
  73
  74 <p>
  75 Next we trace down what will happen if we left click the mouse button to start drawing a track.<br/>
  76 Please note this is a very simplified call graph.
  77 </p>
  78
  79 <p>
  80 <a href="media/devel_intro/draw_line.png" class="media" target="_blank" title="devel_intro:draw_line.png">devel_intro:draw_line.png</a>
  81 </p>
  82
  83 <p>
  84 In the file <em><strong>gpcb-menu.res</strong></em> Left mouse click Mouse = Left =&gt; points to Mode(Notify)
  85 </p>
  86
  87 <p>
  88 [*1] Mode(Notify)
  89 </p>
  90
  91 <p>
  92 <strong>Mode</strong> translates in the action_action_list into _ActionMode_
  93 </p>
  94
  95 <p>
  96 [*2] Left mouse click translates into calling function ActionMode(Notify)
  97 </p>
  98
  99 <p>
 100 [*3] The program will go back and forth between NotifyMode and NotifyLine until [*4].<br/>
 101
 102 In the function NotifyLine all the dynamic processing is done, meaning that here the limitations and restrictions are check realtime. e.g. if the Auto force DRC check flag is checked, this function checks if we try to draw over existing copper.
 103 </p>
 104
 105 <p>
 106 [*4]if two points are selected we can create a line
 107 </p>
 108
 109 <p>
 110 [*5] We need to free memory-space and add our new Line into the linked list. This is done through the GLIB Library.
 111 Next our newly created LINE object is filled with the relevant data.
 112 Basically we are done, the line is added to the data structure. However there is one more thing to do.
 113 </p>
 114
 115 <p>
 116 [*6] Our new line is stored into the main PCBType data structure (actually in the DataType sub structure). Now there is one more administrative task to do, the newly created line must be add to the rtree data structure. Every item that is added to the data structure is also added to the rtree data structure. The R-TREE data structure makes it easy to search for free or occupied areas on a layer.
 117 </p>
 118
 119 <p>
 120 This is in a very simplified description on what happens and the path the software takes to draw a line.
 121 </p>
 122
 123 </div>
 124 </body>
 125 </html>