code cleanup and comments

pcbnew/class_footprint_wizard.cpp

@@ -47,18 +47,6 @@ void FOOTPRINT_WIZARDS::register_wizard(FOOTPRINT_WIZARD *aWizard)
     
     printf("Registered footprint wizard '%s'\n",(const char*)name.mb_str() );
     
-#if 0 
-    /* just to test if it works correctly */
-    int pages = fw->GetNumParameterPages();
-    printf("             %d pages\n",pages);
-    
-    for (int n=0; n<pages; n++)
-    {
-        printf("                      page %d->'%s'\n",n,
-            (const char*)fw->GetParameterPageName(n).mb_str());
-    }
-#endif    
-    
     
 }
 

pcbnew/class_footprint_wizard.h

@@ -16,16 +16,80 @@ class FOOTPRINT_WIZARD
 public:
     FOOTPRINT_WIZARD() {}
     ~FOOTPRINT_WIZARD() {}
+    
+    /** 
+     * Function GetName
+     * @return the name of the wizard
+     */
     virtual wxString      GetName()=0;
+    
+    /**
+     * Function GetImage
+     * @return an svg image of the wizard to be rendered
+     */
     virtual wxString      GetImage()=0;  
+    
+    /**
+     * Function GetDescription
+     * @return a description of the footprint wizard 
+     */
     virtual wxString      GetDescription()=0;
+    
+    /** 
+     * Function GetNumParameterPages
+     * @return the number of parameter pages that this wizard will show to the user
+     */
     virtual int           GetNumParameterPages()=0;
+    
+    /**
+     * Function GetParameterPageName
+     * @param aPage is the page we want the name of
+     * @return a string with the page name
+     */
     virtual wxString      GetParameterPageName(int aPage)=0;
+    
+    /**
+     * Function GetParameterNames
+     * @param aPage is the page we want the parameter names of
+     * @return an array string with the parameter names on a certain page 
+     */
     virtual wxArrayString GetParameterNames(int aPage)=0;
+    
+    /**
+     * Function GetParameterValues
+     * @param aPage is the page we want the parameter values of
+     * @return an array of parameter values
+     */
     virtual wxArrayString GetParameterValues(int aPage)=0;
+    
+    /**
+     * Function GetParameterErrors
+     * @param aPAge is the page we want to know the errors of
+     * @return an array of errors (if any) for the parameters, empty strings for OK parameters
+     */
     virtual wxArrayString GetParameterErrors(int aPage)=0;
+    
+    /**
+     * Function SetParameterValues
+     * @param aPage is the page we want to set the parameters in
+     * @param aValues are the values we want to set into the parameters
+     * @return an array of parameter values
+     */
     virtual wxString      SetParameterValues(int aPage,wxArrayString& aValues)=0;
+    
+    /** 
+     * Function GetModule
+     * This method builds the module itself and returns it to the caller function 
+     * @return  PCB module built from the parameters given to the class
+     */
     virtual MODULE       *GetModule()=0;
+    
+    /**
+     * Function register_wizard
+     * It's the standard method of a "FOOTPRINT_WIZARD" to register itself into
+     * the FOOTPRINT_WIZARDS singleton manager
+     * 
+     */
     void register_wizard();
         
 };
@@ -37,9 +101,35 @@ private:
     static    std::vector<FOOTPRINT_WIZARD*>  m_FootprintWizards;
 
 public:
+    
+    /**
+     * Function register_wizard
+     * A footprint wizard calls this static method when it wants to register itself
+     * into the system wizards
+     * 
+     * @param aWizard is the footprint wizard to be registered
+     * 
+     */
     static void register_wizard(FOOTPRINT_WIZARD *wizard);
+    
+    /**
+     * Function GetWizard
+     * @return a wizard object by it's name or NULL if it isn't available.
+     * 
+     */
     static FOOTPRINT_WIZARD* GetWizard(wxString aName);
+    
+    /**
+     * Function GetWizard
+     * @return a wizard object by it's number or NULL if it isn't available.
+     * 
+     */
     static FOOTPRINT_WIZARD* GetWizard(int aIndex);
+    
+    /** 
+     * Function GetSize
+     * @return the number of wizards available into the system
+     */
     static int GetSize();
 
 };

pcbnew/footprint_wizard.cpp

 /**
- * @file footprint wizard.cpp
+ * @file footprint_wizard.cpp
  */
 
 #include <fctsys.h>
@@ -49,12 +49,18 @@ void FOOTPRINT_WIZARD_FRAME::Process_Special_Functions( wxCommandEvent& event )
     }
 }
 
-
+/* Function OnLeftClick
+ * Captures a left click event in the dialog
+ * 
+ */
 void FOOTPRINT_WIZARD_FRAME::OnLeftClick( wxDC* DC, const wxPoint& MousePos )
 {
 }
 
-
+/* Function OnRightClick
+ * Captures a right click event in the dialog 
+ * 
+ */
 bool FOOTPRINT_WIZARD_FRAME::OnRightClick( const wxPoint& MousePos, wxMenu* PopMenu )
 {
     return true;
@@ -163,6 +169,7 @@ void FOOTPRINT_WIZARD_FRAME::ParametersUpdated( wxGridEvent& event )
  * Function RedrawActiveWindow
  * Display the current selected component.
  * If the component is an alias, the ROOT component is displayed
+ * 
 */
 void FOOTPRINT_WIZARD_FRAME::RedrawActiveWindow( wxDC* DC, bool EraseBg )
 {

pcbnew/footprint_wizard_frame.cpp

 /*
  * This program source code file is part of KiCad, a free EDA CAD application.
  * 
+ * Copyright (C) 2012 Miguel Angel Ajo Pelayo <miguelangel@nbee.es>
  * Copyright (C) 2012 Jean-Pierre Charras, jaen-pierre.charras
  * Copyright (C) 2008-2011 Wayne Stambaugh <stambaughw@verizon.net>
  * Copyright (C) 2004-2011 KiCad Developers, see change_log.txt for contributors.
@@ -99,7 +100,10 @@ static wxAcceleratorEntry accels[] =
 
 #define EXTRA_BORDER_SIZE 2
 
-
+/* Function FOOTPRINT_WIZARD_FRAME
+ * it's the constructor for the footprint wizard frame, it creates everything inside
+ * 
+ */
 FOOTPRINT_WIZARD_FRAME::FOOTPRINT_WIZARD_FRAME( wxWindow* parent, wxSemaphore* semaphore ) :
     PCB_BASE_FRAME( parent, MODULE_VIEWER_FRAME, _( "Footprint Wizard" ),
                     wxDefaultPosition, wxDefaultSize )
@@ -259,6 +263,10 @@ FOOTPRINT_WIZARD_FRAME::~FOOTPRINT_WIZARD_FRAME()
 }
 
 
+/* Function OnCloseWindow
+ * Handles the close event, saving settings an destroying or releasing a semaphore from caller
+ * 
+ */
 void FOOTPRINT_WIZARD_FRAME::OnCloseWindow( wxCloseEvent& Event )
 {
     SaveSettings();
@@ -277,6 +285,9 @@ void FOOTPRINT_WIZARD_FRAME::OnCloseWindow( wxCloseEvent& Event )
 }
 
 
+/* Function OnSashDrag
+ * handles the horizontal separator (sash) drag, updating the pagelist or parameter list 
+ */
 void FOOTPRINT_WIZARD_FRAME::OnSashDrag( wxSashEvent& event )
 {
     if( event.GetDragStatus() == wxSASH_STATUS_OUT_OF_RANGE )
@@ -309,6 +320,10 @@ void FOOTPRINT_WIZARD_FRAME::OnSashDrag( wxSashEvent& event )
 }
 
 
+/* Function OnSize
+ * It handles a dialog resize event, asking for an update 
+ * 
+ */
 void FOOTPRINT_WIZARD_FRAME::OnSize( wxSizeEvent& SizeEv )
 {
     if( m_auimgr.GetManagedWindow() )
@@ -317,14 +332,20 @@ void FOOTPRINT_WIZARD_FRAME::OnSize( wxSizeEvent& SizeEv )
     SizeEv.Skip();
 }
 
-
+/* Function OnSetRelativeOffset
+ * Updates the cursor position and the status bar 
+ * 
+ */
 void FOOTPRINT_WIZARD_FRAME::OnSetRelativeOffset( wxCommandEvent& event )
 {
     GetScreen()->m_O_Curseur = GetScreen()->GetCrossHairPosition();
     UpdateStatusBar();
 }
 
-
+/* Function ReCreatePageList
+ * It recreates the list of pages for a new loaded wizard
+ * 
+ */
 void FOOTPRINT_WIZARD_FRAME::ReCreatePageList()
 {
     if( m_PageList == NULL )
@@ -349,6 +370,10 @@ void FOOTPRINT_WIZARD_FRAME::ReCreatePageList()
     m_canvas->Refresh();
 }
 
+/* Function ReCreateParameterList
+ * It creates the parameter grid for a certain wizard page of the current wizard
+ * 
+ */
 
 void FOOTPRINT_WIZARD_FRAME::ReCreateParameterList()
 {

pcbnew/scripting/TODO.txt

-* Implement iterator for NETCLASSES (NETCLASS) see class_netclass.h
-
-* Saving modules to library (in librairi.cpp)
- 
-     see:
-        - void PCB_EDIT_FRAME::ArchiveModulesOnBoard( const wxString& aLibName, bool aNewModulesOnly )
-
-
-	- bool PCB_BASE_FRAME::Save_Module_In_Library( const wxString& aLibName,
-                                             MODULE*         aModule,
-                                             bool            aOverwrite,
-                                             bool            aDisplayDialog )
-   
-   What do we do about this?, ask Dick, these functions should be transplanted
-   to kicad plugin?
-   
-
-     void PCB_EDIT_FRAME::ArchiveModulesOnBoard( const wxString& aLibName, bool aNewModulesOnly )
+* finish wizard implementation
+* cleanup
+* better build script helpers
 
 

pcbnew/scripting/units.i

@@ -40,36 +40,36 @@
       
    def FromMM(iu): 
       if type(iu) in [int,float]:
-         return int(iu / 0.00254)
+         return iu / 0.00254
       elif type(iu) in [wxPoint,wxSize]:
         return tuple(map(FromMM,iu))
     
    def ToMils(iu): 
       if type(iu) in [int,float]:
-      	return int(iu / 10.0)
+      	return iu / 10.0
       elif type(iu) in [wxPoint,wxSize]:
       	return tuple(map(ToMils,iu))
       	
    def FromMils(iu): 
       if type(iu) in [int,float]:
-         return int(iu*10.0)
+         return iu*10.0
       elif type(iu) in [wxPoint,wxSize]:
       	return tuple(map(FromMils,iu))
       	
-   def wxSizeMM(mmx,mmy): return wxSize(FromMM(mmx),FromMM(mmy))
-   def wxSizeMils(mmx,mmy): return wxSize(FromMils(mmx),FromMils(mmy))
+   def SizeMM(mmx,mmy): return wxSize(FromMM(mmx),FromMM(mmy))
+   def SizeMils(mmx,mmy): return wxSize(FromMils(mmx),FromMils(mmy))
    	
-   def wxPointMM(mmx,mmy): return wxPoint(FromMM(mmx),FromMM(mmy))
-   def wxPointMils(mmx,mmy): return wxPoint(FromMils(mmx),FromMils(mmy))
+   def PointMM(mmx,mmy): return wxPoint(FromMM(mmx),FromMM(mmy))
+   def PointMils(mmx,mmy): return wxPoint(FromMils(mmx),FromMils(mmy))
    
-   def wxRectMM(x,y,wx,wy):
+   def RectMM(x,y,wx,wy):
    	x = int(FromMM(x))
    	y = int(FromMM(y))
    	wx = int(FromMM(wx))
    	wy = int (FromMM(wy))
    	return wxRect(x,y,wx,wy)
    
-   def wxRectMils(x,y,wx,wy):
+   def RectMils(x,y,wx,wy):
    	x = int(FromMils(x))
    	y = int(FromMils(y))
    	wx = int(FromMils(wx))

scripting/python_scripting.cpp

@@ -28,11 +28,17 @@
  */
 
 #include <python_scripting.h>
+#include <stdlib.h>
+#include <string.h>
 
 /* init functions defined by swig */
 
-extern "C" void init_kicad(void);
-extern "C" void init_pcbnew(void);
+extern "C" void init_kicad( void );
+
+extern "C" void init_pcbnew( void );
+
+#define EXTRA_PYTHON_MODULES 2  // this is the number of python
+                                // modules that we want to add into the list
 
 
 /* python inittab that links module names to module init functions
@@ -40,67 +46,86 @@ extern "C" void init_pcbnew(void);
  * our own ones
  */
 
-struct _inittab SwigImportInittab[1000];
+struct _inittab *SwigImportInittab;
 static int      SwigNumModules = 0;
 
 
 /* Add a name + initfuction to our SwigImportInittab */
 
-static void swigAddModule(const char *name, void (*initfunc)()) 
+static void swigAddModule( const char* name, void (* initfunc)() )
 {
-        SwigImportInittab[SwigNumModules].name = (char *)name;
+    SwigImportInittab[SwigNumModules].name     = (char*) name;
     SwigImportInittab[SwigNumModules].initfunc = initfunc;
     SwigNumModules++;
-        SwigImportInittab[SwigNumModules].name = (char *) 0;
+    SwigImportInittab[SwigNumModules].name     = (char*) 0;
     SwigImportInittab[SwigNumModules].initfunc = 0;
 }
 
+
 /* Add the builting python modules */
 
 static void swigAddBuiltin()
 {
     int i = 0;
-        while (PyImport_Inittab[i].name) {
-                swigAddModule(PyImport_Inittab[i].name, PyImport_Inittab[i].initfunc);
+
+    while( PyImport_Inittab[i].name )
+    {
             i++;
     }
     
+    SwigImportInittab = (struct _inittab*)  malloc(
+                        sizeof(struct _inittab)*(i+EXTRA_PYTHON_MODULES));
+    
+    while( PyImport_Inittab[i].name )
+    {
+        swigAddModule( PyImport_Inittab[i].name, PyImport_Inittab[i].initfunc );
+        i++;
+    }
 }
+
+/* Function swigAddModules 
+ * adds the internal modules we offer to the python scripting, so they will be
+ * available to the scripts we run.
+ * 
+ */
+
 static void swigAddModules()
 {
-	swigAddModule("_pcbnew",init_pcbnew);
+    swigAddModule( "_pcbnew", init_pcbnew );
 
     // finally it seems better to include all in just one module
     // but in case we needed to include any other modules,
     // it must be done like this:
     // swigAddModule("_kicad",init_kicad);
-	
 }
 
+/* Function swigSwitchPythonBuiltin
+ * switches python module table to our built one .
+ * 
+ */
+
 static void swigSwitchPythonBuiltin()
 {
     PyImport_Inittab = SwigImportInittab;
 }
 
-
-
+/* Function pcbnewInitPythonScripting
+ * Initializes all the python environment and publish our interface inside it 
+ * 
+ */
 void pcbnewInitPythonScripting()
 {
-    swigAddBuiltin();
-    swigAddModules();
-    swigSwitchPythonBuiltin();
+    swigAddBuiltin();           // add builtin functions
+    swigAddModules();           // add our own modules
+    swigSwitchPythonBuiltin();  // switch the python builtin modules to our new list
 
-    Py_Initialize();
+    Py_Initialize();    // call the python library to get it initialized
 
-    /* setup the scripting path, we may need to add the installation path 
-       of kicad here */
+    // load pcbnew inside python, and load all the user plugins, TODO: add system wide plugins
 
-    PyRun_SimpleString("import sys\n"
+    PyRun_SimpleString( "import sys\n"
                         "sys.path.append(\".\")\n"
                         "import pcbnew\n"
                         "pcbnew.LoadPlugins()"
                         );
-
-
 }
-  
\ No newline at end of file

scripting/python_scripting.h

@@ -3,6 +3,10 @@
 
 #include <Python.h>
 
-void pcbnewInitPythonScripting(void);
+/* Function pcbnewInitPythonScripting
+ * Initializes the Python engine inside pcbnew 
+ */
+
+void pcbnewInitPythonScripting( void );
 
 #endif

scripting/wx_python_helpers.cpp

@@ -33,108 +33,124 @@
 #include <wx/arrstr.h>
 
 
-
 #define WX_DEFAULTENCODING_SIZE 64
 
 static char wxPythonEncoding[WX_DEFAULTENCODING_SIZE] = "ascii";
 
 
-PyObject* wxArrayString2PyList(const wxArrayString& lst)
+PyObject* wxArrayString2PyList( const wxArrayString& lst )
 {
-    PyObject* list = PyList_New(0);
-    for (size_t i=0; i < lst.GetCount(); i++) {
+    PyObject* list = PyList_New( 0 );
+
+    for( size_t i = 0; i < lst.GetCount(); i++ )
+    {
 #if wxUSE_UNICODE
-        PyObject* pyStr = PyUnicode_FromWideChar(lst[i].c_str(), 
+        PyObject* pyStr = PyUnicode_FromWideChar( lst[i].c_str(),
                                                   lst[i].Len()
                                                   );
 #else
-        PyObject* pyStr = PyString_FromStringAndSize(lst[i].c_str(), 
+        PyObject* pyStr = PyString_FromStringAndSize( lst[i].c_str(),
                                                       lst[i].Len()
                                                       );
 #endif
-        PyList_Append(list, pyStr);
-        Py_DECREF(pyStr);
+        PyList_Append( list, pyStr );
+        Py_DECREF( pyStr );
     }
+
     return list;
 }
 
 
-
-wxString* newWxStringFromPy(PyObject* src) {
-
-    bool must_unref_str=false;
+wxString* newWxStringFromPy( PyObject* src )
+{
+    bool        must_unref_str = false;
 
     wxString*   result = NULL;
-    PyObject *obj=src;
+    PyObject*   obj    = src;
 
 #if wxUSE_UNICODE
-    bool must_unref_obj=false;    
+    bool        must_unref_obj = false;
     // Unicode string to python unicode string
     PyObject*   uni_str = src;
 
     // if not an str or unicode, try to str(src)
-    if (!PyString_Check(src) && !PyUnicode_Check(src)) 
+    if( !PyString_Check( src ) && !PyUnicode_Check( src ) )
     {
-        obj = PyObject_Str(src);
+        obj = PyObject_Str( src );
         must_unref_obj = true;
-        if (PyErr_Occurred()) return NULL;
+
+        if( PyErr_Occurred() )
+            return NULL;
     }
 
-    if (PyString_Check(obj)) 
+    if( PyString_Check( obj ) )
     {
-        uni_str = PyUnicode_FromEncodedObject(obj, wxPythonEncoding, "strict");
+        uni_str = PyUnicode_FromEncodedObject( obj, wxPythonEncoding, "strict" );
         must_unref_str = true;
-        if (PyErr_Occurred()) return NULL;
+
+        if( PyErr_Occurred() )
+            return NULL;
     }
 
     result = new wxString();
-    size_t len = PyUnicode_GET_SIZE(uni_str);
-    if (len) 
+    size_t len = PyUnicode_GET_SIZE( uni_str );
+
+    if( len )
     {
-        PyUnicode_AsWideChar((PyUnicodeObject*)uni_str,
-                             wxStringBuffer(*result, len),len);
+        PyUnicode_AsWideChar( (PyUnicodeObject*) uni_str,
+                              wxStringBuffer( *result, len ), len );
     }
 
-    if (must_unref_str) Py_DECREF(uni_str);
-    if (must_unref_obj) Py_DECREF(obj);
+    if( must_unref_str )
+        Py_DECREF( uni_str );
+
+    if( must_unref_obj )
+        Py_DECREF( obj );
+
 #else
     // normal string (or object) to normal python string
     PyObject* str = src;
 
-    if (PyUnicode_Check(src)) // if it's unicode convert to normal string
+    if( PyUnicode_Check( src ) ) // if it's unicode convert to normal string
     {
-        str = PyUnicode_AsEncodedString(src, wxPythonEncoding, "strict");
-        if (PyErr_Occurred()) return NULL;
+        str = PyUnicode_AsEncodedString( src, wxPythonEncoding, "strict" );
+
+        if( PyErr_Occurred() )
+            return NULL;
     }
-    else if (!PyString_Check(src)) // if it's not a string, str(obj)
+    else if( !PyString_Check( src ) ) // if it's not a string, str(obj)
     {
-        str = PyObject_Str(src);
+        str = PyObject_Str( src );
         must_unref_str = true;
-        if (PyErr_Occurred()) return NULL;
+
+        if( PyErr_Occurred() )
+            return NULL;
     }
 
     // get the string pointer and size
     char*       str_ptr;
     Py_ssize_t  str_size;
-    PyString_AsStringAndSize(str, &str_ptr, &str_size);
+    PyString_AsStringAndSize( str, &str_ptr, &str_size );
 
     // build the wxString from our pointer / size
-    result = new wxString(str_ptr, str_size);
+    result = new wxString( str_ptr, str_size );
+
+    if( must_unref_str )
+        Py_DECREF( str );
 
-    if (must_unref_str) Py_DECREF(str);
 #endif
 
     return result;
 }
 
 
-wxString Py2wxString(PyObject* src)
+wxString Py2wxString( PyObject* src )
 {
     wxString    result;
-    wxString* resPtr = newWxStringFromPy(src);    
+    wxString*   resPtr = newWxStringFromPy( src );
 
     // In case of exception clear it and return an empty string
-    if (resPtr==NULL) 
+    if( resPtr==NULL )
     {
         PyErr_Clear();
         return wxEmptyString;
@@ -148,26 +164,26 @@ wxString Py2wxString(PyObject* src)
 }
 
 
-PyObject* wx2PyString(const wxString& src)
+PyObject* wx2PyString( const wxString& src )
 {
     PyObject* str;
+
 #if wxUSE_UNICODE
-    str = PyUnicode_FromWideChar(src.c_str(), src.Len());
+    str = PyUnicode_FromWideChar( src.c_str(), src.Len() );
 #else
-    str = PyString_FromStringAndSize(src.c_str(), src.Len());
+    str = PyString_FromStringAndSize( src.c_str(), src.Len() );
 #endif
     return str;
 }
 
 
-
-void wxSetDefaultPyEncoding(const char* encoding)
+void wxSetDefaultPyEncoding( const char* encoding )
 {
-    strncpy(wxPythonEncoding, encoding, WX_DEFAULTENCODING_SIZE);
+    strncpy( wxPythonEncoding, encoding, WX_DEFAULTENCODING_SIZE );
 }
 
+
 const char* wxGetDefaultPyEncoding()
 {
     return wxPythonEncoding;
 }
-

scripting/wx_python_helpers.h

@@ -7,14 +7,12 @@
 #include <wx/arrstr.h>
 
 
+PyObject*   wxArrayString2PyList( const wxArrayString& lst );
+wxString*   newWxStringFromPy( PyObject* source );
+wxString    Py2wxString( PyObject* source );
+PyObject*   wx2PyString( const wxString& src );
 
-
-PyObject* wxArrayString2PyList(const wxArrayString& lst);
-wxString* newWxStringFromPy(PyObject* source);
-wxString Py2wxString(PyObject* source);
-PyObject* wx2PyString(const wxString& src);
-
-void wxSetDefaultPyEncoding(const char* encoding);
+void        wxSetDefaultPyEncoding( const char* encoding );
 const char* wxGetDefaultPyEncoding();
 
 #endif