gEDA Project Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
As an exercise let's do something easy, like adding an action to PCB.

Before you start coding take a look at: [[pcb_developer_introduction#Build system|Build system]]
It is essential that you have a working build system.

When working on the source code of PCB then please make use of lots and lots of comments (preferably doxygen style). In trying to understand the code I was very grateful for every piece of comment the developer had written.

First make a file called //**example.c**// and add:

<code c>
/*!
 * =====================================================================================
 *
 *                                      COPYRIGHT
 *  Example action implementation for PCB.
 *  Copyright (C) 2015 Robert Zeegers
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; either version 2
 *  of the License, or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 *
 *  \File:   example.c
 *  \Brief:  Example on how to implement a action in the PCB program.
 *  \par Description
 *   Example action implementation for PCB, interactive printed circuit board design
 *  \copyright (C) 2015 Robert Zeegers
 *
 *  \Version:  1.0
 *  Created:  24/07/15
 *
 *  \Todo:     nothing
 *  \Bug:      not that I know of
 *
 * =====================================================================================
 */

/* First thing todo is include global.h  */
/* This will automatically also include const.h and macro.h */
#include "global.h"

/* Second we include hid.h because we want to register our action to the HID */
#include "hid.h"

/* We are going to add an action and therefore we want it to show-up in the PCB manual, */
/* so we add some documentation comments */
/* For the documentation style see the "extract-docs" perl script in the doc directory */

/* %start-doc actions DoSilly
   This function doesn't do anything useful.

   @example
   DoSilly()
   @end example

   %end-doc */

/* All action entry functions must have the same syntax as defined in */
/* typedef struct HID_Action (hid.h)  */
static int
ExampleDo (int argc, char **argv, int x, int y)
{
    /* It should do something, so let's do something silly */
    /* Let's write a Dutch songtext to the Message Log window */
    /* The struct HID is defined in hid.h */
    /* and the variable gui is made available there by "extern HID *gui;" */
    /* First we check if we have a gui. */
    if( 1 == gui->gui )
    {
        /*  if we have one let's write the songtext */
        gui->log (_("Iedereen is van de wereld en de wereld is van iedereen!\n"));
    }
}

/* Now we have to make an action list. */
/* Here we make the connection between our command "DoSilly()" and */
/* the actual function which should be executed ExampleDo().*/
static HID_Action exampledo_action_list[] = {
  {"DoSilly", "Example action", ExampleDo, "Always provide some help", "DoSilly()"}
};

/* Next a macro to register the action in the HID */
/* Note the missing ; at the end, that's correct ;-) */
REGISTER_ACTIONS (exampledo_action_list)

</code>

For an explanation on the ''REGISTER_ACTION'' macro see paragraph [[pcb_developer_introduction#REGISTER|REGISTER]].

Next we need to add our file to the build system.\\
We do that in the file //**MakeFile.am**//.\\ Open //**MakeFile.am**// and look for the variable __PCB_SRCS__ and add the file //**example.c**// there like the others.

Clean your build directory by doing:
  make distclean
Then do:
  ./autogen.sh
Now our file is in //**MakeFile.in**//

Next do:
  ./configure
  make
Run:
  src/pcb

In the PCB program type ":DoSilly()" and watch the message log window.

And do check out the pcb manual in doc/pcb.pdf search for "DoSilly"
gEDA Project Wiki

User Tools

Site Tools

Page Tools
