Add CMake code to enable or disable using images in menu items.

* Add USE_IMAGES_IN_MENUS definition to override the default platform
  behavior for adding images to menu items.
* Update COMPILING.txt to document how to use USE_IMAGES_IN_MENUS.
* Fix Windows segfault when creating language selection submenu introduced
  by new bitmap code in r3087.
* Changed per email from JP from CVPcb to CvPcb because I'm getting old and
  blind and misread the email.
* Lot's of Doxygen comment and coding style policy fixes.

CMakeLists.txt

@@ -107,6 +107,19 @@ if(USE_BOOST_POLYGON_LIBRARY)
     add_definitions(-DUSE_BOOST_POLYGON_LIBRARY)
 endif(USE_BOOST_POLYGON_LIBRARY)
 
+# Allow user to override the default settings for adding images to menu items.  By default
+# images in menu items are enabled on all plaforms except OSX.  This can be over ridden by
+# defining -DUSE_IMAGES_IN_MENUS=ON/OFF to force the preferred behavior.
+if(NOT DEFINED USE_IMAGES_IN_MENUS)
+    if(NOT APPLE)
+        set(USE_IMAGES_IN_MENUS ON)
+    endif(NOT APPLE)
+else(NOT DEFINED USE_IMAGES_IN_MENUS)
+    if(USE_IMAGES_IN_MENUS)
+        set(USE_IMAGES_IN_MENUS ON)
+    endif(USE_IMAGES_IN_MENUS)
+endif(NOT DEFINED USE_IMAGES_IN_MENUS)
+
 # Locations for install targets.
 set(KICAD_BIN bin
     CACHE PATH "Location of KiCad binaries.")

CMakeModules/config.h.cmake

@@ -50,4 +50,6 @@
 /* Warning!!!  Using wxGraphicContext for rendering is experimental. */
 #cmakedefine USE_WX_GRAPHICS_CONTEXT 1
 
+#cmakedefine USE_IMAGES_IN_MENUS 1
+
 #endif  /* __CONFIG_H__ */

Documentation/compiling/COMPILING.txt

@@ -223,5 +223,10 @@ One of these 2 option *must* be set to ON:
    It requires wxWidgets to be built with the --enable-graphics_ctx switch.
    See building wxWidgets above.
 
+ USE_IMAGES_IN_MENUS ON/OFF (OPTIONAL)
+   Force building Kicad with or without images in menu items.  If this is not defined on
+   when CMake is used to create the build files, images will be included in menu items
+   on all platforms except OSX.
+
 Note: that it is easy to build only a specific binary such as pcbnew alone:
     make pcbnew

cvpcb/autosel.cpp

@@ -47,14 +47,6 @@ wxString GetQuotedText( wxString & text )
 }
 
 
-/*
- * Called by the automatic association button
- * Read *.equ files to try to find corresponding footprint
- * for each component that is not already linked to a footprint ( a "free"
- * component )
- * format of a line:
- * 'cmp_ref' 'footprint_name'
- */
 void CVPCB_MAINFRAME::AssocieModule( wxCommandEvent& event )
 {
     FOOTPRINT_ALIAS_LIST aliases;
@@ -72,6 +64,7 @@ void CVPCB_MAINFRAME::AssocieModule( wxCommandEvent& event )
     for( ii = 0; ii < m_AliasLibNames.GetCount(); ii++ )
     {
         fn = m_AliasLibNames[ii];
+
         if( !fn.HasExt() ) {
             fn.SetExt( FootprintAliasFileExtension );
             // above fails if filename have more than one point
@@ -142,10 +135,12 @@ found in the default search paths." ),
         BOOST_FOREACH( FOOTPRINT_ALIAS& alias, aliases )
         {
             bool found = false;
+
             if( alias.m_Name.CmpNoCase( component.m_Value ) != 0 )
                 continue;
 
-            /* filter alias so one can use multiple aliases (for polar and nonpolar caps for example) */
+            /* filter alias so one can use multiple aliases (for polar and nonpolar caps for
+             * example) */
             FOOTPRINT_INFO *module = m_footprints.GetModuleInfo( alias.m_FootprintName );
 
             if( module )
@@ -164,7 +159,7 @@ found in the default search paths." ),
 any of the project footprint libraries." ),
                             GetChars( component.m_Reference ),
                             GetChars( alias.m_FootprintName ) );
-                wxMessageBox( msg, _( "CVPcb Error" ), wxOK | wxICON_ERROR,
+                wxMessageBox( msg, _( "CvPcb Error" ), wxOK | wxICON_ERROR,
                               this );
             }
             if( found )

cvpcb/cvpcb.cpp

@@ -75,11 +75,11 @@ bool WinEDA_App::OnInit()
     wxString         message;
     CVPCB_MAINFRAME* frame = NULL;
 
-    InitEDA_Appl( wxT( "CVPcb" ), APP_TYPE_CVPCB );
+    InitEDA_Appl( wxT( "CvPcb" ), APP_TYPE_CVPCB );
 
     if( m_Checker && m_Checker->IsAnotherRunning() )
     {
-        if( !IsOK( NULL, _( "CVPcb is already running, Continue?" ) ) )
+        if( !IsOK( NULL, _( "CvPcb is already running, Continue?" ) ) )
             return false;
     }
 

cvpcb/cvpcb_mainframe.h

@@ -18,7 +18,7 @@ class DISPLAY_FOOTPRINTS_FRAME;
 
 
 /**
- * The CVPcb application main window.
+ * The CvPcb application main window.
  */
 class CVPCB_MAINFRAME : public EDA_BASE_FRAME
 {
@@ -87,7 +87,17 @@ public:
     void             ConfigCvpcb( wxCommandEvent& event );
     void             OnKeepOpenOnSave( wxCommandEvent& event );
     void             DisplayModule( wxCommandEvent& event );
+
+    /**
+     * Called by the automatic association button
+     * Read *.equ files to try to find corresponding footprint
+     * for each component that is not already linked to a footprint ( a "free"
+     * component )
+     * format of a line:
+     * 'cmp_ref' 'footprint_name'
+     */
     void             AssocieModule( wxCommandEvent& event );
+
     void             WriteStuffList( wxCommandEvent& event );
     void             DisplayDocFile( wxCommandEvent& event );
 
@@ -143,7 +153,7 @@ public:
 
     /**
      * Function LoadSettings
-     * loads the CVPcb main frame specific configuration settings.
+     * loads the CvPcb main frame specific configuration settings.
      *
      * Don't forget to call this base method from any derived classes or the
      * settings will not get loaded.
@@ -152,7 +162,7 @@ public:
 
     /**
      * Function SaveSettings
-     * save the CVPcb frame specific configuration settings.
+     * save the CvPcb frame specific configuration settings.
      *
      * Don't forget to call this base method from any derived classes or the
      * settings will not get saved.
@@ -195,16 +205,16 @@ public:
 
     /**
      * Function GetProjectFileParameters
-     * return project file parameter list for CVPcb.
+     * return project file parameter list for CvPcb.
      * <p>
-     * Populate the project file parameter array specific to CVPcb if it hasn't
+     * Populate the project file parameter array specific to CvPcb if it hasn't
      * already been populated and return a reference to the array to the caller.
      * Creating the parameter list at run time has the advantage of being able
      * to define local variables.  The old method of statically building the array
      * at compile time requiring global variable definitions.
      * </p>
      *
-     * @return A reference to a PARAM_CFG_ARRAY contain the project settings for CVPcb.
+     * @return A reference to a PARAM_CFG_ARRAY contain the project settings for CvPcb.
      */
     PARAM_CFG_ARRAY& GetProjectFileParameters( void );
 

cvpcb/menubar.cpp

@@ -85,7 +85,7 @@ void CVPCB_MAINFRAME::ReCreateMenuBar()
     ADD_MENUITEM_WITH_HELP( filesMenu,
                             wxID_EXIT,
                             _( "&Quit" ),
-                            _( "Quit CVPcb" ),
+                            _( "Quit CvPcb" ),
                             exit_xpm );
 
     // Menu Preferences:
@@ -108,7 +108,7 @@ void CVPCB_MAINFRAME::ReCreateMenuBar()
     // Keep open on save
     item = new wxMenuItem( preferencesMenu, ID_CVPCB_CONFIG_KEEP_OPEN_ON_SAVE,
                            _( "Keep Open On Save" ),
-                           _( "Prevent CVPcb from exiting after saving netlist file" ),
+                           _( "Prevent CvPcb from exiting after saving netlist file" ),
                            wxITEM_CHECK );
     preferencesMenu->Append( item );
     SETBITMAPS( window_close_xpm );
@@ -132,13 +132,13 @@ void CVPCB_MAINFRAME::ReCreateMenuBar()
 
     // Contents
     ADD_MENUITEM_WITH_HELP( helpMenu, wxID_HELP, _( "&Contents" ),
-                            _( "Open the CVPcb handbook" ),
+                            _( "Open the CvPcb handbook" ),
                             online_help_xpm );
 
     // About
     ADD_MENUITEM_WITH_HELP( helpMenu, wxID_ABOUT,
-                            _( "&About CVPcb" ),
-                            _( "About CVPcb schematic to pcb converter" ),
+                            _( "&About CvPcb" ),
+                            _( "About CvPcb schematic to pcb converter" ),
                             info_xpm );
 
     // Create the menubar and append all submenus

cvpcb/savecmp.cpp

@@ -70,7 +70,7 @@ bool CVPCB_MAINFRAME::LoadComponentFile( const wxString& aFileName )
     source = wxFopen( fn.GetFullPath(), wxT( "rt" ) );
     if( source == NULL )
     {
-        msg.Printf( _( "Cannot open CVPcb component file <%s>." ),
+        msg.Printf( _( "Cannot open CvPcb component file <%s>." ),
                     GetChars( fn.GetFullPath() ) );
         msg << wxT( "\n" ) << _( "This is normal if you are opening a new netlist file" );
         wxMessageBox( msg, titleComponentLibErr, wxOK | wxICON_ERROR );

include/appl_wxstruct.h

@@ -80,11 +80,22 @@ public: WinEDA_App();
     /**
      * Function OnInit
      * this is the first executed function (like main() )
-     * @return true if the appliction can be started.
+     * @return true if the application can be started.
      */
     bool      OnInit();
 
+    /**
+     * Function SetBinDir
+     * finds the path to the executable and store it in WinEDA_App::m_BinDir
+     *
+     * @return TODO
+     */
     bool      SetBinDir();
+
+    /**
+     * Function SetDefaultSearchPaths
+     * sets search paths for libraries, modules, internationalization files, etc.
+     */
     void      SetDefaultSearchPaths( void );
 
     /**
@@ -108,34 +119,57 @@ public: WinEDA_App();
     void      InitEDA_Appl( const wxString& aName,
                             id_app_type     aId = APP_TYPE_UNKOWN );
 
-    bool      SetLanguage( bool first_time = FALSE );
+    /**
+     * Function SetLanguage
+     * sets the dictionary file name for internationalization.
+     * <p>
+     * The files are in kicad/internat/xx or kicad/internat/xx_XX and are named kicad.mo
+     * </p>
+     * @param   first_time  must be set to true the first time this funct is
+     *          called, false otherwise
+     * @return  true if the language can be set (i.e. if the locale is available)
+     */
+    bool      SetLanguage( bool first_time = false );
 
     /**
      * Function AddMenuLanguageList
+     * creates a menu list for language choice, and add it as submenu to \a MasterMenu.
      *
-     * Create menu list for language choice, and add it as submenu to a main
-     * menu
-     *
-     * @param MasterMenu : The main menu. The sub menu list will be
-     *                     accessible from the menu item with id
-     *                     ID_LANGUAGE_CHOICE
-     *
-     * @return  the sub menu Language list
+     * @param MasterMenu The main menu. The sub menu list will be accessible from the menu
+     *                   item with id ID_LANGUAGE_CHOICE
      */
     void      AddMenuLanguageList( wxMenu* MasterMenu );
+
+    /**
+     * Function SetLanguageIdentifier
+     * sets in .m_LanguageId member the wxWidgets language identifier Id  from
+     * the kicad menu id (internal menu identifier).
+     *
+     * @param menu_id The kicad menuitem id (returned by Menu Event, when
+     *                clicking on a menu item)
+     */
     void      SetLanguageIdentifier( int menu_id );
+
     void      SetLanguagePath( void );
+
+    /**
+     * Function InitOnLineHelp
+     * initializes Kicad's online help.
+     */
     void      InitOnLineHelp();
 
     /**
      * Function GetSettings
-     * Get application settings
-     * @param aReopenLastUsedDirectory = true to switch to last opened
-     * directory, false to use current CWD
-     * @return  none
+     * gets the application settings.
+     * @param aReopenLastUsedDirectory True to switch to last opened directory, false
+     *                                 to use current CWD
      */
     void      GetSettings( bool aReopenLastUsedDirectory );
 
+    /**
+     * Function SaveSettings
+     * saves the application settings.
+     */
     void      SaveSettings();
 
     void      WriteProjectConfig( const wxString&  local_config_filename,
@@ -157,7 +191,7 @@ public: WinEDA_App();
 
     /**
      * Function ReadCurrentSetupValues
-     * Raed the current setup values previously saved, from m_EDA_Config
+     * Read the current setup values previously saved, from m_EDA_Config
      * saved parameters are parameters that have the .m_Setup member set to
      * true
      * @param aList = array of PARAM_CFG_BASE pointers
@@ -180,10 +214,32 @@ public: WinEDA_App();
     void      ReadPdfBrowserInfos();
     void      WritePdfBrowserInfos();
 
+    /**
+     * Function FindFileInSearchPaths
+     * looks in search paths for \a filename.
+     */
     wxString  FindFileInSearchPaths( const wxString&      filename,
                                      const wxArrayString* subdirs = NULL );
 
+    /**
+     * Function GetHelpFile
+     * get the help file path.
+     * <p?
+     * Return the Kicad help file with path.  The base paths defined in
+     * m_searchPaths are tested for a valid file.  The path returned can
+     * be relative depending on the paths added to m_searchPaths.  See the
+     * documentation for wxPathList for more information. If the help file
+     * for the current locale is not found, an attempt to find the English
+     * version of the help file is made.
+     * wxEmptyString is returned if help file not found.
+     * Help file is searched in directories in this order:
+     *  help/<canonical name> like help/en_GB
+     *  help/<short name> like help/en
+     *  help/en
+     * </p>
+     */
     wxString  GetHelpFile( void );
+
     wxString  GetLibraryFile( const wxString& filename );
     wxString& GetEditorName();
 
@@ -193,7 +249,8 @@ public: WinEDA_App();
     wxPathList& GetLibraryPathList() { return m_libSearchPaths; }
     wxString FindLibraryPath( const wxString& fileName );
 
-    /** FindLibraryPath
+    /**
+     * Function FindLibraryPath
      * Kicad saves user defined library files that are not in the standard
      * library search path list with the full file path.  Calling the library
      * search path list with a user library file will fail.  This helper method
@@ -207,22 +264,24 @@ public: WinEDA_App();
     }
 
 
-    /** ReturnLastVisitedLibraryPath
-     * Returns the last visited library directory, or (if void) the first
+    /**
+     * Function ReturnLastVisitedLibraryPath
+     * returns the last visited library directory, or (if void) the first
      * path in lib path list ( but not the CWD )
+     *
      * @param aSubPathToSearch = Preferred sub path to search in path list
      */
-    wxString ReturnLastVisitedLibraryPath(
-        const wxString& aSubPathToSearch = wxEmptyString );
+    wxString ReturnLastVisitedLibraryPath( const wxString& aSubPathToSearch = wxEmptyString );
+
     void     SaveLastVisitedLibraryPath( const wxString& aPath );
 
-    /** ReturnFilenameWithRelativePathInLibPath
+    /**
+     * Function  ReturnFilenameWithRelativePathInLibPath
      * @return a short filename (with extension) with only a relative path if
      *         this filename can be found in library paths
-     * @param aFullFilename = filename with path and extension.
+     * @param aFullFilename The filename with path and extension.
      */
-    wxString ReturnFilenameWithRelativePathInLibPath(
-        const wxString& aFullFilename );
+    wxString ReturnFilenameWithRelativePathInLibPath( const wxString& aFullFilename );
 
     /**
      * Function RemoveLibraryPath

include/macros.h

@@ -7,6 +7,9 @@
 
 #include <wx/wx.h>
 
+#include "bitmaps.h"
+
+
 /**
  * Macro TO_UTF8
  * converts a wxString to a UTF8 encoded C string for all wxWidgets build modes.
@@ -67,7 +70,7 @@ static inline const wxChar* GetChars( const wxString& s )
 
 #define NEGATE( x ) (x = -x)
 
-/// # of elements in an arrray
+/// # of elements in an array
 #define DIM( x )    unsigned( sizeof(x) / sizeof( (x)[0] ) )    // not size_t
 
 
@@ -85,6 +88,7 @@ static inline const wxChar* GetChars( const wxString& s )
                                            Angle += 3600;\
                                            while( Angle >= 3600 ) \
                                            Angle -= 3600;}
+
 #define NEGATE_AND_NORMALIZE_ANGLE_POS( Angle ) \
     { Angle = -Angle; while( Angle < 0 ) \
           Angle += 3600;while( Angle >= 3600 ) \
@@ -139,7 +143,8 @@ BOOST_TYPEOF_REGISTER_TYPE( BOARD_ITEM* )
 /*****************************************************/
 /* inline functions to insert menuitems with a icon: */
 /*****************************************************/
-static inline void ADD_MENUITEM( wxMenu* menu, int id,
+static inline void ADD_MENUITEM( wxMenu*         menu,
+                                 int             id,
                                  const wxString& text,
                                  const wxBitmap& icon )
 {
@@ -147,14 +152,15 @@ static inline void ADD_MENUITEM( wxMenu* menu, int id,
 
     l_item = new wxMenuItem( menu, id, text );
 
-#if !defined( __WXMAC__ )
+#if defined( USE_IMAGES_IN_MENUS )
     l_item->SetBitmap( icon );
-#endif /* !defined( __WXMAC__ ) */
+#endif
 
     menu->Append( l_item );
 }
 
-static inline void ADD_MENUITEM_WITH_HELP( wxMenu* menu, int id,
+static inline void ADD_MENUITEM_WITH_HELP( wxMenu*         menu,
+                                           int             id,
                                            const wxString& text,
                                            const wxString& help,
                                            const wxBitmap& icon )
@@ -163,43 +169,15 @@ static inline void ADD_MENUITEM_WITH_HELP( wxMenu* menu, int id,
 
     l_item = new wxMenuItem( menu, id, text, help );
 
-#if !defined( __WXMAC__ )
+#if defined( USE_IMAGES_IN_MENUS )
     l_item->SetBitmap( icon );
-#endif /* !defined( __WXMAC__ ) */
+#endif
 
     menu->Append( l_item );
 }
 
-#ifdef __WINDOWS__
-static inline void ADD_MENUITEM_WITH_SUBMENU( wxMenu* menu, wxMenu* submenu,
-                                              int id, const wxString& text,
-                                              const wxBitmap& icon )
-{
-    wxMenuItem* l_item;
-
-    l_item = new wxMenuItem( menu, id, text );
-    l_item->SetSubMenu( submenu );
-    l_item->SetBitmap( icon );
-    menu->Append( l_item );
-};
-
-static inline void ADD_MENUITEM_WITH_HELP_AND_SUBMENU( wxMenu*         menu,
+static inline void ADD_MENUITEM_WITH_SUBMENU( wxMenu*         menu,
                                               wxMenu*         submenu,
-                                                       int             id,
-                                                       const wxString& text,
-                                                       const wxString& help,
-                                                       const wxBitmap& icon )
-{
-    wxMenuItem* l_item;
-
-    l_item = new wxMenuItem( menu, id, text, help );
-    l_item->SetSubMenu( submenu );
-    l_item->SetBitmap( icon );
-    menu->Append( l_item );
-};
-
-#else
-static inline void ADD_MENUITEM_WITH_SUBMENU( wxMenu* menu, wxMenu* submenu,
                                               int             id,
                                               const wxString& text,
                                               const wxBitmap& icon )
@@ -209,12 +187,12 @@ static inline void ADD_MENUITEM_WITH_SUBMENU( wxMenu* menu, wxMenu* submenu,
     l_item = new wxMenuItem( menu, id, text );
     l_item->SetSubMenu( submenu );
 
-#if !defined( __WXMAC__ )
+#if defined( USE_IMAGES_IN_MENUS )
     l_item->SetBitmap( icon );
-#endif /* !defined( __WXMAC__ ) */
+#endif
 
     menu->Append( l_item );
-}
+};
 
 static inline void ADD_MENUITEM_WITH_HELP_AND_SUBMENU( wxMenu*         menu,
                                                        wxMenu*         submenu,
@@ -228,24 +206,23 @@ static inline void ADD_MENUITEM_WITH_HELP_AND_SUBMENU( wxMenu*         menu,
     l_item = new wxMenuItem( menu, id, text, help );
     l_item->SetSubMenu( submenu );
 
-#if !defined( __WXMAC__ )
+#if defined( USE_IMAGES_IN_MENUS )
     l_item->SetBitmap( icon );
-#endif /* !defined( __WXMAC__ ) */
+#endif
 
     menu->Append( l_item );
-}
+};
 
-#endif
 
 // macro to add a bitmap list to check menus (do not use with normal menus)
-#ifdef __WINDOWS__
-#  define SETBITMAPS( icon ) item->SetBitmaps( apply_xpm, (icon) )
+#if defined( USE_IMAGES_IN_MENUS ) && defined(  __WINDOWS__ )
+#  define SETBITMAPS( icon ) item->SetBitmaps( KiBitmap( apply_xpm ), (icon) )
 #else
 #  define SETBITMAPS( icon )
 #endif
 
 // macro to add a bitmap menus (do not use with check menus)
-#ifdef __WXMAC__
+#if !defined( USE_IMAGES_IN_MENUS ) || defined( __WXMAC__ )
 #  define SET_BITMAP( icon )
 #else
 #  define SET_BITMAP( icon ) item->SetBitmap( (icon) )