## Trace an action

Here is a short introduction where to start if you want to trace an action down into the source code: Lets draw a line in the (GTK) GUI.

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 `F2`. 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.

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.

### F2 key

First let's trace the LINE mode selecting by pressing `F2`.

In the file gpcb-menu.res we look for our `F2` key and we find

    {"Line" checked=linemode,1 Mode(Line) a={"F2" "<Key>F2"}}

In the file action.c we find

    HID_Action action_action_list[] {"Mode", 0, ActionMode, mode_help, mode_syntax}

The action_action_list defines that the Mode event is translated into the ActionMode function. So the function called when we press `F2` is `ActionMode(Line)`.

ActionMode is a generic function and therefore it will need to find what to do.

    ActionMode (int argc, char **argv, Coord x, Coord y)

It will do that by calling `GetFunctionID (AGV[0])` in this example AGV[0] = Line. The function ID will tell it to do the function `SetMode (LINE_MODE);`

That function will set the variable Settings.Mode to LINE_MODE

devel_intro:set_mode.png

### Mouse click

Next we trace down what will happen if we left click the mouse button to start drawing a track.
Please note this is a very simplified call graph.

devel_intro:draw_line.png

In the file gpcb-menu.res Left mouse click Mouse = Left => points to Mode(Notify)

[*1] Mode(Notify)

Mode translates in the action_action_list into _ActionMode_

[*2] Left mouse click translates into calling function ActionMode(Notify)

[*3] The program will go back and forth between NotifyMode and NotifyLine until [*4].
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.

[*4]if two points are selected we can create a line

[*5] We need to free memory-space and add our new Line into the linked list. This is done through the GLIB Library. Next our newly created LINE object is filled with the relevant data. Basically we are done, the line is added to the data structure. However there is one more thing to do.

[*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.

This is in a very simplified description on what happens and the path the software takes to draw a line.